gsd-pi 2.30.0-dev.7e1bbce → 2.30.0-dev.ab42fba

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

@@ -732,11 +732,7 @@ export async function buildPlanSlicePrompt(
   const executorContextConstraints = formatExecutorConstraints();
 
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
-  const prefs = loadEffectiveGSDPreferences();
-  const commitDocsEnabled = prefs?.preferences?.git?.commit_docs !== false;
-  const commitInstruction = commitDocsEnabled
-    ? `Commit the plan files only: \`git add ${relSlicePath(base, mid, sid)}/ .gsd/DECISIONS.md .gitignore && git commit -m "docs(${sid}): add slice plan"\`. Do not stage .gsd/STATE.md or other runtime files — the system manages those.`
-    : "Do not commit — planning docs are not tracked in git for this project.";
+  const commitInstruction = "Do not commit planning artifacts — .gsd/ is managed externally.";
   return loadPrompt("plan-slice", {
     workingDirectory: base,
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
@@ -1194,11 +1190,7 @@ export async function buildReassessRoadmapPrompt(
     // Non-fatal — captures module may not be available
   }
 
-  const reassessPrefs = loadEffectiveGSDPreferences();
-  const reassessCommitDocsEnabled = reassessPrefs?.preferences?.git?.commit_docs !== false;
-  const reassessCommitInstruction = reassessCommitDocsEnabled
-    ? `Commit: \`docs(${mid}): reassess roadmap after ${completedSliceId}\`. Stage only the .gsd/milestones/ 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.";
+  const reassessCommitInstruction = "Do not commit planning artifacts — .gsd/ is managed externally.";
 
   return loadPrompt("reassess-roadmap", {
     workingDirectory: base,

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/resources/extensions/gsd/templates/preferences.md

@@ -20,7 +20,6 @@ git:
   main_branch:
   merge_strategy:
   isolation:
-  commit_docs:
   manage_gitignore:
   worktree_post_create:
 unique_milestone_ids:

package/src/resources/extensions/gsd/tests/git-service.test.ts

@@ -1086,12 +1086,12 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
-  // ─── commit_docs: false — smartStage excludes .gsd/ ──────────────────
+  // ─── smartStage always excludes .gsd/ ──────────────────────────────
 
-  console.log("\n=== commit_docs: false — smartStage excludes .gsd/ ===");
+  console.log("\n=== smartStage always excludes .gsd/ ===");
 
   {
-    const repo = mkdtempSync(join(tmpdir(), "gsd-commit-docs-"));
+    const repo = mkdtempSync(join(tmpdir(), "gsd-smart-stage-excludes-"));
     run("git init -b main", repo);
     run("git config user.email test@test.com", repo);
     run("git config user.name Test", repo);
@@ -1104,65 +1104,37 @@ async function main(): Promise<void> {
     writeFileSync(join(repo, ".gsd", "preferences.md"), "---\nversion: 1\n---");
     writeFileSync(join(repo, "src.ts"), "const x = 1;");
 
-    // With commit_docs: false, smartStage should exclude .gsd/
-    const svc = new GitServiceImpl(repo, { commit_docs: false });
-    const msg = svc.commit({ message: "test commit" });
-    assertTrue(msg !== null, "commit_docs=false: commit succeeds with non-.gsd files");
-
-    // .gsd/ files should NOT be in the commit
-    const committed = run("git show --name-only HEAD", repo);
-    assertTrue(!committed.includes(".gsd/"), "commit_docs=false: .gsd/ files not in commit");
-    assertTrue(committed.includes("src.ts"), "commit_docs=false: source files ARE in commit");
-
-    rmSync(repo, { recursive: true, force: true });
-  }
-
-  // ─── commit_docs: true (default) — smartStage includes .gsd/ ────────
-
-  console.log("\n=== commit_docs: true — smartStage includes .gsd/ ===");
-
-  {
-    const repo = mkdtempSync(join(tmpdir(), "gsd-commit-docs-default-"));
-    run("git init -b main", repo);
-    run("git config user.email test@test.com", repo);
-    run("git config user.name Test", repo);
-    writeFileSync(join(repo, "README.md"), "init");
-    run("git add -A && git commit -m init", repo);
-
-    mkdirSync(join(repo, ".gsd", "milestones", "M001"), { recursive: true });
-    writeFileSync(join(repo, ".gsd", "milestones", "M001", "ROADMAP.md"), "# Roadmap");
-    writeFileSync(join(repo, "src.ts"), "const x = 1;");
-
-    // Default behavior (commit_docs not set) — .gsd/ files ARE committed
+    // smartStage always excludes .gsd/ — state is managed externally
     const svc = new GitServiceImpl(repo);
     const msg = svc.commit({ message: "test commit" });
-    assertTrue(msg !== null, "commit_docs=default: commit succeeds");
+    assertTrue(msg !== null, "smartStage: commit succeeds with non-.gsd files");
 
+    // .gsd/ files should NOT be in the commit
     const committed = run("git show --name-only HEAD", repo);
-    assertTrue(committed.includes(".gsd/"), "commit_docs=default: .gsd/ files ARE in commit");
-    assertTrue(committed.includes("src.ts"), "commit_docs=default: source files in commit");
+    assertTrue(!committed.includes(".gsd/"), "smartStage: .gsd/ files not in commit");
+    assertTrue(committed.includes("src.ts"), "smartStage: source files ARE in commit");
 
     rmSync(repo, { recursive: true, force: true });
   }
 
-  // ─── writeIntegrationBranch: commitDocs false skips commit ──────────
+  // ─── writeIntegrationBranch: no commit (metadata in external storage) ──
 
-  console.log("\n=== writeIntegrationBranch: commitDocs false skips commit ===");
+  console.log("\n=== writeIntegrationBranch: no commit ===");
 
   {
     const repo = initBranchTestRepo();
     const commitsBefore = run("git rev-list --count HEAD", repo);
 
-    writeIntegrationBranch(repo, "M001", "f-123-new-thing", { commitDocs: false });
+    writeIntegrationBranch(repo, "M001", "f-123-new-thing");
 
     // File should still be written to disk
     assertEq(readIntegrationBranch(repo, "M001"), "f-123-new-thing",
-      "commitDocs=false: metadata file exists on disk");
+      "writeIntegrationBranch: metadata file exists on disk");
 
-    // But no new commit should have been created
+    // No commit — .gsd/ is managed externally
     const commitsAfter = run("git rev-list --count HEAD", repo);
     assertEq(commitsBefore, commitsAfter,
-      "commitDocs=false: no git commit created for integration branch");
+      "writeIntegrationBranch: no git commit created for integration branch");
 
     rmSync(repo, { recursive: true, force: true });
   }

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -28,18 +28,12 @@ const BASE_VARS = {
   sourceFilePaths: "- **Requirements**: `.gsd/REQUIREMENTS.md`",
 };
 
-test("plan-slice prompt: commit step present when commit_docs=true", () => {
-  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Commit: `docs(S01): add slice plan`" });
-  assert.ok(result.includes("docs(S01): add slice plan"));
+test("plan-slice prompt: commit instruction says do not commit (external state)", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally." });
+  assert.ok(result.includes("Do not commit planning artifacts"));
   assert.ok(!result.includes("{{commitInstruction}}"));
 });
 
-test("plan-slice prompt: no commit step when commit_docs=false", () => {
-  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit — planning docs are not tracked in git for this project." });
-  assert.ok(!result.includes("docs(S01): add slice plan"));
-  assert.ok(result.includes("Do not commit"));
-});
-
 test("plan-slice prompt: all variables substituted", () => {
   const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Commit: `docs(S01): add slice plan`" });
   assert.ok(!result.includes("{{"));

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -1,6 +1,6 @@
 /**
  * Preferences tests — consolidated from:
- *   - preferences-git.test.ts (git.isolation, git.merge_to_main, git.commit_docs)
+ *   - preferences-git.test.ts (git.isolation, git.merge_to_main)
  *   - preferences-hooks.test.ts (post-unit + pre-dispatch hook config)
  *   - preferences-mode.test.ts (solo/team mode defaults, overrides)
  *   - preferences-models.test.ts (model config parsing, OpenRouter, CRLF)
@@ -39,14 +39,6 @@ test("git.merge_to_main produces deprecation warning", () => {
   }
 });
 
-test("git.commit_docs accepts boolean, rejects string", () => {
-  const { errors: e1, preferences: p1 } = validatePreferences({ git: { commit_docs: false } });
-  assert.equal(e1.length, 0);
-  assert.equal(p1.git?.commit_docs, false);
-
-  const { errors: e2 } = validatePreferences({ git: { commit_docs: "no" as any } });
-  assert.ok(e2.length > 0);
-});
 
 test("getIsolationMode defaults to worktree when no prefs file", { skip: "requires no global ~/.gsd/preferences.md" }, () => {
   assert.equal(getIsolationMode(), "worktree");

package/src/resources/extensions/gsd/tests/worktree.test.ts

@@ -108,10 +108,7 @@ async function main(): Promise<void> {
     assertEq(readIntegrationBranch(repo, "M001"), "f-123-thing",
       "captureIntegrationBranch records the current branch");
 
-    // Verify it was committed (not just written to disk)
-    const logOut = run("git log --oneline -1", repo);
-    assertTrue(logOut.includes("integration branch"), "metadata committed to git");
-
+    // .gsd/ metadata is written to disk only (not committed) since commit_docs removal
     rmSync(repo, { recursive: true, force: true });
   }
 

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

@@ -56,13 +56,13 @@ export function setActiveMilestoneId(basePath: string, milestoneId: string | nul
  * record when the user starts from a different branch (#300). Always a no-op
  * if on a GSD slice branch.
  */
-export function captureIntegrationBranch(basePath: string, milestoneId: string, options?: { commitDocs?: boolean }): void {
+export function captureIntegrationBranch(basePath: string, milestoneId: string): void {
   // In a worktree, the base branch is implicit (worktree/<name>).
   // Writing it to META.json would leave stale metadata after merge back to main.
   if (detectWorktreeName(basePath)) return;
   const svc = getService(basePath);
   const current = svc.getCurrentBranch();
-  writeIntegrationBranch(basePath, milestoneId, current, options);
+  writeIntegrationBranch(basePath, milestoneId, current);
 }
 
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────