Clarify source selector clearing behavior
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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 ./...`
|
||||
|
||||
Reference in New Issue
Block a user