@zuzuucodes/cli 1.4.0 → 1.6.0

package/zuzuu/faculty/generation/write.mjs

@@ -0,0 +1,207 @@
+// zuzuu/faculty/generation/write.mjs — the generation WRITE side (WS3-T1,
+// split per the 2026-06-13 overhaul): agent identity repair, minting (freeze +
+// snapshot + flip active) and rollback (restore by content). Read-side paths,
+// enumerators and diffing live in read.mjs.
+
+import { join, dirname } from 'node:path';
+import {
+  existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, renameSync,
+} from 'node:fs';
+import { reindex } from '../../knowledge/index.mjs';
+import {
+  snapshotsDir, activePath, lockfilePath, agentJsonPath, readJson,
+  knowledgeFiles, memoryFiles, actionFiles, guardrailFiles, instructionFiles,
+  snapshotFaculties, agentId, listGenerations, readGeneration,
+} from './read.mjs';
+
+const writeJson = (p, obj) => {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+};
+
+/** Add/repair the agent block in agent.json (bump to v2), preserving other fields. */
+export function ensureAgent(agentDir) {
+  const path = agentJsonPath(agentDir);
+  const m = existsSync(path) ? readJson(path) : {};
+  const id = agentId(agentDir);
+  if (!m.agent || !m.agent.id) {
+    m.agent = { id, createdAt: new Date().toISOString() };
+  }
+  m.version = 2;
+  writeJson(path, m);
+  return m.agent;
+}
+
+function nextGenId(agentDir) {
+  const ids = listGenerations(agentDir);
+  const max = ids.reduce((m, id) => Math.max(m, parseInt(id.slice(4), 10) || 0), 0);
+  return 'gen_' + String(max + 1).padStart(3, '0');
+}
+
+// --- mint -------------------------------------------------------------------
+
+function copySnapshot(agentDir, id) {
+  const base = join(snapshotsDir(agentDir), id);
+  for (const it of knowledgeFiles(agentDir)) {
+    const dest = join(base, 'knowledge', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+  for (const it of memoryFiles(agentDir)) {
+    const dest = join(base, 'memory', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+  for (const a of actionFiles(agentDir)) {
+    for (const rel of a.files) {
+      const dest = join(base, 'actions', a.id, rel);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(join(a.adir, rel)));
+    }
+  }
+  for (const it of guardrailFiles(agentDir)) {
+    const dest = join(base, 'guardrails', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+  for (const it of instructionFiles(agentDir)) {
+    const dest = join(base, 'instructions', it.rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(it.src));
+  }
+}
+
+/**
+ * Mint a new generation: freeze the current faculty state into a content-addressed
+ * lockfile + a byte-for-byte snapshot, and make it active.
+ */
+export function mintGeneration(agentDir, { forkedFrom = null, mintedFrom = [] } = {}) {
+  const agent = ensureAgent(agentDir).id;
+  const id = nextGenId(agentDir);
+  const lockfile = {
+    id,
+    agent,
+    mintedAt: new Date().toISOString(),
+    forkedFrom,
+    mintedFrom,
+    faculties: snapshotFaculties(agentDir),
+  };
+  copySnapshot(agentDir, id);
+  writeJson(lockfilePath(agentDir, id), lockfile);
+  writeJson(activePath(agentDir), { active: id });
+  return lockfile;
+}
+
+// --- rollback ---------------------------------------------------------------
+
+function archive(agentDir, faculty, src) {
+  // Park (never delete) under <faculty>/_rolledback/<basename> — by basename so
+  // a restore is a simple, flat audit trail of what the rollback displaced.
+  const dest = join(agentDir, faculty, '_rolledback', src.slice(dirname(src).length + 1));
+  mkdirSync(dirname(dest), { recursive: true });
+  renameSync(src, dest);
+}
+
+/**
+ * Restore a past generation by content: write each snapshotted item back to its
+ * live faculty path; MOVE (never delete) active items absent from the target into
+ * <faculty>/_rolledback/; reindex knowledge; flip the active pointer.
+ */
+export function rollback(agentDir, id) {
+  const target = readGeneration(agentDir, id);
+  if (!target) throw new Error(`no generation '${id}'`);
+  const base = join(snapshotsDir(agentDir), id);
+  let restored = 0;
+
+  // 1) restore snapshotted knowledge items
+  const targetKnowledge = new Set((target.faculties.knowledge?.items ?? []).map((i) => i.id));
+  for (const i of target.faculties.knowledge?.items ?? []) {
+    const snap = join(base, 'knowledge', `${i.id}.md`);
+    if (existsSync(snap)) {
+      const dest = join(agentDir, 'knowledge', 'items', `${i.id}.md`);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(snap));
+      restored++;
+    }
+  }
+  // archive live knowledge items not in the target
+  const kdir = join(agentDir, 'knowledge', 'items');
+  if (existsSync(kdir)) {
+    for (const e of readdirSync(kdir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && !targetKnowledge.has(e.name.replace(/\.md$/, ''))) {
+        archive(agentDir, 'knowledge', join(kdir, e.name));
+      }
+    }
+  }
+
+  // 2) restore snapshotted memory items + archive extras
+  const targetMemory = new Set((target.faculties.memory?.items ?? []).map((i) => i.id));
+  for (const i of target.faculties.memory?.items ?? []) {
+    const snap = join(base, 'memory', `${i.id}.md`);
+    if (existsSync(snap)) {
+      const dest = join(agentDir, 'memory', 'entries', `${i.id}.md`);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(snap));
+      restored++;
+    }
+  }
+  const mdir = join(agentDir, 'memory', 'entries');
+  if (existsSync(mdir)) {
+    for (const e of readdirSync(mdir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && !targetMemory.has(e.name.replace(/\.md$/, ''))) {
+        archive(agentDir, 'memory', join(mdir, e.name));
+      }
+    }
+  }
+
+  // 3) restore snapshotted actions + archive extras
+  const targetActions = new Set((target.faculties.actions?.items ?? []).map((i) => i.id));
+  const asnap = join(base, 'actions');
+  if (existsSync(asnap)) {
+    for (const slugEnt of readdirSync(asnap, { withFileTypes: true })) {
+      if (!slugEnt.isDirectory()) continue;
+      const sdir = join(asnap, slugEnt.name);
+      for (const f of readdirSync(sdir)) {
+        const dest = join(agentDir, 'actions', slugEnt.name, f);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, readFileSync(join(sdir, f)));
+      }
+      restored++;
+    }
+  }
+  const adir = join(agentDir, 'actions');
+  if (existsSync(adir)) {
+    for (const e of readdirSync(adir, { withFileTypes: true })) {
+      if (e.isDirectory() && e.name !== 'inbox' && e.name !== 'proposals' && e.name !== '_rolledback' && !targetActions.has(e.name)) {
+        archive(agentDir, 'actions', join(adir, e.name));
+      }
+    }
+  }
+
+  // 4) restore guardrails + instructions items (same item-list contract)
+  for (const [faculty, liveSeg] of [['guardrails', ['guardrails', 'items']], ['instructions', ['instructions', 'items']]]) {
+    const targetIds = new Set((target.faculties[faculty]?.items ?? []).map((i) => i.id));
+    for (const i of target.faculties[faculty]?.items ?? []) {
+      const snap = join(base, faculty, `${i.id}.md`);
+      if (existsSync(snap)) {
+        const dest = join(agentDir, ...liveSeg, `${i.id}.md`);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, readFileSync(snap));
+        restored++;
+      }
+    }
+    const liveDir = join(agentDir, ...liveSeg);
+    if (existsSync(liveDir)) {
+      for (const e of readdirSync(liveDir, { withFileTypes: true })) {
+        if (e.isFile() && e.name.endsWith('.md') && !targetIds.has(e.name.replace(/\.md$/, ''))) {
+          archive(agentDir, faculty, join(liveDir, e.name));
+        }
+      }
+    }
+  }
+
+  // 5) regenerate the derived knowledge index + flip the pointer
+  try { reindex(agentDir); } catch { /* derived index; tolerate absence of node:sqlite features */ }
+  writeJson(activePath(agentDir), { active: id });
+  return { ok: true, restored };
+}

package/zuzuu/faculty/items.mjs

@@ -0,0 +1,81 @@
+// zuzuu/faculty/items.mjs — where each faculty's envelope items live (W24).
+//
+// One standard, five homes:
+//   knowledge    → knowledge/items/<id>.md
+//   memory       → memory/entries/<id>.md
+//   instructions → instructions/items/<id>.md
+//   guardrails   → guardrails/items/<id>.md
+//   actions      → actions/<id>/ACTION.md   (dir-shaped: scripts stay siblings)
+//
+// Listing is fail-soft: unparseable files are collected as errors, never thrown
+// (mirrors knowledge allItems — audit surfaces them).
+
+import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { parseEnvelope, serializeEnvelope } from './envelope.mjs';
+
+/** Flat item dirs per faculty (actions are dir-shaped — see itemPathFor). */
+const ITEM_DIRS = {
+  knowledge: ['knowledge', 'items'],
+  memory: ['memory', 'entries'],
+  instructions: ['instructions', 'items'],
+  guardrails: ['guardrails', 'items'],
+};
+
+/** The flat items dir for a faculty, or null for dir-shaped faculties (actions).
+ *  Unknown (declarative) faculties default to `<faculty>/<itemsDir||'items'>`
+ *  under the home — manifest-only faculties get items listing for free. */
+export function itemsDirFor(agentDir, faculty, itemsDir) {
+  if (faculty === 'actions') return null;
+  const rel = ITEM_DIRS[faculty];
+  if (rel) return join(agentDir, ...rel);
+  const sub = itemsDir && itemsDir !== '.' ? itemsDir : 'items';
+  return join(agentDir, faculty, sub);
+}
+
+/** Canonical envelope file path for one item. */
+export function itemPathFor(agentDir, faculty, id) {
+  if (faculty === 'actions') return join(agentDir, 'actions', id, 'ACTION.md');
+  return join(itemsDirFor(agentDir, faculty), `${id}.md`);
+}
+
+/**
+ * All envelope items of a faculty. Parse errors collected, never thrown.
+ * @param {{itemsDir?: string}} [opts]  declarative faculties pass manifest.itemsDir
+ * @returns {{items: object[], errors: Array<{file: string, error: string}>}}
+ */
+export function listFacultyItems(agentDir, faculty, opts = {}) {
+  const items = [];
+  const errors = [];
+  if (faculty === 'actions') {
+    const base = join(agentDir, 'actions');
+    if (!existsSync(base)) return { items, errors };
+    for (const name of readdirSync(base).sort()) {
+      if (name === 'inbox' || name === 'proposals' || name === '_rolledback') continue;
+      const p = join(base, name, 'ACTION.md');
+      let isDir = false;
+      try { isDir = statSync(join(base, name)).isDirectory(); } catch { /* skip */ }
+      if (!isDir || !existsSync(p)) continue;
+      const { ok, item, errors: errs } = parseEnvelope(readFileSync(p, 'utf8'));
+      if (ok) items.push(item);
+      else errors.push({ file: `${name}/ACTION.md`, error: errs[0] ?? 'parse error' });
+    }
+    return { items, errors };
+  }
+  const dir = itemsDirFor(agentDir, faculty, opts.itemsDir);
+  if (!dir || !existsSync(dir)) return { items, errors };
+  for (const f of readdirSync(dir).filter((f) => f.endsWith('.md')).sort()) {
+    const { ok, item, errors: errs } = parseEnvelope(readFileSync(join(dir, f), 'utf8'));
+    if (ok) items.push(item);
+    else errors.push({ file: f, error: errs[0] ?? 'parse error' });
+  }
+  return { items, errors };
+}
+
+/** Write one envelope item to its canonical path. Returns the path. */
+export function writeFacultyItem(agentDir, item) {
+  const path = itemPathFor(agentDir, item.faculty, item.id);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, serializeEnvelope(item));
+  return path;
+}

