gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/src/resources/extensions/gsd/tests/component-types.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Component Types — Unit Tests
+ *
+ * Tests for validation utilities and helper functions in component-types.ts.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+	validateComponentName,
+	validateComponentDescription,
+	computeComponentId,
+	MAX_NAME_LENGTH,
+	MAX_DESCRIPTION_LENGTH,
+} from '../component-types.js';
+
+// ============================================================================
+// validateComponentName
+// ============================================================================
+
+describe('validateComponentName', () => {
+	it('accepts valid names', () => {
+		assert.deepStrictEqual(validateComponentName('my-skill'), []);
+		assert.deepStrictEqual(validateComponentName('scout'), []);
+		assert.deepStrictEqual(validateComponentName('db-migrator-postgres'), []);
+		assert.deepStrictEqual(validateComponentName('a1'), []);
+		assert.deepStrictEqual(validateComponentName('tool-123'), []);
+	});
+
+	it('rejects empty names', () => {
+		const errors = validateComponentName('');
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('required'));
+	});
+
+	it('rejects names with uppercase', () => {
+		const errors = validateComponentName('MySkill');
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('lowercase'));
+	});
+
+	it('rejects names starting with hyphen', () => {
+		const errors = validateComponentName('-scout');
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('hyphen'));
+	});
+
+	it('rejects names ending with hyphen', () => {
+		const errors = validateComponentName('scout-');
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('hyphen'));
+	});
+
+	it('rejects names with consecutive hyphens', () => {
+		const errors = validateComponentName('my--skill');
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('consecutive'));
+	});
+
+	it('rejects names with invalid characters', () => {
+		const errors = validateComponentName('my_skill');
+		assert.ok(errors.length > 0);
+	});
+
+	it('rejects names exceeding max length', () => {
+		const longName = 'a'.repeat(MAX_NAME_LENGTH + 1);
+		const errors = validateComponentName(longName);
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('exceeds'));
+	});
+
+	it('accepts names at exactly max length', () => {
+		const exactName = 'a'.repeat(MAX_NAME_LENGTH);
+		assert.deepStrictEqual(validateComponentName(exactName), []);
+	});
+});
+
+// ============================================================================
+// validateComponentDescription
+// ============================================================================
+
+describe('validateComponentDescription', () => {
+	it('accepts valid descriptions', () => {
+		assert.deepStrictEqual(validateComponentDescription('A useful skill'), []);
+	});
+
+	it('rejects empty descriptions', () => {
+		const errors = validateComponentDescription('');
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('required'));
+	});
+
+	it('rejects undefined descriptions', () => {
+		const errors = validateComponentDescription(undefined);
+		assert.ok(errors.length > 0);
+	});
+
+	it('rejects whitespace-only descriptions', () => {
+		const errors = validateComponentDescription('   ');
+		assert.ok(errors.length > 0);
+	});
+
+	it('rejects descriptions exceeding max length', () => {
+		const longDesc = 'x'.repeat(MAX_DESCRIPTION_LENGTH + 1);
+		const errors = validateComponentDescription(longDesc);
+		assert.ok(errors.length > 0);
+		assert.ok(errors[0].includes('exceeds'));
+	});
+});
+
+// ============================================================================
+// computeComponentId
+// ============================================================================
+
+describe('computeComponentId', () => {
+	it('returns bare name when no namespace', () => {
+		assert.strictEqual(computeComponentId('scout'), 'scout');
+	});
+
+	it('returns namespace:name when namespace provided', () => {
+		assert.strictEqual(computeComponentId('code-review', 'my-plugin'), 'my-plugin:code-review');
+	});
+
+	it('handles undefined namespace same as no namespace', () => {
+		assert.strictEqual(computeComponentId('scout', undefined), 'scout');
+	});
+});

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

@@ -627,4 +627,83 @@ Integration tests mock external services.
 
     assert.strictEqual(result, '', 'empty content returns empty string');
   });
