/tranche

name: blueprint-refactor-tranche
description: "Take ONE target from the plan and land it without changing behaviour: guard it on the untouched code, move it verbatim, prove the equivalence by running both, mutation-sweep the tests, pass every gate, open a PR and merge it on green CI — or decline it with the cost written down."

One target, one change

This step repeats. Each round does **one** target from `.blueprint/targets.json` — the first whose status is `todo` — and nothing else. The whole claim of the change is **"this behaves the same"**, and that is not provable by reading. What follows is how it is proved instead.

Read `.blueprint/spec.md` (the plan the person approved), `.blueprint/gates.json` (the gates) and `.blueprint/answers.json` (`merge`: whether to merge on green CI).

0. The approved plan wins

The person may have changed the plan by talking to it at the review gate, which rewrites `spec.md` but not `targets.json`. If the two disagree — a target added, dropped, reordered or reworded — bring `targets.json` in line with `spec.md` first. Keep finished targets as they are.

A `ci` target

Close the gaps in `.blueprint/ci.json` with the smallest change: prefer adding a step to the workflow that already installs dependencies over a new workflow, and use the install command from `gates.json`. Every workflow gets a top-level `permissions:` block (default `contents: read`; a job gets more only if it needs it) and `actions/checkout` gets `persist-credentials: false`. Then continue from step 8 — the pull request's own checks are the proof that the new CI runs and passes.

1. Start clean, and check nobody else is in the file

• On the default branch, `git pull --ff-only`. Branch: `blueprint/<target id>`.
• `gh pr list --state open` and `git log origin/<default> --oneline -20 -- <files>`. A pull request merged an

hour ago is in neither your tree nor the open list. If someone else is changing these lines, mark the target `skipped` with that as the note, and stop the round.

• Confirm the target is still reachable: grep for its caller or renderer, not its import.

2. Find the guards before touching anything

grep -rln "<file basename>" test/ tests/ src/ --include='*.test.*' --include='*.spec.*'
grep -rn "'<identifier>'\|\"<identifier>\"" test/ tests/ src/

Sort the hits: **behavioural** tests call the code and break loudly. **Source-text** guards (a test that reads a file and looks for a string, a census, an AST scan) **fail open**: when the text moves they go vacuously green, still running and checking nothing. Each of those has to be re-pointed by what it protected (step 5), and a guard should derive its population rather than carry a list written down.

3. Write the missing guard against the UNMODIFIED code

If the behaviour you are about to move — above all an ordering or a shared answer that holds only because the code is adjacent — has no test, write one **now**, on the untouched code, where it passes. Then **break-verify it on the untouched code**: insert exactly the defect the move could introduce and watch it go red. A guard written after the move pins the new shape and proves nothing about the old one.

Commit the guard on its own (`test:` prefix) before the move. For a `test`-kind target this is the whole change: tests for untested, high-value logic, each one mutation-verified (step 7).

4. Move the text verbatim

• The moved body is the original text with mechanical renames only. No "while I'm here" tidying — a

cleanup mixed into a move destroys the only cheap proof you have.

• Pick the move from what the **call site** does on each path. Does this path already `await`?
• An `async` helper suspends its caller even on a path that reaches no `await`: one more microtask before

everything after it. Write the helper synchronous first; keep the `await` at the call site.

• A write to shared state (a module singleton, `process.env`, a registry) and the call that reads it must

stay in one continuation. If the region does I/O and then writes, split it: the async half returns a plan, a synchronous half applies it at the call site.

• `let x;` filled by the block below it → `const x = f(…)`: the canonical, checkable move.
• Prove only the control flow changed: a multiset of the file's code lines against the default branch,

comments stripped, should show only the inversion.

  strip() { grep -vE '^\s*(//|\*|/\*)' "$1" | sed 's/[[:space:]]//g' | grep -v '^$' | sort; }
  diff <(git show origin/<default>:<file> | strip /dev/stdin) <(strip <file>)

5. Re-point every source-text guard by what it protected

Never by where it sat. For each moved anchor: what defect was this there to catch, and where can that defect now appear? Sometimes that is two places — inside the helper **and** around its call. Break-verify each re-pointing.

6. Prove the equivalence — run both, do not reason

In order of preference:

1. **Replica differential.** Copy the OLD code verbatim into a throwaway harness and run it beside the new code over **generated** inputs — not inputs you chose; the ones you would think of are the ones you already believe are equal. Compare the whole result (`JSON.stringify` both sides), and treat a throw as an outcome (`ok:<value>` vs `threw:<message>`). Generate deliberately: missing keys, `null` elements, falsy-but-not-nullish (`0`, `''`, `false`), both alternatives of a `??`/`||` chain present at once, the same value at two positions, keys every object has (`constructor`, `__proto__`). 2. **Drive it** through the seam the codebase already has (an injected clock, client, or `realpath`). 3. Verbatim body plus the guards — and say out loud that this is all it rests on.

**Mutation-verify the harness** before trusting its zero: change one edited line in the new code and the harness must report differences. A zero it cannot move off is not a measurement.

Before deleting the harness, **harves