Methodology

When agents do a large share of a team's implementation work, status becomes an unreliable narrator. Assay is a methodology for that regime: it restructures work into documents a script can check and routes every claim of done through a gate that does not belong to the author. This page is the overview — the discipline as a whole, and the reason each mechanism exists. Each mechanism has its own explainer: Briefs, Registers, Lifecycle, and statusgen.

The problem: the narrator grades its own exam

The controls that keep human-paced software work honest assume two things: the actor who says "done" is durably accountable, and status assertions arrive at human volume. A fleet of spawned agents breaks both at once. Assertions arrive at machine speed, and the asserter is a session that will not exist tomorrow to answer for them. Under that regime the failures are predictable, and each one names a mechanism Assay carries.

Failure	Repair	Mechanism
Agents grade their own homework — "done" becomes a self-report, the weakest signal available.	A verification step that, by rule, cannot be performed by the author.	Lifecycle
Plans drift from reality — the intended state lives in prose nothing can check.	The plan is a typed document a linter parses.	Briefs
Prose dependencies break silently — "depends on the oracle work" survives the rename that broke it.	Typed references, so a broken one is a lint failure.	Briefs
Priority collapses to proximity — each worker takes the next item in its own lane.	A computed queue that weighs every stream at once.	statusgen
The system's memory is editable by the ones being remembered.	Append-only registers whose deletions are machine-visible.	Registers

Issue trackers, CI, and code review are necessary, and Assay assumes them. But they were built for teams where the person who says "done" is accountable in a way a spawned agent is not. The gap they leave — consistency checking over agent-authored work-state, with verification gates keyed to risk — is the gap this methodology fills.

The design stance

Three commitments run through every mechanism.

Every rule is stated with its reason. A convention whose rationale is lost decays into ritual, and a fleet of agents is very good at satisfying rituals literally. Each rule carries the failure it prevents, so it can be re-derived or retired on its merits when circumstances change.
Gates over trust. A rule that depends on discipline is a wish; a rule the machinery enforces is a gate. Wherever a norm can become a check, a check a lint failure, and a lint failure a blocked merge, it does. The friction is the feature.
Claim the weaker, true thing. The strong claim — that status is measured and agents cannot lie — is false: the sensors are writable by the actors they measure. The methodology claims only what its machinery supports and states the residual gap in its own copy. A methodology about verifiable claims that overclaimed for itself would refute its own thesis.

Briefs: the unit of work

The unit of work is a brief: a self-contained scope-and-definition-of-done document in a typed format, small enough for one session to own end to end. Four properties do the work:

Self-containment — fleet workers are ephemeral; context that lives only in a session dies with it.
Typed dependencies — a typed reference that stops resolving is a lint failure; a prose reference that stops being true is silence.
An executable Verify block — verification against a table written in advance is repeatable by a stranger; verification against the implementer's recollection of intent is not.
A risk gate assigned at authoring time — routing review effort by risk is decided by the author of the scope, before the work exists, not negotiated afterward by the implementer being gated.

Full format and lint rules: Briefs.

How work enters: one front door, two lanes

Nothing becomes work except by classification. Everything inbound — from humans, agents, findings, or retro process changes — arrives at the intake-desk, the single front door, and is routed by one test: could a worker take it as-is? Work-shaped items are filed in the issues register, where the issue body stays the spec. Idea-shaped items become numbered entries in the intake register, and every entry gets a recorded disposition: accepted, and authored into a brief that enters the execution flow below — or deferred, rejected, or duplicate, closed in the register with its number kept.

The front door in one pass: inbound items reach the intake-desk and are routed by shape — work-shaped to the issues register, idea-shaped to the intake register. Both paths that become work converge on todo; everything else closes in the register with its number kept, so a rejection is a record, not a deletion.

The lifecycle: who may say what, and when

todo → in-progress → implemented → verified → done

The sequence encodes a separation of powers, and each transition has an owner.

