gsd-pi 2.80.0-dev.c5f2443b3 → 2.80.0-dev.d4fc28e6b

package/src/resources/extensions/gsd/tests/auto-phases-lifecycle.test.ts

@@ -1,17 +1,20 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 
 import { runFinalize } from "../auto/phases.ts";
 import { AutoSession } from "../auto/session.ts";
+import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "../unit-runtime.ts";
 
-test("runFinalize clears currentUnit after successful finalize", async () => {
-  const s = new AutoSession();
-  s.basePath = "/tmp/gsd-finalize-current-unit";
-  s.currentUnit = {
-    type: "execute-task",
-    id: "M001/S01/T01",
-    startedAt: Date.now(),
-  };
+async function runSuccessfulFinalize(s: AutoSession) {
+  const unit = s.currentUnit;
+  assert.ok(unit, "test setup must provide currentUnit");
+
+  writeUnitRuntimeRecord(s.basePath, unit.type, unit.id, unit.startedAt, {
+    phase: "dispatched",
+  });
 
   const deps = {
     clearUnitTimeout() {},
@@ -26,7 +29,7 @@ test("runFinalize clears currentUnit after successful finalize", async () => {
     postUnitPostVerification: async () => "continue",
   };
 
-  const result = await runFinalize(
+  return runFinalize(
     {
       ctx: { ui: { notify() {} } },
       pi: {},
@@ -38,8 +41,8 @@ test("runFinalize clears currentUnit after successful finalize", async () => {
       nextSeq: () => 1,
     } as any,
     {
-      unitType: "execute-task",
-      unitId: "M001/S01/T01",
+      unitType: unit.type,
+      unitId: unit.id,
       prompt: "",
       finalPrompt: "",
       pauseAfterUatDispatch: false,
@@ -55,7 +58,47 @@ test("runFinalize clears currentUnit after successful finalize", async () => {
       consecutiveFinalizeTimeouts: 0,
     },
   );
+}
+
+test("runFinalize clears currentUnit after successful finalize", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-finalize-current-unit-"));
+  const s = new AutoSession();
+  s.basePath = base;
+  s.currentUnit = {
+    type: "execute-task",
+    id: "M001/S01/T01",
+    startedAt: Date.now(),
+  };
+
+  try {
+    const result = await runSuccessfulFinalize(s);
+
+    assert.equal(result.action, "next");
+    assert.equal(s.currentUnit, null);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("runFinalize marks unit runtime finalized after successful finalize", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-finalize-runtime-"));
+  const s = new AutoSession();
+  const startedAt = Date.now();
+  s.basePath = base;
+  s.currentUnit = {
+    type: "complete-milestone",
+    id: "M001",
+    startedAt,
+  };
+
+  try {
+    const result = await runSuccessfulFinalize(s);
+    const runtime = readUnitRuntimeRecord(base, "complete-milestone", "M001");
 
-  assert.equal(result.action, "next");
-  assert.equal(s.currentUnit, null);
+    assert.equal(result.action, "next");
+    assert.equal(runtime?.phase, "finalized");
+    assert.equal(runtime?.lastProgressKind, "finalize-success");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
 });

package/src/resources/extensions/gsd/tests/auto-recovery.test.ts

@@ -5,13 +5,14 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
-import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder } from "../auto-recovery.ts";
+import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder, refreshRecoveryDbForArtifact } from "../auto-recovery.ts";
 import { resolveMilestoneFile } from "../paths.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow, insertTask } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow, insertTask, getMilestoneCommitAttributionShas } from "../gsd-db.ts";
 import { clearParseCache } from "../files.ts";
 import { parseRoadmap } from "../parsers-legacy.ts";
 import { invalidateAllCaches } from "../cache.ts";
 import { deriveState, invalidateStateCache } from "../state.ts";
+import { writeIntegrationBranch } from "../git-service.ts";
 
 const tmpDirs: string[] = [];
 
@@ -174,6 +175,19 @@ test("resolveExpectedArtifactPath returns correct path for all slice-level types
   }
 });
 
+test("refreshRecoveryDbForArtifact treats missing execute-task DB rows as fatal mismatches", () => {
+  makeTmpProject();
+
+  const result = refreshRecoveryDbForArtifact("execute-task", "M001/S01/T01");
+
+  assert.deepEqual(result, {
+    ok: false,
+    fatal: true,
+    reason: "execute-task-artifact-db-missing",
+    message: "Stuck recovery found execute-task M001/S01/T01 artifacts, but no matching DB task row exists after refresh.",
+  });
+});
+
 // ─── diagnoseExpectedArtifact ─────────────────────────────────────────────
 
 test("diagnoseExpectedArtifact returns description for known types", () => {
@@ -735,6 +749,174 @@ test("hasImplementationArtifacts rejects milestone-scoped main history with only
   }
 });
 
+test("hasImplementationArtifacts finds integration implementation-only commits when milestone branch diff is .gsd-only", () => {
+  const base = makeGitBase();
+  try {
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "feature.ts"), "export function feature() {}\n");
+    execFileSync("git", ["add", "src/feature.ts"], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: add milestone feature\n\nGSD-Task: S01/T01"], { cwd: base, stdio: "ignore" });
+
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "M001",
+      title: "Slice One",
+      status: "complete",
+      risk: "low",
+      depends: [],
+    });
+    insertTask({
+      id: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      title: "Task One",
+      status: "complete",
+    });
+
+    execFileSync("git", ["checkout", "-b", "milestone/M001"], { cwd: base, stdio: "ignore" });
+    writeIntegrationBranch(base, "M001", "main");
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nDone.");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "chore: auto-commit after complete-milestone\n\nGSD-Unit: M001"], { cwd: base, stdio: "ignore" });
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(
+      result,
+      "present",
+      ".gsd-only milestone closeout diffs should still honor implementation commits already on the integration branch",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("hasImplementationArtifacts backfills untagged main implementation commits from completed task file hints", () => {
+  const base = makeGitBase();
+  try {
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "M001",
+      title: "Slice One",
+      status: "complete",
+      risk: "low",
+      depends: [],
+    });
+    insertTask({
+      id: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      title: "Task One",
+      status: "complete",
+      keyFiles: ["index.html", "style.css", "app.js"],
+      planning: { files: ["index.html", "style.css", "app.js"] },
+    });
+
+    writeFileSync(join(base, "index.html"), "<main></main>\n");
+    writeFileSync(join(base, "style.css"), "main { display: block; }\n");
+    writeFileSync(join(base, "app.js"), "document.body.dataset.ready = 'true';\n");
+    execFileSync("git", ["add", "index.html", "style.css", "app.js"], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: add to-do app with CRUD and localStorage persistence"], { cwd: base, stdio: "ignore" });
+    const commitSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: base, encoding: "utf-8" }).trim();
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(
+      result,
+      "present",
+      "completed task file hints should repair prior untagged implementation commits on main",
+    );
+    assert.deepEqual(getMilestoneCommitAttributionShas("M001"), [commitSha]);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("hasImplementationArtifacts does not backfill untagged commits before milestone creation", () => {
+  const base = makeGitBase();
+  try {
+    writeFileSync(join(base, "app.js"), "document.body.dataset.ready = 'old';\n");
+    execFileSync("git", ["add", "app.js"], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: old app work"], {
+      cwd: base,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        GIT_AUTHOR_DATE: "2020-01-01T00:00:00Z",
+        GIT_COMMITTER_DATE: "2020-01-01T00:00:00Z",
+      },
+    });
+
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "M001",
+      title: "Slice One",
+      status: "complete",
+      risk: "low",
+      depends: [],
+    });
+    insertTask({
+      id: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      title: "Task One",
+      status: "complete",
+      keyFiles: ["app.js"],
+      planning: { files: ["app.js"] },
+    });
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(result, "absent", "pre-milestone commits must not be attributed to the milestone");
+    assert.deepEqual(getMilestoneCommitAttributionShas("M001"), []);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("hasImplementationArtifacts does not backfill unrelated untagged implementation commits", () => {
+  const base = makeGitBase();
+  try {
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    openDatabase(join(base, ".gsd", "gsd.db"));
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "M001",
+      title: "Slice One",
+      status: "complete",
+      risk: "low",
+      depends: [],
+    });
+    insertTask({
+      id: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      title: "Task One",
+      status: "complete",
+      keyFiles: ["src/expected.ts"],
+      planning: { files: ["src/expected.ts"] },
+    });
+
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "unrelated.ts"), "export const unrelated = true;\n");
+    execFileSync("git", ["add", "src/unrelated.ts"], { cwd: base, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", "feat: unrelated work"], { cwd: base, stdio: "ignore" });
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(result, "absent", "backfill must require overlap with completed task file hints");
+    assert.deepEqual(getMilestoneCommitAttributionShas("M001"), []);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("hasImplementationArtifacts treats empty non-integration branch diff as absent (#4699)", () => {
   const base = makeGitBase();
   try {

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -3,8 +3,14 @@
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { autoSession } from "../auto-runtime-state.ts";
+import { dispatchHookUnit } from "../auto.ts";
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { clearDiscussionFlowState, getPendingGate } from "../bootstrap/write-gate.ts";
 
 const autoTimersPath = join(import.meta.dirname, "..", "auto-timers.ts");
 const autoTimersSrc = readFileSync(autoTimersPath, "utf-8");
@@ -18,6 +24,37 @@ const runUnitSrc = readFileSync(runUnitPath, "utf-8");
 const registerHooksPath = join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts");
 const registerHooksSrc = readFileSync(registerHooksPath, "utf-8");
 
+function makeHookHarness() {
+  const handlers = new Map<string, Array<(event: any, ctx: any) => Promise<any>>>();
+  const pi = {
+    on(name: string, handler: (event: any, ctx: any) => Promise<any>) {
+      const current = handlers.get(name) ?? [];
+      current.push(handler);
+      handlers.set(name, current);
+    },
+  };
+  const ctx = {
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setWidget: () => {},
+    },
+    modelRegistry: {
+      setDisabledModelProviders: () => {},
+    },
+    setCompactionThresholdOverride: () => {},
+  };
+  async function emit(name: string, event: any): Promise<any> {
+    for (const handler of handlers.get(name) ?? []) {
+      const result = await handler(event, ctx);
+      if (result?.block) return result;
+    }
+    return undefined;
+  }
+  registerHooks(pi as any, []);
+  return { emit };
+}
+
 describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () => {
   test("soft timeout wrapup gates triggerTurn on getInFlightToolCount() === 0", () => {
     // The soft timeout sendMessage must NOT use a hardcoded `triggerTurn: true`.
@@ -73,10 +110,65 @@ describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () =>
   });
 });
 
+describe("hook dispatch session workspace root", () => {
+  test("dispatchHookUnit passes basePath explicitly to newSession", async (t) => {
+    const originalCwd = process.cwd();
+    const basePath = mkdtempSync(join(tmpdir(), "gsd-hook-cwd-"));
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    autoSession.reset();
+    t.after(() => {
+      try {
+        process.chdir(originalCwd);
+      } catch {
+        // best effort cleanup after cwd-sensitive dispatch tests
+      }
+      autoSession.reset();
+      rmSync(basePath, { recursive: true, force: true });
+    });
+
+    let newSessionOptions: unknown;
+    const ctx = {
+      ui: {
+        notify: () => {},
+        setStatus: () => {},
+        setWidget: () => {},
+      },
+      modelRegistry: {
+        getAvailable: () => [],
+      },
+      sessionManager: {
+        getSessionFile: () => join(basePath, "session.jsonl"),
+      },
+      newSession: async (options?: unknown) => {
+        newSessionOptions = options;
+        return { cancelled: false };
+      },
+    };
+    const pi = {
+      sendMessage: () => {},
+      setModel: async () => true,
+    };
+
+    const dispatched = await dispatchHookUnit(
+      ctx as any,
+      pi as any,
+      "review",
+      "execute-task",
+      "M001/S01/T01",
+      "review the completed unit",
+      undefined,
+      basePath,
+    );
+
+    assert.equal(dispatched, true);
+    assert.deepEqual(newSessionOptions, { workspaceRoot: basePath });
+  });
+});
+
 describe("#4276: pending/skipped tools stay visible to auto-mode hooks", () => {
   test("tool_call handler marks GSD tools in-flight before execution_start", () => {
     const startMarker = 'pi.on("tool_call", async (event, ctx) => {';
-    const endMarker = 'pi.on("tool_result", async (event) => {';
+    const endMarker = 'pi.on("tool_result", async (event, ctx) => {';
     const toolCallSection = registerHooksSrc.slice(
       registerHooksSrc.indexOf(startMarker),
       registerHooksSrc.indexOf(endMarker),
@@ -90,7 +182,7 @@ describe("#4276: pending/skipped tools stay visible to auto-mode hooks", () => {
   });
 
   test("tool_result handler clears pending tools and records queued-skip errors", () => {
-    const startMarker = 'pi.on("tool_result", async (event) => {';
+    const startMarker = 'pi.on("tool_result", async (event, ctx) => {';
     const endMarker = 'pi.on("tool_execution_start", async (event) => {';
     const toolResultSection = registerHooksSrc.slice(
       registerHooksSrc.indexOf(startMarker),
@@ -193,7 +285,7 @@ describe("#4365: tool_execution_start hook must pass toolName to markToolStart",
 });
 
 describe("deep setup approval questions pause immediately", () => {
-  test("register-hooks sets pending gate during message_update without aborting the stream", () => {
+  test("register-hooks defers the pending gate during message_update without aborting the stream", () => {
     const startMarker = 'pi.on("message_update"';
     const endMarker = 'pi.on("session_shutdown"';
     const messageUpdateSection = registerHooksSrc.slice(
@@ -210,8 +302,8 @@ describe("deep setup approval questions pause immediately", () => {
       "message_update must detect approval/question boundaries",
     );
     assert.ok(
-      messageUpdateSection.includes("approvalGateIdForUnit") && messageUpdateSection.includes("setPendingGate"),
-      "plain-text approval questions must set the durable write gate",
+      messageUpdateSection.includes("approvalGateIdForUnit") && messageUpdateSection.includes("deferApprovalGate"),
+      "plain-text approval questions must defer the durable write gate until same-turn draft persistence can finish",
     );
     assert.ok(
       messageUpdateSection.includes("getDiscussionMilestoneIdFor") && messageUpdateSection.includes('"discuss-milestone"'),
@@ -222,4 +314,74 @@ describe("deep setup approval questions pause immediately", () => {
       "message_update must NOT abort the stream — aborting eats the model's question text on external CLI providers; the pending gate set above blocks subsequent tool calls instead",
     );
   });
+
+  test("plain-text approval boundary defers durable gate until same-turn CONTEXT-DRAFT can save", async () => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-deferred-approval-")));
+    const previousCwd = process.cwd();
+    try {
+      mkdirSync(join(base, ".gsd", "milestones", "M003"), { recursive: true });
+      process.chdir(base);
+      clearDiscussionFlowState(base);
+      autoSession.reset();
+      autoSession.basePath = base;
+      autoSession.currentUnit = {
+        type: "discuss-milestone",
+        id: "M003",
+        startedAt: Date.now(),
+      };
+
+      const { emit } = makeHookHarness();
+      await emit("message_update", {
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Did I capture that correctly? If not, tell me what I missed." }],
+        },
+      });
+
+      assert.equal(
+        getPendingGate(base),
+        null,
+        "approval text should not install the durable pending gate until the assistant turn ends",
+      );
+
+      const draftResult = await emit("tool_call", {
+        toolCallId: "draft-save",
+        toolName: "gsd_summary_save",
+        input: {
+          milestone_id: "M003",
+          artifact_type: "CONTEXT-DRAFT",
+          content: "# M003 Draft\n",
+        },
+      });
+      assert.equal(
+        draftResult?.block,
+        undefined,
+        "same-turn CONTEXT-DRAFT persistence should remain allowed after the approval text streams",
+      );
+
+      const finalContextResult = await emit("tool_call", {
+        toolCallId: "final-context",
+        toolName: "gsd_summary_save",
+        input: {
+          milestone_id: "M003",
+          artifact_type: "CONTEXT",
+          content: "# M003 Context\n",
+        },
+      });
+      assert.equal(finalContextResult?.block, true, "final CONTEXT must still wait for approval");
+      assert.match(finalContextResult.reason, /Approval question "depth_verification_M003_confirm"/);
+
+      await emit("agent_end", { messages: [] });
+      assert.equal(
+        getPendingGate(base),
+        "depth_verification_M003_confirm",
+        "agent_end should activate the durable pending gate for the next turn",
+      );
+    } finally {
+      process.chdir(previousCwd);
+      autoSession.reset();
+      clearDiscussionFlowState(base);
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/clean-root-preflight.test.ts

@@ -131,9 +131,11 @@ test("postflightPopStash — restores stashed changes and emits info notificatio
     run('git commit -m "simulate merge"', repo);
 
     const postNotifications: Array<{ msg: string; level: string }> = [];
-    postflightPopStash(repo, "M004", (msg, level) => {
+    const postflight = postflightPopStash(repo, "M004", preflight.stashMarker, (msg, level) => {
       postNotifications.push({ msg, level });
     });
+    assert.equal(postflight.restored, true, "postflight must report successful restore");
+    assert.equal(postflight.needsManualRecovery, false, "successful restore must not need manual recovery");
 
     // The stashed README.md change must be restored
     const content = readFileSync(join(repo, "README.md"), "utf-8");
@@ -171,7 +173,8 @@ test("preflight + merge + postflight round-trip preserves uncommitted changes",
     run('git commit -m "feat: add feature"', repo);
 
     // Postflight: pop stash
-    postflightPopStash(repo, "M005", () => {});
+    const postflight = postflightPopStash(repo, "M005", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "clean restore must not stop auto-mode");
 
     // README.md must still have our local content
     const restored = readFileSync(join(repo, "README.md"), "utf-8");
@@ -184,3 +187,95 @@ test("preflight + merge + postflight round-trip preserves uncommitted changes",
     try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
   }
 });
+
+test("postflightPopStash conflict warning names the exact stash ref", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# local work\n");
+    const preflight = preflightCleanRoot(repo, "M005C", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed");
+
+    writeFileSync(join(repo, "README.md"), "# merged work\n");
+    run("git add README.md", repo);
+    run('git commit -m "simulate conflicting merge"', repo);
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const postflight = postflightPopStash(repo, "M005C", preflight.stashMarker, (msg, level) => {
+      notifications.push({ msg, level });
+    });
+    assert.equal(postflight.restored, false, "conflicted restore must report restored=false");
+    assert.equal(postflight.needsManualRecovery, true, "conflicted restore must require manual recovery");
+    assert.match(postflight.message, /failed after merge of milestone M005C/);
+
+    const warning = notifications.find((n) => n.level === "warning")?.msg ?? "";
+    assert.match(warning, /git stash pop stash@\{\d+\}/);
+    assert.match(warning, /git stash apply stash@\{\d+\}/);
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+test("postflightPopStash restores the matching GSD stash, not stash@{0}", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# target stash\n");
+    const preflight = preflightCleanRoot(repo, "M006", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed target change");
+
+    writeFileSync(join(repo, "other.txt"), "other stash\n");
+    run('git stash push --include-untracked -m "unrelated newer stash"', repo);
+
+    const postflight = postflightPopStash(repo, "M006", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "targeted restore must not need manual recovery");
+
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# target stash\n");
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("unrelated newer stash"), "unrelated newer stash must remain");
+    assert.ok(!stashList.includes("gsd-preflight-stash [gsd-preflight-stash:M006"), "target stash should be consumed");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+test("postflightPopStash restores the exact preflight marker when another same-milestone stash exists", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# target stash\n");
+    const preflight = preflightCleanRoot(repo, "M007", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed target change");
+    assert.ok(preflight.stashMarker, "preflight must expose exact stash marker");
+
+    writeFileSync(join(repo, "same-milestone.txt"), "newer same milestone stash\n");
+    run('git stash push --include-untracked -m "gsd-preflight-stash [gsd-preflight-stash:M007:other]"', repo);
+
+    const postflight = postflightPopStash(repo, "M007", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "exact marker restore must not need manual recovery");
+
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# target stash\n");
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("gsd-preflight-stash:M007:other"), "newer same-milestone stash must remain");
+    assert.ok(!stashList.includes(preflight.stashMarker), "exact target stash should be consumed");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+test("postflightPopStash falls back to milestone marker prefix when exact marker is unavailable", () => {
+  const repo = createTempRepo();
+  try {
+    writeFileSync(join(repo, "README.md"), "# fallback stash\n");
+    run('git stash push --include-untracked -m "gsd-preflight-stash [gsd-preflight-stash:M008:fallback]"', repo);
+
+    const postflight = postflightPopStash(repo, "M008", undefined, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "fallback marker restore must not need manual recovery");
+
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# fallback stash\n");
+    const stashList = run("git stash list", repo);
+    assert.ok(!stashList.includes("gsd-preflight-stash:M008:fallback"), "fallback stash should be consumed");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});

package/src/resources/extensions/gsd/tests/commands-extract-learnings.test.ts

@@ -1,3 +1,4 @@
+// GSD2 commands-extract-learnings tests
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
@@ -484,6 +485,14 @@ describe("buildExtractionStepsBlock", () => {
     assert.ok(/skip/i.test(block));
   });
 
+  it("limits duplicate checks to one milestone-scoped memory query", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    const memoryQueryMatches = block.match(/memory_query/g) ?? [];
+    assert.equal(memoryQueryMatches.length, 1);
+    assert.ok(block.includes("Do not re-read milestone artefacts or repeat memory queries category-by-category"));
+    assert.ok(!block.includes("Before each `capture_thought` call, optionally call `memory_query`"));
+  });
+
   it("instructs capture_thought as the sole persistence path for Patterns, Lessons, and Decisions (ADR-013 step 6 cutover)", () => {
     const block = buildExtractionStepsBlock(ctx);
     // Each of the three persistence steps must call capture_thought.