<purpose>
Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work.
</purpose>

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

<process>

<step name="parse_arguments">
Parse the command arguments for optional flags:

- `--requirements` — Switch to requirements-first view mode (grouped by requirement ID)
- `--all` — (parallel mode only) Expand ALL in-progress milestones to full detail with `---` separators. Sequential mode emits an unconditional stderr warn and ignores the flag (Phase 66 R3 precedent; STATUS-02).
- No flags — Default progress view

Example: `/gmd:progress --requirements`
Example: `/gmd:progress --all`

Store:
- `REQUIREMENTS_VIEW=true` if `--requirements` is present, `false` otherwise.
- `ALL_FLAG=true` if `--all` is present, `false` otherwise.
</step>

<step name="init_context">
**Load progress context (paths only):**

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

Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`.

Phase 66-01 carry-forward (parallel mode threading): also extract `organizational_mode` ('sequential' | 'parallel'), `active_milestone_slug` (string | null), `active_milestone_needs_prompt` (boolean), `active_milestone_candidates` (string[]).

**Phase 67-01 STATUS-02 — sequential mode `--all` stderr warn (UNCONDITIONAL, Phase 66 R3 precedent):**

After parsing INIT JSON, if `organizational_mode === 'sequential'` AND `ALL_FLAG === true`, emit ONCE to stderr (unconditional — no env-gating, matches `active-milestone.js::resolveActiveMilestoneSlug` T5 pattern):

```
--all flag ignored in sequential mode (single milestone always full-detail)
```

Then proceed with the existing sequential-mode body unchanged. P1 byte-identical regression (vs v1.5.8 ship anchor `a9e6cd4`) covers the post-warn sequential render path.

If `project_exists` is false (no `.planning/` directory):

```
No planning structure found.

Run /gmd:new-project to start a new project.
```

Exit.

If missing STATE.md: suggest `/gmd:new-project`.

**If ROADMAP.md missing but PROJECT.md exists:**

This means a milestone was completed and archived. Go to **Route F** (between milestones).

If missing both ROADMAP.md and PROJECT.md: suggest `/gmd:new-project`.
</step>

<step name="load">
**Use structured extraction from gmd-tools:**

Instead of reading full files, use targeted tools to get only the data needed for the report:
- `ROADMAP=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" roadmap analyze)`
- `STATE=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" state-snapshot)`

This minimizes orchestrator context usage.
</step>

<step name="analyze_roadmap">
**Get comprehensive roadmap analysis (replaces manual parsing):**

```bash
ROADMAP=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" roadmap analyze)
```

This returns structured JSON with:
- All phases with disk status (complete/partial/planned/empty/no_directory)
- Goal and dependencies per phase
- Plan and summary counts per phase
- Aggregated stats: total plans, summaries, progress percent
- Current and next phase identification

Use this instead of manually reading/parsing ROADMAP.md.
</step>

<step name="recent">
**Gather recent work context:**

- Find the 2-3 most recent SUMMARY.md files
- Use `summary-extract` for efficient parsing:
  ```bash
  node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" summary-extract <path> --fields one_liner
  ```
- This shows "what we've been working on"
  </step>

<step name="position">
**Parse current position from init context and roadmap analysis:**

- Use `current_phase` and `next_phase` from `$ROADMAP`
- Note `paused_at` if work was paused (from `$STATE`)
- Count pending todos: use `init todos` or `list-todos`
- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
  </step>

<step name="report">
**Generate progress bar from gmd-tools, then present rich status report:**

```bash
# Get formatted progress bar
PROGRESS_BAR=$(node "$HOME/.claude/get-magic-done/bin/gmd-tools.cjs" progress bar --raw)
```

Present:

```
# [Project Name]

**Progress:** {PROGRESS_BAR}
**Profile:** [quality/balanced/budget]

## Recent Work
- [Phase X, Plan Y]: [what was accomplished - 1 line from summary-extract]
- [Phase X, Plan Z]: [what was accomplished - 1 line from summary-extract]

## Current Position
Phase [N] of [total]: [phase-name]
Plan [M] of [phase-total]: [status]
CONTEXT: [✓ if has_context | - if not]

## Key Decisions Made
- [extract from $STATE.decisions[]]
- [e.g. jq -r '.decisions[].decision' from state-snapshot]

## Blockers/Concerns
- [extract from $STATE.blockers[]]
- [e.g. jq -r '.blockers[].text' from state-snapshot]

## Pending Todos
- [count] pending — /gmd:check-todos to review

## Active Debug Sessions
- [count] active — /gmd:debug to continue
(Only show this section if count > 0)

## What's Next
[Next phase/plan objective from roadmap analyze]
```

</step>

<step name="other_milestones_parallel">
**Phase 67-01 STATUS-01 — Parallel-mode multi-milestone reporting.**

