gsd-pi 2.22.0 → 2.24.0

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -0,0 +1,86 @@
+# Headless Milestone Creation
+
+You are creating a GSD milestone from a provided specification document. This is a **headless** (non-interactive) flow — do NOT ask the user any questions. Work entirely from the provided specification.
+
+## Provided Specification
+
+{{seedContext}}
+
+## Your Task
+
+### Step 1: Reflect
+
+Summarize your understanding of the specification concretely:
+- What is being built
+- Major capabilities/features
+- Scope estimate (how many milestones × slices)
+- Any ambiguities or gaps you notice
+
+### Step 2: Investigate
+
+Scout the codebase to understand what already exists:
+- `ls` the project root and key directories
+- Search for relevant existing code, patterns, dependencies
+- Check library docs if needed (`resolve_library` / `get_library_docs`)
+
+### Step 3: Make Decisions
+
+For any ambiguities or gaps in the specification:
+- Make your best-guess decision based on the spec's intent, codebase patterns, and domain conventions
+- Document each assumption clearly in the Context file
+
+### Step 4: Assess Scope
+
+Based on reflection + investigation:
+- Is this a single milestone or multiple milestones?
+- If multi-milestone: plan the full sequence with dependencies
+
+### Step 5: Write Artifacts
+
+**Milestone ID**: {{milestoneId}}
+
+Use these templates exactly:
+
+{{inlinedTemplates}}
+
+**For single milestone**, write in this order:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
+2. Write `.gsd/PROJECT.md` (using Project template)
+3. Write `.gsd/REQUIREMENTS.md` (using Requirements template)
+4. Write `{{contextPath}}` (using Context template) — preserve the specification's exact terminology, emphasis, and specific framing. Do not paraphrase domain-specific language into generics. Document assumptions under an "Assumptions" section.
+5. Write `{{roadmapPath}}` (using Roadmap template) — decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice.
+6. Seed `.gsd/DECISIONS.md` (using Decisions template)
+7. Update `.gsd/STATE.md`
+8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
+9. Say exactly: "Milestone {{milestoneId}} ready."
+
+**For multi-milestone**, write in this order:
+1. Create all milestone directories: `mkdir -p .gsd/milestones/{M###}/slices` for each
+2. Write `.gsd/PROJECT.md` — full vision across ALL milestones (using Project template)
+3. Write `.gsd/REQUIREMENTS.md` — full capability contract (using Requirements template)
+4. Seed `.gsd/DECISIONS.md` (using Decisions template)
+5. Write PRIMARY `{{contextPath}}` — full context with all assumptions documented
+6. Write PRIMARY `{{roadmapPath}}` — detailed slices for the first milestone only
+7. For each remaining milestone, write full CONTEXT.md with `depends_on` frontmatter:
+   ```yaml
+   ---
+   depends_on: [M001, M002]
+   ---
+
+   # M003: Title
+   ```
+   Each context file should be rich enough that a future agent — with no memory of this conversation — can understand the intent, constraints, dependencies, what the milestone unlocks, and what "done" looks like.
+8. Update `.gsd/STATE.md`
+9. Commit: `docs: project plan — N milestones`
+10. Say exactly: "Milestone {{milestoneId}} ready."
+
+## Critical Rules
+
+- **DO NOT ask the user any questions** — this is headless mode
+- **Preserve the specification's terminology** — don't paraphrase domain-specific language
+- **Document assumptions** — when you make a judgment call, note it in CONTEXT.md under "Assumptions"
+- **Investigate before writing** — always scout the codebase first
+- **Use depends_on frontmatter** for multi-milestone sequences (the state machine reads this field to determine execution order)
+- **Anti-reduction rule** — if the spec describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or reduce scope. Phase complex/risky work into later milestones — do not cut it.
+- **Naming convention** — directories use bare IDs (`M001/`, `S01/`), files use ID-SUFFIX format (`M001-CONTEXT.md`, `M001-ROADMAP.md`)
+- **End with "Milestone {{milestoneId}} ready."** — this triggers auto-start detection

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -31,6 +31,11 @@ Then:
 3. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature.
 4. Write or update tests as part of execution — tests are verification, not an afterthought. If the slice plan defines test files in its Verification section and this is the first task, create them (they should initially fail).
 5. When implementing non-trivial runtime behavior (async flows, API boundaries, background processes, error paths), add or preserve agent-usable observability. Skip this for simple changes where it doesn't apply.
