gsd-pi 2.30.0 → 2.31.0-dev.6ffc032

package/dist/resources/extensions/gsd/auto-start.ts

@@ -37,7 +37,7 @@ import {
 } from "./session-lock.js";
 import { selfHealRuntimeRecords } from "./auto-recovery.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import {
   captureIntegrationBranch,
@@ -109,9 +109,8 @@ export async function bootstrapAutoSession(
 
   // Ensure .gitignore has baseline patterns
   const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-  const commitDocs = gitPrefs?.commit_docs;
   const manageGitignore = gitPrefs?.manage_gitignore;
-  ensureGitignore(base, { commitDocs, manageGitignore });
+  ensureGitignore(base, { manageGitignore });
   if (manageGitignore !== false) untrackRuntimeFiles(base);
 
   // Migrate legacy in-project .gsd/ to external state directory
@@ -127,12 +126,6 @@ export async function bootstrapAutoSession(
   const gsdDir = gsdRoot(base);
   if (!existsSync(gsdDir)) {
     mkdirSync(join(gsdDir, "milestones"), { recursive: true });
-    if (commitDocs !== false) {
-      try {
-        nativeAddAll(base);
-        nativeCommit(base, "chore: init gsd");
-      } catch { /* nothing to commit */ }
-    }
   }
 
   // Initialize GitServiceImpl
@@ -323,7 +316,7 @@ export async function bootstrapAutoSession(
   // Capture integration branch
   if (s.currentMilestoneId) {
     if (getIsolationMode() !== "none") {
-      captureIntegrationBranch(base, s.currentMilestoneId, { commitDocs });
+      captureIntegrationBranch(base, s.currentMilestoneId);
     }
     setActiveMilestoneId(base, s.currentMilestoneId);
   }

package/dist/resources/extensions/gsd/auto-supervisor.ts

@@ -5,6 +5,7 @@
  */
 
 import { clearLock } from "./crash-recovery.js";
+import { releaseSessionLock } from "./session-lock.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
 
 // ─── SIGTERM Handling ─────────────────────────────────────────────────────────
@@ -23,6 +24,7 @@ export function registerSigtermHandler(
 ): () => void {
   if (previousHandler) process.off("SIGTERM", previousHandler);
   const handler = () => {
+    releaseSessionLock(currentBasePath);
     clearLock(currentBasePath);
     process.exit(0);
   };

package/dist/resources/extensions/gsd/auto-worktree.ts

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, readFileSync, realpathSync, unlinkSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync } from "node:fs";
 import { isAbsolute, join, sep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -370,14 +370,18 @@ export function mergeMilestoneToMain(
   // squash merge can fail with "Your local changes would be overwritten" (#1127).
   autoCommitDirtyState(originalBasePath_);
 
-  // 3b. Remove untracked .gsd/ files that syncStateToProjectRoot copied.
-  // autoCommitDirtyState stages and commits everything (git add -A), but if
-  // the project root branch has no .gsd/ tracking (e.g., .gsd/ is gitignored),
-  // these files remain untracked and cause "untracked working tree files would
-  // be overwritten by merge" during squash-merge (#1237).
+  // 3b. Remove untracked .gsd/ runtime files that syncStateToProjectRoot copied.
+  // Only clean specific runtime files — NEVER touch milestones/, decisions, or
+  // other planning artifacts that represent user work (#1250).
+  const runtimeFilesToClean = ["STATE.md", "completed-units.json", "auto.lock", "gsd.db"];
+  for (const f of runtimeFilesToClean) {
+    const p = join(originalBasePath_, ".gsd", f);
+    try { if (existsSync(p)) unlinkSync(p); } catch { /* non-fatal */ }
+  }
   try {
-    execFileSync("git", ["clean", "-fd", ".gsd/"], { cwd: originalBasePath_, stdio: "pipe" });
-  } catch { /* non-fatal — clean failure shouldn't block merge attempt */ }
+    const runtimeDir = join(originalBasePath_, ".gsd", "runtime");
+    if (existsSync(runtimeDir)) rmSync(runtimeDir, { recursive: true, force: true });
+  } catch { /* non-fatal */ }
 
   // 4. Resolve integration branch — prefer milestone metadata, fall back to preferences / "main"
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};

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

@@ -1132,7 +1132,7 @@ async function dispatchNextUnit(
       midTitle = state.activeMilestone?.title;
 
       if (mid) {
-        captureIntegrationBranch(s.basePath, mid, { commitDocs: loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs });
+        captureIntegrationBranch(s.basePath, mid);
         try {
           const wtPath = createAutoWorktree(s.basePath, mid);
           s.basePath = wtPath;
@@ -1147,7 +1147,7 @@ async function dispatchNextUnit(
       }
     } else {
       if (getIsolationMode() !== "none") {
-        captureIntegrationBranch(s.originalBasePath || s.basePath, mid, { commitDocs: loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs });
+        captureIntegrationBranch(s.originalBasePath || s.basePath, mid);
       }
     }
 

package/dist/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -469,16 +469,6 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
     git.isolation = isolationChoice;
   }
 
-  // commit_docs
-  const currentCommitDocs = git.commit_docs;
-  const commitDocsChoice = await ctx.ui.select(
-    `Track .gsd/ planning docs in git${currentCommitDocs !== undefined ? ` (current: ${currentCommitDocs})` : ""}:`,
-    ["true", "false", "(keep current)"],
-  );
-  if (commitDocsChoice && commitDocsChoice !== "(keep current)") {
-    git.commit_docs = commitDocsChoice === "true";
-  }
-
   if (Object.keys(git).length > 0) {
     prefs.git = git;
   }
@@ -598,13 +588,13 @@ export async function configureMode(ctx: ExtensionCommandContext, prefs: Record<
     if (modeStr.startsWith("solo")) {
       prefs.mode = "solo";
       ctx.ui.notify(
-        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=false",
+        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, unique_milestone_ids=false",
         "info",
       );
     } else if (modeStr.startsWith("team")) {
       prefs.mode = "team";
       ctx.ui.notify(
-        "Mode: team — defaults: auto_push=false, push_branches=true, pre_merge_check=true, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=true",
+        "Mode: team — defaults: auto_push=false, push_branches=true, pre_merge_check=true, merge_strategy=squash, isolation=worktree, unique_milestone_ids=true",
         "info",
       );
     } else {

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -82,7 +82,6 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   | `git.pre_merge_check` | `false` | `true` |
   | `git.merge_strategy` | `"squash"` | `"squash"` |
   | `git.isolation` | `"worktree"` | `"worktree"` |
-  | `git.commit_docs` | `true` | `true` |
   | `unique_milestone_ids` | `false` | `true` |
 
   Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
@@ -127,7 +126,6 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
   - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
-  - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
 
@@ -244,7 +242,7 @@ mode: solo
 ---
 ```
 
-Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `git.commit_docs: true`, `unique_milestone_ids: false`.
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: false`.
 
 **Team — unique IDs, push branches, pre-merge checks:**
 
@@ -255,7 +253,7 @@ mode: team
 ---
 ```
 
-Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `git.commit_docs: true`, `unique_milestone_ids: true`.
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: true`.
 
 **Mode with overrides — team mode but with auto-push:**
 

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

@@ -50,11 +50,6 @@ export interface GitPreferences {
    *  - "none": no git isolation — commits land on the user's current branch directly
    */
   isolation?: "worktree" | "branch" | "none";
-  /** When false, prevents GSD from committing .gsd/ planning artifacts to git.
-   *  The .gsd/ folder is added to .gitignore and kept local-only.
-   *  Default: true (planning docs are tracked in git).
-   */
-  commit_docs?: boolean;
   /** When false, GSD will not modify .gitignore at all — no baseline patterns
    *  are added and no self-healing occurs. Use this if you manage your own
    *  .gitignore and don't want GSD touching it.
@@ -226,7 +221,7 @@ export function readIntegrationBranch(basePath: string, milestoneId: string): st
  *
  * The file is committed immediately so the metadata is persisted in git.
  */
-export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string, options?: { commitDocs?: boolean }): void {
+export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string): void {
   // Don't record slice branches as the integration target
   if (SLICE_BRANCH_RE.test(branch)) return;
   // Validate
@@ -250,18 +245,7 @@ export function writeIntegrationBranch(basePath: string, milestoneId: string, br
 
   existing.integrationBranch = branch;
   writeFileSync(metaFile, JSON.stringify(existing, null, 2) + "\n", "utf-8");
-
-  // Commit immediately so the metadata is persisted in git.
-  // Skip when commit_docs is explicitly false — .gsd/ is local-only.
-  if (options?.commitDocs !== false) {
-    try {
-      nativeAddPaths(basePath, [metaFile]);
-      nativeCommit(basePath, `chore(${milestoneId}): record integration branch`, { allowEmpty: false });
-    } catch {
-      // Non-fatal — file is on disk even if commit fails (e.g. nothing to commit
-      // because the file was already tracked with identical content)
-    }
-  }
+  // .gsd/ is managed externally (symlinked) — metadata is not committed to git.
 }
 
 // ─── Git Helper ────────────────────────────────────────────────────────────
@@ -350,10 +334,8 @@ export class GitServiceImpl {
    * @param extraExclusions Additional pathspec exclusions beyond RUNTIME_EXCLUSION_PATHS.
    */
   private smartStage(extraExclusions: readonly string[] = []): void {
-    // When commit_docs is false, exclude the entire .gsd/ directory from staging
-    const commitDocsDisabled = this.prefs.commit_docs === false;
-    const gsdExclusion = commitDocsDisabled ? [".gsd/"] : [];
-    const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...gsdExclusion, ...extraExclusions];
+    // Always exclude .gsd/ — state is managed externally (symlinked to ~/.gsd/projects/<hash>/)
+    const allExclusions = [".gsd/", ...extraExclusions];
 
     // One-time cleanup: if runtime files are already tracked in the index
     // (from older versions where the fallback bug staged them), untrack them

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

@@ -79,15 +79,14 @@ const BASELINE_PATTERNS = [
 ];
 
 /**
- * Ensure basePath/.gitignore contains all baseline patterns.
- * Creates the file if missing; appends only missing lines if it exists.
+ * Ensure basePath/.gitignore contains a blanket `.gsd/` ignore.
+ * Creates the file if missing; appends `.gsd/` if not present.
  * Returns true if the file was created or modified, false if already complete.
  *
- * When `commitDocs` is false, the entire `.gsd/` directory is added to
- * .gitignore instead of individual runtime patterns, keeping all GSD
- * artifacts local-only.
+ * `.gsd/` state is managed externally (symlinked to `~/.gsd/projects/<hash>/`),
+ * so the entire directory is always gitignored.
  */
-export function ensureGitignore(basePath: string, options?: { commitDocs?: boolean; manageGitignore?: boolean }): boolean {
+export function ensureGitignore(basePath: string, options?: { manageGitignore?: boolean }): boolean {
   // If manage_gitignore is explicitly false, do not touch .gitignore at all
   if (options?.manageGitignore === false) return false;
 
@@ -192,7 +191,7 @@ See \`~/.gsd/agent/extensions/gsd/docs/preferences-reference.md\` for full field
 - \`models\`: Model preferences for specific task types
 - \`skill_discovery\`: Automatic skill detection preferences
 - \`auto_supervisor\`: Supervision and gating rules for autonomous modes
-- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, \`commit_docs\` (set to \`false\` to keep .gsd/ local-only), etc.
+- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, etc.
 
 ## Examples
 

package/dist/resources/extensions/gsd/guided-flow-queue.ts

@@ -25,13 +25,9 @@ import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 
 // ─── Commit Instruction Helper (local copy — avoids circular dep) ───────────
 
-/** Build conditional commit instruction for queue prompts based on commit_docs preference. */
-function buildDocsCommitInstruction(message: string): string {
-  const prefs = loadEffectiveGSDPreferences();
-  const commitDocsEnabled = prefs?.preferences?.git?.commit_docs !== false;
-  return commitDocsEnabled
-    ? `Commit: \`${message}\`. Stage only the .gsd/milestones/, .gsd/PROJECT.md, .gsd/REQUIREMENTS.md, .gsd/DECISIONS.md, and .gitignore files you changed — do not stage .gsd/STATE.md or other runtime files.`
-    : "Do not commit — planning docs are not tracked in git for this project.";
+/** Build commit instruction for queue prompts. .gsd/ is managed externally and always gitignored. */
+function buildDocsCommitInstruction(_message: string): string {
+  return "Do not commit planning artifacts — .gsd/ is managed externally.";
 }
 
 // ─── Queue Entry Point ──────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/guided-flow.ts

@@ -47,13 +47,9 @@ export {
 
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 
-/** Build conditional commit instruction for planning prompts based on commit_docs preference. */
-function buildDocsCommitInstruction(message: string): string {
-  const prefs = loadEffectiveGSDPreferences();
-  const commitDocsEnabled = prefs?.preferences?.git?.commit_docs !== false;
-  return commitDocsEnabled
-    ? `Commit: \`${message}\`. Stage only the .gsd/milestones/, .gsd/PROJECT.md, .gsd/REQUIREMENTS.md, .gsd/DECISIONS.md, and .gitignore files you changed — do not stage .gsd/STATE.md or other runtime files.`
-    : "Do not commit — planning docs are not tracked in git for this project.";
+/** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
+function buildDocsCommitInstruction(_message: string): string {
+  return "Do not commit planning artifacts — .gsd/ is managed externally.";
 }
 
 // ─── Auto-start after discuss ─────────────────────────────────────────────────
@@ -269,8 +265,7 @@ function bootstrapGsdProject(basePath: string): void {
   mkdirSync(join(root, "milestones"), { recursive: true });
   mkdirSync(join(root, "runtime"), { recursive: true });
 
-  const commitDocs = loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs;
-  ensureGitignore(basePath, { commitDocs });
+  ensureGitignore(basePath);
   ensurePreferences(basePath);
   untrackRuntimeFiles(basePath);
 }
@@ -507,6 +502,9 @@ export async function showDiscuss(
 
   // Loop: show picker, dispatch discuss, repeat until "not_yet"
   while (true) {
+    // Invalidate caches so we pick up CONTEXT files written by the just-completed discussion
+    invalidateAllCaches();
+
     // Build discussion-state map: which slices have CONTEXT files already?
     const discussedMap = new Map<string, boolean>();
     for (const s of pendingSlices) {
@@ -783,8 +781,7 @@ export async function showSmartEntry(
   }
 
   // ── Ensure .gitignore has baseline patterns ──────────────────────────
-  const commitDocs = loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs;
-  ensureGitignore(basePath, { commitDocs });
+  ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
 
   // ── Self-heal stale runtime records from crashed auto-mode sessions ──

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

@@ -1048,6 +1048,19 @@ export default function (pi: ExtensionAPI) {
       } catch { /* best-effort */ }
     }
 
+    // Auto-commit dirty work in CLI-spawned worktrees so nothing is lost.
+    // The CLI sets GSD_CLI_WORKTREE when launched with -w.
+    const cliWorktree = process.env.GSD_CLI_WORKTREE;
+    if (cliWorktree) {
+      try {
+        const { autoCommitCurrentBranch } = await import("./worktree.js");
+        const msg = autoCommitCurrentBranch(process.cwd(), "session-end", cliWorktree);
+        if (msg) {
+          ctx.ui.notify(`Auto-committed worktree ${cliWorktree} before exit.`, "info");
+        }
+      } catch { /* best-effort */ }
+    }
+
     if (!isAutoActive() && !isAutoPaused()) return;
 
     // Save the current session — the lock file stays on disk

package/dist/resources/extensions/gsd/init-wizard.ts

@@ -10,7 +10,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { showNextAction } from "../shared/mod.js";
-import { nativeIsRepo, nativeInit, nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { gsdRoot } from "./paths.js";
 import { assertSafeDirectory } from "./validate-directory.js";
@@ -27,7 +27,6 @@ interface InitWizardResult {
 
 interface ProjectPreferences {
   mode: "solo" | "team";
-  commitDocs: boolean;
   gitIsolation: "worktree" | "branch" | "none";
   mainBranch: string;
   verificationCommands: string[];
@@ -41,7 +40,6 @@ interface ProjectPreferences {
 
 const DEFAULT_PREFS: ProjectPreferences = {
   mode: "solo",
-  commitDocs: true,
   gitIsolation: "worktree",
   mainBranch: "main",
   verificationCommands: [],
@@ -149,7 +147,6 @@ export async function showProjectInit(
 
   // ── Step 5: Git preferences ────────────────────────────────────────────────
   const gitSummary: string[] = [];
-  gitSummary.push(`Commit .gsd/ plans to git: yes`);
   gitSummary.push(`Git isolation: worktree`);
   gitSummary.push(`Main branch: ${prefs.mainBranch}`);
 
@@ -230,19 +227,9 @@ export async function showProjectInit(
   bootstrapGsdDirectory(basePath, prefs, signals);
 
   // Ensure .gitignore
-  ensureGitignore(basePath, { commitDocs: prefs.commitDocs });
+  ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
 
-  // Commit if enabled
-  if (prefs.commitDocs && nativeIsRepo(basePath)) {
-    try {
-      nativeAddPaths(basePath, [".gsd", ".gitignore"]);
-      nativeCommit(basePath, "chore: init gsd");
-    } catch {
-      // nothing to commit — that's fine
-    }
-  }
-
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");
 
   return { completed: true, bootstrapped: true };
@@ -338,20 +325,6 @@ async function customizeGitPrefs(
   prefs: ProjectPreferences,
   signals: ProjectSignals,
 ): Promise<void> {
-  // Commit docs
-  const commitChoice = await showNextAction(ctx, {
-    title: "Commit .gsd/ plans to git?",
-    summary: [
-      "When enabled, .gsd/ planning docs are tracked in version control.",
-      "Team projects usually want this. Throwaway prototypes may not.",
-    ],
-    actions: [
-      { id: "yes", label: "Yes", description: "Track .gsd/ in git", recommended: true },
-      { id: "no", label: "No", description: "Keep .gsd/ local-only" },
-    ],
-  });
-  prefs.commitDocs = commitChoice !== "no";
-
   // Isolation strategy
   const hasSubmodules = existsSync(join(process.cwd(), ".gitmodules"));
   const isolationActions = [
@@ -459,7 +432,6 @@ function buildPreferencesFile(prefs: ProjectPreferences): string {
 
   // Git preferences
   lines.push("git:");
-  lines.push(`  commit_docs: ${prefs.commitDocs}`);
   lines.push(`  isolation: ${prefs.gitIsolation}`);
   lines.push(`  main_branch: ${prefs.mainBranch}`);
   lines.push(`  auto_push: ${prefs.autoPush}`);

package/dist/resources/extensions/gsd/preferences-types.ts

@@ -34,7 +34,6 @@ export const MODE_DEFAULTS: Record<WorkflowMode, Partial<GSDPreferences>> = {
       pre_merge_check: false,
       merge_strategy: "squash",
       isolation: "worktree",
-      commit_docs: true,
     },
     unique_milestone_ids: false,
   },
@@ -45,7 +44,6 @@ export const MODE_DEFAULTS: Record<WorkflowMode, Partial<GSDPreferences>> = {
       pre_merge_check: true,
       merge_strategy: "squash",
       isolation: "worktree",
-      commit_docs: true,
     },
     unique_milestone_ids: true,
   },

package/dist/resources/extensions/gsd/preferences-validation.ts

@@ -559,8 +559,7 @@ export function validatePreferences(preferences: GSDPreferences): {
       }
     }
     if (g.commit_docs !== undefined) {
-      if (typeof g.commit_docs === "boolean") git.commit_docs = g.commit_docs;
-      else errors.push("git.commit_docs must be a boolean");
+      warnings.push("git.commit_docs is deprecated — .gsd/ is managed externally and always gitignored. Remove this setting.");
     }
     if (g.manage_gitignore !== undefined) {
       if (typeof g.manage_gitignore === "boolean") git.manage_gitignore = g.manage_gitignore;

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

@@ -96,24 +96,39 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
 
 /**
  * Fallback parser for prose-style roadmaps where the LLM wrote
- * `## Slice S01: Title` headers instead of the machine-readable
- * `## Slices` checklist. Extracts slice IDs and titles so auto-mode
- * can at least identify slices and plan them.
+ * slice headers instead of the machine-readable `## Slices` checklist.
+ * Extracts slice IDs and titles so auto-mode can at least identify
+ * slices and plan them.
  *
- * Also handles `## S01: Title` and `## S01 — Title` variants.
+ * Handles these LLM-generated variants:
+ *   ## S01: Title           (H2, colon separator)
+ *   ### S01: Title          (H3)
+ *   #### S01: Title         (H4)
+ *   ## Slice S01: Title     (with "Slice" prefix)
+ *   ## S01 — Title          (em dash)
+ *   ## S01 – Title          (en dash)
+ *   ## S01 - Title          (hyphen)
+ *   ## S01. Title           (dot separator)
+ *   ## S01 Title            (space only, no separator)
+ *   ## **S01: Title**       (bold-wrapped)
+ *   ## **S01**: Title       (bold ID only)
+ *   ## S1: Title            (non-zero-padded ID)
  */
 function parseProseSliceHeaders(content: string): RoadmapSliceEntry[] {
   const slices: RoadmapSliceEntry[] = [];
-  const headerPattern = /^##\s+(?:Slice\s+)?(S\d+)[:\s—–-]+\s*(.+)/gm;
+  // Match H1–H4 headers containing S<digits> with optional "Slice" prefix and bold markers.
+  // Separator after the ID is flexible: colon, dash, em/en dash, dot, or just whitespace.
+  const headerPattern = /^#{1,4}\s+\*{0,2}(?:Slice\s+)?(S\d+)\*{0,2}[:\s.—–-]*\s*(.+)/gm;
   let match: RegExpExecArray | null;
 
   while ((match = headerPattern.exec(content)) !== null) {
     const id = match[1]!;
-    const title = match[2]!.trim();
+    let title = match[2]!.trim().replace(/\*{1,2}$/g, "").trim(); // strip trailing bold markers
+    if (!title) continue; // skip if we only matched the ID with no title
 
     // Try to extract depends from prose: "Depends on: S01" or "**Depends on:** S01, S02"
     const afterHeader = content.slice(match.index + match[0].length);
-    const nextHeader = afterHeader.search(/^##\s/m);
+    const nextHeader = afterHeader.search(/^#{1,4}\s/m);
     const section = nextHeader !== -1 ? afterHeader.slice(0, nextHeader) : afterHeader.slice(0, 500);
 
     const depsMatch = section.match(/\*{0,2}Depends\s+on:?\*{0,2}\s*(.+)/i);

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

@@ -17,7 +17,7 @@
  */
 
 import { createRequire } from "node:module";
-import { existsSync, readFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, unlinkSync, rmSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -51,6 +51,9 @@ let _lockedPath: string | null = null;
 /** Our PID at lock acquisition time. */
 let _lockPid: number = 0;
 
+/** Set to true when proper-lockfile fires onCompromised (mtime drift, sleep, etc.). */
+let _lockCompromised: boolean = false;
+
 const LOCK_FILE = "auto.lock";
 
 function lockPath(basePath: string): string {
@@ -92,33 +95,80 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     return acquireFallbackLock(basePath, lp, lockData);
   }
 
+  const gsdDir = gsdRoot(basePath);
+
   try {
     // Try to acquire an exclusive OS-level lock on the lock file.
     // We lock the directory (gsdRoot) since proper-lockfile works best
     // on directories, and the lock file itself may not exist yet.
-    const gsdDir = gsdRoot(basePath);
     mkdirSync(gsdDir, { recursive: true });
 
     const release = lockfile.lockSync(gsdDir, {
       realpath: false,
-      stale: 300_000, // 5 minutes — consider lock stale if holder hasn't updated
+      stale: 1_800_000, // 30 minutes — safe for laptop sleep / long event loop stalls
       update: 10_000, // Update lock mtime every 10s to prove liveness
+      onCompromised: () => {
+        // proper-lockfile detected mtime drift (system sleep, event loop stall, etc.).
+        // Default handler throws inside setTimeout — an uncaught exception that crashes
+        // or corrupts process state. Instead, set a flag so validateSessionLock() can
+        // detect the compromise gracefully on the next dispatch cycle.
+        _lockCompromised = true;
+        _releaseFunction = null;
+      },
     });
 
     _releaseFunction = release;
     _lockedPath = basePath;
     _lockPid = process.pid;
+    _lockCompromised = false;
+
+    // Safety net: clean up lock dir on process exit if _releaseFunction
+    // wasn't called (e.g., normal exit after clean completion) (#1245).
+    const lockDirForCleanup = join(gsdDir + ".lock");
+    process.once("exit", () => {
+      try {
+        if (_releaseFunction) { _releaseFunction(); _releaseFunction = null; }
+      } catch { /* best-effort */ }
+      try {
+        if (existsSync(lockDirForCleanup)) rmSync(lockDirForCleanup, { recursive: true, force: true });
+      } catch { /* best-effort */ }
+    });
 
     // Write the informational lock data
     atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
 
     return { acquired: true };
   } catch (err) {
-    // Lock is held by another process
+    // Lock is held by another process — or the .gsd.lock/ directory is stranded.
+    // Check: if auto.lock is gone and no process is alive, the lock dir is stale.
     const existingData = readExistingLockData(lp);
     const existingPid = existingData?.pid;
+
+    // If no lock file or no alive process, try to clean up and re-acquire (#1245)
+    if (!existingData || (existingPid && !isPidAlive(existingPid))) {
+      try {
+        const lockDir = join(gsdDir + ".lock");
+        if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+        if (existsSync(lp)) unlinkSync(lp);
+
+        // Retry acquisition after cleanup
+        const release = lockfile.lockSync(gsdDir, {
+          realpath: false,
+          stale: 300_000,
+          update: 10_000,
+        });
+        _releaseFunction = release;
+        _lockedPath = basePath;
+        _lockPid = process.pid;
+        atomicWriteSync(lp, JSON.stringify(lockData, null, 2));
+        return { acquired: true };
+      } catch {
+        // Retry also failed — fall through to the error path
+      }
+    }
+
     const reason = existingPid
-      ? `Another auto-mode session (PID ${existingPid}) is already running on this project.`
+      ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
       : `Another auto-mode session is already running on this project.`;
 
     return { acquired: false, reason, existingPid };
@@ -195,6 +245,11 @@ export function updateSessionLock(
  * This is called periodically during the dispatch loop.
  */
 export function validateSessionLock(basePath: string): boolean {
+  // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
+  if (_lockCompromised) {
+    return false;
+  }
+
   // If we have an OS-level lock, we're still the owner
   if (_releaseFunction && _lockedPath === basePath) {
     return true;
@@ -233,8 +288,20 @@ export function releaseSessionLock(basePath: string): void {
     // Non-fatal
   }
 
+  // Remove the proper-lockfile directory (.gsd.lock/) if it exists.
+  // proper-lockfile creates this directory as the OS-level lock mechanism.
+  // If the process exits without calling _releaseFunction (SIGKILL, crash),
+  // this directory is stranded and blocks the next session (#1245).
+  try {
+    const lockDir = join(gsdRoot(basePath) + ".lock");
+    if (existsSync(lockDir)) rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    // Non-fatal
+  }
+
   _lockedPath = null;
   _lockPid = 0;
+  _lockCompromised = false;
 }
 
 /**