ConfigKit/docs/roadmap/implementation.md

Configuration Overlay Rename Implementation Plan

Status: complete.

Scope and operating instructions

This plan implements the approved overlay roadmap. That document owns naming, preserved behavior, and the decision to make a breaking minor-release change without compatibility aliases. Baseline: d8d9dbf; implemented code is unchanged from aead20f. The intended release is v0.4.0, but this plan does not authorize a release, push, tag, dependency upgrade, or downstream repository edit.

The target implementer is a gpt-5.6-terra coding agent. Each stage is one coherent, reviewable unit. Stage 1 is broader in file count but is a mechanical rename of one feature; splitting the public/engine/consumer rename would leave a broken build or require temporary compatibility machinery. Stage 2 owns the additional regression evidence and final migration audit, not a second implementation.

Before each stage:

• Read AGENTS.md, development guidance, and all policies: agents, architecture, documentation, testing, and release.
• Inspect Git status and preserve unrelated work. Prefer the repository's graph tools for code discovery; use text searches for strings and documentation.
• Read the roadmap and the current selected-input contract in docs/config.md. Inventory references before changing them; do not blindly replace every occurrence of "profile" across the repository.
• Keep dependencies and toolchains available before offline validation. Use the normal local development checks, not a real release workflow. Never wait for CI.

At each stage's end, update this plan's status with completion and validation evidence, review the diff, and commit that stage with a short plain-English message under the agent policy. Do not commit failed or incomplete work as if the stage were complete. Do not repeat checks merely to create the commit.

Stage 1 — Rename the feature end to end

Outcome

The repository builds and existing tests pass using the new public API, selected directory, layer values, diagnostics, and current documentation. No legacy API aliases or filesystem fallbacks remain. Existing selection/merge semantics stay unchanged.

Implementation

1. Apply every public mapping in the roadmap's Target terminology and public surface table. Change Options[T].Profile to Overlay in root lifecycle.go and engine load.go, including the facade options conversion. Change LayerProfile to LayerOverlay with string value overlay, and all seven CodeProfile* constants to their CodeOverlay* equivalents and overlay.* strings in both records.go files. Remove the old declarations; do not leave aliases, deprecated fields, or dual emitted values.
2. Keep merge mechanics in internal/engine/overlay.go. Rename the acquisition files internal/engine/profile.go and profile_test.go to selected_overlay.go and selected_overlay_test.go. Use activeOverlay, validOverlayName, loadSelectedOverlayDocument, readOverlayFile, and overlayDirectiveDiagnostics for their corresponding helpers. Rename test helpers and local variables consistently; do not otherwise refactor the loading pipeline or merge algorithm.
3. Update engine options.go, load_input.go, directives.go, overlay.go, and explain_render.go, plus any other callers found by discovery. Load only overlays/<name>.yml; use the same prefix in source labels. Update diagnostic messages about the selected feature. Preserve shared options.*, import.*, source, and parser classifications where the baseline uses them.
4. Migrate existing tests and assertions, including selected-file tests and engine overlay_test.go, override_test.go, provenance_test.go, metadata_test.go, explain_test.go, render_test.go, glob_test.go, and source_fifo_test.go. Update names, selected-file paths, expected layers, codes, and rendered terminology. Preserve the semantic expectations; do not relax unrelated assertions to obtain a green suite.
5. Rename LoadNarratioProfile to LoadNarratioOverlay in the maintained consumer example, update its callers and Options literals, and move examples/consumers/testdata/narratio/profiles/testing.yml to examples/consumers/testdata/narratio/overlays/testing.yml. Preserve ModelProfile, its model_profile YAML key, and their domain meaning.
6. Update Go declaration/package comments, README, docs/config.md, docs/consumers/README.md, architecture-policy terminology, development test paths/commands, and implemented-component documentation where affected. Rename the contract heading to Selected overlays and repair all inbound links, including links from this plan or the roadmap if needed. Current docs must match the Stage 1 implementation; do not postpone that work to Stage 2.
7. In docs/internal/extraction.md, distinguish literal upstream symbols and historical claims from descriptions of current ConfigKit helpers. Preserve upstream names/revisions; update current ConfigKit references. Preserve accepted ADR decision text and historical release notes. Repair historical navigation links only where necessary. No new architecture decision is needed for this terminology-only change.
8. Add a concise migration section to the consumer guide: rename option/constant identifiers, move selected files, update handling of layer/diagnostic strings, and rebuild. Link to current canonical behavior rather than duplicating the full specification. Explain that application-owned profiles remain unchanged and any application CLI flag rename belongs to that application. Do not create docs/releases/v0.4.0.md in this implementation stage.

Validation and acceptance

• Run gofmt on changed Go files, then ./scripts/check.sh. Its complete suite covers the migrated engine tests, maintained consumers, examples, documentation links, and facade/dependency boundaries; do not rerun these subsets just to duplicate successful coverage.
• Review that empty selection and lowercase default still mean no selection; the name grammar, .yml convention, filesystem checks, error ordering, merge rules, budgets, CLI precedence, and lifecycle are unchanged.
• Review output assertions to ensure overlay and overlay.* propagate through both the engine and public wrappers, including history and explanations.
• Review git diff for accidental changes to model_profile, historical evidence, merge logic, dependencies, or release machinery.

