@entelligentsia/forgecli 0.8.4 → 0.9.1

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

@@ -1,1041 +0,0 @@
-#!/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)