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

Shared report output, PromptKit v0.19.0 adoption, and ConfigKit operator CLI

Status: agreed implementation roadmap; implementation has not started. The numbered decisions and final review clarifications are settled. Exact API signatures and report layouts remain implementation choices; practical beta feedback will guide presentation refinements.

Reading guide: the core prerequisite sections own shared mechanics; OD-1 through OD-11 own integration behavior. The overview links to those decisions, and the completion checklist identifies verification boundaries without redefining policy.

Ownership principles

Applications and integration handlers choose the operation and report content; CommandKit core supplies the shared CLI mechanics. Integrated libraries retain ownership of their domain behavior.

Area	CommandKit Owns	CommandKit Does Not Own
CLI output — core	Format selection, serialization, template execution, and output delivery	Choosing report content or detail level; authoring application-specific text templates
PromptKit/ConfigKit integrations	Standard commands, flags, and report content that expose useful operator tasks through upstream public APIs	Helpers or convenience interfaces for application-internal use of upstream APIs
CLI inputs	CLI syntax, parsing, typed bindings, presence tracking, and usage diagnostics	Application business rules or upstream domain-validation semantics
Upstream behavior	Selecting and invoking supported capabilities, adapting their results, and preserving their meaning	Reimplementing upstream configuration resolution, prompt preparation, validation, or other domain algorithms
Outcomes and errors — core	Carrying and presenting selected outcomes; handling CommandKit's own parsing, rendering, and delivery failures	Deciding application recovery policy or terminating the process
Application lifecycle	Command dispatch and invocation reporting lifecycle	Application startup, engine construction, credential provisioning, signal handling, or long-lived application state

These agreed principles are recorded here for eventual incorporation into architecture.md.

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, with shared core reporting and CLI input capabilities as prerequisites to the downstream work. Core standardizes report format selection, representation, rendering, and delivery for core commands, integrations, and application-owned commands. Applications and integrations continue to choose report content. This 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 records planned work, 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	Shared report output, public CLI JSON parsing, and ordered typed input composition. Text/YAML/JSON land together. Collections and aliases retain existing declaration APIs.
ckconfig	ConfigKit v1.1.0; Go 1.27.0; core v0.3.0	Adopt the new core reporting API, shared CLI inspection extensions, and an appropriate module release.
ckprompt	PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0	Adopt the new core reporting API, 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

First establish the shared core report output capability. The integration work below uses that public API instead of adding independent format-selection and encoding machinery in each module. The core input prerequisites provide shared CLI JSON parsing and the required cross-flag input ordering.

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. The decisions at the end of this document own exact syntax and behavior; these examples summarize operator tasks.

Operator task	CLI examples	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. OD-11 selects simple assignment syntax and normal load-time forwarding; paths containing = are unsupported by these flags. Comparison overrides follow OD-9's independent-side model: --set affects only the left side and --against-set only the right.

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

OD-1 owns prepared preview; OD-2 owns reusable flag collections, aliases, input forms, and precedence. Expose preview as an independent capability alongside existing suite callbacks. Call Engine.Prepare once and project its snapshot; a preliminary ValidateRequest call is unnecessary. Upstream excludes resolved credentials from prepared settings, but rendered application content is not a redacted configuration report.

Build collections using CommandSpec[I].Flags, typed constructors, and Supplied[T]. Existing CaptureFlags and FlagValues.ApplyTo serve ordinary deferred application. Collections and alias generation need no new abstraction; cross-flag input ordering and shared JSON parsing use the additional core input prerequisites. Applications retain their input types, request construction, acquisition, and execution. Keep execution-target overrides distinct from transient retries: ordinary requests and smoke diagnostics have different upstream retry defaults.

Namespace selection

OD-3 owns the opt-in namespace composition, applicability table, and profile-identity clarification. Implement one native view update using declared defaults and supplied fields. Verify the selected flags against actual upstream operations; captured references and catalog filters retain their upstream meanings.

Shared configuration capabilities

Extend ckconfig through optional capabilities, exposed by FromConfigKit and ckprompt.ConfigScope. Providers need not implement every inspection mode; help and availability must reflect their supplied capabilities.

• Metadata discovery uses Metadata.HistoricalPaths, Lookup, IsExplicit, and History. It covers observed paths, not every possible schema field. Preserve history after absent lookup and native list-index paths. OD-4 owns the operator presentation and filters.
• Detailed diff reuses Scope.Compare and native Difference records under OD-5. Native sequence changes remain atomic; no element-matching algorithm or reloadable patch format is added.
• Failed-load evidence uses LoadError.Sources() and Diagnostics() alongside the original error. Acquisition must distinguish unavailable evidence from an available empty inventory. A failed load establishes no effective configuration or metadata capability. OD-6 owns diagnostic presentation, aggregation, and failure delivery; this work requires adapter changes, not only a renderer.

Additional ConfigKit operator workflows