package/zuzuu/faculty/module.mjs

@@ -0,0 +1,74 @@
+// zuzuu/faculty/module.mjs — the Faculty Module contract (2026-06-13 spec).
+//
+// A faculty = a MANIFEST (<faculty>/faculty.json in the home) + an ITEMS
+// collection (Faculty Standard envelopes under manifest.itemsDir) + a set of
+// named HOOK exports (built-ins: zuzuu/faculties/<id>/index.mjs):
+//
+//   manifest                                  — the machine contract (this file's shape)
+//   miner = { faculty, aggregate, propose }   — REQUIRED for code modules
+//   digestSection(agentDir, ctx)              — optional; default = "N item(s)" line
+//   evalSignals(proposal)                     — optional; default mechanical scorer
+//   gate(toolCall)                            — optional; ONLY guardrails today
+//   applyProposal(agentDir, proposal)         — the adapter's apply
+//   validate(agentDir, payload)               — the adapter's validate
+//
+// Host law (fail-soft everywhere): every hook call is try-wrapped (+ time-boxed
+// for miner-class hooks) by the registry — a broken faculty module degrades to
+// items-only, never crashes the CLI, the gate, or a host hook.
+//
+// Manifest-only folders (faculty.json with NO code) are DECLARATIVE faculties:
+// they get items listing, card UI, schema validation and the default digest
+// line today; third-party CODE loading is deferred (W4).
+
+/** The module-API version this host speaks. Majors above this are skipped. */
+export const CONTRACT_VERSION = 1;
+
+/**
+ * Normalize a raw manifest object into the full contract shape (defaults
+ * filled, id forced to the faculty's directory name when absent). Pure.
+ * @param {object} raw      parsed faculty.json (or {})
+ * @param {string} dirName  the faculty folder name (fallback id)
+ */
+export function normalizeManifest(raw = {}, dirName = 'faculty') {
+  const id = typeof raw.id === 'string' && raw.id ? raw.id : dirName;
+  const title = typeof raw.title === 'string' && raw.title ? raw.title : id.charAt(0).toUpperCase() + id.slice(1);
+  return {
+    id,
+    title,
+    tagline: typeof raw.tagline === 'string' ? raw.tagline : '',
+    version: typeof raw.version === 'string' ? raw.version : '1.0.0',
+    contract: Number.isFinite(raw.contract) ? raw.contract : CONTRACT_VERSION,
+    kinds: Array.isArray(raw.kinds) ? raw.kinds.map(String) : [],
+    itemsDir: typeof raw.itemsDir === 'string' && raw.itemsDir ? raw.itemsDir : 'items',
+    schema: typeof raw.schema === 'string' && raw.schema ? raw.schema : 'schema.json',
+    hooks: {
+      miner: !!raw.hooks?.miner,
+      digest: !!raw.hooks?.digest,
+      eval: !!raw.hooks?.eval,
+      gate: !!raw.hooks?.gate,
+    },
+    ui: {
+      icon: typeof raw.ui?.icon === 'string' ? raw.ui.icon : 'folder',
+      accent: typeof raw.ui?.accent === 'string' ? raw.ui.accent : 'neutral',
+      teaching: typeof raw.ui?.teaching === 'string' ? raw.ui.teaching : '',
+    },
+  };
+}
+
+/** Is a manifest's contract version one this host can serve? (major gate) */
+export function compatibleContract(manifest) {
+  return Math.floor(manifest?.contract ?? CONTRACT_VERSION) <= CONTRACT_VERSION;
+}
+
+/**
+ * Validate a manifest's required fields. Returns {ok, errors} — never throws.
+ * (Normalization already fills defaults; this flags the truly broken.)
+ */
+export function validateManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object') return { ok: false, errors: ['not an object'] };
+  if (!manifest.id || !/^[a-z0-9][a-z0-9_-]*$/.test(manifest.id)) errors.push(`id must be a slug (got '${manifest.id}')`);
+  if (!manifest.title) errors.push('title is required');
+  if (!compatibleContract(manifest)) errors.push(`contract ${manifest.contract} > host contract ${CONTRACT_VERSION} — skipped`);
+  return { ok: errors.length === 0, errors };
+}