Stage 1 is complete only with a compiling, passing repository and matching current documentation. It is not permission to ship before Stage 2's audit.

Completion

Completed 2026-09-23. Renamed the selected configuration feature across the facade, engine, maintained consumer, fixtures, contract, and current guidance; application-owned ModelProfile and model_profile remain unchanged. gofmt and ./scripts/check.sh passed on Go 1.26.8/linux. Review confirmed the new overlays/<name>.yml path, overlay/overlay.* public values, and no retained legacy Go declarations or filesystem fallback.

Stage 2 — Verify the breaking migration and finalize the handoff

Outcome

Focused regression tests demonstrate the intentional break and protect against legacy fallback or over-broad renaming. The final public surface and consumer instructions match the roadmap, with no unresolved migration work in this repo.

Implementation and review

1. Extend the renamed selected-file selection test using real temporary files:
   • A selected file under overlays/ loads successfully.
   • The same selected name present only under profiles/ yields CodeOverlayMissing and no usable result; it is not silently loaded.
   • When both locations exist with different values, only the overlays/ file contributes to configuration and sources. Assert the selected source's new label and LayerOverlay; do not manufacture extra source records. Retain the existing empty/default, invalid-name, missing-file, and .yaml no-fallback cases. Reuse existing helpers rather than a new fixture framework.
2. Confirm that a normal explicit import from a directory named profiles remains valid and has base-layer semantics. Add one focused case if existing import coverage does not establish it. This protects the specific decision not to reserve or ban the old word outside named-overlay selection.
3. Verify the public facade with the maintained consumer test. Extend that test only as necessary to assert its application-owned ModelProfile remains intact while overlay selection and public source metadata use the new names. Engine tests own the detailed negative cases; do not replicate them all at the root boundary.
4. Check coverage for the new public layer/code string values and explanation output. Prefer the migrated behavioral assertions; if a mapping lacks coverage, add a small assertion at its existing owner. Do not introduce a blanket ban on the text "profile" in diagnostics or user data, and do not snapshot human wording that is not contractual.
5. Inspect go doc -all . and source references against the baseline. Confirm that Options.Profile, LayerProfile, and CodeProfile* declarations are gone, that all roadmap mappings exist, and that no unrelated exported API changed. A manual source/API review is sufficient for removal of old Go identifiers; no negative-compilation harness or whole-API golden file is required.
6. Audit remaining case-insensitive "profile" references in tracked content. Classify rather than delete them automatically. Legitimate remaining uses include application fields, immutable history/upstream evidence, migration guidance, this plan, and explicit negative/no-fallback test fixtures. Repair any active ConfigKit feature names, stale file paths, or heading links.
7. Finish migration guidance and any gaps found in current docs alongside fixes. Record that v0.4.0 release preparation must explain all four breaking surfaces: Go API, selected-file directory, provenance layer, and diagnostic codes. Actual version selection, release-note creation, tagging, and pushing remain a separately authorized release task using the existing procedure.
8. Once validated, mark this plan complete and reduce the feature roadmap to a completion summary linking to the current configuration contract and consumer migration guidance. Retain completed records until release preparation; do not leave competing normative definitions in roadmap documents.

Validation and acceptance

Run ./scripts/check.sh for changed code and docs. Run GOPROXY=off go test -race ./internal/engine for the final migrated engine, including the existing concurrent-load independence coverage. Do not introduce new release gates, external integration tests, CI waits, or mandatory macOS checks. If a broader equivalent validation already passed for unchanged content, reuse that evidence rather than repeating it.

Report the stage commit, validation results, any skipped platform-specific cases, and the API/filesystem migration summary. The implementation is complete only when both stages pass and the roadmap's target surface and preserved behavior are accounted for. There are no unresolved product questions in this plan.

Completion

Completed 2026-09-23. Added regression coverage that accepts only overlays/<name>.yml for selection, rejects a legacy-only selected file with CodeOverlayMissing, and ignores a legacy sibling when the new selected file is present. Explicit imports from a directory named profiles remain base-layer imports. The maintained consumer confirms ModelProfile is unchanged while its selected source reports overlays/testing.yml and LayerOverlay; public layer/code strings and rendered explanation values are covered.

Validation passed with ./scripts/check.sh and GOPROXY=off go test -race ./internal/engine on Go 1.26.8/linux. No additional platform-specific validation was required; existing symlink coverage remains conditional on Linux or macOS. The API audit found no legacy Go declarations, and the remaining profile references are intentionally limited to application-domain fields, upstream or historical records, migration guidance, and explicit legacy-path regressions. The feature roadmap is now a completion summary; v0.4.0 release preparation must still describe the Go API, selected-file directory, provenance layer, and diagnostic-code breaks.