audita/docs/roadmap/commandkit.md

# CommandKit Adoption Outline

**Updated:** 2026-11-10

**Status:** Adoption target and design decisions resolved; the upstream release
gate is satisfied. Implementation remains pending. The
[master roadmap](library-adoption.md) owns shared direction and exact dependency
revisions; the [implementation plan](implementation.md) owns sequencing. See the
[ConfigKit](configkit.md) and [PromptKit](promptkit.md) outlines for their contracts.

## Baseline and Target

Audita currently uses application-owned CLI parsing, inspection commands, and
reporting, described in the [CLI contract](../cli.md). Adopt CommandKit core v0.6.0
with ckconfig and ckprompt v0.7.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/1613ff95cab60581de5d86f6e9e2a3cc091a44a0/docs/releases/v0.6.0.md),
[ckconfig release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/64f6453b8453f914f272d427bb4ae6f59deacd2b/integrations/ckconfig/docs/releases/v0.7.0.md),
[ckprompt release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/integrations/ckprompt/docs/releases/v0.7.0.md),
and [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/consumers/guide.md)
define the selected set. Core uses Cobra/pflag and declares Go 1.26.0; the matched
integrations require Go 1.27. They select ConfigKit v1.2.0 and PromptKit v0.21.0.
The integration updates preserve their public adapters; wire processing and all
inspection commands to the shared loaders and recorded application context
described in the ConfigKit and PromptKit outlines.

## Adoption Gate: Released Debug Binding and Reporting Mode Access

