@zuzuucodes/cli 1.0.0

package/zuzuu/commands/migrate.mjs

@@ -0,0 +1,125 @@
+// zuzuu/commands/migrate.mjs
+// `zuzuu migrate` — one-time proposal schema migrator (WS2-T5).
+//
+// Tidies on-disk legacy Knowledge proposals from the old {candidate, er} shape
+// to the unified spine shape {payload, analysis, faculty}.  The spine already
+// dual-reads both formats; this migrator exists so on-disk records are clean.
+//
+// Pure core:   migrateProposals(agentDir) → { scanned, migrated, skipped }
+// CLI surface: migrate(args) — resolves agentDir, runs core, prints summary.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from '../store.mjs';
+import { proposalsDir, archiveDir } from '../faculty/contract.mjs';
+
+// ---------------------------------------------------------------------------
+// pure core — testable without process.*
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether a parsed JSON record is already in the new shape.
+ * A record is "new" when it has `payload` AND `faculty` set.
+ * If it only has `candidate` and/or lacks `faculty` it is legacy.
+ */
+function isLegacy(rec) {
+  if (!rec || typeof rec !== 'object') return false;
+  // already migrated: has payload and faculty
+  if (rec.payload !== undefined && rec.faculty !== undefined) return false;
+  // legacy if it has candidate or er keys, or is simply missing faculty/payload
+  return rec.candidate !== undefined || rec.er !== undefined || rec.faculty === undefined;
+}
+
+/**
+ * Convert a legacy record to the new unified shape.
+ * Returns the migrated record (caller writes it back).
+ */
+function migrateRecord(rec) {
+  const out = { ...rec };
+
+  // payload = candidate (drop candidate)
+  if (out.candidate !== undefined) {
+    if (out.payload === undefined) out.payload = out.candidate;
+    delete out.candidate;
+  }
+
+  // analysis = { er } (drop er)
+  if (out.er !== undefined) {
+    if (out.analysis === undefined) out.analysis = { er: out.er };
+    delete out.er;
+  }
+
+  // faculty defaults to 'knowledge' (only knowledge proposals exist pre-spine)
+  if (!out.faculty) out.faculty = 'knowledge';
+
+  return out;
+}
+
+/**
+ * Scan one directory of *.json files and migrate legacy records in-place.
+ * Fail-soft: bad JSON files are counted as skipped and never throw.
+ * Returns { migrated, scanned, skipped } for this directory.
+ */
+function migrateDir(dir) {
+  if (!existsSync(dir)) return { migrated: 0, scanned: 0, skipped: 0 };
+
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  let migrated = 0;
+  let skipped = 0;
+
+  for (const file of files) {
+    const fpath = join(dir, file);
+    let rec;
+    try {
+      rec = JSON.parse(readFileSync(fpath, 'utf8'));
+    } catch {
+      skipped++;
+      continue;
+    }
+
+    if (!isLegacy(rec)) {
+      skipped++;
+      continue;
+    }
+
+    try {
+      const migrated_rec = migrateRecord(rec);
+      writeFileSync(fpath, JSON.stringify(migrated_rec, null, 2) + '\n');
+      migrated++;
+    } catch {
+      skipped++;
+    }
+  }
+
+  return { migrated, scanned: files.length, skipped };
+}
+
+/**
+ * Scan both pending and archived Knowledge proposals.
+ * Returns { scanned, migrated, skipped }.
+ */
+export function migrateProposals(agentDir) {
+  const pending = migrateDir(proposalsDir(agentDir, 'knowledge'));
+  const archived = migrateDir(archiveDir(agentDir, 'knowledge'));
+
+  return {
+    scanned: pending.scanned + archived.scanned,
+    migrated: pending.migrated + archived.migrated,
+    skipped: pending.skipped + archived.skipped,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI surface
+// ---------------------------------------------------------------------------
+
+export function migrate() {
+  const agentDir = paths().dir;
+  const { scanned, migrated, skipped } = migrateProposals(agentDir);
+  console.log(`migrate: scanned ${scanned} proposal(s) — migrated ${migrated}, skipped ${skipped}`);
+  if (migrated > 0) {
+    console.log('  legacy candidate/er keys rewritten to payload/analysis.er + faculty:knowledge');
+  } else {
+    console.log('  nothing to migrate (all records already in new shape)');
+  }
+}

package/zuzuu/commands/review.mjs

@@ -0,0 +1,299 @@
+// `zuzuu review` — the human gate, as a daily ritual. Walks pending proposals
+// one-by-one: shows the candidate, its evidence, and the ER verdict (with the
+// matched item when enrich/duplicate) → y approve · n reject · e edit · s skip ·
+// q quit. Works piped (answers on stdin) — that's also how it's tested.
+// Non-interactive surface: `zuzuu proposals list|show|approve|reject`.
+
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { paths, readIndex } from '../store.mjs';
+import { processInbox } from '../knowledge/inbox.mjs';
+import { getProposal, proposalsDir } from '../knowledge/proposals.mjs';
+import { readItem } from '../knowledge/items.mjs';
+import * as registry from '../faculty/registry.mjs';
+import * as gate from '../faculty/gate.mjs';
+import { listProposals as spineListProposals } from '../faculty/proposal.mjs';
+import { mintGeneration, activeGeneration } from '../faculty/generation.mjs';
+import { rank } from '../eval/rank.mjs';
+import { getScorer, mechanicalScore } from '../eval/score.mjs';
+import { evalLine } from './eval.mjs';
+import '../knowledge/adapter.mjs';    // self-registers the 'knowledge' adapter
+import '../actions/adapter.mjs';      // self-registers the 'actions' adapter
+import '../guardrails/adapter.mjs';   // self-registers the 'guardrails' adapter
+import '../instructions/adapter.mjs'; // self-registers the 'instructions' adapter
+import '../memory/adapter.mjs';       // self-registers the 'memory' adapter
+
+/** Build sessionMtimes map from the sessions index — best-effort, fail-open. */
+function buildSessionMtimes() {
+  try {
+    const idx = readIndex();
+    const map = {};
+    for (const s of idx.sessions ?? []) {
+      if (!s.id) continue;
+      const ms = s.startedAt ? Date.parse(s.startedAt) : 0;
+      if (!isNaN(ms) && ms > 0) map[s.id] = ms;
+    }
+    return map;
+  } catch {
+    return {};
+  }
+}
+
+// Review walks faculties in a fixed order so piped sessions are deterministic
+// (the combo smoke test feeds one stdin across the actions pass then knowledge).
+const REVIEW_ORDER = ['actions', 'knowledge', 'guardrails', 'instructions', 'memory'];
+
+/** Ordered list of adapters that have pending proposals to review. */
+function pendingByFaculty(agentDir) {
+  const adapters = registry.all();
+  const seen = new Set();
+  const ordered = [];
+  for (const name of REVIEW_ORDER) {
+    const a = adapters.find((x) => x.name === name);
+    if (a) { ordered.push(a); seen.add(name); }
+  }
+  for (const a of adapters) if (!seen.has(a.name)) ordered.push(a);
+  const sessionMtimes = buildSessionMtimes();
+  const now = Date.now();
+  const scorer = getScorer();
+  const out = [];
+  for (const a of ordered) {
+    let proposals = facultyPending(agentDir, a);
+    if (!proposals.length) continue;
+    // Rank proposals highest-score-first (display only — never changes approval/mint).
+    const ranked = rank(proposals, scorer, { now, sessionMtimes });
+    proposals = ranked.map((r) => r.proposal);
+    out.push({ adapter: a, proposals });
+  }
+  return out;
+}
+
+/** Pending proposals for one adapter (dir-shaped adapters override listProposals). */
+function facultyPending(agentDir, a) {
+  if (typeof a.listProposals === 'function') return a.listProposals(agentDir);
+  // JSON-record faculties: read via the spine (records carry both the spine shape
+  // and the legacy candidate/er keys the knowledge card renders from).
+  return spineListProposals(agentDir, a.name);
+}
+
+function card(agentDir, p, i, total, scoreResult) {
+  const lines = [];
+  lines.push(`\n━━ proposal ${i + 1}/${total} ── ${p.id} ── ${p.kind} ── source: ${p.source ?? '-'} ━━`);
+  if (p.kind === 'registry') {
+    lines.push(`  register ${p.registry.slice(0, -1)}: '${p.key}'  (seen ${p.evidence?.occurrences}× in candidates)`);
+  } else {
+    const c = p.candidate;
+    lines.push(`  ${c.type}: ${c.body?.slice(0, 100).replace(/\n/g, ' ')}`);
+    for (const [k, v] of Object.entries(c.attributes ?? {})) lines.push(`    · ${k} = ${v}`);
+    for (const r of c.relations ?? []) lines.push(`    → ${r.type} ${r.target}`);
+    const ev = p.evidence ?? {};
+    if (Object.keys(ev).length) lines.push(`  evidence: ${Object.entries(ev).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join('  ')}`);
+    const er = p.er ?? {};
+    lines.push(`  er: ${er.verdict}${er.match ? ` → ${er.match}` : ''}  (${(er.confidence ?? 0).toFixed(2)} · ${er.reason ?? ''})`);
+    if (er.match) {
+      const m = readItem(agentDir, er.match);
+      if (m) lines.push(`  existing: ${m.body.slice(0, 80).replace(/\n/g, ' ')}`);
+    }
+  }
+  // Eval line — always shown; scoreResult computed by caller from ranked array.
+  if (scoreResult) lines.push(`  ${evalLine(scoreResult)}`);
+  return lines.join('\n');
+}
+
+/**
+ * Pure: the graduation ceremony block shown when a generation is minted.
+ * @param {string} genId
+ * @param {string[]} approvedIds
+ * @param {Object<string,number>} byFaculty  faculty → approval count
+ * @returns {string}
+ */
+export function ceremonyBlock(genId, approvedIds, byFaculty) {
+  const n = approvedIds.length;
+  const breakdown = Object.entries(byFaculty)
+    .filter(([, c]) => c > 0)
+    .map(([f, c]) => `${f} +${c}`)
+    .join(' · ');
+  return [
+    `\n✓ generation ${genId} minted from ${n} approval(s)${breakdown ? ` — ${breakdown}` : ''}.`,
+    `  inspect: zuzuu generation show ${genId}   ·   roll back: zuzuu generation rollback ${genId}`,
+  ].join('\n');
+}
+
+export async function review() {
+  const agentDir = paths().dir;
+  const inbox = processInbox(agentDir);
+  if (inbox.processed) console.log(`(processed ${inbox.processed} inbox candidate(s) → proposals)`);
+  const groups = pendingByFaculty(agentDir);
+  if (!groups.length) {
+    console.log('nothing to review — knowledge and actions are current');
+    return;
+  }
+  // Line-queue instead of rl.question: with piped stdin, lines that arrive
+  // between questions would otherwise be dropped (the readline-pipe race —
+  // caught by the first smoke test). EOF answers 'q' (graceful quit).
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const queued = [];
+  let waiter = null;
+  let closed = false;
+  rl.on('line', (l) => {
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w(l);
+    } else queued.push(l);
+  });
+  rl.on('close', () => {
+    closed = true;
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w('q');
+    }
+  });
+  const ask = async (q) => {
+    process.stdout.write(q);
+    if (queued.length) return queued.shift();
+    if (closed) return 'q';
+    return new Promise((res) => {
+      waiter = res;
+    });
+  };
+
+  const approvedIds = [];
+  const approvedByFaculty = {}; // faculty → count, for the graduation ceremony
+  let approved = 0, rejected = 0, skipped = 0;
+  let totalLeft = groups.reduce((n, g) => n + g.proposals.length, 0);
+  const sessionMtimes = buildSessionMtimes();
+  const now = Date.now();
+  const scorer = getScorer();
+  // One loop over faculties with pending proposals (adapter-driven, WS2-T3).
+  for (const { adapter, proposals } of groups) {
+    const isActions = adapter.name === 'actions';
+    for (let i = 0; i < proposals.length; i++) {
+      const p = proposals[i];
+      // Compute scoreResult for this proposal (fail-open).
+      let scoreResult = null;
+      try { scoreResult = scorer(p, { now, sessionMtimes }); } catch { /* fail-open */ }
+      // Card: knowledge keeps its rich card (ER + existing-item lookup); other
+      // faculties render through the adapter contract.
+      if (adapter.name === 'knowledge') console.log(card(agentDir, p, i, proposals.length, scoreResult));
+      else {
+        const r = adapter.render(p);
+        const [head, ...rest] = r.card.split('\n');
+        console.log(`\n━━ ${adapter.name} ${i + 1}/${proposals.length} ── ${head} ━━`);
+        if (rest.length) console.log(rest.join('\n'));
+        if (scoreResult) console.log(`  ${evalLine(scoreResult)}`);
+      }
+      const prompt = isActions
+        ? '  [y]activate [n]reject [s]kip [q]uit > '
+        : '  [y]approve [n]reject [e]dit [s]kip [q]uit > ';
+      let acted = false;
+      while (!acted) {
+        const a = (await ask(prompt)).trim().toLowerCase();
+        if (a === 'y') {
+          const r = gate.approve(agentDir, adapter.name, p.id);
+          if (isActions) console.log(r.ok ? '  ✓ activated' : `  ✗ ${(r.errors ?? [r.action]).join('; ')}`);
+          else { console.log(r.ok ? `  ✓ ${r.action}` : `  ✗ ${(r.errors ?? [r.action]).join('; ')}`); for (const w of r.warnings ?? []) console.log(`  ⚠ ${w}`); }
+          if (r.ok) { approvedIds.push(p.id); approvedByFaculty[adapter.name] = (approvedByFaculty[adapter.name] ?? 0) + 1; }
+          approved++; totalLeft--; acted = true;
+        } else if (a === 'n') {
+          const reason = isActions ? '' : (await ask('  reason (optional) > ')).trim();
+          gate.reject(agentDir, adapter.name, p.id, reason);
+          console.log('  ✗ rejected');
+          rejected++; totalLeft--; acted = true;
+        } else if (a === 'e' && !isActions) {
+          const editor = process.env.EDITOR || 'vi';
+          spawnSync(editor, [join(proposalsDir(agentDir), `${p.id}.json`)], { stdio: 'inherit' });
+          const fresh = getProposal(agentDir, p.id);
+          if (fresh) {
+            proposals[i] = fresh;
+            let freshScore = null;
+            try { freshScore = scorer(fresh, { now, sessionMtimes }); } catch { /* fail-open */ }
+            console.log(card(agentDir, fresh, i, proposals.length, freshScore));
+          }
+        } else if (a === 's') {
+          skipped++; totalLeft--; acted = true;
+        } else if (a === 'q' || a === '') {
+          rl.close();
+          console.log(`\nreview: ${approved} approved · ${rejected} rejected · ${skipped} skipped · ${totalLeft} left`);
+          if (approvedIds.length > 0) {
+            const gen = mintGeneration(agentDir, { forkedFrom: activeGeneration(agentDir), mintedFrom: approvedIds });
+            console.log(ceremonyBlock(gen.id, approvedIds, approvedByFaculty));
+          }
+          return;
+        }
+      }
+    }
+  }
+  rl.close();
+  console.log(`\nreview complete: ${approved} approved · ${rejected} rejected · ${skipped} skipped`);
+  if (approvedIds.length > 0) {
+    const gen = mintGeneration(agentDir, { forkedFrom: activeGeneration(agentDir), mintedFrom: approvedIds });
+    console.log(ceremonyBlock(gen.id, approvedIds, approvedByFaculty));
+  }
+}
+
+/**
+ * Resolve which faculty owns a given proposal id (used when --faculty is omitted).
+ * Defaults to 'knowledge' (the historical path) when no other faculty claims it.
+ */
+function facultyOf(agentDir, id, only) {
+  if (only) return only;
+  for (const { adapter, proposals } of pendingByFaculty(agentDir)) {
+    if (proposals.some((p) => p.id === id)) return adapter.name;
+  }
+  return 'knowledge';
+}
+
+/** Non-interactive: zuzuu proposals list|show <id>|approve <id>|reject <id> [--reason r] [--faculty f] */
+export function proposals(args) {
+  const agentDir = paths().dir;
+  const sub = args._[0] || 'list';
+  const only = args.faculty; // optional filter; default = all
+  if (sub === 'list') {
+    const inbox = processInbox(agentDir);
+    if (inbox.processed) console.log(`(processed ${inbox.processed} inbox candidate(s))`);
+    const groups = pendingByFaculty(agentDir).filter((g) => !only || g.adapter.name === only);
+    const any = groups.some((g) => g.proposals.length);
+    if (!any) return console.log('no pending proposals');
+    for (const { adapter, proposals } of groups) {
+      for (const p of proposals) {
+        // knowledge keeps its historical one-liner; other faculties use adapter.render
+        if (adapter.name === 'knowledge') {
+          const what = p.kind === 'registry'
+            ? `register ${p.registry.slice(0, -1)} '${p.key}'`
+            : `${p.candidate.type}: ${p.candidate.body?.slice(0, 60).replace(/\n/g, ' ')}`;
+          console.log(`  ${p.id}  [${p.er?.verdict ?? p.kind}]  ${what}`);
+        } else {
+          console.log(`  ${adapter.render(p).line}`);
+        }
+      }
+    }
+    return;
+  }
+  const id = args._[1];
+  if (sub === 'show') {
+    const faculty = facultyOf(agentDir, id, only);
+    const a = registry.get(faculty);
+    const p = (a && typeof a.getProposal === 'function') ? a.getProposal(agentDir, id) : getProposal(agentDir, id);
+    if (!p) return console.error('not found');
+    console.log(JSON.stringify(p, null, 2));
+    return;
+  }
+  if (sub === 'approve') {
+    const faculty = facultyOf(agentDir, id, only);
+    const r = gate.approve(agentDir, faculty, id);
+    console.log(r.ok ? `✓ ${r.action}` : `✗ ${(r.errors ?? [r.action]).join('; ')}`);
+    for (const w of r.warnings ?? []) console.log(`⚠ ${w}`);
+    process.exit(r.ok ? 0 : 1);
+  }
+  if (sub === 'reject') {
+    const faculty = facultyOf(agentDir, id, only);
+    const r = gate.reject(agentDir, faculty, id, args.reason || '');
+    console.log(r.ok ? '✓ rejected' : '✗ not found');
+    process.exit(r.ok ? 0 : 1);
+  }
+  console.error('usage: zuzuu proposals list|show <id>|approve <id>|reject <id> [--reason r] [--faculty f]');
+  process.exit(1);
+}

