From ee3cb21ebc145400c90019c4eba3cfc82dc987a6 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 01:46:09 +0000 Subject: [PATCH] Settle override syntax and pass-through loading policy --- docs/roadmap/future.md | 10 +++-- docs/roadmap/promptkit-v0.19.0.md | 62 +++++++++++++++++++------------ 2 files changed, 45 insertions(+), 27 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 128edc9..11951d6 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -37,7 +37,7 @@ The published ckprompt v0.2.0 retains its earlier dependencies; see the 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, open decisions, and completion checklist. Scope is +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. @@ -96,9 +96,11 @@ 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. Loader composition and -unusual path syntax remain design tasks. Persistent configuration editing remains -deferred. +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. Discovery, import defaults, collection identities, and field-level resolution recording remain available through application loaders. Discovery tracing, diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index f1b1897..bdf2173 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -148,8 +148,8 @@ or diagnostics subcommand is planned. Transient configuration overrides are included under OD-11 as an opt-in loader capability. `config validate --set /workers=0` and `config show --set /server/port=8080` apply temporary overrides during acquisition -without editing source files. Unusual pointer keys, loader composition, and -supplemental input grammar remain to be finalized. Comparison +without editing source files. OD-11 selects simple assignment syntax and normal +load-time forwarding; paths containing `=` are unsupported by these flags. Comparison overrides follow OD-9's independent-side model: `--set` affects only the left side and `--against-set` only the right. @@ -624,7 +624,7 @@ incidental formatting detail in tests. 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. - Resolve outstanding acquisition/binding grammar and flag collisions; use + 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 @@ -836,6 +836,11 @@ Default tests remain offline and independent of real credentials. 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 @@ -912,9 +917,10 @@ now agreed above. Remaining details are listed under 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. -The remaining open decision is OD-11, covering unusual-path grammar and loader -composition. Exact helper signatures, typed binding composition, flag collision -handling, and report layouts remain implementation choices, not unresolved scope. +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. ### OD-1: Preview command and report presentation @@ -1426,10 +1432,26 @@ application acquisition as native ConfigKit overrides. This enables validation, inspection, and comparison of temporary settings through consistent CLI syntax. Providers that do not accept overrides retain their existing operations. No source file is edited, and no general application-internal convenience API is -required. The loader contract must state how it combines these records with -any existing application-owned overrides; the generic adapter cannot inject +required. Supply parsed records during the normal configuration load, like any +other explicitly supplied CLI overrides; the generic adapter cannot inject them into an arbitrary loader after the load has completed. +**Agreed input syntax:** support only `POINTER=JSON`, split at the first `=`. +Paths containing `=` are unsupported by `--set` and `--against-set`. Document +this limitation in help; do not add alternate JSON-record syntax, an escaping +scheme, or an override-file option. This limits these flags rather than banning +such keys elsewhere in configuration. The JSON value may itself contain `=`. + +**Agreed loading boundary:** CommandKit parses supplied assignments, preserves +explicit values and safe source labels, and passes the records to the appropriate +loader and comparison side. ConfigKit owns path validity, duplicate/overlap +handling, precedence, resolution, and validation. If the normal load returns a +ConfigKit error, preserve and report it through the existing diagnostic/outcome +path. CommandKit does not deduplicate records, resolve conflicts, invent a +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; @@ -1453,27 +1475,21 @@ Repeat the same `--set` assignments as `--against-set` assignments when both sides should use them. There is no shared CLI override baseline and no `--against-clear-set` flag is needed to undo inheritance. -Prefer inline assignments for ordinary one-value experiments. This is the -largest remaining loader integration design item; revisit scope explicitly if -the required acquisition changes prove disproportionate rather than silently -dropping the agreed feature. Settle these details before implementation: +Implement the selected handoff without reimplementing upstream behavior: - Split at the first `=`; JSON supplies typed null, boolean, string, numeric, - array, and object values, with the agreed numeric policy above. An unambiguous - alternate input form may be needed for pointer keys containing `=`. + array, and object values, with the agreed numeric policy above. - Forward explicit records only, with safe display labels such as `--set`, never raw value-bearing arguments as provenance labels. Preserve native duplicate/overlap handling rather than silently collapsing assignments. -- Follow the released mapping-path constraints, including root/index and - schema-version restrictions, without extending them into a generic patch - language. Empty, false, zero, and null remain intentional supplied values. +- Let ConfigKit enforce its released mapping-path constraints, including + root/index and schema-version restrictions, without introducing a generic + patch language. Empty, false, zero, and null remain intentional supplied values. - Reflect native CLI origins and subsequent resolution in existing reports. Test CommandKit parsing, forwarding, and outcome/report adaptation, leaving ConfigKit's override algorithm to its own tests. -A structured override file is not selected as the primary interface: it handles -complex values and unusual keys well but adds file setup to ordinary one-value -experiments. It remains a possible supplemental form if needed to resolve the -open grammar cases. Application-specific typed flags remain available, but are -not a substitute for the selected standard CLI capability. No persistent -configuration mutation is authorized by this decision. +Application-specific typed flags remain available, but are not a substitute for +the selected standard CLI capability. No persistent configuration mutation is +authorized by this decision. OD-11 requires no further operator-policy decision +for this adoption.