The Self-Auditing Codebase

Architecture as a bug specification

The Frame

We draw diagrams for humans to admire. The real reader should be the machine.

Architecture diagrams get drawn as decoration — something people glance at once and forget. But the reader that can actually act on a graph is an AI agent. This deck follows that idea from a tiny, fully-traceable bug hunt all the way to a codebase that audits itself.

Start where everything is verifiable: one small demo repo.

The Demo

A deliberately tiny, fully-traceable bug hunt

michaeljabbour/string-utils-bug-hunt-demo is a 101-line Python string library with four functions. On the fix branch it tracks exactly three files — small enough to hold the whole story in your head.

Small enough to verify every claim by hand — starting with the bugs.

101

lines in src/string_utils.py

4

functions: truncate, slugify, word_count, contains_html_tags

3

tracked files on feature/fix-string-utils-bugs: README, src, tests

The Proof

Two real bugs, each killed with a single line

slugify left boundary separators in the output; word_count miscounted empties and runs of spaces. One line fixes each — and a 17-test pytest suite goes green.

The workflow really finds and fixes bugs. So why not trust the humans describing it?

# slugify — strip boundary separators
slugify('  Hello  ')   -> '-hello-'
slug = slug.strip(separator)  -> 'hello'

# word_count — split() with no argument
word_count('') -> 1 ; 'Hello   World' -> 4
words = text.split()  -> 0 ; 2

# pytest
17 passed in 0.01s

The Tension

The human-written description already drifted from ground truth

Even in this tiny demo, the README and PR #1 body claim "15 passed" — but the committed suite actually collects and passes 17. If a hand-written description drifts here, why trust the diagrams humans glance at?

The fix: make the machine, not the prose, the source of truth.

15

tests the README & PR #1 body claim passed

17

test functions the committed suite actually collects & passes

The Mechanism

In Amplifier, a pipeline IS a DOT graph the agents execute

make-a-deck.dot is a 205-line digraph of 13 nodes with explicit pass / fail / flagged edges — start → reset → research → factcheck → spine → render → lint → done. The diagram isn't decoration; it's the machine-readable spec agents run.

If a small graph is a spec, what about the huge ones?

205

lines in make-a-deck.dot

13

node declarations agents execute

The Turn

The density that defeats human readers is exactly what agents want

Dense subsystem graphs run up to 736 lines (03-graph-model.dot; 571 in 02-handler-architecture.dot). No human skims that. But an agent reads it end to end — turning an unreadable diagram into an ideal bug-finding map.

So hand that map to an agent built to hunt bugs.

736

lines — largest local architecture DOT graph

571

lines in 02-handler-architecture.dot

The Payoff

Feed the graph to the bug-hunter and the codebase audits itself

Amplifier ships a 314-line bug-hunter agent — hypothesis-driven and LSP-enhanced. Point it at the graph-as-spec and the loop closes: the demo's whole discovery-to-ship workflow lands as one reviewable PR, #1, +284 / −2 across three files.

That loop is the pattern worth keeping.

314

lines in the bug-hunter agent spec (amplifier-foundation)

+284/−2

PR #1, 3 files, discovery to ship (OPEN)

The Takeaway

Stop drawing diagrams only for people. Author them as specs the machine can read.

When the diagram is a machine-readable specification — not decoration — every diagram becomes an audit. The same DOT graph a human skims becomes the agent's map, and the codebase checks itself.

Architecture-as-specification: the pattern to keep.

Sources

Sources & Research Methodology

Data as of: 2026-07-21 (repo cloned on this date)

Primary source: michaeljabbour/string-utils-bug-hunt-demo — PR #1 OPEN (not merged); src + tests exist only on branch feature/fix-string-utils-bugs, main holds README only.

Feature status: bug-hunter agent shipped in amplifier-foundation (314 lines, LSP-enhanced, hypothesis-driven); DOT pipelines live in-repo (make-a-deck.dot, 205 lines / 13 nodes).

Commands run:

gh repo clone michaeljabbour/string-utils-bug-hunt-demo; git checkout feature/fix-string-utils-bugs; git ls-files (3 files)
wc -l src/string_utils.py; grep '^def ' src/string_utils.py (101 lines; 4 functions)
grep -c 'def test_' tests/test_string_utils.py; python3 -m pytest tests/ -q (17 collected; 17 passed in 0.01s)
gh pr view 1 --repo michaeljabbour/string-utils-bug-hunt-demo --json title,state,additions,deletions,files (PR #1 OPEN, +284/−2, 3 files)
find . -maxdepth 4 -iname '*.dot' | while read f; do echo "$(wc -l < $f) $f"; done | sort -rn (736 / 571 / 205)
for f in $(find . -maxdepth 3 -name bug-hunter.md); do wc -l < $f; done (amplifier-foundation = 314 lines)

Gaps / corrections: The topic's "667-line DOT" figure matches no file under the tree — real figures 736 / 571 / 205 used instead. README & PR say "15 passed" but the suite has and passes 17 — the 17 figure is used as ground truth. bug-hunter copies differ by repo (322 in amplifier-foundation-budget-gate); the 314 figure is specific to amplifier-foundation.

Primary contributor: Michael J. Jabbour (michaeljabbour) — sole author of the demo repo, both commits, and PR #1.