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) 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 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 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 Begin CommandKit adoption implementation only after an upstream version is
published with a supported public binding for the parsed `--debug` boolean, published with both supported public capabilities:
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.
Before opening the gate, review the published API against the capture behavior - A binding for the parsed `--debug` boolean, independent of reporting mode,
and acceptance cases below, select compatible released ckconfig and ckprompt 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 versions, and record the exact versions and source revisions in the
[master dependency selection](library-adoption.md#baseline-and-selected-dependency-set). [master dependency selection](library-adoption.md#baseline-and-selected-dependency-set).
No future version number is assumed. The integrations need new releases only 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. switch in this design.
Use CommandKit's planned shared debug binding to initialize capture from typed Use CommandKit's planned shared debug binding to initialize capture from typed
input. The resolved-mode accessor serves reporting decisions and is insufficient input. The resolved-mode accessor serves destination validation and reporting
for capture. This supersedes the earlier decision to tie capture to the effective decisions and is insufficient for capture. This supersedes the earlier decision
mode. The upstream review below records the matching capability plan. to tie capture to the effective mode. The upstream review below records the
matching capability plan.
## Quiet Mode and the Completion Summary — Resolved ## Quiet Mode and the Completion Summary — Resolved
@@ -110,7 +117,7 @@ processing and enabled required outputs have succeeded.
| Output | Ordinary | Verbose/debug | Quiet | | 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 | | Completion summary and created artifact locations | Hidden | Shown | Hidden |
| Requested transcript and ordinary report files | Written | Written | Written | | Requested transcript and ordinary report files | Written | Written | Written |
| Fatal error explanation | Shown | Shown | Shown | | 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 hard-cutover guidance must explain that operators wanting immediate counts and
locations should select verbose/debug reporting. If ordinary reports are disabled, locations should select verbose/debug reporting. If ordinary reports are disabled,
those modes are needed to see the completion counts. Operators wanting a transcript 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 while quiet is effective must select an explicit destination, as resolved below.
quiet with a stdout destination remains a separate open decision 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 ## Work Outline
@@ -149,8 +182,9 @@ design and inventory work can proceed before it opens.
transcript/artifact integrity, cancellation, and partial success. Apply the transcript/artifact integrity, cancellation, and partial success. Apply the
resolved visibility and completion-summary rules above; specify write failures resolved visibility and completion-summary rules above; specify write failures
before implementation. Standard command statuses, including comparison status before implementation. Standard command statuses, including comparison status
3, should not be forced into the 3, should not be forced into the old Audita-only status table without a domain
old Audita-only status table without a domain reason. 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 Wire processing artifact capture to the shared debug boolean once the public
binding API is available; remove Audita's independent debug flag declaration binding API is available; remove Audita's independent debug flag declaration
and parsing while retaining its application-owned capture behavior. 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. summary placement, cancellation, partial success, and output failures.
Verify that the completion summary and created artifact locations appear only Verify that the completion summary and created artifact locations appear only
in verbose/debug diagnostics, never in transcript stdout. Quiet suppresses stdout in verbose/debug diagnostics, never in transcript stdout. Reject quiet processing
transcript delivery while requested file outputs remain enabled. Fatal error with a stdout destination; requested file outputs remain enabled in valid quiet
explanations remain visible in every mode, and a required-output failure must not runs. Fatal error explanations remain visible in every mode, and a required-output
produce a successful completion summary. Cover ordinary reporting disabled as 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. 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 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 | | 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 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.
The reporting-mode request has led to the upstream plan described below. The reporting-mode request has led to the upstream plan described below.
Other candidates for investigation are support for result payloads versus The resolved summary and destination decisions use standard reporting behavior;
diagnostic verbosity and preserving a domain completion they do not require an ordinary-mode summary channel or an exception to quiet
summary alongside stdout data. Use shared upstream improvements where appropriate suppression. Record further concrete integration gaps as they arise and prefer
instead of bypassing the reporter with a permanent local output layer. shared upstream improvements over a permanent local output layer.
### Upstream Review: Shared Debug Input and Reporting Mode ### 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 The capability direction is agreed upstream but not implemented in that reviewed
revision; binding construction and metadata remain open upstream decisions. revision; binding construction and metadata remain open upstream decisions.
Adopt the supported shared binding once the [release gate](#adoption-gate-released-shared-debug-binding) Adopt both capabilities once the
is satisfied. Its boolean value should drive [release gate](#adoption-gate-released-debug-binding-and-reporting-mode-access)
Audita capture; presence information remains available through native typed is satisfied. The bound boolean drives Audita capture; the resolved mode drives
input. Resolve any remaining integration gap upstream rather than inspecting quiet destination validation. Presence information remains available through
private state, inferring input from emitted output, redeclaring the core flag, 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. or reparsing arguments. The mode accessor alone does not unblock capture wiring.
## Open Decisions ## 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 ### Request Preview, Validation, and Smoke Commands
**Recommendation:** include standard offline request preview and validation, **Recommendation:** include standard offline request preview and validation,

9
docs/roadmap/library-adoption.md
View File

@@ -103,9 +103,10 @@ an ordinary compatibility review, not an assumption that later releases are
interchangeable. interchangeable.
**CommandKit release gate:** adoption implementation waits for a published core **CommandKit release gate:** adoption implementation waits for a published core
version providing the independent shared debug binding required by the version providing both the independent shared debug binding for capture and the
[CommandKit outline](commandkit.md#adoption-gate-released-shared-debug-binding). resolved reporting-mode accessor for quiet destination validation, as required by
The resolved-mode accessor alone is insufficient. Replace the reviewed v0.5.0 the [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access).
Either API alone is insufficient. Replace the reviewed v0.5.0
core target with that release and record compatible released integration versions core target with that release and record compatible released integration versions
and exact source revisions after review. No replacement version is selected yet. and exact source revisions after review. No replacement version is selected yet.
@@ -144,7 +145,7 @@ for Audita's complete release workflow.
Identify and remove local code made redundant by the adopted facilities as Identify and remove local code made redundant by the adopted facilities as
part of each migration, rather than leaving cleanup as an unspecified follow-up. part of each migration, rather than leaving cleanup as an unspecified follow-up.
4. **After the CommandKit release gate opens, integrate core and both standard 4. **After the CommandKit release gate opens, integrate core and both standard
integrations.** Confirm the required shared debug binding is published and integrations.** Confirm both required public APIs are published and
select the released dependency set as described above before starting this select the released dependency set as described above before starting this
implementation stage. Complete the previously designed operator interface, implementation stage. Complete the previously designed operator interface,
adapting Audita domain handlers and resolving upstream issues. Earlier design adapting Audita domain handlers and resolving upstream issues. Earlier design