diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index f12e7eac..277234ad 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -25,15 +25,14 @@ Item 2 selects the application command structure and input conventions. Item 3 selects native composition, shared loaders, and application preflight. Item 4 selects native reporting, machine output, and outcomes. Item 5 selects conditional debug capture through the shared `--debug` flag, native diagnostics, and a run/ -operation bundle with a `latest` symlink. Its capture inventory and depth are -resolved below. Item 6 selects verification, migration guidance, and incorporation -into the master roadmap; that incorporation is still pending. +operation bundle with a `latest` symlink. Its capture inventory, depth, and +explicit-empty directory behavior are resolved below. Item 6 selects verification, +migration guidance, and incorporation into the master roadmap; that incorporation +is still pending. The major architectural decisions are settled. Remaining choices are run-report -fields/versioning and durable record formats (item 4/U9), and explicit-empty -debug-directory handling plus any demonstrated need for verbosity without capture -(item 5). Function signatures, bundle filenames other than `latest`, and similar -implementation details do not +fields/versioning and durable record formats (item 4/U9). Function signatures, +bundle filenames other than `latest`, and similar implementation details do not reopen the selected architecture. Broader PromptKit choices remain with the master roadmap. @@ -196,8 +195,8 @@ No upstream feature request has been identified as a blocker for this scope. Evaluate any later demonstrated gap on its actual application need. On roadmap reconciliation, incorporate these versions into U1, replace U10's open standard capability selection with this decision, and incorporate the application wiring -and presentation decisions from items 2–5. Preserve the remaining record and -debug choices explicitly as directed by item 6. +and presentation decisions from items 2–5. Preserve the remaining record choices +explicitly as directed by item 6. ## 2. Native Command Surface And Inputs @@ -665,10 +664,10 @@ summary/trace hierarchy with a compact run index, configuration and composition snapshots, and operation records; maintain a `latest` symlink at the debug root. The capture inventory and depth below are agreed: one default depth retaining every application-visible turn, useful inputs and outputs, and application -assessments, with native snapshots and convenient readable views. Exact filenames -and serialized application fields remain implementation choices. Explicit-empty -directory handling and any demonstrated need for verbosity without capture -remain open. Implementation is pending. +assessments, with native snapshots and convenient readable views. An explicitly +empty debug directory disables capture while preserving native reporting-mode +selection, resolving verbosity without capture. Exact filenames and serialized +application fields remain implementation choices. Implementation is pending. ### Shared Debug Control With Conditional Capture @@ -684,33 +683,53 @@ with each run's bundle beneath it. Temporary diagnostic output belongs under `/tmp` or an operator-selected location under `/var`, rather than beside a configuration file likely to live under `/etc`. Replace the old configuration- relative `./notarius-debug` default. Precedence is CLI override, configured value, -then application default. Explicit relative configuration paths retain their -source-relative interpretation; relative CLI paths use the invocation directory. +then application default. Nonempty relative configuration paths retain their +source-relative interpretation; nonempty relative CLI paths use the invocation +directory. Omitting both directory overrides selects the default, so `--debug` enables -verbosity and capture without requiring a path. Detailed explicit-empty handling -and any demonstrated need for verbosity without capture remain separate choices. +verbosity and capture without requiring a path. + +**Explicit-empty decision:** An explicitly empty `--debug-dir ""` or +`debug.directory: ""` disables capture while preserving native debug verbosity +and reporting-mode ordering. Omission inherits the configured value or default; +an explicit empty value is meaningful and must not fall back to either. CLI +selection overrides configuration, including when the CLI value is empty. A +nonempty CLI directory can therefore re-enable capture over an empty configured +directory when `--debug` is enabled. No additional flag is needed for verbosity +without capture. + +Recognize an empty value before resolving relative paths so it cannot become the +invocation or configuration directory. Disabled capture creates no bundle and +leaves `latest` untouched. A nonempty but unusable destination follows the +requested-capture failure policy when capture is enabled; it does not silently +disable capture or select a fallback directory. Determine capture from the application boolean and destination, not from `Invocation.ReportingMode()`. A later quiet or verbose selection can change presentation without clearing the debug input. Explicit `--debug=false` follows native boolean binding semantics and disables capture. -| Invocation flags | Reporting selection | Capture | -| --- | --- | --- | -| No `--debug`, with any directory selection | Selected native mode | None. | -| `--debug`, no directory override | Debug | Enabled under `/tmp/notarius-debug`. | -| `--debug`, with a directory override | Debug | Enabled under the selected root. | -| `--debug --quiet`, with any directory selection | Quiet | Enabled. | -| `--quiet --debug`, with any directory selection | Debug | Enabled. | +| Configured directory | Invocation flags | Reporting selection | Capture | +| --- | --- | --- | --- | +| Any | No `--debug`, with any directory selection | Selected native mode | None. | +| Omitted | `--debug` | Debug | `/tmp/notarius-debug`. | +| `/var/tmp/notarius` | `--debug` | Debug | `/var/tmp/notarius`. | +| Any | `--debug --debug-dir ""` | Debug | None. | +| `""` | `--debug` | Debug | None. | +| `""` | `--debug --debug-dir /tmp/investigation` | Debug | `/tmp/investigation`. | +| Omitted | `--debug --quiet` | Quiet | `/tmp/notarius-debug`. | +| Omitted | `--quiet --debug` | Debug | `/tmp/notarius-debug`. | +| Any | `--debug --quiet --debug-dir ""` | Quiet | None. | **Upstream ordering clarification:** CommandKit uses the last enabled reporting -mode. Thus `--debug --quiet` suppresses command output while retaining capture; -`--quiet --debug` selects debug verbosity. Preserve that native ordering rather -than making quiet unconditional. Quiet still shows failure explanations, and -capture does not bypass result suppression. On success the normal run report -includes the bundle location; failure explanations include an allocated bundle -path when available. +mode. Thus `--debug --quiet` suppresses command output while retaining capture +when the effective directory is nonempty; `--quiet --debug` selects debug +verbosity. Preserve that native ordering rather than making quiet unconditional. +Quiet still shows failure explanations, and capture does not bypass result +suppression. On success the normal run report includes the bundle location when +capture was enabled; failure explanations include an allocated bundle path when +available. ### Native Evidence And A Small Application Recorder @@ -1112,11 +1131,10 @@ compatibility framework. Resolve U1's dependency baseline and U10's CommandKit scope from items 1–4. Narrow U9 to remaining durable-field and accounting choices, and debug implementation -details within item 5's resolved inventory and depth. Preserve its separate -open directory-control choices. Reconcile removal inventory and acceptance -criteria, including old inspection-command and machine-output compatibility -assumptions. Preserve unresolved schema handling, role-specific retry/fallback -policy, worker defaults, +details within item 5's resolved inventory, depth, and directory controls. +Reconcile removal inventory and acceptance criteria, including old +inspection-command and machine-output compatibility assumptions. Preserve +unresolved schema handling, role-specific retry/fallback policy, worker defaults, checkpoint transition choices, and other concrete choices until actually settled. Once incorporated, the master roadmap owns implementation sequencing and status;