diff --git a/docs/roadmap/upgrades.md b/docs/roadmap/upgrades.md index b234e8c..3c66d0f 100644 --- a/docs/roadmap/upgrades.md +++ b/docs/roadmap/upgrades.md @@ -1,10 +1,9 @@ # 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. +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 @@ -62,9 +61,8 @@ not require changing CommandKit's Go minimum or selected release toolchain. | 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 +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. @@ -123,14 +121,13 @@ composition. Existing ConfigKit defaults preserve prior loading behavior. 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. +Preserve its existing source fields and native inventory order. The accepted +representation is recorded in OD-1. -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. +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 @@ -157,9 +154,9 @@ 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 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; @@ -220,29 +217,31 @@ The namespace behavior has two distinct owners: 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. +global under the upstream contract. Reports show native identities and versions. +OD-3 records the accepted request/API and CLI filter choices. -### Explicit smoke diagnostics as a follow-on +### Explicit smoke testing -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. +Expose PromptKit's `Engine.SmokeTest` through an independently optional command +in this roadmap. Forward a native `SmokeTestRequest` and present the returned +`SmokeTestReport`, including native reachability, authentication, text inference, +or structured-output observations, timing, and available usage as applicable. +Reuse the suite's typed input/state, configuration selection, and engine +acquisition paths. Keep request construction and report presentation close to +the native public API. -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. +Retain a returned report when the native call also returns an error, preserving +supported error identity and reporting output-delivery failures through the +existing outcome model. A nil native error and successful report delivery mean +success; native invocation errors receive the normal operational failure +classification. Present native observations without deriving an additional +readiness verdict or adding warnings about perceived upstream limitations. -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. +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 @@ -268,28 +267,30 @@ not adjacent checkout replacements. 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. +source evidence, new discovery behavior, and smoke testing 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. +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 capabilities also need accurate CLI/API release notes. This roadmap -does not require a CommandKit version to mirror any upstream version. +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 and default/explicit listing filters. 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. +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 +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, @@ -308,93 +309,74 @@ sibling-replaced upstream dependency or committed build requirements. The 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. +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. -## Open Decisions +## Accepted 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. +**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`. -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. +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. -**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 versions in reports -### OD-2: Optional descriptive version labels 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. -**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. +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 -**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. +**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 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. +For applicable listing commands, map operator input directly to native filters: -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. +| Operator input | Native filter mode | +| --- | --- | +| No namespace option | `NamespaceDefault` | +| `--namespace NAME` | `NamespaceNamed` with the supplied name | +| `--namespace ""` | `NamespaceUnqualified` | +| `--all-namespaces` | `NamespaceAll` | -**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. +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. -### OD-4: Delivery boundary for smoke diagnostics +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. -**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. +### OD-4: Delivery boundary for smoke testing -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. +**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. -**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. +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 implementation plan must settle concrete command vocabulary and request +bindings within this scope. A separate smoke feature roadmap is not required.