<purpose>
Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
</purpose>

<required_reading>
Read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>

<process>

## 0. Mode-Aware Path Resolution (Phase 66-04 CMD-05)

Resolve organizational_mode + active_milestone_slug ONCE at workflow start, then route all mode-variant `.planning/` path lookups through `resolveMilestonePaths(mode, slug, artifact)`. Sequential mode resolves to root `.planning/` paths (byte-identical to pre-v1.5.9). Parallel mode routes to `.planning/milestones/<slug>/`. Project-level paths (PROJECT.md, MILESTONES.md, config.json) stay literal per Phase 65 Decision O6-lean.

```bash
INIT=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" init milestone-op --raw)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

MODE=$(echo "$INIT" | jq -r '.organizational_mode // "sequential"')
SLUG=$(echo "$INIT" | jq -r '.active_milestone_slug // empty')

REQS_PATH=$(node -e "const {resolveMilestonePaths}=require('$HOME/.claude/get-magic-done/bin/lib/path-resolve.js'); console.log(resolveMilestonePaths('$MODE', '$SLUG' || null, 'REQUIREMENTS'))")
ROADMAP_PATH=$(node -e "const {resolveMilestonePaths}=require('$HOME/.claude/get-magic-done/bin/lib/path-resolve.js'); console.log(resolveMilestonePaths('$MODE', '$SLUG' || null, 'ROADMAP'))")
STATE_PATH=$(node -e "const {resolveMilestonePaths}=require('$HOME/.claude/get-magic-done/bin/lib/path-resolve.js'); console.log(resolveMilestonePaths('$MODE', '$SLUG' || null, 'STATE'))")
PHASES_DIR=$(node -e "const {resolveMilestonePaths}=require('$HOME/.claude/get-magic-done/bin/lib/path-resolve.js'); console.log(resolveMilestonePaths('$MODE', '$SLUG' || null, 'phases-dir'))")
```

If `MODE == "parallel"` and `INIT.active_milestone_needs_prompt == true`: prompt via AskUserQuestion using `INIT.active_milestone_candidates`; write selection via `node bin/gmd-tools.cjs state set-current-milestone <slug>` then re-run Step 0.

## 0.5. Initialize Milestone Context

```bash
# Init already loaded in Step 0 above.
```

Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.

Resolve integration checker model:
```bash
integration_checker_model=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" resolve-model gmd-integration-checker --complexity complex --raw)
```

## 1. Determine Milestone Scope

```bash
# Get phases in milestone (sorted numerically, handles decimals)
node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" phases list
```

- Parse version from arguments or detect current from ROADMAP.md
- Identify all phase directories in scope
- Extract milestone definition of done from ROADMAP.md
- Extract requirements mapped to this milestone from REQUIREMENTS.md

## 2. Read All Phase Verifications

For each phase directory, read the VERIFICATION.md:

```bash
# For each phase, use find-phase to resolve the directory (handles archived phases)
PHASE_INFO=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" find-phase 01 --raw)
# Extract directory from JSON, then read VERIFICATION.md from that directory
# Repeat for each phase number from ROADMAP.md
```

From each VERIFICATION.md, extract:
- **Status:** passed | gaps_found
- **Critical gaps:** (if any — these are blockers)
- **Non-critical gaps:** tech debt, deferred items, warnings
- **Anti-patterns found:** TODOs, stubs, placeholders
- **Requirements coverage:** which requirements satisfied/blocked

If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.

## 3. Spawn Integration Checker

**3a. Determine milestone shape (skip-gate for non-full-milestone shapes).**

Resolve the milestone shape in this order:
1. `--shape=<value>` flag in `$ARGUMENTS` (e.g., `--shape=foundation-cleanup`)
2. `workflow.milestone_shape` in `.planning/config.json`
3. Default: `full-milestone`

```bash
SHAPE_FLAG=$(echo "$ARGUMENTS" | grep -oE '--shape=[a-z-]+' | sed 's/--shape=//')
if [ -n "$SHAPE_FLAG" ]; then
  MILESTONE_SHAPE="$SHAPE_FLAG"
else
  MILESTONE_SHAPE=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" config get workflow.milestone_shape --raw 2>/dev/null || echo "full-milestone")
  [ -z "$MILESTONE_SHAPE" ] && MILESTONE_SHAPE="full-milestone"
fi
```

Recognized shapes:
- `full-milestone` — primary feature work; cross-phase wiring is novel; integration checker runs.
- `foundation-cleanup` — refactor/extract/cleanup work; phase changes are file-isolated; integration is provable from the closure-script sweep + `bin/lib/mirror-check.js`. Integration checker is **skipped**.
- `hf` — hotfix milestone; one or two narrowly-scoped phases; integration risk is bounded by the closure script. Integration checker is **skipped**.

If `$MILESTONE_SHAPE` is `foundation-cleanup` or `hf`:

```
Skipping integration-checker dispatch.
Reason: milestone shape '{MILESTONE_SHAPE}' relies on the closure-script
zero-regression sweep + mirror-check.js for cross-phase wiring proof. Add
shape='full-milestone' to config or pass --shape=full-milestone to override.
```

