gsd-pi 2.7.1 → 2.8.1

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

@@ -20,18 +20,20 @@
 
 import type {
   ExtensionAPI,
+  ExtensionCommandContext,
   ExtensionContext,
 } from "@gsd/pi-coding-agent";
-import { createBashTool, createWriteTool, createReadTool, createEditTool } from "@gsd/pi-coding-agent";
+import { createBashTool, createWriteTool, createReadTool, createEditTool, isToolCallEventType } from "@gsd/pi-coding-agent";
 
 import { registerGSDCommand } from "./commands.js";
+import { registerExitCommand } from "./exit-command.js";
 import { registerWorktreeCommand, getWorktreeOriginalCwd, getActiveWorktreeName } from "./worktree-command.js";
 import { saveFile, formatContinue, loadFile, parseContinue, parseSummary } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { isAutoActive, isAutoPaused, handleAgentEnd, pauseAuto, getAutoDashboardData } from "./auto.js";
 import { saveActivityLog } from "./activity-log.js";
-import { checkAutoStartAfterDiscuss } from "./guided-flow.js";
+import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId } from "./guided-flow.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import {
   loadEffectiveGSDPreferences,
@@ -42,7 +44,7 @@ import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "./skill-disc
 import {
   resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTaskFiles, resolveTasksDir,
   relSliceFile, relSlicePath, relTaskFile,
-  buildSliceFileName, gsdRoot,
+  buildSliceFileName, buildMilestoneFileName, gsdRoot, resolveMilestonePath,
 } from "./paths.js";
 import { Key } from "@gsd/pi-tui";
 import { join } from "node:path";
@@ -50,6 +52,32 @@ import { existsSync } from "node:fs";
 import { shortcutDesc } from "../shared/terminal.js";
 import { Text } from "@gsd/pi-tui";
 
