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

Resolve quiet reporting and completion summary behavior

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 14:05:00 +00:00
parent 1f2beef08c
commit 68e16f6aac
1 changed files with 57 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/roadmap/commandkit.md
View File

@@ -99,6 +99,34 @@ 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.
## Quiet Mode and the Completion Summary — Resolved
Adopt CommandKit's standard visibility rules. Emit the completion summary and
created report/debug locations as informational diagnostics through the shared
reporter, using deferred information when final ordering requires it. Show them
in verbose and debug modes; suppress them in ordinary and quiet modes. Keep
diagnostics separate from transcript stdout and announce completion only after
processing and enabled required outputs have succeeded.
| Output | Ordinary | Verbose/debug | Quiet |
| --- | --- | --- | --- |
| Transcript on stdout, when selected | Shown | Shown | Suppressed |
| Completion summary and created artifact locations | Hidden | Shown | Hidden |
| Requested transcript and ordinary report files | Written | Written | Written |
| Fatal error explanation | Shown | Shown | Shown |
Debug capture follows the independent boolean decision above in every reporting
mode. Quiet does not cancel processing or suppress file writes. Recoverable
model-operation failures retain their domain meaning and ordinary report records;
do not promote them to fatal errors or warnings merely to make them visible.
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.
## Work Outline
The adoption gate above applies to implementation in this outline; preparatory
@@ -118,9 +146,10 @@ design and inventory work can proceed before it opens.
integration selected in the master roadmap. Do not use a broad private CLI
framework around CommandKit.
4. Adapt domain process handlers to reporting/outcome boundaries, preserving
transcript/artifact integrity, cancellation, and partial success. Specify quiet
mode, completion summaries, and write failures before implementation. Standard
command statuses, including comparison status 3, should not be forced into the
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.
Wire processing artifact capture to the shared debug boolean once the public
binding API is available; remove Audita's independent debug flag declaration
@@ -143,6 +172,13 @@ 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 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
well as enabled, and document the loss of the former default summary.
Verify the independent capture and visibility decisions through CommandKit's
parser for processing commands:
@@ -210,20 +246,26 @@ or reparsing arguments. The mode accessor alone does not unblock capture wiring.
## Open Decisions
### Quiet Mode and the Completion Summary
### Quiet Processing Without a Transcript File
**Recommendation:** start with CommandKit's normal visibility rules, including
quiet suppression of command output, and document their effect on stdout
transcripts. File artifacts remain domain outputs. Determine whether the existing
always-visible completion summary serves a domain need or can become standard
verbose information. Do not silently hide it merely by changing its implementation
to `Reporter.Info`; make the operator behavior change explicit.
**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.
**Alternative:** preserve transcript payloads under quiet mode or preserve an
ordinary-mode diagnostic summary through a shared upstream reporting capability.
This can serve pipelines and operators who distinguish payloads from messages,
but diverges from current core semantics and needs a concrete use case. Prefer an
upstream change over bypassing standard reporting or inventing local quiet rules.
**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