Record the skip in the audit YAML (`integration_checker_skipped: true` with `reason: shape={MILESTONE_SHAPE}`) and proceed to step 4.

**3b. Dispatch (full-milestone shapes only).**

With phase context collected:

Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-IDs assigned to phases in this milestone.

```
Task(
  prompt="Check cross-phase integration and E2E flows.

Phases: {phase_dirs}
Phase exports: {from SUMMARYs}
API routes: {routes created}

Milestone Requirements:
{MILESTONE_REQ_IDS — list each REQ-ID with description and assigned phase}

MUST map each integration finding to affected requirement IDs where applicable.

Verify cross-phase wiring and E2E user flows.",
  subagent_type="gmd-integration-checker",
  model="{integration_checker_model}"
)
```

## 4. Collect Results

Combine:
- Phase-level gaps and tech debt (from step 2)
- Integration checker's report (wiring gaps, broken flows)

## 5. Check Requirements Coverage (3-Source Cross-Reference)

MUST cross-reference three independent sources for each requirement:

### 5a. Parse REQUIREMENTS.md Traceability Table

Extract all REQ-IDs mapped to milestone phases from the traceability table:
- Requirement ID, description, assigned phase, current status, checked-off state (`[x]` vs `[ ]`)

### 5b. Parse Phase VERIFICATION.md Requirements Tables

For each phase's VERIFICATION.md, extract the expanded requirements table:
- Requirement | Source Plan | Description | Status | Evidence
- Map each entry back to its REQ-ID

### 5c. Extract SUMMARY.md Frontmatter Cross-Check

For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
```bash
for summary in ${PHASES_DIR}/*-*/*-SUMMARY.md; do
  node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
done
```

### 5d. Status Determination Matrix

For each REQ-ID, determine status using all three sources:

| VERIFICATION.md Status | SUMMARY Frontmatter | REQUIREMENTS.md | → Final Status |
|------------------------|---------------------|-----------------|----------------|
| passed                 | listed              | `[x]`           | **satisfied**  |
| passed                 | listed              | `[ ]`           | **satisfied** (update checkbox) |
| passed                 | missing             | any             | **partial** (verify manually) |
| gaps_found             | any                 | any             | **unsatisfied** |
| missing                | listed              | any             | **partial** (verification gap) |
| missing                | missing             | any             | **unsatisfied** |

### 5e. FAIL Gate and Orphan Detection

**REQUIRED:** Any `unsatisfied` requirement MUST force `gaps_found` status on the milestone audit.

**Orphan detection:** Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.

## 5.5. Nyquist Compliance Discovery

Skip if `workflow.nyquist_validation` is explicitly `false` (absent = enabled).

```bash
NYQUIST_CONFIG=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" config get workflow.nyquist_validation --raw 2>/dev/null)
```

If `false`: skip entirely.

For each phase directory, check `*-VALIDATION.md`. If exists, parse frontmatter (`nyquist_compliant`, `wave_0_complete`).

Classify per phase:

| Status | Condition |
|--------|-----------|
| COMPLIANT | `nyquist_compliant: true` and all tasks green |
| PARTIAL | VALIDATION.md exists, `nyquist_compliant: false` or red/pending |
| MISSING | No VALIDATION.md |

Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`

Discovery only — never auto-calls `/gmd:validate-phase`.

## 6. Aggregate into v{version}-MILESTONE-AUDIT.md

Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with (Phase 66-04 CMD-05 decision: audit artifacts STAY at `.planning/` root in both modes — mirror Phase 65 v1.5.8-MILESTONE-AUDIT.md convention; milestone-shipped historical record, project-level by precedent):

```yaml
---
milestone: {version}
audited: {timestamp}
status: passed | gaps_found | tech_debt
scores:
  requirements: N/M
  phases: N/M
  integration: N/M
  flows: N/M
gaps:  # Critical blockers
  requirements:
    - id: "{REQ-ID}"
      status: "unsatisfied | partial | orphaned"
      phase: "{assigned phase}"
      claimed_by_plans: ["{plan files that reference this requirement}"]
      completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
      verification_status: "passed | gaps_found | missing | orphaned"
      evidence: "{specific evidence or lack thereof}"
  integration: [...]
  flows: [...]
tech_debt:  # Non-critical, deferred
  - phase: 01-auth
    items:
      - "TODO: add rate limiting"
      - "Warning: no password strength validation"
  - phase: 03-dashboard
    items:
      - "Deferred: mobile responsive layout"
---
```

Plus full markdown report with tables for requirements, phases, integration, tech debt.

**Status values:**
- `passed` — all requirements met, no critical gaps, minimal tech debt
- `gaps_found` — critical blockers exist
- `tech_debt` — no blockers but accumulated deferred items need review

## 7. Structured Output for complete-milestone Consumption

When audit-milestone is dispatched by complete-milestone (mandatory audit gate), the audit results MUST include a parseable per-requirement status block that complete-milestone can consume for traceability updates.

**Required output format** (included in the MILESTONE-AUDIT.md and returned to caller):

```
## Per-Requirement Status

