Select CommandKit v0.6.0 and close the release gate

This commit is contained in:
2026-11-09 14:18:34 +00:00
parent 97f6f48098
commit f1fced498a
2 changed files with 95 additions and 137 deletions

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.

View File

@@ -4,7 +4,7 @@
**Status:** Agreed direction with proposed sequencing. Initial outlines only;
no implementation or dependency changes have been made for this plan. Resolve
the three remaining [open decisions](#open-decisions) in the listed order.
the two remaining [open decisions](#open-decisions) in the listed order.
## Objective and Document Ownership
@@ -81,7 +81,7 @@ For each friction point, record the desired outcome, whether the constraint is
library behavior or an Audita domain requirement, the proposed adaptation or
upstream request, and its acceptance evidence. Distinguish agreed decisions from
recommendations. The [CommandKit outline](commandkit.md#upstream-review-shared-debug-input-and-reporting-mode)
records the reporting request and resulting upstream capability plan.
records the released reporting capabilities and adoption evidence.
## Baseline and Selected Dependency Set
@@ -90,34 +90,32 @@ The reviewed application revision is
uses old-path ConfigKit v0.7.1 and PromptKit v0.14.0, with no CommandKit.
The source minimum is Go 1.26.0; the release runbook selects Go 1.26.8.
The following versions were reviewed as published and mutually aligned.
CommandKit and its integrations are review baselines; final adoption selection
is subject to the release gate below:
The following published versions are selected for adoption. CommandKit core and
both integrations use the reviewed v0.6.0 release set; its release gate is
satisfied as recorded below:
| Module | Version | Reviewed source commit |
| --- | --- | --- |
| `go.maximumdirect.net/configkit` | v1.1.0 | `191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9` |
| `go.maximumdirect.net/promptkit` | v0.20.0 | `8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf` |
| `go.maximumdirect.net/commandkit` | v0.5.0 | `49f2d09ccde3d91d8c412a44ab934f223bef8fe6` |
| `go.maximumdirect.net/ckconfig` | v0.5.0 | `5c960532552037d38119941389e558f78bf73aad` |
| `go.maximumdirect.net/ckprompt` | v0.5.0 | `88ac6e76e4b164571f4172c01d7679c043b94a02` |
| `go.maximumdirect.net/commandkit` | v0.6.0 | `1613ff95cab60581de5d86f6e9e2a3cc091a44a0` |
| `go.maximumdirect.net/ckconfig` | v0.6.0 | `5ed947bd26bf2c6d70d1d748b693eca89f18d605` |
| `go.maximumdirect.net/ckprompt` | v0.6.0 | `1ca660e35fb58fc0dc318e411afb6e3631a40ef1` |
The integration tags are `integrations/ckconfig/v0.5.0` and
`integrations/ckprompt/v0.5.0` in CommandKit's repository. Use the
[corrected module selection guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/88ac6e76e4b164571f4172c01d7679c043b94a02/docs/consumers/guide.md#module-selection);
the core tag's guide predates integration publication. The former missing
`AdaptDiagnostics` blocker is resolved. Changes to these reviewed targets need
an ordinary compatibility review, not an assumption that later releases are
interchangeable.
The integration tags are `integrations/ckconfig/v0.6.0` and
`integrations/ckprompt/v0.6.0` in CommandKit's repository. Use the
[released module selection guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/1ca660e35fb58fc0dc318e411afb6e3631a40ef1/docs/consumers/guide.md#module-selection).
The integration updates retain ConfigKit v1.1.0 and PromptKit v0.20.0 and require
Go 1.27. Changes to these selected versions require an ordinary compatibility
review rather than assuming later releases are interchangeable.
**CommandKit release gate:** adoption implementation waits for a published core
version providing both the independent shared debug binding for capture and the
resolved reporting-mode accessor for quiet destination validation, as required by
the [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access).
Either API alone is insufficient. Replace the reviewed v0.5.0
core target with that release and record compatible released integration versions
and exact source revisions after review. No replacement version is selected yet;
this is [open decision 1](#1-commandkit-released-dependency-set).
**CommandKit release gate — satisfied:** the published v0.6.0 core provides both
the independent shared debug binding for capture and the resolved reporting-mode
accessor for quiet destination validation. The matching released integrations
were reviewed together. The [CommandKit outline](commandkit.md#adoption-gate-released-debug-binding-and-reporting-mode-access)
records the API contract and review evidence. The selected release set removes
the upstream availability blocker; Audita implementation and acceptance remain
pending under the sequence below.
ReleaseKit v0.9.0 at `go.maximumdirect.net/releasekit` is also a required target.
The library graph already brings in that version, but Audita's direct tool still
@@ -153,13 +151,11 @@ for Audita's complete release workflow.
providers. Avoid a permanent replacement or dual configuration engine.
Identify and remove local code made redundant by the adopted facilities as
part of each migration, rather than leaving cleanup as an unspecified follow-up.
4. **After the CommandKit release gate opens, integrate core and both standard
integrations.** Confirm both required public APIs are published and
select the released dependency set as described above before starting this
implementation stage. Complete the previously designed operator interface,
adapting Audita domain handlers and resolving upstream issues. Earlier design
and independent library work may proceed while waiting. This remains required
scope for the next major release.
4. **Integrate the selected CommandKit core and both standard integrations.**
The upstream release gate is satisfied. Complete the designed operator
interface using the selected v0.6.0 set, adapting Audita domain handlers and
verifying the assembled application. Resolve concrete new integration gaps
upstream. This remains required scope for the next major release.
5. **Add stage-specific glossary inputs.** After all four library adoptions,
complete the [glossary-stage roadmap](glossary-stages.md). Use the adopted
configuration and CLI conventions to compose reusable glossary assets through
@@ -186,7 +182,7 @@ implementation stage is ready.
## ReleaseKit Adoption Work
The concrete workflow and validator selection remain
[open decision 2](#2-releasekit-workflow-and-validator-selection).
[open decision 1](#1-releasekit-workflow-and-validator-selection).
1. Review v0.9.0's supported release workflow, validators, and version integration.
Inventory Audita's launcher, scripts, CI responsibilities, and local release
@@ -220,8 +216,12 @@ contracts. Disposable checks using Go 1.27.3 established:
- CLI parent overrides do not rerun ConfigKit inheritance. PromptKit same-ID
replacement drops omitted provider settings; distinct native inheritance can
retain them. Profile null endpoints permit backend fallback.
- Tagged CommandKit core, ckconfig, and ckprompt suites pass independently with
released dependencies, `GOWORK=off`, and no local replacements.
- Tagged CommandKit core, ckconfig, and ckprompt v0.6.0 suites pass independently
with released dependencies, `GOWORK=off`, and no local replacements.
- A separate consumer of all three published v0.6.0 modules passes 33 cases
covering debug capture, reporting-mode ordering, aliases, and quiet transcript
destination validation. The assembled graph retains the selected ConfigKit and
PromptKit versions and brings in ReleaseKit v0.9.0.
These are review results, not implementation acceptance. They involved no live
provider calls and do not prove migrated Audita behavior or cross-platform
@@ -251,31 +251,10 @@ and retain shared license texts. Do not copy upstream policy inventories.
## Open Decisions
Work through these decisions in order. Recommendations below remain proposals;
the existing adoption principles and CommandKit release gate remain in force.
the existing adoption principles remain in force. CommandKit release selection
is resolved in the dependency set above.
### 1. CommandKit Released Dependency Set
Select and record published core, ckconfig, and ckprompt versions and exact
source revisions after verifying the required independent debug binding and
resolved reporting-mode accessor. The roadmap has not yet established that a
released set satisfies both requirements; historical review evidence does not
open the gate.
**Recommendation:** select a published core release that passes the required
behavior checks, retaining the reviewed integration versions if they remain
compatible. Verify the assembled dependency graph and capture/quiet-destination
cases before recording the gate as satisfied. This minimizes unrelated migration
scope while adopting the required public APIs. If no qualifying release is
available, keep the implementation gate closed and continue independent planning
and library work.
**Alternative:** adopt a newer compatible released set of core and both
integrations together. This may incorporate useful fixes and simplify alignment
with current upstream guidance, but requires reviewing additional behavior and
API changes. Neither option permits unreleased replacements, private-state
inspection, or duplicate argument parsing.
### 2. ReleaseKit Workflow and Validator Selection
### 1. ReleaseKit Workflow and Validator Selection
Inventory the current launcher, scripts, CI responsibilities, version integration,
and local release checks against ReleaseKit v0.9.0. Select the concrete workflow,
@@ -297,9 +276,9 @@ upstream except for justified domain checks. This can fit concrete CI needs but
retains local sequencing to maintain; prefer an upstream enhancement for a
reusable gap rather than permanently duplicating release machinery.
### 3. Output-Failure Behavior
### 2. Output-Failure Behavior
Resolve the [output-failure decision](commandkit.md#output-failure-behavior) in
the CommandKit roadmap after the two selections above. That document owns the
the CommandKit roadmap after the ReleaseKit selection above. That document owns the
recommendation, alternative, and behavior contract. This decision completes the
remaining write-failure detail before implementing the output/reporting boundary.