gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.d8826a445

package/src/resources/extensions/gsd/tests/db-writer-root-artifact.test.ts

@@ -0,0 +1,221 @@
+// GSD-2 + db-writer root-artifact path guard: regression tests for M1 fix
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+import {
+  saveArtifactToDb,
+  saveArtifactToDbByScope,
+  saveArtifactToDbForWorkspace,
+} from "../db-writer.ts";
+import { openDatabase, closeDatabase } from "../gsd-db.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-dbwriter-root-")));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+// ─── Suite 1: saveArtifactToDb with undefined milestone_id writes to .gsd/ root, not milestones/ ──
+
+describe("saveArtifactToDb: root artifact (no milestone_id) routes to workspace .gsd root", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = makeProjectDir();
+    openDatabase(join(tmp, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("opts.milestone_id = undefined writes artifact at .gsd/REQUIREMENTS.md, not inside milestones/", async () => {
+    const content = "# Requirements\n\nTest root artifact.\n";
+    const opts = {
+      path: "REQUIREMENTS.md",
+      artifact_type: "REQUIREMENTS_DRAFT",
+      content,
+      milestone_id: undefined,
+    };
+
+    await saveArtifactToDb(opts, tmp);
+
+    const ws = createWorkspace(tmp);
+    const expectedPath = resolve(ws.contract.projectGsd, "REQUIREMENTS.md");
+
+    assert.ok(existsSync(expectedPath), "root artifact written at .gsd/REQUIREMENTS.md");
+    assert.equal(readFileSync(expectedPath, "utf-8"), content, "content matches");
+
+    // Must NOT be inside milestones/ — the latent trap being fixed
+    const wrongPath = resolve(ws.contract.projectGsd, "milestones", "", "REQUIREMENTS.md");
+    assert.ok(!existsSync(wrongPath), "artifact NOT written inside milestones/");
+  });
+
+  test("opts.milestone_id = null writes artifact at .gsd/ root", async () => {
+    const content = "# Project\n\nRoot project doc.\n";
+    const opts = {
+      path: "PROJECT.md",
+      artifact_type: "PROJECT",
+      content,
+      milestone_id: undefined,
+    };
+
+    await saveArtifactToDb(opts, tmp);
+
+    const ws = createWorkspace(tmp);
+    const expectedPath = resolve(ws.contract.projectGsd, "PROJECT.md");
+
+    assert.ok(existsSync(expectedPath), "PROJECT.md written at .gsd/PROJECT.md");
+    assert.equal(readFileSync(expectedPath, "utf-8"), content, "content matches");
+  });
+
+  test("path resolves via workspace.contract.projectGsd, not a hand-rolled join", async () => {
+    const content = "# Knowledge\n";
+    const opts = {
+      path: "KNOWLEDGE.md",
+      artifact_type: "KNOWLEDGE",
+      content,
+      milestone_id: undefined,
+    };
+
+    await saveArtifactToDb(opts, tmp);
+
+    const ws = createWorkspace(tmp);
+    // The canonical path must equal contract.projectGsd + '/KNOWLEDGE.md'
+    const canonicalPath = join(ws.contract.projectGsd, "KNOWLEDGE.md");
+    assert.ok(existsSync(canonicalPath), "file at contract.projectGsd/KNOWLEDGE.md");
+    assert.equal(
+      canonicalPath,
+      join(ws.projectRoot, ".gsd", "KNOWLEDGE.md"),
+      "contract.projectGsd-based path equals projectRoot/.gsd/KNOWLEDGE.md",
+    );
+  });
+});
+
+// ─── Suite 2: saveArtifactToDb with a real milestone_id still works (no regression) ──
+
+describe("saveArtifactToDb: milestone_id present routes to milestones/ (no regression)", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = makeProjectDir();
+    openDatabase(join(tmp, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("milestone_id = 'M001' writes to .gsd/milestones/M001/...", async () => {
+    const relPath = "milestones/M001/M001-CONTEXT.md";
+    const content = "# M001 Context\n";
+    const opts = {
+      path: relPath,
+      artifact_type: "CONTEXT",
+      content,
+      milestone_id: "M001",
+    };
+
+    await saveArtifactToDb(opts, tmp);
+
+    const ws = createWorkspace(tmp);
+    const expectedPath = resolve(ws.contract.projectGsd, relPath);
+
+    assert.ok(existsSync(expectedPath), "milestone artifact written at correct path");
+    assert.equal(readFileSync(expectedPath, "utf-8"), content, "content matches");
+  });
+});
+
+// ─── Suite 3: saveArtifactToDbByScope with empty milestoneId throws a clear error ──
+
+describe("saveArtifactToDbByScope: empty milestoneId throws defensive error", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = makeProjectDir();
+    openDatabase(join(tmp, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("scope with empty milestoneId throws GSDError mentioning saveArtifactToDbForWorkspace", async () => {
+    const ws = createWorkspace(tmp);
+    const emptyScope = scopeMilestone(ws, "");
+    const opts = {
+      path: "REQUIREMENTS.md",
+      artifact_type: "REQUIREMENTS_DRAFT",
+      content: "# req\n",
+    };
+
+    await assert.rejects(
+      () => saveArtifactToDbByScope(emptyScope, opts),
+      (err: unknown) => {
+        assert.ok(err instanceof Error, "thrown value is an Error");
+        assert.ok(
+          err.message.includes("milestoneId is empty"),
+          `error message should mention 'milestoneId is empty', got: ${err.message}`,
+        );
+        assert.ok(
+          err.message.includes("saveArtifactToDbForWorkspace"),
+          `error message should mention 'saveArtifactToDbForWorkspace', got: ${err.message}`,
+        );
+        return true;
+      },
+    );
+  });
+});
+
+// ─── Suite 4: saveArtifactToDbForWorkspace writes at contract.projectGsd, not milestones/ ──
+
+describe("saveArtifactToDbForWorkspace: writes directly to .gsd root via workspace contract", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = makeProjectDir();
+    openDatabase(join(tmp, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("root artifact lands at contract.projectGsd/path, not milestones/", async () => {
+    const ws = createWorkspace(tmp);
+    const content = "# Requirements\n";
+    const opts = {
+      path: "REQUIREMENTS.md",
+      artifact_type: "REQUIREMENTS_DRAFT",
+      content,
+    };
+
+    await saveArtifactToDbForWorkspace(ws, opts);
+
+    const expectedPath = resolve(ws.contract.projectGsd, "REQUIREMENTS.md");
+    assert.ok(existsSync(expectedPath), "artifact written at contract.projectGsd/REQUIREMENTS.md");
+    assert.equal(readFileSync(expectedPath, "utf-8"), content, "content matches");
+
+    // Must not have landed inside milestones/
+    const milestonePath = join(ws.contract.projectGsd, "milestones", "", "REQUIREMENTS.md");
+    assert.ok(!existsSync(milestonePath), "artifact NOT inside milestones/empty-string/");
+  });
+});

package/src/resources/extensions/gsd/tests/db-writer-scope.test.ts

@@ -0,0 +1,230 @@
+// GSD-2 + db-writer saveArtifactToDbByScope: workspace-contract path routing tests
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+import { saveArtifactToDb, saveArtifactToDbByScope } from "../db-writer.ts";
+import { openDatabase, closeDatabase } from "../gsd-db.ts";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-dbwriter-scope-")));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+// ─── Suite 1: scope variant writes to the same canonical path as legacy ──────
+
+describe("saveArtifactToDbByScope: path parity with legacy saveArtifactToDb", () => {
+  let tmp1: string;
+  let tmp2: string;
+
+  beforeEach(() => {
+    tmp1 = makeProjectDir();
+    tmp2 = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp1, { recursive: true, force: true });
+    rmSync(tmp2, { recursive: true, force: true });
+  });
+
+  test("scope variant writes artifact to same canonical path as legacy variant", async () => {
+    const relPath = "milestones/M001/slices/S01/tasks/T01-SUMMARY.md";
+    const content = "# T01 Summary\n\nTest content.\n";
+    const opts = {
+      path: relPath,
+      artifact_type: "SUMMARY",
+      content,
+      milestone_id: "M001",
+      slice_id: "S01",
+      task_id: "T01",
+    };
+
+    // Legacy path: basePath + '.gsd' join
+    const legacyExpectedPath = resolve(tmp1, ".gsd", relPath);
+
+    // Scope path: contract.projectGsd
+    const ws = createWorkspace(tmp2);
+    const scope = scopeMilestone(ws, "M001");
+    const scopeExpectedPath = resolve(ws.contract.projectGsd, relPath);
+
+    // Both should resolve to the same relative structure
+    // (though under different temp dirs — so we compare structure, not absolute path)
+    assert.equal(
+      scopeExpectedPath,
+      resolve(ws.contract.projectGsd, relPath),
+      "scope path must be contract.projectGsd + relPath",
+    );
+    assert.equal(
+      legacyExpectedPath,
+      resolve(tmp1, ".gsd", relPath),
+      "legacy path must be basePath/.gsd + relPath",
+    );
+
+    // Open DB for tmp1 and write via legacy
+    const dbPath1 = join(tmp1, ".gsd", "gsd.db");
+    openDatabase(dbPath1);
+    await saveArtifactToDb(opts, tmp1);
+    closeDatabase();
+
+    // Open DB for tmp2 and write via scope variant
+    const dbPath2 = join(tmp2, ".gsd", "gsd.db");
+    openDatabase(dbPath2);
+    await saveArtifactToDbByScope(scope, opts);
+    closeDatabase();
+
+    // Both should have written to the correct location under their respective .gsd dirs
+    assert.ok(existsSync(legacyExpectedPath), "legacy: artifact written at basePath/.gsd/relPath");
+    assert.ok(existsSync(scopeExpectedPath), "scope: artifact written at contract.projectGsd/relPath");
+
+    // Content must match
+    assert.equal(readFileSync(legacyExpectedPath, "utf-8"), content, "legacy: content matches");
+    assert.equal(readFileSync(scopeExpectedPath, "utf-8"), content, "scope: content matches");
+  });
+});
+
+// ─── Suite 2: scope variant uses contract.projectGsd, not a basePath join ────
+
+describe("saveArtifactToDbByScope: uses contract.projectGsd, not hand-rolled basePath join", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = makeProjectDir();
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("scope.workspace.contract.projectGsd is used as the .gsd root, not basePath/.gsd", async () => {
+    const ws = createWorkspace(tmp);
+    const scope = scopeMilestone(ws, "M001");
+
+    // The contract.projectGsd must equal the canonical join(projectRoot, '.gsd')
+    assert.equal(
+      ws.contract.projectGsd,
+      join(ws.projectRoot, ".gsd"),
+      "contract.projectGsd must equal join(projectRoot, '.gsd')",
+    );
+
+    // It must NOT be a hand-rolled resolution from an arbitrary basePath string
+    // (i.e., contract.projectGsd routes through the workspace contract)
+    assert.ok(
+      ws.contract.projectGsd.startsWith(ws.projectRoot),
+      "contract.projectGsd must be rooted at projectRoot",
+    );
+
+    const relPath = "milestones/M001/M001-CONTEXT.md";
+    const content = "# M001 Context\n";
+    const opts = {
+      path: relPath,
+      artifact_type: "CONTEXT",
+      content,
+      milestone_id: "M001",
+    };
+
+    openDatabase(join(tmp, ".gsd", "gsd.db"));
+    await saveArtifactToDbByScope(scope, opts);
+
+    // File must be at contract.projectGsd/relPath
+    const expectedPath = resolve(ws.contract.projectGsd, relPath);
+    assert.ok(existsSync(expectedPath), "artifact written at contract.projectGsd/relPath");
+    assert.equal(readFileSync(expectedPath, "utf-8"), content, "content matches");
+
+    // And must NOT be at some other location
+    const handRolledPath = resolve(tmp, ".gsd", relPath);
+    // Both should be the same path in project mode (they should agree)
+    assert.equal(
+      expectedPath,
+      handRolledPath,
+      "in project mode, contract.projectGsd resolves same as basePath/.gsd",
+    );
+  });
+});
+
+// ─── Suite 3: worktree-mode scope routes to project root's .gsd/ ─────────────
+
+describe("saveArtifactToDbByScope: worktree scope writes to project root .gsd/", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = realpathSync(mkdtempSync(join(tmpdir(), "gsd-dbwriter-wt-scope-")));
+    // Create project .gsd directory
+    mkdirSync(join(tmp, ".gsd"), { recursive: true });
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("worktree-mode scope: contract.projectGsd resolves to project root's .gsd/, not worktree .gsd/", async () => {
+    // Construct a worktree path inside the project's .gsd/worktrees/<MID>
+    const worktreePath = join(tmp, ".gsd", "worktrees", "M001");
+    mkdirSync(join(worktreePath, ".gsd"), { recursive: true });
+
+    const projectWs = createWorkspace(tmp);
+    const worktreeWs = createWorkspace(worktreePath);
+
+    // Both should share the same projectRoot (worktree-root resolution)
+    assert.equal(
+      worktreeWs.projectRoot,
+      projectWs.projectRoot,
+      "worktree workspace must have same projectRoot as project workspace",
+    );
+
+    // contract.projectGsd for the worktree workspace must point to the PROJECT root's .gsd/
+    assert.equal(
+      worktreeWs.contract.projectGsd,
+      join(projectWs.projectRoot, ".gsd"),
+      "worktree contract.projectGsd must equal project root's .gsd/",
+    );
+
+    // Must NOT be the worktree-local .gsd/
+    assert.notEqual(
+      worktreeWs.contract.projectGsd,
+      join(worktreePath, ".gsd"),
+      "worktree contract.projectGsd must NOT be the worktree-local .gsd/",
+    );
+
+    // Write via the worktree-mode scope
+    const scope = scopeMilestone(worktreeWs, "M001");
+    const relPath = "milestones/M001/M001-CONTEXT.md";
+    const content = "# M001 Context from worktree scope\n";
+    const opts = {
+      path: relPath,
+      artifact_type: "CONTEXT",
+      content,
+      milestone_id: "M001",
+    };
+
+    openDatabase(join(tmp, ".gsd", "gsd.db"));
+    await saveArtifactToDbByScope(scope, opts);
+
+    // File must land in the PROJECT root's .gsd/, not in the worktree's .gsd/
+    const projectPath = resolve(projectWs.contract.projectGsd, relPath);
+    const worktreeLocalPath = resolve(worktreePath, ".gsd", relPath);
+
+    assert.ok(existsSync(projectPath), "artifact written to project root's .gsd/");
+    assert.ok(
+      !existsSync(worktreeLocalPath),
+      "artifact must NOT be written to worktree-local .gsd/",
+    );
+    assert.equal(readFileSync(projectPath, "utf-8"), content, "content at project root matches");
+  });
+});

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

@@ -481,7 +481,7 @@ describe('db-writer', () => {
     }
   });
 
