Skip to main content

Ratchets That Only Shrink: A Boundary You Can Grep and Code Only Tests Use

Coding agents are poor judges of architecture across a large codebase, but they reliably drive a failing check to zero. We used that twice: once to pull every messaging provider's name out of shared code, and once to delete production code that only tests called. Here is the playbook for turning a cleanup into a ratchet, with the numbers and the limits.

CatalEx Engineering · Published November 13, 2026 · 17:00 UTC

On October 23 we wrote down a rule for our relay codebase: shared code asks what a messaging provider can do, never which provider it is. No if provider == Slack. No case WhatsApp:. Differences that are facts go in a catalogue; differences that are behaviour go behind an interface each provider's adapter implements.

It is a good rule, and asking a coding agent to "apply it across the codebase" does not work. The agent reads a few hundred files, fixes the comparisons it notices, and reports the boundary clean. It is not lying. It cannot hold four modules in its head at once, and nothing tells it what it missed. So instead of asking, we counted. Within hours a guard listed 170 uses of a provider's name in shared code, file by file, and failed the build if any file's count went up. Or down.

A little over four hours and ten agent-written pull requests later, the count was zero. This post is about that pattern, a ratchet, and the second time we used it: deleting code that only tests called. Both times the agent did not need to judge the architecture. It needed a number that fails CI, and a rule that the number may only go one way.

Why agents need a number, not a principle​

An agent asked to clean up a boundary has three problems a person on the same task has less of.

  1. It cannot see the whole thing. Its context holds tens of files, not thousands. It judges each file well and the codebase poorly.
  2. It cannot tell when it is done. "The boundary is clean" is an opinion. Without a list, the agent stops when the files it looked at look fine.
  3. Its fixes can create new work. Moving a helper out of a provider-named file can strand a caller elsewhere. Deleting one dead function can make another one dead.

A check that scans the whole codebase solves the first problem. A count solves the second. A loop that reruns the check solves the third. A ratchet is all three: a scan, a recorded count per file, and a rule that the count may only shrink.

The non-obvious arrow is "lower, list not updated". Failing when the count drops sounds perverse. It is what makes the list honest. If fixes could lower the real count without lowering the recorded one, the slack would sit there and the next agent could spend it on a new violation. Forcing the list to match means every improvement is locked in the moment it lands.

Ratchet one: a boundary you can grep​

The rule and its first guard​

The rule lives in a path-scoped rule file that loads whenever an agent touches any of our five Go and TypeScript modules. Its first line is the principle; the rest is what the principle means in code:

.claude/rules/provider-boundary.md (summarised)
InstructionIn practice
No name comparisonsOutside a provider's own code, no if provider == X, no case, no map keyed by provider name
Facts in the catalogueHow senders are addressed, which account kinds exist, a credential field's name: each a declared capability every provider fills in
Behaviour behind a portSetup steps, verification, credential storage, ingress: an interface owned by the shared code, implemented by each adapter, registered once
Provider code stays homeA provider's code lives in its adapter package; a generic helper never lives in a provider-named file
Names on the wire stayExisting provider-named fields and stored values are kept; new ones are neutral

The guard that landed about an hour after the rule is a test-lint check that scans every module that has a provider-boundary.txt file. Production code may name a provider only under paths an allow line lists, such as the adapters and the one registry. Everything else that existed before the rule was recorded as known PATH COUNT. More uses in a file fail. Fewer uses fail too, until the count is lowered or the line removed.

43files on the known list
170recorded uses across 4 modules
~4 hfrom guard to an empty list
10agent pull requests to drain it

The largest share was in the hosted service: 22 files and 99 uses. The local component had 12 files and 53 uses, the shared internal library 5 and 8, the command-line client 4 and 10.

The drain​

Here is what the agents did with the list, in order. Every one of these pull requests carries a Claude co-author trailer, and they landed within about four hours of each other.

Pull requestChangeFilesLines
#1433Move generic gateway helpers out of Slack files10+488/−248
#1434Move Google Chat's gateway code into its package25+264/−142
#1435Move Slack's gateway code into its package53+1,145/−372
#1436Dispatch destination setup steps per provider8+684/−94
#1437Route setup actions through provider flows16+1,303/−263
#1438Empty the hosted service's boundary list46+3,448/−721
#1439Local component reads provider facts from a catalogue and one registry19+713/−118
#1440Command-line client reads platform facts from a catalogue and one registry11+481/−55
#1441Web app reads providers from a catalogue and registries33+661/−191
#1442Setup wizard reads its platforms from one registry12+219/−37

Then a final change, #1443, removed the known mechanism entirely. With every list at zero, any use outside an allow path now simply fails.