package/zuzuu/faculty/pending.mjs

@@ -0,0 +1,63 @@
+// zuzuu/faculty/pending.mjs — pending-proposal collection shared by the gate
+// surfaces (`zuzuu review`, `zuzuu proposals`, `zuzuu eval`). One walk order,
+// one ranked grouping; adapters with their own listProposals (dir-shaped
+// faculties) override the spine read.
+
+import * as registry from './registry.mjs';
+import { listProposals as spineListProposals } from './proposal.mjs';
+import { readIndex } from '../core/store.mjs';
+import { rank } from '../eval/rank.mjs';
+import { getScorer } from '../eval/score.mjs';
+
+// 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).
+export const REVIEW_ORDER = ['actions', 'knowledge', 'guardrails', 'instructions', 'memory'];
+
+/** Build sessionMtimes map from the sessions index — best-effort, fail-open. */
+export function buildSessionMtimes(cwd) {
+  try {
+    const idx = readIndex(cwd);
+    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 {};
+  }
+}
+
+/** Pending proposals for one adapter (dir-shaped adapters override listProposals). */
+export 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);
+}
+
+/** Ordered list of adapters that have pending proposals to review. */
+export 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;
+}

package/zuzuu/faculty/registry.mjs

@@ -1,33 +1,219 @@
-// zuzuu/faculty/registry.mjs
-// Faculty adapter registry — a module-level Map keyed by adapter.name.
-// Adapters register themselves on import; consumers query by name or list all.
+// zuzuu/faculty/registry.mjs — the Faculty Module registry (2026-06-13 spec).
 //
