A Postal Box on a Throughline

The tool, and the contract

Throughline is a Git-native requirements tool: one small YAML file per item, a permanent UID, typed links, and a validator that fails the build on an orphan, a dangling link or an unaccepted item. The first example's technical page sets out the working contract in full. Here it ran in its specification-first form: the whole graph was written from the person's one paragraph, handed over, read and ratified, and only then implemented; every commit names the items it serves; a change of mind was authored on the graph, ratified, and only then coded. The repository's own check runs in its build, non-strict so that a proposed item waits rather than breaks the build, together with the test suite.

One graph, eight registers

The graph is what tl init --no-demo lays down plus three registers added at birth for risks, constraints and assumptions, so that a requirement can mitigate a named risk rather than derive from the intent alone. The one coverage rule, that every live requirement needs an incoming verifies link, was treated as a floor: several requirements carry two or three tests, one per distinct failure worth catching.

Item before code, then code to the item

The sixty-six warnings were the sixty-six unratified items, which is the expected state of a graph nobody has read yet; the commit that carried them said so, and the hand-over named the design calls the AI had made alone. Ratification arrived as one command over all sixty-six, eighteen minutes of reading later, and was committed on its own under the person's name before the implementation began.

Every module opens by naming the items it implements; every test function is named test_0014_… after its TEST item, with the item's UID in its docstring, so the mapping is greppable in both directions. When the implementation was green the requirements, NFRs and tests were moved ratified → implemented in one commit and implemented → verified in the next, because the check compares each item's status with the committed one and a two-step hop in one commit reads as an illegal transition.

Three tolerances the grid cannot promise

REQ-0009 says the cavity is computed on a grid that only ever rounds outward: each cell takes the lowest point of the grown model over the whole cell, less half a cell diagonal, and the outline is grown by one cell. While implementing it the AI worked through the slack that guarantee costs, up to three cells a side (the cell the outline falls in, the cell the clearance reaches into, and the cell of growth), and found that three tests it had written and the person had signed asked for "within one grid pitch". No implementation of the ratified requirement could pass them.

The three were re-worded to what the design guarantees, the rationale of REQ-0009 was corrected to say the same (a rationale is not normative, so its signature held), and the hand-over asked for three re-signatures. The reply was "Ratify and continue", and the AI ran tl ratify … --accept-change with the person's name on his instruction, recording in the commit that it had. The assessment counts those three among thirteen items amended after ratification; none of the thirteen moved silently.

The change of mind, as the graph saw it

"Cut away the box looking down from the top so that the wall thickness is only a parameter defaulting at max 5mm" contradicted NG-0002 as ratified ("does not shape the outside of the box to the model") and changed REQ-0012 (a cuboid), REQ-0011 (a rectangle's wording), REQ-0003 (the option list) and REQ-0015 (lattice panels that would no longer be flat). Nothing was coded. The AI narrowed the non-goal to the top and the underside, amended the four requirements, added RISK-0007 (a cut-back box tips over), REQ-0021 (the tipping angle from the footprint's convex hull, a twenty-degree floor, the rectangle kept when it does better) and three tests, moved the amended verified items to suspect so that their status told the truth, and pushed the proposal with the check at zero errors and twelve warnings.

The person ran that in his own terminal and confirmed each item after reading its diff; the transcript shows twelve prompts and twelve answers. The implementation followed: the outline traced from the cavity's cells, a rounded rectangle intersected with the outline offset by the bounded wall, offsets of that for the wall below the lip and the skirt, a printed lid built from the mirror image of the outline so that it seats after being turned over, lattice holes sampled along the outline and cut inward along its normal, and the tipping check. Two of the three new tests were physically wrong as written: an L bracket's convex hull is never narrow enough to tip where the rectangle does not, and a post on a block does not raise the cradle. Both were re-worded, both went stale, and both were signed again, one of them in the terminal while the AI was still working.

Ratification, in five rounds

Sixty-six items in one command on a hand-off, committed alone under the person's name. Three re-worded tests with --accept-change on his instruction, the commit saying so. Twelve items read one at a time in his terminal, committed alone. Then two singles: TEST-0034 re-signed in the terminal mid-session, and TEST-0035 the next morning before this page was written.

The fault: the mid-session re-signature of TEST-0034 was swept into the implementation commit by git add idd. The rule from the third example, stage explicit paths in a repository that holds a graph, was in the AI's feedback and was still broken, because "explicit paths" was read as "not -A" and a directory felt explicit. It now says never to add a graph directory whole, and to read git status for item files before staging. The signature itself is intact.

The gate, in the pipeline this time

Unlike the third example, the check is in the build: a graph job runs tl -C idd check on every push, non-strict so that a proposed item waits for a signature rather than breaking the build, and a test job installs the tool with wheels only, as its NFR requires, and runs the suite. The first two builds failed in the test job, not the graph job: a library the working copy had carried since an API probe was never declared, so the suite that read 3MF files passed on the workstation and failed on the runner. The same job then measured the NFR's timing test at nine seconds where the loaded workstation had measured forty.

The assessment

Assessed at "done" with the assessment script of the tool's skill: strict check clean, nothing proposed, working tree clean, no test failed. The session record was cut at the last commit of the day's work; the same session went on the next morning to write this example, and those turns are not in the figures. Commits naming an item in the subject line read 9 of 19: every commit cites its items, but the subject lines that the script reads carried the citation only when it fitted, as the third example also found.

What the tooling taught