diff --git a/docs/config.md b/docs/config.md index b2182eb..78ae2dd 100644 --- a/docs/config.md +++ b/docs/config.md @@ -59,7 +59,7 @@ promptkit_sources: schema_dir: ./examples/schemas ``` -Omitting the field or setting it to `[]` (or `null`) selects no +An empty or null final resolved `promptkit_sources` list selects no application-supplied framework sources; Promptkit's selected catalog and maintained definitions still apply. A later sequence item overlays an earlier one. Files within a selected directory are composed together, so conflicting @@ -96,6 +96,16 @@ precedence boundaries. The [collection example](../examples/config.collections.y declares `file` identity with `upsert`, combines imported file selectors, and lets an overlay add another. CLI list overrides still replace the whole list. +At application precedence boundaries, omission preserves lower-precedence +selectors. Under ordinary list replacement, `[]` clears the selection and +`null` resolves to no selectors. Under authored `append` or `upsert`, `[]` +contributes no records and `null` is invalid. To clear a collection with an +inherited policy, declare `mode: replace` at +`destination: [promptkit_sources]` in the higher-precedence source and supply +`promptkit_sources: []`. See +[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime) +for policy lifetime and combination rules. + These application root `config` controls do not change the separate Promptkit v0.12.0 framework format: its selected framework files use the [Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) @@ -105,11 +115,13 @@ and its older ConfigKit controls. root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty and exact lowercase `default` select no overlay. There is no fallback, case folding, inherited stack, or automatic selection; a missing selected -overlay fails. Mappings merge and explicit nulls replace; sequence behavior -depends on any authored collection policy. Defaults-only loading can enable -imports, but an absent main has no import declarations. This CLI supplies no -independent overlay root, so an active overlay cannot be located without a -selected main context. That is not a general ConfigKit restriction. +overlay fails. Mappings merge; sequence contributions and nulls at collection +destinations follow the effective collection policy described above. Other +explicit nulls replace lower values subject to the application schema. +Defaults-only loading can enable imports, but an absent main has no import +declarations. This CLI supplies no independent overlay root, so an active +overlay cannot be located without a selected main context. That is not a general +ConfigKit restriction. The [composed example](../examples/config.composed.yml) imports the application [source-selection fragment](../examples/config-fragments/sources.yml) and has diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index ad95eff..b1fcb7b 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -15,7 +15,8 @@ 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. +runtime restriction was found. One documentation contract overstatement was +identified; its remediation is complete below. | Stage | Review result | | --- | --- | @@ -24,12 +25,12 @@ runtime restriction was found. One documentation contract overstatement remains. | 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. | +| 6: Documentation and attribution | Dependency/toolchain ownership and both notices are aligned; selector-clearing wording is now corrected (R6). | +| 7: End-state validation | Independent tests, builds, example commands, dependency checks, and document checks passed; R6's documentation alignment is now complete. | ### R6: Qualify Selector Clearing By The Effective Collection Policy -Priority: P3 (low). Status: Open. +Priority: P3 (low). Status: Complete. Locations: `docs/config.md:62–64` and `docs/config.md:108–109`. @@ -76,6 +77,17 @@ 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. +Resolution (2026-11-18): the configuration reference now distinguishes the final +resolved selector list from individual source contributions. It explains +omission, empty lists, nulls, and explicit replacement under the effective +collection policy, qualifies overlay null handling, and links to the pinned +upstream policy-lifetime contract. Runtime behavior and CLI whole-list overrides +are unchanged. All 15 temporary selector-policy checks passed against a fresh +build: omitted/empty/null/explicit-replace overlays under ordinary replacement, +append, and upsert, plus CLI whole-list replacement and no-generation rendering +under each policy. The pinned document and anchor and diff whitespace were +checked. No provider was contacted; no production code or tests changed. + ### Independent Review Verification - `go test -count=1 ./...`, `go test -race -count=1 ./...`, and `go vet ./...`