@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdk/src/query/state.ts

@@ -0,0 +1,463 @@
+/**
+ * State query handlers — STATE.md loading, field extraction, and snapshots.
+ *
+ * Ported from sdd/bin/lib/state.cjs and core.cjs.
+ * Provides `state json` / `state.json` (rebuilt frontmatter JSON, `stateJson`), `state.get`
+ * (field/section extraction), and state-snapshot (structured snapshot).
+ *
+ * @example
+ * ```typescript
+ * import { stateJson, stateGet, stateSnapshot } from './state.js';
+ *
+ * const loaded = await stateJson([], '/project');
+ * // { data: { sdd_state_version: '1.0', milestone: 'v3.0', ... } }
+ *
+ * const field = await stateGet(['Status'], '/project');
+ * // { data: { Status: 'executing' } }
+ *
+ * const snap = await stateSnapshot([], '/project');
+ * // { data: { current_phase: '10', status: 'executing', decisions: [...], ... } }
+ * ```
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { extractFrontmatter, stripFrontmatter } from './frontmatter.js';
+import { planningPaths, escapeRegex } from './helpers.js';
+import {
+  computeProgressPercent,
+  normalizeProgressNumbers,
+  normalizeStateStatus,
+  shouldPreserveExistingProgress,
+  stateExtractField,
+} from './state-document.js';
+import { getMilestoneInfo, extractCurrentMilestone } from './roadmap.js';
+import type { QueryHandler } from './utils.js';
+
+// ─── Internal helpers ──────────────────────────────────────────────────────
+
+/**
+ * Build a filter function that checks if a phase directory belongs to the current milestone.
+ *
+ * Port of getMilestonePhaseFilter from core.cjs lines 1409-1442.
+ */
+export async function getMilestonePhaseFilter(projectDir: string, workstream?: string): Promise<((dirName: string) => boolean) & { phaseCount: number }> {
+  const milestonePhaseNums = new Set<string>();
+  try {
+    const roadmapContent = await readFile(planningPaths(projectDir, workstream).roadmap, 'utf-8');
+    const roadmap = await extractCurrentMilestone(roadmapContent, projectDir, workstream);
+    const phasePattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)\s*:/gi;
+    let m: RegExpExecArray | null;
+    while ((m = phasePattern.exec(roadmap)) !== null) {
+      milestonePhaseNums.add(m[1]);
+    }
+  } catch { /* intentionally empty */ }
+
+  if (milestonePhaseNums.size === 0) {
+    const passAllFn = (_dirName: string): boolean => true;
+    const passAll = passAllFn as typeof passAllFn & { phaseCount: number };
+    passAll.phaseCount = 0;
+    return passAll;
+  }
+
+  const normalized = new Set<string>(
+    [...milestonePhaseNums].map(n => (n.replace(/^0+/, '') || '0').toLowerCase())
+  );
+
+  const isDirInMilestone = ((dirName: string): boolean => {
+    // Try numeric match first
+    const m = dirName.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
+    if (m && normalized.has(m[1].toLowerCase())) return true;
+    // Try custom ID match
+    const customMatch = dirName.match(/^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*)/);
+    if (customMatch && normalized.has(customMatch[1].toLowerCase())) return true;
+    // #3600: project-code-prefixed directory (`CK-01-name`) against a
+    // numeric ROADMAP heading (`### Phase 1:`). Strip the same prefix
+    // shape `normalizePhaseName` recognises (`^[A-Z]{1,6}-(?=\d)`) and
+    // retry the numeric match. This runs AFTER the custom-ID match so
+    // a roadmap that uses `Phase PROJ-42:` continues to win via the
+    // existing custom-ID path; the strip-and-retry only fires when the
+    // milestone is keyed on the bare numeric form.
+    const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    if (stripped !== dirName) {
+      const sm = stripped.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
+      if (sm && normalized.has(sm[1].toLowerCase())) return true;
+    }
+    return false;
+  }) as ((dirName: string) => boolean) & { phaseCount: number };
+
+  isDirInMilestone.phaseCount = milestonePhaseNums.size;
+  return isDirInMilestone;
+}
+
+/**
+ * Build state frontmatter from STATE.md body content and disk scanning.
+ *
+ * Port of buildStateFrontmatter from state.cjs lines 650-760.
+ * HIGH complexity: extracts fields, scans disk, computes progress.
+ */
+export async function buildStateFrontmatter(
+  bodyContent: string,
+  projectDir: string,
+  workstream?: string,
+  options: { preserveExistingProgress?: boolean } = {},
+): Promise<Record<string, unknown>> {
+  const currentPhase = stateExtractField(bodyContent, 'Current Phase');
+  const currentPhaseName = stateExtractField(bodyContent, 'Current Phase Name');
+  const currentPlan = stateExtractField(bodyContent, 'Current Plan');
+  const totalPhasesRaw = stateExtractField(bodyContent, 'Total Phases');
+  const totalPlansRaw = stateExtractField(bodyContent, 'Total Plans in Phase');
+  const status = stateExtractField(bodyContent, 'Status');
+  const progressRaw = stateExtractField(bodyContent, 'Progress');
+  const lastActivity = stateExtractField(bodyContent, 'Last Activity');
+  const stoppedAt = stateExtractField(bodyContent, 'Stopped At') || stateExtractField(bodyContent, 'Stopped at');
+  const pausedAt = stateExtractField(bodyContent, 'Paused At');
+
+  // Bug #2613: read existing STATE.md frontmatter as preservation backstop.
+  // The write path through `readModifyWriteStateMd` strips frontmatter before
+  // invoking the modifier, so callers of `buildStateFrontmatter` only see the
+  // body. Without reading frontmatter here, status defaults to 'unknown' when
+  // body has no Status field, and progress is stomped to 0/0 when the current
+  // milestone's phase directories have been archived. Matches the #2495 READ
+  // pattern: STATE.md is authoritative, re-derive only when absent.
+  let existingFm: Record<string, unknown> = {};
+  try {
+    const raw = await readFile(planningPaths(projectDir, workstream).state, 'utf-8');
+    existingFm = extractFrontmatter(raw);
+  } catch { /* STATE.md missing on first write — no preservation needed */ }
+
+  let milestone: string | null = null;
+  let milestoneName: string | null = null;
+  try {
+    const info = await getMilestoneInfo(projectDir, workstream);
+    milestone = info.version;
+    milestoneName = info.name;
+  } catch { /* intentionally empty */ }
+
+  let totalPhases: number | null = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
+  let completedPhases: number | null = null;
+  let totalPlans: number | null = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+  let completedPlans: number | null = null;
+
+  try {
+    const phasesDir = planningPaths(projectDir, workstream).phases;
+    const isDirInMilestone = await getMilestonePhaseFilter(projectDir, workstream);
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const phaseDirs = entries
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+      .filter(isDirInMilestone);
+
+    let diskTotalPlans = 0;
+    let diskTotalSummaries = 0;
+    let diskCompletedPhases = 0;
+
+    for (const dir of phaseDirs) {
+      const files = await readdir(join(phasesDir, dir));
+      const plans = files.filter(f => /-PLAN\.md$/i.test(f)).length;
+      const summaries = files.filter(f => /-SUMMARY\.md$/i.test(f)).length;
+      diskTotalPlans += plans;
+      diskTotalSummaries += summaries;
+      if (plans > 0 && summaries >= plans) diskCompletedPhases++;
+    }
+
+    totalPhases = isDirInMilestone.phaseCount > 0
+      ? Math.max(phaseDirs.length, isDirInMilestone.phaseCount)
+      : phaseDirs.length;
+    completedPhases = diskCompletedPhases;
+    totalPlans = diskTotalPlans;
+    completedPlans = diskTotalSummaries;
+  } catch { /* intentionally empty */ }
+
+  // Derive percent from disk counts (ground truth)
+  let progressPercent = computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases);
+  if (progressPercent === null && progressRaw) {
+    const pctMatch = progressRaw.match(/(\d+)%/);
+    if (pctMatch) progressPercent = parseInt(pctMatch[1], 10);
+  }
+
+  // Normalize status
+  let normalizedStatus = normalizeStateStatus(status, pausedAt);
+
+  // Bug #2613: status preservation — if body has no Status field and existing
+  // frontmatter has a non-unknown status, prefer existing.
+  if (normalizedStatus === 'unknown' && typeof existingFm.status === 'string' && existingFm.status && existingFm.status !== 'unknown') {
+    normalizedStatus = existingFm.status;
+  }
+
+  const fm: Record<string, unknown> = { sdd_state_version: '1.0' };
+
+  if (milestone) fm.milestone = milestone;
+  if (milestoneName) fm.milestone_name = milestoneName;
+  if (currentPhase) fm.current_phase = currentPhase;
+  if (currentPhaseName) fm.current_phase_name = currentPhaseName;
+  if (currentPlan) fm.current_plan = currentPlan;
+  fm.status = normalizedStatus;
+  if (stoppedAt) fm.stopped_at = stoppedAt;
+  if (pausedAt) fm.paused_at = pausedAt;
+  fm.last_updated = new Date().toISOString();
+  if (lastActivity) fm.last_activity = lastActivity;
+
+  const progress: Record<string, unknown> = {};
+  if (totalPhases !== null) progress.total_phases = totalPhases;
+  if (completedPhases !== null) progress.completed_phases = completedPhases;
+  if (totalPlans !== null) progress.total_plans = totalPlans;
+  if (completedPlans !== null) progress.completed_plans = completedPlans;
+  if (progressPercent !== null) progress.percent = progressPercent;
+  if (Object.keys(progress).length > 0) fm.progress = progress;
+
+  // Bug #2613: progress preservation — when disk scan returns zero counts
+  // (archived/shipped milestone) and existing frontmatter has non-zero counts,
+  // prefer existing. Legitimate mid-milestone updates see non-zero disk counts
+  // and fall through, keeping disk as ground truth.
+  const existingProgress = existingFm.progress as Record<string, unknown> | undefined;
+  if (options.preserveExistingProgress !== false && existingProgress && typeof existingProgress === 'object') {
+    const derivedTotalPlans = Number(progress.total_plans ?? 0);
+    const derivedCompletedPlans = Number(progress.completed_plans ?? 0);
+    const existingTotalPlans = Number(existingProgress.total_plans ?? 0);
+    if (derivedTotalPlans === 0 && derivedCompletedPlans === 0 && existingTotalPlans > 0) {
+      fm.progress = normalizeProgressNumbers(existingProgress);
+    }
+  }
+
+  return fm;
+}
+
+// ─── Exported handlers ─────────────────────────────────────────────────────
+
+/**
+ * Query handler for `state json` / `state.json` (CJS `cmdStateJson`).
+ *
+ * Reads STATE.md, rebuilds frontmatter from body + disk scanning.
+ * Returns cached frontmatter-only fields (stopped_at, paused_at) when not in body.
+ *
+ * Port of cmdStateJson from state.cjs lines 872-901.
+ *
+ * @param args - Unused
+ * @param projectDir - Project root directory
+ * @returns QueryResult with rebuilt state frontmatter
+ */
+export const stateJson: QueryHandler = async (_args, projectDir, workstream) => {
+  const statePath = planningPaths(projectDir, workstream).state;
+
+  let content: string;
+  try {
+    content = await readFile(statePath, 'utf-8');
+  } catch {
+    return { data: { error: 'STATE.md not found' } };
+  }
+
+  const existingFm = extractFrontmatter(content);
+  const body = stripFrontmatter(content);
+
+  // Always rebuild from body + disk so progress reflects current state
+  const built = await buildStateFrontmatter(body, projectDir, workstream);
+
+  // Preserve frontmatter-only fields that cannot be recovered from body
+  if (existingFm && existingFm.stopped_at && !built.stopped_at) {
+    built.stopped_at = existingFm.stopped_at;
+  }
+  if (existingFm && existingFm.paused_at && !built.paused_at) {
+    built.paused_at = existingFm.paused_at;
+  }
+
+  // Preserve existing non-unknown status when body-derived is 'unknown'
+  if (built.status === 'unknown' && existingFm && existingFm.status && existingFm.status !== 'unknown') {
+    built.status = existingFm.status;
+  }
+  // Read-side projection: preserve curated cross-milestone aggregates when the
+  // disk scan sees only a narrower realized subset (#3242 Bug A). Mutation sync
+  // remains disk-authoritative when it sees non-zero counts.
+  if (existingFm && shouldPreserveExistingProgress(existingFm.progress, built.progress)) {
+    built.progress = normalizeProgressNumbers(existingFm.progress);
+  }
+
+  return { data: built };
+};
+
+/**
+ * Query handler for state.get.
+ *
+ * Reads STATE.md and extracts a specific field or section.
+ * Returns full content when no field specified.
+ *
+ * Port of cmdStateGet from state.cjs lines 72-113.
+ *
+ * @param args - args[0] is optional field/section name
+ * @param projectDir - Project root directory
+ * @returns QueryResult with field value or full content
+ */
+export const stateGet: QueryHandler = async (args, projectDir, workstream) => {
+  const statePath = planningPaths(projectDir, workstream).state;
+
+  let content: string;
+  try {
+    content = await readFile(statePath, 'utf-8');
+  } catch {
+    return { data: { error: 'STATE.md not found' } };
+  }
+
+  const section = args[0];
+  if (!section) {
+    return { data: { content } };
+  }
+
+  const fieldEscaped = escapeRegex(section);
+
+  // Check for **field:** value (bold format)
+  const boldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, 'i');
+  const boldMatch = content.match(boldPattern);
+  if (boldMatch) {
+    return { data: { [section]: boldMatch[1].trim() } };
+  }
+
+  // Check for field: value (plain format)
+  const plainPattern = new RegExp(`^${fieldEscaped}:\\s*(.*)`, 'im');
+  const plainMatch = content.match(plainPattern);
+  if (plainMatch) {
+    return { data: { [section]: plainMatch[1].trim() } };
+  }
+
+  // Check for ## Section
+  const sectionPattern = new RegExp(`##\\s*${fieldEscaped}\\s*\n([\\s\\S]*?)(?=\\n##|$)`, 'i');
+  const sectionMatch = content.match(sectionPattern);
+  if (sectionMatch) {
+    return { data: { [section]: sectionMatch[1].trim() } };
+  }
+
+  return { data: { error: `Section or field "${section}" not found` } };
+};
+
+/**
+ * Query handler for state-snapshot.
+ *
+ * Returns a structured snapshot of project state with decisions, blockers, and session.
+ *
+ * Port of cmdStateSnapshot from state.cjs lines 546-641.
+ *
+ * @param args - Unused
+ * @param projectDir - Project root directory
+ * @returns QueryResult with structured snapshot
+ */
+export const stateSnapshot: QueryHandler = async (_args, projectDir, workstream) => {
+  const statePath = planningPaths(projectDir, workstream).state;
+
+  let content: string;
+  try {
+    content = await readFile(statePath, 'utf-8');
+  } catch {
+    return { data: { error: 'STATE.md not found' } };
+  }
+
+  // Bug #3265: prefer YAML frontmatter for canonical scalar fields so that a
+  // body table cell containing **Status:** Y cannot shadow the authoritative
+  // frontmatter value.  Matches the precedent set by buildStateFrontmatter
+  // (see state.ts:92 Bug #2613 comment).
+  const fm = extractFrontmatter(content);
+  const body = stripFrontmatter(content);
+
+  // Helper: return frontmatter scalar value when present and non-empty.
+  // Accepts strings, numbers, and booleans — coercing non-string primitives to
+  // their string representation so callers always receive string | null.
+  // Returns null for missing, null/undefined, or empty-after-trim values so
+  // the caller falls back to body extractor (covers STATE.md files that have
+  // no frontmatter at all, or frontmatter that lacks the specific key).
+  const fmScalar = (key: string): string | null => {
+    const v = fm[key];
+    if (v === null || v === undefined) return null;
+    if (typeof v === 'string') return v.trim() || null;
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    return null;
+  };
+
+  // Extract basic fields — frontmatter keys take precedence over body
+  const currentPhase = fmScalar('current_phase') ?? stateExtractField(body, 'Current Phase');
+  const currentPhaseName = fmScalar('current_phase_name') ?? stateExtractField(body, 'Current Phase Name');
+  const totalPhasesRaw = fmScalar('total_phases') ?? stateExtractField(body, 'Total Phases');
+  const currentPlan = fmScalar('current_plan') ?? stateExtractField(body, 'Current Plan');
+  const totalPlansRaw = fmScalar('total_plans_in_phase') ?? stateExtractField(body, 'Total Plans in Phase');
+  const status = fmScalar('status') ?? stateExtractField(body, 'Status');
+  const progressRaw = fmScalar('progress') ?? stateExtractField(body, 'Progress');
+  const lastActivity = fmScalar('last_activity') ?? stateExtractField(body, 'Last Activity');
+  const lastActivityDesc = fmScalar('last_activity_desc') ?? stateExtractField(body, 'Last Activity Description');
+  const pausedAt = fmScalar('paused_at') ?? stateExtractField(body, 'Paused At');
+
+  // Parse numeric fields
+  const totalPhases = totalPhasesRaw ? parseInt(totalPhasesRaw, 10) : null;
+  const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+  // Match sdd-tools `cmdStateSnapshot` (state.cjs): parseInt(progressRaw.replace('%',''), 10) — NaN → null
+  let progressPercent: number | null = null;
+  if (progressRaw) {
+    const n = parseInt(progressRaw.replace(/%/g, ''), 10);
+    progressPercent = Number.isFinite(n) ? n : null;
+  }
+
+  // Extract decisions table
+  const decisions: Array<{ phase: string; summary: string; rationale: string }> = [];
+  const decisionsMatch = body.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
+  if (decisionsMatch) {
+    const tableBody = decisionsMatch[1];
+    const rows = tableBody.trim().split('\n').filter(r => r.includes('|'));
+    for (const row of rows) {
+      const cells = row.split('|').map(c => c.trim()).filter(Boolean);
+      if (cells.length >= 3) {
+        decisions.push({
+          phase: cells[0],
+          summary: cells[1],
+          rationale: cells[2],
+        });
+      }
+    }
+  }
+
+  // Extract blockers list
+  const blockers: string[] = [];
+  const blockersMatch = body.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
+  if (blockersMatch) {
+    const blockersSection = blockersMatch[1];
+    const items = blockersSection.match(/^-\s+(.+)$/gm) || [];
+    for (const item of items) {
+      blockers.push(item.replace(/^-\s+/, '').trim());
+    }
+  }
+
+  // Extract session info
+  const session: { last_date: string | null; stopped_at: string | null; resume_file: string | null } = {
+    last_date: null,
+    stopped_at: null,
+    resume_file: null,
+  };
+
+  const sessionMatch = body.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
+  if (sessionMatch) {
+    const sessionSection = sessionMatch[1];
+    const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i)
+      || sessionSection.match(/^Last Date:\s*(.+)/im);
+    const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i)
+      || sessionSection.match(/^Stopped At:\s*(.+)/im);
+    const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i)
+      || sessionSection.match(/^Resume File:\s*(.+)/im);
+
+    if (lastDateMatch) session.last_date = lastDateMatch[1].trim();
+    if (stoppedAtMatch) session.stopped_at = stoppedAtMatch[1].trim();
+    if (resumeFileMatch) session.resume_file = resumeFileMatch[1].trim();
+  }
+
+  const result = {
+    current_phase: currentPhase,
+    current_phase_name: currentPhaseName,
+    total_phases: totalPhases,
+    current_plan: currentPlan,
+    total_plans_in_phase: totalPlansInPhase,
+    status,
+    progress_percent: progressPercent,
+    last_activity: lastActivity,
+    last_activity_desc: lastActivityDesc,
+    decisions,
+    blockers,
+    paused_at: pausedAt,
+    session,
+  };
+
+  return { data: result };
+};

