Record PromptKit adoption scope and completion criteria

docs/roadmap/future.md

@@ -24,13 +24,21 @@ an idea here does not select its syntax, API, priority, or delivery date.
 ### ckprompt dependency migration and workspace alignment
 
 The [PromptKit v0.18.0 adoption roadmap](promptkit-v0.18.0.md) owns the proposed
-dependency set, API/report and fixture migration, workspace alignment, and open
+dependency set, API/report and fixture migration, workspace alignment, scope
-release, example, and capability scope choices. The current ckprompt v0.2.0 still
+decisions, and completion evidence. The current ckprompt v0.2.0 still
 uses published ckconfig v0.2.0 and old-path ConfigKit v0.8.0; it does not compose
 with local ckconfig v0.3.0. See the
 [consumer guide](../consumers/guide.md#module-selection) and
 [development guide](../development.md) for current module and workspace use.
 
+### Later PromptKit release review
+
+The current adoption develops only against PromptKit v0.18.0 as released.
+Review v0.19.0 separately once it is published; do not inspect or monitor
+unreleased upstream work in anticipation of that review. A later released
+version requires its own contract and compatibility assessment before selection
+and does not delay completion of the v0.18.0 adoption.
+
 ## Future capability targets
 
 ### Comparison extensions
@@ -58,7 +66,11 @@ ConfigKit's public APIs own the evidence and its semantics.
   records without recreating upstream provenance logic. Historical enumeration
   is not an exhaustive inventory of possible schema fields. This gives the
   earlier field-origin inventory proposal a concrete, upstream-backed scope;
-  command names, selectors, and report shapes remain to be designed.
+  command names, selectors, and report shapes remain to be designed. For
+  PromptKit, design this shared optional ckconfig capability first, then wire
+  `ConfigurationInspection.Metadata()` through `ckprompt.ConfigScope`. This is
+  PromptKit adoption OD-3; it does not require a separate provenance model or a
+  new core API.
 - **Failed-load source inventory (OD-4).** Present acquired source evidence from
   `LoadError.Sources()` while retaining the failed outcome and diagnostics.
   Design how an adapter returns its source facet on error and how result output
@@ -84,6 +96,52 @@ recording remain available through application loaders. Standard inspection of
 resource contexts or secrets-directory bootstrap has no immediate proposal;
 those capabilities primarily serve application loading and startup.
 
+### PromptKit inspection and selection extensions
+
+The [PromptKit adoption scope](promptkit-v0.18.0.md#scope-decisions) defers these
+capabilities beyond the v0.18.0 compatibility migration. Shared configuration
+metadata remains the recommended next functional sprint, under
+[configuration inspection extensions](#configuration-inspection-extensions).
+The OD identifiers below belong to the PromptKit adoption roadmap, separately
+from the ConfigKit review identifiers above.
+
+- **Prepared-request inspection (PromptKit OD-4).** Consider an optional provider
+  and report based on the released native `Engine.Prepare` and `PreparedRun`,
+  reusing the concrete request-builder pattern. This would extend standard
+  inspection into rendering and needs an explicit scope decision. The snapshot
+  offers selected resource IDs, effective settings, output/schema metadata,
+  messages, session ID, hashes, and timing without a model call. Its `Messages`
+  contain complete rendered and appended messages; its effective execution
+  settings exclude resolved API-key values. Select report content and document
+  those upstream semantics rather than treating the complete snapshot as an
+  existing inspection report. Command grammar, callback shape, formats, and the
+  relationship to request validation remain open. Validate capability
+  availability, forwarding, projection, and report delivery at CommandKit's
+  boundary. PromptKit retains preparation and rendering semantics. Keeping this
+  operation application-owned remains an alternative; model execution and
+  prepared-handle lifecycle are outside this proposal.
+- **Namespace helpers or standard selectors (PromptKit OD-5).** Begin with the
+  adoption's consumer guidance for loaders returning `Engine.WithNamespaces`.
+  Consider reusable bindings or helpers when consumers demonstrate repeated
+  wiring. Design independent prompt/profile/backend defaults, applicable
+  operations, and their interaction with existing catalog filters together.
+  Namespace views resolve unqualified caller selections; they do not rewrite
+  captured configuration references or global configuration inspection, and
+  namespace/collection inventories remain global. Preserve the distinction
+  between name resolution and catalog filtering. No flag names or changed
+  filtering meanings are selected.
+- **Other reusable request bindings.** Consider helpers for native request
+  options only where consumers repeat wiring. Execution/output-validation
+  overrides, session IDs, appended messages, and retry settings are already
+  reachable through application request builders; engine options remain
+  available through loaders. API availability alone does not select a standard
+  flag or a new core abstraction.
+
+The released [prepared snapshot](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/types.go)
+and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go)
+provide the reviewed upstream contracts. These proposals establish no new
+provider requirement, delivery date, or adoption completion condition.
+
 ### Alias completion and discovery
 
 The delivered [shell completion feature](../cli.md#shell-completion) provides
@@ -139,7 +197,7 @@ operator or consumer need and an appropriate ownership/behavior decision:
   injection, and concurrent-dispatch guarantees.
 
 Execution, rendering, serving, and session operations remain application-owned.
-The [prepared-request inspection proposal](promptkit-v0.18.0.md#od-4-add-prepared-request-inspection-to-the-standard-suite)
+The [prepared-request inspection proposal](#promptkit-inspection-and-selection-extensions)
 would extend standard inspection into rendering and remains an open scope choice.
 Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md).
 Backend replacement remains possible behind the accepted facade, subject to the

docs/roadmap/promptkit-v0.18.0.md

@@ -1,10 +1,11 @@
 # PromptKit v0.18.0 adoption
 
-Status: proposed; implementation has not begun. This roadmap captures the
+Status: adoption scope recorded; implementation has not begun. Released
-ckprompt migration and workspace alignment target. PromptKit v0.18.0 is the
+PromptKit v0.18.0 is the sole development target, as directed by the user.
-reviewed working baseline. Final release selection, the maintained example's
+[Scope decisions](#scope-decisions) record that dependency choice and the
-bundle policy, and optional capability scope have recommendations under
+recommended example policy and capability scope. The
-[Open Decisions](#open-decisions); those choices remain open.
+[completion checklist](#completion-checklist) separates implementation evidence
+from publication and deferred enhancements.
 
 ## Purpose and authority
 
@@ -108,12 +109,11 @@ ownership. OD-4 addresses only the proposed rendering-inspection extension.
 
 ### Modules and Go compatibility
 
-Prepare ckprompt v0.3.0 with this dependency set, subject to OD-1 for the final
+Prepare ckprompt v0.3.0 against this released dependency set under OD-1:
-PromptKit release pin:
 
 | Requirement | Target |
 | --- | --- |
-| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as reviewed baseline |
+| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as released |
 | ConfigKit | `go.maximumdirect.net/configkit v1.1.0` |
 | ckconfig | `go.maximumdirect.net/ckconfig v0.3.0` |
 | Core | Retain `go.maximumdirect.net/commandkit v0.3.0` |
@@ -175,7 +175,13 @@ profiles as a lowest-priority underlay. Catalogs, namespaces, configuration, and
 source reports follow the supplied engine's native inventory. The integration
 does not silently filter those definitions or disable the bundle. Applications
 can select `WithBundledOpenRouter(false)` in their own engine loaders.
-OD-2 addresses that choice for the maintained composed example and fixtures.
+Under OD-2, retain the default bundle in the maintained composed example.
+Focused fixture loaders may explicitly opt out when their purpose requires a
+minimal application-only inventory. Include focused coverage showing that
+bundled records and their source evidence reach CommandKit output; assertions
+about application records alone would not detect accidental bundle filtering.
+Use returned native evidence without duplicating the full bundled catalog or
+fixing expectations to its count.
 
 Existing offline test and smoke-example boundaries remain applicable. Use
 explicit native selections and injected clients/transports as appropriate to
@@ -204,8 +210,8 @@ version or select new release gates.
 
 ## Work from the baseline
 
-1. Record the working dependency baseline and resolve OD-2's example policy;
+1. Use released PromptKit v0.18.0 under OD-1 and the recommended default-bundle
-   carry OD-1's final shipping choice into release preparation. Prepare the
+   example policy under OD-2. Prepare the
    ckprompt dependency/import and Go-minimum changes with the selected Go 1.27
    toolchain, then tidy and inspect authentic metadata with workspace discovery
    off. Review the effective graph for attribution, including tool requirements.
@@ -216,8 +222,9 @@ version or select new release gates.
    inheritance references, list-index paths, and composed-example plumbing.
    Apply the selected bundle policy explicitly in fixture-owned loaders.
 4. Update focused tests for request forwarding and faithful native-result
-   projection. Account for normalized inspection values and native inventories;
+   projection, including bundled records and source evidence reaching output.
-   test the CommandKit adaptation rather than independently establishing bundle
+   Account for normalized inspection values and native inventories; test the
+   CommandKit adaptation rather than independently establishing bundle
    contents, normalization rules, inheritance, or provider behavior.
 5. Run the full ckprompt suite and maintained example tests against its own
    declared dependencies. Validate the restored local workspace and composed
@@ -231,126 +238,77 @@ version or select new release gates.
    native namespace-view loader guidance while keeping standard selector design
    separate.
 
-The native adapter structure remains the starting point. OD-3 through OD-5 are
+The native adapter structure remains the starting point. This sprint covers
-unselected scope choices, not additional adoption completion conditions. The
+dependency, API/report, fixture, and workspace migration plus namespace-loader
-recommended sequence is dependency/report and workspace migration, then shared
+guidance. Core APIs and its Go minimum remain unchanged. Shared metadata,
-metadata inspection, followed by separately selected prepared-request
+prepared-request inspection, and reusable namespace helpers or standard selectors
-inspection. Namespace loader guidance can accompany migration documentation.
+are deferred to [future work](future.md#promptkit-inspection-and-selection-extensions).
-The detailed-comparison, failed-load-inventory, and structured-diagnostic
+The shared detailed-comparison, failed-load-inventory, and structured-diagnostic
-proposals in future work remain separate too. If capability scope is expanded
+proposals remain separate too.
-into this release, revise the dependency target, implementation work, validation,
-and release documentation to match that decision before implementation.
 
-## Upstream remediation boundary
+## Released upstream baseline
 
-Post-release audit notes in the sibling PromptKit checkout identify issues in
+Develop and validate only against PromptKit v0.18.0 as released. Unreleased
-the same production source as v0.18.0. Relevant examples include unrestricted
+upstream branches, sibling-checkout changes, audit notes, and proposed fixes do
-authentication-response buffering in the
+not inform this adoption's implementation, scope, or release criteria. The
-[native authentication probe](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/internal/usecase/smoke_authentication.go)
+migration does not wait for upstream development or introduce local workarounds
-and inference request-construction errors reported as concluded diagnostics by
+for anticipated changes.
-the [native smoke tester](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/internal/usecase/smoke_tester.go).
-Those findings inform OD-1; the disposable CommandKit review did not reproduce
-the full upstream audit set.
 
-Keep domain corrections upstream. This adoption does not add local response
+PromptKit v0.19.0 may be reviewed once it is available as a published release.
-limits, duplicate request validation, or replacement error classification to
+That is a separate dependency review of its released contracts and changes;
-compensate for those defects. Evaluate any published corrective release for
+it does not automatically change this roadmap's v0.18.0 target. No investigation
-compatibility and adapt to its public contract using ordinary change review.
+or monitoring of unreleased work is part of this adoption.
 
-## Open Decisions
+## Scope decisions
 
-### OD-1: Ship on v0.18.0 or await relevant upstream corrections?
+OD-1 records the user's explicit dependency direction. OD-2 through OD-5 record
+the recommended scope for this sprint; deferred capabilities still require
+focused API and CLI design. These decisions do not describe implemented features
+or authorize publication.
 
-**Recommendation:** develop the migration now against the published v0.18.0
+| Decision | Disposition | Implementation consequence |
-baseline and prefer a published corrective release addressing the relevant
+| --- | --- | --- |
-native diagnostic issues for the final shipping pin. That keeps integration
+| OD-1: Upstream baseline | Develop only against released PromptKit v0.18.0. Review v0.19.0 separately once published. | Use the pinned released dependency set; do not consider unreleased upstream work or wait for it. |
-work concrete while keeping fixes with their upstream owner. Taking a newer
+| OD-2: Example bundle policy | Retain the upstream default bundle in the composed example; opt out explicitly in focused minimal fixtures. | Verify bundled records and source evidence reach output, without asserting the complete catalog or count. Keep smoke fixtures on explicit offline targets. |
-release requires reviewing its actual changes and rerunning affected checks;
+| OD-3: Shared metadata | Defer to the next shared functional sprint. | Design the optional ckconfig capability first, then forward PromptKit's native metadata. Retain ckconfig v0.3.0 for adoption. |
-waiting for corrections can delay ckprompt publication. Whether to publish on
+| OD-4: Prepared-request inspection | Defer to a separate design decision after adoption and shared metadata. | Select report content and the rendering scope explicitly before adding a provider or command. |
-v0.18.0 if those corrections are not yet available remains a release choice.
+| OD-5: Namespace support | Include loader guidance now; defer reusable helpers and standard selectors. | Explain independent namespace defaults and keep unqualified-name resolution distinct from catalog filtering. |
 
-**Viable alternative:** finish and publish the ckprompt migration with exactly
+The [future capability record](future.md#promptkit-inspection-and-selection-extensions)
-v0.18.0 using the existing release workflow, then adopt an upstream correction
+owns the deferred PromptKit feature proposals and their design considerations.
-separately. This restores the compatible module set without an upstream-dependent
+Application loaders continue to own engine construction and bundle choices;
-schedule. It ships with the recorded native defects still present and requires
+request builders continue to expose native request options without requiring a
-a later dependency update. Neither option selects local workarounds or makes
+standard flag for each one.
-completion of every upstream audit finding a new release prerequisite.
 
-### OD-2: Which bundle policy should the maintained example demonstrate?
+## Completion checklist
 
-**Recommendation:** retain upstream's default bundle in the composed example
+Record evidence against the final implementation, separately from the earlier
-and make catalog/report assertions about the application-defined records and
+disposable review. Implementation is complete when:
-returned native evidence rather than duplicating the complete bundled catalog.
-Use explicit opt-out in focused fixture loaders when their purpose is a minimal
-application-only inventory. This demonstrates the current native default while
-keeping adapter tests focused. Example inventories and list-index paths need
-updating, and offline smoke wiring must still select the intended fixture target.
 
-**Viable alternative:** opt out explicitly in the composed example with
+- [ ] ckprompt declares PromptKit v0.18.0, ConfigKit v1.1.0, ckconfig v0.3.0,
-`WithBundledOpenRouter(false)`. This is a supported application-loader choice
+  and core v0.3.0 through their vanity paths, with Go 1.27.0 and authentic sums.
-that keeps the example's inventory small and its resource positions simple.
+  Production code, tests, and the composed example exchange matching types.
-It does not demonstrate the default-on inventory; documentation should state
+- [ ] Reports omit removed descriptive prompt-version fields while preserving
-the example's choice, and focused adoption coverage should still show that the
+  collection release labels, source headers, and unrelated application versions.
-integration exposes a default-constructed engine's returned bundle evidence.
+  Native normalized inspection values and source evidence remain faithfully
+  projected through existing adapters.
+- [ ] Fixtures and resource builders use the adopted configuration shapes;
+  the composed example retains the default bundle, focused output checks cover
+  bundle evidence, and smoke tests use their intended offline targets.
+- [ ] The full ckprompt suite and maintained example tests pass independently
+  with workspace discovery off and read-only module metadata on Go 1.27.0.
+- [ ] The aligned three-module workspace and composed consumer pass validation,
+  with appropriate core/ckconfig regression checks. Preserve the ignored local
+  workspace, update its Go version as needed, and restore development guidance.
+  No workspace files or local dependency replacements enter the release.
+- [ ] Current GoDoc, CLI report contracts, consumer/example guidance (including
+  namespace views), notices, and the ckprompt v0.3.0 candidate note match the
+  implemented migration. Markdown links, fragments, examples, and whitespace
+  have been reviewed.
+- [ ] Final validation evidence and remaining deferred features are recorded.
+  Source publication and hosted delivery are tracked separately under the
+  existing release procedure.
 
-### OD-3: Include shared metadata inspection in adoption or a later sprint?
+The checklist records completion evidence; it does not add publication gates
-
+or require implementing deferred features. No core API change is planned for
-**Recommendation:** retain metadata inspection as the next shared functional
+this adoption.
-sprint after dependency adoption. The
-[configuration inspection proposal](future.md#configuration-inspection-extensions)
-owns the field metadata, path discovery, and history scope. Design the optional
-ckconfig provider capability and reports once, then connect PromptKit's native
-`Metadata()` result. Existing providers remain usable without the new facet.
-Preserve upstream field presence, explicitness, origins, and history, including
-history for removed paths; do not recreate provenance logic within ckprompt.
-
-**Viable alternative:** include the shared capability and PromptKit wiring in
-this adoption release. That expands the work beyond dependency alignment and
-requires a newly released ckconfig version containing the capability, replacing
-the current v0.3.0 target. Command grammar, selectors, report shapes, and provider
-design remain open under the shared proposal. The adoption can ship without
-this extension while retaining ckconfig v0.3.0.
-
-### OD-4: Add prepared-request inspection to the standard suite?
-
-**Recommendation:** treat this as the next substantive ckprompt enhancement
-after adoption and shared metadata inspection, with an explicit decision to
-extend standard inspection into rendering. Add an optional provider capability
-and report based on native `Engine.Prepare` and `PreparedRun`, reusing the
-concrete request-builder pattern. The native snapshot supplies selected
-prompt/profile/backend IDs, effective execution settings, rendered messages and
-session ID, output contract and schema metadata, input and rendered hashes, and
-preparation timing without calling an LLM. PromptKit owns preparation semantics.
-
-Command grammar, callback shape, selected report content and formats, and the
-relationship to existing request validation remain open. Any selected feature
-needs acquisition/availability, request forwarding, native-result projection,
-and report-delivery coverage at CommandKit's boundary; upstream retains tests
-of preparation and rendering. Selecting snapshot inspection would not select
-model execution or prepared-handle management.
-
-**Viable alternatives:** retain preparation inspection in application-owned
-commands, or deliberately include the optional feature in ckprompt v0.3.0 after
-resolving that design. The latter expands the release scope and validation;
-neither alternative requires local template resolution or a parallel preparation
-implementation. No new command or provider contract is selected here.
-
-### OD-5: Document namespace views or add standard selection support?
-
-**Recommendation:** begin with consumer guidance showing an application engine
-loader returning `Engine.WithNamespaces` with independently chosen prompt,
-profile, and backend defaults. Applications can already combine their typed
-selectors and loaders for this purpose. Include that guidance with migration
-documentation; consider a reusable helper or standard selectors when concrete
-consumers show repetition that CommandKit could remove.
-
-Namespace views resolve unqualified caller selections. Qualified selections
-retain their native treatment; captured configuration references and global
-configuration inspection are not rewritten, and namespace/collection inventories
-remain global. Existing catalog filtering keeps its current meaning.
-
-**Viable alternative:** design standard namespace-selection bindings or a helper
-as part of this release. The public API, applicable operations, independent
-resource defaults, and interaction with catalog filtering would need explicit
-decisions and focused forwarding coverage. No new flag names or changed meaning
-for existing namespace filters are selected by this roadmap.