@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/review.cjs

@@ -0,0 +1,1821 @@
+/**
+ * Review — Diff report generation for milestones and quick tasks
+ *
+ * Generates structured REVIEW.md files from git diff data.
+ * Default mode uses git stat + commit log (no LLM calls).
+ * Detailed mode uses LLM for per-file summaries and overall narrative.
+ *
+ * Exports: generateDiffReport, generateDiffReportFromJob,
+ *          cmdJobsGenerateReview, cmdQuickGenerateReview
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { output, error, safeReadFile, loadConfig } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+
+// ─── Repo Resolution ────────────────────────────────────────────────────────
+
+/**
+ * Parse REPOS.md and resolve absolute paths for each registered repo.
+ * Reuses the same pattern from recordStartShas in jobs.cjs.
+ *
+ * @param {string} planningRoot - Absolute path to the planning root
+ * @returns {Object} Map of repo name to absolute repo path
+ */
+function resolveRepoPathsFromReposMd(planningRoot) {
+  const reposPath = path.join(planningRoot, 'REPOS.md');
+  const repoMap = {};
+
+  if (!fs.existsSync(reposPath)) {
+    return repoMap;
+  }
+
+  const content = fs.readFileSync(reposPath, 'utf-8');
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/^\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/);
+    if (!match) continue;
+    const name = match[1].trim();
+    const repoPath = match[2].trim();
+    // Skip header row and separator
+    if (name === 'Name' || name.startsWith('-')) continue;
+    if (!repoPath || repoPath.startsWith('-')) continue;
+
+    // Resolve absolute path: paths in REPOS.md are relative to the planning root
+    const absRepoPath = path.resolve(planningRoot, repoPath);
+    if (fs.existsSync(absRepoPath)) {
+      repoMap[name] = absRepoPath;
+    }
+  }
+
+  return repoMap;
+}
+
+/**
+ * Look up the active milestone worktree's repo paths from config.local.json.
+ * A milestone worktree exists for the duration of the milestone branch before
+ * it is merged back to main. There is at most one active milestone worktree
+ * per project. Returns null if no milestone worktree is registered for the
+ * current project (typical post-complete-milestone state), in which case
+ * callers should fall back to REPOS.md main paths.
+ *
+ * @param {string} planningRoot - Absolute path to the planning root
+ * @returns {Object|null} Map of repo name to worktree absolute path, or null
+ */
+function getActiveMilestoneWorktreeRepos(planningRoot) {
+  const localConfigPath = path.join(planningRoot, 'config.local.json');
+  if (!fs.existsSync(localConfigPath)) return null;
+
+  let local;
+  try {
+    local = JSON.parse(fs.readFileSync(localConfigPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+
+  const currentProject = local.current_project;
+  if (!currentProject) return null;
+
+  const projectEntry = local.projects && local.projects[currentProject];
+  if (!projectEntry || !projectEntry.worktrees) return null;
+
+  // At most one milestone worktree per project — pick the first type:'milestone' entry
+  for (const wt of Object.values(projectEntry.worktrees)) {
+    if (wt && wt.type === 'milestone' && wt.repos) {
+      return wt.repos;
+    }
+  }
+
+  return null;
+}
+
+// ─── Git Operations ─────────────────────────────────────────────────────────
+
+/**
+ * Run a git command in a repo directory, returning stdout or null on failure.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} cmd - Git command arguments (after 'git')
+ * @returns {string|null} Command stdout, or null on error
+ */
+function gitCmd(repoPath, cmd) {
+  try {
+    return execSync(`git ${cmd}`, { cwd: repoPath, stdio: 'pipe' }).toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gather diff data for a single repo between startSha and HEAD.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} startSha - Start SHA for the diff range
+ * @returns {Object} Structured diff data for the repo
+ */
+function gatherRepoDiff(repoPath, startSha) {
+  // Get commit log
+  const logOutput = gitCmd(repoPath, `log --oneline ${startSha}..HEAD`);
+  const logLines = logOutput ? logOutput.trim().split('\n').filter(l => l.trim()) : [];
+
+  // Get file status (A/M/D/R)
+  const nameStatusOutput = gitCmd(repoPath, `diff --name-status -M ${startSha}..HEAD`);
+  const nameStatusLines = nameStatusOutput
+    ? nameStatusOutput.trim().split('\n').filter(l => l.trim())
+    : [];
+
+  // Get numstat for insertions/deletions per file
+  const numstatOutput = gitCmd(repoPath, `diff --numstat ${startSha}..HEAD`);
+  const numstatLines = numstatOutput
+    ? numstatOutput.trim().split('\n').filter(l => l.trim())
+    : [];
+
+  // Build numstat lookup: filePath -> { insertions, deletions }
+  const numstatMap = {};
+  for (const line of numstatLines) {
+    const parts = line.split('\t');
+    if (parts.length >= 3) {
+      const ins = parts[0] === '-' ? 0 : parseInt(parts[0], 10) || 0;
+      const del = parts[1] === '-' ? 0 : parseInt(parts[1], 10) || 0;
+      const filePath = parts.slice(2).join('\t'); // handle paths with tabs (rare)
+      numstatMap[filePath] = { insertions: ins, deletions: del };
+    }
+  }
+
+  // Parse name-status into structured file entries
+  const files = [];
+  let totalInsertions = 0;
+  let totalDeletions = 0;
+
+  for (const line of nameStatusLines) {
+    const parts = line.split('\t');
+    if (parts.length < 2) continue;
+
+    const statusChar = parts[0].trim();
+    let filePath, oldPath = null, status;
+
+    if (statusChar.startsWith('R')) {
+      // Rename: R{score}\told/path\tnew/path
+      oldPath = parts[1];
+      filePath = parts[2] || parts[1];
+      status = 'moved';
+    } else if (statusChar === 'A') {
+      filePath = parts[1];
+      status = 'new';
+    } else if (statusChar === 'D') {
+      filePath = parts[1];
+      status = 'deleted';
+    } else if (statusChar === 'M') {
+      filePath = parts[1];
+      status = 'modified';
+    } else {
+      filePath = parts[1];
+      status = 'modified'; // fallback for C (copy), T (type change), etc.
+    }
+
+    const stats = numstatMap[filePath] || numstatMap[oldPath] || { insertions: 0, deletions: 0 };
+    totalInsertions += stats.insertions;
+    totalDeletions += stats.deletions;
+
+    // Get most recent commit message that touched this file in the range
+    const description = getFileDescription(repoPath, startSha, filePath);
+
+    files.push({
+      path: filePath,
+      status,
+      insertions: stats.insertions,
+      deletions: stats.deletions,
+      oldPath,
+      description,
+    });
+  }
+
+  return {
+    commitCount: logLines.length,
+    stats: {
+      filesChanged: files.length,
+      insertions: totalInsertions,
+      deletions: totalDeletions,
+    },
+    files,
+  };
+}
+
+/**
+ * Get the most recent commit message that touched a file in a given range.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} startSha - Start SHA for the range
+ * @param {string} filePath - Relative file path within the repo
+ * @returns {string} Most recent commit subject line, or empty string
+ */
+function getFileDescription(repoPath, startSha, filePath) {
+  const result = gitCmd(repoPath, `log -1 --format="%s" ${startSha}..HEAD -- "${filePath}"`);
+  return result ? result.trim() : '';
+}
+
+// ─── Configuration File Detection ──────────────────────────────────────────
+
+const CONFIG_PATTERNS = [
+  'package.json',
+  'package-lock.json',
+  /\.config\.[jt]s$/,
+  /^\.env/,
+  /^tsconfig/,
+  /^\.github\//,
+  'config.json',
+  'config.local.json',
+  'STATE.md',
+];
+
+// ─── Collapse Thresholds ──────────────────────────────────────────────────
+const COLLAPSE_FILE_THRESHOLD = 50;   // repos with more than this many files trigger collapse
+const COLLAPSE_LINE_THRESHOLD = 5;    // files with fewer than this many combined lines are "minor"
+
+/**
+ * Check if a file path matches any known configuration file pattern.
+ *
+ * @param {string} filePath - Relative file path within the repo
+ * @returns {boolean} True if the file is a configuration file
+ */
+function isConfigFile(filePath) {
+  const basename = path.basename(filePath);
+  for (const pattern of CONFIG_PATTERNS) {
+    if (typeof pattern === 'string') {
+      if (basename === pattern) return true;
+    } else if (pattern instanceof RegExp) {
+      if (pattern.test(filePath) || pattern.test(basename)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Generate a bold risk annotation for a configuration file.
+ *
+ * @param {Object} file - File entry with path, insertions, deletions, status
+ * @returns {string} Bold risk annotation string
+ */
+function generateConfigRiskAnnotation(file) {
+  const basename = path.basename(file.path);
+
+  if (basename === 'package.json') {
+    return '**dependencies changed**';
+  }
+
+  if (basename === 'package-lock.json') {
+    return '**lockfile updated**';
+  }
+
+  if (/^\.env/.test(basename)) {
+    return '**environment variables changed**';
+  }
+
+  if (/^\.github\//.test(file.path)) {
+    return '**CI/CD configuration changed**';
+  }
+
+  if (/^tsconfig/.test(basename)) {
+    return '**TypeScript configuration changed**';
+  }
+
+  return '**settings changed**';
+}
+
+// ─── Rendering ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the stats banner line.
+ *
+ * @param {Object} totals - Aggregated stats across all repos
+ * @param {number} repoCount - Number of repos with changes
+ * @param {number} [riskFlagCount=0] - Number of risk flags detected
+ * @returns {string} Formatted stats banner
+ */
+function buildStatsBanner(totals, repoCount, riskFlagCount) {
+  let banner = `${totals.commits} commits | ${totals.filesChanged} files changed | +${totals.insertions} -${totals.deletions} | ${repoCount} repos`;
+  if (riskFlagCount > 0) {
+    banner += ` | ${riskFlagCount} risk flags`;
+  }
+  return banner;
+}
+
+/**
+ * Render aggregate statistics across all repos for multi-repo reports.
+ * Returns empty string for single-repo reports (caller should omit section).
+ *
+ * @param {Array} repoResults - Array of { name, diff } objects
+ * @param {Object} totals - Aggregated stats { commits, filesChanged, insertions, deletions }
+ * @returns {string} Rendered markdown for aggregate statistics section
+ */
+function renderAggregateStats(repoResults, totals) {
+  // Filter to repos with actual changes
+  const activeRepos = repoResults.filter(r => r.diff.files.length > 0);
+  if (activeRepos.length <= 1) return '';
+
+  const lines = [];
+
+  // Summary totals line
+  lines.push(`**Totals:** ${totals.commits} commits | ${totals.filesChanged} files changed | +${totals.insertions} -${totals.deletions}`);
+  lines.push('');
+
+  // Per-repo breakdown table
+  lines.push('| Repository | Commits | Files | Insertions | Deletions |');
+  lines.push('|------------|---------|-------|------------|-----------|');
+  for (const repo of activeRepos) {
+    lines.push(`| ${repo.name} | ${repo.diff.commitCount} | ${repo.diff.stats.filesChanged} | +${repo.diff.stats.insertions} | -${repo.diff.stats.deletions} |`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render the Code Changes section with per-repo blocks.
+ *
+ * @param {Array} repoResults - Array of { name, startSha, diff } objects
+ * @returns {string} Rendered markdown for all repos
+ */
+function renderCodeChanges(repoResults) {
+  const sections = [];
+
+  for (const repo of repoResults) {
+    const { name, diff } = repo;
+    if (diff.files.length === 0) continue;
+
+    const header = `### ${name} (${diff.commitCount} commits, +${diff.stats.insertions} -${diff.stats.deletions})`;
+
+    // Group files by status and sort alphabetically within each category
+    const groups = {
+      new: diff.files.filter(f => f.status === 'new').sort((a, b) => a.path.localeCompare(b.path)),
+      modified: diff.files.filter(f => f.status === 'modified').sort((a, b) => a.path.localeCompare(b.path)),
+      deleted: diff.files.filter(f => f.status === 'deleted').sort((a, b) => a.path.localeCompare(b.path)),
+      moved: diff.files.filter(f => f.status === 'moved').sort((a, b) => a.path.localeCompare(b.path)),
+    };
+
+    // Separate config files from regular files
+    const configFiles = [];
+    for (const key of ['new', 'modified', 'deleted', 'moved']) {
+      const regular = [];
+      for (const f of groups[key]) {
+        if (isConfigFile(f.path)) {
+          configFiles.push(f);
+        } else {
+          regular.push(f);
+        }
+      }
+      groups[key] = regular;
+    }
+    configFiles.sort((a, b) => a.path.localeCompare(b.path));
+
+    // Collapse minor files when repo has many changes (TMPL-05)
+    // Minor = combined (insertions + deletions) < COLLAPSE_LINE_THRESHOLD
+    // Config files are NEVER collapsed (already separated above)
+    let collapsedSummary = '';
+    if (diff.files.length > COLLAPSE_FILE_THRESHOLD) {
+      const minorFiles = { new: 0, modified: 0, deleted: 0, moved: 0 };
+      let minorTotal = 0;
+
+      for (const key of ['new', 'modified', 'deleted', 'moved']) {
+        const regular = [];
+        for (const f of groups[key]) {
+          const totalLines = f.insertions + f.deletions;
+          if (totalLines < COLLAPSE_LINE_THRESHOLD) {
+            minorFiles[key]++;
+            minorTotal++;
+          } else {
+            regular.push(f);
+          }
+        }
+        groups[key] = regular;
+      }
+
+      if (minorTotal > 0) {
+        const breakdown = [];
+        if (minorFiles.modified > 0) breakdown.push(`${minorFiles.modified} modified`);
+        if (minorFiles.new > 0) breakdown.push(`${minorFiles.new} new`);
+        if (minorFiles.deleted > 0) breakdown.push(`${minorFiles.deleted} deleted`);
+        if (minorFiles.moved > 0) breakdown.push(`${minorFiles.moved} moved`);
+        collapsedSummary = `**Minor changes (${minorTotal} files):** ${breakdown.join(', ')}`;
+      }
+    }
+
+    const parts = [header, ''];
+
+    if (groups.new.length > 0) {
+      parts.push(`**New files (${groups.new.length}):**`);
+      for (const f of groups.new) {
+        const desc = f.description ? ` \u2014 ${f.description}` : '';
+        parts.push(`- ${f.path} (+${f.insertions} -${f.deletions})${desc}`);
+      }
+      parts.push('');
+    }
+
+    if (groups.modified.length > 0) {
+      parts.push(`**Modified (${groups.modified.length}):**`);
+      for (const f of groups.modified) {
+        const desc = f.description ? ` \u2014 ${f.description}` : '';
+        parts.push(`- ${f.path} (+${f.insertions} -${f.deletions})${desc}`);
+      }
+      parts.push('');
+    }
+
+    if (groups.deleted.length > 0) {
+      parts.push(`**Deleted (${groups.deleted.length}):**`);
+      for (const f of groups.deleted) {
+        parts.push(`- ${f.path} (-${f.deletions})`);
+      }
+      parts.push('');
+    }
+
+    if (groups.moved.length > 0) {
+      parts.push(`**Moved (${groups.moved.length}):**`);
+      for (const f of groups.moved) {
+        // Pure renames (no content changes) show no line counts
+        if (f.insertions === 0 && f.deletions === 0) {
+          parts.push(`- ${f.oldPath} \u2192 ${f.path}`);
+        } else {
+          parts.push(`- ${f.oldPath} \u2192 ${f.path} (+${f.insertions} -${f.deletions})`);
+        }
+      }
+      parts.push('');
+    }
+
+    // Configuration Changes subsection
+    if (configFiles.length > 0) {
+      parts.push(`**Configuration Changes (${configFiles.length}):**`);
+      for (const f of configFiles) {
+        const risk = generateConfigRiskAnnotation(f);
+        const counts = f.status === 'deleted'
+          ? `(-${f.deletions})`
+          : `(+${f.insertions} -${f.deletions})`;
+        parts.push(`- ${f.path} ${counts} \u2014 ${risk}`);
+      }
+      parts.push('');
+    }
+
+    // Minor changes collapsed summary (after all regular categories)
+    if (collapsedSummary) {
+      parts.push(collapsedSummary);
+      parts.push('');
+    }
+
+    sections.push(parts.join('\n'));
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Remove a section (## Header + placeholder) from template content
+ * when the section has no data.
+ *
+ * @param {string} content - Template content
+ * @param {string} header - Section header (e.g., "## Goal")
+ * @param {string} placeholder - Placeholder name (e.g., "{goal}")
+ * @returns {string} Content with section removed
+ */
+function removeSection(content, header, placeholder) {
+  // Remove the header line, the placeholder line, and any blank line after
+  const headerEscaped = header.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const placeholderEscaped = placeholder.replace(/[{}]/g, '\\$&');
+  const pattern = new RegExp(
+    `${headerEscaped}\\n\\n${placeholderEscaped}\\n?\\n?`,
+    'g'
+  );
+  return content.replace(pattern, '');
+}
+
+// ─── Content Extraction ────────────────────────────────────────────────────
+
+/**
+ * Extract the milestone goal from ROADMAP.md.
+ *
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} projectRoot - Relative project root (e.g., "projects/gsd")
+ * @param {string} milestoneVersion - Milestone version (e.g., "v22.0")
+ * @returns {string|null} Goal text or null if not found
+ */
+function extractGoalFromRoadmap(planningRoot, projectRoot, milestoneVersion) {
+  const roadmapPath = path.join(planningRoot, projectRoot, 'ROADMAP.md');
+  const content = safeReadFile(roadmapPath);
+  if (!content) return null;
+
+  // Find milestone section and extract goal
+  const milestonePattern = new RegExp(
+    `###?\\s+${milestoneVersion.replace(/\./g, '\\.')}\\s+[^\\n]*\\n[\\s\\S]*?\\*\\*Milestone Goal:\\*\\*\\s*([^\\n]+)`,
+    'i'
+  );
+  const match = content.match(milestonePattern);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Extract What Was Built from SUMMARY.md one-liners across all phases.
+ *
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} projectRoot - Relative project root (e.g., "projects/gsd")
+ * @param {string} roadmapContent - ROADMAP.md content for fallback goal text
+ * @returns {string} Formatted What Was Built markdown section
+ */
+function extractWhatWasBuiltFromSummaries(planningRoot, projectRoot, roadmapContent) {
+  const phasesDir = path.join(planningRoot, projectRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return '';
+
+  const phaseDirs = fs.readdirSync(phasesDir)
+    .filter(d => /^\d+/.test(d))
+    .sort((a, b) => {
+      const numA = parseInt(a.match(/^(\d+)/)[1], 10);
+      const numB = parseInt(b.match(/^(\d+)/)[1], 10);
+      return numA - numB;
+    });
+
+  const lines = [];
+  let index = 1;
+
+  for (const dir of phaseDirs) {
+    const phaseNum = dir.match(/^(\d+)/)[1];
+    const phaseName = dir.replace(/^\d+-/, '').replace(/-/g, ' ');
+    const phaseFullDir = path.join(phasesDir, dir);
+
+    // Find SUMMARY.md files in this phase directory
+    const summaryFiles = fs.readdirSync(phaseFullDir)
+      .filter(f => f.endsWith('-SUMMARY.md'))
+      .sort();
+
+    if (summaryFiles.length === 0) {
+      // Fallback: use ROADMAP goal text
+      const goalMatch = roadmapContent
+        ? roadmapContent.match(new RegExp(`Phase ${phaseNum}[^\\n]*\\n\\*\\*Goal\\*\\*:\\s*([^\\n]+)`, 'i'))
+        : null;
+      const fallback = goalMatch ? goalMatch[1].trim() : phaseName;
+      lines.push(`${index}. Phase ${phaseNum}: ${fallback} (no summary available)`);
+      index++;
+      continue;
+    }
+
+    for (const summaryFile of summaryFiles) {
+      const content = safeReadFile(path.join(phaseFullDir, summaryFile));
+      if (!content) continue;
+      const fm = extractFrontmatter(content);
+      const oneLiner = fm['one-liner'] || null;
+
+      if (oneLiner) {
+        lines.push(`${index}. Phase ${phaseNum}: ${oneLiner}`);
+      } else {
+        // Extract first line of body after frontmatter as fallback
+        const bodyMatch = content.match(/---[\s\S]*?---\s*\n#?\s*([^\n]+)/);
+        const bodyLine = bodyMatch ? bodyMatch[1].replace(/^#+\s*/, '').trim() : phaseName;
+        lines.push(`${index}. Phase ${phaseNum}: ${bodyLine}`);
+      }
+      index++;
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Extract What Was Built from commit messages (for quick tasks).
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} startSha - Start SHA (merge-base)
+ * @returns {string} Formatted bullet list of commit messages
+ */
+function extractWhatWasBuiltFromCommits(repoPath, startSha) {
+  const logOutput = gitCmd(repoPath, `log --oneline --no-merges ${startSha}..HEAD`);
+  if (!logOutput || !logOutput.trim()) return '';
+
+  const seen = new Set();
+  const lines = [];
+  for (const line of logOutput.trim().split('\n')) {
+    // Remove SHA prefix to get message
+    const msg = line.replace(/^[a-f0-9]+\s+/, '').trim();
+    if (msg && !seen.has(msg)) {
+      seen.add(msg);
+      lines.push(`- ${msg}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build an overall narrative describing the architectural shift or nature of changes.
+ *
+ * @param {Object} options - Report options (title, goal, mode)
+ * @param {Object} totals - Aggregated stats { commits, filesChanged, insertions, deletions }
+ * @param {number} repoCount - Number of repos with changes
+ * @param {Array} repoResults - Array of { name, diff } objects
+ * @returns {string} 2-3 sentence narrative
+ */
+function buildOverallNarrative(options, totals, repoCount, repoResults) {
+  const parts = [];
+
+  // Sentence 1: What the milestone/task achieved (from goal)
+  if (options.goal) {
+    parts.push(options.goal.replace(/\.$/, '') + '.');
+  }
+
+  // Sentence 2: Scope summary
+  const repoNames = repoResults.filter(r => r.diff.files.length > 0).map(r => r.name);
+  if (repoNames.length === 1) {
+    parts.push(`Changes span ${totals.filesChanged} files across ${totals.commits} commits in ${repoNames[0]}, with a net delta of +${totals.insertions} -${totals.deletions} lines.`);
+  } else if (repoNames.length > 1) {
+    parts.push(`Changes span ${totals.filesChanged} files across ${totals.commits} commits in ${repoNames.length} repositories (${repoNames.join(', ')}), with a net delta of +${totals.insertions} -${totals.deletions} lines.`);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Extract verification data from phase VERIFICATION.md files.
+ * Returns tiered format: summary line + collapsible per-phase details.
+ *
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} projectRoot - Relative project root
+ * @returns {string|null} Formatted verification section or null if no data
+ */
+function extractVerificationData(planningRoot, projectRoot) {
+  const phasesDir = path.join(planningRoot, projectRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const phaseDirs = fs.readdirSync(phasesDir)
+    .filter(d => /^\d+/.test(d))
+    .sort((a, b) => {
+      const numA = parseInt(a.match(/^(\d+)/)[1], 10);
+      const numB = parseInt(b.match(/^(\d+)/)[1], 10);
+      return numA - numB;
+    });
+
+  let totalReqsVerified = 0;
+  let totalReqs = 0;
+  let totalTestsPassed = 0;
+  let totalHumanReview = 0;
+  const phaseDetails = [];
+
+  for (const dir of phaseDirs) {
+    const phaseNum = dir.match(/^(\d+)/)[1];
+    const phaseFullDir = path.join(phasesDir, dir);
+
+    // Find VERIFICATION.md files
+    const verFiles = fs.readdirSync(phaseFullDir)
+      .filter(f => f.endsWith('-VERIFICATION.md'))
+      .sort();
+
+    for (const vf of verFiles) {
+      const content = safeReadFile(path.join(phaseFullDir, vf));
+      if (!content) continue;
+
+      // Parse verification counts from content
+      // Look for patterns like "X/Y requirements verified" or pass/fail counts
+      const reqMatch = content.match(/(\d+)\s*\/\s*(\d+)\s*(?:requirements?\s+)?(?:verified|passed)/i);
+      if (reqMatch) {
+        totalReqsVerified += parseInt(reqMatch[1], 10);
+        totalReqs += parseInt(reqMatch[2], 10);
+      }
+
+      // Look for test pass counts
+      const testMatch = content.match(/(\d+)\s+tests?\s+passed/i);
+      if (testMatch) {
+        totalTestsPassed += parseInt(testMatch[1], 10);
+      }
+
+      // Look for human review needed items
+      const humanMatch = content.match(/(\d+)\s+(?:items?\s+)?(?:need|require)\s+human\s+review/i);
+      if (humanMatch) {
+        totalHumanReview += parseInt(humanMatch[1], 10);
+      }
+
+      phaseDetails.push({ phaseNum, file: vf, content });
+    }
+  }
+
+  // If no verification data found, return null (section will be omitted)
+  if (phaseDetails.length === 0) return null;
+
+  // Build tiered output
+  const lines = [];
+
+  // Summary line
+  const summaryParts = [];
+  if (totalReqs > 0) {
+    summaryParts.push(`${totalReqsVerified}/${totalReqs} requirements verified`);
+  }
+  if (totalTestsPassed > 0) {
+    summaryParts.push(`${totalTestsPassed} tests passed`);
+  }
+  if (totalHumanReview > 0) {
+    summaryParts.push(`${totalHumanReview} items need human review`);
+  }
+  if (summaryParts.length > 0) {
+    lines.push(summaryParts.join(', '));
+  }
+
+  // Per-phase collapsible details
+  if (phaseDetails.length > 0) {
+    lines.push('');
+    lines.push('<details>');
+    lines.push('<summary>Per-phase verification details</summary>');
+    lines.push('');
+    for (const pd of phaseDetails) {
+      lines.push(`#### Phase ${pd.phaseNum}`);
+      // Extract the meaningful content (skip frontmatter)
+      const body = pd.content.replace(/^---[\s\S]*?---\s*\n?/, '').trim();
+      // Take first meaningful section (up to 20 lines to keep it concise)
+      const bodyLines = body.split('\n').slice(0, 20);
+      lines.push(bodyLines.join('\n'));
+      lines.push('');
+    }
+    lines.push('</details>');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Risk Detection Engine ─────────────────────────────────────────────────
+
+/**
+ * Detect files with large changes (>100 lines changed).
+ * Excludes moved/renamed files (misleading line counts).
+ *
+ * @param {string} repoName - Repository name
+ * @param {Array} files - Files array from gatherRepoDiff()
+ * @returns {Array} Risk flag objects of type 'large_change'
+ */
+function detectLargeChanges(repoName, files) {
+  const flags = [];
+  for (const f of files) {
+    if (f.status === 'moved') continue; // exclude renames — misleading line counts
+    const total = f.insertions + f.deletions;
+    if (total > 100) {
+      flags.push({
+        type: 'large_change',
+        repo: repoName,
+        text: `${repoName}: ${f.path} (+${f.insertions} -${f.deletions}, ${total} total)`,
+      });
+    }
+  }
+  return flags;
+}
+
+/**
+ * Detect dependency changes by parsing package.json diffs.
+ * Classifies changes as New, Updated, or Removed.
+ * Lock file changes do not trigger separate flags.
+ *
+ * @param {string} repoName - Repository name
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} startSha - Start SHA for diff range
+ * @param {Array} files - Files array from gatherRepoDiff()
+ * @returns {Array} Risk flag objects of type 'dependency_change'
+ */
+function detectDependencyChanges(repoName, repoPath, startSha, files) {
+  const flags = [];
+
+  // Only look at package.json changes (not lock files per CONTEXT.md)
+  const pkgFiles = files.filter(f =>
+    path.basename(f.path) === 'package.json' && f.status !== 'deleted'
+  );
+  if (pkgFiles.length === 0) return flags;
+
+  for (const pkgFile of pkgFiles) {
+    const diffOutput = gitCmd(repoPath, `diff ${startSha}..HEAD -- "${pkgFile.path}"`);
+    if (!diffOutput) continue;
+
+    const lines = diffOutput.split('\n');
+    // Track added and removed dependency lines
+    const added = [];   // { name, version }
+    const removed = []; // { name, version }
+
+    // Simple heuristic: lines matching +"name": "version" or -"name": "version"
+    // within a dependencies-like section
+    const nonDepKeys = /^(name|version|description|main|module|types|scripts|repository|author|license|engines|private|type|files|bin|keywords|homepage|bugs|publishConfig|exports|workspaces|packageManager)$/;
+    for (const line of lines) {
+      const addMatch = line.match(/^\+\s*"([^"]+)"\s*:\s*"([^"]+)"/);
+      const remMatch = line.match(/^-\s*"([^"]+)"\s*:\s*"([^"]+)"/);
+      if (addMatch) {
+        const name = addMatch[1];
+        const ver = addMatch[2];
+        if (!nonDepKeys.test(name)) {
+          added.push({ name, version: ver });
+        }
+      }
+      if (remMatch) {
+        const name = remMatch[1];
+        const ver = remMatch[2];
+        if (!nonDepKeys.test(name)) {
+          removed.push({ name, version: ver });
+        }
+      }
+    }
+
+    // Classify: New (added but not removed), Updated (both added and removed), Removed (removed but not added)
+    const removedNames = new Set(removed.map(r => r.name));
+    const addedNames = new Set(added.map(a => a.name));
+
+    for (const dep of added) {
+      if (removedNames.has(dep.name)) {
+        // Updated — find old version
+        const old = removed.find(r => r.name === dep.name);
+        flags.push({
+          type: 'dependency_change',
+          repo: repoName,
+          text: `Updated: ${dep.name} ${old.version}->${dep.version}`,
+        });
+      } else {
+        // New
+        flags.push({
+          type: 'dependency_change',
+          repo: repoName,
+          text: `New: ${dep.name}@${dep.version}`,
+        });
+      }
+    }
+
+    for (const dep of removed) {
+      if (!addedNames.has(dep.name)) {
+        // Removed
+        flags.push({
+          type: 'dependency_change',
+          repo: repoName,
+          text: `Removed: ${dep.name}@${dep.version}`,
+        });
+      }
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Detect items marked as needing human review from VERIFICATION.md and UAT files.
+ *
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} projectRoot - Relative project root (e.g., "projects/gsd")
+ * @returns {Array} Risk flag objects of type 'human_review'
+ */
+function detectHumanReviewNeeded(planningRoot, projectRoot) {
+  const flags = [];
+  if (!planningRoot || !projectRoot) return flags;
+
+  const phasesDir = path.join(planningRoot, projectRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return flags;
+
+  const phaseDirs = fs.readdirSync(phasesDir)
+    .filter(d => /^\d+/.test(d))
+    .sort();
+
+  for (const dir of phaseDirs) {
+    const phaseFullDir = path.join(phasesDir, dir);
+    const phaseNum = dir.match(/^(\d+)/)[1];
+
+    // Check VERIFICATION.md files
+    let dirEntries;
+    try { dirEntries = fs.readdirSync(phaseFullDir); } catch { continue; }
+    const verFiles = dirEntries.filter(f => f.endsWith('-VERIFICATION.md')).sort();
+
+    for (const vf of verFiles) {
+      const content = safeReadFile(path.join(phaseFullDir, vf));
+      if (!content) continue;
+
+      // Find lines with human_needed marker
+      const contentLines = content.split('\n');
+      for (const line of contentLines) {
+        if (/human_needed|human.review.needed|needs.human/i.test(line)) {
+          const cleaned = line.replace(/^[\s*-]+/, '').trim();
+          if (cleaned) {
+            flags.push({
+              type: 'human_review',
+              repo: '',
+              text: `Phase ${phaseNum}: ${cleaned}`,
+            });
+          }
+        }
+      }
+    }
+
+    // Also check UAT files
+    const uatFiles = dirEntries.filter(f => f.endsWith('-UAT.md')).sort();
+    for (const uf of uatFiles) {
+      const content = safeReadFile(path.join(phaseFullDir, uf));
+      if (!content) continue;
+
+      const contentLines = content.split('\n');
+      for (const line of contentLines) {
+        if (/human_needed|human.review.needed|needs.human/i.test(line)) {
+          const cleaned = line.replace(/^[\s*-]+/, '').trim();
+          if (cleaned) {
+            flags.push({
+              type: 'human_review',
+              repo: '',
+              text: `Phase ${phaseNum}: ${cleaned}`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Detect tech debt indicators: TODO/FIXME/HACK on newly introduced lines
+ * and deleted test files.
+ *
+ * @param {string} repoName - Repository name
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {string} startSha - Start SHA for diff range
+ * @param {Array} files - Files array from gatherRepoDiff()
+ * @returns {Array} Risk flag objects of type 'tech_debt'
+ */
+function detectTechDebt(repoName, repoPath, startSha, files) {
+  const flags = [];
+
+  // (a) TODO/FIXME/HACK on newly introduced lines
+  const diffOutput = gitCmd(repoPath, `diff ${startSha}..HEAD`);
+  if (diffOutput) {
+    const lines = diffOutput.split('\n');
+    let currentFile = null;
+    let lineNum = 0;
+
+    for (const line of lines) {
+      // Track current file from +++ b/path header
+      const fileMatch = line.match(/^\+\+\+ b\/(.+)$/);
+      if (fileMatch) {
+        currentFile = fileMatch[1];
+        continue;
+      }
+
+      // Track line number from @@ hunk header
+      const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)/);
+      if (hunkMatch) {
+        lineNum = parseInt(hunkMatch[1], 10);
+        continue;
+      }
+
+      // Only look at added lines (start with + but not +++)
+      if (line.startsWith('+') && !line.startsWith('+++')) {
+        if (currentFile && /\b(TODO|FIXME|HACK)\b/i.test(line)) {
+          const markerMatch = line.match(/\b(TODO|FIXME|HACK)\b[:\s]*(.*)/i);
+          const markerText = markerMatch
+            ? `${markerMatch[1].toUpperCase()}: ${markerMatch[2].trim()}`.replace(/\s*\*\/\s*$/, '').trim()
+            : line.replace(/^\+\s*/, '').trim();
+          flags.push({
+            type: 'tech_debt',
+            repo: repoName,
+            text: `${repoName}: ${currentFile}:${lineNum} — ${markerText}`,
+          });
+        }
+        lineNum++;
+      } else if (!line.startsWith('-')) {
+        // Context line (no prefix) — increment line number
+        lineNum++;
+      }
+      // Removed lines (start with -) don't increment new-side line number
+    }
+  }
+
+  // (b) Test file deletions
+  const testPatterns = [/\.test\.[^.]+$/, /\.spec\.[^.]+$/, /^__tests__\//, /^test\//];
+  for (const f of files) {
+    if (f.status !== 'deleted') continue;
+    const isTest = testPatterns.some(p => p.test(f.path) || p.test(path.basename(f.path)));
+    if (isTest) {
+      flags.push({
+        type: 'tech_debt',
+        repo: repoName,
+        text: `${repoName}: ${f.path} — test file deleted`,
+      });
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Orchestrate all four risk detectors and return a flat array of all risk flags.
+ *
+ * @param {Array} repoResults - Array of { name, startSha, diff, repoPath } objects
+ * @param {Object} options - Report options (planningRoot, projectRoot)
+ * @returns {Array} All risk flag objects
+ */
+function collectRiskFlags(repoResults, options) {
+  const allFlags = [];
+
+  for (const repo of repoResults) {
+    const { name, startSha, diff, repoPath } = repo;
+
+    // RISK-01: Large changes
+    allFlags.push(...detectLargeChanges(name, diff.files));
+
+    // RISK-02: Dependency changes
+    if (repoPath) {
+      allFlags.push(...detectDependencyChanges(name, repoPath, startSha, diff.files));
+    }
+
+    // RISK-04: Tech debt
+    if (repoPath) {
+      allFlags.push(...detectTechDebt(name, repoPath, startSha, diff.files));
+    }
+  }
+
+  // RISK-03: Human review needed (project-level, not per-repo)
+  // Skip for quick tasks — phase-level human_needed markers belong to milestones
+  if (options.planningRoot && options.projectRoot && !options.isQuickTask) {
+    allFlags.push(...detectHumanReviewNeeded(options.planningRoot, options.projectRoot));
+  }
+
+  return allFlags;
+}
+
+/**
+ * Render risk flags as grouped markdown with summary count.
+ * Empty categories are omitted. Returns empty string when no flags.
+ *
+ * @param {Array} flags - Array of risk flag objects
+ * @returns {string} Rendered markdown for the Risk Flags section
+ */
+function renderRiskFlags(flags) {
+  if (flags.length === 0) return '';
+
+  const groups = {
+    large_change: flags.filter(f => f.type === 'large_change'),
+    dependency_change: flags.filter(f => f.type === 'dependency_change'),
+    human_review: flags.filter(f => f.type === 'human_review'),
+    tech_debt: flags.filter(f => f.type === 'tech_debt'),
+  };
+
+  // Build summary count
+  const counts = [];
+  if (groups.large_change.length > 0) counts.push(`${groups.large_change.length} large changes`);
+  if (groups.dependency_change.length > 0) counts.push(`${groups.dependency_change.length} dependency changes`);
+  if (groups.human_review.length > 0) counts.push(`${groups.human_review.length} human review`);
+  if (groups.tech_debt.length > 0) counts.push(`${groups.tech_debt.length} tech debt`);
+
+  const lines = [];
+  lines.push(`**${flags.length} risk flags:** ${counts.join(', ')}`);
+  lines.push('');
+
+  // Render each non-empty group
+  if (groups.large_change.length > 0) {
+    lines.push('### Large Changes');
+    for (const f of groups.large_change) lines.push(`- ${f.text}`);
+    lines.push('');
+  }
+
+  if (groups.dependency_change.length > 0) {
+    lines.push('### Dependency Changes');
+    for (const f of groups.dependency_change) lines.push(`- ${f.text}`);
+    lines.push('');
+  }
+
+  if (groups.human_review.length > 0) {
+    lines.push('### Human Review Needed');
+    for (const f of groups.human_review) lines.push(`- ${f.text}`);
+    lines.push('');
+  }
+
+  if (groups.tech_debt.length > 0) {
+    lines.push('### Tech Debt');
+    for (const f of groups.tech_debt) lines.push(`- ${f.text}`);
+    lines.push('');
+  }
+
+  return lines.join('\n').trim();
+}
+
+// ─── Detailed Mode Functions ────────────────────────────────────────────────
+
+/**
+ * Analyze diff hunks for all files in a repo using an LLM.
+ * Batches all files into one LLM call per repo for coherent cross-file summaries.
+ *
+ * @param {string} repoPath - Absolute path to the repo
+ * @param {Array} files - Array of file objects with { path, status, insertions, deletions }
+ * @param {string} startSha - Start SHA for diff range
+ * @param {string} model - Model name to use (from resolveModelInternal)
+ * @returns {{ success: boolean, summaries: Object|null, error: string|null }}
+ *   summaries maps filePath -> summary string
+ */
+function analyzeRepoDiffs(repoPath, files, startSha, model) {
+  // 1. Collect diff hunks for all files
+  let diffContent = '';
+  for (const file of files) {
+    if (file.status === 'deleted') continue; // no diff hunks for deleted files
+    try {
+      const fileDiff = execSync(
+        'git diff ' + startSha + '..HEAD -- "' + file.path + '"',
+        { cwd: repoPath, stdio: 'pipe', maxBuffer: 10 * 1024 * 1024 }
+      ).toString();
+      if (fileDiff.trim()) {
+        diffContent += '\n--- File: ' + file.path + ' (' + file.status + ', +' + file.insertions + ' -' + file.deletions + ') ---\n';
+        diffContent += fileDiff + '\n';
+      }
+    } catch {
+      // Skip files where diff fails
+    }
+  }
+
+  if (!diffContent.trim()) {
+    return { success: true, summaries: {}, error: null };
+  }
+
+  // 2. Check size limit — fall back if too large
+  if (diffContent.length > 80000) {
+    return { success: false, summaries: null, error: 'Diff too large (' + diffContent.length + ' chars)' };
+  }
+
+  // 3. Build LLM prompt
+  const prompt = 'You are a code review analyst. For each file in the diff below, write a ONE sentence summary explaining what changed and why it matters (purpose + impact). Format your response as one line per file:\nFILE: path/to/file — Your summary here\n\nOnly include files that appear in the diff. Do not add commentary or headers.\n\n' + diffContent;
+
+  // 4. Invoke LLM via claude CLI (use input option to pipe prompt via stdin — safe for large/complex prompts)
+  try {
+    const modelArgs = model === 'inherit' ? '' : ' --model ' + model;
+    const result = execSync(
+      'claude --print' + modelArgs,
+      { input: prompt, cwd: repoPath, stdio: ['pipe', 'pipe', 'pipe'], timeout: 120000, maxBuffer: 10 * 1024 * 1024 }
+    ).toString().trim();
+
+    // 5. Parse response — expect lines like: FILE: path/to/file — summary
+    const summaries = {};
+    const lines = result.split('\n');
+    for (const line of lines) {
+      const match = line.match(/^FILE:\s*(.+?)\s*[—\-]\s*(.+)$/);
+      if (match) {
+        summaries[match[1].trim()] = match[2].trim();
+      }
+    }
+
+    return { success: true, summaries, error: null };
+  } catch (e) {
+    return { success: false, summaries: null, error: e.message || 'LLM call failed' };
+  }
+}
+
+/**
+ * Generate a cross-repo overall narrative from all per-file summaries.
+ *
+ * @param {Object} allSummaries - Map of repoName -> { filePath -> summary }
+ * @param {string} goalText - The report's goal/purpose text
+ * @param {string} model - Model name to use
+ * @returns {{ success: boolean, narrative: string|null, error: string|null }}
+ */
+function generateDetailedNarrative(allSummaries, goalText, model) {
+  // Build context from all summaries
+  let summaryText = '';
+  for (const [repoName, fileSummaries] of Object.entries(allSummaries)) {
+    summaryText += '\n## ' + repoName + '\n';
+    for (const [filePath, summary] of Object.entries(fileSummaries)) {
+      summaryText += '- ' + filePath + ' \u2014 ' + summary + '\n';
+    }
+  }
+
+  if (!summaryText.trim()) {
+    return { success: true, narrative: null, error: null };
+  }
+
+  const prompt = 'You are a code review analyst. Based on the per-file change summaries below, write a 2-3 sentence overall narrative explaining the architectural shift or key outcome of these changes. Be specific about what was achieved, not just what was touched.\n\nGoal: ' + (goalText || 'Not specified') + '\n\nFile changes:\n' + summaryText + '\n\nRespond with ONLY the narrative text, no headers or formatting.';
+
+  try {
+    const modelArgs = model === 'inherit' ? '' : ' --model ' + model;
+    const result = execSync(
+      'claude --print' + modelArgs,
+      { input: prompt, cwd: process.cwd(), stdio: ['pipe', 'pipe', 'pipe'], timeout: 120000, maxBuffer: 10 * 1024 * 1024 }
+    ).toString().trim();
+
+    return { success: true, narrative: result, error: null };
+  } catch (e) {
+    return { success: false, narrative: null, error: e.message || 'Narrative LLM call failed' };
+  }
+}
+
+// ─── Main Function ──────────────────────────────────────────────────────────
+
+/**
+ * Generate a diff report from StartShas for all registered repos.
+ *
+ * Runs git diff --stat, git log --oneline, git diff --name-status per repo.
+ * Reads the REVIEW.md template and fills placeholders. Sections with no
+ * content are omitted entirely (header + placeholder removed).
+ *
+ * Default mode uses git stats only. Detailed mode invokes LLM for per-file summaries and narrative.
+ *
+ * @param {string} cwd - Working directory (planning root context)
+ * @param {Object} startShas - Map of repo name to start SHA
+ *   (e.g., { "_planning": "abc123", "deliver-great-systems": "def456" })
+ * @param {Object} options - Report options
+ * @param {string} options.outputPath - Where to write the REVIEW.md file
+ * @param {string} options.title - Report title (milestone name or quick task name)
+ * @param {string} [options.mode="default"] - "default" (no LLM) or "detailed" (LLM analysis)
+ * @param {string|null} [options.goal] - Goal text (populated by phase 140)
+ * @param {string|null} [options.whatWasBuilt] - What Was Built text (populated by phase 140)
+ * @param {string|null} [options.verification] - Verification text (populated by phase 140)
+ * @param {string|null} [options.riskFlags] - Risk flags text (populated by phase 142)
+ * @param {string|null} [options.overall] - Overall narrative (populated by phase 140)
+ * @param {string|null} [options.planningRoot] - Absolute path to planning root (enables content extraction)
+ * @param {string|null} [options.projectRoot] - Relative project root path (e.g., "projects/gsd")
+ * @param {string|null} [options.milestoneVersion] - Milestone version (e.g., "v22.0") for ROADMAP goal extraction
+ * @param {boolean} [options.isQuickTask=false] - If true, use quick task content extraction logic
+ * @param {string|null} [options.quickTaskDescription] - Quick task description (used as Goal for quick tasks)
+ * @param {string|null} [options.quickTaskRepoPath] - Repo path for quick task commit extraction
+ * @param {string|null} [options.quickTaskStartSha] - Start SHA for quick task commit extraction
+ * @returns {Object} Result with stats on success, or reason on failure
+ */
+function generateDiffReport(cwd, startShas, options) {
+  // Validate inputs
+  if (!startShas || typeof startShas !== 'object' || Object.keys(startShas).length === 0) {
+    return { generated: false, reason: 'No start SHAs provided' };
+  }
+
+  if (!options || !options.outputPath) {
+    return { generated: false, reason: 'No outputPath specified in options' };
+  }
+
+  const warnings = [];
+  const planningRoot = getPlanningRoot(cwd);
+  // Repo paths may be supplied by the caller (e.g. active worktree paths for
+  // pre-merge milestone/quick reviews). Fall back to REPOS.md main paths when
+  // no override is provided — that's correct for post-merge milestone reviews
+  // where the worktree has been cleaned up.
+  const repoMap = (options.repoPaths && typeof options.repoPaths === 'object')
+    ? options.repoPaths
+    : resolveRepoPathsFromReposMd(planningRoot);
+
+  // Gather diff data for each repo in startShas (skip _planning key)
+  const repoResults = [];
+  const totals = { commits: 0, filesChanged: 0, insertions: 0, deletions: 0 };
+  let repoCount = 0;
+
+  for (const [repoName, startSha] of Object.entries(startShas)) {
+    if (repoName === '_planning') continue;
+
+    const repoPath = repoMap[repoName];
+    if (!repoPath) {
+      warnings.push(`Repo '${repoName}' not found in REPOS.md — skipped`);
+      continue;
+    }
+
+    if (!fs.existsSync(repoPath)) {
+      warnings.push(`Repo path does not exist: ${repoPath} — skipped`);
+      continue;
+    }
+
+    try {
+      const diff = gatherRepoDiff(repoPath, startSha);
+      repoResults.push({ name: repoName, startSha, diff, repoPath });
+
+      totals.commits += diff.commitCount;
+      totals.filesChanged += diff.stats.filesChanged;
+      totals.insertions += diff.stats.insertions;
+      totals.deletions += diff.stats.deletions;
+
+      if (diff.files.length > 0) {
+        repoCount++;
+      }
+    } catch (err) {
+      warnings.push(`Failed to gather diff for '${repoName}': ${err.message}`);
+    }
+  }
+
+  // ── Auto-populate outcome sections from project artifacts ──
+  // Only when planningRoot and projectRoot are provided (milestone context)
+  if (options.planningRoot && options.projectRoot) {
+    const pr = options.planningRoot;
+    const projRoot = options.projectRoot;
+
+    // Goal section (RCNT-01)
+    if (!options.goal && options.milestoneVersion) {
+      options.goal = extractGoalFromRoadmap(pr, projRoot, options.milestoneVersion);
+    }
+
+    // What Was Built section (RCNT-02)
+    if (!options.whatWasBuilt) {
+      if (options.isQuickTask && options.quickTaskRepoPath && options.quickTaskStartSha) {
+        options.whatWasBuilt = extractWhatWasBuiltFromCommits(options.quickTaskRepoPath, options.quickTaskStartSha);
+      } else {
+        const roadmapPath = path.join(pr, projRoot, 'ROADMAP.md');
+        const roadmapContent = safeReadFile(roadmapPath);
+        options.whatWasBuilt = extractWhatWasBuiltFromSummaries(pr, projRoot, roadmapContent);
+      }
+    }
+
+    // Overall narrative (RCNT-05)
+    if (!options.overall) {
+      options.overall = buildOverallNarrative(options, totals, repoCount, repoResults);
+    }
+
+    // Verification section (RCNT-06) — skip for quick tasks (they don't belong to milestone phases)
+    if (!options.verification && !options.isQuickTask) {
+      options.verification = extractVerificationData(pr, projRoot);
+    }
+  }
+
+  // Quick task Goal fallback (RCNT-01)
+  if (!options.goal && options.isQuickTask && options.quickTaskDescription) {
+    options.goal = options.quickTaskDescription;
+  }
+
+  // ── Risk flag detection (RISK-01 through RISK-04) ──
+  if (!options.riskFlags) {
+    const riskFlags = collectRiskFlags(repoResults, options);
+    if (riskFlags.length > 0) {
+      options.riskFlags = renderRiskFlags(riskFlags);
+      options._riskFlagCount = riskFlags.length;
+    }
+  }
+
+  // ── Detailed mode: LLM analysis ──
+  if (options.mode === 'detailed') {
+    const { resolveModelInternal } = require('./core.cjs');
+    const model = resolveModelInternal(cwd, 'dgs-review-analyst');
+    const allSummaries = {};
+    let detailedFailed = false;
+
+    for (const repoData of repoResults) {
+      if (!repoData.diff.files || repoData.diff.files.length === 0) continue;
+
+      // Exclude collapsed minor files from LLM analysis (Phase 146)
+      let filesToAnalyze = repoData.diff.files;
+      if (repoData.diff.files.length > COLLAPSE_FILE_THRESHOLD) {
+        filesToAnalyze = repoData.diff.files.filter(f => {
+          // Config files are never collapsed — always analyze
+          if (isConfigFile(f.path)) return true;
+          // Minor files (< threshold) are collapsed — skip LLM analysis
+          return (f.insertions + f.deletions) >= COLLAPSE_LINE_THRESHOLD;
+        });
+      }
+
+      const analysis = analyzeRepoDiffs(
+        repoData.repoPath, filesToAnalyze, repoData.startSha, model
+      );
+
+      if (analysis.success && analysis.summaries) {
+        allSummaries[repoData.name] = analysis.summaries;
+        // Replace file descriptions with LLM summaries
+        for (const file of repoData.diff.files) {
+          if (analysis.summaries[file.path]) {
+            file.description = analysis.summaries[file.path];
+          }
+        }
+      } else if (analysis.error && analysis.error.startsWith('Diff too large')) {
+        // Per-repo fallback — keep default descriptions for this repo
+        warnings.push('Detailed analysis skipped for ' + repoData.name + ' \u2014 diff too large');
+      } else {
+        // LLM failure — fall back to default mode for entire report
+        detailedFailed = true;
+        warnings.push('Detailed mode failed \u2014 falling back to default mode');
+        break;
+      }
+    }
+
+    // Generate overall narrative (only if per-file analysis succeeded)
+    if (!detailedFailed && Object.keys(allSummaries).length > 0) {
+      const goalText = options.goal || '';
+      const narrativeResult = generateDetailedNarrative(
+        allSummaries, goalText, model
+      );
+      if (narrativeResult.success && narrativeResult.narrative) {
+        // Replace the overall section content with LLM narrative
+        options.overall = narrativeResult.narrative;
+      } else if (!narrativeResult.success) {
+        // Narrative failure is non-fatal — keep existing overall content
+        warnings.push('Detailed narrative generation failed \u2014 using default overall');
+      }
+    }
+
+    if (detailedFailed) {
+      // Reset mode to default so template shows correct mode
+      options.mode = 'default';
+    }
+  }
+
+  // Read template
+  const templatePath = path.join(__dirname, '../../templates/REVIEW.md');
+  const template = safeReadFile(templatePath);
+  if (!template) {
+    return { generated: false, reason: `Template not found at ${templatePath}` };
+  }
+
+  // Build content
+  const statsBanner = buildStatsBanner(totals, repoCount, options._riskFlagCount || 0);
+  const codeChanges = renderCodeChanges(repoResults);
+  const aggregateStats = renderAggregateStats(repoResults, totals);
+  if (aggregateStats) {
+    options.aggregateStats = aggregateStats;
+  }
+  const mode = options.mode || 'default';
+  const date = new Date().toISOString().split('T')[0];
+
+  // Fill template
+  let rendered = template;
+  rendered = rendered.replace('{title}', options.title || 'Untitled');
+  rendered = rendered.replace('{stats_banner}', statsBanner);
+  rendered = rendered.replace('{date}', date);
+  rendered = rendered.replace('{mode}', mode);
+
+  // Code Changes — always fill (may be empty string if no changes)
+  if (codeChanges.trim()) {
+    rendered = rendered.replace('{code_changes}', codeChanges);
+  } else {
+    rendered = removeSection(rendered, '## Code Changes', '{code_changes}');
+  }
+
+  // Optional sections — omit entirely when null/undefined/empty
+  const optionalSections = [
+    { key: 'goal', header: '## Goal', placeholder: '{goal}' },
+    { key: 'whatWasBuilt', header: '## What Was Built', placeholder: '{what_was_built}' },
+    { key: 'aggregateStats', header: '## Aggregate Statistics', placeholder: '{aggregate_stats}' },
+    { key: 'verification', header: '## Verification', placeholder: '{verification}' },
+    { key: 'riskFlags', header: '## Risk Flags', placeholder: '{risk_flags}' },
+    { key: 'overall', header: '## Overall', placeholder: '{overall}' },
+  ];
+
+  for (const section of optionalSections) {
+    const value = options[section.key];
+    if (value && String(value).trim()) {
+      rendered = rendered.replace(section.placeholder, String(value));
+    } else {
+      rendered = removeSection(rendered, section.header, section.placeholder);
+    }
+  }
+
+  // Write output
+  const outputDir = path.dirname(options.outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+  fs.writeFileSync(options.outputPath, rendered, 'utf-8');
+
+  return {
+    generated: true,
+    path: options.outputPath,
+    warnings,
+    stats: {
+      repos: repoCount,
+      commits: totals.commits,
+      filesChanged: totals.filesChanged,
+      insertions: totals.insertions,
+      deletions: totals.deletions,
+    },
+  };
+}
+
+// ─── Job File Integration ───────────────────────────────────────────────────
+
+/**
+ * Generate a diff report from a job file's StartShas.
+ * Convenience wrapper: reads the job file, extracts StartShas,
+ * auto-detects project context, calls generateDiffReport.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} jobFilePath - Absolute path to the job file
+ * @param {Object} options - Same options as generateDiffReport (outputPath, title, mode, etc.)
+ *   Project context (planningRoot, projectRoot, milestoneVersion) is auto-detected
+ *   from the job file and planning root if not already set in options.
+ * @returns {Object} Same return as generateDiffReport
+ */
+function generateDiffReportFromJob(cwd, jobFilePath, options) {
+  const { parseJobFile } = require('./jobs.cjs');
+  const parsed = parseJobFile(jobFilePath);
+  if (!parsed.startShas) {
+    return { generated: false, reason: 'Job file has no StartShas recorded' };
+  }
+
+  // Auto-detect project context for content extraction
+  const planningRoot = getPlanningRoot(cwd);
+  if (planningRoot && !options.planningRoot) {
+    options.planningRoot = planningRoot;
+  }
+
+  // Detect project root from job file path (jobs live under projects/{name}/)
+  if (options.planningRoot && !options.projectRoot) {
+    const relPath = path.relative(options.planningRoot, jobFilePath);
+    const projectMatch = relPath.match(/^(projects\/[^/]+)\//);
+    if (projectMatch) {
+      options.projectRoot = projectMatch[1];
+    } else {
+      // Flat-layout fallback: job lives at jobs/*.md (not under projects/)
+      // but project content still lives under projects/<current_project>/.
+      // Read current_project from config.local.json and verify the dir exists.
+      const localConfigPath = path.join(options.planningRoot, 'config.local.json');
+      if (fs.existsSync(localConfigPath)) {
+        try {
+          const local = JSON.parse(fs.readFileSync(localConfigPath, 'utf-8'));
+          const cp = local && local.current_project;
+          if (cp && fs.existsSync(path.join(options.planningRoot, 'projects', cp))) {
+            options.projectRoot = 'projects/' + cp;
+          }
+        } catch {
+          // Malformed config.local.json — leave projectRoot undefined
+        }
+      }
+    }
+  }
+
+  // Extract milestone version from job file parsed data
+  if (!options.milestoneVersion && parsed.version) {
+    options.milestoneVersion = parsed.version;
+  }
+
+  // Before the milestone worktree is merged back to main, the commits live
+  // only on the milestone branch inside the worktree — main has nothing.
+  // Prefer the active milestone worktree paths when one is registered;
+  // fall back to REPOS.md main paths otherwise (post-merge case where the
+  // worktree has been cleaned up).
+  if (!options.repoPaths && options.planningRoot) {
+    const milestoneRepos = getActiveMilestoneWorktreeRepos(options.planningRoot);
+    if (milestoneRepos) {
+      options.repoPaths = milestoneRepos;
+    }
+  }
+
+  return generateDiffReport(cwd, parsed.startShas, options);
+}
+
+// ─── CLI Commands (stubs) ───────────────────────────────────────────────────
+
+/**
+ * CLI command: Generate a review report for a milestone job.
+ * Usage: dgs-tools jobs generate-review [version] [--detailed]
+ *
+ * Auto-detects current milestone from active job file if no version specified.
+ * Finds job file, calls generateDiffReportFromJob, auto-commits the result.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string|undefined} version - Milestone version (e.g., "v22.0"), or undefined for auto-detect
+ * @param {boolean} raw - If true, output JSON instead of formatted text
+ * @param {boolean} [detailed=false] - If true, use LLM-powered detailed analysis mode
+ */
+function cmdJobsGenerateReview(cwd, version, raw, detailed) {
+  const { findJobFile, listJobs } = require('./jobs.cjs');
+
+  // Auto-detect version from active job if not provided
+  let targetVersion = version;
+  if (!targetVersion) {
+    try {
+      const jobList = listJobs(cwd);
+      const activeJobs = jobList.in_progress || [];
+      if (activeJobs.length > 0) {
+        targetVersion = activeJobs[0].version;
+      } else {
+        const completedJobs = jobList.completed || [];
+        if (completedJobs.length > 0) {
+          targetVersion = completedJobs[0].version;
+        }
+      }
+    } catch (_) {
+      // listJobs may fail if no jobs directory exists
+    }
+    if (!targetVersion) {
+      error('No version specified and no active job found. Usage: jobs generate-review [version]');
+    }
+  }
+
+  // Find the job file
+  let jobFile;
+  try {
+    jobFile = findJobFile(cwd, targetVersion);
+  } catch (_) {
+    error(`No job file found for ${targetVersion}. Run a milestone job first.`);
+  }
+
+  // Generate the report
+  const planningRoot = getPlanningRoot(cwd);
+  const milestoneDir = path.join(planningRoot, 'milestones');
+  if (!fs.existsSync(milestoneDir)) {
+    fs.mkdirSync(milestoneDir, { recursive: true });
+  }
+  const outputPath = path.join(milestoneDir, `${targetVersion}-REVIEW.md`);
+
+  const result = generateDiffReportFromJob(cwd, jobFile.path, {
+    outputPath,
+    title: `${targetVersion} Milestone Review`,
+    mode: detailed ? 'detailed' : 'default',
+  });
+
+  if (!result.generated) {
+    error(result.reason || 'Review generation failed');
+  }
+
+  // Auto-commit the generated REVIEW.md
+  try {
+    const commitMsg = `docs(${targetVersion}): generate milestone review report`;
+    execSync(
+      `node "${path.join(__dirname, '..', 'dgs-tools.cjs')}" commit "${commitMsg}" --files "${result.path}"`,
+      { cwd, stdio: 'pipe' }
+    );
+  } catch (_) {
+    // Commit failure is non-fatal — report was still generated
+  }
+
+  // Build output
+  const stats = result.stats || {};
+  const summaryLine = `Generated: ${path.relative(planningRoot, result.path)} (${stats.commits || 0} commits, ${stats.filesChanged || 0} files${stats.riskFlags ? `, ${stats.riskFlags} risk flags` : ''})`;
+
+  if (raw) {
+    output({
+      generated: true,
+      filePath: result.path,
+      relativePath: path.relative(planningRoot, result.path),
+      version: targetVersion,
+      stats: {
+        commits: stats.commits || 0,
+        filesChanged: stats.filesChanged || 0,
+        insertions: stats.insertions || 0,
+        deletions: stats.deletions || 0,
+      },
+    }, raw);
+  } else {
+    output({ message: summaryLine }, raw);
+  }
+}
+
+/**
+ * CLI command: Generate a review for a quick task.
+ * Usage: dgs-tools quick generate-review [slug] [--detailed]
+ *
+ * Auto-detects active quick task from local config if no slug specified.
+ * Computes diff range via git merge-base instead of StartShas.
+ * Fast-forwarded tasks (merge-base === HEAD) produce "No code changes detected".
+ *
+ * @param {string} cwd - Working directory
+ * @param {string|undefined} slug - Quick task slug, or undefined for auto-detect
+ * @param {boolean} raw - If true, output JSON instead of formatted text
+ * @param {boolean} [detailed=false] - If true, use LLM-powered detailed analysis mode
+ */
+function cmdQuickGenerateReview(cwd, slug, raw, detailed) {
+  const { getActiveQuick } = require('./quick.cjs');
+
+  const planningRoot = getPlanningRoot(cwd);
+  const config = loadConfig(cwd);
+  const baseBranch = (config.git && config.git.base_branch) || config.base_branch || 'main';
+
+  // Resolve slug: use argument or auto-detect from active quick
+  let targetSlug = slug;
+  let repoMap = {};
+
+  if (targetSlug) {
+    // If slug provided, find its repos from local config
+    const active = getActiveQuick(cwd);
+    if (active && active.slug === targetSlug) {
+      repoMap = active.entry.repos || {};
+    } else {
+      error('Quick task \'' + targetSlug + '\' is not the active quick. Auto-detection only works for the active task.');
+    }
+  } else {
+    const active = getActiveQuick(cwd);
+    if (!active) {
+      error('No active quick task found. Specify a slug: quick generate-review <slug>');
+    }
+    targetSlug = active.slug;
+    repoMap = active.entry.repos || {};
+  }
+
+  const repoNames = Object.keys(repoMap);
+  if (repoNames.length === 0) {
+    error('Quick task \'' + targetSlug + '\' has no repos tracked');
+  }
+
+  // Compute merge-base for each repo and check for fast-forward
+  const startShas = {};
+  let totalCommits = 0;
+  let fastForward = true;
+  let primaryRepoPath = null;
+  let primaryStartSha = null;
+
+  for (const repoName of repoNames) {
+    const worktreePath = repoMap[repoName];
+    const branchName = 'quick/' + targetSlug;
+
+    // Compute merge-base
+    const mergeBase = gitCmd(worktreePath, 'merge-base ' + baseBranch + ' ' + branchName);
+    if (!mergeBase || !mergeBase.trim()) {
+      // Cannot compute merge-base — skip this repo
+      continue;
+    }
+    const startSha = mergeBase.trim();
+
+    // Count commits on the branch beyond merge-base
+    const commitCount = gitCmd(worktreePath, 'rev-list --count ' + startSha + '..' + branchName);
+    const count = parseInt((commitCount || '0').trim(), 10) || 0;
+    totalCommits += count;
+
+    if (count > 0) {
+      fastForward = false;
+    }
+
+    startShas[repoName] = startSha;
+    if (!primaryRepoPath) {
+      primaryRepoPath = worktreePath;
+      primaryStartSha = startSha;
+    }
+  }
+
+  // Fast-forward detection (RGEN-05): merge-base equals HEAD means zero commits
+  if (fastForward) {
+    if (raw) {
+      output({
+        generated: false,
+        slug: targetSlug,
+        reason: 'No code changes detected',
+        fastForward: true,
+      }, raw);
+    } else {
+      output({ message: 'No code changes detected \u2014 review not generated.' }, raw);
+    }
+    return;
+  }
+
+  // Generate the review report
+  const quickDir = path.join(planningRoot, 'quick', targetSlug);
+  if (!fs.existsSync(quickDir)) {
+    fs.mkdirSync(quickDir, { recursive: true });
+  }
+  const outputPath = path.join(quickDir, 'REVIEW.md');
+
+  // Derive description from slug (convert hyphens to spaces)
+  const description = targetSlug.replace(/-/g, ' ');
+
+  const result = generateDiffReport(cwd, startShas, {
+    outputPath: outputPath,
+    title: 'Quick Task: ' + targetSlug,
+    mode: detailed ? 'detailed' : 'default',
+    isQuickTask: true,
+    quickTaskDescription: description,
+    quickTaskRepoPath: primaryRepoPath,
+    quickTaskStartSha: primaryStartSha,
+    planningRoot: planningRoot,
+    projectRoot: (config.current_project ? 'projects/' + config.current_project : null),
+    // Pass the quick worktree paths through so gatherRepoDiff runs in the
+    // worktree (where the quick/<slug> branch lives), not the main checkout
+    // which hasn't seen the commits yet.
+    repoPaths: repoMap,
+    overall: null,  // Omit overall narrative for quick tasks (Goal section is sufficient)
+  });
+
+  if (!result.generated) {
+    error(result.reason || 'Review generation failed for quick task \'' + targetSlug + '\'');
+  }
+
+  // Auto-commit the generated REVIEW.md
+  try {
+    const commitMsg = 'docs(quick/' + targetSlug + '): generate quick task review report';
+    execSync(
+      'node ' + JSON.stringify(path.join(__dirname, '..', 'dgs-tools.cjs')) + ' commit ' + JSON.stringify(commitMsg) + ' --files ' + JSON.stringify(result.path),
+      { cwd: cwd, stdio: 'pipe' }
+    );
+  } catch (_) {
+    // Commit failure is non-fatal — report was still generated
+  }
+
+  // Build output — count risk flags from REVIEW.md content (since generateDiffReport
+  // doesn't return risk flag count in stats)
+  const stats = result.stats || {};
+  let riskFlagCount = 0;
+  try {
+    const reviewContent = fs.readFileSync(result.path, 'utf-8');
+    const riskMatch = reviewContent.match(/## Risk Flags/);
+    if (riskMatch) {
+      // Count "> **" markers in the risk flags section
+      const riskSection = reviewContent.split('## Risk Flags')[1] || '';
+      const nextSection = riskSection.indexOf('\n## ');
+      const riskText = nextSection > -1 ? riskSection.substring(0, nextSection) : riskSection;
+      const flags = riskText.match(/> \*\*/g);
+      riskFlagCount = flags ? flags.length : 0;
+    }
+  } catch (_) {
+    // Non-fatal — just report 0 flags
+  }
+  const summaryLine = 'Generated: quick/' + targetSlug + '/REVIEW.md (' + (stats.commits || 0) + ' commits, ' + (stats.filesChanged || 0) + ' files' + (riskFlagCount > 0 ? ', ' + riskFlagCount + ' risk flags' : '') + ')';
+
+  if (raw) {
+    output({
+      generated: true,
+      slug: targetSlug,
+      filePath: result.path,
+      relativePath: 'quick/' + targetSlug + '/REVIEW.md',
+      stats: {
+        commits: stats.commits || 0,
+        filesChanged: stats.filesChanged || 0,
+        insertions: stats.insertions || 0,
+        deletions: stats.deletions || 0,
+        riskFlags: riskFlagCount,
+      },
+    }, raw);
+  } else {
+    output({ message: summaryLine }, raw);
+  }
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  generateDiffReport,
+  generateDiffReportFromJob,
+  cmdJobsGenerateReview,
+  cmdQuickGenerateReview,
+};