@grainulation/harvest 1.0.0

package/lib/dashboard.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Slim a claims array for dashboard embedding (compact keys).
+ */
+function slim(claims) {
+  return claims.map(c => ({
+    i: c.id, t: c.type, tp: c.topic,
+    c: c.content || c.text || c.claim || c.description || '',
+    e: c.evidence, s: c.status,
+    p: c.phase_added, ts: c.timestamp || c.created || c.date,
+    cf: (c.conflicts_with || []).length > 0 ? c.conflicts_with : undefined,
+    r: c.resolved_by || undefined,
+    tg: (c.tags || []).length > 0 ? c.tags : undefined
+  }));
+}
+
+/**
+ * Load a claims.json file and return parsed data, or null on failure.
+ */
+function loadClaims(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scan for claims.json files in target directory, archive/, and sprints/ subdirs.
+ * Two levels deep to handle structures like root/sprints/<name>/claims.json.
+ */
+function findSprintFiles(targetDir) {
+  const found = [];
+
+  // Direct claims.json in target dir
+  const direct = path.join(targetDir, 'claims.json');
+  if (fs.existsSync(direct)) {
+    found.push({ file: direct, name: path.basename(targetDir), cat: 'root' });
+  }
+
+  // Archive subdir (flat JSON files)
+  const archiveDir = path.join(targetDir, 'archive');
+  if (fs.existsSync(archiveDir) && fs.statSync(archiveDir).isDirectory()) {
+    for (const f of fs.readdirSync(archiveDir)) {
+      if (f.endsWith('.json') && f.includes('claims')) {
+        found.push({ file: path.join(archiveDir, f), name: f.replace('.json', '').replace(/-/g, ' '), cat: 'archive' });
+      }
+    }
+  }
+
+  // Scan subdirectories (two levels: sprints/<name>/claims.json, examples/<name>/claims.json, etc.)
+  try {
+    const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || entry.name === 'archive' || entry.name === 'node_modules') continue;
+      const childDir = path.join(targetDir, entry.name);
+      const childClaims = path.join(childDir, 'claims.json');
+      if (fs.existsSync(childClaims)) {
+        found.push({ file: childClaims, name: entry.name, cat: 'active' });
+      }
+      // Second level
+      try {
+        const subEntries = fs.readdirSync(childDir, { withFileTypes: true });
+        for (const sub of subEntries) {
+          if (!sub.isDirectory()) continue;
+          if (sub.name.startsWith('.')) continue;
+          const subClaims = path.join(childDir, sub.name, 'claims.json');
+          if (fs.existsSync(subClaims)) {
+            found.push({ file: subClaims, name: sub.name, cat: 'active' });
+          }
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+
+  return found;
+}
+
+/**
+ * Load all sprint data from a target directory.
+ * Returns array of { n, p, q, cat, c } sprint objects ready for template embedding.
+ */
+function loadSprints(targetDir) {
+  const sources = findSprintFiles(targetDir);
+  const sprints = [];
+  for (const src of sources) {
+    const data = loadClaims(src.file);
+    if (!data) continue;
+    const claims = Array.isArray(data) ? data : data.claims || [];
+    if (claims.length === 0) continue;
+    sprints.push({
+      n: src.name,
+      p: data.meta?.phase || 'unknown',
+      q: data.meta?.question || '',
+      cat: src.cat || 'active',
+      c: slim(claims)
+    });
+  }
+  return sprints;
+}
+
+/**
+ * Build the dashboard HTML string from a sprints array.
+ * @param {Array} sprints - Array of { n, p, q, cat, c } sprint objects
+ * @returns {string} Complete HTML string
+ */
+function buildHtml(sprints) {
+  const templatePath = path.join(__dirname, '..', 'templates', 'dashboard.html');
+  const template = fs.readFileSync(templatePath, 'utf8');
+  const jsonData = JSON.stringify(sprints).replace(/<\/script/gi, '<\\/script');
+  return template.replace('__SPRINT_DATA__', jsonData);
+}
+
+/**
+ * Return paths to all claims.json files for watching.
+ */
+function claimsPaths(targetDir) {
+  return findSprintFiles(targetDir).map(s => s.file);
+}
+
+module.exports = { loadSprints, buildHtml, claimsPaths, findSprintFiles, slim };

package/lib/decay.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Knowledge freshness tracking.
+ *
+ * Identifies claims that may have become stale:
+ * - Claims older than a threshold with no revalidation
+ * - Claims referencing external tools/APIs that change frequently
+ * - Claims with evidence tier "web" that are old (web content changes)
+ * - Claims that were challenged but never resolved
+ */
+
+const VOLATILE_EVIDENCE = new Set(['stated', 'web']);
+const DEFAULT_THRESHOLD_DAYS = 90;
+
+function checkDecay(sprints, opts = {}) {
+  const thresholdDays = opts.thresholdDays || DEFAULT_THRESHOLD_DAYS;
+  const now = new Date();
+
+  const allClaims = sprints.flatMap(s => s.claims.map(c => ({ ...c, _sprint: s.name })));
+
+  const decaying = [];
+  const stale = [];
+  const unresolved = [];
+
+  for (const claim of allClaims) {
+    const created = claim.created || claim.date || claim.timestamp;
+    const age = created ? daysBetween(new Date(created), now) : null;
+
+    // Stale: old claims with volatile evidence
+    if (age !== null && age > thresholdDays && VOLATILE_EVIDENCE.has(claim.evidence)) {
+      stale.push({
+        id: claim.id,
+        sprint: claim._sprint,
+        type: claim.type,
+        evidence: claim.evidence,
+        ageDays: age,
+        text: truncate(claim.text || claim.claim || claim.description, 120),
+        reason: `${claim.evidence}-tier evidence is ${age} days old (threshold: ${thresholdDays}).`,
+      });
+    }
+
+    // Decaying: any claim past threshold, regardless of evidence
+    if (age !== null && age > thresholdDays * 1.5) {
+      decaying.push({
+        id: claim.id,
+        sprint: claim._sprint,
+        type: claim.type,
+        evidence: claim.evidence,
+        ageDays: age,
+        text: truncate(claim.text || claim.claim || claim.description, 120),
+        reason: `Claim is ${age} days old with no revalidation.`,
+      });
+    }
+
+    // Unresolved: challenged claims still marked as contested
+    if (claim.status === 'contested' || claim.status === 'challenged') {
+      unresolved.push({
+        id: claim.id,
+        sprint: claim._sprint,
+        type: claim.type,
+        text: truncate(claim.text || claim.claim || claim.description, 120),
+        reason: 'Claim was challenged but never resolved.',
+      });
+    }
+  }
+
+  // Deduplicate (a claim might appear in both stale and decaying)
+  const decayingIds = new Set(decaying.map(c => c.id));
+  const dedupedStale = stale.filter(c => !decayingIds.has(c.id));
+
+  // Sort by age descending
+  const sortByAge = (a, b) => (b.ageDays || 0) - (a.ageDays || 0);
+  decaying.sort(sortByAge);
+  dedupedStale.sort(sortByAge);
+
+  return {
+    summary: {
+      totalClaims: allClaims.length,
+      staleCount: dedupedStale.length,
+      decayingCount: decaying.length,
+      unresolvedCount: unresolved.length,
+      thresholdDays,
+    },
+    stale: dedupedStale,
+    decaying,
+    unresolved,
+    insight: generateDecayInsight(allClaims.length, dedupedStale, decaying, unresolved),
+  };
+}
+
+function daysBetween(a, b) {
+  return Math.floor(Math.abs(b - a) / (1000 * 60 * 60 * 24));
+}
+
+function truncate(str, maxLen) {
+  if (!str) return '';
+  return str.length > maxLen ? str.slice(0, maxLen - 3) + '...' : str;
+}
+
+function generateDecayInsight(total, stale, decaying, unresolved) {
+  const parts = [];
+
+  if (decaying.length > 0) {
+    parts.push(`${decaying.length} claim(s) are significantly outdated and should be revalidated or archived.`);
+  }
+
+  if (stale.length > 0) {
+    parts.push(`${stale.length} claim(s) have volatile evidence (stated/web) that may no longer be accurate.`);
+  }
+
+  if (unresolved.length > 0) {
+    parts.push(`${unresolved.length} challenged claim(s) remain unresolved -- use /resolve to settle them.`);
+  }
+
+  const decayRate = total > 0 ? Math.round((stale.length + decaying.length) / total * 100) : 0;
+  if (decayRate > 30) {
+    parts.push(`Knowledge decay rate is ${decayRate}% -- consider a refresh sprint.`);
+  }
+
+  return parts.length > 0 ? parts.join(' ') : 'Knowledge base looks fresh -- no decay detected.';
+}
+
+module.exports = { checkDecay };

package/lib/farmer.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const https = require('node:https');
+
+/**
+ * POST an activity event to farmer.
+ * Graceful failure -- catch and warn, never crash.
+ * @param {string} farmerUrl - Base URL of farmer (e.g. http://localhost:9090)
+ * @param {object} event - Event object (e.g. { type: "analyze", data: {...} })
+ */
+function notify(farmerUrl, event) {
+  return new Promise((resolve) => {
+    try {
+      const payload = JSON.stringify({
+        tool: 'harvest',
+        event,
+        timestamp: new Date().toISOString()
+      });
+
+      const url = new URL(`${farmerUrl}/hooks/activity`);
+      const transport = url.protocol === 'https:' ? https : http;
+
+      const req = transport.request({
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload)
+        },
+        timeout: 5000
+      }, (res) => {
+        let body = '';
+        res.on('data', chunk => { body += chunk; });
+        res.on('end', () => resolve({ ok: res.statusCode < 400, status: res.statusCode, body }));
+      });
+
+      req.on('error', (err) => {
+        console.error(`[harvest] farmer notify failed: ${err.message}`);
+        resolve({ ok: false, error: err.message });
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        console.error('[harvest] farmer notify timed out');
+        resolve({ ok: false, error: 'timeout' });
+      });
+
+      req.write(payload);
+      req.end();
+    } catch (err) {
+      console.error(`[harvest] farmer notify failed: ${err.message}`);
+      resolve({ ok: false, error: err.message });
+    }
+  });
+}
+
+/**
+ * CLI handler for `harvest connect farmer`.
+ * Reads/writes .farmer.json in targetDir.
+ * @param {string} targetDir - Working directory
+ * @param {string[]} args - CLI arguments (e.g. ["farmer", "--url", "http://..."])
+ */
+async function connect(targetDir, args) {
+  const subcommand = args[0];
+  if (subcommand !== 'farmer') {
+    console.error('Usage: harvest connect farmer [--url http://localhost:9090]');
+    process.exit(1);
+  }
+
+  const configPath = path.join(targetDir, '.farmer.json');
+
+  const urlIdx = args.indexOf('--url');
+  if (urlIdx !== -1 && args[urlIdx + 1]) {
+    const url = args[urlIdx + 1];
+    const config = { url };
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+    console.log(`Farmer connection saved to ${configPath}`);
+    console.log(`  URL: ${url}`);
+
+    // Test the connection
+    const result = await notify(url, { type: 'connect', data: { tool: 'harvest' } });
+    if (result.ok) {
+      console.log('  Connection test: OK');
+    } else {
+      console.log(`  Connection test: failed (${result.error || 'status ' + result.status})`);
+      console.log('  Farmer may not be running. The URL is saved and will be used when farmer is available.');
+    }
+    return;
+  }
+
+  // Show current config
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    console.log(`Farmer connection: ${config.url}`);
+    console.log(`Config: ${configPath}`);
+  } else {
+    console.log('No farmer connection configured.');
+    console.log('Usage: harvest connect farmer --url http://localhost:9090');
+  }
+}
+
+module.exports = { connect, notify };

