The review a change has to survive before anyone calls it done

Prove it works

People ask this as: what should an AI coding agent check before i merge its pull request

Repository policy rather than a command: ten requirements for every feature PR, fifteen adversarial review categories a milestone is attacked with before it merges, a four-value job status vocabulary where the burden of proof sits on the higher value, and ten production gates that are explicitly not met today. Unlike the five commands in this cluster that publish limitation codes it emits none, because it is a document a human enforces — its honest machine-readable analogue is the exit code of npm run verify and the standing list of gates nobody has passed.

Where this stops

Read this before the rest of the page. Every line below is a thing this does not do.

  • It is a document, not a command. It emits no JSON, carries no contract version and publishes no machine-readable limitation codes — the inspector reports that gap from the other side as EVIDENCE_NOT_AGGREGATED.
  • The inspector parses neither. Job status and gate status are prose maintained by people; `crm scenario run <scenario> --json` (DX6) reads the generated job index separately and reports what a business journey established and what it did not, without changing any status. Two scenarios ship.
  • Browser end-to-end coverage is not in CI. It is run manually, and the document names that as the largest coverage gap rather than leaving it to be discovered.
  • None of the ten production gates in section 4 is met: no PostgreSQL conformance suite, no coverage threshold, no mutation tests for versioned policies, no property-based tests, no fuzzing, no dependency scanning in CI, no backup-and-restore rehearsal, no tenant-escape tests and no permission-matrix tests.
  • Authentication-verifier tests remain a deployment concern. Authorization and one-tenant-per-instance isolation are framework-enforced; shared-database row tenancy is not provided.
  • npm run verify proves the tests pass. It does not prove the tests would catch a regression — that is a separate instrument, and it found a real gap the first time it ran.
  • No test count is quoted here. Two files in this repository carry different figures from different commits, and neither was re-run for this page.

No authentication ships: the framework authenticates nobody. Production Spine v1 (ADR-038) gives the framework verified identity, organizations and memberships, server-authoritative authorization and one tenant per application instance — so tenancy and authorization now exist and are enforced. What does not exist is authentication: no login, password, session or OIDC implementation ships, and a deployment must supply the adapter that verifies the request. Production mode refuses to start without one. In local-development mode an actor header is accepted as an assertion and is not an identity, which is the default developer posture. This is not shared-database multi-tenancy and it is not a readiness claim. Every claim and every limitation is on one page.

What question it answers

"What has to be true before this counts as finished?" The document exists because the review discipline that produced several milestones was living in the length of a one-off prompt, and a discipline that depends on how much someone typed that day is not a discipline.

Its definition of complete is a sequence, not a checkbox: implementation, adversarial review, fixes in place with regression tests, compatibility backfill declared, clean-clone verification, CI green, human merge. A milestone that skipped the review is unreviewed, not finished — and the PR body must say so rather than imply otherwise.

What it does

Section 1 sets ten conditions on every feature PR: an ExecPlan written before the code that compares at least three approaches and says why the chosen one wins; a clean baseline verified at the branch point so an inherited failure is found rather than blamed; one milestone per branch; no hidden changes to a shared contract; documentation and ADR moving in the same PR as the code; a conservative job-status update; clean-clone verification from a fresh clone and install; no secrets, databases, logs or build output in the tree; a declared compatibility row for any horizontal capability; and a human merge, never a squash.

Section 2 is the part with teeth: fifteen adversarial categories run against every milestone, where a category that does not apply must be stated as not applicable rather than silently skipped. Public-boundary bypass. State-machine algebra with an explicit transition table rather than a rank. Transaction and fault injection after every significant write. Idempotency with deterministic keys, where a semantic mismatch behind the same key fails closed. Two-connection concurrency. Exact queries proven past 500 rows. Immutable boundaries proven by changing the source and re-reading the snapshot. Provider timeout and late settlement. Replay and reconciliation. Hostile input across `__proto__`, markup, backticks, template substitutions, newlines, Unicode separators, null bytes and oversized strings. Schema compatibility. Backward compatibility. Audit, event and trace exactness — asserting counts, not presence. Real-Chromium browser behaviour. And documentation truthfulness: every claim in a doc, an ADR, a PR body or a job row traces to a merged test, with limitations stated in the same breath as capabilities.

Section 3 is a four-value vocabulary — not supported, partially supported, technically supported, validated end to end — with not supported as the default for anything new, and an explicit ban on inferring a status from an isolated primitive. The vocabulary is enforced mechanically in `docs/benchmarks/jobs.json`, which is why the jobs ledger reads as bluntly as it does: of the rows published there, the overwhelming majority are not supported.

The executable form of section 2 is the `adversarial-review` skill, which `AGENTS.md` rule 10 makes mandatory for any milestone or pre-merge review task.

What it refuses to claim

