@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -63,6 +63,8 @@
     "workflow.context_guard_mode",
     "executor.stall_detect_interval_minutes",
     "executor.stall_threshold_minutes",
+    "planner.stall_detect_interval_minutes",
+    "planner.stall_threshold_minutes",
     "workflow.inline_plan_threshold",
     "hooks.context_warnings",
     "hooks.workflow_guard",

package/gsd-core/references/artifact-types.md

@@ -43,6 +43,13 @@ reads is inert — the consumption mechanism is what gives an artifact meaning.
 - **Lifecycle**: Created at plan completion → Read by subsequent plans in same phase
 - **Location**: `.planning/phases/XX-name/XX-YY-SUMMARY.md`
 - **Consumed by**: Orchestrator (progress), planner (context for future plans), `milestone-summary`
+- **`status:`** — `complete` (default) or **`halted`**. `halted` records a *designed stop*:
+  the plan ran and answered its question, but the answer means the work it was gating cannot
+  proceed (a spike that returns "no", for example). It is a success, not a failure — the plan
+  did its job. Marking a SUMMARY `halted` propagates transitively over `depends_on`: every
+  plan that depends on it, directly or through a chain, is reported as **blocked** rather than
+  offered to the executor as ordinary incomplete work, and is named with its cause. Any other
+  value — including no `status:` field at all — reads as complete. (#2830)
 
 ### HANDOFF.json / .continue-here.md
 - **Shape**: Structured pause state (JSON machine-readable + Markdown human-readable)
@@ -72,11 +79,11 @@ reads is inert — the consumption mechanism is what gives an artifact meaning.
 - **Location**: `.planning/spikes/SPIKE-NNN/`
 - **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
 
-### Spike README.md / MANIFEST.md (per-spike, via /gsd:spike)
-- **Shape**: YAML frontmatter (spike, name, validates, verdict, related, tags) + run instructions + results
+### Spike README.md (per-spike) / MANIFEST.md (per-project index, via /gsd:spike)
+- **Shape**: README — YAML frontmatter (spike, idea, name, validates, verdict, related, tags) + run instructions + results. MANIFEST.md — one `### {idea-key}` section per idea under `## Ideas` (idea paragraph + its own scoped Requirements), plus one durable `## Spikes` table (with an Idea column) indexing every spike across every idea.
 - **Lifecycle**: Created by `/gsd:spike` → Verified → Wrapped up by `/gsd-spike-wrap-up`
 - **Location**: `.planning/spikes/NNN-name/README.md`, `.planning/spikes/MANIFEST.md`
-- **Consumed by**: `/gsd-spike-wrap-up` for curation; `pause-work` for spike context handoff
+- **Consumed by**: `/gsd-spike-wrap-up` for curation (Requirements pulled only from the idea key(s) it wraps); `pause-work` for spike context handoff
 
 ### Sketch README.md / MANIFEST.md / index.html (per-sketch)
 - **Shape**: YAML frontmatter (sketch, name, question, winner, tags) + variants as tabbed HTML

package/gsd-core/references/autonomous-ui-design-contract.md

@@ -0,0 +1,42 @@
+# UI Design Contract (Frontend Phases) — Autonomous Mode
+
+Step 3a.5 of `/gsd:autonomous`: resolve whether the current phase needs a UI-SPEC.md generated before planning, and generate one via active `plan:pre` step hooks if so. Always non-blocking — proceeds to step 3b (Plan) regardless of outcome.
+
+**Inputs:** `PHASE_NUM`, `PHASE_DIR` from execute_phase.
+
+Resolve active `plan:pre` hooks:
+
+```bash
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+HOOKS_JSON=$(gsd_run loop render-hooks plan:pre --raw)
+```
+
+Read the `activeHooks` array directly from `HOOKS_JSON` (in-context — do NOT invoke a shell pipeline). **Compute the active UI step hooks** = entries from `activeHooks` where `kind == "step"` and `ref.skill` is set. **If there are NO active step hooks → skip silently to 3b.** (This covers `workflow.ui_phase=false` — including configurations where only a gate-only entry is present, e.g. `ui_phase=false` + `ui_safety_gate=true` produces `activeHooks=[{kind:"gate"}]`. Autonomous never runs the plan:pre gate — it is always pipeline mode — so a gate-only active set is equivalent to no active step and is silently skipped here. This matches OLD §3a.5 behaviour.)
+
+(At least one active step hook ⇒ `workflow.ui_phase` is on.) Run the UI-SPEC gate:
+
+```bash
+GATE=$(gsd_run check ui-plan-gate "${PHASE_NUM}" --raw)
+```
+
+Read `frontend` and `hasUiSpec` from `GATE` (in-context).
+
+**If `frontend` is false:** Skip silently to 3b.
+
+**If `hasUiSpec` is true (UI-SPEC already exists):** Skip silently to 3b.
+
+**Otherwise (frontend phase + no UI-SPEC):** For each active step hook (the `kind == "step"` set from above, in array order):
+
+```
+Skill(skill="gsd-${ref.skill}", args="${PHASE_NUM}")
+```
+
+(Prepend `gsd-` to `ref.skill` — so `ui-phase` → `gsd-ui-phase`. Bare `${PHASE_NUM}` args — autonomous style, same pattern as the verify:post dispatch.) Entries where `kind == "gate"` are silently ignored — autonomous is always pipeline mode, there is no blocking gate here.
+
+After all step hooks return, re-read:
+
+```bash
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+```
+
+**If `UI_SPEC_FILE` is still empty:** Display warning `Phase ${PHASE_NUM}: UI-SPEC generation did not produce output — continuing without design contract.` and proceed to 3b. NON-BLOCKING.

package/gsd-core/references/debugger-techniques.md

@@ -0,0 +1,255 @@
+# Debugger technique catalog
+
+Full technique bodies for `agents/gsd-debugger.md`, extracted per
+`DEFECT.AGENT-FILE-SIZE-CAP-BREACH` (issue #2995, epic #1671 Phase 6.4). The agent
+keeps each technique's name and routing entry; the step-by-step detail lives here.
+
+## Binary Search / Divide and Conquer
+
+**When:** Large codebase, long execution path, many possible failure points.
+
+**How:** Cut problem space in half repeatedly until you isolate the issue.
+
+1. Identify boundaries (where works, where fails)
+2. Add logging/testing at midpoint
+3. Determine which half contains the bug
+4. Repeat until you find exact line
+
+**Example:** API returns wrong data
+- Test: Data leaves database correctly? YES
+- Test: Data reaches frontend correctly? NO
+- Test: Data leaves API route correctly? YES
+- Test: Data survives serialization? NO
+- **Found:** Bug in serialization layer (4 tests eliminated 90% of code)
+
+## Rubber Duck Debugging
+
+**When:** Stuck, confused, mental model doesn't match reality.
+
+**How:** Explain the problem out loud in complete detail.
+
+Write or say:
+1. "The system should do X"
+2. "Instead it does Y"
+3. "I think this is because Z"
+4. "The code path is: A -> B -> C -> D"
+5. "I've verified that..." (list what you tested)
+6. "I'm assuming that..." (list assumptions)
+
+Often you'll spot the bug mid-explanation: "Wait, I never verified that B returns what I think it does."
+
+## Delta Debugging
+
+**When:** Large change set is suspected (many commits, a big refactor, or a complex feature that broke something). Also when "comment out everything" is too slow.
+
+**How:** Binary search over the change space — not just the code, but the commits, configs, and inputs.
+
+**Over commits (use git bisect):**
+Already covered under Git Bisect. But delta debugging extends it: after finding the breaking commit, delta-debug the commit itself — identify which of its N changed files/lines actually causes the failure.
+
+**Over code (systematic elimination):**
+1. Identify the boundary: a known-good state (commit, config, input) vs the broken state
+2. List all differences between good and bad states
+3. Split the differences in half. Apply only half to the good state.
+4. If broken: bug is in the applied half. If not: bug is in the other half.
+5. Repeat until you have the minimal change set that causes the failure.
+
+**Over inputs:**
+1. Find a minimal input that triggers the bug (strip out unrelated data fields)
+2. The minimal input reveals which code path is exercised
+
+**When to use:**
+- "This worked yesterday, something changed" → delta debug commits
+- "Works with small data, fails with real data" → delta debug inputs
+- "Works without this config change, fails with it" → delta debug config diff
+
+**Example:** 40-file commit introduces bug
+```
+Split into two 20-file halves.
+Apply first 20: still works → bug in second half.
+Split second half into 10+10.
+Apply first 10: broken → bug in first 10.
+... 6 splits later: single file isolated.
+```
+
+## Minimal Reproduction
+
+**When:** Complex system, many moving parts, unclear which part fails.
+
+**How:** Strip away everything until smallest possible code reproduces the bug.
+
+1. Copy failing code to new file
+2. Remove one piece (dependency, function, feature)
+3. Test: Does it still reproduce? YES = keep removed. NO = put back.
+4. Repeat until bare minimum
+5. Bug is now obvious in stripped-down code
+6. **Shrinking (input-space bugs)** — when the bug triggers on a class of inputs, wrap it in a property (fast-check for JS/TS, Hypothesis for Python) and let the shrinker auto-minimize the counterexample; store the **minimized** input as the regression seed. See `gsd-core/references/debugger-repro-hardening.md`.
+
+**Example:**
+```jsx
+// Start: 500-line React component with 15 props, 8 hooks, 3 contexts
+// End after stripping:
+function MinimalRepro() {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    setCount(count + 1); // Bug: infinite loop, missing dependency array
+  });
+
+  return <div>{count}</div>;
+}
+// The bug was hidden in complexity. Minimal reproduction made it obvious.
+```
+
+## Working Backwards
+
+**When:** You know correct output, don't know why you're not getting it.
+
+**How:** Start from desired end state, trace backwards.
+
+1. Define desired output precisely
+2. What function produces this output?
+3. Test that function with expected input - does it produce correct output?
+   - YES: Bug is earlier (wrong input)
+   - NO: Bug is here
+4. Repeat backwards through call stack
+5. Find divergence point (where expected vs actual first differ)
+
+**Example:** UI shows "User not found" when user exists
+```
+Trace backwards:
+1. UI displays: user.error → Is this the right value to display? YES
+2. Component receives: user.error = "User not found" → Correct? NO, should be null
+3. API returns: { error: "User not found" } → Why?
+4. Database query: SELECT * FROM users WHERE id = 'undefined' → AH!
+5. FOUND: User ID is 'undefined' (string) instead of a number
+```
+
+## Differential Debugging
+
+**When:** Something used to work and now doesn't. Works in one environment but not another.
+
+**Time-based (worked, now doesn't):**
+- What changed in code since it worked?
+- What changed in environment? (Node version, OS, dependencies)
+- What changed in data?
+- What changed in configuration?
+
+**Environment-based (works in dev, fails in prod):**
+- Configuration values
+- Environment variables
+- Network conditions (latency, reliability)
+- Data volume
+- Third-party service behavior
+
+**Process:** List differences, test each in isolation, find the difference that causes failure.
+
+**Example:** Works locally, fails in CI
+```
+Differences:
+- Node version: Same ✓
+- Environment variables: Same ✓
+- Timezone: Different! ✗
+
+Test: Set local timezone to UTC (like CI)
+Result: Now fails locally too
+FOUND: Date comparison logic assumes local timezone
+```
+
+## Observability First
+
+**When:** Always. Before making any fix.
+
+**Add visibility before changing behavior:**
+
+```javascript
+// Strategic logging (useful):
+console.log('[handleSubmit] Input:', { email, password: '***' });
+console.log('[handleSubmit] Validation result:', validationResult);
+console.log('[handleSubmit] API response:', response);
+
+// Assertion checks:
+console.assert(user !== null, 'User is null!');
+console.assert(user.id !== undefined, 'User ID is undefined!');
+
+// Timing measurements:
+console.time('Database query');
+const result = await db.query(sql);
+console.timeEnd('Database query');
+
+// Stack traces at key points:
+console.log('[updateUser] Called from:', new Error().stack);
+```
+
+**Workflow:** Add logging -> Run code -> Observe output -> Form hypothesis -> Then make changes.
+
+## Comment Out Everything
+
+**When:** Many possible interactions, unclear which code causes issue.
+
+**How:**
+1. Comment out everything in function/file
+2. Verify bug is gone
+3. Uncomment one piece at a time
+4. After each uncomment, test
+5. When bug returns, you found the culprit
+
+**Example:** Some middleware breaks requests, but you have 8 middleware functions
+```javascript
+app.use(helmet()); // Uncomment, test → works
+app.use(cors()); // Uncomment, test → works
+app.use(compression()); // Uncomment, test → works
+app.use(bodyParser.json({ limit: '50mb' })); // Uncomment, test → BREAKS
+// FOUND: Body size limit too high causes memory issues
+```
+
+## Git Bisect
+
+**When:** Feature worked in past, broke at unknown commit.
+
+**How:** Binary search through git history.
+
+```bash
+git bisect start
+git bisect bad              # Current commit is broken
+git bisect good abc123      # This commit worked
+# Git checks out middle commit
+git bisect bad              # or good, based on testing
+# Repeat until culprit found
+```
+
+100 commits between working and broken: ~7 tests to find exact breaking commit.
+
+## Follow the Indirection
+
+**When:** Code constructs paths, URLs, keys, or references from variables — and the constructed value might not point where you expect.
+
+**The trap:** You read code that builds a path like `path.join(configDir, 'hooks')` and assume it's correct because it looks reasonable. But you never verified that the constructed path matches where another part of the system actually writes/reads.
+
+**How:**
+1. Find the code that **produces** the value (writer/installer/creator)
+2. Find the code that **consumes** the value (reader/checker/validator)
+3. Trace the actual resolved value in both — do they agree?
+4. Check every variable in the path construction — where does each come from? What's its actual value at runtime?
+
+**Common indirection bugs:**
+- Path A writes to `dir/sub/hooks/` but Path B checks `dir/hooks/` (directory mismatch)
+- Config value comes from cache/template that wasn't updated
+- Variable is derived differently in two places (e.g., one adds a subdirectory, the other doesn't)
+- Template placeholder (`{{VERSION}}`) not substituted in all code paths
+
+**Example:** Stale hook warning persists after update
+```
+Check code says:  hooksDir = path.join(configDir, 'hooks')
+                  configDir = ~/.claude
+                  → checks ~/.claude/hooks/
+
+Installer says:   hooksDest = path.join(targetDir, 'hooks')
+                  targetDir = ~/.claude/gsd-core
+                  → writes to ~/.claude/gsd-core/hooks/
+
+MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as stale
+```
+
+**The discipline:** Never assume a constructed path is correct. Resolve it to its actual value and verify the other side agrees. When two systems share a resource (file, directory, key), trace the full path in both.
+

package/gsd-core/references/research-documentation-lookup.md

@@ -2,10 +2,12 @@ When you need library or framework documentation, check in this order:
 
 1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
    - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
-   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+   - Fetch docs: `mcp__context7__query-docs` with `libraryId` (the ID from step 1) and `query`
 
-2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
-   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+2. If Context7 MCP is not available (custom subagents cannot see project-scoped
+   `.mcp.json` servers — they only inherit user-scoped `~/.claude/mcp.json`, so a
+   context7 server configured at the project scope is invisible to spawned
+   agents), use the CLI fallback via Bash:
 
    Step 1 — Resolve library ID:
    ```bash

package/gsd-core/references/specless-probe-fallback.md

@@ -119,16 +119,17 @@ if [ "$APPLICABLE" = "0" ]; then
 fi
 ```
 
-**Edge `--auto` resolution rules (reuse spec-phase 5.5 verbatim, D-06):** auto-`covered` where a
-defensible acceptance criterion can be written (→ a plain `must_haves.truths` string); else
-auto-`backstop` → author it as a **structured flat-scalar marker** `{ statement: <the check>,
+**Edge `--auto` resolution rules (reuse spec-phase 5.5 verbatim, D-06):** auto-`resolved`
+(verification: explicit) where a defensible acceptance criterion can be written (→ a plain
+`must_haves.truths` string); else auto-`resolved` (verification: backstop) → author it as a
+**structured flat-scalar marker** `{ statement: <the check>,
 verification: backstop }` in `must_haves.truths`, NOT a prose note (the verifier branches
 deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110
 fragility; flat scalar `verification:` key, never a nested object, ADR-550 #1278). A `backstop` truth
 the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason
 `insufficient_spec`), never a silent pass (#1154; `references/honest-verifier.md`). **Never
 auto-dismiss** (a wrong dismissal is the exact silent failure this eliminates). An `unclassified` row
-stays **`unresolved`** (#1110) — never auto-`backstop`ped — and is surfaced to the planner as a flagged
+stays **`unresolved`** (#1110) — never auto-resolved with backstop — and is surfaced to the planner as a flagged
 assumption. Pass `$COVERAGE` (+ the gate's `$SPECLESS_FALLBACK_DISABLED` note) into the gsd-planner
 prompt (Step 8). When `EDGE_ABSENT=0`, `$COVERAGE` is empty and this does not run.
 
@@ -159,8 +160,8 @@ assumption — never a silent drop.
 Author the fallback report into `must_haves` with the SAME lift the SPEC path uses — only the source
 changes (the fallback report, not the SPEC):
 
-- **Edges →** every `covered` edge's acceptance criterion → `must_haves.truths` as a plain string;
-  every `backstop` edge → `must_haves.truths` as a structured `{ statement, verification: backstop }`
+- **Edges →** every resolved (verification: explicit) edge's acceptance criterion → `must_haves.truths` as a plain string;
+  every resolved (verification: backstop) edge → `must_haves.truths` as a structured `{ statement, verification: backstop }`
   marker (NOT prose; #1110/#1278), which abstains → `human_needed` at verify time when unconfirmed
   (#1154); every `unresolved`/`unclassified` row → an explicit flagged assumption (never a silent drop).
 - **Prohibitions →** every kept prohibition → the `must_haves.prohibitions:` sibling block (NOT

package/gsd-core/references/verifier-wiring-patterns.md

@@ -0,0 +1,100 @@
+# Verifier wiring and data-flow patterns
+
+Full pattern bodies for `agents/gsd-verifier.md`, extracted per
+`DEFECT.AGENT-FILE-SIZE-CAP-BREACH` (issue #2995, epic #1671 Phase 6.4). The agent
+keeps the step and its checklist; the per-pattern detail and shell recipes live here.
+
+Artifacts that pass Levels 1-3 (exist, substantive, wired) can still be hollow if their data source produces empty or hardcoded values. Level 4 traces upstream from the artifact to verify real data flows through the wiring.
+
+**When to run:** For each artifact that passes Level 3 (WIRED) and renders dynamic data (components, pages, dashboards — not utilities or configs).
+
+**How:**
+
+1. **Identify the data variable** — what state/prop does the artifact render?
+
+```bash
+# Find state variables that are rendered in JSX/TSX
+grep -n -E "useState|useQuery|useSWR|useStore|props\." "$artifact" 2>/dev/null
+```
+
+2. **Trace the data source** — where does that variable get populated?
+
+```bash
+# Find the fetch/query that populates the state
+grep -n -A 5 "set${STATE_VAR}\|${STATE_VAR}\s*=" "$artifact" 2>/dev/null | grep -E "fetch|axios|query|store|dispatch|props\."
+```
+
+3. **Verify the source produces real data** — does the API/store return actual data or static/empty values?
+
+```bash
+# Check the API route or data source for real DB queries vs static returns
+grep -n -E "prisma\.|db\.|query\(|findMany|findOne|select|FROM" "$source_file" 2>/dev/null
+# Flag: static returns with no query
+grep -n -E "return.*json\(\s*\[\]|return.*json\(\s*\{\}" "$source_file" 2>/dev/null
+```
+
+4. **Check for disconnected props** — props passed to child components that are hardcoded empty at the call site
+
+```bash
+# Find where the component is used and check prop values
+grep -r -A 3 "<${COMPONENT_NAME}" "${search_path:-src/}" --include="*.tsx" 2>/dev/null | grep -E "=\{(\[\]|\{\}|null|''|\"\")\}"
+```
+
+> These two status tables are intentionally mirrored in `agents/gsd-verifier.md`.
+> The status vocabulary is load-bearing verifier output and must remain in the
+> agent body (#2995); this copy is here so the procedure below reads standalone.
+
+**Data-flow status:**
+
+| Data Source | Produces Real Data | Status |
+| ---------- | ------------------ | ------ |
+| DB query found | Yes | ✓ FLOWING |
+| Fetch exists, static fallback only | No | ⚠️ STATIC |
+| No data source found | N/A | ✗ DISCONNECTED |
+| Props hardcoded empty at call site | No | ✗ HOLLOW_PROP |
+
+**Final Artifact Status (updated with Level 4):**
+
+| Exists | Substantive | Wired | Data Flows | Status |
+| ------ | ----------- | ----- | ---------- | ------ |
+| ✓ | ✓ | ✓ | ✓ | ✓ VERIFIED |
+| ✓ | ✓ | ✓ | ✗ | ⚠️ HOLLOW — wired but data disconnected |
+| ✓ | ✓ | ✗ | - | ⚠️ ORPHANED |
+| ✓ | ✗ | - | - | ✗ STUB |
+| ✗ | - | - | - | ✗ MISSING |
+
+### Pattern: Component → API
+
+```bash
+grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component" 2>/dev/null
+grep -A 5 "fetch\|axios" "$component" | grep -E "await|\.then|setData|setState" 2>/dev/null
+```
+
+Status: WIRED (call + response handling) | PARTIAL (call, no response use) | NOT_WIRED (no call)
+
+### Pattern: API → Database
+
+```bash
+grep -E "prisma\.$model|db\.$model|$model\.(find|create|update|delete)" "$route" 2>/dev/null
+grep -E "return.*json.*\w+|res\.json\(\w+" "$route" 2>/dev/null
+```
+
+Status: WIRED (query + result returned) | PARTIAL (query, static return) | NOT_WIRED (no query)
+
+### Pattern: Form → Handler
+
+```bash
+grep -E "onSubmit=\{|handleSubmit" "$component" 2>/dev/null
+grep -A 10 "onSubmit.*=" "$component" | grep -E "fetch|axios|mutate|dispatch" 2>/dev/null
+```
+
+Status: WIRED (handler + API call) | STUB (only logs/preventDefault) | NOT_WIRED (no handler)
+
+### Pattern: State → Render
+
+```bash
+grep -E "useState.*$state_var|\[$state_var," "$component" 2>/dev/null
+grep -E "\{.*$state_var.*\}|\{$state_var\." "$component" 2>/dev/null
+```
+
+Status: WIRED (state displayed) | NOT_WIRED (state exists, not rendered)

package/gsd-core/references/worktree-branch-check.md

@@ -30,8 +30,8 @@ if [ "$HEAD_REF" = "DETACHED" ] || echo "$ACTUAL_BRANCH" | grep -Eq '^(main|mast
   echo "FATAL: worktree HEAD on '$ACTUAL_BRANCH' (expected agent-* or worktree-agent-*); refusing to commit or self-recover via 'git update-ref' (#2924)." >&2
   exit 42
 fi
-if ! echo "$ACTUAL_BRANCH" | grep -Eq '^(worktree-)?agent-[A-Za-z0-9._/-]+$'; then
-  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* namespace; refusing to commit (#2924)." >&2
+if ! echo "$ACTUAL_BRANCH" | grep -Eq '^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$'; then
+  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* / worktree-wf_* namespace; refusing to commit (#2924)." >&2
   exit 42
 fi
 ACTUAL_BASE=$(git rev-parse HEAD)

package/gsd-core/templates/summary-complex.md

@@ -28,6 +28,8 @@ completed: YYYY-MM-DD
 status: complete
 ---
 
+**Status (#2830):** `status: complete` is the default — the plan finished. Use `status: halted` instead when the plan reached a designed stop (a gate failure, a spike concluding without expanding into the full build, or any other intentional non-completion) and intentionally left tasks unfinished.
+
 # Phase [X]: [Name] Summary (Complex)
 
 **[Substantive one-liner describing outcome]**

package/gsd-core/templates/summary-minimal.md

@@ -25,6 +25,8 @@ completed: YYYY-MM-DD
 status: complete
 ---
 
+**Status (#2830):** `status: complete` is the default — the plan finished. Use `status: halted` instead when the plan reached a designed stop (a gate failure, a spike concluding without expanding into the full build, or any other intentional non-completion) and intentionally left tasks unfinished.
+
 # Phase [X]: [Name] Summary (Minimal)
 
 **[Substantive one-liner describing outcome]**

package/gsd-core/templates/summary-standard.md

@@ -27,6 +27,8 @@ completed: YYYY-MM-DD
 status: complete
 ---
 
+**Status (#2830):** `status: complete` is the default — the plan finished. Use `status: halted` instead when the plan reached a designed stop (a gate failure, a spike concluding without expanding into the full build, or any other intentional non-completion) and intentionally left tasks unfinished.
+
 # Phase [X]: [Name] Summary
 
 **[Substantive one-liner describing outcome]**

package/gsd-core/templates/summary.md

@@ -171,6 +171,8 @@ None - no external service configuration required.
 **Patterns:** Established conventions future phases should maintain.
 
 **Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
+
+**Status (#2830):** `status: complete` is the default — the plan finished. Use `status: halted` instead when the plan reached a designed stop (a gate failure, a spike concluding without expanding into the full build, or any other intentional non-completion) and intentionally left tasks unfinished. `halted` is machine-read: any plan whose `depends_on` (directly or transitively) names a halted plan is reported as blocked, not offered to the executor, until the halt is resolved and re-summarized as `complete`.
 </frontmatter_guidance>
 
 <coverage_guidance>

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

@@ -124,6 +124,9 @@ For each phase's VERIFICATION.md, extract the expanded requirements table:
 
 For each phase's SUMMARY.md, extract `requirements-completed` from YAML frontmatter:
 ```bash
+# #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

package/gsd-core/workflows/autonomous/steps/converge-banner.md

@@ -0,0 +1 @@
+If `PLAN_STRATEGY` is `converge`, display: `Planning: Plan-review convergence enabled`

package/gsd-core/workflows/autonomous/steps/converge-dispatch-bg.md

@@ -0,0 +1,11 @@
+## Converge Dispatch (Background)
+
+If `PLAN_STRATEGY=converge`, print: `◆ Spawning background plan-convergence loop for phase ${PHASE_NUM}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+
+```
+Agent(
+  description="Plan convergence phase ${PHASE_NUM}: ${PHASE_NAME}",
+  run_in_background=true,
+  prompt="Run plan convergence for phase ${PHASE_NUM}: Skill(skill=\"gsd-plan-review-convergence\", args=\"${PHASE_NUM} ${CONVERGENCE_ARGS}\")"
+)
+```

package/gsd-core/workflows/autonomous/steps/converge-dispatch-inline.md

@@ -0,0 +1,7 @@
+## Converge Dispatch (Inline)
+
+If `PLAN_STRATEGY=converge`:
+
+```
+Skill(skill="gsd-plan-review-convergence", args="${PHASE_NUM} ${CONVERGENCE_ARGS}")
+```

package/gsd-core/workflows/autonomous/steps/converge-fail-fast.md

@@ -0,0 +1,21 @@
+## Converge Fail-Fast
+
+When `PLAN_STRATEGY` is `converge`, fail fast unless the existing convergence feature gate is enabled:
+
+```bash
+_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}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; 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
+if [ "$PLAN_STRATEGY" = "converge" ]; then
+  CONVERGENCE_ENABLED=$(gsd_run query config-get workflow.plan_review_convergence 2>/dev/null || echo "false")
+  if [ "$CONVERGENCE_ENABLED" != "true" ]; then
+    printf '%s\n' \
+      'gsd-autonomous --converge is disabled (workflow.plan_review_convergence=false).' \
+      '' \
+      'Enable plan convergence with:' \
+      '' \
+      '  gsd config-set workflow.plan_review_convergence true' \
+      '' \
+      'Then re-run the autonomous command with --converge.'
+    exit 1
+  fi
+fi
+```

package/gsd-core/workflows/autonomous/steps/converge-loop.md

@@ -0,0 +1,7 @@
+## Converge Loop
+
+If `PLAN_STRATEGY=converge`, run the convergence loop:
+
+```
+Skill(skill="gsd-plan-review-convergence", args="${PHASE_NUM} ${CONVERGENCE_ARGS}")
+```