base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Consolidate adoption roadmap and finalize core prerequisites

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 02:04:57 +00:00
parent ee3cb21ebc
commit 9b85c7cf60
2 changed files with 330 additions and 495 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/roadmap/future.md
View File

@@ -35,26 +35,21 @@ The published ckprompt v0.2.0 retains its earlier dependencies; see the
### PromptKit v0.19.0 adoption
The [PromptKit v0.19.0 roadmap](promptkit-v0.19.0.md) owns the proposed adoption,
the agreed shared core report output prerequisite, operator CLI additions for
PromptKit and ConfigKit, recorded 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.
The [PromptKit v0.19.0 roadmap](promptkit-v0.19.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.
## Future capability targets
### Comparison extensions
Independent per-side domain selectors and opt-in comparison assertions are now
included in the [working roadmap](promptkit-v0.19.0.md#additional-configkit-operator-workflows).
Roadmap OD-9 selects independent ordinary defaults for both sides and explicit
application-declared right-side bindings. Configuration selections and overrides
apply only to their own side; omission never inherits from the opposite side.
Explicit-empty application selectors remain with application-declared bindings
for this release; no additional standard collection-clearing flags are selected.
OD-10 selects an optional assertion outcome with a distinct difference status.
These accepted plans do not change the currently implemented behavior.
The [working roadmap](promptkit-v0.19.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.
General collection-clearing support is deferred pending a concrete consumer need.
Revisit standardized syntax and binding support for explicitly replacing a
@@ -63,44 +58,18 @@ This is separate from clearing configuration lists through OD-11's transient
overrides and does not reinstate comparison inheritance. No clearing grammar
or public helper API is selected.
[Roadmap OD-5](promptkit-v0.19.0.md#od-5-detailed-comparison-selection-and-shape)
selects an optional detailed report while retaining the concise default for
human operators. Both presentations reuse the existing native comparison data;
the accepted initial layout is recorded there for implementation and later beta
feedback.
### Configuration inspection extensions
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. Path discovery is a mode of `config explain`, and
structured diagnostics belong to `config validate`; the suite retains six
subcommands. The roadmap records the agreed explanation modes and help behavior;
[OD-6](promptkit-v0.19.0.md#od-6-failure-evidence-and-structured-diagnostic-delivery)
selects optional validation details, a concise default, and available evidence
on failure. OD-8 selects focused display, source selection, and report filters.
Initial report content, text templates, and filter spellings are selected
in the roadmap; core owns universal and automatic format selection. The
remaining layout details will be evaluated through implementation and beta use.
It also includes focused effective display,
source-ID selection, metadata/diagnostic filters, independent comparison
selectors, and assertion mode. The original four shared proposals had ConfigKit
adoption identifiers 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. The
[initial report implementation approach](promptkit-v0.19.0.md#initial-report-implementation-approach)
uses the shared core reporting prerequisite, direct serialization, and thin
projections. Further presentation refinements should follow practical feedback.
Transient acquisition overrides are included as an opt-in loader capability in
[roadmap OD-11](promptkit-v0.19.0.md#od-11-transient-configuration-overrides).
Comparison overrides follow OD-9's independent-side model and use the same
ordinary Go numeric policy as CLI provider parameters. OD-11 selects assignment
syntax without support for paths containing `=` and pass-through delivery during
normal loading, leaving configuration semantics and errors to ConfigKit.
All numbered roadmap decisions are settled; API signatures and wiring remain
implementation tasks. Persistent configuration editing remains deferred.
The [working roadmap](promptkit-v0.19.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,
and pass-through override policy are defined there. Implementation belongs in
`ckconfig`, with PromptKit exposing native evidence through its configuration
scope. Use the shared core reporting prerequisite and thin projections;
presentation refinements should follow implementation and beta feedback.
All numbered decisions are settled; exact APIs and wiring remain implementation
work. Persistent configuration editing remains deferred.
Discovery, import defaults, collection identities, and field-level resolution
recording remain available through application loaders. Discovery tracing,
@@ -120,7 +89,9 @@ commands, composed through existing core bindings.
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
with policy comments. Those flag and alias features need no core extension.
with policy comments, behind a narrow public core CLI JSON parser. Collections
and aliases use existing declarations; cross-flag text/file precedence uses the
roadmap's ordered typed input prerequisite.
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.
@@ -183,24 +154,14 @@ 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)
is now part of the working adoption roadmap. It records application-owned
content selection, core-owned rendering, text output with optional templates,
and universal format availability. Explicit operator selection wins; otherwise
core selects text for a supplied template or chooses from the logical report
shape. Command-specific format defaults are omitted from the initial API.
Plain text, YAML, and JSON land together. The roadmap selects standard Go JSON
serialization conventions for core-serialized report values. Core explicitly
converts safe inspection YAML into ordinary report values, preserving data
meaning and redaction without a separate native-YAML preservation path.
Text templates use Go's `text/template`
with the original Go report value. Without a template, structured text output
reuses the YAML renderer; template errors never trigger fallback. Aggregate
configuration display uses an ordinary scope-keyed mapping through the same
renderers, with no scope-order guarantee or separate-document machinery.
XML is removed from current consideration.
Markdown and other potential formats are not selected for this adoption; new
core formats will work with
existing commands without per-command adoption.
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)
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
selected for this adoption.
Error-conversion helpers such as `WarnError` remain deferred pending demonstrated
value; applications can already use `report.Warn(err.Error())`. Terminal redraw
@@ -243,8 +204,8 @@ operator or consumer need and an appropriate ownership/behavior decision:
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.
exposes native preparation and rendering as an agreed operator inspection target;
implementation has not started.
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.