+// ── Depth verification state ──────────────────────────────────────────────
+let depthVerificationDone = false;
+
+export function isDepthVerified(): boolean {
+  return depthVerificationDone;
+}
+
+// ── Write-gate: block CONTEXT.md writes during discussion without depth verification ──
+const MILESTONE_CONTEXT_RE = /M\d+-CONTEXT\.md$/;
+
+export function shouldBlockContextWrite(
+  toolName: string,
+  inputPath: string,
+  milestoneId: string | null,
+  depthVerified: boolean,
+): { block: boolean; reason?: string } {
+  if (toolName !== "write") return { block: false };
+  if (!milestoneId) return { block: false };
+  if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
+  if (depthVerified) return { block: false };
+  return {
+    block: true,
+    reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`,
+  };
+}
+
 // ── ASCII logo ────────────────────────────────────────────────────────────
 const GSD_LOGO_LINES = [
   "   ██████╗ ███████╗██████╗ ",
@@ -63,22 +91,12 @@ const GSD_LOGO_LINES = [
 export default function (pi: ExtensionAPI) {
   registerGSDCommand(pi);
   registerWorktreeCommand(pi);
-
-  // ── /exit — graceful exit (cleanup auto-mode, save state) ──────────────
-  pi.registerCommand("exit", {
-    description: "Exit GSD gracefully (saves auto-mode state)",
-    handler: async (_ctx) => {
-      // Gracefully stop auto-mode if running (saves activity log, clears locks)
-      const { stopAuto } = await import("./auto.js");
-      await stopAuto(_ctx, pi);
-      process.exit(0);
-    },
-  });
+  registerExitCommand(pi);
 
   // ── /kill — immediate exit (bypass cleanup) ─────────────────────────────
   pi.registerCommand("kill", {
     description: "Exit GSD immediately (no cleanup)",
-    handler: async (_ctx) => {
+    handler: async (_args: string, _ctx: ExtensionCommandContext) => {
       process.exit(0);
     },
   });
@@ -299,7 +317,10 @@ export default function (pi: ExtensionAPI) {
   // ── agent_end: auto-mode advancement or auto-start after discuss ───────────
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
     // If discuss phase just finished, start auto-mode
-    if (checkAutoStartAfterDiscuss()) return;
+    if (checkAutoStartAfterDiscuss()) {
+      depthVerificationDone = false;
+      return;
+    }
 
     // If auto-mode is already running, advance to next unit
     if (!isAutoActive()) return;
@@ -373,6 +394,80 @@ export default function (pi: ExtensionAPI) {
       saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
     }
   });
+
+  // ── tool_call: block CONTEXT.md writes during discussion without depth verification ──
+  pi.on("tool_call", async (event) => {
+    if (!isToolCallEventType("write", event)) return;
+    const result = shouldBlockContextWrite(
+      event.toolName,
+      event.input.path,
+      getDiscussionMilestoneId(),
+      isDepthVerified(),
+    );
+    if (result.block) return result;
+  });
+
+  // ── tool_result: persist discussion exchanges & detect depth gate ──────
+  pi.on("tool_result", async (event) => {
+    if (event.toolName !== "ask_user_questions") return;
+
+    const milestoneId = getDiscussionMilestoneId();
+    if (!milestoneId) return;
+
+    const details = event.details as any;
+    if (details?.cancelled || !details?.response) return;
+
+    // ── Depth gate detection ──────────────────────────────────────────
+    const questions: any[] = (event.input as any)?.questions ?? [];
+    for (const q of questions) {
+      if (typeof q.id === "string" && q.id.includes("depth_verification")) {
+        depthVerificationDone = true;
+        break;
+      }
+    }
+
+    // ── Persist exchange to DISCUSSION.md ──────────────────────────────
+    const basePath = process.cwd();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) return;
+
+    const fileName = buildMilestoneFileName(milestoneId, "DISCUSSION");
+    const discussionPath = join(milestoneDir, fileName);
+    const timestamp = new Date().toISOString();
+
+    // Format exchange as markdown
+    const lines: string[] = [`## Exchange — ${timestamp}`, ""];
+
+    for (const q of questions) {
+      lines.push(`### ${q.header ?? "Question"}`);
+      lines.push("");
+      lines.push(q.question ?? "");
+      if (Array.isArray(q.options)) {
+        lines.push("");
+        for (const opt of q.options) {
+          lines.push(`- **${opt.label}** — ${opt.description ?? ""}`);
+        }
+      }
+
+      // Append user response for this question
+      const answer = details.response?.answers?.[q.id];
+      if (answer) {
+        lines.push("");
+        const selected = Array.isArray(answer.selected) ? answer.selected.join(", ") : answer.selected;
+        lines.push(`**Selected:** ${selected}`);
+        if (answer.notes) {
+          lines.push(`**Notes:** ${answer.notes}`);
+        }
+      }
+      lines.push("");
+    }
+
+    lines.push("---", "");
+
+    const newBlock = lines.join("\n");
+    const existing = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
+    await saveFile(discussionPath, existing + newBlock);
+  });
 }
 
 async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise<string | null> {

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

@@ -702,6 +702,14 @@ function validatePreferences(preferences: GSDPreferences): {
         errors.push(`git.commit_type must be one of: feat, fix, refactor, docs, test, chore, perf, ci, build, style`);
       }
     }
