Aif Verify

# Project Rules for /aif-verify

> Curated from review pass-through findings.
> Sections under "Auto-generated rules" are managed by `/aif-evolve`; do not hand-edit them.
> Last updated: 2026-09-04
> Based on: 2 adversarial-review pass-throughs (M6 / 2026-05-28, M7 / 2026-05-28)
>
> - /aif-evolve M11b/M11c adversarial-review batch (2026-06-01)
> - /aif-evolve 107-patch batch (2026-06-17, cursor 2026-05-30 → 2026-06-16)
> - /aif-evolve 114-patch batch (2026-07-11, cursor 2026-06-16 → 2026-07-07)
> - /aif-evolve 74-patch batch (2026-09-04, cursor 2026-07-07 → 2026-09-04)

## Rules

### Re-derive the contract-surface list from the diff, not from the plan

**Source**: M6 adversarial review pass-through (2026-05-28)
**Rule**: Before declaring verify pass, enumerate every external-facing contract changed in the diff and confirm each has a corresponding spec/doc edit. Do NOT trust the plan's docs-list alone — the plan often misses spec files that nobody traced from the changed code.

Concrete enumeration checklist (apply to every changed file):

| Surface                                                              | Where the spec lives                                                                                                                                                      |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP route status codes, request shape, response shape               | `docs/api/*.openapi.yaml` AND any prose contract doc (`docs/supervisor.md` for the supervisor; component-level docs under `docs/system-analytics/` for cross-tier flows). |
| SSE event types, payload shape, terminal signals                     | `docs/api/async/*.asyncapi.yaml` AND the relevant `docs/system-analytics/*.md`.                                                                                           |
| Wire fields that changed semantics from "reserved" to "load-bearing" | The same spec file as above — both the prose and the example payloads need to move.                                                                                       |
| New env var or config-file path consumed at runtime                  | `.env.example` AND the env-vars table in `docs/configuration.md` (do not rely on a narrative mention; the table is the canonical source).                                 |
| New CLI flag, `package.json` script, or `pnpm exec` target           | `docs/getting-started.md` "Scripts" section AND the relevant `web/` or `supervisor/` `CLAUDE.md` slice.                                                                   |
| New DB column, new table, new index                                  | Drizzle migration committed AND `docs/database-schema.md` AND the relevant `docs/db/*.md` ERD file.                                                                       |

Mandatory gate: produce the list explicitly in the verification report (even if some entries are "no change required"), so reviewers can see the enumeration was performed. A passing verify report MUST cite the surfaces it checked. If a surface is on the list and the spec was NOT updated, escalate to a blocking finding — not a warning.

**High-drift sub-surfaces the diff scan must also reconcile (each is "code lands, docs lie"):**

- **Documented edge-case bullets** are the MOST dangerous drift — they read as a reviewed invariant and steer future implementers back to the old shape. A behavior that converged/removed a special case MUST delete or rewrite its old edge-case bullet, not just update the diagrams/enums.
- **Dormant-capability flip:** when a change turns a previously-dormant capability ON (e.g. the polymorphic `agent` actor going live), grep the older-stage analytics for `never` / `not yet` / `MUST NOT` claims and `(Designed)` / future status tags that the flip invalidates.
- **DB cascade/default claims** must be derived from the migration SQL `ON DELETE` clause, not the plan prose (docs claimed "no cascade"; migration `0040` shipped `ON DELETE CASCADE`).
- **Cross-file duplicated tables** (the same outcome strings in `readiness.md` AND `configuration.md`) re-drift — flag them to be collapsed per "cross-reference, do not duplicate," and verify the new value landed in EVERY copy (`system-analytics/` + `configuration.md` + `error-taxonomy.md` + every `.openapi.yaml`).
- **Self-contradiction on a touched value:** grep for a headline default the change touched appearing with two values (`MAISTER_MAX_CONCURRENT_RUNS` was `6` at one line and "global cap = 3" at another). New schema (`runs.agent_workspace`, migration `0052`) must be added to the runs/agents domain docs + `database-schema.md` citing its migration.
- **In-code SSOTs are contract surfaces**: grammar/prompt/assistant files shipped to agents (`flow-dsl-grammar.ts`, the `/flow-authoring` skill) and their drift-guard tests move with the DSL/schema change — a `docs/`-only sweep misses them.
- **Route-tree ↔ OpenAPI grep before exit**: when a phase adds an HTTP route — including READ aggregators (`capability-catalog` was missed next to its documented `…/commands` sibling) — grep the route tree against the spec paths.
- **Both directions, both cases**: sweep for phantom spec params the code never reads AND code fields the spec lost; docs greps for columns try snake_case AND the Drizzle camelCase field name (`database-schema.md` documents camelCase — a snake-only grep yields false "missing column" findings).
  **Source (additions)**: 2026-07-01-11.19, 2026-06-17-19.53, 2026-07-02-14.14, 2026-07-01-12.55

