gsd-pi 0.2.8 → 0.3.0

package/README.md

@@ -46,6 +46,28 @@ GSD v2 solves all of these because it's not a prompt framework anymore — it's
 | Roadmap reassessment | Manual | Automatic after each slice completes |
 | Skill discovery | None | Auto-detect and install relevant skills during research |
 
+### Migrating from v1
+
+If you have projects with `.planning` directories from the original Get Shit Done, you can migrate them to GSD-2's `.gsd` format:
+
+```bash
+# From within the project directory
+/gsd migrate
+
+# Or specify a path
+/gsd migrate ~/projects/my-old-project
+```
+
+The migration tool:
+- Parses your old `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, phase directories, plans, summaries, and research
+- Maps phases → slices, plans → tasks, milestones → milestones
+- Preserves completion state (`[x]` phases stay done, summaries carry over)
+- Consolidates research files into the new structure
+- Shows a preview before writing anything
+- Optionally runs an agent-driven review of the output for quality assurance
+
+Supports format variations including milestone-sectioned roadmaps with `<details>` blocks, bold phase entries, bullet-format requirements, decimal phase numbering, and duplicate phase numbers across milestones.
+
 ---
 
 ## How It Works
@@ -187,6 +209,7 @@ On first run, GSD prompts for optional API keys (Brave Search, Context7, Jina) f
 | `/gsd status` | Progress dashboard |
 | `/gsd queue` | Queue future milestones (safe during auto mode) |
 | `/gsd prefs` | Model selection, timeouts, budget ceiling |
+| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format |
 | `/gsd doctor` | Validate `.gsd/` integrity, find and fix issues |
 | `Ctrl+Alt+G` | Toggle dashboard overlay |
 

package/dist/cli.js

@@ -7,18 +7,19 @@ loadStoredEnvKeys(authStorage);
 await runWizardIfNeeded(authStorage);
 const modelRegistry = new ModelRegistry(authStorage);
 const settingsManager = SettingsManager.create(agentDir);
-// Always ensure defaults: anthropic/claude-sonnet-4-6, thinking off.
-// Validates on every startup — catches stale settings from prior installs
+// Validate configured model on startup — catches stale settings from prior installs
 // (e.g. grok-2 which no longer exists) and fresh installs with no settings.
+// Only resets the default when the configured model no longer exists in the registry;
+// never overwrites a valid user choice.
 const configuredProvider = settingsManager.getDefaultProvider();
 const configuredModel = settingsManager.getDefaultModel();
 const allModels = modelRegistry.getAll();
 const configuredExists = configuredProvider && configuredModel &&
     allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
 if (!configuredModel || !configuredExists) {
-    // Preferred default: anthropic/claude-sonnet-4-6
-    const preferred = allModels.find((m) => m.provider === 'anthropic' && m.id === 'claude-sonnet-4-6') ||
-        allModels.find((m) => m.provider === 'anthropic' && m.id.includes('sonnet')) ||
+    // Fallback: pick the best available Anthropic model
+    const preferred = allModels.find((m) => m.provider === 'anthropic' && m.id === 'claude-opus-4-6') ||
+        allModels.find((m) => m.provider === 'anthropic' && m.id.includes('opus')) ||
         allModels.find((m) => m.provider === 'anthropic');
     if (preferred) {
         settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id);
@@ -52,5 +53,46 @@ if (extensionsResult.errors.length > 0) {
         process.stderr.write(`[gsd] Extension load error: ${err.error}\n`);
     }
 }
+// Restore scoped models from settings on startup.
+// The upstream InteractiveMode reads enabledModels from settings when /scoped-models is opened,
+// but doesn't apply them to the session at startup — so Ctrl+P cycles all models instead of
+// just the saved selection until the user re-runs /scoped-models.
+const enabledModelPatterns = settingsManager.getEnabledModels();
+if (enabledModelPatterns && enabledModelPatterns.length > 0) {
+    const availableModels = modelRegistry.getAvailable();
+    const scopedModels = [];
+    const seen = new Set();
+    for (const pattern of enabledModelPatterns) {
+        // Patterns are "provider/modelId" exact strings saved by /scoped-models
+        const slashIdx = pattern.indexOf('/');
+        if (slashIdx !== -1) {
+            const provider = pattern.substring(0, slashIdx);
+            const modelId = pattern.substring(slashIdx + 1);
+            const model = availableModels.find((m) => m.provider === provider && m.id === modelId);
+            if (model) {
+                const key = `${model.provider}/${model.id}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    scopedModels.push({ model });
+                }
+            }
+        }
+        else {
+            // Fallback: match by model id alone
+            const model = availableModels.find((m) => m.id === pattern);
+            if (model) {
+                const key = `${model.provider}/${model.id}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    scopedModels.push({ model });
+                }
+            }
+        }
+    }
+    // Only apply if we resolved some models and it's a genuine subset
+    if (scopedModels.length > 0 && scopedModels.length < availableModels.length) {
+        session.setScopedModels(scopedModels);
+    }
+}
 const interactiveMode = new InteractiveMode(session);
 await interactiveMode.run();

package/dist/wizard.js

@@ -75,7 +75,7 @@ export function loadStoredEnvKeys(authStorage) {
     for (const [provider, envVar] of providers) {
         if (!process.env[envVar]) {
             const cred = authStorage.get(provider);
-            if (cred?.type === 'api_key') {
+            if (cred?.type === 'api_key' && cred.key) {
                 process.env[envVar] = cred.key;
             }
         }
@@ -143,6 +143,7 @@ export async function runWizardIfNeeded(authStorage) {
             savedCount++;
         }
         else {
+            authStorage.set(key.provider, { type: 'api_key', key: '' });
             process.stdout.write(`  ${dim}↷  ${key.label} skipped${reset}\n\n`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "GSD — Get Stuff Done coding agent",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,8 @@
     "test": "node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test 'src/resources/extensions/gsd/tests/*.test.ts' 'src/resources/extensions/gsd/tests/*.test.mjs' 'src/tests/*.test.ts'",
     "dev": "tsc --watch",
     "postinstall": "node scripts/postinstall.js",
-    "prepublishOnly": "npm run build"
+    "sync-pkg-version": "node scripts/sync-pkg-version.cjs",
+    "prepublishOnly": "npm run sync-pkg-version && npm run build"
   },
   "dependencies": {
     "@mariozechner/pi-coding-agent": "^0.57.1",

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "0.1.0",
+  "version": "0.57.1",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/extensions/gsd/auto.ts

@@ -27,6 +27,7 @@ import {
   resolveMilestonePath, resolveDir, resolveTasksDir, resolveTaskFiles, resolveTaskFile,
   relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relMilestonePath,
   milestonesDir, resolveGsdRootFile, relGsdRootFile,
+  buildMilestoneFileName, buildSliceFileName, buildTaskFileName,
 } from "./paths.js";
 import { saveActivityLog } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
@@ -54,7 +55,7 @@ import {
   getProjectTotals, formatCost, formatTokenCount,
 } from "./metrics.js";
 import { join } from "node:path";
-import { readdirSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { execSync } from "node:child_process";
 import {
   autoCommitCurrentBranch,
@@ -1912,6 +1913,7 @@ async function recoverTimedOutUnit(
     }
 
     if (recoveryAttempts < maxRecoveryAttempts) {
+      const isEscalation = recoveryAttempts > 0;
       writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
         phase: "recovered",
         recovery: status,
@@ -1921,11 +1923,19 @@ async function recoverTimedOutUnit(
         progressCount: (runtime?.progressCount ?? 0) + 1,
         lastProgressKind: reason === "idle" ? "idle-recovery-retry" : "hard-recovery-retry",
       });
-      pi.sendMessage(
-        {
-          customType: "gsd-auto-timeout-recovery",
-          display: verbose,
-          content: [
+
+      const steeringLines = isEscalation
+        ? [
+            `**FINAL ${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — last chance before this task is skipped.**`,
+            `You are still executing ${unitType} ${unitId}.`,
+            `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts}.`,
+            `Current durability status: ${formatExecuteTaskRecoveryStatus(status)}.`,
+            "You MUST finish the durable output NOW, even if incomplete.",
+            "Write the task summary with whatever you have accomplished so far.",
+            "Mark the task [x] in the plan. Commit your work.",
+            "A partial summary is infinitely better than no summary.",
+          ]
+        : [
             `**${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — do not stop.**`,
             `You are still executing ${unitType} ${unitId}.`,
             `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts}.`,
@@ -1933,7 +1943,13 @@ async function recoverTimedOutUnit(
             "Do not keep exploring.",
             "Immediately finish the required durable output for this unit.",
             "If full completion is impossible, write the partial artifact/state needed for recovery and make the blocker explicit.",
-          ].join("\n"),
+          ];
+
+      pi.sendMessage(
+        {
+          customType: "gsd-auto-timeout-recovery",
+          display: verbose,
+          content: steeringLines.join("\n"),
         },
         { triggerTurn: true, deliverAs: "steer" },
       );
@@ -1944,7 +1960,29 @@ async function recoverTimedOutUnit(
       return "recovered";
     }
 
+    // Retries exhausted — write missing durable artifacts and advance.
     const diagnostic = formatExecuteTaskRecoveryStatus(status);
+    const [mid, sid, tid] = unitId.split("/");
+    const skipped = mid && sid && tid
+      ? skipExecuteTask(basePath, mid, sid, tid, status, reason, maxRecoveryAttempts)
+      : false;
+
+    if (skipped) {
+      writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
+        phase: "skipped",
+        recovery: status,
+        recoveryAttempts: recoveryAttempts + 1,
+        lastRecoveryReason: reason,
+      });
+      ctx.ui.notify(
+        `${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts (${diagnostic}). Blocker artifacts written. Advancing pipeline.`,
+        "warning",
+      );
+      await dispatchNextUnit(ctx, pi);
+      return "recovered";
+    }
+
+    // Fallback: couldn't write skip artifacts — pause as before.
     writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
       phase: "paused",
       recovery: status,
@@ -1959,7 +1997,26 @@ async function recoverTimedOutUnit(
   }
 
   const expected = diagnoseExpectedArtifact(unitType, unitId, basePath) ?? "required durable artifact";
+
+  // Check if the artifact already exists on disk — agent may have written it
+  // without signaling completion.
+  const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
+  if (artifactPath && existsSync(artifactPath)) {
+    writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
+      phase: "finalized",
+      recoveryAttempts: recoveryAttempts + 1,
+      lastRecoveryReason: reason,
+    });
+    ctx.ui.notify(
+      `${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} artifact already exists on disk. Advancing.`,
+      "info",
+    );
+    await dispatchNextUnit(ctx, pi);
+    return "recovered";
+  }
+
   if (recoveryAttempts < maxRecoveryAttempts) {
+    const isEscalation = recoveryAttempts > 0;
     writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
       phase: "recovered",
       recoveryAttempts: recoveryAttempts + 1,
@@ -1968,11 +2025,19 @@ async function recoverTimedOutUnit(
       progressCount: (runtime?.progressCount ?? 0) + 1,
       lastProgressKind: reason === "idle" ? "idle-recovery-retry" : "hard-recovery-retry",
     });
-    pi.sendMessage(
-      {
-        customType: "gsd-auto-timeout-recovery",
-        display: verbose,
-        content: [
+
+    const steeringLines = isEscalation
+      ? [
+          `**FINAL ${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — last chance before skip.**`,
+          `You are still executing ${unitType} ${unitId}.`,
+          `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts} — next failure skips this unit.`,
+          `Expected durable output: ${expected}.`,
+          "You MUST write the artifact file NOW, even if incomplete.",
+          "Write whatever you have — partial research, preliminary findings, best-effort analysis.",
+          "A partial artifact is infinitely better than no artifact.",
+          "If you are truly blocked, write the file with a BLOCKER section explaining why.",
+        ]
+      : [
           `**${reason === "idle" ? "IDLE" : "HARD TIMEOUT"} RECOVERY — stay in auto-mode.**`,
           `You are still executing ${unitType} ${unitId}.`,
           `Recovery attempt ${recoveryAttempts + 1} of ${maxRecoveryAttempts}.`,
@@ -1980,7 +2045,13 @@ async function recoverTimedOutUnit(
           "Stop broad exploration.",
           "Write the required artifact now.",
           "If blocked, write the partial artifact and explicitly record the blocker instead of going silent.",
-        ].join("\n"),
+        ];
+
+    pi.sendMessage(
+      {
+        customType: "gsd-auto-timeout-recovery",
+        display: verbose,
+        content: steeringLines.join("\n"),
       },
       { triggerTurn: true, deliverAs: "steer" },
     );
@@ -1991,6 +2062,28 @@ async function recoverTimedOutUnit(
     return "recovered";
   }
 
+  // Retries exhausted — write a blocker placeholder and advance the pipeline
+  // instead of silently stalling.
+  const placeholder = writeBlockerPlaceholder(
+    unitType, unitId, basePath,
+    `${reason} recovery exhausted ${maxRecoveryAttempts} attempts without producing the artifact.`,
+  );
+
+  if (placeholder) {
+    writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
+      phase: "skipped",
+      recoveryAttempts: recoveryAttempts + 1,
+      lastRecoveryReason: reason,
+    });
+    ctx.ui.notify(
+      `${unitType} ${unitId} skipped after ${maxRecoveryAttempts} recovery attempts. Blocker placeholder written to ${placeholder}. Advancing pipeline.`,
+      "warning",
+    );
+    await dispatchNextUnit(ctx, pi);
+    return "recovered";
+  }
+
+  // Fallback: couldn't resolve artifact path — pause as before.
   writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
     phase: "paused",
     recoveryAttempts: recoveryAttempts + 1,
@@ -1999,6 +2092,116 @@ async function recoverTimedOutUnit(
   return "paused";
 }
 
+/**
+ * Write skip artifacts for a stuck execute-task: a blocker task summary and
+ * the [x] checkbox in the slice plan. Returns true if artifacts were written.
+ */
+export function skipExecuteTask(
+  base: string, mid: string, sid: string, tid: string,
+  status: { summaryExists: boolean; taskChecked: boolean },
+  reason: string, maxAttempts: number,
+): boolean {
+  // Write a blocker task summary if missing.
+  if (!status.summaryExists) {
+    const tasksDir = resolveTasksDir(base, mid, sid);
+    const sDir = resolveSlicePath(base, mid, sid);
+    const targetDir = tasksDir ?? (sDir ? join(sDir, "tasks") : null);
+    if (!targetDir) return false;
+    if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+    const summaryPath = join(targetDir, buildTaskFileName(tid, "SUMMARY"));
+    const content = [
+      `# BLOCKER — task skipped by auto-mode recovery`,
+      ``,
+      `Task \`${tid}\` in slice \`${sid}\` (milestone \`${mid}\`) failed to complete after ${reason} recovery exhausted ${maxAttempts} attempts.`,
+      ``,
+      `This placeholder was written by auto-mode so the pipeline can advance.`,
+      `Review this task manually and replace this file with a real summary.`,
+    ].join("\n");
+    writeFileSync(summaryPath, content, "utf-8");
+  }
+
+  // Mark [x] in the slice plan if not already checked.
+  if (!status.taskChecked) {
+    const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
+    if (planAbs && existsSync(planAbs)) {
+      const planContent = readFileSync(planAbs, "utf-8");
+      const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`^(- \\[) \\] (\\*\\*${escapedTid}:)`, "m");
+      if (re.test(planContent)) {
+        writeFileSync(planAbs, planContent.replace(re, "$1x] $2"), "utf-8");
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Resolve the expected artifact for a non-execute-task unit to an absolute path.
+ * Returns null for unit types that don't produce a single file (execute-task,
+ * complete-slice, replan-slice).
+ */
+export function resolveExpectedArtifactPath(unitType: string, unitId: string, base: string): string | null {
+  const parts = unitId.split("/");
+  const mid = parts[0]!;
+  const sid = parts[1];
+  switch (unitType) {
+    case "research-milestone": {
+      const dir = resolveMilestonePath(base, mid);
+      return dir ? join(dir, buildMilestoneFileName(mid, "RESEARCH")) : null;
+    }
+    case "plan-milestone": {
+      const dir = resolveMilestonePath(base, mid);
+      return dir ? join(dir, buildMilestoneFileName(mid, "ROADMAP")) : null;
+    }
+    case "research-slice": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "RESEARCH")) : null;
+    }
+    case "plan-slice": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "PLAN")) : null;
+    }
+    case "reassess-roadmap": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "ASSESSMENT")) : null;
+    }
+    case "run-uat": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "UAT-RESULT")) : null;
+    }
+    case "complete-milestone": {
+      const dir = resolveMilestonePath(base, mid);
+      return dir ? join(dir, buildMilestoneFileName(mid, "SUMMARY")) : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Write a placeholder artifact so the pipeline can advance past a stuck unit.
+ * Returns the relative path written, or null if the path couldn't be resolved.
+ */
+export function writeBlockerPlaceholder(unitType: string, unitId: string, base: string, reason: string): string | null {
+  const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
+  if (!absPath) return null;
+  const dir = absPath.substring(0, absPath.lastIndexOf("/"));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const content = [
+    `# BLOCKER — auto-mode recovery failed`,
+    ``,
+    `Unit \`${unitType}\` for \`${unitId}\` failed to produce this artifact after idle recovery exhausted all retries.`,
+    ``,
+    `**Reason**: ${reason}`,
+    ``,
+    `This placeholder was written by auto-mode so the pipeline can advance.`,
+    `Review and replace this file before relying on downstream artifacts.`,
+  ].join("\n");
+  writeFileSync(absPath, content, "utf-8");
+  return diagnoseExpectedArtifact(unitType, unitId, base);
+}
+
 function diagnoseExpectedArtifact(unitType: string, unitId: string, base: string): string | null {
   const parts = unitId.split("/");
   const mid = parts[0];

package/src/resources/extensions/gsd/commands.ts

@@ -30,6 +30,7 @@ import {
   filterDoctorIssues,
 } from "./doctor.js";
 import { loadPrompt } from "./prompt-loader.js";
+import { handleMigrate } from "./migrate/command.js";
 
 function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
@@ -51,10 +52,10 @@ function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportT
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Stuff Done: /gsd auto|stop|status|queue|prefs|doctor",
+    description: "GSD — Get Stuff Done: /gsd auto|stop|status|queue|prefs|doctor|migrate",
 
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ["auto", "stop", "status", "queue", "discuss", "prefs", "doctor"];
+      const subcommands = ["auto", "stop", "status", "queue", "discuss", "prefs", "doctor", "migrate"];
       const parts = prefix.trim().split(/\s+/);
 
       if (parts.length <= 1) {
@@ -136,13 +137,18 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
+        await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
+        return;
+      }
+
       if (trimmed === "") {
         await showSmartEntry(ctx, pi, process.cwd());
         return;
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status], or /gsd doctor [audit|fix|heal] [M###/S##].`,
+        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status], /gsd doctor [audit|fix|heal] [M###/S##], or /gsd migrate <path>.`,
         "warning",
       );
     },

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -17,6 +17,7 @@ import {
   aggregateByModel, formatCost, formatTokenCount, formatCostProjection,
 } from "./metrics.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getActiveWorktreeName } from "./worktree-command.js";
 
 function formatDuration(ms: number): string {
   const s = Math.floor(ms / 1000);
@@ -273,8 +274,12 @@ export class GSDDashboardOverlay {
       : this.dashData.paused
         ? th.fg("warning", "⏸ PAUSED")
         : th.fg("dim", "idle");
+    const worktreeName = getActiveWorktreeName();
+    const worktreeTag = worktreeName
+      ? `  ${th.fg("warning", `⎇ ${worktreeName}`)}`
+      : "";
     const elapsed = th.fg("dim", formatDuration(this.dashData.elapsed));
-    lines.push(row(joinColumns(`${title}  ${status}`, elapsed, contentWidth)));
+    lines.push(row(joinColumns(`${title}  ${status}${worktreeTag}`, elapsed, contentWidth)));
     lines.push(blank());
 
     if (this.dashData.currentUnit) {

package/src/resources/extensions/gsd/files.ts

@@ -21,7 +21,7 @@ import type {
  * Split markdown content into frontmatter (YAML-like) and body.
  * Returns [frontmatterLines, body] where frontmatterLines is null if no frontmatter.
  */
-function splitFrontmatter(content: string): [string[] | null, string] {
+export function splitFrontmatter(content: string): [string[] | null, string] {
   const trimmed = content.trimStart();
   if (!trimmed.startsWith('---')) return [null, content];
 
@@ -42,7 +42,7 @@ function splitFrontmatter(content: string): [string[] | null, string] {
  * Handles simple scalars and arrays (lines starting with "  - ").
  * Handles nested objects like requires (lines with "    key: value").
  */
-function parseFrontmatterMap(lines: string[]): Record<string, unknown> {
+export function parseFrontmatterMap(lines: string[]): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   let currentKey: string | null = null;
   let currentArray: unknown[] | null = null;
@@ -124,7 +124,7 @@ function parseFrontmatterMap(lines: string[]): Record<string, unknown> {
 }
 
 /** Extract the text after a heading at a given level, up to the next heading of same or higher level. */
-function extractSection(body: string, heading: string, level: number = 2): string | null {
+export function extractSection(body: string, heading: string, level: number = 2): string | null {
   const prefix = '#'.repeat(level) + ' ';
   const regex = new RegExp(`^${prefix}${escapeRegex(heading)}\\s*$`, 'm');
   const match = regex.exec(body);
@@ -140,7 +140,7 @@ function extractSection(body: string, heading: string, level: number = 2): strin
 }
 
 /** Extract all sections at a given level, returning heading → content map. */
-function extractAllSections(body: string, level: number = 2): Map<string, string> {
+export function extractAllSections(body: string, level: number = 2): Map<string, string> {
   const prefix = '#'.repeat(level) + ' ';
   const regex = new RegExp(`^${prefix}(.+)$`, 'gm');
   const sections = new Map<string, string>();
@@ -161,14 +161,14 @@ function escapeRegex(s: string): string {
 }
 
 /** Parse bullet list items from a text block. */
-function parseBullets(text: string): string[] {
+export function parseBullets(text: string): string[] {
   return text.split('\n')
     .map(l => l.replace(/^\s*[-*]\s+/, '').trim())
     .filter(l => l.length > 0 && !l.startsWith('#'));
 }
 
 /** Extract key: value from bold-prefixed lines like "**Key:** Value" */
-function extractBoldField(text: string, key: string): string | null {
+export function extractBoldField(text: string, key: string): string | null {
   const regex = new RegExp(`^\\*\\*${escapeRegex(key)}:\\*\\*\\s*(.+)$`, 'm');
   const match = regex.exec(text);
   return match ? match[1].trim() : null;
@@ -548,7 +548,7 @@ export function parseRequirementCounts(content: string | null): RequirementCount
   for (const section of sections) {
     const text = extractSection(content, section.heading, 2);
     if (!text) continue;
-    const matches = text.match(/^###\s+R\d+\s+—/gm);
+    const matches = text.match(/^###\s+[A-Z][\w-]*\d+\s+—/gm);
     counts[section.key] = matches ? matches.length : 0;
   }
 

package/src/resources/extensions/gsd/gitignore.ts

@@ -17,6 +17,7 @@ const BASELINE_PATTERNS = [
   // ── GSD runtime (not source artifacts) ──
   ".gsd/activity/",
   ".gsd/runtime/",
+  ".gsd/worktrees/",
   ".gsd/auto.lock",
   ".gsd/metrics.json",
   ".gsd/STATE.md",

package/src/resources/extensions/gsd/index.ts

@@ -22,8 +22,10 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
+import { createBashTool } from "@mariozechner/pi-coding-agent";
 
 import { registerGSDCommand } from "./commands.js";
+import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
 import { saveFile, formatContinue, loadFile, parseContinue, parseSummary } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
@@ -59,6 +61,16 @@ const GSD_LOGO_LINES = [
 
 export default function (pi: ExtensionAPI) {
   registerGSDCommand(pi);
+  registerWorktreeCommand(pi);
+
+  // ── Dynamic-cwd bash tool ──────────────────────────────────────────────
+  // The built-in bash tool captures cwd at startup. This replacement uses
+  // a spawnHook to read process.cwd() dynamically so that process.chdir()
+  // (used by /worktree switch) propagates to shell commands.
+  const dynamicBash = createBashTool(process.cwd(), {
+    spawnHook: (ctx) => ({ ...ctx, cwd: process.cwd() }),
+  });
+  pi.registerTool(dynamicBash as any);
 
   // ── session_start: render branded GSD header ───────────────────────────
   pi.on("session_start", async (_event, ctx) => {
@@ -131,8 +143,31 @@ export default function (pi: ExtensionAPI) {
 
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
 
+    // Worktree context — override the static CWD in the system prompt
+    let worktreeBlock = "";
+    const worktreeName = getActiveWorktreeName();
+    const worktreeMainCwd = getWorktreeOriginalCwd();
+    if (worktreeName && worktreeMainCwd) {
+      worktreeBlock = [
+        "",
+        "",
+        "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
+        `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
+        `The actual current working directory is: ${process.cwd()}`,
+        "",
+        `You are working inside a GSD worktree.`,
+        `- Worktree name: ${worktreeName}`,
+        `- Worktree path (this is the real cwd): ${process.cwd()}`,
+        `- Main project: ${worktreeMainCwd}`,
+        `- Branch: worktree/${worktreeName}`,
+        "",
+        "All file operations, bash commands, and GSD state resolve against the worktree path above.",
+        "Use /worktree merge to merge changes back. Use /worktree return to switch back to the main tree.",
+      ].join("\n");
+    }
+
     return {
-      systemPrompt: `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${newSkillsBlock}`,
+      systemPrompt: `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${newSkillsBlock}${worktreeBlock}`,
       ...(injection
         ? {
           message: {