What the literature got to first (and the parts we made mandatory)¶

The companion post to this one, Code comments written for the robot, not the human, describes the codemap: annotation and risk system this project built: provenance-tiered inline annotations, a three-tier dependency graph, and a risk score gated on test coverage. That post ends with a short, slightly uncomfortable admission -- I shipped the system before doing the prior-art search, and when I finally did it, the field had already arrived at most of these moves independently.

This is the post that takes that admission seriously. It is the related-work chapter: where the external literature got there first, where this project is genuinely a step ahead, what the comparison made me go back and borrow, and what is still primitive. It is not a victory lap. The honest version is more interesting than the triumphant one, and it is the version that holds up.

The field converged on the same shape¶

The two load-bearing structural ideas in the codemap system -- put tests and source in one graph, and route review attention by blast radius -- are not unique to this repo. Two pieces of published work land on the same shape, with real tooling behind them, not just diagrams.

code-review-graph is a local-first code-intelligence graph that builds a dependency graph and routes review context by impact, with explicit token-reduction claims: instead of handing a reviewer (human or agent) the whole repo, it walks the graph from the changed files and exports just the reachable neighborhood. That is the same instinct behind the codemap subsystem and the blast-factor term in the complexity score -- "what does this change actually reach" -- and, as you will see below, it is the move I most directly copied back.

TDAD (Test-Driven Agentic Development) puts tests in the same graph as the code and selects them by a confidence weight rather than treating every test->code link as equal. The point TDAD makes is subtle and correct: a graph-derived "this test covers this code" link is only useful if you also know how much to trust it. A direct test-imports-source edge is strong; a transitive call hop is weak; a bare co-location is weakest. That is the move behind gating risk on coverage in the codemap scorer, and -- again below -- it is the second thing I went back and borrowed.

I want to be clear about what convergence means here. It is not embarrassing that several independent efforts reached tests-in-one-graph and impact-routed review at roughly the same time. It is the opposite. When the shape shows up repeatedly from people who were not talking to each other, that is the strongest available evidence the shape is right. The codemap system is more credible because code-review-graph and TDAD exist, not less. Saying so out loud is more honest than implying the ideas were invented here.

Where this project is actually ahead¶

Convergence on the graph shape is real. But two cited surfaces -- machine-addressed annotations, and the staleness problem -- have prior art that stops short of what the codemap system enforces, and that gap is the part of this work I am willing to defend as a genuine step forward.

Provenance tiers with enforced currency. The AI-Annotations @! standard formalizes machine-addressed, agent-readable annotations carried in source -- exactly the premise of a codemap: block written for the agent that edits the file next. What it has is categories. What it does not have is a trust grading that says who is allowed to author each fact, or a mechanical check that the fact is still true. The codemap convention adds both: the auto: / ai: / human: provenance tiers put the trust boundary in the data (an agent may revise the ai: judgment, must leave auto: to the annotator, must not invent a human: policy), and the hash: currency stamp plus the lint-annotations gate make a stale judgment a build error rather than a review nit. The convention and the closed vocabulary live in the overview docs; the enforcement is a CLAUDE.md hard rule that any edit to an annotated unit must re-stamp its judgment fields in the same diff.

The staleness problem, named in prior art and almost never enforced. The stale-comment patent (US8607193B2) describes detecting when a comment no longer matches the code it annotates -- the exact problem the hash: stamp solves, patented years before I reached for it. The idea is old. What is rare is a project that actually fails the build when the stamp goes stale. A patent is not enforcement; it is a description of a mechanism almost nobody wires into CI. The contribution here is not the idea of staleness detection -- that is prior art -- it is making it mandatory and machine-checked on every edit.

Tier B protocol edges. One graph edge in the codemap subsystem has no analog in any of the cited tools: the Tier B message_type -> Room.handle_* edge. A client WebSocket send and its server handler never import each other, so a static-import graph is structurally blind to the link -- yet a change to one can break the other. deps.py scans client send sites for a message_type, links each to the matching Room.handle_<type> handler, and cross-checks the pair against the documented protocol, surfacing a missing handler as a graph warning. Convention-derived edges that no import expresses are not something code-review-graph or TDAD claim.

The honest summary of this section: the ideas converged; the part that is this project's own is the enforcement layer -- trust in the data, staleness as a build failure, and convention edges static graphs cannot see.

What the comparison made me borrow back¶

Here is the part I am most glad I did. Reading code-review-graph and TDAD did not just reassure me that the shape was right -- it surfaced four concrete gaps where those tools were ahead of the codemap system, and each became a small ticket that has since shipped. This is the opposite of a victory lap: the related-work search paid for itself in code.