+
+  // ── Regression: issue #4719 — single-H2 with many H3 entries ──────────────
+  // A KNOWLEDGE.md structured as one top-level H2 with many H3 entries must
+  // filter at H3 granularity; otherwise one keyword match against the H2
+  // header or first paragraph returns the entire file.
+  test("single H2 with many H3 entries filters at H3 level (issue #4719)", async () => {
+    const singleH2Knowledge = `# Project Knowledge
+
+## Patterns
+
+### Database: prepared statements
+Always use prepared statements with SQLite.
+
+### API: versioned paths
+Use /v1/resource style versioning.
+
+### Testing: node:test
+Prefer node:test over external frameworks.
+
+### Deployment: blue-green
+Blue-green deployment for zero-downtime releases.
+`;
+
+    const result = await queryKnowledge(singleH2Knowledge, ['database']);
+
+    // Should include only the matching H3 entry, not the whole file
+    assert.match(result, /Database: prepared statements/, 'includes matching H3 entry');
+    assert.ok(
+      !result.includes('API: versioned paths'),
+      'does not include non-matching H3 entry',
+    );
+    assert.ok(
+      !result.includes('Testing: node:test'),
+      'does not include non-matching H3 entry',
+    );
+    assert.ok(
+      !result.includes('Deployment: blue-green'),
+      'does not include non-matching H3 entry',
+    );
+    // The returned payload must be dramatically smaller than the full content
+    assert.ok(
+      result.length < singleH2Knowledge.length / 2,
+      `scoped result (${result.length} chars) should be <50% of full content (${singleH2Knowledge.length} chars)`,
+    );
+  });
+
+  test("single H2 with H3 entries returns empty when no H3 matches (issue #4719)", async () => {
+    const singleH2Knowledge = `# Project Knowledge
+
+## Patterns
+
+### Database: prepared statements
+Always use prepared statements with SQLite.
+
+### API: versioned paths
+Use /v1/resource style versioning.
+`;
+
+    const result = await queryKnowledge(singleH2Knowledge, ['nonexistent']);
+
+    assert.strictEqual(result, '', 'no H3 match returns empty string');
+  });
+
+  test("falls back to H2 when no H3 headings exist at all", async () => {
+    // Backwards-compat: files with only H2 topic headers must still filter.
+    const h2OnlyKnowledge = `# Project Knowledge
+
+## Database Patterns
+Use prepared statements.
+
+## API Design
+REST with OpenAPI.
+`;
+
+    const result = await queryKnowledge(h2OnlyKnowledge, ['database']);
+
+    assert.match(result, /Database Patterns/, 'H2-only file falls back to H2 filtering');
+    assert.ok(!result.includes('API Design'), 'non-matching H2 section excluded');
+  });
 });

package/src/resources/extensions/gsd/tests/copy-planning-artifacts-samepath.test.ts

