@opengsd/get-shit-done-redux 1.0.0

package/get-shit-done/references/model-profiles.md

@@ -0,0 +1,245 @@
+# Model Profiles
+
+Model profiles control which Claude model each GSD agent uses. This allows balancing quality vs token spend, or inheriting the currently selected session model.
+
+## Profile Definitions
+
+| Agent | `quality` | `balanced` | `budget` | `adaptive` | `inherit` |
+|-------|-----------|------------|----------|------------|-----------|
+| gsd-planner | opus | opus | sonnet | opus | inherit |
+| gsd-roadmapper | opus | sonnet | sonnet | sonnet | inherit |
+| gsd-executor | opus | sonnet | sonnet | sonnet | inherit |
+| gsd-phase-researcher | opus | sonnet | haiku | sonnet | inherit |
+| gsd-project-researcher | opus | sonnet | haiku | sonnet | inherit |
+| gsd-research-synthesizer | sonnet | sonnet | haiku | haiku | inherit |
+| gsd-debugger | opus | sonnet | sonnet | opus | inherit |
+| gsd-codebase-mapper | sonnet | haiku | haiku | haiku | inherit |
+| gsd-verifier | sonnet | sonnet | haiku | sonnet | inherit |
+| gsd-plan-checker | sonnet | sonnet | haiku | haiku | inherit |
+| gsd-integration-checker | sonnet | sonnet | haiku | haiku | inherit |
+| gsd-nyquist-auditor | sonnet | sonnet | haiku | haiku | inherit |
+
+## Per-Phase-Type Model Map (#3023)
+
+`.planning/config.json` accepts a coarse per-**phase-type** map under the `models` key. Use this when you want tuning at the phase level ("Opus for planning and execution, Sonnet for the rest") without learning the agent taxonomy.
+
+```json
+{
+  "model_profile": "balanced",
+  "models": {
+    "planning": "opus",
+    "discuss": "opus",
+    "research": "sonnet",
+    "execution": "opus",
+    "verification": "sonnet",
+    "completion": "sonnet"
+  },
+  "model_overrides": {
+    "gsd-codebase-mapper": "haiku"
+  }
+}
+```
+
+### Phase-type → agent mapping
+
+| Phase type | Agents |
+|---|---|
+| `planning` | gsd-planner, gsd-roadmapper, gsd-pattern-mapper |
+| `discuss` | (reserved — no subagent today) |
+| `research` | gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-codebase-mapper, gsd-ui-researcher |
+| `execution` | gsd-executor, gsd-debugger, gsd-doc-writer |
+| `verification` | gsd-verifier, gsd-plan-checker, gsd-integration-checker, gsd-nyquist-auditor, gsd-ui-checker, gsd-ui-auditor, gsd-doc-verifier |
+| `completion` | (reserved — no subagent today) |
+
+### Resolution precedence (highest to lowest)
+
+1. **Per-agent `model_overrides[agent]`** — full IDs accepted; targeted exceptions
+2. **Phase-type `models[phase_type]`** — tier alias only (`opus` / `sonnet` / `haiku` / `inherit`)
+3. **Profile table** — the per-agent column from the active `model_profile`
+4. **Runtime default** — when nothing else applies
+
+### Why two layers above the profile?
+
+- **Profile** is a global tier strategy (everyone runs balanced).
+- **`models`** is coarse phase-level tuning without learning agent names.
+- **`model_overrides`** is per-agent precision (e.g. force `haiku` on `gsd-codebase-mapper` for a fan-out).
+
+The three layers compose: `models` defaults a phase, `model_overrides` carves an exception out of it.
+
+## Profile Philosophy
+
+**quality** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- Use when: quota available, critical architecture work
+
+**balanced** (default) - Smart allocation
+- Opus only for planning (where architecture decisions happen)
+- Sonnet for execution and research (follows explicit instructions)
+- Sonnet for verification (needs reasoning, not just pattern matching)
+- Use when: normal development, good balance of quality and cost
+
+**budget** - Minimal Opus usage
+- Sonnet for anything that writes code
+- Haiku for research and verification
+- Use when: conserving quota, high-volume work, less critical phases
+
+**adaptive** — Role-based cost optimization
+- Opus for planning and debugging (where reasoning quality has highest impact)
+- Sonnet for execution, research, and verification (follows explicit instructions)
+- Haiku for mapping, checking, and auditing (high volume, structured output)
+- Use when: optimizing cost without sacrificing plan quality, solo development on paid API tiers
+
+**inherit** - Follow the current session model
+- All agents resolve to `inherit`
+- Best when you switch models interactively (for example OpenCode or Kilo `/model`)
+- **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise GSD may call Anthropic models directly, incurring unexpected costs
+- Use when: you want GSD to follow your currently selected runtime model
+
+## Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
+
+When installed for a non-Claude runtime, the GSD installer sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
+
+To assign different models to different agents, add `model_overrides` with model IDs your runtime recognizes:
+
+```json
+{
+  "resolve_model_ids": "omit",
+  "model_overrides": {
+    "gsd-planner": "o3",
+    "gsd-executor": "o4-mini",
+    "gsd-debugger": "o3",
+    "gsd-codebase-mapper": "o4-mini"
+  }
+}
+```
+
+The same tiering logic applies: stronger models for planning and debugging, cheaper models for execution and mapping.
+
+## Using Claude Code with Non-Anthropic Providers (OpenRouter, Local)
+
+If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic provider, set the `inherit` profile to prevent GSD from calling Anthropic models for subagents:
+
+```bash
+# Via settings command
+/gsd:settings
+# → Select "Inherit" for model profile
+
+# Or manually in .planning/config.json
+{
+  "model_profile": "inherit"
+}
+```
+
+Without `inherit`, GSD's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider.
+
+## Dynamic Routing with Failure-Tier Escalation (#3024)
+
+When `dynamic_routing.enabled = true` in `.planning/config.json`, the resolver picks a model from a tier-mapped table based on the agent's *default tier* (light / standard / heavy) and escalates to the next tier up on orchestrator-detected soft failure.
+
+```json
+{
+  "dynamic_routing": {
+    "enabled": true,
+    "tier_models": {
+      "light":    "haiku",
+      "standard": "sonnet",
+      "heavy":    "opus"
+    },
+    "escalate_on_failure": true,
+    "max_escalations": 1
+  }
+}
+```
+
+**Agent default tiers** (each agent in `MODEL_PROFILES` declares one):
+
+| Tier | Agents | Use case |
+|---|---|---|
+| `light` | gsd-codebase-mapper, gsd-pattern-mapper, gsd-research-synthesizer, gsd-plan-checker, gsd-integration-checker, gsd-nyquist-auditor, gsd-ui-checker, gsd-ui-auditor, gsd-doc-verifier | Cheap/fast — pure mappers, scanners, low-stakes audits |
+| `standard` | gsd-executor, gsd-phase-researcher, gsd-project-researcher, gsd-verifier, gsd-doc-writer, gsd-ui-researcher | Default workhorse — research, writing, primary verification |
+| `heavy` | gsd-planner, gsd-roadmapper, gsd-debugger | Deep reasoning — already at top, can't escalate further |
+
+**Escalation flow** (orchestrator-driven):
+
+1. Orchestrator spawns agent with `attempt: 0` → resolver returns `tier_models[default_tier]`
+2. If orchestrator marks the result a soft failure, it re-spawns with `attempt: 1` → resolver returns `tier_models[next_tier_up]`
+3. `max_escalations` caps total retries (default 1). Beyond the cap the resolver returns the cap-tier model so the orchestrator can log without burning further budget.
+4. Hard failures (exceptions) bypass escalation and surface immediately.
+
+**Precedence with other tier sources** (highest → lowest):
+
+1. `model_overrides[<agent>]` — full ID, always wins
+2. `dynamic_routing.tier_models[escalated_tier]` — when `enabled: true`
+3. `models[<phase_type>]` — coarse phase-level (#3023)
+4. `model_profile` — global tier strategy
+
+When `dynamic_routing.enabled = false` (default), behavior is identical to today.
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning. The full precedence ladder
+is (highest → lowest):
+
+```text
+1. Read .planning/config.json
+2. Check model_overrides[<agent>] (full IDs accepted; targeted exceptions)
+3. If dynamic_routing.enabled, return tier_models[escalated_tier]
+   (see §Dynamic Routing — escalation steps tier up per attempt counter)
+4. If no dynamic_routing match, check models[phase_type] for a phase-type tier
+   (see §Per-Phase-Type Model Map for the agent → phase-type mapping)
+5. If no phase-type slot, look up agent in profile table
+6. Pass model parameter to Task call
+```
+
+The same precedence applies to `reasoning_effort` resolution on runtimes
+that support it (Codex), so `model` and `reasoning_effort` always derive
+from the same tier source — a `models[phase_type]` or
+`dynamic_routing` override flips both.
+
+## Per-Agent Overrides
+
+Override specific agents without changing the entire profile:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "gsd-executor": "opus",
+    "gsd-planner": "haiku"
+  }
+}
+```
+
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g., `"o3"`, `"openai/o3"`, `"google/gemini-2.5-pro"`).
+
+## Switching Profiles
+
+Runtime: `/gsd-set-profile <profile>`
+
+Per-project default: Set in `.planning/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## Design Rationale
+
+**Why Opus for gsd-planner?**
+Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+
+**Why Sonnet for gsd-executor?**
+Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
+
+**Why Sonnet (not Haiku) for verifiers in balanced?**
+Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+
+**Why Haiku for gsd-codebase-mapper?**
+Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
+
+**Why `inherit` instead of passing `opus` directly?**
+Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. GSD returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.
+
+**Why `inherit` profile?**
+Some runtimes (including OpenCode) let users switch models at runtime (`/model`). The `inherit` profile keeps all GSD subagents aligned to that live selection.