-// This is the registration surface only. Adapters are added in later work units.
+// Replaces the old scattered wiring (miners/registry self-registration,
+// per-faculty adapter imports at every spine call site, digest's hardcoded
+// sections): the five BUILT-IN modules are imported statically here; the spine
+// (gate/review/proposals/eval/distill/digest/doctor) iterates THIS registry —
+// no faculty names hardcoded outside built-in module files (ordering
+// preferences excepted).
+//
+// Discovery beyond built-ins: any `<home>/<dir>/faculty.json` is parsed and
+// listed as a DECLARATIVE faculty (manifest-only — items listing, card UI,
+// schema validation, default digest line work today). Third-party CODE loading
+// is explicitly deferred to W4.
+//
+// Host law: every hook invocation goes through invoke()/invokeTimeboxed() —
+// try-wrapped (+ 5s time-box on miner-class hooks). A broken module degrades
+// to items-only; failures are recorded and surfaced by `zuzuu doctor`.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FACULTIES } from './contract.mjs';
+import { normalizeManifest, compatibleContract } from './module.mjs';
+import * as knowledge from '../faculties/knowledge/index.mjs';
+import * as memory from '../faculties/memory/index.mjs';
+import * as actions from '../faculties/actions/index.mjs';
+import * as instructions from '../faculties/instructions/index.mjs';
+import * as guardrails from '../faculties/guardrails/index.mjs';
+
+export const BUILTIN_MODULES = { knowledge, memory, actions, instructions, guardrails };
+
+// Legacy adapter/miner walk order (the pre-module import order at every call
+// site) — preserved so list/eval/distill outputs stay byte-identical.
+const LEGACY_ORDER = ['knowledge', 'actions', 'guardrails', 'instructions', 'memory'];
 
