Chapter 5. Dead Seams
Chapter 1 told the story: a month of stalls, three dead theories, and an afternoon's scan that found 229 places where the test suite exercised code that nothing in production called. This chapter is the full anatomy. How seams form, why every standard instrument fails to see them, how to find them mechanically, how to repair them, and how to build so they stop forming.
I will say the definition once more, because everything else hangs on it. A dead seam is code that tests reach and production cannot. It is distinct from dead code, which nothing reaches at all, and it is worse than dead code, because dead code looks abandoned while a dead seam looks finished.
How a seam forms
Watching for them since, we see the same few mechanisms, and I present them as mechanisms rather than statistics.
Completion without connection. The organ is requested, built, and tested in one session, and the wiring is left as separate work that no artifact demands. This is the basic case from chapter 1, and everything in agent workflow conspires toward it: the request names a capability, the tests prove the capability, the notes record the capability. Nobody asked for a wire, so there is no line item anywhere for its absence.
The rerouted loop. Nastier, because the organ was wired, once. Then a refactor moved the decision path, the new path never picked up the call, and the old call site died in a file the refactor deleted or bypassed. The tests kept passing throughout, because tests reach the organ directly. Code that used to run and silently stopped is the seam variant that most reliably fools its own author.
The flag that never flips. The organ is wired behind configuration that no environment enables. Wired in text, dead in practice. These hide well because the call site exists and reads as proof of life.
The twin. Two implementations of the same idea, an old one the loop still calls and a new one that sessions keep improving because the notes say it is the real one. All improvement flows to the twin that never runs.
One root under all four: connection is invisible work. People and agents ask for features, test features, and document features. The wire between a feature and the loop that decides what happens next has no natural owner, no test, and no line in anyone's notes, and what nothing owns, nothing checks.
Why your instruments miss it
Every standard quality instrument answers a question adjacent to the one that matters.
Tests reach the organ by the private staircase chapter 1 described: the suite imports the module directly, so it is structurally incapable of noticing that production has no route to it. A test failure means the organ is broken. There is no test result that means the organ is unreachable, because reachability is a property of everything outside the test.
Coverage measures the wrong direction. Coverage asks whether tests reach code. The defect is about whether the application reaches code. A repository can carry 100 percent coverage and be mostly unreachable from its own main loop; the two facts do not even touch.
Review reads diffs, and the defect is an absence. The pull request shows a well-made organ and its well-made tests, and both deserve the approval they get. The missing line lives in a file the diff never touched, and absences do not diff. A reviewer would have to ask, every time, "and where is this called from," which is precisely the discipline this chapter exists to mechanize.
Narration is not evidence. This one is specific to agents and cost us real time. An agent announces its intentions in language: the plan is made, the room will now be furnished. The announcement comes from the language layer, which read the notes, which say the capability exists. Whether the call graph agrees is a separate fact, and during our month of stalls it usually did not. Treat an agent's account of what it is doing as a claim, never as an observation.
Finding them mechanically
The scan is honest work but not clever work, and it has two parts.
The first part is the entry-point census, and it is the part that requires thought. A production entry point is anywhere the outside world starts execution: the binary and exports named in the package manifest, route registrations, scheduled jobs, event subscriptions, message handlers, and the main loop itself. Write the census down; keep it in the repository next to the code it describes. Getting the census right is the only judgment in the whole procedure, and reviewing it takes minutes.
The second part is a walk. From the census roots, follow every call edge and mark what you reach. Then classify every exported unit in the repository (for a manual pass, work at file level; finer grain can wait for tooling). Reached from production roots: alive. Reached only from test files: dead seam. Reached from nowhere: dead code. Dynamic dispatch deserves honesty here: string-keyed registries and reflection blur call edges, and a scanner should report those as low confidence rather than deliver a false verdict. In our experience the blurry cases are a small minority, and a tool that admits uncertainty beats one that lies in either direction.
This book ships with seamcheck, a free scanner that runs the walk for TypeScript and JavaScript projects, as a command line tool and as an MCP tool your agent can call on itself. It exists because the scan that ended our month took one afternoon to write, and the month is what it costs not to have it.
Triage the report before acting on it. Worst first: seams currently being built upon, because every session that trusts them compounds the problem. Then seams on the main decision path, because those are your stalls. The long tail can wait its turn.
Repair
For each seam there are two honest outcomes and one honest holding state.
Wire it, if the organ is wanted. One seam at a time, and after each wire, observe the world rather than the suite: the companion moves, the order goes out, the file appears. The suite was never in doubt; it is the world that has been out of the loop.
Delete it, if the organ is not wanted. Some seams, examined, turn out to be answers to questions nobody is still asking. Deleting verified, tested, well-made code stings, and the sting misleads; the tests were guarding weight. Deleting is repair.
Or record it as unwired by choice, which is the holding state: a ledger fact with a reason and a date, saying this organ exists, is deliberately unconnected, and here is why. That is an honest status. What it is not, ever again, is "complete."
Prevention
Four practices have kept the class from recurring in our workshop so far, ordered from cheapest to deepest.
Run the scan in CI. New seam, failing build. Organs deliberately recorded as unwired by choice go in the scanner's ignore config, so the gate trips only on genuinely new seams. The scan that took an afternoon to write takes seconds to run forever after, and the defect class stops being discoverable months late.
Adopt the completion amendment from chapter 2. A fact claiming something is finished must cite the production call site, file and line. The moment "complete" became a checkable statement, our notes stopped inheriting optimism.
Define done as an observed world change. One sentence, written at the end of the work: when this ran, here is what changed in the world. If the sentence cannot be written, the work is not done, whatever the suite says.
Build wire-first. This is the deepest fix, and it inverts the order that creates seams. The call site is written first, into the live loop, invoking a stub that does almost nothing. Then the organ grows inside a connection that already exists. Nothing is ever finished-but-unreachable, because reachability came first and capability grew into it. Plug in the lamp before you build the lamp.
The number, revisited
What the scan actually bought us was not the fixing of 229 bugs, because seams are not bugs. Each one was finished work waiting for a single line. What the scan bought was the end of mystery. Stalls stopped being moods to investigate and became entries on a checklist, and a system that had spent a month being inexplicable became, in one afternoon, merely unfinished.
The defect class is humble. The fix is humble. The expensive part, the part that cost the month, was believing green. Chapter 1 gave you the doctrine and this chapter gave you the machinery; between them, that particular belief should never cost you more than an afternoon again.
Checklist
- Write the entry-point census and commit it to the repository beside the code.
- Run a reachability scan before your next feature estimate; count seams before promising anything new.
- Triage: seams being built upon, then seams on the main path, then the tail.
- For every seam: wire it, delete it, or ledger it as unwired by choice with reason and date. Nothing keeps the label "complete."
- Add the scan to CI with a failing exit code on new seams; declare deliberate unwired-by-choice organs in its ignore config so only new ones trip it.
- Rewrite your definition of done: cited production call site, plus one sentence of observed world change.
- Build wire-first from now on: stub in the loop before organ in the library.
This is one of two free chapters. The full book is nine chapters and a receipts appendix: the ledger architecture, the operator's-words archive, the wipe criterion, the Windows field guide, checkpoint ladders, and the collaboration protocol. $19, delivered as clean HTML plus a full markdown machine edition your agent can execute. 30-day refunds, no questions.