msd-core/gsd-core/workflows/audit-milestone.md

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.

<required_reading> Read all files referenced by the invoking prompt's execution_context 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

_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
INIT=$(gsd_run query init.milestone-op)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS_CHECKER=$(gsd_run query agent-skills gsd-integration-checker)

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

Resolve integration checker model:

integration_checker_model=$(gsd_run query resolve-model gsd-integration-checker --raw)

1. Determine Milestone Scope

# Get phases in milestone (sorted numerically, handles decimals)
gsd_run query 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=$(gsd_run query 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.

Print: "Spawning integration checker (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)"

Model omission (#2517). Omit the model parameter entirely when the value it would carry (integration_checker_model) is "inherit" or empty. An empty value 404s on runtimes without native tier aliases — the default on non-Claude runtimes. Omitting it inherits the orchestrator's model. See @gsd-core/references/model-profile-resolution.md.

Agent(
  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.

<!-- #2508 runtime-aware-dispatch -->

> **Runtime-aware dispatch (#2508 Phase 4).** GSD workflows dispatch specialized subagents by role. Before dispatching on a built-in-only runtime (kimi-code — three built-ins only), resolve the role to a built-in via `gsd_run query resolve-dispatch-type --requested <role> --raw`. On named-dispatch runtimes (Claude/OpenCode/…) the role is returned unchanged; on kimi-code it maps to `coder`/`explore`/`plan` by role-suffix. The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3) regardless. See @gsd-core/references/runtime-aware-dispatch.md.

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

ORCHESTRATOR RULE — CODEX RUNTIME: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.

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:

# #2962: zsh aborts the block on an unmatched for-list glob (nomatch); bash passes it through. nullglob both.
shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null

for summary in .planning/phases/*-*/*-SUMMARY.md; do
  [ -e "$summary" ] || continue
  gsd_run query summary-extract "$summary" --fields requirements_completed --pick 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 the Nyquist capability is inactive.

VERIFY_POST_HOOKS_JSON=$(gsd_run loop render-hooks verify:post --raw)

Resolve active step hooks from VERIFY_POST_HOOKS_JSON where kind == "step" and ref.skill == "validate-phase".

If no active validate-phase step hook exists: skip entirely.

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

Classify per phase:

Status	Condition
COMPLIANT	status: validated and nyquist_compliant: true and all tasks green
PARTIAL	status: validated and (nyquist_compliant: false or red/pending)
NOT-VALIDATED	status: draft (or absent) — validate-phase has not yet reconciled this file (#2117)
MISSING	No VALIDATION.md

NOT-VALIDATED vs PARTIAL (#2117): A phase reads status: draft when it was seeded by plan-phase but never reconciled by validate-phase, OR when its VALIDATION.md predates the status field (files written before #2117 stay draft whether or not validation ran). In both cases nyquist_compliant is not authoritative, so this is a coverage TODO ("run validate-phase") — not a compliance failure. Re-running validate-phase promotes the file to status: validated and yields the real COMPLIANT/PARTIAL verdict. Only status: validated + nyquist_compliant: false is a genuine PARTIAL.

Add to audit YAML: nyquist: { compliant_phases, partial_phases, not_validated_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 — [${PROJECT_CODE}] ${PROJECT_TITLE}

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

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

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

---

▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}

Close the gaps inline — gap planning happens as part of this audit's output (see the Unsatisfied Requirements, Cross-Phase Issues, Broken Flows, and Nyquist Coverage sections above). Insert one closure phase per gap (or per group of related gaps) using the standard phase chain:

/clear then:

/gsd:phase --insert "Close gap: — " /gsd:discuss-phase /gsd:plan-phase /gsd:execute-phase

For Nyquist-coverage gaps flagged in the table above, prefer running /gsd:validate-phase <N> for each flagged phase (and /gsd:secure-phase <N> if SECURITY.md was flagged) before inserting a new closure phase — they may close the gap retroactively without a new phase.

---

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 a cleanup phase — address the debt above before completing. Insert a closure phase using the standard chain:

/clear then:

/gsd:phase --insert "Address tech debt: " /gsd:discuss-phase /gsd:plan-phase /gsd:execute-phase

---

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