# Configuration Overlay Rename Implementation Plan Status: complete. ## Scope and operating instructions This plan implements the approved [overlay roadmap](overlays.md). 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](../development.md), and all policies: [agents](../policy/agents.md), [architecture](../policy/architecture.md), [documentation](../policy/documentation.md), [testing](../policy/testing.md), and [release](../policy/release.md). - 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/.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/.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/.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.