- **Auth added to a route** changes its status-code surface — the spec entry must gain `401`/`403` (via the `Unauthenticated`/`Forbidden` `$ref`s); **every `.strict()` zod body has exactly one `additionalProperties:false` spec schema** — sweep Class A (zod field ⊄ spec properties) and Class B (route returns 401/403, spec omits) over every route the branch changed, using the right file (`/api/v1/ext/*` → `operations.openapi.yaml`, everything else → `web.openapi.yaml`); prove every internal `$ref` resolves; response-shape-vs-code drift is INVISIBLE to `validate:contracts` — diff re-authored schemas field-by-field against the handler.
- **Engine bumps** are cross-surface (constant + compatibility tests + fixtures + agent-facing DSL grammar + host-version docs); **stored-form changes** put every read DTO returning that text in scope; a **phased feature** re-runs the as-built reconcile when its UI phase lands; a canonical `docs/system-analytics/*` artifact is an AS-BUILT surface ("Designed"/"planned" → implemented).
- **Mechanism sentences** (REQ "reads the persisted snapshot", "discriminated union") and refusal-table "Where checked" cells are re-derived from code line by line; an Expectation bullet must NAME what enforces it.
- **Coverage honesty**: the test inventory distinguishes browser happy-path coverage from recovery/refusal tests; release tasks record the external package TAG + COMMIT, and release evidence must be reproducible from the TAGGED bytes (live patches during acceptance → re-cut the tag, re-run from a fresh checkout).
  **Source (additions)**: 2026-07-16-15.20, 2026-07-25-11.14, 2026-07-15-12.41-engine-3.1-and-product-contract-sweep, 2026-07-27-09.30, 2026-07-12-22.40, 2026-07-27-11.00, 2026-07-11-21.30, 2026-09-02-03.51, 2026-07-17-00.10, 2026-07-14-22.10, 2026-08-01-09.09

### Runtime parity gate — verify deployment can actually exercise the new path

**Source**: M6 adversarial review pass-through (2026-05-28)
**Rule**: For features that introduce env vars, config files, sidecar processes, new ports, or new host-mounted paths, verify the SHIPPED runtime (Docker compose files) can run the new path. Passing tests against mocks or testcontainer fixtures do NOT prove deployment readiness — they bypass the container boundary entirely.

Concrete checks per change class:

- **New env var consumed by a service** → grep `compose.yml`, `compose.production.yml`, `compose.override.yml` for the var name. Absent in all three → blocker (or explicit "deferred" docs entry per rule A2 in aif-implement).
- **New config file read from a host path** → grep the same files for a bind mount or named volume that exposes the path inside the container. Absent → blocker.
- **New sidecar binary** → confirm the dep is declared in the consuming package's `package.json` (lockfile committed), and that the bin is reachable from the container's PATH (workspace bin path is enough in dev compose; production prod overlay may need PATH adjustments).
- **New bound port** → if reachable from outside, confirm port mapping in compose; if internal-only, confirm no port conflict with other services on the same network.

The verify report MUST contain an explicit "Runtime parity" section listing each new dependency and its compose status (✅ wired / ❌ missing / ⏭️ explicitly deferred with docs link). Skipping this section = automatic warning; finding a missing wire that the plan did NOT mark deferred = blocker.

### Config→DB round-trip gate (SET and CLEAR symmetry)

**Source**: M6 adversarial review pass-through (2026-05-28)
**Rule**: When a feature introduces a YAML→DB column mapping that downstream readers use, the verify step MUST confirm the test suite covers BOTH halves of the round-trip:

1. **SET half**: writing the YAML field → the DB column equals the resolved value.
2. **CLEAR half**: removing the YAML field from a config that previously had it → the column equals the default (null / false / zero).

Asymmetric coverage is a blocker, not a documented limitation. If the SET-only test exists and the CLEAR-half test is missing, the verify report MUST list the missing test as a blocking finding under "Config→DB symmetry". An integration test that asserts the stale value persists after CLEAR is the WORST outcome — flag it as a bug that has been enshrined as behavior, and require both the test and the implementation to be fixed before verify passes.

This rule applies to any persistence layer (Postgres column, SQLite column, JSON file on disk that downstream code reads, env var written by a config materializer). The pattern "for entry in config: if !entry.field continue" is the giveaway.