package/zuzuu/commands/status.mjs

@@ -0,0 +1,82 @@
+// `zuzuu status` — detected hosts + recorded sessions (the git-native index).
+
+import { existsSync } from 'node:fs';
+import { detected } from '../../experiments/experiment-1-trace-capture/adapters/registry.mjs';
+import { readIndex, paths } from '../store.mjs';
+import { FACULTIES } from '../faculty/contract.mjs';
+import { listProposals } from '../faculty/proposal.mjs';
+import { activeGeneration as activeGenerationFn } from '../faculty/generation.mjs';
+import { detectDrift } from './doctor.mjs';
+
+const fmtDur = (ms) => (ms < 60_000 ? `${(ms / 1000).toFixed(0)}s` : `${(ms / 60_000).toFixed(1)}m`);
+
+/** Pure: structured status for a faculty home (the zuzuu-web /status source). Fail-soft per field. */
+export function statusData(agentDir) {
+  let active = null, drift = { dirty: false, items: [] };
+  const pending = {};
+  try { active = activeGenerationFn(agentDir); } catch { active = null; }
+  for (const f of FACULTIES) {
+    try { pending[f] = listProposals(agentDir, f).length; } catch { pending[f] = 0; }
+  }
+  try {
+    const d = detectDrift(agentDir);
+    const items = Array.isArray(d?.drifted) ? d.drifted : [];
+    drift = { dirty: items.length > 0, items };
+  } catch { /* fail-soft */ }
+  return { home: existsSync(agentDir), activeGeneration: active, pending, drift };
+}
+
+/**
+ * Pure: the faculties graduation line for `zuzuu status`. Fail-soft — any error in
+ * a sub-read degrades to a safe default rather than throwing.
+ * @param {string} agentDir
+ * @returns {string}
+ */
+export function facultiesLine(agentDir) {
+  let gen = null, pending = 0, drifted = false;
+  try { gen = activeGenerationFn(agentDir); } catch { /* fail-soft */ }
+  try {
+    for (const f of FACULTIES) {
+      try { pending += listProposals(agentDir, f).length; } catch { /* per-faculty fail-soft */ }
+    }
+  } catch { /* fail-soft */ }
+  try {
+    const d = detectDrift(agentDir);
+    drifted = Array.isArray(d?.drifted) && d.drifted.length > 0;
+  } catch { /* fail-soft */ }
+  let line = `faculties: ${gen || 'no generation yet'} · ${pending} pending review`;
+  if (drifted) line += ' · ⚠ drift (run zuzuu doctor)';
+  return line;
+}
+
+export function status(args = {}) {
+  if (args.json) { console.log(JSON.stringify(statusData(paths().dir))); return; }
+  const { sessions } = readIndex();
+  console.log(`this project — recorded sessions (agent/sessions.json): ${sessions.length}`);
+  if (!sessions.length) {
+    console.log('  none yet — run `zuzuu capture`, or just start your agent (live capture)');
+  } else {
+    console.log('');
+    console.log('  STATUS     HOST          DUR     GIT       T/TOOLS/ERR  SESSION');
+    for (const s of sessions.slice(0, 12)) {
+      const dur = fmtDur(s.durationMs || 0).padStart(6);
+      const git = (s.git?.commit ? s.git.commit.slice(0, 7) : '-------').padEnd(8);
+      const cnt = `${s.counts?.turns ?? 0}/${s.counts?.tools ?? 0}/${s.counts?.errors ?? 0}`.padEnd(11);
+      console.log(`  ${s.status.padEnd(10)} ${s.host.padEnd(13)} ${dur}  ${git}  ${cnt}  ${s.id.slice(0, 8)}`);
+    }
+    if (sessions.length > 12) console.log(`  … and ${sessions.length - 12} more`);
+  }
+
+  try { console.log('\n' + facultiesLine(paths().dir)); } catch { /* fail-soft */ }
+
+  const hosts = detected();
+  console.log('\nhosts detected on this machine:');
+  if (!hosts.length) {
+    console.log('  (none — no supported agent data found)');
+  } else {
+    for (const a of hosts) {
+      const n = a.listSessions({ cwd: process.cwd() }).length;
+      console.log(`  ● ${a.name}  (${n} session${n === 1 ? '' : 's'} available)`);
+    }
+  }
+}