**Satisfied by core v0.6.0 and the selected v0.7.0 integrations.**
Upstream publication, public APIs,
released integration dependencies, and the required behavior were verified in the
[review below](#upstream-review-shared-debug-input-and-reporting-mode).

Both required capabilities are available:

- A `BoolFlag` named `debug` attaches to the shared reporting option and supplies
  its parsed boolean independently of the reporting mode for artifact capture.
- `Invocation.ReportingMode()` exposes the resolved reporting mode for quiet
  transcript-destination validation.

The [master dependency selection](library-adoption.md#baseline-and-selected-dependency-set)
records exact published versions and source revisions. No unreleased dependency,
local replacement, private-state inspection, or duplicate argument parsing is
needed. Audita integration and its acceptance tests remain implementation work;
the released capabilities remove the upstream availability blocker.

## 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 released optional `BoolFlag` binding named `debug`, with a false
default, to initialize capture from its typed boolean value. The
resolved-mode accessor serves destination validation and reporting decisions;
capture follows the bound value independently. The upstream review below records
the matching released contract.

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

## Output-Failure Behavior — Resolved

Require successful delivery of the transcript and enabled ordinary reports.
Debug artifacts remain optional even when capture was explicitly requested.
Adopt CommandKit's native handling of CLI output and diagnostic write failures.

| Output | Failure behavior |
| --- | --- |
| Transcript file or stdout | Fail the invocation. |
| Enabled ordinary reports | Fail the invocation if any required report cannot be written. |
| Debug directory or individual debug artifacts | Continue processing and submit a redacted warning through CommandKit. |
| CommandKit output and diagnostic streams | Preserve the native outcome and delivery-error behavior. |

Ordinary reports describe incomplete work, recoverable model failures, and
repairs. When enabled, delivering that account is part of completing the run.
Debug artifacts provide supplemental investigative detail; their loss alone does
not invalidate a delivered transcript and reports. Do not add a debug strictness
option.

Detect required-destination problems before model work wherever practical through
the [output preparation below](#output-resource-preparation-during-preflight--resolved).
If a required output fails later, retain successfully written files, fail the
invocation, and attempt to finalize the remaining reports with the failure
recorded. A report failure after transcript publication must not erase that
transcript or repeat model calls. Preserve the original processing failure when
secondary reporting or cleanup also fails. Emit the completion summary only
after processing and all enabled required outputs have succeeded, including
required final writes, closes, and file replacements.

Use the existing redaction and resolved visibility rules for debug warnings.
In particular, `--debug --quiet` still attempts capture but suppresses warnings
about missing optional artifacts; required-output failures retain the normal
fatal-error explanation. A separate failure while writing a warning can still
make the invocation fail under CommandKit's native
[output-failure contract](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.6.0/docs/cli.md#output-failures).
Keep that outcome under upstream ownership rather than overriding it to make
diagnostic stream failures nonfatal.

## Output Resource Preparation During Preflight — Resolved

Prepare output resources as part of Audita's expressly named
`internal/framework/preflight` phase, after ConfigKit handoff and before model
calls. Follow the [preflight package boundary](glossary-stages.md#empty-collections-and-audita-preflight--resolved).
Complete configuration, invocation, and domain-readiness checks for the entire
pipeline first, including the quiet-destination rule and active destination
collision checks. Only then prepare output resources, and begin execution after
required preparation succeeds. Disabled report and debug destinations remain
inactive.

- For a regular transcript destination, create and open a temporary file in its
  destination directory before processing. Preserve the existing destination
  until processing and writing succeed, then replace it. This also preserves
  input when the transcript intentionally replaces its own source; preparation
  must not truncate the final path.
- Initialize enabled ordinary reports before processing, using the existing
  `in_progress` report lifecycle and per-file replacement. An initialization
  failure stops the invocation before model work.
- When debug capture is enabled, create its directory and initial artifacts
  early. Create later artifacts as needed instead of opening every possible
  artifact in advance. Debug preparation failures follow the nonfatal artifact
  rule above.
- Use CommandKit's supplied writer for transcript stdout. Defer opening pipe and
  device destinations until output delivery; in particular, opening a named pipe
  during preflight could block waiting for its reader. Do not replace these
  destinations with regular temporary files.

The preflight package coordinates preparation through the output-session
component. Reuse and adapt that component to own prepared handles, cleanup, and
final publication; keep filesystem machinery out of individual readiness checks.
Close owned handles and remove unpublished temporary files on failure or
cancellation, while retaining published outputs and retained diagnostic evidence.
The caller retains ownership of supplied standard streams.

Opening resources early establishes readiness at that point; later writes,
closes, and replacements can still fail. Apply the output-failure rules throughout
execution and finalization. Preserve per-file publication without adding a
transaction across the transcript and reports.

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

All three capabilities 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.

## Integration Boundaries

The native `app` and PromptKit configuration scopes are distinct. Both sides of
native comparison use their own selected inputs. Scope validation follows native
scope behavior; process preflight checks what execution needs. The same
engine-loading path and
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved)
serve processing and all standard PromptKit commands. ReleaseKit supplies the
application version; CommandKit owns standard flags, formats, help, completion,
and outcomes, including native comparison status 3.

Audita supplies typed process inputs, domain request construction, preflight,
and output-session coordination. [Glossary readiness](glossary-stages.md#empty-collections-and-audita-preflight--resolved)
is part of that shared phase. Standard inspection remains independent of
processing inputs. Canonical Audita documentation owns application-specific
behavior and the hard cutover; standard commands link to the adopted upstream
reference. Exact selected dependencies and notices belong in attribution.

## 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 automatic prompt replacements and their origins agree between
processing, resource/configuration inspection, and request preview. Apply the
shared loader's source selection to validation and smoke commands as well, using
controlled provider boundaries for smoke acceptance. Inspection must retain the
same source behavior without requiring processing inputs or starting preflight.

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 required-output preparation failure before model calls, late write/close/
replacement failures, and report failure after a transcript has been published.
Verify retention of published output, preservation of the original processing
failure when reporting also fails, and attempts to finalize available reports.
Exercise optional debug-directory and artifact failures, including suppressed
warnings in quiet mode, and the native CommandKit outcome when a diagnostic
write itself fails. Keep these checks focused on Audita's integration and output
responsibilities rather than duplicating upstream reporter tests.

Verify that readiness failures occur before output resources are created.
Check that preparing regular transcript output preserves existing content,
including an in-place transcript, and that failure or cancellation closes owned
resources and removes unpublished temporary files. Cover enabled report
initialization, inactive disabled destinations, and debug artifacts created as
needed. Confirm that preflight does not open pipe/device destinations and that
supplied standard streams remain caller-owned.

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 request is fulfilled by the released capabilities 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-09, verified published upstream tags for core, ckconfig, and ckprompt
v0.6.0, the then-selected release set. Reviewed the core
source changes and external public-API tests. Compared with the previous reviewed
integration releases, ckconfig and ckprompt change dependency pins and release
notes without changing integration implementation.

The released [binding contract](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1613ff95cab60581de5d86f6e9e2a3cc091a44a0/binding.go)
and [invocation API](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1613ff95cab60581de5d86f6e9e2a3cc091a44a0/identity.go)
support the selected design. The shared binding preserves supplied-value tracking,
explicit false, repeated occurrences, and aliases. Application defaults affect
the bound input, not reporting-mode selection; Audita selects a false default.
`Invocation.ReportingMode()` reports the selection independently of delivery
success and remains available after finalization. `--debug --quiet` therefore
retains a true capture input while the reporting mode is quiet.

Using Go 1.27.3, all three tagged module suites passed with `GOWORK=off` and
released dependencies. An isolated consumer importing all three published v0.6.0
modules, without local replacements, passed 33 cases spanning the roadmap's
capture/mode combinations, aliases, and quiet-destination policy. The resolved
graph selected the intended ConfigKit v1.1.0 and PromptKit v0.20.0 dependencies.

On 2026-11-10, the newly selected ckconfig and ckprompt v0.7.0 tagged suites
also passed independently with released dependencies. Their changes update
dependency pins and release documentation without changing adapter implementation.
The new graph selects ConfigKit v1.2.0, PromptKit v0.21.0, and core v0.6.0.
These checks establish the upstream gate; they do not replace Audita's assembled
integration acceptance. No additional upstream request was identified.