@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.75048e7

package/src/resources/extensions/gsd/tests/integration/run-uat.test.ts

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url';
 import { extractUatType } from '../../files.ts';
 import { resolveSliceFile } from '../../paths.ts';
 import { buildRunUatPrompt, checkNeedsRunUat } from '../../auto-prompts.ts';
+import { buildRunUatResultPresentation, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from '../../tool-presentation-plan.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const worktreePromptsDir = join(__dirname, '../..', 'prompts');
@@ -20,6 +21,8 @@ function loadPromptFromWorktree(name: string, vars: Record<string, string> = {})
   let content = readFileSync(path, 'utf-8');
   const effectiveVars = {
     skillActivation: 'If no installed skill clearly matches this unit, skip explicit skill activation and continue with the required workflow.',
+    canonicalPresentation: JSON.stringify(buildRunUatResultPresentation(), null, 2),
+    toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
     ...vars,
   };
   for (const [key, value] of Object.entries(effectiveVars)) {
@@ -72,6 +75,38 @@ function makeBrowserObservableUatContent(mode = 'artifact-driven'): string {
   ].join('\n');
 }
 
+function makeDeferredBrowserUatContent(): string {
+  return [
+    '# UAT File',
+    '',
+    '## UAT Type',
+    '',
+    '- UAT mode: artifact-driven',
+    '- Why this mode is sufficient: Node interaction tests exercise the real app.js render/event/localStorage loop through a DOM harness. Live browser, keyboard, responsive, and visual-polish UAT remain intentionally deferred to S02.',
+    '',
+    '## Smoke Test',
+    '',
+    'Run `node --test tests/s01-static-interactions.test.js` and confirm all tests pass.',
+    '',
+    '## Test Cases',
+    '',
+    '1. Click the todo row edit control in the DOM harness.',
+    '2. Save changed text and reload/recreate the app from persisted localStorage.',
+    '3. Expected: the stored record shape remains unchanged.',
+    '',
+    '## Not Proven By This UAT',
+    '',
+    '- Final visual polish of edit controls.',
+    '- Keyboard usability through a real browser.',
+    '- Browser console and local network cleanliness.',
+    '',
+    '## Notes for Tester',
+    '',
+    'S02 should capture browser evidence for the full loop rather than changing this persisted model.',
+    '',
+  ].join('\n');
+}
+
 describe('run-uat', () => {
 test('(a) artifact-driven', () => {
   assert.deepStrictEqual(
@@ -232,8 +267,8 @@ test('(k) run-uat prompt template', () => {
     `prompt contains detected dynamic uatType value "${uatType}" after substitution`,
   );
   assert.ok(
-    promptResult?.includes(`uatType: ${uatType}`) ?? false,
-    `prompt contains dynamic uatType frontmatter value "${uatType}" after substitution`,
+    promptResult?.includes(`uatType: "${uatType}"`) ?? false,
+    `prompt contains dynamic uatType field "${uatType}" after substitution`,
   );
   assert.ok(
     !/\{\{[^}]+\}\}/.test(promptResult ?? ''),
@@ -249,7 +284,7 @@ test('(k) run-uat prompt template', () => {
   );
 });
 
-test('(k2) run-uat prompt references gsd_summary_save, not direct write', () => {
+test('(k2) run-uat prompt references gsd_uat_result_save, not direct write', () => {
   const promptResult = loadPromptFromWorktree('run-uat', {
     workingDirectory: '/tmp/test-project',
     milestoneId: 'M001',
@@ -261,17 +296,25 @@ test('(k2) run-uat prompt references gsd_summary_save, not direct write', () =>
   });
 
   assert.ok(
-    promptResult.includes('gsd_summary_save'),
-    'run-uat prompt should reference gsd_summary_save tool',
+    promptResult.includes('gsd_uat_result_save'),
+    'run-uat prompt should reference gsd_uat_result_save tool',
+  );
+  assert.ok(
+    promptResult.includes('presentedTools') && promptResult.includes('blockedTools'),
+    'run-uat prompt should specify the tool presentation contract',
   );
   assert.ok(
-    promptResult.includes('artifact_type: "ASSESSMENT"'),
-    'run-uat prompt should specify ASSESSMENT artifact type',
+    !promptResult.includes('Call `gsd_summary_save`'),
+    'run-uat prompt should not instruct direct summary-save UAT persistence',
   );
   assert.ok(
     !promptResult.includes('MUST write'),
     'run-uat prompt should not instruct direct file write in footer',
   );
+  assert.ok(
+    !promptResult.includes('Call `gsd_summary_save` with `artifact_type: "ASSESSMENT"`'),
+    'run-uat prompt should not instruct the legacy summary-save UAT path',
+  );
 });
 
 test('(l) dispatch preconditions via resolveSliceFile', () => {
@@ -482,8 +525,8 @@ test('(n) stale replay guard', async () => {
 });
 
 test('(q) verdict in ASSESSMENT file skips UAT dispatch (file-based path)', async () => {
-    // Regression test for #2644: run-uat prompt writes the verdict to
-    // S{sid}-ASSESSMENT.md (via gsd_summary_save artifact_type:"ASSESSMENT"),
+    // Regression test for #2644: run-uat writes the verdict to
+    // S{sid}-ASSESSMENT.md through the structured UAT save path,
     // but checkNeedsRunUat only checked S{sid}-UAT.md — causing a stuck loop.
     const base = createFixtureBase();
     try {
@@ -679,11 +722,30 @@ test('(u) run-uat prompt promotes artifact-driven browser specs to browser-execu
       const prompt = await buildRunUatPrompt('M001', 'S01', uatRel, uatContent, base);
 
       assert.match(prompt, /\*\*Detected UAT mode:\*\*\s*`browser-executable`/);
-      assert.match(prompt, /uatType: browser-executable/);
+      assert.match(prompt, /uatType: "browser-executable"/);
       assert.match(prompt, /use gsd-browser tools/i);
+      assert.match(prompt, /"browser_navigate"/);
+      assert.match(prompt, /"browser_assert"/);
     } finally {
       cleanup(base);
     }
 });
 
+test('(v) run-uat prompt keeps deferred browser work artifact-driven', async () => {
+    const base = createFixtureBase();
+    try {
+      const uatRel = '.gsd/milestones/M001/slices/S01/S01-UAT.md';
+      const uatContent = makeDeferredBrowserUatContent();
+      writeSliceFile(base, 'M001', 'S01', 'UAT', uatContent);
+
+      const prompt = await buildRunUatPrompt('M001', 'S01', uatRel, uatContent, base);
+
+      assert.match(prompt, /\*\*Detected UAT mode:\*\*\s*`artifact-driven`/);
+      assert.match(prompt, /uatType: "artifact-driven"/);
+      assert.doesNotMatch(prompt, /uatType: "browser-executable"/);
+      assert.doesNotMatch(prompt, /"browser_navigate"/);
+    } finally {
+      cleanup(base);
+    }
+});
 });

package/src/resources/extensions/gsd/tests/mcp-project-config.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
+  buildProjectBrowserMcpServerConfig,
   ensureClaudeCodeMcpJsonServerEnabled,
   ensureProjectWorkflowMcpConfig,
   GSD_BROWSER_MCP_SERVER_NAME,
@@ -160,6 +161,37 @@ test("ensureProjectWorkflowMcpConfig can disable the default browser MCP server"
   }
 });
 
+test("buildProjectBrowserMcpServerConfig prefers newer gsd-browser on PATH", () => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-browser-"));
+
+  try {
+    const config = buildProjectBrowserMcpServerConfig(projectRoot, {
+      GSD_BROWSER_PATH_VERSION: "99.0.0",
+    });
+
+    assert.equal(config?.command, "gsd-browser");
+    assert.equal(config?.args?.[0], "mcp");
+  } finally {
+    rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test("buildProjectBrowserMcpServerConfig keeps bundled browser when PATH version is older", () => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-browser-"));
+
+  try {
+    const config = buildProjectBrowserMcpServerConfig(projectRoot, {
+      GSD_BROWSER_PATH_VERSION: "0.0.1",
+    });
+
+    assert.equal(config?.command, process.execPath);
+    assert.match(config?.args?.[0] ?? "", /@opengsd[\/\\]gsd-browser[\/\\]bin[\/\\]gsd-browser/);
+    assert.equal(config?.args?.[1], "mcp");
+  } finally {
+    rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
 test("ensureProjectWorkflowMcpConfig is idempotent when config is already current", () => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-init-"));
   mkdirSync(join(projectRoot, ".gsd"), { recursive: true });

package/src/resources/extensions/gsd/tests/mcp-status.test.ts

@@ -341,6 +341,8 @@ describe("formatMcpInitResult", () => {
     assert.match(result, /created project mcp config/i);
     assert.match(result, /\/tmp\/project\/\.mcp\.json/);
     assert.match(result, /mcp-capable clients/i);
+    assert.match(result, /workflow and gsd-browser MCP servers/i);
+    assert.match(result, /Pi Providers use the managed gsd-browser engine/i);
     assert.doesNotMatch(result, /claude code/i);
   });
 

package/src/resources/extensions/gsd/tests/memory-maintenance.test.ts

@@ -11,6 +11,16 @@ import {
 import { createMemoryRelation, listRelationsFor } from '../memory-relations.ts';
 import { saveEmbedding, getEmbeddingForMemory } from '../memory-embeddings.ts';
 
+function markProcessedUnits(count = 21): void {
+  const now = Date.now();
+  for (let i = 0; i < count; i++) {
+    markUnitProcessed(`unit/${i}`, `file-${i}`);
+    _getAdapter()!
+      .prepare('UPDATE memory_processed_units SET processed_at = :ts WHERE unit_key = :key')
+      .run({ ':ts': new Date(now + i * 1000).toISOString(), ':key': `unit/${i}` });
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // enforceMemoryCap — cascade cleanup of embeddings and relations
 // ═══════════════════════════════════════════════════════════════════════════
@@ -71,14 +81,7 @@ test('memory-decay: returns decayed memory IDs', () => {
   openDatabase(':memory:');
 
   // Insert processed units — decayStaleMemories needs at least N rows.
-  const now = Date.now();
-  for (let i = 0; i < 21; i++) {
-    markUnitProcessed(`unit/${i}`, `file-${i}`);
-    // small spacing to create deterministic ordering
-    const row = _getAdapter()!
-      .prepare('UPDATE memory_processed_units SET processed_at = :ts WHERE unit_key = :key');
-    row.run({ ':ts': new Date(now + i * 1000).toISOString(), ':key': `unit/${i}` });
-  }
+  markProcessedUnits();
 
   // Create memory with updated_at in the distant past
   createMemory({ category: 'pattern', content: 'stale entry', confidence: 0.9 });
@@ -98,6 +101,34 @@ test('memory-decay: returns decayed memory IDs', () => {
   closeDatabase();
 });
 
+test('memory-decay: skips stale decision-sourced memories', () => {
+  openDatabase(':memory:');
+  markProcessedUnits();
+
+  createMemory({ category: 'pattern', content: 'stale working note', confidence: 0.9 });
+  createMemory({
+    category: 'architecture',
+    content: 'decision-backed architecture memory',
+    confidence: 0.85,
+    structuredFields: { sourceDecisionId: 'D001' },
+  });
+  _getAdapter()!
+    .prepare("UPDATE memories SET updated_at = '2000-01-01T00:00:00Z' WHERE id IN ('MEM001', 'MEM002')")
+    .run({});
+
+  const decayed = decayStaleMemories(20);
+  assert.ok(decayed.includes('MEM001'));
+  assert.ok(!decayed.includes('MEM002'));
+
+  const rows = _getAdapter()!
+    .prepare("SELECT id, confidence FROM memories WHERE id IN ('MEM001', 'MEM002') ORDER BY id")
+    .all() as Array<{ id: string; confidence: number }>;
+  assert.ok(rows.find((row) => row.id === 'MEM001')!.confidence < 0.9);
+  assert.equal(rows.find((row) => row.id === 'MEM002')!.confidence, 0.85);
+
+  closeDatabase();
+});
+
 test('memory-decay: returns empty when there are fewer processed units than the threshold', () => {
   openDatabase(':memory:');
   createMemory({ category: 'pattern', content: 'fresh' });

package/src/resources/extensions/gsd/tests/merge-closeout-consistency-gate.test.ts

@@ -0,0 +1,63 @@
+// Project/App: gsd-pi
+// File Purpose: Regression tests for DB-backed closeout consistency before merge.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { mergeMilestoneToMain } from "../auto-worktree.ts";
+import { closeDatabase, insertMilestone, openDatabase } from "../gsd-db.ts";
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function createRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "merge-closeout-gate-")));
+  git(["init"], dir);
+  git(["config", "user.email", "test@test.com"], dir);
+  git(["config", "user.name", "Test"], dir);
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  git(["add", "."], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+
+  git(["checkout", "-b", "milestone/M001"], dir);
+  writeFileSync(join(dir, "feature.ts"), "export const feature = true;\n");
+  git(["add", "feature.ts"], dir);
+  git(["commit", "-m", "feat: milestone work"], dir);
+  git(["checkout", "main"], dir);
+  return dir;
+}
+
+test("mergeMilestoneToMain blocks when project DB closeout is still open", () => {
+  const savedCwd = process.cwd();
+  const repo = createRepo();
+  try {
+    assert.equal(openDatabase(join(repo, ".gsd", "gsd.db")), true);
+    insertMilestone({ id: "M001", title: "Milestone One", status: "active" });
+
+    const mainHeadBefore = git(["rev-parse", "main"], repo);
+    process.chdir(repo);
+
+    assert.throws(
+      () => mergeMilestoneToMain(repo, "M001", "# M001\n- [x] **S01: Done**\n"),
+      /closeout-consistency-blocked/,
+    );
+
+    assert.equal(git(["rev-parse", "main"], repo), mainHeadBefore);
+    assert.equal(git(["branch", "--show-current"], repo), "main");
+  } finally {
+    closeDatabase();
+    process.chdir(savedCwd);
+    if (existsSync(repo)) rmSync(repo, { recursive: true, force: true });
+  }
+});

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

@@ -15,7 +15,7 @@ import { delimiter, join } from "node:path";
 import { execFileSync } from "node:child_process";
 
 import { mergeMilestoneToMain } from "../auto-worktree.ts";
-import { closeDatabase, openDatabase } from "../gsd-db.ts";
+import { closeDatabase, insertAssessment, insertMilestone, insertSlice, openDatabase } from "../gsd-db.ts";
 import { GIT_NO_PROMPT_ENV } from "../git-constants.js";
 import { _clearGsdRootCache } from "../paths.ts";
 import { _resetServiceCache } from "../worktree.ts";
@@ -145,6 +145,15 @@ test("mergeMilestoneToMain keeps the Windows DB cycle closed through squash merg
 
     withPlatform("win32", () => {
       assert.equal(openDatabase(join(repo, ".gsd", "gsd.db")), true);
+      insertMilestone({ id: "M001", title: "Windows DB cycle", status: "complete" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+      insertAssessment({
+        path: "milestones/M001/M001-VALIDATION.md",
+        milestoneId: "M001",
+        status: "pass",
+        scope: "milestone-validation",
+        fullContent: "verdict: pass",
+      });
       assert.equal(existsSync(join(repo, ".gsd", "gsd.db-shm")), true);
 
       process.env.PATH = `${bin}${delimiter}${originalPath}`;

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

@@ -6,7 +6,7 @@ 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 { openDatabase, insertMilestone, closeDatabase } from "../gsd-db.js";
+import { openDatabase, insertAssessment, insertMilestone, insertSlice, closeDatabase } from "../gsd-db.js";
 import {
   isMilestoneCloseoutSettled,
   evaluateCompleteMilestoneDispatch,
@@ -39,6 +39,14 @@ test("isMilestoneCloseoutSettled requires DB closed and summary artifact", async
   mkdirSync(join(base, ".gsd"), { recursive: true });
   openDatabase(join(base, ".gsd", "gsd.db"));
   insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
   const milestoneDir = join(base, ".gsd", "milestones", "M001");
   mkdirSync(milestoneDir, { recursive: true });
   writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\n");

package/src/resources/extensions/gsd/tests/new-milestone-discuss-routing.test.ts

@@ -13,10 +13,10 @@ test("dispatchNewMilestoneDiscuss uses discuss.md only on greenfield projects",
 
   assert.match(fnBody, /findMilestoneIds\(basePath\)\.length === 0/);
   assert.match(fnBody, /prepareAndBuildDiscussPrompt/);
-  assert.match(fnBody, /loadPrompt\("guided-discuss-milestone"/);
+  assert.match(fnBody, /buildDiscussMilestonePrompt/);
   assert.match(
     fnBody,
-    /if \(isGreenfield\)[\s\S]*prepareAndBuildDiscussPrompt[\s\S]*loadPrompt\("guided-discuss-milestone"/,
+    /if \(isGreenfield\)[\s\S]*prepareAndBuildDiscussPrompt[\s\S]*buildDiscussMilestonePrompt/,
     "greenfield branch must precede guided-discuss-milestone branch",
   );
 });
@@ -24,7 +24,7 @@ test("dispatchNewMilestoneDiscuss uses discuss.md only on greenfield projects",
 test("dispatchNewMilestoneDiscuss uses milestone-specific preparation guidance", () => {
   const source = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
   const fnBody = extractSourceRegion(source, "async function dispatchNewMilestoneDiscuss(");
-  assert.match(fnBody, /buildDiscussPreparationContext\(ctx, basePath, "milestone"\)/);
+  assert.match(fnBody, /buildDiscussPreparationContext\(ctx, basePath, "milestone", true\)/);
 });
 
 test("launchNextMilestoneDiscuss routes through dispatchNewMilestoneDiscuss for normal path", () => {

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -83,6 +83,15 @@ test("plan-slice prompt: compact planning gates survive template substitution",
   assert.ok(!result.includes("{{"));
 });
 
+test("plan-slice prompt: absence checks use negated quiet searches", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
+  assert.ok(result.includes("For absence checks"));
+  assert.ok(result.includes("`! grep -q 'pattern' file`"));
+  assert.ok(result.includes("`! rg -q 'pattern' file`"));
+  assert.ok(result.includes("do not use `grep -c` or `rg -c`"));
+  assert.ok(result.includes("count commands exit 1 when they find zero matches"));
+});
+
 test("plan-slice prompt: footer references gsd_plan_slice tool, not direct write", () => {
   const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
   assert.ok(

package/src/resources/extensions/gsd/tests/post-unit-hooks.test.ts

@@ -11,6 +11,7 @@ import {
   resetHookState,
   isRetryPending,
   consumeRetryTrigger,
+  consumeGateBlock,
   resolveHookArtifactPath,
   runPreDispatchHooks,
   persistHookState,
@@ -20,6 +21,7 @@ import {
   formatHookStatus,
   triggerHookManually,
 } from "../post-unit-hooks.ts";
+import { invalidateAllCaches } from "../cache.ts";
 
 // ─── Fixture Helpers ───────────────────────────────────────────────────────
 
@@ -29,6 +31,11 @@ function createFixtureBase(): string {
   return base;
 }
 
+function writeHookPreferences(base: string, hookYaml: string): void {
+  writeFileSync(join(base, ".gsd", "PREFERENCES.md"), `---\npost_unit_hooks:\n${hookYaml}\n---\n`, "utf-8");
+  invalidateAllCaches();
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Phase 1: Post-Unit Hook Tests
 // ═══════════════════════════════════════════════════════════════════════════
@@ -104,6 +111,156 @@ test('consumeRetryTrigger clears state', () => {
   assert.ok(!isRetryPending(), "no retry initially");
 });
 
+test('Advisory hook keeps artifact idempotency without verdict frontmatter', () => {
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    writeHookPreferences(base, `  - name: docs-hint
+    after:
+      - execute-task
+    prompt: Review docs
+    artifact: DOCS-HINT.md
+`);
+    writeFileSync(resolveHookArtifactPath(base, "M001/S01/T01", "DOCS-HINT.md"), "plain advisory note", "utf-8");
+
+    const result = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.deepStrictEqual(result, null, "existing advisory artifact remains idempotent");
+    assert.deepStrictEqual(consumeGateBlock(), null, "advisory hook does not create gate block");
+  } finally {
+    resetHookState();
+    invalidateAllCaches();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('Blocking hook skips only after passing frontmatter verdict', () => {
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    writeHookPreferences(base, `  - name: security-review
+    after:
+      - execute-task
+    prompt: Review security
+    artifact: SECURITY-REVIEW.md
+    criticality: blocking
+`);
+    writeFileSync(
+      resolveHookArtifactPath(base, "M001/S01/T01", "SECURITY-REVIEW.md"),
+      "---\nverdict: pass\n---\n\nNo blocking findings.\n",
+      "utf-8",
+    );
+
+    const result = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.deepStrictEqual(result, null, "passing gate artifact is idempotent");
+    assert.deepStrictEqual(consumeGateBlock(), null, "passing gate does not block");
+  } finally {
+    resetHookState();
+    invalidateAllCaches();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('Blocking hook reruns invalid artifact once then blocks at cycle budget', () => {
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    writeHookPreferences(base, `  - name: security-review
+    after:
+      - execute-task
+    prompt: Review security
+    artifact: SECURITY-REVIEW.md
+    criticality: blocking
+`);
+    writeFileSync(resolveHookArtifactPath(base, "M001/S01/T01", "SECURITY-REVIEW.md"), "partial output", "utf-8");
+
+    const dispatch = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.ok(dispatch, "invalid gate artifact dispatches the blocking hook");
+    assert.equal(dispatch.unitType, "hook/security-review");
+
+    const afterHook = checkPostUnitHooks("hook/security-review", "M001/S01/T01", base);
+    assert.deepStrictEqual(afterHook, null, "no further hook dispatch after max_cycles=1");
+    const block = consumeGateBlock();
+    assert.ok(block, "gate block is recorded");
+    assert.equal(block.hookName, "security-review");
+    assert.match(block.reason, /missing frontmatter verdict/);
+  } finally {
+    resetHookState();
+    invalidateAllCaches();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('Blocking hook restored from disk does not trust artifact without clean hook completion', () => {
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    writeHookPreferences(base, `  - name: security-review
+    after:
+      - execute-task
+    prompt: Review security
+    artifact: SECURITY-REVIEW.md
+    criticality: blocking
+    max_cycles: 2
+`);
+    const firstDispatch = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.ok(firstDispatch, "gate dispatches first cycle");
+    persistHookState(base);
+
+    writeFileSync(
+      resolveHookArtifactPath(base, "M001/S01/T01", "SECURITY-REVIEW.md"),
+      "---\noutcome:\n  verdict: pass\n---\n",
+      "utf-8",
+    );
+
+    resetHookState();
+    restoreHookState(base);
+
+    const resumed = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.ok(resumed, "persisted active gate reruns when clean hook completion was not observed");
+    assert.equal(resumed.unitType, "hook/security-review");
+  } finally {
+    resetHookState();
+    invalidateAllCaches();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('Blocking hook needs-rework verdict requests trigger unit retry', () => {
+  resetHookState();
+  const base = createFixtureBase();
+  try {
+    writeHookPreferences(base, `  - name: review-arbiter
+    after:
+      - execute-task
+    prompt: Review task
+    artifact: REVIEW-DEBATE.md
+    criticality: blocking
+    max_cycles: 2
+    on_block:
+      action: retry-unit
+`);
+    const dispatch = checkPostUnitHooks("execute-task", "M001/S01/T01", base);
+    assert.ok(dispatch, "gate dispatches");
+    writeFileSync(
+      resolveHookArtifactPath(base, "M001/S01/T01", "REVIEW-DEBATE.md"),
+      "---\nverdict: needs-rework\n---\n\nRework required.\n",
+      "utf-8",
+    );
+
+    const afterHook = checkPostUnitHooks("hook/review-arbiter", "M001/S01/T01", base);
+    assert.deepStrictEqual(afterHook, null, "needs-rework routes via retry signal");
+    assert.ok(isRetryPending(), "retry is pending");
+    assert.deepStrictEqual(consumeRetryTrigger(), {
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+  } finally {
+    resetHookState();
+    invalidateAllCaches();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 // ─── Variable substitution in prompts ──────────────────────────────────────
 test('Variable substitution', () => {
   const base = "/project";