eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Separate debug artifact capture from reporting mode

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 13:54:35 +00:00
parent 90d82b5b5f
commit 32bac58b5e
1 changed files with 61 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
docs/roadmap/commandkit.md
View File

@@ -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