From 66e080ed349346e443d6f5c121c8f5f5f03081c1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 23 Sep 2026 18:20:25 +0000 Subject: [PATCH] Plan the staged overlay rename --- docs/roadmap/implementation.md | 181 +++++++++++++++++++++++++++++++++ docs/roadmap/overlays.md | 83 +++++---------- 2 files changed, 209 insertions(+), 55 deletions(-) create mode 100644 docs/roadmap/implementation.md diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..7bc2604 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,181 @@ +# Configuration Overlay Rename Implementation Plan + +Status: not started. Execute Stage 1, then 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/.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. + +## 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. diff --git a/docs/roadmap/overlays.md b/docs/roadmap/overlays.md index b9ada44..14a73cf 100644 --- a/docs/roadmap/overlays.md +++ b/docs/roadmap/overlays.md @@ -1,6 +1,7 @@ # Rename Configuration Profiles to Overlays -Status: approved target, not yet implemented. +Status: approved target, not yet implemented. Execution steps and stage status +belong to the [implementation plan](implementation.md). ## Purpose and release scope @@ -91,61 +92,35 @@ Ordinary explicit imports retain their existing rules regardless of a file's directory name. Removing legacy selection support does not reserve or ban these names elsewhere. -## Work required from the baseline +## Internal architecture and maintained examples -### Public facade and engine +The public facade retains root-owned named types and inward-only dependencies. +Selected-file acquisition and the existing overlay merge mechanism remain +distinct responsibilities within the engine. Internal naming reflects the new +terminology without a pipeline or merge-algorithm redesign. -Update root `lifecycle.go`, `records.go`, and package/API comments along with -their engine counterparts. Rename selection helpers, variables, and tests that -refer to ConfigKit profiles. Preserve root-owned public types and inward-only -dependencies; no facade redesign is needed. +Maintained examples use the new API and selected-file directory. The Narratio +example still has an application-owned `ModelProfile` / `model_profile`; that +concept is deliberately independent of ConfigKit overlay selection. -The existing `internal/engine/overlay.go` owns merge mechanics. Keep that role -distinct from selected-file acquisition: rename `profile.go` and its tests to -`selected_overlay.go` and `selected_overlay_test.go`, with names such as -`loadSelectedOverlayDocument` for acquisition. Do not combine unrelated code -merely to resolve the filename collision. Update option validation, directive -checks, input loading, and explanation rendering consistently. +## Documentation and migration contract -### Tests and maintained consumer examples +Current public comments, configuration documentation, consumer guidance, +architecture terminology, and implementation descriptions consistently call the +feature an overlay. Accepted ADR decisions and historical release notes retain +their historical wording. The extraction inventory preserves literal upstream +symbols and revision-specific evidence while distinguishing current ConfigKit +implementation names. Historical navigation links may change when their targets +move; historical decisions do not change. -Migrate existing coverage and fixtures rather than duplicating the entire suite. -Update assertions for layer/code values, labels, paths, and rendered output; -retain all existing semantic assertions under the new terminology. +Consumer migration consists of updating Go identifiers, moving selected files to +`overlays/`, and updating any handling of the renamed provenance-layer and +diagnostic-code strings. Applications own any corresponding CLI flag rename; +ConfigKit does not define or modify downstream CLIs. -Add focused regression evidence that selection uses `overlays/`, never falls -back to `profiles/`, and chooses only `overlays/` when both exist. Preserve coverage -for empty/default selection, invalid and missing names, root containment, -version/directive rules, source budgets, CLI precedence, and provenance/history. -Existing public-boundary and consumer tests must continue to pass after their -API migration. A source/API review must confirm that old exported names were -removed, not hidden behind aliases. - -Move the maintained Narratio fixture from `profiles/testing.yml` to -`overlays/testing.yml`, update the example helper and callers, and keep its -application-owned `ModelProfile` / `model_profile` unchanged. This distinction is -part of the motivation for the rename, not leftover work. - -### Documentation and consumer migration - -Update the canonical configuration heading and inbound links, public Go -reference comments, README, architecture policy terminology, development -test map, consumer guide, and implemented-component descriptions as applicable. -The architecture itself remains unchanged. - -Do not globally replace every occurrence of "profile". Preserve immutable -historical release notes and accepted ADR decision content. Preserve upstream -symbol names and revision-specific evidence in the extraction inventory while -updating its descriptions of the current ConfigKit implementation. Historical -navigation links may be repaired when headings or files move. - -At release preparation, the version-matched minor-release note must explicitly -describe the breaking API, directory, provenance-layer, and diagnostic-code -changes. Consumer instructions must cover updating Go identifiers, moving -selected files to `overlays/`, and updating any downstream output/diagnostic -handling. Applications own any corresponding CLI flag rename; ConfigKit does -not define or modify downstream CLIs. Do not create a release note before an -actual reviewed release candidate exists. +The future minor-release note must explain those four breaking surfaces. Release +preparation and publication remain governed by the [release procedure](../release.md); +this roadmap does not create a release candidate or introduce additional gates. ## Completion criteria @@ -156,11 +131,9 @@ and no directory fallback. Remaining "profile" references must be intentional application data, migration explanation, or historical records, not active ConfigKit feature names. -Validate locally under the [testing policy](../policy/testing.md), including -affected behavioral tests, examples, documentation links, facade boundaries, -formatting, vet, and builds. Publication is a separate task governed by the -[release procedure](../release.md); neither CI waiting nor additional release -gates are introduced by this roadmap. +Tests establish the new selection directory, absence of legacy fallback, and +preservation of existing semantics. Existing coverage remains with its owning +layer instead of being duplicated across the facade and engine. After implementation, current contracts own the renamed behavior and this roadmap becomes a completion record for retirement during release preparation.