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

package/dist/resources/extensions/aws-auth/index.ts

@@ -0,0 +1,144 @@
+/**
+ * AWS Auth Refresh Extension
+ *
+ * Automatically refreshes AWS credentials when Bedrock API requests fail
+ * with authentication/token errors, then retries the user's message.
+ *
+ * ## How it works
+ *
+ * Hooks into `agent_end` to check if the last assistant message failed with
+ * an AWS auth error (expired SSO token, missing credentials, etc.). If so:
+ *
+ *   1. Runs the configured `awsAuthRefresh` command (e.g. `aws sso login`)
+ *   2. Streams the SSO auth URL and verification code to the TUI so users
+ *      can copy/paste if the browser doesn't auto-open
+ *   3. Calls `retryLastTurn()` which removes the failed assistant response
+ *      and re-runs the agent from the user's original message
+ *
+ * ## Activation
+ *
+ * This extension is completely inert unless BOTH conditions are met:
+ *   1. A Bedrock API request fails with a recognized AWS auth error
+ *   2. `awsAuthRefresh` is configured in settings.json
+ *
+ * Non-Bedrock users and Bedrock users without `awsAuthRefresh` configured
+ * are not affected in any way.
+ *
+ * ## Setup
+ *
+ * Add to ~/.gsd/agent/settings.json (or project-level .gsd/settings.json):
+ *
+ *   { "awsAuthRefresh": "aws sso login --profile my-profile" }
+ *
+ * ## Matched error patterns
+ *
+ * The extension recognizes errors from the AWS SDK, Bedrock, and SSO
+ * credential providers including:
+ *   - ExpiredTokenException / ExpiredToken
+ *   - The security token included in the request is expired
+ *   - The SSO session associated with this profile has expired or is invalid
+ *   - Unable to locate credentials / Could not load credentials
+ *   - UnrecognizedClientException
+ *   - Error loading SSO Token / Token does not exist
+ *   - SSOTokenProviderFailure
+ */
+
+import { exec } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+/** Matches AWS SDK / Bedrock / SSO credential and token errors. */
+const AWS_AUTH_ERROR_RE =
+	/ExpiredToken|security token.*expired|unable to locate credentials|SSO.*(?:session|token).*(?:expired|not found|invalid)|UnrecognizedClient|Could not load credentials|Invalid identity token|token is expired|credentials.*(?:could not|cannot|failed to).*(?:load|resolve|find)|The.*token.*is.*not.*valid|token has expired|SSOTokenProviderFailure|Error loading SSO Token|Token.*does not exist/i;
+
+/**
+ * Reads the `awsAuthRefresh` command from settings.json.
+ * Checks project-level first, then global (~/.gsd/agent/settings.json).
+ */
+function getAwsAuthRefreshCommand(): string | undefined {
+	const configDir = process.env.PI_CONFIG_DIR || ".gsd";
+	const paths = [
+		join(process.cwd(), configDir, "settings.json"),
+		join(homedir(), configDir, "agent", "settings.json"),
+	];
+	for (const settingsPath of paths) {
+		if (!existsSync(settingsPath)) continue;
+		try {
+			const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+			if (settings.awsAuthRefresh) return settings.awsAuthRefresh;
+		} catch {}
+	}
+	return undefined;
+}
+
+/**
+ * Runs the refresh command with a 2-minute timeout (for SSO browser flows).
+ * Streams stdout/stderr to capture and display the SSO auth URL and
+ * verification code in real-time via TUI notifications.
+ */
+async function runRefresh(
+	command: string,
+	notify: (msg: string, level: "info" | "warning" | "error") => void,
+): Promise<boolean> {
+	notify("Refreshing AWS credentials...", "info");
+	try {
+		await new Promise<void>((resolve, reject) => {
+			const child = exec(command, { timeout: 120_000, env: { ...process.env } });
+			const onData = (data: Buffer | string) => {
+				const text = data.toString();
+				const urlMatch = text.match(/https?:\/\/\S+/);
+				if (urlMatch) {
+					notify(`Open this URL if the browser didn't launch: ${urlMatch[0]}`, "warning");
+				}
+				const codeMatch = text.match(/code[:\s]+([A-Z]{4}-[A-Z]{4})/i);
+				if (codeMatch) {
+					notify(`Verification code: ${codeMatch[1]}`, "info");
+				}
+			};
+			child.stdout?.on("data", onData);
+			child.stderr?.on("data", onData);
+			child.on("close", (code) => {
+				if (code === 0) resolve();
+				else reject(new Error(`Refresh command exited with code ${code}`));
+			});
+			child.on("error", reject);
+		});
+		notify("AWS credentials refreshed successfully ✓", "info");
+		return true;
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		const isTimeout = /timed out|ETIMEDOUT|killed/i.test(msg);
+		if (isTimeout) {
+			notify("AWS credential refresh timed out. The SSO login may have been cancelled or the browser window was closed.", "error");
+		} else {
+			notify(`AWS credential refresh failed: ${msg}`, "error");
+		}
+		return false;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("agent_end", async (event, ctx) => {
+		const refreshCommand = getAwsAuthRefreshCommand();
+		if (!refreshCommand) return;
+
+		const messages = event.messages;
+		const lastAssistant = messages[messages.length - 1];
+		if (
+			!lastAssistant ||
+			lastAssistant.role !== "assistant" ||
+			!("errorMessage" in lastAssistant) ||
+			!lastAssistant.errorMessage ||
+			!AWS_AUTH_ERROR_RE.test(lastAssistant.errorMessage)
+		) {
+			return;
+		}
+
+		const refreshed = await runRefresh(refreshCommand, (m, level) => ctx.ui.notify(m, level));
+		if (!refreshed) return;
+
+		pi.retryLastTurn();
+	});
+}

package/dist/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/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-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/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/templates/preferences.md

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