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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user