-/** @type {Map<string, object>} */
-const _registry = new Map();
+// ---------------------------------------------------------------------------
+// adapter surface (back-compat: gate/review/proposals/eval consume these)
+// ---------------------------------------------------------------------------
+
+/** Test/extension overrides layered over the built-ins. */
+const overrides = new Map();
 
 /**
- * Register an adapter (keyed by adapter.name). Overwrites if already registered.
- * @param {{ name: string, [key: string]: any }} adapter
+ * Register an adapter override (keyed by adapter.name). Built-ins are always
+ * present; this layers replacements/additions on top (tests, future plugins).
  */
 export function register(adapter) {
-  _registry.set(adapter.name, adapter);
+  overrides.set(adapter.name, adapter);
+}
+
+/** Retrieve an adapter by faculty name (override > built-in). */
+export function get(name) {
+  return overrides.get(name) ?? BUILTIN_MODULES[name]?.adapter;
+}
+
+/** All adapters, built-ins first in the legacy order, then extra overrides. */
+export function all() {
+  const names = [...LEGACY_ORDER];
+  for (const n of overrides.keys()) if (!names.includes(n)) names.push(n);
+  return names.map(get).filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// miner surface (replaces miners/registry.mjs)
+// ---------------------------------------------------------------------------
+
+/** All built-in miners in the legacy distill order. */
+export function miners() {
+  return LEGACY_ORDER.map((f) => BUILTIN_MODULES[f]?.miner).filter(Boolean);
+}
+
+/** The miner for a faculty, or undefined. */
+export function minerOf(faculty) {
+  return BUILTIN_MODULES[faculty]?.miner;
+}
+
+// ---------------------------------------------------------------------------
+// faculty discovery — built-ins + declarative faculty.json folders
+// ---------------------------------------------------------------------------
+
+/** Read + normalize `<home>/<id>/faculty.json` → {manifest|null, error|null}. */
+function readHomeManifest(agentDir, id) {
+  const p = join(agentDir, id, 'faculty.json');
+  if (!existsSync(p)) return { manifest: null, error: null };
+  try {
+    const manifest = normalizeManifest(JSON.parse(readFileSync(p, 'utf8')), id);
+    if (!compatibleContract(manifest)) {
+      return { manifest: null, error: `contract ${manifest.contract} unsupported by this host` };
+    }
+    return { manifest, error: null };
+  } catch (e) {
+    return { manifest: null, error: e.message ?? String(e) };
+  }
 }
 
+// Home dirs that are never faculties.
+const NON_FACULTY_DIRS = new Set(['generations']);
+
 /**
- * Retrieve a registered adapter by name. Returns undefined if not found.
- * @param {string} name
- * @returns {{ name: string, [key: string]: any } | undefined}
+ * Every faculty this home serves: the five built-ins (always — module code +
+ * manifest, home faculty.json overriding the built-in manifest when present)
+ * plus declarative manifest-only folders. Fail-soft: a broken faculty.json
+ * lists the faculty with `manifestError` (degraded — doctor reports it).
+ *
+ * @param {string} agentDir
+ * @returns {Array<{id, manifest, module, builtin, declarative, manifestSource, manifestError?}>}
  */
-export function get(name) {
-  return _registry.get(name);
+export function facultiesOf(agentDir) {
+  const out = [];
+  for (const id of FACULTIES) {
+    const mod = BUILTIN_MODULES[id];
+    const home = readHomeManifest(agentDir, id);
+    out.push({
+      id,
+      builtin: true,
+      declarative: false,
+      module: mod,
+      manifest: home.manifest ?? mod.manifest,
+      manifestSource: home.manifest ? 'home' : 'builtin',
+      ...(home.error ? { manifestError: home.error } : {}),
+    });
+  }
+  try {
+    for (const e of readdirSync(agentDir, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name.startsWith('.') || e.name.startsWith('_')) continue;
+      if (FACULTIES.includes(e.name) || NON_FACULTY_DIRS.has(e.name)) continue;
+      const home = readHomeManifest(agentDir, e.name);
+      if (!home.manifest && !home.error) continue; // no faculty.json → not a faculty
+      out.push({
+        id: e.name,
+        builtin: false,
+        declarative: true,
+        module: null, // third-party CODE loading deferred to W4 — manifest-only today
+        manifest: home.manifest ?? normalizeManifest({}, e.name),
+        manifestSource: 'home',
+        ...(home.error ? { manifestError: home.error } : {}),
+      });
+    }
+  } catch { /* no home dir yet → built-ins only */ }
+  return out;
+}
+
+/** One faculty entry by id (built-in or declarative), or null. */
+export function facultyOf(agentDir, id) {
+  return facultiesOf(agentDir).find((f) => f.id === id) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// fail-soft hook invocation (+ degradation record for doctor)
+// ---------------------------------------------------------------------------
+
+/** Miner-class hooks get a wall-clock budget (spec: 5s). */
+export const MINER_HOOK_TIMEOUT_MS = 5000;
+
+const failures = new Map(); // `${faculty}.${hook}` → { faculty, hook, error, at }
+
+function recordFailure(faculty, hook, error) {
+  failures.set(`${faculty}.${hook}`, { faculty, hook, error: String(error?.message ?? error), at: new Date().toISOString() });
+}
+
+/** Hook failures recorded this process — `zuzuu doctor` surfaces these. */
+export function hookFailures() {
+  return [...failures.values()];
+}
+
+/** Tests only: forget recorded failures. */
+export function clearHookFailures() {
+  failures.clear();
 }
 
 /**
- * Return all registered adapters as an array.
- * @returns {Array<{ name: string, [key: string]: any }>}
+ * Invoke a module hook fail-soft (synchronous spine paths: digest, gate,
+ * signals). NEVER throws.
+ * @param {{id:string, module:object|null}} entry  a facultiesOf() entry (or {id, module})
+ * @returns {{ok:true, value:any} | {ok:false, missing?:true, error?:string}}
  */
-export function all() {
-  return [..._registry.values()];
+export function invoke(entry, hook, ...args) {
+  const fn = entry?.module?.[hook];
+  if (typeof fn !== 'function') return { ok: false, missing: true };
+  try {
+    return { ok: true, value: fn(...args) };
+  } catch (e) {
+    recordFailure(entry.id ?? entry.module?.manifest?.id ?? '?', hook, e);
+    return { ok: false, error: String(e?.message ?? e) };
+  }
+}
+
+/**
+ * Invoke a miner-class hook fail-soft WITH a time-box: synchronous throws are
+ * caught; an async (Promise-returning) hook is raced against `timeoutMs`
+ * (default 5s). NEVER rejects.
+ * @returns {Promise<{ok:true, value:any} | {ok:false, missing?:true, timedOut?:true, error?:string}>}
+ */
+export async function invokeTimeboxed(entry, hook, args = [], { timeoutMs = MINER_HOOK_TIMEOUT_MS } = {}) {
+  const fn = entry?.module?.[hook];
+  if (typeof fn !== 'function') return { ok: false, missing: true };
+  const faculty = entry.id ?? entry.module?.manifest?.id ?? '?';
+  try {
+    const r = fn(...args);
+    if (!r || typeof r.then !== 'function') return { ok: true, value: r };
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve({ __zuzuuTimeout: true }), timeoutMs);
+    });
+    const settled = await Promise.race([Promise.resolve(r).catch((e) => ({ __zuzuuError: e })), timeout]);
+    clearTimeout(timer);
+    if (settled && settled.__zuzuuTimeout) {
+      recordFailure(faculty, hook, `timed out after ${timeoutMs}ms`);
+      return { ok: false, timedOut: true, error: `timed out after ${timeoutMs}ms` };
+    }
+    if (settled && settled.__zuzuuError !== undefined) {
+      recordFailure(faculty, hook, settled.__zuzuuError);
+      return { ok: false, error: String(settled.__zuzuuError?.message ?? settled.__zuzuuError) };
+    }
+    return { ok: true, value: settled };
+  } catch (e) {
+    recordFailure(faculty, hook, e);
+    return { ok: false, error: String(e?.message ?? e) };
+  }
 }