Record upgrade decisions and include smoke testing

docs/roadmap/upgrades.md

@@ -1,10 +1,9 @@
 # ConfigKit, PromptKit, and ReleaseKit adoption
 
-Status: adoption roadmap; implementation has not started. The release targets
+Status: adoption roadmap; implementation has not started. The release targets,
-and adoption order are agreed. Detailed presentation and capability choices
+adoption order, and OD-1 through OD-4 are accepted. Smoke testing is included
-under Open Decisions remain proposals. This document defines the desired end
+in the current scope. This document defines the desired end state and required
-state and required work; a separate implementation plan will sequence coding
+work; a separate implementation plan will sequence coding tasks.
-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
+Expanded PromptKit discovery and explicitly invoked smoke testing are included
-diagnostics are a distinct follow-on capability, with the delivery boundary
+after its base migration. These are product/dependency relationships, not a staged
-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.
 
@@ -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
+Preserve its existing source fields and native inventory order. The accepted
-the added representation.
+representation is recorded in OD-1.
 
-Use only the evidence returned by ConfigKit. A declaration's presence, null/text
+Project the native fields and their values directly into the report, including
-state, location, and redaction state do not establish that a checker ran or
+`version_check` corresponding to `SourceInfo.VersionCheck`. Use ConfigKit's
-accepted a value. An unresolved destination is source evidence, not by itself
+returned, sanitized evidence and describe its fields neutrally. ConfigKit owns
-a CommandKit validation failure. Preserve upstream sensitivity treatment without
+the meaning and disclosure of that evidence.
-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
@@ -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
+the native optional representation. Use `version` for a prompt or collection's
-from an explicitly empty one. OD-2 recommends the report encoding. Do not turn
+reported version, omit the field when absent, and retain `""` when explicitly
-the removed selector into a CommandKit-only lookup or label-filtering mechanism.
+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;
+global under the upstream contract. Reports show native identities and versions.
-membership does not imply resource readiness. OD-3 recommends request/API and
+OD-3 records the accepted request/API and CLI filter choices.
-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
+Expose PromptKit's `Engine.SmokeTest` through an independently optional command
-invoked optional command. It exposes reachability, authentication, text inference,
+in this roadmap. Forward a native `SmokeTestRequest` and present the returned
-and structured-output inference observations, with timing and available usage.
+`SmokeTestReport`, including native reachability, authentication, text inference,
-These calls can contact providers and incur inference costs.
+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
+Retain a returned report when the native call also returns an error, preserving
-overall readiness verdict. A nil native error can accompany negative findings;
+supported error identity and reporting output-delivery failures through the
-an error or caller cancellation can accompany partial observations. Presentation
+existing outcome model. A nil native error and successful report delivery mean
-and invocation outcomes therefore need an operation-specific design that retains
+success; native invocation errors receive the normal operational failure
-useful partial evidence and supported error identity. Existing success-only
+classification. Present native observations without deriving an additional
-inspection report paths cannot simply discard an error-bearing report.
+readiness verdict or adding warnings about perceived upstream limitations.
 
