Verifying changes

Build finished. You're about to run ana run verify. This guide covers what Verify does, what the report means, and what to do when it comes back FAIL.

#What Verify does

Verify reads the spec and the code — never the build report. Eight steps:

1. Seal check — confirms the contract wasn't modified after sealing
2. Run tests, build, lint — establishes the baseline
3. Predict — writes predictions before reading code, to resist confirmation bias
4. Read code and evaluate assertions — finds each @ana tag, verifies the test actually satisfies the contract
5. Check for over-building — flags code not in the spec
6. Resolve predictions — confirmed, not found, or surprised
7. Walk acceptance criteria — each one gets PASS, FAIL, PARTIAL, or UNVERIFIABLE
8. Write findings and verdict — PASS or FAIL, one word

Before evaluating assertions, Verify runs ana proof context on the changed files — surfacing prior findings, the verified work items that shaped each file, and its co-change partners — so the review is oriented by history, not just the diff at HEAD.

#The asymmetry

Both agents read the same planning artifacts and project config. The difference is one file: build_report.md. Only the developer sees both reports.

# ana-build reads:
- spec.md           # how to build it
- contract.yaml     # what done means (sealed)
- plan.md           # sequencing and phasing
- ana.json          # build/test/lint commands
- scan.json         # stack awareness
- the codebase      # current state

# ana-verify reads:
- spec.md           # same
- contract.yaml     # same
- plan.md           # same
- ana.json          # same
- scan.json         # same
- the codebase      # the diff at HEAD
- ❌ build_report.md  # forbidden

#The verify report

Verify produces two files: a markdown report for the developer and a YAML companion (verify_data.yaml) for the proof chain. The report's key section is Contract Compliance — a per-assertion ledger:

## Contract Compliance

| ID   | Says                                        | Status        | Evidence                          |
|------|---------------------------------------------|---------------|-----------------------------------|
| A001 | Slugs with shell injection are rejected     | ✅ SATISFIED | test line 42, rejects "; rm -rf"  |
| A003 | Valid kebab-case slugs pass validation      | ✅ SATISFIED | test line 58, passes "my-feature" |
| A023 | No direct execSync calls remain in commands | ✅ SATISFIED | grep confirms zero matches        |

After the ledger: Findings (categorized observations with severity and suggested actions — these enter the proof chain), AC Walkthrough (each acceptance criterion: PASS, FAIL, PARTIAL, or UNVERIFIABLE), Blockers, Deployer Handoff, and the Verdict. On re-verification, a Previous Findings Resolution section shows how each prior issue was addressed.

The AC Walkthrough is anchored by the coverage map (ana plan coverage <slug>), which links each acceptance criterion to the assertions that claim to cover it. This makes "every assertion passed" and "intent was met" two separate gates — a contract can satisfy every assertion and still leave an acceptance criterion uncovered.

#PASS and FAIL

Findings measure depth of review. The verdict measures contract compliance. They're independent.

The headline verdict isn't taken on the model's word. It's cross-checked against the Contract Compliance ledger — a PASS that contradicts an UNSATISFIED row is automatically coerced to FAIL, so the one-word verdict can't drift from the per-assertion evidence.

#When Verify fails

FAIL sends the work back to Build. 26 of Anatomia's own 213 proofs had rejection cycles.

1. Read the verify report. It lists every UNSATISFIED assertion and every finding.
2. Run ana run build. Build reads the verify report and fixes exactly what failed.
3. Run ana run verify again. On re-verification, Verify reads its own previous report and addresses each prior issue explicitly in a Previous Findings Resolution section.

Re-verification is a full pass. Every assertion is re-evaluated. The previous report provides a checklist, not a shortcut.

If the failure isn't obvious from the report, see Troubleshooting.

#Running verify

Verify runs in the worktree Build created — no branch switching or setup needed.

# After Build finishes, open a new session:
$ ana run verify

# Verify finds the work item, enters the worktree,
# runs the 8-step process, writes the report.
# On PASS, it creates a PR for review.

Under the hood: ana work status → ana work start → ana verify pre-check → verification → ana artifact save verify-report → ana pr create. The save runs the seal check again — tampered contracts are blocked.

After the PR is created: read both reports, merge, then ana work complete to archive and record the proof chain entry.

#Comparing the two reports

After PASS, you have build_report.md and verify_report.md. Read both before merging. Where to look:

• Assertion status. Build claims 27/27 SATISFIED. Verify also says 27/27. If they disagree — Build says SATISFIED but Verify says UNSATISFIED — that's the highest-value signal. Read both evidence columns.
• Test quality. Build reports test counts. Verify reports whether those tests actually prove anything. A test tagged @ana A003 that uses toBeDefined() passes on both correct and incorrect implementations — Verify catches that.
• Open issues vs findings. Build's "Open Issues" are honest admissions. Verify's "Findings" are independent observations. Overlap means the issue is real. A finding that Build didn't mention means Build missed something.
• Over-building. Verify flags code that exists but wasn't in the spec. Build's report won't mention it because Build wrote it intentionally. The gap itself is the signal.
• Sealed test evidence. Both reports carry a compact, SHA-sealed marker from ana test — Build seals --stage build, Verify seals --stage verify (the full project). The captured counts should agree; a divergence between the two sealed markers is worth reading.