Run ONLY in parallel mode (`organizational_mode === 'parallel'`). Sequential mode skips this step entirely (P1 byte-identical baseline preserved).

**Default behavior (`ALL_FLAG === false`):** After the current-milestone detail rendered by `<step name="report">`, append a NEW `## Other In-Progress Milestones` section listing one line per non-current in-progress milestone.

1. Parse root MILESTONES.md `## In Progress` table rows in order (NOT alphabetical — preserves user-intent ordering per CONTEXT.md Area 1).
2. For each row whose slug does NOT match `active_milestone_slug`:
   - Call `bin/lib/state.cjs::readPerMilestoneState(cwd, slug)` to fetch per-milestone STATE.md frontmatter (`current_phase`, `phase_name` or equivalent, `last_activity`).
   - Build milestone object: `{ slug, current_phase, phase_name, last_activity }`.
   - Render via `require('./bin/lib/milestones-render.js').formatMilestoneOneLine(milestone)`.
3. If zero other in-progress milestones exist, omit the section entirely (no empty heading).

Output shape (default, parallel mode, no --all):

```
## Other In-Progress Milestones

<slug> | Phase <N>: <name> | last activity: <iso-date>
<slug> | Phase <N>: <name> | last activity: <iso-date>
```

**`--all` branch (`ALL_FLAG === true`):** For each in-progress milestone (iteration order = MILESTONES.md `## In Progress` table row order; current milestone FIRST with `▶` glyph in its detail header), render full detail with horizontal-rule (`---`) separator BETWEEN milestones.

1. Render current milestone full detail with `▶` glyph prefix on the header line.
2. For each other in-progress milestone (MILESTONES.md row order):
   - Emit `\n---\n` separator.
   - Render full detail block (same shape as current milestone — phases, plans, decisions, blockers).
   - Source data: per-milestone STATE.md frontmatter + per-milestone ROADMAP.md progress.

**Output-stability contract (critic Gate 3 MC-5):** Column shape locked in `bin/lib/milestones-render.js` (`formatMilestoneOneLine` signature). Golden-output baseline lives at `tests/fixtures/progress-parallel-baseline.txt`; regenerate via `node bin/gmd-tools.cjs progress --golden-regen`. Diff test in `bin/lib/milestones-render.test.cjs` D1 strict-equals the rendered output against the captured fixture.
</step>

<step name="requirements_view">
**Requirements-first view (only when `--requirements` flag is present).**

If `REQUIREMENTS_VIEW` is false, skip this step entirely and proceed to the `route` step. Default behavior is completely unchanged.

When `REQUIREMENTS_VIEW` is true:

**1. Read active requirements only:**

```bash
cat .planning/REQUIREMENTS.md
```

Read ONLY `.planning/REQUIREMENTS.md` — never glob-read `.planning/requirements/*.md` archive files. This is a locked anti-pattern decision.

**2. Parse each requirement:**

For each requirement entry in REQUIREMENTS.md, determine its status:
- `complete` — Marked `[x]` in REQUIREMENTS.md
- `verified` — Has a passing verification result (traced to a SUMMARY.md with Self-Check: PASSED)
- `gaps-found` — Has a failing verification or UAT gap referencing this requirement
- `pending` — Not yet addressed (no phase/plan has claimed it)

**3. Group output by requirement ID:**

Present a requirements-grouped view:

```
# Requirements Progress

**Progress:** {PROGRESS_BAR}

## By Requirement

| ID | Description | Status | Phase |
|----|-------------|--------|-------|
| REQ-01 | [description] | complete | Phase 2 |
| REQ-02 | [description] | verified | Phase 3 |
| REQ-03 | [description] | gaps-found | Phase 4 |
| REQ-04 | [description] | pending | — |

## Summary

- Complete: N
- Verified: N
- Gaps found: N
- Pending: N
```

**4. Show archived count (without loading archive files):**

Count files in the `.planning/requirements/` directory if it exists:

```bash
ARCHIVED_COUNT=$(ls -1 .planning/requirements/*.md 2>/dev/null | wc -l)
```

Append to the requirements view:

```
{ARCHIVED_COUNT} requirements archived (from previous milestones)
```

If the directory does not exist or is empty, show: `0 requirements archived (from previous milestones)`

Do NOT read the content of any archived requirement files — only count them.

**5. Exit after requirements view:**

When `--requirements` is active, the requirements view IS the full output. Do NOT continue to the `route` step — no next-action routing is needed. The user asked for a requirements-focused report.

</step>

<step name="route">
**Determine next action based on verified counts.**

**Step 1: Count plans, summaries, and issues in current phase**

List files in the current phase directory:

```bash
ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l
```

State: "This phase has {X} plans, {Y} summaries."

