Plan the staged overlay rename
This commit is contained in:
181
docs/roadmap/implementation.md
Normal file
181
docs/roadmap/implementation.md
Normal file
@@ -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/<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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user