diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 561bc76a..f96d1e44 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -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.