The #138 refactor was undone within hours — add a size ratchet so decomposition holds

[serge-ivo]

The evidence

packages/sdk/src/voice/use-voice.ts, measured over one day:

When	LOC
#138 filed	1127
this morning	1441
after f194a72 (the #138 refactor)	1315
now, hours later	1532

The refactor removed 126 lines and was fully undone within hours — the file is now larger than
it was when the refactor started, and 36% above the number in the ticket that asked for it.

f194a72 was good work. Its commit body explains, with measurements, why the three sub-hooks the
ticket named were the wrong seams (ttsRef is read at ~20 sites because "is the agent speaking" is
an input to the guard model, so a useTts would hand the refs straight back out) and extracts what
genuinely separates instead: cues.ts and voice-audio.ts, with tests.

None of that survives contact with the next feature. There is no mechanism keeping it.

The general shape

The largest files are also the untested ones:

1695  workers/api/src/routes/instances.ts
1646  workers/api/src/routes/coding.ts
1532  packages/sdk/src/voice/use-voice.ts      no test file
1216  agents/coder/web/src/CodingTab.tsx       no test file
1148  store/console/src/tabs/SettingsTab.tsx   no test file
1141  store/console/src/pages/InstanceDetail.tsx

That correlation is not incidental — a file too large to test is where behaviour goes to hide. Two
of today's bugs were in exactly these files: #240 (stale tab data / cross-agent save,
InstanceDetail) and #241 (unrecoverable offline state, CodingTab). Both were found by
reading, because nothing else could find them.

Proposal: a ratchet, not another refactor ticket

A size check in CI over a small allowlist of known-large files, each pinned at its current LOC:

• exceeding the pin fails, with a message naming the file and the ticket for splitting it;
• lowering the pin is a normal part of any PR that shrinks the file;
• new files over a threshold need an entry, which makes adding one a decision.

This is the same shape as the guard added for #231 (a test that scans the tree for raw
UPDATE agent_instances SET config, because "a reviewer cannot be expected to catch the
seventeenth by eye"). Same reasoning: the fix holds only if something keeps it held.

Cheap, and it converts "we should refactor that someday" into "you cannot make it worse without
saying so."

Not proposed

Reopening #138. Its conclusion — that the remaining code is imperative sequencing over shared
mutable state and does not decompose into the hooks that were imagined — was correct and measured.
The problem is not that the split was wrong; it is that nothing defends the ground it took.

[serge-ivo]

Shipped in 80c5149 — scripts/check-file-size.mjs, wired into ci.yml and available as pnpm size:check. 17 known-large files pinned at their length at ee819e3.

Three arms, and the second is what makes it a ratchet rather than a ceiling

condition	result
over the pin	fail — split it, or raise the pin in the same commit, which makes growth a decision someone signed
under pin - 40	fail — a file that SHRANK must record its new floor
new file over 800 lines	fail — needs an entry, so adding one is a decision

Without the shrink arm, f194a72's 126 lines stay available as headroom and the file walks straight back up to its pin — which is precisely, numerically, what the ticket documents.

Verified red by mutation, against the ticket's own file, then reverted

+6 lines    → "grew to 1539 lines, pinned at 1533 (+6)"                        exit 1
-120 lines  → "is 1413 lines but pinned at 1533 (-120)… Lower its entry to 1413" exit 1
new 901-line tracked file → "has no entry… Add \"…\": 901,"                    exit 1

Two deliberate exclusions

• Tests are not counted. The ticket's own observation is that the largest files are also the untested ones; a guard that fires when you add tests punishes the only thing that fixes the problem it is about.
• git ls-files, not a directory walk — generated output (workers/host/src/pages.ts, store/docs/), dist/ and the per-session .claude/worktrees/* checkouts are excluded for free, rather than by maintaining a fourth copy of the same ignore list.

Lines are counted the way wc -l counts them, comments included: this codebase explains itself at length and that prose is load-bearing, so a "code lines only" metric would reward deleting the explanations.

⚠️ Heads-up for concurrent work: store/console/src/{pages/InstanceDetail.tsx,tabs/SettingsTab.tsx}, agents/coder/web/src/CodingTab.tsx and workers/api/src/lib/connectors/mcp.ts are pinned at their current size. In-flight branches that grow or shrink them by more than the slack will need their pin adjusted in the same commit — that is the intended workflow, and the failure message names the file and the exact number to write.

#138 stays closed; its conclusion was correct. This defends the ground it took.

Note: no CI run verified this. GitHub Actions is in a declared major outage and dispatched nothing for the push; verified locally instead.