Briefs: a definition of done a stranger can run

Somewhere in your backlog is a ticket that says "tighten up the release checks." A colleague can execute that — they will ask what you meant. An agent dispatched at two in the morning into a repo it has never seen will not ask, and will close the ticket with a confident report you should not take at face value. What form must a unit of work take for one stranger to execute it and a second stranger to check it — with nobody relying on anybody's account of what happened?

Our answer is the brief: one markdown file, one scope, one definition of done, written as a contract. Our tree currently carries 366 of them. The whole format falls out of one design rule, and it is the sentence to keep: every line of a brief is either executable by a stranger or auditable by a reviewer — nothing rests on the author's word. Scope is exact file paths. Risk is four recorded answers. Done is a table of commands with expected output. The rest is that rule unpacked, through one real brief — a fail-closed lint that stops the toolkit's own shipped prose from making claims the house has ruled out, such as calling its output an assurance opinion. Call it the claims-lint brief.

written for a stranger who cannot ask

The self-containment rule is blunt: a single agent must be able to execute a brief without reading the rest of the plan. Everything the implementer needs is in the file: the exact paths they will touch, and the three-to-five project facts required to execute, as key-value pairs — prose drifts and cannot be parsed. Knowledge from another brief is a typed dependency, not a paragraph.

The frontmatter of the claims-lint brief, abridged (its stream carries an internal name; the label here is generic):

brief: claims-lint/lint
          title: Prohibited-claims lint — fail-closed scan of shipped prose
          wave: 1
          depends: ["claims-lint/manifest"]
          effort: M
          gate: model
          risk: {regulatory: no, customer: no, irreversible: no, sensitive-data: no}
          schema: brief-v1
          authored: 2026-08-06 by the authoring session
          sources: ["scoping doc §3.2",
                    "freshness-checked 2026-08-06 @ 822d896 (no claims lint exists)"]

Every field earns its place. sources is provenance — an empty list is "a gap a reviewer bounces, not a shortcut": nobody can later tell why the work exists or whether a newer finding invalidated it. The freshness check is dated and pinned to a commit: "this doesn't already exist" is a claim, and claims get timestamps. Even the standing ground rules are about strangers: the implementer stops at implemented, never advancing their own work to verified, and an implementer who finds the brief contradicting repo state reports that and stops — a stranger who guesses is executing a contract nobody reviewed.

the gate is a conclusion, not an opinion

The frontmatter contains no chosen review gate. It contains four risk answers — regulatory, customer-facing, irreversible, sensitive-data — and the gate is derived from them. All four no: a model may review. Any single yes: the gate is human, and closing it later requires a sign-off naming a person; a model's approval does not count, however strong the model.

The point of recording the answers instead of the verdict is auditability. A reviewer confronted with gate: model on a risky-looking brief does not argue about the gate — they audit the four answers, which are concrete claims about the work. A wrong answer is a findable defect; a wrong opinion is a negotiation. The design rule again: the gate line is not a judgment to trust but a computation anyone can re-run, from inputs a reviewer can attack.

done is a table, and the table can fail

The heart of a brief is its Verify table: literal commands with expected output, runnable from the repo root by someone who did not do the work. The template states the standard: a row with no literal command and no expected exit or output "is a hope, not a check." The claims-lint brief carries 14; here is the row worth staring at:

The row plants a prohibited claim in the README, demands the lint go red and name the file, then reverts the damage — one command whose own exit code is the verdict. The house rule behind it: a brief that adds a check must include a mutation-test row, because a green check you have never watched fail is indistinguishable from a check wired to nothing. In one measured sweep of our instrument failures, six of eight would have been caught in minutes by a row of this kind.