package/lib/patterns.js

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * Decision pattern detection.
+ *
+ * Analyzes what research approaches lead to better outcomes by examining:
+ * - Which command sequences produce the most well-evidenced claims
+ * - Whether prototyping before recommending leads to better accuracy
+ * - Whether challenge/witness steps improve final outcomes
+ * - Common anti-patterns (e.g., jumping to recommendations without research)
+ */
+
+const EVIDENCE_RANK = {
+  stated: 1,
+  web: 2,
+  documented: 3,
+  tested: 4,
+  production: 5,
+};
+
+function detectPatterns(sprints) {
+  const patterns = [];
+  const antiPatterns = [];
+
+  for (const sprint of sprints) {
+    const claims = sprint.claims;
+    if (claims.length === 0) continue;
+
+    const phases = extractPhases(claims);
+    const avgEvidence = averageEvidenceLevel(claims);
+    const hasPrototype = claims.some(c => c.id && c.id.startsWith('p'));
+    const hasChallenge = claims.some(c => c.id && c.id.startsWith('x'));
+    const hasWitness = claims.some(c => c.id && c.id.startsWith('w'));
+    const recommendations = claims.filter(c => c.type === 'recommendation');
+    const estimates = claims.filter(c => c.type === 'estimate');
+
+    // Pattern: prototype-before-recommend
+    if (hasPrototype && recommendations.length > 0) {
+      const protoIndices = claims
+        .map((c, i) => c.id && c.id.startsWith('p') ? i : -1)
+        .filter(i => i >= 0);
+      const recIndices = claims
+        .map((c, i) => c.type === 'recommendation' ? i : -1)
+        .filter(i => i >= 0);
+
+      const prototypedFirst = protoIndices.some(pi =>
+        recIndices.some(ri => pi < ri)
+      );
+
+      if (prototypedFirst) {
+        patterns.push({
+          sprint: sprint.name,
+          pattern: 'prototype-before-recommend',
+          description: 'Prototyped before making recommendations -- tends to produce higher-evidence claims.',
+          evidenceLevel: avgEvidence,
+        });
+      }
+    }
+
+    // Pattern: adversarial testing
+    if (hasChallenge) {
+      patterns.push({
+        sprint: sprint.name,
+        pattern: 'adversarial-testing',
+        description: 'Used /challenge to stress-test claims -- builds confidence in findings.',
+        claimsChallenged: claims.filter(c => c.id && c.id.startsWith('x')).length,
+      });
+    }
+
+    // Pattern: external corroboration
+    if (hasWitness) {
+      patterns.push({
+        sprint: sprint.name,
+        pattern: 'external-corroboration',
+        description: 'Used /witness to corroborate claims with external sources.',
+        witnessCount: claims.filter(c => c.id && c.id.startsWith('w')).length,
+      });
+    }
+
+    // Anti-pattern: recommend without research
+    const researchClaims = claims.filter(c => c.id && c.id.startsWith('r'));
+    if (recommendations.length > 0 && researchClaims.length === 0) {
+      antiPatterns.push({
+        sprint: sprint.name,
+        pattern: 'recommend-without-research',
+        description: 'Recommendations made without dedicated research claims.',
+        severity: 'high',
+      });
+    }
+
+    // Anti-pattern: estimate without evidence
+    const weakEstimates = estimates.filter(c =>
+      (EVIDENCE_RANK[c.evidence] || 0) <= 2
+    );
+    if (weakEstimates.length > estimates.length * 0.5 && estimates.length > 0) {
+      antiPatterns.push({
+        sprint: sprint.name,
+        pattern: 'weak-estimates',
+        description: `${weakEstimates.length}/${estimates.length} estimates have weak evidence (stated/web only).`,
+        severity: 'medium',
+      });
+    }
+
+    // Anti-pattern: type monoculture
+    const typeCounts = {};
+    for (const c of claims) {
+      typeCounts[c.type || 'unknown'] = (typeCounts[c.type || 'unknown'] || 0) + 1;
+    }
+    const maxType = Object.entries(typeCounts).sort((a, b) => b[1] - a[1])[0];
+    if (maxType && maxType[1] / claims.length > 0.7 && claims.length > 5) {
+      antiPatterns.push({
+        sprint: sprint.name,
+        pattern: 'type-monoculture',
+        description: `${Math.round(maxType[1] / claims.length * 100)}% of claims are "${maxType[0]}" -- diversity of analysis may be lacking.`,
+        severity: 'low',
+      });
+    }
+  }
+
+  // Cross-sprint patterns
+  const crossSprint = analyzeCrossSprintTrends(sprints, patterns);
+
+  return {
+    summary: {
+      totalSprints: sprints.length,
+      patternsFound: patterns.length,
+      antiPatternsFound: antiPatterns.length,
+    },
+    patterns,
+    antiPatterns,
+    crossSprint,
+    insight: generatePatternInsight(patterns, antiPatterns, crossSprint),
+  };
+}
+
+function extractPhases(claims) {
+  const phases = new Set();
+  for (const c of claims) {
+    if (!c.id) continue;
+    const prefix = c.id.replace(/\d+$/, '');
+    phases.add(prefix);
+  }
+  return [...phases];
+}
+
+function averageEvidenceLevel(claims) {
+  const levels = claims.map(c => EVIDENCE_RANK[c.evidence] || 0).filter(l => l > 0);
+  if (levels.length === 0) return 0;
+  return Math.round(levels.reduce((a, b) => a + b, 0) / levels.length * 10) / 10;
+}
+
+function analyzeCrossSprintTrends(sprints, patterns) {
+  const trends = {};
+
+  // How many sprints use each pattern?
+  for (const p of patterns) {
+    trends[p.pattern] = trends[p.pattern] || { count: 0, sprints: [] };
+    trends[p.pattern].count++;
+    trends[p.pattern].sprints.push(p.sprint);
+  }
+
+  // Evidence level trend across sprints (are we getting better?)
+  const evidenceTrend = sprints.map(s => ({
+    sprint: s.name,
+    avgEvidence: averageEvidenceLevel(s.claims),
+    claimCount: s.claims.length,
+  }));
+
+  return { patternFrequency: trends, evidenceTrend };
+}
+
+function generatePatternInsight(patterns, antiPatterns, crossSprint) {
+  const parts = [];
+
+  const protoBeforeRec = patterns.filter(p => p.pattern === 'prototype-before-recommend');
+  if (protoBeforeRec.length > 0) {
+    parts.push(`${protoBeforeRec.length} sprint(s) prototyped before recommending -- good practice.`);
+  }
+
+  const noResearch = antiPatterns.filter(p => p.pattern === 'recommend-without-research');
+  if (noResearch.length > 0) {
+    parts.push(`${noResearch.length} sprint(s) recommended without dedicated research -- consider adding /research steps.`);
+  }
+
+  const trend = crossSprint.evidenceTrend;
+  if (trend.length >= 2) {
+    const first = trend[0].avgEvidence;
+    const last = trend[trend.length - 1].avgEvidence;
+    if (last > first) {
+      parts.push('Evidence quality is trending up across sprints.');
+    } else if (last < first) {
+      parts.push('Evidence quality has declined -- recent sprints may need stronger validation.');
+    }
+  }
+
+  return parts.length > 0 ? parts.join(' ') : 'Not enough sprint data to detect clear patterns.';
+}
+
+module.exports = { detectPatterns };