+
+   **Background process rule:** Never use bare `command &` to run background processes. The shell's `&` operator leaves stdout/stderr attached to the parent, which causes the Bash tool to hang indefinitely waiting for those streams to close. Always redirect output before backgrounding:
+   - Correct: `command > /dev/null 2>&1 &` or `nohup command > /dev/null 2>&1 &`
+   - Example: `python -m http.server 8080 > /dev/null 2>&1 &` (NOT `python -m http.server 8080 &`)
+   - Preferred: use the `bg_shell` tool if available — it manages process lifecycle correctly without stream-inheritance issues
 6. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors)
 7. Run the slice-level verification checks defined in the slice plan's Verification section. Track which pass. On the final task of the slice, all must pass before marking done. On intermediate tasks, partial passes are expected — note which ones pass in the summary.
 8. If the task touches UI, browser flows, DOM behavior, or user-visible web state:

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -1,5 +1,108 @@
 Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Use the **Context** output template below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
 
+**Structured questions available: {{structuredQuestionsAvailable}}**
+
 {{inlinedTemplates}}
 
-**Investigate between question rounds to make your questions smarter.** Before each round of questions, do enough lightweight research that your questions are grounded in reality — not guesses about what exists or what's possible. Check library docs (`resolve_library`/`get_library_docs`) when tech choices are relevant, search the web (`search-the-web` with `freshness`/`domain` filters, then `fetch_page` for full content) to verify the landscape, scout the codebase (`rg`, `find`, `scout`) to understand what already exists. Don't go deep — just enough that your next question reflects what's actually true. The goal is to ask questions the user can't answer by saying "did you check the docs?" or "look at the code."
+---
+
+## Interview Protocol
+
+### Before your first question round
+
+Do a lightweight targeted investigation so your questions are grounded in reality:
+- Scout the codebase (`rg`, `find`, or `scout`) to understand what already exists that this milestone touches or builds on
+- Check the roadmap context above (if present) to understand what surrounds this milestone
+- Identify the 3–5 biggest behavioural and architectural unknowns: things where the user's answer will materially change what gets built
+
+Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume.
+
+### Question rounds
+
+Ask **1–3 questions per round**. Keep each question focused on one of:
+- **What they're building** — concrete enough to explain to a stranger
+- **Why it needs to exist** — the problem it solves or the desire it fulfills
+- **Who it's for** — user, team, themselves
+- **What "done" looks like** — observable outcomes, not abstract goals
+- **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
+- **What external systems/services this touches** — APIs, databases, third-party services
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). Always include a freeform "Other / let me explain" option. When the user picks that option or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions. Wait for answers before asking the next round.
+
+After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
+
+### Check-in after each round
+
+After each round of answers, ask:
+
+> "I think I have a solid picture of this milestone. Ready to wrap up and write the context file, or is there more to cover?"
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with options:
+- "Wrap up — write the context file" *(recommended after ~2–3 rounds)*
+- "Keep going — more to discuss"
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text.
+
+If the user wants to keep going, keep asking. Stop when they say wrap up.
+
+---
+
+## Questioning philosophy
+
+**Start open, follow energy.** Let the user's enthusiasm guide where you dig deeper.
+
+**Challenge vagueness, make abstract concrete.** When the user says something abstract ("it should be smart" / "good UX"), push for specifics.
+
+**Questions must be about the experience, not the implementation.** Never ask "what auth provider?" — ask "when someone logs in, what should that feel like?" Implementation is your job. Understanding what they want to experience is the discussion's job.
+
+**Position-first framing.** Have opinions. "I'd lean toward X because Y — does that match your thinking?" is better than "what do you think about X vs Y?"
+
+**Negative constraints.** Ask what would disappoint them. What they explicitly don't want. Negative constraints are sharper than positive wishes.
+
+**Anti-patterns — never do these:**
+- Checklist walking through predetermined topics regardless of what the user said
+- Canned generic questions that could apply to any project
+- Corporate speak ("What are your key success metrics?")
+- Rapid-fire questions without acknowledging answers
+- Asking about technical skill level
+
+---
+
+## Depth Verification
+
+Before moving to the wrap-up gate, verify you have covered:
+
+- [ ] What they're building — concrete enough to explain to a stranger
+- [ ] Why it needs to exist
+- [ ] Who it's for
+- [ ] What "done" looks like
+- [ ] The biggest technical unknowns / risks
+- [ ] What external systems/services this touches
+
+**Print a structured depth summary in chat first** — using the user's own terminology. Cover what you understood, what shaped your understanding, and any areas of remaining uncertainty.
+
+**Then confirm:**
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with:
+- header: "Depth Check"
+- question: "Did I capture the depth right?"
+- options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
+- **The question ID must contain `depth_verification`** (e.g. `depth_verification_confirm`) — this enables the write-gate downstream.
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? Anything I missed?" Wait for confirmation before proceeding.
+
+If they clarify, absorb the correction and re-verify.
+
+---
+
+## Output
+
+Once the user confirms depth:
+
+1. Use the **Context** output template below
+2. `mkdir -p` the milestone directory if needed
+3. Write `{{milestoneId}}-CONTEXT.md` — preserve the user's exact terminology, emphasis, and framing. Do not paraphrase nuance into generic summaries. The context file is downstream agents' only window into this conversation.
+4. Commit: `git add {{milestoneId}}-CONTEXT.md && git commit -m "docs({{milestoneId}}): milestone context from discuss"`
+5. Say exactly: `"{{milestoneId}} context written."` — nothing else.

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -51,6 +51,7 @@ Apply these when decomposing and ordering slices:
 - **Completion must imply capability.** If every slice in this roadmap were completed exactly as written, the milestone's promised outcome should actually work at the proof level claimed. Do not write slices that can all be checked off while the user-visible capability still does not exist.
 - **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
 - **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
