gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

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

@@ -0,0 +1,77 @@
+// GSD-2 dispatch-guard regression test: SUMMARY/DB mismatch fail-closed behavior (#4663)
+//
+// Sibling bug to #4658 / PR #4660. A failure-path SUMMARY file on disk
+// must not let the cross-milestone dispatch guard treat an "active"
+// milestone as complete. DB status is authoritative when available.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getPriorSliceCompletionBlocker } from "../dispatch-guard.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice } from "../gsd-db.ts";
+
+function setupRepo(): string {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-dispatch-guard-4663-"));
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  openDatabase(join(repo, ".gsd", "gsd.db"));
+  return repo;
+}
+
+function teardownRepo(repo: string): void {
+  closeDatabase();
+  rmSync(repo, { recursive: true, force: true });
+}
+
+test("#4663: dispatch guard blocks when prior milestone has failure SUMMARY but DB is still active", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M003"), { recursive: true });
+
+  // M002: DB says active with a pending slice, but a failure SUMMARY exists on disk.
+  insertMilestone({ id: "M002", title: "Previous", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M002", title: "Pending", status: "pending", depends: [] });
+
+  insertMilestone({ id: "M003", title: "Current", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M003", title: "First", status: "pending", depends: [] });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), "# M002\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M003", "M003-ROADMAP.md"), "# M003\n");
+  writeFileSync(
+    join(repo, ".gsd", "milestones", "M002", "M002-SUMMARY.md"),
+    "# M002 Summary\nverification FAILED — not complete.\n",
+  );
+
+  // Before #4663: SUMMARY presence short-circuited the loop and M002 was skipped,
+  // allowing M003/S01 to dispatch. After: DB status is consulted and M002 still blocks.
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M003/S01"),
+    "Cannot dispatch plan-slice M003/S01: earlier slice M002/S01 is not complete.",
+  );
+});
+
+test("#4663: dispatch guard allows dispatch when prior milestone has SUMMARY and DB is complete", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M003"), { recursive: true });
+
+  insertMilestone({ id: "M002", title: "Previous", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M002", title: "Done", status: "complete", depends: [] });
+
+  insertMilestone({ id: "M003", title: "Current", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M003", title: "First", status: "pending", depends: [] });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), "# M002\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M003", "M003-ROADMAP.md"), "# M003\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-SUMMARY.md"), "# M002 Summary\nDone.\n");
+
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M003/S01"),
+    null,
+  );
+});

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

@@ -255,6 +255,31 @@ test("dispatch guard skips completed milestone with SUMMARY even if it has unche
   );
 });
 
+test("dispatch guard does not skip failed milestone SUMMARY without blocker prose", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M001"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+
+  insertMilestone({ id: "M001", title: "Previous" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Core", status: "complete", depends: [], sequence: 1 });
+  insertSlice({ id: "S02", milestoneId: "M001", title: "Unfinished", status: "pending", depends: ["S01"], sequence: 2 });
+
+  insertMilestone({ id: "M002", title: "Current" });
+  insertSlice({ id: "S01", milestoneId: "M002", title: "Start", status: "pending", depends: [], sequence: 1 });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), "# M001\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M001", "M001-SUMMARY.md"),
+    "---\nstatus: failed\n---\n# M001 Summary\nRecovery stopped.\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), "# M002\n");
+
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M002/S01"),
+    "Cannot dispatch plan-slice M002/S01: earlier slice M001/S02 is not complete.",
+  );
+});
+
 test("dispatch guard works without git repo", (t) => {
   const repo = setupRepo();
   t.after(() => teardownRepo(repo));

package/src/resources/extensions/gsd/tests/dispatch-missing-task-plans.test.ts

@@ -57,6 +57,17 @@ function scaffoldSlicePlan(basePath: string, mid: string, sid: string): void {
   ].join("\n"));
 }
 
