# How work gets proven

Source: https://flow-next.dev/understand/how-work-gets-proven/

One system with one bias, verification. In-loop checks against numbered acceptance criteria, review receipts, evidence JSON, live-app QA verdicts, and gate receipts keyed to exact commits.

Agents generate. Flow-Next proves.

Every stage of the pipeline leaves an artifact that the next stage, or a human six months later, can audit. That is **one system with one bias: verification**. This page names its parts and explains why it is built this way. The measured problem it answers, and the thinking it comes from, are on [Why Flow-Next](https://flow-next.dev/understand/why-flow-next/).

The pipeline proves the change does what was asked and records what it did; it does not prove the codebase stays maintainable. What it can do is ask before code exists: since 5.5.0, plan review answers two structural questions from the plan as written - does the plan make the same edit or the same decision in more than one place, and does it add a back-edge against the intended dependency direction or new branching to a module’s hottest function - and record a concrete finding or `none identified`. Advisory, never a gate or a score; a named finding lands as one line in the spec’s Decision Context. The measured reason the questions are asked at the plan and not of the implementer is on [Evidence & evals](https://flow-next.dev/project/evidence/).

## It starts inside the loop

Direct execution through `work --no-plan` keeps this verification contract. One owner covers all R-IDs against the full spec. Optional task decomposition changes coordination, not the configured review, coverage, completion, or evidence requirements.

The gates below are handover checkpoints - proof that changes hands between stages. But verification does not wait for a handover. It starts while the implementation agent is still typing.

Every spec carries **numbered acceptance criteria** (`R1`, `R2`, …), and every task declares which ones it satisfies (`satisfies: [R1, R3]`). That is not paperwork - it is the target the implementation verifies against. A single-task spec is built inline in the conversation: a failing test first where it is cheap, then the fix, then focused tests. On a spec with several tasks, before it edits a single line, each [worker](https://flow-next.dev/skills/work/) runs the spec’s own commands to establish a **green baseline**, so “it passed” later means *this change* passed, not that it inherited a suite that was already broken. Either way, it fixes anything it breaks mid-implementation before continuing. And before it is allowed to claim the task done, it re-runs those checks itself - re-anchored on the criteria, proving its own work with evidence, not asserting it in a summary.

This is the bias in its earliest form. The harness makes the implementer *verify as it builds*, against criteria written down before the build started. Everything below is the second line of defence.

### Which commands, and how often: you decide

“The spec’s own commands” is a literal block in the spec (`## Quick commands`), authored by you or by the planning skill, and it is the one place the tiering lives. The convention the bundled scaffold ships with: per-task commands name the focused suites for the files that task touches, and a full-suite entrypoint for the final gate. Work runs a full gate only when you ask for it or your repository’s instructions name a command to run when work is finished (a session-completion or definition-of-done checklist, or before committing, pushing or opening a pull request); that command runs as written, once, at the end, and a command the instructions only list does not run. CI owns regressions. Two mechanisms stop that from becoming a whole-suite run per task - a green receipt keyed to the exact commit and the exact command string skips a re-run at unchanged HEAD, and a docs-only diff drops to lint and format only.

That is a project decision, not a framework one. Want narrower per-task runs? Author narrow commands and keep the full-suite entrypoint as the final-gate command. Want the full suite every task? List it, and it runs. Projects with strong opinions state them in their conductor instructions (`CLAUDE.md` / `AGENTS.md`), which the host agent reads.

One honest boundary: this selection is authored, never computed. Nothing infers that a change in one module should pull in a distant suite. It keeps needless full runs out of the loop; it does not pick the right tests for you - which is why your CI, and the full suite when you ask for it, stay in the table below.

## One system, six vertebrae

Each stage’s proof is a file on disk, not a sentence in a transcript:

| Stage                                                              | What must be proven                                                                                                             | Artifact                                                      |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [In-loop implementation](https://flow-next.dev/skills/work/)       | A green baseline held; the change passes the spec’s own commands                                                                | captured suite output → evidence JSON                         |
| [Implementation review](https://flow-next.dev/skills/impl-review/) | A reviewer issued SHIP, by risk (a skipped review records its reason; an unattended loop can end on a recorded author override) | `.flow/review-receipts/<branch>.json`                         |
| [Task completion](https://flow-next.dev/skills/work/)              | Commits, tests, and a done summary exist                                                                                        | evidence JSON required by `flowctl done`                      |
| [Live-app QA](https://flow-next.dev/skills/qa/)                    | The running app actually behaves                                                                                                | `qa_verdict` receipt; PASS by reading source is **forbidden** |
| [Merge](https://flow-next.dev/autonomy/land/)                      | CI green, reviews converged                                                                                                     | land’s gate tree - evidence over narration                    |
| [Quality gates](https://flow-next.dev/reference/receipts/)         | The exact suite passed at the exact commit                                                                                      | green receipts keyed to commit SHA + command hash             |

Two of those artifacts are worth knowing by name. The **review receipt** at `.flow/review-receipts/<branch>.json` carries the verdict, confidence anchors, introduced-versus-pre-existing finding counts, and deferrals; autonomous loops read it to decide progression, and so can you. The **green receipt** proves one exact command passed at one exact commit, and a reused one leaves a loud `GATE_SKIPPED` line rather than a silent pass. Both formats are documented in [Receipts](https://flow-next.dev/reference/receipts/).

## Two principles hold it together

**Evidence is self-run; the verdict never is.** The implementer verifies its own work *mechanically* - it runs the suite, checks the baseline, gathers the evidence. What it never does is *grade* it: the model that wrote the diff never issues its own SHIP. Reviews are [cross-model by design](https://flow-next.dev/guides/review-workflow/) - a different model family reads the change blind, so the writer’s blind spots and the reviewer’s blind spots do not overlap. (The `claude` backend on a Claude Code host is same-family; it still runs, and the receipt says so.) QA goes further: the skill is structurally forbidden from marking PASS by reading source code, because an implementer’s narration of correctness is exactly the thing that needs checking. Running the tests is evidence; declaring the work good is a judgment - and only the first is the author’s to make.

**Evidence over narration.** Agents narrate confidently; the pipeline is built to ignore that. `flowctl done` rejects completion without evidence JSON. [Land](https://flow-next.dev/autonomy/land/) merges on CI state and converged review threads, never on an agent’s summary of them. Where a claim can be a file, Flow-Next makes it a file.

That matters most where nobody is watching. On [autonomous loops](https://flow-next.dev/autonomy/going-autonomous/) the spine *is* the safety. `flow --auto` advances on receipts and observed flowctl state, and land merges on evidence. The dial changes who is present, never what is proven.

## Where to go next

* [Receipts](https://flow-next.dev/reference/receipts/) - the artifact formats in detail
* [The Pipeline](https://flow-next.dev/understand/pipeline/) - the end-to-end walk, every stage and gate
* [Evidence-first recipes](https://flow-next.dev/guides/cookbook/#evidence-first) - putting the spine to work day-to-day
* [Why Flow-Next](https://flow-next.dev/understand/why-flow-next/) - the measured problem and the lineage this system comes from