**Step 1.5: Check for unaddressed UAT gaps**

Check for UAT.md files with status "diagnosed" (has gaps needing fixes).

```bash
# Check for diagnosed UAT with gaps
grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null
```

Track:
- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)

**Step 2: Route based on counts**

| Condition | Meaning | Action |
|-----------|---------|--------|
| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** |
| summaries < plans | Unexecuted plans exist | Go to **Route A** |
| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
| plans = 0 | Phase not yet planned | Go to **Route B** |

---

**Route A: Unexecuted plan exists**

Find the first PLAN.md without matching SUMMARY.md.
Read its `<objective>` section.

```
---

## ▶ Next Up

**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]

`/gmd:execute-phase {phase}`

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

---
```

---

**Route B: Phase needs planning**

Check if `{phase_num}-CONTEXT.md` exists in phase directory.

**If CONTEXT.md exists:**

```
---

## ▶ Next Up

**Phase {N}: {Name}** — {Goal from ROADMAP.md}
<sub>✓ Context gathered, ready to plan</sub>

`/gmd:plan-phase {phase-number}`

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

---
```

**If CONTEXT.md does NOT exist:**

```
---

## ▶ Next Up

**Phase {N}: {Name}** — {Goal from ROADMAP.md}

`/gmd:discuss-phase {phase}` — gather context and clarify approach

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

---

**Also available:**
- `/gmd:plan-phase {phase}` — skip discussion, plan directly
- `/gmd:list-phase-assumptions {phase}` — see Claude's assumptions

---
```

---

**Route E: UAT gaps need fix plans**

UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.

```
---

## ⚠ UAT Gaps Found

**{phase_num}-UAT.md** has {N} gaps requiring fixes.

`/gmd:plan-phase {phase} --gaps`

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

---

**Also available:**
- `/gmd:execute-phase {phase}` — execute phase plans
- `/gmd:verify-work {phase}` — run more UAT testing

---
```

---

**Step 3: Check milestone status (only when phase complete)**

Read ROADMAP.md and identify:
1. Current phase number
2. All phase numbers in the current milestone section

Count total phases and identify the highest phase number.

State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."

**Route based on milestone status:**

| Condition | Meaning | Action |
|-----------|---------|--------|
| current phase < highest phase | More phases remain | Go to **Route C** |
| current phase = highest phase | Milestone complete | Go to **Route D** |

---

**Route C: Phase complete, more phases remain**

Read ROADMAP.md to get the next phase's name and goal.

```
---

## ✓ Phase {Z} Complete

## ▶ Next Up

**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}

`/gmd:discuss-phase {Z+1}` — gather context and clarify approach

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

---

**Also available:**
- `/gmd:plan-phase {Z+1}` — skip discussion, plan directly
- `/gmd:verify-work {Z}` — user acceptance test before continuing

---
```

---

**Route D: Milestone complete**

```
---

## 🎉 Milestone Complete

All {N} phases finished!

## ▶ Next Up

**Complete Milestone** — archive and prepare for next

`/gmd:complete-milestone`

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

---

**Also available:**
- `/gmd:verify-work` — user acceptance test before completing milestone

---
```

---

**Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**

A milestone was completed and archived. Ready to start the next milestone cycle.

Read MILESTONES.md to find the last completed milestone version.

```
---

## ✓ Milestone v{X.Y} Complete

Ready to plan the next milestone.

## ▶ Next Up

**Start Next Milestone** — questioning → research → requirements → roadmap

`/gmd:new-milestone`

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

---
```

</step>

<step name="edge_cases">
**Handle edge cases:**

- Phase complete but next phase not planned → offer `/gmd:plan-phase [next]`
- All work complete → offer milestone completion
- Blockers present → highlight before offering to continue
- Handoff file exists → mention it, offer `/gmd:resume-work`
  </step>

</process>

<success_criteria>

- [ ] Rich context provided (recent work, decisions, issues)
- [ ] Current position clear with visual progress
- [ ] What's next clearly explained
- [ ] Smart routing: /gmd:execute-phase if plans exist, /gmd:plan-phase if not
- [ ] User confirms before any action
- [ ] Seamless handoff to appropriate gmd command
- [ ] (Phase 67-01 STATUS-01) Parallel mode renders `## Other In-Progress Milestones` section with one line per non-current in-progress milestone via `bin/lib/milestones-render.js::formatMilestoneOneLine`
- [ ] (Phase 67-01 STATUS-02) `--all` flag in parallel mode expands all in-progress milestones to full detail with `---` separators (MILESTONES.md row order); sequential mode emits unconditional stderr warn and proceeds with sequential body unchanged
- [ ] (Phase 67-01 P1) Sequential-mode output BYTE-IDENTICAL to v1.5.8 ship anchor `a9e6cd4`
      </success_criteria>
