PROP-031 — Algorithmic refactoring: the codemod engine and the write-side of the model

1. Problem statement

03Refactoring in this repository is done one of two ways today, and both are wrong for the volume ahead:

1. 04By hand. The naming campaigns in the git log (refactor(spec): spec:// authority joins group and name with /; repoint every reference to the new package groups) were large, mechanical, cross-file renames performed by a human or an LLM walking files. Correct, but slow and not repeatable.
2. By LLM file-rewriting. An agent opens each file and rewrites it. For an elementary change — rename a spec:// address, move a spec unit into a package — this can take hours, cost a fortune in tokens, and is unreliable: a single missed call-site silently severs a spec↔code edge, and nothing catches it unless a gate happens to run.

• 05Both violate the repository's own delegation-first thesis (CLAUDE.md): mechanical transforms should cost O(decision), not O(files).
• A rename has zero generative content — it is a deterministic function of the tree — so it should not consume any model at all, cheap or expensive; it should be a tool call.

• 06The beachhead exists. The AI-Native discipline already ships Scaffold I — codemods (scaffold-i-codemods): "a recurring multi-file change offered as ONE parameterized, checked, atomic operation," explicitly naming codemod rename-seam --from X --to Y.
• But today it is (a) one operation (add-cell scaffolding only), (b) marked [E-hyp] (unvalidated hypothesis), and (c) a single language stack's card, not a cross-layer capability with a ratified model.
• The upcoming cultural-pattern extraction refactoring will perform thousands of unit moves and address renames; without an algorithmic engine it is economically and operationally impossible to do well.

07This PROP names the capability, fixes the model, and — critically — states what every artifact must do now so the engine, when it lands, has a clean model to operate on.

2. Decisions

rename-address   <from-uri> <to-uri>              # retarget every citing edge to a new spec:// address
move-unit        <from-uri> <to-doc>[#anchor]     # relocate a spec unit across a boundary (the capsule)
retarget-edge    <symbol> <from-uri> <to-uri>     # repoint one code→spec edge
bump-revision    <uri> --to r<N>                  # bump a unit's revision; list the pins it makes suspect
rename-symbol    <from> <to>                       # rename a code symbol + its spec tags (wraps §2.5)
rename-package   <from-fqid> <to-fqid>            # rename a package + repoint every consumer (product tier)
repoint-dependency <consumer> <from> <to>          # move a dependency edge in the manifest graph
relocate-boot-snippet <slot> <to>                  # move a boot entry + regenerate INDEX.md

3. Build-in-anticipation discipline (what to do NOW)

22req r1 — The engine does not exist yet, but its arrival is a standing assumption from this PROP forward. Everything authored between now and then MUST keep the model refactor-ready, so the engine inherits a clean substrate rather than a swamp:

1. 23Address everything; prose-reference nothing. Every cross-reference is a resolvable URI (spec://…#anchor, a package FQID, a symbol path), never "see above" / "the section on X". Generalises PROP-014 §3.1.9 from a style rule to a precondition: the engine can only rename what it can address. An un-addressable reference is invisible to the refactorer and will silently rot.
2. Stable identity for anything that can move. Spec units keep immutable {#anchor}s; code carries #[spec]/scope!; packages carry FQIDs; boot entries carry INDEX ids. Renaming preserves the anchor; retiring tombstones it (PROP-014 §2.1). Identity is what an operation targets.
3. Prefer the graph over prose for anything you may later refactor. If a link must survive a rename, it belongs in the machine-readable graph, not in a paragraph. This resolves the SPECMAP plan's D3 in favour of graph-edges: prose spec:// references should become first-class specmap edges (extend mdspec), because that makes them not merely gated but refactorable. A standalone prose-link checker gates; a graph edge gates and moves.
4. Build bespoke tools as instances of the algebra, not one-offs. The SPECMAP move-unit command is written as the first operation of this engine (§2.6), sharing the dry-run / atomic / gated contract, so the second operation is composition, not a rewrite.
5. Gate the models now. A write-side is only trustworthy over a read-side that is enforced. Wiring specmap --check into self-check.sh (SPECMAP Plan M1) is a precondition for any refactoring operation: the invariant the engine checks against must already be green and gated.

4. Rejected alternatives

1. 24LLM free-form file-rewriting (the status quo). The problem, not a solution: O(files) cost, no atomicity, no gate, silent edge-severing. Retained only for the judgement half (deciding what to refactor), never the mechanical half.
2. A sidecar refactoring database (operations recorded outside the tree). Violates "project facts live in the repo" (CLAUDE.md memory discipline) and PROP-014's rejection of sidecar maps — the model is the tree (specmap graph + manifests), and the engine reads/writes it directly.
3. Reimplementing AST surgery per language. Wasteful and fragile against language evolution; §2.5 wraps mature permissive engines instead, adding only spec-awareness.
4. IDE-only refactoring (LSP rename in the editor). Necessary but insufficient: not scriptable, not headless, not gated by the discipline, not composable into swarm/fractality runs, and blind to spec:// addresses and package graphs. The engine is CLI-first and gate-first; IDE integration is a later surface over the same operations.
5. Deferring the model until the engine is built. Rejected as the whole point of this PROP: the anticipation discipline (§3) is what makes the eventual engine cheap. Building the model late means retrofitting addressability across a corpus that grew without it.

5. Prior art & license posture

25Conventions and ideas are free; code is not (PROP-000 §3). Roles explicit; license fields re-verified before any code-level reuse.

27Differentiators.

1. 28operations are spec-aware — they update the spec:// edge graph, which no general refactoring tool knows about;
2. they are gated by the discipline's own invariant (specmap --check / self-check), not merely "compiles";
3. an LLM is a first-class participant — strictly as the proposer/parameterizer behind a deterministic core (§2.2);
4. operations compose across three tiers (spec / code / package) because the models are addressable end-to-end.

6. Open questions

1. 29Where the discipline mechanism lives. This host PROP is the vibevm-facing anchor. Elevating Scaffold I from an [E-hyp] card to a ratified language-neutral mechanism in flow:org.vibevm.ai-native/core-ai-native (a sibling of PROP-014) is a separate, later, owner-decided step. Decide when the second operation lands.
2. Weak-tier parameterization (the [E-hyp] question, inherited from Scaffold I). Can the weakest swarm tier correctly parameterize an operation, or must the weakest tier be restricted to fixed-parameter invocations? The prime pilot question; answered empirically once rename-address / move-unit ship.
3. Transactional multi-tier operations. A rename-package fans out into discipline + language operations across many files; is the whole fan-out one transaction (all-or-nothing across tiers), or a checkpointed sequence? Lean: one transaction with a single post-gate, checkpointing only if wall-time forces it.
4. Concurrency with in-flight human edits. An operation assumes a quiescent tree; define the posture when the working tree is dirty (refuse? operate only on committed state?).
5. Undo / history. Beyond git revert — does the engine keep an operation journal for structured inverse operations, or is git the only undo? Lean: git is the undo; operations are designed to invert cleanly (a rename's inverse is a rename).
6. Redirect vs eager-retarget as the default (PROP-014 §7.3). rename-address eager-retargets; redirect stubs are the deferred/parallel path. Which is the default for a swarm run is a policy the operation exposes, not a fixed choice (SPECMAP Plan D1).

• 30This PROP is a design proposal. Ratification — and the first operation's implementation — happens through PR review against this document and the SPECMAP Unit-Mobility Plan.
• Any mechanism specified here that is not exercised by the second shipped operation is removed from the spec rather than carried as aspirational documentation (the PROP-014 §335 discipline, inherited).