The rules also draw a line the table cannot cross on its own. For prose deliverables, executable rows are presence gates — a section exists, a token appears — and the brief must say so honestly, because a grep passes a confidently wrong document exactly as it passes a true one. The measurement that forced this into a rule: a setup guide shipped with eight Verify rows, every one a presence count; all eight passed, and the guide was factually wrong in four places, one load-bearing. So a deliverable that makes checkable factual claims must carry at least one dereferencing row — fetch the link and inspect what it serves, run the documented command and compare its real output — a row capable of failing on a wrong-but-well-formed document. Quality still belongs to the human review gate; the table's job is to keep that gate from standing alone.

dependencies are edges, not sentences

depends and unblocks take typed IDs only — claims-lint/manifest, never "after the manifest brief" — because a typed ID survives a rename and a script can follow the graph. The scheduler computes what is dispatchable purely from those edges, which has a corollary: an ordering constraint that lives only in prose — "no X before Y" in a README — is invisible to it, and the worker pool dispatches straight past it. That is the most dangerous blocker class — every consumer of the queue is blind to it — so a lint flags gate-shaped prose carrying no matching edge. Mid-flight changes route by the same spine: does the tweak change the Verify table? No — just do it; a brief is a contract, not a keystroke script. Yes — amend the brief in the same commit and demote it so it re-gates, because changing the table changes what done means.

the discipline is a fossil record

Behind the template sits a rules file: each rule stated with the failure that forced it, numbered append-only because rules are cited by number elsewhere. The deepest stratum is row-runner discipline: command shapes that make a Verify row report a verdict it never measured. A grep alternation without -E treats the pipe as a literal character; one brief's table returned 1,1,1,1,1,1,1 against thresholds of 3,3,1,3,2,3,3 — every row green, every row matching only itself. go run flattens every non-zero exit into 1, so a row asserting "exit 2" passes on a tree that does not even compile. A comparison based on a moving branch ref returned different verdicts on consecutive runs with nothing under test changed. Each shape shares one property: the harness silently substitutes its own answer for the one under test, and the row goes green either way. None is discoverable from a passing run — which is why they are lint rules, not reviewer vigilance.

one brief, start to finish

Thread the claims-lint brief through its life. Authored 2026-08-06 with a pinned freshness check. Implemented in an isolated worktree; on 2026-08-13 the implementer ran all 14 rows and appended a witness table — command, exit, observed output, date, runner — then a section titled "what a clean run here does NOT establish": the matcher is literal, so a reworded claim slips it. The board row stayed at implemented: the implementer's own run does not verify. On 2026-08-20 a non-implementing identity re-ran the whole table against merged main. Rows 1 through 12 passed as written. Rows 13 and 14 could not run — the tree had evolved out from under a tool they invoked — and the verifier recorded them as could-not-check with a re-baseline filed, not as passes, because an instrument that could not look does not get to answer. Both runs sit in the file, dated and attributed. That is the contract doing its job: not one flawless green, but a record two strangers built independently and a third could re-derive.

what the contract does not prove

State the claim at its honest strength. A Verify table is a check a stranger can run — it is not proof the work is correct. A behavioral row proves the behaviors someone thought to demand, not the ones nobody imagined; a presence row proves less still. The risk answers are self-reported, so a wrong no mis-derives the gate; the mitigation is that they are claims a reviewer audits, not that they are reliably right. Completeness is an authoring judgment throughout — the tooling corroborates what was written and says on every run that an omitted entry is invisible to it. The format narrows the gap between claimed and checkable. It does not close the gap between checkable and true; the review gate, the independent re-run, and the human on the merge button live in that gap on purpose.

the install

None of this needs our tooling. A brief is a markdown file; the Verify table is shell commands; the gate derivation is an if-statement over four recorded answers. Write your next agent-bound task as one file a stranger could execute: exact paths, the facts required, provenance for why it exists. Record the risk answers and derive the gate. Then write done as commands with expected output — including one row that must go red when the work is broken, so you have seen the check fail before you believe it passing. That is the whole discipline: every line either executable by a stranger or auditable by a reviewer, and nothing resting on the author's word.

What happens to a brief after implemented — the evidence log, the compiled board, the desks passing work between identities — is the wider loop, and we walked it in "Introduction to Assay."