@howlil/ez-agents 3.5.0 → 4.0.0

package/ez-agents/bin/lib/commands.cjs

@@ -1,685 +1,685 @@
-/**
- * Commands — Standalone utility commands
- */
-const fs = require('fs');
-const path = require('path');
-const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
-const { extractFrontmatter } = require('./frontmatter.cjs');
-const { defaultLogger: logger } = require('./logger.cjs');
-
-function cmdGenerateSlug(text, raw) {
-  if (!text) {
-    error('text required for slug generation');
-  }
-
-  const slug = text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-
-  const result = { slug };
-  output(result, raw, slug);
-}
-
-function cmdCurrentTimestamp(format, raw) {
-  const now = new Date();
-  let result;
-
-  switch (format) {
-    case 'date':
-      result = now.toISOString().split('T')[0];
-      break;
-    case 'filename':
-      result = now.toISOString().replace(/:/g, '-').replace(/\..+/, '');
-      break;
-    case 'full':
-    default:
-      result = now.toISOString();
-      break;
-  }
-
-  output({ timestamp: result }, raw, result);
-}
-
-function cmdListTodos(cwd, area, raw) {
-  const pendingDir = path.join(cwd, '.planning', 'todos', 'pending');
-
-  let count = 0;
-  const todos = [];
-
-  try {
-    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
-
-    for (const file of files) {
-      try {
-        const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8');
-        const createdMatch = content.match(/^created:\s*(.+)$/m);
-        const titleMatch = content.match(/^title:\s*(.+)$/m);
-        const areaMatch = content.match(/^area:\s*(.+)$/m);
-
-        const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
-
-        // Apply area filter if specified
-        if (area && todoArea !== area) continue;
-
-        count++;
-        todos.push({
-          file,
-          created: createdMatch ? createdMatch[1].trim() : 'unknown',
-          title: titleMatch ? titleMatch[1].trim() : 'Untitled',
-          area: todoArea,
-          path: toPosixPath(path.join('.planning', 'todos', 'pending', file)),
-        });
-      } catch (err) {
-        logger.warn('Failed to parse todo file in cmdListTodos', { file, error: err.message });
-      }
-    }
-  } catch (err) {
-    logger.warn('Failed to list pending todos in cmdListTodos', { pendingDir, error: err.message });
-  }
-
-  const result = { count, todos };
-  output(result, raw, count.toString());
-}
-
-function cmdVerifyPathExists(cwd, targetPath, raw) {
-  if (!targetPath) {
-    error('path required for verification');
-  }
-
-  const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
-
-  try {
-    const stats = fs.statSync(fullPath);
-    const type = stats.isDirectory() ? 'directory' : stats.isFile() ? 'file' : 'other';
-    const result = { exists: true, type };
-    output(result, raw, 'true');
-  } catch (err) {
-    logger.warn('Path verification failed in cmdVerifyPathExists', { fullPath, error: err.message });
-    const result = { exists: false, type: null };
-    output(result, raw, 'false');
-  }
-}
-
-function cmdHistoryDigest(cwd, raw) {
-  const phasesDir = path.join(cwd, '.planning', 'phases');
-  const digest = { phases: {}, decisions: [], tech_stack: new Set() };
-
-  // Collect all phase directories: archived + current
-  const allPhaseDirs = [];
-
-  // Add archived phases first (oldest milestones first)
-  const archived = getArchivedPhaseDirs(cwd);
-  for (const a of archived) {
-    allPhaseDirs.push({ name: a.name, fullPath: a.fullPath, milestone: a.milestone });
-  }
-
-  // Add current phases
-  if (fs.existsSync(phasesDir)) {
-    try {
-      const currentDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
-        .filter(e => e.isDirectory())
-        .map(e => e.name)
-        .sort();
-      for (const dir of currentDirs) {
-        allPhaseDirs.push({ name: dir, fullPath: path.join(phasesDir, dir), milestone: null });
-      }
-    } catch (err) {
-      logger.warn('Failed to enumerate current phase directories in cmdHistoryDigest', { phasesDir, error: err.message });
-    }
-  }
-
-  if (allPhaseDirs.length === 0) {
-    digest.tech_stack = [];
-    output(digest, raw);
-    return;
-  }
-
-  try {
-    for (const { name: dir, fullPath: dirPath } of allPhaseDirs) {
-      const summaries = fs.readdirSync(dirPath).filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-
-      for (const summary of summaries) {
-        try {
-          const content = fs.readFileSync(path.join(dirPath, summary), 'utf-8');
-          const fm = extractFrontmatter(content);
-
-          const phaseNum = fm.phase || dir.split('-')[0];
-
-          if (!digest.phases[phaseNum]) {
-            digest.phases[phaseNum] = {
-              name: fm.name || dir.split('-').slice(1).join(' ') || 'Unknown',
-              provides: new Set(),
-              affects: new Set(),
-              patterns: new Set(),
-            };
-          }
-
-          // Merge provides
-          if (fm['dependency-graph'] && fm['dependency-graph'].provides) {
-            fm['dependency-graph'].provides.forEach(p => digest.phases[phaseNum].provides.add(p));
-          } else if (fm.provides) {
-            fm.provides.forEach(p => digest.phases[phaseNum].provides.add(p));
-          }
-
-          // Merge affects
-          if (fm['dependency-graph'] && fm['dependency-graph'].affects) {
-            fm['dependency-graph'].affects.forEach(a => digest.phases[phaseNum].affects.add(a));
-          }
-
-          // Merge patterns
-          if (fm['patterns-established']) {
-            fm['patterns-established'].forEach(p => digest.phases[phaseNum].patterns.add(p));
-          }
-
-          // Merge decisions
-          if (fm['key-decisions']) {
-            fm['key-decisions'].forEach(d => {
-              digest.decisions.push({ phase: phaseNum, decision: d });
-            });
-          }
-
-          // Merge tech stack
-          if (fm['tech-stack'] && fm['tech-stack'].added) {
-            fm['tech-stack'].added.forEach(t => digest.tech_stack.add(typeof t === 'string' ? t : t.name));
-          }
-
-        } catch (err) {
-          logger.warn('Skipping malformed summary in cmdHistoryDigest', { summary, dirPath, error: err.message });
-        }
-      }
-    }
-
-    // Convert Sets to Arrays for JSON output
-    Object.keys(digest.phases).forEach(p => {
-      digest.phases[p].provides = [...digest.phases[p].provides];
-      digest.phases[p].affects = [...digest.phases[p].affects];
-      digest.phases[p].patterns = [...digest.phases[p].patterns];
-    });
-    digest.tech_stack = [...digest.tech_stack];
-
-    output(digest, raw);
-  } catch (err) {
-    logger.error('Failed to generate history digest', { error: err.message });
-    error('Failed to generate history digest: ' + err.message);
-  }
-}
-
-function cmdResolveModel(cwd, agentType, raw) {
-  if (!agentType) {
-    error('agent-type required');
-  }
-
-  const config = loadConfig(cwd);
-  const profile = config.model_profile || 'balanced';
-  const model = resolveModelInternal(cwd, agentType);
-
-  const agentModels = MODEL_PROFILES[agentType];
-  const result = agentModels
-    ? { model, profile }
-    : { model, profile, unknown_agent: true };
-  output(result, raw, model);
-}
-
-async function cmdCommit(cwd, message, files, raw, amend) {
-  if (!message && !amend) {
-    error('commit message required');
-  }
-
-  const config = loadConfig(cwd);
-
-  // Check commit_docs config
-  if (!config.commit_docs) {
-    const result = { committed: false, hash: null, reason: 'skipped_commit_docs_false' };
-    output(result, raw, 'skipped');
-    return;
-  }
-
-  // Check if .planning is gitignored
-  if (await isGitIgnored(cwd, '.planning')) {
-    const result = { committed: false, hash: null, reason: 'skipped_gitignored' };
-    output(result, raw, 'skipped');
-    return;
-  }
-
-  // Stage files
-  const filesToStage = files && files.length > 0 ? files : ['.planning/'];
-  for (const file of filesToStage) {
-    await execGit(cwd, ['add', file]);
-  }
-
-  // Commit
-  const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message];
-  const commitResult = await execGit(cwd, commitArgs);
-  if (commitResult.exitCode !== 0) {
-    if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
-      const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
-      output(result, raw, 'nothing');
-      return;
-    }
-    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
-    output(result, raw, 'nothing');
-    return;
-  }
-
-  // Get short hash
-  const hashResult = await execGit(cwd, ['rev-parse', '--short', 'HEAD']);
-  const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
-  const result = { committed: true, hash, reason: 'committed' };
-  output(result, raw, hash || 'committed');
-}
-
-function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
-  if (!summaryPath) {
-    error('summary-path required for summary-extract');
-  }
-
-  const fullPath = path.join(cwd, summaryPath);
-
-  if (!fs.existsSync(fullPath)) {
-    output({ error: 'File not found', path: summaryPath }, raw);
-    return;
-  }
-
-  const content = fs.readFileSync(fullPath, 'utf-8');
-  const fm = extractFrontmatter(content);
-
-  // Parse key-decisions into structured format
-  const parseDecisions = (decisionsList) => {
-    if (!decisionsList || !Array.isArray(decisionsList)) return [];
-    return decisionsList.map(d => {
-      const colonIdx = d.indexOf(':');
-      if (colonIdx > 0) {
-        return {
-          summary: d.substring(0, colonIdx).trim(),
-          rationale: d.substring(colonIdx + 1).trim(),
-        };
-      }
-      return { summary: d, rationale: null };
-    });
-  };
-
-  // Build full result
-  const fullResult = {
-    path: summaryPath,
-    one_liner: fm['one-liner'] || null,
-    key_files: fm['key-files'] || [],
-    tech_added: (fm['tech-stack'] && fm['tech-stack'].added) || [],
-    patterns: fm['patterns-established'] || [],
-    decisions: parseDecisions(fm['key-decisions']),
-    requirements_completed: fm['requirements-completed'] || [],
-  };
-
-  // If fields specified, filter to only those fields
-  if (fields && fields.length > 0) {
-    const filtered = { path: summaryPath };
-    for (const field of fields) {
-      if (fullResult[field] !== undefined) {
-        filtered[field] = fullResult[field];
-      }
-    }
-    output(filtered, raw);
-    return;
-  }
-
-  output(fullResult, raw);
-}
-
-async function cmdWebsearch(query, options, raw) {
-  const apiKey = process.env.BRAVE_API_KEY;
-
-  if (!apiKey) {
-    // No key = silent skip, agent falls back to built-in WebSearch
-    output({ available: false, reason: 'BRAVE_API_KEY not set' }, raw, '');
-    return;
-  }
-
-  if (!query) {
-    output({ available: false, error: 'Query required' }, raw, '');
-    return;
-  }
-
-  const params = new URLSearchParams({
-    q: query,
-    count: String(options.limit || 10),
-    country: 'us',
-    search_lang: 'en',
-    text_decorations: 'false'
-  });
-
-  if (options.freshness) {
-    params.set('freshness', options.freshness);
-  }
-
-  try {
-    const response = await fetch(
-      `https://api.search.brave.com/res/v1/web/search?${params}`,
-      {
-        headers: {
-          'Accept': 'application/json',
-          'X-Subscription-Token': apiKey
-        }
-      }
-    );
-
-    if (!response.ok) {
-      output({ available: false, error: `API error: ${response.status}` }, raw, '');
-      return;
-    }
-
-    const data = await response.json();
-
-    const results = (data.web?.results || []).map(r => ({
-      title: r.title,
-      url: r.url,
-      description: r.description,
-      age: r.age || null
-    }));
-
-    output({
-      available: true,
-      query,
-      count: results.length,
-      results
-    }, raw, results.map(r => `${r.title}\n${r.url}\n${r.description}`).join('\n\n'));
-  } catch (err) {
-    logger.warn('Websearch request failed in cmdWebsearch', { query, error: err.message });
-    output({ available: false, error: err.message }, raw, '');
-  }
-}
-
-function cmdProgressRender(cwd, format, raw) {
-  const phasesDir = path.join(cwd, '.planning', 'phases');
-  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
-  const milestone = getMilestoneInfo(cwd);
-
-  const phases = [];
-  let totalPlans = 0;
-  let totalSummaries = 0;
-
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
-
-    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 = fs.readdirSync(path.join(phasesDir, dir));
-      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
-      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
-
-      totalPlans += plans;
-      totalSummaries += summaries;
-
-      let status;
-      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 (err) {
-    logger.warn('Failed to enumerate phase directories in cmdProgressRender', { phasesDir, error: err.message });
-  }
-
-  const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
-
-  if (format === 'table') {
-    // Render markdown 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`;
-    out += `| Phase | Name | Plans | Status |\n`;
-    out += `|-------|------|-------|--------|\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 {
-    // JSON format
-    output({
-      milestone_version: milestone.version,
-      milestone_name: milestone.name,
-      phases,
-      total_plans: totalPlans,
-      total_summaries: totalSummaries,
-      percent,
-    }, raw);
-  }
-}
-
-function cmdTodoComplete(cwd, filename, raw) {
-  if (!filename) {
-    error('filename required for todo complete');
-  }
-
-  const pendingDir = path.join(cwd, '.planning', 'todos', 'pending');
-  const completedDir = path.join(cwd, '.planning', 'todos', 'completed');
-  const sourcePath = path.join(pendingDir, filename);
-
-  if (!fs.existsSync(sourcePath)) {
-    error(`Todo not found: ${filename}`);
-  }
-
-  // Ensure completed directory exists
-  fs.mkdirSync(completedDir, { recursive: true });
-
-  // Read, add completion timestamp, move
-  let content = fs.readFileSync(sourcePath, 'utf-8');
-  const today = new Date().toISOString().split('T')[0];
-  content = `completed: ${today}\n` + content;
-
-  fs.writeFileSync(path.join(completedDir, filename), content, 'utf-8');
-  fs.unlinkSync(sourcePath);
-
-  output({ completed: true, file: filename, date: today }, raw, 'completed');
-}
-
-function cmdScaffold(cwd, type, options, raw) {
-  const { phase, name } = options;
-  const padded = phase ? normalizePhaseName(phase) : '00';
-  const today = new Date().toISOString().split('T')[0];
-
-  // Find phase directory
-  const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
-  const phaseDir = phaseInfo ? path.join(cwd, phaseInfo.directory) : null;
-
-  if (phase && !phaseDir && type !== 'phase-dir') {
-    error(`Phase ${phase} directory not found`);
-  }
-
-  let filePath, content;
-
-  switch (type) {
-    case 'context': {
-      filePath = path.join(phaseDir, `${padded}-CONTEXT.md`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /ez-discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
-      break;
-    }
-    case 'uat': {
-      filePath = path.join(phaseDir, `${padded}-UAT.md`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — User Acceptance Testing\n\n## Test Results\n\n| # | Test | Status | Notes |\n|---|------|--------|-------|\n\n## Summary\n\n_Pending UAT_\n`;
-      break;
-    }
-    case 'verification': {
-      filePath = path.join(phaseDir, `${padded}-VERIFICATION.md`);
-      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Verification\n\n## Goal-Backward Verification\n\n**Phase Goal:** [From ROADMAP.md]\n\n## Checks\n\n| # | Requirement | Status | Evidence |\n|---|------------|--------|----------|\n\n## Result\n\n_Pending verification_\n`;
-      break;
-    }
-    case 'phase-dir': {
-      if (!phase || !name) {
-        error('phase and name required for phase-dir scaffold');
-      }
-      const slug = generateSlugInternal(name);
-      const dirName = `${padded}-${slug}`;
-      const phasesParent = path.join(cwd, '.planning', 'phases');
-      fs.mkdirSync(phasesParent, { recursive: true });
-      const dirPath = path.join(phasesParent, dirName);
-      fs.mkdirSync(dirPath, { recursive: true });
-      output({ created: true, directory: `.planning/phases/${dirName}`, path: dirPath }, raw, dirPath);
-      return;
-    }
-    default:
-      error(`Unknown scaffold type: ${type}. Available: context, uat, verification, phase-dir`);
-  }
-
-  if (fs.existsSync(filePath)) {
-    output({ created: false, reason: 'already_exists', path: filePath }, raw, 'exists');
-    return;
-  }
-
-  fs.writeFileSync(filePath, content, 'utf-8');
-  const relPath = toPosixPath(path.relative(cwd, filePath));
-  output({ created: true, path: relPath }, raw, relPath);
-}
-
-async function cmdStats(cwd, format, raw) {
-  const phasesDir = path.join(cwd, '.planning', 'phases');
-  const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
-  const statePath = path.join(cwd, '.planning', 'STATE.md');
-  const milestone = getMilestoneInfo(cwd);
-
-  // Phase & plan stats (reuse progress pattern)
-  const phases = [];
-  let totalPlans = 0;
-  let totalSummaries = 0;
-
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
-
-    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 = fs.readdirSync(path.join(phasesDir, dir));
-      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
-      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
-
-      totalPlans += plans;
-      totalSummaries += summaries;
-
-      let status;
-      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 (err) {
-    logger.warn('Failed to enumerate phase directories in cmdStats', { phasesDir, error: err.message });
-  }
-
-  const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
-
-  // Requirements stats
-  let requirementsTotal = 0;
-  let requirementsComplete = 0;
-  try {
-    if (fs.existsSync(reqPath)) {
-      const reqContent = fs.readFileSync(reqPath, 'utf-8');
-      const checked = reqContent.match(/^- \[x\] \*\*/gm);
-      const unchecked = reqContent.match(/^- \[ \] \*\*/gm);
-      requirementsComplete = checked ? checked.length : 0;
-      requirementsTotal = requirementsComplete + (unchecked ? unchecked.length : 0);
-    }
-  } catch (err) {
-    logger.warn('Failed to parse REQUIREMENTS.md in cmdStats', { reqPath, error: err.message });
-  }
-
-  // Last activity from STATE.md
-  let lastActivity = null;
-  try {
-    if (fs.existsSync(statePath)) {
-      const stateContent = fs.readFileSync(statePath, 'utf-8');
-      const activityMatch = stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/);
-      if (activityMatch) lastActivity = activityMatch[1].trim();
-    }
-  } catch (err) {
-    logger.warn('Failed to read STATE.md in cmdStats', { statePath, error: err.message });
-  }
-
-  // Git stats
-  let gitCommits = 0;
-  let gitFirstCommitDate = null;
-  try {
-    const commitCount = await execGit(cwd, ['rev-list', '--count', 'HEAD']);
-    gitCommits = parseInt(commitCount.trim(), 10) || 0;
-    const firstDate = await execGit(cwd, ['log', '--reverse', '--format=%as', '--max-count=1']);
-    gitFirstCommitDate = firstDate.trim() || null;
-  } catch (err) {
-    logger.warn('Failed to compute git stats in cmdStats', { cwd, error: err.message });
-  }
-
-  const completedPhases = phases.filter(p => p.status === 'Complete').length;
-
-  const result = {
-    milestone_version: milestone.version,
-    milestone_name: milestone.name,
-    phases,
-    phases_completed: completedPhases,
-    phases_total: phases.length,
-    total_plans: totalPlans,
-    total_summaries: totalSummaries,
-    percent,
-    requirements_total: requirementsTotal,
-    requirements_complete: requirementsComplete,
-    git_commits: gitCommits,
-    git_first_commit_date: gitFirstCommitDate,
-    last_activity: lastActivity,
-  };
-
-  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} \u2014 Statistics\n\n`;
-    out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n`;
-    out += `**Phases:** ${completedPhases}/${phases.length} complete\n`;
-    if (requirementsTotal > 0) {
-      out += `**Requirements:** ${requirementsComplete}/${requirementsTotal} complete\n`;
-    }
-    out += '\n';
-    out += `| Phase | Name | Plans | Completed | Status |\n`;
-    out += `|-------|------|-------|-----------|--------|\n`;
-    for (const p of phases) {
-      out += `| ${p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${p.status} |\n`;
-    }
-    if (gitCommits > 0) {
-      out += `\n**Git:** ${gitCommits} commits`;
-      if (gitFirstCommitDate) out += ` (since ${gitFirstCommitDate})`;
-      out += '\n';
-    }
-    if (lastActivity) out += `**Last activity:** ${lastActivity}\n`;
-    output({ rendered: out }, raw, out);
-  } else {
-    output(result, raw);
-  }
-}
-
-module.exports = {
-  cmdGenerateSlug,
-  cmdCurrentTimestamp,
-  cmdListTodos,
-  cmdVerifyPathExists,
-  cmdHistoryDigest,
-  cmdResolveModel,
-  cmdCommit,
-  cmdSummaryExtract,
-  cmdWebsearch,
-  cmdProgressRender,
-  cmdTodoComplete,
-  cmdScaffold,
-  cmdStats,
-};
+/**
+ * Commands — Standalone utility commands
+ */
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { defaultLogger: logger } = require('./logger.cjs');
+
+function cmdGenerateSlug(text, raw) {
+  if (!text) {
+    error('text required for slug generation');
+  }
+
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  const result = { slug };
+  output(result, raw, slug);
+}
+
+function cmdCurrentTimestamp(format, raw) {
+  const now = new Date();
+  let result;
+
+  switch (format) {
+    case 'date':
+      result = now.toISOString().split('T')[0];
+      break;
+    case 'filename':
+      result = now.toISOString().replace(/:/g, '-').replace(/\..+/, '');
+      break;
+    case 'full':
+    default:
+      result = now.toISOString();
+      break;
+  }
+
+  output({ timestamp: result }, raw, result);
+}
+
+function cmdListTodos(cwd, area, raw) {
+  const pendingDir = path.join(cwd, '.planning', 'todos', 'pending');
+
+  let count = 0;
+  const todos = [];
+
+  try {
+    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8');
+        const createdMatch = content.match(/^created:\s*(.+)$/m);
+        const titleMatch = content.match(/^title:\s*(.+)$/m);
+        const areaMatch = content.match(/^area:\s*(.+)$/m);
+
+        const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
+
+        // Apply area filter if specified
+        if (area && todoArea !== area) continue;
+
+        count++;
+        todos.push({
+          file,
+          created: createdMatch ? createdMatch[1].trim() : 'unknown',
+          title: titleMatch ? titleMatch[1].trim() : 'Untitled',
+          area: todoArea,
+          path: toPosixPath(path.join('.planning', 'todos', 'pending', file)),
+        });
+      } catch (err) {
+        logger.warn('Failed to parse todo file in cmdListTodos', { file, error: err.message });
+      }
+    }
+  } catch (err) {
+    logger.warn('Failed to list pending todos in cmdListTodos', { pendingDir, error: err.message });
+  }
+
+  const result = { count, todos };
+  output(result, raw, count.toString());
+}
+
+function cmdVerifyPathExists(cwd, targetPath, raw) {
+  if (!targetPath) {
+    error('path required for verification');
+  }
+
+  const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
+
+  try {
+    const stats = fs.statSync(fullPath);
+    const type = stats.isDirectory() ? 'directory' : stats.isFile() ? 'file' : 'other';
+    const result = { exists: true, type };
+    output(result, raw, 'true');
+  } catch (err) {
+    logger.warn('Path verification failed in cmdVerifyPathExists', { fullPath, error: err.message });
+    const result = { exists: false, type: null };
+    output(result, raw, 'false');
+  }
+}
+
+function cmdHistoryDigest(cwd, raw) {
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const digest = { phases: {}, decisions: [], tech_stack: new Set() };
+
+  // Collect all phase directories: archived + current
+  const allPhaseDirs = [];
+
+  // Add archived phases first (oldest milestones first)
+  const archived = getArchivedPhaseDirs(cwd);
+  for (const a of archived) {
+    allPhaseDirs.push({ name: a.name, fullPath: a.fullPath, milestone: a.milestone });
+  }
+
+  // Add current phases
+  if (fs.existsSync(phasesDir)) {
+    try {
+      const currentDirs = fs.readdirSync(phasesDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .sort();
+      for (const dir of currentDirs) {
+        allPhaseDirs.push({ name: dir, fullPath: path.join(phasesDir, dir), milestone: null });
+      }
+    } catch (err) {
+      logger.warn('Failed to enumerate current phase directories in cmdHistoryDigest', { phasesDir, error: err.message });
+    }
+  }
+
+  if (allPhaseDirs.length === 0) {
+    digest.tech_stack = [];
+    output(digest, raw);
+    return;
+  }
+
+  try {
+    for (const { name: dir, fullPath: dirPath } of allPhaseDirs) {
+      const summaries = fs.readdirSync(dirPath).filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+
+      for (const summary of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(dirPath, summary), 'utf-8');
+          const fm = extractFrontmatter(content);
+
+          const phaseNum = fm.phase || dir.split('-')[0];
+
+          if (!digest.phases[phaseNum]) {
+            digest.phases[phaseNum] = {
+              name: fm.name || dir.split('-').slice(1).join(' ') || 'Unknown',
+              provides: new Set(),
+              affects: new Set(),
+              patterns: new Set(),
+            };
+          }
+
+          // Merge provides
+          if (fm['dependency-graph'] && fm['dependency-graph'].provides) {
+            fm['dependency-graph'].provides.forEach(p => digest.phases[phaseNum].provides.add(p));
+          } else if (fm.provides) {
+            fm.provides.forEach(p => digest.phases[phaseNum].provides.add(p));
+          }
+
+          // Merge affects
+          if (fm['dependency-graph'] && fm['dependency-graph'].affects) {
+            fm['dependency-graph'].affects.forEach(a => digest.phases[phaseNum].affects.add(a));
+          }
+
+          // Merge patterns
+          if (fm['patterns-established']) {
+            fm['patterns-established'].forEach(p => digest.phases[phaseNum].patterns.add(p));
+          }
+
+          // Merge decisions
+          if (fm['key-decisions']) {
+            fm['key-decisions'].forEach(d => {
+              digest.decisions.push({ phase: phaseNum, decision: d });
+            });
+          }
+
+          // Merge tech stack
+          if (fm['tech-stack'] && fm['tech-stack'].added) {
+            fm['tech-stack'].added.forEach(t => digest.tech_stack.add(typeof t === 'string' ? t : t.name));
+          }
+
+        } catch (err) {
+          logger.warn('Skipping malformed summary in cmdHistoryDigest', { summary, dirPath, error: err.message });
+        }
+      }
+    }
+
+    // Convert Sets to Arrays for JSON output
+    Object.keys(digest.phases).forEach(p => {
+      digest.phases[p].provides = [...digest.phases[p].provides];
+      digest.phases[p].affects = [...digest.phases[p].affects];
+      digest.phases[p].patterns = [...digest.phases[p].patterns];
+    });
+    digest.tech_stack = [...digest.tech_stack];
+
+    output(digest, raw);
+  } catch (err) {
+    logger.error('Failed to generate history digest', { error: err.message });
+    error('Failed to generate history digest: ' + err.message);
+  }
+}
+
+function cmdResolveModel(cwd, agentType, raw) {
+  if (!agentType) {
+    error('agent-type required');
+  }
+
+  const config = loadConfig(cwd);
+  const profile = config.model_profile || 'balanced';
+  const model = resolveModelInternal(cwd, agentType);
+
+  const agentModels = MODEL_PROFILES[agentType];
+  const result = agentModels
+    ? { model, profile }
+    : { model, profile, unknown_agent: true };
+  output(result, raw, model);
+}
+
+async function cmdCommit(cwd, message, files, raw, amend) {
+  if (!message && !amend) {
+    error('commit message required');
+  }
+
+  const config = loadConfig(cwd);
+
+  // Check commit_docs config
+  if (!config.commit_docs) {
+    const result = { committed: false, hash: null, reason: 'skipped_commit_docs_false' };
+    output(result, raw, 'skipped');
+    return;
+  }
+
+  // Check if .planning is gitignored
+  if (await isGitIgnored(cwd, '.planning')) {
+    const result = { committed: false, hash: null, reason: 'skipped_gitignored' };
+    output(result, raw, 'skipped');
+    return;
+  }
+
+  // Stage files
+  const filesToStage = files && files.length > 0 ? files : ['.planning/'];
+  for (const file of filesToStage) {
+    await execGit(cwd, ['add', file]);
+  }
+
+  // Commit
+  const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message];
+  const commitResult = await execGit(cwd, commitArgs);
+  if (commitResult.exitCode !== 0) {
+    if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
+      const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
+      output(result, raw, 'nothing');
+      return;
+    }
+    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
+    output(result, raw, 'nothing');
+    return;
+  }
+
+  // Get short hash
+  const hashResult = await execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
+  const result = { committed: true, hash, reason: 'committed' };
+  output(result, raw, hash || 'committed');
+}
+
+function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
+  if (!summaryPath) {
+    error('summary-path required for summary-extract');
+  }
+
+  const fullPath = path.join(cwd, summaryPath);
+
+  if (!fs.existsSync(fullPath)) {
+    output({ error: 'File not found', path: summaryPath }, raw);
+    return;
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+
+  // Parse key-decisions into structured format
+  const parseDecisions = (decisionsList) => {
+    if (!decisionsList || !Array.isArray(decisionsList)) return [];
+    return decisionsList.map(d => {
+      const colonIdx = d.indexOf(':');
+      if (colonIdx > 0) {
+        return {
+          summary: d.substring(0, colonIdx).trim(),
+          rationale: d.substring(colonIdx + 1).trim(),
+        };
+      }
+      return { summary: d, rationale: null };
+    });
+  };
+
+  // Build full result
+  const fullResult = {
+    path: summaryPath,
+    one_liner: fm['one-liner'] || null,
+    key_files: fm['key-files'] || [],
+    tech_added: (fm['tech-stack'] && fm['tech-stack'].added) || [],
+    patterns: fm['patterns-established'] || [],
+    decisions: parseDecisions(fm['key-decisions']),
+    requirements_completed: fm['requirements-completed'] || [],
+  };
+
+  // If fields specified, filter to only those fields
+  if (fields && fields.length > 0) {
+    const filtered = { path: summaryPath };
+    for (const field of fields) {
+      if (fullResult[field] !== undefined) {
+        filtered[field] = fullResult[field];
+      }
+    }
+    output(filtered, raw);
+    return;
+  }
+
+  output(fullResult, raw);
+}
+
+async function cmdWebsearch(query, options, raw) {
+  const apiKey = process.env.BRAVE_API_KEY;
+
+  if (!apiKey) {
+    // No key = silent skip, agent falls back to built-in WebSearch
+    output({ available: false, reason: 'BRAVE_API_KEY not set' }, raw, '');
+    return;
+  }
+
+  if (!query) {
+    output({ available: false, error: 'Query required' }, raw, '');
+    return;
+  }
+
+  const params = new URLSearchParams({
+    q: query,
+    count: String(options.limit || 10),
+    country: 'us',
+    search_lang: 'en',
+    text_decorations: 'false'
+  });
+
+  if (options.freshness) {
+    params.set('freshness', options.freshness);
+  }
+
+  try {
+    const response = await fetch(
+      `https://api.search.brave.com/res/v1/web/search?${params}`,
+      {
+        headers: {
+          'Accept': 'application/json',
+          'X-Subscription-Token': apiKey
+        }
+      }
+    );
+
+    if (!response.ok) {
+      output({ available: false, error: `API error: ${response.status}` }, raw, '');
+      return;
+    }
+
+    const data = await response.json();
+
+    const results = (data.web?.results || []).map(r => ({
+      title: r.title,
+      url: r.url,
+      description: r.description,
+      age: r.age || null
+    }));
+
+    output({
+      available: true,
+      query,
+      count: results.length,
+      results
+    }, raw, results.map(r => `${r.title}\n${r.url}\n${r.description}`).join('\n\n'));
+  } catch (err) {
+    logger.warn('Websearch request failed in cmdWebsearch', { query, error: err.message });
+    output({ available: false, error: err.message }, raw, '');
+  }
+}
+
+function cmdProgressRender(cwd, format, raw) {
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
+  const milestone = getMilestoneInfo(cwd);
+
+  const phases = [];
+  let totalPlans = 0;
+  let totalSummaries = 0;
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+
+    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 = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+
+      totalPlans += plans;
+      totalSummaries += summaries;
+
+      let status;
+      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 (err) {
+    logger.warn('Failed to enumerate phase directories in cmdProgressRender', { phasesDir, error: err.message });
+  }
+
+  const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
+
+  if (format === 'table') {
+    // Render markdown 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`;
+    out += `| Phase | Name | Plans | Status |\n`;
+    out += `|-------|------|-------|--------|\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 {
+    // JSON format
+    output({
+      milestone_version: milestone.version,
+      milestone_name: milestone.name,
+      phases,
+      total_plans: totalPlans,
+      total_summaries: totalSummaries,
+      percent,
+    }, raw);
+  }
+}
+
+function cmdTodoComplete(cwd, filename, raw) {
+  if (!filename) {
+    error('filename required for todo complete');
+  }
+
+  const pendingDir = path.join(cwd, '.planning', 'todos', 'pending');
+  const completedDir = path.join(cwd, '.planning', 'todos', 'completed');
+  const sourcePath = path.join(pendingDir, filename);
+
+  if (!fs.existsSync(sourcePath)) {
+    error(`Todo not found: ${filename}`);
+  }
+
+  // Ensure completed directory exists
+  fs.mkdirSync(completedDir, { recursive: true });
+
+  // Read, add completion timestamp, move
+  let content = fs.readFileSync(sourcePath, 'utf-8');
+  const today = new Date().toISOString().split('T')[0];
+  content = `completed: ${today}\n` + content;
+
+  fs.writeFileSync(path.join(completedDir, filename), content, 'utf-8');
+  fs.unlinkSync(sourcePath);
+
+  output({ completed: true, file: filename, date: today }, raw, 'completed');
+}
+
+function cmdScaffold(cwd, type, options, raw) {
+  const { phase, name } = options;
+  const padded = phase ? normalizePhaseName(phase) : '00';
+  const today = new Date().toISOString().split('T')[0];
+
+  // Find phase directory
+  const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
+  const phaseDir = phaseInfo ? path.join(cwd, phaseInfo.directory) : null;
+
+  if (phase && !phaseDir && type !== 'phase-dir') {
+    error(`Phase ${phase} directory not found`);
+  }
+
+  let filePath, content;
+
+  switch (type) {
+    case 'context': {
+      filePath = path.join(phaseDir, `${padded}-CONTEXT.md`);
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Context\n\n## Decisions\n\n_Decisions will be captured during /ez-discuss-phase ${phase}_\n\n## Discretion Areas\n\n_Areas where the executor can use judgment_\n\n## Deferred Ideas\n\n_Ideas to consider later_\n`;
+      break;
+    }
+    case 'uat': {
+      filePath = path.join(phaseDir, `${padded}-UAT.md`);
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — User Acceptance Testing\n\n## Test Results\n\n| # | Test | Status | Notes |\n|---|------|--------|-------|\n\n## Summary\n\n_Pending UAT_\n`;
+      break;
+    }
+    case 'verification': {
+      filePath = path.join(phaseDir, `${padded}-VERIFICATION.md`);
+      content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || 'Unnamed'}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || 'Unnamed'} — Verification\n\n## Goal-Backward Verification\n\n**Phase Goal:** [From ROADMAP.md]\n\n## Checks\n\n| # | Requirement | Status | Evidence |\n|---|------------|--------|----------|\n\n## Result\n\n_Pending verification_\n`;
+      break;
+    }
+    case 'phase-dir': {
+      if (!phase || !name) {
+        error('phase and name required for phase-dir scaffold');
+      }
+      const slug = generateSlugInternal(name);
+      const dirName = `${padded}-${slug}`;
+      const phasesParent = path.join(cwd, '.planning', 'phases');
+      fs.mkdirSync(phasesParent, { recursive: true });
+      const dirPath = path.join(phasesParent, dirName);
+      fs.mkdirSync(dirPath, { recursive: true });
+      output({ created: true, directory: `.planning/phases/${dirName}`, path: dirPath }, raw, dirPath);
+      return;
+    }
+    default:
+      error(`Unknown scaffold type: ${type}. Available: context, uat, verification, phase-dir`);
+  }
+
+  if (fs.existsSync(filePath)) {
+    output({ created: false, reason: 'already_exists', path: filePath }, raw, 'exists');
+    return;
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+  const relPath = toPosixPath(path.relative(cwd, filePath));
+  output({ created: true, path: relPath }, raw, relPath);
+}
+
+async function cmdStats(cwd, format, raw) {
+  const phasesDir = path.join(cwd, '.planning', 'phases');
+  const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+  const statePath = path.join(cwd, '.planning', 'STATE.md');
+  const milestone = getMilestoneInfo(cwd);
+
+  // Phase & plan stats (reuse progress pattern)
+  const phases = [];
+  let totalPlans = 0;
+  let totalSummaries = 0;
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+
+    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 = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').length;
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md').length;
+
+      totalPlans += plans;
+      totalSummaries += summaries;
+
+      let status;
+      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 (err) {
+    logger.warn('Failed to enumerate phase directories in cmdStats', { phasesDir, error: err.message });
+  }
+
+  const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
+
+  // Requirements stats
+  let requirementsTotal = 0;
+  let requirementsComplete = 0;
+  try {
+    if (fs.existsSync(reqPath)) {
+      const reqContent = fs.readFileSync(reqPath, 'utf-8');
+      const checked = reqContent.match(/^- \[x\] \*\*/gm);
+      const unchecked = reqContent.match(/^- \[ \] \*\*/gm);
+      requirementsComplete = checked ? checked.length : 0;
+      requirementsTotal = requirementsComplete + (unchecked ? unchecked.length : 0);
+    }
+  } catch (err) {
+    logger.warn('Failed to parse REQUIREMENTS.md in cmdStats', { reqPath, error: err.message });
+  }
+
+  // Last activity from STATE.md
+  let lastActivity = null;
+  try {
+    if (fs.existsSync(statePath)) {
+      const stateContent = fs.readFileSync(statePath, 'utf-8');
+      const activityMatch = stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/);
+      if (activityMatch) lastActivity = activityMatch[1].trim();
+    }
+  } catch (err) {
+    logger.warn('Failed to read STATE.md in cmdStats', { statePath, error: err.message });
+  }
+
+  // Git stats
+  let gitCommits = 0;
+  let gitFirstCommitDate = null;
+  try {
+    const commitCount = await execGit(cwd, ['rev-list', '--count', 'HEAD']);
+    gitCommits = parseInt(commitCount.trim(), 10) || 0;
+    const firstDate = await execGit(cwd, ['log', '--reverse', '--format=%as', '--max-count=1']);
+    gitFirstCommitDate = firstDate.trim() || null;
+  } catch (err) {
+    logger.warn('Failed to compute git stats in cmdStats', { cwd, error: err.message });
+  }
+
+  const completedPhases = phases.filter(p => p.status === 'Complete').length;
+
+  const result = {
+    milestone_version: milestone.version,
+    milestone_name: milestone.name,
+    phases,
+    phases_completed: completedPhases,
+    phases_total: phases.length,
+    total_plans: totalPlans,
+    total_summaries: totalSummaries,
+    percent,
+    requirements_total: requirementsTotal,
+    requirements_complete: requirementsComplete,
+    git_commits: gitCommits,
+    git_first_commit_date: gitFirstCommitDate,
+    last_activity: lastActivity,
+  };
+
+  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} \u2014 Statistics\n\n`;
+    out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n`;
+    out += `**Phases:** ${completedPhases}/${phases.length} complete\n`;
+    if (requirementsTotal > 0) {
+      out += `**Requirements:** ${requirementsComplete}/${requirementsTotal} complete\n`;
+    }
+    out += '\n';
+    out += `| Phase | Name | Plans | Completed | Status |\n`;
+    out += `|-------|------|-------|-----------|--------|\n`;
+    for (const p of phases) {
+      out += `| ${p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${p.status} |\n`;
+    }
+    if (gitCommits > 0) {
+      out += `\n**Git:** ${gitCommits} commits`;
+      if (gitFirstCommitDate) out += ` (since ${gitFirstCommitDate})`;
+      out += '\n';
+    }
+    if (lastActivity) out += `**Last activity:** ${lastActivity}\n`;
+    output({ rendered: out }, raw, out);
+  } else {
+    output(result, raw);
+  }
+}
+
+module.exports = {
+  cmdGenerateSlug,
+  cmdCurrentTimestamp,
+  cmdListTodos,
+  cmdVerifyPathExists,
+  cmdHistoryDigest,
+  cmdResolveModel,
+  cmdCommit,
+  cmdSummaryExtract,
+  cmdWebsearch,
+  cmdProgressRender,
+  cmdTodoComplete,
+  cmdScaffold,
+  cmdStats,
+};