package/get-shit-done/references/mvp-concepts.md

@@ -0,0 +1,49 @@
+# MVP Concepts — index
+
+Cross-reference for the six MVP-related reference files. Each file has a single, narrow purpose. This index exists so future readers (and agents resolving `@`-refs) can find the right file without grepping the directory.
+
+Canonical domain terms for the concepts named below live in [CONTEXT.md](../../CONTEXT.md) under "Domain terms" — start there if you need a precise definition.
+
+## File map
+
+| File | Purpose | Loaded by |
+|---|---|---|
+| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
+| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gsd-planner` agent when the Walking Skeleton gate fires |
+| `references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header |
+| `references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gsd-mvp-phase` workflow when the user story exceeds size threshold |
+| `references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
+| `references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gsd-verifier` agent when the phase under verification has `mode: mvp` |
+
+## Concept-to-file map
+
+If you're looking for the canonical statement of a concept, this is where to find it:
+
+- **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `execute-phase.md` and `verify-work.md`.
+- **`**Mode:** mvp` parser** — `get-shit-done/bin/lib/roadmap.cjs` (`searchPhaseInContent` + `cmdRoadmapAnalyze`). Workflows compare against the parser output, never re-parse.
+- **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `gsd-verifier` (the user-story-format guard) and `gsd-mvp-phase` (interactive validation).
+- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
+- **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
+- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
+- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
+- **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
+- **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
+
+## Interactions worth knowing
+
+- **`--mvp` and `--prd <file>` together on Phase 1.** Both paths converge at the planner spawn. The PRD express path creates `CONTEXT.md` from the PRD file and continues to the research step; the Walking Skeleton gate fires independently when Phase 1 + new project + `--mvp`. The planner therefore receives both `WALKING_SKELETON=true` and PRD-derived context. This is intentional: the PRD informs what the skeleton should prove.
+- **`MVP_MODE` is all-or-nothing per phase, not per task.** A phase is either MVP-mode or standard. Mixed-mode phases are not supported (PRD #2826 Q1).
+- **`TDD_MODE` is independent of `MVP_MODE`.** TDD can be on without MVP, MVP can be on without TDD. Only the *intersection* (both true) activates the MVP+TDD Gate.
+- **The `gsd-roadmapper` agent makes the MVP/standard decision once at project init** based on `PROJECT_MODE`. Per-phase opt-in/out happens later via `/gsd:mvp-phase` or `/gsd-edit-phase`.
+
+## Tests
+
+Structural contract tests for each integration site live under `tests/`:
+
+- `plan-phase-mvp-flag.test.cjs` — plan-phase MVP_MODE resolution chain
+- `planner-mvp-mode.test.cjs` — gsd-planner agent MVP section
+- `mvp-phase-command.test.cjs`, `mvp-phase-integration.test.cjs`, `mvp-phase-spidr.test.cjs` — `/gsd:mvp-phase`
+- `execute-mvp-tdd-gate.test.cjs`, `executor-mvp-tdd-section.test.cjs` — MVP+TDD Gate
+- `verifier-mvp-section.test.cjs`, `verify-mvp-uat.test.cjs` — verifier UAT framing
+- `new-project-mvp-prompt.test.cjs` — mode prompt at init
+- `progress-mvp-display.test.cjs`, `stats-mvp-display.test.cjs`, `graphify-mvp-viz.test.cjs` — discovery surfaces

package/get-shit-done/references/phase-argument-parsing.md

@@ -0,0 +1,61 @@
+# Phase Argument Parsing
+
+Parse and normalize phase arguments for commands that operate on phases.
+
+## Extraction
+
+From `$ARGUMENTS`:
+- Extract phase number (first numeric argument)
+- Extract flags (prefixed with `--`)
+- Remaining text is description (for insert/add commands)
+
+## Using gsd-tools
+
+The `find-phase` command handles normalization and validation in one step:
+
+```bash
+PHASE_INFO=$(gsd-sdk query find-phase "${PHASE}")
+```
+
+Returns JSON with:
+- `found`: true/false
+- `directory`: Full path to phase directory
+- `phase_number`: Normalized number (e.g., "06", "06.1")
+- `phase_name`: Name portion (e.g., "foundation")
+- `plans`: Array of PLAN.md files
+- `summaries`: Array of SUMMARY.md files
+
+## Manual Normalization (Legacy)
+
+Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
+
+```bash
+# Normalize phase number
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  # Integer: 8 → 08
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  # Decimal: 2.1 → 02.1
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+## Validation
+
+Use `roadmap get-phase` to validate phase exists:
+
+```bash
+PHASE_CHECK=$(gsd-sdk query roadmap.get-phase "${PHASE}" --pick found)
+if [ "$PHASE_CHECK" = "false" ]; then
+  echo "ERROR: Phase ${PHASE} not found in roadmap"
+  exit 1
+fi
+```
+
+## Directory Lookup
+
+Use `find-phase` for directory lookup:
+
+```bash
+PHASE_DIR=$(gsd-sdk query find-phase "${PHASE}" --raw)
+```