### Regression-test enumeration for trust-boundary, retry-semantics, and deferred-release classes

**Source**: M7 adversarial review pass-through (2026-05-28)
**Rule**: When the plan or diff touches any HTTP route handler, SSE event handler, or queue consumer that the plan-side rules in `.ai-factory/skill-context/aif-plan/SKILL.md` flag as relevant ("cross-resource identifier", "two-phase commit", "no hidden deferreds"), the verify step MUST confirm a regression test exists for EACH of the following classes that applies to the diff:

| Class                                              | Test must assert                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Trust-boundary (body-controlled cross-resource id) | A request whose body field tries to name a different resource than the server-state-derived one is rejected — OR the body field is absent from the route entirely. Concrete shape: a test that constructs a request bound to session A but with a body claim of session B's runId, and asserts the handler does not write under session B's path.                                                                                                                                  |
| Retry-semantics (two-phase commit)                 | (a) The happy path leaves the idempotency marker set ONLY after the downstream ack. (b) Simulated downstream 4xx (terminal class) transitions the parent resource to its terminal state AND marks the row terminal-failed in the same call. (c) Simulated downstream 5xx / network error returns the retryable status and leaves the row in a state a retry can recover (response set, marker null); a follow-up retry under the same row succeeds when the downstream comes back. |
| Deferred-release (no hidden deferreds)             | A test that simulates a failure in the releasing-side code (DB error during the persist step, etc.) and asserts the deferred-creating-side release API was invoked exactly once with the right arguments. Use a spy on the cancel / reject API; without the spy, the regression cannot regress safely.                                                                                                                                                                             |

The verify report MUST contain an explicit "Failure-class regression coverage" subsection listing each applicable class and the test file + test name(s) that cover it. A class that applies to the diff with no matching test is a blocking finding, NOT a warning. A class that does not apply (e.g. the diff added a pure read-only route with no downstream effects) is marked `n/a` with a one-line justification.

Reason: M7's first design described the three failure modes the Codex adversarial review found ONLY in the prose of the plan. None of the failure modes had a regression test, so an implementation following the prose could have shipped any of them. The fix added explicit test cases per failure class. The verify step's job is to make sure the test cases survived the implementation pass — they have a habit of being trimmed under deadline pressure. Re-derive the list from the plan + diff, not from the implementer's word.

Degraded/temporal matrix additions (confirm coverage per applicable class): disabled-switch path (feature off → EVERY consumer no-ops); never-resolving external fetch (explicit `AbortSignal.timeout` exercised); concurrent double-fire; redelivery-after-alternate-branch (reinforce, not just insert); pause→resume round-trip PER run_kind that can reach the pause (a `runFlow` resume throws `PRECONDITION "flow not found"` for `flowId=null` agent/scratch runs — swallowed and stranded); BOTH branches of any changed validation predicate (where intentionally skipped AND where still required); broken-resource recovery separated from happy-path disable (register, remove from the tracked ref, then disable); the temporal stale-pass case (older `passed` attempt + newer LIVE `pending` ⇒ not passed); exact-failure-mode assertions (a broad `PRECONDITION` assert can pass on the WRONG precondition path — assert the specific message/evidence); and for any "could not complete the side effect" branch, assert the run CANNOT advance to success (assert the terminal status, not just absence of a happy-path artifact).
**Source (additions)**: 2026-07-02-15.32, 2026-06-22-11.32, 2026-07-04-14.30, 2026-07-04-14.15, 2026-07-03-16.40, 2026-06-24-03.08, 2026-07-04-01.04

2026-07..09 matrix additions: every ownership state transition (`preparing`/`active`/`releasing`) has a direct interruption/retry case; lifecycle code has a cleanup-FAILURE case (`Pool.end()` throws → container still shut down); every renewable lease has long-running renewal AND stale-completion-after-expiry; recovery arms are seeded with EACH non-terminal phase (`verifying`, `pushing`); answer-vs-successor races are asserted as MUTUALLY EXCLUSIVE terminal outcomes; schema-migration contracts cover ABSENT vs PRESENT source artifact sets; transition-derived behavior is tested on a topology where the forward PRODUCER and the REWORK TARGET differ; anti-evasion (an ungoverned pass-through between denies does not reset the breaker); every mutating pair is symmetric (a CAS on delete matching the CAS on save); an asymmetric boolean has one test per arm; the tree-terminate/finalizer arms are exercised with the REAL child kind (agent, not flow).
**Source (additions)**: 2026-07-11-12.25, 2026-07-13-01.45-test-database-review-findings, 2026-07-17-00.10-workspace-lifecycle-review-remediation, 2026-07-16-11.20, 2026-07-14-human-ask-review-remediation, 2026-07-14-14.00-legacy-package-schema-compat, 2026-07-14-22.10, 2026-07-12-10.43, 2026-07-27-21.50, 2026-07-27-09.30, 2026-09-03-21.47

