audita/docs/roadmap/commandkit.md

CommandKit Adoption Outline

Updated: 2026-11-08

Status: Initial outline. Adoption is part of the agreed target, not an optional future evaluation. Implementation is gated on the upstream release described below. The master roadmap owns shared direction and sequencing; ConfigKit and PromptKit integration contracts are developed in their outlines.

Baseline and Target

Audita currently uses application-owned CLI parsing, inspection commands, and reporting, described in the CLI contract. Adopt CommandKit core and compatible releases of ckconfig and ckprompt as the standard operator interface. The reviewed v0.5.0 set is a baseline, not the final adoption target. Use supported command declarations, typed inputs, supplied-value tracking, help/version, reporting, and formatting. Audita handlers retain transcript processing and artifact responsibilities.

The upstream core release, ckconfig release, ckprompt release, and consumer guide 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 debug-input and reporting-mode APIs introduce the release gate below.

Adoption Gate: Released Debug Binding and Reporting Mode Access

Begin CommandKit adoption implementation only after an upstream version is published with both supported public capabilities:

• 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. No future version number is assumed. The integrations need new releases only if their existing releases are incompatible with the selected core version.

Design, command inventories, and upstream coordination may continue while waiting, as may the independent library work in the master sequence. Do not bypass the gate with an unreleased dependency, local replacement, or duplicate debug parsing. CommandKit adoption remains required for Audita's next major release.

Agreed Operator Experience

• Install the full ckprompt inspection surface: prompt/profile/backend views, resource and namespace/collection inventories, contextual requirement inspection, and captured engine configuration through its config scope. Native reports and namespace selection must remain available; a curated Audita subset is not a substitute. Inspection success is not execution readiness.
• Apply the resolved profile-summary decision: retire the curated profiles view, use standard configuration/resource inspection and request preview, and add no replacement custom role summary at this stage.
• Adopt standard ckconfig viewing, validation, sources, path discovery, explanation, and comparison. Use native evidence and common text/YAML/JSON rendering. Do not recreate removed provider-specific explanation writers.
• Use standard command names and reporting flags. CommandKit owns --debug; its parsed boolean also enables Audita artifact capture for processing runs, independently of the resolved reporting mode, as resolved below.
• Keep domain transcript serialization and ordinary report files under Audita's output contracts. Generic report formatting need not transform transcript JSON. Preserve meaningful partial success: a work-unit model error is not automatically a failed CLI invocation or a reporter warning.
• Preserve safe library redaction without restricting standard inspection to today's curated fields. Loading for help/version must not trigger credentials, provider calls, or domain processing.

Debug Reporting and Artifact Capture — Resolved

Use one --debug flag for detailed diagnostics: standard CommandKit debug reporting plus retained Audita diagnostic artifacts during processing. Do not introduce --debug-artifacts, duplicate the reserved flag, or add a second parser. Artifact capture follows the parsed --debug boolean independently of the resolved reporting mode. In particular, --debug --quiet suppresses ordinary CLI output while retaining diagnostic artifacts; --debug --verbose also retains them. CommandKit continues to own CLI visibility and mode ordering.

Use the native boolean semantics: omission disables capture, --debug enables it, --debug=false disables it, and the last debug occurrence wins. Quiet and verbose flags do not rewrite this value. Aliases refer to the same input; tokens consumed as other flag values or following -- do not count as debug flags.

Inspection commands keep standard debug reporting without creating processing artifacts. Help and migration guidance must explain that supplying --debug for processing also writes diagnostic files, including when quiet suppresses output. Report artifact locations through CommandKit's normal visibility rules; artifact creation does not require an always-visible message in quiet mode. Retain Audita's 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 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

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	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

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 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

The adoption gate above applies to implementation in this outline; preparatory design and inventory work can proceed before it opens.

1. Inventory Audita commands, arguments, flags, supplied empty/false/zero values, streams, and exit behavior against standard declarations. Record intentional migrations rather than recreating the old parser around CommandKit.
2. Establish shared loaders and scopes using the native ConfigKit and PromptKit integrations. Keep configuration/resource inspection distinct from preparing an actual domain request. Standard scope validation need not reproduce the current combined settings-and-two-roles command; process setup must still establish what execution needs. Review generic override forwarding explicitly.
3. Install standard inspection and configuration commands, native formats, help/version, and suite-consistent aliases/completion through supported APIs. Supply the application's version identity from the ReleaseKit v0.9.0 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. 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. 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.
5. Develop concrete request adapters for preview, validation, and any selected smoke commands. They need correct variables, schema contracts, and credential handling, not just an engine loader. Keep generic resource inspection independent of those domain inputs and distinguish generic from Audita-prepared requests.
6. Update CLI, configuration, operations, subprocess integration, examples, help, completion guidance, and migration documentation with implementation. Adopt the dependencies and exact attribution together.

Acceptance and Upstream Requests

Check the complete standard inspection/configuration inventory and native formats through the assembled CLI, including failed-load evidence, redaction, source selection, and missing/partial resources. Check help/version without 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. 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 with a valid explicit transcript destination:

Arguments after the command path	Reporting mode	Capture artifacts
None	Ordinary	No
--debug	Debug	Yes
--debug --quiet	Quiet	Yes
--quiet --debug	Debug	Yes
--debug --verbose	Verbose	Yes
--debug --debug=false	Ordinary	No
--debug=false --debug	Debug	Yes
--debug --quiet --debug=false	Quiet	No

Check aliases, explicit false values, and option-looking operands or values through native parsing. Inspection must not create processing artifacts even with debug enabled. Check artifact-location reporting subject to normal visibility and help text explaining capture under quiet mode.

Tagged core and integration suites passed during review, but do not establish these Audita behaviors. Use offline tests and controlled providers; explicitly invoked smoke operations may contact providers and incur costs, but are not an 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. 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

On 2026-11-08, verified upstream main at 69257066e21c12ea3492237ebee072598adea60c and the v0.5.0 tag at 49f2d09ccde3d91d8c412a44ab934f223bef8fe6. The relevant reporting and invocation implementation is unchanged between those revisions. Public API inspection of v0.5.0 confirms that neither Invocation nor Reporter exposes the effective reporting mode. Reporter.Debug emits a message; it is not a mode query. Parsed reporting selection and the reporter's mode are internal.

The upstream reporter, invocation API, and mode rules define the reviewed behavior.

The original request proposed using a read-only resolved-mode accessor for capture. The corrected requirement above supersedes that use: quiet reporting must not clear an independently enabled capture request.

The CommandKit checkout at ec0e58efff638d0d4cc2ef20e930a9d477ed2e83 contains a shared-debug plan covering both a typed debug binding and a resolved-mode accessor. It explicitly 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 both capabilities once the release gate 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

Request Preview, Validation, and Smoke Commands

Recommendation: include standard offline request preview and validation, and expose smoke diagnostics as explicit operator-invoked commands once the request adapter is correct. This best supports the suite happy path. Generic inspection remains available without a runnable request, and smoke results must retain unknown/unsupported facts rather than imply provider readiness.

Alternative: deliver the agreed full inspection/configuration surface first, then add request operations in a named follow-up stage if their adapter needs upstream work. This limits premature request semantics but leaves a temporarily incomplete suite experience. It is not permission to defer the full inspection set or to silently omit commands because they were absent from old Audita.