From 9b85c7cf605724e1f6f5b199320f43ee712aaa77 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 02:04:57 +0000 Subject: [PATCH] Consolidate adoption roadmap and finalize core prerequisites --- docs/roadmap/future.md | 105 ++--- docs/roadmap/promptkit-v0.19.0.md | 720 ++++++++++++------------------ 2 files changed, 330 insertions(+), 495 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 11951d6..80858ef 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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. diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index bdf2173..d322bef 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -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