/mz:verify

Verify that a phase achieved its GOAL by performing goal-backward verification against ROADMAP.md success criteria and PLAN.md must_haves. Spawns a verifier subagent via the Task tool that checks truths, artifacts (3-level), key links, and requirement coverage against the actual codebase. Produces VERIFICATION.md with results.

Note: This skill always works when invoked manually, regardless of the workflow.verifier config setting. The config toggle only controls whether /mz:go automatically suggests verification after execution.

Reference @skills/init/design-system.md for visual output formatting. Reference @skills/shared/presentation-standards.md for content formatting rules. Reference @skills/shared/terminology.md for official term definitions. Reference @skills/verify/verifier.md for verification protocol and spawning patterns.

Step 1: Display Banner

Output the stage banner:

+===============================================+
|  MEGAZORD > VERIFY                            |
+===============================================+

Step 2: Load Context and Validate

Read .planning/megazord.config.json. If missing, display error and stop:

## Error

Project not initialized — no megazord.config.json found.

`/mz:init`

If config exists, continue loading:

• Read .planning/STATE.md for current position.
• Read .planning/ROADMAP.md for phase details and success criteria.

Parse the user's message (text after /mz:verify) for arguments:

• {phase_num} -- verify a specific phase (optional, defaults to current)
• --partial -- verify even if some plans are incomplete (skip completion check)
• --milestone {version} -- run milestone audit mode instead of phase verification (see Step 3b)

Determine the plugin path for CLI commands:

1. Read plugin_path from the config JSON.
2. If plugin_path is not set in config, try ~/.claude/plugins/mz. Check if ~/.claude/plugins/mz/bin/megazord.mjs exists.
3. If neither exists, display error and stop:

## Error

Plugin path not configured.

`/mz:settings` to set plugin_path, or `/mz:init` to re-initialize.

Use this resolved path for all node {plugin_path}/bin/megazord.mjs commands below:

node {plugin_path}/bin/megazord.mjs tools plan incomplete --phase-dir {phase_dir}

Step 3: Determine Target Phase

• If phase number argument provided: use that phase.
• Otherwise: use current phase from STATE.md.
• Compute the phase directory path (e.g., .planning/phases/05-code-review-and-verification).
• Extract phase goal and success criteria from ROADMAP.md.
• If phase not found in ROADMAP.md, display error and stop:

## Error

Phase {N} not found in roadmap. Valid phases: {list}.

`/mz:status` to check current position.

Display:

> Target
  Phase {N}: {Name} — {functional_sentence_from_goal}

The goal is already inline in the functional sentence — no separate "Goal:" line needed.

Step 3b: Milestone Audit Mode (alternative path)

If --milestone {version} was provided, the skill enters milestone audit mode instead of the regular phase verification flow (Steps 4-7 are skipped).

Milestone Audit Flow

1. Display:

   > Milestone Audit: {version}
   

2. Determine which phases belong to this milestone:

   • Check if .planning/MILESTONE.md exists with the specified version. If found, read the phases list from it.
   • If no MILESTONE.md exists, treat all completed phases as the milestone scope. Scan ROADMAP.md for phases marked complete (- [x]) and collect their phase numbers.

3. Run the milestone audit via CLI tool:

   node {plugin_path}/bin/megazord.mjs tools milestone audit --phases "{comma-separated phase numbers}"
   

4. Parse the JSON audit result.

5. Display audit results:

   If all phases pass:

   +===============================================+
   |  Milestone {version} Audit: PASSED           |
   +-----------------------------------------------+
   |  Phases verified: {N}/{N}                     |
   |  All verification gates passed.               |
   +===============================================+
   

   Suggest: "Run /mz:plan to complete the milestone (archive and tag)."

   If some phases fail:

   +===============================================+
   |  Milestone {version} Audit: GAPS FOUND       |
   +-----------------------------------------------+
   |  Phases verified: {passed}/{total}            |
   |                                               |
   |  Failed:                                      |
   |  - Phase {N}: {Name} — {reason}              |
   |  - Phase {M}: {Name} — No VERIFICATION.md    |
   +===============================================+
   

   Suggest: "Run /mz:verify {N} for each failed phase."

6. Write MILESTONE-AUDIT.md in .planning/ with:

   • Version and date
   • Status: passed or gaps_found
   • Per-phase verification status (phase number, name, status, details)
   • Aggregate statistics (total phases, passed count, failed count)

7. Display Next Up block:

   If passed:

   ## Next Up
   
   **Milestone {version} audit passed.** Ready to archive.
   `/mz:lifecycle`
   
   <sub>`/clear` — start fresh context for the next step</sub>
   

   If gaps found:

   ## Next Up
   
   **Address gaps before closing milestone.**
   `/mz:verify {N}` for Phase {N}: {Name}
   
   <sub>`/clear` — start fresh context for the next step</sub>
   

8. Exit (do not proceed to regular phase verification).

If --milestone was NOT provided: Continue to Step 4 (regular phase verification flow).

Step 4: Check Plan Completion

node {plugin_path}/bin/megazord.mjs tools plan incomplete --phase-dir {phase_dir}

• If no plans found in the phase directory, display error and stop:

## Error

No plans found for Phase {N}: {Name}.

`/mz:plan {N}`

• If incomplete plans exist AND --partial was NOT provided: Display warning listing incomplete plans. Ask user whether to proceed with partial verification or wait:

  > Warning: Incomplete Plans
    The following plans have not been executed:
    - {plan_file_1}
    - {plan_file_2}
  
    Verification may report false gaps for artifacts in unexecuted plans.
    Proceed with partial verification? (yes/no)
    Or run with --partial to skip this check.
  