## Auto-generated rules (managed by `/aif-evolve` — do not hand-edit below this line)

### "Logic exists + unit test passes" is NOT proof the behavior runs in production

**Source**: 2026-06-01-12.16, 2026-06-01-13.16 (#3), 2026-06-01-01.29, 2026-05-31-14.34
**Rule**: Before declaring verify pass, for every validation/branch the plan promises, PROVE it executes on the production path and that its test exercises the production path — a green test is not evidence by itself. Four concrete false-green gates:

1. **Optional-parameter validation (tested-but-unwired).** If a check is gated behind an OPTIONAL parameter (`loadFlowManifest(..., opts.executorIds)`), grep ALL production call sites and confirm at least one supplies it. A unit test that passes the parameter itself proves nothing about production wiring — the rejection branch can be dead in prod while the test is green. Trace from the diff's call graph, not from the test. Relatedly: validation whose inputs are project-scoped must run at a project-scoped seam (launch / `POST /api/runs`), not a package-scoped seam (install); and a reference id must be validated against the correct id-space (`executors.executor_ref_id`, not the `executors.id` PK).

2. **Parse-layer fidelity.** A schema-driven behavior test that builds its input from a hand-written object LITERAL bypasses the production Zod parse and any parse-time defaults — a false green for the deployed path. For schema-driven logic the test MUST feed real input through the production schema (`flowYamlV1Schema` → evaluator). Verify each such test actually parses; a literal-fed test is non-evidence.

3. **Sweep / coverage counts.** A source-sweep or "all classes cleared" assertion that checks only a loose MINIMUM count lets a missing scope look covered. Require an EXACT configured-scope count AND at least one fixture per supported source/scope, so a future source addition cannot silently drop from CLEAR handling.

4. **Never trust a piped exit code.** A verify command piped through `| tail` / `| grep` / `| head` reports the LAST stage's exit status (0), masking a failing vitest / lint / typecheck. Run the command BARE and check `$?`, or use `set -o pipefail`, before asserting pass/fail. A green-looking `| tail` is the worst false-green — it nearly shipped a 20-test-red integration suite as "exit 0". Also: a committed integration seed that inserts a FK/`NOT NULL` column as `null` (loose `drizzle(pool)` does not enforce it) makes a Docker-gated suite silently red — confirm the suite actually ran green, not merely "was present".

5. **Mock-hid-the-bug.** A recovery/branch/dispatch action (redispatch, resume, retry, promote) MUST have a test that drives the REAL executor and asserts an OBSERVABLE effect (a new attempt ran, a row advanced), NEVER "the dispatcher was called" against a mock — `runGraph`'s no-op guard returned `{state:"redispatched"}` while doing nothing, invisible because the test mocked `runFlow`. Relatedly, do not let a seeded e2e fixture stand in for the REAL producer of a NEW contract (the `aif` evidence manifest "passed" e2e while being unproducible through the real runner because the e2e seeded the artifacts) — exercise the real producer at least once.

6. **Codify the contract, not the current emission.** A test that asserts "the shape the code currently returns" cements drift. When the contract lives in docs or another module (`classifyRecover`, `assertEvidenceReady`, OpenAPI), assert against THAT, with the EXACT DTO shape (object vs string array; no extra keys) — a route test asserting a field is ABSENT (`expect(body.files).toBeUndefined()`) is a tripwire: when it flips to presence, the matching OpenAPI schema is a required edit in the same commit.

7. **Vacuous-pass guard.** A test asserting "did NOT happen" (not crashed, not quarantined, no supersede) MUST also assert the path was actually exercised (e.g. `candidates >= 1`) so it cannot pass on an empty/short-circuited run. A bounded-query/N+1 test must seed ENOUGH rows to trip a per-run loop (8 runs, not 1).

8. **Concurrency tests must hit the lock branch.** A Postgres-only branch (`isPostgres()` + `FOR UPDATE`/CAS) silently skips unless `process.env.DB_URL` points at the testcontainer in `beforeAll`; the contention contract (409-vs-500) needs TWO racers, not a single-threaded test. Env-var fixtures must capture-and-restore (`originalDbUrl = process.env.DB_URL`; in `afterAll`, `delete` only when originally `undefined`, else restore) — an unconditional `delete` corrupts a pre-existing value.

9. **Probe the host before deferring; mind the vitest realm + glob.** Before deferring a Testcontainers lane as "unrunnable here," probe the HOST with the sandbox disabled (`docker info` against `~/.docker/run/docker.sock`) — "no container runtime" is usually a sandbox limit, not a host one. `vi.resetModules()` + a dynamically-imported SUT breaks `instanceof MaisterError` (fresh module realm) → status maps to 500 instead of 409. `.integration.test.ts` is for real external deps only; a pure-function test belongs in the unit project — after renaming across the unit/integration glob boundary, re-run BOTH projects and confirm per-project counts shifted (a file matching neither glob runs nowhere).

10. **Integration lane is mandatory for schema/SQL claims.** "Gates green" means `pnpm test:integration` RAN, not just unit (a branch shipped "green" with a 76-file/439-test-red integration baseline); raw-SQL readers, null-column predicates, CAS/fence fixes, and burn/no-burn ordering have ZERO coverage from mocked-db unit tests — real Postgres only; prove a new regression by reverting the fix to reproduce the error.

11. **Merge sign-off = FULL suites scoped by CONTRACT, not by diff.** A merge that widens a shared emit/DTO/required field (`parent_run_id` required on run-terminal `emitDomainEvent`) breaks exact-shape `toEqual` asserts in files the branch never opened — run full integration AND full unit before stamping a merge green (targeted runs are for iteration, not sign-off); also run the full unit project after touching shared services (fake-DB branch tests exercise paths real-PG integration never hits).

12. **Cross-tier payloads test the REAL acceptor schema.** A web payload mocked at the supervisor-client boundary proves nothing and tsc can't help (the two sides' types are structurally unrelated) — feed a representative resolved payload through the actual `.strict()` acceptor (`StartSessionRequestSchema`).