package/get-shit-done/references/planner-antipatterns.md

@@ -0,0 +1,89 @@
+# Planner Anti-Patterns and Specificity Examples
+
+> Reference file for gsd-planner agent. Loaded on-demand via `@` reference.
+> For sub-200K context windows, this content is stripped from the agent prompt and available here for on-demand loading.
+
+## Checkpoint Anti-Patterns
+
+### Bad — Asking human to automate
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com, import repo, click deploy...</instructions>
+</task>
+```
+
+**Why bad:** Vercel has a CLI. Claude should run `vercel --yes`. Never ask the user to do what Claude can automate via CLI/API.
+
+### Bad — Too many checkpoints
+
+```xml
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+```
+
+**Why bad:** Verification fatigue. Users should not be asked to verify every small step. Combine into one checkpoint at the end of meaningful work.
+
+### Good — Single verification checkpoint
+
+```xml
+<task type="auto">Create schema</task>
+<task type="auto">Create API</task>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+</task>
+```
+
+### Bad — Mixing checkpoints with implementation
+
+A plan should not interleave multiple checkpoint types with implementation tasks. Checkpoints belong at natural verification boundaries, not scattered throughout.
+
+## Specificity Examples
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "Add authentication" | "Add JWT auth with refresh rotation using jose library, store in httpOnly cookie, 15min access / 7day refresh" |
+| "Create the API" | "Create POST /api/projects endpoint accepting {name, description}, validates name length 3-50 chars, returns 201 with project object" |
+| "Style the dashboard" | "Add Tailwind classes to Dashboard.tsx: grid layout (3 cols on lg, 1 on mobile), card shadows, hover states on action buttons" |
+| "Handle errors" | "Wrap API calls in try/catch, return {error: string} on 4xx/5xx, show toast via sonner on client" |
+| "Set up the database" | "Add User and Project models to schema.prisma with UUID ids, email unique constraint, createdAt/updatedAt timestamps, run prisma db push" |
+
+**Specificity test:** Could a different Claude instance execute the task without asking clarifying questions? If not, add more detail.
+
+## Context Section Anti-Patterns
+
+### Bad — Reflexive SUMMARY chaining
+
+```markdown
+<context>
+@.planning/phases/01-foundation/01-01-SUMMARY.md
+@.planning/phases/01-foundation/01-02-SUMMARY.md  <!-- Does Plan 02 actually need Plan 01's output? -->
+@.planning/phases/01-foundation/01-03-SUMMARY.md  <!-- Chain grows, context bloats -->
+</context>
+```
+
+**Why bad:** Plans are often independent. Reflexive chaining (02 refs 01, 03 refs 02...) wastes context. Only reference prior SUMMARY files when the plan genuinely uses types/exports from that prior plan or a decision from it affects the current plan.
+
+### Good — Selective context
+
+```markdown
+<context>
+@.planning/PROJECT.md
+@.planning/STATE.md
+@.planning/phases/01-foundation/01-01-SUMMARY.md  <!-- Uses User type defined in Plan 01 -->
+</context>
+```
+
+## Scope Reduction Anti-Patterns
+
+**Prohibited language in task actions:**
+- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
+- "future enhancement", "placeholder", "basic version", "minimal implementation"
+- "will be wired later", "dynamic in future phase", "skip for now"
+
+If a decision from CONTEXT.md says "display cost calculated from billing table in impulses", the plan must deliver exactly that. Not "static label /min" as a "v1". If the phase is too complex, recommend a phase split instead of silently reducing scope.

package/get-shit-done/references/planner-chunked.md

@@ -0,0 +1,49 @@
+# Chunked Mode Return Formats
+
+Used when `plan-phase` spawns `gsd-planner` with `CHUNKED_MODE=true` (triggered by `--chunked`
+flag or `workflow.plan_chunked: true` config). Splits the single long-lived planner Task into
+shorter-lived Tasks to bound the blast radius of Windows stdio hangs.
+
+## Modes
+
+### outline-only
+
+Write **only** `{PHASE_DIR}/{PADDED_PHASE}-PLAN-OUTLINE.md`. Do not write any PLAN.md files.
+Return:
+
+```markdown
+## OUTLINE COMPLETE
+
+**Phase:** {phase-name}
+**Plans:** {N} plan(s) in {M} wave(s)
+
+| Plan ID | Objective | Wave | Depends On | Requirements |
+|---------|-----------|------|-----------|-------------|
+| {padded_phase}-01 | [brief objective] | 1 | none | REQ-001, REQ-002 |
+| {padded_phase}-02 | [brief objective] | 1 | none | REQ-003 |
+```
+
+The orchestrator reads this table, then spawns one single-plan Task per row.
+
+### single-plan
+
+Write **exactly one** `{PHASE_DIR}/{plan_id}-PLAN.md`. Do not write any other plan files.
+Return:
+
+```markdown
+## PLAN COMPLETE
+
+**Plan:** {plan-id}
+**Objective:** {brief}
+**File:** {PHASE_DIR}/{plan-id}-PLAN.md
+**Tasks:** {N}
+```
+
+The orchestrator verifies the file exists on disk after each return, commits it, then moves
+to the next plan entry from the outline.
+
+## Resume Behaviour
+
+If the orchestrator detects that `PLAN-OUTLINE.md` already exists (from a prior interrupted
+run), it skips the outline-only Task and goes directly to single-plan Tasks, skipping any
+`{plan_id}-PLAN.md` files that already exist on disk.

package/get-shit-done/references/planner-gap-closure.md

@@ -0,0 +1,62 @@
+# Gap Closure Mode — Planner Reference
+
+Triggered by `--gaps` flag. Creates plans to address verification or UAT failures.
+
+**Important: Skip deferred items.** When reading VERIFICATION.md, only the `gaps:` section contains actionable items that need closure plans. The `deferred:` section (if present) lists items explicitly addressed in later milestone phases — these are NOT gaps and must be ignored during gap closure planning. Creating plans for deferred items wastes effort on work already scheduled for future phases.
+
+**1. Find gap sources:**
+
+Use init context (from load_project_state) which provides `phase_dir`:
+
+```bash
+# Check for VERIFICATION.md (code verification gaps)
+ls "$phase_dir"/*-VERIFICATION.md 2>/dev/null
+
+# Check for UAT.md with diagnosed status (user testing gaps)
+grep -l "status: diagnosed" "$phase_dir"/*-UAT.md 2>/dev/null
+```
+
+**2. Parse gaps:** Each gap has: truth (failed behavior), reason, artifacts (files with issues), missing (things to add/fix).
+
+**3. Load existing SUMMARYs** to understand what's already built.
+
+**4. Find next plan number:** If plans 01-03 exist, next is 04.
+
+**5. Group gaps into plans** by: same artifact, same concern, dependency order (can't wire if artifact is stub → fix stub first).
+
+**6. Create gap closure tasks:**
+
+```xml
+<task name="{fix_description}" type="auto">
+  <files>{artifact.path}</files>
+  <action>
+    {For each item in gap.missing:}
+    - {missing item}
+
+    Reference existing code: {from SUMMARYs}
+    Gap reason: {gap.reason}
+  </action>
+  <verify>{How to confirm gap is closed}</verify>
+  <done>{Observable truth now achievable}</done>
+</task>
+```
+
+**7. Assign waves using standard dependency analysis** (same as `assign_waves` step):
+- Plans with no dependencies → wave 1
+- Plans that depend on other gap closure plans → max(dependency waves) + 1
+- Also consider dependencies on existing (non-gap) plans in the phase
+
+**8. Write PLAN.md files:**
+
+```yaml
+---
+phase: XX-name
+plan: NN              # Sequential after existing
+type: execute
+wave: N               # Computed from depends_on (see assign_waves)
+depends_on: [...]     # Other plans this depends on (gap or existing)
+files_modified: [...]
+autonomous: true
+gap_closure: true     # Flag for tracking
+---
+```

package/get-shit-done/references/planner-graphify-auto-update.md

@@ -0,0 +1,67 @@
+# Graphify Auto-Update — Status Surfacing
+
+> Documents how `gsd-planner` and `gsd-phase-researcher` surface the opt-in graphify auto-update state (issue #3347). The status surface lives inside `graphifyStatus()` in `get-shit-done/bin/lib/graphify.cjs`; no planner-side prompt changes are required.
+
+## Why this exists
+
+The graph at `.planning/graphs/graph.json` is consumed automatically (every `gsd-planner` and `gsd-phase-researcher` step) but produced manually (`/gsd:graphify build` per session at best). Without auto-update, the producer-consumer gap silently widens with every commit. The existing `stale: true` annotation tells the consumer the mtime is old; it cannot tell the consumer whether the auto-build hook has been running, just failed, or is in flight.
+
+When `graphify.auto_update: true`, the bundled `hooks/gsd-graphify-update.sh` PostToolUse hook fires after HEAD-advancing git operations on the default branch and dispatches `graphify update .` in a detached subprocess. The hook writes a status file synchronously before detach; the detached process rewrites it on completion.
+
+## The status file
+
+`.planning/graphs/.last-build-status.json`:
+
+```json
+{
+  "ts": "2026-05-15T14:02:23Z",
+  "status": "running" | "ok" | "failed",
+  "exit_code": null | <int>,
+  "duration_ms": null | <int>,
+  "head_at_build": "<commit-sha>",
+  "graphify_version": null | "<version>"
+}
+```
+
+The hook writes `status: "running"` synchronously **before** detach, so the next planner invocation can see the in-flight signal even if `graphify update .` has not finished. The detached `hooks/lib/gsd-graphify-rebuild.sh` rewrites the file to `ok` or `failed` on completion (with `exit_code` and `duration_ms`).
+
+## How the planner surfaces it (zero new prompt content)
+
+`graphifyStatus()` in `get-shit-done/bin/lib/graphify.cjs` reads `.last-build-status.json` and folds the `running` / `failed` states into the existing `stale: true` signal:
+
+```javascript
+const autoUpdateStale =
+  lastBuildAutoUpdate &&
+  (lastBuildAutoUpdate.status === 'failed' || lastBuildAutoUpdate.status === 'running');
+
+return {
+  ...
+  stale: age > STALE_MS || Boolean(autoUpdateStale),
+  ...
+  last_build_auto_update: lastBuildAutoUpdate || null,
+};
+```
+
+The planner and researcher already run `node ... graphify status` inside their `<step name="load_graph_context">` blocks and already have the rule:
+
+> If the status response has `stale: true`, note for later: "Graph is `{age_hours}h` old — treat semantic relationships as approximate."
+
+That rule now fires correctly in three additional cases:
+
+| Trigger | What user sees |
+|---------|----------------|
+| Auto-build status = `failed` | Existing "treat as approximate" note fires (because `stale: true`). The full `last_build_auto_update` object is in the JSON for callers that want exit-code / duration / commit-sha context. |
+| Auto-build status = `running` | Same — the next planner invocation knows the graph is mid-rebuild and treats it as approximate until the detached process completes. |
+| Auto-build status = `ok` AND mtime < 24h | Annotation is silent — the graph is fresh and the most recent auto-build succeeded. |
+
+The file-missing case is silent (the operator either has not opted in or has not yet triggered a HEAD-advancing git op since enabling).
+
+## Why this design
+
+- **No planner-side prompt changes.** Folding into `stale: true` reuses the existing rule, which means no new content in `agents/gsd-planner.md` (which is already at the `< 48K` decomposition limit per `DEFECT.AGENT-FILE-SIZE-CAP-BREACH`).
+- **Tests catch regressions on the seam.** `tests/feat-3347-graphify-auto-update-config.test.cjs` pins `graphifyStatus` behavior for status=`failed` / `running` / `ok` / file-missing.
+- **Backwards compatible.** Callers that don't read `last_build_auto_update` see the same shape as before, with `stale` reflecting both mtime AND auto-build state. No consumer breakage.
+
+## Opt-in reminder
+
+The auto-update mechanism is opt-in (`graphify.auto_update: false` by default per issue #3347). Users who haven't opted in will never produce this file. `graphifyStatus()` returns `last_build_auto_update: null` and falls back to the mtime-only `stale` rule.