half-renamed-codebase

Description

A specialization of graduation-promotion where the lagging-rename pattern is itself diagnostic: the project’s new structural shape is visible in the code, but the old name is still in the directory tree / config keys / function signatures / docs. The mismatch surfaces an UNABSORBED mental model — the maintainer’s reflexes haven’t caught up to where the code has already moved.

The diagnostic move: when you notice you’re working around an old name, ask “what mental model would I be using if the name matched the code?” The gap usually points to a structural simplification or a missing abstraction.

Structural shape:

1. Project starts with a name N₀ encoding mental-model M₀.
2. Iteration produces a structurally different system better described by M₁.
3. Code reflects M₁ in shape; surfaces (file names, identifiers, docs) still reflect N₀.
4. Working on the codebase requires translation between the old vocabulary and the new reality on every read.
5. The translation cost is the load-bearing signal that the rename is overdue.

Tentative composition

• graduation-promotion (specialization-of — the rename is a graduation move)
• surface (the lagging name is a surface mismatch)
• cargo-cult (related — old names persisting because “we’ve always called it that,” like surface copying without the underlying mechanism)
• load-bearing (the rename is load-bearing when the translation cost is high on every read; trivially decorative when it’s not)

Provenance

Surfaced as a deferred candidate in forms/README.md (pre-Chunk-A staging prose). Conversational coining; encountered repeatedly in James’s work across KCC + analogy (e.g. Projection → Analogy rename in v0-design-spec §5, which itself is an instance of the form).

Promotion criteria

Promote to a full Form when:

• At least 3 documented encounters from distinct codebases (not just analogy + KCC)
• The trigger pattern can be articulated separately from generic “refactoring is overdue” — what’s the specific shape that makes this a distinct form rather than a vague code-smell?
• Empirical evidence that the rename diagnostic produces NEW moves (per the change-next-move FAC gate) and not just “yeah we should rename that someday”