eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Select CommandKit v0.6.0 and close the release gate

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-09 14:18:34 +00:00
parent 97f6f48098
commit f1fced498a
2 changed files with 95 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/roadmap/commandkit.md
View File

@@ -2,57 +2,45 @@
**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).
**Status:** Adoption target selected; the upstream release gate is satisfied.
Implementation remains pending. The [master roadmap](library-adoption.md) owns
shared direction, exact dependency revisions, and sequencing; ConfigKit and
PromptKit 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
reporting, described in the [CLI contract](../cli.md). Adopt CommandKit core,
ckconfig, and ckprompt v0.6.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; the required
debug-input and reporting-mode APIs introduce the release gate below.
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/5ed947bd26bf2c6d70d1d748b693eca89f18d605/integrations/ckconfig/docs/releases/v0.6.0.md),
[ckprompt release](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/integrations/ckprompt/docs/releases/v0.6.0.md),
and [consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/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 retain ConfigKit v1.1.0 and PromptKit v0.20.0.
## 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:
**Satisfied by the selected v0.6.0 release set.** 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).
- 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.
Both required capabilities are available:
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.
- 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.
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.
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
@@ -101,11 +89,11 @@ creation does not require an always-visible message in quiet mode. Retain Audita
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.
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
@@ -192,8 +180,8 @@ 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.
The adoption gate above is satisfied. Follow the master sequence and selected
released dependency set when implementing this outline.
1. Inventory Audita commands, arguments, flags, supplied empty/false/zero values,
streams, and exit behavior against standard declarations. Record intentional
@@ -216,9 +204,9 @@ design and inventory work can proceed before it opens.
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.
Wire processing artifact capture to the released shared debug boolean; replace
Audita's independent debug parsing with the native binding 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
@@ -281,7 +269,7 @@ 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 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
@@ -289,43 +277,34 @@ 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.
On 2026-11-09, verified published upstream tags for core, ckconfig, and ckprompt
v0.6.0 against the exact revisions in the master roadmap. 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 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 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.
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.
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.
These checks establish the upstream gate; they do not replace Audita's assembled
integration acceptance. No additional upstream request was identified.
## Open Decisions
### Output-Failure Behavior
This is decision 3 in the [master discussion order](library-adoption.md#open-decisions).
This is decision 2 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.