The node graph, and flying through it
Everything the loop knows about a feature is one graph: who asked for what, which code does it, every way that code was broken, and which test noticed. The graph of osu!’s scoring rules has 1,062 nodes and 5,675 edges, SemVer’s has 448 and 1,554, JsonObject’s 1,091 and 3,840. Each is stored as SQLite and N-Triples. The fly-through of osu!’s graph draws such a store as it is, with nothing added and nothing left out. The pictures behind the slides are stills from the same page, of osu!’s scoring rules.
How it is laid out
The store has no shape of its own, so the demo gives it one you can read from top to bottom, one ring for each kind of node. On osu!’s scoring rules:
- Why it exists: 1 source (the code’s own doc comments), 30 requirements (all written by hand, none inferred), 1 owner’s question, 5 use cases (one epic and four under it) and their 17 steps.
- Claude’s reasoning: a chain and its steps, each citing what it stands on. This trial wrote no chain, so the ring is empty; argument chains has one, run on the kit’s example.
- What the code does: 34 methods in a ring, sorted by name, so a class’s methods sit together.
- What proves it: 200 branch cells (191 branches and 9 for what a judgement moves), 563 breaks and 168 tests, of which 151 ran. Each branch and each break sits at the angle of the method it belongs to, so a method and everything under it line up.
How code maps to requirements
Two kinds of edge do it. A branch maps to a requirement: 339 of those. A branch is at a method: 191. Together they take you from any decision in the code to who asked for it, and from a requirement to all the code that answers to it. A decision no requirement owns is a hole, and the loop lists it.
What the red points are
The 277 breaks no test caught. Red is what the graph records, not a verdict: 250 got past every test that ran, 13 are proven by compiled code to be the same program and 14 did not run. The 250 are the real work: none has a written reason. That is what the 53.4% means: 286 caught of the 536 live breaks, leaving out the 13 and the 14. It is what three test files hold, not what the game’s whole test project holds.
The demo
Drag to orbit, scroll to zoom, W A S D to fly, Q and E for down and up. The tour follows one real thread: a source, a requirement, the step that needs it, Claude’s reasoning, the code, a branch, a break of that branch, the test that caught it, and a break that got past. The Show menu narrows it to one question: how code maps to requirements, every break and what caught it, Claude’s reasoning, requirements and use cases, or what the graph neural network reads.
It is a tool in the kit, for any graph the loop has written. --hide keeps names you choose off the page:
python graph_flythrough.py <store.sqlite> --out page.html --hide "NameA|NameB"
The knowledge graph
A graph here is just a list of things (nodes) and the links between them (edges). The things are requirements, use case steps, places in the code, branches, breaks, tests and reasoning steps. The links say how they relate, for example:
requirement W-1 is checked by test Pay_TakesExactlyThePrice
break #312 was caught by test Pay_TakesExactlyThePrice
method Pay is claimed by requirement W-1
The graph is the record: the 18 checks read it, and a later agent reads it instead of re-deriving what an earlier one found. It is written on every run as a SQLite database and as an N-Triples text file, a standard format any graph tool can open.
How big it gets
Measured The graph of osu!’s scoring rules holds 1,062 nodes and 5,675 edges, SemVer’s 448 and 1,554 and JsonObject’s 1,091 and 3,840, each read from its run’s line in the morph log.
The documents are nodes too. When a number or a behaviour changes, something has to say which documents go stale, so a model can declare its documents and each section, slide and page becomes a node. A link from a requirement, stat, goal or method to a document exists only when the document names it literally, or an authored line says so and quotes the words it stands on. Likeness never makes a link. doc_nodes.py what-to-update <node> answers which documents describe a node. A document naming a requirement the model does not hold is a hole. A requirement no document describes is counted and named, not failed, because most models have never declared any documents.
On the slides: slide 13.
Made by RJ’s TNT Tools. TNT Tools’ own work, not a Heavy Iron product.