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. Accepted report formats are an initial implementation target; practical beta feedback will guide later refinements rather than requiring exhaustive layout design now.

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, optional-module decision, and reporting decision govern implementation. The CLI reference 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 needed for flag collections or scoped aliases; assess a small shared YAML output helper during implementation.
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, 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, request and report types, engine API, namespace API, configuration inspection API, and smoke API. 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, metadata API, and configuration reference 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, ConfigKit adapters, and PromptKit adapters.

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; config validate --details --scope promptkit	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. OD-4 selects --list and --path as the explanation modes, with help on a bare invocation. OD-6 selects config validate --details for detailed diagnostics while retaining concise validation by default. Initial report presentation and filter spellings are selected under OD-4, OD-6, and OD-8; exact Go projections can be refined during implementation. No separate path inventory or diagnostics subcommand is planned.

Transient configuration overrides are included under OD-11 as an opt-in loader capability. config validate --set /workers=0 and config show --set /server/port=8080 apply temporary overrides during acquisition without editing source files. Numeric conversion, unusual pointer keys, loader composition, and comparison-side grammar remain to be finalized.

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 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 and defers output-contract overrides and appended-message controls.

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. Under the agreed OD-3 design, opt-in selectors combine explicitly declared suite defaults with supplied overrides; they do not infer defaults from a loader's engine view.

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 optional detailed comparison, project the native Difference records already returned by Scope.Compare; retain the existing concise report by default. Keep snapshots and their presence/redaction fields together, including HiddenChanged when the safe values look equal. Reuse the same loading and comparison path for both presentations. 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 config validate --details; its interaction with ordinary diagnostic messages remains a presentation design task. 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. 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. Use the agreed 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 overrides. As agreed 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.

Initial report implementation approach

Use the accepted OD-4 through OD-6 flags and formats as a practical starting point. Keep added code, report types, and translations proportionate. Beta feedback on actual reports should guide changes; do not delay implementation for speculative layout options or build a report framework in anticipation of future formats.

The repository already uses go.yaml.in/yaml/v4 and small Go-value-to-YAML writers in core and both integrations. Centralize common encoder configuration and reusable output helpers where practical. A small shared writer accepting an io.Writer and a Go report value is sufficient; exact placement and exported API, if needed across module boundaries, are implementation choices. Keep any core helper independent of ConfigKit and PromptKit types. A separately versioned output module or custom serialization engine is not needed. Account for module release/dependency ordering under OD-7 if a shared public core helper is added.

Prefer directly encoding suitable native inspection/report values or a thin Go projection with serialization tags. Do not mirror a whole upstream object graph just to rename fields or rearrange equivalent data. Reuse small path, snapshot, location, and duration projections where they are genuinely needed. Types whose intended representation depends on JSON tags or custom JSON serialization cannot be assumed to encode identically under YAML; reuse their supported serialization or provide a small explicit adapter rather than inventing a reflection framework.

Exceptions serve concrete report semantics: preserving absent/null/false/zero and empty collections, expressing paths and durations readably, projecting safe snapshot values, and retaining native redaction. Encode report/inspection values, not engines, mutable runtime configuration, or request credential storage. Reuse native writers where their output already serves the selected report. Keep the existing concise diff and validation presentations; the simpler YAML approach applies to detailed reports and other suitable projections.

Separate content projection from YAML encoding and from invocation delivery. Use the existing Reporter and outcome lifecycle for delivery and failures. Share common helpers without forcing text output through a YAML round trip or forcing semantically different reports into one schema. Validate representative reports and meaningful adaptation boundaries, rather than freezing every incidental formatting detail in tests.

Work sequence

1. Confirm remaining implementation choices. Use the accepted flags and report formats as the MVP target. Resolve outstanding acquisition/binding grammar and flag collisions; use concrete examples to review report details during implementation rather than reopening accepted scope.
2. Adopt v0.19.0. Update integrations/ckprompt/go.mod and go.sum, then module attribution 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 via config validate --details, 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 agreed assertion outcome. Implement explicit override acquisition and comparison-side wiring under OD-11 as a separate reviewable unit. Reuse and centralize output helpers under the initial report implementation approach. 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.

Validation and completion checklist

