gsd-pi 2.66.1-dev.ed243f2 → 2.67.0-dev.43b0159

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -14,7 +14,7 @@ This is remediation round {{remediationRound}}. If this is round 0, this is the
 
 ## Context
 
-All relevant context has been preloaded below — the roadmap, all slice summaries, UAT results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+All relevant context has been preloaded below — the roadmap, all slice summaries, assessment results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
 
 {{inlinedContext}}
 
@@ -30,8 +30,8 @@ Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directo
 **Reviewer B — Cross-Slice Integration**
 Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, check that the producing slice's SUMMARY confirms it produced the artifact, and the consuming slice's SUMMARY confirms it consumed it. Output a markdown table: Boundary | Producer Summary | Consumer Summary | Status. End with a one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
-**Reviewer C — UAT & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} UAT and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for acceptance criteria. Check for UAT-RESULT files in each slice directory. Verify each acceptance criterion maps to either a passing UAT result or clear SUMMARY evidence. Output a checklist: [ ] Criterion | Evidence. End with a one-line verdict: PASS if all criteria met, NEEDS-ATTENTION if gaps exist."
+**Reviewer C — Assessment & Acceptance Criteria**
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for acceptance criteria. Check for ASSESSMENT files in each slice directory. Verify each acceptance criterion maps to either a passing assessment result or clear SUMMARY evidence. Output a checklist: [ ] Criterion | Evidence. End with a one-line verdict: PASS if all criteria met, NEEDS-ATTENTION if gaps exist."
 
 ### Step 2 — Synthesize Findings
 
@@ -40,9 +40,9 @@ After all reviewers complete, aggregate their verdicts:
 - If any reviewer says NEEDS-ATTENTION → overall verdict: `needs-attention`
 - If any reviewer says FAIL → overall verdict: `needs-remediation`
 
-### Step 3 — Write VALIDATION File
+### Step 3 — Persist Validation
 
-Write to `{{validationPath}}`:
+Prepare the validation content you will pass to `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` — the DB-backed tool is the canonical write path and renders the validation file for you.
 
 ```markdown
 ---
@@ -59,7 +59,7 @@ reviewers: 3
 ## Reviewer B — Cross-Slice Integration
 <paste Reviewer B output>
 
-## Reviewer C — UAT & Acceptance Criteria
+## Reviewer C — Assessment & Acceptance Criteria
 <paste Reviewer C output>
 
 ## Synthesis
@@ -69,13 +69,15 @@ reviewers: 3
 <if verdict is not pass: specific actions required>
 ```
 
+Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`.
+
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools. Direct DB access corrupts the WAL and bypasses tool-level validation.
 
 If verdict is `needs-remediation`:
-- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
-- These slices will be planned and executed before validation re-runs
+- Use `gsd_reassess_roadmap` to add the remediation slices instead of editing `{{roadmapPath}}` manually
+- Those slices will be planned and executed before validation re-runs
 
-**You MUST write `{{validationPath}}` before finishing.**
+**You MUST call `gsd_validate_milestone` before finishing. Do not manually write `{{validationPath}}`.**
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
 

package/src/resources/extensions/gsd/prompts/worktree-merge.md

@@ -90,9 +90,11 @@ Present a merge plan to the user:
 
 Ask the user to confirm the merge plan before proceeding.
 
+**CRITICAL — Non-bypassable gate:** Do NOT execute any merge commands until the user explicitly approves the merge plan. If `ask_user_questions` fails, errors, returns no response, or the user's response is ambiguous, you MUST re-ask — never rationalize past the block. "No response, I'll proceed with the clean merges," "the plan looks safe, merging," or any other self-authorization is **forbidden**. The gate exists to protect the user's branches; treat a block as an instruction to wait, not an obstacle to work around.
+
 ### Step 4: Execute Merge
 
-Once confirmed, run all commands from `{{mainTreePath}}` (your CWD):
+Once the user has explicitly confirmed, run all commands from `{{mainTreePath}}` (your CWD):
 
 1. Ensure you are on the target branch: `git checkout {{mainBranch}}`
 2. If there are conflicts requiring manual reconciliation, apply the reconciled versions first

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -10,6 +10,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { normalizePlannedFileReference } from "../files.js";
 import { logWarning } from "../workflow-logger.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
@@ -57,7 +58,9 @@ export function validateFileChanges(
 
   // Normalize expected paths (strip leading ./ or /)
   const normalizedExpected = new Set(
-    [...allExpected].map(f => f.replace(/^\.\//, "").replace(/^\//, "")),
+    [...allExpected].map((f) =>
+      normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, ""),
+    ),
   );
 
   // Compute symmetric difference

package/src/resources/extensions/gsd/state.ts

@@ -1317,7 +1317,8 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       ? `All milestones complete. ${activeReqs} active requirement${activeReqs === 1 ? '' : 's'} in REQUIREMENTS.md ${activeReqs === 1 ? 'has' : 'have'} not been mapped to a milestone.`
       : 'All milestones complete.';
     return {
-      activeMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null,
+      activeMilestone: null,
+      lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null,
       activeSlice: null,
       activeTask: null,
       phase: 'complete',

package/src/resources/extensions/gsd/tests/auto-dashboard.test.ts

@@ -1,7 +1,8 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
 
 import {
   unitVerb,
@@ -11,11 +12,29 @@ import {
   formatWidgetTokens,
   estimateTimeRemaining,
   extractUatSliceId,
+  getWidgetMode,
+  cycleWidgetMode,
+  _resetWidgetModeForTests,
 } from "../auto-dashboard.ts";
 
 const autoSource = readFileSync(join(process.cwd(), "src", "resources", "extensions", "gsd", "auto.ts"), "utf-8");
 const dashboardSource = readFileSync(join(process.cwd(), "src", "resources", "extensions", "gsd", "auto-dashboard.ts"), "utf-8");
 
+function makeTempDir(prefix: string): string {
+  return join(
+    tmpdir(),
+    `gsd-auto-dashboard-test-${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+}
+
+function cleanup(dir: string): void {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+}
+
 // ─── unitVerb ─────────────────────────────────────────────────────────────
 
 test("unitVerb maps known unit types to verbs", () => {
@@ -209,3 +228,35 @@ test("extractUatSliceId returns null for invalid formats", () => {
   assert.equal(extractUatSliceId(""), null);
   assert.equal(extractUatSliceId("M001/T01"), null);
 });
+
+test("widget mode respects project preference precedence and persists there", (t) => {
+  const homeDir = makeTempDir("home");
+  const projectDir = makeTempDir("project");
+  const globalPrefsPath = join(homeDir, ".gsd", "preferences.md");
+  const projectPrefsPath = join(projectDir, ".gsd", "preferences.md");
+
+  mkdirSync(join(homeDir, ".gsd"), { recursive: true });
+  mkdirSync(join(projectDir, ".gsd"), { recursive: true });
+  writeFileSync(globalPrefsPath, "---\nversion: 1\nwidget_mode: off\n---\n", "utf-8");
+  writeFileSync(projectPrefsPath, "---\nversion: 1\nwidget_mode: small\n---\n", "utf-8");
+
+  t.after(() => {
+    cleanup(homeDir);
+    cleanup(projectDir);
+    _resetWidgetModeForTests();
+  });
+
+  _resetWidgetModeForTests();
+
+  assert.equal(getWidgetMode(projectPrefsPath, globalPrefsPath), "small", "project widget_mode overrides global");
+  assert.equal(
+    cycleWidgetMode(projectPrefsPath, globalPrefsPath),
+    "min",
+    "cycling advances from the project-owned mode",
+  );
+
+  const projectPrefs = readFileSync(projectPrefsPath, "utf-8");
+  const globalPrefs = readFileSync(globalPrefsPath, "utf-8");
+  assert.match(projectPrefs, /widget_mode:\s*min/);
+  assert.match(globalPrefs, /widget_mode:\s*off/);
+});

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -1,4 +1,4 @@
-import test from "node:test";
+import test, { mock } from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -191,6 +191,54 @@ test("runUnit returns cancelled when session creation times out", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit keeps the session-switch guard across a late newSession settlement", async () => {
+  _resetPendingResolve();
+  mock.timers.enable();
+
+  try {
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    // Use delays longer than NEW_SESSION_TIMEOUT_MS (120s) so the timeout fires
+    const firstSession = makeMockSession({ newSessionDelayMs: 200_000 });
+    const secondSession = makeMockSession({ newSessionDelayMs: 200_000 });
+
+    const firstRun = runUnit(ctx, pi, firstSession, "task", "T01", "prompt");
+
+    // Tick past the 120s session timeout
+    mock.timers.tick(121_000);
+    await Promise.resolve();
+
+    const firstResult = await firstRun;
+    assert.equal(firstResult.status, "cancelled");
+    assert.equal(isSessionSwitchInFlight(), true, "guard should remain set after the timed-out session");
+
+    mock.timers.tick(1);
+    const secondRun = runUnit(ctx, pi, secondSession, "task", "T02", "prompt");
+
+    mock.timers.tick(100_000);
+    await Promise.resolve();
+    assert.equal(
+      isSessionSwitchInFlight(),
+      true,
+      "late settlement from the first session must not clear the newer session guard",
+    );
+
+    // Tick past the second session's timeout (121s total > 120s NEW_SESSION_TIMEOUT_MS)
+    mock.timers.tick(21_001);
+    await Promise.resolve();
+
+    const secondResult = await secondRun;
+    assert.equal(secondResult.status, "cancelled");
+
+    // Tick past the second session's delayed promise (200s) so .finally() fires
+    mock.timers.tick(80_000);
+    await Promise.resolve();
+    assert.equal(isSessionSwitchInFlight(), false, "guard should clear after the newer session settles");
+  } finally {
+    mock.timers.reset();
+  }
+});
+
 test("runUnit returns cancelled when s.active is false before sendMessage", async () => {
   _resetPendingResolve();
 
@@ -412,7 +460,7 @@ function makeMockDeps(
     getCurrentBranch: () => "main",
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
-    reconcileMergeState: () => false,
+    reconcileMergeState: () => "clean",
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,

package/src/resources/extensions/gsd/tests/auto-model-selection.test.ts

@@ -143,17 +143,17 @@ test("resolvePreferredModelConfig keeps explicit phase models as the ceiling", (
 
 // ─── resolveModelId tests ─────────────────────────────────────────────────
 
-test("resolveModelId: bare ID resolves to anthropic over claude-code when session is claude-code (#2905)", () => {
+test("resolveModelId: bare ID resolves to claude-code when session is claude-code (#3772)", () => {
   const availableModels = [
     { id: "claude-sonnet-4-6", provider: "anthropic" },
     { id: "claude-sonnet-4-6", provider: "claude-code" },
   ];
 
-  // Bug: when currentProvider is "claude-code", bare ID "claude-sonnet-4-6"
-  // resolves to claude-code/claude-sonnet-4-6 instead of anthropic/claude-sonnet-4-6
+  // When currentProvider is "claude-code" (set by startup migration for subscription
+  // users), bare IDs must resolve to claude-code to avoid the third-party block (#3772).
   const result = resolveModelId("claude-sonnet-4-6", availableModels, "claude-code");
   assert.ok(result, "should resolve a model");
-  assert.equal(result.provider, "anthropic", "bare ID must resolve to anthropic, not claude-code");
+  assert.equal(result.provider, "claude-code", "bare ID must resolve to claude-code when session provider is claude-code");
 });
 
 test("resolveModelId: bare ID still prefers current provider when it is a first-class API provider", () => {
@@ -227,14 +227,28 @@ test("model change notify in selectAndApplyModel is gated behind verbose flag",
   );
 });
 
-test("resolveModelId: anthropic wins over claude-code regardless of list order", () => {
+test("resolveModelId: anthropic wins over claude-code when session provider is not claude-code", () => {
   const availableModels = [
     { id: "claude-sonnet-4-6", provider: "claude-code" },
     { id: "claude-sonnet-4-6", provider: "anthropic" },
   ];
 
-  // Even when claude-code appears first in the list, anthropic should win
+  // When the session is NOT on claude-code, bare IDs should resolve to
+  // the canonical anthropic provider (original #2905 behavior preserved).
+  const result = resolveModelId("claude-sonnet-4-6", availableModels, undefined);
+  assert.ok(result, "should resolve a model");
+  assert.equal(result.provider, "anthropic", "anthropic must win when session is not claude-code");
+});
+
+test("resolveModelId: claude-code wins when session is claude-code regardless of list order", () => {
+  const availableModels = [
+    { id: "claude-sonnet-4-6", provider: "claude-code" },
+    { id: "claude-sonnet-4-6", provider: "anthropic" },
+  ];
+
+  // When session provider is claude-code (subscription user migration), it must
+  // win regardless of candidate ordering to avoid the third-party block (#3772).
   const result = resolveModelId("claude-sonnet-4-6", availableModels, "claude-code");
   assert.ok(result, "should resolve a model");
-  assert.equal(result.provider, "anthropic", "anthropic must win over claude-code regardless of list order");
+  assert.equal(result.provider, "claude-code", "claude-code must win when it is the session provider");
 });

package/src/resources/extensions/gsd/tests/auto-recovery.test.ts

@@ -0,0 +1,48 @@
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { verifyExpectedArtifact } from "../auto-recovery.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow } from "../gsd-db.ts";
+
+const tmpDirs: string[] = [];
+
+function makeTmpProject(): string {
+  const dir = mkdtempSync(join(tmpdir(), "auto-recovery-"));
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  openDatabase(join(dir, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test Milestone", status: "active" });
+  insertSlice({
+    milestoneId: "M001",
+    id: "S01",
+    title: "Test Slice",
+    status: "pending",
+    risk: "low",
+    depends: [],
+  });
+  insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+  tmpDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  closeDatabase();
+  for (const dir of tmpDirs) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+  tmpDirs.length = 0;
+});
+
+test("verifyExpectedArtifact checks pending gate-evaluate artifacts without ESM require failures", () => {
+  const base = makeTmpProject();
+
+  const verified = verifyExpectedArtifact("gate-evaluate", "M001/S01/gates+Q3", base);
+
+  assert.equal(verified, false, "pending gates should keep gate-evaluate unverified");
+});

package/src/resources/extensions/gsd/tests/codebase-generator.test.ts

@@ -138,6 +138,28 @@ test("generateCodebaseMap: excludes .gsd/ files", () => {
   }
 });
 
+test("generateCodebaseMap: excludes .claude/ and other tool directories", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+    addFile(base, ".claude/CLAUDE.md");
+    addFile(base, ".claude/memory/user.md");
+    addFile(base, ".plans/plan.md");
+    addFile(base, ".cursor/settings.json");
+    addFile(base, ".vscode/settings.json");
+
+    const result = generateCodebaseMap(base);
+    assert.ok(result.content.includes("`src/main.ts`"), "should include src/main.ts");
+    assert.ok(!result.content.includes("CLAUDE.md"), "should exclude .claude/ files");
+    assert.ok(!result.content.includes("user.md"), "should exclude .claude/memory/ files");
+    assert.ok(!result.content.includes(".plans"), "should exclude .plans/ files");
+    assert.ok(!result.content.includes(".cursor"), "should exclude .cursor/ files");
+    assert.ok(!result.content.includes(".vscode"), "should exclude .vscode/ files");
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("generateCodebaseMap: excludes binary and lock files", () => {
   const base = makeTmpRepo();
   try {

package/src/resources/extensions/gsd/tests/commands-workflow-custom.test.ts

@@ -100,6 +100,18 @@ steps: []
 // ─── Catalog Registration ────────────────────────────────────────────────
 
 describe("workflow catalog registration", () => {
+  it("model appears in TOP_LEVEL_SUBCOMMANDS", () => {
+    const entry = TOP_LEVEL_SUBCOMMANDS.find((c) => c.cmd === "model");
+    assert.ok(entry, "model should be in TOP_LEVEL_SUBCOMMANDS");
+    assert.match(entry!.desc, /session model/i);
+  });
+
+  it("getGsdArgumentCompletions('m') includes model", () => {
+    const completions = getGsdArgumentCompletions("m");
+    const labels = completions.map((c: any) => c.label);
+    assert.ok(labels.includes("model"), "should include model completion");
+  });
+
   it("workflow appears in TOP_LEVEL_SUBCOMMANDS", () => {
     const entry = TOP_LEVEL_SUBCOMMANDS.find((c) => c.cmd === "workflow");
     assert.ok(entry, "workflow should be in TOP_LEVEL_SUBCOMMANDS");

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

@@ -15,6 +15,8 @@ import {
   formatRequirementsForPrompt,
   queryArtifact,
   queryProject,
+  formatRoadmapExcerpt,
+  queryKnowledge,
 } from '../context-store.ts';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -452,3 +454,177 @@ describe("context-store: queryProject", () => {
     assert.strictEqual(content, null, 'queryProject returns null when DB closed');
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// context-store: formatRoadmapExcerpt
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("context-store: formatRoadmapExcerpt", () => {
+  // Sample roadmap content matching actual M005-ROADMAP.md format
+  const sampleRoadmap = `# M005: Tiered Context Injection
+
+## Vision
+Refactor prompt builders to inject relevance-scoped context.
+
+## Slice Overview
+| ID | Slice | Risk | Depends | Done | After this |
+|----|-------|------|---------|------|------------|
+| S01 | Scope existing queries | low | — | ✅ | planSlice prompt scoped. |
+| S02 | KNOWLEDGE scoping | medium | S01 | ⬜ | KNOWLEDGE sections filtered. |
+| S03 | Measurement test | low | S02 | ⬜ | 40% reduction confirmed. |
+`;
+
+  test("S02 with S01 predecessor includes both rows", () => {
+    const result = formatRoadmapExcerpt(sampleRoadmap, 'S02', '.gsd/milestones/M005/M005-ROADMAP.md');
+
+    // Should have header
+    assert.match(result, /\| ID \| Slice \| Risk \| Depends \| Done \| After this \|/, 'has header row');
+    // Should have separator
+    assert.match(result, /\|----\|/, 'has separator row');
+    // Should have S01 predecessor
+    assert.match(result, /\| S01 \|/, 'has predecessor S01 row');
+    // Should have S02 target
+    assert.match(result, /\| S02 \|/, 'has target S02 row');
+    // Should have reference directive
+    assert.match(result, /See full roadmap:.*M005-ROADMAP\.md/, 'has reference directive');
+    // Should NOT have S03 (not relevant)
+    assert.ok(!result.includes('| S03 |'), 'does not include unrelated S03');
+  });
+
+  test("S01 with no predecessor includes only target row", () => {
+    const result = formatRoadmapExcerpt(sampleRoadmap, 'S01');
+
+    // Should have header + separator + S01 only
+    assert.match(result, /\| ID \| Slice \|/, 'has header row');
+    assert.match(result, /\| S01 \|/, 'has target S01 row');
+    // Should NOT have S02 or S03
+    assert.ok(!result.includes('| S02 |'), 'does not include S02');
+    assert.ok(!result.includes('| S03 |'), 'does not include S03');
+    // Should have reference
+    assert.match(result, /See full roadmap:/, 'has reference directive');
+
+    // Count rows: header + separator + S01 + blank + directive = 5 lines
+    const lines = result.split('\n');
+    assert.strictEqual(lines.length, 5, 'correct number of lines (no predecessor)');
+  });
+
+  test("missing slice returns empty string", () => {
+    const result = formatRoadmapExcerpt(sampleRoadmap, 'S99');
+
+    assert.strictEqual(result, '', 'missing slice returns empty string');
+  });
+
+  test("empty input returns empty string", () => {
+    assert.strictEqual(formatRoadmapExcerpt('', 'S01'), '', 'empty content returns empty');
+    assert.strictEqual(formatRoadmapExcerpt(sampleRoadmap, ''), '', 'empty sliceId returns empty');
+  });
+
+  test("handles table with various column formats", () => {
+    // Table with different spacing and content
+    const variantRoadmap = `# Milestone
+
+| ID | Slice | Risk | Depends | Done | After this |
+|:---|:------|:-----|:--------|:-----|:-----------|
+| S01 | First slice title | low | — | ✅ | First complete. |
+| S02 | Second longer slice title here | medium | S01 | ⬜ | Second working. |
+`;
+
+    const result = formatRoadmapExcerpt(variantRoadmap, 'S02');
+
+    assert.match(result, /\| S01 \|/, 'has predecessor with different spacing');
+    assert.match(result, /\| S02 \|/, 'has target with different spacing');
+    assert.match(result, /Second longer slice title/, 'preserves full slice title');
+  });
+
+  test("handles multiple dependencies by using first one", () => {
+    const multiDepRoadmap = `| ID | Slice | Risk | Depends | Done | After this |
+|----|-------|------|---------|------|------------|
+| S01 | First | low | — | ✅ | Done. |
+| S02 | Second | low | — | ✅ | Done. |
+| S03 | Third | medium | S01, S02 | ⬜ | Working. |
+`;
+
+    const result = formatRoadmapExcerpt(multiDepRoadmap, 'S03');
+
+    // Should include S01 (first dependency) and S03
+    assert.match(result, /\| S01 \|/, 'has first dependency S01');
+    assert.match(result, /\| S03 \|/, 'has target S03');
+    // S02 is also a dependency but we only include the first one
+    // (This is intentional to keep excerpts minimal)
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// context-store: queryKnowledge
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("context-store: queryKnowledge", () => {
+  // Sample KNOWLEDGE.md content
+  const sampleKnowledge = `# Project Knowledge
+
+## Database Patterns
+SQLite is used with WAL mode for concurrent reads.
+Always use prepared statements.
+
+More database details here.
+
+## API Design
+REST endpoints follow OpenAPI spec.
+Use versioned paths like /v1/resource.
+
+## Testing Guidelines
+Unit tests use node:test.
+Integration tests mock external services.
+`;
+
+  test("single keyword matches header", async () => {
+    const result = await queryKnowledge(sampleKnowledge, ['database']);
+
+    assert.match(result, /## Database Patterns/, 'includes matching section header');
+    assert.match(result, /SQLite is used with WAL mode/, 'includes section content');
+    // Should NOT include other sections
+    assert.ok(!result.includes('## API Design'), 'does not include non-matching API section');
+    assert.ok(!result.includes('## Testing Guidelines'), 'does not include non-matching Testing section');
+  });
+
+  test("multiple keywords match multiple sections", async () => {
+    const result = await queryKnowledge(sampleKnowledge, ['database', 'testing']);
+
+    assert.match(result, /## Database Patterns/, 'includes Database section');
+    assert.match(result, /## Testing Guidelines/, 'includes Testing section');
+    assert.ok(!result.includes('## API Design'), 'does not include API section');
+  });
+
+  test("no matches returns empty string", async () => {
+    const result = await queryKnowledge(sampleKnowledge, ['nonexistent']);
+
+    assert.strictEqual(result, '', 'no matches returns empty string per D020');
+  });
+
+  test("keyword in first paragraph matches", async () => {
+    const result = await queryKnowledge(sampleKnowledge, ['sqlite']);
+
+    // 'sqlite' appears in first paragraph of Database Patterns
+    assert.match(result, /## Database Patterns/, 'matches keyword in first paragraph');
+    assert.match(result, /SQLite is used/, 'includes the section with matching paragraph');
+  });
+
+  test("case-insensitive matching", async () => {
+    const result = await queryKnowledge(sampleKnowledge, ['DATABASE', 'API']);
+
+    assert.match(result, /## Database Patterns/, 'case-insensitive header match');
+    assert.match(result, /## API Design/, 'case-insensitive header match for API');
+  });
+
+  test("empty keywords returns empty string", async () => {
+    const result = await queryKnowledge(sampleKnowledge, []);
+
+    assert.strictEqual(result, '', 'empty keywords returns empty string');
+  });
+
+  test("empty content returns empty string", async () => {
+    const result = await queryKnowledge('', ['database']);
+
+    assert.strictEqual(result, '', 'empty content returns empty string');
+  });
+});