Verification

CONCEPT · EVIDENCE, NOT CLAIMS

Verification is the evidence that the intended behavior works and that the constraints still hold. In Maverick it is a set of gates: commands that read the code and the diff, never the agent's summary, and that each write a report next to the task.

Why it matters

An agent that says "all tests pass" is making a claim. A green command alone may not prove the requested outcome either: tests can be skipped, weakened or simply not cover the new behavior. Verification asks three separate questions, and a change has to answer all of them:

Question	Gate	Report
Do the checks pass?	`maverick verify` runs the detected lint, typecheck, test and build commands	`EVIDENCE.md` with every command and exit code
Did it change only what the plan said?	`maverick guard` compares the diff with TECHSPEC File References and the task Files, and checks the change budget	`SCOPE-GUARD.md`
Is it safe?	`maverick security` scans the diff for private keys, secret assignments and unsafe dynamic execution	`SECURITY-REPORT.md`
What came in?	`maverick deps` lists changed manifests and lockfiles across ecosystems	`DEPENDENCY-REVIEW.md`

Try it: run the gates

Pick what the agent changed. Notice that the tests can pass while other gates still warn, and that the gates react to the diff itself.

DECLARED SCOPE · TECHSPEC + TASK FILES

src/orders/orders.controller.ts
src/orders/orders.service.ts
src/orders/dto/list-orders.dto.ts
test/orders.e2e-spec.ts

THE DIFF

src/orders/orders.controller.ts
src/orders/orders.service.ts
src/orders/dto/list-orders.dto.ts
test/orders.e2e-spec.ts
src/common/date-utils.tsa drive-by refactor
package.jsona new dependency
package-lock.jsonits lockfile
.env.examplea sensitive-looking path

Tests pass Diff adds apiKey = "sk_live_…"

PASSmaverick verify

EVIDENCE.md

PASS npm test · exit 0
PASS npm run lint · exit 0
PASS npx tsc --noEmit · exit 0

PASSmaverick guard

SCOPE-GUARD.md

Changed 4 · expected 4 · budget 8

PASSmaverick security

SECURITY-REPORT.md

No high-signal patterns found in the current diff.

PASSmaverick deps

DEPENDENCY-REVIEW.md

Manifests: none
Lockfiles: none

PASSmaverick review --diff

REVIEW-FINDINGS.md

Blast radius listed for 4 file(s)

Where the commands come from

maverick verify does not guess. It detects your stack (maverick stack) and picks commands per check kind, lint, typecheck, test and build, from the project's own runners: npm scripts, a Makefile, pyproject.toml, go.mod, Cargo.toml and others, per subproject in a monorepo. When detection is not enough, declare them:

json

{
  "verification": {
    "commands": [
      "npm run lint",
      { "name": "e2e", "command": "npm run test:e2e", "cwd": "apps/api" }
    ]
  }
}

With no detected or declared command, verify fails instead of passing silently.

What evidence looks like

# Verification Evidence — add-cursor-pagination-orders-endpoint

Generated: 2026-10-05T14:02:11.420Z

## PASS — npm run lint
Exit code: 0

## PASS — npx tsc --noEmit
Exit code: 0

## FAIL — npm test
Exit code: 1
  ✕ orders › returns 400 for an invalid cursor (12 ms)

Evidence is a file, not a chat message, so it survives the session, is attached to the PR draft and is checked by maverick readiness.

Verification during the build

Verification is not one step at the end. The maverick-build skill verifies every subtask before marking it done:

Take the next ready subtask
maverick subtask next <task> shows the ones whose dependencies are done; the skill marks one in progress.
Work through its checklist
Each Step, test and criterion in task_NN.md is checked as it is done.
Run its Verification
The tests named in the task, then maverick verify for the whole stack.
Mark it done, then ask
subtask set … done refuses while an item is unchecked. The skill asks you before the next subtask.

When checks fail, the bounded fix-checks flow lets an agent iterate on lint, typecheck and test failures, up to five times, and stops early when two iterations make no progress:

bash

maverick flow run fix-checks add-cursor-pagination-orders-endpoint --agent claude-code

Checks of the checks

Passing checks are necessary, not sufficient. Three checks ask whether the checks themselves can be trusted:

Integrity (maverick integrity): did the change make a check weaker? Deleted, skipped or looser tests, silenced lint, edited check configuration.
Ablation (maverick ablation): can the new tests fail at all? Each new or changed test file runs with the change, where it must pass, and on the code before it with only the new tests on top, where it must fail. A test that passes both ways is vacuous-test. A regression guard named in the TECHSPEC Test Plan is meant to pass both ways.
Structure (maverick structure, the architecture gate): did the change make the import graph worse? A new cycle, a new import the boundary rules forbid, or a health drop beyond architecture.maxHealthDrop fails it, unless the TECHSPEC declares the edge under ## Architecture.

The ship flow runs ablation and structure as warnings; the built-in loop flow blocks on structure, so no iteration can add a cycle. For the strongest evidence, add sealed tests: checks the agent never sees.

Strict work

The strict workflow, chosen for security, data, payments, migrations and shared infrastructure, adds a SECURITY stage before review, requires EVIDENCE.md before review --diff is clean, and requires a CHECKPOINT.md (git status and diff, saved with maverick checkpoint) before merge readiness.

Common mistakes

Weakening tests to make a generated change pass. Deleting an assertion, adding .skip, or loosening a matcher. The review checklist asks about it explicitly.
Trusting the agent's summary. Read EVIDENCE.md, not the message that says it passed.
Only running the happy path. If AC-02 is "invalid cursor returns 400", a test must send an invalid cursor.
Starting without a git baseline. If git tracks nothing, the diff cannot separate the task from the project, and guard and review --diff say so.
Silencing guard. An out-of-scope file is either a missing plan update or a drive-by change. Decide which.

Checklist

[ ] Every acceptance criterion has a test that exercises it, including edge cases
[ ] maverick verify passes and EVIDENCE.md is current
[ ] maverick guard findings are explained or fixed
[ ] maverick security signals were read by a person
[ ] New dependencies in DEPENDENCY-REVIEW.md are necessary and maintained
[ ] No test was weakened, skipped or deleted to pass (maverick integrity <task> checks this from the diff)

Commands

Command	Does	Fails when
`maverick verify <task>`	Runs the detected checks, writes `EVIDENCE.md`	Any check fails, or none is detected
`maverick guard <task>`	Compares the diff with the declared scope	A file is outside scope, or the budget (default 8) is exceeded
`maverick integrity <task>`	Audits the diff for weakened checks: deleted, skipped or focused tests, fewer or looser assertions, silenced lint or types, edited check configuration or CI	A blocking finding is found (see Loop engineering)
`maverick security <task>`	Scans the diff for high-signal patterns	Any signal is found
`maverick deps <task>`	Lists changed manifests and lockfiles	Never: it is a report for the reviewer
`maverick policy check <task>`	Applies `.maverick/policy.json` (max files, sensitive paths)	A rule is broken
`maverick flow run ship <task>`	Runs every gate in order as one contract	A blocking gate fails

Review →Take the evidence to a human decision.The workflowBuild, verify and review, end to end.

Verification ​

Why it matters ​

Try it: run the gates ​

Where the commands come from ​

What evidence looks like ​

Verification during the build ​

Take the next ready subtask

Work through its checklist

Run its Verification

Mark it done, then ask

Checks of the checks ​

Strict work ​

Common mistakes ​

Checklist ​

Commands ​

Next ​