gsd-pi 2.66.1-dev.ed243f2 → 2.67.0

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

package/src/resources/extensions/gsd/tests/core-overlay-fallback.test.ts

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { handleCoreCommand } from "../commands/handlers/core.ts";
+
+function makeCtx(customResult: unknown) {
+  const notices: Array<{ message: string; type?: string }> = [];
+  return {
+    hasUI: true,
+    ui: {
+      custom: async () => customResult,
+      notify: (message: string, type?: string) => {
+        notices.push({ message, type });
+      },
+    },
+    notices,
+  };
+}
+
+test("visualize only falls back when ctx.ui.custom() is unavailable", async () => {
+  const successCtx = makeCtx(true);
+  const success = await handleCoreCommand("visualize", successCtx as any);
+  assert.equal(success, true);
+  assert.equal(successCtx.notices.length, 0, "successful overlay close does not trigger fallback");
+
+  const fallbackCtx = makeCtx(undefined);
+  const fallback = await handleCoreCommand("visualize", fallbackCtx as any);
+  assert.equal(fallback, true);
+  assert.equal(fallbackCtx.notices.length, 1, "unavailable overlay triggers fallback warning");
+  assert.match(fallbackCtx.notices[0]!.message, /interactive terminal/i);
+});
+
+test("show-config only falls back when ctx.ui.custom() is unavailable", async () => {
+  const successCtx = makeCtx(true);
+  const success = await handleCoreCommand("show-config", successCtx as any);
+  assert.equal(success, true);
+  assert.equal(successCtx.notices.length, 0, "successful overlay close does not trigger fallback");
+
+  const fallbackCtx = makeCtx(undefined);
+  const fallback = await handleCoreCommand("show-config", fallbackCtx as any);
+  assert.equal(fallback, true);
+  assert.equal(fallbackCtx.notices.length, 1, "unavailable overlay triggers text fallback");
+  assert.match(fallbackCtx.notices[0]!.message, /GSD Configuration/);
+});

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

@@ -178,7 +178,7 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     getCurrentBranch: () => "main",
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
-    reconcileMergeState: () => false,
+    reconcileMergeState: () => "clean",
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,
@@ -311,6 +311,12 @@ describe("Custom engine loop integration", () => {
       `stopAuto reason should include "Workflow complete", got: ${stopEntry}`,
     );
 
+    assert.equal(
+      deps.callLog.filter((e: string) => e === "deriveState").length,
+      3,
+      "custom engine should stop immediately after a milestone-complete reconcile",
+    );
+
     // Verify dev path was NOT used (resolveDispatch should not appear)
     assert.ok(
       !deps.callLog.includes("resolveDispatch"),

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

@@ -249,6 +249,37 @@ describe("CustomWorkflowEngine.reconcile", () => {
     const graph = readGraph(runDir);
     assert.equal(graph.steps[0].status, "complete");
   });
+
+  it("re-reads GRAPH.yaml before reconcile so concurrent edits are preserved", async () => {
+    const { engine, runDir } = setupEngine([
+      makeStep({ id: "step-1" }),
+      makeStep({ id: "step-2", dependsOn: ["step-1"] }),
+    ], "wf");
+
+    const staleState = await engine.deriveState("/unused");
+
+    // Simulate another process appending a new step after deriveState() ran.
+    writeGraph(runDir, makeGraph([
+      makeStep({ id: "step-1" }),
+      makeStep({ id: "step-2", dependsOn: ["step-1"] }),
+      makeStep({ id: "step-3", dependsOn: ["step-2"] }),
+    ], "wf"));
+
+    const result = await engine.reconcile(staleState, {
+      unitType: "custom-step",
+      unitId: "wf/step-1",
+      startedAt: Date.now() - 1000,
+      finishedAt: Date.now(),
+    });
+
+    assert.equal(result.outcome, "continue");
+
+    const graph = readGraph(runDir);
+    assert.equal(graph.steps.length, 3, "reconcile should preserve the concurrent graph edit");
+    assert.equal(graph.steps[0].status, "complete");
+    assert.equal(graph.steps[1].status, "pending");
+    assert.equal(graph.steps[2].status, "pending");
+  });
 });
 
 // ─── getDisplayMetadata ──────────────────────────────────────────────────

package/src/resources/extensions/gsd/tests/decision-scope-cascade.test.ts

