commandkit/docs/roadmap/upgrades.md

# ConfigKit, PromptKit, and ReleaseKit adoption

Status: adoption roadmap; implementation has not started. The release targets,
adoption order, and OD-1 through OD-4 are accepted. Smoke testing is included
in the current scope. 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.

Keep adaptation proportionate to that ownership. Reports are direct projections
of upstream data, with small presentation DTOs where YAML naming and formatting
need them. Preserve native values and meanings rather than introducing a
parallel semantic model or normalization layer.

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 and explicitly invoked smoke testing are included
after its base migration. 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. The accepted
representation is recorded in OD-1.

Project the native fields and their values directly into the report, including
`version_check` corresponding to `SourceInfo.VersionCheck`. Use ConfigKit's
returned, sanitized evidence and describe its fields neutrally. ConfigKit owns
the meaning and disclosure of that evidence.

`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 representation. Use `version` for a prompt or collection's
reported version, omit the field when absent, and retain `""` when explicitly
empty, as accepted in OD-2. Selection continues to use the native ID-only API.

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.

Keep the maintained composed consumer migration small: update its configuration,
loader, request builder, and fixtures as needed for direct definitions and the
new interfaces, without requiring a model service. Use a small configuration to
illustrate the relevant wiring and identities; a comprehensive collections
example or migration framework is not required. 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.

Forward native namespace filters and resource-kind selections to their respective
APIs. PromptKit performs identity resolution and inventory membership selection;
the adapter translates the selected CLI syntax into those native inputs.

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 versions.
OD-3 records the accepted request/API and CLI filter choices.

### Explicit smoke testing

Expose PromptKit's `Engine.SmokeTest` through an independently optional
`promptkit test` command in this roadmap. Keep request construction and report
presentation close to the native public API, reusing the suite's typed
input/state, configuration selection, and engine acquisition paths.

#### Command vocabulary

The selected syntax is:

```text
app promptkit test KIND [options]
app promptkit test all [options]
```

One operand selects either a native kind or the aggregate `all` operation.
The native kind spellings are `reachability`, `authentication`, `text_inference`,
and `structured_output`. `all` is CommandKit-owned coordination syntax, not a
native `SmokeTestKind`.

For example:

```text
app promptkit test reachability --backend local
app promptkit test authentication --profile editorial
app promptkit test text_inference --prompt briefing
app promptkit test structured_output --profile editorial --model example-model
app promptkit test all --profile editorial
```

#### Request bindings

Bind operator inputs directly to `promptkit.SmokeTestRequest` and its native
`ExecutionTargetOverride`:

| CLI input | Native destination | Binding |
| --- | --- | --- |
| `KIND` | `Kind` | Native kind string; aggregate expansion is described below. |
| `--backend` | `BackendID` | String. |
| `--prompt` | `PromptID` | String. |
| `--profile` | `ProfileID` | String. |
| `--endpoint` | `Execution.Endpoint` | String. |
| `--model` | `Execution.Model` | String. |
| `--temperature` | `Execution.Temperature` | Optional floating-point value. |
| `--max-tokens` | `Execution.MaxTokens` | Optional integer. |
| `--top-p` | `Execution.TopP` | Optional floating-point value. |
| `--timeout-seconds` | `Execution.TimeoutSeconds` | Optional integer. |
| `--service-tier` | `Execution.ServiceTier` | String. |
| `--reasoning-effort` | `Execution.ReasoningEffort` | Optional string. |
| `--api-key-env` | `Execution.APIKeyEnv` | String. |
| `--transient-retries` | `TransientRetries` | Optional integer. |

Also accept the existing `--config`, `--overlay`, and suite selectors. Reports
are YAML-only; `--format` defaults to `yaml` and accepts `yaml`. Built-in flags
are singleton bindings with the established last-occurrence behavior; suite
selectors retain their declared binding behavior.

Preserve omission versus explicit zero or empty values for native pointer
fields. Leave `Execution` nil when no execution override was supplied. Backend,
prompt, and profile selectors may be supplied together: PromptKit owns their
precedence, resolution, defaults, ranges, and request validation. CommandKit
owns CLI syntax and primitive value conversion.

Direct `APIKey` and structured `ExtraParams` remain available through the
optional application request builder. This scope uses that existing integration
pattern rather than adding a credential-source mechanism or generic override
language.

#### Consumer API and request construction

Use a narrow ckprompt-owned envelope:

```go
type SmokeRequest struct {
    Selection ckconfig.Selection
    Request   promptkit.SmokeTestRequest
}
```

An independently optional `Suite.SmokeTest` callback receives context,
`SmokeRequest`, typed application input, and shared state, and returns
`(commandkit.Acquired[*promptkit.SmokeTestReport], error)`. It represents one
concrete test and preserves both a returned native report and error.

Provide `WithSmokeTesting(suite, load, build)` following the existing
request-validation adapter pattern. The loader uses the existing engine-loader
signature. The optional builder receives context, `SmokeRequest`, typed input,
and shared state, and returns a complete native `SmokeTestRequest` and error.
With no builder, forward the CLI-created native request. With a builder, its
returned request is authoritative; do not merge CLI values back over it.

For aggregate execution, invoke the optional builder separately for each
concrete kind, seeding that kind into the otherwise common bound request.
Applications can supply per-kind credentials, structured parameters, or other
native request choices. The synthetic `all` value does not reach the native
request or the per-test builder.

#### Aggregate execution

`app promptkit test all` selects these four tests sequentially, in order:

1. `reachability`
2. `authentication`
3. `text_inference`
4. `structured_output`

Coordinate the concrete test callbacks within one CommandKit invocation, using
its configuration selection, prepared typed input, and shared state. Reuse
configuration acquisition and the engine where practical within the existing
loader model; this does not require a new caching framework or guarantee a
particular loader call count.

Continue to the next kind after an individual test error so that remaining
results can be collected. When the invocation is canceled, stop scheduling
further tests and retain the results already available. PromptKit owns each
individual operation; CommandKit coordinates the selected sequence.

#### Reports and invocation outcomes

Present the native `SmokeTestReport`, including observations, timing, attempts,
and available usage. For `all`, deliver one YAML report containing the
individual results in execution order, with each selected kind's returned
report and associated error, when present. Retain useful partial reports
returned with errors. Preserve supported error identity through the invocation
outcome as well as presenting the errors.

For a single test, a nil native error and successful report delivery mean
success. For `all`, success requires all selected calls to return without errors
and reporting to succeed. Native invocation errors use the normal operational
failure classification; cancellation and delivery failures retain their existing
outcome handling. Native negative or unknown findings remain reported facts;
CommandKit does not derive an additional readiness verdict or failure rule from
them.

Use a focused report-delivery path that preserves a returned report alongside
its native error, including cancellation. The existing success-only inspection
writer cannot be reused unchanged for that case. Adapt delivery within the
current outcome model; this work does not require a general diagnostics
framework. Describe returned data neutrally, without adding warnings about
perceived upstream limitations.

Smoke testing runs when its command is explicitly invoked. Configuration,
requirements, help, and release operations retain their own existing behavior.
OD-4 records its inclusion in the current delivery scope; a separate feature
roadmap is unnecessary. The broader deferred proposals in
[deferred work](deferred.md) do not defer this selected native capability.

## 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, new discovery behavior, and smoke testing under their canonical
owners.

The accepted architecture already supports independently optional operations and
native-library authority. Adding these optional capabilities and following
upstream selection semantics fit those accepted boundaries. Any concrete new
architectural decision is evaluated under the ADR policy.

Retain historical release records. Explain incompatible ckprompt changes in an
appropriately versioned future module release. New source-report fields and
catalog and smoke 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 test CommandKit-owned interfaces and adaptation
under the [upstream testing ownership policy](../policy/testing.md#upstream-integration-testing-ownership).
Verify that command inputs and context reach the intended native APIs, including
ID-only prompt requests, default/explicit listing filters, and smoke requests.
Verify faithful representation of upstream-returned source evidence, optional
labels, inventories, diagnostics, and errors, together with CommandKit's optional
command availability, invocation lifetimes, outcome classification, and output
delivery. Include smoke request bindings, per-kind builder forwarding, aggregate
order and continuation, cancellation, report-plus-error delivery, and error
identity in this boundary coverage.

These checks establish CommandKit's access to the capabilities. They should not
test whether ConfigKit correctly places or composes sources, checks versions,
or classifies sensitivity, nor whether PromptKit correctly resolves namespaces,
discovers requirements, or validates concrete requests. Those domain tests belong
to the upstream libraries. Real upstream fixtures and maintained offline
consumers can exercise CommandKit's boundary without duplicating native feature
test matrices. Existing release-launcher coverage likewise owns CommandKit's
tool invocation, not ReleaseKit's publication algorithms.

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. The migration, discovery,
and smoke adapter checks can use offline fixtures and test doubles; smoke tests
verify request forwarding and report/error adaptation, leaving provider behavior
to PromptKit.

## Accepted Decisions

### OD-1: Representation of the added source evidence

**Accepted:** Extend both existing source formats with `destination` using
ConfigKit's canonical JSON Pointer string (root is `""`), `placement` using native
mode names, `destination_unresolved`, and `version_check` corresponding to
`SourceInfo.VersionCheck`.

Preserve the native nested evidence: path, version presence/null/text, optional
source location, and redaction flag. Use native sanitized values and maximize
API-to-report correspondence. Field descriptions explain the returned data
neutrally, without promising additional checker behavior or warning about
perceived upstream limitations.

### OD-2: Optional versions in reports

**Accepted:** Report a prompt or collection's version as `version`. Omit this
optional field when the native value is absent; retain `""` when it is present
and empty. For collections, this projects the native `ReleaseVersion` value.
Use the same naming and presence treatment across the affected reports.

Version metadata retains its upstream meaning. ID-only selection and source
configuration headers remain governed by their respective native APIs.

### OD-3: Catalog requests and namespace-filter syntax

**Accepted:** 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 aligned with its unfiltered native API. Revise
existing catalog callback shapes coherently rather than retaining parallel
filtered/unfiltered variants solely for the prototype API.

For applicable listing commands, map operator input directly to native filters:

| Operator input | Native filter mode |
| --- | --- |
| No namespace option | `NamespaceDefault` |
| `--namespace NAME` | `NamespaceNamed` with the supplied name |
| `--namespace ""` | `NamespaceUnqualified` |
| `--all-namespaces` | `NamespaceAll` |

Existing flag-presence tracking distinguishes omission from an explicitly empty
namespace. These choices need no separate `--unqualified` flag or reserved
namespace name such as `all`. Conflicting namespace choices are usage errors:
one native listing accepts at most one namespace filter.

Namespace enumeration uses repeatable `--kind prompt|profile|backend`; omission
retains the native union. Application-created engine views and explicit listing
filters retain their separate native meanings.

### OD-4: Delivery boundary for smoke testing

**Accepted:** Include an independently optional smoke command in this roadmap,
alongside dependency migration and expanded discovery. Expose the native request,
operation, and report directly through the existing integration model.

Deliver native reports, including a report returned with an error. Successful
native invocation and report delivery yield success; native errors remain
operational failures with supported error identity preserved. Native observations
are reported neutrally. CommandKit does not add an aggregate readiness judgment
or warnings about perceived upstream limitations.

The [explicit smoke testing target](#explicit-smoke-testing) records the accepted
`promptkit test KIND` and `promptkit test all` vocabulary, native request
bindings, per-kind builder, and aggregate execution/reporting semantics. A
separate smoke feature roadmap is not required.