---
name: gmd:check-integration
description: On-demand per-phase cross-phase integration check (dispatches gmd-integration-checker for a specific phase without waiting for milestone boundary)
argument-hint: "[phase]"
allowed-tools:
  - Read
  - Bash
  - Grep
  - Glob
  - Task
---

<objective>
Run `gmd-integration-checker` against a single phase (or the current in-progress phase from STATE.md if no argument given) to validate export/import wiring, API coverage, E2E flow traces, and Requirements Integration Map.

**Why subagent:** Integration auditing across a phase burns context quickly (reading every PLAN/SUMMARY, scanning source for imports, tracing flows). Fresh 200k context per invocation keeps the main session lean.

**Relationship to milestone auto-fire:** Milestone-boundary integration checking already runs automatically from `workflows/audit-milestone.md`. This command does NOT replace that — it provides an early on-demand path for per-phase granularity between milestone boundaries.
</objective>

<when_to_use>

**Use when:**

- A phase was just completed and you want early feedback on whether its exports wire correctly with prior phases' imports, WITHOUT waiting for the next milestone audit
- Investigating a suspected cross-phase integration gap before the milestone pass
- Getting a second-opinion integration report after a verification run that passed goal-backward checks but felt thin on wiring

**Do NOT use for:**

- Every phase as a matter of course — milestone auto-fire handles the systematic case. Per-phase auto-fire was explicitly rejected in Phase 5 CONTEXT.md as too token-heavy and noisy.
- Active development of a phase — run AFTER the phase is marked complete in STATE.md, not during plan execution.
- Replacing the milestone-boundary check — that pass remains authoritative for milestone completion.

</when_to_use>

<context>

User's phase argument: $ARGUMENTS (may be empty)

```bash
PHASE_ARG="${1:-$ARGUMENTS}"
PHASE_ARG=$(echo "$PHASE_ARG" | tr -d '[:space:]')
```

</context>

<process>

## 0. Initialize Context

```bash
INIT=$(node "${CLAUDE_PLUGIN_ROOT}/bin/gmd-tools.cjs" state load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

Resolve integration-checker model:

```bash
checker_model=$(node "${CLAUDE_PLUGIN_ROOT}/bin/gmd-tools.cjs" resolve-model gmd-integration-checker --complexity standard --raw)
```

## 1. Resolve Phase Argument

If `$PHASE_ARG` is empty, default to the current in-progress phase from STATE.md:

```bash
if [ -z "$PHASE_ARG" ]; then
  PHASE_ARG=$(grep -oE "Phase: [0-9.]+" .planning/STATE.md | head -1 | awk '{print $2}')
fi
```

Resolve to phase directory:

```bash
PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
if [ -z "$PHASE_DIR" ]; then
  # Also try zero-padded (e.g. "5" -> "05-*")
  PADDED=$(printf "%02d" "${PHASE_ARG%%.*}" 2>/dev/null)
  PHASE_DIR=$(ls -d .planning/phases/${PADDED}-* 2>/dev/null | head -1)
fi

if [ -z "$PHASE_DIR" ]; then
  echo "ERROR: phase '$PHASE_ARG' not found under .planning/phases/"
  exit 1
fi
```

## 2. Gather Phase Context

Collect the inputs `gmd-integration-checker` needs:

- All `*-PLAN.md` files in the phase directory
- All `*-SUMMARY.md` files in the phase directory (integration check requires phase to be executed)
- ROADMAP.md phase entry + "Depends on" line for prior phase lookup
- REQUIREMENTS.md entries mapped to this phase

```bash
PLANS=$(ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
SUMMARIES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)

if [ -z "$SUMMARIES" ]; then
  echo "WARNING: Phase ${PHASE_ARG} has no SUMMARY.md files. Integration check requires completed plans."
  echo "Run /gmd:execute-phase ${PHASE_ARG} first, or use a completed phase."
  exit 1
fi

# Find prior phases this one depends on (ROADMAP.md "Depends on: X, Y" line for this phase)
DEPENDS_ON=$(grep -A 20 "^### Phase ${PHASE_ARG}" .planning/ROADMAP.md 2>/dev/null | grep -i "depends on" | head -1)
```

## 3. Dispatch gmd-integration-checker

```
Task(
  subagent_type="gmd-integration-checker",
  model="{checker_model}",
  prompt="
    <objective>
    On-demand cross-phase integration check for phase ${PHASE_ARG}.

    Check whether this phase's exports wire correctly with prior phases' imports.
    Produce export→import map, API coverage, flow traces (auth/data/form where relevant),
    and a Requirements Integration Map showing CONNECTED/ORPHANED/IMPORTED_NOT_USED status
    for every requirement tagged to this phase.
    </objective>

    <scope>
    phase: ${PHASE_ARG}
    mode: on-demand
    context: user-invoked via /gmd:check-integration (not milestone boundary)
    depends_on: ${DEPENDS_ON}
    </scope>

    <files_to_read>
    - ${PHASE_DIR}/*-PLAN.md
    - ${PHASE_DIR}/*-SUMMARY.md
    - .planning/ROADMAP.md
    - .planning/REQUIREMENTS.md
    - .planning/STATE.md
    (Also read prior phases this phase depends on — derive from ROADMAP.md 'Depends on' line above.)
    </files_to_read>

    <output>
    Create ${PHASE_DIR}/${PHASE_ARG}-INTEGRATION.md with the full report structured per
    gmd-integration-checker.md §output:
      - Wiring Summary (Connected / Orphaned / Missing counts + details)
      - API Coverage (Consumed / Orphaned)
      - Auth Protection (Protected / Unprotected)
      - E2E Flows (Complete / Broken with specific break points)
      - Requirements Integration Map table
      - Requirements with no cross-phase wiring
    </output>
  ",
  description="On-demand integration check for phase ${PHASE_ARG}"
)
```

## 4. Report Summary

After `gmd-integration-checker` completes, report to user:

- Location of the new `${PHASE_ARG}-INTEGRATION.md` report file
- Summary counts: CONNECTED / ORPHANED / IMPORTED_NOT_USED
- Broken flow count (if any)
- Unprotected auth routes (if any)
- Next step:
  - **If gaps found:** user reviews the report; if real gaps exist, the plan-phase flow can be re-run with `--gaps` mode after VERIFICATION.md is updated
  - **If clean:** no action — early validation confirms the phase wires correctly with prior phases

```
/gmd:check-integration ${PHASE_ARG} complete.

Report: ${PHASE_DIR}/${PHASE_ARG}-INTEGRATION.md
Connected: {N}  Orphaned: {M}  Missing: {K}
Broken flows: {B}  Unprotected routes: {U}
```

</process>

<relationship_to_milestone_audit>

**Per-phase auto-fire is explicitly rejected** in `.planning/phases/05-review-verification/05-CONTEXT.md` (too token-heavy per phase boundary; milestone-boundary auto-fire already exists).

This command is the on-demand escape hatch:

- `/gmd:check-integration` (this command) — on-demand, user-invoked, optional
- `workflows/audit-milestone.md` — automatic at milestone boundaries, authoritative for milestone completion

Running both on the same phase is fine. The milestone pass is the source of truth for milestone sign-off; this command gives earlier feedback when desired.

</relationship_to_milestone_audit>

<success_criteria>

- [ ] Phase argument resolved (from $1 or STATE.md default)
- [ ] Phase directory found and validated
- [ ] Phase has SUMMARY.md files (i.e. phase is executed)
- [ ] gmd-integration-checker spawned via Task with structured context
- [ ] INTEGRATION.md report produced in phase directory
- [ ] Summary reported to user with next-step guidance

</success_criteria>