@@ -0,0 +1,370 @@
+// decision-scope-cascade: Tests for R005 fallback cascade and scope derivation
+//
+// Validates:
+// (a) inlineDecisionsFromDb cascade: milestone + scope → milestone only → null
+// (b) deriveSliceScope extracts meaningful scope keywords from slice titles
+// (c) deriveSliceScope returns undefined for generic titles
+
+import { describe, test, afterEach, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  openDatabase,
+  closeDatabase,
+  isDbAvailable,
+  insertDecision,
+} from '../gsd-db.ts';
+import {
+  queryDecisions,
+  formatDecisionsForPrompt,
+} from '../context-store.ts';
+import { deriveSliceScope } from '../auto-prompts.ts';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// deriveSliceScope: Extract meaningful scope from slice titles
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("deriveSliceScope: keyword extraction", () => {
+  test("extracts first meaningful noun from title", () => {
+    // "Auth Middleware & Protected Route" → "auth"
+    assert.strictEqual(
+      deriveSliceScope("Auth Middleware & Protected Route"),
+      "auth",
+      "extracts 'auth' from auth-related title",
+    );
+
+    // "Database & User Model Setup" → "database" (not "setup" which is generic)
+    const dbScope = deriveSliceScope("Database & User Model Setup");
+    assert.ok(
+      dbScope === "database" || dbScope === "user",
+      `expected 'database' or 'user', got '${dbScope}'`,
+    );
+
+    // "API Rate Limiting" → "api"
+    assert.strictEqual(
+      deriveSliceScope("API Rate Limiting"),
+      "api",
+      "extracts 'api' from API-related title",
+    );
+
+    // "Stripe Payment Integration" → "stripe"
+    assert.strictEqual(
+      deriveSliceScope("Stripe Payment Integration"),
+      "stripe",
+      "extracts 'stripe' from payment-related title",
+    );
+  });
+
+  test("returns undefined for generic titles", () => {
+    // "Integration Testing" → undefined (both words are generic)
+    assert.strictEqual(
+      deriveSliceScope("Integration Testing"),
+      undefined,
+      "returns undefined for generic 'Integration Testing'",
+    );
+
+    // "Setup & Configuration" → undefined (all generic)
+    assert.strictEqual(
+      deriveSliceScope("Setup & Configuration"),
+      undefined,
+      "returns undefined for generic 'Setup & Configuration'",
+    );
+
+    // "Final Review" → undefined
+    assert.strictEqual(
+      deriveSliceScope("Final Review"),
+      undefined,
+      "returns undefined for generic 'Final Review'",
+    );
+
+    // "Basic Implementation" → undefined
+    assert.strictEqual(
+      deriveSliceScope("Basic Implementation"),
+      undefined,
+      "returns undefined for generic 'Basic Implementation'",
+    );
+  });
+
+  test("handles description as additional context", () => {
+    // Generic title but specific description
+    const scope = deriveSliceScope(
+      "Initial Setup",
+      "Configure PostgreSQL database connection",
+    );
+    assert.ok(
+      scope === "postgresql" || scope === "database" || scope === "configure",
+      `expected meaningful scope from description, got '${scope}'`,
+    );
+  });
+
+  test("handles edge cases", () => {
+    // Empty title
+    assert.strictEqual(
+      deriveSliceScope(""),
+      undefined,
+      "returns undefined for empty title",
+    );
+
+    // Short words only
+    assert.strictEqual(
+      deriveSliceScope("A B C"),
+      undefined,
+      "returns undefined for very short words",
+    );
+
+    // Mixed case and punctuation
+    assert.strictEqual(
+      deriveSliceScope("OAuth2 + JWT Authentication"),
+      "oauth2",
+      "handles mixed case and punctuation",
+    );
+  });
+
+  test("filters unit IDs (S01, M001, T03)", () => {
+    // "S01: Infrastructure" → undefined (S01 is a unit ID, infrastructure is generic)
+    assert.strictEqual(
+      deriveSliceScope("S01: Infrastructure"),
+      undefined,
+      "skips S01 ID and returns undefined for generic 'Infrastructure'",
+    );
+
+    // "M001 Setup" → undefined (M001 is a unit ID, setup is generic)
+    assert.strictEqual(
+      deriveSliceScope("M001 Setup"),
+      undefined,
+      "skips M001 ID and returns undefined for generic 'Setup'",
+    );
+
+    // "T03: Database Migration" → "database" (skips T03, returns meaningful word)
+    assert.strictEqual(
+      deriveSliceScope("T03: Database Migration"),
+      "database",
+      "skips T03 ID and returns 'database'",
+    );
+
+    // "S02 Auth Flow" → "auth" (skips S02, returns meaningful word)
+    assert.strictEqual(
+      deriveSliceScope("S02 Auth Flow"),
+      "auth",
+      "skips S02 ID and returns 'auth'",
+    );
+  });
+
+  test("filters process/activity words", () => {
+    // "Integration Testing + Hardening" → undefined (all generic/process words)
+    assert.strictEqual(
+      deriveSliceScope("Integration Testing + Hardening"),
+      undefined,
+      "returns undefined for 'Integration Testing + Hardening'",
+    );
+
+    // "Validation & Verification" → undefined (both are process words)
+    assert.strictEqual(
+      deriveSliceScope("Validation & Verification"),
+      undefined,
+      "returns undefined for 'Validation & Verification'",
+    );
+
+    // "Performance Optimization" → "performance" (optimization is generic, performance is domain)
+    assert.strictEqual(
+      deriveSliceScope("Performance Optimization"),
+      "performance",
+      "extracts 'performance' before generic 'optimization'",
+    );
+
+    // "Security Enhancement" → "security" (enhancement is generic, security is domain)
+    assert.strictEqual(
+      deriveSliceScope("Security Enhancement"),
+      "security",
+      "extracts 'security' before generic 'enhancement'",
+    );
+
+    // "WebSocket Delivery Pipeline" → "websocket"
+    assert.strictEqual(
+      deriveSliceScope("WebSocket Delivery Pipeline"),
+      "websocket",
+      "extracts 'websocket' from delivery pipeline title",
+    );
+
+    // "Prisma Schema + Migration" → "prisma"
+    assert.strictEqual(
+      deriveSliceScope("Prisma Schema + Migration"),
+      "prisma",
+      "extracts 'prisma' from schema migration title",
+    );
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// inlineDecisionsFromDb cascade: R005 implementation
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("inlineDecisionsFromDb: cascade fallback (R005)", () => {
+  beforeEach(() => {
+    openDatabase(':memory:');
+  });
+
+  afterEach(() => {
+    closeDatabase();
+  });
+
+  test("cascade: scoped query returns scoped decisions when they exist", () => {
+    // Insert decisions with different scopes
+    insertDecision({
+      id: 'D001', when_context: 'M001/S01', scope: 'auth',
+      decision: 'use JWT', choice: 'JWT', rationale: 'standard',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+    insertDecision({
+      id: 'D002', when_context: 'M001/S02', scope: 'database',
+      decision: 'use PostgreSQL', choice: 'PostgreSQL', rationale: 'relational',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+    insertDecision({
+      id: 'D003', when_context: 'M001/S01', scope: 'architecture',
+      decision: 'use microservices', choice: 'microservices', rationale: 'scalable',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+
+    // Query with scope 'auth' should return D001 only
+    const authDecisions = queryDecisions({ milestoneId: 'M001', scope: 'auth' });
+    assert.strictEqual(authDecisions.length, 1, 'scoped query returns 1 decision');
+    assert.strictEqual(authDecisions[0]?.id, 'D001', 'returns D001 for auth scope');
+
+    // Query with scope 'database' should return D002 only
+    const dbDecisions = queryDecisions({ milestoneId: 'M001', scope: 'database' });
+    assert.strictEqual(dbDecisions.length, 1, 'scoped query returns 1 decision');
+    assert.strictEqual(dbDecisions[0]?.id, 'D002', 'returns D002 for database scope');
+  });
+
+  test("cascade: milestone-only fallback when scoped query returns empty", () => {
+    // Insert decisions for M001 with generic scope (e.g. 'architecture')
+    insertDecision({
+      id: 'D001', when_context: 'M001/S01', scope: 'architecture',
+      decision: 'use microservices', choice: 'microservices', rationale: 'scalable',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+    insertDecision({
+      id: 'D002', when_context: 'M001/S02', scope: 'performance',
+      decision: 'use caching', choice: 'Redis', rationale: 'fast',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+
+    // Query with scope 'auth' (no decisions with this scope) should return empty
+    const authDecisions = queryDecisions({ milestoneId: 'M001', scope: 'auth' });
+    assert.strictEqual(authDecisions.length, 0, 'scoped query for auth returns empty');
+
+    // Simulate cascade: fallback to milestone-only query
+    const milestoneDecisions = queryDecisions({ milestoneId: 'M001' });
+    assert.strictEqual(milestoneDecisions.length, 2, 'milestone-only query returns 2 decisions');
+    const ids = milestoneDecisions.map(d => d.id).sort();
+    assert.deepStrictEqual(ids, ['D001', 'D002'], 'milestone fallback returns all M001 decisions');
+  });
+
+  test("cascade: returns null when both scoped and milestone queries are empty", () => {
+    // Insert decisions only for M002
+    insertDecision({
+      id: 'D001', when_context: 'M002/S01', scope: 'auth',
+      decision: 'use OAuth', choice: 'OAuth2', rationale: 'standard',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+
+    // Query M001 with scope should return empty (no M001 decisions at all)
+    const scopedDecisions = queryDecisions({ milestoneId: 'M001', scope: 'auth' });
+    assert.strictEqual(scopedDecisions.length, 0, 'scoped query returns empty');
+
+    // Fallback to milestone-only should also return empty (no M001 decisions)
+    const milestoneDecisions = queryDecisions({ milestoneId: 'M001' });
+    assert.strictEqual(milestoneDecisions.length, 0, 'milestone-only query returns empty');
+
+    // This scenario would result in null from inlineDecisionsFromDb
+    // (we can't directly test inlineDecisionsFromDb here without mocking fs)
+  });
+
+  test("cascade: demonstrates the full cascade behavior", () => {
+    // This test demonstrates the cascade logic that inlineDecisionsFromDb implements:
+    // 1. First try { milestoneId: 'M001', scope: 'payment' } → empty
+    // 2. Then try { milestoneId: 'M001' } → gets D001, D002
+    // 3. Return the milestone-level decisions
+
+    // Setup: decisions exist at milestone level but not for 'payment' scope
+    insertDecision({
+      id: 'D001', when_context: 'M001/S01', scope: 'architecture',
+      decision: 'use REST', choice: 'REST API', rationale: 'standard',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+    insertDecision({
+      id: 'D002', when_context: 'M001/S02', scope: 'security',
+      decision: 'use HTTPS', choice: 'TLS 1.3', rationale: 'secure',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+
+    // Step 1: Query with scope 'payment' (no matches)
+    const paymentDecisions = queryDecisions({ milestoneId: 'M001', scope: 'payment' });
+    assert.strictEqual(paymentDecisions.length, 0, 'payment scope query returns empty');
+
+    // Step 2: Since scope was provided but returned empty, cascade to milestone-only
+    const milestoneDecisions = queryDecisions({ milestoneId: 'M001' });
+    assert.strictEqual(milestoneDecisions.length, 2, 'milestone fallback returns 2 decisions');
+
+    // Step 3: Format and verify content
+    const formatted = formatDecisionsForPrompt(milestoneDecisions);
+    assert.match(formatted, /D001/, 'formatted output includes D001');
+    assert.match(formatted, /D002/, 'formatted output includes D002');
+    assert.match(formatted, /architecture/, 'formatted output includes architecture scope');
+    assert.match(formatted, /security/, 'formatted output includes security scope');
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Integration: scope derivation feeds into cascade
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("integration: scope derivation with cascade", () => {
+  beforeEach(() => {
+    openDatabase(':memory:');
+  });
+
+  afterEach(() => {
+    closeDatabase();
+  });
+
+  test("derived scope finds matching decisions when they exist", () => {
+    // Insert decisions with 'auth' scope
+    insertDecision({
+      id: 'D001', when_context: 'M001/S01', scope: 'auth',
+      decision: 'use JWT', choice: 'JWT tokens', rationale: 'stateless',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+
+    // Derive scope from slice title
+    const derivedScope = deriveSliceScope("Auth Middleware & Protected Routes");
+    assert.strictEqual(derivedScope, 'auth', 'derives auth scope from title');
+
+    // Query with derived scope should find the decision
+    const decisions = queryDecisions({ milestoneId: 'M001', scope: derivedScope });
+    assert.strictEqual(decisions.length, 1, 'scoped query finds matching decision');
+    assert.strictEqual(decisions[0]?.id, 'D001', 'finds the auth decision');
+  });
+
+  test("generic title triggers milestone-level fallback", () => {
+    // Insert decisions with various scopes
+    insertDecision({
+      id: 'D001', when_context: 'M001/S01', scope: 'architecture',
+      decision: 'use monolith', choice: 'monolith', rationale: 'simple',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+    insertDecision({
+      id: 'D002', when_context: 'M001/S02', scope: 'tooling',
+      decision: 'use TypeScript', choice: 'TypeScript', rationale: 'type safety',
+      revisable: 'yes', made_by: 'agent', superseded_by: null,
+    });
+
+    // Derive scope from generic slice title
+    const derivedScope = deriveSliceScope("Integration Testing");
+    assert.strictEqual(derivedScope, undefined, 'generic title returns undefined scope');
+
+    // Without a scope, query returns all milestone decisions
+    const decisions = queryDecisions({ milestoneId: 'M001', scope: derivedScope });
+    assert.strictEqual(decisions.length, 2, 'no scope filter returns all decisions');
+  });
+});