Select focused boundary tests under the testing policy. 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. Verify that the last command-line occurrence for a name wins across text/file forms and all aliases, preserving actual occurrence order.
• Output-contract override and appended-message flags remain outside this adoption, with their operator use cases retained in future work.
• Opt-in namespace selectors combine declared suite defaults with supplied fields in one native view update. Omission preserves each declared default; explicit empty values clear only the selected default. Qualified selections and catalog filters retain their native meanings. Custom scoped loaders remain usable without the option. Canonical namespace names and scoped aliases match OD-3, with an explicit applicability table.
• 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.
• Bare config explain displays help successfully, presenting --list and --path as the two alternatives. Selecting both modes is a usage error; explicitly supplied --path "" selects root explanation rather than help.
• Discovery uses text by default with YAML available, compact path/presence/ explicitness fields, and the selected --historical, --under, and --explicit behavior. Historical-only paths and unavailable discovery are not misreported as current implicit values or an empty configuration.
• Metadata discovery through config explain distinguishes effective and historical paths, retains available history on absent lookup, and projects native field/change records.
• Default config diff retains its concise additions/changes/deletions report. Optional --details uses the same comparison records to present both snapshots and presence/redaction/hidden-change evidence. Cover additions, deletions, explicit null, empty comparisons, sequence-level changes, and report-delivery failures without extra configuration loads or comparisons. Detailed YAML uses one before/after entry per path and an explicit empty list when there are no differences.
• Focused display preserves native snapshot content and distinguishes missing/historical-only paths from explicit null. Whole-document display retains its current contract. Focused display uses one scope and native YAML without a snapshot wrapper; absent effective paths and unknown source IDs produce clear operational failures.
• 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. Explicit empty right-side collection selection is designed and covered.
• Assertion mode distinguishes equality, native differences (including hidden changes), usage errors, and operational failures with statuses 0, 3, 2, and 1 respectively, without changing ordinary diff outcomes. Report-delivery failures remain observable.
• Only supplied CLI overrides reach opted-in loaders under OD-11, with typed values and safe flag labels, selected comparison-side behavior, native errors, and returned provenance preserved. No tests independently re-establish ConfigKit override semantics.
• Default validation remains concise; --details selects the additional diagnostic report, with text by default and optional YAML. Selecting YAML alone does not enable detailed mode. Severity/code filters, evidence availability, no-match presentation, and known duplicate-warning handling preserve the underlying validation outcome.
• config sources and config validate --details 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.
• Suitable reports use direct Go-value serialization or thin projections, sharing YAML and common output helpers where practical. Necessary adapters preserve native meaning without a generic report translation framework.
• 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. Then validate the aligned workspace from the root with:

GOTOOLCHAIN=local go test ./...
GOTOOLCHAIN=local go test ./integrations/ckconfig/...
GOTOOLCHAIN=local go test ./integrations/ckprompt/...

Use the development guide 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 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 are included under OD-11. Output-contract override and appended-message flags are deferred under OD-2 and retained in future work. 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.

Agreed input precedence: the last command-line occurrence for a given input name wins across text and file bindings, including every alias. Implementation must preserve actual occurrence order rather than applying one flag collection after the other in a fixed order. Select the necessary binding composition during implementation; do not claim this behavior from independent flag binding alone.

Deferred output-contract overrides: no CLI override is included in this adoption. Retain the candidate in future work; existing configuration and application builders remain available.

Deferred appended-message flags: no CLI message-appending option is included in this adoption. The potential standard-command task is reproducing a request with application-added messages for preparation validation or preview. Revisit when that is a demonstrated operator requirement; ordinary named inputs remain available for inspecting prompt definitions with concrete content. Retain the candidate in future work. No message-file format, flag syntax, or role-selection interface is selected. Native application-supplied appended messages remain part of prepared-request inspection; deferring flags does not remove that report evidence. No general-purpose request-building API follows from these CLI choices.

OD-3: Namespace flags and loader defaults

Agreed: make the standard namespace selectors opt-in with explicit application-supplied defaults for prompts, profiles, and backends in the suite. ckprompt combines those defaults with the supplied CLI fields, then applies one native WithNamespaces call. Loaders using this option leave namespace default selection to that adapter rather than relying on hidden engine-view state. Without the option, existing scoped loaders continue as before.

Omitting a selector preserves its declared default. Supplying a namespace replaces that default for the invocation; supplying an explicitly empty value clears it. Each resource type is independent. For example, overriding the prompt namespace must preserve the declared profile and backend defaults. Qualified resource IDs pass through unchanged. Catalog namespace filters remain separate from these resource-resolution defaults.

The standard option owns composition instead of requiring an application callback to merge every selection. Applications needing custom namespace selection can retain their own loading behavior without enabling the option.

Agreed names:

Canonical selector	Scoped alias within applicable promptkit commands
--llm-prompt-namespace	--prompt-namespace
--llm-profile-namespace	--profile-namespace
--llm-backend-namespace	--backend-namespace

