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

# PromptKit v0.19.0 adoption and ConfigKit 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 except where explicitly recorded as agreed below.

## 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 ConfigKit v1.1.0 operator features 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.

ConfigKit v1.1.0 is already adopted at released commit
`191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9`. Its
[inspection API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/inspection.go),
[metadata API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/metadata.go),
and [configuration reference](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md)
support the additional CLI work below without an upstream dependency upgrade.
Its matched history for registered records moving within lists flows through
native inspection; it does not introduce identity-based CLI paths or
element-level effective diffs.

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

Effective display currently writes the whole configuration. Sources are reported
as a complete inventory. Comparison accepts independent config/overlay choices,
but applies the same application selectors to both typed inputs and succeeds
when a comparison reports differences. The new tasks extend those boundaries;
they do not replace already-delivered explanation or smoke functionality.

## 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 unless selected
in 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 prepared PROMPT_ID --profile … --input-file … --var …` | `ckprompt`: YAML report of selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
| Supply a short sample to one prompt without creating a file | `promptkit show prepared PROMPT_ID --input NAME=TEXT`; also request validation | `ckprompt`: native inline input for single-prompt preparation; file input remains available through `--input-file NAME=PATH`. |
| Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--llm-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 explain --list --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; structured diagnostics within `config validate` | `ckconfig`, with both native adapters: acquired source inventory and native codes, severities, paths, and locations while retaining the load failure. |
| Inspect one effective value or subtree | `config show --scope app --path /server` | `ckconfig`: the selected native effective snapshot, retaining redaction and absence/null distinctions. |
| Follow a source reference | `config sources --source-id ID` | `ckconfig`: the matching acquired source record, including evidence available after failure. |
| Compare different application selections | For example, `config diff --campaign spring --against-campaign autumn` | `ckconfig`: independently prepared typed inputs passed to the existing native comparison provider. |
| Detect configuration differences in scripts | `config diff --check` | `ckconfig`: a deliberate difference outcome based on native records, alongside the selected comparison report. |
| Narrow an inspection to relevant evidence | Subtree/explicitness filters on explanation discovery; severity/code filters on validation diagnostics | `ckconfig`: filtered native evidence with source references retained. |

The configuration suite retains six subcommands: `scopes`, `validate`, `show`,
`sources`, `explain`, and `diff`. Path discovery belongs within `config explain`;
structured diagnostics belong within `config validate`. This command placement
is agreed. Mode flags such as `--list` and `--diagnostics`, report shapes, and
filter spellings remain proposals under OD-4, OD-6, and OD-8. No separate path
inventory or diagnostics subcommand is planned.

Transient configuration overrides are an open scope decision under OD-11, with
a recommendation to include them as an optional loader capability. Illustrative
`config validate --set /workers=0` and `config show --set /server/port=8080`
would apply explicit overrides during acquisition without editing source files.
Their inclusion and exact CLI/API contract remain for review.

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

Expose preview as `promptkit show prepared PROMPT_ID`, with YAML-only output
initially, through an independently available 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.

Provide public, reusable typed execution-flag collections in `ckprompt`, defined
once and used by smoke, validation, preview, and application-owned commands.
The collections standardize flag names, help, parsing, completion hints,
supplied-value tracking, and binding into native PromptKit request fields.
Applications retain their own input structs, request construction, engine
acquisition, execution, and outcomes. Reusing CLI declarations is within
CommandKit's ownership boundary; it does not introduce runtime convenience APIs.

Use the existing core `CommandSpec[I].Flags`, typed flag constructors, and
`Supplied[T]`. A generic collection factory can accept destination accessors
and return ordinary `[]commandkit.Flag[I]`. Direct binding is sufficient for
ordinary use; existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go)
support deferred application or multiple destinations where needed. No core
change or new core collection abstraction is currently required. Exact exported
names and accessor signatures remain implementation design choices.

Keep execution-target overrides and the request-level transient retry field
distinct even when one convenient collection includes both. Preserve omission
instead of imposing shared defaults: ordinary execution and smoke diagnostics
have different native retry defaults. Preserve native explicit zero/empty
values and whole-map replacement semantics. Support deliberate subsets for
actual command needs while retaining common flag names and meanings, using a
proportionate composition API. Keep parsing in CommandKit and domain validity
in PromptKit. Existing application builders remain authoritative as agreed in
OD-2. That decision also selects literal-text and file input bindings, defers
output-contract overrides, and leaves appended-message controls open.

### 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 inspection mode. Providers lacking metadata
or structured diagnostics retain their existing explanation/validation behavior;
mode availability and help must reflect the capabilities supplied.

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 within explanation discovery 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
validation diagnostic mode and its interaction with ordinary diagnostics.
Structured records describe that validation invocation, including a failed
load; they are not a retrieval interface for an earlier command. Preserve the
current aggregate validation stopping behavior unless deliberately revised;
structured reporting alone does not promise exhaustive findings across scopes.

### Additional ConfigKit operator workflows

**Focused effective display.** Use the effective snapshot from native
`Explain(path)` for path-selected display. The ordinary whole-document path
continues to use `WriteEffective`. A historical-only path can be explainable
while lacking an effective value; distinguish that case from a present YAML
null. Select the missing-value behavior, provider availability, and aggregate
scope applicability under OD-8. Do not read mutable `Result.Config` or source
files to reconstruct inspection values.

**Source selection and report filters.** Select source IDs from the acquired
inventory, preserving existing record fields and upstream ordering. Native
`Source(id)` is a convenience, not an additional provider requirement. IDs are
local to a load and do not guarantee the same source in a later acquisition.
Apply subtree filtering to parsed configuration paths, not raw string prefixes
that would confuse `/server` with `/server2`. Specify explicitness filtering for
historical-only paths without treating unavailable effective metadata as false.
Diagnostic filters affect the presented records, not the underlying acquisition
outcome; retain the source references needed to interpret selected records.

**Independent comparison selections.** Extend the per-side typed-input design
in [ADR 0012](../adr/0012-typed-configuration-comparison-pairs.md). Capture
applicable selector bindings for each side, prepare and check both inputs before
comparison, and preserve the existing shared invocation state. Resolve omitted
right selectors, explicit empty values, repeated selectors, and flag-name
collisions under OD-9. Domain interpretation and loader caching remain with the
application; the comparison provider still receives two selections.

**Comparison assertions.** Base a difference outcome on native record presence,
including hidden changes whose redacted snapshots look equal. Equal effective
values can have different histories or explicitness. Comparison also does not
detect changed credential bytes behind an unchanged secret reference. Define
the opt-in outcome and report-delivery behavior under OD-10; retain the current
ordinary diff outcome. A load or comparison failure is not evidence of equality.

**Transient override candidate.** If selected in OD-11, parse explicitly supplied
CLI values into native `Override` records and pass them through a declared loader
capability. ConfigKit owns override path validity, supported values, precedence,
decoding, resolution, provenance, and validation. Its configuration overrides
recursively overlay mappings and replace sequences; this differs from the
PromptKit execution override's complete provider-map replacement. Do not reuse
one grammar implementation in a way that erases that distinction. Source-load
errors remain errors even if an override would replace the affected value.

## 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, literal-text
   input and renamed file-input flags, applicable override flags,
   provider-parameter input, and namespace selectors. Implement
   public `ckprompt` execution-flag collections on existing core bindings and
   reuse them in the standard commands. Generate scoped convenience aliases and
   provide a collection for installing the commands and routing declarations.
   Reuse the standard suite's lifecycle and preserve existing application adapter
   seams.
4. **Implement shared configuration inspection.** Add discovery and metadata
   within `config explain`, structured diagnostics within `config validate`,
   detailed diff presentation, and source evidence on failure in `ckconfig`.
   Retain the six-command suite and wire native PromptKit facets through
   `ConfigScope`. Add focused effective display, source selection, and bounded
   metadata/diagnostic filters using those evidence capabilities. Extend typed
   comparison selection and add the selected assertion outcome. If OD-11 is
   accepted, implement explicit override acquisition and comparison-side wiring
   as a separate reviewable unit. Keep boundary coverage with each change.
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.
- [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and
  faithfully reports native fields in YAML, the only initial output format.
  Help identifies the argument as a prompt ID and explains resource I/O and
  rendered content disclosure. 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.
- [ ] The same public execution-flag collection works in a standard subcommand
  and an application-owned command with its own typed input. Parsing, presence,
  metadata, and selected subsets remain consistent; omitted retry values retain
  the applicable native defaults. Application execution behavior remains outside
  the collection.
- [ ] Canonical `--llm-` flags and scoped convenience aliases follow OD-2.
  Alias generation covers only enabled commands and applicable flags, shares
  canonical binding/presence behavior, and preserves mixed-spelling occurrence
  order. Generic spellings remain available to unrelated application commands.
- [ ] The convenient installation collection includes commands and their scoped
  aliases; canonical-only installation remains available. Help and migration
  guidance explain both forms without requiring consumer-maintained alias lists.
- [ ] Text and file input names and aliases follow OD-2. Literal content,
  including empty text, reaches native inline inputs; file bindings remain file
  references. Examples, help, and documentation use the selected meanings.
  Resolve and cover duplicate-name precedence across the two input forms.
- [ ] Appended-message options receive an explicit scope decision before
  implementation; output-contract override flags remain deferred.
- [ ] Namespace defaults, explicit clearing, qualified selections, and catalog
  filters are forwarded according to the selected design.
- [ ] The full configuration suite retains six subcommands. Explanation
  discovery and validation diagnostics are modes of existing commands, with
  capability-aware help and selected mode/flag combination checks.
- [ ] Metadata discovery through `config explain` 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.
- [ ] Focused display preserves native snapshot content and distinguishes
  missing/historical-only paths from explicit null. Whole-document display
  retains its current contract.
- [ ] Source-ID selection works on successful and failed acquisitions. Path,
  explicitness, severity, and code filters preserve the selected evidence and
  source references without masking the acquisition outcome.
- [ ] Independent comparison selectors preserve the chosen inheritance and
  repeatable-value rules, side-specific checks, and shared-state lifecycle.
- [ ] Assertion mode distinguishes equality, native differences (including
  hidden changes), usage errors, and operational failures under the selected
  outcome contract. Report-delivery failures remain observable.
- [ ] OD-11 has an explicit scope decision. If included, only supplied CLI
  overrides reach opted-in loaders, with typed values, safe flag labels,
  selected comparison-side behavior, native errors, and returned provenance
  preserved. No tests independently re-establish ConfigKit override semantics.
- [ ] `config sources` and the structured mode of `config validate` report
  available evidence 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, including
  collection reuse by an application-owned command.
- [ ] 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. Persistent configuration editing, new live probes, dynamic completion,
JSON report formats, and unrelated deferred proposals are not added by this
roadmap. Transient acquisition overrides remain an explicit choice in OD-11.
Output-contract override flags are also deferred under OD-2 and retained in
[future work](future.md#promptkit-inspection-and-selection-extensions).
Discovery tracing and secrets-directory bootstrap commands remain deferred:
the source inventory is not a trace of rejected search candidates, and bootstrap
performs application startup effects.

## Open Decisions

These decisions concern significant choices within the proposed scope. Resolved
items retain their numbers and record the agreed decision. OD numbers are local
to this roadmap, not the retired adoption documents.

### OD-1: Preview command and report presentation

**Agreed:** use `promptkit show prepared PROMPT_ID`, with YAML-only output
initially and the complete relevant `PreparedRun` projection. The argument names
the prompt to prepare, not a saved prepared object. A single native preparation
supplies both validation and preview evidence.

The command sits beside definition inspection and emphasizes that the report
contains resolved settings and rendered content. Use help wording such as:
"Prepare a prompt request and show the resulting messages and settings without
calling the model."

Document resource I/O and rendered content disclosure directly in help and CLI
guidance. The report is an inspection snapshot, not a saved execution handle or
a guarantee that later execution uses the same snapshot or succeeds. A separate
text presentation may be considered later; it is outside the initial scope.

### OD-2: Request controls and provider-parameter grammar

**Agreed:** execution flags are public reusable CLI collections owned by
`ckprompt`, available to standard and application-owned commands using existing
core APIs. Give validation and preview the applicable execution controls already
on smoke tests, and add a singleton `--llm-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. The
single-object form is selected over repeated key assignments.

