diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index b4e9dfe..f48fb4b 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -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, diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index b6bd5fb..53386f2 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -103,9 +103,10 @@ an ordinary compatibility review, not an assumption that later releases are interchangeable. **CommandKit release gate:** adoption implementation waits for a published core -version providing the independent shared debug binding required by the -[CommandKit outline](commandkit.md#adoption-gate-released-shared-debug-binding). -The resolved-mode accessor alone is insufficient. Replace the reviewed v0.5.0 +version providing both the independent shared debug binding for capture and the +resolved reporting-mode accessor for quiet destination validation, as required by +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 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 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 - 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 implementation stage. Complete the previously designed operator interface, adapting Audita domain handlers and resolving upstream issues. Earlier design