From 68e16f6aac710c58af18213be0ea1cfee4994b58 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 14:05:00 +0000 Subject: [PATCH] Resolve quiet reporting and completion summary behavior --- docs/roadmap/commandkit.md | 72 ++++++++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 15 deletions(-) diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 189e808..b4e9dfe 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -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