OD-8 owns focused values and source selection. Obtain path values from native Explain(path) and whole configuration values from safe WriteEffective output, converting both through core. Never reconstruct inspection from mutable Result.Config or source files. Select source IDs from acquired inventory; native Source(id) is a convenience, not another provider requirement. Source IDs are local to one load.

OD-9 replaces the current comparison inheritance while retaining the two-input/provider lifecycle. Domain defaults and caching remain application-owned. OD-10 uses native differences for assertions; source/history differences alone and changed credential bytes behind unchanged references are not necessarily effective-value differences.

OD-11 owns temporary override syntax and forwarding. ConfigKit recursively overlays mapping overrides and replaces sequences, unlike PromptKit's complete provider-map replacement. Shared numeric parsing must not erase that distinction. Source-load errors remain errors even if a supplied override would replace the affected value.

Shared core report output prerequisite

Agreed scope: add a first-class public reporting capability to CommandKit core before implementing the downstream integration additions. An application or integration gathers report data and hands it to core; core selects the default or operator-requested format, renders the report, and delivers it. Centralize formatting and translation machinery to the greatest practical extent so commands share output conventions and avoid repeated infrastructure. Core remains independent of ConfigKit and PromptKit types and domain semantics.

Deliver plain text, YAML, and JSON together in the same core feature release, implemented in separate reviewable units as useful. Exercise all three before downstream integration additions depend on the API, so representation decisions are validated across formats. XML is removed from current consideration. Markdown is not selected for this adoption. New core formats must work with existing commands without handler refactoring or per-command encoder registration. This supersedes both the optional YAML-helper proposal and earlier YAML-only report restrictions. Keep implementation proportionate; exact public names, signatures, and internal representation remain design work.

Agreed universal and automatic format selection

Core owns the universal --format flag, its available options, help, input validation, and renderer selection. Commands do not maintain format allowlists; adding a renderer and format option in core makes it available to existing commands automatically. An unknown format is a usage error before acquisition or other command work. Use one format flag rather than separate format flags.

The initial public API does not offer command-specific format defaults. Resolve the effective format in this order:

1. The operator's explicit --format choice.
2. Text when the report handoff includes a text template.
3. Core's automatic selection from the shared report representation below.

Report content, without a text template	Automatic format
String	Text
Nonempty sequence containing only strings	Text, one item per line
Number or boolean	Text
Mapping, including an empty mapping	YAML
Sequence of mappings, nested sequences, or mixed values	YAML
Empty sequence or null	YAML, keeping the empty result visible

Inspect the logical report representation after the selected serialization and adaptation rules, not just the original Go type. A struct normally represents a mapping, while a custom serializer may represent that value as a string. Use the outer shape; do not search inside mappings for a presumed primary field. Select once for the complete logical report, not independently for each item in a result collection.

Omitting --format means "CommandKit chooses," not a fixed text default. The choice can vary with the result: a populated string list yields text, while an empty list yields YAML []. Explicit selection provides a predictable format when needed, including config show --format yaml for a configuration document even when the selected value is a string. Core can deliberately evolve its automatic policy in a future release.

This supersedes optional command defaults and the proposed per-command default inventory, including explicit YAML defaults for config show, config diff, and prepared-request preview. Applications choose report content and optional text templates; core selects the format. Reconsider command overrides only for a concrete demonstrated requirement.

For config show, hand off the selected logical configuration value, not a string containing serialized YAML or a snapshot metadata wrapper. With no text template, a configuration mapping naturally selects YAML and a selected string value selects text. Native snapshot adaptation must preserve that distinction.

Agreed format-independent reporting operation

The application or integration decides what content to report, including which information appears normally and what is added by --details. Core does not select domain facts, add detail when a format changes, or infer a summary. Retain the agreed --details spelling for the standard commands.

Provide one public operation through the invocation Reporter that accepts the selected report data and an optional plain-text template, without requiring a handler to switch on the selected format or configure an encoder. Core renders both concise and detailed report values. invocation.Reporter().Report(report) illustrates the intended operation only; it is not a selected signature or an existing API.

Provide a corresponding writer-based API for rendering outside an invocation. Both entry points share the rendering implementation. Invocation reporting uses the existing Reporter lifecycle for visibility, destinations, delivery, and presentation failures, preserving domain outcomes and causes. This extends the existing reporting facility rather than creating a second delivery lifecycle.

Agreed shared representation rules

Agreed: use Go's standard encoding/json serialization conventions to interpret ordinary Go report values for core serialization. Prepare one logical representation for YAML/JSON output and for automatic selection and text rendering when no text template is used. Application-supplied text templates instead receive the original Go value, as specified below. JSON conventions do not select JSON as the default output format or expose core's intermediate data representation as a public template contract.

