gsd-pi 2.62.1 → 2.63.0-dev.351157b

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -449,6 +449,45 @@ console.log('\n=== complete-task: handler with missing plan file ===');
   cleanup(dbPath);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// complete-task: minimal params — no optional fields (#2771 regression)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== complete-task: minimal params (no keyFiles, keyDecisions, verificationEvidence, blockerDiscovered) ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const { basePath, planPath } = createTempProject();
+
+  insertMilestone({ id: 'M001', title: 'Test Milestone' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice' });
+
+  // Minimal params — only required fields, all optional enrichment fields omitted
+  const minimalParams = {
+    taskId: 'T01',
+    sliceId: 'S01',
+    milestoneId: 'M001',
+    oneLiner: 'Basic task',
+    narrative: 'Did the work.',
+    verification: 'Looks good.',
+    // keyFiles, keyDecisions, verificationEvidence, blockerDiscovered intentionally omitted
+  };
+
+  const result = await handleCompleteTask(minimalParams as any, basePath);
+
+  assertTrue(!('error' in result), 'handler should not crash with minimal params (no optional fields)');
+  if (!('error' in result)) {
+    assertTrue(fs.existsSync(result.summaryPath), 'summary file should be written with minimal params');
+    const summaryContent = fs.readFileSync(result.summaryPath, 'utf-8');
+    assertMatch(summaryContent, /blocker_discovered:\s*false/, 'blocker_discovered should default to false');
+    assertMatch(summaryContent, /\(none\)/, 'key_files/key_decisions should show (none) placeholder');
+  }
+
+  cleanupDir(basePath);
+  cleanup(dbPath);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 
 report();

package/src/resources/extensions/gsd/tests/dashboard-model-label-ordering.test.ts

@@ -0,0 +1,107 @@
+/**
+ * dashboard-model-label-ordering.test.ts — Regression test for #2899.
+ *
+ * The dashboard model label was showing the previous unit's model because
+ * updateProgressWidget was called before selectAndApplyModel in phases.ts.
+ * This test verifies:
+ *   1. updateProgressWidget is called AFTER selectAndApplyModel in phases.ts
+ *   2. session.ts has a currentDispatchedModelId field
+ *   3. auto.ts exposes getCurrentDispatchedModelId in widgetStateAccessors
+ *   4. auto-dashboard.ts reads from a dispatched model accessor, not cmdCtx?.model
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, assertMatch, report } = createTestContext();
+
+const phasesPath = join(import.meta.dirname, "..", "auto", "phases.ts");
+const sessionPath = join(import.meta.dirname, "..", "auto", "session.ts");
+const autoPath = join(import.meta.dirname, "..", "auto.ts");
+const dashboardPath = join(import.meta.dirname, "..", "auto-dashboard.ts");
+
+const phasesSrc = readFileSync(phasesPath, "utf-8");
+const sessionSrc = readFileSync(sessionPath, "utf-8");
+const autoSrc = readFileSync(autoPath, "utf-8");
+const dashboardSrc = readFileSync(dashboardPath, "utf-8");
+
+console.log("\n=== #2899: Dashboard model label shows correct (dispatched) model ===");
+
+// ── Test 1: updateProgressWidget is called AFTER selectAndApplyModel ──────
+
+// Find the positions of the calls in the dispatch function body.
+// selectAndApplyModel must appear BEFORE updateProgressWidget.
+const selectModelPos = phasesSrc.indexOf("deps.selectAndApplyModel(");
+const updateWidgetPos = phasesSrc.indexOf("deps.updateProgressWidget(");
+
+assertTrue(
+  selectModelPos > 0,
+  "phases.ts contains deps.selectAndApplyModel call",
+);
+
+assertTrue(
+  updateWidgetPos > 0,
+  "phases.ts contains deps.updateProgressWidget call",
+);
+
+assertTrue(
+  selectModelPos < updateWidgetPos,
+  `selectAndApplyModel (pos ${selectModelPos}) must be called BEFORE updateProgressWidget (pos ${updateWidgetPos}) — widget needs fresh model`,
+);
+
+// ── Test 2: session.ts declares currentDispatchedModelId ──────────────────
+
+assertTrue(
+  sessionSrc.includes("currentDispatchedModelId"),
+  "session.ts has currentDispatchedModelId field",
+);
+
+// ── Test 3: auto.ts exposes getCurrentDispatchedModelId in widgetStateAccessors ──
+
+assertTrue(
+  autoSrc.includes("getCurrentDispatchedModelId"),
+  "auto.ts exposes getCurrentDispatchedModelId accessor",
+);
+
+// Verify it's in the widgetStateAccessors object
+const accessorsBlock = autoSrc.slice(
+  autoSrc.indexOf("const widgetStateAccessors"),
+  autoSrc.indexOf("};", autoSrc.indexOf("const widgetStateAccessors")) + 2,
+);
+
+assertTrue(
+  accessorsBlock.includes("getCurrentDispatchedModelId"),
+  "getCurrentDispatchedModelId is in the widgetStateAccessors object",
+);
+
+// ── Test 4: WidgetStateAccessors interface has getCurrentDispatchedModelId ──
+
+assertTrue(
+  dashboardSrc.includes("getCurrentDispatchedModelId"),
+  "auto-dashboard.ts references getCurrentDispatchedModelId",
+);
+
+// The dashboard render closure should NOT read model from cmdCtx?.model for display.
+// It should use the accessor for the dispatched model ID.
+// Check that the "Model display" section uses the accessor, not cmdCtx?.model directly.
+const modelDisplaySection = dashboardSrc.slice(
+  dashboardSrc.indexOf("// Model display"),
+  dashboardSrc.indexOf("// Model display") + 500,
+);
+
+assertTrue(
+  modelDisplaySection.includes("getCurrentDispatchedModelId") ||
+  modelDisplaySection.includes("getDispatchedModelId"),
+  "Model display section reads from dispatched model accessor, not cmdCtx?.model alone",
+);
+
+// ── Test 5: currentDispatchedModelId is set after selectAndApplyModel in phases.ts ──
+
+// After selectAndApplyModel returns, phases.ts should store the dispatched model ID
+assertTrue(
+  phasesSrc.includes("currentDispatchedModelId"),
+  "phases.ts stores currentDispatchedModelId after model selection",
+);
+
+report();

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

@@ -0,0 +1,109 @@
+// GSD2 — Regression tests: DB anti-pattern guardrails in prompt templates
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const promptsDir = join(process.cwd(), "src/resources/extensions/gsd/prompts");
+
+function readPrompt(name: string): string {
+  return readFileSync(join(promptsDir, `${name}.md`), "utf-8");
+}
+
+// ─── Layer 1: system.md global guardrail ──────────────────────────────────────
+
+test("system.md anti-patterns section prohibits direct .gsd/gsd.db access", () => {
+  const prompt = readPrompt("system");
+  assert.match(
+    prompt,
+    /Never query.*\.gsd\/gsd\.db.*directly/i,
+    "system.md must prohibit direct .gsd/gsd.db access in the anti-patterns section",
+  );
+  assert.match(prompt, /sqlite3/, "system.md DB guardrail must name the sqlite3 CLI");
+  assert.match(prompt, /better-sqlite3/, "system.md DB guardrail must name better-sqlite3");
+  assert.match(prompt, /gsd_\*/, "system.md DB guardrail must redirect to gsd_* tools");
+});
+
+test("system.md DB guardrail explains single-writer WAL risk", () => {
+  const prompt = readPrompt("system");
+  assert.match(prompt, /single-writer WAL/i, "system.md must explain the WAL architecture risk");
+});
+
+// ─── Layer 2: high-risk prompt guardrails ─────────────────────────────────────
+
+test("validate-milestone.md contains DB access safety guardrail with tool redirect", () => {
+  const prompt = readPrompt("validate-milestone");
+  assert.match(prompt, /DB access safety/i, "validate-milestone.md must have DB access safety section");
+  assert.match(prompt, /gsd_milestone_status/, "validate-milestone.md must name gsd_milestone_status as alternative");
+  assert.match(prompt, /Do NOT query.*\.gsd\/gsd\.db/i, "validate-milestone.md must prohibit direct DB queries");
+});
+
+test("complete-milestone.md contains DB access safety guardrail with tool redirect", () => {
+  const prompt = readPrompt("complete-milestone");
+  assert.match(prompt, /DB access safety/i, "complete-milestone.md must have DB access safety section");
+  assert.match(prompt, /gsd_milestone_status/, "complete-milestone.md must name gsd_milestone_status as alternative");
+  assert.match(prompt, /Do NOT query.*\.gsd\/gsd\.db/i, "complete-milestone.md must prohibit direct DB queries");
+});
+
+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");
+});
+
+test("forensics.md contains DB inspection guardrail", () => {
+  const prompt = readPrompt("forensics");
+  assert.match(prompt, /gsd_milestone_status/, "forensics.md must name gsd_milestone_status as the DB inspection tool");
+  assert.match(prompt, /sqlite3.*\.gsd\/gsd\.db/i, "forensics.md must prohibit sqlite3 against .gsd/gsd.db");
+});
+
+test("reassess-roadmap.md contains DB access safety guardrail", () => {
+  const prompt = readPrompt("reassess-roadmap");
+  assert.match(prompt, /DB access safety/i, "reassess-roadmap.md must have DB access safety section");
+  assert.match(prompt, /gsd_milestone_status/, "reassess-roadmap.md must name gsd_milestone_status as alternative");
+});
+
+// ─── Negative assertion: no prompt instructs running sqlite3 as a command ─────
+
+test("no prompt file contains an unguarded sqlite3 command invocation", () => {
+  const files = readdirSync(promptsDir).filter((f) => f.endsWith(".md"));
+  assert.ok(files.length >= 35, `Expected at least 35 prompt files, found ${files.length}`);
+
+  const violations: string[] = [];
+
+  for (const file of files) {
+    const content = readFileSync(join(promptsDir, file), "utf-8");
+    const lines = content.split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      // Match lines containing sqlite3 targeting gsd.db in any common form:
+      //   sqlite3 .gsd/gsd.db, sqlite3 ./.gsd/gsd.db, sqlite3 "/path/.gsd/gsd.db",
+      //   sqlite3 -header .gsd/gsd.db, etc.
+      // Guardrail text that says "Never run" or "Do NOT query" is fine — only flag
+      // lines where these appear without a surrounding prohibition keyword.
+      if (/sqlite3\b.*gsd\.db/.test(trimmed)) {
+        const context = lines.slice(Math.max(0, i - 3), i + 1).join(" ");
+        if (!/Never|Do NOT|do not|don't|prohibited|forbidden|never run/i.test(context)) {
+          violations.push(`${file}:${i + 1} — unguarded sqlite3 command: ${trimmed}`);
+        }
+      }
+      // Match node -e with better-sqlite3 require in any quoting style
+      if (/node\s+-e\s+.*(?:require|import).*better-sqlite3/.test(trimmed)) {
+        const context = lines.slice(Math.max(0, i - 3), i + 1).join(" ");
+        if (!/Never|Do NOT|do not|don't|prohibited|forbidden|never run/i.test(context)) {
+          violations.push(`${file}:${i + 1} — unguarded node -e require command: ${trimmed}`);
+        }
+      }
+    }
+  }
+
+  assert.deepEqual(
+    violations,
+    [],
+    `Found prompts with unguarded sqlite3/better-sqlite3 invocations:\n${violations.join("\n")}`,
+  );
+});

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