1. Test edges in the graph. the codemap subsystem now emits Tier A test edges from each test file's imports to the source it pulls in -- 858 of them at last count. Before this landed, the graph only knew about source-to-source imports; the test edge weight (0.5) already sat in the codemap subsystem but no edge of that type was ever produced, so the weight was inert config waiting for a producer. Putting tests in the graph is the precondition for everything else in this list -- it is the TDAD "tests and source in one graph" move, and it is what makes the next three possible.

2. A minimal review-context export. the codemap subsystem (run via the project dev wrapper) walks the graph from the changed files and emits a compact JSON read-set: the changed units, their annotation summaries, and the tests that pin them. That is code-review-graph's token-savings move made local -- hand the reviewer the reachable neighborhood, not the repo. It is deliberately an informational command, not yet a review-preflight gate.

3. A static, grep-able source-to-tests map. the codemap subsystem (the project dev wrapper) writes the codemap subsystem, a committed artifact mapping each source file to the tests that cover it, with the covers: capability tokens each test carries. This is the TDAD "tell the agent which tests, not the procedure" mechanism: an agent about to touch a file can grep one file to learn what already pins it, instead of inferring it from a test run. A freshness lint (lint-test-map-fresh) keeps the artifact from drifting.

4. Graded coverage confidence. the codemap scorer used to treat coverage as a boolean -- CoverageMark.satisfies_capability was set membership, so a golden replay fixture with a negative assertion and a test that merely happened to carry the capability mark discharged a capability's risk identically. Now a CoverageGrade discharges severity proportionally to the confidence of the protecting test, with the tiers (none / low / medium / high / full) and their discharge multipliers living as policy in the coverage_confidence block of the codemap subsystem. A coverage link that is also backed by a direct test edge to the changed unit grades higher than a bare capability mark. That is TDAD's stratified-confidence weighting, replacing the scorer's weakest signal -- and it depends on augmentation #1, because the grade can only factor in graph linkage once test edges exist.

Each of these is a few hundred lines, not a research program. The point is that an honest related-work pass is not just defensive citation -- done properly, it is a backlog generator.

What is still primitive¶

The companion post ends on an honest-edges beat, and this one earns the same. Three things in particular a reader deciding whether to build something similar should know are not yet resolved:

No function-level call graph. Both the dependency graph and the annotation hash work at file granularity. The structural machinery to deepen to class- and function-level is wired (the annotator already walks ast.ClassDef and ast.FunctionDef), but it is switched off by deliberate YAGNI, documented as such in the overview docs. code-review-graph-style tools that resolve to symbol granularity see finer edges than this graph does today.
Confidence is computed from mark signals, not learned. The coverage_confidence tiers and every weight in the codemap subsystem are hand-tuned starting points that encode my current judgment about what strong coverage looks like (a direct test edge, a negative assertion, a behavior-preservation fixture). They are not fitted to any corpus of shipped changes. TDAD frames its weights as confidence estimates; here they are policy a human wrote, auditable but not empirical.
Token savings are estimated, not measured. The review-context export and the review-prompt-size prediction in the codemap scorer reason about size in bytes and lines, not real tokenizer output. When the system says a change will produce a large review prompt, it is a byte/line heuristic, not a token count. code-review-graph's token-reduction claims are the thing being approximated here, not yet measured against an actual tokenizer.

None of that is hidden -- it is in the convention doc and the weights file -- but the system earns its keep at file granularity with hand-written weights and estimated token counts, and gets sharper from there. That is a very different claim from "fully resolved," and it is the true one.

Where this sits in the cluster¶

This is the related-work companion to Code comments written for the robot, not the human, which owns the annotation and risk system itself; read that one first if you have not. The same machine shows up in the test-and-logging half, The test that knows what it is (the covers: capability vocabulary the source annotations share), gets put to concrete work in Let the library carry the proof (using the risk score to decide which hand-rolled code is safe to replace), and extends from code metadata into project history in The project that remembers itself.

The thread running through all of them is the same one this post is about from the outside: ordinary artifacts -- a comment, a test, a dependency edge, a ticket -- become agent infrastructure when they are typed, local, and mechanically checked. The literature got to most of the structure first. The part worth defending is making it mandatory.

That same thread now has a sharper principle in Derive It, Don't Stamp It: derive the recoverable routing signal from current artifacts and stamp only irreducible judgment. The canonical scoring doc records the rule in Change Risk Scoring.

Or: subscribe to the newsletter for more posts on building this stuff.