From 7b9b945baa8c85969554bf4e33d96389d164a879 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 17 Oct 2026 15:02:03 +0000 Subject: [PATCH] Plan ConfigKit, PromptKit, and ReleaseKit upgrades --- docs/roadmap/upgrades.md | 389 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 389 insertions(+) create mode 100644 docs/roadmap/upgrades.md diff --git a/docs/roadmap/upgrades.md b/docs/roadmap/upgrades.md new file mode 100644 index 0000000..822e94d --- /dev/null +++ b/docs/roadmap/upgrades.md @@ -0,0 +1,389 @@ +# ConfigKit, PromptKit, and ReleaseKit adoption + +Status: adoption roadmap; implementation has not started. The release targets +and adoption order are agreed. Detailed presentation and capability choices +under Open Decisions remain proposals. This document defines the desired end +state and required work; a separate implementation plan will sequence coding +tasks. + +## Purpose and authority + +Adopt ReleaseKit v0.4.2, ConfigKit v0.8.0, and PromptKit v0.16.0 while providing +useful operator access to their capabilities. The organizing principle remains: +**CommandKit provides useful, consistent access to capabilities owned elsewhere.** + +CommandKit owns vocabulary, registration, selection, coordination, presentation, +and invocation outcomes. Integrated libraries own configuration composition, +resource identity and resolution, validation, inspection evidence, and diagnostic +meaning. Applications choose their inputs, policies, defaults, credentials, +artifacts, and runtime construction. + +The [architecture policy](../policy/architecture.md), accepted [ADRs](../adr/), +and [release policy](../policy/release.md) govern this work. Upstream contract +changes flow through the owning integration; they do not justify reimplementing +removed behavior in CommandKit. The existing API and CLI references describe the +current implementation until these changes land. + +## Baseline and reviewed releases + +The CommandKit baseline is `5f633e3feea71f623e5e378a7df476ff7e811e5e`. + +| Dependency | Current baseline | Target | Owning CommandKit area | +| --- | --- | --- | --- | +| ReleaseKit | Root tool requirement v0.4.0; integration graphs currently select v0.4.1 | v0.4.2 | Root tool pin, launcher integration, release documentation, and notices | +| ConfigKit | v0.7.1 in both integrations | v0.8.0 | ckconfig adaptation and reports; ckprompt's direct dependency | +| PromptKit | v0.15.0 | v0.16.0 | ckprompt adapters, standard commands, reports, and composed consumer | + +The root module owns generic commands, dispatch, bindings, help/version, and +outcomes. ckconfig owns the configuration family. ckprompt currently supplies +prompt/profile catalogs, named inspection, requirements discovery, and concrete +request validation; its engine configuration scope is composed through ckconfig. + +The completed requirements roadmap, implementation plan, and remediation record +remain historical evidence for the delivered baseline. This roadmap describes +new work and does not restart those completed assignments. + +Reviewed upstream references: + +| Release | Source commit | Release record | +| --- | --- | --- | +| ReleaseKit v0.4.2 | `7d033c5ca1c95aec7db9690293638a0a1ac887b8` | [Release notes](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/7d033c5ca1c95aec7db9690293638a0a1ac887b8/docs/releases/v0.4.2.md) | +| ConfigKit v0.8.0 | `137769f3f18a370c68444242fb5d88e620e307e5` | [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/docs/releases/v0.8.0.md) | +| PromptKit v0.16.0 | `9178f3eb91c2b2138caa78e22be93c048b4bc992` | [Release notes](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/releases/v0.16.0.md) | + +All three releases retain Go 1.26.0 as their consumer minimum. The adoption does +not require changing CommandKit's Go minimum or selected release toolchain. + +## Adoption order and delivery boundaries + +| Order | Adoption | Reason | +| --- | --- | --- | +| First | ReleaseKit v0.4.2 | A small, independent maintainer-tool update establishes the selected tool before integration migration. | +| Next | ConfigKit v0.8.0, including richer source inspection | Supplies the prerequisite for PromptKit v0.16.0 and exposes useful native evidence through ckconfig. | +| Then | PromptKit v0.16.0 API/configuration migration | Removes obsolete version selectors and bundled-catalog assumptions across ckprompt. | + +Expanded PromptKit discovery follows its base migration. Explicit smoke +diagnostics are a distinct follow-on capability, with the delivery boundary +recommended in OD-4. These are product/dependency relationships, not a staged +implementation plan or a requirement for separately releasable intermediate +commits. ConfigKit and PromptKit can be handled in one coordinated sprint. + +ReleaseKit has no runtime ordering dependency on the other two. ConfigKit must +be adopted before, or atomically with, PromptKit: Go module selection would +otherwise introduce v0.8.0 transitively while ckconfig still declares v0.7.1. +Keep both integrations' direct ConfigKit requirements aligned with the adopted +version and verify their independent module graphs. + +Publication remains source-only and follows the existing +[core, ckconfig, ckprompt dependency order](../release.md#scope-and-release-order) +for affected releases. CommandKit module versions remain independent of upstream +version numbers. Explain intentional public API/CLI changes under the existing +pre-v1 compatibility policy; select concrete release versions during release +preparation. + +## Target state: ReleaseKit v0.4.2 + +The root Go tool requirement selects ReleaseKit v0.4.2. The existing launcher, +three module profiles, shared-file selection, and source-publication procedure +continue using its supported public contracts. No application command family or +runtime ReleaseKit import is added. + +v0.4.1 changed upstream test synchronization. v0.4.2 corrected maintained +Woodpecker delivery workflows for annotated-tag-object events; their event and +tag IDs are resolved to commits before verification and delivery. CommandKit +has no copied Woodpecker delivery workflow and publishes no hosted deliverables, +so adopting this patch does not require adding either. + +Required work includes the root requirement/checksums, selected-graph notices, +the version named in the release policy, and version/commit references in the +maintainer release procedure. Review the launcher and release integration against +the unchanged CLI/profile contracts; a script/profile redesign is not expected. +The ignored `.releasekit/` directory remains local bootstrap storage. + +If a delivery workflow is introduced later, start from the corrected maintained +example: changing a module pin does not update copied YAML. This adoption does +not add delivery automation or new publication gates. + +## Target state: ConfigKit v0.8.0 + +### Native behavior and ownership + +Both integration modules use ConfigKit v0.8.0. Its input destinations, relative +import destinations, sequence-item placement, shared source-version checking, +and registered identified-sequence composition are available to application +loaders through upstream public options and definitions. + +CommandKit does not need a parallel composition layer or new generic flags to +select those policies. Applications decide whether to enable source-version +checking, which declarations to accept, and which sequences use identity-based +composition. Existing ConfigKit defaults preserve prior loading behavior. + +### Source inspection + +Extend `config sources` in text and YAML with useful native destination, +placement, unresolved-destination, and source-version declaration evidence. +The current [source DTO](../../integrations/ckconfig/sources.go) omits all four. +Preserve its existing source fields and native inventory order. OD-1 recommends +the added representation. + +Use only the evidence returned by ConfigKit. A declaration's presence, null/text +state, location, and redaction state do not establish that a checker ran or +accepted a value. An unresolved destination is source evidence, not by itself +a CommandKit validation failure. Preserve upstream sensitivity treatment without +rereading headers or reconstructing withheld values. + +`config explain` continues to expose the native explanation/history contract; +the new SourceInfo fields do not require adding a source inventory to every +explanation. Compact diagnostic source legends can continue identifying sources +by ID, label, and filesystem path. + +### Required adaptation + +Update both dependency graphs, owning notices, native fixtures, and affected +consumer guidance. Review unkeyed literals and any equality/map-key assumptions: +ConfigKit's expanded `SourceInfo` contains a `Path` and is no longer comparable. +Its [release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/docs/releases/v0.8.0.md) +describe this source-compatibility change. The existing provider model need not +be redesigned merely to adopt these additions. + +## Target state: PromptKit v0.16.0 + +### ID-based prompt selection and descriptive labels + +ckprompt uses native ID-only prompt selection. Remove the prompt-specific +`--version` flag from named prompt inspection, requirements show, and requirements +validate. Remove `PromptRequest.Version` and obsolete version-selector plumbing; +use `InspectPrompt(ctx, promptID)` and the revised native request types. +Application version reporting remains governed by its existing identity contract. + +Version labels remain useful metadata. Update inspection/catalog report DTOs for +the native optional label representation, preserving an absent label separately +from an explicitly empty one. OD-2 recommends the report encoding. Do not turn +the removed selector into a CommandKit-only lookup or label-filtering mechanism. + +The standard requirements operations continue delegating discovery and concrete +preparation to PromptKit. Partial discovery remains a successful inspection; +native validation remains authoritative for a constructed request. The existing +typed input/state, nil-builder path, callback capture, error identity, and +delivery behavior apply through the revised API. + +### Explicit configuration and collections + +Replace version-keyed prompt fixtures with one definition per prompt ID. Where +an application formerly supplied multiple definitions under one ID, it chooses +which definition to install or gives distinct resources distinct IDs. +PromptKit's optional resource labels do not make that deployment choice. + +Treat a root configuration `version` as the upstream source specification +header, distinct from a prompt's descriptive `version` or a collection's +`release_version`. Their meaning and any configured acceptance checks remain +with the owning library and application. + +Supply backend/profile resources explicitly where needed. Remove assumptions +about installed provider catalogs and the former built-in standard/auto profiles. +CommandKit must not silently reintroduce those catalogs. The owning application +chooses files, embedded inputs, programmatic mappings, and collections. + +The maintained composed consumer should demonstrate valid explicit composition +and useful root/qualified identities without requiring a model service. Update +its campaign configuration, loader, request builder, fixtures, and examples to +the direct-definition format. Collections are available through native +`CollectionInput` and configuration sources; applications need not use them to +adopt v0.16.0. + +Configured references retain their native exact identities. Mounting a source +does not rewrite backend/profile references or extend profile inheritance beyond +its native scope. Migration guidance should link to the upstream +[configuration/API migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/configuration-migration.md). + +### Expanded operator discovery + +After the base migration, extend the existing optional family with: + +| Operation | Native capability | +| --- | --- | +| `app promptkit list backends` | `Engine.ListBackends` | +| `app promptkit list namespaces` | `Engine.ListNamespaces` | +| `app promptkit list collections` | `Engine.ListCollections` | + +Keep prompt/profile listings and add native namespace filtering where applicable. +These capabilities remain independently optional; one missing inventory does +not disable other operations. Reuse the existing construction, registration, +typed input/state, configuration selection, and diagnostic machinery. + +The namespace behavior has two distinct owners: + +- An application loader may return a native `WithNamespaces` engine view. That + view controls short caller-ID resolution and default resource listing scopes. +- An explicit native listing filter overrides membership selection for one + listing call. It does not change the engine view or rewrite configuration. + +Omitted filters retain native defaults: the corresponding resource view scope, +or all identities when unscoped. Namespace and collection inventories remain +global under the upstream contract. Reports show native identities and labels; +membership does not imply resource readiness. OD-3 recommends request/API and +CLI filter choices. + +### Explicit smoke diagnostics as a follow-on + +PromptKit's `Engine.SmokeTest` is a useful candidate for a separate, explicitly +invoked optional command. It exposes reachability, authentication, text inference, +and structured-output inference observations, with timing and available usage. +These calls can contact providers and incur inference costs. + +The follow-on design should provide native factual evidence without inventing an +overall readiness verdict. A nil native error can accompany negative findings; +an error or caller cancellation can accompany partial observations. Presentation +and invocation outcomes therefore need an operation-specific design that retains +useful partial evidence and supported error identity. Existing success-only +inspection report paths cannot simply discard an error-bearing report. + +OD-4 recommends settling that command in a separate feature roadmap after the +base migration and discovery work. The dependency upgrade itself does not add +provider probes to configuration validation, requirements inspection/validation, +help, or release preparation. Application use of the public native API remains +an application choice. + +## Work across the integrations + +### Dependencies and attribution + +Update the owning module requirements and real checksums for the selected +releases. PromptKit v0.16.0 drops its bundled backend-catalog dependencies; +remove obsolete indirect requirements, sums, and notices when absent from the +resulting CommandKit graphs. Do not replace them with implicit catalog loading. + +Keep root and integration attribution entries matched to their actual selected +graphs. ConfigKit and PromptKit still declare ReleaseKit v0.4.1 upstream; a +CommandKit graph may select v0.4.2 through its own core dependency. Record the +effective selection rather than blindly assigning the root tool version to +every module. Verify pinned license/notice source links for each adopted release. + +Core remains independent of optional ConfigKit/PromptKit dependencies, including +through examples, tests, and tools. Committed builds use released public modules, +not adjacent checkout replacements. + +### Documentation and compatibility + +Update GoDoc, the CLI reference, consumer guidance, maintained examples, internal +inventory, and release-tool references as their owning implementations land. +Document changed prompt configuration, ID-only selection, optional label data, +source evidence, and new discovery behavior under their canonical owners. + +The accepted architecture already supports independently optional operations and +native-library authority. No ADR rewrite is needed merely to add inventories or +follow upstream selection semantics. If the later smoke design changes an +architectural boundary, evaluate that concrete decision under the ADR policy +rather than assuming the dependency upgrade settles it. + +Retain historical release records. Explain incompatible ckprompt changes in an +appropriately versioned future module release. New source-report fields and +catalog capabilities also need accurate CLI/API release notes. This roadmap +does not require a CommandKit version to mirror any upstream version. + +### Evidence for the eventual implementation + +The implementation plan should select proportionate evidence for native source +placement/version disclosure, direct prompt selection, absent/empty labels, +preserved requirements behavior, optional catalog availability, scoped/default +and explicit listing filters, errors, and output delivery. Use maintained offline +consumers and existing release-launcher coverage where applicable. + +Verify all affected modules both in the local workspace and with their own +readonly dependency graphs. Temporary replacements for unpublished CommandKit +prerequisites may support development checks; they are not evidence for a +sibling-replaced upstream dependency or committed build requirements. The +[developer guide](../development.md) owns the established module-check practices. + +New tests should protect selected contracts without requiring incidental +factory activity after failure, complete diagnostic text snapshots, YAML key +ordering, or arbitrary copies of caller-owned objects. No live provider call is +needed to validate the dependency migration and offline discovery features. + +## Open Decisions + +### OD-1: Representation of the added source evidence + +**Recommendation:** Extend both existing source formats with `destination` +using ConfigKit's canonical JSON Pointer string (root is `""`), semantic +`placement` names, explicit `destination_unresolved`, and nullable +`version_evidence`. When the native evidence exists, retain its path, version +presence/null/text fields, nullable source location, and redaction flag without +omitting false or empty values. Use only the native sanitized values. + +This makes the new evidence useful while distinguishing the configuration +destination from the existing filesystem `path`. The name `version_evidence` +also avoids suggesting that a checker necessarily ran or accepted a declaration. +These are report fields, not new application composition or validation policy. + +**Alternative:** Name the nested record `version_check` to match the public +`SourceInfo.VersionCheck` field. That improves API-to-report correspondence but +needs especially clear documentation of what the evidence does and does not +establish. Both representations can preserve the same native information. + +### OD-2: Optional descriptive version labels in reports + +**Recommendation:** Keep the existing context-appropriate field names: +`prompt_version` in named/requirements inspection and `version` in prompt +identity catalogs. Represent absent labels as YAML null and explicitly empty +labels as `""`. New collection inventory can use `release_version` with the +same native optional-label treatment. Document that these values are descriptive, +with no selection behavior. + +This preserves native distinctions and the current explicit-field reporting +style without unrelated key renames. Text reports should communicate absence +versus an explicitly empty label where they display this metadata. + +**Alternative:** Rename descriptive label fields consistently, for example to +`version_label`. That makes the semantic transition conspicuous and can simplify +terminology, but adds schema changes beyond those needed to remove selection. +It still needs an explicit absent/empty representation. + +### OD-3: Catalog requests and namespace-filter syntax + +**Recommendation:** Use narrow ckprompt-owned request envelopes carrying +configuration selection and native `promptkit.NamespaceFilter` for prompt, +profile, and backend catalogs. Give namespace enumeration its native resource-kind +selection, and leave collection enumeration without an invented membership +filter. Revise existing catalog callback shapes coherently rather than retaining +parallel filtered/unfiltered callback variants solely for the prototype API. + +For the applicable listing commands, recommend `--namespace NAME`, +`--unqualified`, and `--all-namespaces` as alternative filter choices; omission +forwards the native default. For namespace enumeration, recommend repeatable +`--kind prompt|profile|backend`, with omission retaining the native union. +Conflicting filter choices should produce a usage error because one native +listing accepts at most one namespace filter. Avoid reserving ordinary namespace +names such as `all` or treating an empty named filter as a new root alias. + +This exposes useful native membership selection while preserving the separate +meaning of application-created engine views. Exact request declarations and +flag-presence details should be settled before the staged plan is finalized. + +**Alternative:** Add the inventories with existing selection-only callback +shapes, and initially rely on loader-supplied engine views for default scoping. +That is a smaller API change and can deliver inventories sooner. It leaves +operators without standard per-call named/unqualified/all overrides and requires +another public API change when those native capabilities are exposed later. + +### OD-4: Delivery boundary for smoke diagnostics + +**Recommendation:** Deliver the dependency/configuration migration and expanded +discovery first, then prepare a separate feature roadmap for an optional smoke +diagnostic command. That roadmap should settle vocabulary, typed request +construction, native evidence presentation, partial-report delivery, and status +meaning. A suitable starting recommendation is success when a native diagnostic +concludes and its report is delivered, with negative/unknown findings retained +as facts; native invocation errors remain failures with useful partial evidence +preserved when supplied. + +The current [deferred-work record](deferred.md) still lists credential diagnostics +and live probes as unselected work. This recommendation proposes a focused next +feature, without making that larger design a prerequisite for the three upgrades +or changing the existing validation commands into provider probes. + +**Alternative:** Include the new optional diagnostic capability in the same +implementation sprint. This can yield one coherent pass over the public suite +API and documentation, but requires resolving its request, CLI, evidence, and +outcome contracts before implementation planning. It increases the adoption +scope and delays delivery of the otherwise independent migration/discovery work.