This is the first of the three entries in this cluster where the honest answer is that there are no limitation codes. Quality gates is a Markdown document that people enforce; it emits no JSON, has no contract version, and publishes no `limitations[]` array. The inspector says so about it from the other side, under `EVIDENCE_NOT_AGGREGATED`: job and quality-gate status live in Markdown maintained by people, are referenced by path, and are never parsed into structured claims. Machine-readable evidence for this is partly built: `crm project verify --json` orchestrates the project's own authorities, and `crm scenario run <scenario> --json` maps real business journeys onto the JTBD index and states the rows they did not establish; two scenarios ship, over two different compositions. Quality-gate status itself is still prose, coverage is claimed by a scenario rather than discovered, and neither command promotes a JTBD row.

Its self-declared blind spots live instead in section 4, a list of ten production gates each described as a hard gate before public multi-user use, and none of which exists today: a PostgreSQL conformance suite running the same tests on both adapters, browser end-to-end in CI (today it is manual, and the document calls it the largest coverage gap), an enforced coverage threshold, mutation tests for versioned policies, property-based tests for pricing arithmetic and state machines, fuzzing for the webhook route and the URL router, dependency and security scanning, backup and restore rehearsal, tenant-escape tests, and permission-matrix tests once role-based access control exists.

This page also quotes no test count. The claims ledger and the project status file were generated at different commits and carry different numbers, and a figure nobody has re-run is precisely the kind of claim these gates exist to refuse. What was re-run for this page is the cheap half: `npm run check` passed, which is all `check` is — a syntax pass over every JavaScript file in the repository, with `verify` being that plus the test suite.

What it costs to run

`npm run verify` is `npm run check && npm test`. The project-doctor ExecPlan measured it at about 156,000 ms on this repository — roughly a thousand times the cost of the source-only checks, which is the entire argument for those existing. The syntax half alone returns in about a second.

It exits non-zero on any failing test and writes nothing to the repository. The rest of the discipline is not a command at all: an adversarial review is a person or an agent working through fifteen categories, and clean-clone verification means a fresh `git clone` and a fresh `npm install` before running anything.

The document carries a companion budget that does run. `node scripts/surface-check.js` fails the build when the surface an agent must understand exceeds a stated ceiling, and it printed here: 1/1 goal entry points, 12/12 skills, 9/10 always-on tools, 11/11 commands in skills, with the closing line "Internal complexity may grow. Perceived complexity has not." Every ceiling carries the reason it is where it is, so raising one is a deliberate edit with an argument attached.

Where it fits

It is the last gate, and it is the one the other seven tools are measured against. The cheap commands exist because this one is expensive; the falsification kit exists because passing this one is not the same as being defended by it.

The jobs it serves are honest about the gap. Verifying a solution against defined acceptance is partially supported — the gates, the validator, the suites, the clean-clone run and the jobs matrix are real and enforced, and there is no automated goal-to-acceptance runner. Reporting unavailable capabilities honestly is also only partially supported: the matrix and package metadata make the honest answer available, and nothing enforces that an agent uses it, which is why the skills state it as a rule.

The evidence this page rests on

Claims and limitations are printed from site/claims.json word for word. Job statuses come from docs/benchmarks/jobs.json; a job with no page of its own is listed with its status rather than linked.

Claims

  • C-20 The verification gate runs on every push — source checks and then the whole test suite — covering happy paths and the policy boundaries that matter: hostile input, transaction rollback, idempotency, concurrency and immutability among them.

    LimitA test count measures effort, not correctness — read the adversarial-review categories in docs/QUALITY_GATES.md to see what is actually attacked. Real-browser tests are run manually and are not in CI.

  • C-16 Every mutation goes through a module service or a named workflow, and leaves an audit event and a step-level trace behind it.

    LimitAudit records what the process did under an asserted actor. It is not a tamper-evident or externally attestable log, and it is not a compliance control.

  • C-04 The agent cannot approve on the human's behalf. A test asserts the refusal, so the boundary is a property of the system rather than a promise in a README.

    LimitIn local-development mode the actor is asserted, not authenticated: no authentication ships, so an actor header there is not an identity. This holds a boundary against an honest agent, not against an attacker with network access.

Limitations

  • L-01 No authentication ships: the framework authenticates nobody. Production Spine v1 (ADR-038) gives the framework verified identity, organizations and memberships, server-authoritative authorization and one tenant per application instance — so tenancy and authorization now exist and are enforced. What does not exist is authentication: no login, password, session or OIDC implementation ships, and a deployment must supply the adapter that verifies the request. Production mode refuses to start without one. In local-development mode an actor header is accepted as an assertion and is not an identity, which is the default developer posture. This is not shared-database multi-tenancy and it is not a readiness claim.
  • L-03 The build benchmark has not been run. The protocol is designed and published; no Successful Agent Build Rate exists yet. Any number you see quoted for this project is not ours.
  • L-06 Bounded customer imports and logical identity; incomplete data operations. Customer Data Foundation supports bounded JSON imports with preview/apply, per-row receipts and idempotency, deterministic duplicate candidates, and human-governed canonical identity as logical links. It does not provide CSV ingestion, physical merge, complete export/erasure, bulk editing, saved views or global search.

Jobs it covers

Documented in

Proved by