gsd-audit-milestone

name: gsd-audit-milestone description: "Audit milestone completion against original intent before archiving" argument-hint: "[version]" allowed-tools:

• Read
• Glob
• Grep
• Bash
• Task
• Write

This command IS the orchestrator. 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. </objective>

<required_reading> Read the skill content below before starting. </required_reading>

<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):

• gsd-integration-checker — Checks cross-phase integration </available_agent_types>

0. Initialize Milestone Context

INIT=$(node "$GSD_TOOLS" init milestone-op)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS_CHECKER=$(node "$GSD_TOOLS" agent-skills gsd-integration-checker 2>/dev/null)

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

Resolve integration checker model:

integration_checker_model=$(node "$GSD_TOOLS" resolve-model gsd-integration-checker --raw)

1. Determine Milestone Scope

# Get phases in milestone (sorted numerically, handles decimals)
node "$GSD_TOOLS" 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:

# For each phase, use find-phase to resolve the directory (handles archived phases)
PHASE_INFO=$(node "$GSD_TOOLS" 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

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.
${AGENT_SKILLS_CHECKER}",
  subagent_type="gsd-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:

for summary in .planning/phases/*-*/*-SUMMARY.md; do
  [ -e "$summary" ] || continue
  node "$GSD_TOOLS" summary-extract "$summary" --fields requirements_completed --pick requirements_completed
done

5d. Status Determination Matrix

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

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).

NYQUIST_CONFIG=$(node "$GSD_TOOLS" 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:

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

Discovery only — never auto-calls /gsd-validate-phase.

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

Create .planning/v{version}-v{version}-MILESTONE-AUDIT.md with:

---
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. Present Results

Route by status (see <offer_next>).

<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

/clear then:

/gsd-complete-milestone {version}

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

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

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

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

▶ Next Up

Plan gap closure — create phases to complete milestone

/clear then:

/gsd-plan-milestone-gaps

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

Also available:

• cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
• /gsd-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

/gsd-complete-milestone {version}

B. Plan cleanup phase — address debt before completing

/clear then:

/gsd-plan-milestone-gaps

─────────────────────────────────────────────────────────────── </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>

Core planning files are resolved in-workflow (init milestone-op) and loaded only as needed.

Completed Work: Glob: .planning/phases//-SUMMARY.md Glob: .planning/phases//-VERIFICATION.md </context>