13. **Composition-root wiring.** A handler reading an OPTIONAL injected dependency with no fallback (`opts.optionalDeps?.lifecycleManager` → 409) is certified by unit tests but dead in prod if the entrypoint never sets it — require a test on the real composition root (extract `buildRegisterRoutesOptions(deps)`), and treat a "409 when not configured" test passing with `boot(undefined)` as a smell that encodes broken prod as expected; grep every `opts.<dep>?` read for a fallback or a wiring test.

14. **Guard-neutralize RED proof.** Prove a guard test non-vacuous by neutralizing the guard line and watching the test go RED, then restore; "no leak / size === 0" assertions must first ARRANGE a non-zero leakable state (assert the count was >0 before cleanup) or they pass vacuously.

15. **Coverage-location honesty.** The test's ACTOR matches its stated intent ("manual/human" ⇒ a user actor + seeded `users` row, not the system/token entry point); user-facing FORM paths are covered, not only API routes hand-fed complete payloads (API tests supplied the `flowId` the real modal never sent); partial matchers (`objectContaining`/`toMatchObject`) on route responses verify presence never absence — require exact `toEqual` both-direction key equality; boolean→array contract changes need `toHaveLength`, not truthiness (an empty array is truthy).

16. **Contract tests are written RED-first** against existing drift (the RED run enumerated 10 drifted tools no human spotted), and `Intl`-dependent formatting stubs the timezone (UTC CI flake).

17. **Cover the divergent variant.** The adapter whose behavior differs (codex sigils, not just claude), the config axis that exits through a different status (`workspace: worktree` children exit `Review`; the e2e used `none` and masked the headline case), and per-discriminant arms (half-A + half-B ≠ A∘B).

