ConfigKit/docs/roadmap/implementation.md

# Configuration Overlay Rename Implementation Plan

Status: Stage 1 complete. Execute Stage 2.

## 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/<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.