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](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,
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](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. 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](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 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.

## 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 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](../cli.md), [configuration](../config.md), [operations](../operations.md),
   [subprocess integration](../integrations/subprocess.md), 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 the independent capture and visibility decisions through CommandKit's
parser for processing commands:

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

### 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 the supported shared binding once released. 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,
or reparsing arguments. The mode accessor alone does not unblock capture wiring.

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