+- **Dependency format is comma-separated, never range syntax.** Write `depends:[S01,S02,S03]` — not `depends:[S01-S03]`. Range syntax is not a valid format and permanently blocks the slice.
 - **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.
 - **Right-size the decomposition.** Match slice count to actual complexity. If the work is small enough to build and verify in one pass, it's one slice — don't split it into three just because you can identify sub-steps. Multiple requirements can share a single slice. Conversely, don't cram genuinely independent capabilities into one slice just to keep the count low. Let the work dictate the structure.
 

package/dist/resources/extensions/gsd/prompts/research-slice.md

@@ -46,7 +46,7 @@ Research what this slice needs. Narrate key findings and surprises as you go —
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content
+5. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
 6. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.

package/dist/resources/extensions/gsd/prompts/system.md

@@ -154,7 +154,7 @@ Templates showing the expected format for each artifact type are in:
 
 **External facts:** Use `search-the-web` + `fetch_page`, or `search_and_read` for one-call extraction. Use `freshness` for recency. Never state current facts from training data without verification.
 
-**Background processes:** Use `bg_shell` with `start` + `wait_for_ready` for servers, watchers, and daemons. Never poll with `sleep`/retry loops — `wait_for_ready` exists for this. For status checks, use `digest` (~30 tokens), not `output` (~2000 tokens). Use `highlights` (~100 tokens) when you need significant lines only. Use `output` only when actively debugging.
+**Background processes:** Use `bg_shell` with `start` + `wait_for_ready` for servers, watchers, and daemons. Never use `bash` with `&` or `nohup` to background a process — the `bash` tool waits for stdout to close, so backgrounded children that inherit the file descriptors cause it to hang indefinitely. Never poll with `sleep`/retry loops — `wait_for_ready` exists for this. For status checks, use `digest` (~30 tokens), not `output` (~2000 tokens). Use `highlights` (~100 tokens) when you need significant lines only. Use `output` only when actively debugging.
 
 **One-shot commands:** Use `async_bash` for builds, tests, and installs. The result is pushed to you when the command exits — no polling needed. Use `await_job` to block on a specific job.
 
@@ -169,6 +169,7 @@ Templates showing the expected format for each artifact type are in:
 - Never use `cat` to read a file you might edit — `read` gives you the exact text `edit` needs.
 - Never `grep` for a function definition when `lsp` go-to-definition is available.
 - Never poll a server with `sleep 1 && curl` loops — use `bg_shell` `wait_for_ready`.
+- Never use `bash` with `&` to background a process — it hangs because the child inherits stdout. Use `bg_shell` `start` instead.
 - Never use `bg_shell` `output` for a status check — use `digest`.
 - Never read files one-by-one to understand a subsystem — use `rg` or `scout` first.
 - Never guess at library APIs from training data — use `get_library_docs`.

package/dist/resources/extensions/gsd/prompts/validate-milestone.md

