Restructure: add a reference-integrity gate before moves

[dubedad]

Restructure: add a reference-integrity gate before moves

What this changes

Restructure mode currently: classify files → propose → migrate → validate with the walk test. This PR inserts one step — verify reference integrity, before proposing — and tightens two things around it.

• New step 4 (Verify reference integrity): before any file is proposed for a move, enumerate what depends on it across four scopes — in-vault, sibling-path (../), symlink, and external/cross-boundary (other repos or systems that hardcode paths in). This adds no new role — it flags a move: any file with a live referrer is held, and can't be classified Dead until the check comes back clean.
• Sharpened Dead role: a file is Dead only once step 4 confirms nothing depends on it. Apparent disuse is not proof.
• Migrate is now copy → verify parity → remove (never move-and-hope).
• Walk test gains a no-orphaned-references check: after a restructure, every reference that existed before the move must still resolve.
• New references/reference-integrity.md documents the method, tool-agnostically.

Two files, +73/−4. No new dependencies, no template changes, nothing mandatory outside Restructure mode.

Why — the gap

Restructure's flow is "migration map → wait for your yes → move and check the result." This PR gives the yes something to stand on. The map shows where each file goes; nothing shows what depends on it. So the walk test proves the result is navigable, but nothing checks whether the act of moving a file broke a dependency the move couldn't see. The skill already senses this — step 5 says to leave a link "if anything might reference it." "Might" is a hunch. This PR turns the hunch into a checked list the approval gate can stand on — and it stays tool-agnostic (documented as shapes of checks, not a mandated script) so it works the same under Claude or a codex agents.md.

This is impact analysis (the DAMA-DMBOK term for "what breaks if I change this"), applied to a folder instead of a database — and it strengthens the human gate the method already has, rather than adding new ceremony.

Where it came from — a real test run

I ran Restructure mode against a genuinely messy real workspace: ~68 project folders, ~30k files, accumulated output from months of work. Classification was good. But bolting on a reference check before approving any move caught two things the walk test would have sailed straight past:

1. The safest-looking file was the most load-bearing. The oldest, most obviously-superseded version of a deliverable — the one any "archive old versions" pass would move first — turned out to have the most inbound references (15), while every newer version had zero. Presence of a newer version said nothing about the old one's position in the dependency graph.
2. A dependency lived in another repo entirely. Live scripts in a separate project hardcoded paths into this workspace. A perfectly reasonable regroup would have silently broken them — and no in-vault search would ever have found them.

A third finding motivated the durability note: ~88 MB of active work was living only inside an ephemeral, git-ignored location, one cleanup away from unrecoverable. Reorganizing within a workspace that isn't itself durable is rearranging deck chairs.

None of these are exotic. They're the normal failure modes of moving files in a real system — which is exactly why a gate for them belongs in the tool.

Design notes

• Tool-agnostic on purpose. ICM runs under any agent, so reference-integrity.md documents the shape of each check with illustrative commands, not a mandated script.
• Fits the guardrails. It doesn't over-structure — it adds nothing to Build mode and nothing to workspaces that don't move files. It makes the existing human gate informed.
• Additive. The step numbers shift (4→5→6→7); no existing guidance is removed.

[VanCliefMedia]

Love it. Great catch