gsd-pi 2.79.0 → 2.80.0

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

@@ -7,7 +7,7 @@ import { randomUUID } from "node:crypto";
 
 import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps, writeBlockerPlaceholder } from "../auto-recovery.ts";
 import { resolveMilestoneFile } from "../paths.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow, insertTask } from "../gsd-db.ts";
 import { clearParseCache } from "../files.ts";
 import { parseRoadmap } from "../parsers-legacy.ts";
 import { invalidateAllCaches } from "../cache.ts";
@@ -90,6 +90,46 @@ test("resolveExpectedArtifactPath returns correct path for plan-slice", () => {
   }
 });
 
+test("plan-slice artifact resolution handles lowercase unit IDs against uppercase paths", () => {
+  const base = makeTmpBase();
+  try {
+    const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    const tasksDir = join(sliceDir, "tasks");
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: Implement feature** `est:1h`",
+    ].join("\n"));
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan");
+
+    const artifactPath = resolveExpectedArtifactPath("plan-slice", "m001/s01", base);
+    assert.ok(
+      artifactPath?.endsWith(".gsd/milestones/M001/slices/S01/S01-PLAN.md"),
+      "lowercase unit IDs should resolve to the existing uppercase artifact path",
+    );
+
+    const diagnostic = diagnoseExpectedArtifact("plan-slice", "m001/s01", base);
+    assert.ok(
+      diagnostic?.includes(".gsd/milestones/M001/slices/S01/S01-PLAN.md"),
+      "diagnostic should report the existing uppercase artifact path",
+    );
+    assert.ok(
+      diagnostic?.includes("task plans"),
+      "diagnostic should mention task plans because slice plan alone is insufficient",
+    );
+
+    assert.equal(
+      verifyExpectedArtifact("plan-slice", "m001/s01", base),
+      true,
+      "verification should pass when the uppercase slice plan and task plans exist",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("resolveExpectedArtifactPath returns null for unknown type", () => {
   const base = makeTmpBase();
   try {
@@ -764,6 +804,73 @@ test("hasImplementationArtifacts finds implementation commits when .gsd/ is giti
   }
 });
 
+test("hasImplementationArtifacts binds GSD-Task trailer to milestone via DB state when .gsd/ is gitignored", () => {
+  const base = makeGitBase();
+  try {
+    writeFileSync(join(base, ".git", "info", "exclude"), ".gsd/\n");
+    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",
+    });
+
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "feature.ts"), "export function feature() {}\n");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync(
+      "git",
+      ["commit", "-m", "feat: add feature\n\nGSD-Task: S01/T01"],
+      { cwd: base, stdio: "ignore" },
+    );
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(
+      result,
+      "present",
+      "DB task ownership should bind S01/T01 implementation commits to M001 without explicit M001 text",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("hasImplementationArtifacts does not bind GSD-Task trailer without milestone ownership evidence", () => {
+  const base = makeGitBase();
+  try {
+    writeFileSync(join(base, ".git", "info", "exclude"), ".gsd/\n");
+    mkdirSync(join(base, "src"), { recursive: true });
+    writeFileSync(join(base, "src", "feature.ts"), "export function feature() {}\n");
+    execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" });
+    execFileSync(
+      "git",
+      ["commit", "-m", "feat: add feature\n\nGSD-Task: S01/T01"],
+      { cwd: base, stdio: "ignore" },
+    );
+
+    const result = hasImplementationArtifacts(base, "M001");
+    assert.equal(
+      result,
+      "absent",
+      "S01/T01 shape alone must not bind an implementation commit to M001",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("hasImplementationArtifacts ignores malformed milestone IDs in commit-message fallback", () => {
   const base = makeGitBase();
   try {

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

@@ -0,0 +1,39 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { autoSession, getAutoRuntimeSnapshot } from "../auto-runtime-state.ts";
+
+test("getAutoRuntimeSnapshot includes orchestration phase when available", () => {
+  autoSession.reset();
+  autoSession.active = true;
+  autoSession.basePath = "/tmp/project";
+  autoSession.orchestration = {
+    async start() { return { kind: "advanced" as const }; },
+    async advance() { return { kind: "advanced" as const }; },
+    async resume() { return { kind: "advanced" as const }; },
+    async stop() { return { kind: "stopped" as const }; },
+    getStatus() {
+      return { phase: "running" as const, transitionCount: 3, lastTransitionAt: 123 };
+    },
+  };
+
+  const snap = getAutoRuntimeSnapshot();
+
+  assert.equal(snap.active, true);
+  assert.equal(snap.basePath, "/tmp/project");
+  assert.equal(snap.orchestrationPhase, "running");
+  assert.equal(snap.orchestrationTransitionCount, 3);
+  assert.equal(snap.orchestrationLastTransitionAt, 123);
+
+  autoSession.reset();
+});
+
+test("getAutoRuntimeSnapshot omits orchestration phase when seam not wired", () => {
+  autoSession.reset();
+
+  const snap = getAutoRuntimeSnapshot();
+
+  assert.equal(snap.orchestrationPhase, undefined);
+  assert.equal(snap.orchestrationTransitionCount, undefined);
+  assert.equal(snap.orchestrationLastTransitionAt, undefined);
+});

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

@@ -201,6 +201,9 @@ test("AutoSession.toJSON() includes key diagnostic properties", () => {
     "basePath",
     "currentMilestoneId",
     "currentUnit",
+    "orchestrationPhase",
+    "orchestrationTransitionCount",
+    "orchestrationLastTransitionAt",
   ];
 
   const missing = requiredDiagnostics.filter(prop => !toJSONBody.includes(prop));

package/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts

@@ -31,9 +31,9 @@ describe("bootstrap deriveState DB guards (#3844)", () => {
     const compactIdx = registerHooksSrc.indexOf('pi.on("session_before_compact"');
     assert.ok(compactIdx > -1, "register-hooks should define session_before_compact");
     const compactSection = extractSourceRegion(registerHooksSrc, 'pi.on("session_before_compact"');
-    const ensureIdx = compactSection.indexOf("ensureDbOpen()");
+    const ensureIdx = compactSection.indexOf("ensureDbOpen(basePath)");
     const deriveIdx = compactSection.indexOf("deriveGsdState(basePath)");
-    assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen()");
+    assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen(basePath)");
     assert.ok(deriveIdx > -1, "session_before_compact should derive state");
     assert.ok(ensureIdx < deriveIdx, "session_before_compact should open DB before deriveState");
   });

package/src/resources/extensions/gsd/tests/check-auto-start-pending-gate.test.ts

@@ -0,0 +1,203 @@
+// GSD-2 + Regression tests for checkAutoStartAfterDiscuss Gate 1a (R2)
+//
+// When a depth-verification gate is still pending (the LLM emitted the
+// confirmation question via ask_user_questions or plain chat but the user has
+// not answered), checkAutoStartAfterDiscuss must NOT advance — even if
+// CONTEXT.md and STATE.md are present on disk. Otherwise the LLM can render
+// the question and the "Milestone M001 ready" phrase in the same turn and
+// race past the gate.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  checkAutoStartAfterDiscuss,
+  setPendingAutoStart,
+  clearPendingAutoStart,
+} from "../guided-flow.ts";
+import { drainLogs } from "../workflow-logger.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+import {
+  setPendingGate,
+  clearPendingGate,
+  clearDiscussionFlowState,
+} from "../bootstrap/write-gate.ts";
+
+interface MockCapture {
+  notifies: Array<{ msg: string; level: string }>;
+  messages: Array<{ payload: any; options: any }>;
+}
+
+function mkCapture(): MockCapture {
+  return { notifies: [], messages: [] };
+}
+
+function mkCtx(cap: MockCapture): any {
+  return {
+    ui: {
+      notify: (msg: string, level: string) => {
+        cap.notifies.push({ msg, level });
+      },
+    },
+  };
+}
+
+function mkPi(cap: MockCapture): any {
+  return {
+    sendMessage: (payload: any, options: any) => {
+      cap.messages.push({ payload, options });
+    },
+    setActiveTools: () => undefined,
+    getActiveTools: () => [],
+  };
+}
+
+function mkBase(): string {
+  // realpathSync to normalize the macOS /var → /private/var symlink so the
+  // basePath we pass to setPendingGate matches what the workspace's
+  // realpath-normalized projectRoot will resolve to.
+  const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-gate1a-pending-")));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  // CONTEXT.md (Gate 1) and STATE.md (Gate 2) both present so the only
+  // possible blocker in these tests is the new Gate 1a.
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+    "# M001: Pending Gate Test\n\nContext.\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "STATE.md"),
+    "# State\n\nactive: M001\n",
+  );
+  return base;
+}
+
+describe("checkAutoStartAfterDiscuss Gate 1a (pending depth-verification gate)", () => {
+  let base: string;
+  let cap: MockCapture;
+
+  beforeEach(() => {
+    clearPendingAutoStart();
+    drainLogs();
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    clearPendingAutoStart();
+    if (base) {
+      try { clearDiscussionFlowState(base); } catch { /* */ }
+      try { clearPendingGate(base); } catch { /* */ }
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test("returns false while a depth_verification gate is pending for the same milestone", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    // DB row present + active so Gate 1b is not the blocker
+    insertMilestone({ id: "M001", title: "Pending Gate Test", status: "active" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    // The depth-verification gate for THIS milestone is still pending.
+    setPendingGate("depth_verification_M001_confirm", base);
+
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, false, "must not advance while the milestone gate is pending");
+    // Must not have announced "ready" or kicked auto.
+    const readyNotify = cap.notifies.find((n) => /ready\.?$/i.test(n.msg) && n.level === "success");
+    assert.equal(readyNotify, undefined, "must not announce 'ready' while gate pending");
+  });
+
+  test("returns false while a depth_verification_project_confirm gate is pending (deep setup)", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Pending Gate Test", status: "active" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    // A project-level depth-verification gate (no milestone id encoded) is pending —
+    // deep-setup interview has not been confirmed yet.
+    setPendingGate("depth_verification_project_confirm", base);
+
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, false, "must not advance while a project-level gate is pending");
+  });
+
+  test("returns false while a depth_verification_requirements_confirm gate is pending", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Pending Gate Test", status: "active" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    setPendingGate("depth_verification_requirements_confirm", base);
+
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, false, "must not advance while the requirements gate is pending");
+  });
+
+  test("Gate 1a does NOT trip when the pending gate is for a DIFFERENT milestone", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    // status: "queued" so that Gate 1b downstream of Gate 1a fires its
+    // recovery notify ("context file exists but milestone is still queued") —
+    // observing that notify proves we advanced past Gate 1a. If Gate 1a
+    // wrongly tripped on the M999 gate it would `return false` immediately
+    // and Gate 1b would never run, so the notify would be absent.
+    insertMilestone({ id: "M001", title: "Pending Gate Test", status: "queued" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    setPendingGate("depth_verification_M999_confirm", base);
+
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, false, "Gate 1b returns false (expected) — but only if Gate 1a let us through");
+
+    // Positive proof we passed Gate 1a: Gate 1b emitted its recovery notify
+    // about M001 (not M999 — the pending-gate milestone is irrelevant here).
+    const gate1bNotify = cap.notifies.find(n =>
+      n.level === "warning" && /M001.*context file exists but milestone is still queued/i.test(n.msg)
+    );
+    assert.ok(
+      gate1bNotify,
+      `expected Gate 1b warning notify about M001; got: ${JSON.stringify(cap.notifies)}`,
+    );
+
+    // Negative proof: no Gate 1a notification path exists in source today, but
+    // also assert no notify mentions M999 (the pending-gate milestone) — that
+    // would suggest Gate 1a is leaking the wrong milestone into messaging.
+    const m999Notify = cap.notifies.find(n => /M999/i.test(n.msg));
+    assert.equal(m999Notify, undefined, "no notify should reference M999 (the pending-gate milestone)");
+  });
+});

package/src/resources/extensions/gsd/tests/check-auto-start-ready-guard.test.ts

@@ -0,0 +1,148 @@
+// GSD-2 + Regression tests for checkAutoStartAfterDiscuss "ready" notify guard (R3b)
+//
+// Belt-and-suspenders: even when CONTEXT.md and STATE.md exist on disk, the
+// "Milestone X ready." success notify must not fire when the milestone DB row
+// is absent. Otherwise the user sees "ready" and then /gsd reports
+// "No Active Milestone" because the milestone was never registered.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  checkAutoStartAfterDiscuss,
+  setPendingAutoStart,
+  clearPendingAutoStart,
+} from "../guided-flow.ts";
+import { drainLogs } from "../workflow-logger.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+import {
+  clearDiscussionFlowState,
+  clearPendingGate,
+} from "../bootstrap/write-gate.ts";
+
+interface MockCapture {
+  notifies: Array<{ msg: string; level: string }>;
+  messages: Array<{ payload: any; options: any }>;
+}
+
+function mkCapture(): MockCapture {
+  return { notifies: [], messages: [] };
+}
+
+function mkCtx(cap: MockCapture): any {
+  return {
+    ui: {
+      notify: (msg: string, level: string) => {
+        cap.notifies.push({ msg, level });
+      },
+    },
+  };
+}
+
+function mkPi(cap: MockCapture): any {
+  return {
+    sendMessage: (payload: any, options: any) => {
+      cap.messages.push({ payload, options });
+    },
+    setActiveTools: () => undefined,
+    getActiveTools: () => [],
+  };
+}
+
+function mkBase(): string {
+  // realpathSync to normalize the macOS /var → /private/var symlink so the
+  // basePath we pass matches what the workspace projectRoot resolves to.
+  const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-ready-guard-")));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+    "# M001: Ready Guard Test\n\nContext.\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "STATE.md"),
+    "# State\n\nactive: M001\n",
+  );
+  return base;
+}
+
+describe("checkAutoStartAfterDiscuss ready-notify DB guard (R3b)", () => {
+  let base: string;
+  let cap: MockCapture;
+
+  beforeEach(() => {
+    clearPendingAutoStart();
+    drainLogs();
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    clearPendingAutoStart();
+    if (base) {
+      try { clearDiscussionFlowState(base); } catch { /* */ }
+      try { clearPendingGate(base); } catch { /* */ }
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test("does not announce 'ready' when the milestone DB row is absent", () => {
+    base = mkBase();
+    // Open a fresh in-memory DB but DO NOT insertMilestone for M001.
+    openDatabase(":memory:");
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, false, "must return false when DB row missing");
+
+    // No success "ready" notify
+    const successReady = cap.notifies.find(
+      (n) => n.level === "success" && /ready\.?$/i.test(n.msg),
+    );
+    assert.equal(successReady, undefined, "must not announce 'ready' when DB row missing");
+
+    // An error notify must explain the missing DB row
+    const errorNotify = cap.notifies.find((n) => n.level === "error");
+    assert.ok(errorNotify, "must emit an error notify when the DB row is missing");
+    assert.match(
+      errorNotify!.msg,
+      /no DB row exists/i,
+      "error notify must mention the missing DB row",
+    );
+    assert.match(errorNotify!.msg, /M001/, "error notify must mention the milestone id");
+  });
+
+  test("announces 'ready' when DB row exists", () => {
+    base = mkBase();
+    openDatabase(":memory:");
+    insertMilestone({ id: "M001", title: "Ready Guard Test", status: "active" });
+
+    cap = mkCapture();
+    setPendingAutoStart(base, {
+      basePath: base,
+      milestoneId: "M001",
+      ctx: mkCtx(cap),
+      pi: mkPi(cap),
+    });
+
+    const result = checkAutoStartAfterDiscuss();
+    assert.equal(result, true, "must return true on the happy path");
+
+    const successReady = cap.notifies.find(
+      (n) => n.level === "success" && /Milestone\s+M001\s+ready/i.test(n.msg),
+    );
+    assert.ok(successReady, "must announce 'Milestone M001 ready.' on success");
+  });
+});

package/src/resources/extensions/gsd/tests/current-directory-root-homedir-fallback.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Regression test — currentDirectoryRoot() uses os.homedir() as fallback
+ * when process.cwd() throws (e.g. worktree teardown deletes the cwd).
+ *
+ * Before the fix, the catch block used `process.env.HOME ?? "/"`. On
+ * Windows, HOME is typically unset so this resolved to "/", an invalid
+ * path. After the fix, os.homedir() is used — it checks USERPROFILE,
+ * HOMEDRIVE+HOMEPATH, etc., returning a valid path on all platforms.
+ *
+ * The test monkey-patches process.cwd() to throw ENOENT, simulating a
+ * deleted cwd. currentDirectoryRoot() must NOT propagate the raw error;
+ * instead it falls back to homedir(), which validateDirectory correctly
+ * rejects as "blocked", yielding GSDNoProjectError — the same controlled
+ * error path handlers already know how to catch.
+ *
+ * The error message is also asserted to match validateDirectory(homedir()),
+ * confirming the fallback resolved to homedir() specifically (not "/" or
+ * any other path).
+ */
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { homedir } from "node:os";
+
+import { currentDirectoryRoot, GSDNoProjectError } from "../commands/context.ts";
+import { validateDirectory } from "../validate-directory.ts";
+
+describe("currentDirectoryRoot() homedir() fallback on deleted cwd", () => {
+  const originalCwd = process.cwd.bind(process);
+
+  beforeEach(() => {
+    process.cwd = () => {
+      const err = new Error("ENOENT: no such file or directory, uv_cwd");
+      (err as NodeJS.ErrnoException).code = "ENOENT";
+      throw err;
+    };
+  });
+
+  afterEach(() => {
+    process.cwd = originalCwd;
+  });
+
+  test("does not propagate ENOENT — throws GSDNoProjectError via homedir() fallback", () => {
+    const expected = validateDirectory(homedir());
+    assert.equal(expected.severity, "blocked", "homedir() itself should be blocked");
+
+    assert.throws(
+      () => currentDirectoryRoot(),
+      (err: unknown) => {
+        assert.ok(
+          err instanceof GSDNoProjectError,
+          `expected GSDNoProjectError, got: ${err}`,
+        );
+        assert.equal(
+          (err as Error).message,
+          expected.reason ?? "GSD must be run inside a project directory.",
+          "error message must match validateDirectory(homedir()), confirming homedir() was the fallback",
+        );
+        return true;
+      },
+      "should throw GSDNoProjectError (homedir fallback validated), not raw ENOENT",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/deep-planning-mode-dispatch.test.ts

@@ -14,6 +14,7 @@ import {
   DISPATCH_RULES,
   getDeepStageGate,
   hasPendingDeepStage,
+  resolveDispatch,
   setResearchProjectPromptBuilderForTest,
   type DispatchContext,
 } from "../auto-dispatch.ts";
@@ -248,6 +249,11 @@ function writeCapturedDeepPrefs(base: string): void {
   );
 }
 
+function writeSkippedProjectResearchDecision(base: string): void {
+  mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "runtime", "research-decision.json"), JSON.stringify({ decision: "skip" }));
+}
+
 function makeCtx(
   basePath: string,
   prefs: GSDPreferences | undefined,
@@ -785,6 +791,42 @@ test("Deep mode: research-project DOES dispatch when only 3 of 4 research files
   assert.ok(result && result.action === "dispatch", "any missing dimension must trigger re-run");
 });
 
+test("Deep mode: queued milestone without CONTEXT.md routes to milestone research after project setup", async (t) => {
+  const base = makeIsolatedBaseWithCleanup(t);
+
+  writeCapturedDeepPrefs(base);
+  writeValidProject(base);
+  writeValidRequirements(base);
+  writeSkippedProjectResearchDecision(base);
+
+  const prefs = { planning_depth: "deep" } as GSDPreferences;
+  const result = await resolveDispatch(makeCtx(base, prefs));
+
+  assert.equal(result.action, "dispatch");
+  if (result.action === "dispatch") {
+    assert.equal(result.unitType, "research-milestone");
+    assert.equal(result.unitId, "M001");
+  }
+});
+
+test("Deep mode: queued milestone without CONTEXT.md can route directly to milestone planning", async (t) => {
+  const base = makeIsolatedBaseWithCleanup(t);
+
+  writeCapturedDeepPrefs(base);
+  writeValidProject(base);
+  writeValidRequirements(base);
+  writeSkippedProjectResearchDecision(base);
+
+  const prefs = { planning_depth: "deep", phases: { skip_research: true } } as GSDPreferences;
+  const result = await resolveDispatch(makeCtx(base, prefs));
+
+  assert.equal(result.action, "dispatch");
+  if (result.action === "dispatch") {
+    assert.equal(result.unitType, "plan-milestone");
+    assert.equal(result.unitId, "M001");
+  }
+});
+
 // ─── centralized deep-stage gate ─────────────────────────────────────────
 
 test("Deep mode gate reports the earliest missing section", (t) => {