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. 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, ckconfig, and ckprompt v0.5.0 as the standard operator interface. 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. There is no known publication blocker to adoption.

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 effective debug mode also enables Audita artifact capture for processing runs, 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 effective reporting mode after CommandKit applies its flag ordering, aliases, and explicit boolean rules. It does not depend merely on whether --debug appeared somewhere in the arguments.

Inspection commands keep standard debug reporting without creating processing artifacts. Help and migration guidance must explain that processing in debug mode also writes diagnostic files, and processing output must identify their location. Retain Audita's artifact redaction and lifecycle responsibilities. The accepted tradeoff is that debug reporting for processing also enables artifact capture; there is no separate capture switch in this design.

Use a supported public accessor for the effective mode to initialize capture. The upstream review below identifies the missing API and proposed change.

Work Outline

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. Specify quiet mode, completion summaries, and 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 effective debug mode once the public reporting-state API is available; remove Audita's duplicate debug flag binding.
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 processing in effective debug mode both reports debug details and captures artifacts, while inspection does not create processing artifacts. Cover mode ordering and explicit false values through CommandKit's parser, including --debug --quiet, --quiet --debug, and --debug --debug=false. Check artifact location reporting and help text explaining the combined behavior.

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. No request has yet been submitted. First 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.

Upstream Review: Effective 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.

Proposed upstream request: expose the resolved mode through a read-only public API on the invocation or reporter. Prefer a typed ordinary/quiet/verbose/debug value, with exact naming left to upstream. It should report the final selection after native parsing and aliases, be available before the handler starts capture, and preserve invocation isolation. No mutable parser or reporter internals need to be exposed.

This is an identified integration blocker for combined debug reporting and capture in v0.5.0. Request and adopt the upstream addition before implementing that wiring; do not inspect private state, infer the mode from emitted output, or reimplement argument parsing in Audita. No upstream request has been submitted by this review.

Open Decisions

Quiet Mode and the Completion Summary

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.

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.

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.