Plan PromptKit v0.19.0 adoption and operator CLI additions
This commit is contained in:
@@ -33,33 +33,13 @@ 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 roadmap preparation
|
||||
### PromptKit v0.19.0 adoption
|
||||
|
||||
The completed adoption used PromptKit v0.18.0 as released. PromptKit v0.19.0
|
||||
has now been released and reviewed. The working adoption scope includes the
|
||||
dependency, checksum, attribution, and unpublished candidate-note updates;
|
||||
consumer compatibility guidance and corrected credential-report wording;
|
||||
focused authentication-reason and smoke preparation-error coverage; and final
|
||||
independent-module and aligned-workspace validation.
|
||||
|
||||
The proposed additional CLI scope is agreed in principle, subject to review of
|
||||
the adoption roadmap: concrete request preview, applicable request-override
|
||||
flags, namespace selection, configuration path discovery and explicitness,
|
||||
and detailed configuration comparison. Configuration failure investigation is
|
||||
also proposed for this roadmap, combining failed-load source inventory and
|
||||
structured diagnostics under
|
||||
[configuration inspection extensions](#configuration-inspection-extensions).
|
||||
Successful evidence reporting must retain the failed configuration outcome;
|
||||
report-delivery failures remain separately observable.
|
||||
|
||||
These proposals concern standard operator commands, flags, and reports, not
|
||||
general-purpose helpers for application-internal PromptKit use. Exact CLI/API
|
||||
contracts and implementation sequencing remain for roadmap review. Focused
|
||||
backend inspection remains deferred pending released upstream support, as
|
||||
recorded under
|
||||
[PromptKit inspection and selection extensions](#promptkit-inspection-and-selection-extensions).
|
||||
Use released upstream contracts only; do not inspect or monitor unreleased
|
||||
upstream work in anticipation of future adoption.
|
||||
The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md) owns the proposed adoption,
|
||||
operator CLI additions, shared configuration inspection work, open decisions,
|
||||
and completion checklist. Scope is agreed in principle and remains subject to
|
||||
roadmap review. Implementation has not started. Use released upstream contracts
|
||||
only; do not inspect or monitor unreleased work in anticipation of adoption.
|
||||
|
||||
## Future capability targets
|
||||
|
||||
@@ -72,42 +52,16 @@ relevant ADRs.
|
||||
|
||||
### Configuration inspection extensions
|
||||
|
||||
The [completed ConfigKit v1.1.0 adoption review](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap/configkit-v1.1.0.md#selected-scope-decisions)
|
||||
retained the following work after dependency and source-report adoption.
|
||||
Metadata inspection is the recommended next functional sprint; the other
|
||||
features have no selected sequence or delivery date. These proposals do not
|
||||
establish command grammar, report schemas, or new provider requirements.
|
||||
ConfigKit's public APIs own the evidence and its semantics.
|
||||
The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md#shared-configuration-capabilities)
|
||||
now includes the shared operator tasks previously retained here: metadata/path
|
||||
discovery and explicitness, failed-load source inventory, detailed comparison,
|
||||
and structured diagnostics. Their earlier ConfigKit adoption identifiers were
|
||||
OD-3 through OD-6; the new roadmap has its own decision numbering. Implementation
|
||||
belongs in `ckconfig`, with PromptKit exposing native evidence through its
|
||||
configuration scope. CLI syntax and report contracts remain subject to review.
|
||||
|
||||
Additional unselected work:
|
||||
|
||||
- **Optional field metadata, path discovery, and history (OD-3).** Expose native
|
||||
`Metadata.Lookup`, `IsExplicit`, `HistoricalPaths`, and `History` through an
|
||||
optional provider capability. Design field and history reports together,
|
||||
keeping existing providers usable. Distinguish effective paths from removed
|
||||
historical paths: a failed `Lookup` must not suppress available `History`.
|
||||
Validate that distinction and faithful projection of returned field/change
|
||||
records without recreating upstream provenance logic. Historical enumeration
|
||||
is not an exhaustive inventory of possible schema fields. This gives the
|
||||
earlier field-origin inventory proposal a concrete, upstream-backed scope;
|
||||
command names, selectors, and report shapes remain to be designed. For
|
||||
PromptKit, design this shared optional ckconfig capability first, then wire
|
||||
`ConfigurationInspection.Metadata()` through `ckprompt.ConfigScope`. This is
|
||||
PromptKit adoption OD-3; it does not require a separate provenance model or a
|
||||
new core API.
|
||||
- **Failed-load source inventory (OD-4).** Present acquired source evidence from
|
||||
`LoadError.Sources()` while retaining the failed outcome and diagnostics.
|
||||
Design how an adapter returns its source facet on error and how result output
|
||||
precedes terminal failure presentation. Cover acquisition and report-delivery
|
||||
failures together; current diagnostic context remains available meanwhile.
|
||||
- **Detailed comparison (OD-5).** Consider an additional form projecting native
|
||||
`Difference` paths, both snapshots, presence/redaction fields, and
|
||||
`HiddenChanged`. The current comparison retains the reduced
|
||||
additions/changes/deletions report. Decide later whether a detailed form
|
||||
complements it or replaces it through a deliberate compatibility change.
|
||||
- **Structured diagnostics (OD-6).** Consider machine-readable native codes,
|
||||
paths, severities, and locations alongside CommandKit's shared reporting
|
||||
design. Define result/diagnostic channels, warning and terminal-failure
|
||||
interaction, and delivery outcomes. A ckconfig-specific report remains an
|
||||
alternative, with its cross-family alignment considered explicitly.
|
||||
- **Source-ID filtering.** Consider selecting a record already available in the
|
||||
source inventory. Native `Source(id)` lookup is a convenience; this proposal
|
||||
need not introduce another command or require a lookup method from every
|
||||
@@ -120,12 +74,11 @@ those capabilities primarily serve application loading and startup.
|
||||
|
||||
### PromptKit inspection and selection extensions
|
||||
|
||||
The [completed PromptKit adoption scope](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap/promptkit-v0.18.0.md#scope-decisions) deferred these
|
||||
capabilities beyond the v0.18.0 compatibility migration. Shared configuration
|
||||
metadata remains the recommended next functional sprint, under
|
||||
[configuration inspection extensions](#configuration-inspection-extensions).
|
||||
The OD identifiers below belong to the PromptKit adoption roadmap, separately
|
||||
from the ConfigKit review identifiers above.
|
||||
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. These are CLI features;
|
||||
general-purpose helpers for application-internal PromptKit use are outside
|
||||
CommandKit's ownership boundary.
|
||||
|
||||
- **Focused backend inspection.** Defer a standard backend detail command
|
||||
until a released PromptKit version provides a suitable public backend
|
||||
@@ -137,43 +90,12 @@ from the ConfigKit review identifiers above.
|
||||
configuration. Review the released upstream capability before selecting
|
||||
command syntax and report fields; this feature is outside the v0.19.0
|
||||
adoption scope.
|
||||
- **Prepared-request inspection (PromptKit OD-4).** Consider an optional provider
|
||||
and report based on the released native `Engine.Prepare` and `PreparedRun`,
|
||||
reusing the concrete request-builder pattern. This would extend standard
|
||||
inspection into rendering and needs an explicit scope decision. The snapshot
|
||||
offers selected resource IDs, effective settings, output/schema metadata,
|
||||
messages, session ID, hashes, and timing without a model call. Its `Messages`
|
||||
contain complete rendered and appended messages; its effective execution
|
||||
settings exclude resolved API-key values. Select report content and document
|
||||
those upstream semantics rather than treating the complete snapshot as an
|
||||
existing inspection report. Command grammar, callback shape, formats, and the
|
||||
relationship to request validation remain open. Validate capability
|
||||
availability, forwarding, projection, and report delivery at CommandKit's
|
||||
boundary. PromptKit retains preparation and rendering semantics. Keeping this
|
||||
operation application-owned remains an alternative; model execution and
|
||||
prepared-handle lifecycle are outside this proposal.
|
||||
- **Namespace helpers or standard selectors (PromptKit OD-5).** The
|
||||
[consumer guidance](../consumers/guide.md#namespace-views) covers loaders
|
||||
returning `Engine.WithNamespaces`.
|
||||
Consider reusable bindings or helpers when consumers demonstrate repeated
|
||||
wiring. Design independent prompt/profile/backend defaults, applicable
|
||||
operations, and their interaction with existing catalog filters together.
|
||||
Namespace views resolve unqualified caller selections; they do not rewrite
|
||||
captured configuration references or global configuration inspection, and
|
||||
namespace/collection inventories remain global. Preserve the distinction
|
||||
between name resolution and catalog filtering. No flag names or changed
|
||||
filtering meanings are selected.
|
||||
- **Other reusable request bindings.** Consider helpers for native request
|
||||
options only where consumers repeat wiring. Execution/output-validation
|
||||
overrides, session IDs, appended messages, and retry settings are already
|
||||
reachable through application request builders; engine options remain
|
||||
available through loaders. API availability alone does not select a standard
|
||||
flag or a new core abstraction.
|
||||
|
||||
The released [prepared snapshot](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/types.go)
|
||||
and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go)
|
||||
provide the reviewed upstream contracts. These proposals establish no new
|
||||
provider requirement, delivery date, or adoption completion condition.
|
||||
Additional request controls, including output-contract, inline-input, and
|
||||
appended-message flags, remain scope choices under
|
||||
[roadmap OD-2](promptkit-v0.19.0.md#od-2-request-controls-and-provider-parameter-grammar).
|
||||
Their native API availability alone does not select CLI syntax or require a
|
||||
convenience API for application execution.
|
||||
|
||||
### Alias completion and discovery
|
||||
|
||||
@@ -229,9 +151,10 @@ operator or consumer need and an appropriate ownership/behavior decision:
|
||||
- Backend selection or replacement, a plugin framework, general dependency
|
||||
injection, and concurrent-dispatch guarantees.
|
||||
|
||||
Execution, rendering, serving, and session operations remain application-owned.
|
||||
The [prepared-request inspection proposal](#promptkit-inspection-and-selection-extensions)
|
||||
would extend standard inspection into rendering and remains an open scope choice.
|
||||
Execution, serving, and session operations remain application-owned. The
|
||||
[request preview proposal](promptkit-v0.19.0.md#preview-and-request-flags)
|
||||
would expose native preparation and rendering as an operator inspection command;
|
||||
it remains subject to roadmap review.
|
||||
Shared vocabulary is guidance under [ADR 0006](../adr/0006-command-grammar.md).
|
||||
Backend replacement remains possible behind the accepted facade, subject to the
|
||||
published API/CLI contracts and deliberate compatibility decisions.
|
||||
|
||||
398
docs/roadmap/promptkit-v0.19.0.md
Normal file
398
docs/roadmap/promptkit-v0.19.0.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# PromptKit v0.19.0 adoption and operator CLI
|
||||
|
||||
Status: proposed roadmap for review. Scope is agreed in principle; implementation
|
||||
has not started. Command spellings, report designs, and API changes below are
|
||||
recommendations until the open decisions are resolved.
|
||||
|
||||
## Purpose and ownership
|
||||
|
||||
Adopt released PromptKit v0.19.0 and expose useful operator tasks through
|
||||
standard CommandKit commands, flags, and reports. This roadmap covers CLI
|
||||
exposure, including shared configuration inspection in `ckconfig`. It does not
|
||||
turn `ckprompt` into a convenience library for application-internal PromptKit
|
||||
operations. Applications continue to own engine construction, domain inputs,
|
||||
credentials, execution, and their executable lifecycle.
|
||||
|
||||
The [architecture policy](../policy/architecture.md),
|
||||
[optional-module decision](../adr/0010-optional-integration-modules.md), and
|
||||
[reporting decision](../adr/0014-invocation-reporting.md) govern implementation.
|
||||
The [CLI reference](../cli.md) and public GoDoc remain the owners of implemented
|
||||
contracts. This roadmap selects work for review, not new guarantees about
|
||||
upstream behavior or permanent limits on future features.
|
||||
|
||||
## Baseline and released evidence
|
||||
|
||||
Repository baseline: `0b4e47c4206e323f7c5d5ec3f357494dd23008b2`.
|
||||
The completed v0.18.0 adoption is not reopened.
|
||||
|
||||
| Component | Current baseline | Target |
|
||||
| --- | --- | --- |
|
||||
| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | No core change currently identified. |
|
||||
| `ckconfig` | ConfigKit v1.1.0; Go 1.27.0; core v0.3.0 | Shared CLI inspection extensions and a new appropriate module release. |
|
||||
| `ckprompt` | PromptKit v0.18.0; ConfigKit v1.1.0; ckconfig/core v0.3.0; Go 1.27.0 | PromptKit v0.19.0 and the ckconfig version delivering the shared work. |
|
||||
| Candidate | [ckprompt v0.3.0](../../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
|
||||
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).
|
||||
Work against released versions only; do not inspect or monitor unreleased
|
||||
upstream work in anticipation of another adoption.
|
||||
|
||||
Current `ckprompt` supplies prompt/profile inspection, requirements discovery,
|
||||
concrete request validation, prompt/profile/backend/namespace/collection
|
||||
catalogs, and four smoke operations plus `test all`. Smoke commands already
|
||||
expose most execution overrides and detailed native evidence. Validation has
|
||||
profile, session, variable, and file-input flags but lacks that override surface.
|
||||
There is no concrete request preview or dedicated backend detail command.
|
||||
|
||||
Current `ckconfig` supplies validation, native effective YAML, source inventory,
|
||||
path explanation with history, and reduced semantic comparison. Its `View`
|
||||
contains effective, sources, and explanation facets. Native metadata is not
|
||||
exposed as a capability. `config sources` returns on acquisition failure before
|
||||
rendering evidence; loaders convert native diagnostics into presentation
|
||||
messages but do not expose a structured diagnostics report. Relevant boundaries
|
||||
are [ckconfig contracts](../../integrations/ckconfig/contracts.go),
|
||||
[ConfigKit adapters](../../integrations/ckconfig/configkit_adapter.go), and
|
||||
[PromptKit adapters](../../integrations/ckprompt/adapters.go).
|
||||
|
||||
## Targeted end state
|
||||
|
||||
The original adoption tasks remain included:
|
||||
|
||||
1. Update the dependency, checksums, attribution, and unpublished candidate note.
|
||||
2. Document all three upstream compatibility changes and correct credential
|
||||
inspection wording.
|
||||
3. Cover the new authentication reason and corrected smoke preparation-error
|
||||
propagation at CommandKit's boundary.
|
||||
4. Validate the final independent modules and aligned workspace.
|
||||
|
||||
Add the following operator capabilities. Syntax is illustrative and subject to
|
||||
the decisions at the end of this document.
|
||||
|
||||
| Operator task | Proposed CLI | Owning module and report |
|
||||
| --- | --- | --- |
|
||||
| Inspect what a concrete prompt request prepares | `promptkit show request ID --profile … --input … --var …` | `ckprompt`: selected IDs, effective settings, rendered/appended messages, output contract and schema, session, hashes, and timing from `PreparedRun`. |
|
||||
| Reproduce target/provider settings without editing configuration | Applicable existing smoke override flags on validation and preview; `--extra-params JSON` on these and smoke operations | `ckprompt`: native request forwarding; preview and smoke reports show returned effective settings. |
|
||||
| Resolve unqualified resource selections in chosen namespaces | Independent prompt/profile/backend namespace flags | `ckprompt`: delegate to native namespace views, retaining the distinction from catalog filters. |
|
||||
| Find configuration paths and inspect their explicitness | `config paths --scope promptkit`, with historical selection; metadata alongside path explanation | `ckconfig`, wired through `ckprompt.ConfigScope`: observed paths, effective presence, explicitness/null/origin evidence, and available history. |
|
||||
| Understand both sides of configuration changes | `config diff --scope promptkit --details` | `ckconfig`: native paths, left/right snapshots, presence/redaction, and hidden-change evidence. |
|
||||
| Investigate a failed configuration load | `config sources --scope promptkit` on failure; a structured diagnostics operation | `ckconfig`, with both native adapters: acquired source inventory and native codes, severities, paths, and locations while retaining the load failure. |
|
||||
|
||||
### Compatibility and native semantics
|
||||
|
||||
Document these v0.19.0 changes for consumers constructing engines and inputs:
|
||||
|
||||
- Successful custom `ArtifactReader.Read` transfers ownership of its returned
|
||||
artifact and mutable body storage. Readers retaining scratch storage must
|
||||
supply independent returned storage and stop mutating returned aliases.
|
||||
- `ProfileSource` and `BackendSource` provider maps now use ConfigKit's native
|
||||
recursive Mapping forms: built-in scalar values, `[]any`, and
|
||||
`map[string]any`. Explain explicit conversion of `json.Number` and typed
|
||||
containers. Runtime execution overrides have a separate accepted-value
|
||||
contract; do not impose configuration-source restrictions on their flags.
|
||||
- Local-validation and structured-output schemas must be self-contained.
|
||||
External resources and filename-dependent base references fail preparation;
|
||||
internal references or explicit schema IDs supply the supported route.
|
||||
|
||||
No configuration-format migration is required from v0.18.0. Correct the CLI
|
||||
description of `api_key_required`: it indicates a usable direct or environment
|
||||
credential requirement and can coexist with `api_key_env`. Neither field is
|
||||
evidence of current credential availability.
|
||||
|
||||
The new authentication response-limit reason is factual evidence with unknown
|
||||
credential acceptance. Continue forwarding native findings without converting
|
||||
false, unknown, unsupported, or incomplete observations into command failures.
|
||||
Actual preparation/operation errors retain the operational outcome and supported
|
||||
cause identity. Native errors and their categories remain upstream-owned.
|
||||
|
||||
### Preview and request flags
|
||||
|
||||
Add an independently available preview capability alongside existing suite
|
||||
callbacks. The native adapter calls `Engine.Prepare` and projects its returned
|
||||
snapshot; a preliminary `ValidateRequest` call is unnecessary. Use existing
|
||||
typed selection, acquisition diagnostics, and invocation reporting patterns.
|
||||
Exact callback names and signatures follow the selected CLI design.
|
||||
|
||||
Preview performs applicable resource I/O and rendering but no model call.
|
||||
Rendered and appended messages contain application content. Upstream excludes
|
||||
resolved credentials from prepared settings; that does not make the whole
|
||||
snapshot a redacted configuration report or a transferable execution handle.
|
||||
Expose the upstream snapshot evidence without implying later execution uses
|
||||
that exact snapshot or will succeed.
|
||||
|
||||
Share CLI binding implementation where it reduces duplication between smoke,
|
||||
validation, and preview. Preserve native explicit zero/empty values and
|
||||
whole-map replacement semantics. Keep parsing in CommandKit and domain validity
|
||||
in PromptKit. Existing application builders remain usable; resolve override
|
||||
precedence and the remaining request controls under OD-2 before documenting new
|
||||
public behavior. These helpers serve standard CLI commands only.
|
||||
|
||||
### Namespace selection
|
||||
|
||||
Design independent prompt, profile, and backend defaults together. Native
|
||||
`WithNamespaces` replaces all defaults on its new view; it has no partial-update
|
||||
semantics. Omission must therefore have a deliberate meaning when a loader
|
||||
already returns a scoped engine (OD-3).
|
||||
|
||||
Qualified IDs pass through native selection unchanged. Captured references,
|
||||
configuration inspection, and namespace/collection inventories retain their
|
||||
native meanings. Existing `--namespace`/`--all-namespaces` catalog filters
|
||||
continue to describe filtering. Install new selectors only on operations where
|
||||
they have a defined use; define that applicability table during implementation.
|
||||
|
||||
### Shared configuration capabilities
|
||||
|
||||
Extend `ckconfig` through optional capabilities so existing custom providers can
|
||||
keep their currently declared operations. Both `FromConfigKit` and
|
||||
`ckprompt.ConfigScope` should expose available native evidence. Do not require
|
||||
all providers to implement every new operation.
|
||||
|
||||
For metadata, use `Metadata.HistoricalPaths`, `Lookup`, `IsExplicit`, and
|
||||
`History`. Enumeration covers observed paths, not all possible schema fields.
|
||||
Do not discard history because effective lookup fails. Existing explanation
|
||||
already reports current/historical values; add the missing discovery and
|
||||
explicitness instead of reproducing upstream provenance logic. Preserve native
|
||||
list-index paths; do not silently reinterpret them as resource IDs.
|
||||
|
||||
For detailed comparison, project native `Difference` records. Keep snapshots
|
||||
and their presence/redaction fields together, including `HiddenChanged` when
|
||||
the safe values look equal. Native sequence comparisons remain atomic; this
|
||||
work does not add element-level resource matching or a reloadable patch format.
|
||||
|
||||
For failure investigation, retain `LoadError.Sources()` and `Diagnostics()` as
|
||||
evidence alongside the error. The current adapters and `config sources` failure
|
||||
path need changes, not just another renderer. Define an acquisition shape that
|
||||
distinguishes unavailable evidence from an available empty inventory. A failed
|
||||
load does not establish an effective configuration or metadata capability.
|
||||
|
||||
Render available evidence through normal invocation reporting before terminal
|
||||
failure presentation. Keep the original load error and supported identity;
|
||||
successful report delivery must not convert failure to success. Preserve
|
||||
render/write failures separately through the current outcome machinery. Cover
|
||||
cancellation with partial evidence explicitly without promising interruption of
|
||||
an arbitrary writer or rollback of already-delivered bytes. OD-6 selects the
|
||||
structured diagnostics command and its interaction with ordinary diagnostics.
|
||||
|
||||
## Work sequence
|
||||
|
||||
1. **Resolve the significant CLI choices.** Review the open decisions, record
|
||||
selections here, and identify affected published reports and flag collisions.
|
||||
Prepare concrete command/flag/report examples for implementation review.
|
||||
2. **Adopt v0.19.0.** Update `integrations/ckprompt/go.mod` and `go.sum`, then
|
||||
[module attribution](../../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.
|
||||
3. **Implement request inspection and selection.** Add preview, applicable
|
||||
override flags, provider-parameter input, and namespace selectors. Reuse the
|
||||
standard suite's lifecycle and preserve existing application adapter seams.
|
||||
4. **Implement shared configuration inspection.** Add metadata discovery and
|
||||
explicitness, detailed diff presentation, source evidence on failure, and
|
||||
structured diagnostics in `ckconfig`; wire native PromptKit facets through
|
||||
`ConfigScope`. Keep each change reviewable with its boundary coverage.
|
||||
5. **Update operator and consumer documentation.** The CLI reference owns
|
||||
syntax, report schemas, availability, and outcomes; GoDoc owns callback and
|
||||
value contracts. Extend maintained simple/composed examples to demonstrate
|
||||
the new CLI tasks using local fixtures, without adding application-internal
|
||||
execution helpers. Record intentional compatibility effects in module notes.
|
||||
6. **Align module dependencies and validate.** Prepare the `ckconfig` release
|
||||
needed by `ckprompt`, update the latter's dependency/checksums, and complete
|
||||
the validation below. OD-7 addresses the interim development dependency.
|
||||
Publication and hosted delivery remain separate actions under the
|
||||
[release procedure](../release.md).
|
||||
|
||||
## Validation and completion checklist
|
||||
|
||||
Select focused boundary tests under the [testing policy](../policy/testing.md).
|
||||
The checklist concerns adapter/CLI behavior; it does not ask CommandKit to
|
||||
retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms.
|
||||
Default tests remain offline and independent of real credentials.
|
||||
|
||||
- [ ] Dependency, checksums, attribution commit links, and candidate notes match
|
||||
the final selected module versions.
|
||||
- [ ] All three compatibility changes and corrected credential wording are
|
||||
documented, with earlier v0.18.0 migration guidance retained where relevant.
|
||||
- [ ] The authentication response-limit reason survives report projection with
|
||||
native unknown facts. Smoke preparation errors retain supported causes and
|
||||
operational outcomes, including the no-report case; no model dispatch is
|
||||
introduced by CommandKit to handle them.
|
||||
- [ ] Preview forwards the intended request and faithfully reports native
|
||||
fields. Its CLI path makes no model call and does not create/execute retained
|
||||
prepared handles.
|
||||
- [ ] New flags preserve selected omission/empty/zero semantics, parse malformed
|
||||
inputs through the existing usage path, and do not leak state between runs.
|
||||
Numeric decoding of provider JSON matches the selected strategy in OD-2.
|
||||
- [ ] Namespace defaults, explicit clearing, qualified selections, and catalog
|
||||
filters are forwarded according to the selected design.
|
||||
- [ ] Metadata discovery distinguishes effective and historical paths, retains
|
||||
available history on absent lookup, and projects native field/change records.
|
||||
- [ ] Detailed diff retains both snapshots and presence/redaction/hidden-change
|
||||
evidence, including empty comparisons and sequence-level changes.
|
||||
- [ ] Source and diagnostic evidence can be reported with an acquisition error;
|
||||
the original failure, unavailable-versus-empty evidence, cancellation, and
|
||||
report-delivery failures remain distinguishable.
|
||||
- [ ] Existing providers remain usable; help, version, and capability discovery
|
||||
do not start acquisition. New operation/flag metadata and static completion
|
||||
match the implemented surface.
|
||||
- [ ] Maintained consumer examples demonstrate the selected CLI tasks and the
|
||||
configuration failure workflow with deterministic local evidence.
|
||||
- [ ] Canonical documentation, module release notes, and roadmap links agree
|
||||
with the implemented boundary. Open decisions are resolved or deliberately
|
||||
superseded before the corresponding behavior is claimed complete.
|
||||
- [ ] Final independent-module and aligned-workspace suites pass, with the
|
||||
dependency identities used by each recorded.
|
||||
|
||||
With the documented Go 1.27.0 toolchain selected, run
|
||||
`GOWORK=off GOTOOLCHAIN=local go test ./...` independently in the root,
|
||||
`integrations/ckconfig`, and `integrations/ckprompt`. Prepare dependencies before
|
||||
offline execution as described in the [release procedure](../release.md).
|
||||
Then validate the aligned workspace from the root with:
|
||||
|
||||
```sh
|
||||
GOTOOLCHAIN=local go test ./...
|
||||
GOTOOLCHAIN=local go test ./integrations/ckconfig/...
|
||||
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.
|
||||
|
||||
## 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. Configuration mutation, new live probes, dynamic completion,
|
||||
JSON report formats, and unrelated deferred proposals are not added by this
|
||||
roadmap. A later ConfigKit review may propose further CLI tasks separately.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
These decisions concern significant choices within the proposed scope. OD
|
||||
numbers are local to this roadmap, not the retired adoption documents.
|
||||
|
||||
### OD-1: Preview command and report presentation
|
||||
|
||||
**Recommendation:** use `promptkit show request ID`, with YAML as the initial
|
||||
report format and the complete relevant `PreparedRun` projection. It sits beside
|
||||
definition inspection while clearly requiring concrete inputs. A single native
|
||||
preparation supplies both validation and preview evidence. Document rendered
|
||||
content disclosure directly in help and CLI guidance.
|
||||
|
||||
**Alternative:** `promptkit prepare ID`, with text and YAML reports. This names
|
||||
the native action and makes interactive inspection easier, but can suggest an
|
||||
executable prepared handle and adds a second rendering contract. Both forms can
|
||||
stay entirely within CLI ownership; select vocabulary and formats before coding.
|
||||
|
||||
### OD-2: Request controls and provider-parameter grammar
|
||||
|
||||
**Recommendation:** give validation and preview the applicable execution flags
|
||||
already on smoke tests, and add a singleton `--extra-params JSON` object option
|
||||
to all three. Use native whole-map replacement, including native behavior for
|
||||
empty maps. Specify JSON number decoding deliberately so supported values reach
|
||||
PromptKit without accidental precision loss or new numeric guarantees. Retain
|
||||
the current authoritative-builder rule: the standard flags seed a request and
|
||||
an application builder can return its complete replacement.
|
||||
|
||||
**Alternative:** repeatable `--extra-param KEY=JSON` assignments. This is easier
|
||||
for individual shell overrides, but requires rules for duplicate keys and makes
|
||||
whole-map replacement less obvious. It must still construct a single native map
|
||||
rather than imply an upstream field-by-field merge.
|
||||
|
||||
**Remaining request surface:** recommend keeping output-contract overrides,
|
||||
inline-input flags, and appended-message flags as separately selectable CLI
|
||||
extensions after execution-flag parity. Existing file inputs and application
|
||||
builders continue to support preview. A viable alternative is to include a
|
||||
whole-output-contract file option and message/input options now, supporting
|
||||
more reproduction workflows at the cost of additional syntax, precedence, and
|
||||
reporting decisions. No general-purpose request-building API follows from
|
||||
either choice.
|
||||
|
||||
### OD-3: Namespace flags and loader defaults
|
||||
|
||||
**Recommendation:** make the standard namespace selectors opt-in with explicit
|
||||
suite-owned namespace defaults. Compose supplied fields with those defaults,
|
||||
then apply one native `WithNamespaces` call. Loaders using this option leave
|
||||
default selection to that adapter. This gives omission and explicit empty
|
||||
values predictable meanings without trying to read private engine state.
|
||||
Without the option, existing scoped loaders continue as before.
|
||||
|
||||
**Alternative:** pass presence-aware namespace choices to an acquisition
|
||||
callback and let the application combine them with its existing loader defaults.
|
||||
This accommodates applications whose defaults depend on domain input, but adds
|
||||
consumer wiring and makes consistent behavior less automatic. Either design
|
||||
must account for the native API replacing all three defaults at once.
|
||||
|
||||
### OD-4: Configuration path and metadata presentation
|
||||
|
||||
**Recommendation:** add `config paths` with effective paths by default and an
|
||||
explicit historical selection, and expose optional metadata alongside existing
|
||||
path explanation. Use the current single-scope selection model. This makes
|
||||
paths discoverable and uses an established command for their meaning/history.
|
||||
Define availability and unavailable metadata explicitly for older providers.
|
||||
|
||||
**Alternative:** a separate `config metadata --path …` operation plus historical
|
||||
enumeration. This keeps the existing explanation report unchanged and gives
|
||||
metadata-only providers an independent operation, but splits related operator
|
||||
information across commands. Weigh that compatibility benefit against the
|
||||
extra command and report contract before selecting additive explanation fields.
|
||||
|
||||
### OD-5: Detailed comparison selection and shape
|
||||
|
||||
**Recommendation:** add `--details` to `config diff`, retaining the existing
|
||||
default. Emit a YAML record sequence carrying native paths, snapshots, and
|
||||
hidden-change fields, preferably within a scope-labeled envelope. This supplies
|
||||
the missing evidence without changing existing reduced-report consumers.
|
||||
|
||||
**Alternative:** replace the reduced form with the detailed report in a new
|
||||
minor module release. One canonical report is simpler to maintain and avoids
|
||||
selection flags, but requires migration of published CLI consumers. The release
|
||||
policy permits a deliberate pre-v1 minor compatibility change; the benefit must
|
||||
justify that disruption.
|
||||
|
||||
### OD-6: Failure evidence and structured diagnostic delivery
|
||||
|
||||
**Recommendation:** extend `config sources` to report acquired inventory on
|
||||
failure and add `config diagnostics --format yaml` for native structured records
|
||||
and their source legend. Build this as optional `ckconfig` evidence facets,
|
||||
including evidence returned with an acquisition error. Keep ordinary human
|
||||
messages on the diagnostic stream and structured results on the result stream,
|
||||
using existing terminal failure/outcome handling. This is a bounded operator
|
||||
workflow with no demonstrated need for a generic core diagnostics schema.
|
||||
|
||||
**Alternative:** add structured diagnostic output to every configuration
|
||||
operation through a common format option or report envelope. It avoids a
|
||||
second invocation when diagnosing another command, but complicates existing
|
||||
native YAML/report shapes and result-versus-diagnostic stream contracts. A
|
||||
broader core representation is viable if concrete cross-family needs justify
|
||||
it; it is more work than exposing ConfigKit records alone. Specify warning
|
||||
presentation, evidence availability, and partial-result cancellation behavior
|
||||
for the selected design rather than silently changing all operations.
|
||||
|
||||
### OD-7: Module release and interim workspace coordination
|
||||
|
||||
**Recommendation:** prepare a new ckconfig minor release for the shared API/CLI
|
||||
features, then update the still-unpublished ckprompt candidate to require it.
|
||||
Confirm available versions under the existing release procedure. During joint
|
||||
development use the ignored aligned workspace; record that workspace success
|
||||
does not establish independent ckprompt compatibility with its old ckconfig
|
||||
requirement. Before final independent validation, pin the released ckconfig
|
||||
version actually supplying the APIs. Publication requires its own authorization.
|
||||
|
||||
**Alternative:** publish a compatibility-only ckprompt release first and deliver
|
||||
the additional CLI features in subsequent releases. This makes v0.19.0 fixes
|
||||
available sooner, but creates an extra consumer upgrade and does not complete
|
||||
this roadmap's targeted end state. A disposable local module replacement can
|
||||
help test intermediate changes, but cannot substitute for final validation of
|
||||
the declared released dependency.
|
||||
Reference in New Issue
Block a user