package/lib/report.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Generate retrospective HTML reports.
+ *
+ * Combines all analysis modules into a single dark-themed HTML report.
+ */
+
+function generateReport(sprints, fns) {
+  const analysis = fns.analyzeFn(sprints);
+  const calibration = fns.calibrateFn(sprints);
+  const patterns = fns.patternsFn(sprints);
+  const decay = fns.decayFn(sprints);
+  const velocity = fns.velocityFn(sprints);
+
+  // Try to load template
+  const templatePath = path.join(__dirname, '..', 'templates', 'retrospective.html');
+  let template;
+  try {
+    template = fs.readFileSync(templatePath, 'utf8');
+  } catch {
+    template = getDefaultTemplate();
+  }
+
+  // Inject data into template
+  const html = template
+    .replace('{{GENERATED_DATE}}', new Date().toISOString().split('T')[0])
+    .replace('{{SPRINT_COUNT}}', String(analysis.summary.totalSprints))
+    .replace('{{CLAIM_COUNT}}', String(analysis.summary.totalClaims))
+    .replace('{{AVG_CLAIMS}}', String(analysis.summary.averageClaimsPerSprint))
+    .replace('{{ACCURACY_RATE}}', calibration.summary.accuracyRate !== null ? calibration.summary.accuracyRate + '%' : 'N/A')
+    .replace('{{ESTIMATE_COUNT}}', String(calibration.summary.totalEstimates))
+    .replace('{{MATCHED_COUNT}}', String(calibration.summary.matched))
+    .replace('{{UNMATCHED_COUNT}}', String(calibration.summary.unmatched))
+    .replace('{{CALIBRATION_INSIGHT}}', escapeHtml(calibration.insight))
+    .replace('{{PATTERN_COUNT}}', String(patterns.summary.patternsFound))
+    .replace('{{ANTI_PATTERN_COUNT}}', String(patterns.summary.antiPatternsFound))
+    .replace('{{PATTERN_INSIGHT}}', escapeHtml(patterns.insight))
+    .replace('{{PATTERNS_LIST}}', renderPatternsList(patterns))
+    .replace('{{ANTI_PATTERNS_LIST}}', renderAntiPatternsList(patterns))
+    .replace('{{STALE_COUNT}}', String(decay.summary.staleCount))
+    .replace('{{DECAYING_COUNT}}', String(decay.summary.decayingCount))
+    .replace('{{UNRESOLVED_COUNT}}', String(decay.summary.unresolvedCount))
+    .replace('{{DECAY_INSIGHT}}', escapeHtml(decay.insight))
+    .replace('{{AVG_DURATION}}', velocity.summary.avgDurationDays !== null ? velocity.summary.avgDurationDays + ' days' : 'N/A')
+    .replace('{{AVG_CLAIMS_PER_DAY}}', velocity.summary.avgClaimsPerDay !== null ? String(velocity.summary.avgClaimsPerDay) : 'N/A')
+    .replace('{{TOTAL_STALLS}}', String(velocity.summary.totalStalls))
+    .replace('{{VELOCITY_INSIGHT}}', escapeHtml(velocity.insight))
+    .replace('{{TYPE_DISTRIBUTION}}', renderDistribution(analysis.typeDistribution))
+    .replace('{{EVIDENCE_DISTRIBUTION}}', renderDistribution(analysis.evidenceDistribution))
+    .replace('{{WEAK_CLAIMS_TABLE}}', renderWeakClaimsTable(analysis.weakClaims))
+    .replace('{{DECAY_TABLE}}', renderDecayTable([...decay.stale, ...decay.decaying]))
+    .replace('{{VELOCITY_TABLE}}', renderVelocityTable(velocity.sprints));
+
+  return html;
+}
+
+function escapeHtml(str) {
+  if (!str) return '';
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function renderDistribution(dist) {
+  return Object.entries(dist)
+    .sort((a, b) => b[1] - a[1])
+    .map(([key, val]) => `<div class="bar-row"><span class="bar-label">${escapeHtml(key)}</span><div class="bar" style="width: ${Math.min(100, val * 5)}%">${val}</div></div>`)
+    .join('\n');
+}
+
+function renderPatternsList(patterns) {
+  if (patterns.patterns.length === 0) return '<p class="muted">No positive patterns detected yet.</p>';
+  return '<ul>' + patterns.patterns.map(p =>
+    `<li><strong>${escapeHtml(p.pattern)}</strong> (${escapeHtml(p.sprint)}): ${escapeHtml(p.description)}</li>`
+  ).join('') + '</ul>';
+}
+
+function renderAntiPatternsList(patterns) {
+  if (patterns.antiPatterns.length === 0) return '<p class="muted">No anti-patterns detected.</p>';
+  return '<ul>' + patterns.antiPatterns.map(p =>
+    `<li class="severity-${p.severity}"><strong>${escapeHtml(p.pattern)}</strong> (${escapeHtml(p.sprint)}): ${escapeHtml(p.description)}</li>`
+  ).join('') + '</ul>';
+}
+
+function renderWeakClaimsTable(claims) {
+  if (claims.length === 0) return '<p class="muted">All claims have solid evidence.</p>';
+  const rows = claims.slice(0, 20).map(c =>
+    `<tr><td>${escapeHtml(c.id)}</td><td>${escapeHtml(c.sprint)}</td><td>${escapeHtml(c.type)}</td><td>${escapeHtml(c.evidence)}</td><td>${escapeHtml(String(c.text || ''))}</td></tr>`
+  ).join('');
+  return `<table><thead><tr><th>ID</th><th>Sprint</th><th>Type</th><th>Evidence</th><th>Claim</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function renderDecayTable(items) {
+  if (items.length === 0) return '<p class="muted">No knowledge decay detected.</p>';
+  const rows = items.slice(0, 20).map(c =>
+    `<tr><td>${escapeHtml(c.id)}</td><td>${escapeHtml(c.sprint)}</td><td>${c.ageDays || '?'} days</td><td>${escapeHtml(c.reason)}</td></tr>`
+  ).join('');
+  return `<table><thead><tr><th>ID</th><th>Sprint</th><th>Age</th><th>Reason</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function renderVelocityTable(sprintResults) {
+  if (sprintResults.length === 0) return '<p class="muted">No velocity data available.</p>';
+  const rows = sprintResults.map(s =>
+    `<tr><td>${escapeHtml(s.sprint)}</td><td>${s.durationDays ?? 'N/A'}</td><td>${s.totalClaims ?? '?'}</td><td>${s.claimsPerDay ?? 'N/A'}</td><td>${s.stalls.length}</td></tr>`
+  ).join('');
+  return `<table><thead><tr><th>Sprint</th><th>Days</th><th>Claims</th><th>Claims/Day</th><th>Stalls</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function getDefaultTemplate() {
+  // Fallback inline template if file not found
+  return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Harvest Retrospective</title>
+<style>body{background:#0f0f0f;color:#e5e5e5;font-family:system-ui;padding:2rem;max-width:900px;margin:0 auto}
+h1,h2{color:#f97316}.muted{color:#888}</style></head>
+<body><h1>Harvest Retrospective</h1><p>Generated: {{GENERATED_DATE}}</p>
+<p>{{SPRINT_COUNT}} sprints, {{CLAIM_COUNT}} claims</p></body></html>`;
+}
+
+module.exports = { generateReport };