Migrate

---
name: migrate
description: Move an in-flight two-file work into the folder layout — snapshot, log and artifacts into .genius/<slug>/, the contract out into CONTRACT.md, every link rebased. In-flight only; finished work is never converted.
disable-model-invocation: true
argument-hint: "a work slug, or nothing to list the in-flight works that could move"
---

# Migrate

Work written before the folder layout reads correctly as it stands: a snapshot and a log flat in `.genius/` is this format before the folder, not an older one. What it cannot do is grow a `CONTRACT.md` — that file lives in a work's own folder, and `.genius/` holds only what spans works — so its contract stays in the snapshot, and the snapshot stays over its ceiling however faithfully anyone compacts it (`/compact` reports exactly this and stops). This command is the way out, and the only one.

The concept: **the user's command moves a work that is still being built; nothing else is ever moved.** Two rules do most of the deciding, and both come from rulings this flow already made.

- **In flight only.** `stage: done` is a hard stop, whatever the argument says. A finished work's record is worth what it is worth because it is what was written then; converting one is assembling a record afterwards. (The leg of that ruling which said no migration path should ship at all was overturned on measured evidence; `AGENTS.md` carries the account, including which two legs still stand. This is one of them.)
- **Older formats never move either.** They finish in the shape they started. ⚠ **Never take a `<slug>/` folder as the mark of one** — the current layout gives every work a folder, so the folder tells you nothing and the discriminator is content. The `genius-file` skill's format holds it; read it there rather than carrying a second copy here, since a copy that drifts here rejects work the format accepts.

## What a migration is

Five moves, and the first four are mechanical:

1. **The folder.** ⚠ **Check `.genius/<slug>/` does not already exist first** — the older per-stage format used that same name, and moving into it merges two formats silently. Then `<slug>.md` and `<slug>.log.md` move with the repository's own move (`git mv` where it is tracked), plus this work's artifacts — a prototype, a screenshot, a report — which until now had no home and have been sitting loose in `.genius/`. Find them by reading the snapshot and the log; anything left loose in `.genius/` that neither names is reported, never guessed at, because that directory is supposed to hold only what spans works.
2. **The contract, into its two layers — where there is one.** A work that never ran Galvanizing has no contract and gets no `CONTRACT.md`; absence is the record there too. Where there is one: the brief, the test seams and the pinned values go to the plan layer; the conventions slices established go to the established layer, each with its source link. ⚠ A block belongs to the plan layer if a version bump should replace it — a page-height rule the *user* changed is contract v2 itself, not something a slice established, however late it arrived. Getting this wrong costs nothing today and everything at the next bump, which replaces the plan layer whole.
3. **The closed slices, collapsed.** Each to its line and its links, the displaced text appended to the log verbatim. ⚠ **Read the paragraphs one at a time, and answer the format's question of each: does this paragraph hold a constraint `CONTRACT.md` does not already have?** Report the yes-or-no per slice in the proposal, so that having read them is visible in the output rather than claimed. This is the step that can lose something: a closed slice's paragraph is where corrections live — a line saying an earlier line got the map wrong is both a constraint and a record, and routing by shape rather than by reading is how a later slice follows the map that was already corrected once.
4. **The links, rebased — in both directions.** Inside the folder they are siblings, so a work file's own path to its artifact becomes the bare filename: **a path written from the repository root breaks at exactly this moment**, and those live in prose and backticks where a link checker never looks, so they are read for, not scanned for. From `.genius/BACKLOG.md`, `BACKLOG.log.md`, `DECIDED.md` and `HISTORY.md` the links gain the slug's folder. **Rebase every one of them, not the ones you happen to notice** — the format's link rule says why a file left half on each basis is worse than one left wholly on the old. Where a link points at a log heading whose key carries prose, the format holds that repair too, and this pass is where the temptation to fix the heading instead is strongest: the log is moving anyway.
   ⚠ **When other works are still flat, those files at `.genius/` cannot be all on one basis.** Migrating one work makes them mixed by definition. Say so in the report rather than pretending otherwise, and offer the only thing that resolves it: migrate the rest, or accept mixed bases with the rule that a link's basis is told by whether the work it names has a folder.
5. **The compaction.** Once the folder exists, all three destinations do, so the work-file question can finally be answered in full (`genius-file`'s format holds it; `/compact` does this move on its own for work already in a folder).

## How it runs

- **Propose, then move.** Read-only until the user has seen: which files move where, what the contract splits into, what each closed slice collapses to, which links get rebased and how many, and the character count before and after, counted the way the format counts — instrument and exclusions both, read there rather than from memory, because a migration's whole case to the user is that number moving. One confirmation covers the batch.
- **`.genius/BACKLOG.log.md` is the one log this command may write, and only its paths.** A retired or merged seed's body went in carrying the links it had, and this move invalidates them exactly as it invalidates the ones in `BACKLOG.md`. Rebase those paths and nothing else — not a word of the entry's text — and name in the report which entries were touched, because a file whose rule is append-only has just been written to and the reader deserves to know it was this command. **What separates it from the log below is what the file is to this move**: the cross-work files are bystanders holding pointers *into* the thing being moved, and a pointer is maintained rather than rewritten; the work's own log is the record being moved, and editing a record to match its new address is changing testimony. ⚠ The cross-work files at `.genius/` are never themselves migrated into a folder, whatever their shape — the format states that exemption and its why for every pass that reads shape rather than names.
- **The log moves; it is never edited.** Not to fix an anchor, not to tidy a heading, not to remove a duplicate. Appending the displaced text is the only writing this command does to it. ⚠ **So a link written inside the log on the old basis — to `BACKLOG.md`, or to a sibling work's file, one level up after the move — is broken by this move and cannot be repaired here.** That is the append-only rule costing something real, and the honest price is naming those links in the report as broken by the move, separately from what the work arrived broken. Editing the log to turn the check green would buy a green check by spending the thing the log is for.
- **Nothing is deleted, ever.** Every line of the old snapshot lands in the new snapshot, `CONTRACT.md`, the log, or `BACKLOG.md` as a seed pointing at the log. A migration that cannot place a line stops and says which line.
- **Report both directions afterwards**: every link *this command may write* resolves — the new snapshot, `CONTRACT.md`, and the files at `.genius/` — and every log entry is reachable from the snapshot. Breakage the report names comes in two kinds and they are not the same finding: what arrived with the work is inherited, and what the move broke inside the log is the move's, unfixable here by the rule above. Neither is quietly fixed or quietly left — and check before calling anything broken, since a heading whose key carries prose looks missing and is not.
- **Check that nothing binding left the binding layer.** Every line that was in the snapshot's contract section is now in `CONTRACT.md` or the new snapshot. This command splits the contract, so it is the one most able to demote a live constraint to history — and a line that reached only the log has been demoted, silently.
- **The work file records its own move.** A `## migrated-<date>` entry naming what moved where, and the snapshot's `next:` written — a work older than the folder layout predates that field, so it usually has none, and a resuming session's first question is the one it answers.

Done when the work reads from its folder with nothing lost, every link this pass could write resolving, and the report saying plainly what was inherited broken, what the move broke in the log, and what this pass changed. A work that should not have moved — done, or an older format — is named with the reason, and left alone.