diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 7cd10c9..ad95eff 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -1,5 +1,98 @@ # Implementation Review Remediation +## ConfigKit v1.2.0 Interim Adoption Review + +Reviewed on 2026-11-17 at +`eec4fa2d91beca68b176dcf20026a0c7e5a7b7bf`, covering the seven implementation +commits after `222f405`. The review followed each stage of the +[implementation plan](implementation.md) against the code, tests, examples, +documentation, and [feature roadmap](configkit.md). + +The runtime architecture matches the selected interim target. Application +configuration uses public ConfigKit v1.2.0 with native discovery, composition, +post-decode CLI assignment, recorded leaf normalization, and final domain +validation. PromptKit v0.12.0 retains old-path ConfigKit v0.5.0 for framework +sources and captured inspection. Each generation's paths, diagnostics, and +writers remain separate; the shared YAML dependency stays at v4.0.0-rc.6. +No runtime correctness defect, unnecessary compatibility layer, or unrequested +runtime restriction was found. One documentation contract overstatement remains. + +| Stage | Review result | +| --- | --- | +| 1: Dependencies and toolchain | Both ConfigKit identities, unchanged PromptKit/catalogs/YAML, Go 1.27.0 consumer minimum, and Go 1.27.4 release image are selected as planned. | +| 2: Native application loading | One native load owns discovery and processing; application callbacks retain schema/domain responsibilities and leaf recording. | +| 3: Adapter type separation | Application and framework values use their respective public types; structured errors and warnings reach the matching native writer. | +| 4: Configuration coverage | Tests cover discovery, optional/required imports, placement, authored collections, CLI timing, presence, normalization, and inspection without new application identity rules. | +| 5: Integration and examples | New application controls coexist with old framework controls; ordinary, composed, inheritance, and collection examples work, including overlay retention. | +| 6: Documentation and attribution | Dependency/toolchain ownership and both notices are aligned; selector-clearing language still overstates the native contract (R6). | +| 7: End-state validation | Independent tests, builds, example commands, dependency checks, and document checks passed; R6 must be resolved for complete documentation alignment. | + +### R6: Qualify Selector Clearing By The Effective Collection Policy + +Priority: P3 (low). Status: Open. + +Locations: `docs/config.md:62–64` and `docs/config.md:108–109`. + +The selector reference says that omitting `promptkit_sources` or setting it to +`[]` or `null` selects no application-supplied framework sources. The overlay +description also says that explicit nulls replace without qualifying collection +operations. Those statements retain the former simple-list contract even +though the upgrade now exposes native authored collection policies. The later +general statement that policies may combine lists does not explain the +different empty/null behavior. + +Evidence: with this application main document: + +```yaml +config: + sequences: + - destination: [promptkit_sources] + key: file + mode: upsert +promptkit_sources: + - file: ./base-framework.yml +``` + +an overlay containing `promptkit_sources: []` makes `config show` succeed and +retain `base-framework.yml`. An overlay containing `promptkit_sources: null` +instead exits 1 with `sequence.invalid`: append and upsert require a sequence +contribution. These checks used the reviewed binary and temporary application +files; no framework file or provider was needed. The results agree with +[ConfigKit's pinned collection contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime). + +Required change: distinguish an empty final resolved selector list from an +authored source contribution. Under ordinary replacement, an empty list clears +the selection and an allowed null produces no selectors. Under append/upsert, +`[]` contributes no records and null is invalid; omission preserves lower +contributions. Explain or link to the native way to clear an identified +collection: select `mode: replace` at that destination and supply `[]`. +Qualify the overlay null statement accordingly. + +This is a documentation fix. Preserve ConfigKit's current behavior and the +existing CLI whole-list override semantics; do not add special-case clearing, +new validation, or a compatibility merge pass to satisfy the old wording. + +Acceptance: the selector and overlay descriptions agree with the pinned native +contract and the reproduced empty/null cases. Check the affected links and any +added example. No production-code change or new runtime guarantee is required. + +### Independent Review Verification + +- `go test -count=1 ./...`, `go test -race -count=1 ./...`, and `go vet ./...` + passed with Go 1.27.4 and a provisioned offline cache. +- A native binary and Linux amd64/arm64 binaries built outside the worktree; + cross-builds used the existing cgo-disabled, trimpath, stripped settings. +- All six maintained configuration/overlay selections passed application + validate/show/sources/explain, framework validate/sources, and JSON render. + Framework show/explain also passed. Selected credential variables were unset; + no generation command or live provider was invoked. +- The selected module and executable dependency graphs, `go mod tidy -diff`, + changed-Go formatting, diff whitespace, affected local documentation links, + workflow YAML/shell syntax, both ConfigKit notice revisions, and shared + LGPL/GPL text fidelity were checked. No workspace or vendor tree is committed. +- The only repository change made by this review is this remediation record. + Historical findings below are retained unchanged. + ## PromptKit v0.12.0 Review Reviewed on 2026-10-04 at