diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 22237fc..5eab4c5 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -38,8 +38,8 @@ known publication blocker to adoption. explanation, and comparison. Use native evidence and common text/YAML/JSON rendering. Do not recreate removed provider-specific explanation writers. - Use standard command names and reporting flags. CommandKit owns `--debug`; - its effective debug mode also enables Audita artifact capture for processing - runs, as resolved below. + its parsed boolean also enables Audita artifact capture for processing runs, + independently of the resolved reporting mode, as resolved below. - Keep domain transcript serialization and ordinary report files under Audita's output contracts. Generic report formatting need not transform transcript JSON. Preserve meaningful partial success: a work-unit model error is not automatically @@ -53,19 +53,28 @@ known publication blocker to adoption. Use one `--debug` flag for detailed diagnostics: standard CommandKit debug reporting plus retained Audita diagnostic artifacts during processing. Do not introduce `--debug-artifacts`, duplicate the reserved flag, or add a second parser. -Artifact capture follows the effective reporting mode after CommandKit applies -its flag ordering, aliases, and explicit boolean rules. It does not depend merely -on whether `--debug` appeared somewhere in the arguments. +Artifact capture follows the parsed `--debug` boolean independently of the +resolved reporting mode. In particular, `--debug --quiet` suppresses ordinary CLI +output while retaining diagnostic artifacts; `--debug --verbose` also retains +them. CommandKit continues to own CLI visibility and mode ordering. + +Use the native boolean semantics: omission disables capture, `--debug` enables +it, `--debug=false` disables it, and the last debug occurrence wins. Quiet and +verbose flags do not rewrite this value. Aliases refer to the same input; tokens +consumed as other flag values or following `--` do not count as debug flags. Inspection commands keep standard debug reporting without creating processing -artifacts. Help and migration guidance must explain that processing in debug mode -also writes diagnostic files, and processing output must identify their location. -Retain Audita's artifact redaction and lifecycle responsibilities. The accepted -tradeoff is that debug reporting for processing also enables artifact capture; -there is no separate capture switch in this design. +artifacts. Help and migration guidance must explain that supplying `--debug` for +processing also writes diagnostic files, including when quiet suppresses output. +Report artifact locations through CommandKit's normal visibility rules; artifact +creation does not require an always-visible message in quiet mode. Retain Audita's +artifact redaction and lifecycle responsibilities. There is no separate capture +switch in this design. -Use a supported public accessor for the effective mode to initialize capture. -The upstream review below identifies the missing API and proposed change. +Use CommandKit's planned shared debug binding to initialize capture from typed +input. The resolved-mode accessor serves reporting decisions and is insufficient +for capture. This supersedes the earlier decision to tie capture to the effective +mode. The upstream review below records the matching capability plan. ## Work Outline @@ -87,8 +96,9 @@ The upstream review below identifies the missing API and proposed change. mode, completion summaries, and write failures before implementation. Standard command statuses, including comparison status 3, should not be forced into the old Audita-only status table without a domain reason. - Wire processing artifact capture to the effective debug mode once the public - reporting-state API is available; remove Audita's duplicate debug flag binding. + Wire processing artifact capture to the shared debug boolean once the public + binding API is available; remove Audita's independent debug flag declaration + and parsing while retaining its application-owned capture behavior. 5. Develop concrete request adapters for preview, validation, and any selected smoke commands. They need correct variables, schema contracts, and credential handling, not just an engine loader. Keep generic resource inspection independent @@ -107,11 +117,24 @@ configuration and supplied-value handling through domain settings. Exercise stdout transcript isolation, file output, quiet/verbose/debug behavior, completion summary placement, cancellation, partial success, and output failures. -Verify that processing in effective debug mode both reports debug details and -captures artifacts, while inspection does not create processing artifacts. Cover -mode ordering and explicit false values through CommandKit's parser, including -`--debug --quiet`, `--quiet --debug`, and `--debug --debug=false`. Check artifact -location reporting and help text explaining the combined behavior. +Verify the independent capture and visibility decisions through CommandKit's +parser for processing commands: + +| Arguments after the command path | Reporting mode | Capture artifacts | +| --- | --- | --- | +| None | Ordinary | No | +| `--debug` | Debug | Yes | +| `--debug --quiet` | Quiet | Yes | +| `--quiet --debug` | Debug | Yes | +| `--debug --verbose` | Verbose | Yes | +| `--debug --debug=false` | Ordinary | No | +| `--debug=false --debug` | Debug | Yes | +| `--debug --quiet --debug=false` | Quiet | No | + +Check aliases, explicit false values, and option-looking operands or values +through native parsing. Inspection must not create processing artifacts even +with debug enabled. Check artifact-location reporting subject to normal +visibility and help text explaining capture under quiet mode. Tagged core and integration suites passed during review, but do not establish these Audita behaviors. Use offline tests and controlled providers; explicitly @@ -120,12 +143,13 @@ automatic startup or release check. CommandKit and integrations are early-stage. Freely propose upstream improvements where reporting, declaration, or integration APIs are problematic or incomplete. -No request has yet been submitted. First candidates for investigation are support -for result payloads versus diagnostic verbosity and preserving a domain completion +The reporting-mode request has led to the upstream plan described below. +Other candidates for investigation are support for result payloads versus +diagnostic verbosity and preserving a domain completion summary alongside stdout data. Use shared upstream improvements where appropriate instead of bypassing the reporter with a permanent local output layer. -### Upstream Review: Effective Reporting Mode +### Upstream Review: Shared Debug Input and Reporting Mode On 2026-11-08, verified upstream `main` at `69257066e21c12ea3492237ebee072598adea60c` and the v0.5.0 tag at @@ -140,17 +164,22 @@ The upstream [reporter](https://forge.maximumdirect.net/base-layer/commandkit/sr and [mode rules](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/docs/cli.md#modes-and-visibility) define the reviewed behavior. -**Proposed upstream request:** expose the resolved mode through a read-only public -API on the invocation or reporter. Prefer a typed ordinary/quiet/verbose/debug -value, with exact naming left to upstream. It should report the final selection -after native parsing and aliases, be available before the handler starts capture, -and preserve invocation isolation. No mutable parser or reporter internals need -to be exposed. +The original request proposed using a read-only resolved-mode accessor for +capture. The corrected requirement above supersedes that use: quiet reporting +must not clear an independently enabled capture request. -This is an identified integration blocker for combined debug reporting and capture -in v0.5.0. Request and adopt the upstream addition before implementing that wiring; -do not inspect private state, infer the mode from emitted output, or reimplement -argument parsing in Audita. No upstream request has been submitted by this review. +The CommandKit checkout at `ec0e58efff638d0d4cc2ef20e930a9d477ed2e83` contains a +[shared-debug plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/ec0e58efff638d0d4cc2ef20e930a9d477ed2e83/docs/roadmap/shared-debug-binding.md) +covering both a typed debug binding and a resolved-mode accessor. It explicitly +preserves the bound debug value when quiet or verbose changes reporting mode. +The capability direction is agreed upstream but not implemented in that reviewed +revision; binding construction and metadata remain open upstream decisions. + +Adopt the supported shared binding once released. Its boolean value should drive +Audita capture; presence information remains available through native typed +input. Resolve any remaining integration gap upstream rather than inspecting +private state, inferring input from emitted output, redeclaring the core flag, +or reparsing arguments. The mode accessor alone does not unblock capture wiring. ## Open Decisions