@zuzuucodes/cli 1.4.0 → 1.6.0

package/zuzuu/commands/review.mjs

@@ -1,105 +1,22 @@
-// `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`.
+// `zuzuu review` — the human gate, as a daily ritual (the interactive ceremony).
+// 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. The non-interactive surface lives in proposals.mjs.
 
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
-import { paths, readIndex } from '../store.mjs';
+import { paths } from '../core/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 { pendingByFaculty, buildSessionMtimes } from '../faculty/pending.mjs';
+import { knowledgeCard } from '../faculty/render.mjs';
+import { activeGeneration } from '../faculty/generation/read.mjs';
+import { mintGeneration } from '../faculty/generation/write.mjs';
+import { getScorer } 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.
@@ -177,7 +94,7 @@ export async function review() {
       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));
+      if (adapter.name === 'knowledge') console.log(knowledgeCard(agentDir, p, i, proposals.length, scoreResult));
       else {
         const r = adapter.render(p);
         const [head, ...rest] = r.card.split('\n');
@@ -210,7 +127,7 @@ export async function review() {
             proposals[i] = fresh;
             let freshScore = null;
             try { freshScore = scorer(fresh, { now, sessionMtimes }); } catch { /* fail-open */ }
-            console.log(card(agentDir, fresh, i, proposals.length, freshScore));
+            console.log(knowledgeCard(agentDir, fresh, i, proposals.length, freshScore));
           }
         } else if (a === 's') {
           skipped++; totalLeft--; acted = true;
@@ -233,134 +150,3 @@ export async function review() {
     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';
-}
-
-/**
- * Pure: the structured object for `proposals approve --json`.
- * Calls gate.approve and returns the result object the branch prints.
- * @param {string} agentDir
- * @param {string} id
- * @param {string} faculty
- * @returns {object}  the gate result (contains ok, action, etc.)
- */
-export function approveData(agentDir, id, faculty) {
-  return gate.approve(agentDir, faculty, id);
-}
-
-/**
- * Pure: the structured object for `proposals reject --json`.
- * Calls gate.reject and returns the result object the branch prints.
- * @param {string} agentDir
- * @param {string} id
- * @param {string} faculty
- * @param {string} [reason]
- * @returns {object}  { ok, id, ... }
- */
-export function rejectData(agentDir, id, faculty, reason = '') {
-  const r = gate.reject(agentDir, faculty, id, reason);
-  return { ...r, id };
-}
-
-/**
- * Pure: list pending proposals as structured data — the zuzuu-web /proposals source.
- * @param {string} agentDir
- * @param {string} [only]  optional faculty filter
- * @returns {{ pending: Array<{id, faculty, title}> }}
- */
-export function proposalsListData(agentDir, only) {
-  const groups = pendingByFaculty(agentDir).filter((g) => !only || g.adapter.name === only);
-  const pending = [];
-  for (const { adapter, proposals } of groups) {
-    for (const p of proposals) {
-      // derive a human title the same way the table does
-      let title;
-      if (adapter.name === 'knowledge') {
-        title = p.kind === 'registry'
-          ? `register ${p.registry?.slice(0, -1) ?? ''} '${p.key ?? ''}'`
-          : (p.candidate?.body ?? p.payload?.body ?? p.id)?.slice(0, 80);
-      } else {
-        title = p.title ?? adapter.render(p).line;
-      }
-      pending.push({ id: p.id, faculty: adapter.name, title: title ?? p.id });
-    }
-  }
-  return { pending };
-}
-
-/** 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') {
-    if (args.json) {
-      processInbox(agentDir);  // promote plain-text inbox candidates, same as text path
-      const d = proposalsListData(agentDir, only);
-      console.log(JSON.stringify(d));
-      return;
-    }
-    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');
-    // show always prints JSON (both with and without --json flag)
-    console.log(JSON.stringify(p, null, 2));
-    return;
-  }
-  if (sub === 'approve') {
-    const faculty = facultyOf(agentDir, id, only);
-    const r = approveData(agentDir, id, faculty);
-    if (args.json) {
-      console.log(JSON.stringify(r));
-    } else {
-      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 = rejectData(agentDir, id, faculty, args.reason || '');
-    if (args.json) {
-      console.log(JSON.stringify(r));
-    } else {
-      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/session.mjs

@@ -8,7 +8,8 @@
 // All git mutation lives in session-git.mjs (fail-soft, never throws); this is
 // the thin print layer (xxxData pattern — pure data fns + --json everywhere).
 
-import { sessionStatus, closeSession, continueSession, discardSession } from '../session-git.mjs';
+import { sessionStatus, closeSession, continueSession, discardSession } from '../sessions/session-git.mjs';
+import { sessionInspect } from './sessions.mjs';
 
 /** Pure: structured session-git state (the leftover detector included). */
 export function sessionStatusData(cwd = process.cwd()) {
@@ -98,6 +99,11 @@ export function session(args = {}) {
     process.exit(1);
   }
 
-  console.error(`unknown: zuzuu session ${sub}\nusage: zuzuu session [status|merge [--title t]|continue|discard --yes]`);
+  if (sub === 'inspect') {
+    sessionInspect(args);
+    return;
+  }
+
+  console.error(`unknown: zuzuu session ${sub}\nusage: zuzuu session [status|merge [--title t]|continue|discard --yes|inspect <id>]`);
   process.exit(1);
 }

package/zuzuu/commands/sessions.mjs

@@ -0,0 +1,159 @@
+// zuzuu/commands/sessions.mjs — the sessions observability surface (overhaul
+// Part A, 2026-06-13).
+//
+//   zuzuu sessions [--json]              recorded sessions w/ state labels
+//   zuzuu session inspect <id> [--json]  one session: trace summary +
+//                                        per-faculty mined signals
+//
+// inspect = { session, trace: {spans, tools, duration}, signals: {<faculty>:
+// counts} } — the span count reads the stored OTLP blob; the signals re-mine
+// the HOST transcript through the proven adapters' mineSignals and map the
+// superset onto faculties via each module's sessionSignals hook. Fail-soft
+// throughout: a gone blob/transcript degrades to warnings, never a throw.
+
+import { readFileSync } from 'node:fs';
+import { readIndex, resolveTrace, paths } from '../core/store.mjs';
+import { transcriptsFor, mineHostSession } from '../knowledge/distill.mjs';
+import { facultiesOf, invoke } from '../faculty/registry.mjs';
+
+/** Pure: the sessions list with state labels — the web Sessions section source. */
+export function sessionsListData(cwd = process.cwd()) {
+  const { sessions } = readIndex(cwd);
+  return {
+    sessions: sessions.map((s) => ({
+      id: s.id,
+      host: s.host,
+      state: s.status, // active | completed | abandoned | crashed | captured | opening
+      startedAt: s.startedAt ?? null,
+      endedAt: s.endedAt ?? null,
+      durationMs: s.durationMs ?? 0,
+      counts: s.counts ?? { turns: 0, tools: 0, errors: 0 },
+      generation: s.generation ?? null,
+      git: s.git ?? { commit: null, branch: null },
+    })),
+  };
+}
+
+/** Count spans across an OTLP/JSON NDJSON blob (one export request per line). */
+function countTraceSpans(file) {
+  let spans = 0;
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    const req = JSON.parse(line);
+    for (const rs of req.resourceSpans ?? []) {
+      for (const ss of rs.scopeSpans ?? []) spans += (ss.spans ?? []).length;
+    }
+  }
+  return spans;
+}
+
+/**
+ * Pure-ish: one session's observability document, or null for an unknown id.
+ * Accepts a unique id prefix (the table shows 8-char ids).
+ * @param {string} cwd
+ * @param {string} idArg
+ * @param {{transcripts?: Array<{host,ref,sessionId}>}} [opts]  injectable for hermetic tests
+ * @returns {{session, trace:{spans,tools,duration}, signals:object, warnings:string[]} | null}
+ */
+export function sessionInspectData(cwd, idArg, { transcripts } = {}) {
+  if (!idArg) return null;
+  const { sessions } = readIndex(cwd);
+  const matches = sessions.filter((s) => s.id === idArg);
+  const byPrefix = matches.length ? matches : sessions.filter((s) => String(s.id).startsWith(idArg));
+  if (!byPrefix.length) return null;
+  const s = byPrefix[0];
+  const warnings = [];
+
+  // trace summary — span count from the stored OTLP blob (fail-soft)
+  let spans = null;
+  try {
+    spans = countTraceSpans(resolveTrace(s.traceRef, cwd));
+  } catch {
+    warnings.push('trace blob unavailable — span count unknown');
+  }
+  const trace = { spans, tools: s.counts?.tools ?? 0, duration: s.durationMs ?? 0 };
+
+  // per-faculty mined signals — re-mine the host transcript (fail-soft when gone)
+  const signals = {};
+  try {
+    const pairs = transcripts ?? transcriptsFor({ scope: 'all', cwd });
+    const pair = pairs.find((p) => p.host === s.host && String(p.sessionId) === String(s.id));
+    const mined = pair ? mineHostSession(pair) : null;
+    if (!mined) {
+      warnings.push('host transcript unavailable — signals empty');
+    } else {
+      const agentDir = paths(cwd).dir;
+      for (const entry of facultiesOf(agentDir)) {
+        const r = invoke(entry, 'sessionSignals', mined);
+        if (r.ok && r.value && typeof r.value === 'object') signals[entry.id] = r.value;
+      }
+    }
+  } catch {
+    warnings.push('signal mining failed — signals empty');
+  }
+
+  return {
+    session: {
+      id: s.id,
+      host: s.host,
+      state: s.status,
+      startedAt: s.startedAt ?? null,
+      endedAt: s.endedAt ?? null,
+      durationMs: s.durationMs ?? 0,
+      counts: s.counts ?? { turns: 0, tools: 0, errors: 0 },
+      generation: s.generation ?? null,
+      git: s.git ?? { commit: null, branch: null },
+      traceRef: s.traceRef ?? null,
+    },
+    trace,
+    signals,
+    warnings,
+  };
+}
+
+const fmtDur = (ms) => (ms < 60_000 ? `${(ms / 1000).toFixed(0)}s` : `${(ms / 60_000).toFixed(1)}m`);
+
+/** `zuzuu sessions [--json]` — the recorded-sessions list with state labels. */
+export function sessions(args = {}) {
+  const cwd = process.cwd();
+  const d = sessionsListData(cwd);
+  if (args.json) { console.log(JSON.stringify(d)); return; }
+  if (!d.sessions.length) {
+    console.log('no recorded sessions yet — run `zuzuu capture`, or just start your agent (live capture)');
+    return;
+  }
+  console.log('  STATE      HOST          DUR     T/TOOLS/ERR  STARTED               SESSION');
+  for (const s of d.sessions) {
+    const dur = fmtDur(s.durationMs || 0).padStart(6);
+    const cnt = `${s.counts.turns}/${s.counts.tools}/${s.counts.errors}`.padEnd(11);
+    const started = (s.startedAt ?? '').slice(0, 19).padEnd(20);
+    console.log(`  ${s.state.padEnd(10)} ${s.host.padEnd(13)} ${dur}  ${cnt}  ${started}  ${String(s.id).slice(0, 8)}`);
+  }
+  console.log(`\n${d.sessions.length} session(s) — inspect one: zuzuu session inspect <id>`);
+}
+
+/** `zuzuu session inspect <id> [--json]` — print one session's document. */
+export function sessionInspect(args = {}) {
+  const cwd = process.cwd();
+  const id = args._?.[1];
+  const d = sessionInspectData(cwd, id);
+  if (!d) {
+    console.error(id ? `no recorded session matching '${id}'` : 'usage: zuzuu session inspect <id> [--json]');
+    process.exit(1);
+  }
+  if (args.json) { console.log(JSON.stringify(d)); return; }
+  const s = d.session;
+  console.log(`${s.id} — ${s.host} · ${s.state}`);
+  console.log(`  started: ${s.startedAt ?? '?'}  ended: ${s.endedAt ?? '?'}  dur: ${fmtDur(s.durationMs || 0)}`);
+  console.log(`  git: ${s.git?.commit ? s.git.commit.slice(0, 8) : '-'} (${s.git?.branch ?? '-'})  generation: ${s.generation ?? '-'}`);
+  console.log(`  trace: ${d.trace.spans ?? '?'} span(s) · ${d.trace.tools} tool(s) · ${fmtDur(d.trace.duration || 0)}`);
+  const sigs = Object.entries(d.signals);
+  if (sigs.length) {
+    console.log('  signals:');
+    for (const [faculty, counts] of sigs) {
+      const parts = Object.entries(counts).map(([k, v]) => `${k} ${v}`).join(' · ');
+      console.log(`    ${faculty.padEnd(13)} ${parts}`);
+    }
+  }
+  for (const w of d.warnings) console.log(`  ⚠ ${w}`);
+}