-  test('updateRequirementInDb — seeds from REQUIREMENTS.md when DB empty (#3346)', async () => {
+  test('updateRequirementInDb — ignores REQUIREMENTS.md projection when DB empty', async () => {
     const tmpDir = makeTmpDir();
     const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
     openDatabase(dbPath);
@@ -515,31 +515,28 @@ describe('db-writer', () => {
       ].join('\n');
       fs.writeFileSync(path.join(tmpDir, '.gsd', 'REQUIREMENTS.md'), reqContent);
 
-      // DB is empty — no requirements seeded. Update R005 to "validated".
-      // Before #3346 fix: this would create a skeleton with empty fields.
-      // After fix: this seeds all 3 requirements from REQUIREMENTS.md first.
+      // DB is empty. REQUIREMENTS.md is a projection and must not be imported
+      // implicitly by a runtime DB write.
       await updateRequirementInDb('R005', {
         status: 'validated',
         validation: 'S02 — auth flow verified',
       }, tmpDir);
 
-      // R005 should have the update AND the original content from markdown
+      // R005 should have the requested update only; disk projection content is ignored.
       const r005 = getRequirementById('R005');
       assert.ok(r005, 'R005 should exist');
       assert.equal(r005!.status, 'validated', 'status should be updated');
       assert.equal(r005!.validation, 'S02 — auth flow verified', 'validation should be updated');
-      assert.equal(r005!.class, 'functional', 'class should be preserved from REQUIREMENTS.md');
-      assert.ok(r005!.description?.includes('authentication') || r005!.full_content?.includes('authentication'),
-        'original content should be preserved');
+      assert.equal(r005!.class, '', 'class should not be imported from REQUIREMENTS.md');
+      assert.ok(!r005!.description?.includes('authentication'), 'description should not be imported');
+      assert.ok(!r005!.full_content?.includes('authentication'), 'full content should not be imported');
 
-      // R007 and R001 should also be seeded (not just the one being updated)
+      // Other requirements in the projection are not seeded.
       const r007 = getRequirementById('R007');
-      assert.ok(r007, 'R007 should be seeded from REQUIREMENTS.md');
-      assert.equal(r007!.status, 'active', 'R007 status should be active');
+      assert.equal(r007, null, 'R007 should not be imported from REQUIREMENTS.md');
 
       const r001 = getRequirementById('R001');
-      assert.ok(r001, 'R001 should be seeded from REQUIREMENTS.md');
-      assert.equal(r001!.status, 'validated', 'R001 status should be validated (from section heading)');
+      assert.equal(r001, null, 'R001 should not be imported from REQUIREMENTS.md');
     } finally {
       closeDatabase();
       cleanupDir(tmpDir);
@@ -663,15 +660,16 @@ describe('db-writer', () => {
         'disk file preserved — shrinkage guard prevented overwrite',
       );
 
-      // DB should contain the full disk content, not the abbreviated content
+      // DB should keep the caller-provided content. The larger disk file is a
+      // stale projection, not runtime authority.
       const adapter = _getAdapter();
       const row = adapter!
         .prepare('SELECT full_content FROM artifacts WHERE path = ?')
         .get(relPath);
       assert.deepStrictEqual(
         row!['full_content'],
-        fullContent,
-        'DB stores the richer disk content instead of abbreviated content',
+        abbreviatedContent,
+        'DB stores caller-provided content instead of importing disk projection content',
       );
     } finally {
       closeDatabase();

package/src/resources/extensions/gsd/tests/delegation-policy.test.ts

@@ -0,0 +1,151 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  annotateBackgroundable,
+  getDelegationVerdict,
+  getVerdictByUnitType,
+  isBackgroundable,
+  listBackgroundableTools,
+} from "../delegation-policy.js";
+
+// Pin the GOOD set: changes here must come with explicit re-evaluation.
+const EXPECTED_BACKGROUNDABLE = [
+  "gsd_execute",
+  "gsd_plan_slice",
+  "gsd_reassess_roadmap",
+  "gsd_validate_milestone",
+];
+
+test("isBackgroundable returns true for the four GOOD-verdict tools", () => {
+  for (const name of EXPECTED_BACKGROUNDABLE) {
+    assert.equal(isBackgroundable(name), true, `${name} should be backgroundable`);
+  }
+});
+
+test("isBackgroundable returns false for RISKY-verdict tools", () => {
+  for (const name of ["gsd_doctor", "gsd_plan_milestone", "gsd_replan_slice"]) {
+    assert.equal(isBackgroundable(name), false, `${name} should not be backgroundable`);
+  }
+});
+
+test("isBackgroundable returns false for NO-verdict tools", () => {
+  assert.equal(isBackgroundable("gsd_plan_task"), false);
+});
+
+test("isBackgroundable defaults to false for unknown tools (default-deny)", () => {
+  assert.equal(isBackgroundable("gsd_nonexistent_tool"), false);
+  assert.equal(isBackgroundable(""), false);
+});
+
+test("listBackgroundableTools returns exactly the four GOOD tools, sorted", () => {
+  assert.deepEqual(listBackgroundableTools(), EXPECTED_BACKGROUNDABLE);
+});
+
+test("getDelegationVerdict resolves alias names to canonical entries", () => {
+  for (const [alias, canonical] of [
+    ["gsd_milestone_validate", "gsd_validate_milestone"],
+    ["gsd_roadmap_reassess", "gsd_reassess_roadmap"],
+    ["gsd_slice_replan", "gsd_replan_slice"],
+    ["gsd_task_plan", "gsd_plan_task"],
+  ] as const) {
+    const entry = getDelegationVerdict(alias);
+    assert.ok(entry, `alias ${alias} should resolve`);
+    assert.equal(entry.toolName, canonical, `${alias} should resolve to ${canonical}`);
+  }
+});
+
+test("plan_slice carries the slice-lock + await constraints", () => {
+  const entry = getDelegationVerdict("gsd_plan_slice");
+  assert.ok(entry);
+  assert.ok(entry.constraints && entry.constraints.length >= 3);
+  assert.ok(
+    entry.constraints!.some((c) => /lock the slice/i.test(c)),
+    "plan_slice must carry the slice-lock constraint",
+  );
+  assert.ok(
+    entry.constraints!.some((c) => /await background completion/i.test(c)),
+    "plan_slice must require await before downstream reads",
+  );
+});
+
+test("doctor carries fix-mode safety constraints", () => {
+  const entry = getDelegationVerdict("gsd_doctor");
+  assert.ok(entry);
+  assert.equal(entry.verdict, "risky");
+  assert.ok(
+    entry.constraints && entry.constraints.some((c) => /fix=false/.test(c)),
+    "doctor must restrict background runs to fix=false",
+  );
+});
+
+test("getVerdictByUnitType maps dispatcher unit types back to the policy", () => {
+  assert.equal(getVerdictByUnitType("plan-slice")?.toolName, "gsd_plan_slice");
+  assert.equal(getVerdictByUnitType("validate-milestone")?.toolName, "gsd_validate_milestone");
+  assert.equal(getVerdictByUnitType("reassess-roadmap")?.toolName, "gsd_reassess_roadmap");
+  assert.equal(getVerdictByUnitType("plan-milestone")?.toolName, "gsd_plan_milestone");
+  assert.equal(getVerdictByUnitType("replan-slice")?.toolName, "gsd_replan_slice");
+  assert.equal(getVerdictByUnitType("nonexistent-unit"), null);
+});
+
+test("every entry carries a non-empty rationale so the verdict is auditable", () => {
+  for (const name of [...EXPECTED_BACKGROUNDABLE, "gsd_doctor", "gsd_plan_milestone", "gsd_replan_slice", "gsd_plan_task"]) {
+    const entry = getDelegationVerdict(name);
+    assert.ok(entry, `${name} should be in the policy`);
+    assert.ok(entry.rationale.length > 20, `${name} rationale must be substantive`);
+  }
+});
+
+// ─── annotateBackgroundable contract pins ────────────────────────────────
+
+test("annotateBackgroundable recomputes the verdict on every call (no internal cache)", () => {
+  // The annotator mutates in place. Repeated calls on the same object with
+  // different unit types must always reflect the latest unitType — never a
+  // stale cached value. This pins the contract documented in the JSDoc so a
+  // future "optimization" that adds memoization keyed on object identity
+  // breaks the suite instead of silently leaking a stale flag.
+  const action: { action: "dispatch"; unitType: string; backgroundable?: boolean } = {
+    action: "dispatch",
+    unitType: "plan-slice",
+  };
+  annotateBackgroundable(action);
+  assert.equal(action.backgroundable, true, "plan-slice should annotate true");
+
+  action.unitType = "plan-milestone";
+  annotateBackgroundable(action);
+  assert.equal(action.backgroundable, false, "plan-milestone (risky) should re-annotate false");
+
+  action.unitType = "validate-milestone";
+  annotateBackgroundable(action);
+  assert.equal(action.backgroundable, true, "validate-milestone should re-annotate true");
+
+  action.unitType = "complete-slice";
+  annotateBackgroundable(action);
+  assert.equal(action.backgroundable, false, "uncovered unit type should re-annotate false (default-deny)");
+});
+
+test("annotateBackgroundable passes stop/skip actions through unchanged", () => {
+  const stop = { action: "stop" as const, reason: "x", level: "info" as const };
+  const skip = { action: "skip" as const };
+  assert.equal(annotateBackgroundable(stop), stop);
+  assert.equal(annotateBackgroundable(skip), skip);
+  assert.equal((stop as Record<string, unknown>).backgroundable, undefined);
+  assert.equal((skip as Record<string, unknown>).backgroundable, undefined);
+});
+
+// ─── F4 latent gap pin: silent default-deny on unit types invoking GOOD tools ──
+
+test("execute-task / reactive-execute / execute-task-simple intentionally default-deny despite gsd_execute being GOOD", () => {
+  // gsd_execute carries a GOOD verdict but no `unitType`, by design — the
+  // unit-level orchestrations wrap prompt and harness work whose safety is
+  // a separate analysis. Lifting these out of default-deny must be an
+  // explicit, audited change. This test pins the current behavior; if the
+  // policy entry gains a unitType mapping (or a unitTypes array), update
+  // both the entry and this test together.
+  for (const unitType of ["execute-task", "execute-task-simple", "reactive-execute"]) {
+    assert.equal(
+      getVerdictByUnitType(unitType),
+      null,
+      `${unitType} must remain unmapped until per-unit analysis is recorded`,
+    );
+  }
+});