Record ConfigKit review finding

This commit is contained in:
2026-11-17 23:51:33 +00:00
parent eec4fa2d91
commit 65bd2da51a

View File

@@ -1,5 +1,98 @@
# Implementation Review Remediation # 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 ## PromptKit v0.12.0 Review
Reviewed on 2026-10-04 at Reviewed on 2026-10-04 at