commandkit/docs/roadmap/upgrades.md

# 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.