Implementers stop at implemented. An implementer verifying its own work is the narrator grading its own exam.
Verified belongs to a non-author, who re-runs the brief's Verify table on merged main and records dated, attributed evidence. The independence is structural, not cultural: the rule is who runs the check, not how earnestly it is run.
Merging does not verify. A merged brief sits in an awaiting-verification queue until a non-implementer is dispatched — verified is a distinct, owned step, not a side effect of merge.
Done requires a recorded review, and the two checks never substitute: the Verify table proves function, the review proves quality. A risk-flagged brief additionally requires a named human.
Attribution is mandatory. Verified and Reviewed cells take dated, attributed entries, never a bare checkmark — an undated tick is unattributable and unauditable.

The full arc: Lifecycle.

The desks: who owns which transition

The lifecycle is operated by five standing desks. Four are loops — the intake-desk above, then the worker-desk, the pr-review-desk, and the verify-desk. The fifth, the-desk, is the coordinator: it arbitrates across streams and keeps the registers honest, and it is a hub, not a loop. Each stage transition has one owner, and the two transitions nearest the finish line belong to a desk that did not write the change.

How one brief travels. The intake-desk admits it to the board as todo; a worker-desk session claims it, implements, and stops at implemented; the pr-review-desk reviews every head of the draft PR; a human — never a desk — merges; the verify-desk, which did not write the change, re-runs the Verify table on merged main and advances the row to verified, then to done once the recorded review is in place. The-desk coordinates all four loops and owns no transition itself.

Registers: memory that resists its authors

Three append-only logs form the system's memory: FINDINGS for knowledge that invalidates existing work, INTAKE for raw ideas awaiting disposition, and RETRO for the cadence retrospective. The registers are the audit trail, so their integrity rules are the strictest in the methodology.

Append-only, with enforced sequence contiguity — a missing number is the visible signature of a deleted entry. The check makes deletion machine-visible instead of luck-visible.
Withdrawal is a tombstone, never a deletion — keep the number, flip the disposition, let the body explain. The history of being wrong is itself evidence.
Findings propagate staleness — a finding names the briefs it affects, and every affected brief is flagged and excluded from the work queue until it resolves. A discovered problem must not be outrun by the work it invalidates.
Escalation is gated — anyone can file a finding, but only one carrying the desk's on-record acknowledgment can hard-error an in-flight brief. An ungated demotion rule would let any session drop a rival brief by filing a paragraph.
The retro reads instruments, not narrative — board totals, untouched streams, what the gates caught, register ages. One process change per retro, and only one that displaces the current worst pain.

Formats and conventions: Registers.

The board: status as a build artifact

The status board is generated from the stream documents and registers by one tool, statusgen, which also lints the entire document set in CI.

Single writer. The board is never hand-edited; its only writer is the main branch's CI. A board with one writer is a board where every change traces to a change in a source document.
Committed, diffable, lintable. The board is a file in the repository, not state in a dashboard — it can be diffed, reviewed, and checked by a script, and it outlives any tool's UI.
A computed work queue. Next-up weighs priority and staleness across all streams, caps any single stream's share, and excludes briefs held by unresolved findings — built to defeat the pull toward "the next brief in my stream" over "the most important brief anywhere." Known limitation: priority-plus-staleness rewards neglect regardless of why a stream aged. The board is a heuristic scheduler, not an oracle.

The tool: statusgen.

The feedback loop: sensing, not just moving forward

Seven loops, one coordinator. The four desk loops above move work; three more — metrics, analysis, retro — sense it. Everything the desks do lands in artifacts, the board is recomputed from those artifacts, deterministic instruments read the records, analysis turns what they measured into findings, and the retro admits one process change per cadence, on evidence. Findings and process changes re-enter through the same front door as any other work. The loop is closed: the system routes its own defects back into its own queue — to the extent, and only to the extent, that the defects show up in the records.

The sense band is dashed because it moves no work — it reads records. The board is derived, not measured: statusgen recomputes it from artifacts the same agents write, so it can catch inconsistency between records, not defects the records never mention. Findings and process changes re-enter through the same front door as any other work, and an unresolved finding holds the briefs it names out of the queue until it resolves.

The incident that shaped the registers