@@ -0,0 +1,70 @@
+You are executing GSD auto-mode.
+
+## UNIT: Validate Milestone {{milestoneId}} ("{{milestoneTitle}}")
+
+## Working Directory
+
+Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
+
+## Your Role in the Pipeline
+
+All slices are done. Before the milestone can be completed, you must validate that the planned work was delivered as specified. Compare the roadmap's success criteria and slice definitions against the actual slice summaries and UAT results. This is a reconciliation gate — catch gaps, regressions, or missing deliverables before the milestone is sealed.
+
+This is remediation round {{remediationRound}}. If this is round 0, this is the first validation pass. If > 0, prior validation found issues and remediation slices were added and executed — verify those remediation slices resolved the issues.
+
+All relevant context has been preloaded below — the roadmap, all slice summaries, UAT results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+## Validation Steps
+
+1. For each **success criterion** in `{{roadmapPath}}`, check whether slice summaries and UAT results provide evidence that it was met. Record pass/fail per criterion.
+2. For each **slice** in the roadmap, verify its demo/deliverable claim against its summary. Flag any slice whose summary does not substantiate its claimed output.
+3. Check **cross-slice integration points** — do boundary map entries (produces/consumes) align with what was actually built?
+4. Check **requirement coverage** — are all active requirements addressed by at least one slice?
+5. Determine a verdict:
+   - `pass` — all criteria met, all slices delivered, no gaps
+   - `needs-attention` — minor gaps that do not block completion (document them)
+   - `needs-remediation` — material gaps found; add remediation slices to the roadmap
+
+## Output
+
+Write `{{validationPath}}` with this structure:
+
+```markdown
+---
+verdict: <pass|needs-attention|needs-remediation>
+remediation_round: {{remediationRound}}
+---
+
+# Milestone Validation: {{milestoneId}}
+
+## Success Criteria Checklist
+- [x] Criterion 1 — evidence: ...
+- [ ] Criterion 2 — gap: ...
+
+## Slice Delivery Audit
+| Slice | Claimed | Delivered | Status |
+|-------|---------|-----------|--------|
+| S01   | ...     | ...       | pass   |
+
+## Cross-Slice Integration
+(any boundary mismatches)
+
+## Requirement Coverage
+(any unaddressed requirements)
+
+## Verdict Rationale
+(why this verdict was chosen)
+
+## Remediation Plan
+(only if verdict is needs-remediation — list new slices to add to the roadmap)
+```
+
+If verdict is `needs-remediation`:
+- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
+- These slices will be planned and executed before validation re-runs
+
+**You MUST write `{{validationPath}}` before finishing.**
+
+When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/dist/resources/extensions/gsd/provider-error-pause.ts

@@ -2,11 +2,38 @@ export type ProviderErrorPauseUI = {
   notify(message: string, level?: "info" | "warning" | "error" | "success"): void;
 };
 
+/**
+ * Pause auto-mode due to a provider error.
+ *
+ * For rate-limit errors with a known reset delay, schedules an automatic
+ * resume after the delay and shows a countdown notification. For all other
+ * errors, pauses indefinitely (user must manually resume).
+ */
 export async function pauseAutoForProviderError(
   ui: ProviderErrorPauseUI,
   errorDetail: string,
   pause: () => Promise<void>,
+  options?: {
+    isRateLimit?: boolean;
+    retryAfterMs?: number;
+    resume?: () => void;
+  },
 ): Promise<void> {
-  ui.notify(`Auto-mode paused due to provider error${errorDetail}`, "warning");
-  await pause();
+  if (options?.isRateLimit && options.retryAfterMs && options.retryAfterMs > 0 && options.resume) {
+    const delaySec = Math.ceil(options.retryAfterMs / 1000);
+    ui.notify(
+      `Rate limited${errorDetail}. Auto-resuming in ${delaySec}s...`,
+      "warning",
+    );
+    await pause();
+
+    // Schedule auto-resume after the rate limit window
+    setTimeout(() => {
+      ui.notify("Rate limit window elapsed. Resuming auto-mode.", "info");
+      options.resume!();
+    }, options.retryAfterMs);
+  } else {
+    ui.notify(`Auto-mode paused due to provider error${errorDetail}`, "warning");
+    await pause();
+  }
 }

package/dist/resources/extensions/gsd/roadmap-slices.ts

@@ -1,5 +1,45 @@
 import type { RoadmapSliceEntry, RiskLevel } from "./types.js";
 
