Plan ConfigKit, PromptKit, and ReleaseKit upgrades
This commit is contained in:
389
docs/roadmap/upgrades.md
Normal file
389
docs/roadmap/upgrades.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user