Retain the authoritative-builder rule: standard flags seed a request, and an
application builder can return its complete replacement. Do not reapply CLI
values after the builder returns.

**Agreed naming and aliases:** use `--llm-` canonical names throughout the
reusable request-control family. Standard `promptkit` commands also accept the
unprefixed convenience spellings wherever the corresponding flag applies.
Application-owned commands receive canonical names from the reusable collections;
applications may deliberately install convenience aliases on their own commands.

| Canonical flag | Convenience alias within applicable `promptkit` commands |
| --- | --- |
| `--llm-endpoint` | `--endpoint` |
| `--llm-model` | `--model` |
| `--llm-temperature` | `--temperature` |
| `--llm-max-tokens` | `--max-tokens` |
| `--llm-top-p` | `--top-p` |
| `--llm-timeout-seconds` | `--timeout-seconds` |
| `--llm-service-tier` | `--service-tier` |
| `--llm-reasoning-effort` | `--reasoning-effort` |
| `--llm-api-key-env` | `--api-key-env` |
| `--llm-transient-retries` | `--transient-retries` |
| `--llm-extra-params` | `--extra-params` |
| `--llm-backend` | `--backend` |
| `--llm-profile` | `--profile` |
| `--llm-prompt` | `--prompt` |
| `--llm-session-id` | `--session-id` |
| `--llm-var` | `--var` |
| `--llm-input-text NAME=TEXT` | `--input-text`, `--llm-input`, `--input` |
| `--llm-input-file NAME=PATH` | `--input-file` |

