Stop encoding plan identifiers (unit/requirement/decision numbers) in code identifiers

[vicondoa]

Stop encoding plan identifiers (unit / requirement / decision numbers) in code identifiers

Summary

Code carries plan numbering in symbols, test names, module names and comments:
U9_SHARED_PROVIDER_RUNNERS, U9_PROVIDER_REFS, is_u9_provider_ref,
u9_repair_preserves_child_mutation_result, plus doc-comment citations like
(U8, KTD6/KTD8; R23-R25, R28) and (KTD3) with no local explanation. The ids
are meaningful only in the context of one planning document, they churn as that
document evolves, and they collide across documents.

Motivating incident (2026-09-10). "U9" names two different things: the
plan's unit U9 (the Phase A composition cutover, long finished) and the
interaction provider family of the old plane (U9_SHARED_PROVIDER_RUNNERS -
display-wayland, audio-pipewire, shell-terminal) being converted under U12.
Told "what's left on U9", an engineer had to disambiguate which U9 was meant;
the code offered no help because the identifier is a number, not a
description.

What the rule should be

1. Identifiers, file/module names, test names: describe behavior. No unit,
   requirement, decision or acceptance-example numbers. Test names say what
   behavior they pin (display_and_audio_runners_enroll_finalizers_before_effects)
   rather than which plan item produced them
   (u9_runner_enrolls_exact_finalizers_before_effects).
2. Comments may cite a decision as a pointer, never as the explanation.
   // plan: KTD13 (process launches route through the Process controller)
   is useful; a bare (KTD3) on a struct field is not - the reasoning must be
   readable without opening the plan. Prefer citing stable external spec
   sections where they exist (the spec's section numbering is a contract, the
   plan's unit ids are bookkeeping).
3. Plan documents keep their numbering. This issue is about code depending
   on that numbering, not about the plan.

Inventory (2026-09-10, pre-U14 sweep)

Identifier-level (the hard cases):

• packages/d2bd/src/resource_runtime/interaction_provider_runtime.rs:43
U9_SHARED_PROVIDER_RUNNERS, :110 U9_PROVIDER_REFS;
  packages/d2bd/src/resource_runtime.rs:217, :224, :256, :11615,
  :11619, :15760, :15860, :16258 (re-exports, predicates, tests);
  packages/d2bd/tests/core_composition.rs:8, :117, :127, :201.
• Test names: u9_repair_preserves_child_mutation_result (resource_runtime.rs:15859),
  u9_runner_enrolls_exact_finalizers_before_effects (:16257),
  u9_composition_builds_one_fenced_runner_per_owned_interaction_resource
  (core_composition.rs:116).
• Deleted-but-instructive examples of the same pattern: U12ControllerKind,
  U10_PROVIDER_COUNT, U10_PROVIDER_CONTROLLERS, U7_SHARED_PROVIDER_RUNNERS,
  prepare_u8_provider_runners - all named after the unit that introduced them,
  none after the behavior they implemented.

Comment-level citations (softer; many are fine, some are load-bearing):

• packages/d2b-resource-runtime/src/context.rs:1, :22, :52, :108, :164,
  :327 - (U4, KTD3; spec sections 12, 14, 15), (R5, R6 ...), (F1, AE1).
• packages/d2b-resource-api/src/manager_backend.rs:2, :12, :21, :80,
  :90, :156, :188, :217, :248, :32x, :444, :554, :753, :933,
  :1003 - dense KTD6/KTD8/R11/R23/R24/R28/F1/AE1/AE6 citations.
• packages/d2b-provider-volume-virtiofs/src/{bindings.rs,controller.rs,lib.rs,port.rs,worker.rs}
  • repeated bare (KTD1) / (KTD3) / (KTD5) / (KTD6).
• packages/d2b-contracts/src/identity.rs:53 - (R35/F1 exclusive per-type partition).
• packages/d2b-resource-api/src/registered.rs:5497-5500 - the deliberate
  #[ignore] reason string names U14 ("redb controller-API machinery is
  deleted in U14"), which will read as nonsense once U14 is done and forgotten.

Non-code carriers that also land permanently: changelog fragment filenames
(changelog.d/u12-volume-leg.md, u12-activation.md) and lane worktree names.

Sequencing (important)

Most U-numbered identifiers live in the old-plane machinery that U14 deletes
(resource_runtime.rs runner tables, *_provider_runtime.rs modules, the
interaction_provider_runtime.rs registrations). Do the sweep after U14, so
it only renames survivors - renaming code that is about to be deleted is pure
churn and creates merge conflicts for the in-flight conversion lanes.

Proposed work

1. After U14: rename surviving identifiers, tests and modules to behavior
   descriptions (mechanical, via rename tooling, not hand edits across files).
2. Convert bare comment citations to plan: <ID> (<one-line meaning>) or, better,
   inline reasoning; keep spec-section references where they are the contract.
3. Replace id-bearing changelog fragment filenames with behavior-scoped names
   (volume-leg-driver-conversion.md).
4. Add a guard so the pattern does not return: an xtask check (there is already
   //packages/xtask:repository_contract) that flags new unit-numbered
   identifiers/test names in packages/** (\bU[0-9]+_?[A-Za-z], u[0-9]+_
   in fn/test names, U[0-9]+[A-Za-z]* consts) with an allowlist for
   pre-existing hits, plus a note in the contributing guidance.

Acceptance criteria

• No identifier, module, test name or changelog filename in packages/** or
  tests/** encodes a unit/requirement/decision number; the guard fails a new
  one.
• Every remaining decision citation in a comment states its meaning locally or
  points at a named document and section.
• The sweep is behavior-preserving: make check green, no test deleted or
  weakened to accommodate renames (renames only).

Non-goals

• Not renaming anything that U14 deletes anyway.
• Not rewriting git history or archived plan documents.
• Not banning references to the spec's stable section numbers, or to ADRs.

[vicondoa]

Decision: option (a) - full retrofit, with a scope clarification.

Plan identifiers (unit, requirement and decision numbers) are removed from code identifiers and from comments in code. They remain appropriate in plans and architecture documents, which is where they belong and where they stay.

Acceptance: no plan identifier appears in a code identifier, a code comment, a test name or a build file; plans, ADRs and contributor docs are untouched; the convention is enforceable, so a policy check prevents recurrence rather than relying on the next reviewer.