diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index 158dc1fa..73769fc3 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -97,9 +97,9 @@ Two application needs already identified for deliberate treatment are: replaces its presentation with one compact application report rendered natively for humans and machines. Exact fields/versioning remain with U9; reports must describe the actual publication and domain outcome. -- Item 5 uses native `--debug` for diagnostic verbosity and for capture when a - debug directory is supplied through CLI or configuration. Capture selection - remains independent of the final reporting mode. +- Item 5 uses native `--debug` for diagnostic verbosity and for capture when an + effective debug directory is available, including an application default. + Capture selection remains independent of the final reporting mode. ### Intended Sequencing @@ -645,24 +645,30 @@ 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 -conditional durable capture. The summary/trace distinction, concrete capture -inventory, and bundle organization remain under discussion. Implementation is -pending. +conditional durable capture. The default-directory policy is reopened; removing +the existing default is not an agreed requirement. Operator-owned data handling +and recording each fact once are agreed. The summary/trace distinction, concrete +capture inventory, and bundle organization remain under discussion. +Implementation is pending. ### Shared Debug Control With Conditional Capture Attach a native application boolean binding to CommandKit's shared `--debug` option on the pipeline run command. Capture is enabled when that boolean is true -and a debug directory is defined by `--debug-dir PATH` or `debug.directory` in -application configuration. The CLI directory overrides the configured directory. -A directory alone does not enable capture. Do not add a separate +and an effective debug directory is available. `--debug-dir PATH` overrides +`debug.directory` in application configuration, which may have an application +default. A directory alone does not enable capture. Do not add a separate `--capture-debug` flag. -Make the configured directory optional, removing the implicit -`./notarius-debug` default. With no supplied destination, `--debug` supplies -native diagnostics without creating files. Preserve normal CLI/configuration -path resolution; detailed empty-value handling can be settled with the -configuration migration. +**Default-directory discussion:** The earlier removal of the implicit +`./notarius-debug` default was an inference, not a user-selected requirement; +withdraw it. A default destination is compatible with the design. With a default, +`--debug` ordinarily enables both verbosity and capture without an explicit path. +The existing destination is relative to the selected main configuration file; +explicit CLI paths are relative to the invocation directory. Decide the default +and whether there is a useful explicit way to select no capture destination +before finalizing absent/empty-value behavior. Do not assume omission of a CLI or +configuration key means there is no effective destination. Determine capture from the application boolean and destination, not from `Invocation.ReportingMode()`. A later quiet or verbose selection can change @@ -671,11 +677,14 @@ native boolean binding semantics and disables capture. | Invocation flags | Reporting selection | Capture | | --- | --- | --- | -| `--debug`, no CLI/configured directory | Debug | None. | -| `--debug`, with CLI/configured directory | Debug | Enabled. | -| `--debug --quiet`, no CLI/configured directory | Quiet | None. | -| `--debug --quiet`, with CLI/configured directory | Quiet | Enabled. | -| `--quiet --debug`, with CLI/configured directory | Debug | Enabled. | +| `--debug`, no effective directory | Debug | None. | +| `--debug`, effective directory from CLI/configuration/default | Debug | Enabled. | +| `--debug --quiet`, no effective directory | Quiet | None. | +| `--debug --quiet`, effective directory from CLI/configuration/default | Quiet | Enabled. | +| `--quiet --debug`, effective directory from CLI/configuration/default | Debug | Enabled. | + +The no-effective-directory rows apply only if the final directory policy allows +that state; with a default, omission alone does not select it. **Upstream ordering clarification:** CommandKit uses the last enabled reporting mode. Thus `--debug --quiet` suppresses command output while retaining capture; @@ -746,15 +755,26 @@ capture finalization succeed. If finalization fails after publication, identify the published output and available debug location in the native failure explanation; preserve the successful publication as a fact. -### Disclosure And Retention +### Debug Data And Operator Responsibility -Retain the separate debug root, restrictive debug permissions, and explicit -operator retention policy. Captured content may include source material, rendered -requests, generated output, and correction history. Credential redaction does not -make that material safe to share. Do not record credential values, authorization -headers, or environment dumps. Use upstream safe inspection where available and -deliberate content selection elsewhere. No summary or directory label should -imply that arbitrary diagnostic content is non-sensitive. +Debug artifacts are expected to contain internal application data, including +source material, rendered requests, model output, and correction history where +useful for diagnosis. If the application data is sensitive, the debug artifacts +are sensitive in the same way. Operators secure them through the ordinary means +used for application inputs and outputs, such as filesystem permissions. Do not +require a special debug-only security or retention model, or use sensitivity +concerns to limit useful diagnostic content. + +Do not directly print or serialize values explicitly marked as secrets by +ConfigKit, such as resolved API keys. Use native secret-aware configuration +inspection and preserve upstream credential omissions. This boundary does not +authorize scanning or rewriting LLM output, prompts, source content, or arbitrary +strings for suspected sensitive values. Do not carry forward heuristic content +scrubbing or generic secret-detection machinery as a migration requirement. + +Separate debug/output/cache lifecycles and no automatic debug deletion remain +application organization choices. Choose capture contents for diagnostic value, +size, and duplication, rather than promising a shareable or sanitized bundle. ### Native Optional Diagnostics @@ -777,10 +797,14 @@ status zero alone does not establish that a check passed. ### Open Discussion: Summary And Trace +**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. + The current `summary/` and `trace/` layout is not selected as the new design. -Discuss what diagnostic questions the bundle should answer, which application -records and native evidence it needs, and how to avoid duplicate snapshots or -execution accounting. Keep these choices open: +Discuss what diagnostic questions the bundle should answer and which application +records and native evidence it needs. Summary/trace are not separate security +classes. Keep these choices open: - Whether a separate summary is useful, and whether it is a compact index/final outcome rather than another copy of execution records. @@ -812,6 +836,9 @@ The current [debug lifecycle](../internal/state.md#debug-bundles) and and which migration examples, documentation, and ADRs need coordinated updates? - What release-documentation guidance will show operators and subprocess callers how to migrate their workflows and integrations to the new conventions? +- Reconcile older debug-sensitivity language, special-handling requirements, and + heuristic redaction behavior/tests with item 5's clarified boundary. Do not + reintroduce them as implicit requirements while migrating documentation or code. After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing, removals, and acceptance criteria, including its treatment of existing inspection