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.
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.
- It cannot see the whole thing. Its context holds tens of files, not thousands. It judges each file well and the codebase poorly.
- 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.
- 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:
| Instruction | In practice |
|---|---|
| No name comparisons | Outside a provider's own code, no if provider == X, no case, no map keyed by provider name |
| Facts in the catalogue | How senders are addressed, which account kinds exist, a credential field's name: each a declared capability every provider fills in |
| Behaviour behind a port | Setup steps, verification, credential storage, ingress: an interface owned by the shared code, implemented by each adapter, registered once |
| Provider code stays home | A provider's code lives in its adapter package; a generic helper never lives in a provider-named file |
| Names on the wire stay | Existing 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.
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 request | Change | Files | Lines |
|---|---|---|---|
| #1433 | Move generic gateway helpers out of Slack files | 10 | +488/−248 |
| #1434 | Move Google Chat's gateway code into its package | 25 | +264/−142 |
| #1435 | Move Slack's gateway code into its package | 53 | +1,145/−372 |
| #1436 | Dispatch destination setup steps per provider | 8 | +684/−94 |
| #1437 | Route setup actions through provider flows | 16 | +1,303/−263 |
| #1438 | Empty the hosted service's boundary list | 46 | +3,448/−721 |
| #1439 | Local component reads provider facts from a catalogue and one registry | 19 | +713/−118 |
| #1440 | Command-line client reads platform facts from a catalogue and one registry | 11 | +481/−55 |
| #1441 | Web app reads providers from a catalogue and registries | 33 | +661/−191 |
| #1442 | Setup wizard reads its platforms from one registry | 12 | +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.
| Line | Expected |
|---|---|
| Open Slack to finish. | flagged |
| send by whats app | flagged |
| the GOOGLE_CLOUD project | flagged |
| https://console.cloud.google.com/apis | flagged |
| the Google sign-in page and an MCP server's name | allowed |
| tool.Meta = mcp.Meta | allowed |
| a margin of error | allowed |
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:
| Commit | Change | Files | Lines |
|---|---|---|---|
| Nov 4 | Remove provider knowledge from the local component | 124 | +5,778/−1,647 |
| Nov 4 | Move provider calls from the local component to the hosted service | 137 | +8,740/−1,061 |
| Nov 4 | Delete provider forwarding | 75 | +625/−9,744 |
| Nov 8 | Keep the local component unaware of shared links | 41 | +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.
- Lint only looked at changed files. The module's
lint-checktarget 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. - A test is a caller.
unusedcounts 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?
| Tool | What it finds | Findings | Verdict |
|---|---|---|---|
unused, whole module, tests included | Unreferenced unexported code | 0 | Already clean, but only if run on the whole module |
unused with run.tests: false | Unexported code only tests call | 30 identifiers (after removing other-OS false positives) | Gate it |
deadcode from each main, without -test | Any function no program reaches, exported included | 493 | Too noisy for a gate: test helpers, reflection targets, code another OS calls |
deadcode -test | Functions nothing reaches, not even tests | A handful | Gate 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.gofile 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-allowfile, 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,fakesormocksare expected to be reached only by tests. Whole segments only, so a production package namedharnessormockconnectorstays 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.
| Commit | Change | Files | Lines |
|---|---|---|---|
| #2786 | Delete test-only code and gate it in lint-check | 63 | +408/−782 |
| #2808 | Remove exports only tests call (hosted service) | 112 | +1,183/−1,167 |
| #2843 | Remove exports only tests call (tools) | 6 | +26/−148 |
| #2845 | Remove exports only tests call (local component) | 102 | +2,619/−2,331 |
| #2848 | Remove the last test-only exports (local component) | 38 | +388/−1,797 |
| #2859 | Fail lint on exports only tests reach | 44 | +459/−1,825 |
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.
- With the first deletion,
lint-checkgained adead-code-checkthat runs on the whole module, not just changed files:unusedwith tests,unusedwithout them, anddeadcode -test. The gap that remained, exported code only tests reach, was filed as a numbered tech-debt item in the same change. - With the last deletion, the check added
deadcodewithout-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 linedead 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.
| Situation | Do this | Why |
|---|---|---|
| You have a principle and many violations | Write a scan, record known PATH COUNT per file, fail on higher and on lower | Agents 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 one | The agent judged the files it saw, not the codebase |
| The list reaches zero | Retire the list and tighten the scan | The stricter scan shows what the first one missed |
| A rule can only be checked by reading English | Change 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 files | Run the dead-code check on the whole module | Deleting a caller in A must fail for the dead code in B |
| A tool is too noisy for a gate | Narrow it (other OS, reflection, test packages) and allowlist with reasons | 493 findings is a report; zero after narrowing is a gate |
| Deletion strands more code | Loop: delete, rescan, until no new findings | One function's death can be another's |
| Turning on a check would break everything | Drain first, gate last; file the remainder as tech debt | The gate starts at zero and only ratchets |
Failure modes, and the check for each
| Failure mode | Looks like | Caught by |
|---|---|---|
| New violation in an old file | A provider name added to a file already on the list | Count goes up: fail |
| Silent slack | A file fixed but its count not lowered | Count goes down without the list: fail |
| Name hidden in an identifier | accountWhatsApp | Identifier and file-name scan (since Nov 3) |
| Name in a comment or string | "Open Slack to finish." in the local component | Semgrep over all text (since Nov 4) |
| Dead code in an unchanged file | Last caller deleted elsewhere | Whole-module dead-code check |
| Code kept alive by its tests | Production caller replaced, tests remain | unused without tests; deadcode without -test |
| False dead code | Reflection 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.