audita/docs/roadmap/commandkit.md

# CommandKit Adoption Outline

**Updated:** 2026-11-09

**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](library-adoption.md) owns shared direction
and sequencing; ConfigKit and PromptKit integration contracts are developed in
[their](configkit.md) [outlines](promptkit.md).

## Baseline and Target

Audita currently uses application-owned CLI parsing, inspection commands, and
reporting, described in the [CLI contract](../cli.md). 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](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/docs/releases/v0.5.0.md),
[ckconfig release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/integrations/ckconfig/docs/releases/v0.5.0.md),
[ckprompt release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/integrations/ckprompt/docs/releases/v0.5.0.md),
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
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](library-adoption.md#baseline-and-selected-dependency-set).
The concrete release selection is [master open decision 1](library-adoption.md#1-commandkit-released-dependency-set).
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.
- Apply the [resolved profile-summary decision](promptkit.md#profile-inspection-and-summary--resolved):
  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.

## Request Preview, Validation, and Smoke Commands — Resolved

Include standard ckprompt request preview, request validation, and the complete
smoke-command surface in the next major release. Enable the upstream adapters
and retain native commands, flags, reports, and outcomes. Smoke commands remain
explicit operator-invoked operations, separate from application startup and
automated release checks.

Use the standard request inputs directly where they suffice. Where Audita adds
role/profile selection, shared instructions, response schemas, or domain inputs,
reuse its processing request-construction helpers in the relevant adapters.
Preserve native operator overrides and keep generic requests usable without
Audita processing context. Request preview and validation operate on supplied
inputs; representative validator candidates can come from maintained fixtures
without running proposal inference as part of request construction.

Establish runtime and request construction first, then wire preview and
validation, followed by smoke commands and assembled-CLI verification. All are
required adoption scope. Address concrete integration blockers upstream rather
than silently omitting standard capabilities.

For standard CommandKit commands passed through by Audita, provide a concise
link to the upstream documentation for the adopted version. Upstream owns their
command reference and behavior explanations. Do not duplicate that documentation,
add local provider-call/cost warnings, or add caveats or workarounds for perceived
limitations of the standard capabilities. Audita documentation covers only its
own selectors, request construction, domain inputs, and application-specific
behavior. Apply this documentation boundary to the whole standard command suite.

## 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; resolve
   [output-failure behavior](#output-failure-behavior) 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. Enable the standard preview, validation, and full smoke capabilities using the
   resolved adapter and sequencing approach above. Share Audita request helpers
   where domain additions are needed; keep generic resource inspection independent
   of those domain inputs.
6. Update [CLI](../cli.md), [configuration](../config.md), [operations](../operations.md),
   [subprocess integration](../integrations/subprocess.md), examples, help,
   completion guidance, and migration documentation with implementation. Document
   Audita-specific behavior and link to upstream for standard command usage.
   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.

Verify preview, validation, and every standard smoke operation through the
assembled CLI using fixtures and controlled providers. Focus on Audita's command
registration, engine loading, input forwarding, shared request construction, and
native report/outcome handoff. Keep integration coverage proportionate rather
than duplicating upstream capability tests.

Tagged core and integration suites passed during review, but do not establish
these Audita behaviors. Use offline tests and controlled providers.

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](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/reporter.go),
[invocation API](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/identity.go),
and [mode rules](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/49f2d09ccde3d91d8c412a44ab934f223bef8fe6/docs/cli.md#modes-and-visibility)
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](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/ec0e58efff638d0d4cc2ef20e930a9d477ed2e83/docs/roadmap/shared-debug-binding.md)
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](#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

### Output-Failure Behavior

This is decision 3 in the [master discussion order](library-adoption.md#open-decisions).
Specify how failed transcript, report, debug-artifact, and standard reporter writes
influence the process outcome. The existing visibility rules and prohibition on
a successful completion summary after required-output failure remain selected.

**Recommendation:** required transcript and enabled ordinary-report failures fail
the invocation. Optional debug-artifact failures remain nonfatal and use the
standard reporting path with existing redaction and visibility rules. Standard
CommandKit reporter failures follow native behavior rather than an Audita-owned
replacement policy. This preserves the distinction between delivering the
requested product and retaining supplemental diagnostic evidence, while avoiding
a second reporting implementation. Validate the exact adopted reporter behavior
and cover early and late output failures, including a report failure after the
transcript has already been written.

**Alternative:** also make debug-artifact failures fatal when debug capture was
explicitly requested. This treats capture as a required deliverable and makes
incomplete evidence visible in the process outcome, but can fail an otherwise
successful transcript run solely because supplemental evidence could not be
saved. Standard reporter behavior would still remain upstream-owned. Choose the
artifact requirement deliberately rather than infer it from the debug reporting
mode, which remains independent of capture.