| REQ-ID | Description | Phase | Status | Evidence |
|--------|-------------|-------|--------|----------|
| {ID} | {text} | {phase} | verified | {VERIFICATION.md reference} |
| {ID} | {text} | {phase} | gaps_found | {gap description} |
| {ID} | {text} | {phase} | not_checked | {reason} |
```

**Status values for each requirement:**
- `verified` — 3-source cross-reference confirms satisfied (VERIFICATION + SUMMARY + traceability)
- `gaps_found` — any source reports gaps or requirement is unsatisfied
- `not_checked` — requirement not covered by any phase verification

**REQUIREMENTS.md traceability cross-reference:** The audit agent MUST read `${REQS_PATH}` (resolved at Step 0; sequential = `.planning/REQUIREMENTS.md`, parallel = `.planning/milestones/<slug>/REQUIREMENTS.md`) traceability table and cross-reference each requirement ID with:
1. Phase VERIFICATION.md files (pass/fail status per requirement)
2. Phase SUMMARY.md frontmatter (`requirements_completed` field)
3. REQUIREMENTS.md checkbox state (`[x]` vs `[ ]`)

This cross-reference is the authoritative input for complete-milestone's traceability status update step.

**Integration checker wiring:** The gmd-integration-checker dispatch (Section 3) MUST verify:
- All phase VERIFICATION.md files for pass/fail status
- Cross-phase integration (imports, exports, wiring between phases)
- Requirement coverage (each requirement has at least one verification)

## 8. Present Results

Route by status (see `<offer_next>`).

</process>

<offer_next>
Output this markdown directly (not as a code block). Route based on status:

---

**If passed:**

## ✓ Milestone {version} — Audit Passed

**Score:** {N}/{M} requirements satisfied
**Report:** .planning/v{version}-MILESTONE-AUDIT.md

All requirements covered. Cross-phase integration verified. E2E flows complete.

───────────────────────────────────────────────────────────────

## ▶ Next Up

**Complete milestone** — archive and tag

/gmd:complete-milestone {version}

<sub>/clear first → fresh context window</sub>

───────────────────────────────────────────────────────────────

---

**If gaps_found:**

## ⚠ Milestone {version} — Gaps Found

**Score:** {N}/{M} requirements satisfied
**Report:** .planning/v{version}-MILESTONE-AUDIT.md

### Unsatisfied Requirements

{For each unsatisfied requirement:}
- **{REQ-ID}: {description}** (Phase {X})
  - {reason}

### Cross-Phase Issues

{For each integration gap:}
- **{from} → {to}:** {issue}

### Broken Flows

{For each flow gap:}
- **{flow name}:** breaks at {step}

### Nyquist Coverage

| Phase | VALIDATION.md | Compliant | Action |
|-------|---------------|-----------|--------|
| {phase} | exists/missing | true/false/partial | `/gmd:validate-phase {N}` |

Phases needing validation: run `/gmd:validate-phase {N}` for each flagged phase.

───────────────────────────────────────────────────────────────

## ▶ Next Up

**Plan gap closure** — create phases to complete milestone

/gmd:plan-milestone-gaps

<sub>/clear first → fresh context window</sub>

───────────────────────────────────────────────────────────────

**Also available:**
- cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
- /gmd:complete-milestone {version} — proceed anyway (accept tech debt)

───────────────────────────────────────────────────────────────

---

**If tech_debt (no blockers but accumulated debt):**

## ⚡ Milestone {version} — Tech Debt Review

**Score:** {N}/{M} requirements satisfied
**Report:** .planning/v{version}-MILESTONE-AUDIT.md

All requirements met. No critical blockers. Accumulated tech debt needs review.

### Tech Debt by Phase

{For each phase with debt:}
**Phase {X}: {name}**
- {item 1}
- {item 2}

### Total: {N} items across {M} phases

───────────────────────────────────────────────────────────────

## ▶ Options

**A. Complete milestone** — accept debt, track in backlog

/gmd:complete-milestone {version}

**B. Plan cleanup phase** — address debt before completing

/gmd:plan-milestone-gaps

<sub>/clear first → fresh context window</sub>

───────────────────────────────────────────────────────────────
</offer_next>

<success_criteria>
- [ ] Milestone scope identified
- [ ] All phase VERIFICATION.md files read
- [ ] SUMMARY.md `requirements-completed` frontmatter extracted for each phase
- [ ] REQUIREMENTS.md traceability table parsed for all milestone REQ-IDs
- [ ] 3-source cross-reference completed (VERIFICATION + SUMMARY + traceability)
- [ ] Orphaned requirements detected (in traceability but absent from all VERIFICATIONs)
- [ ] Tech debt and deferred gaps aggregated
- [ ] Integration checker spawned with milestone requirement IDs
- [ ] v{version}-MILESTONE-AUDIT.md created with structured requirement gap objects
- [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
- [ ] Nyquist compliance scanned for all milestone phases (if enabled)
- [ ] Missing VALIDATION.md phases flagged with validate-phase suggestion
- [ ] Results presented with actionable next steps
</success_criteria>
