"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.