diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index a3a2f47b..71f2ca4d 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -647,10 +647,11 @@ retains the bookkeeping boundary; U9 still owns concrete durable record choices. **Discussion / decision:** Controls, native capture hooks, lifecycle, failure policy, and optional diagnostics agreed. Use `--debug` for native verbosity and durable capture with `/tmp/notarius-debug` as the default root. Operator-owned -data handling and recording each fact once are agreed. Replace the summary/trace -hierarchy with a compact run index, configuration/composition snapshots, and -operation records; maintain a `latest` symlink at the debug root. Capture depth -and concrete serialized fields remain under discussion. Implementation is pending. +data handling and convenient diagnostic representation are agreed. Replace the +summary/trace hierarchy with a compact run index, configuration and composition +snapshots, and operation records; maintain a `latest` symlink at the debug root. Convenience +guides capture depth; the precise inventory and serialized fields remain under +discussion. Implementation is pending. ### Shared Debug Control With Conditional Capture @@ -712,8 +713,9 @@ copied execution summaries, synthetic call identities, and duplicate terminal reporting. Keep callbacks lightweight and synchronize shared capture state: callbacks are synchronous, can overlap across operations, and `OnPrepared` runs while admission is held. Retain needed details and persist them at normal -operation boundaries rather than buffering an entire pipeline or repeatedly -writing every accumulated conversation prefix. +operation boundaries without requiring an entire pipeline's content in memory. +Native snapshots may repeat conversation prefixes when that is the convenient +representation; do not introduce a custom delta format merely to remove them. Capture only available evidence. Preparation/admission failures may have no `OnPrepared` notification; observer events have metadata, not response bodies; @@ -806,9 +808,17 @@ status zero alone does not establish that a check passed. ### Selected Bundle Organization -**Agreed principle:** Record each fact once and reference it where needed. Use -shared application outcome facts and native execution evidence rather than -parallel summary/trace accounting or repeated snapshots. +**Guiding principle:** Capture the most convenient debug representation. Optimize +for straightforward capture and useful inspection, rather than maximum +conciseness, completeness, or deduplication. Native values, complete snapshots, +and self-contained operation records are appropriate even when fields or content +repeat. + +"Record each fact once and reference it where needed" remains a practical +guideline for avoiding independently maintained decisions and accounting, not a +strict storage constraint. Use shared application outcome facts and native +execution evidence. Repeating that evidence in useful representations does not +require another source of truth or justify custom compression/reconstruction. Organize the bundle around the run and its operations, replacing `summary/` and `trace/` as separate categories. Use a compact overview for navigation and keep @@ -838,28 +848,30 @@ exact serialized fields remain implementation choices: | Resolved pipeline | Describe selected steps, lanes, modules, validators, and reference relationships. | | Operation records | Connect diagnostic evidence with its stage, chunk, lane, or validator. | -The overview is an index rather than a second execution ledger. Its terminal -facts come from the same application outcome used for the CLI report, and it -references detailed records instead of duplicating requests, responses, findings, -or error history. Capture configuration and resolved composition once when -available. Use native execution IDs with application scope to connect records. +The overview provides navigation, with terminal facts drawn from the same +application outcome used for the CLI report. Reference detailed records where +useful; include convenient summary fields without maintaining a second execution +ledger. Configuration and resolved composition normally need one snapshot each. +Use native execution IDs with application scope to connect records. Reused work has a checkpoint/reuse decision and reference, not a fabricated model execution. Retain enough available context to investigate a run that fails before publishing output. Do not depend entirely on a successful output manifest or automatically -copy every original input and published artifact. Select a conversation -representation that avoids repeatedly saving the complete accumulated history -after each turn or maintaining an independent competing transcript. +copy every original input and published artifact. Prefer the native conversation +representation when convenient, including complete per-turn snapshots if those +are easier to capture and inspect. Do not build a competing transcript model or +deduplication system to eliminate repeated history. ### Open Discussion: Capture Depth -The organization is selected; precise evidence and granularity remain open: +The organization and emphasis on convenience are selected; precise evidence +and granularity remain open. Capture readily available, useful evidence without +making exhaustive reconstruction or every provider attempt a prerequisite: - Which prepared request details, outputs, intermediate artifacts, validation decisions, and correction content to retain. -- How to represent conversation history without repeated prefixes while using - PromptKit's native evidence. +- Which native conversation snapshots make troubleshooting most convenient. - How much failed-run context to retain independently, and when references to existing inputs, checkpoints, or published artifacts suffice. - Which desired evidence is available through native public hooks and which