package/sdk/src/query/sub-repos-root.integration.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Regression: issue #2623 — `sdd-sdk query` must resolve the parent
+ * `.planning/` root when invoked from a `sub_repos`-listed child repo.
+ *
+ * Exercises the end-to-end path: findProjectRoot(startDir) -> registry dispatch
+ * of `init.new-milestone`, and asserts the handler reports the parent workspace
+ * as `project_root` with `project_exists: true`.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { findProjectRoot } from './helpers.js';
+import { createRegistry } from './index.js';
+
+describe('issue #2623 — sub_repos project-root resolution through query dispatch', () => {
+  let workspace: string;
+  let appDir: string;
+
+  beforeEach(async () => {
+    workspace = await mkdtemp(join(tmpdir(), 'sdd-2623-'));
+    await mkdir(join(workspace, '.planning'), { recursive: true });
+    await mkdir(join(workspace, '.planning', 'phases'), { recursive: true });
+    await writeFile(
+      join(workspace, '.planning', 'config.json'),
+      JSON.stringify({ sub_repos: ['app'] }),
+      'utf-8',
+    );
+    await writeFile(join(workspace, '.planning', 'PROJECT.md'), '# Project\n', 'utf-8');
+    await writeFile(
+      join(workspace, '.planning', 'ROADMAP.md'),
+      '# Roadmap\n\n## Milestone v1.0.0 — Bootstrap\n',
+      'utf-8',
+    );
+    await writeFile(
+      join(workspace, '.planning', 'STATE.md'),
+      '---\ncurrent_phase: 01-bootstrap\n---\n',
+      'utf-8',
+    );
+
+    appDir = join(workspace, 'app');
+    await mkdir(join(appDir, '.git'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(workspace, { recursive: true, force: true });
+  });
+
+  it('findProjectRoot(app) resolves to the parent workspace that owns .planning/', () => {
+    expect(findProjectRoot(appDir)).toBe(workspace);
+  });
+
+  it('init.new-milestone dispatched with resolved root reports project_exists:true', async () => {
+    // Simulate the CLI path: user starts inside the sub_repo.
+    const resolved = findProjectRoot(appDir);
+    expect(resolved).toBe(workspace);
+
+    const registry = createRegistry();
+    const result = await registry.dispatch('init.new-milestone', [], resolved, undefined);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.project_exists).toBe(true);
+    expect(data.roadmap_exists).toBe(true);
+    expect(data.state_exists).toBe(true);
+    expect(data.project_root).toBe(workspace);
+  });
+
+  it('without findProjectRoot walk-up, the same handler reports project_exists:false (baseline)', async () => {
+    // Proves the walk-up is load-bearing — invoking from the child directly
+    // reproduces the bug described in #2623.
+    const registry = createRegistry();
+    const result = await registry.dispatch('init.new-milestone', [], appDir, undefined);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.project_exists).toBe(false);
+    expect(data.project_root).toBe(appDir);
+  });
+});

