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