package/zuzuu/commands/trace.mjs

@@ -0,0 +1,19 @@
+// `zuzuu trace [--last | <file>]` — print the span tree of a captured trace.
+
+import { existsSync } from 'node:fs';
+import { loadSpans, renderTree } from '../../experiments/experiment-1-trace-capture/core/render.mjs';
+import { lastTrace } from '../store.mjs';
+
+export function trace(args) {
+  let file = args._[0];
+  if (args.last || !file) file = lastTrace();
+  if (!file) {
+    console.error('no trace found — run `zuzuu capture` first, or pass a file path');
+    process.exit(1);
+  }
+  if (!existsSync(file)) {
+    console.error(`no such trace file: ${file}`);
+    process.exit(1);
+  }
+  console.log(renderTree(loadSpans(file)));
+}

package/zuzuu/digest.mjs

@@ -0,0 +1,149 @@
+// zuzuu/digest.mjs
+// The grounding digest — a pure, deterministic, zero-network, no-model brief of
+// the faculty home, injected at session start. Returns { text, sections }.
+// I/O-free: callers (the CLI + the SessionStart hook) handle output. Every
+// reader is wrapped so a single broken faculty never sinks the whole digest.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { allItems } from './knowledge/items.mjs';
+import { listProposals } from './knowledge/proposals.mjs';
+import { loadRules } from './guardrails.mjs';
+import { allActions } from './actions/manifest.mjs';
+
+const PLACEHOLDER_MARK = '<!-- Fill in:';
+
+/** Read instructions/project.md; classify empty vs steering text. */
+function readInstructions(agentDir) {
+  const path = join(agentDir, 'instructions', 'project.md');
+  let raw = '';
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch { /* missing or unreadable → treat as empty */ }
+  const stripped = raw.replace(/^#.*$/gm, '').trim();
+  const empty = !stripped || raw.includes(PLACEHOLDER_MARK);
+  return { empty, text: empty ? '' : raw.trim() };
+}
+
+const INTERVIEW = [
+  'Project steering is empty. Before substantive work, interview your human',
+  '(what is this project, its conventions, its priorities), draft',
+  'agent/instructions/project.md from their answers, and get their approval.',
+].join(' ');
+
+function knowledgeSection(agentDir, limit) {
+  try {
+    const { items } = allItems(agentDir);
+    const ranked = [...items]
+      .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))
+      .slice(0, limit);
+    return { count: items.length, shown: ranked.map((i) => ({ id: i.id, type: i.type, body: i.body })) };
+  } catch {
+    return { count: 0, shown: [] };
+  }
+}
+
+function proposalsSection(agentDir) {
+  try {
+    // count only pending — defensive if listProposals ever returns archived too
+    const pending = listProposals(agentDir).filter((p) => p.status === 'pending');
+    return { pending: pending.length };
+  } catch {
+    return { pending: 0 };
+  }
+}
+
+function actionsSection(agentDir, limit) {
+  try {
+    const list = allActions(agentDir);
+    return { count: list.length, shown: list.slice(0, limit).map((a) => ({ slug: a.slug, kind: a.kind, promptSnippet: a.promptSnippet })) };
+  } catch {
+    return { count: 0, shown: [] };
+  }
+}
+
+function guardrailsSection(agentDir) {
+  try {
+    const loaded = loadRules(join(agentDir, 'guardrails', 'rules.json'));
+    return { ok: loaded.ok, count: loaded.ok ? loaded.rules.length : 0 };
+  } catch {
+    return { ok: false, count: 0 };
+  }
+}
+
+/**
+ * Compute the digest for a faculty home.
+ * @param {string} agentDir  path to the agent/ directory
+ * @param {{ knowledgeLimit?: number, budget?: number }} options
+ * @returns {{ text: string, sections: object }}
+ */
+export function computeDigest(agentDir, { knowledgeLimit = 5, budget = 1500 } = {}) {
+  const charBudget = budget * 4;
+  const sections = {};
+  const lines = ['# zuzuu faculty digest', ''];
+
+  const instr = readInstructions(agentDir);
+  sections.instructions = instr;
+  lines.push('## Instructions');
+  lines.push(instr.empty ? INTERVIEW : instr.text);
+  lines.push('');
+
+  const knowledge = knowledgeSection(agentDir, knowledgeLimit);
+  lines.push('## Knowledge');
+  if (!knowledge.count) {
+    lines.push('(no items yet — propose facts to knowledge/inbox/)');
+    sections.knowledge = { ...knowledge, renderedCount: 0 };
+  } else {
+    lines.push(`${knowledge.count} item(s); most recent:`);
+    let shown = 0;
+    for (const it of knowledge.shown) {
+      const line = `- ${it.id} · ${it.type} · ${it.body.split('\n')[0].slice(0, 80)}`;
+      // join is O(items²) but trivial: once-per-session, knowledgeLimit default 5
+      if (lines.join('\n').length + line.length > charBudget && shown > 0) break;
+      lines.push(line);
+      shown++;
+    }
+    const dropped = knowledge.count - shown;
+    if (dropped > 0) lines.push(`- … (${dropped} more — \`zuzuu recall\`)`);
+    // `shown` = items actually rendered (after budget); `count` = total available
+    sections.knowledge = { ...knowledge, shown: knowledge.shown.slice(0, shown), renderedCount: shown };
+  }
+  lines.push('');
+
+  const actions = actionsSection(agentDir, knowledgeLimit);
+  sections.actions = actions;
+  if (actions.count) {
+    lines.push('## Actions');
+    lines.push(`${actions.count} available; run with \`zuzuu act <slug>\`:`);
+    let shownA = 0;
+    for (const a of actions.shown) {
+      const line = `- ${a.slug} · ${a.promptSnippet}`;
+      if (lines.join('\n').length + line.length > charBudget && shownA > 0) break;
+      lines.push(line);
+      shownA++;
+    }
+    const droppedA = actions.count - shownA;
+    if (droppedA > 0) lines.push(`- … (${droppedA} more — \`zuzuu act list\`)`);
+    lines.push('');
+    // mirror the Knowledge contract: shown reflects what actually rendered
+    sections.actions = { ...actions, shown: actions.shown.slice(0, shownA), renderedCount: shownA };
+  } else {
+    sections.actions = { ...actions, renderedCount: 0 };
+  }
+
+  const proposals = proposalsSection(agentDir);
+  sections.proposals = proposals;
+  if (proposals.pending > 0) {
+    lines.push('## Proposals');
+    lines.push(`${proposals.pending} proposal(s) await your approval — run \`zuzuu review\`; approving mints a generation (your checkpoint).`);
+    lines.push('');
+  }
+
+  const guardrails = guardrailsSection(agentDir);
+  sections.guardrails = guardrails;
+  lines.push('## Guardrails');
+  lines.push(guardrails.count ? `${guardrails.count} rule(s) — the enforced gate is on; refusals are policy.` : 'no rules configured.');
+  lines.push('');
+
+  return { text: lines.join('\n').trimEnd() + '\n', sections };
+}