Notice the shape of the work. Each pull request is a refactor a person would recognise as sensible (move the helpers, introduce the catalogue, route through a port). But none of them required the agent to decide what "the boundary" meant across the whole system. The list told it which files, the count told it how much, and the build told it when that file was done.

Tightening the scan, and what it found​

A ratchet at zero is the moment to make the scan stricter, because the stricter scan shows you what the first one could not see.

On November 3 the check learned to find a provider's name inside an identifier (accountWhatsApp, SlackFoo) or inside a file or directory name (account_whatsapp.go), not only as a whole word. The change fixed what the stricter scan caught in the same pull request and removed one allow line from the local component.

On November 4 we went further for the local component, the part that runs on a user's machine. The decision record is blunt about why: the October decision had removed name comparisons, "but Local Relay kept a registry, a catalogue copy, provider-shaped fields, provider link hosts and wording. Adding a provider still meant a Local Relay release." The first ratchet had done exactly what it measured, and the thing it measured was narrower than the goal.

So the new rule for that component is that it names no provider at all: not in code, not in strings, not in comments. That is enforced by a Semgrep rule, local-relay-provider-name, that runs a case-insensitive regular expression over the component's production paths and excludes tests. It runs in the rule checks the merge gate executes on every pull request's exact head.

.semgrep/tests/local-relay-provider-name.txt (excerpt)
LineExpected
Open Slack to finish.flagged
send by whats appflagged
the GOOGLE_CLOUD projectflagged
https://console.cloud.google.com/apisflagged
the Google sign-in page and an MCP server's nameallowed
tool.Meta = mcp.Metaallowed
a margin of errorallowed

The last row is there for a reason. The rule file tells agents to write "margin" where they would otherwise write the English word that happens to share its spelling with a messaging product, "since the scan cannot tell the English word from the product". It is a small, slightly absurd concession, and the right one: the price of a check that a regex can run is that you write code the regex can read.

The refactors that followed were large, and again agent-written:

CommitChangeFilesLines
Nov 4Remove provider knowledge from the local component124+5,778/−1,647
Nov 4Move provider calls from the local component to the hosted service137+8,740/−1,061
Nov 4Delete provider forwarding75+625/−9,744
Nov 8Keep the local component unaware of shared links41+585/−552

By the morning of November 13, the local component's allowlist has zero allow lines. Across all modules, the allowlists hold three lines. The hosted service has no list at all: its boundary test infers which code belongs to a provider from the code itself, and also refuses an import of one provider's package from another's.

Ratchet two: code only tests use​

The blind spots​

Our Go modules already ran golangci-lint with the unused linter, and it reported zero findings. A research note on November 12 asked whether that zero was real. It found two blind spots.

  1. Lint only looked at changed files. The module's lint-check target reports issues only in files changed since a base revision. Delete the last caller of a function in file A, and the now-dead function in file B is never reported, because B did not change.
  2. A test is a caller. unused counts a function called only by its own tests as used. Code whose production caller was replaced, but whose tests kept it alive, looks healthy forever.

The note measured each candidate tool against the same question: could it be a hard gate, or only a report?

ToolWhat it findsFindingsVerdict
unused, whole module, tests includedUnreferenced unexported code0Already clean, but only if run on the whole module
unused with run.tests: falseUnexported code only tests call30 identifiers (after removing other-OS false positives)Gate it
deadcode from each main, without -testAny function no program reaches, exported included493Too noisy for a gate: test helpers, reflection targets, code another OS calls
deadcode -testFunctions nothing reaches, not even testsA handfulGate it, with an allowlist for reflection

And one finding that shaped the rest of the work: neither tool deletes code. Both only report. The note says deletion stays a manual or agent task, "repeated until no new findings appear, because deleting one function can strand another".

Deletion as a loop​

That sentence is the whole design. The agent is not asked to find dead code. The tools find it. The agent is asked to delete what the tools report, along with the tests that only exercised it, and then run the tools again.

Three details keep the loop from producing false work.

  • Intersect across operating systems. A function called only from a _windows.go file looks dead on Linux. The check runs under each target OS and fails only on what is dead under all of them.
  • Allowlist with reasons. A method that only reflection calls is invisible to the call graph. It goes in a root .deadcode-allow file, one package-qualified name per line, under a comment that says why it runs. After the last change in this series it holds four names: two configuration decoders a mapping library calls through reflection, and the two helpers only they reach.
  • Skip packages that exist for tests. Packages with a path segment like testutil, fakes or mocks are expected to be reached only by tests. Whole segments only, so a production package named harness or mockconnector stays checked.

The deletions​

The first pull request landed the night the research note was written, and the rest followed through November 13. Each module was its own loop, and five of the six changes carry a Claude co-author trailer.

