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 until the open decisions are resolved.

Purpose and ownership

Adopt released PromptKit v0.19.0 and expose useful operator tasks through standard CommandKit commands, flags, and reports. This roadmap covers CLI exposure, including 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 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, 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 and subject to the decisions at the end of this document.

Operator task	Proposed CLI	Owning module and report
Inspect what a concrete prompt request prepares	promptkit show request ID --profile … --input … --var …	ckprompt: selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from PreparedRun.
Reproduce target/provider settings without editing configuration	Applicable existing smoke override flags on validation and preview; --extra-params JSON on these and smoke operations	ckprompt: native request forwarding; preview and smoke reports show returned effective settings.
Resolve unqualified resource selections in chosen namespaces	Independent prompt/profile/backend namespace flags	ckprompt: delegate to native namespace views, retaining the distinction from catalog filters.
Find configuration paths and inspect their explicitness	config 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

Add an independently available preview capability alongside existing suite callbacks. The native adapter calls Engine.Prepare and projects its returned snapshot; a preliminary ValidateRequest call is unnecessary. Use existing typed selection, acquisition diagnostics, and invocation reporting patterns. Exact callback names and signatures follow the selected CLI design.

Preview performs applicable resource I/O and rendering but no model call. Rendered and appended messages contain application content. Upstream excludes resolved credentials from prepared settings; that does not make the whole snapshot a redacted configuration report or a transferable execution handle. Expose the upstream snapshot evidence without implying later execution uses that exact snapshot or will succeed.

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 usable; resolve override precedence and the remaining request controls under OD-2 before documenting new public behavior.

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. 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 against the released notices and source commit. Update the unpublished candidate note and affected canonical dependency/compatibility guidance. No core Go-minimum increase follows from this adoption.
3. Implement request inspection and selection. Add preview, applicable override flags, provider-parameter input, and namespace selectors. Implement public ckprompt execution-flag collections on existing core bindings and reuse them in the standard commands. 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.

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.
• Preview forwards the intended request and faithfully reports native fields. Its CLI path makes no model call and does not create/execute retained prepared handles.
• New flags preserve selected omission/empty/zero semantics, parse malformed inputs through the existing usage path, and do not leak state between runs. Numeric decoding of provider JSON matches the selected strategy in OD-2.
• 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.
• 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. 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 remain an explicit choice in OD-11. 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. OD numbers are local to this roadmap, not the retired adoption documents.

OD-1: Preview command and report presentation

Recommendation: use promptkit show request ID, with YAML as the initial report format and the complete relevant PreparedRun projection. It sits beside definition inspection while clearly requiring concrete inputs. A single native preparation supplies both validation and preview evidence. Document rendered content disclosure directly in help and CLI guidance.

Alternative: promptkit prepare ID, with text and YAML reports. This names the native action and makes interactive inspection easier, but can suggest an executable prepared handle and adds a second rendering contract. Both forms can stay entirely within CLI ownership; select vocabulary and formats before coding.

OD-2: Request controls and provider-parameter grammar

Agreed design direction: execution flags are public reusable CLI collections owned by ckprompt, available to standard and application-owned commands using existing core APIs. The remaining decisions here concern request controls and grammar, not whether application commands may reuse the collections.

Recommendation: give validation and preview the applicable execution flags already on smoke tests, and add a singleton --extra-params JSON object option to all three. Use native whole-map replacement, including native behavior for empty maps. Specify JSON number decoding deliberately so supported values reach PromptKit without accidental precision loss or new numeric guarantees. Retain the current authoritative-builder rule: the standard flags seed a request and an application builder can return its complete replacement.

Alternative: repeatable --extra-param KEY=JSON assignments. This is easier for individual shell overrides, but requires rules for duplicate keys and makes whole-map replacement less obvious. It must still construct a single native map rather than imply an upstream field-by-field merge.

Remaining request surface: recommend keeping output-contract overrides, inline-input flags, and appended-message flags as separately selectable CLI extensions after execution-flag parity. Existing file inputs and application builders continue to support preview. A viable alternative is to include a whole-output-contract file option and message/input options now, supporting more reproduction workflows at the cost of additional syntax, precedence, and reporting decisions. No general-purpose request-building API follows from either choice.

OD-3: Namespace flags and loader defaults

Recommendation: make the standard namespace selectors opt-in with explicit suite-owned namespace defaults. Compose supplied fields with those defaults, then apply one native WithNamespaces call. Loaders using this option leave default selection to that adapter. This gives omission and explicit empty values predictable meanings without trying to read private engine state. Without the option, existing scoped loaders continue as before.

Alternative: pass presence-aware namespace choices to an acquisition callback and let the application combine them with its existing loader defaults. This accommodates applications whose defaults depend on domain input, but adds consumer wiring and makes consistent behavior less automatic. Either design must account for the native API replacing all three defaults at once.

OD-4: Configuration path and metadata presentation

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.