diff --git a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md index 7273a81..9c2745b 100644 --- a/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md +++ b/docs/roadmap/configkit-v1.4.0-promptkit-v0.24.0.md @@ -28,7 +28,7 @@ Reviewed repository revision: `b1c7962f51eb9e81104a291bc1966a90b4e772a3`. | Component | Baseline | Adoption target | | --- | --- | --- | | CommandKit core | v0.7.0 | No core change required by this scope | -| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0 and native scoped path enumeration support | +| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0, native scoped path enumeration, and a public native-inspection adapter | | ckprompt | v0.10.0; PromptKit v0.23.2, ConfigKit v1.2.1, ckconfig v0.9.0 | PromptKit v0.24.0, ConfigKit v1.4.0, and the resulting released ckconfig | | Go | Consumer minimum 1.27.0; release toolchain 1.27.4 | No change required by these upstream releases | @@ -121,6 +121,28 @@ their native whole-document meaning. An absent effective subtree and explicit null retain their upstream distinction and errors through the existing report delivery mechanism. Do not invent an empty configuration to hide absence. +### Public native-inspection adapter + +Include a reusable ckconfig adapter in this adoption and the next ckconfig +release. It registers a named configuration scope backed by ConfigKit's native +subtree inspection, reducing application wiring for effective settings, path +discovery, explanations, source evidence, and comparison. Applications retain +configuration acquisition and selection; the adapter supplies standard CLI +integration and delegates domain operations to ConfigKit. + +Design this adapter together with the shared native path-enumeration capability. +Demonstrate one application section, such as storage settings, in the maintained +composed example. The section name is illustrative, not a new reserved scope. +Preserve load diagnostics and error evidence through existing reporting and +outcome conventions. A focused inspection does not independently validate a +subtree or make whole-load evidence local to it. + +PromptKit uses the shared inspection capability directly. It need not pass +through this new helper if that would require converting its public inspection +type merely to fit the helper. Exact API shape and evidence handoff remain under +discussion in OD-2; acceptance of the feature does not select a new result type, +loader framework, or diagnostics policy. + ### Existing commands expose the new upstream evidence | Operator task | Existing command | Adoption behavior | @@ -174,8 +196,14 @@ resources and reports, not just successful engine construction. ### Adapter and example work -- Implement scoped enumeration through the shared configuration provider boundary - and wire the native PromptKit method directly. +- Design the adapter's public API and evidence handoff, then implement scoped + enumeration through the shared configuration provider boundary and the public + ckconfig adapter together. Reuse existing acquisition, diagnostics, comparison, + and outcome conventions where they serve the native capability. +- Wire PromptKit's native enumeration directly through the shared capability; + avoid an extra conversion layer solely to reuse the new adapter. +- Demonstrate registration and inspection of one application subtree, including + comparison and preservation of available diagnostics on failure. - Restructure the composed example around the shared load, with local fixtures and the existing injected client for smoke demonstrations. Update its consumer walkthrough and meaningful tests together. @@ -225,6 +253,9 @@ layout or hash literals. Tests remain offline and credential-independent. - [ ] Scoped path enumeration uses upstream's listing; existing CLI filters and metadata descriptions still work. A representative whole-load sibling verifies that the adapter does not substitute full metadata enumeration. +- [ ] The public ckconfig adapter exposes a native subtree through the standard + scope commands, with a maintained example and focused coverage of acquisition, + comparison, and diagnostics/error propagation. Its public handoff is documented. - [ ] Explicit paths, source evidence, focused rendering, and comparison preserve native meaning and error handling, including available ancestor evidence. - [ ] Reports preserve returned schema fields, repair-budget zero, and the new @@ -250,33 +281,47 @@ This roadmap selects no new commands, engine-construction convenience API, automatic configuration migration, core cache, or application execution workflow. These are scope decisions for this adoption, not additional permanent prohibitions. +## Resolved decisions + +### OD-1: Include the native-inspection adapter in this adoption — closed + +Include the helper in the next ckconfig release, as part of this roadmap. +Its implementation overlaps the required native enumeration work; designing both +together provides a concrete second use of the shared boundary and avoids +revisiting that boundary immediately after release. Keep the adapter focused on +standard CLI scopes and direct upstream inspection. Preserve native comparison +semantics for the views accepted by the selected API. + +The previous deferral recommendation is superseded. The remaining API discussion +does not reopen whether to include the feature. + ## Open Decisions -### OD-1: Add a general native-inspection adapter to ckconfig now? +### OD-2: Public API and diagnostics/error handoff -ConfigKit's non-generic `Inspection` could support a reusable public adapter for -applications exposing additional subtree scopes, including native comparison -across different root Go types. This is separate from the required narrow path -enumeration support used by `ckprompt.ConfigScope`. +**Recommendation for discussion: accept the existing typed ConfigKit result +loader plus an explicit subtree path.** A sibling of `FromConfigKit` can obtain +diagnostics and source evidence from the result, select `InspectSubtree(path)`, +and delegate comparison to the native inspection views. On failed loading, +reuse the existing handling of ConfigKit load-error evidence and supported error +identity. This keeps the ordinary application loader reusable and avoids asking +applications to package inspection and diagnostics into a new envelope. The +tradeoff is that a callback returning only an already selected native inspection, +or different root result types across comparison sides, does not fit this typed +loader signature directly. The proposed name and signature are not yet selected. -**Recommendation: defer the additional public adapter from this sprint.** The -existing typed `FromConfigKit` adapter serves the application's result, and -`ckprompt.ConfigScope` serves the engine's inspection. Shared loading itself -does not require a third adapter. Keep the required native enumeration capability -small, and use the revised example to identify any actual remaining boilerplate -before selecting another public contract. The tradeoff is that applications -wanting additional native subtree scopes must currently assemble the existing -scope/provider contract themselves. +**Viable alternative: accept an already selected `configkit.Inspection` with +its associated acquisition evidence.** This directly serves callers holding +native views and allows native comparison across different root Go types. +However, the view itself has no diagnostics method, and a failed load may provide +sources and diagnostics without any usable view. The API would need a way to +carry that evidence, adding application wiring or a public handoff type. Evaluate +that complete handoff against the result-and-path approach before selecting it; +do not require callers to reconstruct provenance or stringify structured errors. -**Viable alternative: include a focused native-inspection adapter now.** This -could standardize useful CLI subtree scopes and avoid repeated acquisition and -comparison wiring across applications. It belongs in ckconfig because it serves -operator commands, not application-internal configuration access. However, native -`Inspection` does not itself carry the result's diagnostics or acquisition -errors; the helper's inputs must account for that evidence without becoming a -second result type or loader framework. Before selecting this alternative, -demonstrate a concrete scope in the maintained example and compare the complete -wiring burden and conceptual cost against using the existing provider API. - -This choice does not reopen the agreed requirement to delegate PromptKit path -enumeration and explicit queries to the native upstream methods. +For either approach, retain the existing distinction between report evidence +and a returned error. Discuss how native diagnostics reach detailed validation, +ordinary messages, and terminal explanations without duplicate presentation. +Existing error classification remains authoritative; the scope's reporting focus +does not imply that unrelated load failures can be ignored or that validation is +limited to the selected subtree.