CommitChangeFilesLines
#2786Delete test-only code and gate it in lint-check63+408/−782
#2808Remove exports only tests call (hosted service)112+1,183/−1,167
#2843Remove exports only tests call (tools)6+26/−148
#2845Remove exports only tests call (local component)102+2,619/−2,331
#2848Remove the last test-only exports (local component)38+388/−1,797
#2859Fail lint on exports only tests reach44+459/−1,825
30unexported identifiers only tests called
−8,050lines deleted across six changes
+5,083lines added, mostly rewritten tests

The insertion column is the honest part of the table. Removing an export that only tests call usually means the test was testing an internal seam. To keep the behaviour covered, the test has to be rewritten to go through the public path, and that is new code. Net, the codebase lost about 3,000 lines. Gross, the agents touched about 13,000.

The gate, staged​

The gate went in two steps, which is a ratchet of its own.

  1. With the first deletion, lint-check gained a dead-code-check that runs on the whole module, not just changed files: unused with tests, unused without them, and deadcode -test. The gap that remained, exported code only tests reach, was filed as a numbered tech-debt item in the same change.
  2. With the last deletion, the check added deadcode without -test, restricted to production packages and minus what the previous step already reports. That closed the tech-debt item. A clean run ends with the line dead code: none.

The order matters. Turning on the exported check first would have failed the lint of every module with findings until the agents finished. Turning it on last means it starts at zero, and from then on any change that leaves code only tests reach fails in the author's own lint run.

The playbook​

The two stories differ in tools, and the pattern is the same. Here is what to do in each situation.

SituationDo thisWhy
You have a principle and many violationsWrite a scan, record known PATH COUNT per file, fail on higher and on lowerAgents get a list, a count, and a definition of done
An agent says "the boundary is clean"Ask what check says so; if none, write oneThe agent judged the files it saw, not the codebase
The list reaches zeroRetire the list and tighten the scanThe stricter scan shows what the first one missed
A rule can only be checked by reading EnglishChange the vocabulary so a regex can read it"margin" over the product name is cheap; a false positive per week is not
Lint only checks changed filesRun the dead-code check on the whole moduleDeleting a caller in A must fail for the dead code in B
A tool is too noisy for a gateNarrow it (other OS, reflection, test packages) and allowlist with reasons493 findings is a report; zero after narrowing is a gate
Deletion strands more codeLoop: delete, rescan, until no new findingsOne function's death can be another's
Turning on a check would break everythingDrain first, gate last; file the remainder as tech debtThe gate starts at zero and only ratchets

Failure modes, and the check for each​

Failure modeLooks likeCaught by
New violation in an old fileA provider name added to a file already on the listCount goes up: fail
Silent slackA file fixed but its count not loweredCount goes down without the list: fail
Name hidden in an identifieraccountWhatsAppIdentifier and file-name scan (since Nov 3)
Name in a comment or string"Open Slack to finish." in the local componentSemgrep over all text (since Nov 4)
Dead code in an unchanged fileLast caller deleted elsewhereWhole-module dead-code check
Code kept alive by its testsProduction caller replaced, tests remainunused without tests; deadcode without -test
False dead codeReflection target, other-OS caller.deadcode-allow with a reason; OS intersection

What this does not fix​

  • A ratchet is not proof. The boundary check finds names. It does not find a shared function that branches on a capability so specific it is a provider name in disguise. The dead-code check finds unreachable functions. It does not find reachable code nobody needs.
  • The scans are only as wide as their patterns. The first guard missed names inside identifiers for more than ten days. The web app's check still covers quoted names, object keys and file names, but not identifiers. Each gap is a place the count reads zero and the goal is not met.
  • Agents still make the design calls inside each file. The ratchet tells the agent where to work, not how. Whether a difference is a fact for the catalogue or behaviour for a port is a judgement, and the agent's judgement is only as good as the rule file's examples.
  • Exceptions accumulate quietly. An allowlist line is cheap to add. We keep them few by requiring a reason beside each one, and by reviewing allowlist changes like any other code. That is a habit, not a check.

What it costs​

  • Big diffs. The boundary refactors added far more than they removed in the hosted service (+8,740 in one change), because ports and catalogues are more code than an if. Reviewing them is real work, even when an agent wrote them.
  • Rewritten tests. About 5,000 lines of new test code came with the deletions. Some of those tests are now slower, because they go through a public path instead of calling an internal function.
  • Lint time. The dead-code check builds call graphs for two or three operating systems on every lint run of every module.
  • Vocabulary constraints. Writing "margin" because a regex cannot tell a word from a product is a small tax on everyone who writes a comment in that component, forever.

An agent cannot tell you whether your architecture is clean. It can drive a number to zero and keep it there. Give it the number.


Written by CatalEx Engineering. We build the AI operating layer for AI-native companies: one platform to build, deploy, and run AI agents in production. More at catalex.co.