Reuse the standard library's field selection, JSON tags, omission rules, nested value handling, and supported custom JSON serialization. Avoid a new CommandKit tag convention or reflection-based serialization engine. Suitable upstream values can reuse their existing JSON contract; thin projections remain useful when the desired operator content differs from that representation.

• One serialized field interpretation. JSON field tags and custom serialization govern ordinary values in core-serialized outputs. Conflicting YAML tags or YAML-specific serialization do not change that interpretation. For example, a field tagged json:"retry_count" yaml:"retries" appears as retry_count in both JSON and YAML. Do not independently serialize the original Go value with each encoder.
• Explicit omission. Honor omissions selected by the JSON contract. Core does not additionally hide zero, false, empty, or null values for brevity. Preserve the remaining distinctions among absent, null, false, zero, and empty values through conversion and rendering.
• Preserved numeric values. Avoid precision loss in intermediate conversion, including accidental rounding of large integers through floating point. This preserves the serialized value rather than promising precision beyond the supplied value and its serialization contract.
• Observable failures. When serialization is used, values rejected by its contract produce presentation errors through the existing reporting lifecycle. Do not silently drop unsupported data or substitute arbitrary string representations. Templated text executes against the original value without requiring a JSON round trip.

Agreed configuration input conversion: decode upstream safe inspection YAML into ordinary Go report values, then use the same shared representation and renderers as other reports. Core owns the explicit YAML-input conversion helper; ordinary report strings are never heuristically parsed as YAML. This supersedes the proposed separate native-YAML preservation path.

Preserve meaningful data: strings versus numbers and booleans, null versus empty collections, absent versus present false/zero/null, numeric precision, sequence order, and upstream redaction. Retain presence and other inspection metadata where the selected report calls for it. Mapping order, comments, whitespace, quoting, block/flow style, and exact numeric spelling are not preservation requirements. Unsupported conversion must remain observable rather than silently changing meaning. ConfigKit v1.1.0's safe inspection YAML already represents a restricted, JSON-like value model, making this conversion proportionate.

Obtain those values from upstream safe inspection output, not application runtime configuration structs: the latter may lose the captured snapshot, field inclusion, disclosure rules, or inspection evidence. This is an output conversion, not a replacement for upstream configuration loading or validation. No lossless YAML document model or second rendering pipeline is needed.

When implementation lands, update the current display contract to replace native-writer and mapping-order requirements. The aggregate presentation decision below also replaces separate-document framing. These presentation changes follow the ownership boundary in ADR 0006; they do not require a separate successor ADR. The alpha consolidation retired the former detailed report records without changing current behavior.

This approach reduces new machinery by reusing standard serialization and centralizing the remaining conversion and rendering work. Exact internal representation and adapter APIs remain implementation design tasks; a large public document model is not selected. Validate representative reports before assuming that an upstream type can be handed off without adaptation.

Agreed plain-text rendering

Agreed template boundary: applications and integrations own the report value and optional text template. Core prepares and executes templates using Go's built-in text/template, passing the original Go value supplied in the report handoff. Templates use Go field names, types, and standard template behavior, not JSON field names or CommandKit's intermediate representation. For example, a Go field PromptID tagged json:"prompt_id" is accessed as .PromptID.

JSON tags and custom JSON serialization govern structured rendering, not the template's field access. An exported field tagged json:"-" remains accessible to the application's template, and custom JSON serialization does not replace the template input. The application owns that text content choice. Core retains ownership of execution, shared helpers, delivery, and presentation failures. Prefer reusable templates prepared during setup. Exact preparation and handoff signatures remain implementation choices; begin with standard template functions and add shared helpers only for concrete report needs.

When text is selected and a template is supplied, execute it as supplied and deliver its output without applying a second formatting pass. Template syntax or execution errors are errors, not a reason to fall back to another renderer. Use standard text/template semantics rather than introducing a new template language. A template selects text automatically only when the operator omits --format; explicit YAML or JSON takes precedence and does not execute it.

Agreed text behavior without a template: use core's logical report representation to select the following rendering behavior:

• Print strings directly, nonempty sequences containing only strings one item per line, and numbers or booleans as their values.
• For mappings, nested or mixed collections, empty collections, and null, reuse the shared YAML renderer. Empty sequences use this rule even when their Go element type is string, retaining the visible [] result.

Automatic selection already chooses YAML for the second group. The additional case is explicit --format text with structured data and no template, such as config show --format text. Text and YAML intentionally coincide in that case. This retains universal format support without a separate hierarchical text renderer or pretty-printer. It supersedes the proposed generic text outline. Applications do not supply separate YAML/JSON writers, and a failing template never enters this no-template path.

Agreed aggregate configuration presentation

Agreed: config show --scope all produces one mapping keyed by the unique scope identifiers. Each value is that scope's safe effective configuration:

app:
  server:
    port: 8080
promptkit:
  default_profile: standard

