@hone-ai/cli 1.4.0

package/lib/install-hooks.js

@@ -0,0 +1,205 @@
+'use strict';
+/**
+ * install-hooks.js — HC-001 (first git hook the framework ships).
+ *
+ * Pure helper that installs / uninstalls the framework's pre-commit and
+ * pre-push hooks into a target repo's `.git/hooks/`. Implements OptionsFlow
+ * E15-A-L1 (deferred during SC-009 absorption).
+ *
+ * Architecture decisions (per HC-001 step-1-plan.md):
+ *   - Hook content as STATIC `.sh` files in `cli/lib/hook-templates/`
+ *   - Default mode: NATIVE (`.git/hooks/`); detect husky and skip if present
+ *   - Marker: COMMENT line in the hook (`# managed-by: hone`)
+ *   - Idempotent: re-install over managed hook is no-op; never overwrite unmanaged
+ *
+ * Failure modes (all return structured result; never throw):
+ *   - target .git/hooks/ missing            → 'no-git-dir' finding
+ *   - existing unmanaged hook (no --force)  → 'unmanaged-existing-hook' skipped entry
+ *   - husky detected (no --mode native)     → 'husky-detected' skipped entry
+ *   - template file missing                 → 'template-missing' finding
+ *
+ * Pure-helper-with-injected-IO style (Category B per cli/lib/README.md).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const HOOK_NAMES = ['pre-commit', 'pre-push'];
+const MANAGED_MARKER = 'managed-by: hone';
+const TEMPLATES_DIR = path.join(__dirname, 'hook-templates');
+
+/**
+ * Install framework hooks into a target repo.
+ *
+ * @param {object}  args
+ * @param {string}  args.repoRoot
+ * @param {string}  [args.mode]      'auto' (default) | 'native' | 'skip-husky'
+ * @param {boolean} [args.force]     overwrite unmanaged hooks
+ * @returns {{
+ *   findings: Array,
+ *   summary: { total, errors, warnings, info },
+ *   installed: string[],
+ *   skipped: Array<{hook, reason, userAction?}>,
+ * }}
+ */
+function installHooks(args) {
+  const { repoRoot, mode = 'auto', force = false } = args || {};
+  const findings = [];
+  const installed = [];
+  const skipped = [];
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return wrap([{ severity: 'ERROR', code: 'invalid-args', message: 'repoRoot is required' }], installed, skipped);
+  }
+
+  const hooksDir = path.join(repoRoot, '.git/hooks');
+  if (!fs.existsSync(hooksDir)) {
+    return wrap([{ severity: 'ERROR', code: 'no-git-dir', message: `not a git repo (no .git/hooks at ${repoRoot})` }],
+      installed, skipped);
+  }
+
+  // Husky detection (when mode = 'auto')
+  const huskyPresent = fs.existsSync(path.join(repoRoot, '.husky'));
+  if (huskyPresent && mode === 'auto') {
+    for (const hook of HOOK_NAMES) {
+      skipped.push({
+        hook,
+        reason: 'husky-detected — adopter uses husky; pass --mode native to override',
+      });
+    }
+    return wrap(findings, installed, skipped);
+  }
+
+  for (const hook of HOOK_NAMES) {
+    const target = path.join(hooksDir, hook);
+    const templatePath = path.join(TEMPLATES_DIR, `${hook}.sh`);
+
+    if (!fs.existsSync(templatePath)) {
+      findings.push({
+        severity: 'ERROR',
+        code: 'template-missing',
+        message: `template not found: ${templatePath}`,
+      });
+      continue;
+    }
+
+    // Check existing hook
+    if (fs.existsSync(target)) {
+      const existing = fs.readFileSync(target, 'utf8');
+      const isManaged = existing.includes(MANAGED_MARKER);
+      if (isManaged && !force) {
+        skipped.push({
+          hook,
+          reason: 'already-managed — re-install is a no-op; pass --force to overwrite',
+        });
+        continue;
+      }
+      if (!isManaged && !force) {
+        skipped.push({
+          hook,
+          reason: 'unmanaged-existing-hook — refusing to overwrite adopter customization',
+          userAction: 'pass --force to overwrite, or remove the hook manually first',
+        });
+        continue;
+      }
+    }
+
+    // Write hook
+    try {
+      const content = fs.readFileSync(templatePath, 'utf8');
+      fs.writeFileSync(target, content, { mode: 0o755 });
+      // Ensure executable bit (writeFileSync mode option may not apply on all platforms)
+      try { fs.chmodSync(target, 0o755); } catch {}
+      installed.push(hook);
+    } catch (e) {
+      findings.push({
+        severity: 'ERROR',
+        code: 'write-failed',
+        hook,
+        message: `failed to write ${target}: ${e.message}`,
+      });
+    }
+  }
+
+  return wrap(findings, installed, skipped);
+}
+
+/**
+ * Uninstall framework hooks (only removes hooks carrying the managed-by marker).
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @returns {{ findings, summary, removed: string[], skipped: Array }}
+ */
+function uninstallHooks(args) {
+  const { repoRoot } = args || {};
+  const findings = [];
+  const removed = [];
+  const skipped = [];
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return wrapUninstall([{ severity: 'ERROR', code: 'invalid-args', message: 'repoRoot is required' }],
+      removed, skipped);
+  }
+
+  const hooksDir = path.join(repoRoot, '.git/hooks');
+  if (!fs.existsSync(hooksDir)) {
+    return wrapUninstall([{ severity: 'ERROR', code: 'no-git-dir', message: `not a git repo (no .git/hooks at ${repoRoot})` }],
+      removed, skipped);
+  }
+
+  for (const hook of HOOK_NAMES) {
+    const target = path.join(hooksDir, hook);
+    if (!fs.existsSync(target)) continue;
+
+    const existing = fs.readFileSync(target, 'utf8');
+    if (!existing.includes(MANAGED_MARKER)) {
+      skipped.push({
+        hook,
+        reason: 'unmanaged — not removing (was not installed by hone)',
+      });
+      continue;
+    }
+
+    try {
+      fs.unlinkSync(target);
+      removed.push(hook);
+    } catch (e) {
+      findings.push({
+        severity: 'ERROR',
+        code: 'unlink-failed',
+        hook,
+        message: `failed to remove ${target}: ${e.message}`,
+      });
+    }
+  }
+
+  return wrapUninstall(findings, removed, skipped);
+}
+
+function wrap(findings, installed, skipped) {
+  const summary = {
+    total: findings.length,
+    errors: findings.filter(f => f.severity === 'ERROR').length,
+    warnings: findings.filter(f => f.severity === 'WARN').length,
+    info: findings.filter(f => f.severity === 'INFO').length,
+  };
+  return { findings, summary, installed, skipped };
+}
+
+function wrapUninstall(findings, removed, skipped) {
+  const summary = {
+    total: findings.length,
+    errors: findings.filter(f => f.severity === 'ERROR').length,
+    warnings: findings.filter(f => f.severity === 'WARN').length,
+    info: findings.filter(f => f.severity === 'INFO').length,
+  };
+  return { findings, summary, removed, skipped };
+}
+
+module.exports = {
+  installHooks,
+  uninstallHooks,
+  HOOK_NAMES,
+  MANAGED_MARKER,
+};

