gsd-pi 2.33.1-dev.235d83a → 2.33.1-dev.29a8268

package/dist/resources/extensions/gsd/tests/integration-edge.test.ts

@@ -0,0 +1,228 @@
+// Integration Edge Case Tests
+//
+// Three scenarios that only had per-module coverage before:
+// 1. Empty project — no markdown files → migration finds nothing → queries return empty
+// 2. Partial migration — DECISIONS.md exists but no REQUIREMENTS.md → no crash
+// 3. Fallback mode — _resetProvider → queries degrade → re-open restores
+//
+// Uses real module imports (no mocks), file-backed DBs, temp directories.
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { openDatabase, closeDatabase, isDbAvailable, _resetProvider } from '../gsd-db.ts';
+import { migrateFromMarkdown } from '../md-importer.ts';
+import {
+  queryDecisions,
+  queryRequirements,
+  formatDecisionsForPrompt,
+  formatRequirementsForPrompt,
+} from '../context-store.ts';
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+// ─── Fixture Helper ────────────────────────────────────────────────────────
+
+function generateDecisionsMarkdown(count: number): string {
+  const lines: string[] = [
+    '# Decisions Register',
+    '',
+    '<!-- Append-only. Never edit or remove existing rows. -->',
+    '',
+    '| # | When | Scope | Decision | Choice | Rationale | Revisable? |',
+    '|---|------|-------|----------|--------|-----------|------------|',
+  ];
+
+  for (let i = 1; i <= count; i++) {
+    const id = `D${String(i).padStart(3, '0')}`;
+    const milestone = i <= 3 ? 'M001' : 'M002';
+    lines.push(`| ${id} | ${milestone}/S01 | testing | decision ${i} text | choice ${i} | rationale ${i} | yes |`);
+  }
+
+  return lines.join('\n');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Edge Case 1: Empty Project
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== integration-edge: empty project ===');
+{
+  const base = mkdtempSync(join(tmpdir(), 'gsd-int-edge-empty-'));
+  const gsdDir = join(base, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  const dbPath = join(gsdDir, 'test-edge-empty.db');
+
+  try {
+    // Open DB first so migrateFromMarkdown doesn't auto-create at default path
+    openDatabase(dbPath);
+    assertTrue(isDbAvailable(), 'empty: DB available after open');
+
+    // Migrate with no markdown files on disk
+    const result = migrateFromMarkdown(base);
+
+    assertEq(result.decisions, 0, 'empty: 0 decisions imported');
+    assertEq(result.requirements, 0, 'empty: 0 requirements imported');
+    assertEq(result.artifacts, 0, 'empty: 0 artifacts imported');
+
+    // Query decisions → empty array
+    const decisions = queryDecisions();
+    assertEq(decisions.length, 0, 'empty: queryDecisions returns empty array');
+
+    // Query requirements → empty array
+    const requirements = queryRequirements();
+    assertEq(requirements.length, 0, 'empty: queryRequirements returns empty array');
+
+    // Query with scope filters → still empty, no crash
+    const scopedDecisions = queryDecisions({ milestoneId: 'M001' });
+    assertEq(scopedDecisions.length, 0, 'empty: scoped queryDecisions returns empty');
+
+    const scopedRequirements = queryRequirements({ sliceId: 'S01' });
+    assertEq(scopedRequirements.length, 0, 'empty: scoped queryRequirements returns empty');
+
+    // Format empty results → empty strings
+    const formattedD = formatDecisionsForPrompt([]);
+    const formattedR = formatRequirementsForPrompt([]);
+    assertEq(formattedD, '', 'empty: formatDecisionsForPrompt returns empty string');
+    assertEq(formattedR, '', 'empty: formatRequirementsForPrompt returns empty string');
+
+    // Format with actual empty query results
+    const formattedD2 = formatDecisionsForPrompt(decisions);
+    const formattedR2 = formatRequirementsForPrompt(requirements);
+    assertEq(formattedD2, '', 'empty: format of empty query decisions is empty string');
+    assertEq(formattedR2, '', 'empty: format of empty query requirements is empty string');
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Edge Case 2: Partial Migration (decisions only, no requirements)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== integration-edge: partial migration ===');
+{
+  const base = mkdtempSync(join(tmpdir(), 'gsd-int-edge-partial-'));
+  const gsdDir = join(base, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  // Write DECISIONS.md but NOT REQUIREMENTS.md
+  const decisionsMarkdown = generateDecisionsMarkdown(6);
+  writeFileSync(join(gsdDir, 'DECISIONS.md'), decisionsMarkdown);
+
+  const dbPath = join(gsdDir, 'test-edge-partial.db');
+
+  try {
+    openDatabase(dbPath);
+    assertTrue(isDbAvailable(), 'partial: DB available after open');
+
+    const result = migrateFromMarkdown(base);
+
+    // Decisions imported, requirements skipped gracefully
+    assertTrue(result.decisions === 6, `partial: imported ${result.decisions} decisions, expected 6`);
+    assertEq(result.requirements, 0, 'partial: 0 requirements imported (no file)');
+
+    // Decisions queryable
+    const decisions = queryDecisions();
+    assertTrue(decisions.length === 6, `partial: queryDecisions returns 6 (got ${decisions.length})`);
+
+    const m001Decisions = queryDecisions({ milestoneId: 'M001' });
+    assertTrue(m001Decisions.length > 0, 'partial: M001 decisions non-empty');
+    assertTrue(m001Decisions.length < decisions.length, 'partial: M001 scope filters correctly');
+
+    // Requirements return empty — no crash
+    const requirements = queryRequirements();
+    assertEq(requirements.length, 0, 'partial: queryRequirements returns empty');
+
+    const scopedReqs = queryRequirements({ sliceId: 'S01' });
+    assertEq(scopedReqs.length, 0, 'partial: scoped queryRequirements returns empty');
+
+    // Format works on partial data
+    const formattedD = formatDecisionsForPrompt(m001Decisions);
+    assertTrue(formattedD.length > 0, 'partial: formatted decisions non-empty');
+
+    const formattedR = formatRequirementsForPrompt(requirements);
+    assertEq(formattedR, '', 'partial: formatted empty requirements is empty string');
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Edge Case 3: Fallback Mode (_resetProvider)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== integration-edge: fallback mode ===');
+{
+  const base = mkdtempSync(join(tmpdir(), 'gsd-int-edge-fallback-'));
+  const gsdDir = join(base, '.gsd');
+  mkdirSync(gsdDir, { recursive: true });
+
+  const decisionsMarkdown = generateDecisionsMarkdown(4);
+  writeFileSync(join(gsdDir, 'DECISIONS.md'), decisionsMarkdown);
+
+  const dbPath = join(gsdDir, 'test-edge-fallback.db');
+
+  try {
+    // Step 1: Open DB normally and verify it works
+    openDatabase(dbPath);
+    assertTrue(isDbAvailable(), 'fallback: DB available after open');
+
+    migrateFromMarkdown(base);
+    const before = queryDecisions();
+    assertTrue(before.length === 4, `fallback: 4 decisions before reset (got ${before.length})`);
+
+    // Step 2: Close and reset provider → DB unavailable
+    closeDatabase();
+    _resetProvider();
+    assertTrue(!isDbAvailable(), 'fallback: DB unavailable after _resetProvider');
+
+    // Step 3: Queries degrade gracefully (return empty, don't throw)
+    const degradedDecisions = queryDecisions();
+    assertEq(degradedDecisions.length, 0, 'fallback: queryDecisions returns empty when unavailable');
+
+    const degradedRequirements = queryRequirements();
+    assertEq(degradedRequirements.length, 0, 'fallback: queryRequirements returns empty when unavailable');
+
+    const degradedScopedD = queryDecisions({ milestoneId: 'M001' });
+    assertEq(degradedScopedD.length, 0, 'fallback: scoped queryDecisions returns empty when unavailable');
+
+    const degradedScopedR = queryRequirements({ sliceId: 'S01' });
+    assertEq(degradedScopedR.length, 0, 'fallback: scoped queryRequirements returns empty when unavailable');
+
+    // Format functions work on empty arrays (no crash)
+    const formattedD = formatDecisionsForPrompt(degradedDecisions);
+    assertEq(formattedD, '', 'fallback: format degraded decisions is empty');
+
+    const formattedR = formatRequirementsForPrompt(degradedRequirements);
+    assertEq(formattedR, '', 'fallback: format degraded requirements is empty');
+
+    // Step 4: Re-open DB → restores availability
+    openDatabase(dbPath);
+    assertTrue(isDbAvailable(), 'fallback: DB available after re-open');
+
+    // Data should be there from the file-backed DB (persisted by first open)
+    // But rows may need re-import since the DB was freshly opened from the file
+    migrateFromMarkdown(base);
+    const restored = queryDecisions();
+    assertTrue(restored.length === 4, `fallback: 4 decisions after re-open (got ${restored.length})`);
+
+    closeDatabase();
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+// ─── Report ────────────────────────────────────────────────────────────────
+
+report();

package/dist/resources/extensions/gsd/tests/integration-lifecycle.test.ts

@@ -0,0 +1,277 @@
+// Integration Lifecycle Test
+//
+// Proves full M001 subsystem composition end-to-end:
+// realistic markdown on disk → migrateFromMarkdown → scoped DB queries →
+// formatted prompt output → token savings validation → re-import after changes →
+// structured tool write-back → DB consistency verification.
+//
+// Crosses ≥4 module boundaries: gsd-db, md-importer, context-store, db-writer.
+// Uses file-backed DB (not :memory:) for WAL fidelity.
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { openDatabase, closeDatabase, isDbAvailable, _getAdapter } from '../gsd-db.ts';
+import { migrateFromMarkdown, parseDecisionsTable } from '../md-importer.ts';
+import {
+  queryDecisions,
+  queryRequirements,
+  formatDecisionsForPrompt,
+  formatRequirementsForPrompt,
+} from '../context-store.ts';
+import { saveDecisionToDb, generateDecisionsMd } from '../db-writer.ts';
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+// ─── Fixture Generators (duplicated from token-savings.test.ts — file-scoped) ──
+
+function generateDecisionsMarkdown(count: number, milestones: string[]): string {
+  const lines: string[] = [
+    '# Decisions Register',
+    '',
+    '<!-- Append-only. Never edit or remove existing rows. -->',
+    '',
+    '| # | When | Scope | Decision | Choice | Rationale | Revisable? |',
+    '|---|------|-------|----------|--------|-----------|------------|',
+  ];
+
+  for (let i = 1; i <= count; i++) {
+    const id = `D${String(i).padStart(3, '0')}`;
+    const milestone = milestones[(i - 1) % milestones.length];
+    const sliceNum = ((i - 1) % 5) + 1;
+    const when = `${milestone}/S${String(sliceNum).padStart(2, '0')}`;
+    const scope = ['architecture', 'testing', 'observability', 'security', 'performance'][(i - 1) % 5];
+    const decision = `${scope} decision ${i}: implement ${scope}-level ${['caching', 'validation', 'retry logic', 'circuit breaker', 'rate limiting'][(i - 1) % 5]} for the ${['API layer', 'data pipeline', 'auth subsystem', 'notification service', 'background workers'][(i - 1) % 5]}`;
+    const choice = `Use ${['SQLite', 'Redis', 'in-memory cache', 'exponential backoff', 'token bucket'][(i - 1) % 5]} with ${['WAL mode', 'cluster mode', 'LRU eviction', 'jitter', 'sliding window'][(i - 1) % 5]}`;
+    const rationale = `${['Built-in Node.js support eliminates external dependency', 'Sub-millisecond latency meets P99 requirement', 'Memory-efficient with bounded growth prevents OOM', 'Prevents thundering herd during recovery', 'Protects downstream services from burst traffic'][(i - 1) % 5]}. Aligns with ${scope} principles for ${milestone}.`;
+    const revisable = i % 3 === 0 ? 'no' : 'yes';
+
+    lines.push(`| ${id} | ${when} | ${scope} | ${decision} | ${choice} | ${rationale} | ${revisable} |`);
+  }
+
+  return lines.join('\n');
+}
+
+function milestone_shorthand(index: number): string {
+  return ['alpha', 'beta', 'GA'][index] ?? 'alpha';
+}
+
+function generateRequirementsMarkdown(count: number, sliceAssignments: { milestone: string; slice: string }[]): string {
+  const lines: string[] = [
+    '# Requirements',
+    '',
+    '## Active',
+    '',
+  ];
+
+  for (let i = 1; i <= count; i++) {
+    const id = `R${String(i).padStart(3, '0')}`;
+    const assignment = sliceAssignments[(i - 1) % sliceAssignments.length];
+    const reqClass = ['functional', 'non-functional', 'constraint', 'functional', 'non-functional'][(i - 1) % 5];
+    const description = `${['Response latency', 'Data consistency', 'Error recovery', 'Access control', 'Audit logging', 'Cache invalidation', 'Schema migration'][(i - 1) % 7]} requirement for ${assignment.milestone}/${assignment.slice}`;
+    const why = `Critical for ${['user experience', 'data integrity', 'system reliability', 'security compliance', 'regulatory requirements', 'operational visibility', 'deployment safety'][(i - 1) % 7]}. Without this, the system would ${['degrade under load', 'lose data during failures', 'fail to recover from crashes', 'expose unauthorized data', 'violate compliance mandates', 'have stale data issues', 'break during schema changes'][(i - 1) % 7]}.`;
+    const source = `Architecture review ${milestone_shorthand((i - 1) % 3)}, stakeholder feedback round ${((i - 1) % 4) + 1}`;
+    const primaryOwner = assignment.slice;
+    const supportingSlices = sliceAssignments
+      .filter(a => a.slice !== assignment.slice && a.milestone === assignment.milestone)
+      .map(a => a.slice)
+      .slice(0, 2)
+      .join(', ');
+    const validation = `${['Automated test suite covers all edge cases', 'Load test confirms P99 < 200ms under 1000 RPS', 'Chaos test proves recovery within 30s', 'Penetration test shows no unauthorized access paths', 'Audit log review confirms complete event capture', 'Integration test validates cache consistency', 'Migration test verifies zero-downtime upgrade'][(i - 1) % 7]}.`;
+    const notes = `Tracked in JIRA-${100 + i}. See ADR-${((i - 1) % 5) + 1} for background.`;
+
+    lines.push(`### ${id} — ${description}`);
+    lines.push('');
+    lines.push(`- Class: ${reqClass}`);
+    lines.push(`- Status: active`);
+    lines.push(`- Why it matters: ${why}`);
+    lines.push(`- Source: ${source}`);
+    lines.push(`- Primary owning slice: ${primaryOwner}`);
+    if (supportingSlices) {
+      lines.push(`- Supporting slices: ${supportingSlices}`);
+    }
+    lines.push(`- Validation: ${validation}`);
+    lines.push(`- Notes: ${notes}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Fixture Constants ─────────────────────────────────────────────────────
+
+const MILESTONES = ['M001', 'M002'];
+const SLICE_ASSIGNMENTS = [
+  { milestone: 'M001', slice: 'S01' },
+  { milestone: 'M001', slice: 'S02' },
+  { milestone: 'M001', slice: 'S03' },
+  { milestone: 'M002', slice: 'S04' },
+  { milestone: 'M002', slice: 'S05' },
+];
+const DECISIONS_COUNT = 14;
+const REQUIREMENTS_COUNT = 12;
+
+const ROADMAP_CONTENT = `# M001: Test Milestone\n\n**Vision:** Integration test milestone.\n\n## Slices\n\n- [ ] **S01: First Slice** \`risk:low\` \`depends:[]\`\n  > After this: Done.\n`;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Full Lifecycle Integration Test
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main(): Promise<void> {
+
+  console.log('\n=== integration-lifecycle: full pipeline ===');
+  {
+    // ── Step 1: Set up temp dir with realistic .gsd/ structure ──────────
+    const base = mkdtempSync(join(tmpdir(), 'gsd-int-lifecycle-'));
+    const gsdDir = join(base, '.gsd');
+    mkdirSync(gsdDir, { recursive: true });
+    mkdirSync(join(gsdDir, 'milestones', 'M001'), { recursive: true });
+    mkdirSync(join(gsdDir, 'milestones', 'M002'), { recursive: true });
+
+    const decisionsMarkdown = generateDecisionsMarkdown(DECISIONS_COUNT, MILESTONES);
+    const requirementsMarkdown = generateRequirementsMarkdown(REQUIREMENTS_COUNT, SLICE_ASSIGNMENTS);
+
+    writeFileSync(join(gsdDir, 'DECISIONS.md'), decisionsMarkdown);
+    writeFileSync(join(gsdDir, 'REQUIREMENTS.md'), requirementsMarkdown);
+    writeFileSync(join(gsdDir, 'milestones', 'M001', 'M001-ROADMAP.md'), ROADMAP_CONTENT);
+
+    const dbPath = join(gsdDir, 'test-lifecycle.db');
+
+    try {
+      // ── Step 2: Open file-backed DB + migrateFromMarkdown ──────────────
+      openDatabase(dbPath);
+      assertTrue(isDbAvailable(), 'lifecycle: DB is available after open');
+
+      const result = migrateFromMarkdown(base);
+
+      assertTrue(result.decisions === DECISIONS_COUNT, `lifecycle: imported ${result.decisions} decisions, expected ${DECISIONS_COUNT}`);
+      assertTrue(result.requirements === REQUIREMENTS_COUNT, `lifecycle: imported ${result.requirements} requirements, expected ${REQUIREMENTS_COUNT}`);
+      assertTrue(result.artifacts >= 1, `lifecycle: imported at least 1 artifact (got ${result.artifacts})`);
+
+      // Verify file-backed DB uses WAL
+      const adapter = _getAdapter()!;
+      const mode = adapter.prepare('PRAGMA journal_mode').get();
+      assertEq(mode?.['journal_mode'], 'wal', 'lifecycle: file-backed DB uses WAL mode');
+
+      // ── Step 3: Scoped queries — decisions by milestone ────────────────
+      const allDecisions = queryDecisions();
+      const m001Decisions = queryDecisions({ milestoneId: 'M001' });
+      const m002Decisions = queryDecisions({ milestoneId: 'M002' });
+
+      assertTrue(allDecisions.length === DECISIONS_COUNT, `lifecycle: all decisions count = ${DECISIONS_COUNT} (got ${allDecisions.length})`);
+      assertTrue(m001Decisions.length > 0, 'lifecycle: M001 decisions non-empty');
+      assertTrue(m002Decisions.length > 0, 'lifecycle: M002 decisions non-empty');
+      assertTrue(m001Decisions.length < allDecisions.length, 'lifecycle: M001 filtered count < total count');
+      assertTrue(m002Decisions.length < allDecisions.length, 'lifecycle: M002 filtered count < total count');
+      assertEq(m001Decisions.length + m002Decisions.length, allDecisions.length, 'lifecycle: M001 + M002 = total decisions');
+
+      // Verify scoping correctness
+      for (const d of m001Decisions) {
+        assertTrue(d.when_context.includes('M001'), `lifecycle: M001 decision ${d.id} has M001 in when_context`);
+      }
+      for (const d of m002Decisions) {
+        assertTrue(d.when_context.includes('M002'), `lifecycle: M002 decision ${d.id} has M002 in when_context`);
+      }
+
+      // ── Step 4: Scoped queries — requirements by slice ─────────────────
+      const allRequirements = queryRequirements();
+      const s01Requirements = queryRequirements({ sliceId: 'S01' });
+      const s04Requirements = queryRequirements({ sliceId: 'S04' });
+
+      assertTrue(allRequirements.length === REQUIREMENTS_COUNT, `lifecycle: all requirements count = ${REQUIREMENTS_COUNT} (got ${allRequirements.length})`);
+      assertTrue(s01Requirements.length > 0, 'lifecycle: S01 requirements non-empty');
+      assertTrue(s04Requirements.length > 0, 'lifecycle: S04 requirements non-empty');
+      assertTrue(s01Requirements.length < allRequirements.length, 'lifecycle: S01 filtered count < total count');
+
+      // ── Step 5: Format + token savings validation ──────────────────────
+      const formattedDecisions = formatDecisionsForPrompt(m001Decisions);
+      const formattedRequirements = formatRequirementsForPrompt(s01Requirements);
+
+      assertTrue(formattedDecisions.length > 0, 'lifecycle: formatted M001 decisions non-empty');
+      assertTrue(formattedRequirements.length > 0, 'lifecycle: formatted S01 requirements non-empty');
+      assertMatch(formattedDecisions, /\| D/, 'lifecycle: formatted decisions contains decision rows');
+      assertMatch(formattedRequirements, /### R\d+/, 'lifecycle: formatted requirements has headings');
+
+      // Token savings: scoped output vs full file content
+      const fullDecisionsContent = readFileSync(join(gsdDir, 'DECISIONS.md'), 'utf-8');
+      const fullRequirementsContent = readFileSync(join(gsdDir, 'REQUIREMENTS.md'), 'utf-8');
+      const dbScopedTotal = formattedDecisions.length + formattedRequirements.length;
+      const fullTotal = fullDecisionsContent.length + fullRequirementsContent.length;
+      const savingsPercent = ((fullTotal - dbScopedTotal) / fullTotal) * 100;
+
+      console.log(`  Token savings: ${savingsPercent.toFixed(1)}% (scoped: ${dbScopedTotal}, full: ${fullTotal})`);
+
+      assertTrue(dbScopedTotal > 0, 'lifecycle: scoped content non-empty');
+      assertTrue(dbScopedTotal < fullTotal, 'lifecycle: scoped content smaller than full content');
+      assertTrue(savingsPercent >= 30, `lifecycle: savings ≥30% (actual: ${savingsPercent.toFixed(1)}%)`);
+
+      // ── Step 6: Simulate content change → re-import ────────────────────
+      const newDecisionRow = `| D${DECISIONS_COUNT + 1} | M001/S01 | testing | new decision added after initial import | choice X | rationale Y | yes |`;
+      appendFileSync(join(gsdDir, 'DECISIONS.md'), '\n' + newDecisionRow + '\n');
+
+      const result2 = migrateFromMarkdown(base);
+      assertTrue(result2.decisions === DECISIONS_COUNT + 1, `lifecycle: re-import got ${result2.decisions} decisions, expected ${DECISIONS_COUNT + 1}`);
+
+      const afterReimport = queryDecisions();
+      assertTrue(afterReimport.length === DECISIONS_COUNT + 1, `lifecycle: DB has ${DECISIONS_COUNT + 1} decisions after re-import (got ${afterReimport.length})`);
+
+      // Verify the new decision is queryable
+      const newM001 = queryDecisions({ milestoneId: 'M001' });
+      const foundNew = newM001.some(d => d.id === `D${DECISIONS_COUNT + 1}`);
+      assertTrue(foundNew, `lifecycle: newly imported D${DECISIONS_COUNT + 1} found in M001 scope`);
+
+      // ── Step 7: saveDecisionToDb write-back + round-trip ───────────────
+      const saved = await saveDecisionToDb(
+        {
+          scope: 'M001/S01',
+          decision: 'integration test write-back decision',
+          choice: 'option Z',
+          rationale: 'proves round-trip fidelity',
+          when_context: 'M001/S01',
+        },
+        base,
+      );
+
+      assertTrue(typeof saved.id === 'string', 'lifecycle: saveDecisionToDb returned an id');
+      assertMatch(saved.id, /^D\d+$/, 'lifecycle: saved ID matches D### pattern');
+
+      // Query back from DB
+      const allAfterSave = queryDecisions();
+      const savedDecision = allAfterSave.find(d => d.id === saved.id);
+      assertTrue(savedDecision !== null && savedDecision !== undefined, `lifecycle: saved decision ${saved.id} found in DB`);
+      assertEq(savedDecision?.decision, 'integration test write-back decision', 'lifecycle: saved decision text matches');
+      assertEq(savedDecision?.choice, 'option Z', 'lifecycle: saved choice matches');
+
+      // Verify DECISIONS.md was regenerated with the new decision
+      const regeneratedMd = readFileSync(join(gsdDir, 'DECISIONS.md'), 'utf-8');
+      assertTrue(regeneratedMd.includes(saved.id), `lifecycle: regenerated DECISIONS.md contains ${saved.id}`);
+      assertTrue(regeneratedMd.includes('integration test write-back decision'), 'lifecycle: regenerated md contains write-back text');
+
+      // Round-trip: parse regenerated markdown back → verify field fidelity
+      const reparsed = parseDecisionsTable(regeneratedMd);
+      const reparsedSaved = reparsed.find(d => d.id === saved.id);
+      assertTrue(reparsedSaved !== undefined, `lifecycle: reparsed markdown contains ${saved.id}`);
+      assertEq(reparsedSaved?.choice, 'option Z', 'lifecycle: round-trip choice preserved');
+      assertEq(reparsedSaved?.rationale, 'proves round-trip fidelity', 'lifecycle: round-trip rationale preserved');
+
+      // ── Step 8: DB consistency — total count sanity ─────────────────────
+      const finalCount = queryDecisions().length;
+      // Original 14 + 1 re-import + 1 saveDecisionToDb = 16
+      assertTrue(finalCount === DECISIONS_COUNT + 2, `lifecycle: final DB count = ${DECISIONS_COUNT + 2} (got ${finalCount})`);
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});