The example illustrates the report shape. Scope names sit outside each configuration's namespace; no scope or config metadata field is inserted into the configuration. Keep the scope-keyed mapping even when only one scope is registered. Single-scope display continues to return the configuration value directly, without a scope wrapper.

ckconfig collects the safe values and hands the complete ordinary Go mapping to core once. Core renders it using the shared machinery: automatic selection chooses YAML, explicit JSON renders the same mapping, and explicit text without a template uses the YAML fallback. No separate-document output or special core multi-result rendering API is needed. Applications and integrations choose how to group other reports using ordinary report values.

Scope order has no semantic significance or output-order guarantee in this aggregate mapping. Retain the existing availability checks and acquisition behavior: acquire all selected views and complete provider-required validation before report output begins; a failure prevents the combined display. The new shape does not introduce partial-success output.

When implementation lands, update the CLI display contract and affected tests for this aggregate shape. Scope discovery and acquisition ordering are unchanged. The capability model in ADR 0003 does not prescribe report framing or mapping order.

Remaining core reporting implementation details

Exact public signatures, reusable template preparation and helper functions, flag integration/collision handling, and replacement of existing format plumbing are implementation design tasks. The decisions above do not reopen content selection, JSON conventions for core serialization, original Go values for text templates, no-template text rendering, universal formats, automatic selection, safe YAML input conversion, aggregate configuration presentation, or joint format delivery. Report serialization is separate from the agreed CLI JSON number policy in OD-2, also adopted for configuration overrides in OD-11.

Shared core CLI input prerequisites

These two narrow capabilities land with the core reporting prerequisite. They support the selected integration behavior without adding a collection framework.

Public CLI JSON parsing boundary

Add a small public CLI JSON parsing entry point to core. It parses one JSON value using the OD-2 numeric policy and returns ordinary Go values. Integrations enforce their flag's outer shape: provider parameters require an object; configuration assignments accept a JSON value after their pointer prefix. Keep numeric conversion and its policy comments in one private helper behind that entry point.

The separate module paths go.maximumdirect.net/commandkit, go.maximumdirect.net/ckconfig, and go.maximumdirect.net/ckprompt cannot share core's private internal packages. The public CLI parser is the deliberate cross-module boundary; no public general-purpose numeric conversion API or separately versioned numeric package is introduced. It must work in independently built modules, not only in the local workspace. Exact naming is implementation work.

Ordered typed input composition

Add a small typed binding-composition capability preserving occurrence order across participating flags. Current RepeatFlag and FlagValues.ApplyTo group values by binding, which cannot establish OD-2's text/file winner by command-line order. Exercise alternating text/file flags and their aliases before finalizing the core API. Keep parsing, presence, conversion errors, and invocation isolation in core; integrations choose how ordered typed values form their request.

Do not expose Cobra/pflag structures or reparse raw arguments in ckprompt. Ordinary flag collections and scoped alias declarations keep their existing APIs. This prerequisite adds only the ordering support those declarations lack.

Initial report implementation approach

Use ordinary report structs/maps, standard JSON interpretation, the existing go.yaml.in/yaml/v4 encoder, and standard text/template. Share rendering across the invocation and writer APIs. Start with built-in template functionality; add helpers only for demonstrated report needs. No new output module, custom serialization engine, public document model, or per-format report tree is needed.

Prefer native report values or thin projections. Migrate YAML-only tags to the agreed JSON contract where needed. Small path, snapshot, location, and duration projections serve report meaning; cosmetic field rearrangement does not justify mirroring entire upstream object graphs. Render inspection values, not engines, mutable runtime configurations, or credential storage. Preserve selected presence/redaction distinctions and use the explicit YAML input conversion.

Output migration inventory

Core's universal --format controls report submissions. All migrated reports accept every core format; handlers retain no format allowlists. Existing raw output remains an explicit delivery path, not data that core guesses how to parse or translate. Apply the existing visibility and failure lifecycle to both.

Output path	Migration and format boundary
Core version report	Hand off version data and its ordinary text template to the shared API.
config scopes, show, sources, explain, and diff	Migrate their report projections; remove local format selection and encoders. OD-4, OD-5, OD-8, and the aggregate-show decision own content.
config validate, including --scope all and --details	Submit one report for reached scopes, including failure evidence, under OD-6.
Prompt/profile inspection, requirements show/validate, catalogs, and prepared preview	Use shared report rendering and suitable thin projections or text templates.
Single smoke tests and promptkit test all	Preserve native evidence and the aggregate test list in one report submission, including partial results and errors.
Maintained application-owned command example	Demonstrate report handoff, optional template, and universal formats without a local format switch.
Help and usage	Keep the existing help/usage text path; the report format flag does not serialize help text.
Warnings, progress, deferred diagnostics, and terminal failures	Keep existing diagnostic presentation and destinations; report format does not change diagnostic content or channels.
Shell-completion scripts/protocol output and caller-selected raw writes	Preserve raw output required by the receiving shell or caller; do not wrap or encode it as a report.