@@ -2,6 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 test("copyPlanningArtifacts skips when source and destination .gsd resolve to the same path", () => {
   const srcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
@@ -10,7 +11,7 @@ test("copyPlanningArtifacts skips when source and destination .gsd resolve to th
   const fnIdx = src.indexOf("function copyPlanningArtifacts");
   assert.ok(fnIdx !== -1, "copyPlanningArtifacts function exists");
 
-  const fnBody = src.slice(fnIdx, fnIdx + 2400);
+  const fnBody = extractSourceRegion(src, "function copyPlanningArtifacts");
 
   const guardIdx = fnBody.indexOf("if (isSamePath(srcGsd, dstGsd)) return;");
   const copyIdx = fnBody.indexOf("safeCopyRecursive(join(srcGsd, \"milestones\")");

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -179,6 +179,8 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
     reconcileMergeState: () => "clean",
+    preflightCleanRoot: () => ({ stashPushed: false, summary: "" }),
+    postflightPopStash: () => {},
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,
@@ -479,6 +481,165 @@ describe("Custom engine loop integration", () => {
     );
   });
 
+  it("stops custom workflow after repeated verification retries", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([makeStep({ id: "retry-step" })], "retry-exhaustion");
+    writeGraph(runDir, graph);
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify({
+      version: 1,
+      name: "retry-exhaustion",
+      steps: [{
+        id: "retry-step",
+        name: "retry-step",
+        prompt: "Do retry-step",
+        produces: "retry-step/output.md",
+        verify: { policy: "shell-command", command: "exit 1" },
+      }],
+    }));
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s.active = false;
+      },
+    });
+
+    const resolver = setInterval(() => {
+      resolveAgentEnd({ messages: [{ role: "assistant" }] });
+    }, 25);
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        autoLoop(ctx, pi, s, deps),
+        new Promise((_, reject) =>
+          timeout = setTimeout(() => {
+            s.active = false;
+            resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            reject(new Error(
+              `autoLoop did not stop after verification retry exhaustion; calls=${pi.calls.length}; log=${deps.callLog.join(",")}`,
+            ));
+          }, 3_000),
+        ),
+      ]);
+    } finally {
+      clearInterval(resolver);
+      if (timeout) clearTimeout(timeout);
+    }
+
+    assert.equal(pi.calls.length, 4, "verification retry should be capped after four dispatched attempts");
+    const stopEntry = deps.callLog.find((e: string) => e.startsWith("stopAuto:"));
+    assert.match(stopEntry ?? "", /requested retry 4 times without passing/);
+    const finalGraph = readGraph(runDir);
+    assert.equal(finalGraph.steps[0]?.status, "active", "failed verification must not reconcile the step complete");
+  });
+
+  it("persists custom verification retry budget across a session restart", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([makeStep({ id: "retry-step" })], "retry-restart");
+    writeGraph(runDir, graph);
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify({
+      version: 1,
+      name: "retry-restart",
+      steps: [{
+        id: "retry-step",
+        name: "retry-step",
+        prompt: "Do retry-step",
+        produces: "retry-step/output.md",
+        verify: { policy: "shell-command", command: "exit 1" },
+      }],
+    }));
+
+    const ctx1 = makeMockCtx();
+    const pi1 = makeMockPi();
+    const s1 = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const deps1 = makeMockDeps();
+    const resolver1 = setInterval(() => {
+      resolveAgentEnd({ messages: [{ role: "assistant" }] });
+      if (pi1.calls.length >= 2) {
+        s1.active = false;
+      }
+    }, 25);
+    let timeout1: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        autoLoop(ctx1, pi1, s1, deps1),
+        new Promise((_, reject) =>
+          timeout1 = setTimeout(() => {
+            s1.active = false;
+            resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            reject(new Error(
+              `first autoLoop did not pause after two retry attempts; calls=${pi1.calls.length}; log=${deps1.callLog.join(",")}`,
+            ));
+          }, 3_000),
+        ),
+      ]);
+    } finally {
+      clearInterval(resolver1);
+      if (timeout1) clearTimeout(timeout1);
+    }
+    assert.equal(pi1.calls.length, 2, "first session should consume two retry attempts");
+    assert.equal(
+      deps1.callLog.some((e: string) => e.startsWith("stopAuto:")),
+      false,
+      "first session should stop because the session deactivated, not because retry budget exhausted",
+    );
+
+    _resetPendingResolve();
+    const ctx2 = makeMockCtx();
+    const pi2 = makeMockPi();
+    const s2 = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+    });
+    const deps2 = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps2.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s2.active = false;
+      },
+    });
+    const resolver2 = setInterval(() => {
+      resolveAgentEnd({ messages: [{ role: "assistant" }] });
+    }, 25);
+    let timeout2: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        autoLoop(ctx2, pi2, s2, deps2),
+        new Promise((_, reject) =>
+          timeout2 = setTimeout(() => {
+            s2.active = false;
+            resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            reject(new Error(
+              `second autoLoop did not stop after persisted retry exhaustion; calls=${pi2.calls.length}; log=${deps2.callLog.join(",")}`,
+            ));
+          }, 3_000),
+        ),
+      ]);
+    } finally {
+      clearInterval(resolver2);
+      if (timeout2) clearTimeout(timeout2);
+    }
+
+    assert.equal(pi2.calls.length, 2, "second session should exhaust after attempts 3 and 4");
+    const stopEntry = deps2.callLog.find((e: string) => e.startsWith("stopAuto:"));
+    assert.match(stopEntry ?? "", /requested retry 4 times without passing/);
+  });
+
   it("GRAPH.yaml step stays pending when session deactivates before reconcile", async () => {
     _resetPendingResolve();
 

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

@@ -50,6 +50,7 @@ test("doctor-heal.md contains DB access guardrail naming gsd_milestone_status",
   const prompt = readPrompt("doctor-heal");
   assert.match(prompt, /gsd_milestone_status/, "doctor-heal.md must name gsd_milestone_status as the DB inspection tool");
   assert.match(prompt, /Do NOT query.*\.gsd\/gsd\.db/i, "doctor-heal.md must prohibit direct DB queries");
+  assert.doesNotMatch(prompt, /\{\{milestoneId\}\}/, "doctor-heal.md must not declare unprovided milestoneId template variables");
 });
 
 test("forensics.md contains DB inspection guardrail", () => {

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

@@ -694,6 +694,48 @@ describe('derive-state-db', async () => {
     }
   });
 
+  // ─── Test 14b: needs-remediation + all slices done → blocked (#4506) ──
+  test('derive-state-db: needs-remediation with all slices done returns blocked (#4506)', async () => {
+    const base = createFixtureBase();
+    try {
+      const doneRoadmap = `# M001: Stuck Remediation
+
+**Vision:** Test needs-remediation loop guard.
+
+## Slices
+
+- [x] **S01: Done Slice** \`risk:low\` \`depends:[]\`
+  > After this: Done.
+`;
+      writeFile(base, 'milestones/M001/M001-ROADMAP.md', doneRoadmap);
+      writeFile(base, 'milestones/M001/M001-VALIDATION.md',
+        '---\nverdict: needs-remediation\nremediation_round: 1\n---\n\n# Validation\nNeeds fixes.');
+
+      invalidateStateCache();
+      const fileState = await _deriveStateImpl(base);
+
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'Stuck Remediation', status: 'active' });
+      insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Done Slice', status: 'complete', risk: 'low', depends: [] });
+
+      invalidateStateCache();
+      const dbState = await deriveStateFromDb(base);
+
+      assert.deepStrictEqual(dbState.phase, 'blocked', 'remediation-stuck-db: phase is blocked');
+      assert.deepStrictEqual(dbState.phase, fileState.phase, 'remediation-stuck-db: phase matches filesystem');
+      assert.deepStrictEqual(dbState.activeMilestone?.id, 'M001', 'remediation-stuck-db: activeMilestone is M001');
+      assert.ok(
+        dbState.blockers.some(b => b.includes('needs-remediation') && b.includes('M001')),
+        'remediation-stuck-db: blocker message mentions milestone and verdict',
+      );
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
   // ─── Test 15: Completing-milestone — terminal validation, no summary ──
   test('derive-state-db: completing-milestone via DB', async () => {
     const base = createFixtureBase();

package/src/resources/extensions/gsd/tests/derive-state-helpers.test.ts

@@ -446,8 +446,8 @@ describe('derive-state-helpers', () => {
     }
   });
 
-  // ─── handleAllSlicesDone: needs-remediation re-triggers validation ──
-  test('handleAllSlicesDone: needs-remediation verdict triggers validating-milestone', async () => {
+  // ─── handleAllSlicesDone: needs-remediation + all slices done → blocked (#4506) ──
+  test('handleAllSlicesDone: needs-remediation with all slices done returns blocked', async () => {
     const base = createFixtureBase();
     try {
       const doneRoadmap = `# M001: Remediation Test\n\n**Vision:** Test.\n\n## Slices\n\n- [x] **S01: Done** \`risk:low\` \`depends:[]\`\n  > Done.\n`;
@@ -462,8 +462,12 @@ describe('derive-state-helpers', () => {
       invalidateStateCache();
       const state = await deriveStateFromDb(base);
 
-      assert.equal(state.phase, 'validating-milestone', 'remediation: phase is validating-milestone');
-      assert.equal(state.activeMilestone?.id, 'M001', 'remediation: activeMilestone is M001');
+      assert.equal(state.phase, 'blocked', 'remediation-stuck: phase is blocked (no infinite re-dispatch)');
+      assert.equal(state.activeMilestone?.id, 'M001', 'remediation-stuck: activeMilestone is M001');
+      assert.ok(
+        state.blockers.some(b => b.includes('needs-remediation') && b.includes('M001')),
+        'remediation-stuck: blocker message mentions milestone and verdict',
+      );
     } finally {
       closeDatabase();
       cleanup(base);

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

@@ -431,7 +431,7 @@ Continue from step 2.
       cleanup(base1);
     }
 
-    // Case B: S01 depends on nonexistent S99 → truly blocked
+    // Case B: S01 depends on nonexistent S99 -> fallback picks best available slice
     const base2 = createFixtureBase();
     try {
       writeRoadmap(base2, 'M001', `# M001: Test Milestone
@@ -446,7 +446,6 @@ Continue from step 2.
 
       const state2 = await deriveState(base2);
 
-      // With partial-dep fallback, S01 is picked despite unmet dep on S99
       assert.deepStrictEqual(state2.phase, 'planning', 'blocked-B: phase is planning (fallback picks S01)');
       assert.deepStrictEqual(state2.activeSlice?.id, 'S01', 'blocked-B: activeSlice is S01 via fallback');
     } finally {

package/src/resources/extensions/gsd/tests/discuss-slice-structured-questions.test.ts

@@ -11,6 +11,7 @@ import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const template = readFileSync(
   resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'prompts', 'guided-discuss-slice.md'),
@@ -37,7 +38,7 @@ describe('discuss-slice structuredQuestionsAvailable template variable', () => {
     const falseIdx = template.indexOf('`{{structuredQuestionsAvailable}}` is `false`')
     assert.ok(falseIdx !== -1)
 
-    const afterFalse = template.slice(falseIdx, falseIdx + 300)
+    const afterFalse = extractSourceRegion(template, '`{{structuredQuestionsAvailable}}` is `false`')
     assert.ok(
       afterFalse.includes('plain text'),
       'when structuredQuestionsAvailable is false, questions should be in plain text',

package/src/resources/extensions/gsd/tests/discuss-tool-scope-leak.test.ts

@@ -22,6 +22,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const guidedFlowSource = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
@@ -58,7 +59,7 @@ describe("#3616 — discuss tool scoping must not leak across sessions", () => {
 		);
 		const newSessionStart = agentSessionSource.indexOf("async newSession(options?:");
 		assert.ok(newSessionStart >= 0, "should find newSession");
-		const body = agentSessionSource.slice(newSessionStart, newSessionStart + 3000);
+		const body = extractSourceRegion(agentSessionSource, "async newSession(options?:");
 
 		// Both branches (cwd-changed and cwd-unchanged) must include extension tools
 		assert.ok(

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

@@ -47,21 +47,26 @@ describe("completing-milestone dispatch guard (#4324)", () => {
     assert.ok(dispatchIdx > -1, "complete-milestone dispatch should exist after the skip guard");
   });
 
-  test("imports updateMilestoneStatus for DB reconciliation", () => {
-    assert.match(source, /import\s*\{[^}]*updateMilestoneStatus[^}]*\}\s*from\s*["']\.\/gsd-db/);
-  });
-
-  test("reconciles DB when SUMMARY exists on disk but DB is out of sync", () => {
+  test("classifies SUMMARY outcome and conditionally reconciles DB (#4658)", () => {
     const phaseCheck = source.indexOf('phase !== "completing-milestone"');
     // The SUMMARY-exists reconciliation guard must appear in this rule
     const summaryGuard = source.indexOf('resolveMilestoneFile(basePath, mid, "SUMMARY")', phaseCheck);
     assert.ok(summaryGuard > -1, "SUMMARY file check should exist in the completing-milestone rule");
 
+    const classifyCall = source.indexOf("classifyMilestoneSummaryContent", summaryGuard);
+    assert.ok(classifyCall > -1, "SUMMARY mismatch handling should classify summary content");
+    const dbGateBeforeClassify = source.indexOf("existingSummary && isDbAvailable()", summaryGuard);
+    assert.ok(
+      dbGateBeforeClassify === -1 || dbGateBeforeClassify > classifyCall,
+      "SUMMARY classification must not be gated on DB availability",
+    );
+
     const reconcileCall = source.indexOf('updateMilestoneStatus(mid, "complete"', summaryGuard);
-    assert.ok(reconcileCall > -1, "updateMilestoneStatus reconciliation should follow the SUMMARY check");
+    assert.ok(reconcileCall > -1, "successful SUMMARY should reconcile DB to complete");
 
-    // Reconciliation must happen before the dispatch action
-    const dispatchIdx = source.indexOf('unitType: "complete-milestone"', reconcileCall);
-    assert.ok(dispatchIdx > -1, "reconciliation should appear before the dispatch action");
+    const stopAction = source.indexOf('action: "stop"', summaryGuard);
+    assert.ok(stopAction > -1, "SUMMARY mismatch should return stop action");
+    const warningLevel = source.indexOf('level: "warning"', summaryGuard);
+    assert.ok(warningLevel > -1, "SUMMARY mismatch should be warning-level stop (pauses auto-mode)");
   });
 });

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,
+  );
+});