@opengsd/get-shit-done-redux 1.0.0

package/get-shit-done/workflows/note.md

@@ -0,0 +1,158 @@
+<purpose>
+Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+Runs inline — no Task, no AskUserQuestion, no Bash.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="storage_format">
+**Note storage format.**
+
+Notes are stored as individual markdown files:
+
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` exists in cwd
+- **Global scope**: `~/.claude/notes/{YYYY-MM-DD}-{slug}.md` — fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
+
+**`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
+
+**Important**: Do NOT create `.planning/` if it doesn't exist. Fall back to global scope silently.
+</step>
+
+<step name="parse_subcommand">
+**Parse subcommand from $ARGUMENTS (after stripping --global).**
+
+| Condition | Subcommand |
+|-----------|------------|
+| Arguments are exactly `list` (case-insensitive) | **list** |
+| Arguments are exactly `promote <N>` where N is a number | **promote** |
+| Arguments are empty (no text at all) | **list** |
+| Anything else | **append** (the text IS the note) |
+
+**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/gsd-note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
+</step>
+
+<step name="append">
+**Subcommand: append — create a timestamped note file.**
+
+1. Determine scope (project or global) per storage format above
+2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see storage format)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
+   - Where `{scope}` is "project" or "global"
+
+**Constraints:**
+- **Never modify the note text** — capture verbatim, including typos
+- **Never ask questions** — just write and confirm
+- **Timestamp format**: Use local time, `YYYY-MM-DD HH:mm` (24-hour, no seconds)
+</step>
+
+<step name="list">
+**Subcommand: list — show notes from both scopes.**
+
+1. Glob `.planning/notes/*.md` (if directory exists) — project notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — global notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
+6. If total active entries > 20, show only the last 10 with a note about how many were omitted
+
+**Display format:**
+
+```
+Notes:
+
+Project (.planning/notes/):
+  1. [2026-02-08 14:32] refactor the hook system to support async validators
+  2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
+  3. [2026-02-08 15:10] consider adding a --dry-run flag to build
+
+Global (~/.claude/notes/):
+  4. [2026-02-08 10:00] cross-project idea about shared config
+
+{count} active note(s). Use `/gsd-note promote <N>` to convert to a todo.
+```
+
+If a scope has no directory or no entries, show: `(no notes)`
+</step>
+
+<step name="promote">
+**Subcommand: promote — convert a note into a todo.**
+
+1. Run the **list** logic to build the numbered index (both scopes)
+2. Find entry N from the numbered list
+3. If N is invalid or refers to an already-promoted note, tell the user and stop
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a GSD project. Run `/gsd:new-project` to initialize one."
+5. Ensure `.planning/todos/pending/` directory exists
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/completed/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+7. Extract the note text from the source file (body after frontmatter)
+8. Create `.planning/todos/pending/{id}.md`:
+
+```yaml
+---
+title: "{note text}"
+status: pending
+priority: P2
+source: "promoted from /gsd-note"
+created: {YYYY-MM-DD}
+theme: general
+---
+
+## Goal
+
+{note text}
+
+## Context
+
+Promoted from quick note captured on {original date}.
+
+## Acceptance Criteria
+
+- [ ] {primary criterion derived from note text}
+```
+
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
+10. Confirm: `Promoted note {N} to todo {id}: {note text}`
+</step>
+
+</process>
+
+<edge_cases>
+1. **"list" as note text**: `/gsd-note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `/gsd:new-project`
+4. **Large files**: `list` shows last 10 when >20 active entries
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
+6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
+7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
+8. **Empty note text after stripping flags**: Treat as `list` subcommand
+</edge_cases>
+
+<success_criteria>
+- [ ] Append: Note file written with correct frontmatter and verbatim text
+- [ ] Append: No questions asked — instant capture
+- [ ] List: Both scopes shown with sequential numbering
+- [ ] List: Promoted notes shown but dimmed
+- [ ] Promote: Todo created with correct format
+- [ ] Promote: Source note marked as promoted
+- [ ] Global fallback: Works when no `.planning/` exists
+</success_criteria>

package/get-shit-done/workflows/pause-work.md

@@ -0,0 +1,254 @@
+<purpose>
+Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files to preserve complete work state across sessions. The JSON provides machine-readable state for `/gsd:resume-work`; the markdown provides human-readable context.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="detect">
+## Context Detection
+
+Determine what kind of work is being paused and set the handoff destination accordingly:
+
+```bash
+# Check for active phase
+phase=$(( ls -lt .planning/phases/*/PLAN.md 2>/dev/null || true ) | head -1 | grep -oP 'phases/\K[^/]+' || true)
+
+# Check for active spike
+spike=$(( ls -lt .planning/spikes/*/SPIKE.md .planning/spikes/*/DESIGN.md .planning/spikes/*/README.md 2>/dev/null || true ) | head -1 | grep -oP 'spikes/\K[^/]+' || true)
+
+# Check for active sketch
+sketch=$(( ls -lt .planning/sketches/*/README.md .planning/sketches/*/index.html 2>/dev/null || true ) | head -1 | grep -oP 'sketches/\K[^/]+' || true)
+
+# Check for active deliberation
+deliberation=$(ls .planning/deliberations/*.md 2>/dev/null | head -1 || true)
+```
+
+- **Phase work**: active phase directory → handoff to `.planning/phases/XX-name/.continue-here.md`
+- **Spike work**: active spike directory or spike-related files (no active phase) → handoff to `.planning/spikes/SPIKE-NNN/.continue-here.md` (create directory if needed)
+- **Sketch work**: active sketch directory (no active phase/spike) → handoff to `.planning/sketches/.continue-here.md`
+- **Deliberation work**: active deliberation file (no phase/spike/sketch) → handoff to `.planning/deliberations/.continue-here.md`
+- **Research work**: research notes exist but no phase/spike/sketch/deliberation → handoff to `.planning/.continue-here.md`
+- **Default**: no detectable context → handoff to `.planning/.continue-here.md`, note the ambiguity in `<current_state>`
+
+If phase is detected, proceed with phase handoff path. Otherwise use the first matching non-phase path above.
+</step>
+
+<step name="gather">
+**Collect complete state for handoff:**
+
+1. **Current position**: Which phase, which plan, which task
+2. **Work completed**: What got done this session
+3. **Work remaining**: What's left in current plan/phase
+4. **Decisions made**: Key decisions and rationale
+5. **Blockers/issues**: Anything stuck
+6. **Human actions pending**: Things that need manual intervention (MCP setup, API keys, approvals, manual testing)
+7. **Background processes**: Any running servers/watchers that were part of the workflow
+8. **Files modified**: What's changed but not committed
+9. **Blocking constraints**: Anti-patterns or methodological failures encountered during this session that a resuming agent MUST be aware of before proceeding. Only include items discovered through actual failure — not warnings or predictions. Assign each constraint a `severity`:
+   - `blocking` — The resuming agent MUST demonstrate understanding before proceeding. The discuss-phase and execute-phase workflows will enforce a mandatory understanding check.
+   - `advisory` — Important context but does not gate resumption.
+
+Ask user for clarifications if needed via conversational questions.
+
+**Also inspect SUMMARY.md files for false completions:**
+```bash
+# Check for placeholder content in existing summaries
+grep -l "To be filled\|placeholder\|TBD" .planning/phases/*/*.md 2>/dev/null || true
+```
+Report any summaries with placeholder content as incomplete items.
+</step>
+
+<step name="write_structured">
+**Write structured handoff to `.planning/HANDOFF.json`:**
+
+```bash
+# SDK resolution: prefer local gsd-tools.cjs, fall back to global gsd-sdk (#3668)
+GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
+if [ -f "$GSD_TOOLS" ]; then
+  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-sdk >/dev/null 2>&1; then
+  GSD_SDK="gsd-sdk"
+else
+  echo "ERROR: gsd-sdk not found on PATH and $GSD_TOOLS does not exist." >&2
+  echo "Run: npx get-shit-done-cc@latest --claude --local" >&2
+  exit 1
+fi
+timestamp=$($GSD_SDK query current-timestamp full --raw)
+```
+
+```json
+{
+  "version": "1.0",
+  "timestamp": "{timestamp}",
+  "phase": "{phase_number}",
+  "phase_name": "{phase_name}",
+  "phase_dir": "{phase_dir}",
+  "plan": {current_plan_number},
+  "task": {current_task_number},
+  "total_tasks": {total_task_count},
+  "status": "paused",
+  "completed_tasks": [
+    {"id": 1, "name": "{task_name}", "status": "done", "commit": "{short_hash}"},
+    {"id": 2, "name": "{task_name}", "status": "done", "commit": "{short_hash}"},
+    {"id": 3, "name": "{task_name}", "status": "in_progress", "progress": "{what_done}"}
+  ],
+  "remaining_tasks": [
+    {"id": 4, "name": "{task_name}", "status": "not_started"},
+    {"id": 5, "name": "{task_name}", "status": "not_started"}
+  ],
+  "blockers": [
+    {"description": "{blocker}", "type": "technical|human_action|external", "workaround": "{if any}"}
+  ],
+  "human_actions_pending": [
+    {"action": "{what needs to be done}", "context": "{why}", "blocking": true}
+  ],
+  "decisions": [
+    {"decision": "{what}", "rationale": "{why}", "phase": "{phase_number}"}
+  ],
+  "uncommitted_files": [],
+  "next_action": "{specific first action when resuming}",
+  "context_notes": "{mental state, approach, what you were thinking}"
+}
+```
+</step>
+
+<step name="write">
+**Write handoff to the path determined in the detect step** (e.g. `.planning/phases/XX-name/.continue-here.md`, `.planning/spikes/SPIKE-NNN/.continue-here.md`, or `.planning/.continue-here.md`):
+
+```markdown
+---
+context: [phase|spike|sketch|deliberation|research|default]
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: [timestamp from current-timestamp]
+---
+
+# BLOCKING CONSTRAINTS — Read Before Anything Else
+
+> These are not suggestions. Each constraint below was discovered through failure.
+> Acknowledge each one explicitly before proceeding.
+
+- [ ] CONSTRAINT: [name] — [what it is] — [structural mitigation required]
+
+**Do not proceed until all boxes are checked.**
+
+_If no constraints have been identified yet, remove this section._
+
+## Critical Anti-Patterns
+
+| Pattern | Description | Severity | Prevention Mechanism |
+|---------|-------------|----------|---------------------|
+| [pattern name] | [what it is and how it manifested] | blocking | [structural step that prevents recurrence — not acknowledgment] |
+| [pattern name] | [what it is and how it manifested] | advisory | [guidance for avoiding it] |
+
+**Severity values:** `blocking` — resuming agent must pass understanding check before proceeding. `advisory` — important context, does not gate resumption.
+
+_Remove rows that do not apply. The discuss-phase and execute-phase workflows parse this table and enforce a mandatory understanding check for any `blocking` rows._
+
+<current_state>
+[Where exactly are we? Immediate context]
+</current_state>
+
+<completed_work>
+
+Completed Tasks:
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done]
+</completed_work>
+
+<remaining_work>
+
+- Task 3: [what's left]
+- Task 4: Not started
+- Task 5: Not started
+</remaining_work>
+
+<decisions_made>
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+## Required Reading (in order)
+<!-- List documents the resuming agent must read before acting -->
+1. [document] — [why it matters]
+1. `.planning/METHODOLOGY.md` (if it exists) — project analytical lenses; apply before any assumption analysis
+
+## Critical Anti-Patterns (do NOT repeat these)
+<!-- Mistakes discovered this session that must be structurally avoided -->
+- [ANTI-PATTERN]: [what it is] → [structural mitigation]
+
+## Infrastructure State
+<!-- Running services, external state, environment specifics -->
+- [service/env]: [current state]
+
+## Pre-Execution Critique Required
+<!-- Fill in ONLY if pausing between design and execution (e.g. spike design done, not yet run) -->
+- Design artifact: [path]
+- Critique focus: [key questions the critic should probe]
+- Gate: Do NOT begin execution until critique is complete and design is revised
+
+<context>
+[Mental state, what were you thinking, the plan]
+</context>
+
+<next_action>
+Start with: [specific first action when resuming]
+</next_action>
+```
+
+Be specific enough for a fresh Claude to understand immediately.
+
+Use `current-timestamp` for last_updated field. You can use init todos (which provides timestamps) or call directly:
+```bash
+timestamp=$($GSD_SDK query current-timestamp full --raw)
+```
+</step>
+
+<step name="commit">
+```bash
+$GSD_SDK query commit "wip: [context-name] paused at [X]/[Y]" --files [handoff-path] .planning/HANDOFF.json
+```
+</step>
+
+<step name="confirm">
+```
+✓ Handoff created:
+  - .planning/HANDOFF.json (structured, machine-readable)
+  - [handoff-path] (human-readable)
+
+Current state:
+
+- Context: [phase|spike|deliberation|research]
+- Location: [XX-name or SPIKE-NNN]
+- Task: [X] of [Y]
+- Status: [in_progress/blocked]
+- Blockers: [count] ({human_actions_pending count} need human action)
+- Committed as WIP
+
+To resume: /gsd:resume-work
+
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Context detected (phase/spike/deliberation/research/default)
+- [ ] .continue-here.md created at correct path for detected context
+- [ ] Required Reading, Anti-Patterns, and Infrastructure State sections filled
+- [ ] Pre-Execution Critique section filled if pausing between design and execution
+- [ ] Committed as WIP
+- [ ] User knows location and how to resume
+</success_criteria>

package/get-shit-done/workflows/plan-milestone-gaps.md

@@ -0,0 +1,291 @@
+<purpose>
+Create all phases necessary to close gaps identified by `/gsd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/gsd-add-phase` per gap.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 1. Load Audit Results
+
+```bash
+# Find the most recent audit file
+(ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null || true) | head -1
+```
+
+Parse YAML frontmatter to extract structured gaps:
+- `gaps.requirements` — unsatisfied requirements
+- `gaps.integration` — missing cross-phase connections
+- `gaps.flows` — broken E2E flows
+
+If no audit file exists or has no gaps, error:
+```
+No audit gaps found. Run `/gsd:audit-milestone` first.
+```
+
+## 2. Prioritize Gaps
+
+Group gaps by priority from REQUIREMENTS.md:
+
+| Priority | Action |
+|----------|--------|
+| `must` | Create phase, blocks milestone |
+| `should` | Create phase, recommended |
+| `nice` | Ask user: include or defer? |
+
+For integration/flow gaps, infer priority from affected requirements.
+
+## 3. Group Gaps into Phases
+
+Cluster related gaps into logical phases:
+
+**Grouping rules:**
+- Same affected phase → combine into one fix phase
+- Same subsystem (auth, API, UI) → combine
+- Dependency order (fix stubs before wiring)
+- Keep phases focused: 2-4 tasks each
+
+**Example grouping:**
+```
+Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
+Gap: Integration Phase 1→3 (Auth not passed to API calls)
+Gap: Flow "View dashboard" broken at data fetch
+
+→ Phase 6: "Wire Dashboard to API"
+  - Add fetch to Dashboard.tsx
+  - Include auth header in fetch
+  - Handle response, update state
+  - Render user data
+```
+
+## 4. Determine Phase Numbers
+
+Find highest existing phase:
+```bash
+# Get sorted phase list, extract last one
+# SDK resolution: prefer local gsd-tools.cjs, fall back to global gsd-sdk (#3668)
+GSD_TOOLS="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}/get-shit-done/bin/gsd-tools.cjs"
+if [ -f "$GSD_TOOLS" ]; then
+  GSD_SDK="node $GSD_TOOLS"
+elif command -v gsd-sdk >/dev/null 2>&1; then
+  GSD_SDK="gsd-sdk"
+else
+  echo "ERROR: gsd-sdk not found on PATH and $GSD_TOOLS does not exist." >&2
+  echo "Run: npx get-shit-done-cc@latest --claude --local" >&2
+  exit 1
+fi
+HIGHEST=$($GSD_SDK query phases.list --pick directories[-1])
+```
+
+New phases continue from there:
+- If Phase 5 is highest, gaps become Phase 6, 7, 8...
+
+## 5. Present Gap Closure Plan
+
+```markdown
+## Gap Closure Plan
+
+**Milestone:** {version}
+**Gaps to close:** {N} requirements, {M} integration, {K} flows
+
+### Proposed Phases
+
+**Phase {N}: {Name}**
+Closes:
+- {REQ-ID}: {description}
+- Integration: {from} → {to}
+Tasks: {count}
+
+**Phase {N+1}: {Name}**
+Closes:
+- {REQ-ID}: {description}
+- Flow: {flow name}
+Tasks: {count}
+
+{If nice-to-have gaps exist:}
+
+### Deferred (nice-to-have)
+
+These gaps are optional. Include them?
+- {gap description}
+- {gap description}
+
+---
+
+Create these {X} phases? (yes / adjust / defer all optional)
+```
+
+Wait for user confirmation.
+
+## 6. Update ROADMAP.md
+
+Add new phases to current milestone:
+
+```markdown
+### Phase {N}: {Name}
+**Goal:** {derived from gaps being closed}
+**Requirements:** {REQ-IDs being satisfied}
+**Gap Closure:** Closes gaps from audit
+
+### Phase {N+1}: {Name}
+...
+```
+
+## 7. Update REQUIREMENTS.md Traceability Table (REQUIRED)
+
+For each REQ-ID assigned to a gap closure phase:
+- Update the Phase column to reflect the new gap closure phase
+- Reset Status to `Pending`
+
+Reset checked-off requirements the audit found unsatisfied:
+- Change `[x]` → `[ ]` for any requirement marked unsatisfied in the audit
+- Update coverage count at top of REQUIREMENTS.md
+
+```bash
+# Verify traceability table reflects gap closure assignments
+grep -c "Pending" .planning/REQUIREMENTS.md
+```
+
+## 8. Create Phase Directories
+
+For each new phase (N, N+1, …), resolve the directory name via `init.phase-op` so the `project_code` prefix is honoured:
+
+```bash
+INIT=$($GSD_SDK query init.phase-op "{NN}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+expected_phase_dir=$(echo "$INIT" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).expected_phase_dir)")
+mkdir -p "${expected_phase_dir}"
+```
+
+Repeat for each gap-closure phase number. This produces `{CODE}-{NN}-{slug}/` when `project_code` is set in `.planning/config.json`, and `{NN}-{slug}/` otherwise — consistent with all other phase-creation paths.
+
+## 9. Commit Roadmap and Requirements Update
+
+```bash
+$GSD_SDK query commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
+```
+
+## 10. Offer Next Steps
+
+```markdown
+## ✓ Gap Closure Phases Created
+
+**Phases added:** {N} - {M}
+**Gaps addressed:** {count} requirements, {count} integration, {count} flows
+
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Plan first gap closure phase**
+
+`/clear` then:
+
+`/gsd:plan-phase {N}`
+
+---
+
+**Also available:**
+- `/gsd:execute-phase {N}` — if plans already exist
+- `cat .planning/ROADMAP.md` — see updated roadmap
+
+---
+
+**After all gap phases complete:**
+
+`/gsd:audit-milestone` — re-audit to verify gaps closed
+`/gsd:complete-milestone {version}` — archive when audit passes
+```
+
+</process>
+
+<gap_to_phase_mapping>
+
+## How Gaps Become Tasks
+
+**Requirement gap → Tasks:**
+```yaml
+gap:
+  id: DASH-01
+  description: "User sees their data"
+  reason: "Dashboard exists but doesn't fetch from API"
+  missing:
+    - "useEffect with fetch to /api/user/data"
+    - "State for user data"
+    - "Render user data in JSX"
+
+becomes:
+
+phase: "Wire Dashboard Data"
+tasks:
+  - name: "Add data fetching"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useEffect that fetches /api/user/data on mount"
+
+  - name: "Add state management"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useState for userData, loading, error states"
+
+  - name: "Render user data"
+    files: [src/components/Dashboard.tsx]
+    action: "Replace placeholder with userData.map rendering"
+```
+
+**Integration gap → Tasks:**
+```yaml
+gap:
+  from_phase: 1
+  to_phase: 3
+  connection: "Auth token → API calls"
+  reason: "Dashboard API calls don't include auth header"
+  missing:
+    - "Auth header in fetch calls"
+    - "Token refresh on 401"
+
+becomes:
+
+phase: "Add Auth to Dashboard API Calls"
+tasks:
+  - name: "Add auth header to fetches"
+    files: [src/components/Dashboard.tsx, src/lib/api.ts]
+    action: "Include Authorization header with token in all API calls"
+
+  - name: "Handle 401 responses"
+    files: [src/lib/api.ts]
+    action: "Add interceptor to refresh token or redirect to login on 401"
+```
+
+**Flow gap → Tasks:**
+```yaml
+gap:
+  name: "User views dashboard after login"
+  broken_at: "Dashboard data load"
+  reason: "No fetch call"
+  missing:
+    - "Fetch user data on mount"
+    - "Display loading state"
+    - "Render user data"
+
+becomes:
+
+# Usually same phase as requirement/integration gap
+# Flow gaps often overlap with other gap types
+```
+
+</gap_to_phase_mapping>
+
+<success_criteria>
+- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
+- [ ] Gaps prioritized (must/should/nice)
+- [ ] Gaps grouped into logical phases
+- [ ] User confirmed phase plan
+- [ ] ROADMAP.md updated with new phases
+- [ ] REQUIREMENTS.md traceability table updated with gap closure phase assignments
+- [ ] Unsatisfied requirement checkboxes reset (`[x]` → `[ ]`)
+- [ ] Coverage count updated in REQUIREMENTS.md
+- [ ] Phase directories created
+- [ ] Changes committed (includes REQUIREMENTS.md)
+- [ ] User knows to run `/gsd:plan-phase` next
+</success_criteria>