Audit each listed path during migration and remove obsolete format bindings and format-specific helpers. Verify unknown format handling before domain work and collision handling for the core-owned flag. Report aggregation belongs to each integration; core does not gain a generic streaming-document framework. Beta feedback should guide exact layouts; avoid tests that freeze incidental spacing or field order.

Work sequence

1. Finalize the core handoffs. Use the accepted flags, report content, aggregate presentation, and automatic format policy as the MVP target. Specify the report/writer APIs, CLI JSON parsing boundary, ordered typed input composition, and internal conversion under the agreed representation contract. Design the acquisition/binding wiring and flag collision handling; use concrete examples to review report details during implementation rather than reopening accepted scope.
2. Implement the core prerequisites. Deliver the agreed automatic format policy, universal --format selection, format-independent Reporter operation, writer-based API, and shared representation/encoding machinery. Deliver YAML encoding, text printing/templates, JSON encoding, CLI JSON parsing, and ordered typed input support in the core feature release. Exercise the public API with core reporting and an application-owned command example, and consolidate suitable existing integration reports onto it. Cover the selected contracts and update their canonical documentation with the implementation. Complete this prerequisite before building the downstream additions; use the aligned workspace until the core release is available under OD-7.
3. 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.
4. 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 using core bindings and the new ordered input capability, then 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. Render suitable new reports through the shared core API.
5. 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. Use the shared core API under the initial report implementation approach. Keep boundary coverage with each change.
6. Update operator and consumer documentation. The CLI reference owns syntax, report schemas, availability, and outcomes; GoDoc owns callback and value contracts. Keep architectural ownership references aligned, and replace the testing policy's old native-YAML/document-order guidance when the new report behavior lands. 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.
7. Align module dependencies and validate. Prepare the core release needed by both integrations and the ckconfig release needed by ckprompt. Align requirements/checksums and complete the validation below. OD-7 addresses interim workspace development and dependency order. 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 core reporting and 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.

The linked sections own behavior; these checks cover consequential boundaries rather than prescribing one test per line or exact cosmetic snapshots.

