Record ConfigKit upgrade review findings

This commit is contained in:
2026-11-17 22:05:49 +00:00
parent d88a01cec0
commit 6f0a75e7cf

View File

@@ -1,4 +1,8 @@
# PromptKit Configuration Migration Review Remediation
# Configuration Upgrade Review Remediation
The earlier PromptKit findings below retain their original scope and status.
The ConfigKit 1.2.0 review and its two new findings are recorded in the final
section; they do not reopen or attribute earlier issues to that upgrade.
## Scope And Overall Assessment
@@ -191,3 +195,125 @@ verify the ADR link, and run `git diff --check`.
Recommended remediation is limited to these findings, not another configuration
system, new security policy, or unrelated pipeline refactoring.
## ConfigKit 1.2.0 Review
Reviewed on 2026-11-17 against implementation revision `c9744ad`, compared with
planning revision `79088a3` and the ConfigKit feature roadmap and implementation
plan. The subsequent roadmap-only clarification in `d88a01c` does not change
the reviewed runtime. ConfigKit v1.2.0 resolves to
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`.
The production architecture matches the target. Application configuration uses
new-path ConfigKit v1.2.0; the unchanged PromptKit v0.12.0 adapter retains
old-path ConfigKit v0.5.0. Both use YAML v4.0.0-rc.6 under Go 1.27.0. The CLI
describes one exclusive file or ordered native search source, while ConfigKit
owns acquisition, imports, collections, inheritance, decoding, diagnostics, and
inspection. Notarius supplies domain defaults, recorded normalization,
validation, detached runtime conversion, and catalog-dependent resolution.
No new production correctness defect or unwarranted restriction was found.
The changed controls, optional import defaults, post-decode CLI assignments,
step identity/upsert, search behavior, and higher Go minimum are approved scope.
The remaining gaps are two operator-documentation inaccuracies from Stage 9,
also missed by Stage 11's final documentation check. Production fixes are not
required for either finding.
### Finding CK-1 — Distinguish Mapping And Record Inheritance Syntax
Priority: P3. Category: documentation accuracy. Status: open.
Evidence: `docs/config.md:143–149` introduces both mapping and identified-record
inheritance, then says a directive names an immediate sibling in the same
mapping. That describes mapping inheritance only. For an identified step record,
the parent belongs to the same sequence and the reference must be an identity
mapping, such as `extends: {id: parent}`. The reference never shows that form.
An offline CLI probe with a parent step providing references and a child step
providing an artifact lane confirmed that `extends: parent` fails with
`inheritance.invalid`, while changing only the directive to
`extends: {id: parent}` loads successfully and preserves the inherited reference.
`TestIdentifiedStepRecordInheritance` already exercises the correct form in
`internal/core/config/collection_composition_test.go:182–208`.
Required changes:
- Explain string-valued mapping-sibling inheritance and identity-mapping
sequence-record inheritance separately, including their distinct lookup scopes.
- Add a minimal step-record example or a direct link to the pinned upstream
syntax example. Preserve the existing rules for null cancellation, validation,
and whole-record upsert; no new application inheritance machinery is needed.
Acceptance: an operator can determine the correct syntax for both a pipeline
mapping and a step record from the canonical reference. Any added snippet loads
through the current configuration boundary. Reuse the existing behavioral test;
do not add a documentation snapshot or change runtime behavior to fit the prose.
### Finding CK-2 — Describe Dependency-Ready Step Assembly Order
Priority: P3. Category: documentation accuracy. Status: open.
Evidence: `docs/config.md:167–170` says distinct imported step IDs combine
"in source order." ConfigKit distinguishes acquisition/import declaration order
from dependency-ready assembly order. Ready contributions are selected by their
stable source keys, so independent branches can interleave. The feature roadmap
and Stage 8 correctly rely on dependency-ready assembly rather than a Notarius
append pass.
An offline CLI probe declared imports in the order `z-first.yml`, then
`a-second.yml`, each contributing a different step and lane. Effective output
placed the step from `a-second.yml` first, then the step from `z-first.yml`.
Thus declaration order does not determine the resulting step list. This matters
because Notarius executes steps in the resolved list order and validates their
generated-reference dependencies.
Required changes:
- Replace the source-order claim with the native dependency-ready assembly rule
and link to ConfigKit v1.2.0's pinned composition contract for its full ordering
semantics. Do not promise declaration order or duplicate the upstream scheduler.
- Explain briefly why the maintained complete example's imported describe-session
step precedes the importing body's extract-events step: the imported dependency
is assembled before its importer. Keep the canonical operator rule in
`docs/config.md`; other documentation should link rather than redefine it.
Acceptance: the reference does not imply that reordering independent import
declarations necessarily reorders steps. The complete example's actual step
order and generated-reference handoffs remain unchanged. No custom sorting,
merging, or scheduler changes belong in this remediation.
### Stage-By-Stage Review Evidence
| Stage | Review result |
| --- | --- |
| 1 — Dependencies/toolchain | The selected graph builds with Go 1.27.0, both approved ConfigKit versions, PromptKit v0.12.0, and YAML rc.6; tidy reports no diff. |
| 2 — API/handoff | Application imports use the new package, old types remain in the PromptKit boundary, and LoadSource/MainSourcePath retain frozen inspection and detached runtime values. |
| 3 — Normalization/origins | Paths resolve before key movement; unchanged step identities retain leaf records, changed identities retain covering structural records. Existing tests and an additional temporary combined key/path-normalization probe pass. |
| 4 — Collections | The exact step-only identity registration delegates composition to ConfigKit. Real-file tests cover imports, upsert, replace, append, clearing, record inheritance, and source-relative references. |
| 5 — Fixtures | Application fixtures use native controls and assignment timing; old PromptKit fixtures remain correctly scoped. The full suite passes. |
| 6 — CLI discovery | The shared loader describes File/SearchConfig sources once and returns the recorded selected file. Manual probe helpers are removed. |
| 7 — Discovery/failures | Controlled tests cover precedence, filename selection, required exhaustion, terminal failures, reports, symlinks, and debug provenance without relying on host system files. |
| 8 — Examples | Minimal, complete, and development pipelines validate without inference; the supporting fragment preserves module choices, step order, and handoffs. |
| 9 — Operator docs | Search, controls, path bases, CLI timing, and toolchain guidance are updated. CK-1 and CK-2 remain. |
| 10 — Internal/integration docs and notices | The mixed dependency boundary and pinned ConfigKit attribution match the selected graph. Accepted ADRs, policy, and project license/grant were not modified by the sprint. |
| 11 — Final verification | Full tests, vet, tidy, native build, dependency inspection, and provider-free validation/effective/explanation commands pass. The final documentation review missed CK-1 and CK-2. |
### ConfigKit Review Validation
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go test ./...` passed.
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go vet ./...` passed.
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go test -race ./internal/core/config ./internal/cli` passed.
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go mod tidy -diff` produced no changes.
- A native build in a temporary directory succeeded. Minimal, complete, and
development configuration validation, plus application and PromptKit effective
and explanation reports, succeeded without provider calls.
- Selected module inspection confirmed the four approved ConfigKit, PromptKit,
and YAML versions. Pinned local upstream documentation and notices were checked.
- Temporary fixtures outside the repository reproduced both documentation gaps
and verified combined identifier/reference-path normalization. No production
pipeline, credential lookup, or live model-quality evaluation was performed.
- The review document passed `git diff --check`; production code and current
operator documentation were not changed by this review.
Keep the earlier PromptKit findings separate from these two documentation fixes.
The deferred PromptKit/ConfigKit v1.2.1 upgrade and release work remain out of scope.