Commit R

A test suite that grew alongside its code tends to pin the shape the code happened to take, not the outcome anyone wanted. Editing either one in place keeps that shape. Commit R removes both halves of one compartment and writes them again in the order that exposes the difference: first the tests, from a hypothesis about what the compartment is for, then the production code those tests now demand. The deletions are commits of their own while the pass runs, so each step can be read against the one before it. Before anything is pushed, a compartment's commits become one that passes the gate alone, and its body keeps the argument the steps made.

The compartment

The unit is a compartment: one subject, one target, one component. It is not a file. A compartment can span a test file, the module it tests, the constant table that module reads, and two adjacent functions in a neighbouring module that exist only to serve it. What holds it together is one question someone could want changed. Some examples of that kind of question:

• climbing: what the stop tells the operator;
• information handover: what one round leaves the next;
• prompting: what the Builder is told about the reference solve.

Each compartment gets its own hypothesis, written before any test: what should change, and why a production path at about half the complexity probably reaches the same outcome, or 90 to 95 percent of it — the super-Pareto form of rule 8 in AGENTS.md — and what it would give up if it does not reach all of it. Two compartments in one pass must carry different hypotheses. If they would share one, they are one compartment.

Take one to three compartments per pass, which usually comes to 500 to 2,000 test lines in all. Fewer than that finds nothing new, and more cannot be reviewed as one argument.

The sequence

Every step ends in a local commit. Only the last of a compartment's four could pass the gate on its own — an R: commit deletes files the rest of the tree imports, and the rewritten tests fail on purpose — so step 8 squashes them into one before anything is pushed, as AGENTS.md's commit policy requires of any working commit.

1. Commit what is in flight. Start from a clean tree, so the R commits remove only the compartment.

2. R: <test paths>. Read the test files in full first, and write down every boundary they hold, because the rewrite has to keep each one or say why it was dropped. Then git rm them and commit with the subject R: test/a.test.ts test/b.test.ts and nothing else.

3. Rewrite the tests from the hypothesis. Write for the outcome, not the old shape:

   • keep each boundary the old file held;
   • fold cases that now assert the same thing;
   • add the cases the hypothesis predicts.

   Run them. Production should fail on purpose, and only in the new cases. A new case that passes already is not testing the hypothesis, and an old boundary that now fails means the rewrite broke something rather than asked something. Commit, and in the body state the hypothesis and which cases fail on purpose.

4. Read why they fail, and look for the faster path. Before touching production, ask which module actually owns the behaviour, whether a simpler owner exists, and which adjacent functions or type members only served the old shape. Grep every export and every member of a union: a branch whose producer is gone is dead code to remove, not to preserve. Then look for the simpler algorithm, not only the simpler owner: the one that computes the answer once instead of twice, or drops a case the recorded evidence never reaches. A negative claim such as "nothing produces X" needs the grep against origin/main too, in the same turn.

5. R: <production paths>. git rm the production files the rewrite replaces, and commit with the subject R: src/x.ts src/y.ts.

6. Rewrite production, and fix or remove the outdated adjacent code. Make the new tests pass with the smallest owner that holds them. In the same commit:

   • patch the neighbouring modules and their tests;
   • delete what served only the old shape;
   • run typecheck, bun run lint -- --strict, bun tools/loc/source-policy.ts (no arguments) and bun tools/loc/complexity-policy.ts, plus every test file that imports the compartment.

   The body says what the rewrite found. Name any behaviour that changed, anything the simpler form gave up and how that was measured, and any code that looked dead but is left for the operator because a contract describes it as live.

7. Fix in place. Every published commit passes the gate on its own, so a finding on an earlier commit is fixed inside it: git commit --fixup=<sha>, then GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <sha>~1.

8. Squash the compartment. git reset --soft <the commit before its first R:>, then one commit titled for the change the compartment made, whose body joins the hypothesis, the cases that failed on purpose and what the rewrite found. Its diff holds every removed and returned line.

Then take the next compartment from step 2.

What a pass must not do

• Change model-visible text without flagging it as a new condition. A literal that reaches a Builder, Judge or reviewer moves a prompt digest. Say so in the commit body, and leave text whose change is an open operator decision out of scope.
• Silence a failing old test. It is either a boundary the rewrite keeps, or one the commit body retires, with the reason.
• Rewrite a compartment someone else is editing. Check scripts/worktree.sh list first.
• Push. It stays local, and the operator decides on publication as for any other branch. The pre-push gate then runs over each squashed compartment alone and over the pass's tip in full.

Report

For each compartment, report four things:

• the hypothesis;
• the four working commits (R, tests, R, production) and the squashed commit that replaced them;
• the test count, with how many failed on purpose and then passed;
• what the rewrite found: the owner moved, the branches removed, what the simpler form gave up, anything left for the operator.

State the line counts before and after, measured, not estimated. When the compartment gave nothing up, say that, because it is the claim a reader will check first.