• Public report/writer APIs, the CLI JSON parser, and ordered typed input composition are documented. Maintained consumers exercise applicable APIs, and both integrations build independently. Core has no integration dependency.
• Universal format selection follows the agreed precedence and logical shapes. Cover explicit choices, templates, scalars, empty/nonempty collections, null, invalid formats before acquisition, flag collisions, and invocation isolation. New formats require no handler changes or local allowlists.
• JSON interpretation and explicit safe-YAML conversion preserve selected field omissions, numeric values, type/presence/null/empty distinctions, sequence order, and redaction. Unsupported serialization/conversion remains observable. Ordinary strings are not implicitly parsed as YAML; mapping order is not a test requirement. Do not substitute runtime configuration for inspection snapshots.
• Templates receive original Go values and standard template behavior. Explicit YAML/JSON does not execute a template; errors never trigger fallback. Untemplated text follows the selected scalar/string-list or YAML rules.
• Invocation and writer APIs share rendering; quiet mode, domain outcomes, cause identity, cancellation, and presentation failures retain their agreed lifecycle. Changing format does not change selected content or detail level.
• Every path in the migration inventory is reviewed. Remove obsolete per-command format plumbing and duplicate encoders; preserve explicit raw output, help, and diagnostic boundaries.
• config show --scope all submits the agreed scope-keyed mapping, including a one-scope aggregate. Single-scope output remains unwrapped. Cover safe values, fields named scope/config, and failure before combined display.
• Dependency versions/checksums, attribution, and candidate notes match the selected releases. Document the three upstream compatibility changes and corrected credential wording, retaining applicable v0.18.0 migration guidance.
• Authentication response-limit evidence and smoke preparation errors retain native unknown facts, supported causes, and outcomes, including no-report cases. Smoke aggregation preserves ordered results and partial failure/cancellation evidence in one report. Default tests need no live credentials or model calls.
• OD-1 preview forwards the request, calls preparation once, and projects native evidence without a model call or retained execution handle. Help explains the prompt-ID argument, resource I/O, and rendered-content disclosure.
• OD-2 collections work in standard and application-owned commands with their own typed inputs. Preserve selected subsets, omission/empty/zero values, upstream retry defaults, authoritative builders, and native map replacement.
• CLI JSON parsing follows OD-2 for provider objects and configuration values. Cover nested values, integer boundaries, decimal/exponent forms, range errors, and ordinary float approximation. The private helper documents the policy and its limits; no arbitrary-precision fallback or public numeric framework appears.
• Canonical flags and scoped aliases follow OD-2; generated aliases cover enabled/applicable bindings, preserve presence, and do not claim unrelated application spellings. Canonical-only and convenient installation both work.
• Ordered composition selects the last text/file occurrence for each input name, including mixed aliases, while retaining literal empty text and file references. Cover reordered/interleaved flags, conversion failures, and fresh invocations. No prompt-input flags are added to smoke tests.
• OD-3 namespace composition and applicability match the native boundary. Cover defaults, explicit clearing, qualified IDs, and preservation of unrelated defaults/catalog filters. Requirements help explains profile identity; cover prompt-default fallback and short explicit profile selection without rewriting configured references. Custom scoped loaders remain usable without the option.
• The six-command configuration suite and optional provider capabilities match installed help/completion metadata. Existing providers remain usable; help, version, and capability discovery never trigger acquisition.
• OD-4 explanation modes, filters, and bare-help behavior distinguish explicit root selection, current/historical-only paths, and unavailable metadata. Preserve native paths/history; do not assert upstream resolution algorithms.
• OD-5 concise/detailed diff reuse the same native records and loads. Cover additions/deletions, missing versus null, redaction/hidden changes, empty results, atomic sequence changes, and delivery failure through the shared renderers.
• OD-6 validation and failed-load source evidence preserve failure and unavailable-versus-empty distinctions. Filters and known duplicate-message coordination do not mask outcomes. Aggregate validation submits one document with reached-scope evidence after stopping on acquisition failure/cancellation; no unvisited scope is reported valid. Test the changed delivery timing and separate operation/presentation failures without promising writer rollback.
• OD-8 focused values and source selection respect capability availability, one-scope path selection, absent versus null, unknown IDs, and acquisition failure. Filters retain source references without changing validation outcomes.
• OD-9 comparisons cover left-only, right-only, both/neither, and partially specified sides, including repeated values and supplied state. Each side starts independently; command-wide controls and the shared-state lifecycle remain shared. Explicit-empty application selectors stay application-defined.
• OD-10 assertion outcomes distinguish equality, changes, usage, and failures; concealed changes count. Ordinary diff behavior and nonzero domain outcomes survive presentation failure according to the reporting contract.
• OD-11 parses only the selected assignment syntax, forwards explicit values and safe labels to the correct side during loading, and preserves upstream errors/provenance. Help documents unsupported = paths. No alternate input, deduplication, conflict/precedence policy, or altered-value retry is added.
• Maintained simple/composed consumers demonstrate the new CLI tasks and failure workflow with deterministic fixtures. Code remains proportionate: thin projections, one shared rendering implementation, and focused tests.
• Update CLI/API contracts, release notes, and examples with the implementation, including report framing, independent comparison selections, and validation delivery timing. Incorporate the ownership principles into architecture.md and replace obsolete native-YAML/document-order guidance in testing policy. The consolidated ADRs own architectural rationale; these presentation and selector changes need no separate successor records. Current documentation must match the landed scope.
• Final independent-module and aligned-workspace suites pass with dependency identities recorded. Deferred features remain outside this adoption.

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, and unrelated deferred proposals are not added by this roadmap. The shared core API targets text, YAML, and JSON, with automatic availability of newly added core formats. XML is removed from current consideration; Markdown is not selected for this adoption. The three initial formats land together in the core feature release. 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

All numbered decisions are resolved for this adoption and retain their numbers for reference. OD numbers are local to this roadmap, not the retired adoption documents. The core prerequisite sections above own shared reporting and input mechanics. Exact API signatures, typed binding composition, loader wiring, flag collision handling, and report layouts remain implementation choices, not unresolved scope.

OD-1: Preview command and report presentation

Agreed: use promptkit show prepared PROMPT_ID with the complete relevant PreparedRun projection. The structured mapping, without a dedicated text template, selects YAML through core's automatic policy. Universal format choices and automatic selection supersede both the earlier YAML-only restriction and the command-specific default proposal. 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. Core's YAML renderer also supplies explicit --format text output without requiring a dedicated preview template; a specialized template is not required for initial delivery.

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. Collections and aliases use existing declarations; JSON parsing and cross-flag ordering use the core input prerequisites. 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. The single-object form is selected over repeated key assignments.

Agreed CLI JSON number policy: pass ordinary Go numeric values to PromptKit and to ConfigKit for the configuration overrides selected in OD-11. Classify numbers by their written JSON syntax, not by whether their mathematical value could be an integer:

• Integer syntax (no decimal point or exponent) becomes int64. Nonnegative values above its range become uint64 when representable. Reject integers outside those ranges with a clear input error; do not fall back to floating point.
• Decimal or exponent syntax becomes float64: 42.0 and 1e3 remain floating point even though their mathematical values are whole numbers. Accept ordinary floating-point approximation; exact decimal representation is not required. Report numeric range errors through the existing input-error path.
• Apply the same rules recursively inside JSON objects and arrays, preserving other JSON value types. Decode with the standard library's UseNumber to avoid premature floating-point conversion, then convert the temporary json.Number values before handing parsed values to either upstream library.