package/lib/knowledge-graph.js

@@ -0,0 +1,188 @@
+'use strict';
+/**
+ * knowledge-graph.js — HC-020 in-memory knowledge graph from existing
+ * YAML cross-references.
+ *
+ * Zero schema changes. Zero dependencies. Reads existing fields:
+ *   referenced_skill, evidence, references (item-level)
+ *
+ * Graph is a Map-based adjacency list:
+ *   nodes: Map<id, { id, type, name, ...attrs }>
+ *   outEdges: Map<fromId, [{ to, type }]>
+ *   inEdges: Map<toId, [{ from, type }]>
+ *
+ * Node types (4): learning, skill, file, story
+ * Edge types (4): REFERENCES_SKILL, HAS_EVIDENCE, HAS_LEARNING, REFERENCES
+ *
+ * Architecture: docs/architecture/knowledge-graph-phases.md (Phase 1)
+ */
+
+class KnowledgeGraph {
+  constructor() {
+    this.nodes = new Map();
+    this.outEdges = new Map();
+    this.inEdges = new Map();
+  }
+
+  addNode(id, attrs) {
+    if (!this.nodes.has(id)) {
+      this.nodes.set(id, { id, ...attrs });
+    }
+  }
+
+  addEdge(from, to, type) {
+    if (!this.outEdges.has(from)) this.outEdges.set(from, []);
+    this.outEdges.get(from).push({ to, type });
+    if (!this.inEdges.has(to)) this.inEdges.set(to, []);
+    this.inEdges.get(to).push({ from, type });
+  }
+
+  // ── Query Functions (HC-020b) ──────────────────────────────
+
+  /** Which learnings reference this skill? */
+  learningsForSkill(skillName) {
+    const skillId = `skill:${skillName}`;
+    return (this.inEdges.get(skillId) || [])
+      .filter(e => e.type === 'REFERENCES_SKILL')
+      .map(e => this.nodes.get(e.from))
+      .filter(Boolean);
+  }
+
+  /** Which code files are evidence for this learning? */
+  filesForLearning(learningId) {
+    return (this.outEdges.get(learningId) || [])
+      .filter(e => e.type === 'HAS_EVIDENCE')
+      .map(e => this.nodes.get(e.to))
+      .filter(Boolean);
+  }
+
+  /** Which learnings mention this file as evidence? */
+  learningsForFile(filePath) {
+    const fileId = `file:${filePath}`;
+    return (this.inEdges.get(fileId) || [])
+      .filter(e => e.type === 'HAS_EVIDENCE')
+      .map(e => this.nodes.get(e.from))
+      .filter(Boolean);
+  }
+
+  /** HC-019d-fix-L2: Which OTHER files are connected via shared learnings? */
+  siblingFiles(filePath) {
+    const fileId = `file:${filePath}`;
+    const learnings = (this.inEdges.get(fileId) || [])
+      .filter(e => e.type === 'HAS_EVIDENCE')
+      .map(e => e.from);
+    const siblings = new Set();
+    for (const lid of learnings) {
+      for (const edge of (this.outEdges.get(lid) || [])) {
+        if (edge.type === 'HAS_EVIDENCE' && edge.to !== fileId) {
+          siblings.add(edge.to);
+        }
+      }
+    }
+    return [...siblings].map(s => this.nodes.get(s)).filter(Boolean);
+  }
+
+  /** Which skills does this story touch? (via story→learning→skill) */
+  skillsForStory(storyId) {
+    const storyNode = `story:${storyId}`;
+    const learnings = (this.outEdges.get(storyNode) || [])
+      .filter(e => e.type === 'HAS_LEARNING')
+      .map(e => e.to);
+    const skills = new Set();
+    for (const lid of learnings) {
+      for (const edge of (this.outEdges.get(lid) || [])) {
+        if (edge.type === 'REFERENCES_SKILL') skills.add(edge.to);
+      }
+    }
+    return [...skills].map(s => this.nodes.get(s)).filter(Boolean);
+  }
+
+  // ── Metrics ────────────────────────────────────────────────
+
+  get nodeCount() { return this.nodes.size; }
+  get edgeCount() {
+    let count = 0;
+    for (const edges of this.outEdges.values()) count += edges.length;
+    return count;
+  }
+}
+
+/**
+ * Build graph from existing YAML data. Zero schema changes.
+ *
+ * @param {object} opts
+ * @param {object[]} opts.learningFiles — parsed .github/learnings/*.yml
+ * @returns {KnowledgeGraph}
+ */
+function buildKnowledgeGraph({ learningFiles = [] }) {
+  const graph = new KnowledgeGraph();
+
+  for (const file of learningFiles) {
+    if (!file || typeof file !== 'object') continue;
+
+    const storyId = file.story_id;
+    if (storyId) {
+      graph.addNode(`story:${storyId}`, { type: 'story', name: storyId });
+    }
+
+    // Support Schema C (learnings array) and Schema B (enterprise_candidates)
+    const items = file.learnings || file.enterprise_candidates || [];
+
+    for (const item of items) {
+      if (!item || !item.id) continue;
+      const learningId = `learning:${item.id}`;
+
+      graph.addNode(learningId, {
+        type: 'learning',
+        name: item.title || item.id,
+        learningType: item.type || null,
+        referencedSection: item.referenced_section || null,
+        enterpriseSummary: item.enterprise_summary || null,
+        category: item.category || null,
+        status: file.status || 'pending',
+      });
+
+      // Story → Learning
+      if (storyId) {
+        graph.addEdge(`story:${storyId}`, learningId, 'HAS_LEARNING');
+      }
+
+      // Learning → Skill
+      if (item.referenced_skill) {
+        const skillId = `skill:${item.referenced_skill}`;
+        graph.addNode(skillId, { type: 'skill', name: item.referenced_skill });
+        graph.addEdge(learningId, skillId, 'REFERENCES_SKILL');
+      }
+
+      // Learning → Evidence files
+      for (const evidence of (item.evidence || [])) {
+        const fileId = `file:${evidence}`;
+        graph.addNode(fileId, { type: 'file', name: evidence });
+        graph.addEdge(learningId, fileId, 'HAS_EVIDENCE');
+      }
+
+      // Learning → References (item-level, not file-level)
+      // v1.1 fix: reads item.references, not file.references
+      for (const ref of (item.references || [])) {
+        if (typeof ref !== 'string') continue;
+        if (ref.includes('/learnings/') && ref.endsWith('.yml')) {
+          const match = ref.match(/learnings\/([^.]+)\.yml/);
+          if (match) {
+            const targetStory = `story:${match[1]}`;
+            graph.addNode(targetStory, { type: 'story', name: match[1] });
+            graph.addEdge(learningId, targetStory, 'REFERENCES');
+          }
+        } else {
+          // Code file reference (additional evidence)
+          const fileId = `file:${ref}`;
+          graph.addNode(fileId, { type: 'file', name: ref });
+          graph.addEdge(learningId, fileId, 'HAS_EVIDENCE');
+        }
+      }
+    }
+  }
+
+  return graph;
+}
+
+module.exports = { KnowledgeGraph, buildKnowledgeGraph };

