From 93dd406459815051359d6ecd25c90d7389c22cc0 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 19 Nov 2026 16:04:23 +0000 Subject: [PATCH] Record CommandKit versions and standard capability scope --- .../commandkit-migration-discussion.md | 91 +++++++++++++++---- 1 file changed, 74 insertions(+), 17 deletions(-) diff --git a/docs/roadmap/commandkit-migration-discussion.md b/docs/roadmap/commandkit-migration-discussion.md index c69be59b..05720698 100644 --- a/docs/roadmap/commandkit-migration-discussion.md +++ b/docs/roadmap/commandkit-migration-discussion.md @@ -19,6 +19,10 @@ dependency baseline, implementation phases, removal inventory, and acceptance criteria. No application or dependency changes have been implemented through this discussion. +Item 1 selects the dependency versions and standard capabilities, including +PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target. +Application-specific commands, wiring, and reporting details remain open below. + The PromptKit architecture and checkpoint decisions remain in force. This discussion develops the CommandKit portion of that migration and its interactions with U1 (dependencies), U9 (records/reporting), and U10 (CommandKit adoption). @@ -74,10 +78,9 @@ spending migration effort recreating existing CLI conventions. | Pipeline execution and listing, pipeline-specific preflight, artifact publication, checkpoints, and domain outcomes | Notarius application handlers and framework. | | Receipt content, debug artifact lifecycle, and application outcome meaning | Notarius, expressed through CommandKit's reporting and outcome conventions. | -Evaluate the full standard capability set and adopt applicable upstream commands -and recommendations directly. Optional capability selection remains open; assess -its usefulness rather than limiting the initial surface to commands Notarius -already has. +Adopt the standard capability suite selected in item 1, including upstream +commands and recommendations beyond the existing Notarius surface. The remaining +discussion determines application-specific inputs, wiring, and result content. Pipeline and domain code should remain independent of CommandKit. Native PromptKit observations supply execution facts; Notarius attaches application @@ -95,8 +98,8 @@ Two application needs already identified for deliberate treatment are: ### Intended Sequencing -1. Resolve compatible dependency versions and native command scope alongside the - dependency baseline, bringing U10 forward. +1. Incorporate item 1's selected dependency baseline and standard capabilities, + and resolve native application command design, bringing U10 forward. 2. Introduce CommandKit composition alongside native source assembly. Connect shared loaders and standard inspection while retaining application orchestration responsibilities. @@ -110,19 +113,73 @@ work units and their placement in the master roadmap follow the discussion below ## 1. Adoption Scope And Dependency Baseline -**Discussion / decision:** Detailed choices pending. +**Discussion / decision:** Versions and standard capability scope agreed. Adopt +the set below, including the move to PromptKit v0.23.3. Application-specific +command design and reporting details remain with the subsequent topics. These +are selected migration targets; the application dependencies have not changed. -- Which compatible tagged CommandKit, ckconfig, and ckprompt versions should join - the final PromptKit/ConfigKit dependency set? -- Which standard capabilities belong in the initial cutover, and which can remain - optional future additions? -- Are any actual Notarius requirements unsupported upstream, warranting a feature - request rather than retention of duplicate local mechanics? +### Selected Versions -The previously reviewed integrations already align with the roadmap's initial -PromptKit v0.23.2 and ConfigKit v1.2.1 targets. Confirm the selected release set -and attribution when this choice is resolved; do not infer final pins from the -current sibling checkouts. +| Module | Version | Role | +| --- | --- | --- | +| `go.maximumdirect.net/commandkit` | `v0.7.0` | Native command declarations, inputs, help/version, reporting, and completion. | +| `go.maximumdirect.net/ckconfig` | `v0.9.0` | Standard configuration commands and ConfigKit diagnostic classification. | +| `go.maximumdirect.net/ckprompt` | `v0.10.0` | Standard PromptKit inspection, validation, preparation, and smoke diagnostics. | +| `go.maximumdirect.net/configkit` | `v1.2.1` | Shared configuration dependency for the application and integrations. | +| `go.maximumdirect.net/promptkit` | `v0.23.3` | Native model execution, including corrected timeout/cancellation reporting. | + +The CommandKit integration releases form a documented compatible set using +PromptKit v0.23.2. Select v0.23.3 explicitly for its timeout attribution and +cancellation/error identity fixes. It retains the same dependencies and requires +no configuration or request API migration from v0.23.2. The Go consumer minimum +remains 1.27. Verify the assembled dependency set through the migration's normal +integration checks and update attribution when the dependency changes land. + +The version review used locally available release tags and tagged dependency +manifests. Remote release lookup was unavailable, so it did not establish whether +newer tags existed remotely. These are deliberate selected versions, not a claim +that every module is the latest published release. + +Evidence: [integration version guidance](../../../commandkit/docs/consumers/guide.md#module-selection) +and [PromptKit v0.23.3 release notes](../../../promptkit/docs/releases/v0.23.3.md). + +### Selected Standard Capabilities + +| Area | Adopt in the cutover | +| --- | --- | +| Core CLI | Native help, `version`, typed flags and operands, supplied-value semantics, standard outcomes, and command declaration/dispatch. | +| Reporting | Native `--format` with text/YAML/JSON, `--quiet`, `--verbose`, `--debug`, and `--progress`, including upstream visibility and failure behavior. | +| Configuration | `config scopes`, `validate`, `show`, `sources`, `explain`, and `diff`, for application and PromptKit configuration. | +| Resource discovery | PromptKit listings for prompts, profiles, backends, namespaces, and collections, with native filters and selectors. | +| Resource inspection | Native prompt, profile, and backend reports, plus requirements discovery. | +| Concrete request checks | Requirements validation and prepared-request preview using native inputs, variables, profiles, and execution overrides. | +| Provider diagnostics | Reachability, authentication, text-inference, structured-output, and aggregate smoke tests. | +| Convenience features | Bash, Zsh, and Fish completion, useful declaration hints, and upstream PromptKit convenience aliases. | + +Use the [upstream CLI conventions](../../../commandkit/docs/cli.md) directly. +Providing the standard capability suite means supplying application loaders and +callbacks, not recreating those commands locally. Upstream convenience aliases +are selected native features; this does not reintroduce legacy Notarius aliases. + +### Wiring Boundaries And Follow-Up + +- Keep configuration validation, requirements discovery, and concrete request + validation distinct. Pipeline preflight remains application-owned. Concrete + preparation may read inputs and schemas and check credentials even though it + makes no model call. +- Install smoke commands for explicit invocation. Their availability does not + introduce provider calls during startup, ordinary validation, or offline tests. +- Enable application configuration overrides through ConfigKit. The selected + PromptKit configuration scope does not support arbitrary `--set` overrides; + use supported request-level controls rather than implementing a local equivalent. +- Retain application handlers for pipeline execution and discovery, with native + commands, inputs, and result presentation to be designed in items 2–5. + +No upstream feature request has been identified as a blocker for this scope. +Evaluate any later demonstrated gap on its actual application need. On roadmap +reconciliation, incorporate these versions into U1, replace U10's open standard +capability selection with this decision, and retain the unresolved application +wiring and presentation details explicitly. ## 2. Native Command Surface And Inputs