+    if (g.merge_strategy !== undefined) {
+      const validStrategies = new Set(["squash", "merge"]);
+      if (typeof g.merge_strategy === "string" && validStrategies.has(g.merge_strategy)) {
+        git.merge_strategy = g.merge_strategy as "squash" | "merge";
+      } else {
+        errors.push("git.merge_strategy must be one of: squash, merge");
+      }
+    }
     if (g.main_branch !== undefined) {
       if (typeof g.main_branch === "string" && g.main_branch.trim() !== "" && VALID_BRANCH_NAME.test(g.main_branch)) {
         git.main_branch = g.main_branch;

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -17,13 +17,13 @@ Then:
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
 5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
 6. Write `{{sliceSummaryAbsPath}}` (compress all task summaries).
-7. Write `{{sliceUatAbsPath}}`.
+7. Write `{{sliceUatAbsPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
 8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
 9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
 10. Do not commit or squash-merge manually — the system auto-commits your changes and handles the merge after this unit succeeds.
 11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 12. Update `.gsd/STATE.md`
 
-**You MUST mark {{sliceId}} as `[x]` in `{{roadmapPath}}` AND write `{{sliceSummaryAbsPath}}` before finishing.**
+**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryAbsPath}}`, (2) write `{{sliceUatAbsPath}}`, (3) mark {{sliceId}} as `[x]` in `{{roadmapPath}}`. The unit will not be marked complete if any of these files are missing.**
 
 When done, say: "Slice {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -52,6 +52,16 @@ You are a thinking partner, not an interviewer.
 
 **Freeform rule:** When the user selects "Other" or clearly wants to explain something freely, stop using `ask_user_questions` and switch to plain text follow-ups. Let them talk. Resume structured questions when appropriate.
 
+**Depth-signal awareness.** When a user writes extensively about something — long notes, detailed explanations, specific examples — that's a signal. Probe that area deeper. Don't spread attention evenly across all topics when the user is clearly investing energy in one.
+
+**Enrichment fusion.** Weave the user's specific language, terminology, and framing into your subsequent questions. If they said "craft feel," your next question references "craft feel" — don't paraphrase it into "user experience quality." Their precision is signal, not noise.
+
+**Position-first framing.** Have opinions. State your read of a tradeoff with rationale before asking what they think. "I'd lean toward X because Y — does that match your thinking, or am I missing context?" is better than "what do you think about X vs Y?" You're a thinking partner, not a neutral interviewer.
+
+**Negative constraints.** Ask what would disappoint them. What they explicitly don't want. What the product should never feel like. Negative constraints are sharper than positive wishes — "never feel sluggish" defines the performance bar more precisely than "should be fast."
+
+**Observation ≠ Conclusion.** Technical facts you discover in the codebase during investigation are context, not decisions. Present them as context and let the user decide what they mean for direction. "The current auth uses JWT with 24h expiry" is an observation. Whether to keep that pattern is the user's call.
+
 **Anti-patterns — never do these:**
 - **Checklist walking** — going through a predetermined list of topics regardless of what the user said
 - **Canned questions** — asking generic questions that could apply to any project
@@ -73,10 +83,22 @@ Do NOT offer to proceed until ALL of the following are satisfied. Track these in
 - [ ] **The biggest technical unknowns / risks** — what could fail, what hasn't been proven
 - [ ] **What external systems/services this touches** — APIs, databases, third-party services, hardware
 
+Before offering to proceed, demonstrate absorption: reference specific things the user emphasized, specific terminology they used, specific nuance they sharpened — and show how those shaped your understanding. Synthesize, don't recite. "Your emphasis on X led me to prioritize Y over Z" is good. "You said X, you said Y, you said Z" is not. The user should feel heard in the specifics, not just acknowledged in the abstract.
+
 **Questioning depth should match scope.** Simple, well-defined work needs fewer rounds — maybe 1-2. Large, ambiguous visions need more — maybe 4+. Don't pad rounds to hit a number. Stop when the depth checklist is satisfied and you genuinely understand the work.
 
 Do not count the reflection step as a question round. Rounds start after reflection is confirmed.
 
+## Depth Verification
+
+Before moving to the wrap-up gate, present a structured depth summary to the user via `ask_user_questions`. This is a checkpoint — show what you captured across the depth checklist dimensions, using the user's own terminology and framing.
+
+The question should summarize: what you understood them to be building, what shaped your understanding most (their emphasis, constraints, concerns), and any areas where you're least confident in your understanding. Frame it as: "Before we move to planning, here's what I captured — did I get the depth right?"
+
+**Convention:** The question ID must contain `depth_verification` (e.g., `depth_verification_summary`). This naming convention enables downstream mechanical detection of this step.
+
+Offer two options: "Yes, you got it (Recommended)" and "Not quite — let me clarify." If they clarify, absorb the correction and re-verify.
+
 ## Wrap-up Gate
 
 Only after the depth checklist is fully satisfied and you genuinely understand the work, offer to proceed.
@@ -166,6 +188,9 @@ Once the user is satisfied, in a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
 2. Write or update `.gsd/PROJECT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
 3. Write or update `.gsd/REQUIREMENTS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
+**Depth-Preservation Guidance for context.md:**
+When writing context.md, preserve the user's exact terminology, emphasis, and specific framing from the discussion. Do not paraphrase user nuance into generic summaries. If the user said "craft feel," write "craft feel" — not "high-quality user experience." If they emphasized a specific constraint or negative requirement, carry that emphasis through verbatim. The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
+
 4. Write `{{contextAbsPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
 5. Write `{{roadmapAbsPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
 6. Seed `.gsd/DECISIONS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.

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

@@ -0,0 +1,50 @@
+import type { RoadmapSliceEntry, RiskLevel } from "./types.ts";
+
+function extractSlicesSection(content: string): string {
+  const headingMatch = /^## Slices\s*$/m.exec(content);
+  if (!headingMatch || headingMatch.index == null) return "";
+
+  const start = headingMatch.index + headingMatch[0].length;
+  const rest = content.slice(start).replace(/^\r?\n/, "");
+  const nextHeading = /^##\s+/m.exec(rest);
+  return (nextHeading ? rest.slice(0, nextHeading.index) : rest).trimEnd();
+}
+
+export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
+  const slicesSection = extractSlicesSection(content);
+  const slices: RoadmapSliceEntry[] = [];
+  if (!slicesSection) return slices;
+
+  const checkboxItems = slicesSection.split("\n");
+  let currentSlice: RoadmapSliceEntry | null = null;
+
+  for (const line of checkboxItems) {
+    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*(\w+):\s+(.+?)\*\*\s*(.*)/);
+    if (cbMatch) {
+      if (currentSlice) slices.push(currentSlice);
+
+      const done = cbMatch[1].toLowerCase() === "x";
+      const id = cbMatch[2]!;
+      const title = cbMatch[3]!;
+      const rest = cbMatch[4] ?? "";
+
+      const riskMatch = rest.match(/`risk:(\w+)`/);
+      const risk = (riskMatch ? riskMatch[1] : "low") as RiskLevel;
+
+      const depsMatch = rest.match(/`depends:\[([^\]]*)\]`/);
+      const depends = depsMatch && depsMatch[1]!.trim()
+        ? depsMatch[1]!.split(",").map(s => s.trim())
+        : [];
+
+      currentSlice = { id, title, risk, depends, done, demo: "" };
+      continue;
+    }
+
+    if (currentSlice && line.trim().startsWith(">")) {
+      currentSlice.demo = line.trim().replace(/^>\s*/, "").replace(/^After this:\s*/i, "");
+    }
+  }
+
+  if (currentSlice) slices.push(currentSlice);
+  return slices;
+}

package/src/resources/extensions/gsd/tests/dispatch-guard.test.ts

@@ -0,0 +1,102 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getPriorSliceCompletionBlocker } from "../dispatch-guard.ts";
+
+let passed = 0;
+let failed = 0;
+
+function assertEq<T>(actual: T, expected: T, message: string): void {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) {
+    passed += 1;
+    return;
+  }
+  failed += 1;
+  console.error(`FAIL: ${message} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+
+function run(command: string, cwd: string): void {
+  execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+const repo = mkdtempSync(join(tmpdir(), "gsd-dispatch-guard-"));
+try {
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M003"), { recursive: true });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), [
+    "# M002: Previous",
+    "",
+    "## Slices",
+    "- [x] **S01: Done** `risk:low` `depends:[]`",
+    "- [ ] **S02: Pending** `risk:low` `depends:[S01]`",
+    "",
+  ].join("\n"));
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M003", "M003-ROADMAP.md"), [
+    "# M003: Current",
+    "",
+    "## Slices",
+    "- [ ] **S01: First** `risk:low` `depends:[]`",
+    "- [ ] **S02: Second** `risk:low` `depends:[S01]`",
+    "",
+  ].join("\n"));
+
+  run("git init -b main", repo);
+  run("git config user.email test@example.com", repo);
+  run("git config user.name Test", repo);
+  run("git add .", repo);
+  run("git commit -m init", repo);
+
+  assertEq(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M003/S01"),
+    "Cannot dispatch plan-slice M003/S01: earlier slice M002/S02 is not complete on main.",
+    "blocks first slice of next milestone when prior milestone is incomplete on main",
+  );
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), [
+    "# M002: Previous",
+    "",
+    "## Slices",
+    "- [x] **S01: Done** `risk:low` `depends:[]`",
+    "- [x] **S02: Done** `risk:low` `depends:[S01]`",
+    "",
+  ].join("\n"));
+  run("git add .", repo);
+  run("git commit -m complete-m002", repo);
+
+  assertEq(
+    getPriorSliceCompletionBlocker(repo, "main", "execute-task", "M003/S02/T01"),
+    "Cannot dispatch execute-task M003/S02/T01: earlier slice M003/S01 is not complete on main.",
+    "blocks later slice in same milestone when an earlier slice is incomplete on main",
+  );
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M003", "M003-ROADMAP.md"), [
+    "# M003: Current",
+    "",
+    "## Slices",
+    "- [x] **S01: First** `risk:low` `depends:[]`",
+    "- [ ] **S02: Second** `risk:low` `depends:[S01]`",
+    "",
+  ].join("\n"));
+  run("git add .", repo);
+  run("git commit -m complete-m003-s01", repo);
+
+  assertEq(
+    getPriorSliceCompletionBlocker(repo, "main", "execute-task", "M003/S02/T01"),
+    null,
+    "allows dispatch when all earlier slices are complete on main",
+  );
+
+  assertEq(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-milestone", "M003"),
+    null,
+    "does not affect non-slice dispatch types",
+  );
+} finally {
+  rmSync(repo, { recursive: true, force: true });
+}
+
+console.log(`Passed: ${passed}, Failed: ${failed}`);
+if (failed > 0) process.exit(1);

