Record PromptKit capability options and scope decisions

docs/roadmap/future.md

@@ -25,10 +25,11 @@ an idea here does not select its syntax, API, priority, or delivery date.
 
 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
-release/example choices. The current ckprompt v0.2.0 still uses published
+release, example, and capability scope choices. The current ckprompt v0.2.0 still
-ckconfig v0.2.0 and old-path ConfigKit v0.8.0; it does not compose with local
+uses published ckconfig v0.2.0 and old-path ConfigKit v0.8.0; it does not compose
-ckconfig v0.3.0. See the [consumer guide](../consumers/guide.md#module-selection)
+with local ckconfig v0.3.0. See the
-and [development guide](../development.md) for current module and workspace use.
+[consumer guide](../consumers/guide.md#module-selection) and
+[development guide](../development.md) for current module and workspace use.
 
 ## Future capability targets
 
@@ -138,6 +139,8 @@ 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)
+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
 published API/CLI contracts and deliberate compatibility decisions.

docs/roadmap/promptkit-v0.18.0.md

@@ -2,8 +2,9 @@
 
 Status: proposed; implementation has not begun. This roadmap captures the
 ckprompt migration and workspace alignment target. PromptKit v0.18.0 is the
-reviewed working baseline; final release selection and the maintained example's
+reviewed working baseline. Final release selection, the maintained example's
-bundle policy have recommendations under [Open Decisions](#open-decisions).
+bundle policy, and optional capability scope have recommendations under
+[Open Decisions](#open-decisions); those choices remain open.
 
 ## Purpose and authority
 
@@ -23,8 +24,10 @@ The [architecture](../policy/architecture.md), [agent](../policy/agents.md),
 [release](../policy/release.md), and [OSS](../policy/oss.md) policies govern the
 work. Current behavior remains owned by Go declarations and GoDoc, the
 [CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md).
-The other inspection proposals in [future work](future.md#configuration-inspection-extensions)
+The shared inspection proposals in
-remain separate from this dependency adoption.
+[future work](future.md#configuration-inspection-extensions) retain their own
+scope. This roadmap records how PromptKit could use that work and identifies
+additional capabilities without selecting them as adoption requirements.
 
 ## Baseline and review evidence
 
@@ -65,6 +68,42 @@ code or using local dependency replacements:
 - The full suite still needs version-fixture, configuration-shape, and report
   expectation changes. These diagnostics do not establish completed adoption.
 
+## API coverage and capability candidates
+
+A follow-up review compared the published v0.18.0 API with ckprompt at
+CommandKit revision `69cc642`. Existing report shapes cover the current prompt,
+profile, requirements, catalog, and smoke inspection results after removing
+obsolete prompt-version fields. Smoke reports already carry the native facts,
+timing, attempts, and usage; the review found no additional report fields to add
+in those operations.
+
+Three capabilities merit consideration beyond compatibility migration:
+
+| Capability | Current integration | Recommendation and scope decision |
+| --- | --- | --- |
+| Configuration metadata and history | Native `ConfigurationInspection.Metadata()` returns ConfigKit metadata. `ConfigScope` connects effective configuration, sources, explanations, and comparison, but has no metadata facet. | Extend the shared optional ckconfig capability first, then connect PromptKit's native metadata. Keep this as the next shared enhancement following adoption; see OD-3. |
+| Prepared-request inspection | Native `Engine.Prepare` returns a `PreparedRun` snapshot. ckprompt exposes concrete request validation but has no operation returning preparation results. | Consider an optional provider capability and report as the next substantive ckprompt enhancement. This extends standard inspection into rendering and needs an explicit scope choice; see OD-4. |
+| Namespace selection helpers | Native `Engine.WithNamespaces` supplies separate prompt, profile, and backend namespace defaults for unqualified selections. Applications can already return that view from an engine loader. Existing standard namespace selectors filter catalogs. | Begin with documented loader wiring; consider reusable helpers or standard selectors when consumers demonstrate repeated wiring. Keep name resolution distinct from catalog filtering; see OD-5. |
+
+The released [configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/configuration_inspection.go),
+[preparation API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go),
+[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)
+own those capabilities. They are available in v0.18.0; this review does not imply
+that each was introduced in that release.
+
+Request execution and output-validation overrides, session IDs, appended
+messages, and retry settings are already reachable through application request
+builders. Engine construction and bundle options remain available through
+loaders. Consider reusable bindings where consumers repeat the same wiring;
+adoption does not require a standard flag for every native option.
+
+`Run`, `PrepareExecution`, `RunPrepared`, and execution observers serve the
+application-owned execution workflow. Prepared-request inspection can use
+`Prepare` without adding model generation or prepared-handle lifecycle to the
+standard suite. Execution, serving, and session operations retain their current
+ownership. OD-4 addresses only the proposed rendering-inspection extension.
+
 ## Targeted end state
 
 ### Modules and Go compatibility
@@ -188,11 +227,19 @@ version or select new release gates.
 6. Update current contract owners, dependency notices and pinned license/source
    references, and the candidate release note. Review links, examples, and
    whitespace. Record final validation and publication status separately from
-   the earlier disposable review evidence.
+   the earlier disposable review evidence. Under OD-5's recommendation, include
+   native namespace-view loader guidance while keeping standard selector design
+   separate.
 
-The native adapter structure remains the starting point. The deferred metadata,
+The native adapter structure remains the starting point. OD-3 through OD-5 are
-detailed-comparison, failed-load-inventory, and structured-diagnostic proposals
+unselected scope choices, not additional adoption completion conditions. The
-in future work are not completion conditions for this adoption.
+recommended sequence is dependency/report and workspace migration, then shared
+metadata inspection, followed by separately selected prepared-request
+inspection. Namespace loader guidance can accompany migration documentation.
+The detailed-comparison, failed-load-inventory, and structured-diagnostic
+proposals in future work remain separate too. If capability scope is expanded
+into this release, revise the dependency target, implementation work, validation,
+and release documentation to match that decision before implementation.
 
 ## Upstream remediation boundary
 
@@ -245,3 +292,65 @@ that keeps the example's inventory small and its resource positions simple.
 It does not demonstrate the default-on inventory; documentation should state
 the example's choice, and focused adoption coverage should still show that the
 integration exposes a default-constructed engine's returned bundle evidence.
+
+### OD-3: Include shared metadata inspection in adoption or a later sprint?
+
+**Recommendation:** retain metadata inspection as the next shared functional
+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.