Retain existing value syntax and units, including integer timeout seconds.
The input naming and content changes are specified below. Commands taking a
positional prompt ID retain that argument; this naming decision does not add a redundant prompt flag. Execution,
resource-selection, and request-input collections may remain separately
composable. Namespace controls remain subject to OD-3.

**Agreed assembly approach:** keep alias generation in `ckprompt`; no core
upgrade is required. Define each flag-to-alias relationship once and generate
existing `FlagAliasFor` routing declarations from the flags selected for each
enabled canonical command. Do not maintain a separate hand-written matrix of
all command/flag combinations. Aliases target the original flag binding rather
than introducing duplicate bindings. Both spellings retain core parsing,
presence, and occurrence-order behavior.

Offer a convenient collection containing the command family and its scoped
routing declarations, using existing `[]commandkit.Declaration` installation.
Keep `ckprompt.Command(suite)` available for canonical commands without the
convenience aliases. Exact helper names remain implementation choices. Generate
aliases only for enabled commands and applicable flags; do not install
application-wide aliases or make consumers reproduce the command/flag matrix.
Applications can install selected aliases on their own commands through the
existing core API. Subtree alias scopes and a new core declaration-bundle type
are not part of this adoption.

Help should identify canonical names and their applicable aliases using current
core presentation. CommandKit is alpha with no consumers; redesign without
compatibility constraints is explicitly accepted for these flags. Update implementation, examples, help, and documentation together; do not
retain old meanings merely for compatibility. Canonical-only installation does
not supply convenience aliases.

