Separate debug artifact capture from reporting mode
This commit is contained in:
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user