package/sdk/src/query/summary.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Tests for summary / history digest handlers.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { summaryExtract, historyDigest } from './summary.js';
+
+describe('summaryExtract', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'sdd-sum-'));
+    await mkdir(join(tmpDir, '.planning', 'phases', '01-x'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns structured fields from SUMMARY frontmatter (CJS parity)', async () => {
+    const rel = '.planning/phases/01-x/01-SUMMARY.md';
+    await writeFile(
+      join(tmpDir, '.planning', 'phases', '01-x', '01-SUMMARY.md'),
+      [
+        '---',
+        'phase: "01"',
+        'name: Test Phase',
+        'one-liner: From YAML',
+        'key-files:',
+        '  - a.ts',
+        'key-decisions:',
+        '  - "Choice: because reasons"',
+        'patterns-established:',
+        '  - "Pattern one"',
+        'tech-stack:',
+        '  added:',
+        '    - vitest',
+        'requirements-completed:',
+        '  - R1',
+        '---',
+        '',
+        '# Summary',
+        '',
+        '**Body one-liner ignored when FM has one-liner**',
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+    const r = await summaryExtract([rel], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.path).toBe(rel);
+    expect(data.one_liner).toBe('From YAML');
+    expect(data.key_files).toEqual(['a.ts']);
+    expect(data.requirements_completed).toEqual(['R1']);
+    expect(Array.isArray(data.decisions)).toBe(true);
+  });
+
+  it('filters with --fields', async () => {
+    const rel = '.planning/phases/01-x/01-SUMMARY.md';
+    await writeFile(
+      join(tmpDir, '.planning', 'phases', '01-x', '01-SUMMARY.md'),
+      ['---', 'phase: "01"', 'one-liner: X', 'key-files:', '  - z.ts', '---', ''].join('\n'),
+      'utf-8',
+    );
+    const r = await summaryExtract([rel, '--fields', 'path,one_liner'], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(Object.keys(data).sort()).toEqual(['one_liner', 'path'].sort());
+    expect(data.one_liner).toBe('X');
+  });
+});
+
+describe('historyDigest', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'sdd-hist-'));
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns digest object for project without phases', async () => {
+    const r = await historyDigest([], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.phases).toEqual({});
+    expect(data.decisions).toEqual([]);
+    expect(data.tech_stack).toEqual([]);
+  });
+});