Consolidate adoption roadmap and finalize core prerequisites
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
# Shared report output, PromptKit v0.19.0 adoption, and ConfigKit 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 except where explicitly recorded as agreed below. Accepted
|
||||
report formats are an initial implementation target; practical beta feedback
|
||||
will guide later refinements rather than requiring exhaustive layout design now.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Ownership principles
|
||||
|
||||
@@ -28,8 +31,8 @@ These agreed principles are recorded here for eventual incorporation into
|
||||
|
||||
Adopt released PromptKit v0.19.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 a new
|
||||
public core reporting capability as a prerequisite to the downstream work.
|
||||
exposure, including ConfigKit v1.1.0 operator features in `ckconfig`, with shared
|
||||
core reporting and CLI input capabilities as prerequisites to the downstream work.
|
||||
Core standardizes report format selection, representation, rendering, and
|
||||
delivery for core commands, integrations, and application-owned commands.
|
||||
Applications and integrations continue to choose report content. This does not
|
||||
@@ -41,8 +44,8 @@ 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.
|
||||
contracts. This roadmap records planned work, not new guarantees about upstream
|
||||
behavior or permanent limits on future features.
|
||||
|
||||
## Baseline and released evidence
|
||||
|
||||
@@ -51,7 +54,7 @@ The completed v0.18.0 adoption is not reopened.
|
||||
|
||||
| Component | Current baseline | Target |
|
||||
| --- | --- | --- |
|
||||
| Core | `go.maximumdirect.net/commandkit`; Go 1.26.0 minimum | Public report output API with universal format choices and automatic selection; text/YAML/JSON land together as a prerequisite. Flag collections and scoped aliases still use existing core APIs. |
|
||||
| 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. |
|
||||
| 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. |
|
||||
@@ -106,7 +109,9 @@ they do not replace already-delivered explanation or smoke functionality.
|
||||
|
||||
First establish the [shared core report output capability](#shared-core-report-output-prerequisite).
|
||||
The integration work below uses that public API instead of adding independent
|
||||
format-selection and encoding machinery in each module.
|
||||
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:
|
||||
|
||||
@@ -117,10 +122,10 @@ The original adoption tasks remain included:
|
||||
propagation at CommandKit's boundary.
|
||||
4. Validate the final independent modules and aligned workspace.
|
||||
|
||||
Add the following operator capabilities. Syntax is illustrative unless selected
|
||||
in the decisions at the end of this document.
|
||||
Add the following operator capabilities. The decisions at the end of this
|
||||
document own exact syntax and behavior; these examples summarize operator tasks.
|
||||
|
||||
| Operator task | Proposed CLI | Owning module and report |
|
||||
| Operator task | CLI examples | Owning module and report |
|
||||
| --- | --- | --- |
|
||||
| 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`. |
|
||||
@@ -182,150 +187,71 @@ cause identity. Native errors and their categories remain upstream-owned.
|
||||
|
||||
### Preview and request flags
|
||||
|
||||
Expose preview as `promptkit show prepared PROMPT_ID`, using core's automatic
|
||||
selection and universal format choices, through an independently available
|
||||
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.
|
||||
[OD-1](#od-1-preview-command-and-report-presentation) owns prepared preview;
|
||||
[OD-2](#od-2-request-controls-and-provider-parameter-grammar) owns reusable flag
|
||||
collections, aliases, input forms, and precedence. Expose preview as an independent
|
||||
capability alongside existing suite callbacks. Call `Engine.Prepare` once and
|
||||
project its snapshot; a preliminary `ValidateRequest` call is unnecessary.
|
||||
Upstream excludes resolved credentials from prepared settings, but rendered
|
||||
application content is not a redacted configuration report.
|
||||
|
||||
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.
|
||||
|
||||
Provide public, reusable typed execution-flag collections in `ckprompt`, defined
|
||||
once and used by smoke, validation, preview, and application-owned commands.
|
||||
The collections standardize flag names, help, parsing, completion hints,
|
||||
supplied-value tracking, and binding into native PromptKit request fields.
|
||||
Applications retain their own input structs, request construction, engine
|
||||
acquisition, execution, and outcomes. Reusing CLI declarations is within
|
||||
CommandKit's ownership boundary; it does not introduce runtime convenience APIs.
|
||||
|
||||
Use the existing core `CommandSpec[I].Flags`, typed flag constructors, and
|
||||
`Supplied[T]`. A generic collection factory can accept destination accessors
|
||||
and return ordinary `[]commandkit.Flag[I]`. Direct binding is sufficient for
|
||||
ordinary use; existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go)
|
||||
support deferred application or multiple destinations where needed. These flag
|
||||
collections require no core change or new core collection abstraction. Exact
|
||||
exported names and accessor signatures remain implementation design choices.
|
||||
|
||||
Keep execution-target overrides and the request-level transient retry field
|
||||
distinct even when one convenient collection includes both. Preserve omission
|
||||
instead of imposing shared defaults: ordinary execution and smoke diagnostics
|
||||
have different native retry defaults. Preserve native explicit zero/empty
|
||||
values and whole-map replacement semantics. Support deliberate subsets for
|
||||
actual command needs while retaining common flag names and meanings, using a
|
||||
proportionate composition API. Keep parsing in CommandKit and domain validity
|
||||
in PromptKit. Existing application builders remain authoritative as agreed in
|
||||
OD-2. That decision also selects literal-text and file input bindings and defers
|
||||
output-contract overrides and appended-message controls.
|
||||
Build collections using `CommandSpec[I].Flags`, typed constructors, and
|
||||
`Supplied[T]`. Existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go)
|
||||
serve ordinary deferred application. Collections and alias generation need no
|
||||
new abstraction; cross-flag input ordering and shared JSON parsing use the
|
||||
[additional core input prerequisites](#shared-core-cli-input-prerequisites).
|
||||
Applications retain their input types, request construction, acquisition, and
|
||||
execution. Keep execution-target overrides distinct from transient retries:
|
||||
ordinary requests and smoke diagnostics have different upstream retry defaults.
|
||||
|
||||
### 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. Under the agreed OD-3 design, opt-in selectors combine explicitly
|
||||
declared suite defaults with supplied overrides; they do not infer defaults
|
||||
from a loader's engine view.
|
||||
|
||||
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 selectors according to the agreed
|
||||
applicability table in OD-3 and verify their use at the upstream call boundary.
|
||||
[OD-3](#od-3-namespace-flags-and-loader-defaults) owns the opt-in namespace
|
||||
composition, applicability table, and profile-identity clarification. Implement
|
||||
one native view update using declared defaults and supplied fields. Verify the
|
||||
selected flags against actual upstream operations; captured references and
|
||||
catalog filters retain their upstream meanings.
|
||||
|
||||
### 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 inspection mode. Providers lacking metadata
|
||||
or structured diagnostics retain their existing explanation/validation behavior;
|
||||
mode availability and help must reflect the capabilities supplied.
|
||||
Extend `ckconfig` through optional capabilities, exposed by `FromConfigKit` and
|
||||
`ckprompt.ConfigScope`. Providers need not implement every inspection mode;
|
||||
help and availability must reflect their supplied capabilities.
|
||||
|
||||
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 within explanation discovery instead of reproducing upstream
|
||||
provenance logic. Preserve native list-index paths; do not silently reinterpret
|
||||
them as resource IDs.
|
||||
|
||||
For optional detailed comparison, project the native `Difference` records
|
||||
already returned by `Scope.Compare`; retain the existing concise report by
|
||||
default. Keep snapshots and their presence/redaction fields together, including
|
||||
`HiddenChanged` when the safe values look equal. Reuse the same loading and
|
||||
comparison path for both presentations. 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
|
||||
`config validate --details`; its interaction with ordinary diagnostic messages
|
||||
remains a presentation design task.
|
||||
Structured records describe that validation invocation, including a failed
|
||||
load; they are not a retrieval interface for an earlier command. Preserve the
|
||||
current aggregate validation stopping behavior unless deliberately revised;
|
||||
structured reporting alone does not promise exhaustive findings across scopes.
|
||||
- Metadata discovery uses `Metadata.HistoricalPaths`, `Lookup`, `IsExplicit`,
|
||||
and `History`. It covers observed paths, not every possible schema field.
|
||||
Preserve history after absent lookup and native list-index paths. OD-4 owns
|
||||
the operator presentation and filters.
|
||||
- Detailed diff reuses `Scope.Compare` and native `Difference` records under
|
||||
OD-5. Native sequence changes remain atomic; no element-matching algorithm or
|
||||
reloadable patch format is added.
|
||||
- Failed-load evidence uses `LoadError.Sources()` and `Diagnostics()` alongside
|
||||
the original error. Acquisition must distinguish unavailable evidence from an
|
||||
available empty inventory. A failed load establishes no effective configuration
|
||||
or metadata capability. OD-6 owns diagnostic presentation, aggregation, and
|
||||
failure delivery; this work requires adapter changes, not only a renderer.
|
||||
|
||||
### Additional ConfigKit operator workflows
|
||||
|
||||
**Focused effective display.** Use the effective snapshot from native
|
||||
`Explain(path)` for path-selected display. The ordinary whole-document path
|
||||
continues to use `WriteEffective`. A historical-only path can be explainable
|
||||
while lacking an effective value; distinguish that case from a present YAML
|
||||
null. Select the missing-value behavior, provider availability, and aggregate
|
||||
scope applicability under OD-8. Do not read mutable `Result.Config` or source
|
||||
files to reconstruct inspection values.
|
||||
[OD-8](#od-8-focused-configuration-reports-and-filtering) owns focused values and
|
||||
source selection. Obtain path values from native `Explain(path)` and whole
|
||||
configuration values from safe `WriteEffective` output, converting both through
|
||||
core. Never reconstruct inspection from mutable `Result.Config` or source files.
|
||||
Select source IDs from acquired inventory; native `Source(id)` is a convenience,
|
||||
not another provider requirement. Source IDs are local to one load.
|
||||
|
||||
**Source selection and report filters.** Select source IDs from the acquired
|
||||
inventory, preserving existing record fields and upstream ordering. Native
|
||||
`Source(id)` is a convenience, not an additional provider requirement. IDs are
|
||||
local to a load and do not guarantee the same source in a later acquisition.
|
||||
Apply subtree filtering to parsed configuration paths, not raw string prefixes
|
||||
that would confuse `/server` with `/server2`. Specify explicitness filtering for
|
||||
historical-only paths without treating unavailable effective metadata as false.
|
||||
Diagnostic filters affect the presented records, not the underlying acquisition
|
||||
outcome; retain the source references needed to interpret selected records.
|
||||
[OD-9](#od-9-independent-comparison-selector-bindings) replaces ADR 0012's
|
||||
inheritance while retaining its two-input/provider lifecycle. Domain defaults
|
||||
and caching remain application-owned.
|
||||
[OD-10](#od-10-comparison-assertion-outcomes) uses native differences for assertions;
|
||||
source/history differences alone and changed credential bytes behind unchanged
|
||||
references are not necessarily effective-value differences.
|
||||
|
||||
**Independent comparison selections.** Extend the per-side typed-input design
|
||||
in [ADR 0012](../adr/0012-typed-configuration-comparison-pairs.md), deliberately
|
||||
replacing its left-to-right inheritance and shared application-selector rules.
|
||||
Initialize each side from ordinary application defaults and apply only that
|
||||
side's explicitly supplied configuration selections and overrides under OD-9.
|
||||
Prepare and check both inputs before comparison and preserve the existing shared
|
||||
invocation state. Domain parsing, default interpretation, and loader caching
|
||||
remain with the application; the comparison provider still receives two selections.
|
||||
|
||||
**Comparison assertions.** Base a difference outcome on native record presence,
|
||||
including hidden changes whose redacted snapshots look equal. Equal effective
|
||||
values can have different histories or explicitness. Comparison also does not
|
||||
detect changed credential bytes behind an unchanged secret reference. Use
|
||||
the agreed opt-in outcome and report-delivery behavior under OD-10; retain the
|
||||
current ordinary diff outcome. A load or comparison failure is not evidence of equality.
|
||||
|
||||
**Transient overrides.** As agreed in OD-11, parse explicitly supplied
|
||||
CLI values into native `Override` records and pass them through a declared loader
|
||||
capability. ConfigKit owns override path validity, supported values, precedence,
|
||||
decoding, resolution, provenance, and validation. Its configuration overrides
|
||||
recursively overlay mappings and replace sequences; this differs from the
|
||||
PromptKit execution override's complete provider-map replacement. Do not reuse
|
||||
one grammar implementation in a way that erases that distinction. Source-load
|
||||
errors remain errors even if an override would replace the affected value.
|
||||
[OD-11](#od-11-transient-configuration-overrides) owns temporary override syntax
|
||||
and forwarding. ConfigKit recursively overlays mapping overrides and replaces
|
||||
sequences, unlike PromptKit's complete provider-map replacement. Shared numeric
|
||||
parsing must not erase that distinction. Source-load errors remain errors even
|
||||
if a supplied override would replace the affected value.
|
||||
|
||||
## Shared core report output prerequisite
|
||||
|
||||
@@ -500,8 +426,9 @@ template's field access. An exported field tagged `json:"-"` remains accessible
|
||||
to the application's template, and custom JSON serialization does not replace
|
||||
the template input. The application owns that text content choice. Core retains
|
||||
ownership of execution, shared helpers, delivery, and presentation failures.
|
||||
Prefer reusable templates prepared during setup; exact public preparation and
|
||||
handoff signatures and the small helper set remain implementation design tasks.
|
||||
Prefer reusable templates prepared during setup. Exact preparation and handoff
|
||||
signatures remain implementation choices; begin with standard template functions
|
||||
and add shared helpers only for concrete report needs.
|
||||
|
||||
When text is selected and a template is supplied, execute it as supplied and
|
||||
deliver its output without applying a second formatting pass. Template syntax
|
||||
@@ -576,65 +503,98 @@ format delivery.
|
||||
Report serialization is separate from the agreed CLI JSON number policy in OD-2,
|
||||
also adopted for configuration overrides in OD-11.
|
||||
|
||||
## Shared core CLI input prerequisites
|
||||
|
||||
These two narrow capabilities land with the core reporting prerequisite. They
|
||||
support the selected integration behavior without adding a collection framework.
|
||||
|
||||
### Public CLI JSON parsing boundary
|
||||
|
||||
Add a small public CLI JSON parsing entry point to core. It parses one JSON value
|
||||
using the [OD-2 numeric policy](#od-2-request-controls-and-provider-parameter-grammar)
|
||||
and returns ordinary Go values. Integrations enforce their flag's outer shape:
|
||||
provider parameters require an object; configuration assignments accept a JSON
|
||||
value after their pointer prefix. Keep numeric conversion and its policy comments
|
||||
in one private helper behind that entry point.
|
||||
|
||||
The separate module paths `go.maximumdirect.net/commandkit`,
|
||||
`go.maximumdirect.net/ckconfig`, and `go.maximumdirect.net/ckprompt` cannot share
|
||||
core's private `internal` packages. The public CLI parser is the deliberate
|
||||
cross-module boundary; no public general-purpose numeric conversion API or
|
||||
separately versioned numeric package is introduced. It must work in independently
|
||||
built modules, not only in the local workspace. Exact naming is implementation work.
|
||||
|
||||
### Ordered typed input composition
|
||||
|
||||
Add a small typed binding-composition capability preserving occurrence order
|
||||
across participating flags. Current `RepeatFlag` and `FlagValues.ApplyTo` group
|
||||
values by binding, which cannot establish OD-2's text/file winner by command-line
|
||||
order. Exercise alternating text/file flags and their aliases before finalizing
|
||||
the core API. Keep parsing, presence, conversion errors, and invocation isolation
|
||||
in core; integrations choose how ordered typed values form their request.
|
||||
|
||||
Do not expose Cobra/pflag structures or reparse raw arguments in `ckprompt`.
|
||||
Ordinary flag collections and scoped alias declarations keep their existing
|
||||
APIs. This prerequisite adds only the ordering support those declarations lack.
|
||||
|
||||
## Initial report implementation approach
|
||||
|
||||
Use the accepted OD-4 through OD-6 flags and formats as a practical starting
|
||||
point. Keep added code, report types, and translations proportionate. Beta
|
||||
feedback on actual reports should guide changes. Resolve the core design details
|
||||
above, then implement the agreed extension points without delaying delivery
|
||||
for exhaustive layout design or speculative additional renderers.
|
||||
Use ordinary report structs/maps, standard JSON interpretation, the existing
|
||||
`go.yaml.in/yaml/v4` encoder, and standard `text/template`. Share rendering across
|
||||
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.
|
||||
|
||||
The repository already uses `go.yaml.in/yaml/v4` and small Go-value-to-YAML
|
||||
writers in core and both integrations. Consolidate suitable report paths onto
|
||||
the new core API and share encoder configuration and representation helpers.
|
||||
Use the capability in core, both integrations, and a maintained application-owned
|
||||
command example. A separately versioned output module or custom serialization
|
||||
engine is not needed. Follow module release/dependency ordering under OD-7.
|
||||
Prefer native report values or thin projections. Migrate YAML-only tags to 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.
|
||||
|
||||
Prefer handing off suitable native inspection/report values or a thin Go
|
||||
projection using the agreed JSON serialization conventions. Do not mirror a
|
||||
whole upstream object graph just to rename fields or rearrange equivalent data.
|
||||
Reuse small path, snapshot,
|
||||
location, and duration projections where they are genuinely needed. Core reuses
|
||||
the JSON contract across its serialization paths; migrate YAML-only report tags
|
||||
or provide a thin projection where necessary. Safe configuration YAML enters the
|
||||
ordinary Go-value path through core's explicit input conversion helper.
|
||||
### Output migration inventory
|
||||
|
||||
Exceptions serve concrete report semantics: preserving absent/null/false/zero
|
||||
and empty collections, expressing paths and durations readably, projecting safe
|
||||
snapshot values, and retaining native redaction. Encode report/inspection values,
|
||||
not engines, mutable runtime configuration, or request credential storage.
|
||||
Preserve inspection data meaning and the concise diff and validation content
|
||||
selections. Integrations prepare those values and any text templates; core owns
|
||||
rendering. YAML input conversion feeds that same machinery without preserving
|
||||
source formatting or adding an integration-owned formatting pipeline.
|
||||
Core's universal `--format` controls report submissions. All migrated reports
|
||||
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.
|
||||
|
||||
Separate content projection from format rendering and from invocation delivery.
|
||||
Use the existing Reporter and outcome lifecycle for delivery and failures.
|
||||
Text templates receive original Go values. Simple text output uses the logical
|
||||
report values directly, while structured text without a template delegates to
|
||||
the YAML renderer without a YAML encode/decode round trip. Do not force
|
||||
semantically different reports into one schema. Validate representative
|
||||
reports and meaningful adaptation boundaries, rather than freezing every
|
||||
incidental formatting detail in tests.
|
||||
| Output path | Migration 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 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. |
|
||||
| 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
|
||||
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
|
||||
feedback should guide exact layouts; avoid tests that freeze incidental spacing
|
||||
or field order.
|
||||
|
||||
## Work sequence
|
||||
|
||||
1. **Confirm remaining implementation choices.** Use the accepted flags, report
|
||||
1. **Finalize the core handoffs.** Use the accepted flags, report
|
||||
content, aggregate presentation, and automatic format policy as the MVP target.
|
||||
Specify the public API, reusable template helpers,
|
||||
and internal conversion design under the agreed JSON representation contract.
|
||||
Specify the report/writer APIs, CLI JSON parsing boundary, ordered typed input
|
||||
composition, and internal conversion under the agreed representation contract.
|
||||
Design the acquisition/binding wiring and flag collision handling; use
|
||||
concrete examples to review report details during implementation rather than
|
||||
reopening accepted scope.
|
||||
2. **Implement shared core report output.** Deliver the agreed automatic format
|
||||
2. **Implement the core prerequisites.** Deliver the agreed automatic format
|
||||
policy, universal `--format` selection, format-independent Reporter
|
||||
operation, writer-based API, and shared representation/encoding machinery.
|
||||
Deliver YAML encoding, text printing/templates, and JSON encoding together
|
||||
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
|
||||
Deliver YAML encoding, text printing/templates, JSON encoding, CLI JSON parsing,
|
||||
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
|
||||
@@ -645,9 +605,10 @@ incidental formatting detail in tests.
|
||||
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
|
||||
public `ckprompt` execution-flag collections on existing core bindings and
|
||||
reuse them in the standard commands. Generate scoped convenience aliases and
|
||||
provide a collection for installing the commands and routing declarations.
|
||||
public `ckprompt` execution-flag collections using core bindings and the new
|
||||
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.
|
||||
5. **Implement shared configuration inspection.** Add discovery and metadata
|
||||
@@ -662,7 +623,9 @@ incidental formatting detail in tests.
|
||||
implementation approach. Keep boundary coverage with each change.
|
||||
6. **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
|
||||
value contracts. Update the affected ADRs and architecture policy, and replace
|
||||
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.
|
||||
7. **Align module dependencies and validate.** Prepare the core release needed
|
||||
@@ -680,191 +643,101 @@ CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit
|
||||
resolution algorithms.
|
||||
Default tests remain offline and independent of real credentials.
|
||||
|
||||
- [ ] Public signatures and shared representation conventions are
|
||||
documented with implementation.
|
||||
- [ ] Core owns universal `--format` options, help, validation, and selection.
|
||||
Added core formats work with existing commands without refactoring or local
|
||||
allowlists. Unknown selections fail before acquisition, and selected formats
|
||||
do not leak between invocations.
|
||||
- [ ] Explicit operator selection overrides automatic selection. Without it,
|
||||
a text template selects text; otherwise core selects from the shared report
|
||||
shape. Cover scalars, nonempty string lists, mappings, mixed/nested lists,
|
||||
empty collections, and null. The initial API has no command format defaults.
|
||||
- [ ] Automatic selection uses the logical report after adaptation, once per
|
||||
complete report. Native YAML source strings are not mistaken for string
|
||||
configuration values. Focused configuration values follow the same rules.
|
||||
- [ ] Plain text, YAML, and JSON ship together; representative reports exercise
|
||||
shared representation and explicit selection across all three.
|
||||
- [ ] Text templates execute with standard `text/template` behavior against the
|
||||
original Go report value, retaining field names and types. JSON tags and custom
|
||||
JSON serialization do not rename, omit, or replace the template input.
|
||||
Explicit YAML/JSON output does not execute the text template.
|
||||
- [ ] Template syntax and execution failures remain observable errors; a failing
|
||||
template never falls back to scalar printing or YAML output.
|
||||
- [ ] Text without a template prints strings, nonempty string lists, numbers,
|
||||
and booleans directly; structured values, empty collections, and null use the
|
||||
shared YAML renderer. Cover explicit `--format text` for those values without
|
||||
introducing a separate pretty-printer.
|
||||
- [ ] The integration chooses concise/detailed content; changing format does
|
||||
not implicitly change the selected detail level. Core owns rendering and
|
||||
delivery in both templated and non-templated paths.
|
||||
- [ ] The invocation and writer-based public APIs share rendering behavior;
|
||||
handlers submit report data without their own format switches or encoder
|
||||
setup. Existing quiet-mode, presentation-failure, and domain-outcome behavior
|
||||
is preserved through the Reporter lifecycle.
|
||||
- [ ] Core-serialized ordinary Go reports follow the standard JSON contract,
|
||||
including JSON tags, supported custom serialization, and selected omissions.
|
||||
Conflicting YAML tags do not rename fields or change values in YAML output.
|
||||
Verify that automatic selection follows the resulting logical shape.
|
||||
- [ ] Representative reports retain null/false/zero/empty distinctions and
|
||||
numeric values through conversion, including large integers. Unsupported
|
||||
values and serialization failures remain observable presentation failures.
|
||||
- [ ] Safe inspection YAML is explicitly converted to ordinary Go report values
|
||||
in core and uses the shared renderers. Preserve types, presence/null/empty
|
||||
distinctions, numeric precision, sequence order, and redaction. Do not require
|
||||
mapping order or source formatting, or substitute runtime configuration structs.
|
||||
Conversion failures are observable; ordinary strings are not parsed as YAML.
|
||||
- [ ] A superseding ADR records the replacement of native-writer, mapping-order,
|
||||
and separate-document requirements in ADR 0007 and the combined-display ordering
|
||||
requirement in ADR 0009; canonical contracts are updated with implementation.
|
||||
- [ ] `config show --scope all` hands off one mapping keyed by scope identifier,
|
||||
including when only one scope is registered. All formats retain scope identity
|
||||
and safe values without injecting metadata into configuration fields. Cover
|
||||
configurations with fields named `scope` or `config`, single-scope unwrapped
|
||||
output, and failure before combined display. Do not assert aggregate scope order.
|
||||
- [ ] Core, both integrations, and a maintained application-owned command
|
||||
exercise the public reporting capability. Suitable duplicate selection and
|
||||
encoding code is removed; core has no optional integration dependencies.
|
||||
- [ ] 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.
|
||||
- [ ] `promptkit show prepared PROMPT_ID` forwards the intended request and
|
||||
faithfully reports native fields, using automatic selection and accepting
|
||||
universal format choices.
|
||||
Help identifies the argument as a prompt ID and explains resource I/O and
|
||||
rendered content disclosure. 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 and configuration overrides follows the same
|
||||
policy in OD-2 and OD-11, including nested values and input-error behavior.
|
||||
- [ ] The small, centralized internal CLI JSON conversion helper documents the
|
||||
numeric policy and its rationale in code comments. Cover integer boundaries,
|
||||
decimal/exponent forms, nested objects/arrays, and range errors. Accept ordinary
|
||||
floating-point approximation; do not add arbitrary-precision fallbacks or a
|
||||
public/general-purpose numeric conversion API.
|
||||
- [ ] The same public execution-flag collection works in a standard subcommand
|
||||
and an application-owned command with its own typed input. Parsing, presence,
|
||||
metadata, and selected subsets remain consistent; omitted retry values retain
|
||||
the applicable native defaults. Application execution behavior remains outside
|
||||
the collection.
|
||||
- [ ] Canonical `--llm-` flags and scoped convenience aliases follow OD-2.
|
||||
Alias generation covers only enabled commands and applicable flags, shares
|
||||
canonical binding/presence behavior, and preserves mixed-spelling occurrence
|
||||
order. Generic spellings remain available to unrelated application commands.
|
||||
- [ ] The convenient installation collection includes commands and their scoped
|
||||
aliases; canonical-only installation remains available. Help and migration
|
||||
guidance explain both forms without requiring consumer-maintained alias lists.
|
||||
- [ ] Text and file input names and aliases follow OD-2. Literal content,
|
||||
including empty text, reaches native inline inputs; file bindings remain file
|
||||
references. Examples, help, and documentation use the selected meanings.
|
||||
Verify that the last command-line occurrence for a name wins across text/file
|
||||
forms and all aliases, preserving actual occurrence order.
|
||||
- [ ] Output-contract override and appended-message flags remain outside this
|
||||
adoption, with their operator use cases retained in future work.
|
||||
- [ ] Opt-in namespace selectors combine declared suite defaults with supplied
|
||||
fields in one native view update. Omission preserves each declared default;
|
||||
explicit empty values clear only the selected default. Qualified selections
|
||||
and catalog filters retain their native meanings. Custom scoped loaders remain
|
||||
usable without the option. Canonical namespace names and scoped aliases match
|
||||
OD-3 and its agreed applicability table. Requirements inspection retains
|
||||
optional profile selection and profile namespace resolution; help explains
|
||||
that the profile establishes report identity, not discovered dependencies.
|
||||
Cover prompt-default fallback, missing profile selection, and explicitly
|
||||
selected short profile IDs without rewriting configured default references.
|
||||
- [ ] The full configuration suite retains six subcommands. Explanation
|
||||
discovery and validation diagnostics are modes of existing commands, with
|
||||
capability-aware help and selected mode/flag combination checks.
|
||||
- [ ] Bare `config explain` displays help successfully, presenting `--list` and
|
||||
`--path` as the two alternatives. Selecting both modes is a usage error;
|
||||
explicitly supplied `--path ""` selects root explanation rather than help.
|
||||
- [ ] Discovery supplies a compact text template, which core selects when no
|
||||
format is requested, with compact path/presence/explicitness fields and the
|
||||
selected `--historical`, `--under`, and `--explicit` behavior. Historical-only
|
||||
paths and unavailable discovery are not misreported as current implicit
|
||||
values or an empty configuration.
|
||||
- [ ] Metadata discovery through `config explain` distinguishes effective and
|
||||
historical paths, retains available history on absent lookup, and projects
|
||||
native field/change records.
|
||||
- [ ] Default `config diff` retains its concise additions/changes/deletions
|
||||
report. Optional `--details` uses the same comparison records to present both
|
||||
snapshots and presence/redaction/hidden-change evidence. Cover additions,
|
||||
deletions, explicit null, empty comparisons, sequence-level changes, and
|
||||
report-delivery failures without extra configuration loads or comparisons.
|
||||
Detailed YAML uses one before/after entry per path and an explicit empty list
|
||||
when there are no differences.
|
||||
- [ ] Focused display preserves native snapshot content and distinguishes
|
||||
missing/historical-only paths from explicit null. Whole-document display
|
||||
preserves safe inspection values through the shared renderers. Focused display
|
||||
uses one scope and hands off the logical value without a snapshot wrapper or
|
||||
text template; core applies automatic or explicit selection. Absent effective
|
||||
paths and unknown source IDs produce clear operational failures.
|
||||
- [ ] Source-ID selection works on successful and failed acquisitions. Path,
|
||||
explicitness, severity, and code filters preserve the selected evidence and
|
||||
source references without masking the acquisition outcome.
|
||||
- [ ] Comparison sides start independently from ordinary application defaults.
|
||||
Supplied config/overlay selections, domain selectors, and their presence apply
|
||||
only to their own side, including repeatable values. Cover left-only,
|
||||
right-only, both-side, neither-side, and partially supplied right selections;
|
||||
no omitted right field inherits from the left. Preserve side-specific checks
|
||||
and the shared-state lifecycle. Command-wide controls remain shared.
|
||||
- [ ] A superseding ADR records OD-9's replacement of ADR 0012's inheritance and
|
||||
shared-selector application rules. Update canonical CLI/API contracts and
|
||||
examples with implementation, including cases that now require repeating a
|
||||
common nondefault selection on both sides.
|
||||
- [ ] Assertion mode distinguishes equality, native differences (including
|
||||
hidden changes), usage errors, and operational failures with statuses
|
||||
`0`, `3`, `2`, and `1` respectively, without changing ordinary diff outcomes.
|
||||
Report-delivery failures remain observable.
|
||||
- [ ] Only supplied CLI overrides reach opted-in loaders under OD-11, with typed
|
||||
values and safe flag labels. `--set` applies only to the left comparison side,
|
||||
and `--against-set` only to the right; omission supplies no CLI override records
|
||||
for that side. Native errors and returned provenance are preserved. No tests
|
||||
independently re-establish ConfigKit override semantics.
|
||||
- [ ] Override flags accept only `POINTER=JSON`, split at the first `=`. Help
|
||||
documents unsupported paths containing `=`; no alternate record syntax,
|
||||
escaping scheme, or override-file option is added. Forward records through
|
||||
normal acquisition without CommandKit conflict resolution, deduplication,
|
||||
precedence rules, or retries with altered values. Preserve upstream errors.
|
||||
- [ ] Default validation remains concise; `--details` selects the additional
|
||||
diagnostic report with a text template. Core automatically selects text when
|
||||
that template is supplied, while explicit formats still win. Changing format
|
||||
alone does not enable detailed mode.
|
||||
Severity/code filters, evidence availability, no-match presentation, and
|
||||
known duplicate-warning handling preserve the underlying validation outcome.
|
||||
- [ ] `config sources` and `config validate --details` report
|
||||
available evidence 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, including
|
||||
collection reuse by an application-owned command.
|
||||
- [ ] Suitable reports use direct Go-value serialization or thin projections,
|
||||
sharing the core representation and rendering machinery. Necessary adapters
|
||||
preserve native meaning without duplicating a full report tree per format.
|
||||
- [ ] 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.
|
||||
The linked sections own behavior; these checks cover consequential boundaries
|
||||
rather than prescribing one test per line or exact cosmetic snapshots.
|
||||
|
||||
- [ ] Public report/writer APIs, the CLI JSON parser, and ordered typed input
|
||||
composition are documented. Maintained consumers exercise applicable APIs, and
|
||||
both integrations build independently. Core has no integration dependency.
|
||||
- [ ] Universal format selection follows the agreed precedence and logical shapes.
|
||||
Cover explicit choices, templates, scalars, empty/nonempty collections, null,
|
||||
invalid formats before acquisition, flag collisions, and invocation isolation.
|
||||
New formats require no handler changes or local allowlists.
|
||||
- [ ] JSON interpretation and explicit safe-YAML conversion preserve selected
|
||||
field omissions, numeric values, type/presence/null/empty distinctions, sequence
|
||||
order, and redaction. Unsupported serialization/conversion remains observable.
|
||||
Ordinary strings are not implicitly parsed as YAML; mapping order is not a test
|
||||
requirement. Do not substitute runtime configuration for inspection snapshots.
|
||||
- [ ] Templates receive original Go values and standard template behavior.
|
||||
Explicit YAML/JSON does not execute a template; errors never trigger fallback.
|
||||
Untemplated text follows the selected scalar/string-list or YAML rules.
|
||||
- [ ] 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
|
||||
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.
|
||||
- [ ] 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
|
||||
evidence in one report. Default tests need no live credentials or model calls.
|
||||
- [ ] OD-1 preview forwards the request, calls preparation once, and projects
|
||||
native evidence without a model call or retained execution handle. Help explains
|
||||
the prompt-ID argument, resource I/O, and rendered-content disclosure.
|
||||
- [ ] OD-2 collections work in standard and application-owned commands with their
|
||||
own typed inputs. Preserve selected subsets, omission/empty/zero values,
|
||||
upstream retry defaults, authoritative builders, and native map replacement.
|
||||
- [ ] CLI JSON parsing follows OD-2 for provider objects and configuration values.
|
||||
Cover nested values, integer boundaries, decimal/exponent forms, range errors,
|
||||
and ordinary float approximation. The private helper documents the policy and
|
||||
its limits; no arbitrary-precision fallback or public numeric framework appears.
|
||||
- [ ] Canonical flags and scoped aliases follow OD-2; generated aliases cover
|
||||
enabled/applicable bindings, preserve presence, and do not claim unrelated
|
||||
application spellings. Canonical-only and convenient installation both work.
|
||||
- [ ] Ordered composition selects the last text/file occurrence for each input
|
||||
name, including mixed aliases, while retaining literal empty text and file
|
||||
references. Cover reordered/interleaved flags, conversion failures, and fresh
|
||||
invocations. No prompt-input flags are added to smoke tests.
|
||||
- [ ] OD-3 namespace composition and applicability match the native boundary.
|
||||
Cover defaults, explicit clearing, qualified IDs, and preservation of unrelated
|
||||
defaults/catalog filters. Requirements help explains profile identity; cover
|
||||
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.
|
||||
- [ ] 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.
|
||||
- [ ] OD-5 concise/detailed diff reuse the same native records and loads. Cover
|
||||
additions/deletions, missing versus null, redaction/hidden changes, empty results,
|
||||
atomic sequence changes, and delivery failure through the shared renderers.
|
||||
- [ ] OD-6 validation and failed-load source evidence preserve failure and
|
||||
unavailable-versus-empty distinctions. Filters and known duplicate-message
|
||||
coordination do not mask outcomes. Aggregate validation submits one document
|
||||
with reached-scope evidence after stopping on acquisition failure/cancellation;
|
||||
no unvisited scope is reported valid. Test the changed delivery timing and
|
||||
separate operation/presentation failures without promising writer rollback.
|
||||
- [ ] OD-8 focused values and source selection respect capability availability,
|
||||
one-scope path selection, absent versus null, unknown IDs, and acquisition
|
||||
failure. Filters retain source references without changing validation outcomes.
|
||||
- [ ] OD-9 comparisons cover left-only, right-only, both/neither, and partially
|
||||
specified sides, including repeated values and supplied state. Each side starts
|
||||
independently; command-wide controls and the shared-state lifecycle remain
|
||||
shared. Explicit-empty application selectors stay application-defined.
|
||||
- [ ] OD-10 assertion outcomes distinguish equality, changes, usage, and failures;
|
||||
concealed changes count. Ordinary diff behavior and nonzero domain outcomes
|
||||
survive presentation failure according to the reporting contract.
|
||||
- [ ] OD-11 parses only the selected assignment syntax, forwards explicit values
|
||||
and safe labels to the correct side during loading, and preserves upstream
|
||||
errors/provenance. Help documents unsupported `=` paths. No alternate input,
|
||||
deduplication, conflict/precedence policy, or altered-value retry is added.
|
||||
- [ ] Maintained simple/composed consumers demonstrate the new CLI tasks and
|
||||
failure workflow with deterministic fixtures. Code remains proportionate:
|
||||
thin projections, one shared rendering implementation, and focused tests.
|
||||
- [ ] Superseding ADRs record changes to ADR 0007/0009 reporting and ADR 0012
|
||||
comparison. Update CLI/API contracts, release notes, and examples with the
|
||||
implementation, including validation delivery timing. Incorporate the ownership
|
||||
principles into architecture.md and replace obsolete native-YAML/document-order
|
||||
guidance in testing policy. Current documentation must match the landed scope.
|
||||
- [ ] Final independent-module and aligned-workspace suites pass with dependency
|
||||
identities recorded. Deferred features remain outside this adoption.
|
||||
|
||||
With the documented Go 1.27.0 toolchain selected, run
|
||||
`GOWORK=off GOTOOLCHAIN=local go test ./...` independently in the root,
|
||||
@@ -906,21 +779,12 @@ performs application startup effects.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
These decisions concern significant choices within the proposed scope. Resolved
|
||||
items retain their numbers and record the agreed decision. OD numbers are local
|
||||
to this roadmap, not the retired adoption documents.
|
||||
|
||||
The core ownership, JSON representation conventions, text printing/templates,
|
||||
universal-format, automatic-selection, and joint format-delivery decisions are
|
||||
now agreed above. Remaining details are listed under
|
||||
[remaining core reporting implementation details](#remaining-core-reporting-implementation-details).
|
||||
CLI JSON number decoding for both integrations, namespace applicability, and
|
||||
independent comparison defaults are agreed. OD-9 is settled: explicit-empty
|
||||
application selectors remain with application-declared bindings for this release.
|
||||
OD-11's assignment syntax and pass-through loading policy are also settled.
|
||||
All numbered decisions below are resolved for this adoption. Exact helper
|
||||
signatures, typed binding composition, loader wiring, flag collision handling,
|
||||
and report layouts remain implementation choices, not unresolved scope.
|
||||
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.
|
||||
|
||||
### OD-1: Preview command and report presentation
|
||||
|
||||
@@ -946,10 +810,12 @@ dedicated preview template; a specialized template is not required for initial d
|
||||
### OD-2: Request controls and provider-parameter grammar
|
||||
|
||||
**Agreed:** execution flags are public reusable CLI collections owned by
|
||||
`ckprompt`, available to standard and application-owned commands using existing
|
||||
core APIs. Give validation and preview the applicable execution controls already
|
||||
on smoke tests, and add a singleton `--llm-extra-params JSON` object option to
|
||||
all three. Use native whole-map replacement, including native behavior for
|
||||
`ckprompt`, available to standard and application-owned commands. Collections
|
||||
and aliases use existing declarations; JSON parsing and cross-flag ordering use
|
||||
the [core input prerequisites](#shared-core-cli-input-prerequisites). Give
|
||||
validation and preview the applicable execution controls already on smoke tests,
|
||||
and add a singleton `--llm-extra-params JSON` object option to all three.
|
||||
Use native whole-map replacement, including native behavior for
|
||||
empty maps. The single-object form is selected over repeated key assignments.
|
||||
|
||||
**Agreed CLI JSON number policy:** pass ordinary Go numeric values to PromptKit
|
||||
@@ -971,9 +837,9 @@ value could be an integer:
|
||||
|
||||
Keep this in one small, centralized internal helper dedicated to CLI JSON input.
|
||||
Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose
|
||||
number conversion package, public conversion API, or extensible numeric framework
|
||||
is selected. CommandKit is a Go library for Go applications and deliberately
|
||||
accepts the precision and range of these Go types. It does not compensate for
|
||||
number conversion package, public numeric conversion API, or extensible numeric
|
||||
framework is selected. CommandKit is a Go library for Go applications and
|
||||
deliberately accepts the precision and range of these Go types. It does not compensate for
|
||||
their limits with alternate numeric representations.
|
||||
|
||||
**Required implementation comments:** document the syntax-based type selection,
|
||||
@@ -984,8 +850,8 @@ intentional policy, not a missing feature to work around later.
|
||||
|
||||
This policy governs parsed CLI provider parameters and configuration override
|
||||
values, not application-supplied runtime values or core report serialization.
|
||||
Centralize the bounded CLI JSON conversion utility; its placement across the
|
||||
independent modules is an implementation task that must respect module ownership.
|
||||
The [public CLI parsing boundary](#public-cli-json-parsing-boundary) shares this
|
||||
policy across modules while retaining private numeric conversion.
|
||||
Reusing number conversion does not unify the libraries' different override
|
||||
semantics or introduce a general-purpose conversion facility.
|
||||
|
||||
@@ -1077,9 +943,9 @@ flags to smoke tests, which use their own diagnostic content.
|
||||
**Agreed input precedence:** the last command-line occurrence for a given input
|
||||
name wins across text and file bindings, including every alias. Implementation
|
||||
must preserve actual occurrence order rather than applying one flag collection
|
||||
after the other in a fixed order. Select the necessary binding composition
|
||||
during implementation; do not claim this behavior from independent flag binding
|
||||
alone.
|
||||
after the other in a fixed order. Use the core
|
||||
[ordered typed input composition](#ordered-typed-input-composition) prerequisite;
|
||||
independent flag binding alone does not supply this behavior.
|
||||
|
||||
**Deferred output-contract overrides:** no CLI override is included in this
|
||||
adoption. Retain the candidate in
|
||||
@@ -1288,18 +1154,30 @@ introducing a general diagnostics framework.
|
||||
|
||||
Structured results use the result stream and ordinary messages use the
|
||||
diagnostic stream. Preserve report-delivery failures separately from the original
|
||||
operation failure through existing outcome handling. Retain current aggregate
|
||||
stopping behavior; detailed output does not promise exhaustive validation across
|
||||
all scopes. Partial-evidence and cancellation presentation should use the same
|
||||
simple report values and existing reporting lifecycle, with exact layout refined
|
||||
during implementation and practical testing.
|
||||
operation failure through existing outcome handling.
|
||||
|
||||
**Agreed aggregate delivery:** for `config validate --scope all`, collect results
|
||||
for the scopes reached and submit one report after acquisition completes or
|
||||
stops. Stop at the first acquisition failure or cancellation; retain completed-scope
|
||||
results and available evidence from the failing scope. Do not claim unvisited scopes
|
||||
were validated. Apply the same aggregation to concise and detailed modes, using
|
||||
one ordinary report value and the shared renderers, including one JSON document.
|
||||
|
||||
This deliberately changes delivery timing: scope results are no longer written
|
||||
one at a time during acquisition. Output failures are observed after acquisition
|
||||
has stopped and cannot prevent already-completed loads. Preserve the original
|
||||
operation failure and separate presentation failure under the existing outcome
|
||||
rules. This replaces the old output-failure stopping behavior; it does not add
|
||||
exhaustive validation, whole-invocation buffering, or writer rollback. Diagnostics
|
||||
retain their existing lifecycle. Update the canonical validation contract and
|
||||
its focused failure tests when this lands.
|
||||
|
||||
### OD-7: Module release and interim workspace coordination
|
||||
|
||||
**Agreed:** complete the core reporting prerequisite and planned integration work
|
||||
together rather than splitting out a dependency-only PromptKit release. With no
|
||||
**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.
|
||||
Prepare the core release supplying the reporting API, then a new ckconfig minor
|
||||
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
|
||||
new API, and ckprompt must require the ckconfig version supplying the shared
|
||||
@@ -1452,14 +1330,10 @@ combination or precedence policy for application-owned overrides, or retry with
|
||||
altered values. Application loading retains its existing responsibilities.
|
||||
Exact loader signatures and wiring remain implementation design tasks.
|
||||
|
||||
**Agreed numeric conversion:** adopt the ordinary Go numeric policy in OD-2 for
|
||||
both `--set` and `--against-set`, including nested objects and arrays. Integer
|
||||
syntax uses `int64`, with `uint64` for larger representable nonnegative values;
|
||||
decimal or exponent syntax uses `float64`. Accept ordinary floating-point
|
||||
approximation and report numeric range errors as input errors. Temporary
|
||||
`json.Number` values are converted before forwarding to ConfigKit. Use the same
|
||||
small, centralized internal CLI JSON utility and required policy comments;
|
||||
no arbitrary-precision fallback or public numeric conversion API is selected.
|
||||
**Agreed numeric conversion:** both assignment flags use the
|
||||
[OD-2 numeric policy](#od-2-request-controls-and-provider-parameter-grammar),
|
||||
including nested values, through core's public CLI JSON parser. ConfigKit receives
|
||||
ordinary Go values; the shared numeric helper and policy comments remain private.
|
||||
|
||||
**Agreed comparison behavior:** `--set` supplies override records only to the
|
||||
left side; `--against-set` supplies records only to the right. Each side starts
|
||||
|
||||
Reference in New Issue
Block a user