package/src/resources/extensions/gsd/tests/exit-command.test.ts

@@ -0,0 +1,50 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { registerExitCommand } from "../exit-command.ts";
+
+test("/exit requests graceful shutdown instead of process.exit", async () => {
+  const commands = new Map<
+    string,
+    {
+      description?: string;
+      handler: (args: string, ctx: { shutdown: () => Promise<void> }) => Promise<void>;
+    }
+  >();
+
+  const pi = {
+    registerCommand(name: string, options: any) {
+      commands.set(name, options);
+    },
+  };
+
+  let stopAutoCalls = 0;
+  registerExitCommand(pi as any, {
+    async stopAuto() {
+      stopAutoCalls += 1;
+    },
+  });
+
+  const exit = commands.get("exit");
+  assert.ok(exit, "registerExitCommand should register /exit");
+  assert.equal(exit.description, "Exit GSD gracefully");
+
+  let shutdownCalls = 0;
+  const originalExit = process.exit;
+  process.exit = ((code?: number) => {
+    throw new Error(`process.exit should not be called: ${code ?? "undefined"}`);
+  }) as typeof process.exit;
+
+  try {
+    await exit.handler("", {
+      async shutdown() {
+        shutdownCalls += 1;
+      },
+    });
+  } finally {
+    process.exit = originalExit;
+  }
+
+  assert.equal(stopAutoCalls, 1, "handler should stop auto-mode exactly once before shutdown");
+  assert.equal(shutdownCalls, 1, "handler should request graceful shutdown exactly once");
+});

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

