maestro-verify
Use for verification and close. Read WORKFLOW.md for testing, recovery, authorization, and completion rules. Delivery actions such as commit, install, push, or release remain separate gates.
Precondition: an open bundle with a drafted VERIFY.md. Without a bundle,
verify inline and close a tracked item with maestro work done; an untracked
quickfix needs no record. This skill's table pass is for Full work. The
evidence-layer vocabulary below still applies to any claim at any tier.
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. A suite that is green only on this machine
is not a source claim about the repo: before any commit, release, or handback
gate, re-run the touched suite with the developer environment removed
(HOME=$(mktemp -d), env -u HERDR_ENV). A test that reads the installed
copy, the room, or a home config passes for you and fails in CI. Every proof
and VERIFY result lists untested links explicitly as NOT TESTED, never by
omission:
textproof: "suite 135 pass @ a52bd4a7 (source); runtime stamp readback a52bd4a7 (installed); live: NOT TESTED" Assumptions not verified: None Residual risks: None
Verify
- Cross-check the evidence plan against acceptance and relevant risks. Map existing tests, necessary new checks, readbacks, or baselines to VERIFY.md. A missing behavior check is a gap; the absence of a newly written test is not.
- 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).
Stamp the pass with its date and commit. Results hold this run only: a
re-run replaces prior results wholesale, and a failed pass leaves its
one-line
failed:note on the work item, never accumulated rounds in VERIFY.md. Apply Recovery and verification when a scenario cannot run as written: document and execute an equivalent check without changing acceptance, or report the gap if equivalence is unknown. - Run the repo's checks for the touched surface (tests, lint, types, build), then freeze and review the task-owned diff: every changed line traces to the SPEC's scope or a linked work item; nothing unrelated is staged.
- For a concrete assertion-strength concern, inspect whether the existing check distinguishes the approved outcome from the suspected wrong behavior. A focused mutation can establish that; restore it before continuing. Do not expand verification into an unrelated edge-case or coverage campaign.
- 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. A subagent that fails to start or report is a dispatch failure, not evidence: run the checklist in this session instead of polling for it.
On FAIL, leave maestro work note <id> "failed: <one line>" and return the
evidence to the implementation owner. Use the shared recovery rule to choose
the next action from the cause, not a failure count. Read prior failed notes
so a new session does not repeat the same uninformative attempt.
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 command is stale, so I can skip the check" | Repair it or demonstrate an equivalent measurement; preserve acceptance and record the change. |
| "The mutant survived, but the code is clearly fine" | If the mutant violates acceptance, the check is weak; report the gap rather than filling PASS. |
| "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.
Use Completion and delivery to decide whether the accepted scope is complete or an authorized transfer is ready. Close procedure:
- Run
maestro handoff <bundle-id>one last time, then add a dated close-out line citing verification evidence and the candidate (base commit plus task-owned diff if uncommitted), or the explicit handoff/cancellation. Record pending delivery actions and retained authority in the handoff. - Harvest: any mid-flight choice that is hard to reverse, surprising without
context, and a real trade-off is a locked decision with its rejected
alternative; a new domain term is
maestro term add. maestro bundle close <id>: snapshots the trio into the store and archives the directory.
The snapshot is the durable memory; after close the directory is disposable
and maestro search still recalls the text.
If acceptance includes delivery not yet authorized or proven, leave the work open with that exact next action and blocker. Otherwise a verified implementation may close without a commit. Do not mark failed acceptance complete; an explicit transfer or cancellation records the unresolved failure rather than calling it PASS. Never stage or commit bundle contents.
Use the shared review routing. A code change after the verdict reruns the affected VERIFY.md scenarios before close; the old verdict does not cover the new diff.
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.
