mechanical-refactor-verify

1---2name: mechanical-refactor-verify3description: Make mechanical refactoring (file splits, function moves, module extractions, renames) machine-checkable instead of eyeballed. Reproduce a relocation commit byte-for-byte from faithful primitives, and split an extraction into a verifiable prepare + move + postpare. Use when doing or reviewing such changes.4user_invocable: true5argument: "split <base>..<tip> | construct <base>..<tip> [--match REGEX] [--out DIR] | verify --base <base> --branch <branch> --proof <folder> [--jobs N] [--skip-passed]"6---7 8# Mechanical Refactor — Machine-Checkable Verification9 10## 1. Overview11 12- The correctness of a mechanical change (file split, function move, module extraction,13  rename) must be **machine-checkable, not eyeballed** — the proof is something anyone can14  re-run, whoever made the change and whenever.15- **One property**: *a commit is a pure relocation*. **One proof**: **reproduce** —16  regenerate the move from the base commit with faithful primitives, run the formatter,17  byte-diff against the target.18- Empty diff = the proof. Any residual = a bundled non-move change, surfaced for review.19- A reshape must not ride along: split into optional **prepare** + certified **move** +20  optional **postpare** (`guide-split.md`).21 22## 2. Commands — what do you want to do?23 24The skill takes an argument naming one of three commands; invoked without one, pick the25row matching your task.26 27- **`split <base>..<tip>`** — author a compliant refactor branch: split it into commits,28  satisfy the contract (extract, move, file split) → `guide-split.md`: §1 splits the PR29  into classified pieces (the chain contract: classification format, correct labeling,30  proofs PASS, non-mechanical commits correctness-reviewed); §2 splits one piece into31  prepare + move + postpare (the case recipes and the anti-patterns). The argument is the32  chain to author (or a single commit / a description of the change to split).33- **`construct <base>..<tip> [--match REGEX] [--out DIR]`** — construct the proof, for34  the chain or one commit → `guide-construct-proof.md`: §1 generates + publishes the35  whole chain's proof folder (the flags are the generator's:36  `scripts/mechanical_refactor_proof_generator.py <base>..<tip> --match REGEX --out DIR`);37  §2 proves a single commit — pass just `<commit>` (the generator, or a hand-written38  `Repro` when it reports `UNSUPPORTED`).39- **`verify --base <base> --branch <branch> --proof <folder> [--jobs N] [--skip-passed]`**40  — verify someone's proof: a whole chain / PR branch → `guide-verify-proof.md`: run the41  chain verifier with exactly these flags42  (`scripts/mechanical_refactor_reproduction_cli.py`) — it checks every commit declares43  `mechanical_provable` or `non_mechanical_provable`, runs **every** provable commit's44  proof (never a sample), and writes one full report; then audit the authored surfaces45  and the `HUMAN_REVIEW` rows. Re-running one commit's script is for diagnosis only.46- **Decide whether a change counts as a clean move** → `spec-reproduction-utils.md`: the47  property, the whole whitelist / not-allowed list, and each primitive's contract. The48  source of truth for the reproduction module; if any other file disagrees, it wins.49- **Change this skill itself** (edit the engine, the generator, or the spec) →50  `guide-modify-skill.md`: the spec-leads rule, the faithfulness invariant, and the testing51  bar a change must clear before it is trusted.52 53## 3. Files54 55- [`guide-split.md`](guide-split.md) — split the PR into classified pieces (§1, the56  chain contract) and each piece into prepare + move + postpare (§2: case recipes, what57  stays mechanical, anti-patterns).58- [`guide-construct-proof.md`](guide-construct-proof.md) — produce the proof: the whole59  chain's proof folder + publishing (§1), and a single commit's proof — generator or60  hand-written `Repro` (§2).61- [`guide-verify-proof.md`](guide-verify-proof.md) — consume the proof: the whole-chain62  verifier, single-commit re-runs, verdicts, and the audit checklist for authored63  surfaces.64- [`spec-reproduction-utils.md`](spec-reproduction-utils.md) — the normative spec of the65  clean-move property and the reproduction primitives.66- [`spec-reproduction-cli.md`](spec-reproduction-cli.md) — the normative spec of the67  verified-chain property: the classification word rule, the proof obligation, the report,68  and the exit codes.69- [`guide-modify-skill.md`](guide-modify-skill.md) — change the engine, the generator, or70  the spec: the spec-leads rule, the byte-faithfulness invariant, and the testing bar.71- [`scripts/mechanical_refactor_proof_generator.py`](scripts/mechanical_refactor_proof_generator.py) —72  the **generator**: infers a reproduce recipe from a commit's diff and emits/runs a73  standalone, auditable script per commit, with a `PASS` / `RESIDUAL` / `UNSUPPORTED` verdict.74- [`scripts/mechanical_refactor_reproduction_utils.py`](scripts/mechanical_refactor_reproduction_utils.py) — the75  **proof engine**: the `Repro` builder's faithful relocation primitives plus the worktree +76  pre-commit + byte-diff scaffold. Self-contained — only git and the standard library.77- [`scripts/mechanical_refactor_reproduction_cli.py`](scripts/mechanical_refactor_reproduction_cli.py) — the78  **chain verifier**: classifies every commit in `base..branch`, runs every provable79  commit's proof from the proof folder, and emits the full chain report.80- [`scripts/tests/`](scripts/tests/) — pytest suites, one folder per module:81  `reproduction_utils/` for the proof engine, `proof_generator/` for the generator,82  `reproduction_cli/` for the chain verifier.83