diff --git a/docs/adr/0006-invocation-reporting.md b/docs/adr/0006-invocation-reporting.md index daec796..109f6dc 100644 --- a/docs/adr/0006-invocation-reporting.md +++ b/docs/adr/0006-invocation-reporting.md @@ -4,7 +4,7 @@ Accepted. The structured-report formatting extension is accepted but not yet implemented; -the [adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite) +the [adoption roadmap](../roadmap/promptkit-v0.20.0.md#shared-core-report-output-prerequisite) tracks that work. ## Date diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 452932b..66eea72 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -162,7 +162,7 @@ finalization. Applications and integrations choose their report content and messages; callers choose the destinations. [ADR 0006](../adr/0006-invocation-reporting.md) records this reporting and outcome ownership model. Its accepted structured-report extension remains planned in the -[adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite). +[adoption roadmap](../roadmap/promptkit-v0.20.0.md#shared-core-report-output-prerequisite). For that shared report handoff, core owns format selection, serialization, template execution, and delivery. Applications and integrations select logical diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 0abb9bc..5286e49 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -26,27 +26,28 @@ an idea here does not select its syntax, API, priority, or delivery date. ### ckprompt release -The PromptKit v0.18.0 migration is complete. The +The PromptKit v0.18.0 adoption is complete. The [ckprompt v0.3.0 candidate](../../integrations/ckprompt/docs/releases/v0.3.0.md) remains unpublished. Publication and hosted delivery remain separate operations under the [release procedure](../release.md). The published ckprompt v0.2.0 retains its earlier dependencies; see the [consumer guide](../consumers/guide.md#module-selection) for module selection. -### PromptKit v0.19.0 adoption +### PromptKit v0.20.0 adoption -The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md) owns the agreed adoption, +The [PromptKit v0.20.0 roadmap](promptkit-v0.20.0.md) owns the agreed adoption, the shared core reporting/input prerequisites, operator CLI additions for -PromptKit and ConfigKit, recorded decisions, and completion checklist. Final -review clarifications are incorporated; implementation has not started. Use -released upstream contracts only; do not inspect or monitor unreleased work in -anticipation of adoption. +PromptKit and ConfigKit, recorded decisions, and completion checklist. It targets +a clean alpha adoption without backward-compatibility provisions or consumer +migration guidance. Implementation has not started. Use released upstream +contracts only; do not inspect or monitor unreleased work in anticipation of +adoption. ## Future capability targets ### Comparison extensions -The [working roadmap](promptkit-v0.19.0.md#additional-configkit-operator-workflows) +The [working roadmap](promptkit-v0.20.0.md#additional-configkit-operator-workflows) owns independent comparison selections (OD-9), assertion outcomes (OD-10), and optional detailed reports (OD-5). These accepted plans do not change currently implemented behavior. @@ -60,7 +61,7 @@ or public helper API is selected. ### Configuration inspection extensions -The [working roadmap](promptkit-v0.19.0.md#shared-configuration-capabilities) +The [working roadmap](promptkit-v0.20.0.md#shared-configuration-capabilities) owns metadata/path discovery (OD-4), detailed comparison (OD-5), failed-load evidence and aggregate validation (OD-6), focused inspection/filters (OD-8), and transient overrides (OD-11). The six-command suite, selected output behavior, @@ -80,12 +81,14 @@ application loading and startup. ### PromptKit inspection and selection extensions -The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md#targeted-end-state) -now owns concrete request preview, applicable request flags, namespace selection, -and the shared configuration inspection extensions. Its execution flags will be -public reusable `ckprompt` collections for standard and application-owned CLI -commands, composed through existing core bindings. -[Roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar) +The [PromptKit v0.20.0 roadmap](promptkit-v0.20.0.md#targeted-end-state) +owns native prompt/profile/backend resource inspection, concrete request preview, +applicable request flags, namespace selection, and the shared configuration +inspection extensions. The [resource inspection plan](promptkit-v0.20.0.md#resource-inspection) +includes backend inspection through the released upstream API. Execution flags +will be public reusable `ckprompt` collections for standard and application-owned +CLI commands, composed through existing core bindings. +[Roadmap OD-2](promptkit-v0.20.0.md#od-2-request-controls-and-provider-parameter-grammar) records the agreed canonical naming, scoped convenience aliases, integration installation collection, selected text/file input forms, and CLI JSON number policy. Numeric conversion uses ordinary Go types and a small internal helper @@ -96,22 +99,11 @@ Output-contract overrides and appended-message flags are deferred below. These are CLI features; general-purpose helpers for application-internal PromptKit use are outside CommandKit's ownership boundary. -[Roadmap OD-3](promptkit-v0.19.0.md#od-3-namespace-flags-and-loader-defaults) +[Roadmap OD-3](promptkit-v0.20.0.md#od-3-namespace-flags-and-loader-defaults) records the agreed namespace-selector applicability, including the limited role of profile selection in requirements inspection. That selection follows the released upstream identity requirement; it does not change prompt dependencies. -- **Focused backend inspection.** Defer a standard backend detail command - until a released PromptKit version provides a suitable public backend - inspection capability. The operator task is to inspect one backend's - endpoint, credential environment reference, concurrency and queue settings, - provider defaults, and smoke-probe configuration without running a probe. - PromptKit v0.19.0 has no dedicated backend inspection API. Do not implement - this proposal by reconstructing backend selection from captured - configuration. Review the released upstream capability before selecting - command syntax and report fields; this feature is outside the v0.19.0 - adoption scope. - - **Output-contract override flags.** Deferred from the current adoption. A possible future operator task is validating or previewing one prompt with a replacement output contract without editing its definition. PromptKit uses @@ -132,7 +124,7 @@ released upstream identity requirement; it does not change prompt dependencies. Deferring flags does not remove native appended messages from preview reports when an application builder supplies them. -[Roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar) +[Roadmap OD-2](promptkit-v0.20.0.md#od-2-request-controls-and-provider-parameter-grammar) selects inline text and explicit file input for single-prompt validation and preview. Native API availability alone does not select further CLI syntax or require a convenience API for application execution. @@ -153,11 +145,11 @@ steps. No delivery date or final API is selected here. ### Reporting extensions -The [shared core report output prerequisite](promptkit-v0.19.0.md#shared-core-report-output-prerequisite) +The [shared core report output prerequisite](promptkit-v0.20.0.md#shared-core-report-output-prerequisite) owns application-selected content, core rendering, universal/automatic format selection, JSON representation conventions, text templates, and safe YAML input conversion. Text, YAML, and JSON land together; new core formats work through the -same report API. The [migration inventory](promptkit-v0.19.0.md#output-migration-inventory) +same report API. The [output inventory](promptkit-v0.20.0.md#output-implementation-inventory) identifies report paths and preserves explicit raw/help/diagnostic boundaries. OD-6 defines one aggregate validation report and its changed delivery timing. XML is outside current consideration; Markdown and other renderers are not @@ -203,7 +195,7 @@ operator or consumer need and an appropriate ownership/behavior decision: injection, and concurrent-dispatch guarantees. Execution, serving, and session operations remain application-owned. The -[request preview proposal](promptkit-v0.19.0.md#preview-and-request-flags) +[request preview proposal](promptkit-v0.20.0.md#preview-and-request-flags) exposes native preparation and rendering as an agreed operator inspection target; implementation has not started. The [architecture policy](../policy/architecture.md#command-and-application-ownership) @@ -224,9 +216,6 @@ records are historical evidence, not performance guarantees or release gates. ## Consumer adoption -Consumer migrations remain separate from library delivery. Applications can -replace duplicated standard handlers and routing, then update their CLI docs -and subprocess consumers for intentional changes while retaining domain commands. -No migration order or claim about individual applications' adoption is recorded -here; the [consumer guide](../consumers/guide.md) and maintained examples provide -integration guidance. +CommandKit is in alpha with no consumers. No application adoption work or rollout +order is selected. The [consumer guide](../consumers/guide.md) and maintained +examples provide integration guidance for future applications. diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.20.0.md similarity index 86% rename from docs/roadmap/promptkit-v0.19.0.md rename to docs/roadmap/promptkit-v0.20.0.md index d268919..4b2ff95 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.20.0.md @@ -1,13 +1,15 @@ -# Shared report output, PromptKit v0.19.0 adoption, and ConfigKit operator CLI +# Shared report output, PromptKit v0.20.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. +numbered decisions and final review clarifications are settled. Exact helper +signatures and layouts of integration-owned report projections remain +implementation choices; native resource report fields follow upstream. +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. +Reading guide: the core prerequisite sections own shared mechanics; resource +inspection and 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 @@ -20,7 +22,7 @@ input, serialization, and presentation contracts. ## Purpose and ownership -Adopt released PromptKit v0.19.0 and expose useful operator tasks through +Adopt released PromptKit v0.20.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. @@ -31,6 +33,12 @@ 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. +`ckprompt` neutrally exposes the released upstream capabilities and their returned +evidence. CommandKit is in alpha with no consumers: implement a clean adoption +of v0.20.0, with no backward-compatibility adapters, legacy report shapes, or +consumer migration guidance. Update the final API, CLI documentation, examples, +and candidate notes to describe the selected behavior directly. + The [architecture policy](../policy/architecture.md), [optional-module decision](../adr/0004-optional-integration-modules.md), and [reporting decision](../adr/0006-invocation-reporting.md) govern implementation. @@ -40,26 +48,28 @@ behavior or permanent limits on future features. ## Baseline and released evidence -Repository baseline: `0b4e47c4206e323f7c5d5ec3f357494dd23008b2`. -The completed v0.18.0 adoption is not reopened. +Planning baseline: `e90821331874c926eb5f95216dc2bb4bcbf4a115`. The table +below distinguishes the implemented dependencies from the selected target. | 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. | +| `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.20.0, and the ckconfig version delivering the shared work. | | Candidate | [ckprompt v0.3.0](../../integrations/ckprompt/docs/releases/v0.3.0.md), recorded as unpublished | Update the unpublished candidate after checking its status during implementation. | | Local workspace | Core and both integrations, Go 1.27.0 | Validate local composition and independent modules separately. | -Use PromptKit tag `v0.19.0`, commit -`4f3212bfb6c1f37f43d50715c2cedc1d43203064`. Its Go minimum remains +Use PromptKit tag `v0.20.0`, commit +`8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf`. Its Go minimum remains 1.27.0 and its ConfigKit dependency remains v1.1.0. Reviewed sources are the -[release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/docs/releases/v0.19.0.md), -[request and report types](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/types.go), -[engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/engine.go), -[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/namespaces.go), -[configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/configuration_inspection.go), -and [smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/4f3212bfb6c1f37f43d50715c2cedc1d43203064/smoke_diagnostics.go). +[release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/releases/v0.20.0.md), +[request and report types](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/types.go), +[resource inspection reports](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/resource_inspection.go), +[configuration and execution semantics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/docs/formats.md), +[engine API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/engine.go), +[namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/namespaces.go), +[configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/configuration_inspection.go), +and [smoke API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/8ff9aa3efdc9f16b9d2729e0a29ea083eb3c3eaf/smoke_diagnostics.go). Work against released versions only; do not inspect or monitor unreleased upstream work in anticipation of another adoption. @@ -104,20 +114,24 @@ format-selection and encoding machinery in each module. The [core input prerequisites](#shared-core-cli-input-prerequisites) provide shared CLI JSON parsing and the required cross-flag input ordering. -The original adoption tasks remain included: +The adoption includes: -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. +1. Update the dependency, checksums, attribution, and unpublished candidate note + to the released v0.20.0 target. +2. Use the released resource inspection types and document the operator-facing + distinctions among resources, configuration evidence, and prepared requests. +3. Cover native resource reports/errors, authentication response-limit evidence, + and 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. +Deliver the following operator capabilities. The resource inspection section +and numbered decisions own syntax and behavior; these examples summarize tasks. | Operator task | CLI examples | Owning module and report | | --- | --- | --- | +| Inspect a captured prompt definition | `promptkit show prompt PROMPT_ID` | `ckprompt`: native `PromptInspection`, including unrendered messages and presence-aware metadata. | +| Inspect a resolved profile resource | `promptkit show profile PROFILE_ID` | `ckprompt`: native `ProfileInspection`, before backend completion and request overrides. | +| Inspect backend settings without running a probe | `promptkit show backend BACKEND_ID` | `ckprompt`: native `BackendInspection`, including configured smoke diagnostics. | | 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. | @@ -149,32 +163,92 @@ load-time forwarding; paths containing `=` are unsupported by these flags. Compa overrides follow OD-9's independent-side model: `--set` affects only the left side and `--against-set` only the right. -### Compatibility and native semantics +### Resource inspection -Document these v0.19.0 changes for consumers constructing engines and inputs: +Expose `promptkit show prompt PROMPT_ID`, `promptkit show profile PROFILE_ID`, +and `promptkit show backend BACKEND_ID` as peer resource commands. Each selects +one resource through its corresponding released `Engine.Inspect*` API and hands +the returned `PromptInspection`, `ProfileInspection`, or `BackendInspection` +directly to core. Use the full native report, without a separate summary/details +mode or a dedicated text template. The structured mapping automatically selects +YAML; explicit JSON or text uses the same core rendering rules and content. +Remove the duplicated prompt/profile report structs and per-field formatters. -- 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. +The upstream report types own the fields and their meanings: -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. +- Prompt inspection includes captured, unrendered inline or imported messages, + cache metadata, declared inputs, description/session/default-profile metadata, + output settings, and the opaque prompt hash. Referenced profiles and schemas + are not resolved by this inspection. +- Profile inspection exposes the resolved profile after composition and sibling + inheritance, before backend completion, execution defaults, or request + overrides. An omitted endpoint is not evidence that the completed request + lacks one. Use `show prepared` to see completed request settings; do not + reconstruct an effective target inside the profile command. +- Backend inspection includes its endpoint, credential environment reference, + concurrency/queue configuration, provider parameters, and configured smoke + diagnostics. These are configured settings, not live capacity occupancy, + derived probe destinations, or probe results. Actual smoke operations remain + under `promptkit test`. -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. +Preserve native omission and presence, including explicit empty strings, zero, +false, and empty collections. Do not fill absent resource fields with execution +defaults or infer provenance from nil pointers. Configuration inspection through +`config show` and `config explain` remains the source of effective configuration, +explicit null, and provenance evidence; resource reports do not replace it. + +Add an independently optional backend-inspection callback to `Suite`, following +the prompt/profile acquisition pattern, and wire it through `FromEngine`. A nil +callback omits only that command. Use the standard configuration/application +selectors and input/state/diagnostic lifecycle. Backend selection is a positional +ID; install only its applicable namespace control under OD-3, without request +execution overrides, profile selection, or a redundant backend flag. Help and +completion reflect capability availability without acquiring an engine. + +Preserve acquisition failures, cancellation, and supported native error identity, +including `ErrBackendNotFound`; do not relabel an absent backend as +`ErrInvalidRequest` or fabricate an empty successful report. Use the existing +operational-outcome and presentation-failure paths. + +Help distinguishes captured resource content from rendered request content. +Application acquisition can load sources and capture message files; the resource +inspection call itself does not prepare requests, read schemas or request inputs, +resolve credentials, or contact providers. Inspection success is not a readiness +check. Credential environment references are names, not resolved secrets, but +arbitrary prompt and provider content is not guaranteed safe for public disclosure. + +### Released upstream semantics + +Adopt PromptKit v0.20.0 semantics directly. Keep operator help focused on the +selected operation and link to upstream contracts for domain rules: + +- After configuration composition and inheritance, profile null endpoint, + credential source, and whole provider map permit backend defaults. Empty + strings explicitly clear the endpoint or credential source; an empty provider + map does not suppress backend entries. Profile-level whole-map suppression + is not an upstream operation. Nested provider nulls remain literal data. + ConfigKit's inspection still records explicit nulls and their provenance. +- `api_key_required`, when present and true, requires a usable direct or + environment credential and can coexist with an explicit profile `api_key_env`. + A required key with an absent/null profile source suppresses the backend + credential source. Inspection does not establish credential availability. +- Request provider overrides retain their native whole-map replacement behavior, + separate from configuration composition. Do not impose source-construction + restrictions on runtime request flags or reimplement upstream merging rules. +- Preparation uses self-contained schemas. Preserve native preparation failures + and their causes; resource inspection reports a schema reference without + loading or validating it. Upstream owns schema acceptance and resolution. + +The authentication response-limit reason is evidence of unknown credential +acceptance. Forward 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. + +Programmatic `PromptSource`, profile/backend source construction, custom artifact +readers, and backend sibling-inheritance helpers remain application-owned upstream +APIs. Maintained examples must use the released contracts, but this adoption adds +no CommandKit wrappers or CLI commands for those construction conveniences. ### Preview and request flags @@ -458,7 +532,9 @@ app: server: port: 8080 promptkit: - default_profile: standard + backends: + - id: local + endpoint: https://example.test/v1 ``` The example illustrates the report shape. Scope names sit outside each @@ -539,33 +615,34 @@ 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 +Prefer native report values or thin projections. Align YAML-only tags with 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 +### Output implementation inventory -Core's universal `--format` controls report submissions. All migrated reports +Core's universal `--format` controls report submissions. All report submissions 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 | +| Output path | Implementation 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 scopes`, `show`, `sources`, `explain`, and `diff` | Use shared rendering for 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. | +| Prompt/profile/backend resource inspection | Hand the native inspection results directly to core under [resource inspection](#resource-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 +Audit each listed path during implementation 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 @@ -588,14 +665,19 @@ or field order. 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 + 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.20.0.** Update `integrations/ckprompt/go.mod` and `go.sum`, then [module attribution](../../integrations/ckprompt/docs/oss/attribution.md) against the released notices and source commit. Update the unpublished - candidate note and affected canonical dependency/compatibility guidance. - No core Go-minimum increase follows from this adoption. + candidate note and canonical dependency guidance. Replace the prompt/profile + report adapters with native v0.20.0 report handoffs, including their optional + fields and captured messages. Implement the independent backend-inspection + capability, command, and `FromEngine` wiring under + [resource inspection](#resource-inspection). Keep domain semantics upstream-owned; + no compatibility layer or consumer migration documentation is part of this + work. 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 @@ -603,8 +685,9 @@ or field order. 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. + Reuse the standard suite's lifecycle and application-owned acquisition and + request-builder boundaries. 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`. @@ -621,7 +704,8 @@ or field order. 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. + execution helpers. Describe the delivered capabilities and selected behavior + directly 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 @@ -661,15 +745,25 @@ rather than prescribing one test per line or exact cosmetic snapshots. - [ ] 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](#output-migration-inventory) is +- [ ] Every path in the [output inventory](#output-implementation-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. + selected v0.20.0/ConfigKit releases. Canonical docs and examples describe the + selected contracts without legacy report/API variants or migration guidance. +- [ ] Resource commands pass native prompt/profile/backend reports to core, + preserving returned message content, field omissions, and explicit + zero/false/empty values across formats. No per-field report mirror or backend + completion is added. Help distinguishes resource inspection, preparation, + credential references, and configuration provenance. +- [ ] Backend inspection is independently optional, wired by `FromEngine`, and + uses the selected ID, applicable configuration selectors, and backend namespace. + Help/completion require no acquisition. Preserve native not-found errors, + cancellation, acquisition diagnostics, and delivery failures. Boundary tests + establish faithful forwarding and reporting, not upstream resolution rules. - [ ] 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 @@ -697,8 +791,8 @@ rather than prescribing one test per line or exact cosmetic snapshots. 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. + match installed help/completion metadata. Providers supply only enabled + capabilities; 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. @@ -751,18 +845,15 @@ GOTOOLCHAIN=local go test ./integrations/ckprompt/... Use the [development guide](../development.md) for toolchain/workspace setup and documentation checks. Reuse successful checks for unchanged content; these -adoption checks do not add permanent publication gates. The earlier disposable -dependency-only compatibility test is preliminary evidence, not completion -evidence for these features. +adoption checks do not add permanent publication gates. A dependency-only build +is insufficient evidence for the completed CLI and reporting work. ## Deferred work -Focused backend inspection remains in [future work](future.md#promptkit-inspection-and-selection-extensions) -until a released upstream API supports it. Do not reconstruct backend selection -from configuration to deliver it in this roadmap. General execution, prepared -handle lifecycle, sessions, and observer convenience APIs remain application -responsibilities. Persistent configuration editing, new live probes, dynamic -completion, and unrelated deferred proposals are not added by 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](#shared-core-report-output-prerequisite) 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 @@ -781,8 +872,9 @@ 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. +collision handling, and layouts of integration-owned report projections remain +implementation choices, not unresolved scope. Resource reports use the native +upstream fields selected under [resource inspection](#resource-inspection). ### OD-1: Preview command and report presentation @@ -794,8 +886,9 @@ 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: +The command sits beside [resource inspection](#resource-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." @@ -910,10 +1003,8 @@ 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. +core presentation. Update implementation, examples, help, and documentation +together. 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 @@ -928,7 +1019,7 @@ 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. +`--input` denotes literal text; 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 @@ -969,7 +1060,8 @@ 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. +state. Without the option, applications control namespace selection in their +loaders. Omitting a selector preserves its declared default. Supplying a namespace replaces that default for the invocation; supplying an explicitly empty value @@ -997,6 +1089,7 @@ when the application enables the standard namespace option. | --- | --- | | `promptkit show prompt` | Prompt | | `promptkit show profile` | Profile | +| `promptkit show backend` | Backend | | `promptkit requirements show` | Prompt and profile | | `promptkit requirements validate` | Prompt, profile, and backend | | `promptkit show prepared` | Prompt, profile, and backend | @@ -1009,7 +1102,7 @@ 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 +and the profile namespace selector. In released PromptKit v0.20.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 @@ -1071,8 +1164,7 @@ reviewed with concrete examples. **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. +changes. The default serves human operators who need a quick overview. The detailed mode should help an operator compare old and new values, distinguish absence from explicit null, and understand concealed changes even @@ -1174,8 +1266,7 @@ 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. +integration work together in the selected feature delivery. 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