From 90d82b5b5f5cf980c78f42ee31dd4ee3d83989b6 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 13:25:44 +0000 Subject: [PATCH] Resolve unified debug mode and record CommandKit API gap --- docs/roadmap/commandkit.md | 73 ++++++++++++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 15 deletions(-) diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index fc516c6..22237fc 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -1,6 +1,6 @@ # CommandKit Adoption Outline -**Updated:** 2026-11-07 +**Updated:** 2026-11-08 **Status:** Initial outline. Adoption is part of the agreed target, not an optional future evaluation. The [master roadmap](library-adoption.md) owns shared direction @@ -37,9 +37,9 @@ known publication blocker to adoption. - Adopt standard ckconfig viewing, validation, sources, path discovery, 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. Adapt Audita's existing - `--debug` artifact-capture spelling to avoid colliding with CommandKit's reserved - reporter flag; the final capture spelling is decided below. +- 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. - 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 @@ -48,6 +48,25 @@ known publication blocker to adoption. today's curated fields. Loading for help/version must not trigger credentials, provider calls, or domain processing. +## Debug Reporting and Artifact Capture — Resolved + +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. + +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. + +Use a supported public accessor for the effective mode to initialize capture. +The upstream review below identifies the missing API and proposed change. + ## Work Outline 1. Inventory Audita commands, arguments, flags, supplied empty/false/zero values, @@ -68,6 +87,8 @@ known publication blocker to adoption. 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. 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 @@ -86,6 +107,12 @@ 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. + Tagged core and integration suites passed during review, but do not establish these Audita behaviors. Use offline tests and controlled providers; explicitly invoked smoke operations may contact providers and incur costs, but are not an @@ -98,19 +125,35 @@ for result payloads versus diagnostic verbosity and preserving a domain completi 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 + +On 2026-11-08, verified upstream `main` at +`69257066e21c12ea3492237ebee072598adea60c` and the v0.5.0 tag at +`49f2d09ccde3d91d8c412a44ab934f223bef8fe6`. The relevant reporting and invocation +implementation is unchanged between those revisions. Public API inspection of +v0.5.0 confirms that neither `Invocation` nor `Reporter` exposes the effective +reporting mode. `Reporter.Debug` emits a message; it is not a mode query. Parsed +reporting selection and the reporter's mode are internal. + +The upstream [reporter](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/reporter.go), +[invocation API](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/identity.go), +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. + +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. + ## Open Decisions -### Artifact Capture Flag - -**Recommendation:** use `--debug-artifacts` for retained Audita artifacts and keep -`--debug` exclusively for standard reporting verbosity. The meanings are distinct, -and separation follows CommandKit's supported reserved-flag contract. - -**Alternative:** deliberately couple debug verbosity with artifact capture through -supported application hooks. This reduces operator flags but can retain sensitive -request/response artifacts when an operator only wanted verbosity. It would need -clear suite-wide semantics; duplicate declaration of `--debug` is unsupported. - ### Quiet Mode and the Completion Summary **Recommendation:** start with CommandKit's normal visibility rules, including