package/zuzuu/commands/status.mjs

@@ -3,11 +3,11 @@
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { detected } from '../capture/adapters/registry.mjs';
-import { sessionStatus } from '../session-git.mjs';
-import { readIndex, paths } from '../store.mjs';
+import { sessionStatus } from '../sessions/session-git.mjs';
+import { readIndex, paths } from '../core/store.mjs';
 import { FACULTIES } from '../faculty/contract.mjs';
 import { listProposals } from '../faculty/proposal.mjs';
-import { activeGeneration as activeGenerationFn } from '../faculty/generation.mjs';
+import { activeGeneration as activeGenerationFn } from '../faculty/generation/read.mjs';
 import { detectDrift } from './doctor.mjs';
 
 const fmtDur = (ms) => (ms < 60_000 ? `${(ms / 1000).toFixed(0)}s` : `${(ms / 60_000).toFixed(1)}m`);

package/zuzuu/commands/trace.mjs

@@ -2,7 +2,7 @@
 
 import { existsSync } from 'node:fs';
 import { loadSpans, renderTree } from '../capture/core/render.mjs';
-import { lastTrace } from '../store.mjs';
+import { lastTrace } from '../core/store.mjs';
 
 export function trace(args) {
   let file = args._[0];

package/zuzuu/{capture-core.mjs → core/capture-core.mjs}

@@ -3,9 +3,9 @@
 // (`hook`/`reconcile`, statuses active/completed/abandoned). One proven path —
 // Design B: the hook never builds spans, it re-runs THIS.
 
-import { eventsToSpans } from './capture/core/spans.mjs';
-import { toExportRequest } from './capture/core/otlp.mjs';
-import { EventKind, Status } from './capture/core/event.mjs';
+import { eventsToSpans } from '../capture/core/spans.mjs';
+import { toExportRequest } from '../capture/core/otlp.mjs';
+import { EventKind, Status } from '../capture/core/event.mjs';
 import { makeSession, SessionState } from './session.mjs';
 import { writeTrace, upsertSession, gitInfo } from './store.mjs';
 

package/zuzuu/{store.mjs → core/store.mjs}

@@ -11,7 +11,7 @@
 import { join, relative, resolve, isAbsolute } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { writeNdjson } from './capture/core/otlp.mjs';
+import { writeNdjson } from '../capture/core/otlp.mjs';
 
 const INDEX_VERSION = 1;
 

package/zuzuu/digest/compose.mjs

@@ -0,0 +1,96 @@
+// zuzuu/digest/compose.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.
+//
+// Composition (the Faculty Module contract): each built-in module exports its
+// own digestSection(agentDir, ctx); this file iterates the registry and stacks
+// the sections in the canonical order — instructions → knowledge → actions →
+// proposals (spine-level) → guardrails — then a default "N item(s)" section
+// for every DECLARATIVE faculty. Every hook call rides registry.invoke
+// (fail-soft): a single broken faculty never sinks the whole digest.
+
+import { listProposals } from '../knowledge/proposals.mjs';
+import { listFacultyItems } from '../faculty/items.mjs';
+import { facultiesOf, invoke } from '../faculty/registry.mjs';
+
+// The canonical section order (instructions/knowledge/actions render above the
+// proposals block; guardrails closes the brief — preserved pre-module layout).
+const HEAD_SECTIONS = ['instructions', 'knowledge', 'actions'];
+const TAIL_SECTIONS = ['guardrails'];
+
+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 };
+  }
+}
+
+/** Run one faculty's digestSection hook fail-soft; null = no section. */
+function sectionOf(entry, agentDir, ctx) {
+  const r = invoke(entry, 'digestSection', agentDir, ctx);
+  if (!r.ok || !r.value || !Array.isArray(r.value.lines)) return null;
+  return r.value;
+}
+
+/** The default section a faculty WITHOUT a digest hook gets: "N item(s)". */
+function defaultSection(agentDir, entry) {
+  let count = 0;
+  try {
+    count = listFacultyItems(agentDir, entry.id, { itemsDir: entry.manifest?.itemsDir }).items.length;
+  } catch { /* unreadable → 0 */ }
+  return { lines: [`## ${entry.manifest?.title ?? entry.id}`, `${count} item(s)`], data: { count } };
+}
+
+/**
+ * Compute the digest for a faculty home.
+ * @param {string} agentDir  path to the .zuzuu/ 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 faculties = facultiesOf(agentDir);
+  const byId = new Map(faculties.map((f) => [f.id, f]));
+  const ctx = () => ({ limit: knowledgeLimit, charBudget, priorLines: lines });
+
+  for (const id of HEAD_SECTIONS) {
+    const s = sectionOf(byId.get(id), agentDir, ctx());
+    if (!s) continue;
+    sections[id] = s.data;
+    if (s.lines.length) lines.push(...s.lines, '');
+  }
+
+  // Proposals — spine-level (cross-faculty pending count lives with the gate).
+  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('');
+  }
+
+  for (const id of TAIL_SECTIONS) {
+    const s = sectionOf(byId.get(id), agentDir, ctx());
+    if (!s) continue;
+    sections[id] = s.data;
+    if (s.lines.length) lines.push(...s.lines, '');
+  }
+
+  // Declarative faculties (manifest-only): the default "N item(s)" line each —
+  // a faculty you drop into the home is mentioned in the very next brief.
+  for (const entry of faculties) {
+    if (!entry.declarative || entry.manifestError) continue;
+    const s = sectionOf(entry, agentDir, ctx()) ?? defaultSection(agentDir, entry);
+    sections[entry.id] = s.data;
+    if (s.lines.length) lines.push(...s.lines, '');
+  }
+
+  return { text: lines.join('\n').trimEnd() + '\n', sections };
+}

package/zuzuu/eval/score.mjs

@@ -1,8 +1,14 @@
 // zuzuu/eval/score.mjs
 // Mechanical scorer — weighted sum of normalized signals → { score, confidence, rationale, signals }.
 // Pure; deterministic; no FS, no Date.now(), no Math.random().
+//
+// Faculty Module hook: a module may export evalSignals(proposal) → PARTIAL
+// signals; those overlay the mechanical extraction (fail-soft via the
+// registry's invoke — a broken hook leaves the default scorer untouched).
+// No built-in implements it today, so behavior is unchanged.
 
 import { extractSignals } from './signals.mjs';
+import { BUILTIN_MODULES, invoke } from '../faculty/registry.mjs';
 
 // Weight vector (must sum to 1.0).
 const W = {
@@ -60,7 +66,14 @@ function buildRationale(s) {
  * @returns {{ score: number, confidence: string, rationale: string, signals: object }}
  */
 export function mechanicalScore(proposal, opts = {}) {
-  const s = extractSignals(proposal, opts);
+  let s = extractSignals(proposal, opts);
+
+  // Optional per-faculty evalSignals hook — partial overlay, fail-soft.
+  const mod = BUILTIN_MODULES[proposal?.faculty];
+  if (mod && typeof mod.evalSignals === 'function') {
+    const r = invoke({ id: proposal.faculty, module: mod }, 'evalSignals', proposal);
+    if (r.ok && r.value && typeof r.value === 'object') s = { ...s, ...r.value };
+  }
 
   const raw =
     W.occurrence       * s.occurrence +