**Agreed input forms:** include literal text alongside file input for
`promptkit requirements validate` and `promptkit show prepared`. The concrete
operator task is preparing one selected prompt with a short, disposable sample
without creating a fixture file. File inputs remain useful for substantial
content and repeatable artifacts. These operations make no model call and do
not establish model-output quality or application-workflow success. Assess
usefulness within these standard commands; speculative applicability to
multi-prompt application workflows is not a reason to add flags.

Use the explicit canonical pair `--llm-input-text NAME=TEXT` and
`--llm-input-file NAME=PATH`. The scoped aliases in the table include both
`--input` and `--llm-input` for literal text. They route to the original text
binding with the same parsing, presence, and occurrence-order behavior.
`--input` no longer means a file path; file bindings use the explicit file form.
Do not infer file access from literal content that resembles a path.

Provide repeatable named bindings, splitting at the first `=` and preserving
literal content, including explicit empty text, through native `Inline` inputs.
File bindings continue to use native `File` references. Keep the canonical
forms available through reusable request-input collections; application commands
choose whether these bindings fit their workflow and may opt into aliases.
None of these aliases is application-wide by default. Do not add prompt-input
flags to smoke tests, which use their own diagnostic content.

Duplicate-name precedence across text and file bindings remains a design point
for review. The current recommendation is last command-line occurrence wins
across both forms; this is not yet an agreed cross-binding ordering contract.