Keep catalog --namespace filtering separate. Applicability to individual commands and exact public helper signatures remain design tasks; install only selectors with a defined use for that operation.

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.

Agreed mode selection: bare config explain displays command help as a successful help request. Help explains that an operation requires either --list to discover paths or --path POINTER to explain a selected path. This makes both capabilities visible instead of implicitly choosing discovery.

• Neither mode selected: show help, with success on successful help delivery.
• --list selected: discover configuration paths.
• --path supplied: explain that path.
• Both modes selected: report a usage error.

Track path presence separately from its value: explicit --path "" selects the root explanation, not help. This deliberately replaces the current missing-path usage error; automatic discovery on a bare invocation is not selected.

Agreed initial presentation: use a compact text discovery report by default, with YAML available through --format yaml, and one scope at a time. List current effective paths by default; --historical adds historical-only paths rather than selecting only removed paths. Show path, current/historical-only presence, and available explicitness. Do not equate non-explicit values with application defaults or historical-only metadata with explicitness false.

Use --under POINTER to narrow listing to a subtree and --explicit=true|false to select current explicitness. Omitting explicitness filtering includes both states and, when requested, historical-only entries; historical-only entries do not match either current explicitness value. Apply subtree filtering to parsed paths, not textual prefixes. These filters and --historical belong to listing mode; --path continues to select detailed explanation, including its available metadata and history.

Keep values and change history out of the compact listing. Include useful field metadata in detailed explanation without repeating existing evidence. If a provider cannot supply discovery metadata, report that capability as unavailable rather than presenting an empty configuration; its existing path-specific explanation remains usable. These are sufficient starting choices for the MVP; exact field layout and mode-specific error wording can be decided in code and reviewed with concrete examples.

OD-5: Detailed comparison selection and shape

Agreed: retain the existing concise additions/changes/deletions report as the default for config diff, and add optional --details for investigating changes. The default serves human operators who need a quick overview; retaining it is a presentation choice, not a compatibility constraint.

The detailed mode should help an operator compare old and new values, distinguish absence from explicit null, and understand concealed changes even when the displayed safe snapshots look equal. Present native paths, left/right snapshots, presence, redaction, and hidden-change evidence in readable YAML.

Agreed initial layout: one entry per changed path in a scope-labeled YAML report, with before/after snapshots rather than expanded versions of the three summary categories. Display snapshot values as YAML values, preserving explicit presence so missing and null remain distinct. Show redaction and concealed-change annotations where relevant; omission of an optional annotation has a defined meaning and never relies on recognizing a marker-looking string. Prefer ordinary Go fields and serialization tags to custom omission logic. An empty comparison has an explicit empty difference list. YAML is the only initial detailed format.

Keep the projection close to native report values, using the shared reporting approach rather than extensive translation for cosmetic layout. Exact field names are implementation choices for the initial release and can evolve with beta feedback.

Keep implementation localized to flag selection and a second report writer, with focused boundary tests, help, and examples. The existing Scope.Compare contract and both native adapters already return the required difference records. Reuse that data and existing safe-snapshot decoding; no new comparison callback, additional load, or comparison algorithm is required. A shared YAML output helper may be used, but detailed comparison needs no domain-specific core API. A side-by-side terminal display is not part of this adoption. Comparison exit status follows OD-10.

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.

Agreed: add config validate --details, consistent with the optional detail mode on config diff. Retain concise validation by default, including its ordinary warning and error reporting. Detailed mode reports available native diagnostic records and source references alongside the validation result. The purpose is to help a human operator locate and investigate configuration problems; it does not introduce new validation rules. Selecting YAML alone does not implicitly enable the additional detail.

Preserve available evidence when loading fails: config validate --details reports diagnostic findings and relevant source references, and config sources reports acquired source inventory. These describe the current invocation, not a previous failed command. Keep the original failure and its supported cause identity; successfully displaying evidence must not turn failure into success. A failed load does not imply an effective configuration is available.

Build optional ckconfig evidence facets that can accompany an acquisition error. Unlike detailed comparison, the existing adapters need to carry additional structured evidence through to reporting. Use current core reporting and outcome handling; no generic cross-family diagnostics framework is required.

Agreed initial presentation: detailed validation uses text by default, with YAML available through --format yaml. Begin text output with scope and outcome, then show readable findings with their available messages, severities, codes, configuration paths, and source locations. Place useful locations near messages; YAML may use a source legend shared by multiple findings.