package/lib/learnings-audit.js

@@ -0,0 +1,254 @@
+'use strict';
+/**
+ * learnings-audit.js — LC-003 (#58 G2 partial, story 3/3): pure helper for
+ * the `hone audit-learnings` retrospective CLI.
+ *
+ * Read-only retrospective: walks the captured learnings corpus, classifies
+ * each entry by freshness/incorporation/contradiction status, and reports
+ * which learnings still need attention vs. which are settled.
+ *
+ * Pure-helper-with-injected-I/O: the caller owns filesystem + git access
+ * and injects:
+ *   - learningsFiles: array of {fileLabel, content} pairs
+ *   - skillNames:     array of known skills
+ *   - getSkillLastModifiedDays(name): number|null — days since the skill
+ *     file was last touched (caller queries `git log -1 --format=%ct`)
+ *   - today: 'YYYY-MM-DD' (caller injects for testability; defaults to
+ *     new Date().toISOString().slice(0,10))
+ *
+ * Built on LC-001's schema (category + referenced_skill). Without LC-001
+ * this audit cannot distinguish promotion candidates from compliance
+ * evidence — see the LC-002-L1 learning for the same logic in audit-skills.
+ *
+ * Issue: #58 (G2 partial, story 3/3).
+ */
+const { parseLearningsFile, LEARNING_CATEGORIES } = require('./learnings-parse');
+const yaml = require('js-yaml');
+
+/** Status enum for each audited learning entry. */
+const STATUS = Object.freeze({
+  FRESH:        'fresh',          // age ≤ 30d, not yet incorporated, no contradiction
+  AGING:        'aging',          // 30d < age ≤ 180d, no incorporation, no contradiction
+  STALE:        'stale',          // age > 180d, no incorporation, no contradiction
+  INCORPORATED: 'incorporated',   // promoted, OR referenced skill was touched after capture
+  CONTRADICTED: 'contradicted',   // a later learning marks this skill as exception-with-rationale
+  UNKNOWN:      'unknown',        // can't determine (missing captured_at, etc.)
+});
+
+const FRESH_THRESHOLD_DAYS = 30;
+const STALE_THRESHOLD_DAYS = 180;
+
+/**
+ * Audit a corpus of learnings.
+ *
+ * @param {object} opts
+ * @param {Array<{fileLabel: string, content: string}>} opts.learningsFiles
+ * @param {string[]} [opts.skillNames]
+ * @param {(name: string) => number|null} [opts.getSkillLastModifiedDays]
+ *   Returns days since the named skill file was last modified.
+ *   null = skill doesn't exist or no commits found.
+ * @param {(fileLabel: string) => number|null} [opts.getCapturedAtFromGit]
+ *   LC-004 (#143): fallback for entries with no `captured_at` field.
+ *   Given a learnings file label (e.g. "H-001.yml"), returns the
+ *   Unix MILLISECONDS of the file's first commit, or null if the
+ *   file is unknown to git. Without this, ~65% of OptionsFlow's
+ *   pre-LC-001 corpus lands in `unknown` because Schemas A/B don't
+ *   carry the field.
+ * @param {string} [opts.today] - 'YYYY-MM-DD' for deterministic testing
+ * @returns {{ entries: Array, summary: object }}
+ */
+function auditLearnings(opts = {}) {
+  const learningsFiles = opts.learningsFiles || [];
+  const skillNames = opts.skillNames || [];
+  const getSkillLastModifiedDays = typeof opts.getSkillLastModifiedDays === 'function'
+    ? opts.getSkillLastModifiedDays
+    : () => null;
+  // LC-004: optional injected git-log fallback
+  const getCapturedAtFromGit = typeof opts.getCapturedAtFromGit === 'function'
+    ? opts.getCapturedAtFromGit
+    : null;
+  const todayStr = opts.today || new Date().toISOString().slice(0, 10);
+  const todayMs = Date.parse(todayStr + 'T00:00:00Z');
+  const knownSkills = new Set(skillNames);
+
+  // ─── Pass 1: parse + collect raw entries (so we can do cross-entry analysis) ───
+  const rawEntries = [];
+  const parseErrors = [];
+  for (const lf of learningsFiles) {
+    if (!lf || !lf.content) continue;
+    const fileLabel = lf.fileLabel || '<unknown>';
+    let parsed;
+    try { parsed = yaml.load(lf.content); }
+    catch (e) {
+      parseErrors.push({ file: fileLabel, error: e.message });
+      continue;
+    }
+    if (!parsed || typeof parsed !== 'object') continue;
+
+    const fileCapturedAt = parsed.captured_at || null;
+    const fileStoryId = parsed.story_id || null;
+    const fileTopStatus = parsed.status || 'pending';
+
+    // Walk items in any of the 3 schemas (no eligibility filter — we audit
+    // EVERYTHING captured, including promoted/retracted).
+    const items = [];
+    if (Array.isArray(parsed)) {
+      for (const i of parsed) items.push({ item: i, schema: 'A' });
+    } else {
+      if (Array.isArray(parsed.enterprise_candidates)) {
+        for (const c of parsed.enterprise_candidates) items.push({ item: c, schema: 'B' });
+      }
+      if (Array.isArray(parsed.learnings)) {
+        for (const l of parsed.learnings) items.push({ item: l, schema: 'C' });
+      }
+    }
+
+    for (const { item, schema } of items) {
+      if (!item || typeof item !== 'object') continue;
+      const ref = item.referenced_skill || item.candidate_for || item.skill_update || null;
+      const refSkill = ref && typeof ref === 'string'
+        ? ref.replace(/^enterprise\/skills\//, '').replace(/\/SKILL\.md$/, '')
+        : null;
+      const capturedAt = item.captured_at || fileCapturedAt || null;
+      const itemStatus = item.status || fileTopStatus;
+      const category = (typeof item.category === 'string' && item.category) || null;
+      // Schema A/C carry full ids (e.g. "X-7-L1"); Schema B uses raw
+      // numeric ids that need the story prefix synthesized.
+      const synthId = item.id == null
+        ? null
+        : (schema === 'B' && fileStoryId)
+          ? `${fileStoryId}-${item.id}`
+          : String(item.id);
+
+      rawEntries.push({
+        file: fileLabel,
+        storyId: fileStoryId,
+        learningId: synthId,
+        schema,
+        category,
+        referencedSkill: refSkill,
+        capturedAt,
+        rawStatus: itemStatus,
+        enterpriseCandidate: item.enterprise_candidate === true,
+      });
+    }
+  }
+
+  // ─── Pass 2: build a per-skill index for contradiction detection ───
+  // Map: refSkill → array of { capturedAtMs, category }
+  const perSkill = new Map();
+  for (const e of rawEntries) {
+    if (!e.referencedSkill || !e.capturedAt) continue;
+    const ms = Date.parse(e.capturedAt);
+    if (Number.isNaN(ms)) continue;
+    if (!perSkill.has(e.referencedSkill)) perSkill.set(e.referencedSkill, []);
+    perSkill.get(e.referencedSkill).push({ capturedAtMs: ms, category: e.category });
+  }
+
+  // ─── Pass 3: classify each entry ───
+  const entries = [];
+  for (const e of rawEntries) {
+    const out = {
+      file: e.file,
+      storyId: e.storyId,
+      learningId: e.learningId,
+      category: e.category,
+      referencedSkill: e.referencedSkill,
+      capturedAt: e.capturedAt,
+      ageDays: null,
+      status: STATUS.UNKNOWN,
+      reason: '',
+    };
+
+    let capturedMs = e.capturedAt ? Date.parse(e.capturedAt) : NaN;
+
+    // LC-004 (#143): fallback for missing captured_at — query git for the
+    // file's first-commit timestamp. Resolves ~65% of OptionsFlow's
+    // pre-LC-001 corpus that lands in `unknown` because Schemas A/B
+    // don't carry the field.
+    if (Number.isNaN(capturedMs) && getCapturedAtFromGit && e.file) {
+      const fallbackMs = getCapturedAtFromGit(e.file);
+      if (typeof fallbackMs === 'number' && Number.isFinite(fallbackMs)) {
+        capturedMs = fallbackMs;
+        out.capturedAt = new Date(fallbackMs).toISOString();
+        out.capturedAtSource = 'git-fallback';   // surfaces in JSON output
+      }
+    }
+
+    if (Number.isNaN(capturedMs)) {
+      out.reason = 'no captured_at (and git-fallback returned null or absent)';
+      entries.push(out);
+      continue;
+    }
+    out.ageDays = Math.max(0, Math.round((todayMs - capturedMs) / 86400000));
+
+    // 1. Promoted → incorporated
+    if (e.rawStatus === 'promoted') {
+      out.status = STATUS.INCORPORATED;
+      out.reason = 'status: promoted';
+      entries.push(out);
+      continue;
+    }
+
+    // 2. Skill touched after capture → incorporated
+    if (e.referencedSkill && knownSkills.has(e.referencedSkill)) {
+      const skillAge = getSkillLastModifiedDays(e.referencedSkill);
+      if (typeof skillAge === 'number' && skillAge < out.ageDays) {
+        out.status = STATUS.INCORPORATED;
+        out.reason = `skill "${e.referencedSkill}" modified ${skillAge}d ago, after capture (${out.ageDays}d ago)`;
+        entries.push(out);
+        continue;
+      }
+    }
+
+    // 3. Contradiction: a LATER learning with the same skill has category=exception
+    if (e.referencedSkill && e.category !== LEARNING_CATEGORIES.EXCEPTION_WITH_RATIONALE) {
+      const peers = perSkill.get(e.referencedSkill) || [];
+      const contradicting = peers.find(p =>
+        p.capturedAtMs > capturedMs &&
+        p.category === LEARNING_CATEGORIES.EXCEPTION_WITH_RATIONALE
+      );
+      if (contradicting) {
+        out.status = STATUS.CONTRADICTED;
+        out.reason = `later exception-with-rationale learning targets "${e.referencedSkill}"`;
+        entries.push(out);
+        continue;
+      }
+    }
+
+    // 4. Age-based bucketing
+    if (out.ageDays > STALE_THRESHOLD_DAYS) {
+      out.status = STATUS.STALE;
+      out.reason = `age ${out.ageDays}d > ${STALE_THRESHOLD_DAYS}d, not incorporated`;
+    } else if (out.ageDays > FRESH_THRESHOLD_DAYS) {
+      out.status = STATUS.AGING;
+      out.reason = `age ${out.ageDays}d > ${FRESH_THRESHOLD_DAYS}d, not incorporated`;
+    } else {
+      out.status = STATUS.FRESH;
+      out.reason = `age ${out.ageDays}d ≤ ${FRESH_THRESHOLD_DAYS}d`;
+    }
+    entries.push(out);
+  }
+
+  // ─── Summary ───
+  const counts = { fresh: 0, aging: 0, stale: 0, incorporated: 0, contradicted: 0, unknown: 0 };
+  for (const e of entries) counts[e.status] = (counts[e.status] || 0) + 1;
+
+  return {
+    entries,
+    summary: {
+      total: entries.length,
+      ...counts,
+      parse_errors: parseErrors.length,
+      today: todayStr,
+    },
+    parseErrors,
+  };
+}
+
+module.exports = {
+  auditLearnings,
+  STATUS,
+  FRESH_THRESHOLD_DAYS,
+  STALE_THRESHOLD_DAYS,
+};