@jokerized/getresearchdone 0.4.1

package/lib/commands/estimate.ts

@@ -0,0 +1,204 @@
+'use strict';
+
+/** GRD Commands/Estimate -- Token cost preview for a phase before execution */
+
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  output,
+  error,
+  findPhaseInternal,
+  loadConfig,
+}: {
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+  findPhaseInternal: (cwd: string, phase: string) => import('../types').PhaseInfo | null;
+  loadConfig: (cwd: string) => { model_profile?: string; [key: string]: unknown };
+} = require('../utils');
+
+// ─── Domain Types ────────────────────────────────────────────────────────────
+
+interface PlanEstimate {
+  plan_file: string;
+  wave: number;
+  agent_type: string;
+  effort: string;
+  estimated_tokens: number;
+  estimated_usd: number;
+}
+
+interface WaveEstimate {
+  wave: number;
+  plans: PlanEstimate[];
+  wave_tokens: number;
+  wave_usd: number;
+}
+
+interface EstimateResult {
+  phase: string;
+  model_profile: string;
+  wave_count: number;
+  total_plans: number;
+  total_tokens: number;
+  total_usd: number;
+  waves: WaveEstimate[];
+  note: string;
+}
+
+// ─── Token + USD Bands ───────────────────────────────────────────────────────
+
+// Effort-level token bands (input+output combined estimate)
+const EFFORT_TOKENS: Record<string, number> = {
+  high: 200_000,
+  medium: 80_000,
+  low: 30_000,
+};
+
+// Approximate per-token cost in USD by model profile (blended input+output)
+// Based on claude-sonnet-4 and claude-opus-4 pricing (illustrative)
+const PROFILE_COST_PER_TOKEN: Record<string, number> = {
+  quality: 15 / 1_000_000,   // ~opus tier
+  balanced: 3 / 1_000_000,   // ~sonnet tier
+  budget: 0.8 / 1_000_000,   // ~haiku tier
+};
+
+// Effort level resolved per agent type. Unknown agents default to 'medium'.
+const AGENT_EFFORT_DEFAULTS: Record<string, Record<string, string>> = {
+  'grd-planner':           { quality: 'high',   balanced: 'high',   budget: 'low' },
+  'grd-executor':          { quality: 'high',   balanced: 'medium', budget: 'low' },
+  'grd-verifier':          { quality: 'medium', balanced: 'low',    budget: 'low' },
+  'grd-debugger':          { quality: 'high',   balanced: 'medium', budget: 'low' },
+  'grd-phase-researcher':  { quality: 'high',   balanced: 'medium', budget: 'low' },
+  'grd-codebase-mapper':   { quality: 'medium', balanced: 'low',    budget: 'low' },
+  'grd-plan-checker':      { quality: 'medium', balanced: 'medium', budget: 'low' },
+  'grd-surveyor':          { quality: 'medium', balanced: 'medium', budget: 'low' },
+  'grd-deep-diver':        { quality: 'high',   balanced: 'medium', budget: 'low' },
+  'grd-code-reviewer':     { quality: 'high',   balanced: 'medium', budget: 'low' },
+};
+
+function resolveEffort(agentType: string, profile: string): string {
+  const agentMap = AGENT_EFFORT_DEFAULTS[agentType];
+  if (!agentMap) return 'medium';
+  return agentMap[profile] || agentMap['balanced'] || 'medium';
+}
+
+// ─── Estimate ────────────────────────────────────────────────────────────────
+
+/**
+ * CLI command: Preview token cost and agent dispatch plan for a phase before execution.
+ *
+ * Reads all plan files for phase N, groups by wave, maps effort levels to token bands
+ * using the project model_profile from config.json, and outputs a per-wave cost table.
+ *
+ * @param cwd - Project working directory
+ * @param phase - Phase number (e.g., "3" or "03")
+ * @param raw - Output raw text instead of JSON
+ */
+function cmdEstimate(cwd: string, phase: string, raw: boolean): void {
+  if (!phase) {
+    error('phase required. Usage: gd estimate <phase>');
+    return;
+  }
+
+  const phaseInfo = findPhaseInternal(cwd, phase);
+  if (!phaseInfo || !phaseInfo.found) {
+    error(`Phase ${phase} not found`);
+  }
+
+  let modelProfile = 'balanced';
+  try {
+    const config = loadConfig(cwd);
+    if (config.model_profile && typeof config.model_profile === 'string') {
+      modelProfile = config.model_profile;
+    }
+  } catch {
+    // Config unavailable — use default
+  }
+
+  const costPerToken = PROFILE_COST_PER_TOKEN[modelProfile] ?? PROFILE_COST_PER_TOKEN['balanced'];
+
+  const phaseDir = path.join(cwd, (phaseInfo as import('../types').PhaseInfo).directory);
+  // Read plan files
+  let planFiles: string[] = [];
+  try {
+    planFiles = (fs.readdirSync(phaseDir) as string[])
+      .filter((f: string) => f.endsWith('-PLAN.md') || f === 'PLAN.md')
+      .sort();
+  } catch {
+    error(`Cannot read phase directory: ${phaseDir}`);
+  }
+
+  const waveMap = new Map<number, PlanEstimate[]>();
+
+  for (const file of planFiles) {
+    const filePath = path.join(phaseDir, file);
+    let content: string;
+    try { content = fs.readFileSync(filePath, 'utf-8') as string; } catch { continue; }
+
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    const fm = fmMatch ? fmMatch[1] : '';
+
+    const waveMatch = fm.match(/^wave:\s*(\d+)/m);
+    const waveNum = waveMatch ? parseInt(waveMatch[1], 10) : 1;
+
+    const agentMatch = fm.match(/^agent_type:\s*(.+)$/m);
+    const agentType = agentMatch ? agentMatch[1].trim() : 'grd-executor';
+
+    const effort = resolveEffort(agentType, modelProfile);
+    const tokens = EFFORT_TOKENS[effort] ?? EFFORT_TOKENS['medium'];
+    const usd = tokens * costPerToken;
+
+    const estimate: PlanEstimate = { plan_file: file, wave: waveNum, agent_type: agentType, effort, estimated_tokens: tokens, estimated_usd: usd };
+    const bucket = waveMap.get(waveNum) ?? [];
+    bucket.push(estimate);
+    waveMap.set(waveNum, bucket);
+  }
+
+  const waves: WaveEstimate[] = Array.from(waveMap.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([wave, plans]) => ({
+      wave,
+      plans,
+      wave_tokens: plans.reduce((s, p) => s + p.estimated_tokens, 0),
+      wave_usd: plans.reduce((s, p) => s + p.estimated_usd, 0),
+    }));
+
+  const totalTokens = waves.reduce((s, w) => s + w.wave_tokens, 0);
+  const totalUsd = waves.reduce((s, w) => s + w.wave_usd, 0);
+  const totalPlans = waves.reduce((s, w) => s + w.plans.length, 0);
+
+  const result: EstimateResult = {
+    phase,
+    model_profile: modelProfile,
+    wave_count: waves.length,
+    total_plans: totalPlans,
+    total_tokens: totalTokens,
+    total_usd: Math.round(totalUsd * 100) / 100,
+    waves,
+    note: 'Token estimates are approximate. Actual usage depends on context size and agent behavior.',
+  };
+
+  if (raw) {
+    const lines = [
+      `Phase ${phase} cost estimate [${modelProfile} profile]`,
+      `${'─'.repeat(60)}`,
+    ];
+    for (const w of waves) {
+      lines.push(`Wave ${w.wave}: ${w.plans.length} plan(s) — ${(w.wave_tokens / 1000).toFixed(0)}K tokens ≈ $${w.wave_usd.toFixed(2)}`);
+      for (const p of w.plans) {
+        lines.push(`  ${p.plan_file} [${p.agent_type}/${p.effort}] ${(p.estimated_tokens / 1000).toFixed(0)}K tokens`);
+      }
+    }
+    lines.push(`${'─'.repeat(60)}`);
+    lines.push(`Total: ${totalPlans} plans, ${(totalTokens / 1000).toFixed(0)}K tokens ≈ $${totalUsd.toFixed(2)}`);
+    output(result, raw, lines.join('\n'));
+  } else {
+    output(result, raw, `Phase ${phase}: ${totalPlans} plans, ~${(totalTokens / 1000).toFixed(0)}K tokens, ~$${totalUsd.toFixed(2)} (${modelProfile})`);
+  }
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = { cmdEstimate };

package/lib/commands/eval-diff.ts

@@ -0,0 +1,252 @@
+'use strict';
+
+/** GRD Commands/EvalDiff -- Side-by-side EVAL.md metric comparison across phases */
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+
+const {
+  output,
+  error,
+}: {
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (msg: string) => never;
+} = require('../utils');
+
+const {
+  phasesDir: getPhasesDirPath,
+}: {
+  phasesDir: (cwd: string, milestone?: string | null) => string;
+} = require('../paths');
+
+interface MetricDelta {
+  metric: string;
+  value_a: number;
+  value_b: number;
+  delta: number;
+  delta_pct: number;
+  direction: 'improved' | 'regressed' | 'unchanged';
+}
+
+interface EvalDiffResult {
+  phase_a: string;
+  phase_b: string;
+  metrics_in_a: number;
+  metrics_in_b: number;
+  common_metrics: number;
+  deltas: MetricDelta[];
+}
+
+function _findPhaseDir(cwd: string, phaseNum: string): string | null {
+  const phasesPath = getPhasesDirPath(cwd);
+  const normalized = phaseNum.padStart(2, '0');
+  try {
+    const entries = fs.readdirSync(phasesPath, { withFileTypes: true }) as import('fs').Dirent[];
+    const match = entries.find(
+      (e) =>
+        e.isDirectory() &&
+        (e.name.startsWith(normalized + '-') || e.name.startsWith(phaseNum + '-'))
+    );
+    return match ? path.join(phasesPath, match.name) : null;
+  } catch {
+    return null;
+  }
+}
+
+function _findEvalFile(phaseDir: string): string | null {
+  try {
+    const files = fs.readdirSync(phaseDir) as string[];
+    const evalFile = files.find((f: string) => f.endsWith('-EVAL.md') || f === 'EVAL.md');
+    return evalFile ? path.join(phaseDir, evalFile) : null;
+  } catch {
+    return null;
+  }
+}
+
+function _parseMetrics(content: string): Record<string, number> {
+  const metrics: Record<string, number> = {};
+  const re = /\b([A-Za-z][A-Za-z0-9_\-/ ]{0,30}):\s*([\d]+(?:\.[\d]+)?)\s*(?:%|dB|ms|s|min)?\b/g;
+  for (const m of content.matchAll(re)) {
+    const key = m[1].trim().toLowerCase().replace(/\s+/g, '_');
+    const val = parseFloat(m[2]);
+    if (!isNaN(val) && key.length > 1) {
+      metrics[key] = val;
+    }
+  }
+  return metrics;
+}
+
+function _resolveLatestTwoPhases(cwd: string): [string, string] | null {
+  const phasesPath = getPhasesDirPath(cwd);
+  try {
+    // Codex r8 P2: only consider phases that actually have EVAL.md.
+    // Picking the last two by name fails when the newest phases are
+    // still planned/in-progress (no EVAL.md yet).
+    const dirs = (fs.readdirSync(phasesPath, { withFileTypes: true }) as import('fs').Dirent[])
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((n) => /^\d{2}/.test(n))
+      .filter((n) => {
+        // Codex r9 P2: phase dirs commonly use prefixed EVAL names like
+        // `100-EVAL.md`. Match both forms (same as _findEvalFile).
+        try {
+          return (fs.readdirSync(path.join(phasesPath, n)) as string[]).some(
+            (f: string) => f === 'EVAL.md' || /-EVAL\.md$/.test(f)
+          );
+        } catch {
+          return false;
+        }
+      })
+      // Codex r13 P2: lexicographic sort puts `100-...` before `99-...`.
+      // Sort by numeric prefix; ties broken lexicographically as a
+      // safety net.
+      .sort((a, b) => {
+        const na = parseInt(a.match(/^(\d+)/)?.[1] ?? '0', 10);
+        const nb = parseInt(b.match(/^(\d+)/)?.[1] ?? '0', 10);
+        if (na !== nb) return na - nb;
+        return a.localeCompare(b);
+      });
+    if (dirs.length < 2) return null;
+    const last = dirs[dirs.length - 1].match(/^(\d+)/)?.[1] ?? '';
+    const secondLast = dirs[dirs.length - 2].match(/^(\d+)/)?.[1] ?? '';
+    return secondLast && last ? [secondLast, last] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * CLI command: Compare EVAL.md metrics between two phases side-by-side.
+ * Use 'latest' as phaseB to auto-compare the last two completed phases.
+ */
+function cmdEvalDiff(cwd: string, phaseA: string, phaseB: string, raw: boolean): void {
+  if (!phaseA || !phaseB) {
+    error('Usage: gd eval diff <phaseA> <phaseB> — or: gd eval diff latest');
+  }
+
+  let resolvedA = phaseA;
+  let resolvedB = phaseB;
+
+  // Codex r12 P2: only resolve sides that are literally `latest`. The
+  // prior branch overwrote both sides whenever either was `latest`,
+  // so `gd eval diff 5 latest` discarded the explicit `5`. When both
+  // are `latest`, fall back to the previous behaviour (last two with
+  // EVAL.md). When only one is `latest`, pick the most recent phase
+  // with EVAL.md that differs from the explicit side.
+  const aLatest = phaseA === 'latest';
+  const bLatest = phaseB === 'latest';
+  if (aLatest && bLatest) {
+    const pair = _resolveLatestTwoPhases(cwd);
+    if (!pair) {
+      error('Could not find two completed phases with EVAL.md files');
+    }
+    [resolvedA, resolvedB] = pair!;
+  } else if (aLatest || bLatest) {
+    const pair = _resolveLatestTwoPhases(cwd);
+    if (!pair) {
+      error('Could not find a phase with EVAL.md to resolve `latest`');
+    }
+    // Codex r22 P2: compare phase ids by their numeric value so zero-
+    // padding does not cause `05` vs `5` to be treated as different.
+    const explicit = aLatest ? phaseB : phaseA;
+    const sameNum = (a: string, b: string): boolean => parseInt(a, 10) === parseInt(b, 10);
+    const latestResolved = sameNum(pair![1], explicit) ? pair![0] : pair![1];
+    if (aLatest) resolvedA = latestResolved;
+    else resolvedB = latestResolved;
+  }
+
+  const dirA = _findPhaseDir(cwd, resolvedA);
+  const dirB = _findPhaseDir(cwd, resolvedB);
+
+  if (!dirA) error(`Phase ${resolvedA} directory not found`);
+  if (!dirB) error(`Phase ${resolvedB} directory not found`);
+
+  const evalPathA = _findEvalFile(dirA!);
+  const evalPathB = _findEvalFile(dirB!);
+
+  if (!evalPathA) error(`No EVAL.md found in phase ${resolvedA}`);
+  if (!evalPathB) error(`No EVAL.md found in phase ${resolvedB}`);
+
+  let contentA: string;
+  let contentB: string;
+  try {
+    contentA = fs.readFileSync(evalPathA!, 'utf-8');
+  } catch {
+    error(`Cannot read EVAL.md for phase ${resolvedA}`);
+    return;
+  }
+  try {
+    contentB = fs.readFileSync(evalPathB!, 'utf-8');
+  } catch {
+    error(`Cannot read EVAL.md for phase ${resolvedB}`);
+    return;
+  }
+
+  const metricsA = _parseMetrics(contentA);
+  const metricsB = _parseMetrics(contentB);
+
+  const commonKeys = Object.keys(metricsA).filter((k) => k in metricsB);
+
+  // Codex r11 P2 + r12 P2: lower-is-better metrics need direction flip.
+  // `_parseMetrics` normalizes labels to snake_case (`Response time` →
+  // `response_time`), so the regex needs to match underscore-separated
+  // tokens too. Normalize underscores to spaces before testing.
+  const lowerIsBetterRe = /\b(latency|duration|elapsed|time|error|fail|loss|cost|memory|leak|bytes|ms|seconds?|minutes?)\b/i;
+  const deltas: MetricDelta[] = commonKeys.map((metric) => {
+    const vA = metricsA[metric];
+    const vB = metricsB[metric];
+    const delta = vB - vA;
+    const lowerBetter = lowerIsBetterRe.test(metric.replace(/_/g, ' '));
+    const improvedSign = lowerBetter ? delta < 0 : delta > 0;
+    // Codex r27/r29 P2: zero-baseline metrics. Direction comes from
+    // delta sign; magnitude can't be expressed as a percentage of 0,
+    // so use Infinity (clamped to 999.99 on display so the user sees
+    // a huge but bounded value, and so sorting puts these changes at
+    // the top instead of burying them at 0%).
+    const isZeroBaseline = vA === 0;
+    const deltaPct = isZeroBaseline
+      ? (delta === 0 ? 0 : Number.POSITIVE_INFINITY)
+      : (delta / Math.abs(vA)) * 100;
+    const direction: MetricDelta['direction'] = isZeroBaseline
+      ? (delta === 0 ? 'unchanged' : improvedSign ? 'improved' : 'regressed')
+      : Math.abs(deltaPct) < 0.5 ? 'unchanged' : improvedSign ? 'improved' : 'regressed';
+    const displayPct = isZeroBaseline
+      ? (delta === 0 ? 0 : (delta > 0 ? 999.99 : -999.99))
+      : Math.round(deltaPct * 100) / 100;
+    return { metric, value_a: vA, value_b: vB, delta, delta_pct: displayPct, direction };
+  });
+
+  deltas.sort((a, b) => Math.abs(b.delta_pct) - Math.abs(a.delta_pct));
+
+  const result: EvalDiffResult = {
+    phase_a: resolvedA,
+    phase_b: resolvedB,
+    metrics_in_a: Object.keys(metricsA).length,
+    metrics_in_b: Object.keys(metricsB).length,
+    common_metrics: commonKeys.length,
+    deltas,
+  };
+
+  if (raw) {
+    const pad = (s: string, n: number) => s.padEnd(n).slice(0, n);
+    const lines = [
+      `Eval diff: Phase ${resolvedA} vs Phase ${resolvedB}`,
+      `${'─'.repeat(70)}`,
+      `${pad('Metric', 30)} ${pad('Phase ' + resolvedA, 12)} ${pad('Phase ' + resolvedB, 12)} Delta`,
+      `${'─'.repeat(70)}`,
+    ];
+    for (const d of deltas) {
+      const arrow = d.direction === 'improved' ? '+' : d.direction === 'regressed' ? '-' : ' ';
+      lines.push(
+        `${pad(d.metric, 30)} ${pad(String(d.value_a), 12)} ${pad(String(d.value_b), 12)} ${arrow}${Math.abs(d.delta_pct).toFixed(1)}%`
+      );
+    }
+    if (deltas.length === 0) lines.push('  No common metrics found.');
+    lines.push(`${'─'.repeat(70)}`);
+    output(result, raw, lines.join('\n'));
+  } else {
+    output(result, raw, `${commonKeys.length} common metrics, ${deltas.filter((d) => d.direction === 'regressed').length} regressions`);
+  }
+}
+
+module.exports = { cmdEvalDiff };

package/lib/commands/freshness.ts

@@ -0,0 +1,213 @@
+'use strict';
+
+/** GRD Commands/Freshness -- Research freshness scanner for RESEARCH.md and LANDSCAPE.md */
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+
+const {
+  safeReadFile,
+  output,
+  error,
+  findPhaseInternal,
+}: {
+  safeReadFile: (p: string) => string | null;
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+  findPhaseInternal: (cwd: string, phase: string) => { found: boolean; directory: string } | null;
+} = require('../utils');
+
+const {
+  phasesDir: getPhasesDirPath,
+  researchDir: getResearchDir,
+  currentMilestone,
+}: {
+  phasesDir: (cwd: string, milestone?: string | null) => string;
+  researchDir: (cwd: string, milestone?: string | null) => string;
+  currentMilestone: (cwd: string) => string;
+} = require('../paths');
+
+interface FreshnessItem {
+  title: string;
+  type: 'paper' | 'repo' | 'url';
+  url?: string;
+  research_date?: string;
+  days_since_research: number;
+  staleness: 'fresh' | 'aging' | 'stale';
+  source_file: string;
+}
+
+interface FreshnessResult {
+  phase?: string;
+  items: FreshnessItem[];
+  stale_count: number;
+  aging_count: number;
+  fresh_count: number;
+  files_scanned: number;
+}
+
+const STALE_DAYS = 30;
+const AGING_DAYS = 14;
+
+function _classifyStaleness(days: number): 'fresh' | 'aging' | 'stale' {
+  if (days >= STALE_DAYS) return 'stale';
+  if (days >= AGING_DAYS) return 'aging';
+  return 'fresh';
+}
+
+function _extractResearchDate(content: string): string | undefined {
+  // Look for frontmatter date field or explicit "research_date:" line
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fm) {
+    const d = fm[1].match(/(?:date|research_date):\s*(\d{4}-\d{2}-\d{2})/);
+    if (d) return d[1];
+  }
+  const inline = content.match(/research_date:\s*(\d{4}-\d{2}-\d{2})/);
+  if (inline) return inline[1];
+  return undefined;
+}
+
+function _extractCitations(content: string): Array<{ title: string; url?: string; type: 'paper' | 'repo' | 'url' }> {
+  const items: Array<{ title: string; url?: string; type: 'paper' | 'repo' | 'url' }> = [];
+  const seen = new Set<string>();
+
+  // arXiv links
+  for (const m of content.matchAll(/https?:\/\/arxiv\.org\/abs\/[\d.]+/g)) {
+    const url = m[0];
+    if (!seen.has(url)) {
+      seen.add(url);
+      const titleMatch = content.slice(Math.max(0, m.index! - 200), m.index!).match(/#+\s+(.+)$|["']([^"']{5,80})["']/m);
+      items.push({ title: titleMatch ? (titleMatch[1] ?? titleMatch[2] ?? url) : url, url, type: 'paper' });
+    }
+  }
+
+  // GitHub repos
+  for (const m of content.matchAll(/https?:\/\/github\.com\/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+/g)) {
+    const url = m[0].replace(/[)\].,]+$/, '');
+    if (!seen.has(url)) {
+      seen.add(url);
+      const parts = url.split('/');
+      items.push({ title: parts.slice(-2).join('/'), url, type: 'repo' });
+    }
+  }
+
+  // Markdown headings that look like paper titles (heuristic: ## Title with year)
+  for (const m of content.matchAll(/^#{2,3}\s+(.{10,120})\s*\(\d{4}\)/gm)) {
+    const title = m[1].trim();
+    if (!seen.has(title)) {
+      seen.add(title);
+      items.push({ title, type: 'paper' });
+    }
+  }
+
+  return items;
+}
+
+function _scanFile(filePath: string, today: Date): FreshnessItem[] {
+  const content = safeReadFile(filePath);
+  if (!content) return [];
+
+  const researchDate = _extractResearchDate(content);
+  const citations = _extractCitations(content);
+
+  const refDate = researchDate ? new Date(researchDate) : null;
+  const daysSince = refDate
+    ? Math.floor((today.getTime() - refDate.getTime()) / 86400000)
+    : 999;
+
+  return citations.map((c) => ({
+    title: c.title,
+    type: c.type,
+    url: c.url,
+    research_date: researchDate,
+    days_since_research: daysSince,
+    staleness: _classifyStaleness(daysSince),
+    source_file: filePath,
+  }));
+}
+
+/**
+ * CLI command: Check research freshness for a phase or all phases.
+ *
+ * Reads RESEARCH.md and LANDSCAPE.md files, extracts paper titles and
+ * GitHub repo URLs, and flags stale citations with days-since-research.
+ */
+function cmdFreshness(cwd: string, phaseArg: string | null, raw: boolean): void {
+  let milestone: string;
+  try {
+    milestone = currentMilestone(cwd);
+  } catch {
+    error('No active milestone found. Run gd init first.');
+  }
+
+  const today = new Date();
+  const allItems: FreshnessItem[] = [];
+  const filePaths: string[] = [];
+
+  if (phaseArg) {
+    // Codex r2 P2: numeric phase ids resolve through findPhaseInternal.
+    const phaseInfo = findPhaseInternal(cwd, phaseArg);
+    if (!phaseInfo || !phaseInfo.found) {
+      error(`Phase not found: ${phaseArg}`);
+    }
+    // Codex r4 P2: directory is cwd-relative.
+    // Codex r9 P2: phase research artifacts commonly use prefixed names
+    // like `83-RESEARCH.md`. Match both bare and prefixed forms.
+    const phaseDir = path.join(cwd, phaseInfo!.directory);
+    try {
+      for (const f of fs.readdirSync(phaseDir) as string[]) {
+        if (f === 'RESEARCH.md' || f === 'LANDSCAPE.md' || /-(RESEARCH|LANDSCAPE)\.md$/.test(f)) {
+          filePaths.push(path.join(phaseDir, f));
+        }
+      }
+    } catch { /* skip */ }
+  } else {
+    // Scan all phases and the milestone research dir
+    const resDir = getResearchDir(cwd, milestone!);
+    for (const f of ['RESEARCH.md', 'LANDSCAPE.md']) {
+      const p = path.join(resDir, f);
+      if (fs.existsSync(p)) filePaths.push(p);
+    }
+
+    const phasesBase = getPhasesDirPath(cwd, milestone!);
+    if (fs.existsSync(phasesBase)) {
+      try {
+        for (const phaseDir of fs.readdirSync(phasesBase) as string[]) {
+          const phaseFull = path.join(phasesBase, phaseDir);
+          try {
+            for (const f of fs.readdirSync(phaseFull) as string[]) {
+              if (f === 'RESEARCH.md' || f === 'LANDSCAPE.md' || /-(RESEARCH|LANDSCAPE)\.md$/.test(f)) {
+                filePaths.push(path.join(phaseFull, f));
+              }
+            }
+          } catch { /* skip */ }
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  if (filePaths.length === 0) {
+    output({ items: [], stale_count: 0, aging_count: 0, fresh_count: 0, files_scanned: 0 }, raw, 'No RESEARCH.md or LANDSCAPE.md files found');
+    return;
+  }
+
+  for (const fp of filePaths) {
+    allItems.push(..._scanFile(fp, today));
+  }
+
+  allItems.sort((a, b) => b.days_since_research - a.days_since_research);
+
+  const result: FreshnessResult = {
+    phase: phaseArg ?? undefined,
+    items: allItems,
+    stale_count: allItems.filter((i) => i.staleness === 'stale').length,
+    aging_count: allItems.filter((i) => i.staleness === 'aging').length,
+    fresh_count: allItems.filter((i) => i.staleness === 'fresh').length,
+    files_scanned: filePaths.length,
+  };
+
+  const summary = `${filePaths.length} files: ${result.stale_count} stale, ${result.aging_count} aging, ${result.fresh_count} fresh citations`;
+  output(result, raw, summary);
+}
+
+module.exports = { cmdFreshness };