Use repeatable --severity and --code filters in detailed mode. Multiple values within a filter match any selected value; different filters narrow results together. Filtering never changes the validation outcome. Distinguish no native findings, no findings matching the filters, and unavailable structured evidence. Keep referenced sources needed to interpret selected findings.

Avoid presenting a finding both in the detailed report and as a duplicate ordinary warning when the records have a known relationship. Do not deduplicate by guessing from message text. Preserve unrelated messages and the terminal failure explanation. Keep this coordination within the integration rather than introducing a general diagnostics framework.

Structured results use the result stream and ordinary messages use the diagnostic stream. Preserve report-delivery failures separately from the original operation failure through existing outcome handling. Retain current aggregate stopping behavior; detailed output does not promise exhaustive validation across all scopes. Partial-evidence and cancellation presentation should use the same simple report values and existing reporting lifecycle, with exact layout refined during implementation and practical testing.

OD-7: Module release and interim workspace coordination

Agreed: complete the planned integration work together rather than splitting out a dependency-only PromptKit release. With no current consumers, an early compatibility release has no demonstrated benefit. Prepare a new ckconfig minor release for the shared API/CLI features, then update the still-unpublished ckprompt candidate to require that released version. Confirm candidate status and available versions under the release procedure before choosing versions.

Use the ignored aligned workspace during joint development. Workspace success does not establish independent ckprompt correctness with its old ckconfig requirement. Before final independent validation, pin the released ckconfig version supplying the APIs and validate both independent modules and the aligned workspace. Release ckconfig before ckprompt. Publication remains a separate action requiring authorization; this decision does not authorize publication.

OD-8: Focused configuration reports and filtering

Agreed: add config show --path POINTER and config sources --source-id ID; add subtree/explicitness filters to config explain --list and severity/code filters to config validate --details. Keep reports unfiltered by default. The purpose is to reduce noise for a human operator investigating a known part of the configuration.

Focused show emits the selected native effective YAML directly, without a snapshot wrapper containing presence/redaction/YAML fields. Use the existing explanation capability to obtain the native snapshot. An absent effective path or unknown source ID produces a clear operational failure. Explicitly present null remains a valid value; historical-only paths are not effective values. Path-selected display initially uses one scope, while whole-document --scope all remains available.

Filters change presentation, not validation outcomes. Keep source references needed to interpret the selected findings. Apply subtree filtering to parsed paths; distinguish unavailable current metadata on historical-only paths from an effective value that was not explicitly supplied.

Selected filter grammar: OD-4 records discovery filters and OD-6 records diagnostic filters. Exact report field layout and remaining edge-case messages are implementation choices for the MVP. No additional snapshot-wrapper report or aggregate path-selected display is selected for this adoption.

OD-9: Independent comparison selector bindings

Agreed: applications declare which domain selectors support right-side comparison values, with explicit metadata for their --against-* spellings. Do not generate comparison flags for every application option automatically. Omission inherits the left value and presence; an explicit right value replaces it. For repeatable selectors, the supplied right collection replaces the inherited collection rather than appending to it. This supports comparisons such as two campaigns without requiring different files or repeating every unchanged selection.

Domain parsing stays in the declared typed bindings; no generic selector language is introduced. Review the refinement of ADR 0012 and flag collision handling before implementation. Exact helper signatures and an explicit way to select an empty right-side collection remain open. An empty string element is not necessarily an empty collection; do not equate them implicitly.

OD-10: Comparison assertion outcomes

Agreed: add opt-in --check, retaining normal report delivery and ordinary diff behavior when omitted. Under assertion mode, use status 0 for equality, 3 for differences, 2 for usage errors, and 1 for operational failures. This distinguishes a successful comparison that found differences from a comparison that could not run. Ordinary diff remains successful when it finds differences.

Base the difference outcome on native records, including concealed changes, not equality of the displayed safe values. Apply existing reporting outcome rules, including preservation of a nonzero domain outcome when presentation also fails; callers can inspect the separate presentation evidence. Document and test that interaction explicitly. These are selected future behaviors, not claims about the currently implemented CLI.

OD-11: Transient configuration overrides

Agreed scope: 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.

Prefer inline assignments for ordinary one-value experiments. This is the largest remaining loader integration design item; revisit scope explicitly if the required acquisition changes prove disproportionate rather than silently dropping the agreed feature. 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 agreed 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.

A structured override file is not selected as the primary interface: it handles complex values and unusual keys well but adds file setup to ordinary one-value experiments. It remains a possible supplemental form if needed to resolve the open grammar cases. Application-specific typed flags remain available, but are not a substitute for the selected standard CLI capability. No persistent configuration mutation is authorized by this decision.