commandkit/docs/roadmap/promptkit-v0.19.0.md

# 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.