From f1fced498abe47b0055e82b63b444e86341c6ca5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 9 Nov 2026 14:18:34 +0000 Subject: [PATCH] Select CommandKit v0.6.0 and close the release gate --- docs/roadmap/commandkit.md | 135 +++++++++++++------------------ docs/roadmap/library-adoption.md | 97 +++++++++------------- 2 files changed, 95 insertions(+), 137 deletions(-) diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index d93e2c4..12f4b58 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -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. diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 742c939..cbefaf9 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -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.