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

Require an explicit transcript destination for quiet processing

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 14:31:44 +00:00
parent 68e16f6aac
commit 9dba2d506a
2 changed files with 76 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
docs/roadmap/commandkit.md
View File

@@ -24,18 +24,24 @@ The upstream [core release](https://forge.maximumdirect.net/base-layer/commandki
and [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/docs/consumers/guide.md)
define the reviewed set. Core uses Cobra/pflag; the matched integrations require
Go 1.27. The former missing diagnostic adapter has been published; the required
shared debug binding introduces the release gate below.
debug-input and reporting-mode APIs introduce the release gate below.
## Adoption Gate: Released Shared Debug Binding
## Adoption Gate: Released Debug Binding and Reporting Mode Access
Begin CommandKit adoption implementation only after an upstream version is
published with a supported public binding for the parsed `--debug` boolean,
independent of the resolved reporting mode. A release containing only the
resolved-mode accessor does not satisfy this gate. Neither the v0.5.0 baseline
nor an implementation available only on upstream `main` is sufficient.
published with both supported public capabilities:
Before opening the gate, review the published API against the capture behavior
and acceptance cases below, select compatible released ckconfig and ckprompt
- A binding for the parsed `--debug` boolean, independent of reporting mode,
to control artifact capture.
- An accessor for the resolved reporting mode, to reject quiet processing
without an explicit transcript destination.
A release containing only one capability does not satisfy this gate. Neither
the v0.5.0 baseline nor an implementation available only on upstream `main` is
sufficient.
Before opening the gate, review the published APIs against the capture and
destination-validation cases below, select compatible released ckconfig and ckprompt
versions, and record the exact versions and source revisions in the
[master dependency selection](library-adoption.md#baseline-and-selected-dependency-set).
No future version number is assumed. The integrations need new releases only
@@ -95,9 +101,10 @@ artifact redaction and lifecycle responsibilities. There is no separate capture
switch in this design.
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.
input. The resolved-mode accessor serves destination validation and 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.
## Quiet Mode and the Completion Summary — Resolved
@@ -110,7 +117,7 @@ processing and enabled required outputs have succeeded.
| Output | Ordinary | Verbose/debug | Quiet |
| --- | --- | --- | --- |
| Transcript on stdout, when selected | Shown | Shown | Suppressed |
| Transcript on stdout, when selected | Shown | Shown | Rejected before processing |
| Completion summary and created artifact locations | Hidden | Shown | Hidden |
| Requested transcript and ordinary report files | Written | Written | Written |
| Fatal error explanation | Shown | Shown | Shown |
@@ -124,8 +131,34 @@ This deliberately retires the always-visible completion summary. Help and
hard-cutover guidance must explain that operators wanting immediate counts and
locations should select verbose/debug reporting. If ordinary reports are disabled,
those modes are needed to see the completion counts. Operators wanting a transcript
while quiet is effective should select a file destination. Whether to reject
quiet with a stdout destination remains a separate open decision below.
while quiet is effective must select an explicit destination, as resolved below.
## Quiet Processing Requires a Transcript Destination — Resolved
Reject a processing invocation when its resolved reporting mode is quiet and its
selected transcript destination is stdout. Require an explicit non-stdout output
destination, such as `--output corrected.json`. Deliberate disposal remains
available through `--output /dev/null`; do not introduce a `--force` bypass.
An empty output value that selects stdout does not satisfy the requirement.
Audita's primary product is the corrected transcript. Reports and debug evidence
do not substitute for delivering it, so their enablement does not exempt a run
from this check. The domain-specific restriction prevents incurring processing
costs while accidentally discarding that product. It leaves CommandKit's standard
quiet semantics intact and does not apply to inspection commands.
Use CommandKit's public resolved-mode accessor and Audita's selected destination.
Return a usage failure with a visible explanation before creating output or debug
artifacts or starting model calls. For example: "Quiet processing requires an
output destination; use --output FILE, or --output /dev/null to discard the
transcript deliberately." Do not scan arguments or infer mode from output.
Shell redirection does not satisfy the requirement because CommandKit still
suppresses stdout transcript delivery.
Check effective mode after native ordering, boolean values, and aliases:
`--quiet --verbose` permits stdout, whereas `--verbose --quiet` requires an
explicit destination. `--debug --quiet` also requires one; debug capture remains
independent once the invocation passes this check.
## Work Outline
@@ -149,8 +182,9 @@ design and inventory work can proceed before it opens.
transcript/artifact integrity, cancellation, and partial success. Apply the
resolved visibility and completion-summary rules above; specify 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.
3, should not be forced into the old Audita-only status table without a domain
reason. Validate quiet mode against the transcript destination before creating
outputs or starting model work, using the released reporting-mode accessor.
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.
@@ -173,14 +207,20 @@ stdout transcript isolation, file output, quiet/verbose/debug behavior, completi
summary placement, cancellation, partial success, and output failures.
Verify that the completion summary and created artifact locations appear only
in verbose/debug diagnostics, never in transcript stdout. Quiet suppresses stdout
transcript delivery while requested file outputs remain enabled. Fatal error
explanations remain visible in every mode, and a required-output failure must not
produce a successful completion summary. Cover ordinary reporting disabled as
in verbose/debug diagnostics, never in transcript stdout. Reject quiet processing
with a stdout destination; requested file outputs remain enabled in valid quiet
runs. Fatal error explanations remain visible in every mode, and a required-output
failure must not produce a successful completion summary. Cover ordinary reporting disabled as
well as enabled, and document the loss of the former default summary.
Cover omitted and empty output selections in effective quiet mode, including
with reports or debug capture enabled: reject before model calls and artifact
creation. Accept valid explicit file and discard destinations. Exercise native
mode ordering, explicit false, and aliases so the check follows the resolved
mode. Keep quiet inspection valid and help/version free of processing setup.
Verify the independent capture and visibility decisions through CommandKit's
parser for processing commands:
parser for processing commands with a valid explicit transcript destination:
| Arguments after the command path | Reporting mode | Capture artifacts |
| --- | --- | --- |
@@ -206,10 +246,10 @@ 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.
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.
The resolved summary and destination decisions use standard reporting behavior;
they do not require an ordinary-mode summary channel or an exception to quiet
suppression. Record further concrete integration gaps as they arise and prefer
shared upstream improvements over a permanent local output layer.
### Upstream Review: Shared Debug Input and Reporting Mode
@@ -237,36 +277,16 @@ 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 the [release gate](#adoption-gate-released-shared-debug-binding)
is satisfied. 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,
Adopt both capabilities once the
[release gate](#adoption-gate-released-debug-binding-and-reporting-mode-access)
is satisfied. The bound boolean drives Audita capture; the resolved mode drives
quiet destination validation. 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
### Quiet Processing Without a Transcript File
**Recommendation, not yet selected:** allow effective quiet mode with the default
stdout destination, without requiring `--force`. The corrected transcript will
not be delivered, but enabled ordinary reports and requested debug artifacts still
provide useful results. This supports report-only and diagnostic runs and follows
CommandKit's suppression semantics. Even if all file outputs are disabled, an
operator may intentionally want only the processing outcome. Explain clearly that
processing and model costs still occur and that shell redirection cannot recover
suppressed stdout. The tradeoff is that an accidental combination can discard an
expensive transcript result.
**Viable alternative:** reject effective quiet mode with a stdout destination
before creating outputs or starting model calls, requiring an explicit transcript
destination. This protects against accidentally discarding the primary product of
processing, but adds an Audita-specific restriction to valid report-only or debug
workflows. An explicit discard destination such as `/dev/null` could express
deliberate disposal without introducing a broad `--force` flag. If selected, base
the check on resolved reporting mode and destination, not argument presence;
`--quiet --verbose` does not leave quiet effective.
### Request Preview, Validation, and Smoke Commands
**Recommendation:** include standard offline request preview and validation,