diff --git a/docs/release-control/internal/AGENT_VALUES.md b/docs/release-control/internal/AGENT_VALUES.md index f6a6ed2c8..42e082802 100644 --- a/docs/release-control/internal/AGENT_VALUES.md +++ b/docs/release-control/internal/AGENT_VALUES.md @@ -61,8 +61,12 @@ that already belong to the canonical system. 11. Keep legacy support at the boundary. Backward compatibility is acceptable only where a real external boundary, migration edge, upgrade path, or explicit interoperability obligation still - requires it. Do not preserve or polish legacy-primary internal paths when a - canonical v6 path exists. + requires it. When a canonical replacement makes an internal path legacy, + or a touched governed surface reveals clearly obsolete old-way code, + retire that legacy code instead of leaving shadow code behind unless a + named boundary-only exception still owns it. Do not wait for the current + slice to have authored the replacement before cleaning up clearly obsolete + old-way internals in the surface it is already governing. 12. Prefer the largest coherent slice. When a claimed lane is already moving through one clear behavior arc on one surface, prefer the largest same-surface slice that still has one coherent diff --git a/docs/release-control/internal/CONTROL_PLANE.md b/docs/release-control/internal/CONTROL_PLANE.md index fc6cfe67d..6d951a919 100644 --- a/docs/release-control/internal/CONTROL_PLANE.md +++ b/docs/release-control/internal/CONTROL_PLANE.md @@ -95,6 +95,16 @@ model that active and future release profiles reuse. compatibility shims from primary paths, using canonical v6 types and APIs, and updating subsystem ownership plus proof routing when runtime ownership changes. + When canonicalization makes an old internal path obsolete, the same slice + should retire the superseded code, docs, fixtures, and helpers rather than + leaving parallel legacy-primary implementations behind. + This is not limited to code the slice directly replaced: if work lands on + clearly obsolete old-way internals inside the governed surface, cleanup + should pull that retirement forward instead of leaving known legacy clutter + behind for a future pass. + Any retained legacy behavior must be named as a boundary-only exception, + and the slice should carry proof or guardrails showing that the supported + boundary still works after the broader old path is removed. These modernization rules are retrospective as well as forward-looking: existing lanes that were previously improved in a legacy-shaped way must be re-judged against the canonical v6 model when they are touched again, and diff --git a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md index edb5956a7..16c8201f1 100644 --- a/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md +++ b/docs/release-control/v6/internal/CANONICAL_DEVELOPMENT_PROTOCOL.md @@ -27,7 +27,8 @@ exist: 2. route through unified resources when that is the canonical shape 3. prefer canonical shared types, APIs, and paths over lane-local variants 4. remove or isolate legacy host-era terminology, adapters, and compatibility - shims from primary runtime paths + shims from primary runtime paths, and retire newly superseded or clearly + obsolete internal paths instead of leaving shadow implementations behind 5. update subsystem ownership, path policies, and proof routing when runtime ownership moves 6. record any unavoidable modernization residual explicitly instead of treating @@ -211,12 +212,18 @@ Every substantial task must finish by checking these questions: addition, or lane expansion shape is clear enough to name explicitly. 3. Did I change stable governance, scope, evergreen readiness assertions, or lock a new architectural/release decision? If yes: update `SOURCE_OF_TRUTH.md`. -4. Did I replace an old path with a new canonical path? - If yes: add or tighten a guardrail so the old path cannot silently return. +4. Did I replace an old path with a new canonical path, or did this slice + uncover clearly obsolete legacy-primary code in the governed surface? + If yes: retire the superseded or obsolete implementation, docs, fixtures, + and helpers in the same slice unless a named boundary-only exception still + needs them, and add or tighten a guardrail so the old path cannot silently + return. 5. Did I add a new extension point? If yes: record exactly where future work must attach to it. 6. Did I leave compatibility code in runtime paths? - If yes: either remove it now or explicitly classify it as a boundary-only exception. + If yes: either remove it now or explicitly classify it as a boundary-only + exception and verify that the remaining supported boundary still works + without the retired internal path. 7. Did the user state a durable product truth or change the current priority? If yes: classify it as a readiness assertion, release gate, open decision, or active-target update and record it in the owning control file instead of @@ -287,9 +294,13 @@ Every substantial task must finish by checking these questions: upgrades, imports, external contracts, or wire compatibility that still genuinely exist. If I am improving an old internal path just to keep it alive alongside the - canonical v6 path, that is drift. Retire it or record the exception - explicitly as boundary-only compatibility rather than treating it as normal - lane progress. + canonical v6 path, that is drift. Retire it in full or record the + exception explicitly as boundary-only compatibility, with proof that the + supported boundary still works without the rest of the legacy path, rather + than treating it as normal lane progress. + The same rule applies when I merely discover clearly obsolete old-way code + while working nearby; finding it is enough to make its retirement part of + the governed cleanup story. 11. Is the remaining work still part of this lane? If not, stop cleanly and normalize it into the next target, another lane, or an explicit open decision instead of letting this task expand forever. diff --git a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md index 28f9ce54a..fddfc7a55 100644 --- a/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md +++ b/docs/release-control/v6/internal/SOURCE_OF_TRUTH.md @@ -254,6 +254,13 @@ Assertion design rules: as migrations, upgrades, imports, external contracts, or wire interoperability that still genuinely exist; otherwise retire the legacy-primary path instead of teaching the lane to depend on it. + When a canonical replacement lands, remove the superseded internal path in + the same slice unless a boundary-only exception is explicitly governed, + and prove that the remaining supported boundary still works. + Do not wait only for the slice that authored the replacement: if a later + governed slice lands on clearly obsolete old-way internals in that same + surface, cleanup should retire them rather than normalizing their + continued presence. 20. Guardrail-only work is support work, not lane advancement. Contract ratchets, proof-routing cleanup, registry tightening, and guardrail-only tests may strengthen confidence, but they must not be @@ -271,9 +278,12 @@ Assertion design rules: 22. Legacy compatibility must be named as a boundary exception, not assumed as a primary v6 design goal. If a touched surface still needs old-path support, make the boundary - obligation explicit in the owning contract or lane residual. Otherwise, - treat continuing investment in that old internal path as drift, not - prudence. + obligation explicit in the owning contract or lane residual and keep the + rest of the superseded internal path retired. Otherwise, treat continuing + investment in that old internal path as drift, not prudence. + Clearly obsolete old-way code discovered during adjacent governed work is + part of that same drift signal; clean it up or record the blocking reason + explicitly instead of leaving it behind as ambient repo clutter. 23. Claimed lane work should prefer the largest coherent same-surface slice. Within an active claimed lane, prefer the largest coherent same-surface slice. When one behavior arc on one governed surface is already clearly in scope, diff --git a/docs/release-control/v6/internal/status.json b/docs/release-control/v6/internal/status.json index 10a9749f7..65b774592 100644 --- a/docs/release-control/v6/internal/status.json +++ b/docs/release-control/v6/internal/status.json @@ -3225,7 +3225,7 @@ "lane_followups": [ { "id": "architecture-post-rc-canonicalization", - "summary": "Track the remaining post-RC architecture cleanup that still belongs to L6 after canonicalizing Connected infrastructure and the frontend state contract by construction.", + "summary": "Track the remaining post-RC architecture cleanup that still belongs to L6 after canonicalizing Connected infrastructure and the frontend state contract by construction, including retirement of newly legacy or clearly obsolete old-way internal paths unless a boundary-only exception is explicitly governed.", "owner": "project-owner", "status": "planned", "recorded_at": "2026-03-13",