@jokerized/getresearchdone 0.4.1

package/lib/commands/plan-phase.ts

@@ -0,0 +1,375 @@
+'use strict';
+
+/**
+ * GRD Commands/PlanPhase — multi-candidate plan scaffolding (v0.4 Phase 2).
+ *
+ * Parses a planner subprocess's marker-fenced output and writes N
+ * PLAN-i.md files to the phase directory atomically. Fail-closed by
+ * default: if the planner returned a count other than N, NO files are
+ * written. Pass --allow-partial-candidates to write what was found and
+ * warn loudly.
+ *
+ * Marker format the planner is told to emit (in commands/plan-phase.md
+ * <multi_candidate> block):
+ *
+ *   <<<PLAN-1>>>
+ *   ... full plan content (YAML frontmatter + body) ...
+ *   <<</PLAN-1>>>
+ *   <<<PLAN-2>>>
+ *   ...
+ *   <<</PLAN-2>>>
+ *
+ * When N === 1, this command is a no-op for the planner prompt
+ * (commands/plan-phase.md suppresses the <multi_candidate> block) and
+ * the planner writes a bare PLAN.md via its Write tool, as in v0.3.x.
+ *
+ * Public surface:
+ *   - parsePlanCandidates(text, expectedN) — pure parser
+ *   - writePlanCandidates(phaseDir, blocks) — atomic batched writer
+ *   - cmdPlanPhase(cwd, phaseNum, opts, raw) — CLI entry
+ *
+ * Exit codes:
+ *   0 — success (N files written)
+ *   1 — validation failure (count mismatch, marker parse error)
+ *   2 — invocation error (phase not found, input unreadable)
+ */
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+
+const {
+  findPhaseDir,
+  getMilestoneInfo,
+  loadConfig,
+  resolveEffortKnob,
+  output,
+  error,
+}: {
+  findPhaseDir: (phasesDir: string, phaseArg: string) => string | null;
+  getMilestoneInfo: (cwd: string) => { version: string };
+  loadConfig: (cwd: string) => import('../types').GrdConfig;
+  resolveEffortKnob: (
+    config: import('../types').GrdConfig,
+    knob: import('../types').EffortKnobName
+  ) => number;
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+} = require('../utils');
+
+const {
+  atomicWriteFileSync,
+}: {
+  atomicWriteFileSync: (filePath: string, data: string) => void;
+} = require('../autopilot-waves');
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface PlanCandidateBlock {
+  index: number;
+  content: string;
+}
+
+export type ParseResult =
+  | { ok: true; blocks: PlanCandidateBlock[] }
+  | { ok: false; reason: string; foundIndices: number[] };
+
+export interface WriteResult {
+  written: string[];
+}
+
+export interface PlanPhaseOptions {
+  candidates: number;
+  inputFile?: string;
+  allowPartial?: boolean;
+}
+
+// ─── Marker parsing ────────────────────────────────────────────────────────
+
+const OPEN_RE = /^<<<PLAN-(\d+)>>>\s*$/;
+const CLOSE_RE = /^<<<\/PLAN-(\d+)>>>\s*$/;
+
+/**
+ * Parse marker-fenced PLAN blocks from planner output.
+ *
+ * Returns ok: true with sorted unique blocks when the count of valid
+ * <<<PLAN-i>>>...<<</PLAN-i>>> pairs equals expectedN AND the indices
+ * cover 1..expectedN exactly. Anything else returns ok: false with a
+ * reason and the list of indices that were found (for diagnostics).
+ *
+ * Rejects: duplicate indices, mismatched open/close pairs, nested
+ * blocks, blocks with index 0 or > expectedN.
+ */
+export function parsePlanCandidates(text: string, expectedN: number): ParseResult {
+  if (expectedN < 1) {
+    return { ok: false, reason: 'expectedN must be >= 1', foundIndices: [] };
+  }
+
+  const lines: string[] = text.split('\n');
+  const blocks: PlanCandidateBlock[] = [];
+  let currentIndex: number | null = null;
+  let currentBuffer: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line: string = lines[i];
+    const openMatch = line.match(OPEN_RE);
+    const closeMatch = line.match(CLOSE_RE);
+
+    if (openMatch) {
+      if (currentIndex !== null) {
+        return {
+          ok: false,
+          reason: `nested <<<PLAN-${openMatch[1]}>>> opened while <<<PLAN-${currentIndex}>>> still open (line ${i + 1})`,
+          foundIndices: blocks.map((b) => b.index),
+        };
+      }
+      currentIndex = parseInt(openMatch[1], 10);
+      currentBuffer = [];
+    } else if (closeMatch) {
+      const closeIndex: number = parseInt(closeMatch[1], 10);
+      if (currentIndex === null) {
+        return {
+          ok: false,
+          reason: `unexpected <<</PLAN-${closeIndex}>>> with no matching open (line ${i + 1})`,
+          foundIndices: blocks.map((b) => b.index),
+        };
+      }
+      if (closeIndex !== currentIndex) {
+        return {
+          ok: false,
+          reason: `mismatched <<</PLAN-${closeIndex}>>> for open <<<PLAN-${currentIndex}>>> (line ${i + 1})`,
+          foundIndices: blocks.map((b) => b.index),
+        };
+      }
+      blocks.push({ index: currentIndex, content: currentBuffer.join('\n') });
+      currentIndex = null;
+      currentBuffer = [];
+    } else if (currentIndex !== null) {
+      currentBuffer.push(line);
+    }
+  }
+
+  if (currentIndex !== null) {
+    return {
+      ok: false,
+      reason: `<<<PLAN-${currentIndex}>>> never closed`,
+      foundIndices: blocks.map((b) => b.index),
+    };
+  }
+
+  const indices: number[] = blocks.map((b) => b.index);
+
+  if (blocks.length !== expectedN) {
+    return {
+      ok: false,
+      reason: `expected ${expectedN} PLAN block(s), found ${blocks.length}`,
+      foundIndices: indices,
+    };
+  }
+
+  const seen: Set<number> = new Set();
+  for (const idx of indices) {
+    if (seen.has(idx)) {
+      return { ok: false, reason: `duplicate PLAN-${idx} block`, foundIndices: indices };
+    }
+    seen.add(idx);
+  }
+
+  for (let i = 1; i <= expectedN; i++) {
+    if (!seen.has(i)) {
+      return {
+        ok: false,
+        reason: `missing PLAN-${i} block (expected 1..${expectedN})`,
+        foundIndices: indices,
+      };
+    }
+  }
+
+  blocks.sort((a, b) => a.index - b.index);
+  return { ok: true, blocks };
+}
+
+// ─── File writing ──────────────────────────────────────────────────────────
+
+/**
+ * Write each block to `<phaseDir>/PLAN-<i>.md` atomically. Writes are
+ * batched: every file's content is materialized to disk via
+ * atomicWriteFileSync. Callers are expected to have already validated
+ * that the phase directory exists.
+ */
+export function writePlanCandidates(
+  phaseDir: string,
+  blocks: PlanCandidateBlock[]
+): WriteResult {
+  if (!fs.existsSync(phaseDir)) {
+    throw new Error(`phase directory not found: ${phaseDir}`);
+  }
+  const written: string[] = [];
+  for (const block of blocks) {
+    const filename: string = `PLAN-${block.index}.md`;
+    const filePath: string = path.join(phaseDir, filename);
+    atomicWriteFileSync(filePath, block.content);
+    written.push(filePath);
+  }
+  return { written };
+}
+
+// ─── CLI entry ─────────────────────────────────────────────────────────────
+
+interface CmdResult {
+  phase: string;
+  phaseDir: string;
+  candidates: number;
+  blocksFound: number;
+  written: string[];
+  ok: boolean;
+  reason?: string;
+}
+
+/**
+ * `gd plan-phase <N> --candidates K [--input FILE] [--allow-partial-candidates]`
+ *
+ * Reads planner output text from --input (or stdin if no --input given),
+ * parses K marker-fenced PLAN blocks, and writes them as PLAN-1.md ...
+ * PLAN-K.md in the phase directory. Fail-closed on count mismatch
+ * unless --allow-partial-candidates is set.
+ *
+ * Default candidate count resolves from
+ * `resolveEffortKnob(config, 'candidates_per_plan_phase')` per
+ * v0.4 Phase 1.
+ */
+export function cmdPlanPhase(
+  cwd: string,
+  phaseNum: string,
+  opts: PlanPhaseOptions,
+  raw: boolean
+): void {
+  const milestone = getMilestoneInfo(cwd);
+  const phasesDir: string = path.join(
+    cwd,
+    '.planning',
+    'milestones',
+    milestone.version,
+    'phases'
+  );
+  const phaseDirName: string | null = findPhaseDir(phasesDir, phaseNum);
+  if (!phaseDirName) {
+    error(`phase ${phaseNum} not found under ${phasesDir}`);
+  }
+  const phaseDir: string = path.join(phasesDir, phaseDirName as string);
+
+  // Resolve N: explicit --candidates wins; else fall back to effort knob.
+  let expectedN: number = opts.candidates;
+  if (!Number.isInteger(expectedN) || expectedN < 1) {
+    const cfg = loadConfig(cwd);
+    expectedN = resolveEffortKnob(cfg, 'candidates_per_plan_phase');
+  }
+  if (expectedN > 9) {
+    error(`--candidates ${expectedN} exceeds the v0.4 sanity bound of 9`);
+  }
+
+  // Read planner output: --input file path, or stdin if absent.
+  const plannerText: string = readPlannerInput(opts.inputFile);
+
+  const parsed: ParseResult = parsePlanCandidates(plannerText, expectedN);
+
+  if (!parsed.ok && !opts.allowPartial) {
+    const result: CmdResult = {
+      phase: phaseNum,
+      phaseDir,
+      candidates: expectedN,
+      blocksFound: parsed.foundIndices.length,
+      written: [],
+      ok: false,
+      reason: parsed.reason,
+    };
+    // Fail-closed: emit JSON / raw on stdout so the caller can see the
+    // structured failure, then exit with code 1.
+    if (raw) {
+      process.stdout.write(`plan-candidates failed: ${parsed.reason}\n`);
+    } else {
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+    process.exit(1);
+  }
+
+  // --allow-partial-candidates: extract whatever valid blocks we can.
+  let blocks: PlanCandidateBlock[];
+  if (parsed.ok) {
+    blocks = parsed.blocks;
+  } else {
+    // Re-parse with relaxed validation: any well-formed block counts.
+    blocks = extractPartialBlocks(plannerText);
+    process.stderr.write(
+      `Warning: --allow-partial-candidates active. Planner returned ${blocks.length} valid block(s) instead of ${expectedN}. Writing what was found.\n`
+    );
+  }
+
+  const writeRes: WriteResult = writePlanCandidates(phaseDir, blocks);
+
+  const result: CmdResult = {
+    phase: phaseNum,
+    phaseDir,
+    candidates: expectedN,
+    blocksFound: blocks.length,
+    written: writeRes.written,
+    ok: true,
+  };
+  output(result, raw, writeRes.written.join('\n'));
+}
+
+/**
+ * Read planner output text from an explicit file or stdin. error() is
+ * `never` so callers can treat the return as definitely-string.
+ */
+function readPlannerInput(inputFile: string | undefined): string {
+  if (inputFile) {
+    try {
+      return fs.readFileSync(inputFile, 'utf-8');
+    } catch (e) {
+      error(`failed to read --input ${inputFile}: ${(e as Error).message}`);
+      throw new Error('unreachable', { cause: e });
+    }
+  }
+  try {
+    return fs.readFileSync(0, 'utf-8');
+  } catch (e) {
+    error(`failed to read planner output from stdin: ${(e as Error).message}`);
+    throw new Error('unreachable', { cause: e });
+  }
+}
+
+/**
+ * Extract every well-formed <<<PLAN-i>>>...<<</PLAN-i>>> block without
+ * enforcing count/index coverage. Used only on the
+ * --allow-partial-candidates path.
+ */
+function extractPartialBlocks(text: string): PlanCandidateBlock[] {
+  const lines: string[] = text.split('\n');
+  const blocks: PlanCandidateBlock[] = [];
+  let currentIndex: number | null = null;
+  let buffer: string[] = [];
+
+  for (const line of lines) {
+    const openMatch = line.match(OPEN_RE);
+    const closeMatch = line.match(CLOSE_RE);
+    if (openMatch) {
+      currentIndex = parseInt(openMatch[1], 10);
+      buffer = [];
+    } else if (closeMatch) {
+      if (currentIndex !== null && parseInt(closeMatch[1], 10) === currentIndex) {
+        blocks.push({ index: currentIndex, content: buffer.join('\n') });
+      }
+      currentIndex = null;
+      buffer = [];
+    } else if (currentIndex !== null) {
+      buffer.push(line);
+    }
+  }
+  return blocks;
+}
+
+module.exports = {
+  parsePlanCandidates,
+  writePlanCandidates,
+  cmdPlanPhase,
+};

package/lib/commands/progress.ts

@@ -0,0 +1,319 @@
+'use strict';
+
+/** GRD Commands/Progress -- Project progress rendering in json, table, and bar formats */
+
+
+import type { MilestoneInfo } from '../types';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  output,
+  getMilestoneInfo,
+}: {
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  getMilestoneInfo: (cwd: string) => MilestoneInfo;
+} = require('../utils');
+const {
+  phasesDir: getPhasesDirPath,
+  planningDir: getPlanningDir,
+}: {
+  phasesDir: (cwd: string) => string;
+  planningDir: (cwd: string) => string;
+} = require('../paths');
+const {
+  readCachedState,
+}: {
+  readCachedState: (statePath: string) => string | null;
+} = require('./phase-info');
+const {
+  loadConfig,
+}: {
+  loadConfig: (cwd: string) => { survey?: { staleness_days?: number }; [key: string]: unknown };
+} = require('../utils');
+
+// ─── Domain Types ────────────────────────────────────────────────────────────
+
+interface PhaseProgress {
+  number: string;
+  name: string;
+  plans: number;
+  summaries: number;
+  status: string;
+}
+
+// ─── Progress Render ─────────────────────────────────────────────────────────
+
+/** Render project progress in the specified format (json, table, or bar). */
+function cmdProgressRender(cwd: string, format: string, raw: boolean): void {
+  const phasesDir = getPhasesDirPath(cwd) as string;
+  const milestone = getMilestoneInfo(cwd);
+  const phases: PhaseProgress[] = [];
+  let totalPlans = 0;
+  let totalSummaries = 0;
+
+  try {
+    const dirs: string[] = fs
+      .readdirSync(phasesDir, { withFileTypes: true })
+      .filter((e: { isDirectory: () => boolean }) => e.isDirectory())
+      .map((e: { name: string }) => e.name)
+      .sort((a: string, b: string) => {
+        const aNum = parseFloat((a.match(/^(\d+(?:\.\d+)?)/) || ['0'])[1] || '0');
+        const bNum = parseFloat((b.match(/^(\d+(?:\.\d+)?)/) || ['0'])[1] || '0');
+        return aNum - bNum;
+      });
+
+    for (const dir of dirs) {
+      const dm = dir.match(/^(\d+(?:\.\d+)?)-?(.*)/);
+      const phaseNum = dm ? dm[1] : dir;
+      const phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
+      const phaseFiles: string[] = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(
+        (f: string) => f.endsWith('-PLAN.md') || f === 'PLAN.md'
+      ).length;
+      const summaries = phaseFiles.filter(
+        (f: string) => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md'
+      ).length;
+      totalPlans += plans;
+      totalSummaries += summaries;
+
+      let status: string;
+      if (plans === 0) status = 'Pending';
+      else if (summaries >= plans) status = 'Complete';
+      else if (summaries > 0) status = 'In Progress';
+      else status = 'Planned';
+
+      phases.push({ number: phaseNum, name: phaseName, plans, summaries, status });
+    }
+  } catch {
+    /* phases dir may not exist */
+  }
+
+  const percent = totalPlans > 0 ? Math.round((totalSummaries / totalPlans) * 100) : 0;
+
+  // Check research file staleness
+  let stalenessDays = 30;
+  try {
+    const cfg = loadConfig(cwd);
+    if (cfg.survey && typeof cfg.survey.staleness_days === 'number') {
+      stalenessDays = cfg.survey.staleness_days;
+    }
+  } catch {
+    // Config unavailable — use default
+  }
+  const stalenessMs = stalenessDays * 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  const staleResearchFiles: string[] = [];
+  const planningBase = getPlanningDir(cwd);
+  const researchFilesToCheck: string[] = [
+    path.join(planningBase, 'research', 'LANDSCAPE.md'),
+  ];
+  try {
+    const milestonesBase = path.join(planningBase, 'milestones');
+    const msDirs = (fs.readdirSync(milestonesBase) as string[]).filter((d: string) => {
+      try { return fs.statSync(path.join(milestonesBase, d)).isDirectory(); } catch { return false; }
+    });
+    for (const ms of msDirs) {
+      // Codex r3 P2: survey output is LANDSCAPE.md (path helpers'
+      // canonical name); SUMMARY.md is a phase artifact, not a
+      // research artifact, so it would never trigger staleness.
+      researchFilesToCheck.push(path.join(milestonesBase, ms, 'research', 'LANDSCAPE.md'));
+    }
+  } catch {
+    // milestones dir may not exist
+  }
+  for (const resFile of researchFilesToCheck) {
+    try {
+      const stat = fs.statSync(resFile);
+      if (now - stat.mtimeMs > stalenessMs) {
+        staleResearchFiles.push(path.relative(cwd, resFile));
+      }
+    } catch {
+      // File doesn't exist — not stale, just absent
+    }
+  }
+
+  // Parse active blockers from STATE.md
+  const blockerItems: string[] = [];
+  try {
+    const statePath = path.join(getPlanningDir(cwd), 'STATE.md');
+    const stateContent = readCachedState(statePath) || '';
+    const blockersSection = stateContent.match(/## Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
+    if (blockersSection) {
+      const blockersText = blockersSection[1].trim();
+      if (blockersText && blockersText !== 'None.' && blockersText !== 'None') {
+        const items = blockersText.match(/^-\s+(.+)$/gm) || [];
+        for (const item of items) blockerItems.push(item.replace(/^-\s+/, '').trim());
+      }
+    }
+  } catch {
+    /* STATE.md may not exist */
+  }
+
+  if (format === 'table') {
+    const barWidth = 10;
+    const filled = Math.round((percent / 100) * barWidth);
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
+    let out = `# ${milestone.version} ${milestone.name}\n\n`;
+    out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n\n`;
+    if (blockerItems.length > 0) {
+      out += `> **BLOCKED** \u2014 ${blockerItems.length} active blocker(s):\n`;
+      for (const b of blockerItems) out += `> - ${b}\n`;
+      out += `\n`;
+    }
+    if (staleResearchFiles.length > 0) {
+      out += `## Research Freshness Warnings\n\n`;
+      out += `The following research files are older than ${stalenessDays} days. Run \`/grd:survey\` to refresh:\n\n`;
+      for (const f of staleResearchFiles) out += `- \`${f}\`\n`;
+      out += `\n`;
+    }
+    out += `| Phase | Name | Plans | Status |\n|-------|------|-------|--------|\n`;
+    for (const p of phases)
+      out += `| ${p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${p.status} |\n`;
+    output({ rendered: out }, raw, out);
+  } else if (format === 'bar') {
+    const barWidth = 20;
+    const filled = Math.round((percent / 100) * barWidth);
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
+    const text = `[${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)`;
+    output({ bar: text, percent, completed: totalSummaries, total: totalPlans }, raw, text);
+  } else {
+    const humanSummary = `${milestone.version} ${milestone.name}: ${totalSummaries}/${totalPlans} plans (${percent}%)`;
+    output(
+      {
+        milestone_version: milestone.version,
+        milestone_name: milestone.name,
+        phases,
+        total_plans: totalPlans,
+        total_summaries: totalSummaries,
+        percent,
+        active_blockers: blockerItems.length,
+        blocker_items: blockerItems,
+        stale_research_files: staleResearchFiles,
+        staleness_threshold_days: stalenessDays,
+      },
+      raw,
+      humanSummary
+    );
+  }
+}
+
+// ─── Research Gap Detector ───────────────────────────────────────────────────
+
+interface MustConsiderPaper {
+  title: string;
+  keywords: string[];
+}
+
+interface PhaseGapRow {
+  phase: string;
+  cited: string[];
+  missing: string[];
+}
+
+interface ResearchGapsResult {
+  must_consider_count: number;
+  phases_scanned: number;
+  coverage: PhaseGapRow[];
+  uncited_global: string[];
+}
+
+/**
+ * Scan all phase RESEARCH.md and PLAN.md files for citations of must-consider
+ * papers listed in .planning/config.json `must_consider_papers`. Reports a
+ * per-phase coverage table showing which papers are cited vs. missing.
+ */
+function cmdResearchGaps(cwd: string, raw: boolean): void {
+  const planningDir = getPlanningDir(cwd) as string;
+  const configPath = path.join(planningDir, 'config.json');
+  let mustConsider: MustConsiderPaper[] = [];
+  if (fs.existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8') as string) as Record<string, unknown>;
+      const raw_papers = cfg['must_consider_papers'];
+      if (Array.isArray(raw_papers)) {
+        mustConsider = (raw_papers as Array<Record<string, unknown>>).map((p) => ({
+          title: String(p['title'] ?? ''),
+          keywords: Array.isArray(p['keywords']) ? (p['keywords'] as string[]).map(String) : [],
+        })).filter((p) => p.title.length > 0);
+      }
+    } catch { /* ignore parse errors */ }
+  }
+
+  if (mustConsider.length === 0) {
+    output({ must_consider_count: 0, phases_scanned: 0, coverage: [], uncited_global: [], note: 'No must_consider_papers in .planning/config.json' }, raw, 'No must_consider_papers configured. Add them to .planning/config.json to use research-gaps.');
+    return;
+  }
+
+  // Gather phase directories
+  const milestonesBase = path.join(planningDir, 'milestones');
+  const phaseDirs: { phaseId: string; dir: string }[] = [];
+  if (fs.existsSync(milestonesBase)) {
+    try {
+      for (const ms of (fs.readdirSync(milestonesBase) as string[])) {
+        const phasesBase = path.join(milestonesBase, ms, 'phases');
+        if (!fs.existsSync(phasesBase)) continue;
+        try {
+          for (const ph of (fs.readdirSync(phasesBase) as string[])) {
+            phaseDirs.push({ phaseId: `${ms}/${ph}`, dir: path.join(phasesBase, ph) });
+          }
+        } catch { /* skip */ }
+      }
+    } catch { /* skip */ }
+  }
+
+  const coverage: PhaseGapRow[] = [];
+  const globalCited = new Set<string>();
+
+  for (const { phaseId, dir } of phaseDirs) {
+    // Codex r3 P2: phase plans are typically prefixed like
+    // `01-01-PLAN.md`, not bare `PLAN.md`. Include all *-PLAN.md and
+    // *-RESEARCH.md files so citation scanning matches the real layout.
+    const candidates: string[] = [];
+    try {
+      for (const f of fs.readdirSync(dir) as string[]) {
+        if (f === 'RESEARCH.md' || f === 'PLAN.md' || /-PLAN\.md$/.test(f) || /-RESEARCH\.md$/.test(f)) {
+          candidates.push(path.join(dir, f));
+        }
+      }
+    } catch { /* skip */ }
+    let phaseText = '';
+    for (const c of candidates) {
+      if (fs.existsSync(c)) {
+        try { phaseText += ' ' + (fs.readFileSync(c, 'utf-8') as string).toLowerCase(); } catch { /* skip */ }
+      }
+    }
+    if (!phaseText.trim()) continue;
+
+    const cited: string[] = [];
+    const missing: string[] = [];
+    for (const paper of mustConsider) {
+      const allTerms = [paper.title, ...paper.keywords].map((t) => t.toLowerCase());
+      const isCited = allTerms.some((term) => phaseText.includes(term));
+      if (isCited) {
+        cited.push(paper.title);
+        globalCited.add(paper.title);
+      } else {
+        missing.push(paper.title);
+      }
+    }
+    coverage.push({ phase: phaseId, cited, missing });
+  }
+
+  const uncited_global = mustConsider.map((p) => p.title).filter((t) => !globalCited.has(t));
+  const result: ResearchGapsResult = {
+    must_consider_count: mustConsider.length,
+    phases_scanned: coverage.length,
+    coverage,
+    uncited_global,
+  };
+
+  const summary = uncited_global.length === 0
+    ? `All ${mustConsider.length} must-consider papers cited across ${coverage.length} phases`
+    : `${uncited_global.length}/${mustConsider.length} papers uncited in any phase`;
+  output(result, raw, summary);
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = { cmdProgressRender, cmdResearchGaps };