gsd-pi 2.11.0 → 2.13.0

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

@@ -53,10 +53,10 @@ function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportT
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|doctor|migrate|remote",
+    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|hooks|doctor|migrate|remote",
 
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "doctor", "migrate", "remote"];
+      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "hooks", "doctor", "migrate", "remote"];
       const parts = prefix.trim().split(/\s+/);
 
       if (parts.length <= 1) {
@@ -151,6 +151,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "hooks") {
+        const { formatHookStatus } = await import("./post-unit-hooks.js");
+        ctx.ui.notify(formatHookStatus(), "info");
+        return;
+      }
+
       if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
         await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
         return;
@@ -168,7 +174,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status|wizard|setup], /gsd doctor [audit|fix|heal] [M###/S##], /gsd migrate <path>, or /gsd remote [slack|discord|status|disconnect].`,
+        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status|wizard|setup], /gsd hooks, /gsd doctor [audit|fix|heal] [M###/S##], /gsd migrate <path>, or /gsd remote [slack|discord|status|disconnect].`,
         "warning",
       );
     },

package/dist/resources/extensions/gsd/doctor.ts

@@ -1,3 +1,4 @@
+import { execSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
@@ -5,6 +6,9 @@ import { loadFile, parsePlan, parseRoadmap, parseSummary, saveFile, parseTaskPla
 import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
+import { listWorktrees } from "./worktree-manager.js";
+import { abortAndReset } from "./git-self-heal.js";
+import { RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
@@ -22,7 +26,12 @@ export type DoctorIssueCode =
   | "task_done_must_haves_not_verified"
   | "active_requirement_missing_owner"
   | "blocked_requirement_missing_reason"
-  | "blocker_discovered_no_replan";
+  | "blocker_discovered_no_replan"
+  | "delimiter_in_title"
+  | "orphaned_auto_worktree"
+  | "stale_milestone_branch"
+  | "corrupt_merge_state"
+  | "tracked_runtime_files";
 
 export interface DoctorIssue {
   severity: DoctorSeverity;
@@ -91,15 +100,43 @@ function validatePreferenceShape(preferences: GSDPreferences): string[] {
   return issues;
 }
 
+/**
+ * Characters that are used as delimiters in GSD state management documents
+ * and should not appear in milestone or slice titles.
+ *
+ * - "—" (em dash, U+2014): used as a display separator in STATE.md and other docs.
+ *   A title containing "—" makes the separator ambiguous, corrupting state display
+ *   and confusing the LLM agent that reads and writes these files.
+ * - "–" (en dash, U+2013): visually similar to em dash; same ambiguity risk.
+ * - "/" (forward slash, U+002F): used as the path separator in unit IDs (M001/S01)
+ *   and git branch names (gsd/M001/S01). A slash in a title can break path resolution.
+ */
+const TITLE_DELIMITER_RE = /[\u2014\u2013\/]/; // em dash, en dash, forward slash
+
+/**
+ * Check whether a milestone or slice title contains characters that conflict
+ * with GSD's state document delimiter conventions.
+ * Returns a human-readable description of the problem, or null if the title is safe.
+ */
+export function validateTitle(title: string): string | null {
+  if (TITLE_DELIMITER_RE.test(title)) {
+    const found: string[] = [];
+    if (/[\u2014\u2013]/.test(title)) found.push("em/en dash (\u2014 or \u2013)");
+    if (/\//.test(title)) found.push("forward slash (/)");
+    return `title contains ${found.join(" and ")}, which conflict with GSD state document delimiters`;
+  }
+  return null;
+}
+
 function buildStateMarkdown(state: Awaited<ReturnType<typeof deriveState>>): string {
   const lines: string[] = [];
   lines.push("# GSD State", "");
 
   const activeMilestone = state.activeMilestone
-    ? `${state.activeMilestone.id} — ${state.activeMilestone.title}`
+    ? `${state.activeMilestone.id}: ${state.activeMilestone.title}`
     : "None";
   const activeSlice = state.activeSlice
-    ? `${state.activeSlice.id} — ${state.activeSlice.title}`
+    ? `${state.activeSlice.id}: ${state.activeSlice.title}`
     : "None";
 
   lines.push(`**Active Milestone:** ${activeMilestone}`);
@@ -422,6 +459,189 @@ export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   }).join("\n");
 }
 
+async function checkGitHealth(
+  basePath: string,
+  issues: DoctorIssue[],
+  fixesApplied: string[],
+  shouldFix: (code: DoctorIssueCode) => boolean,
+): Promise<void> {
+  // Degrade gracefully if not a git repo
+  try {
+    execSync("git rev-parse --git-dir", { cwd: basePath, stdio: "pipe" });
+  } catch {
+    return; // Not a git repo — skip all git health checks
+  }
+
+  const gitDir = join(basePath, ".git");
+
+  // ── Orphaned auto-worktrees ──────────────────────────────────────────
+  try {
+    const worktrees = listWorktrees(basePath);
+    const milestoneWorktrees = worktrees.filter(wt => wt.branch.startsWith("milestone/"));
+
+    // Load roadmap state once for cross-referencing
+    const state = await deriveState(basePath);
+
+    for (const wt of milestoneWorktrees) {
+      // Extract milestone ID from branch name "milestone/M001" → "M001"
+      const milestoneId = wt.branch.replace(/^milestone\//, "");
+      const milestoneEntry = state.registry.find(m => m.id === milestoneId);
+
+      // Check if milestone is complete via roadmap
+      let isComplete = false;
+      if (milestoneEntry) {
+        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+        const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+        if (roadmapContent) {
+          const roadmap = parseRoadmap(roadmapContent);
+          isComplete = isMilestoneComplete(roadmap);
+        }
+      }
+
+      if (isComplete) {
+        issues.push({
+          severity: "warning",
+          code: "orphaned_auto_worktree",
+          scope: "milestone",
+          unitId: milestoneId,
+          message: `Worktree for completed milestone ${milestoneId} still exists at ${wt.path}`,
+          fixable: true,
+        });
+
+        if (shouldFix("orphaned_auto_worktree")) {
+          // Never remove a worktree matching current working directory
+          const cwd = process.cwd();
+          if (wt.path === cwd || cwd.startsWith(wt.path + "/")) {
+            fixesApplied.push(`skipped removing worktree at ${wt.path} (is cwd)`);
+          } else {
+            try {
+              execSync(`git worktree remove --force "${wt.path}"`, { cwd: basePath, stdio: "pipe" });
+              fixesApplied.push(`removed orphaned worktree ${wt.path}`);
+            } catch {
+              fixesApplied.push(`failed to remove worktree ${wt.path}`);
+            }
+          }
+        }
+      }
+    }
+
+    // ── Stale milestone branches ─────────────────────────────────────────
+    try {
+      const branchOutput = execSync("git branch --list 'milestone/*'", { cwd: basePath, stdio: "pipe" }).toString().trim();
+      if (branchOutput) {
+        const branches = branchOutput.split("\n").map(b => b.trim().replace(/^\*\s*/, "")).filter(Boolean);
+        const worktreeBranches = new Set(milestoneWorktrees.map(wt => wt.branch));
+
+        for (const branch of branches) {
+          // Skip branches that have a worktree (handled above)
+          if (worktreeBranches.has(branch)) continue;
+
+          const milestoneId = branch.replace(/^milestone\//, "");
+          const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+          const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+          if (!roadmapContent) continue;
+
+          const roadmap = parseRoadmap(roadmapContent);
+          if (isMilestoneComplete(roadmap)) {
+            issues.push({
+              severity: "info",
+              code: "stale_milestone_branch",
+              scope: "milestone",
+              unitId: milestoneId,
+              message: `Branch ${branch} exists for completed milestone ${milestoneId}`,
+              fixable: true,
+            });
+
+            if (shouldFix("stale_milestone_branch")) {
+              try {
+                execSync(`git branch -D "${branch}"`, { cwd: basePath, stdio: "pipe" });
+                fixesApplied.push(`deleted stale branch ${branch}`);
+              } catch {
+                fixesApplied.push(`failed to delete branch ${branch}`);
+              }
+            }
+          }
+        }
+      }
+    } catch {
+      // git branch list failed — skip stale branch check
+    }
+  } catch {
+    // listWorktrees or deriveState failed — skip worktree/branch checks
+  }
+
+  // ── Corrupt merge state ────────────────────────────────────────────────
+  try {
+    const mergeStateFiles = ["MERGE_HEAD", "SQUASH_MSG"];
+    const mergeStateDirs = ["rebase-apply", "rebase-merge"];
+    const found: string[] = [];
+
+    for (const f of mergeStateFiles) {
+      if (existsSync(join(gitDir, f))) found.push(f);
+    }
+    for (const d of mergeStateDirs) {
+      if (existsSync(join(gitDir, d))) found.push(d);
+    }
+
+    if (found.length > 0) {
+      issues.push({
+        severity: "error",
+        code: "corrupt_merge_state",
+        scope: "project",
+        unitId: "project",
+        message: `Corrupt merge/rebase state detected: ${found.join(", ")}`,
+        fixable: true,
+      });
+
+      if (shouldFix("corrupt_merge_state")) {
+        const result = abortAndReset(basePath);
+        fixesApplied.push(`cleaned merge state: ${result.cleaned.join(", ")}`);
+      }
+    }
+  } catch {
+    // Can't check .git dir — skip
+  }
+
+  // ── Tracked runtime files ──────────────────────────────────────────────
+  try {
+    const trackedPaths: string[] = [];
+    for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
+      try {
+        const output = execSync(`git ls-files "${exclusion}"`, { cwd: basePath, stdio: "pipe" }).toString().trim();
+        if (output) {
+          trackedPaths.push(...output.split("\n").filter(Boolean));
+        }
+      } catch {
+        // Individual ls-files can fail — continue
+      }
+    }
+
+    if (trackedPaths.length > 0) {
+      issues.push({
+        severity: "warning",
+        code: "tracked_runtime_files",
+        scope: "project",
+        unitId: "project",
+        message: `${trackedPaths.length} runtime file(s) are tracked by git: ${trackedPaths.slice(0, 5).join(", ")}${trackedPaths.length > 5 ? "..." : ""}`,
+        fixable: true,
+      });
+
+      if (shouldFix("tracked_runtime_files")) {
+        try {
+          for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
+            execSync(`git rm --cached -r --ignore-unmatch "${exclusion}"`, { cwd: basePath, stdio: "pipe" });
+          }
+          fixesApplied.push(`untracked ${trackedPaths.length} runtime file(s)`);
+        } catch {
+          fixesApplied.push("failed to untrack runtime files");
+        }
+      }
+    }
+  } catch {
+    // git ls-files failed — skip
+  }
+}
+
 export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all" }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
@@ -462,6 +682,9 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
+  // Git health checks (orphaned worktrees, stale branches, corrupt merge state, tracked runtime files)
+  await checkGitHealth(basePath, issues, fixesApplied, shouldFix);
+
   const milestonesPath = milestonesDir(basePath);
   if (!existsSync(milestonesPath)) {
     return { ok: issues.every(issue => issue.severity !== "error"), basePath, issues, fixesApplied };
@@ -477,6 +700,20 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     const milestonePath = resolveMilestonePath(basePath, milestoneId);
     if (!milestonePath) continue;
 
+    // Validate milestone title for delimiter characters that break state documents.
+    const milestoneTitleIssue = validateTitle(milestone.title);
+    if (milestoneTitleIssue) {
+      issues.push({
+        severity: "warning",
+        code: "delimiter_in_title",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `Milestone ${milestoneId} ${milestoneTitleIssue}. Rename the milestone to remove these characters to prevent state corruption.`,
+        file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+        fixable: false,
+      });
+    }
+
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
     if (!roadmapContent) continue;
@@ -486,6 +723,20 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       const unitId = `${milestoneId}/${slice.id}`;
       if (options?.scope && !matchesScope(unitId, options.scope) && options.scope !== milestoneId) continue;
 
+      // Validate slice title for delimiter characters.
+      const sliceTitleIssue = validateTitle(slice.title);
+      if (sliceTitleIssue) {
+        issues.push({
+          severity: "warning",
+          code: "delimiter_in_title",
+          scope: "slice",
+          unitId,
+          message: `Slice ${unitId} ${sliceTitleIssue}. Rename the slice to remove these characters to prevent state corruption.`,
+          file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+          fixable: false,
+        });
+      }
+
       const slicePath = resolveSlicePath(basePath, milestoneId, slice.id);
       if (!slicePath) continue;
 

package/dist/resources/extensions/gsd/git-self-heal.ts

@@ -0,0 +1,198 @@
+/**
+ * git-self-heal.ts — Automated git state recovery utilities.
+ *
+ * Four synchronous functions for recovering from broken git state
+ * during auto-mode operations. Uses only `git reset --hard HEAD` —
+ * never `git clean` (which would delete untracked .gsd/ dirs).
+ *
+ * Observability: Each function returns structured results describing
+ * what actions were taken. `formatGitError` maps raw git errors to
+ * user-friendly messages suggesting `/gsd doctor`.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { MergeConflictError } from "./git-service.js";
+
+// Re-export for consumers
+export { MergeConflictError };
+
+/** Result from abortAndReset describing what was cleaned up. */
+export interface AbortAndResetResult {
+  /** List of actions taken, e.g. ["aborted merge", "removed SQUASH_MSG", "reset to HEAD"] */
+  cleaned: string[];
+}
+
+/**
+ * Detect and clean up leftover merge/rebase state, then hard-reset.
+ *
+ * Checks for: .git/MERGE_HEAD, .git/SQUASH_MSG, .git/rebase-apply.
+ * Aborts in-progress merge or rebase if detected. Always finishes
+ * with `git reset --hard HEAD`.
+ *
+ * @returns Structured result listing what was cleaned. Empty `cleaned`
+ *          array means repo was already in a clean state.
+ */
+export function abortAndReset(cwd: string): AbortAndResetResult {
+  const gitDir = join(cwd, ".git");
+  const cleaned: string[] = [];
+
+  // Abort in-progress merge
+  if (existsSync(join(gitDir, "MERGE_HEAD"))) {
+    try {
+      execSync("git merge --abort", { cwd, stdio: "pipe" });
+      cleaned.push("aborted merge");
+    } catch {
+      // merge --abort can fail if state is really broken; continue to reset
+      cleaned.push("merge abort attempted (may have failed)");
+    }
+  }
+
+  // Remove leftover SQUASH_MSG (squash-merge leaves this without MERGE_HEAD)
+  const squashMsgPath = join(gitDir, "SQUASH_MSG");
+  if (existsSync(squashMsgPath)) {
+    try {
+      unlinkSync(squashMsgPath);
+      cleaned.push("removed SQUASH_MSG");
+    } catch {
+      // Not critical
+    }
+  }
+
+  // Abort in-progress rebase
+  if (existsSync(join(gitDir, "rebase-apply")) || existsSync(join(gitDir, "rebase-merge"))) {
+    try {
+      execSync("git rebase --abort", { cwd, stdio: "pipe" });
+      cleaned.push("aborted rebase");
+    } catch {
+      cleaned.push("rebase abort attempted (may have failed)");
+    }
+  }
+
+  // Always hard-reset to HEAD
+  try {
+    execSync("git reset --hard HEAD", { cwd, stdio: "pipe" });
+    if (cleaned.length > 0) {
+      cleaned.push("reset to HEAD");
+    }
+  } catch {
+    cleaned.push("reset to HEAD failed");
+  }
+
+  return { cleaned };
+}
+
+/**
+ * Wrap a merge operation with self-healing retry logic.
+ *
+ * Calls `mergeFn()`. On failure:
+ * - If conflicted files exist (via `git diff --diff-filter=U`), re-throws
+ *   as MergeConflictError immediately — no retry for real code conflicts.
+ * - Otherwise, runs `abortAndReset(cwd)`, retries `mergeFn()` once.
+ * - On second failure, throws the error.
+ *
+ * @param cwd - Working directory for git operations
+ * @param mergeFn - Synchronous function that performs the merge
+ * @returns The return value of `mergeFn()`
+ */
+export function withMergeHeal<T>(cwd: string, mergeFn: () => T): T {
+  try {
+    return mergeFn();
+  } catch (firstError) {
+    // Check for real code conflicts — escalate immediately, no retry
+    try {
+      const conflictOutput = execSync("git diff --name-only --diff-filter=U", {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+
+      if (conflictOutput.length > 0) {
+        const conflictedFiles = conflictOutput.split("\n").filter(Boolean);
+        // If the original error is already a MergeConflictError, re-throw as-is
+        if (firstError instanceof MergeConflictError) {
+          throw firstError;
+        }
+        throw new MergeConflictError(
+          conflictedFiles,
+          "merge",
+          "unknown",
+          "unknown",
+        );
+      }
+    } catch (diffErr) {
+      // If diffErr is a MergeConflictError we just created/re-threw, propagate it
+      if (diffErr instanceof MergeConflictError) throw diffErr;
+      // Otherwise git diff itself failed — proceed with retry
+    }
+
+    // No real conflict detected — try abort+reset+retry once
+    abortAndReset(cwd);
+
+    // Retry
+    return mergeFn();
+  }
+}
+
+/**
+ * Recover a failed checkout by resetting first, then checking out.
+ *
+ * Performs `git reset --hard HEAD` then `git checkout <targetBranch>`.
+ * If checkout still fails after reset, throws with context.
+ */
+export function recoverCheckout(cwd: string, targetBranch: string): void {
+  execSync("git reset --hard HEAD", { cwd, stdio: "pipe" });
+
+  try {
+    execSync(`git checkout ${targetBranch}`, { cwd, stdio: "pipe" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `recoverCheckout failed: could not checkout '${targetBranch}' after reset. ${msg}`,
+    );
+  }
+}
+
+/** Known git error patterns mapped to user-friendly messages. */
+const ERROR_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+  {
+    pattern: /conflict|CONFLICT|merge conflict/i,
+    message: "A merge conflict occurred. Code changes on different branches touched the same files. Run `/gsd doctor` to diagnose.",
+  },
+  {
+    pattern: /cannot checkout|did not match any|pathspec .* did not match/i,
+    message: "Git could not switch branches — the target branch may not exist or the working tree is dirty. Run `/gsd doctor` to diagnose.",
+  },
+  {
+    pattern: /HEAD detached|detached HEAD/i,
+    message: "Git is in a detached HEAD state — not on any branch. Run `/gsd doctor` to diagnose and reattach.",
+  },
+  {
+    pattern: /\.lock|Unable to create .* lock|lock file/i,
+    message: "A git lock file is blocking operations. Another git process may be running, or a previous one crashed. Run `/gsd doctor` to diagnose.",
+  },
+  {
+    pattern: /fatal: not a git repository/i,
+    message: "This directory is not a git repository. Run `/gsd doctor` to check your project setup.",
+  },
+];
+
+/**
+ * Translate raw git error strings into user-friendly messages.
+ *
+ * Pattern-matches against common git error strings and returns
+ * a non-technical message suggesting `/gsd doctor`. Returns the
+ * original message if no pattern matches.
+ */
+export function formatGitError(error: string | Error): string {
+  const errorStr = error instanceof Error ? error.message : error;
+
+  for (const { pattern, message } of ERROR_PATTERNS) {
+    if (pattern.test(errorStr)) {
+      return message;
+    }
+  }
+
+  return `A git error occurred: ${errorStr.slice(0, 200)}. Run \`/gsd doctor\` for help.`;
+}

package/dist/resources/extensions/gsd/git-service.ts

@@ -37,6 +37,8 @@ export interface GitPreferences {
   commit_type?: string;
   main_branch?: string;
   merge_strategy?: "squash" | "merge";
+  isolation?: "worktree" | "branch";
+  merge_to_main?: "milestone" | "slice";
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -764,6 +766,15 @@ export class GitServiceImpl {
       this.git(mergeArgs);
     } catch (mergeError) {
       // Check if conflicts can be auto-resolved (#189, #218)
+      //
+      // ─── BRANCH-MODE ONLY (D038) ────────────────────────────────────────
+      // The conflict resolution logic below applies ONLY when git.isolation = "branch".
+      // In worktree isolation mode, each milestone works in its own worktree directory
+      // so merge conflicts between slice branches and main are handled differently
+      // (worktree teardown merges via worktree-manager). This block is never reached
+      // in worktree mode because mergeSliceToMain is only called from the branch-mode
+      // code path. If you're modifying this logic, verify the isolation mode first.
+      // ─────────────────────────────────────────────────────────────────────
       const conflicted = this.git(["diff", "--name-only", "--diff-filter=U"], { allowFailure: true });
       if (conflicted) {
         const conflictedFiles = conflicted.split("\n").filter(Boolean);