Plan PromptKit v0.19.0 adoption and operator CLI additions

docs/roadmap/future.md

@@ -33,33 +33,13 @@ under the [release procedure](../release.md).
 The published ckprompt v0.2.0 retains its earlier dependencies; see the
 [consumer guide](../consumers/guide.md#module-selection) for module selection.
 
-### PromptKit v0.19.0 roadmap preparation
+### PromptKit v0.19.0 adoption
 
-The completed adoption used PromptKit v0.18.0 as released. PromptKit v0.19.0
+The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md) owns the proposed adoption,
-has now been released and reviewed. The working adoption scope includes the
+operator CLI additions, shared configuration inspection work, open decisions,
-dependency, checksum, attribution, and unpublished candidate-note updates;
+and completion checklist. Scope is agreed in principle and remains subject to
-consumer compatibility guidance and corrected credential-report wording;
+roadmap review. Implementation has not started. Use released upstream contracts
-focused authentication-reason and smoke preparation-error coverage; and final
+only; do not inspect or monitor unreleased work in anticipation of adoption.
-independent-module and aligned-workspace validation.
-
-The proposed additional CLI scope is agreed in principle, subject to review of
-the adoption roadmap: concrete request preview, applicable request-override
-flags, namespace selection, configuration path discovery and explicitness,
-and detailed configuration comparison. Configuration failure investigation is
-also proposed for this roadmap, combining failed-load source inventory and
-structured diagnostics under
-[configuration inspection extensions](#configuration-inspection-extensions).
-Successful evidence reporting must retain the failed configuration outcome;
-report-delivery failures remain separately observable.
-
-These proposals concern standard operator commands, flags, and reports, not
-general-purpose helpers for application-internal PromptKit use. Exact CLI/API
-contracts and implementation sequencing remain for roadmap review. Focused
-backend inspection remains deferred pending released upstream support, as
-recorded under
-[PromptKit inspection and selection extensions](#promptkit-inspection-and-selection-extensions).
-Use released upstream contracts only; do not inspect or monitor unreleased
-upstream work in anticipation of future adoption.
 
 ## Future capability targets
 
@@ -72,42 +52,16 @@ relevant ADRs.
 
 ### Configuration inspection extensions
 
-The [completed ConfigKit v1.1.0 adoption review](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap/configkit-v1.1.0.md#selected-scope-decisions)
+The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md#shared-configuration-capabilities)
-retained the following work after dependency and source-report adoption.
+now includes the shared operator tasks previously retained here: metadata/path
-Metadata inspection is the recommended next functional sprint; the other
+discovery and explicitness, failed-load source inventory, detailed comparison,
-features have no selected sequence or delivery date. These proposals do not
+and structured diagnostics. Their earlier ConfigKit adoption identifiers were
-establish command grammar, report schemas, or new provider requirements.
+OD-3 through OD-6; the new roadmap has its own decision numbering. Implementation
-ConfigKit's public APIs own the evidence and its semantics.
+belongs in `ckconfig`, with PromptKit exposing native evidence through its
+configuration scope. CLI syntax and report contracts remain subject to review.
+
+Additional unselected work:
 
-- **Optional field metadata, path discovery, and history (OD-3).** Expose native
-  `Metadata.Lookup`, `IsExplicit`, `HistoricalPaths`, and `History` through an
-  optional provider capability. Design field and history reports together,
-  keeping existing providers usable. Distinguish effective paths from removed
-  historical paths: a failed `Lookup` must not suppress available `History`.
-  Validate that distinction and faithful projection of returned field/change
-  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. 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
-  precedes terminal failure presentation. Cover acquisition and report-delivery
-  failures together; current diagnostic context remains available meanwhile.
-- **Detailed comparison (OD-5).** Consider an additional form projecting native
-  `Difference` paths, both snapshots, presence/redaction fields, and
-  `HiddenChanged`. The current comparison retains the reduced
-  additions/changes/deletions report. Decide later whether a detailed form
-  complements it or replaces it through a deliberate compatibility change.
-- **Structured diagnostics (OD-6).** Consider machine-readable native codes,
-  paths, severities, and locations alongside CommandKit's shared reporting
-  design. Define result/diagnostic channels, warning and terminal-failure
-  interaction, and delivery outcomes. A ckconfig-specific report remains an
-  alternative, with its cross-family alignment considered explicitly.
 - **Source-ID filtering.** Consider selecting a record already available in the
   source inventory. Native `Source(id)` lookup is a convenience; this proposal
   need not introduce another command or require a lookup method from every
@@ -120,12 +74,11 @@ those capabilities primarily serve application loading and startup.
 
 ### PromptKit inspection and selection extensions
 
-The [completed PromptKit adoption scope](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap/promptkit-v0.18.0.md#scope-decisions) deferred these
+The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md#targeted-end-state)
-capabilities beyond the v0.18.0 compatibility migration. Shared configuration
+now owns concrete request preview, applicable request flags, namespace selection,
-metadata remains the recommended next functional sprint, under
+and the shared configuration inspection extensions. These are CLI features;
-[configuration inspection extensions](#configuration-inspection-extensions).
+general-purpose helpers for application-internal PromptKit use are outside
-The OD identifiers below belong to the PromptKit adoption roadmap, separately
+CommandKit's ownership boundary.
-from the ConfigKit review identifiers above.
 
 - **Focused backend inspection.** Defer a standard backend detail command
   until a released PromptKit version provides a suitable public backend
@@ -137,43 +90,12 @@ from the ConfigKit review identifiers above.
   configuration. Review the released upstream capability before selecting
   command syntax and report fields; this feature is outside the v0.19.0
   adoption scope.
-- **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).** The
-  [consumer guidance](../consumers/guide.md#namespace-views) covers 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)
+Additional request controls, including output-contract, inline-input, and
-and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go)
+appended-message flags, remain scope choices under
-provide the reviewed upstream contracts. These proposals establish no new
+[roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar).
-provider requirement, delivery date, or adoption completion condition.
+Their native API availability alone does not select CLI syntax or require a
+convenience API for application execution.
 
 ### Alias completion and discovery
 
@@ -229,9 +151,10 @@ operator or consumer need and an appropriate ownership/behavior decision:
 - Backend selection or replacement, a plugin framework, general dependency
   injection, and concurrent-dispatch guarantees.
 
-Execution, rendering, serving, and session operations remain application-owned.
+Execution, serving, and session operations remain application-owned. The
-The [prepared-request inspection proposal](#promptkit-inspection-and-selection-extensions)
+[request preview proposal](promptkit-v0.19.0.md#preview-and-request-flags)
-would extend standard inspection into rendering and remains an open scope choice.
+would expose native preparation and rendering as an operator inspection command;
+it remains subject to roadmap review.
 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.19.0.md

@@ -0,0 +1,398 @@
+# PromptKit v0.19.0 adoption and operator CLI
+
+Status: proposed roadmap for review. Scope is agreed in principle; implementation
+has not started. Command spellings, report designs, and API changes below are
+recommendations until the open decisions are resolved.
+
+## Purpose and ownership
+
+Adopt released PromptKit v0.19.0 and expose useful operator tasks through
+standard CommandKit commands, flags, and reports. This roadmap covers CLI
+exposure, including shared configuration inspection in `ckconfig`. It does not
+turn `ckprompt` into a convenience library for application-internal PromptKit
+operations. Applications continue to own engine construction, domain inputs,
+credentials, execution, and their executable lifecycle.
+
+The [architecture policy](../policy/architecture.md),
+[optional-module decision](../adr/0010-optional-integration-modules.md), and
+[reporting decision](../adr/0014-invocation-reporting.md) govern implementation.
+The [CLI reference](../cli.md) and public GoDoc remain the owners of implemented
+contracts. This roadmap selects work for review, not new guarantees about
+upstream behavior or permanent limits on future features.
+
+## Baseline and released evidence
+
+Repository baseline: `0b4e47c4206e323f7c5d5ec3f357494dd23008b2`.
+The completed v0.18.0 adoption is not reopened.
+
+| Component | Current baseline | Target |
+| --- | --- | --- |
+| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | No core change currently identified. |
+| `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Shared CLI inspection extensions and a new appropriate module release. |
+| `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | PromptKit v0.19.0 and the ckconfig version delivering the shared work. |
+| Candidate | [ckprompt v0.3.0](../../integrations/ckprompt/docs/releases/v0.3.0.md), recorded as unpublished | Update the unpublished candidate after checking its status during implementation. |
+| Local workspace | Core and both integrations, Go 1.27.0 | Validate local composition and independent modules separately. |
+
+Use PromptKit tag `v0.19.0`, commit
+`4f3212bfb6c1f37f43d50715c2cedc1d43203064`. Its Go minimum remains
+1.27.0 and its ConfigKit dependency remains v1.1.0. Reviewed sources are the
+[release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/docs/releases/v0.19.0.md),
+[request and report types](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/types.go),
+[engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/engine.go),
+[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/namespaces.go),
+[configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/configuration_inspection.go),
+and [smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/smoke_diagnostics.go).
+Work against released versions only; do not inspect or monitor unreleased
+upstream work in anticipation of another adoption.
+
+Current `ckprompt` supplies prompt/profile inspection, requirements discovery,
+concrete request validation, prompt/profile/backend/namespace/collection
+catalogs, and four smoke operations plus `test all`. Smoke commands already
+expose most execution overrides and detailed native evidence. Validation has
+profile, session, variable, and file-input flags but lacks that override surface.
+There is no concrete request preview or dedicated backend detail command.
+
+Current `ckconfig` supplies validation, native effective YAML, source inventory,
+path explanation with history, and reduced semantic comparison. Its `View`
+contains effective, sources, and explanation facets. Native metadata is not
+exposed as a capability. `config sources` returns on acquisition failure before
+rendering evidence; loaders convert native diagnostics into presentation
+messages but do not expose a structured diagnostics report. Relevant boundaries
+are [ckconfig contracts](../../integrations/ckconfig/contracts.go),
+[ConfigKit adapters](../../integrations/ckconfig/configkit_adapter.go), and
+[PromptKit adapters](../../integrations/ckprompt/adapters.go).
+
+## Targeted end state
+
+The original adoption tasks remain included:
+
+1. Update the dependency, checksums, attribution, and unpublished candidate note.
+2. Document all three upstream compatibility changes and correct credential
+   inspection wording.
+3. Cover the new authentication reason and corrected smoke preparation-error
+   propagation at CommandKit's boundary.
+4. Validate the final independent modules and aligned workspace.
+
+Add the following operator capabilities. Syntax is illustrative and subject to
+the decisions at the end of this document.
+
+| Operator task | Proposed CLI | Owning module and report |
+| --- | --- | --- |
+| Inspect what a concrete prompt request prepares | `promptkit show request ID --profile … --input … --var …` | `ckprompt`: selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
+| Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--extra-params JSON` on these and smoke operations | `ckprompt`: native request forwarding; preview and smoke reports show returned effective settings. |
+| Resolve unqualified resource selections in chosen namespaces | Independent prompt/profile/backend namespace flags | `ckprompt`: delegate to native namespace views, retaining the distinction from catalog filters. |
+| Find configuration paths and inspect their explicitness | `config paths --scope promptkit`, with historical selection; metadata alongside path explanation | `ckconfig`, wired through `ckprompt.ConfigScope`: observed paths, effective presence, explicitness/null/origin evidence, and available history. |
+| Understand both sides of configuration changes | `config diff --scope promptkit --details` | `ckconfig`: native paths, left/right snapshots, presence/redaction, and hidden-change evidence. |
+| Investigate a failed configuration load | `config sources --scope promptkit` on failure; a structured diagnostics operation | `ckconfig`, with both native adapters: acquired source inventory and native codes, severities, paths, and locations while retaining the load failure. |
+
+### Compatibility and native semantics
+
+Document these v0.19.0 changes for consumers constructing engines and inputs:
+
+- Successful custom `ArtifactReader.Read` transfers ownership of its returned
+  artifact and mutable body storage. Readers retaining scratch storage must
+  supply independent returned storage and stop mutating returned aliases.
+- `ProfileSource` and `BackendSource` provider maps now use ConfigKit's native
+  recursive Mapping forms: built-in scalar values, `[]any`, and
+  `map[string]any`. Explain explicit conversion of `json.Number` and typed
+  containers. Runtime execution overrides have a separate accepted-value
+  contract; do not impose configuration-source restrictions on their flags.
+- Local-validation and structured-output schemas must be self-contained.
+  External resources and filename-dependent base references fail preparation;
+  internal references or explicit schema IDs supply the supported route.
+
+No configuration-format migration is required from v0.18.0. Correct the CLI
+description of `api_key_required`: it indicates a usable direct or environment
+credential requirement and can coexist with `api_key_env`. Neither field is
+evidence of current credential availability.
+
+The new authentication response-limit reason is factual evidence with unknown
+credential acceptance. Continue forwarding native findings without converting
+false, unknown, unsupported, or incomplete observations into command failures.
+Actual preparation/operation errors retain the operational outcome and supported
+cause identity. Native errors and their categories remain upstream-owned.
+
+### Preview and request flags
+
+Add an independently available preview capability alongside existing suite
+callbacks. The native adapter calls `Engine.Prepare` and projects its returned
+snapshot; a preliminary `ValidateRequest` call is unnecessary. Use existing
+typed selection, acquisition diagnostics, and invocation reporting patterns.
+Exact callback names and signatures follow the selected CLI design.
+
+Preview performs applicable resource I/O and rendering but no model call.
+Rendered and appended messages contain application content. Upstream excludes
+resolved credentials from prepared settings; that does not make the whole
+snapshot a redacted configuration report or a transferable execution handle.
+Expose the upstream snapshot evidence without implying later execution uses
+that exact snapshot or will succeed.
+
+Share CLI binding implementation where it reduces duplication between smoke,
+validation, and preview. Preserve native explicit zero/empty values and
+whole-map replacement semantics. Keep parsing in CommandKit and domain validity
+in PromptKit. Existing application builders remain usable; resolve override
+precedence and the remaining request controls under OD-2 before documenting new
+public behavior. These helpers serve standard CLI commands only.
+
+### Namespace selection
+
+Design independent prompt, profile, and backend defaults together. Native
+`WithNamespaces` replaces all defaults on its new view; it has no partial-update
+semantics. Omission must therefore have a deliberate meaning when a loader
+already returns a scoped engine (OD-3).
+
+Qualified IDs pass through native selection unchanged. Captured references,
+configuration inspection, and namespace/collection inventories retain their
+native meanings. Existing `--namespace`/`--all-namespaces` catalog filters
+continue to describe filtering. Install new selectors only on operations where
+they have a defined use; define that applicability table during implementation.
+
+### Shared configuration capabilities
+
+Extend `ckconfig` through optional capabilities so existing custom providers can
+keep their currently declared operations. Both `FromConfigKit` and
+`ckprompt.ConfigScope` should expose available native evidence. Do not require
+all providers to implement every new operation.
+
+For metadata, use `Metadata.HistoricalPaths`, `Lookup`, `IsExplicit`, and
+`History`. Enumeration covers observed paths, not all possible schema fields.
+Do not discard history because effective lookup fails. Existing explanation
+already reports current/historical values; add the missing discovery and
+explicitness instead of reproducing upstream provenance logic. Preserve native
+list-index paths; do not silently reinterpret them as resource IDs.
+
+For detailed comparison, project native `Difference` records. Keep snapshots
+and their presence/redaction fields together, including `HiddenChanged` when
+the safe values look equal. Native sequence comparisons remain atomic; this
+work does not add element-level resource matching or a reloadable patch format.
+
+For failure investigation, retain `LoadError.Sources()` and `Diagnostics()` as
+evidence alongside the error. The current adapters and `config sources` failure
+path need changes, not just another renderer. Define an acquisition shape that
+distinguishes unavailable evidence from an available empty inventory. A failed
+load does not establish an effective configuration or metadata capability.
+
+Render available evidence through normal invocation reporting before terminal
+failure presentation. Keep the original load error and supported identity;
+successful report delivery must not convert failure to success. Preserve
+render/write failures separately through the current outcome machinery. Cover
+cancellation with partial evidence explicitly without promising interruption of
+an arbitrary writer or rollback of already-delivered bytes. OD-6 selects the
+structured diagnostics command and its interaction with ordinary diagnostics.
+
+## Work sequence
+
+1. **Resolve the significant CLI choices.** Review the open decisions, record
+   selections here, and identify affected published reports and flag collisions.
+   Prepare concrete command/flag/report examples for implementation review.
+2. **Adopt v0.19.0.** Update `integrations/ckprompt/go.mod` and `go.sum`, then
+   [module attribution](../../integrations/ckprompt/docs/oss/attribution.md)
+   against the released notices and source commit. Update the unpublished
+   candidate note and affected canonical dependency/compatibility guidance.
+   No core Go-minimum increase follows from this adoption.
+3. **Implement request inspection and selection.** Add preview, applicable
+   override flags, provider-parameter input, and namespace selectors. Reuse the
+   standard suite's lifecycle and preserve existing application adapter seams.
+4. **Implement shared configuration inspection.** Add metadata discovery and
+   explicitness, detailed diff presentation, source evidence on failure, and
+   structured diagnostics in `ckconfig`; wire native PromptKit facets through
+   `ConfigScope`. Keep each change reviewable with its boundary coverage.
+5. **Update operator and consumer documentation.** The CLI reference owns
+   syntax, report schemas, availability, and outcomes; GoDoc owns callback and
+   value contracts. Extend maintained simple/composed examples to demonstrate
+   the new CLI tasks using local fixtures, without adding application-internal
+   execution helpers. Record intentional compatibility effects in module notes.
+6. **Align module dependencies and validate.** Prepare the `ckconfig` release
+   needed by `ckprompt`, update the latter's dependency/checksums, and complete
+   the validation below. OD-7 addresses the interim development dependency.
+   Publication and hosted delivery remain separate actions under the
+   [release procedure](../release.md).
+
+## Validation and completion checklist
+
+Select focused boundary tests under the [testing policy](../policy/testing.md).
+The checklist concerns adapter/CLI behavior; it does not ask CommandKit to
+retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms.
+Default tests remain offline and independent of real credentials.
+
+- [ ] Dependency, checksums, attribution commit links, and candidate notes match
+  the final selected module versions.
+- [ ] All three compatibility changes and corrected credential wording are
+  documented, with earlier v0.18.0 migration guidance retained where relevant.
+- [ ] The authentication response-limit reason survives report projection with
+  native unknown facts. Smoke preparation errors retain supported causes and
+  operational outcomes, including the no-report case; no model dispatch is
+  introduced by CommandKit to handle them.
+- [ ] Preview forwards the intended request and faithfully reports native
+  fields. Its CLI path makes no model call and does not create/execute retained
+  prepared handles.
+- [ ] New flags preserve selected omission/empty/zero semantics, parse malformed
+  inputs through the existing usage path, and do not leak state between runs.
+  Numeric decoding of provider JSON matches the selected strategy in OD-2.
+- [ ] Namespace defaults, explicit clearing, qualified selections, and catalog
+  filters are forwarded according to the selected design.
+- [ ] Metadata discovery distinguishes effective and historical paths, retains
+  available history on absent lookup, and projects native field/change records.
+- [ ] Detailed diff retains both snapshots and presence/redaction/hidden-change
+  evidence, including empty comparisons and sequence-level changes.
+- [ ] Source and diagnostic evidence can be reported with an acquisition error;
+  the original failure, unavailable-versus-empty evidence, cancellation, and
+  report-delivery failures remain distinguishable.
+- [ ] Existing providers remain usable; help, version, and capability discovery
+  do not start acquisition. New operation/flag metadata and static completion
+  match the implemented surface.
+- [ ] Maintained consumer examples demonstrate the selected CLI tasks and the
+  configuration failure workflow with deterministic local evidence.
+- [ ] Canonical documentation, module release notes, and roadmap links agree
+  with the implemented boundary. Open decisions are resolved or deliberately
+  superseded before the corresponding behavior is claimed complete.
+- [ ] Final independent-module and aligned-workspace suites pass, with the
+  dependency identities used by each recorded.
+
+With the documented Go 1.27.0 toolchain selected, run
+`GOWORK=off GOTOOLCHAIN=local go test ./...` independently in the root,
+`integrations/ckconfig`, and `integrations/ckprompt`. Prepare dependencies before
+offline execution as described in the [release procedure](../release.md).
+Then validate the aligned workspace from the root with:
+
+```sh
+GOTOOLCHAIN=local go test ./...
+GOTOOLCHAIN=local go test ./integrations/ckconfig/...
+GOTOOLCHAIN=local go test ./integrations/ckprompt/...
+```
+
+Use the [development guide](../development.md) for toolchain/workspace setup and
+documentation checks. Reuse successful checks for unchanged content; these
+adoption checks do not add permanent publication gates. The earlier disposable
+dependency-only compatibility test is preliminary evidence, not completion
+evidence for these features.
+
+## Deferred work
+
+Focused backend inspection remains in [future work](future.md#promptkit-inspection-and-selection-extensions)
+until a released upstream API supports it. Do not reconstruct backend selection
+from configuration to deliver it in this roadmap. General execution, prepared
+handle lifecycle, sessions, and observer convenience APIs remain application
+responsibilities. Configuration mutation, new live probes, dynamic completion,
+JSON report formats, and unrelated deferred proposals are not added by this
+roadmap. A later ConfigKit review may propose further CLI tasks separately.
+
+## Open Decisions
+
+These decisions concern significant choices within the proposed scope. OD
+numbers are local to this roadmap, not the retired adoption documents.
+
+### OD-1: Preview command and report presentation
+
+**Recommendation:** use `promptkit show request ID`, with YAML as the initial
+report format and the complete relevant `PreparedRun` projection. It sits beside
+definition inspection while clearly requiring concrete inputs. A single native
+preparation supplies both validation and preview evidence. Document rendered
+content disclosure directly in help and CLI guidance.
+
+**Alternative:** `promptkit prepare ID`, with text and YAML reports. This names
+the native action and makes interactive inspection easier, but can suggest an
+executable prepared handle and adds a second rendering contract. Both forms can
+stay entirely within CLI ownership; select vocabulary and formats before coding.
+
+### OD-2: Request controls and provider-parameter grammar
+
+**Recommendation:** give validation and preview the applicable execution flags
+already on smoke tests, and add a singleton `--extra-params JSON` object option
+to all three. Use native whole-map replacement, including native behavior for
+empty maps. Specify JSON number decoding deliberately so supported values reach
+PromptKit without accidental precision loss or new numeric guarantees. Retain
+the current authoritative-builder rule: the standard flags seed a request and
+an application builder can return its complete replacement.
+
+**Alternative:** repeatable `--extra-param KEY=JSON` assignments. This is easier
+for individual shell overrides, but requires rules for duplicate keys and makes
+whole-map replacement less obvious. It must still construct a single native map
+rather than imply an upstream field-by-field merge.
+
+**Remaining request surface:** recommend keeping output-contract overrides,
+inline-input flags, and appended-message flags as separately selectable CLI
+extensions after execution-flag parity. Existing file inputs and application
+builders continue to support preview. A viable alternative is to include a
+whole-output-contract file option and message/input options now, supporting
+more reproduction workflows at the cost of additional syntax, precedence, and
+reporting decisions. No general-purpose request-building API follows from
+either choice.
+
+### OD-3: Namespace flags and loader defaults
+
+**Recommendation:** make the standard namespace selectors opt-in with explicit
+suite-owned namespace defaults. Compose supplied fields with those defaults,
+then apply one native `WithNamespaces` call. Loaders using this option leave
+default selection to that adapter. This gives omission and explicit empty
+values predictable meanings without trying to read private engine state.
+Without the option, existing scoped loaders continue as before.
+
+**Alternative:** pass presence-aware namespace choices to an acquisition
+callback and let the application combine them with its existing loader defaults.
+This accommodates applications whose defaults depend on domain input, but adds
+consumer wiring and makes consistent behavior less automatic. Either design
+must account for the native API replacing all three defaults at once.
+
+### OD-4: Configuration path and metadata presentation
+
+**Recommendation:** add `config paths` with effective paths by default and an
+explicit historical selection, and expose optional metadata alongside existing
+path explanation. Use the current single-scope selection model. This makes
+paths discoverable and uses an established command for their meaning/history.
+Define availability and unavailable metadata explicitly for older providers.
+
+**Alternative:** a separate `config metadata --path …` operation plus historical
+enumeration. This keeps the existing explanation report unchanged and gives
+metadata-only providers an independent operation, but splits related operator
+information across commands. Weigh that compatibility benefit against the
+extra command and report contract before selecting additive explanation fields.
+
+### OD-5: Detailed comparison selection and shape
+
+**Recommendation:** add `--details` to `config diff`, retaining the existing
+default. Emit a YAML record sequence carrying native paths, snapshots, and
+hidden-change fields, preferably within a scope-labeled envelope. This supplies
+the missing evidence without changing existing reduced-report consumers.
+
+**Alternative:** replace the reduced form with the detailed report in a new
+minor module release. One canonical report is simpler to maintain and avoids
+selection flags, but requires migration of published CLI consumers. The release
+policy permits a deliberate pre-v1 minor compatibility change; the benefit must
+justify that disruption.
+
+### OD-6: Failure evidence and structured diagnostic delivery
+
+**Recommendation:** extend `config sources` to report acquired inventory on
+failure and add `config diagnostics --format yaml` for native structured records
+and their source legend. Build this as optional `ckconfig` evidence facets,
+including evidence returned with an acquisition error. Keep ordinary human
+messages on the diagnostic stream and structured results on the result stream,
+using existing terminal failure/outcome handling. This is a bounded operator
+workflow with no demonstrated need for a generic core diagnostics schema.
+
+**Alternative:** add structured diagnostic output to every configuration
+operation through a common format option or report envelope. It avoids a
+second invocation when diagnosing another command, but complicates existing
+native YAML/report shapes and result-versus-diagnostic stream contracts. A
+broader core representation is viable if concrete cross-family needs justify
+it; it is more work than exposing ConfigKit records alone. Specify warning
+presentation, evidence availability, and partial-result cancellation behavior
+for the selected design rather than silently changing all operations.
+
+### OD-7: Module release and interim workspace coordination
+
+**Recommendation:** prepare a new ckconfig minor release for the shared API/CLI
+features, then update the still-unpublished ckprompt candidate to require it.
+Confirm available versions under the existing release procedure. During joint
+development use the ignored aligned workspace; record that workspace success
+does not establish independent ckprompt compatibility with its old ckconfig
+requirement. Before final independent validation, pin the released ckconfig
+version actually supplying the APIs. Publication requires its own authorization.
+
+**Alternative:** publish a compatibility-only ckprompt release first and deliver
+the additional CLI features in subsequent releases. This makes v0.19.0 fixes
+available sooner, but creates an extra consumer upgrade and does not complete
+this roadmap's targeted end state. A disposable local module replacement can
+help test intermediate changes, but cannot substitute for final validation of
+the declared released dependency.