Keep this in one small, centralized internal helper dedicated to CLI JSON input. Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose number conversion package, public numeric conversion API, or extensible numeric framework is selected. CommandKit is a Go library for Go applications and deliberately accepts the precision and range of these Go types. It does not compensate for their limits with alternate numeric representations.

Required implementation comments: document the syntax-based type selection, the int64/uint64/float64 choices, accepted floating-point approximation, range-error behavior, and the rationale for this narrow boundary beside the helper. The comments must make clear that ordinary Go numeric limits are an intentional policy, not a missing feature to work around later.

This policy governs parsed CLI provider parameters and configuration override values, not application-supplied runtime values or core report serialization. The public CLI parsing boundary shares this policy across modules while retaining private numeric conversion. Reusing number conversion does not unify the libraries' different override semantics or introduce a general-purpose conversion facility.

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; alias assembly requires no core upgrade. 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. Use the core ordered typed input composition prerequisite; independent flag binding alone does not supply this behavior.

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

Agreed applicability: install only namespace selectors used by the operation when the application enables the standard namespace option.

Operation	Resource-resolution namespace selectors
promptkit show prompt	Prompt
promptkit show profile	Profile
promptkit requirements show	Prompt and profile
promptkit requirements validate	Prompt, profile, and backend
promptkit show prepared	Prompt, profile, and backend
promptkit test KIND, including all	Prompt, profile, and backend
Resource catalogs	None; retain existing namespace filters
Configuration inspection	None; configuration inspection remains global within the selected configuration scope

Verify this table against the native calls during implementation. Do not install a selector for symmetry when an operation cannot use it. Exact public helper signatures remain implementation choices.

Agreed requirements-inspection behavior: retain optional profile selection and the profile namespace selector. In released PromptKit v0.19.0, requirements inspection selects and verifies a profile identity, using the explicit profile or the prompt's default, and includes that identity in the report. It fails when neither supplies a profile or the selected profile does not exist. The profile need not be execution-ready or have working credentials.

The selected profile does not change the discovered prompt inputs or variables; analysis uses the captured prompt templates, supplied variables, and session context. Help must explain that profile selection establishes the reported identity, not a different set of prompt requirements. The profile namespace qualifies explicitly supplied short profile IDs; it does not rewrite the prompt's configured default reference. Preserve this released upstream behavior without adding a CommandKit workaround for profile-independent requirements inspection.

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: supply a compact text discovery template, which core selects automatically when no format is requested. Explicit alternatives use core's universal --format. Operate on 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. Both concise and detailed comparison hand off structured mappings without a text template; core's automatic policy selects YAML. Universal format choices supersede the earlier YAML-only detailed restriction. The same selected comparison evidence is handed to core in every format; explicit text without a template reuses core's YAML renderer.

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 detail selection and a report projection, 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. Use the shared core report output capability; 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. Changing the output format 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: supply a detailed validation text template, which core selects automatically unless the operator requests another format. The template begins with scope and outcome, then shows 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.

Agreed aggregate delivery: for config validate --scope all, collect results for the scopes reached and submit one report after acquisition completes or stops. Stop at the first acquisition failure or cancellation; retain completed-scope results and available evidence from the failing scope. Do not claim unvisited scopes were validated. Apply the same aggregation to concise and detailed modes, using one ordinary report value and the shared renderers, including one JSON document.

This deliberately changes delivery timing: scope results are no longer written one at a time during acquisition. Output failures are observed after acquisition has stopped and cannot prevent already-completed loads. Preserve the original operation failure and separate presentation failure under the existing outcome rules. This replaces the old output-failure stopping behavior; it does not add exhaustive validation, whole-invocation buffering, or writer rollback. Diagnostics retain their existing lifecycle. Update the canonical validation contract and its focused failure tests when this lands.

OD-7: Module release and interim workspace coordination

Agreed: complete the core reporting/input prerequisites and 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 the core release supplying those APIs, then a new ckconfig minor release for the shared API/CLI features, and update the still-unpublished ckprompt candidate. Both integrations must require a core version supplying the new API, and ckprompt must require the ckconfig version supplying the shared work. 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 integration correctness with old core or ckconfig requirements. Before final independent validation, pin released dependency versions supplying the APIs and validate all three independent modules and the aligned workspace. Dependency release order is core, ckconfig, then 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.

config show hands off the selected logical configuration value without a text template. Core selects from its shape: a mapping yields YAML, while a selected string yields text. Explicit --format yaml renders the safe effective value as YAML, without a snapshot wrapper containing presence/redaction/YAML fields or a promise to preserve upstream formatting or mapping order. All formats render the selected value through the shared representation. 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 uses the agreed scope-keyed mapping.

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 comparison model: initialize the left and right sides independently from the configuration the application ordinarily loads without CLI configuration selections or overrides. Ordinary loading retains application discovery, files, defaults, environment handling, and resolution; it does not mean an empty or defaults-only configuration.

