Separate debug artifact capture from reporting mode

This commit is contained in:
2026-11-08 13:54:35 +00:00
parent 90d82b5b5f
commit 32bac58b5e

View File

@@ -38,8 +38,8 @@ known publication blocker to adoption.
explanation, and comparison. Use native evidence and common text/YAML/JSON explanation, and comparison. Use native evidence and common text/YAML/JSON
rendering. Do not recreate removed provider-specific explanation writers. rendering. Do not recreate removed provider-specific explanation writers.
- Use standard command names and reporting flags. CommandKit owns `--debug`; - Use standard command names and reporting flags. CommandKit owns `--debug`;
its effective debug mode also enables Audita artifact capture for processing its parsed boolean also enables Audita artifact capture for processing runs,
runs, as resolved below. independently of the resolved reporting mode, as resolved below.
- Keep domain transcript serialization and ordinary report files under Audita's - Keep domain transcript serialization and ordinary report files under Audita's
output contracts. Generic report formatting need not transform transcript JSON. output contracts. Generic report formatting need not transform transcript JSON.
Preserve meaningful partial success: a work-unit model error is not automatically 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 Use one `--debug` flag for detailed diagnostics: standard CommandKit debug
reporting plus retained Audita diagnostic artifacts during processing. Do not reporting plus retained Audita diagnostic artifacts during processing. Do not
introduce `--debug-artifacts`, duplicate the reserved flag, or add a second parser. introduce `--debug-artifacts`, duplicate the reserved flag, or add a second parser.
Artifact capture follows the effective reporting mode after CommandKit applies Artifact capture follows the parsed `--debug` boolean independently of the
its flag ordering, aliases, and explicit boolean rules. It does not depend merely resolved reporting mode. In particular, `--debug --quiet` suppresses ordinary CLI
on whether `--debug` appeared somewhere in the arguments. 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 Inspection commands keep standard debug reporting without creating processing
artifacts. Help and migration guidance must explain that processing in debug mode artifacts. Help and migration guidance must explain that supplying `--debug` for
also writes diagnostic files, and processing output must identify their location. processing also writes diagnostic files, including when quiet suppresses output.
Retain Audita's artifact redaction and lifecycle responsibilities. The accepted Report artifact locations through CommandKit's normal visibility rules; artifact
tradeoff is that debug reporting for processing also enables artifact capture; creation does not require an always-visible message in quiet mode. Retain Audita's
there is no separate capture switch in this design. 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. Use CommandKit's planned shared debug binding to initialize capture from typed
The upstream review below identifies the missing API and proposed change. 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 ## 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 mode, completion summaries, and write failures before implementation. Standard
command statuses, including comparison status 3, should not be forced into the command statuses, including comparison status 3, should not be forced into the
old Audita-only status table without a domain reason. old Audita-only status table without a domain reason.
Wire processing artifact capture to the effective debug mode once the public Wire processing artifact capture to the shared debug boolean once the public
reporting-state API is available; remove Audita's duplicate debug flag binding. 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 5. Develop concrete request adapters for preview, validation, and any selected
smoke commands. They need correct variables, schema contracts, and credential smoke commands. They need correct variables, schema contracts, and credential
handling, not just an engine loader. Keep generic resource inspection independent 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 stdout transcript isolation, file output, quiet/verbose/debug behavior, completion
summary placement, cancellation, partial success, and output failures. summary placement, cancellation, partial success, and output failures.
Verify that processing in effective debug mode both reports debug details and Verify the independent capture and visibility decisions through CommandKit's
captures artifacts, while inspection does not create processing artifacts. Cover parser for processing commands:
mode ordering and explicit false values through CommandKit's parser, including
`--debug --quiet`, `--quiet --debug`, and `--debug --debug=false`. Check artifact | Arguments after the command path | Reporting mode | Capture artifacts |
location reporting and help text explaining the combined behavior. | --- | --- | --- |
| 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 Tagged core and integration suites passed during review, but do not establish
these Audita behaviors. Use offline tests and controlled providers; explicitly 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 CommandKit and integrations are early-stage. Freely propose upstream improvements
where reporting, declaration, or integration APIs are problematic or incomplete. where reporting, declaration, or integration APIs are problematic or incomplete.
No request has yet been submitted. First candidates for investigation are support The reporting-mode request has led to the upstream plan described below.
for result payloads versus diagnostic verbosity and preserving a domain completion 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 summary alongside stdout data. Use shared upstream improvements where appropriate
instead of bypassing the reporter with a permanent local output layer. 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 On 2026-11-08, verified upstream `main` at
`69257066e21c12ea3492237ebee072598adea60c` and the v0.5.0 tag 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) and [mode rules](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/docs/cli.md#modes-and-visibility)
define the reviewed behavior. define the reviewed behavior.
**Proposed upstream request:** expose the resolved mode through a read-only public The original request proposed using a read-only resolved-mode accessor for
API on the invocation or reporter. Prefer a typed ordinary/quiet/verbose/debug capture. The corrected requirement above supersedes that use: quiet reporting
value, with exact naming left to upstream. It should report the final selection must not clear an independently enabled capture request.
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 The CommandKit checkout at `ec0e58efff638d0d4cc2ef20e930a9d477ed2e83` contains a
in v0.5.0. Request and adopt the upstream addition before implementing that wiring; [shared-debug plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/ec0e58efff638d0d4cc2ef20e930a9d477ed2e83/docs/roadmap/shared-debug-binding.md)
do not inspect private state, infer the mode from emitted output, or reimplement covering both a typed debug binding and a resolved-mode accessor. It explicitly
argument parsing in Audita. No upstream request has been submitted by this review. 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 ## Open Decisions