@@ -210,8 +210,8 @@ async function main(): Promise<void> {
 
   assertEq(
     RUNTIME_EXCLUSION_PATHS.length,
-    6,
-    "exactly 6 runtime exclusion paths"
+    7,
+    "exactly 7 runtime exclusion paths"
   );
 
   const expectedPaths = [
@@ -220,6 +220,7 @@ async function main(): Promise<void> {
     ".gsd/worktrees/",
     ".gsd/auto.lock",
     ".gsd/metrics.json",
+    ".gsd/completed-units.json",
     ".gsd/STATE.md",
   ];
 
@@ -347,52 +348,76 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
-  // ─── GitServiceImpl: smart staging fallback ────────────────────────────
+  // ─── GitServiceImpl: smart staging excludes tracked runtime files ──────
 
-  console.log("\n=== GitServiceImpl: smart staging fallback ===");
+  console.log("\n=== GitServiceImpl: smart staging excludes tracked runtime files ===");
 
   {
-    // We can't easily make the pathspec fail in a real repo, but we can test
-    // the fallback behavior by verifying that if smart staging somehow fails,
-    // everything gets staged. We do this by checking that a commit with both
-    // runtime and real files works when pathspec would fail.
+    // Reproduces the real bug: .gsd/ runtime files that are already tracked
+    // (in the git index) must be excluded from staging even when .gsd/ is
+    // in .gitignore. The old pathspec-exclude approach failed silently in
+    // this case and fell back to `git add -A`, staging everything.
     //
-    // To force the fallback: temporarily override RUNTIME_EXCLUSION_PATHS
-    // with an invalid pathspec. Since we can't modify a readonly array,
-    // we'll test the actual fallback by creating a custom subclass.
+    // The fix has three layers:
+    // 1. Auto-cleanup: git rm --cached removes tracked runtime files from index
+    // 2. Stage-then-unstage: git add -A + git reset HEAD replaces pathspec excludes
+    // 3. Pre-checkout discard: git checkout -- .gsd/ clears dirty runtime files
 
     const repo = initTempRepo();
+    const svc = new GitServiceImpl(repo);
 
-    // Create a subclass that overrides smartStage to simulate failure + fallback
-    class FallbackTestService extends GitServiceImpl {
-      fallbackUsed = false;
-      smartStageWithBadPathspec(): void {
-        // Simulate: try bad pathspec, catch, fallback
-        try {
-          runGit(this.basePath, ["add", "-A", "--", ".", ":(exclude)__NONEXISTENT_PATHSPEC_SYNTAX_ERROR__["]);
-          // If the above doesn't throw, git accepted it (some versions do).
-          // That's fine — the point is testing the fallback path.
-          throw new Error("force fallback for test");
-        } catch {
-          console.error("GitService: smart staging failed, falling back to git add -A");
-          this.fallbackUsed = true;
-          runGit(this.basePath, ["add", "-A"]);
-        }
-      }
-    }
-
-    const svc = new FallbackTestService(repo);
+    // Simulate a repo where .gsd/ files were previously force-added
+    createFile(repo, ".gsd/metrics.json", '{"version":1}');
+    createFile(repo, ".gsd/completed-units.json", '["unit1"]');
+    createFile(repo, ".gsd/activity/log.jsonl", '{"ts":1}');
     createFile(repo, "src/real.ts", "real code");
-    createFile(repo, ".gsd/activity/log.jsonl", "log");
+    // Force-add .gsd/ files to simulate historical tracking
+    runGit(repo, ["add", "-f", ".gsd/metrics.json", ".gsd/completed-units.json", ".gsd/activity/log.jsonl", "src/real.ts"]);
+    runGit(repo, ["commit", "-F", "-"], { input: "init with tracked runtime files" });
+
+    // Add .gitignore with .gsd/ (matches real-world setup from ensureGitignore)
+    createFile(repo, ".gitignore", ".gsd/\n");
+    runGit(repo, ["add", ".gitignore"]);
+    runGit(repo, ["commit", "-F", "-"], { input: "add gitignore" });
+
+    // Verify runtime files are tracked (precondition)
+    const tracked = run("git ls-files .gsd/", repo);
+    assert(tracked.includes("metrics.json"), "precondition: metrics.json tracked");
+    assert(tracked.includes("completed-units.json"), "precondition: completed-units.json tracked");
+    assert(tracked.includes("activity/log.jsonl"), "precondition: activity log tracked");
+
+    // Now modify both runtime and real files
+    createFile(repo, ".gsd/metrics.json", '{"version":2}');
+    createFile(repo, ".gsd/completed-units.json", '["unit1","unit2"]');
+    createFile(repo, ".gsd/activity/log.jsonl", '{"ts":2}');
+    createFile(repo, "src/real.ts", "updated code");
+
+    // autoCommit should commit real.ts. The first call also runs auto-cleanup
+    // which removes runtime files from the index via a dedicated commit.
+    const msg = svc.autoCommit("execute-task", "M001/S01/T01");
+    assert(msg !== null, "autoCommit produces a commit");
 
-    // Call the fallback path manually
-    svc.smartStageWithBadPathspec();
-
-    // Check that everything was staged (fallback stages all)
-    const staged = run("git diff --cached --name-only", repo);
-    assert(staged.includes("src/real.ts"), "fallback stages real files");
-    assert(staged.includes(".gsd/activity/log.jsonl"), "fallback stages runtime files too (no exclusion)");
-    assert(svc.fallbackUsed, "fallback path was actually used");
+    const show = run("git show --stat HEAD", repo);
+    assert(show.includes("src/real.ts"), "real files are committed");
+
+    // After the commit, runtime files must no longer be in the git index.
+    // They remain on disk but are untracked (protected by .gitignore).
+    const trackedAfter = run("git ls-files .gsd/", repo);
+    assertEq(trackedAfter, "", "no .gsd/ runtime files remain in the index");
+
+    // Verify a second autoCommit with changed runtime files does NOT stage them
+    createFile(repo, ".gsd/metrics.json", '{"version":3}');
+    createFile(repo, ".gsd/completed-units.json", '["unit1","unit2","unit3"]');
+    createFile(repo, "src/real.ts", "third version");
+
+    const msg2 = svc.autoCommit("execute-task", "M001/S01/T02");
+    assert(msg2 !== null, "second autoCommit produces a commit");
+
+    const show2 = run("git show --stat HEAD", repo);
+    assert(show2.includes("src/real.ts"), "real files committed in second commit");
+    assert(!show2.includes("metrics"), "metrics.json not in second commit");
+    assert(!show2.includes("completed-units"), "completed-units.json not in second commit");
+    assert(!show2.includes("activity"), "activity not in second commit");
 
     rmSync(repo, { recursive: true, force: true });
   }