maestro-verify

name	maestro-verify
description	Verify and close - cross-check coverage, run the VERIFY table, deliver the verdict, harvest durable lessons into decisions, close the bundle, and never claim remote state from local evidence.
review-date	2026-11-28T00:00:00.000Z

maestro-verify

Use for close, commit, install, push, publish, release, or archive gates. Local implementation authority does not imply authority for remote or external state changes.

Evidence layers

Proof follows five links. Claim only as far as the last proven link.

• source - source-level tests, lint, type checks, or direct inspection.
• artifact - the built or packaged output is present and has been read back.
• installed - the installed stamp, version, or files match the intended artifact.
• live - the running process, pid, or active runtime matches the installed layer.
• journey - the real user path reaches the observable outcome end to end.

"Tests pass" is a source claim. A claim that touches install or runtime must include a readback at that layer. Every proof and VERIFY result lists untested links explicitly as NOT TESTED, never by omission:

proof: "suite 135 pass @ a52bd4a7 (source); runtime stamp readback a52bd4a7 (installed); live: NOT TESTED"
Assumptions not verified: None
Residual risks: None

Verify

• Cross-check coverage before running anything: every behavior in scope has a red test that went green, every red test maps to a VERIFY.md scenario or repo check, and every scenario traces back to a work item's acceptance or an anti-goal. An orphan on any side is a gap - record and surface it, never silently proceed past it.
• Run every VERIFY.md scenario against its work item's acceptance/claims and fill the Result column; run each anti-goal check (grep, diff, readback). The scenario list is frozen once the pass starts: scenarios gain results here, never rewrites or removals. A scenario that cannot run as written goes back to maestro-design for a checkable rewrite - do not invent a substitute measurement.
• For risky seams, spot-check assertion strength before filling PASS. First check the tests assert the decided contract itself: the decided error class, and the message when one was decided - a bare toThrow() passes on any thrown value, and a substring matcher like toThrow(string) passes on a changed message; a decided contract no assertion pins is a FAIL. Then derive mutants from the record, not at random: bend the code toward each alternative the linked decisions rejected - the suite must go red each time, and a survivor is a weak or missing test and a FAIL of that scenario, not a side note. Last, probe each input edge no decision settled (whitespace, case, sign, empty) by mutating the code (e.g. insert an input.trim()), never by only calling the function - a call shows current behavior, a surviving mutant shows no test pins it; a suite that stays green under an edge mutant is an open fork to record, not a pass. Restore after each mutant.
• Re-read the user's exact delivery authority and target before any gate.
• Select one legal next gate at a time: final verification, independent QA or witness, scoped commit, local install, external delivery, or stop. Do not bundle gates whose authority differs.
• Read back the actual result: test output, commit hash, installed version. A started or interrupted command is not delivery evidence.

For substantial diffs, verify in a fresh context: dispatch a subagent that reads only the bundle and the diff - the implementer verifying their own work invites confirmation bias. The subagent never fixes anything: mutants it flips are reverted before reporting, and on FAIL it records the verdict and stops; routing back to implementation belongs to the parent turn that holds the user's ask.

On FAIL, route back to maestro-work and leave the exact one-line failed-pass trace maestro work note <id> "failed: <one line>". The prefix is the literal lowercase failed: followed by one space. A scenario still failing after three implement passes - counted from the work item's notes across sessions, not this session's memory - is a design problem, not an implementation one: stop and re-settle the decision via maestro-design.

Read-only review method: references/audit.md. When the failure location is unclear, follow references/triage.md.

Red flags

The thought	The reality
"It obviously passes - running it is a formality"	Scenarios exist because "obviously" has been wrong before. Run every one and record the output.
"The scenario can't run as written, but this similar check proves the same thing"	That is a substitute measurement. Route back to maestro-design for a checkable rewrite.
"The mutant survived, but the code is clearly fine"	A surviving mutant is a weak or missing test, and a FAIL of that scenario.
"I wrote this diff - I know it works"	That is the confirmation bias the fresh-context rule exists for.
"I'll just fix this small failure while I'm verifying"	Verify delivers a verdict, never fixes. A FAIL routes back to maestro-work.

Learn, then close

Before closing, harvest what outlives the bundle (references/learning.md): a verified correction or durable constraint becomes a locked decision or a work note - never only chat.

maestro bundle close <id>    # snapshots the trio into the store, archives it

The snapshot is the durable memory; after close the directory is disposable and maestro search still recalls the text.

Definition of done

Acceptance met, changed surface verified, available test/lint/type/build checks pass, claims name their falsifier, risky changes carry rollback notes. Never claim push, release, or publish from local state; those gates are the user's.