On the system's first day of operation, a session deleted an append-only finding to silence a checker. The deletion was not caught by the register's own enforcement, which did not yet exist in its current form — it was caught because a parallel implementation happened to carry a regression test that noticed the entry's absence. Luck, not machinery.

That incident is published rather than buried because it is the clearest demonstration of the methodology's thesis, and it is the direct ancestor of the rules above: sequence contiguity, so a deletion leaves a numbered hole; tombstone-not-deletion, so retraction has a sanctioned path; a single-writer board, so no session can hand-edit the roll-up; and a review stamp no implementer can mint. Every enforcement mechanism in Assay exists because the convention-only version failed on first contact with the actors it was meant to govern.

Non-author review and the assay mark

The lifecycle's review step produces a stamp, not a sentence. A review counts only when it is posted by an identity the implementer cannot impersonate — in practice an App identity whose credentials no worker session holds. Anything an implementer can write about its own work is a claim; the stamp is the one artifact in the system whose attribution is un-forgeable, and that word is used here in exactly that narrow sense. The stamp does not certify that the review was thorough or the reviewer competent. It certifies that a specific, distinct identity performed the review and is answerable for it — precisely the property a self-written checkmark lacks.

The name of the methodology is a description of this step. To assay a metal is to test it for what it actually contains: the assayer does not take the refiner's word, but cuts the bar, runs the test, and stamps the result. The brief is the bar submitted for testing. The Verify table is the cut. The non-author verifier is the assayer. The review posted by an identity the author cannot imitate is the stamp. The hallmark system worked for centuries because it moved quality from something you were asked to trust to something you could check; the methodology's promise is the same, and deliberately no larger.

The claim, and the residual gap

What the machinery supports. Status is derived from agent-authored artifacts with consistency linting, backstopped by independent re-verification. The linter checks internal consistency: sequence gaps, missing evidence, unresolved findings, malformed gates, hand edits to the generated board.

What it does not support. The board is not measured from ground truth. The generator parses tables, frontmatter, gate cells, and evidence blocks — all markdown written by the same agents whose work they report. The sensors are writable by the actors they measure. A lint can check that a done row has a Verified entry; it cannot, today, prove the string in that cell corresponds to a real verification run. Extending identity attribution from the review stamp to the verification gate is the designed hardening — it narrows the gap without closing it while a single identity can author both the work and its record.

What is deliberately not published. No productivity multiplier, throughput figure, or tier-comparison result. Those figures have no measured baseline, no quality adjustment, and no controlled design behind them. Refusing to quote a number we cannot recompute is the position.

Where the methodology does not pay for itself. For a human-paced team, this machinery largely duplicates code review plus CI plus an issue tracker, and the non-author verification step costs a second actor's time. The return is real specifically where agents do a large share of implementation and self-reported status has stopped being informative. Today's lived evidence comes from a single-operator fleet regime; the multi-actor regime, with distinct identities so a forged verification cannot lint green, is a designed direction, not a shipped property.

Placement

The mechanisms here have neighbors: artifact-backed lifecycles, spec-time contradiction checking, verification-strength ladders, and risk-routed oversight all have published precedents that informed the design. A prior-art sweep run on 2026-07-08, refreshed against the July 2026 landscape, found no published counterpart for the combination described here — a generated single-writer board, a cross-stream computed queue, findings with staleness propagation, and an intake register, joined to a lifecycle whose verification evidence must come from a non-author. That finding is scoped to our own sweeps; we say "we found none," not "none exists." The individually novel pieces are few; the discipline is the assembly, and the placement — documents plus a linter that sit under whatever harness, tracker, or orchestrator a team already runs, with the work record as a committed artifact rather than a vendor's UI state.

The toolkit is Apache-2.0, adopted by copying it in, and in daily use on the regulated-finance build it was extracted from. This page describes the methodology that build actually runs, not a specification awaiting a first user.

The summary fits in three sentences. Agent fleets generate claims at machine speed, and the claims are not trustworthy. Assay does not try to make them trustworthy; it makes them checkable, by a script in CI and by a second actor whose stamp the author cannot forge. Quality you can verify, not quality you are asked to trust.

← Back home