gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8a893322c

package/src/resources/extensions/gsd/tests/bundled-skill-triggers.test.ts

@@ -2,12 +2,56 @@
 //
 // Guards the skill-trigger table in system-context.ts against accidental
 // regression. Every entry must have a non-empty trigger + skill, and the
-// skills added in PR #4505 must remain present.
+// skills added in PR #4505 and PR #5060 must remain present.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
 import { BUNDLED_SKILL_TRIGGERS } from '../bootstrap/system-context.ts';
 
+const PR_4505_BUNDLED_SKILLS = [
+  'review',
+  'test',
+  'lint',
+  'make-interfaces-feel-better',
+  'accessibility',
+  'grill-me',
+  'design-an-interface',
+  'tdd',
+  'write-milestone-brief',
+  'decompose-into-slices',
+  'spike-wrap-up',
+  'verify-before-complete',
+  'create-mcp-server',
+  'write-docs',
+  'forensics',
+  'handoff',
+  'security-review',
+  'api-design',
+  'dependency-upgrade',
+  'observability',
+] as const;
+
+const PR_5060_BUNDLED_SKILLS = [
+  'react-best-practices',
+  'core-web-vitals',
+  'github-workflows',
+  'web-quality-audit',
+  'agent-browser',
+  'web-design-guidelines',
+  'userinterface-wiki',
+  'create-skill',
+  'create-gsd-extension',
+  'create-workflow',
+  'code-optimizer',
+] as const;
+
+function assertBundledSkillsRegistered(label: string, expectedSkills: readonly string[]): void {
+  const registered = new Set(BUNDLED_SKILL_TRIGGERS.map(e => e.skill));
+  for (const skill of expectedSkills) {
+    assert.ok(registered.has(skill), `${label}: expected bundled skill "${skill}" to be registered`);
+  }
+}
+
 test('BUNDLED_SKILL_TRIGGERS: every entry has a non-empty trigger and skill', () => {
   assert.ok(BUNDLED_SKILL_TRIGGERS.length > 0, 'table should not be empty');
   for (const { trigger, skill } of BUNDLED_SKILL_TRIGGERS) {
@@ -17,32 +61,11 @@ test('BUNDLED_SKILL_TRIGGERS: every entry has a non-empty trigger and skill', ()
 });
 
 test('BUNDLED_SKILL_TRIGGERS: PR #4505 bundled skills are present', () => {
-  const expected = [
-    'review',
-    'test',
-    'lint',
-    'make-interfaces-feel-better',
-    'accessibility',
-    'grill-me',
-    'design-an-interface',
-    'tdd',
-    'write-milestone-brief',
-    'decompose-into-slices',
-    'spike-wrap-up',
-    'verify-before-complete',
-    'create-mcp-server',
-    'write-docs',
-    'forensics',
-    'handoff',
-    'security-review',
-    'api-design',
-    'dependency-upgrade',
-    'observability',
-  ];
-  const registered = new Set(BUNDLED_SKILL_TRIGGERS.map(e => e.skill));
-  for (const skill of expected) {
-    assert.ok(registered.has(skill), `expected bundled skill "${skill}" to be registered`);
-  }
+  assertBundledSkillsRegistered('PR #4505', PR_4505_BUNDLED_SKILLS);
+});
+
+test('BUNDLED_SKILL_TRIGGERS: PR #5060 previously-unexposed skills are present', () => {
+  assertBundledSkillsRegistered('PR #5060', PR_5060_BUNDLED_SKILLS);
 });
 
 test('BUNDLED_SKILL_TRIGGERS: skill ids are unique', () => {

package/src/resources/extensions/gsd/tests/commands-extensions-version-compare.test.ts

@@ -0,0 +1,58 @@
+// GSD2 — Regression test for Issue #4946 isVersionGreater (commands-extensions.ts)
+//
+// Covers the inline npm-version comparator that replaced the `semver` import in
+// commands-extensions.ts. The original import broke `tsc -p tsconfig.json` whenever
+// `@types/semver` failed to install — the file is type-checked transitively despite
+// being under the `src/resources` exclude. The replacement keeps the same comparison
+// semantics for the realistic input space (npm extension version strings) without
+// pulling in the full semver type surface.
+
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { isVersionGreater } from "../commands-extensions.ts";
+
+describe("isVersionGreater — npm extension version comparison (#4946)", () => {
+	test("strictly greater patch beats lesser patch", () => {
+		assert.equal(isVersionGreater("1.2.4", "1.2.3"), true);
+		assert.equal(isVersionGreater("1.2.3", "1.2.4"), false);
+	});
+
+	test("equal versions are not strictly greater", () => {
+		assert.equal(isVersionGreater("1.2.3", "1.2.3"), false);
+	});
+
+	test("numeric (not lexicographic) component comparison", () => {
+		// Lexicographic compare would say "1.10.0" < "1.9.0".
+		assert.equal(isVersionGreater("1.10.0", "1.9.0"), true);
+		assert.equal(isVersionGreater("1.9.0", "1.10.0"), false);
+	});
+
+	test("major bump beats minor and patch differences", () => {
+		assert.equal(isVersionGreater("2.0.0", "1.99.99"), true);
+		assert.equal(isVersionGreater("1.99.99", "2.0.0"), false);
+	});
+
+	test("missing trailing components default to zero", () => {
+		assert.equal(isVersionGreater("1.2", "1.1.9"), true);
+		assert.equal(isVersionGreater("1", "0.9.9"), true);
+		assert.equal(isVersionGreater("1.2", "1.2.0"), false);
+	});
+
+	test("release version beats prerelease at the same release number", () => {
+		assert.equal(isVersionGreater("1.0.0", "1.0.0-beta.1"), true);
+		assert.equal(isVersionGreater("1.0.0-beta.1", "1.0.0"), false);
+	});
+
+	test("prerelease ordering: beta.2 > beta.1, rc.1 > beta.9", () => {
+		assert.equal(isVersionGreater("1.0.0-beta.2", "1.0.0-beta.1"), true);
+		assert.equal(isVersionGreater("1.0.0-rc.1", "1.0.0-beta.9"), true);
+	});
+
+	test("non-numeric junk in components doesn't crash — coerces to 0", () => {
+		// Defensive: we don't throw on garbage input; we treat unparseable
+		// components as 0. This matches the behaviour the extension installer
+		// can rely on without surfacing an error to the user.
+		assert.equal(isVersionGreater("1.x.0", "1.0.0"), false);
+		assert.equal(isVersionGreater("abc", "0.0.1"), false);
+	});
+});

package/src/resources/extensions/gsd/tests/commands-worktree-clean.test.ts

@@ -0,0 +1,48 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  formatCleanKeepReason,
+  type WorktreeStatus,
+} from "../commands-worktree.ts";
+
+function mkStatus(over: Partial<WorktreeStatus>): WorktreeStatus {
+  const name = over.name ?? "feat-x";
+  return {
+    name,
+    path: `/repo/.gsd/worktrees/${name}`,
+    branch: `gsd/${name}`,
+    exists: true,
+    filesChanged: 0,
+    linesAdded: 0,
+    linesRemoved: 0,
+    uncommitted: false,
+    commits: 0,
+    ...over,
+  };
+}
+
+test("clean keep reason shows uncommitted-only worktrees clearly", () => {
+  const reason = formatCleanKeepReason(mkStatus({ uncommitted: true }));
+  assert.equal(reason, "uncommitted changes");
+});
+
+test("clean keep reason includes uncommitted context with changed files", () => {
+  const reason = formatCleanKeepReason(mkStatus({ filesChanged: 2, uncommitted: true }));
+  assert.equal(reason, "2 changed files, uncommitted");
+});
+
+test("clean keep reason flags missing directory with prune hint", () => {
+  const reason = formatCleanKeepReason(mkStatus({ exists: false }));
+  assert.equal(reason, "directory missing — run 'git worktree prune' to unregister");
+});
+
+test("clean keep reason reports changed files without uncommitted suffix", () => {
+  const reason = formatCleanKeepReason(mkStatus({ filesChanged: 2, uncommitted: false }));
+  assert.equal(reason, "2 changed files");
+});
+
+test("clean keep reason uses singular form for a single changed file", () => {
+  const reason = formatCleanKeepReason(mkStatus({ filesChanged: 1, uncommitted: false }));
+  assert.equal(reason, "1 changed file");
+});

package/src/resources/extensions/gsd/tests/google-search-stub.test.ts

@@ -11,26 +11,23 @@ test("google-search stub: default export is a function", async (_t) => {
   assert.equal(typeof stubFn, "function");
 });
 
-test("google-search stub: registers session_start handler", async (_t) => {
-  // STUB-01: stub calls pi.on("session_start", ...)
+test("google-search stub: registers no event handlers", async (_t) => {
+  // STUB-01: deprecation notice is suppressed — stub must not call pi.on() at all
   const mod = await import("../../google-search/index.ts");
   const stubFn = mod.default;
 
-  let capturedEvent: string | undefined;
-  let capturedHandler: unknown;
+  let onCallCount = 0;
 
   const mockPi = {
-    on(event: string, handler: unknown) {
-      capturedEvent = event;
-      capturedHandler = handler;
+    on(_event: string, _handler: unknown) {
+      onCallCount++;
     },
     registerTool: () => {},
   };
 
   stubFn(mockPi as never);
 
-  assert.equal(capturedEvent, "session_start");
-  assert.equal(typeof capturedHandler, "function");
+  assert.equal(onCallCount, 0, "stub should not register any event handlers");
 });
 
 test("google-search stub: does NOT call registerTool", async (_t) => {
@@ -50,82 +47,45 @@ test("google-search stub: does NOT call registerTool", async (_t) => {
   assert.equal(registerToolCalled, false);
 });
 
-test("google-search stub: session_start warning contains package name", async (_t) => {
-  // STUB-01: warning includes @gsd-extensions/google-search
+test("google-search stub: does not emit any notifications", async (_t) => {
+  // STUB-01: deprecation notice is suppressed — stub must not call ctx.ui.notify()
   const mod = await import("../../google-search/index.ts");
   const stubFn = mod.default;
 
-  let capturedHandler: ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
+  let notifyCallCount = 0;
 
   const mockPi = {
-    on(_event: string, handler: (event: unknown, ctx: unknown) => Promise<void>) {
-      capturedHandler = handler;
-    },
+    on(_event: string, _handler: unknown) {},
     registerTool: () => {},
   };
 
+  // Verify no notify is emitted by the stub itself (it registers no handlers,
+  // so there is nothing to invoke — this simply confirms no top-level notify call).
   stubFn(mockPi as never);
 
-  assert.ok(capturedHandler, "session_start handler should have been registered");
-
-  let capturedMessage: string | undefined;
-  const mockCtx = {
-    ui: {
-      notify(message: string, _level: string) {
-        capturedMessage = message;
-      },
-    },
-  };
-
-  await capturedHandler!({}, mockCtx);
-
-  assert.ok(
-    capturedMessage?.includes("@gsd-extensions/google-search"),
-    `Expected message to include "@gsd-extensions/google-search", got: "${capturedMessage}"`,
-  );
+  assert.equal(notifyCallCount, 0, "stub should not emit any notifications");
 });
 
-test("google-search stub: session_start warning explains package is not yet published", async (_t) => {
-  // STUB-01: stub must NOT advise `gsd extensions install` — the replacement
-  // package is not yet on npm, so that command would 404. The message must
-  // explain the extraction is in progress and no user action is required.
+test("google-search stub: is a complete no-op (no handlers, no tools, no notifications)", async (_t) => {
+  // STUB-01: the deprecation notice is suppressed until @gsd-extensions/google-search
+  // ships. The stub must call nothing on the ExtensionAPI.
   const mod = await import("../../google-search/index.ts");
   const stubFn = mod.default;
 
-  let capturedHandler: ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
+  let onCallCount = 0;
+  let registerToolCallCount = 0;
 
   const mockPi = {
-    on(_event: string, handler: (event: unknown, ctx: unknown) => Promise<void>) {
-      capturedHandler = handler;
+    on(_event: string, _handler: unknown) {
+      onCallCount++;
+    },
+    registerTool: () => {
+      registerToolCallCount++;
     },
-    registerTool: () => {},
   };
 
   stubFn(mockPi as never);
 
-  assert.ok(capturedHandler, "session_start handler should have been registered");
-
-  let capturedMessage: string | undefined;
-  const mockCtx = {
-    ui: {
-      notify(message: string, _level: string) {
-        capturedMessage = message;
-      },
-    },
-  };
-
-  await capturedHandler!({}, mockCtx);
-
-  assert.ok(
-    !capturedMessage?.includes("gsd extensions install"),
-    `Expected message NOT to include unpublished install command, got: "${capturedMessage}"`,
-  );
-  assert.ok(
-    capturedMessage?.includes("not yet published"),
-    `Expected message to include "not yet published", got: "${capturedMessage}"`,
-  );
-  assert.ok(
-    capturedMessage?.includes("No action needed"),
-    `Expected message to include "No action needed", got: "${capturedMessage}"`,
-  );
+  assert.equal(onCallCount, 0, "stub should not register any event handlers");
+  assert.equal(registerToolCallCount, 0, "stub should not register any tools");
 });

package/src/resources/extensions/gsd/tests/home-dir.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Tests for getHomeDir() — cross-platform home directory resolution.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { homedir } from "node:os";
+
+describe("getHomeDir", () => {
+  let savedHome: string | undefined;
+  let savedUserProfile: string | undefined;
+  let getHomeDir: () => string;
+
+  beforeEach(async () => {
+    savedHome = process.env.HOME;
+    savedUserProfile = process.env.USERPROFILE;
+    const mod = await import("../home-dir.ts");
+    getHomeDir = mod.getHomeDir;
+  });
+
+  afterEach(() => {
+    if (savedHome !== undefined) {
+      process.env.HOME = savedHome;
+    } else {
+      delete process.env.HOME;
+    }
+    if (savedUserProfile !== undefined) {
+      process.env.USERPROFILE = savedUserProfile;
+    } else {
+      delete process.env.USERPROFILE;
+    }
+  });
+
+  it("returns HOME when set", () => {
+    process.env.HOME = "/test/home";
+    delete process.env.USERPROFILE;
+    assert.equal(getHomeDir(), "/test/home");
+  });
+
+  it("falls back to USERPROFILE when HOME is unset", () => {
+    delete process.env.HOME;
+    process.env.USERPROFILE = String.raw`C:\Users\test`;
+    assert.equal(getHomeDir(), String.raw`C:\Users\test`);
+  });
+
+  it("falls back to os.homedir() when both HOME and USERPROFILE are unset", () => {
+    delete process.env.HOME;
+    delete process.env.USERPROFILE;
+    assert.equal(getHomeDir(), homedir());
+  });
+});

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

@@ -7,7 +7,7 @@
 
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -21,6 +21,7 @@ import {
   getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
   syncGsdStateToWorktree,
+  _resetAutoWorktreeOriginalBaseForTests,
 } from "../../auto-worktree.ts";
 
 // Note: execSync is used intentionally in tests for git operations with
@@ -142,6 +143,54 @@ describe("auto-worktree lifecycle", () => {
     teardownAutoWorktree(tempDir, "M003");
   });
 
+  test("symlink-resolved auto worktree is detected after module state reset", () => {
+    tempDir = createTempRepo();
+    const savedGsdHome = process.env.GSD_HOME;
+    const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "auto-wt-home-")));
+    const storage = join(fakeHome, ".gsd", "projects", "abc123def456");
+    mkdirSync(join(storage, "milestones", "M001"), { recursive: true });
+    writeFileSync(join(storage, "milestones", "M001", "CONTEXT.md"), "# M001\n");
+    symlinkSync(storage, join(tempDir, ".gsd"));
+    process.env.GSD_HOME = join(fakeHome, ".gsd");
+
+    try {
+      const wtPath = createAutoWorktree(tempDir, "M001");
+      const realWtPath = realpathSync(wtPath);
+      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+
+      _resetAutoWorktreeOriginalBaseForTests();
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+
+      assert.ok(isInAutoWorktree(tempDir), "structural detection works without module originalBase");
+      const resolved = getAutoWorktreePath(realWtPath, "M001");
+      assert.ok(resolved, "existing worktree is found when basePath is the worktree path");
+      assert.equal(realpathSync(resolved!), realWtPath);
+      assert.equal(existsSync(join(realWtPath, ".gsd", "worktrees", "M001")), false);
+
+      enterAutoWorktree(tempDir, "M001");
+      process.chdir(join(realWtPath, ".gsd", "milestones", "M001"));
+      assert.deepStrictEqual(
+        getActiveAutoWorktreeContext(),
+        {
+          originalBase: tempDir,
+          worktreeName: "M001",
+          branch: "milestone/M001",
+        },
+        "active context is detected from a symlink-resolved worktree cwd",
+      );
+    } finally {
+      process.chdir(tempDir);
+      try {
+        teardownAutoWorktree(tempDir, "M001");
+      } catch {
+        // Best-effort cleanup for partially-created temp worktrees.
+      }
+      if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+      else process.env.GSD_HOME = savedGsdHome;
+      rmSync(fakeHome, { recursive: true, force: true });
+    }
+  });
+
   test("coexistence with manual worktree", async () => {
     tempDir = createTempRepo();
     const msDir = join(tempDir, ".gsd", "milestones", "M003");

package/src/resources/extensions/gsd/tests/milestone-report-path.test.ts

@@ -10,7 +10,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
-import { _resolveReportBasePath } from "../auto/phases.ts";
+import { _resolveDispatchGuardBasePath, _resolveReportBasePath } from "../auto/phases.ts";
 
 describe("_resolveReportBasePath", () => {
   test("uses originalBasePath when set (worktree scenario)", () => {
@@ -48,4 +48,21 @@ describe("_resolveReportBasePath", () => {
 
     assert.equal(_resolveReportBasePath(session), "/home/user/repo");
   });
+
+  test("uses GSD_PROJECT_ROOT for symlink-resolved worktree paths", () => {
+    const savedProjectRoot = process.env.GSD_PROJECT_ROOT;
+    process.env.GSD_PROJECT_ROOT = "/real/project";
+    try {
+      const session = {
+        originalBasePath: "",
+        basePath: "/Users/dev/.gsd/projects/abc123/worktrees/M001/slices/S01",
+      };
+
+      assert.equal(_resolveReportBasePath(session), "/real/project");
+      assert.equal(_resolveDispatchGuardBasePath(session), "/real/project");
+    } finally {
+      if (savedProjectRoot === undefined) delete process.env.GSD_PROJECT_ROOT;
+      else process.env.GSD_PROJECT_ROOT = savedProjectRoot;
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/safety-harness-false-positives.test.ts

@@ -18,9 +18,11 @@ import { shouldBlockQueueExecution } from "../bootstrap/write-gate.ts";
 import {
   resetEvidence,
   recordToolCall,
+  recordToolResult,
   getEvidence,
   saveEvidenceToDisk,
   loadEvidenceFromDisk,
+  type BashEvidence,
 } from "../safety/evidence-collector.ts";
 import { validateFileChanges } from "../safety/file-change-validator.ts";
 
@@ -110,6 +112,38 @@ test("safety-harness-bug2: loadEvidenceFromDisk returns empty array when no file
   assert.equal(getEvidence().length, 0, "no evidence on fresh unit is correct — not a false positive");
 });
 
+test("safety-harness-bug2-race: bash evidence survives mid-unit reset between tool_call and tool_execution_end", (t) => {
+  // Reproduces the race where runUnitPhase re-fires (resetEvidence + loadEvidenceFromDisk)
+  // between a bash tool_call and its tool_execution_end. Pre-fix, the call entry lived
+  // only in memory until tool_execution_end; the reset wiped it and recordToolResult
+  // silently no-op'd, producing the "task complete with no bash calls" false positive.
+  // Post-fix, register-hooks.ts persists at tool_call time too — so the entry survives
+  // the reset via the disk round-trip.
+  const base = mkdtempSync(join(tmpdir(), "gsd-evidence-race-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  resetEvidence();
+
+  // tool_call fires: record AND persist (post-fix register-hooks.ts behavior).
+  recordToolCall("tc-bash-1", "bash", { command: "grep -q saveTodos app.js" });
+  saveEvidenceToDisk(base, "M001", "S01", "T02");
+
+  // Mid-unit race: runUnitPhase re-fires, calling resetEvidence + loadEvidenceFromDisk.
+  resetEvidence();
+  assert.equal(getEvidence().length, 0, "memory cleared by mid-unit reset");
+  loadEvidenceFromDisk(base, "M001", "S01", "T02");
+  assert.equal(getEvidence().length, 1, "entry restored from disk-persisted tool_call");
+
+  // tool_execution_end fires: result must update the restored entry by toolCallId.
+  recordToolResult("tc-bash-1", "bash", "Command exited with code 0\nfound\n", false);
+
+  const bash = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(bash.length, 1, "bash entry must survive race + result update");
+  assert.equal(bash[0].exitCode, 0, "result populated the restored entry");
+  assert.equal(bash[0].command, "grep -q saveTodos app.js", "command preserved across race");
+  assert.ok(bash[0].outputSnippet.includes("found"), "output snippet captured");
+});
+
 // ─── Bug 3: git diff HEAD~1 scope check ─────────────────────────────────────
 
 test("safety-harness-bug3: validateFileChanges works on initial commit (no HEAD~1)", (t) => {

package/src/resources/extensions/gsd/tests/steer-worktree-path.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { appendOverride, loadActiveOverrides } from "../files.ts";
@@ -73,6 +73,22 @@ describe("steer worktree path resolution (#3476)", () => {
     assert.equal(result, null, "returns null for worktree without .git file");
   });
 
+  test("getAutoWorktreePath returns null when .git is a directory", () => {
+    mkdirSync(join(worktreePath, ".git"), { recursive: true });
+
+    const result = getAutoWorktreePath(projectRoot, "M001");
+
+    assert.equal(result, null, "returns null for standalone .git directories");
+  });
+
+  test("getAutoWorktreePath returns null when .git file is not a gitdir pointer", () => {
+    writeFileSync(join(worktreePath, ".git"), "not-a-gitdir\n", "utf-8");
+
+    const result = getAutoWorktreePath(projectRoot, "M001");
+
+    assert.equal(result, null, "returns null for invalid .git files");
+  });
+
   test("override routing: inactive worktree directory should not receive overrides", async () => {
     // Simulate the handleSteer path-resolution logic:
     // When no auto-mode is running, even if a worktree dir exists,

package/src/resources/extensions/gsd/tests/unit-context-manifest.test.ts

@@ -199,8 +199,8 @@ test("#4934: every manifest declares a tools policy", () => {
   }
 });
 
-test("#4934: tools.mode is one of the four declared policies", () => {
-  const validModes = new Set(["all", "read-only", "planning", "docs"]);
+test("#4934: tools.mode is one of the declared policies", () => {
+  const validModes = new Set(["all", "read-only", "planning", "planning-dispatch", "docs"]);
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     const mode = (manifest as { tools: { mode: string } }).tools.mode;
     assert.ok(
@@ -219,7 +219,42 @@ test('#4934: only execute-task and reactive-execute may use tools.mode "all" (fu
         allowedAllUnits.has(unitType),
         `manifest "${unitType}" declares tools.mode = "all" but is not on the execute-track. ` +
         'Only execute-task and reactive-execute should have full source write access; ' +
-        'planning/discuss/research units must use "planning" (or "docs" for rewrite-docs).',
+        'planning/discuss/research units must use "planning" or "planning-dispatch" (or "docs" for rewrite-docs).',
+      );
+    }
+  }
+});
+
+test('planning-dispatch mode is reserved for slice-level decomposition and completion units', () => {
+  const allowedDispatchUnits = new Set([
+    "plan-slice",
+    "refine-slice",
+    "complete-slice",
+    "complete-milestone",
+  ]);
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const mode = (manifest as { tools: { mode: string } }).tools.mode;
+    if (mode === "planning-dispatch") {
+      assert.ok(
+        allowedDispatchUnits.has(unitType),
+        `manifest "${unitType}" declares tools.mode = "planning-dispatch" but is not on the dispatch-allowed allowlist. ` +
+        'planning-dispatch is intentionally narrow — extend the allowlist consciously when a new unit type genuinely benefits from subagent delegation.',
+      );
+    }
+  }
+});
+
+test('planning-dispatch manifests declare non-empty allowedSubagents lists', () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    if (manifest.tools.mode !== "planning-dispatch") continue;
+    assert.ok(
+      Array.isArray(manifest.tools.allowedSubagents) && manifest.tools.allowedSubagents.length > 0,
+      `manifest "${unitType}" has planning-dispatch policy but no allowedSubagents — explicit allowlist is required for runtime dispatch gating`,
+    );
+    for (const agent of manifest.tools.allowedSubagents) {
+      assert.ok(
+        typeof agent === "string" && agent.length > 0,
+        `manifest "${unitType}" has empty/invalid allowedSubagents entry: ${JSON.stringify(agent)}`,
       );
     }
   }