Keeping software coherent at agent speed

Agents write much of the Fuz stack's code. Whether a session commits its work depends on what it was asked to do, so some work waits uncommitted for the maintainer to read, and some commits land on the main branch before the maintainer has read them. At that speed one person's reading cannot be what keeps the software right. This page lists the ways agent-written work goes wrong here, and what holds each one.

So part of the review happens after the fact. Work is reviewed before it is committed, and commits that have landed are reviewed too, by agents when asked and by the maintainer, for whom it is sometimes the first reading. The release is the checkpoint for that review: versions and publishing are the maintainer's, and a common pattern is to review all the work since the last release before making the next one.

Two of the stack's projects are made for that reading. zzz is for reading work on the maintainer's own machine, and its projects page shows each repo's uncommitted work and its distance from origin. fuz_forge is for commits that have landed: it shows a repo's commit log and its diffs to a reader, with no pull request to approve first.

What is at stake is coherence: software that still reads as one design, with one way to do each thing, one name for each concept, documents that are still true, and checks that mean what they say. The rows fall into families. The first is that loss itself, a design that drifts. The other three are how it starts: checks that mean less than they say, claims that nothing confirmed, and sessions that repeat a mistake, collide or overstep.

A hold is whatever stops a failure or catches it. Holds sit on the rungs of a ladder, from a person's judgment down to the shape of the system. Each rung down depends less on anyone remembering than the one before it. A rule moves down when a lower form of it is simpler to keep than the rule alone: a check that holds it, or a structure that makes it unnecessary.

The projects named are the ones on the Fuz stack page. See also the skills the written rung cites, the values the stack's design is measured against, and the glossary for the words used here.

Claude Fable 5.2 wrote this section and its data file. Its claims were checked against the repos on . The maintainer has not yet reviewed it.

The grid

Each row is a failure, each column a rung, and each cell what holds that failure at that rung. The column is how strong a hold is and the mark is only how much of the stack has it, so a full mark on a written rule is still a rule that someone has to follow. A blank cell means nothing at that rung is aimed at the failure. Two holds apply to every row and are listed once: review after landing, under "Green but wrong", and the gate, under "A known mistake comes back".

  • Throughout In place across the stack.
  • In places In some projects, or for part of the failure. The entry says what is left out.
  • Out of reach This rung cannot hold the failure.
  • Wanted More is intended here and not built.
FailurePerson A person decides, each time.Session An agent carries out a procedure, again in each session.Written A rule in a file that sessions load.Tool A check runs and gives a verdict.Shape The system is built so the failure cannot be expressed.
The design drifts The code stops being one design that a person can reason about: features that do not fit, copies that disagree, faults that are hidden.
Design drifts to the model's averagePerson Throughout: One owner per projectSession nothingWritten Throughout: Conventions in loaded filesTool In places: Lints for the mechanical rulesShape Out of reach: Fit is a judgment
Two copies drift apartPerson nothingSession nothingWritten Throughout: One name, one copy, no shimsTool In places: Drift checks and twin suites , more wantedShape In places: One schema, one library
A fault is absorbed and the program runs onPerson nothingSession nothingWritten Throughout: Fail loud, not just closedTool In places: Schema drift guardShape In places: No quiet path to take
The checks weaken A check shows green and means less than it says.
Green but wrongPerson In places: Review after landing , more wantedSession In places: Writer and reviewer loopWritten nothingTool In places: Oracles, mutants and control cases , more wantedShape nothing
A check is silenced instead of satisfiedPerson nothingSession In places: The expected diff is read as codeWritten In places: Fix the code, not the expectationTool In places: Suppressions that expireShape nothing
A gate stops gatingPerson nothingSession nothingWritten Throughout: Read the exit codeTool In places: Suites that fail on a skipShape In places: One gate definition
A slow check gets skippedPerson nothingSession nothingWritten Throughout: The full gate before landingTool In places: CI reruns the gateShape In places: Fast tools
The claims go unverified A statement is acted on that nothing has confirmed.
A wrong claim gets acted onPerson In places: Approval before code, in tsvSession In places: Check the claim against the codeWritten Throughout: Leads, not factsTool In places: Figures computed from reportsShape nothing
A stale statement is trustedPerson nothingSession In places: Distill, then deleteWritten In places: Mark built from designedTool In places: Link and drift checksShape In places: Docs generated from source
A predicted speedup that is not onePerson nothingSession In places: Race the candidatesWritten Throughout: Measure before claimingTool In places: Committed size limitsShape Out of reach: Speed is a measurement
The sessions overstep Sessions share no memory and work unwatched, so one repeats a mistake, collides with another, publishes what was private, or takes an action that was a person's to take.
A known mistake comes backPerson nothingSession nothingWritten Throughout: The correction is written downTool In places: The gateShape In places: Impossible states do not compile
Two sessions collidePerson nothingSession nothingWritten In places: One writer per checkoutTool In places: Busy detection and rebase on pushShape In places: A worktree per effort
Private content reaches a public repoPerson nothingSession nothingWritten Throughout: The planning layer stays outTool In places: Checks at the edgesShape In places: An inert planning layer
An unattended session does something irreversiblePerson Throughout: The maintainer releasesSession nothingWritten Throughout: Rules for versions and dependenciesTool In places: Deny rules and dry runsShape In places: A push tool that cannot

More in this section