Apply each side's explicitly supplied values only to that side:

• --config, --overlay, application configuration selectors, and --set affect the left side.
• Their declared --against-* counterparts affect the right side.
• Every omitted field retains that side's ordinary application default and unsupplied state. Never copy the opposite side's value or supplied state, even when other fields on the right are explicitly supplied.
• Repeatable selectors follow their declared typed binding behavior on their own side. Left-side elements are never copied into the right collection.
• Command-wide controls such as --scope, --format, --details, and --check govern the comparison as a whole and remain outside this separation.

Invocation after app config diff	Left selection	Right selection
--config candidate.yml	candidate.yml	Ordinary configuration
--config before.yml --against-config after.yml	before.yml	after.yml
--config base.yml --against-overlay experimental	base.yml	Ordinary configuration with the selected overlay
--config base.yml --against-config base.yml --against-overlay experimental	base.yml	base.yml with the selected overlay
--against-config candidate.yml	Ordinary configuration	candidate.yml
No side-specific flags	Ordinary configuration	Ordinary configuration

The examples retain normal application interpretation of file and overlay selectors. Explicitly selecting the same nondefault input on both sides requires supplying it on both sides. Equal selections remain allowed and do not skip acquisition or comparison.

Applications declare which domain selectors support right-side values, with explicit metadata for their --against-* spellings. Do not generate comparison flags for every application option automatically. A configuration selector without a right-side binding still affects only the left when supplied; it is not implicitly shared. Domain parsing stays in declared typed bindings; no generic selector language is introduced. Retain the two input preparations and checks, one shared invocation state, and existing provider lifecycle.

This deliberately replaces the current inheritance model, including existing config/overlay behavior and shared application selectors. Update CLI/API contracts and examples when implementation lands. The input/state ownership in ADR 0001 remains unchanged; selector policy does not need a separate successor ADR. Exact helper signatures and flag collision handling remain implementation design tasks.

Agreed collection scope: leave explicit-empty selection for application-defined repeatable selectors to application-declared bindings in this release. Omission retains that side's ordinary collection; an empty string element is not implicitly an empty collection. No additional standard collection-clearing flags, including the earlier proposed --against-clear-* forms, are selected.

Actual configuration lists supported by OD-11 can be replaced with an empty list using --set /path=[] or --against-set /path=[] on the corresponding side, subject to upstream path and schema rules. This does not necessarily express empty selection for an application selector that controls which sources load. Retain general collection-clearing support as a future candidate pending a concrete consumer need. OD-9 requires no further operator-policy decision for this adoption.

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. Supply parsed records during the normal configuration load, like any other explicitly supplied CLI overrides; the generic adapter cannot inject them into an arbitrary loader after the load has completed.

Agreed input syntax: support only POINTER=JSON, split at the first =. Paths containing = are unsupported by --set and --against-set. Document this limitation in help; do not add alternate JSON-record syntax, an escaping scheme, or an override-file option. This limits these flags rather than banning such keys elsewhere in configuration. The JSON value may itself contain =.

Agreed loading boundary: CommandKit parses supplied assignments, preserves explicit values and safe source labels, and passes the records to the appropriate loader and comparison side. ConfigKit owns path validity, duplicate/overlap handling, precedence, resolution, and validation. If the normal load returns a ConfigKit error, preserve and report it through the existing diagnostic/outcome path. CommandKit does not deduplicate records, resolve conflicts, invent a combination or precedence policy for application-owned overrides, or retry with altered values. Application loading retains its existing responsibilities. Exact loader signatures and wiring remain implementation design tasks.

Agreed numeric conversion: both assignment flags use the OD-2 numeric policy, including nested values, through core's public CLI JSON parser. ConfigKit receives ordinary Go values; the shared numeric helper and policy comments remain private.

Agreed comparison behavior: --set supplies override records only to the left side; --against-set supplies records only to the right. Each side starts from its ordinary configuration under OD-9. Omission supplies no CLI override records for that side; it never inherits records from the other side. Normal application-owned overrides are part of ordinary loading and are not erased by omitting these flags.

For example, config diff --set /workers=4 compares the left configuration with that override against the ordinary right configuration. Adding --against-set /workers=8 explicitly overrides the right configuration as well. Repeat the same --set assignments as --against-set assignments when both sides should use them. There is no shared CLI override baseline and no --against-clear-set flag is needed to undo inheritance.

Implement the selected handoff without reimplementing upstream behavior:

• Split at the first =; JSON supplies typed null, boolean, string, numeric, array, and object values, with the agreed numeric policy above.
• 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.
• Let ConfigKit enforce its released mapping-path constraints, including root/index and schema-version restrictions, without introducing a generic patch language. Empty, false, zero, and null remain intentional supplied values.
• 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.

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. OD-11 requires no further operator-policy decision for this adoption.