-OD-4 recommends settling that command in a separate feature roadmap after the
+Smoke testing runs when its command is explicitly invoked. Configuration,
-base migration and discovery work. The dependency upgrade itself does not add
+requirements, help, and release operations retain their own existing behavior.
-provider probes to configuration validation, requirements inspection/validation,
+OD-4 records its inclusion in the current delivery scope; a separate feature
-help, or release preparation. Application use of the public native API remains
+roadmap is unnecessary. The broader deferred proposals in
-an application choice.
+[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
+native-library authority. Adding these optional capabilities and following
-follow upstream selection semantics. If the later smoke design changes an
+upstream selection semantics fit those accepted boundaries. Any concrete new
-architectural boundary, evaluate that concrete decision under the ADR policy
+architectural decision is evaluated 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
+catalog and smoke capabilities also need accurate CLI/API release notes. This
-does not require a CommandKit version to mirror any upstream version.
+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
+ID-only prompt requests, default/explicit listing filters, and smoke requests.
-representation of upstream-returned source evidence, optional labels, inventories,
+Verify faithful representation of upstream-returned source evidence, optional
-diagnostics, and errors, together with CommandKit's optional command availability,
+labels, inventories, diagnostics, and errors, together with CommandKit's optional
-invocation lifetimes, outcome classification, and output delivery.
+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
+ordering, or arbitrary copies of caller-owned objects. The migration, discovery,
-needed to validate the dependency migration and offline discovery features.
+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`
+**Accepted:** Extend both existing source formats with `destination` using
-using ConfigKit's canonical JSON Pointer string (root is `""`), semantic
+ConfigKit's canonical JSON Pointer string (root is `""`), `placement` using native
-`placement` names, explicit `destination_unresolved`, and nullable
+mode names, `destination_unresolved`, and `version_check` corresponding to
-`version_evidence`. When the native evidence exists, retain its path, version
+`SourceInfo.VersionCheck`.
-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
+Preserve the native nested evidence: path, version presence/null/text, optional
-destination from the existing filesystem `path`. The name `version_evidence`
+source location, and redaction flag. Use native sanitized values and maximize
-also avoids suggesting that a checker necessarily ran or accepted a declaration.
+API-to-report correspondence. Field descriptions explain the returned data
-These are report fields, not new application composition or validation policy.
+neutrally, without promising additional checker behavior or warning about
+perceived upstream limitations.
 
-**Alternative:** Name the nested record `version_check` to match the public
+### OD-2: Optional versions in reports
-`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
+**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:
+Version metadata retains its upstream meaning. ID-only selection and source
-`prompt_version` in named/requirements inspection and `version` in prompt
+configuration headers remain governed by their respective native APIs.
-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
+**Accepted:** Use narrow ckprompt-owned request envelopes carrying configuration
-configuration selection and native `promptkit.NamespaceFilter` for prompt,
+selection and native `promptkit.NamespaceFilter` for prompt, profile, and backend
-profile, and backend catalogs. Give namespace enumeration its native resource-kind
+catalogs. Give namespace enumeration its native resource-kind selection, and
-selection, and leave collection enumeration without an invented membership
+leave collection enumeration aligned with its unfiltered native API. Revise
-filter. Revise existing catalog callback shapes coherently rather than retaining
+existing catalog callback shapes coherently rather than retaining parallel
-parallel filtered/unfiltered callback variants solely for the prototype API.
+filtered/unfiltered variants solely for the prototype API.
 
-For the applicable listing commands, recommend `--namespace NAME`,
+For applicable listing commands, map operator input directly to native filters:
-`--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
+| Operator input | Native filter mode |
-meaning of application-created engine views. Exact request declarations and
+| --- | --- |
-flag-presence details should be settled before the staged plan is finalized.
+| 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
+Existing flag-presence tracking distinguishes omission from an explicitly empty
-shapes, and initially rely on loader-supplied engine views for default scoping.
+namespace. These choices need no separate `--unqualified` flag or reserved
-That is a smaller API change and can deliver inventories sooner. It leaves
+namespace name such as `all`. Conflicting namespace choices are usage errors:
-operators without standard per-call named/unqualified/all overrides and requires
+one native listing accepts at most one namespace filter.
-another public API change when those native capabilities are exposed later.
 
-### 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
+### OD-4: Delivery boundary for smoke testing
-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
+**Accepted:** Include an independently optional smoke command in this roadmap,
-and live probes as unselected work. This recommendation proposes a focused next
+alongside dependency migration and expanded discovery. Expose the native request,
-feature, without making that larger design a prerequisite for the three upgrades
+operation, and report directly through the existing integration model.
-or changing the existing validation commands into provider probes.
 
-**Alternative:** Include the new optional diagnostic capability in the same
+Deliver native reports, including a report returned with an error. Successful
-implementation sprint. This can yield one coherent pass over the public suite
+native invocation and report delivery yield success; native errors remain
-API and documentation, but requires resolving its request, CLI, evidence, and
+operational failures with supported error identity preserved. Native observations
-outcome contracts before implementation planning. It increases the adoption
+are reported neutrally. CommandKit does not add an aggregate readiness judgment
-scope and delays delivery of the otherwise independent migration/discovery work.
+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.