@@ -38,13 +38,17 @@ assertEq(
   "Standard worktree layout resolves to project root DB path",
 );
 
-// Symlink-resolved layout (the regression — /.gsd/projects/<hash>/worktrees/...)
+// Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/...
+// After PR #2952, these paths resolve to the hash-level DB (same as external-state),
+// because on POSIX getcwd() returns the canonical (symlink-resolved) path anyway, so
+// a path like <proj>/.gsd/projects/<hash>/worktrees/ in practice is always
+// ~/.gsd/projects/<hash>/worktrees/ after the OS resolves the .gsd symlink.
 const symlinkPath = `/home/user/myproject/.gsd/projects/abc123def/worktrees/M001/work`;
 const symlinkResult = resolveProjectRootDbPath(symlinkPath);
 assertEq(
   symlinkResult,
-  join("/home/user/myproject", ".gsd", "gsd.db"),
-  "Symlink-resolved layout (/.gsd/projects/<hash>/worktrees/) resolves to project root DB path (#2517)",
+  join("/home/user/myproject/.gsd/projects/abc123def", "gsd.db"),
+  "/.gsd/projects/<hash>/worktrees/ resolves to hash-level DB (#2517, updated for #2952)",
 );
 
 // Windows-style separators for symlink layout
@@ -53,8 +57,8 @@ if (sep === "\\") {
   const winResult = resolveProjectRootDbPath(winSymlinkPath);
   assertEq(
     winResult,
-    join("C:\\Users\\dev\\project", ".gsd", "gsd.db"),
-    "Windows symlink layout resolves correctly",
+    join("C:\\Users\\dev\\project\\.gsd\\projects\\abc123def", "gsd.db"),
+    "Windows /.gsd/projects/<hash>/worktrees/ resolves to hash-level DB",
   );
 } else {
   // On non-Windows, test forward-slash variant explicitly
@@ -62,8 +66,8 @@ if (sep === "\\") {
   const fwdResult = resolveProjectRootDbPath(fwdSymlinkPath);
   assertEq(
     fwdResult,
-    join("/home/user/myproject", ".gsd", "gsd.db"),
-    "Forward-slash symlink layout resolves correctly on POSIX",
+    join("/home/user/myproject/.gsd/projects/abc123def", "gsd.db"),
+    "Forward-slash /.gsd/projects/<hash>/worktrees/ resolves to hash-level DB on POSIX",
   );
 }
 
@@ -72,8 +76,8 @@ const deepSymlinkPath = `/home/user/myproject/.gsd/projects/deadbeef42/worktrees
 const deepResult = resolveProjectRootDbPath(deepSymlinkPath);
 assertEq(
   deepResult,
-  join("/home/user/myproject", ".gsd", "gsd.db"),
-  "Deep symlink worktree path still resolves to project root DB",
+  join("/home/user/myproject/.gsd/projects/deadbeef42", "gsd.db"),
+  "Deep /.gsd/projects/<hash>/worktrees/ path resolves to hash-level DB (#2952)",
 );
 
 // Non-worktree path should be unchanged

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

@@ -24,6 +24,7 @@ import {
   saveDecisionToDb,
   updateRequirementInDb,
   saveArtifactToDb,
+  extractDeferredSliceRef,
 } from '../db-writer.ts';
 import type { Decision, Requirement } from '../types.ts';
 
@@ -475,6 +476,71 @@ describe('db-writer', () => {
     }
   });
 
+  test('updateRequirementInDb — seeds from REQUIREMENTS.md when DB empty (#3346)', async () => {
+    const tmpDir = makeTmpDir();
+    const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
+    openDatabase(dbPath);
+
+    try {
+      // Write a REQUIREMENTS.md with real content (simulating discussion phase output)
+      const reqContent = [
+        '# Requirements',
+        '',
+        '## Active',
+        '',
+        '### R005 — User authentication',
+        '- Class: functional',
+        '- Why: Users need secure access',
+        '- Source: user-research',
+        '- Primary owner: M001/S02',
+        '',
+        '### R007 — API rate limiting',
+        '- Class: non-functional',
+        '- Why: Prevent abuse',
+        '- Source: architecture',
+        '- Primary owner: M001/S03',
+        '',
+        '## Validated',
+        '',
+        '### R001 — Database schema',
+        '- Class: functional',
+        '- Why: Foundation for storage',
+        '- Source: design',
+        '- Validation: S01 verified',
+      ].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.
+      await updateRequirementInDb('R005', {
+        status: 'validated',
+        validation: 'S02 — auth flow verified',
+      }, tmpDir);
+
+      // R005 should have the update AND the original content from markdown
+      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');
+
+      // R007 and R001 should also be seeded (not just the one being updated)
+      const r007 = getRequirementById('R007');
+      assert.ok(r007, 'R007 should be seeded from REQUIREMENTS.md');
+      assert.equal(r007!.status, 'active', 'R007 status should be active');
+
+      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)');
+    } finally {
+      closeDatabase();
+      cleanupDir(tmpDir);
+    }
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
   // saveArtifactToDb Tests
   // ═══════════════════════════════════════════════════════════════════════════
@@ -694,4 +760,72 @@ describe('db-writer', () => {
 
   // ═══════════════════════════════════════════════════════════════════════════
 
+  // ═══════════════════════════════════════════════════════════════════════════
+  //  extractDeferredSliceRef
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  describe('extractDeferredSliceRef', () => {
+    const fields = (scope: string, choice: string, decision: string) => ({
+      scope,
+      choice,
+      decision,
+    });
+
+    test('detects deferral in scope with M###/S## pattern in choice', () => {
+      const result = extractDeferredSliceRef(
+        fields('deferral of low-priority work', 'Move M001/S03 to backlog', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M001', sliceId: 'S03' });
+    });
+
+    test('detects deferral in choice field', () => {
+      const result = extractDeferredSliceRef(
+        fields('slice prioritization', 'defer M002/S01 until next sprint', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M002', sliceId: 'S01' });
+    });
+
+    test('detects deferral in decision field', () => {
+      const result = extractDeferredSliceRef(
+        fields('resource constraints', '', 'deferred M010/S12 pending review'),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M010', sliceId: 'S12' });
+    });
+
+    test('returns null when no M###/S## pattern is present', () => {
+      const result = extractDeferredSliceRef(
+        fields('deferral of work', 'will revisit later', 'deferred indefinitely'),
+      );
+      assert.strictEqual(result, null);
+    });
+
+    test('recognises "deferring" variant', () => {
+      const result = extractDeferredSliceRef(
+        fields('deferring this slice', 'M005/S02 can wait', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M005', sliceId: 'S02' });
+    });
+
+    test('recognises "defers" variant', () => {
+      const result = extractDeferredSliceRef(
+        fields('team defers slice', 'M100/S10 not urgent', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M100', sliceId: 'S10' });
+    });
+
+    test('returns first M###/S## match when multiple patterns exist', () => {
+      const result = extractDeferredSliceRef(
+        fields('', 'defer M003/S01 and M003/S02', ''),
+      );
+      assert.deepStrictEqual(result, { milestoneId: 'M003', sliceId: 'S01' });
+    });
+
+    test('returns null when no deferral keyword is present', () => {
+      const result = extractDeferredSliceRef(
+        fields('approved work', 'M001/S01 is ready', 'proceed with M001/S01'),
+      );
+      assert.strictEqual(result, null);
+    });
+  });
+
 });

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

@@ -0,0 +1,203 @@
+/**
+ * Regression test for #2661: Auto-mode dispatches deferred slices.
+ *
+ * When a decision defers a slice, the dispatcher must skip it and advance
+ * to the next eligible slice. This tests both:
+ *   1. deriveStateFromDb skips slices with status "deferred"
+ *   2. saveDecisionToDb updates the slice status when the decision is a deferral
+ */
+
+import { describe, 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 { deriveStateFromDb, invalidateStateCache } from "../state.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  isDbAvailable,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  insertArtifact,
+  updateSliceStatus,
+} from "../gsd-db.ts";
+import { isDeferredStatus } from "../status-guards.ts";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-deferred-dispatch-"));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function writeFile(base: string, relativePath: string, content: string): void {
+  const full = join(base, ".gsd", relativePath);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, content);
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────
+
+describe("deferred-slice-dispatch (#2661)", () => {
+  test("isDeferredStatus returns true for 'deferred'", () => {
+    assert.ok(isDeferredStatus("deferred"), "should recognize 'deferred'");
+    assert.ok(!isDeferredStatus("active"), "should not match 'active'");
+    assert.ok(!isDeferredStatus("complete"), "should not match 'complete'");
+    assert.ok(!isDeferredStatus("pending"), "should not match 'pending'");
+  });
+
+  test("deriveStateFromDb skips deferred slice and picks next eligible", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+      assert.ok(isDbAvailable());
+
+      // M001 with three slices: S01 complete, S02 deferred, S03 pending
+      insertMilestone({ id: "M001", title: "Test Milestone", status: "active" });
+
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete", risk: "low", depends: [] });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Deferred Slice", status: "deferred", risk: "low", depends: [] });
+      insertSlice({ id: "S03", milestoneId: "M001", title: "Next Slice", status: "pending", risk: "low", depends: [] });
+
+      // S01 needs a SUMMARY file to count as complete for milestone-level checks
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001: Test Milestone
+
+**Vision:** Test deferred slices.
+
+## Slices
+
+- [x] **S01: Done Slice** \`risk:low\` \`depends:[]\`
+  > Done.
+
+- [ ] **S02: Deferred Slice** \`risk:low\` \`depends:[]\`
+  > Deferred.
+
+- [ ] **S03: Next Slice** \`risk:low\` \`depends:[]\`
+  > Next.
+`);
+      writeFile(base, "milestones/M001/slices/S01/S01-SUMMARY.md", "# S01 Summary\nDone.");
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // The active slice must be S03, NOT S02 (which is deferred)
+      assert.equal(state.activeMilestone?.id, "M001", "active milestone is M001");
+      assert.equal(state.activeSlice?.id, "S03", "active slice should skip deferred S02 and land on S03");
+      assert.notEqual(state.activeSlice?.id, "S02", "active slice must NOT be the deferred S02");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test("deriveStateFromDb does not count deferred slices as done for progress", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Complete", status: "complete", risk: "low", depends: [] });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Deferred", status: "deferred", risk: "low", depends: [] });
+      insertSlice({ id: "S03", milestoneId: "M001", title: "Pending", status: "pending", risk: "low", depends: [] });
+
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001
+## Slices
+- [x] **S01: Complete** \`risk:low\` \`depends:[]\`
+- [ ] **S02: Deferred** \`risk:low\` \`depends:[]\`
+- [ ] **S03: Pending** \`risk:low\` \`depends:[]\`
+`);
+      writeFile(base, "milestones/M001/slices/S01/S01-SUMMARY.md", "# Done");
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // Deferred slices should not count as "done" in progress
+      // Only S01 (complete) counts as done
+      assert.equal(state.progress?.slices?.done, 1, "only 1 slice (S01) should be done");
+      // Total should still be 3 (deferred slices are still part of the milestone)
+      assert.equal(state.progress?.slices?.total, 3, "all 3 slices counted in total");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test("all slices deferred results in blocked state", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Deferred A", status: "deferred", risk: "low", depends: [] });
+      insertSlice({ id: "S02", milestoneId: "M001", title: "Deferred B", status: "deferred", risk: "low", depends: [] });
+
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001
+## Slices
+- [ ] **S01: Deferred A** \`risk:low\` \`depends:[]\`
+- [ ] **S02: Deferred B** \`risk:low\` \`depends:[]\`
+`);
+
+      invalidateStateCache();
+      const state = await deriveStateFromDb(base);
+
+      // No eligible slice — should be blocked
+      assert.equal(state.activeSlice, null, "no active slice when all deferred");
+      assert.equal(state.phase, "blocked", "phase should be blocked when all slices deferred");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  test("saveDecisionToDb marks slice as deferred when decision is a deferral", async () => {
+    const base = createFixtureBase();
+    try {
+      openDatabase(":memory:");
+
+      insertMilestone({ id: "M001", title: "Test", status: "active" });
+      insertSlice({ id: "S03", milestoneId: "M001", title: "Target Slice", status: "active", risk: "low", depends: [] });
+
+      writeFile(base, "milestones/M001/M001-ROADMAP.md", `# M001
+## Slices
+- [ ] **S03: Target Slice** \`risk:low\` \`depends:[]\`
+`);
+
+      const { saveDecisionToDb } = await import("../db-writer.ts");
+      const { getSlice } = await import("../gsd-db.ts");
+
+      // Save a deferral decision that references M001/S03
+      await saveDecisionToDb(
+        {
+          scope: "deferral",
+          decision: "Defer S03 to focus on higher priority work",
+          choice: "defer M001/S03",
+          rationale: "Not ready yet",
+        },
+        base,
+      );
+
+      // The slice status should now be "deferred"
+      const slice = getSlice("M001", "S03");
+      assert.equal(slice?.status, "deferred", "slice status should be updated to 'deferred' after deferral decision");
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+});