Retarget adoption roadmap to PromptKit v0.20.0
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user