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