**Deferred output-contract overrides:** no CLI override is included in this
adoption. Retain the candidate in
[future work](future.md#promptkit-inspection-and-selection-extensions);
existing configuration and application builders remain available.

**Remaining request surface:** discuss appended-message flags individually
before selecting scope and syntax. No general-purpose request-building API
follows from these CLI choices.

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

**Agreed placement:** path discovery is part of `config explain`; no separate
path or metadata command will be added in this roadmap.

**Recommendation:** add an explicit discovery mode such as
`config explain --list`, with effective paths by default, optional historical
selection, and subtree/explicitness filters. Keep `config explain --path POINTER` for detailed
explanation, including optional field metadata. This retains the current
missing-path usage error outside discovery mode and makes the operator's intent
clear. Use the current single-scope model. Define mode combinations, formats,
and unavailable metadata handling before implementation; exact flag spellings
remain open.

**Alternative:** make omission of `--path` select discovery automatically, while
supplying it selects detailed explanation. This reduces flags and gives bare
explanation a useful behavior, but deliberately changes today's missing-path
error and can make an accidentally omitted path harder to notice. Both designs
keep discovery and detailed history together in one command.

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

**Agreed placement:** structured configuration diagnostics are part of
`config validate`; there will be no separate diagnostics command. Source
inventory on failure remains part of `config sources`.

**Recommendation:** add an explicit validation diagnostic mode, for example
`config validate --diagnostics --format yaml`, reporting native records and a
source legend alongside the validation result. Keep the existing validation
report when that mode is omitted. Support severity/code filters in the mode
without changing the underlying outcome. This preserves existing consumers and
lets the same invocation both validate and explain its findings, including
available evidence on load failure.

Build optional `ckconfig` evidence facets that can accompany an acquisition
error. Structured results use the result stream, ordinary messages use the
diagnostic stream, and terminal failure/outcome handling remains in place.
Resolve warning duplication, unavailable-versus-empty evidence, report shape,
and partial-result cancellation behavior during design. Successful delivery of
findings must not replace a failed load with a successful validation result.

**Alternative:** enrich `config validate --format yaml` directly with diagnostic
records and source evidence, without a new mode flag. This gives scripts richer
information by default but changes the existing YAML report and failure-output
contract, requiring deliberate compatibility treatment. Either choice stays
within validation and uses current core reporting; a generic cross-family core
diagnostics schema is not needed for this scope.

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

### OD-8: Focused configuration reports and filtering

**Recommendation:** extend existing commands: `config show --path POINTER` and
`config sources --source-id ID`; add subtree/explicitness filters to
explanation discovery and severity/code filters to validation diagnostics. Keep
unfiltered reports as the default within those modes. Use the existing
explanation capability for selected effective YAML, and recommend an operational
failure for an absent effective path or
unknown source ID, consistent with unknown-path explanation. Recommend starting
path-selected display with one scope; whole-document `--scope all` remains
available. Specify presence-aware explicitness filtering so historical-only
entries are not labeled implicitly defined. These choices reuse existing
operator vocabulary and native evidence with little additional acquisition work.

**Alternative:** offer a structured mode of `config show --path POINTER` with
a snapshot envelope containing `present`, `redacted`, and `yaml`, and return
absence as report data. This is convenient for scripts and preserves
unknown/null/absence distinctions without relying on exit status, but adds a
report format choice alongside native effective YAML. Aggregate path-selected
reports are also viable if scope-labeled per-scope absence and delivery semantics
are designed. Filters can be deferred
in favor of downstream YAML tools, reducing CLI surface but making routine
operator inspection more cumbersome.

### OD-9: Independent comparison selector bindings

**Recommendation:** let applications declare which domain selectors support
right-side comparison values, with explicit metadata for their `--against-*`
spellings. Omission inherits the left value and presence; an explicit right
value replaces it. For repeatable selectors, recommend replacing the inherited
collection with the supplied right collection. This follows config/overlay
selection conventions and supports comparisons such as two campaigns without
requiring different files. Review the selected refinement of ADR 0012 and flag
collision handling before implementation; exact helper signatures remain open.

**Alternative:** require symmetric explicit left/right selectors for opted-in
bindings. This makes each side independent and easier to reason about when
defaults are complex, but adds repetition and departs from the existing
right-inherits-left convention. Either design keeps application domain parsing
in its declared bindings and avoids inventing a generic selector language.

### OD-10: Comparison assertion outcomes

**Recommendation:** add opt-in `--check`, retaining normal report delivery and
ordinary diff behavior when omitted. Recommend status `0` for equality and a
domain difference status `3`; retain current usage `2` and operational `1`
classification. This lets scripts distinguish differences from failed
comparison. The status is a proposal, not an existing contract. Apply existing
reporting outcome rules, including preservation of a nonzero domain outcome
when presentation also fails; callers can inspect the separate presentation
evidence. Document that interaction explicitly.

**Alternative:** use status `1` for both differences and operational failures
in the opt-in assertion mode. This fits simple shell checks and avoids a new
difference status, but requires additional evidence to distinguish detected
changes from failed comparison. Both approaches remain modes of `config diff`.

### OD-11: Transient configuration overrides

**Recommendation:** include a declared, opt-in override capability for standard
configuration commands, with repeatable `--set POINTER=JSON` values passed to
application acquisition as native ConfigKit overrides. This enables validation,
inspection, and comparison of temporary settings through consistent CLI syntax.
Providers that do not accept overrides retain their existing operations. No
source file is edited, and no general application-internal convenience API is
required. The loader contract must state how it combines these records with
any existing application-owned overrides; the generic adapter cannot inject
them into an arbitrary loader after the load has completed.

If selected, settle these details before implementation:

- Split at the first `=`; JSON supplies typed null, boolean, string, numeric,
  array, and object values. Specify numeric conversion to ConfigKit-supported
  built-in forms rather than passing `json.Number` or silently promising
  arbitrary numeric precision. An unambiguous alternate input form may be
  needed for pointer keys containing `=`.
- Forward explicit records only, with safe display labels such as `--set`,
  never raw value-bearing arguments as provenance labels. Preserve native
  duplicate/overlap handling rather than silently collapsing assignments.
- Follow the released mapping-path constraints, including root/index and
  schema-version restrictions, without extending them into a generic patch
  language. Empty, false, zero, and null remain intentional supplied values.
- For comparison, recommend `--set` as the shared baseline and
  `--against-set` as a right-side replacement list when supplied, following
  OD-9's proposed repeatable-selector rule. Define an explicit way to select
  an empty right list before finalizing this grammar; appending or replacing
  individual paths would need a different selected rule.
- Reflect native CLI origins and subsequent resolution in existing reports.
  Test CommandKit parsing, forwarding, and outcome/report adaptation, leaving
  ConfigKit's override algorithm to its own tests.

**Alternative A:** retain application-specific typed flags and loader translation
to `Options.Overrides`. This gives applications tailored vocabulary and avoids
generic JSON numeric/path syntax, but repeats CLI infrastructure and prevents
uniform temporary-setting workflows across applications. This is a viable
deferral if the generic acquisition contract is too disruptive for this sprint.

**Alternative B:** accept a structured override document containing path/value
records instead of inline `--set` assignments. It handles complex values and
unusual pointer keys naturally and makes an empty comparison-side list explicit,
but adds file-input handling and is less convenient for one-value shell changes.
It still needs deliberate typed-value decoding and loader opt-in. Neither
alternative authorizes persistent configuration mutation.