@jokerized/getresearchdone 0.4.1

package/lib/commands/assumptions.ts

@@ -0,0 +1,232 @@
+'use strict';
+
+/** GRD Commands/Assumptions -- Pre-execution stale assumption detection and validation */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  safeReadFile,
+  output,
+  error,
+  execGit,
+}: {
+  safeReadFile: (p: string) => string | null;
+  output: (result: unknown, raw: boolean, rawValue?: unknown) => never;
+  error: (message: string) => never;
+  execGit: (cwd: string, args: string[], opts?: { allowBlocked?: boolean }) => { exitCode: number; stdout: string; stderr: string };
+} = require('../utils');
+const {
+  phasesDir: getPhasesDirPath,
+}: {
+  phasesDir: (cwd: string) => string;
+} = require('../paths');
+
+// ─── Domain Types ─────────────────────────────────────────────────────────────
+
+interface AssumptionEntry {
+  text: string;
+  source_file: string;
+}
+
+interface AssumptionValidationResult {
+  assumption: string;
+  source_file: string;
+  potentially_stale: boolean;
+  reason: string;
+}
+
+interface CheckAssumptionsResult {
+  phase: string;
+  assumptions_found: number;
+  stale_count: number;
+  clean_count: number;
+  results: AssumptionValidationResult[];
+  git_diff_lines: number;
+  skipped: boolean;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Extract ## Assumptions sections from plan markdown files. */
+function parseAssumptions(planPaths: string[]): AssumptionEntry[] {
+  const entries: AssumptionEntry[] = [];
+  for (const planPath of planPaths) {
+    const content = safeReadFile(planPath);
+    if (!content) continue;
+    const match = content.match(/##\s+Assumptions?\s*\n([\s\S]*?)(?=\n##|$)/i);
+    if (!match) continue;
+    for (const line of match[1].split('\n')) {
+      const trimmed = line.replace(/^[-*]\s+/, '').trim();
+      if (trimmed && trimmed.length > 5) {
+        entries.push({ text: trimmed, source_file: path.basename(planPath) });
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * Validate whether assumptions may be stale by checking them against a git diff.
+ * Flags assumptions that reference files, functions, or exports mentioned in the diff.
+ */
+function validateAssumptionsFreshness(
+  assumptions: AssumptionEntry[],
+  gitDiff: string
+): AssumptionValidationResult[] {
+  const changedFiles = new Set<string>();
+  const changedSymbols = new Set<string>();
+
+  for (const line of gitDiff.split('\n')) {
+    const fileMatch = line.match(/^(?:\+\+\+|---)\s+[ab]\/(.+)/);
+    if (fileMatch) {
+      changedFiles.add(path.basename(fileMatch[1]));
+      changedFiles.add(path.basename(fileMatch[1], path.extname(fileMatch[1])));
+    }
+    if (line.startsWith('+') || line.startsWith('-')) {
+      const content = line.slice(1);
+      for (const m of content.matchAll(/\b(?:function|export|const|class)\s+(\w+)/g)) {
+        changedSymbols.add(m[1]);
+      }
+      for (const m of content.matchAll(/require\(['"]([^'"]+)['"]\)|from\s+['"]([^'"]+)['"]/g)) {
+        const mod = m[1] || m[2];
+        if (mod) changedSymbols.add(path.basename(mod, path.extname(mod)));
+      }
+    }
+  }
+
+  return assumptions.map((assumption) => {
+    const lower = assumption.text.toLowerCase();
+    const matchedFile = Array.from(changedFiles).find((f) => lower.includes(f.toLowerCase()));
+    const matchedSymbol = Array.from(changedSymbols).find(
+      (s) => s.length > 3 && lower.includes(s.toLowerCase())
+    );
+
+    if (matchedFile || matchedSymbol) {
+      return {
+        assumption: assumption.text,
+        source_file: assumption.source_file,
+        potentially_stale: true,
+        reason: matchedFile
+          ? `References "${matchedFile}" which changed in recent commits`
+          : `References symbol "${matchedSymbol}" which changed in recent commits`,
+      };
+    }
+    return {
+      assumption: assumption.text,
+      source_file: assumption.source_file,
+      potentially_stale: false,
+      reason: 'No conflicts detected in recent git diff',
+    };
+  });
+}
+
+// ─── CLI: Check Assumptions ───────────────────────────────────────────────────
+
+/**
+ * CLI command: Parse assumptions from phase plan files and validate them against
+ * recent git history. Surfaces potentially stale assumptions as pre-execution warnings.
+ * @param cwd - Project root
+ * @param phase - Phase number string
+ * @param raw - Raw output flag
+ * @param skipCheck - If true, skip validation and just list assumptions
+ */
+function cmdCheckAssumptions(cwd: string, phase: string, raw: boolean, skipCheck = false): void {
+  if (!phase) {
+    error('Phase number required');
+    return;
+  }
+
+  const phasesPath = getPhasesDirPath(cwd);
+  const normalized = phase.padStart(2, '0');
+  let phaseDir: string | null = null;
+  try {
+    const entries: { isDirectory: () => boolean; name: string }[] = fs.readdirSync(phasesPath, {
+      withFileTypes: true,
+    });
+    const match = entries.find(
+      (e: { isDirectory: () => boolean; name: string }) =>
+        e.isDirectory() &&
+        (e.name.startsWith(normalized + '-') || e.name.startsWith(phase + '-'))
+    );
+    phaseDir = match ? path.join(phasesPath, match.name) : null;
+  } catch {
+    /* phases dir may not exist */
+  }
+
+  if (!phaseDir) {
+    output(
+      { error: `Phase ${phase} directory not found`, phase, assumptions_found: 0, stale_count: 0, clean_count: 0, results: [], skipped: false },
+      raw,
+      `Phase ${phase} not found`
+    );
+    return;
+  }
+
+  let planFiles: string[] = [];
+  try {
+    // Codex r8 P2: include bare `PLAN.md` alongside `*-PLAN.md` so
+    // single-plan phases are not silently skipped.
+    planFiles = (fs.readdirSync(phaseDir) as string[])
+      .filter((f: string) => f === 'PLAN.md' || f.endsWith('-PLAN.md'))
+      .map((f: string) => path.join(phaseDir!, f));
+  } catch {
+    /* ignore */
+  }
+
+  const assumptions = parseAssumptions(planFiles);
+
+  if (assumptions.length === 0) {
+    const result: CheckAssumptionsResult = {
+      phase, assumptions_found: 0, stale_count: 0, clean_count: 0,
+      results: [], git_diff_lines: 0, skipped: false,
+    };
+    output(result, raw, `Phase ${phase}: no assumptions found in plan files`);
+    return;
+  }
+
+  if (skipCheck) {
+    const result: CheckAssumptionsResult = {
+      phase,
+      assumptions_found: assumptions.length,
+      stale_count: 0,
+      clean_count: assumptions.length,
+      results: assumptions.map((a) => ({
+        assumption: a.text,
+        source_file: a.source_file,
+        potentially_stale: false,
+        reason: 'Skipped (--skip-assumption-check)',
+      })),
+      git_diff_lines: 0,
+      skipped: true,
+    };
+    output(result, raw, `Phase ${phase}: assumption check skipped (${assumptions.length} assumptions)`);
+    return;
+  }
+
+  // Use execGit (whitelisted) to get recent diff for staleness detection
+  const diffResult = execGit(cwd, ['diff', 'HEAD~5', '--'], { allowBlocked: false });
+  const gitDiff = diffResult.exitCode === 0 ? diffResult.stdout : '';
+  const diffLines = gitDiff ? gitDiff.split('\n').length : 0;
+
+  const validationResults = validateAssumptionsFreshness(assumptions, gitDiff);
+  const staleCount = validationResults.filter((r) => r.potentially_stale).length;
+
+  const result: CheckAssumptionsResult = {
+    phase,
+    assumptions_found: assumptions.length,
+    stale_count: staleCount,
+    clean_count: assumptions.length - staleCount,
+    results: validationResults,
+    git_diff_lines: diffLines,
+    skipped: false,
+  };
+
+  const rawMsg =
+    staleCount > 0
+      ? `Phase ${phase}: ${staleCount} potentially stale assumption(s) — review before executing`
+      : `Phase ${phase}: all ${assumptions.length} assumption(s) look fresh`;
+  output(result, raw, rawMsg);
+}
+
+module.exports = { parseAssumptions, validateAssumptionsFreshness, cmdCheckAssumptions };

package/lib/commands/blame.ts

@@ -0,0 +1,174 @@
+'use strict';
+
+/** GRD Commands/Blame -- Map changed files to the plans/tasks that produced them */
+
+const fs = require('fs') as typeof import('fs');
+const path = require('path') as typeof import('path');
+const childProcess = require('child_process') as typeof import('child_process');
+
+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 {
+  currentMilestone,
+}: {
+  currentMilestone: (cwd: string) => string;
+} = require('../paths');
+
+interface BlameRow {
+  file: string;
+  plan: string;
+  task: string;
+}
+
+interface BlameResult {
+  phase: string;
+  rows: BlameRow[];
+  unmatched_files: string[];
+  total_files: number;
+}
+
+function _getPhaseFiles(cwd: string, phaseDir: string): string[] {
+  // Codex r3 P2: scope file collection to the phase. Find commits that
+  // touched .planning/<phase>/ first, derive the phase commit range
+  // from those, then ask git for non-.planning files touched in that
+  // range. Falls back to empty when the phase has no commits.
+  const phaseRel = path.relative(cwd, phaseDir);
+  const phaseShas = childProcess.spawnSync(
+    'git',
+    ['log', '--pretty=format:%H', '--', phaseRel],
+    { cwd, encoding: 'utf-8', stdio: 'pipe' }
+  );
+  if (phaseShas.status !== 0) return [];
+  const shas = (phaseShas.stdout || '').split('\n').filter((s: string) => s.length === 40);
+  if (shas.length === 0) return [];
+  const earliest = shas[shas.length - 1];
+  const latest = shas[0];
+  const range = earliest === latest ? `${earliest}^!` : `${earliest}^..${latest}`;
+  const result = childProcess.spawnSync(
+    'git',
+    ['log', range, '--name-only', '--pretty=format:', '--diff-filter=ACMR'],
+    { cwd, encoding: 'utf-8', stdio: 'pipe' }
+  );
+  if (result.status !== 0) return [];
+  const seen = new Set<string>();
+  for (const l of (result.stdout || '').split('\n').map((s: string) => s.trim())) {
+    if (l.length > 0 && !l.startsWith('.planning/')) seen.add(l);
+  }
+  return Array.from(seen);
+}
+
+function _extractTasksFromPlan(content: string): string[] {
+  const tasks: string[] = [];
+  for (const line of content.split('\n')) {
+    const m = line.match(/^[-*]\s+\[[ x]\]\s+(.+)/) ?? line.match(/^\d+\.\s+(.+)/);
+    if (m) tasks.push(m[1].trim());
+  }
+  // Codex r13 P2: GRD plans typically use `<task>title=...>...</task>`
+  // XML blocks; extractor was missing those entirely. Pick a label from
+  // common attributes or the inner text first line.
+  for (const m of content.matchAll(/<task\b([^>]*)>([\s\S]*?)<\/task>/gi)) {
+    const attrs = m[1] || '';
+    const inner = (m[2] || '').trim();
+    const titleAttr = attrs.match(/(?:title|name|summary)\s*=\s*"([^"]+)"/i)?.[1];
+    const idAttr = attrs.match(/\bid\s*=\s*"([^"]+)"/i)?.[1];
+    const innerFirst = inner.split('\n')[0]?.replace(/^[#*\-\s]+/, '').trim();
+    const label = titleAttr ?? idAttr ?? innerFirst;
+    if (label) tasks.push(label);
+  }
+  return tasks;
+}
+
+function _fileMatchesPlan(filePath: string, planContent: string): string | null {
+  const basename = path.basename(filePath);
+  const noExt = basename.split('.')[0].toLowerCase();
+  // Check if plan content references this file or module
+  const lowerContent = planContent.toLowerCase();
+  if (lowerContent.includes(basename.toLowerCase()) || lowerContent.includes(noExt)) {
+    const tasks = _extractTasksFromPlan(planContent);
+    // Return first matching task that references the file/module
+    for (const task of tasks) {
+      if (task.toLowerCase().includes(noExt) || task.toLowerCase().includes(basename.toLowerCase())) {
+        return task;
+      }
+    }
+    return tasks[0] ?? '(unknown task)';
+  }
+  return null;
+}
+
+/**
+ * CLI command: Map modified files in a completed phase to plan tasks.
+ *
+ * Runs git log to find files changed since the phase started, then joins
+ * against plan task lists to produce a file → plan → task table.
+ */
+function cmdBlame(cwd: string, phaseArg: string, raw: boolean): void {
+  if (!phaseArg) {
+    error('phase required. Usage: gd blame <phase>');
+  }
+
+  try {
+    currentMilestone(cwd);
+  } catch {
+    error('No active milestone found. Run gd init first.');
+  }
+
+  // Codex r2 P2: resolve numeric phase ids via findPhaseInternal so
+  // `gd blame 1` works (was looking for a literal `phases/1/` dir).
+  const phaseInfo = findPhaseInternal(cwd, phaseArg!);
+  if (!phaseInfo || !phaseInfo.found) {
+    error(`Phase not found: ${phaseArg}`);
+  }
+  // Codex r4 P2: directory is cwd-relative.
+  const phaseDir = path.join(cwd, phaseInfo!.directory);
+
+  let planFiles: string[] = [];
+  try {
+    planFiles = (fs.readdirSync(phaseDir) as string[]).filter(
+      (f: string) => f.endsWith('-PLAN.md') || f === 'PLAN.md'
+    );
+  } catch {
+    error(`Cannot read phase directory: ${phaseDir}`);
+  }
+
+  const changedFiles = _getPhaseFiles(cwd, phaseDir);
+  const rows: BlameRow[] = [];
+  const unmatched: string[] = [];
+
+  for (const file of changedFiles) {
+    let matched = false;
+    for (const planFile of planFiles) {
+      const content = safeReadFile(path.join(phaseDir, planFile));
+      if (!content) continue;
+      const task = _fileMatchesPlan(file, content);
+      if (task) {
+        rows.push({ file, plan: planFile, task });
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) unmatched.push(file);
+  }
+
+  const result: BlameResult = {
+    phase: phaseArg!,
+    rows,
+    unmatched_files: unmatched,
+    total_files: changedFiles.length,
+  };
+
+  const summary = `Phase ${phaseArg}: ${changedFiles.length} files, ${rows.length} matched, ${unmatched.length} unmatched`;
+  output(result, raw, summary);
+}
+
+module.exports = { cmdBlame };

package/lib/commands/budget.ts

@@ -0,0 +1,148 @@
+'use strict';
+
+/** GRD Commands/Budget -- Phase token budget estimator for pre-execution cost projection */
+
+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 {
+  currentMilestone,
+}: {
+  currentMilestone: (cwd: string) => string;
+} = require('../paths');
+
+interface PlanBudget {
+  plan: string;
+  task_items: number;
+  code_blocks: number;
+  dependency_chains: number;
+  estimated_tokens_low: number;
+  estimated_tokens_mid: number;
+  estimated_tokens_high: number;
+}
+
+interface PhaseBudget {
+  phase: string;
+  plans: PlanBudget[];
+  total_low: number;
+  total_mid: number;
+  total_high: number;
+  large_plans: string[];
+}
+
+const TOKENS_PER_TASK_LOW = 800;
+const TOKENS_PER_TASK_MID = 1500;
+const TOKENS_PER_TASK_HIGH = 3000;
+const TOKENS_PER_CODE_BLOCK = 200;
+const TOKENS_PER_DEP_CHAIN = 500;
+const LARGE_PLAN_THRESHOLD = 15000;
+
+function _estimatePlan(content: string, planName: string): PlanBudget {
+  // Codex r3 P2: GRD plans use `<task>...</task>` XML blocks inside
+  // `<tasks>`. Counting only markdown checkboxes / numbered lists gave
+  // zero for normal plans, making the budget command unusable. Sum
+  // markdown + XML task forms.
+  const taskItems = (content.match(/^[-*]\s+\[[ x]\]/gm) ?? []).length
+    + (content.match(/^\d+\.\s+/gm) ?? []).length
+    + (content.match(/<task\b[^>]*>/gi) ?? []).length;
+  const codeBlocks = (content.match(/^```/gm) ?? []).length / 2;
+  const depChains = (content.match(/\b(depends_on|requires|after|blocks|before):/gi) ?? []).length;
+
+  const low = taskItems * TOKENS_PER_TASK_LOW + codeBlocks * TOKENS_PER_CODE_BLOCK + depChains * TOKENS_PER_DEP_CHAIN;
+  const mid = taskItems * TOKENS_PER_TASK_MID + codeBlocks * TOKENS_PER_CODE_BLOCK + depChains * TOKENS_PER_DEP_CHAIN;
+  const high = taskItems * TOKENS_PER_TASK_HIGH + codeBlocks * TOKENS_PER_CODE_BLOCK + depChains * TOKENS_PER_DEP_CHAIN;
+
+  return {
+    plan: planName,
+    task_items: taskItems,
+    code_blocks: Math.round(codeBlocks),
+    dependency_chains: depChains,
+    estimated_tokens_low: low,
+    estimated_tokens_mid: mid,
+    estimated_tokens_high: high,
+  };
+}
+
+/**
+ * CLI command: Estimate token budget for a phase before execution.
+ *
+ * Reads all PLAN.md files under .planning/milestones/{v}/phases/{N}/,
+ * counts task items, code blocks, and dependency chains, then outputs
+ * a projected token range (low/mid/high) per plan and for the whole phase.
+ */
+function cmdBudget(cwd: string, phaseArg: string, raw: boolean): void {
+  if (!phaseArg) {
+    error('phase required. Usage: gd budget <phase>');
+  }
+
+  try {
+    currentMilestone(cwd);
+  } catch {
+    error('No active milestone found. Run gd init first.');
+  }
+
+  // Codex r2 P2: route numeric phase ids through findPhaseInternal so
+  // `gd budget 1` resolves to `phases/01-test/` instead of looking for
+  // a literal `phases/1/` directory.
+  const phaseInfo = findPhaseInternal(cwd, phaseArg!);
+  if (!phaseInfo || !phaseInfo.found) {
+    error(`Phase not found: ${phaseArg}`);
+  }
+  // Codex r4 P2: findPhaseInternal returns `directory` (cwd-relative),
+  // not `dir`. Resolve to absolute.
+  const phaseDir = path.join(cwd, phaseInfo!.directory);
+
+  let files: string[];
+  try {
+    files = (fs.readdirSync(phaseDir) as string[]).filter(
+      (f: string) => f.endsWith('-PLAN.md') || f === 'PLAN.md'
+    );
+  } catch {
+    error(`Cannot read phase directory: ${phaseDir}`);
+  }
+
+  if ((files! as string[]).length === 0) {
+    error(`No PLAN.md files found in phase ${phaseArg}`);
+  }
+
+  const plans: PlanBudget[] = [];
+  for (const file of files!) {
+    const content = safeReadFile(path.join(phaseDir, file));
+    if (!content) continue;
+    plans.push(_estimatePlan(content, file));
+  }
+
+  const total_low = plans.reduce((s, p) => s + p.estimated_tokens_low, 0);
+  const total_mid = plans.reduce((s, p) => s + p.estimated_tokens_mid, 0);
+  const total_high = plans.reduce((s, p) => s + p.estimated_tokens_high, 0);
+  const large_plans = plans
+    .filter((p) => p.estimated_tokens_mid >= LARGE_PLAN_THRESHOLD)
+    .map((p) => p.plan);
+
+  const result: PhaseBudget = {
+    phase: phaseArg!,
+    plans,
+    total_low,
+    total_mid,
+    total_high,
+    large_plans,
+  };
+
+  const summary = `Phase ${phaseArg}: ${plans.length} plans, ~${Math.round(total_mid / 1000)}K tokens mid estimate` +
+    (large_plans.length > 0 ? ` (${large_plans.length} large plan(s))` : '');
+  output(result, raw, summary);
+}
+
+module.exports = { cmdBudget };