@entelligentsia/forgecli 0.7.9 → 0.8.4

package/dist/forge-payload/.tools/collate.cjs

@@ -0,0 +1,1041 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: collate
+// Regenerate markdown views from the JSON store. Deterministic — no AI needed.
+// Usage: collate [SPRINT_ID | BUG_ID] [--dry-run] [--purge-events]
+//
+// Positional argument can be a sprint ID (e.g. FORGE-S12) or a bug ID
+// (e.g. FORGE-BUG-007, HELLO-B02). Bug IDs are first-class arguments:
+// passing a bug ID automatically enables event purging for that entity,
+// so `collate HELLO-B02` works identically to `collate HELLO-B02 --purge-events`.
+//
+// --purge-events  After generating COST_REPORT.md for the given SPRINT_ID,
+//                 delete .forge/store/events/{SPRINT_ID}/ entirely.
+//                 If SPRINT_ID is not a known sprint (e.g. a bug ID), no
+//                 COST_REPORT is generated but the event directory is still
+//                 purged. Requires a positional argument. Safe to combine with
+//                 --dry-run (reports what would be deleted without deleting).
+
+const fs = require('fs');
+const path = require('path');
+const { ok: resultOk, fail: resultFail, RESULT_CODES } = require('./lib/result.js');
+const { computeCost, canonicalizeModel } = require('./lib/pricing.cjs');
+
+let _store;
+function _getStore() { return _store || (_store = require('./store.cjs')); }
+
+const GENERATED = '<!-- GENERATED by forge/collate — do not edit manually -->';
+
+// --- Pure helpers (exported for testing) ---
+
+function statusBadge(status) {
+  const map = {
+    committed: '✅', approved: '✅', completed: '✅',
+    'retrospective-done': '✅', fixed: '✅', verified: '✅',
+    implemented: '🔧', implementing: '🔧',
+    'in-progress': '🔵', active: '🔵',
+    'plan-approved': '📋', 'review-approved': '📋', planned: '📋',
+    planning: '📝', draft: '📝',
+    triaged: '🟡', 'partially-completed': '🟡',
+    'plan-revision-required': '🔄', 'code-revision-required': '🔄',
+    reported: '🔴', blocked: '🚫', escalated: '⚠️',
+    abandoned: '❌',
+  };
+  const badge = map[status];
+  return badge ? `${badge} ${status}` : status;
+}
+
+function padTable(rows) {
+  if (rows.length === 0) return '';
+  const cols = rows[0].length;
+  const widths = Array.from({ length: cols }, (_, i) => Math.max(...rows.map(r => String(r[i] ?? '').length)));
+  return rows.map((r, ri) => {
+    const cells = r.map((c, i) => String(c ?? '').padEnd(widths[i]));
+    const line = `| ${cells.join(' | ')} |`;
+    if (ri === 0) return line + '\n' + `| ${widths.map(w => '-'.repeat(w)).join(' | ')} |`;
+    return line;
+  }).join('\n');
+}
+
+function fmtTokens(n) {
+  if (n === undefined || n === null) return '—';
+  return n.toLocaleString('en-US');
+}
+
+function fmtCost(n) {
+  if (n === undefined || n === null) return '—';
+  return `$${n.toFixed(4)}`;
+}
+
+function sourceLabel(sources) {
+  // sources: Set of tokenSource values (may include undefined)
+  const vals = [...sources];
+  const hasReported  = vals.includes('reported');
+  const hasEstimated = vals.includes('estimated');
+  const hasUnknown   = vals.some(v => v === undefined || v === null);
+
+  if (hasReported && !hasEstimated && !hasUnknown) return '(reported)';
+  if (hasEstimated && !hasReported && !hasUnknown) return '(estimated)';
+  if (!hasReported && !hasEstimated && hasUnknown)  return '(unknown)';
+  return '(mixed)';
+}
+
+const SPRINT_DOCS = [
+  { file: 'SPRINT_PLAN.md',         label: 'Sprint Plan',         purpose: 'Sprint scope and task definitions' },
+  { file: 'SPRINT_REQUIREMENTS.md', label: 'Sprint Requirements', purpose: 'Requirements and acceptance criteria' },
+  { file: 'COST_REPORT.md',         label: 'Cost Report',         purpose: 'Token usage and cost analysis' },
+];
+
+const TASK_DOCS = [
+  { file: 'TASK_PROMPT.md',         label: 'Task Prompt',         purpose: 'Task definition and prompt' },
+  { file: 'PLAN.md',                label: 'Plan',                purpose: 'Implementation plan' },
+  { file: 'PROGRESS.md',            label: 'Progress',            purpose: 'Implementation progress log' },
+  { file: 'ARCHITECT_APPROVAL.md',  label: 'Architect Approval',  purpose: 'Architecture review' },
+  { file: 'CODE_REVIEW.md',         label: 'Code Review',         purpose: 'Code review' },
+  { file: 'VALIDATION_REPORT.md',   label: 'Validation Report',   purpose: 'Validation results' },
+];
+
+// Resolve the task directory name within a sprint directory.
+// Returns the directory name string, or null if no directory can be found.
+//
+// Resolution order:
+// 1. If task.path is under engPath (an engineering KB path) — basename of that path.
+// 2. Filesystem scan of sprintDirPath for a directory whose name starts with taskId
+//    or whose leading integer matches that of taskId (slug-named dirs).
+// 3. null if nothing matches.
+function resolveTaskDir(task, sprintDirPath, engPath) {
+  const normalizedTaskPath = task.path ? task.path.replace(/\\/g, '/').replace(/\/$/, '') : null;
+  const normalizedEngPath  = engPath   ? engPath.replace(/\\/g, '/').replace(/\/$/, '')  : '';
+
+  // Case 1: path is under the engineering root — it IS the task directory
+  if (normalizedTaskPath && normalizedEngPath && normalizedTaskPath.startsWith(normalizedEngPath + '/')) {
+    return resultOk(path.basename(normalizedTaskPath));
+  }
+
+  // Case 2 (and fallback for case 1 missing): filesystem scan
+  if (fs.existsSync(sprintDirPath)) {
+    const entries = fs.readdirSync(sprintDirPath).sort();
+    // Prefer exact match first
+    if (entries.includes(task.taskId)) return resultOk(task.taskId);
+    // Then prefix match (slug-named dirs like TST-S01-T01-my-feature)
+    const prefix = task.taskId + '-';
+    const slugMatch = entries.find(e => e.startsWith(prefix) && fs.statSync(path.join(sprintDirPath, e)).isDirectory());
+    if (slugMatch) return resultOk(slugMatch);
+    // Numeric fallback: match first integer in taskId
+    const numMatch = task.taskId.match(/\d+/g);
+    const targetNum = numMatch ? parseInt(numMatch[numMatch.length - 1], 10) : null;
+    if (targetNum !== null) {
+      for (const e of entries) {
+        const em = e.match(/\d+/g);
+        if (em && parseInt(em[em.length - 1], 10) === targetNum && fs.statSync(path.join(sprintDirPath, e)).isDirectory()) {
+          return resultOk(e);
+        }
+      }
+    }
+  }
+
+  return resultFail(RESULT_CODES.MISSING_DIR, `No task directory found for ${task.taskId} in ${sprintDirPath}`);
+}
+
+function buildSprintIndex(sprint, tasks, availableDocs) {
+  const avail = new Set(availableDocs);
+  const lines = [GENERATED, '', `# Sprint: ${sprint.title || sprint.sprintId}`, '',
+    `> Sprint ID: ${sprint.sprintId}`,
+    `> Status: ${statusBadge(sprint.status)}`,
+    sprint.executionMode ? `> Execution Mode: ${sprint.executionMode}` : null,
+    ''].filter(l => l !== null);
+
+  if (sprint.goal) lines.push('## Goal', '', sprint.goal, '');
+  if (sprint.description && sprint.description !== sprint.goal) lines.push('## Description', '', sprint.description, '');
+
+  const presentDocs = SPRINT_DOCS.filter(d => avail.has(d.file));
+  if (presentDocs.length > 0) {
+    lines.push('## Sprint Documents', '');
+    const rows = [['Document', 'Purpose']];
+    for (const d of presentDocs) rows.push([`[${d.label}](${d.file})`, d.purpose]);
+    lines.push(padTable(rows), '');
+  }
+
+  lines.push('## Tasks', '');
+  if (tasks.length > 0) {
+    const rows = [['Task', 'Title', 'Status', 'Estimate']];
+    for (const t of tasks) {
+      const linkDir = t._taskDir || t.taskId;
+      rows.push([`[${t.taskId}](${linkDir}/INDEX.md)`, t.title || '—', statusBadge(t.status), t.estimate || '—']);
+    }
+    lines.push(padTable(rows), '');
+  } else {
+    lines.push('_No tasks._', '');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function buildTaskIndex(task, availableDocs) {
+  const avail = new Set(availableDocs);
+  const lines = [GENERATED, '', `# Task: ${task.title || task.taskId}`, '',
+    `> Task ID: ${task.taskId}`,
+    `> Sprint: [${task.sprintId}](../INDEX.md)`,
+    `> Status: ${statusBadge(task.status)}`,
+    task.estimate ? `> Estimate: ${task.estimate}` : null,
+    ''].filter(l => l !== null);
+
+  if (task.description) lines.push('## Description', '', task.description, '');
+
+  const presentDocs = TASK_DOCS.filter(d => avail.has(d.file));
+  if (presentDocs.length > 0) {
+    lines.push('## Task Documents', '');
+    const rows = [['Document', 'Purpose']];
+    for (const d of presentDocs) rows.push([`[${d.label}](${d.file})`, d.purpose]);
+    lines.push(padTable(rows), '');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+const BUG_DOCS = [
+  { file: 'ANALYSIS.md',         label: 'Analysis',          purpose: 'Bug analysis and triage' },
+  { file: 'BUG_FIX_PLAN.md',    label: 'Fix Plan',           purpose: 'Fix implementation plan' },
+  { file: 'PLAN.md',             label: 'Plan',               purpose: 'Fix implementation plan' },
+  { file: 'PLAN_REVIEW.md',      label: 'Plan Review',        purpose: 'Fix plan review' },
+  { file: 'PROGRESS.md',         label: 'Progress',           purpose: 'Fix progress log' },
+  { file: 'APPROVAL.md',         label: 'Approval',           purpose: 'Architecture approval' },
+  { file: 'ARCHITECT_APPROVAL.md', label: 'Architect Approval', purpose: 'Architecture approval' },
+  { file: 'CODE_REVIEW.md',      label: 'Code Review',        purpose: 'Code review' },
+  { file: 'VALIDATION_REPORT.md', label: 'Validation Report', purpose: 'Fix validation' },
+];
+
+function buildBugIndex(bug, availableDocs, costTotals) {
+  const avail = new Set(availableDocs);
+  const lines = [GENERATED, '', `# Bug: ${bug.title || bug.bugId}`, '',
+    `> Bug ID: ${bug.bugId}`,
+    `> Severity: ${bug.severity || '—'}`,
+    `> Status: ${statusBadge(bug.status)}`,
+    bug.reportedAt ? `> Reported: ${bug.reportedAt.slice(0, 10)}` : null,
+    bug.resolvedAt ? `> Resolved: ${bug.resolvedAt.slice(0, 10)}` : null,
+    ''].filter(l => l !== null);
+
+  if (bug.description) lines.push('## Description', '', bug.description, '');
+
+  // Cost aggregation section — included when costTotals is provided
+  // (typically when --purge-events aggregates event costs before deletion).
+  if (costTotals && costTotals.inputTokens !== undefined) {
+    lines.push('## Cost', '');
+    const rows = [
+      ['Input Tokens', 'Output Tokens', 'Cache Read', 'Cache Write', 'Est. Cost USD', 'Source'],
+      [
+        fmtTokens(costTotals.inputTokens),
+        fmtTokens(costTotals.outputTokens),
+        fmtTokens(costTotals.cacheReadTokens),
+        fmtTokens(costTotals.cacheWriteTokens),
+        fmtCost(costTotals.estimatedCostUSD),
+        costTotals.sourceLabel || '—',
+      ],
+    ];
+    lines.push(padTable(rows), '');
+  }
+
+  const presentDocs = BUG_DOCS.filter(d => avail.has(d.file));
+  if (presentDocs.length > 0) {
+    lines.push('## Bug Documents', '');
+    const rows = [['Document', 'Purpose']];
+    for (const d of presentDocs) rows.push([`[${d.label}](${d.file})`, d.purpose]);
+    lines.push(padTable(rows), '');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Detect whether a string matches the bug-ID pattern.
+ * Bug IDs match one of these patterns:
+ * 1. Contains 'BUG-' followed by digits (e.g., BUG-001, FORGE-BUG-007)
+ * 2. Contains '-B' followed by digits at a segment boundary (e.g., HELLO-B02)
+ * Sprint IDs (FORGE-S12) and task IDs (FORGE-S12-T03) are excluded.
+ */
+function isBugId(id) {
+  if (!id || typeof id !== 'string') return false;
+  return /BUG-\d+/.test(id) || /-B\d+\b/.test(id);
+}
+
+/**
+ * mergeSidecarEvents(primaryEvents, sidecars)
+ *
+ * Merges sidecar token data onto matching primary events by eventId.
+ * Returns { events, orphanSidecars, huskPrimaries } where:
+ *   - events:         all primary events (merged primaries have token fields from sidecar)
+ *   - orphanSidecars: sidecars with no matching primary
+ *   - huskPrimaries:  primaries that still have no token data after merge attempt
+ *
+ * On merge:
+ *   - Token fields (inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens,
+ *     estimatedCostUSD) are copied from the sidecar onto the primary.
+ *   - If all four token counts are present after merge and the primary has a known
+ *     model, estimatedCostUSD is recomputed via pricing.computeCost (overwrites
+ *     any fabricated value from the sidecar).
+ *   - The model field on the primary is canonicalized if possible.
+ *
+ * Pure function — no filesystem I/O.
+ */
+function mergeSidecarEvents(primaryEvents, sidecars) {
+  // Build sidecar lookup map by eventId
+  const sidecarMap = new Map();
+  for (const s of sidecars) {
+    if (s && s.eventId) {
+      sidecarMap.set(s.eventId, s);
+    }
+  }
+
+  const usedSidecarIds = new Set();
+  const events = [];
+  const huskPrimaries = [];
+
+  for (const primary of primaryEvents) {
+    if (!primary) continue;
+    const merged = Object.assign({}, primary);
+
+    // Canonicalize model on read
+    if (merged.model) {
+      const canonResult = canonicalizeModel(merged.model);
+      if (canonResult !== null) {
+        merged.model = canonResult.canonical;
+      }
+    }
+
+    // Attempt sidecar merge
+    const sidecar = sidecarMap.get(merged.eventId);
+    if (sidecar) {
+      usedSidecarIds.add(merged.eventId);
+      // Merge token fields from sidecar
+      if (sidecar.inputTokens      !== undefined) merged.inputTokens      = sidecar.inputTokens;
+      if (sidecar.outputTokens     !== undefined) merged.outputTokens     = sidecar.outputTokens;
+      if (sidecar.cacheReadTokens  !== undefined) merged.cacheReadTokens  = sidecar.cacheReadTokens;
+      if (sidecar.cacheWriteTokens !== undefined) merged.cacheWriteTokens = sidecar.cacheWriteTokens;
+      if (sidecar.estimatedCostUSD !== undefined) merged.estimatedCostUSD = sidecar.estimatedCostUSD;
+      if (sidecar.tokenSource      !== undefined) merged.tokenSource      = sidecar.tokenSource;
+      if (sidecar.model && !merged.model) merged.model = sidecar.model;
+    }
+
+    // Recompute cost when all four counts are present and model is known
+    if (
+      merged.inputTokens !== undefined &&
+      merged.outputTokens !== undefined &&
+      merged.cacheReadTokens !== undefined &&
+      merged.cacheWriteTokens !== undefined &&
+      merged.model
+    ) {
+      const recomputed = computeCost({
+        inputTokens: merged.inputTokens,
+        outputTokens: merged.outputTokens,
+        cacheReadTokens: merged.cacheReadTokens,
+        cacheWriteTokens: merged.cacheWriteTokens,
+        model: merged.model,
+      });
+      if (recomputed !== null) {
+        merged.estimatedCostUSD = recomputed;
+      }
+    }
+
+    events.push(merged);
+
+    // Classify as husk if no token data after merge
+    if (merged.inputTokens === undefined) {
+      huskPrimaries.push(merged);
+    }
+  }
+
+  // Collect orphan sidecars (no matching primary)
+  const orphanSidecars = sidecars.filter(s => s && s.eventId && !usedSidecarIds.has(s.eventId));
+
+  return { events, orphanSidecars, huskPrimaries };
+}
+
+/**
+ * loadSprintEvents(sprintId)
+ *
+ * Reads primary and sidecar event files for a sprint from the store.
+ * Returns { events, orphanSidecars, huskPrimaries } — see mergeSidecarEvents.
+ *
+ * Primary files: .json files NOT starting with '_'
+ * Sidecar files: .json files starting with '_' and ending with '_usage.json'
+ */
+function loadSprintEvents(sprintId) {
+  const store = _getStore();
+  const allFilenames = store.listEventFilenames(sprintId);
+
+  const primaryFilenames = allFilenames.filter(({ filename }) => !filename.startsWith('_'));
+  const sidecarFilenames = allFilenames.filter(({ filename }) =>
+    filename.startsWith('_') && filename.endsWith('_usage.json')
+  );
+
+  // Read each primary event individually (avoids re-reading sidecars)
+  const primaryEvents = primaryFilenames
+    .map(({ id }) => store.getEvent(id, sprintId))
+    .filter(Boolean);
+
+  // Read sidecar files via getEvent using the id (filename without .json)
+  const sidecars = sidecarFilenames
+    .map(({ id }) => store.getEvent(id, sprintId))
+    .filter(Boolean);
+
+  return mergeSidecarEvents(primaryEvents, sidecars);
+}
+
+/**
+ * buildIngestionQuality(orphanSidecars, huskPrimaries, noTaskEvents, unmappedModels, totalEvents, tokenSourceCounts)
+ *
+ * Builds the "## Ingestion Quality" section for COST_REPORT.md.
+ * Returns a markdown string (without trailing newline; caller adds one).
+ *
+ * @param {object[]} orphanSidecars      - sidecars with no matching primary
+ * @param {object[]} huskPrimaries       - primaries with no token data
+ * @param {object[]} noTaskEvents        - token events with no taskId
+ * @param {string[]} unmappedModels      - raw model strings that did not canonicalize
+ * @param {number}   totalEvents         - total primary events loaded (with and without token data)
+ * @param {{reported: number, estimated: number, missing: number}} tokenSourceCounts - tokenSource tallies
+ */
+function buildIngestionQuality(orphanSidecars, huskPrimaries, noTaskEvents, unmappedModels, totalEvents, tokenSourceCounts) {
+  const lines = ['## Ingestion Quality', ''];
+
+  const orphanCount   = orphanSidecars  ? orphanSidecars.length  : 0;
+  const huskCount     = huskPrimaries   ? huskPrimaries.length   : 0;
+  const noTaskCount   = noTaskEvents    ? noTaskEvents.length    : 0;
+  const unmappedCount = unmappedModels  ? unmappedModels.length  : 0;
+  const total         = (typeof totalEvents === 'number') ? totalEvents : null;
+  const tsc           = tokenSourceCounts || null;
+
+  const hasIssues = orphanCount > 0 || huskCount > 0 || noTaskCount > 0 || unmappedCount > 0;
+
+  if (!hasIssues && total === null && tsc === null) {
+    lines.push('_All events attributed cleanly — no data gaps detected._', '');
+    return lines.join('\n');
+  }
+
+  const rows = [['Metric', 'Count', 'Detail']];
+
+  // Total events row — always rendered when totalEvents is provided
+  if (total !== null) {
+    const withTokenData = total - huskCount;
+    rows.push(['Total events', String(total), `${withTokenData} with token data`]);
+  }
+
+  // Token source breakdown — always rendered when tokenSourceCounts is provided
+  if (tsc !== null) {
+    const reported  = tsc.reported  || 0;
+    const estimated = tsc.estimated || 0;
+    const missing   = tsc.missing   || 0;
+    rows.push(['Token source breakdown', String(reported + estimated + missing), `reported: ${reported}, estimated: ${estimated}, missing: ${missing}`]);
+  }
+
+  if (orphanCount > 0) {
+    const ids = orphanSidecars.map(s => s.eventId || '?').join(', ');
+    rows.push(['Orphan sidecars (no matching primary)', String(orphanCount), ids.length > 80 ? ids.slice(0, 77) + '…' : ids]);
+  }
+
+  if (huskCount > 0) {
+    const ids = huskPrimaries.map(h => h.eventId || '?').join(', ');
+    rows.push(['Primary events with no token data (husks)', String(huskCount), ids.length > 80 ? ids.slice(0, 77) + '…' : ids]);
+  }
+
+  if (noTaskCount > 0) {
+    rows.push(['Primary events with no taskId (no-task)', String(noTaskCount), 'Attributed to "no-task" row in Per-Task Totals']);
+  }
+
+  if (unmappedCount > 0) {
+    const raw = unmappedModels.join(', ');
+    rows.push(['Unmapped model names (cost not recomputed)', String(unmappedCount), raw.length > 80 ? raw.slice(0, 77) + '…' : raw]);
+  }
+
+  lines.push(padTable(rows), '');
+  return lines.join('\n');
+}
+
+/**
+ * buildCostReport(sprint, events, orphanSidecars, huskPrimaries)
+ *
+ * Pure function — builds the full COST_REPORT.md content string for a sprint.
+ *
+ * @param {object} sprint             - sprint record with sprintId and title
+ * @param {object[]} events           - merged primary events (from mergeSidecarEvents)
+ * @param {object[]} orphanSidecars   - sidecars with no matching primary
+ * @param {object[]} huskPrimaries    - primaries with no token data
+ * @returns {string}                  - full markdown content for COST_REPORT.md
+ */
+function buildCostReport(sprint, events, orphanSidecars, huskPrimaries) {
+  const REVIEW_PHASES = new Set(['review', 'review-plan', 'review-code', 'review-implementation']);
+
+  // Only events that have at least inputTokens present
+  const tokenEvents = events.filter(e => e.inputTokens !== undefined);
+
+  const lines = [
+    GENERATED,
+    '',
+    `# Cost Report — ${sprint.sprintId}`,
+    '',
+    `> Generated: ${new Date().toISOString().slice(0, 10)}`,
+    `> Sprint: ${sprint.title || sprint.sprintId}`,
+    '',
+  ];
+
+  // Tally total events and tokenSource counts over all primary events (including husks)
+  const totalEvents = events.length;
+  const tokenSourceCounts = { reported: 0, estimated: 0, missing: 0 };
+  for (const e of events) {
+    if (e.tokenSource === 'reported') tokenSourceCounts.reported++;
+    else if (e.tokenSource === 'estimated') tokenSourceCounts.estimated++;
+    else tokenSourceCounts.missing++;
+  }
+
+  if (tokenEvents.length === 0) {
+    lines.push('_No token data available for this sprint._', '');
+    lines.push(buildIngestionQuality(orphanSidecars || [], huskPrimaries || [], [], [], totalEvents, tokenSourceCounts), '');
+    return lines.join('\n') + '\n';
+  }
+
+  // Collect no-task events and unmapped models for IQ section
+  const noTaskEvents = tokenEvents.filter(e => !e.taskId);
+  const unmappedModels = [];
+  const seenUnmapped = new Set();
+  for (const e of tokenEvents) {
+    if (e.model) {
+      const c = canonicalizeModel(e.model);
+      if (c === null && !seenUnmapped.has(e.model)) {
+        seenUnmapped.add(e.model);
+        unmappedModels.push(e.model);
+      }
+    }
+  }
+
+  // --- Section 1: Per-task totals ---
+  lines.push('## Per-Task Totals', '');
+  {
+    const byTask = {};
+    for (const e of tokenEvents) {
+      const tid = e.taskId || 'no-task';
+      if (!byTask[tid]) byTask[tid] = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUSD: 0, sources: new Set() };
+      const g = byTask[tid];
+      g.inputTokens     += e.inputTokens     || 0;
+      g.outputTokens    += e.outputTokens    || 0;
+      g.cacheReadTokens += e.cacheReadTokens  || 0;
+      g.cacheWriteTokens+= e.cacheWriteTokens || 0;
+      g.estimatedCostUSD+= e.estimatedCostUSD || 0;
+      g.sources.add(e.tokenSource);
+    }
+    const rows = [['Task', 'Input Tokens', 'Output Tokens', 'Cache Read', 'Cache Write', 'Est. Cost USD', 'Source']];
+    for (const [tid, g] of Object.entries(byTask).sort(([a], [b]) => a.localeCompare(b))) {
+      rows.push([
+        tid,
+        fmtTokens(g.inputTokens),
+        fmtTokens(g.outputTokens),
+        fmtTokens(g.cacheReadTokens),
+        fmtTokens(g.cacheWriteTokens),
+        fmtCost(g.estimatedCostUSD),
+        sourceLabel(g.sources),
+      ]);
+    }
+    lines.push(padTable(rows), '');
+  }
+
+  // --- Section 2: Per-role breakdown ---
+  lines.push('## Per-Role Breakdown', '');
+  {
+    const byRole = {};
+    for (const e of tokenEvents) {
+      const role = e.role || '(unknown)';
+      if (!byRole[role]) byRole[role] = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUSD: 0 };
+      const g = byRole[role];
+      g.inputTokens     += e.inputTokens     || 0;
+      g.outputTokens    += e.outputTokens    || 0;
+      g.cacheReadTokens += e.cacheReadTokens  || 0;
+      g.cacheWriteTokens+= e.cacheWriteTokens || 0;
+      g.estimatedCostUSD+= e.estimatedCostUSD || 0;
+    }
+    const rows = [['Role', 'Input Tokens', 'Output Tokens', 'Cache Read', 'Cache Write', 'Est. Cost USD']];
+    for (const [role, g] of Object.entries(byRole).sort(([a], [b]) => a.localeCompare(b))) {
+      rows.push([
+        role,
+        fmtTokens(g.inputTokens),
+        fmtTokens(g.outputTokens),
+        fmtTokens(g.cacheReadTokens),
+        fmtTokens(g.cacheWriteTokens),
+        fmtCost(g.estimatedCostUSD),
+      ]);
+    }
+    lines.push(padTable(rows), '');
+  }
+
+  // --- Section 3: Revision waste ---
+  lines.push('## Revision Waste', '');
+  {
+    const revisionEvents = tokenEvents.filter(e => (e.iteration || 1) > 1 && REVIEW_PHASES.has(e.phase));
+    if (revisionEvents.length === 0) {
+      lines.push('_No revision waste in this sprint._', '');
+    } else {
+      const byTask = {};
+      for (const e of revisionEvents) {
+        const tid = e.taskId || 'no-task';
+        if (!byTask[tid]) byTask[tid] = { iterations: new Set(), inputTokens: 0, outputTokens: 0, estimatedCostUSD: 0 };
+        const g = byTask[tid];
+        g.iterations.add(e.iteration);
+        g.inputTokens     += e.inputTokens     || 0;
+        g.outputTokens    += e.outputTokens    || 0;
+        g.estimatedCostUSD+= e.estimatedCostUSD || 0;
+      }
+      const rows = [['Task', 'Revision Iterations', 'Input Tokens', 'Output Tokens', 'Est. Cost USD']];
+      for (const [tid, g] of Object.entries(byTask).sort(([a], [b]) => a.localeCompare(b))) {
+        rows.push([
+          tid,
+          g.iterations.size,
+          fmtTokens(g.inputTokens),
+          fmtTokens(g.outputTokens),
+          fmtCost(g.estimatedCostUSD),
+        ]);
+      }
+      lines.push(padTable(rows), '');
+    }
+  }
+
+  // --- Section 4: Model split ---
+  lines.push('## Model Split', '');
+  {
+    const byModel = {};
+    for (const e of tokenEvents) {
+      const model = e.model || '(unknown)';
+      if (!byModel[model]) byModel[model] = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUSD: 0 };
+      const g = byModel[model];
+      g.inputTokens     += e.inputTokens     || 0;
+      g.outputTokens    += e.outputTokens    || 0;
+      g.cacheReadTokens += e.cacheReadTokens  || 0;
+      g.cacheWriteTokens+= e.cacheWriteTokens || 0;
+      g.estimatedCostUSD+= e.estimatedCostUSD || 0;
+    }
+    const rows = [['Model', 'Input Tokens', 'Output Tokens', 'Cache Read', 'Cache Write', 'Est. Cost USD']];
+    for (const [model, g] of Object.entries(byModel).sort(([a], [b]) => a.localeCompare(b))) {
+      rows.push([
+        model,
+        fmtTokens(g.inputTokens),
+        fmtTokens(g.outputTokens),
+        fmtTokens(g.cacheReadTokens),
+        fmtTokens(g.cacheWriteTokens),
+        fmtCost(g.estimatedCostUSD),
+      ]);
+    }
+    lines.push(padTable(rows), '');
+  }
+
+  // --- Section 5: Ingestion Quality ---
+  lines.push(buildIngestionQuality(orphanSidecars || [], huskPrimaries || [], noTaskEvents, unmappedModels, totalEvents, tokenSourceCounts), '');
+
+  return lines.join('\n') + '\n';
+}
+
+module.exports = { statusBadge, padTable, fmtTokens, fmtCost, sourceLabel, GENERATED, buildSprintIndex, buildTaskIndex, buildBugIndex, resolveTaskDir, isBugId, mergeSidecarEvents, buildIngestionQuality, buildCostReport };
+
+// --- CLI ---
+if (require.main === module) {
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const SPRINT_ARG = process.argv.slice(2).find(a => !a.startsWith('--'));
+
+// Bug IDs are first-class arguments — auto-enable purge when a bug ID is passed.
+// This makes `collate.cjs HELLO-B02` work identically to `collate.cjs HELLO-B02 --purge-events`.
+const IS_BUG_ARG = isBugId(SPRINT_ARG);
+const PURGE_EVENTS = process.argv.includes('--purge-events') || IS_BUG_ARG;
+
+if (PURGE_EVENTS && !SPRINT_ARG) {
+  console.error('Error: --purge-events requires a sprint or bug ID argument');
+  process.exit(1);
+}
+const cwd = process.cwd();
+
+function writeFile(filePath, content) {
+  if (DRY_RUN) { console.log(`[dry-run] would write: ${path.relative(cwd, filePath)}`); return; }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+// Resolve a directory name under `base` by trying candidates in order.
+// Returns the first candidate whose directory exists. If none exist,
+// attempts a numeric glob: finds the first alphabetically-sorted dir
+// in `base` whose first integer matches the first integer in the last
+// candidate. Falls back to the last candidate if no match is found.
+function resolveDir(base, ...candidates) {
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(base, c))) return c;
+  }
+  // Numeric glob fallback
+  const last = candidates[candidates.length - 1];
+  const numMatch = last.match(/\d+/);
+  if (numMatch && fs.existsSync(base)) {
+    const target = parseInt(numMatch[0], 10);
+    const dirs = fs.readdirSync(base).sort();
+    for (const d of dirs) {
+      const m = d.match(/\d+/);
+      if (m && parseInt(m[0], 10) === target) return d;
+    }
+  }
+  return last;
+}
+
+// --- Load store ---
+function readConfig() {
+  const p = path.join(cwd, '.forge', 'config.json');
+  if (!fs.existsSync(p)) { console.error('Error: .forge/config.json not found'); process.exit(1); }
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) {
+    console.error(`Error: .forge/config.json is not valid JSON: ${e.message}`); process.exit(1);
+  }
+}
+
+const config = readConfig();
+const storePath  = config.paths?.store || '.forge/store';
+const engPath    = config.paths?.engineering || 'engineering';
+const projectName = config.project?.name || config.project?.prefix || 'Project';
+
+const storeRoot = path.join(cwd, storePath);
+const engRoot   = path.join(cwd, engPath);
+
+const store = _getStore();
+const allSprints = store.listSprints()
+  .sort((a, b) => a.sprintId.localeCompare(b.sprintId));
+const allTasks   = store.listTasks();
+const allBugs    = store.listBugs();
+const allFeatures= store.listFeatures()
+  .sort((a, b) => (a.id || '').localeCompare(b.id || ''));
+
+// Group tasks by sprint
+const tasksBySprint = {};
+for (const t of allTasks) {
+  if (!tasksBySprint[t.sprintId]) tasksBySprint[t.sprintId] = [];
+  tasksBySprint[t.sprintId].push(t);
+}
+
+// Sprints to process
+const targetSprints = SPRINT_ARG
+  ? allSprints.filter(s => s.sprintId === SPRINT_ARG || s.sprintId.endsWith(`-${SPRINT_ARG}`))
+  : allSprints;
+
+if (SPRINT_ARG && targetSprints.length === 0) {
+  if (IS_BUG_ARG || PURGE_EVENTS) {
+    // Bug ID or non-sprint entity with --purge-events — skip sprint processing,
+    // fall through to bug INDEX generation and purge step.
+  } else {
+    console.error(`Error: '${SPRINT_ARG}' not found as a sprint or bug in store`);
+    process.exit(1);
+  }
+}
+
+// --- Generate MASTER_INDEX.md ---
+{
+  const masterPath = path.join(engRoot, 'MASTER_INDEX.md');
+  let preserved = {};
+
+  // Extract preserved sections (## headings not in GENERATED marker block)
+  if (fs.existsSync(masterPath)) {
+    const existing = fs.readFileSync(masterPath, 'utf8');
+    const isGenerated = existing.trimStart().startsWith(GENERATED.trim().slice(0, 10));
+    if (!isGenerated) {
+      // Preserve all sections from manually written file
+      const sections = existing.split(/^(?=## )/m);
+      for (const s of sections) {
+        const m = s.match(/^## (.+)/);
+        if (m) preserved[m[1].trim()] = s;
+      }
+    }
+  }
+
+  const lines = [GENERATED, '', `# ${projectName} — Master Index`, '',
+    `> Generated: ${new Date().toISOString().slice(0, 10)}`, ''];
+
+  // Feature Registry
+  lines.push('## Feature Registry', '');
+  if (allFeatures.length > 0) {
+    lines.push(`[Browse all ${allFeatures.length} features ↗](features/INDEX.md)`, '');
+  } else {
+    lines.push(`_[No features yet ↗](features/INDEX.md)_`, '');
+  }
+
+  // Sprint registry
+  lines.push('## Sprint Registry', '');
+  if (allSprints.length > 0) {
+    const rows = [['Sprint', 'Title', 'Status', 'Tasks']];
+    for (const s of [...allSprints].reverse()) {
+      const tasks = tasksBySprint[s.sprintId] || [];
+      const completed = tasks.filter(t => t.status === 'committed').length;
+      rows.push([
+        s.sprintId, s.title || '—', statusBadge(s.status),
+        `${completed}/${tasks.length}`,
+      ]);
+    }
+    lines.push(padTable(rows), '');
+  } else {
+    lines.push('_No sprints yet._', '');
+  }
+
+  // Task registry — most recent sprint first
+  lines.push('## Task Registry', '');
+  for (const sprint of [...allSprints].reverse()) {
+    const tasks = (tasksBySprint[sprint.sprintId] || []).sort((a, b) => a.taskId.localeCompare(b.taskId));
+    if (tasks.length === 0) continue;
+    lines.push(`### ${sprint.sprintId}`, '');
+    const rows = [['Task', 'Title', 'Status', 'Estimate']];
+    const sprintDir = sprint.path
+      ? path.basename(sprint.path.replace(/\/$/, ''))
+      : resolveDir(path.join(engRoot, 'sprints'), sprint.sprintId, sprint.sprintId.split('-').pop());
+    for (const t of tasks) {
+      // Derive task link from t.path if available (most reliable — already has correct dir names).
+      // Fall back to filesystem detection against full task ID vs. trailing segment.
+      let taskLink;
+      if (t.path) {
+        // If path is under the engineering root, it IS the task directory — link directly.
+        // Otherwise (e.g. forge/tools/seed-store.cjs), it's a plugin source reference;
+        // strip the filename to get the containing directory.
+        const normalizedPath = t.path.replace(/\\/g, '/').replace(/\/$/, '');
+        const normalizedEngPath = engPath.replace(/\\/g, '/').replace(/\/$/, '');
+        if (normalizedPath.startsWith(normalizedEngPath + '/')) {
+          const rel = path.relative(engPath, t.path).replace(/\\/g, '/');
+          taskLink = rel + '/INDEX.md';
+        } else {
+          const rel = path.relative(engPath, t.path).replace(/\\/g, '/');
+          taskLink = path.dirname(rel).replace(/\\/g, '/') + '/INDEX.md';
+        }
+      } else {
+        const taskDir = resolveDir(path.join(engRoot, 'sprints', sprintDir), t.taskId, t.taskId.split('-').pop());
+        taskLink = `sprints/${sprintDir}/${taskDir}/INDEX.md`;
+      }
+      rows.push([
+        `[${t.taskId}](${taskLink})`,
+        t.title || '—', statusBadge(t.status), t.estimate || '—',
+      ]);
+    }
+    lines.push(padTable(rows), '');
+  }
+
+  // Bug registry
+  if (allBugs.length > 0) {
+    lines.push('## Bug Registry', '');
+    const open   = allBugs.filter(b => !['fixed', 'verified'].includes(b.status));
+    const closed = allBugs.filter(b =>  ['fixed', 'verified'].includes(b.status));
+    const rows = [['Bug', 'Title', 'Severity', 'Status']];
+    for (const b of [...open, ...closed]) {
+      const bugDir = resolveDir(path.join(engRoot, 'bugs'), b.bugId, b.bugId.split('-').pop());
+      rows.push([
+        `[${b.bugId}](bugs/${bugDir}/INDEX.md)`,
+        b.title || '—', b.severity || '—', statusBadge(b.status),
+      ]);
+    }
+    lines.push(padTable(rows), '');
+  }
+
+  // Re-append preserved sections not already present
+  for (const [heading, content] of Object.entries(preserved)) {
+    if (!['Feature Registry', 'Sprint Registry', 'Task Registry', 'Bug Registry'].includes(heading)) {
+      lines.push(content);
+    }
+  }
+
+  writeFile(masterPath, lines.join('\n') + '\n');
+}
+
+// --- Generate features/INDEX.md and per-feature pages ---
+{
+  const featRoot = path.join(engRoot, 'features');
+
+  const featLines = [GENERATED, '', `# Feature Registry`, '',
+    `> Generated: ${new Date().toISOString().slice(0, 10)}`, ''];
+
+  if (allFeatures.length > 0) {
+    const rows = [['Feature ID', 'Title', 'Status', 'Sprints', 'Tasks']];
+    for (const f of allFeatures) {
+      if (!f.id) continue;
+      const sp = f.sprints || [];
+      const ts = f.tasks || [];
+      rows.push([
+        `[${f.id}](${f.id}.md)`,
+        f.title || '—',
+        statusBadge(f.status || 'draft'),
+        sp.length ? sp.join(', ') : '—',
+        ts.length ? ts.join(', ') : '—'
+      ]);
+
+      // Per-feature page
+      const pfLines = [GENERATED, '', `# Feature: ${f.title || f.id}`, '',
+        `> Feature ID: ${f.id}`,
+        `> Status: ${statusBadge(f.status || 'draft')}`,
+        `> Created: ${f.created_at || '—'}`,
+        ''];
+
+      if (f.description) pfLines.push('## Description', '', f.description, '');
+
+      if (f.requirements && f.requirements.length > 0) {
+        pfLines.push('## Requirements', '');
+        f.requirements.forEach(req => pfLines.push(`- ${req}`));
+        pfLines.push('');
+      }
+
+      if (sp.length > 0) {
+        pfLines.push('## Linked Sprints', '');
+        sp.forEach(s => pfLines.push(`- ${s}`));
+        pfLines.push('');
+      }
+
+      if (ts.length > 0) {
+        pfLines.push('## Linked Tasks', '');
+        ts.forEach(t => pfLines.push(`- ${t}`));
+        pfLines.push('');
+      }
+
+      writeFile(path.join(featRoot, `${f.id}.md`), pfLines.join('\n') + '\n');
+    }
+    featLines.push(padTable(rows), '');
+  } else {
+    featLines.push('_No features yet._', '');
+  }
+
+  writeFile(path.join(featRoot, 'INDEX.md'), featLines.join('\n') + '\n');
+}
+
+// --- Generate Sprint INDEX.md and Task INDEX.md ---
+function availableDocsIn(dir, knownDocs) {
+  if (!fs.existsSync(dir)) return [];
+  return knownDocs.map(d => d.file).filter(f => fs.existsSync(path.join(dir, f)));
+}
+
+let sprintIndexesWritten = 0;
+let taskIndexesWritten = 0;
+
+for (const sprint of targetSprints) {
+  let sprintDirName;
+  if (sprint.path) {
+    sprintDirName = path.basename(sprint.path.replace(/\/$/, ''));
+  } else {
+    sprintDirName = resolveDir(
+      path.join(engRoot, 'sprints'),
+      sprint.sprintId,
+      sprint.sprintId.split('-').pop()
+    );
+  }
+  const sprintDir = path.join(engRoot, 'sprints', sprintDirName);
+
+  // Resolve task directories for all tasks in this sprint
+  const rawSprintTasks = (tasksBySprint[sprint.sprintId] || []).sort((a, b) => a.taskId.localeCompare(b.taskId));
+  const sprintTasks = rawSprintTasks.map(t => {
+    const dirResult = resolveTaskDir(t, sprintDir, engPath);
+    return dirResult.ok ? Object.assign({}, t, { _taskDir: dirResult.value }) : t;
+  });
+
+  // Sprint INDEX.md — pass tasks with _taskDir so links resolve correctly
+  const sprintAvailDocs = availableDocsIn(sprintDir, SPRINT_DOCS);
+  writeFile(path.join(sprintDir, 'INDEX.md'), buildSprintIndex(sprint, sprintTasks, sprintAvailDocs));
+  sprintIndexesWritten++;
+
+  // Task INDEX.md files — generate for every task that has a KB directory
+  for (const task of sprintTasks) {
+    if (!task._taskDir) continue;
+    const taskDir = path.join(sprintDir, task._taskDir);
+    if (!fs.existsSync(taskDir)) continue;
+    const taskAvailDocs = availableDocsIn(taskDir, TASK_DOCS);
+    writeFile(path.join(taskDir, 'INDEX.md'), buildTaskIndex(task, taskAvailDocs));
+    taskIndexesWritten++;
+  }
+}
+
+// --- Generate Bug INDEX.md files ---
+let bugIndexesWritten = 0;
+for (const bug of allBugs) {
+  const bugDirName = resolveDir(path.join(engRoot, 'bugs'), bug.bugId, bug.bugId.split('-').pop());
+  const bugDir = path.join(engRoot, 'bugs', bugDirName);
+  if (!fs.existsSync(bugDir)) continue;
+  const bugAvailDocs = availableDocsIn(bugDir, BUG_DOCS);
+
+  // When purging events for a bug, aggregate cost data from event files
+  // before they are deleted. The aggregated cost summary is embedded in
+  // the bug's INDEX.md so the information survives the purge.
+  let costTotals;
+  if (PURGE_EVENTS && SPRINT_ARG && SPRINT_ARG === bug.bugId) {
+    const { events } = loadSprintEvents(bug.bugId);
+    const tokenEvents = events.filter(e => e.inputTokens !== undefined);
+    if (tokenEvents.length > 0) {
+      const totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUSD: 0, sources: new Set() };
+      for (const e of tokenEvents) {
+        totals.inputTokens     += e.inputTokens     || 0;
+        totals.outputTokens    += e.outputTokens    || 0;
+        totals.cacheReadTokens += e.cacheReadTokens  || 0;
+        totals.cacheWriteTokens+= e.cacheWriteTokens || 0;
+        totals.estimatedCostUSD+= e.estimatedCostUSD || 0;
+        totals.sources.add(e.tokenSource);
+      }
+      costTotals = {
+        inputTokens: totals.inputTokens,
+        outputTokens: totals.outputTokens,
+        cacheReadTokens: totals.cacheReadTokens,
+        cacheWriteTokens: totals.cacheWriteTokens,
+        estimatedCostUSD: totals.estimatedCostUSD,
+        sourceLabel: sourceLabel(totals.sources),
+      };
+    }
+  }
+
+  writeFile(path.join(bugDir, 'INDEX.md'), buildBugIndex(bug, bugAvailDocs, costTotals));
+  bugIndexesWritten++;
+}
+
+// --- Generate COST_REPORT.md per sprint ---
+let costReportsWritten = 0;
+
+for (const sprint of targetSprints) {
+  const { events, orphanSidecars, huskPrimaries } = loadSprintEvents(sprint.sprintId);
+
+  let sprintDirName;
+  if (sprint.path) {
+    sprintDirName = path.basename(sprint.path.replace(/\/$/, ''));
+  } else {
+    sprintDirName = resolveDir(
+      path.join(engRoot, 'sprints'),
+      sprint.sprintId,
+      sprint.sprintId.split('-').pop()
+    );
+  }
+  const reportPath = path.join(engRoot, 'sprints', sprintDirName, 'COST_REPORT.md');
+  const reportContent = buildCostReport(sprint, events, orphanSidecars, huskPrimaries);
+
+  writeFile(reportPath, reportContent);
+  costReportsWritten++;
+}
+
+// --- Write COLLATION_STATE.json ---
+const stateData = {
+  collatedAt: new Date().toISOString(),
+  featureCount: allFeatures.length,
+  sprintCount: targetSprints.length,
+  taskCount: allTasks.filter(t => targetSprints.some(s => s.sprintId === t.sprintId)).length,
+  bugCount: allBugs.length,
+};
+if (DRY_RUN) {
+  console.log(`[dry-run] would write: ${path.relative(cwd, path.join(storeRoot, 'COLLATION_STATE.json'))}`);
+} else {
+  _getStore().writeCollationState(stateData);
+}
+
+const tag = DRY_RUN ? '[dry-run] ' : '';
+console.log(`${tag}Collated: ${targetSprints.length} sprint(s), ${allBugs.length} bug(s) → MASTER_INDEX.md updated, ${sprintIndexesWritten} sprint INDEX(es), ${taskIndexesWritten} task INDEX(es), ${bugIndexesWritten} bug INDEX(es), ${costReportsWritten} COST_REPORT(s) written`);
+
+// --- Purge event directory if requested ---
+if (PURGE_EVENTS) {
+  const relDir = path.relative(cwd, path.join(storeRoot, 'events', SPRINT_ARG));
+  try {
+    const result = _getStore().purgeEvents(SPRINT_ARG, { dryRun: DRY_RUN });
+    if (result.fileCount === 0) {
+      console.log(`${tag}Purge: no events directory found for '${SPRINT_ARG}' — nothing to delete`);
+    } else if (DRY_RUN) {
+      console.log(`[dry-run] would purge: ${relDir}/ (${result.fileCount} file(s))`);
+    } else {
+      console.log(`Purged: ${relDir}/ (${result.fileCount} event file(s) deleted)`);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+} // end if (require.main === module)