sglang/.claude/skills/mechanical-refactor-verify/guide-modify-skill.md

Modify this skill: the engine, the generator, or the spec

• How to change scripts/mechanical_refactor_reproduction_utils.py (the proof engine), scripts/mechanical_refactor_proof_generator.py (the generator), scripts/mechanical_refactor_reproduction_cli.py (the chain verifier), or the specs — without silently weakening the proof.
• Read this before editing any file under this skill. The engine is trusted: a wrong primitive certifies a non-mechanical commit as clean, and every downstream reviewer believes it. Changes here carry a higher bar than ordinary code.

1. What has which bar

File	Role	Bar
spec-reproduction-utils.md	normative source of truth (SKILL.md §2): the clean-move property, the whitelist / not-allowed lists, each primitive's contract, the arbiter	any behavior change lands here first
spec-reproduction-cli.md	normative source of truth for the chain verifier: the word rule, the proof obligation, the report, the exit codes	any behavior change lands here first
mechanical_refactor_reproduction_utils.py	trusted engine: the relocation primitives + the arbiter	highest — byte-faithfulness proven by tests
mechanical_refactor_proof_generator.py	convenience: infers a recipe from a diff	lower — may report RESIDUAL/UNSUPPORTED without compromising trust, but still tested
mechanical_refactor_reproduction_cli.py	gatekeeper: walks a chain, runs the proofs, reports	high — a false chain PASS certifies an unproven commit; classification, resolution, and PASS-criterion behavior proven by tests
guide-*.md, SKILL.md	workflow + file map	kept in sync, never describe behavior the code lacks

2. Cardinal rule — the spec leads, code follows

• spec-reproduction-utils.md wins over every other file (SKILL.md §2). Code serves the spec, not the reverse.
• A behavior change to a primitive, to §2.1/§2.2 (what counts as a clean move), or to the §4 arbiter must edit the spec in the same commit as the code. Code and spec never diverge across commits.
  • New primitive → add its contract to §3.
  • Changed clean-move boundary → edit §2.1 (allowed) / §2.2 (not allowed).
  • Changed reproduce/diff behavior → edit §4.
• If you discover code and spec already disagree, the spec is authoritative: fix the code to match — or, if the spec itself is wrong, change it deliberately in one commit with the reasoning, not as a silent side effect.

3. The faithfulness invariant — never break this

• Every primitive relocates original source bytes: AST-located, spliced as the source text that was there, never regenerated. A byte match after the formatter is the entire proof — the moment a primitive regenerates instead of splicing, the proof is worthless (it can no longer distinguish "moved" from "rewritten to look moved").
• A new or changed primitive must:
  • locate its target through the AST, not by string search over source;
  • splice the original bytes (interiors of multi-line strings, comments, a magic trailing comma, semicolon-joined statements all survive verbatim);
  • preserve the file's newline style (CRLF round-trips) and UTF-8-byte-accurate columns.
• Do not add a primitive that normalizes, reflows, or reformats. Formatting belongs to the pre-commit pass in the §4 arbiter, applied to both sides; primitives do relocation only.
• When the generator cannot infer a move, the answer is a hand-written Repro (guide-construct-proof §2.3) — not loosening a primitive to make it fit.

4. Testing rules — the hard bar

• The engine is trusted, so an untested change to it is not acceptable. "It ran once" is not a test.

• Run the full suite and keep it green:

  cd scripts && uv run --with pytest --python 3.12 python -m pytest tests/ -q
  

  Baseline at the time of writing: 188 passed. Your change must leave the count at or above baseline — never delete a case to make the suite pass.

• Layout mirrors the modules; put your test where it belongs:

  • tests/reproduction_utils/ — one test_<primitive>.py per engine primitive.
  • tests/proof_generator/ — the inference layer (test_infer_*, test_script_and_diff).
  • tests/reproduction_cli/ — the chain verifier (classification, proof discovery, chain walking, the report).

• A new or changed primitive requires, in its test_<primitive>.py:

  • a byte-exact assertion on the resulting file (compare full bytes, not "contains");
  • at least one adversarial case where a regenerating implementation would differ from splicing — a comment mid-body, a magic trailing comma, odd indentation, a semicolon-joined import, non-ASCII text, or a CRLF file — asserting the original bytes survive;
  • the raise paths the spec promises: ambiguous anchor raises, missing anchor raises, wrong/absent from_class raises.

• A change to the generator requires a tests/proof_generator/ case that runs it on a synthetic commit and asserts PASS, plus one non-move / bundled-change case that asserts RESIDUAL or UNSUPPORTED — so a future regression that makes it "pass" a dirty commit is caught.

• A change to the chain verifier requires a tests/reproduction_cli/ case asserting a verified chain passes, plus one asserting the broken shape it guards (an unclassified commit, a missing proof, a failing proof) still fails — so a regression cannot silently green a dirty chain.

• The engine stays self-contained: mechanical_refactor_reproduction_utils.py imports only git (via subprocess) and the standard library. Do not add a third-party dependency to it.

5. Before you commit — checklist

• spec-reproduction-utils.md / spec-reproduction-cli.md edited in this same commit (if any behavior changed).
• Full pytest suite green; case count ≥ prior baseline.
• New/changed primitive has: byte-exact test + ≥1 adversarial (regeneration-would-differ) case + the raise-path tests.
• Generator change has a PASS test and a RESIDUAL/UNSUPPORTED test.
• SKILL.md §3 file map and the relevant guide-*.md updated for any new file or workflow change.
• mechanical_refactor_reproduction_utils.py still imports only git + stdlib.