Record ConfigKit review finding
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user