18. **Mutation-proof every fix, and prove the mutation applied.** `expect(code).toBe("CONFLICT")` passed with the guard deleted because a SECOND mechanism yields the same code — neuter the fix, watch the new test fail, restore; verify the mutation string actually MATCHED before believing a red (two fences "passed" under a mutation that had not applied); a TTL write survived `SET lock_expires_at = lock_expires_at`, transport URLs survived `/BROKEN-*` — re-read the column from the DB, not the fixture.
19. **Test-seed realism.** A seed no production writer produces (a claim with no `lifecycle_operation_attempt_id`, a self-stamped `root_run_id`, `prState:"closed"+prHasConflicts:true`, a paused run with no in-process driver, a branch initialized exactly at `main`) is a HOLE, not a fixture — "does any production writer produce this row?"; a check that only fires under an unusual precondition needs a second test in the ordinary shape; read DB CHECK constraints before seeding.
20. **Races at the owning layer, contending on the invariant.** A two-racer at the route layer self-serializes on identical I/O; the racers must be able to BOTH violate the property (two different parents for an ancestor-scoped count) and the winner must perform the real writes (uncommitted child inserts, parking asserted via `pg_stat_activity`); assert ORDER through signals, never "already happened by now"; cover BOTH orderings; every barrier released in `finally` and both racers awaited (a leaked winner lands in the next test's spies); mutation-check by disabling the guard.
21. **Deny-only coverage is unproven.** Grep each new scope/grant constant — if every test naming it asserts a refusal, the granted path is unverified (an oracle fix made it unreachable and stayed green); require the positive end-to-end case.
22. **Wire fields on the wire.** A `details`/`code`/header that exists for a client is read off a real `Response` in at least one test; a value placed in a MOCK is not tested — grep for the field in mock setup with no matching response assertion.
23. **Discriminating assertions.** The asserted effect must be one only the new path produces (`status === "Failed"` was produced by the bug; the revoked token + the promoted AGENT run was not); composition tests assert `errors: []`; refusal tests exercise the EXPENSIVE branch (the terminal-run 409 test had no children so it never entered the cascade); a "self-X" test for a neighbouring concept is not coverage of the new one.
24. **A test that pins weak behavior is worse than none** — an assertion whose comment explains why the weak thing is fine (viewer→200 on repo-class data) freezes the wrong answer; read a fixture's DATA, not its comment (a "colliding" fixture with distinct refs proves the weaker property); ask what a proposed test would PROVE (a stepwise migration replay would test Postgres's `ADD COLUMN` semantics — `information_schema.column_default` proves strictly more); a test that cannot OBSERVE a violation (forbidden row unreachable AND scoped away) is decoration.
25. **Suite state is evidence only when it loaded and is judged by name.** A 0-test suite (`Failed to load url sqlite`) is a failure; when the dependency tree is unavailable every gate is UNRUN and the delivery NO-GO; integration regression is judged on NAME SETS, never counts (±2 flips run-to-run); BASELINE-PROVE before blaming the diff (stash → run on main); a "red on main / accepted baseline" test is debt to diagnose; classify environment gaps (`supervisor unavailable (network)` → no :7777; `listen EPERM` → sandbox; no container runtime) before chasing; "reproducible failure" ≠ "product bug" — check WHERE the test failed (the promote returned 200; only the page-wide `getByText` assertion was wrong).
26. **Send-site and parity coverage.** A value derived in one module and accepted in another has a test at the SEND site (the spy on the outgoing `createSession` body); a contract split across two processes has a PARITY suite running one scenario table against the fake AND a real peer.
27. **Mock identity and effect counts.** A hook-returned function mocked as a fresh function per render (`next-intl`) loops to OOM — mocks preserve the real hook's stable identity, and mounted tests assert EXACT side-effect counts; role mocks refuse the real role's full deny set; a second `vi.mock` of one module in a file silently shadows the first.
28. **Security-control tests assert the BYPASS.** Enumerate evasion shapes (transport prefixes, option-leading, encoding) and pin each as a negative test; re-derive the regex's actual accept-set by running it on the evasion strings — "malicious input rejected" for an unrelated reason is false green.
29. **Test matrices and ownership regressions.** A Test Matrix is a checklist to AUDIT row-by-row against real assertions (four rows claimed covered had no test, incl. the security-relevant live-loader `flow_not_launchable`); keep mocked route tests for DTO shape but add at least ONE DB-backed regression whenever the feature relies on server-derived project/run ownership (token bound to project A → 404 for project B's run + the audit row, on the real `handleExt` + token + DB path) or on transaction visibility / commit order; control-plane invariants are tested through the REAL service + Postgres (rollback + re-entry), and retry idempotency at the observable OUTBOX boundary.
30. **E2E hygiene.** A fixture seeding N runs against ONE mutable git ref couples its scenarios (each gets its own ref); `--workers=1` closing a render→click window does not clear an order-dependent flake — ask which INTERLEAVING opens it; a flaky e2e is root-caused (dump the run row, transitions, ledger and host log on timeout), never quarantined; every spec needing a session is in the AUTHENTICATED Playwright project; status assertions use the surface's own testid.
    **Source (additions)**: 2026-07-16-14.05, 2026-09-01-04.15, 2026-07-21-23.50, 2026-07-16-16.05, 2026-07-15-18.10, 2026-09-03-15.06, 2026-09-03-17.20, 2026-09-01-05.40, 2026-09-03-23.46, 2026-07-27-20.55, 2026-09-03-14.30, 2026-09-04-01.33, 2026-07-27-21.50, 2026-08-06-19.10, 2026-09-03-21.47, 2026-09-03-15.37, 2026-07-27-09.30, 2026-07-14-13.45, 2026-07-16-16.40, 2026-07-12-11.21, 2026-07-11-13.34, 2026-07-17-00.00, 2026-07-22-01.14, 2026-07-11-23.47-mcp-v2-review-fixes, 2026-07-11-12.42, 2026-09-03-16.10, 2026-07-11-21.30, 2026-09-04-00.21, 2026-07-16-13.03, 2026-09-02-12.10, 2026-07-12-11.12, 2026-07-24-15.19, 2026-07-27-11.00, 2026-07-27-11.56, 2026-07-14-22.50-plan-review-review-fixes, 2026-07-13-00.59-unified-test-database-review-remediation

The verify report MUST state, for each applicable gate, the production call site / parse path / exact count / bare-exit-code check / real-executor effect it confirmed. A gate skipped is an automatic warning; a confirmed false-green (dead validation, literal-fed schema test, piped exit code hiding red, mock-asserted dispatch, vacuous "did-not-happen" test) is a blocking finding.
**Source (additions)**: 2026-06-27-14.28, 2026-06-27-16.03, 2026-06-27-23.45, 2026-06-30-01.37, 2026-06-30-12.23, 2026-06-21-03.05, 2026-06-22-12.47, 2026-06-23-13.22, 2026-06-20-18.43, 2026-06-18-22.18, 2026-06-23-18.25, 2026-06-22-19.56, 2026-07-04-22.53, 2026-07-02-16.42, 2026-06-25-17.19, 2026-07-02-14.14, 2026-06-17-19.53, 2026-06-20-23.22, 2026-07-02-17.52

### ADR / migration numbers and journal integrity — re-grep main's HEAD at merge, never trust a checkbox

**Source**: 2026-06-07-20.16, 2026-06-09-18.47, 2026-06-11-09.20, 2026-06-11-12.51, 2026-06-10-23.57, 2026-06-09-20.30
**Rule**: ADR numbers and Drizzle migration `idx`/`tag` are a globally-sequential shared namespace, so a collision is invisible on a single branch (every gate green). Before declaring verify pass on a branch that adds an ADR or migration:

- Re-grep `git show main:docs/decisions.md | grep "^### ADR-"` AND `git show main:web/lib/db/migrations/meta/_journal.json` for the claimed numbers — immediately before merge AND again every time main moves. A `[x]` checkbox or commit subject is NOT evidence the ADR/migration landed (a Task marked `[x]` "write ADR-063" shipped with the ADR silently omitted).
- Verify each migration number against the JOURNAL, not the prose (`0029` documented in 5 places shipped as `0030`).
- `pnpm validate:docs` only parses Mermaid; `validate-docs-adr-anchors.mjs` only checks an anchor RESOLVES, not that the visible `[ADR-NNN]` link text matches the `#adr-NNN-…` slug it targets — an over-reached `[ADR-072](#adr-071-…)` passes green. Verify link-text↔slug agreement manually.
- Keep/confirm a `migration-journal-integrity` test asserting every tag↔file, unique `idx`, unique `tag` (Drizzle's `readMigrationFiles` ignores `idx`, iterates by array order, resolves `${tag}.sql`, dedups by `when` — so a reserved idx-gap is safe but an orphan/dup tag is not).
- A new migration is a TRIPLE: SQL file + `_journal.json` entry + `meta/<NNNN>_snapshot.json` — the NEWEST journal entry MUST have a matching Drizzle snapshot (a missing snapshot silently starves future `db:generate`; newest-only so legacy gaps stay tolerated); journal `when` must never be future-dated (a later `Date.now()` migration would be silently skipped); hand-authored second lineages (brain) get the same journal lint, parameterized over BOTH lineages, and `pnpm db:generate` must report "No schema changes" after.
- **Claims are not evidence**: "covered by suite X" → open X and confirm it actually imports/calls the SUT (directory adjacency ≠ coverage); a ✅-checked task whose plan listed explicit test cases stays PARTIAL until each listed case is found in the diff; an implementer deviating from a LOCKED plan decision without sign-off is a finding, not a silent pass — and an accepted deviation rewrites every stale plan/spec sibling in the same pass (one prominent superseding note naming them all suffices); when the test strategy changes (planned Playwright replaced by SSR/route coverage), the traceability matrix and acceptance rows are amended — never a checked task promising absent tests.
  **Source (additions)**: 2026-07-07-13.51, 2026-07-02-17.52, 2026-06-18-23.21, 2026-06-18-12.07, 2026-06-18-12.19, 2026-07-04-01.04, 2026-06-24-20.47

- `schema.ts` is the FOURTH leg of the migration contract: after a hand-authored migration, run `drizzle-kit generate` and confirm "No schema changes" — a proposed UNDO means `schema.ts` was never updated (0125 widened a CHECK to 13 kinds while `schema.ts` declared 11).
- A migration that DROP+re-CREATEs a CHECK/enum on a SHARED table is re-derived from `schema.ts` at rebase, never carried verbatim (0111 dropped main's `run_pr_merged`; snapshot + schema correctness MASKS it from every drizzle tool) — grep the re-created value list against main's newest migration on that constraint.
- A migration that STRENGTHENS a multi-column invariant is verified by running the owning real-Postgres suites after enumerating every writer and fixture — typecheck cannot see check-constraint violations.
- Guard the guards: an ADR gate that `Set`-collapses duplicate numbers and a migration test that PREFIX-matches `0103` both pass while broken — match by NAME and assert the snapshot `prevId` chain + `when` monotonicity; a follow-up migration updates the journal test to locate the owning migration by CONTRACT, not "newest"; a cross-cutting constraint receives its OWN number.
- After ANY provenance renumber the grep-to-zero surface includes STATUS LABELS (`Designed`/`Accepted` → `Implemented`), prose number forms, CODE COMMENTS, ADR index refs, and the ADR's own Consequences paragraph as a cross-check against its body; a bulk flip reports the FORMS covered (`| Designed |` table cells vs `(Designed — ADR-x)` prose).
- In-place amendment of migration SQL is acceptable only under a RECORDED "applied nowhere durable" premise re-confirmed with the owner.
  **Source (additions)**: 2026-09-01-05.40, 2026-07-18-13.35, 2026-07-16-22.26-workspace-reconciliation-review-fixes, 2026-07-16-16.05, 2026-07-17-00.10-workspace-lifecycle-review-remediation, 2026-07-15-11.19-gate-chat-recovery, 2026-07-24-15.19, 2026-08-06-19.10

### Tool authorities: what counts as build / binary / diagnostic evidence

**Source**: 2026-06-29-01.37, 2026-06-24-19.45, 2026-06-22-12.47, 2026-06-29-01.03
**Rule**: (1) Next.js 71007 "serializable props" warnings on `"use client"` files are LSP heuristics, distinct from real build failures — the only build authority is `pnpm build` (exit 0 + BUILD_ID generated); don't chase them as errors and don't accept them as evidence of breakage. (2) A fresh git worktree has no `node_modules` — a blizzard of "Cannot find module 'react'"/JSX-intrinsics diagnostics is pure env noise; run `pnpm install --frozen-lockfile` first, then trust real `tsc`/`eslint`/`vitest` over inline diagnostics. (3) Binary/NUL verification targets the WORKING TREE (`tr -cd '\000' < f | wc -c` or a python bytes count) — `git diff --stat` shows `Bin` when EITHER blob contains a NUL (HEAD still has it after the fix), and `grep -c $'\x00'` reads the pattern as EMPTY and counts every line (a false positive that looks like thousands of NULs). (4) For behavior-preserving refactors of a shared path, a characterization snapshot (byte-identical output before/after, e.g. the installed-source snapshot) is the cheapest non-regression proof — keep such snapshots.

(5) A script branching on a WRAPPER tool's exit code is trusted only after testing the wrapper's actual codes — docker compose FLATTENS 125/126/127 to exit 1 (env class = those codes OR a trailing `Error response from daemon:` marker). (6) Every Bash call `cd`s to the package dir explicitly — a bare `pnpm exec vitest` from the wrong cwd prints only "Command not found", which a summary grep hides. (7) `mcp/src` edits are inert until `pnpm --filter @maister/mcp build` — compare `mcp/dist` vs `src` mtimes. (8) After a rebase, grep consecutive duplicate statements (`awk 'prev==$0 && $0!=""{print FILENAME": "FNR": "$0}{prev=$0}'`) — two rebases duplicated an epoch mint. (9) A `pnpm typecheck` is mandatory on any branch that adds binary `readFile`/`writeFile` flows (TS 5.6 vs `@types/node@20.9.0` `Buffer`≠`Uint8Array`), and a new `node:*` builtin import is verified under the pinned Vite.
**Source (additions)**: 2026-08-01-09.09, 2026-09-02-03.51, 2026-07-18-13.35, 2026-09-04-00.21, 2026-07-12-11.21