+/**
+ * Expand dependency shorthand into individual slice IDs.
+ *
+ * Handles two common LLM-generated patterns that the roadmap parser
+ * previously treated as single literal IDs (silently blocking slices):
+ *
+ *   "S01-S04"  → ["S01", "S02", "S03", "S04"]  (range syntax)
+ *   "S01..S04" → ["S01", "S02", "S03", "S04"]  (dot-range syntax)
+ *
+ * Plain IDs ("S01", "S02") and empty strings pass through unchanged.
+ */
+export function expandDependencies(deps: string[]): string[] {
+  const result: string[] = [];
+  for (const dep of deps) {
+    const trimmed = dep.trim();
+    if (!trimmed) continue;
+
+    // Match range syntax: S01-S04 or S01..S04 (case-insensitive prefix)
+    const rangeMatch = trimmed.match(/^([A-Za-z]+)(\d+)(?:-|\.\.)+([A-Za-z]+)(\d+)$/);
+    if (rangeMatch) {
+      const prefixA = rangeMatch[1]!.toUpperCase();
+      const startNum = parseInt(rangeMatch[2]!, 10);
+      const prefixB = rangeMatch[3]!.toUpperCase();
+      const endNum = parseInt(rangeMatch[4]!, 10);
+
+      // Only expand when both prefixes match and range is valid
+      if (prefixA === prefixB && startNum <= endNum) {
+        const width = rangeMatch[2]!.length; // preserve zero-padding (S01 not S1)
+        for (let i = startNum; i <= endNum; i++) {
+          result.push(`${prefixA}${String(i).padStart(width, "0")}`);
+        }
+        continue;
+      }
+    }
+
+    result.push(trimmed);
+  }
+  return result;
+}
+
 function extractSlicesSection(content: string): string {
   const headingMatch = /^## Slices\s*$/m.exec(content);
   if (!headingMatch || headingMatch.index == null) return "";
@@ -33,7 +73,7 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
 
       const depsMatch = rest.match(/`depends:\[([^\]]*)\]`/);
       const depends = depsMatch && depsMatch[1]!.trim()
-        ? depsMatch[1]!.split(",").map(s => s.trim())
+        ? expandDependencies(depsMatch[1]!.split(",").map(s => s.trim()))
         : [];
 
       currentSlice = { id, title, risk, depends, done, demo: "" };

package/dist/resources/extensions/gsd/session-forensics.ts

@@ -22,6 +22,7 @@ import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
 import { nativeWorkingTreeStatus, nativeDiffStat } from "./native-git-bridge.js";
+import { getAutoWorktreePath } from "./auto-worktree.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -296,12 +297,45 @@ export function synthesizeCrashRecovery(
  * Replaces the old shallow getLastActivityDiagnostic().
  */
 export function getDeepDiagnostic(basePath: string): string | null {
-  const activityDir = join(basePath, ".gsd", "activity");
-  const trace = readLastActivityLog(activityDir);
+  // Try worktree activity logs first if an auto-worktree is active
+  let trace: ExecutionTrace | null = null;
+  try {
+    const mid = readActiveMilestoneId(basePath);
+    if (mid) {
+      const wtPath = getAutoWorktreePath(basePath, mid);
+      if (wtPath) {
+        const wtActivityDir = join(wtPath, ".gsd", "activity");
+        trace = readLastActivityLog(wtActivityDir);
+      }
+    }
+  } catch { /* non-fatal — fall through to root */ }
+
+  // Fall back to root activity logs
+  if (!trace || trace.toolCallCount === 0) {
+    const activityDir = join(basePath, ".gsd", "activity");
+    trace = readLastActivityLog(activityDir);
+  }
+
   if (!trace || trace.toolCallCount === 0) return null;
   return formatTraceSummary(trace);
 }
 
+/**
+ * Read the active milestone ID directly from STATE.md without async deriveState().
+ * Looks for `**Active Milestone:** M001` pattern.
+ */
+function readActiveMilestoneId(basePath: string): string | null {
+  try {
+    const statePath = join(basePath, ".gsd", "STATE.md");
+    if (!existsSync(statePath)) return null;
+    const content = readFileSync(statePath, "utf-8");
+    const match = /\*\*Active Milestone:\*\*\s*(\S+)/i.exec(content);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // ─── Formatting ───────────────────────────────────────────────────────────────
 
 function formatRecoveryPrompt(