From 1f2beef08c6a7059b2233bd43257984f61cc4202 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 13:56:40 +0000 Subject: [PATCH] Gate CommandKit adoption on released shared debug binding --- docs/roadmap/commandkit.md | 39 +++++++++++++++++++++++++++----- docs/roadmap/library-adoption.md | 27 ++++++++++++++++------ 2 files changed, 53 insertions(+), 13 deletions(-) diff --git a/docs/roadmap/commandkit.md b/docs/roadmap/commandkit.md index 5eab4c5..189e808 100644 --- a/docs/roadmap/commandkit.md +++ b/docs/roadmap/commandkit.md @@ -3,15 +3,17 @@ **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 +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). ## 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 +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 command declarations, typed inputs, supplied-value tracking, help/version, reporting, and formatting. Audita handlers retain transcript processing and artifact responsibilities. @@ -21,8 +23,29 @@ The upstream [core release](https://forge.maximumdirect.net/base-layer/commandki [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. +Go 1.27. The former missing diagnostic adapter has been published; the required +shared debug binding introduces the release gate below. + +## Adoption Gate: Released Shared Debug Binding + +Begin CommandKit adoption implementation only after an upstream version is +published with a supported public binding for the parsed `--debug` boolean, +independent of the resolved reporting mode. A release containing only the +resolved-mode accessor does not satisfy this gate. Neither the v0.5.0 baseline +nor an implementation available only on upstream `main` is sufficient. + +Before opening the gate, review the published API against the capture behavior +and acceptance 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). +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. ## Agreed Operator Experience @@ -78,6 +101,9 @@ mode. The upstream review below records the matching capability plan. ## Work Outline +The adoption gate above applies to implementation in this outline; preparatory +design and inventory work can proceed before it opens. + 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. @@ -175,7 +201,8 @@ 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 +Adopt the supported shared binding once the [release gate](#adoption-gate-released-shared-debug-binding) +is satisfied. 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, diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 0dbd90b..b6bd5fb 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -1,6 +1,6 @@ # Next Major Release Roadmap -**Updated:** 2026-11-07 +**Updated:** 2026-11-08 **Status:** Agreed direction with proposed sequencing. Initial outlines only; no implementation or dependency changes have been made for this plan. @@ -72,7 +72,8 @@ They do not select unrelated work in [future.md](future.md). 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. No upstream request has been submitted by this planning work. +recommendations. The [CommandKit outline](commandkit.md#upstream-review-shared-debug-input-and-reporting-mode) +records the reporting request and resulting upstream capability plan. ## Baseline and Selected Dependency Set @@ -81,7 +82,9 @@ 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 targets were reviewed as published and mutually aligned: +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: | Module | Version | Reviewed source commit | | --- | --- | --- | @@ -99,6 +102,13 @@ the core tag's guide predates integration publication. The former missing an ordinary compatibility review, not an assumption that later releases are interchangeable. +**CommandKit release gate:** adoption implementation waits for a published core +version providing the independent shared debug binding required by the +[CommandKit outline](commandkit.md#adoption-gate-released-shared-debug-binding). +The resolved-mode accessor 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. + 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 uses old-path v0.4.1. Direct adoption includes reviewing the v0.9.0 release and @@ -133,10 +143,13 @@ 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. **Integrate CommandKit and both standard integrations.** Complete the - previously designed operator interface, adapting Audita domain handlers and - resolving upstream issues. This is required target scope, not an optional - follow-up whose justification is deferred. +4. **After the CommandKit release gate opens, integrate core and both standard + integrations.** Confirm the required shared debug binding is 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. 5. **Add stage-specific glossary inputs.** After all four library adoptions, complete the [glossary-stage roadmap](glossary-stages.md). Use the adopted configuration, resource, and CLI conventions to support ordered stages such