gsd-pi 2.63.0-dev.026d309 → 2.63.0-dev.351157b

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

@@ -264,6 +264,146 @@ describe("complete-milestone", () => {
     );
   });
 
+  test("sanitizeCompleteMilestoneParams normalizes string parameters", async () => {
+    const { sanitizeCompleteMilestoneParams } = await import("../bootstrap/sanitize-complete-milestone.ts");
+
+    // Simulate params as they might arrive from the SDK after partial JSON parse:
+    // - numbers instead of strings
+    // - null instead of arrays
+    // - extra whitespace in strings
+    // - undefined optional fields
+    const raw: any = {
+      milestoneId: "  M011 ",
+      title: 42,                              // number instead of string
+      oneLiner: "  One-liner with spaces  ",
+      narrative: "# Big markdown\n\nWith newlines and `backticks`\n\n```ts\ncode();\n```\n",
+      successCriteriaResults: null,            // null instead of string
+      definitionOfDoneResults: undefined,      // undefined instead of string
+      requirementOutcomes: 12345,              // number instead of string
+      keyDecisions: "not an array",            // string instead of array
+      keyFiles: null,                          // null instead of array
+      lessonsLearned: [" lesson one ", null, "", "  lesson two  "],
+      followUps: "  follow up  ",
+      deviations: undefined,
+      verificationPassed: "true",             // string instead of boolean
+    };
+
+    const sanitized = sanitizeCompleteMilestoneParams(raw);
+
+    // String fields are trimmed and coerced
+    assert.strictEqual(sanitized.milestoneId, "M011");
+    assert.strictEqual(sanitized.title, "42");
+    assert.strictEqual(sanitized.oneLiner, "One-liner with spaces");
+    assert.ok(sanitized.narrative.includes("# Big markdown"), "narrative preserves markdown");
+    assert.strictEqual(sanitized.successCriteriaResults, "");
+    assert.strictEqual(sanitized.definitionOfDoneResults, "");
+    assert.strictEqual(sanitized.requirementOutcomes, "12345");
+
+    // Array fields are normalized
+    assert.ok(Array.isArray(sanitized.keyDecisions), "keyDecisions is an array");
+    assert.deepStrictEqual(sanitized.keyDecisions, []);
+    assert.ok(Array.isArray(sanitized.keyFiles), "keyFiles is an array");
+    assert.deepStrictEqual(sanitized.keyFiles, []);
+    assert.deepStrictEqual(sanitized.lessonsLearned, ["lesson one", "lesson two"]);
+
+    // Optional fields — toStr() returns "" for undefined/null
+    assert.strictEqual(sanitized.followUps, "follow up");
+    assert.strictEqual(sanitized.deviations, "");
+
+    // Boolean coercion
+    assert.strictEqual(sanitized.verificationPassed, true);
+  });
+
+  test("sanitizeCompleteMilestoneParams handles large markdown content", async () => {
+    const { sanitizeCompleteMilestoneParams } = await import("../bootstrap/sanitize-complete-milestone.ts");
+
+    // Generate a large markdown string (~25k characters to exceed the 23667 position from the bug)
+    const largeMd = "# Milestone Summary\n\n" +
+      Array.from({ length: 500 }, (_, i) =>
+        `## Section ${i}\n\n` +
+        `- [x] Task ${i} completed with \`code\` and **bold** text\n` +
+        `  - Sub-item with special chars: <, >, &, ", '\n` +
+        `  - Another sub-item: \`\`\`ts\nconst x = ${i};\n\`\`\`\n`
+      ).join("\n");
+
+    assert.ok(largeMd.length > 23667, `generated markdown is ${largeMd.length} chars, must exceed 23667`);
+
+    const raw: any = {
+      milestoneId: "M011",
+      title: "Content Depth, Narrative & Onboarding",
+      oneLiner: "Large milestone with many slices",
+      narrative: largeMd,
+      successCriteriaResults: largeMd,
+      definitionOfDoneResults: largeMd,
+      requirementOutcomes: largeMd,
+      keyDecisions: ["decision 1", "decision 2"],
+      keyFiles: ["file1.ts", "file2.ts"],
+      lessonsLearned: ["lesson 1"],
+      followUps: "Some follow-ups",
+      deviations: "Some deviations",
+      verificationPassed: true,
+    };
+
+    const sanitized = sanitizeCompleteMilestoneParams(raw);
+
+    // Large content should pass through without truncation or corruption
+    assert.strictEqual(sanitized.narrative, largeMd.trim());
+    assert.strictEqual(sanitized.successCriteriaResults, largeMd.trim());
+    assert.strictEqual(sanitized.definitionOfDoneResults, largeMd.trim());
+    assert.strictEqual(sanitized.requirementOutcomes, largeMd.trim());
+  });
+
+  test("milestoneCompleteExecute uses sanitized params", async () => {
+    // This test verifies that the execute function sanitizes params before passing
+    // to handleCompleteMilestone. We test indirectly: if we pass numeric milestoneId,
+    // the handler should still receive a string (and return a meaningful error, not a crash).
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const { sanitizeCompleteMilestoneParams } = await import("../bootstrap/sanitize-complete-milestone.ts");
+    const base = createFixtureBase();
+    try {
+      // Simulate what milestoneCompleteExecute should do: sanitize then call handler
+      const raw: any = {
+        milestoneId: 42,           // number — would crash without sanitization
+        title: "Test",
+        oneLiner: "Test",
+        narrative: "Test narrative",
+        successCriteriaResults: "Results",
+        definitionOfDoneResults: "Done",
+        requirementOutcomes: "Outcomes",
+        keyDecisions: null,        // null — would crash .length without sanitization
+        keyFiles: "not-array",     // string — would crash .map without sanitization
+        lessonsLearned: undefined, // undefined — would crash .map without sanitization
+        followUps: "",
+        deviations: "",
+        verificationPassed: true,
+      };
+
+      const sanitized = sanitizeCompleteMilestoneParams(raw);
+
+      // Verify sanitization didn't crash and produced valid typed params
+      assert.strictEqual(typeof sanitized.milestoneId, "string", "milestoneId is a string after sanitization");
+      assert.ok(Array.isArray(sanitized.keyDecisions), "keyDecisions is array after sanitization");
+      assert.ok(Array.isArray(sanitized.keyFiles), "keyFiles is array after sanitization");
+      assert.ok(Array.isArray(sanitized.lessonsLearned), "lessonsLearned is array after sanitization");
+      assert.strictEqual(typeof sanitized.verificationPassed, "boolean", "verificationPassed is boolean after sanitization");
+
+      // Calling handleCompleteMilestone may throw GSD_STALE_STATE (no DB in test env)
+      // but it should NOT throw TypeError from type mismatches — that's the bug fix.
+      try {
+        await handleCompleteMilestone(sanitized, base);
+      } catch (err: any) {
+        // GSD_STALE_STATE or "No database open" is acceptable — it means we got past
+        // the type-sensitive code and failed on DB access, which is expected in tests.
+        assert.ok(
+          err.code === "GSD_STALE_STATE" || err.message?.includes("database"),
+          `expected DB error, got: ${err.message}`,
+        );
+      }
+    } finally {
+      cleanup(base);
+    }
+  });
+
   test("deriveState completing-milestone integration", async () => {
     const { deriveState, isMilestoneComplete } = await import("../state.ts");
     const { invalidateAllCaches: invalidateAllCachesDynamic } = await import("../cache.ts");

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