+function scaffoldMilestoneContext(basePath: string, mid: string): void {
+  const dir = join(basePath, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-CONTEXT.md`), [
+    `# ${mid}: Test Milestone`,
+    "",
+    "Context for dispatch recovery tests.",
+    "",
+  ].join("\n"));
+}
+
 function scaffoldTaskPlan(basePath: string, mid: string, sid: string, tid: string): void {
   const dir = join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks");
   mkdirSync(dir, { recursive: true });
@@ -76,6 +87,7 @@ test("dispatch: missing task plan triggers plan-slice (not stop) — issue #909"
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
   // Slice plan exists with tasks, but tasks/ directory is empty
+  scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
 
   const ctx = makeContext(tmp);
@@ -92,6 +104,7 @@ test("dispatch: present task plan proceeds to execute-task normally", async (t)
   const tmp = mkdtempSync(join(tmpdir(), "gsd-909-ok-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
+  scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
   scaffoldTaskPlan(tmp, "M002", "S03", "T01");
 
@@ -111,6 +124,7 @@ test("dispatch: plan-slice recovery loop — second call after plan-slice still
   const tmp = mkdtempSync(join(tmpdir(), "gsd-909-loop-"));
   t.after(() => rmSync(tmp, { recursive: true, force: true }));
 
+  scaffoldMilestoneContext(tmp, "M002");
   scaffoldSlicePlan(tmp, "M002", "S03");
 
   const ctx = makeContext(tmp);

package/src/resources/extensions/gsd/tests/dispatcher-stuck-planning.test.ts

@@ -4,7 +4,7 @@
  * Verify that state.ts contains the disk-to-DB task reconciliation logic
  * that prevents the dispatcher from getting stuck in an infinite planning
  * loop when the planner writes a PLAN.md but never calls the persistence
- * tool, leaving the DB with zero task rows.
+ * tool, leaving the DB with zero or partial task rows.
  */
 
 import { describe, test } from "node:test";
@@ -24,7 +24,8 @@ describe("dispatcher stuck-planning reconciliation (#3656)", () => {
   });
 
   test("contains plan-file task reconciliation block", () => {
-    assert.match(source, /tasks\.length\s*===\s*0\s*&&\s*planFile/);
+    assert.match(source, /if\s*\(\s*planFile\s*\)/);
+    assert.match(source, /dbTaskIds\.has\(t\.id\)/);
   });
 
   test("calls insertTask for each disk plan task", () => {

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -768,6 +768,37 @@ test("runProviderChecks detects claude.cmd in PATH on Windows (#4503)", { skip:
   });
 });
 
+test("runProviderChecks detects claude.exe in PATH on Windows (#4548)", { skip: process.platform !== "win32" }, () => {
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cc-exe-home-")));
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(binDir, { recursive: true });
+
+  // Some Windows installs ship a direct claude.exe binary (not a .cmd shim).
+  const fakeClaudeExe = join(binDir, "claude.exe");
+  writeFileSync(fakeClaudeExe, "");
+
+  withEnv({
+    HOME: tmpHome,
+    ANTHROPIC_API_KEY: undefined,
+    ANTHROPIC_OAUTH_TOKEN: undefined,
+    COPILOT_GITHUB_TOKEN: undefined,
+    GH_TOKEN: undefined,
+    GITHUB_TOKEN: undefined,
+    PATH: `${binDir};${process.env.PATH ?? ""}`,
+    PATHEXT: ".COM;.EXE;.BAT;.CMD",
+  }, () => {
+    try {
+      const results = runProviderChecks();
+      const anthropic = results.find(r => r.name === "anthropic");
+      assert.ok(anthropic, "anthropic result should exist");
+      assert.equal(anthropic!.status, "ok", "should be ok when claude.exe is in PATH (#4548)");
+      assert.ok(anthropic!.message.toLowerCase().includes("claude"), "should mention claude-code as source");
+    } finally {
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});
+
 test("PROVIDER_ROUTES includes google-gemini-cli as route for google (#2922)", async () => {
   const { readFileSync: readFS } = await import("node:fs");
   const { dirname: dirn, join: joinPath } = await import("node:path");

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

@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AutoSession } from "../auto/session.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -20,7 +21,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const completeIdx = phasesSrc.indexOf('state.phase === "complete"');
     assert.ok(completeIdx > 0, "phases.ts should have a 'complete' phase check");
 
-    const afterComplete = phasesSrc.slice(completeIdx, completeIdx + 600);
+    const afterComplete = extractSourceRegion(phasesSrc, 'state.phase === "complete"');
     const mergeIdx = afterComplete.indexOf("deps.resolver.mergeAndExit");
     const flagIdx = afterComplete.indexOf("s.milestoneMergedInPhases = true");
 
@@ -42,7 +43,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const allCompleteIdx = phasesSrc.indexOf("incomplete.length === 0");
     assert.ok(allCompleteIdx > 0, "phases.ts should have an all-milestones-complete check");
 
-    const afterAllComplete = phasesSrc.slice(allCompleteIdx, allCompleteIdx + 600);
+    const afterAllComplete = extractSourceRegion(phasesSrc, "incomplete.length === 0");
     const mergeIdx = afterAllComplete.indexOf("deps.resolver.mergeAndExit");
     const flagIdx = afterAllComplete.indexOf("s.milestoneMergedInPhases = true");
 
@@ -64,7 +65,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const step4Idx = autoSrc.indexOf("Step 4: Auto-worktree exit");
     assert.ok(step4Idx > 0, "auto.ts should have Step 4 worktree exit");
 
-    const step4Block = autoSrc.slice(step4Idx, step4Idx + 600);
+    const step4Block = extractSourceRegion(autoSrc, "Step 4: Auto-worktree exit");
     assert.ok(
       step4Block.includes("milestoneMergedInPhases"),
       "stopAuto Step 4 must check milestoneMergedInPhases before merging",

package/src/resources/extensions/gsd/tests/empty-content-abort-loop.test.ts

@@ -13,6 +13,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const RECOVERY_PATH = join(__dirname, "..", "bootstrap", "agent-end-recovery.ts");
@@ -30,7 +31,7 @@ test("agent-end-recovery.ts does not pause on aborted messages with empty conten
   assert.ok(abortIdx > -1, "abort handler must exist in agent-end-recovery.ts");
 
   // Extract the region around the abort handler (enough to see the guard logic)
-  const abortRegion = source.slice(Math.max(0, abortIdx - 200), abortIdx + 600);
+  const abortRegion = extractSourceRegion(source, 'stopReason === "aborted"', { fromIdx: abortIdx });
 
   // Must check for empty content before pausing
   assert.ok(
@@ -48,7 +49,7 @@ test("agent-end-recovery.ts routes empty-content aborted messages to resolveAgen
   assert.ok(abortIdx > -1, "abort handler must exist");
 
   // Get the full abort handling block (from the if to the next stopReason check or success path)
-  const afterAbort = source.slice(abortIdx, abortIdx + 800);
+  const afterAbort = extractSourceRegion(source, 'stopReason === "aborted"');
 
   // The abort block must have a code path that calls resolveAgentEnd (for empty-content case)
   assert.ok(
@@ -63,7 +64,7 @@ test("agent-end-recovery.ts checks for errorMessage presence in abort handler (#
   const abortIdx = source.indexOf('stopReason === "aborted"');
   assert.ok(abortIdx > -1, "abort handler must exist");
 
-  const abortRegion = source.slice(abortIdx, abortIdx + 600);
+  const abortRegion = extractSourceRegion(source, 'stopReason === "aborted"');
 
   // Fatal aborts should have error context (errorMessage field).
   // The handler should check for this to distinguish fatal from non-fatal aborts.

package/src/resources/extensions/gsd/tests/ensure-db-open.test.ts

@@ -389,7 +389,7 @@ describe('ensure-db-open', () => {
       assert.ok(db, 'adapter should be available after ensureDbOpen');
       assert.equal(
         db.prepare('SELECT MAX(version) as version FROM schema_version').get()?.version,
-        21,
+        22,
         'legacy DB should migrate to current schema version',
       );
 

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

@@ -348,7 +348,7 @@ test("ADR-011 P2: schema v20 fresh DB has all escalation columns on tasks + sour
   assert.ok(decCols.includes("source"), "decisions table must have source column");
 
   const version = adapter.prepare("SELECT MAX(version) as v FROM schema_version").get();
-  assert.equal(version?.["v"], 21);
+  assert.equal(version?.["v"], 22);
 });
 
 test("ADR-011 P2: findUnappliedEscalationOverride returns null when escalation_pending=1 (still pending)", (t) => {

package/src/resources/extensions/gsd/tests/exec-history.test.ts

@@ -122,3 +122,116 @@ test('executeExecSearch: includes stdout_path and preview in details', () => {
     cleanup(base);
   }
 });
+
+// ── Path traversal security tests (issue #4590) ───────────────────────────
+
+test('safeReadMeta: ignores malicious stdout_path in JSON, derives path from meta file location', () => {
+  // Arrange: write a .meta.json whose JSON content has a path-traversal value
+  // in stdout_path / stderr_path. The read-side must silently discard these
+  // and derive sibling paths from the actual .meta.json location instead.
+  const base = freshBase();
+  try {
+    const dir = join(base, '.gsd', 'exec');
+    mkdirSync(dir, { recursive: true });
+    const id = 'traversal-test-run';
+    const metaPath = join(dir, `${id}.meta.json`);
+    const stdoutPath = join(dir, `${id}.stdout`);
+    const stderrPath = join(dir, `${id}.stderr`);
+    // Write real sibling files so digest_preview can succeed.
+    writeFileSync(stdoutPath, 'legitimate stdout content\n');
+    writeFileSync(stderrPath, '');
+    // Write a meta.json that tries to point stdout_path outside the exec dir.
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        id,
+        runtime: 'bash',
+        purpose: 'test run',
+        started_at: '2026-04-20T12:00:00.000Z',
+        finished_at: '2026-04-20T12:00:00.100Z',
+        duration_ms: 100,
+        exit_code: 0,
+        signal: null,
+        timed_out: false,
+        stdout_bytes: 24,
+        stderr_bytes: 0,
+        stdout_truncated: false,
+        stderr_truncated: false,
+        // These malicious values must NEVER be used as filesystem paths.
+        stdout_path: '../../etc/passwd',
+        stderr_path: '../../etc/shadow',
+      }),
+    );
+
+    const entries = listExecHistory(base);
+    assert.equal(entries.length, 1);
+    const entry = entries[0]!;
+
+    // stdout_path must be derived from the meta file location, not from JSON.
+    assert.equal(entry.stdout_path, stdoutPath,
+      `stdout_path must be a sibling of the meta file; got: ${entry.stdout_path}`);
+    assert.equal(entry.stderr_path, stderrPath,
+      `stderr_path must be a sibling of the meta file; got: ${entry.stderr_path}`);
+
+    // Verify neither traversal string leaked into the returned entry.
+    assert.ok(!entry.stdout_path.includes('..'),
+      `stdout_path must not contain path traversal sequences: ${entry.stdout_path}`);
+    assert.ok(!entry.stderr_path.includes('..'),
+      `stderr_path must not contain path traversal sequences: ${entry.stderr_path}`);
+    assert.ok(!entry.stdout_path.includes('etc/passwd'),
+      `stdout_path must not point to /etc/passwd: ${entry.stdout_path}`);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('searchExecHistory: digest_preview is read from derived sibling path, not JSON stdout_path', () => {
+  // Arrange: a .meta.json with a malicious stdout_path pointing to /etc/passwd.
+  // The digest_preview should be read from the real sibling .stdout file,
+  // not from the JSON-supplied path.
+  const base = freshBase();
+  try {
+    const dir = join(base, '.gsd', 'exec');
+    mkdirSync(dir, { recursive: true });
+    const id = 'preview-traversal-run';
+    const metaPath = join(dir, `${id}.meta.json`);
+    const stdoutPath = join(dir, `${id}.stdout`);
+    writeFileSync(stdoutPath, 'safe-sentinel-content\n');
+    writeFileSync(join(dir, `${id}.stderr`), '');
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        id,
+        runtime: 'bash',
+        purpose: null,
+        started_at: '2026-04-20T12:00:00.000Z',
+        finished_at: '2026-04-20T12:00:00.100Z',
+        duration_ms: 50,
+        exit_code: 0,
+        signal: null,
+        timed_out: false,
+        stdout_bytes: 21,
+        stderr_bytes: 0,
+        stdout_truncated: false,
+        stderr_truncated: false,
+        // Attacker-controlled path — must be ignored.
+        stdout_path: '/etc/passwd',
+        stderr_path: '/etc/shadow',
+      }),
+    );
+
+    const hits = searchExecHistory(base, {});
+    assert.equal(hits.length, 1);
+    const hit = hits[0]!;
+
+    // The preview must come from the safe sibling, not /etc/passwd.
+    assert.ok(
+      hit.digest_preview?.includes('safe-sentinel-content'),
+      `digest_preview should contain safe-sentinel-content; got: ${hit.digest_preview}`,
+    );
+    // Ensure the entry paths are the derived ones.
+    assert.equal(hit.entry.stdout_path, stdoutPath);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/execution-entry-missing-context-4671.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Regression tests for #4671 — execution-entry phase + missing CONTEXT.md.
+ *
+ * When a milestone advances to an execution-entry phase (executing /
+ * summarizing / validating-milestone / completing-milestone) without
+ * `CONTEXT.md` on disk, the `pre-planning (no context) → discuss-milestone`
+ * rule no longer fires and the plan-v2 gate only blocks. This rule provides
+ * the recovery by redispatching to discuss-milestone.
+ *
+ * Exercises the dispatch rule from DISPATCH_RULES directly with a
+ * DispatchContext built against a real temp directory.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { DISPATCH_RULES, type DispatchContext } from "../auto-dispatch.ts";
+import type { GSDState, Phase } from "../types.ts";
+
+const RULE_NAME_TOKEN = "execution-entry phase (no context)";
+
+function findRule() {
+  const matches = DISPATCH_RULES.filter((r) => r.name.includes(RULE_NAME_TOKEN));
+  if (matches.length !== 1) {
+    throw new Error(
+      `expected exactly one dispatch rule containing "${RULE_NAME_TOKEN}", found ${matches.length}`,
+    );
+  }
+  return matches[0];
+}
+
+function buildState(phase: Phase): GSDState {
+  return {
+    activeMilestone: { id: "M001", title: "Test milestone" },
+    activeSlice: null,
+    activeTask: null,
+    phase,
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "",
+    registry: [],
+  };
+}
+
+function makeBasePath(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), `gsd-4671-${prefix}-`));
+  mkdirSync(join(dir, ".gsd", "milestones", "M001"), { recursive: true });
+  return dir;
+}
+
+function buildCtx(basePath: string, state: GSDState): DispatchContext {
+  return {
+    basePath,
+    mid: "M001",
+    midTitle: "Test milestone",
+    state,
+    prefs: undefined,
+  };
+}
+
+describe("#4671 execution-entry phase missing-context recovery", () => {
+  const executionEntryPhases: Phase[] = [
+    "executing",
+    "summarizing",
+    "validating-milestone",
+    "completing-milestone",
+  ];
+
+  for (const phase of executionEntryPhases) {
+    test(`phase=${phase} with missing CONTEXT.md → dispatches discuss-milestone`, async () => {
+      const basePath = makeBasePath(`missing-${phase}`);
+      try {
+        const action = await findRule().match(buildCtx(basePath, buildState(phase)));
+        assert.ok(action, "rule must return an action when CONTEXT.md is missing");
+        assert.strictEqual(action!.action, "dispatch");
+        if (action!.action === "dispatch") {
+          assert.strictEqual(action!.unitType, "discuss-milestone");
+          assert.strictEqual(action!.unitId, "M001");
+          assert.ok(typeof action!.prompt === "string" && action!.prompt.length > 0);
+        }
+      } finally {
+        rmSync(basePath, { recursive: true, force: true });
+      }
+    });
+  }
+
+  test("phase=executing with CONTEXT.md present → falls through", async () => {
+    const basePath = makeBasePath("has-context");
+    try {
+      writeFileSync(
+        join(basePath, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "# M001 Context\n\nSome real context.\n",
+      );
+      const action = await findRule().match(buildCtx(basePath, buildState("executing")));
+      assert.strictEqual(action, null, "rule must fall through when CONTEXT.md exists");
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  test("phase=executing accepts finalized CONTEXT.md from GSD_PROJECT_ROOT fallback", async () => {
+    const projectRoot = makeBasePath("project-root-context");
+    const worktreeBase = makeBasePath("worktree-context");
+    const prevProjectRoot = process.env.GSD_PROJECT_ROOT;
+    try {
+      writeFileSync(
+        join(projectRoot, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "# M001 Context\n\nFinalized context at project root.\n",
+      );
+      process.env.GSD_PROJECT_ROOT = projectRoot;
+
+      const action = await findRule().match(buildCtx(worktreeBase, buildState("executing")));
+      assert.strictEqual(
+        action,
+        null,
+        "rule must align with plan-v2 project-root fallback before redispatching",
+      );
+    } finally {
+      if (prevProjectRoot === undefined) {
+        delete process.env.GSD_PROJECT_ROOT;
+      } else {
+        process.env.GSD_PROJECT_ROOT = prevProjectRoot;
+      }
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(worktreeBase, { recursive: true, force: true });
+    }
+  });
+
+  test("phase=pre-planning does not trigger this rule (handled by upstream rule)", async () => {
+    const basePath = makeBasePath("pre-planning");
+    try {
+      const action = await findRule().match(buildCtx(basePath, buildState("pre-planning")));
+      assert.strictEqual(
+        action,
+        null,
+        "rule must only target execution-entry phases; pre-planning is handled elsewhere",
+      );
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  test("empty CONTEXT.md (whitespace only) → rule still fires", async () => {
+    const basePath = makeBasePath("empty-context");
+    try {
+      writeFileSync(
+        join(basePath, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "   \n\t\n",
+      );
+      const action = await findRule().match(buildCtx(basePath, buildState("summarizing")));
+      assert.ok(action, "rule must fire when CONTEXT.md is empty/whitespace-only");
+      if (action?.action === "dispatch") {
+        assert.strictEqual(action.unitType, "discuss-milestone");
+      }
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  test("rule ordering: fires BEFORE execution-entry phase handlers", () => {
+    const recoveryIdx = DISPATCH_RULES.findIndex((r) => r.name.includes(RULE_NAME_TOKEN));
+    const summarizingIdx = DISPATCH_RULES.findIndex((r) =>
+      r.name.startsWith("summarizing → complete-slice"),
+    );
+    assert.ok(recoveryIdx > -1, "recovery rule must exist");
+    assert.ok(summarizingIdx > -1, "summarizing rule must exist");
+    assert.ok(
+      recoveryIdx < summarizingIdx,
+      `recovery rule (idx ${recoveryIdx}) must come before summarizing rule (idx ${summarizingIdx}) so it can redispatch before the plan-v2 gate blocks`,
+    );
+  });
+});