• If incomplete plans exist AND --partial was provided: proceed with a note:

  > Note: Partial verification (--partial). Skipping completion check.
  

• If all plans complete: proceed to verification.

Step 5: Spawn Verifier

1. Read all PLAN.md files in the phase directory (extract must_haves from frontmatter for each).
2. Read all SUMMARY.md files in the phase directory (extract key accomplishments, files, decisions).
3. Read {plugin_path}/agents/mz-verifier.md content using the Read tool.
4. Extract requirement IDs from the phase's ROADMAP.md entry.
5. Compose the Task prompt:

<agent_role>
{content of agents/mz-verifier.md}
</agent_role>

<phase_goal>
{Phase goal from ROADMAP.md}
</phase_goal>

<success_criteria>
{Success criteria list from ROADMAP.md, numbered}
</success_criteria>

<plans>
{For each PLAN.md: filename, must_haves section from frontmatter, requirements field}
</plans>

<summaries>
{For each SUMMARY.md: filename, key accomplishments section, key-files, key-decisions}
</summaries>

<requirements>
{Requirement IDs mapped to this phase with their descriptions from REQUIREMENTS.md}
</requirements>

<verification_rules>
- Phase: {phase_number}
- Phase directory: {phase_dir}
- Report path: {phase_dir}/{padded}-VERIFICATION.md
- Mode: hybrid (automated first, user confirmation for ambiguous)
- Criteria sources: ROADMAP.md success criteria + PLAN.md must_haves
</verification_rules>

6. Spawn via Task tool:

   • subagent_type: "general-purpose"
   • description: "Verify Phase {phase_number}: {phase name}"

7. Wait for completion.

8. Parse the structured result (look for ## VERIFICATION COMPLETE).

Note: All file contents are read BEFORE spawning the Task subagent and embedded as inline text. @file references do NOT work across Task boundaries. This is the same pattern used by /mz:go for executor spawning (see skills/go/executor.md).

Step 6: Handle Result

Parse the verification status from the structured result:

Status: passed

All truths verified, all artifacts exist and are wired, all requirements covered.

Display the strong phase completion banner first:

═══════════════════════════════════════════════════

### Phase {N}: {Name} — Complete

{Brief recap: what this phase delivered, 1-2 sentences}

═══════════════════════════════════════════════════

Then display verification stats:

+===============================================+
|  Phase {N}: {Name} — Verification: PASSED    |
+===============================================+
|  Truths: {N}/{N} passed                      |
|  Artifacts: {N}/{N} verified                 |
|  Key Links: {N}/{N} wired                    |
|  Requirements: {N}/{N} covered               |
+===============================================+

Suggest advancing to next phase.

Status: gaps_found

Some truths failed, artifacts missing, or requirements uncovered.

Display gaps clearly with details from VERIFICATION.md:

+===============================================+
|  Phase {N}: {Name} — Verification: GAPS FOUND|
+===============================================+
|  Truths: {passed}/{total} ({failed} failed)  |
|  Artifacts: {passed}/{total}                 |
|  Key Links: {wired}/{total}                  |
|  Requirements: {covered}/{total}             |
+===============================================+

Then display each gap:

> Gaps

1. [FAILED] {truth/artifact/link description}
   Evidence: {what was checked}
   Expected: {what should exist}

Suggest running /mz:go to address gaps or re-planning. Do NOT auto-advance the phase.

Status: human_needed

Some items need user confirmation.

Display the automated results (passed/failed items) first. Then present each UNCERTAIN item to the user one at a time:

> Human Verification Needed

1. {uncertain truth/artifact description}
   Evidence checked: {what was verified}
   Question: Does this satisfy the criteria? (yes/no/partial)

Collect user responses. Update the overall status based on responses:

• All "yes": upgrade to passed (or gaps_found if other items failed)
• Any "no": mark as failed, overall status becomes gaps_found
• Any "partial": mark as warning, note in report

Re-write VERIFICATION.md with user confirmations included.

Step 7: Post-Verification Summary

Display Next Up block:

If passed:

## Next Up

**Plan Phase {N+1}: {NextName}** — {functional_sentence_of_next_phase}
`/mz:plan {N+1}`

<sub>`/clear` — start fresh context for the next step</sub>

If gaps_found:

## Next Up

**Address gaps in Phase {N}: {Name}** — fix issues, then re-verify
`/mz:go`

- Re-verify after fixes: `/mz:verify {N}`

<sub>`/clear` — start fresh context for the next step</sub>

If human_needed (after user confirms all): Update and proceed as passed or gaps_found based on user responses.

Error Handling

Error	Step	Action
Config missing	Step 2	Error box, suggest /mz:init. Stop.
ROADMAP.md missing	Step 2	Error box, suggest /mz:plan. Stop.
Phase not found in ROADMAP	Step 3	Error message with valid phase numbers. Stop.
No plans in phase	Step 4	Error message, suggest /mz:plan. Stop.
Verifier subagent fails	Step 5	Save error, display failure details. Stop.

Notes

• All file contents are read BEFORE spawning Task subagents and embedded as inline text. @file references do NOT work across Task boundaries.
• The verifier agent ({plugin_path}/agents/mz-verifier.md) performs all verification logic. This skill orchestrates: load context, check completion, spawn verifier, handle result.
• Only the orchestrator (this skill) presents UNCERTAIN items to the user in hybrid mode. The verifier identifies them; this skill manages the user interaction.
• The verifier does NOT update STATE.md or ROADMAP.md. State updates happen at the orchestrator level (e.g., /mz:go after phase completion).
• ALWAYS use bun/bunx for JavaScript/TypeScript operations (never npm/npx).
• The {plugin_path} for CLI commands and agent files is resolved from config.plugin_path, falling back to ~/.claude/plugins/mz.