@zuzuucodes/cli 1.5.0 → 1.6.0

package/zuzuu/faculty/items.mjs

@@ -22,10 +22,15 @@ const ITEM_DIRS = {
   guardrails: ['guardrails', 'items'],
 };
 
-/** The flat items dir for a faculty, or null for dir-shaped faculties (actions). */
-export function itemsDirFor(agentDir, faculty) {
+/** 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];
-  return rel ? join(agentDir, ...rel) : null;
+  if (rel) return join(agentDir, ...rel);
+  const sub = itemsDir && itemsDir !== '.' ? itemsDir : 'items';
+  return join(agentDir, faculty, sub);
 }
 
 /** Canonical envelope file path for one item. */
@@ -36,9 +41,10 @@ export function itemPathFor(agentDir, faculty, id) {
 
 /**
  * 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) {
+export function listFacultyItems(agentDir, faculty, opts = {}) {
   const items = [];
   const errors = [];
   if (faculty === 'actions') {
@@ -56,7 +62,7 @@ export function listFacultyItems(agentDir, faculty) {
     }
     return { items, errors };
   }
-  const dir = itemsDirFor(agentDir, faculty);
+  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'));

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) };
+  }
 }

package/zuzuu/faculty/render.mjs

@@ -0,0 +1,59 @@
+// zuzuu/faculty/render.mjs — shared proposal card/text rendering for the human
+// gate surfaces (`zuzuu review` cards + `zuzuu proposals` lines). Pure string
+// builders; no I/O beyond the existing-item lookup the knowledge card shows.
+
+import { readItem } from '../knowledge/items.mjs';
+import { evalLine } from '../commands/eval.mjs';
+
+/**
+ * The rich knowledge proposal card (id, type, attrs/relations, evidence, ER
+ * verdict + the matched item when enrich/duplicate, eval line).
+ * @returns {string}
+ */
+export function knowledgeCard(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 {
+    // dual-read: legacy records carry `candidate`/`er`; spine records (e.g.
+    // inbox-promoted) carry `payload`/`analysis.er` — both must render.
+    const c = p.candidate ?? p.payload ?? {};
+    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 ?? p.analysis?.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');
+}
+
+/** The historical knowledge one-liner for `zuzuu proposals list`. */
+export function knowledgeLine(p) {
+  const c = p.candidate ?? p.payload ?? {}; // dual-read, same as the card
+  const what = p.kind === 'registry'
+    ? `register ${p.registry.slice(0, -1)} '${p.key}'`
+    : `${c.type}: ${c.body?.slice(0, 60).replace(/\n/g, ' ')}`;
+  return `  ${p.id}  [${p.er?.verdict ?? p.analysis?.er?.verdict ?? p.kind}]  ${what}`;
+}
+
+/** Derive the human title for a proposal (the JSON list/table form). */
+export function proposalTitle(adapter, p) {
+  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;
+  }
+  return title ?? p.id;
+}

package/zuzuu/faculty/trail.mjs

@@ -7,7 +7,7 @@
 
 import { join } from 'node:path';
 import { mkdirSync, appendFileSync } from 'node:fs';
-import { liveDir } from '../store.mjs';
+import { liveDir } from '../core/store.mjs';
 
 /**
  * Append a trail entry for a faculty. Never throws.

package/zuzuu/{guardrails.mjs → guardrails/engine.mjs}

@@ -31,7 +31,7 @@
 
 import { join } from 'node:path';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { parseEnvelope } from './faculty/envelope.mjs';
+import { parseEnvelope } from '../faculty/envelope.mjs';
 
 const SEVERITY = { deny: 3, ask: 2, allow: 1 };
 const ACTIONS = new Set(Object.keys(SEVERITY));

package/zuzuu/{scaffold.mjs → home/scaffold.mjs}

@@ -15,8 +15,9 @@
 
 import { join } from 'node:path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
-import { SEED_TYPES, SEED_ATTRIBUTES, SEED_RELATIONS } from './knowledge/registry.mjs';
-import { serializeEnvelope, PAYLOAD_SCHEMAS, FACULTY_KINDS } from './faculty/envelope.mjs';
+import { SEED_TYPES, SEED_ATTRIBUTES, SEED_RELATIONS } from '../knowledge/registry.mjs';
+import { serializeEnvelope, PAYLOAD_SCHEMAS, FACULTY_KINDS } from '../faculty/envelope.mjs';
+import { BUILTIN_MODULES } from '../faculty/registry.mjs';
 
 export const MANIFEST_VERSION = 4;
 
@@ -194,6 +195,10 @@ const ENVELOPE_SPEC = JSON.stringify(
 
 const payloadSchemaSeed = (f) => JSON.stringify(PAYLOAD_SCHEMAS[f], null, 2) + '\n';
 
+/** Faculty Module manifest seed (faculty.json) — the built-in module's canonical
+ *  manifest, serialized. Pinned definitions: byte-identical on re-init. */
+export const manifestSeed = (f) => JSON.stringify(BUILTIN_MODULES[f].manifest, null, 2) + '\n';
+
 /** The layout contract: dirs + seed files (relative to the project root). */
 export const LAYOUT = {
   dirs: ['.zuzuu', '.zuzuu/knowledge', '.zuzuu/knowledge/registry', '.zuzuu/knowledge/items', '.zuzuu/knowledge/inbox', '.zuzuu/knowledge/proposals', '.zuzuu/memory', '.zuzuu/memory/entries', '.zuzuu/memory/inbox', '.zuzuu/memory/proposals', '.zuzuu/actions', '.zuzuu/actions/inbox', '.zuzuu/instructions', '.zuzuu/instructions/items', '.zuzuu/instructions/inbox', '.zuzuu/instructions/proposals', '.zuzuu/guardrails', '.zuzuu/guardrails/items', '.zuzuu/guardrails/inbox', '.zuzuu/guardrails/proposals', '.zuzuu/generations', '.zuzuu/generations/snapshots'],
@@ -202,15 +207,20 @@ export const LAYOUT = {
     '.zuzuu/schema.json': ENVELOPE_SPEC,
     '.zuzuu/knowledge/README.md': KNOWLEDGE_README,
     '.zuzuu/knowledge/schema.json': payloadSchemaSeed('knowledge'),
+    '.zuzuu/knowledge/faculty.json': manifestSeed('knowledge'),
     '.zuzuu/memory/README.md': MEMORY_README,
     '.zuzuu/memory/schema.json': payloadSchemaSeed('memory'),
+    '.zuzuu/memory/faculty.json': manifestSeed('memory'),
     '.zuzuu/actions/README.md': ACTIONS_README,
     '.zuzuu/actions/schema.json': payloadSchemaSeed('actions'),
+    '.zuzuu/actions/faculty.json': manifestSeed('actions'),
     '.zuzuu/instructions/README.md': INSTRUCTIONS_README,
     '.zuzuu/instructions/schema.json': payloadSchemaSeed('instructions'),
+    '.zuzuu/instructions/faculty.json': manifestSeed('instructions'),
     '.zuzuu/instructions/items/steering.md': STEERING_SEED,
     '.zuzuu/guardrails/README.md': GUARDRAILS_README,
     '.zuzuu/guardrails/schema.json': payloadSchemaSeed('guardrails'),
+    '.zuzuu/guardrails/faculty.json': manifestSeed('guardrails'),
     '.zuzuu/guardrails/items/no-root-wipe.md': RULE_SEEDS['no-root-wipe'],
     '.zuzuu/guardrails/items/no-secret-reads.md': RULE_SEEDS['no-secret-reads'],
     '.zuzuu/guardrails/items/confirm-force-push.md': RULE_SEEDS['confirm-force-push'],

package/zuzuu/live/live-store.mjs

@@ -7,8 +7,8 @@
 
 import { join } from 'node:path';
 import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
-import { paths, liveDir as liveDirOf } from '../store.mjs';
-import { SessionState } from '../session.mjs';
+import { paths, liveDir as liveDirOf } from '../core/store.mjs';
+import { SessionState } from '../core/session.mjs';
 
 const liveDir = (cwd) => liveDirOf(paths(cwd).dir);
 // Some hosts pass a file PATH as the session id (pi → the session-file path).

package/zuzuu/live/reconcile.mjs

@@ -5,8 +5,8 @@
 
 import { listLive, isStale, closeLive } from './live-store.mjs';
 import { byName } from '../capture/adapters/registry.mjs';
-import { captureTrace } from '../capture-core.mjs';
-import { SessionState } from '../session.mjs';
+import { captureTrace } from '../core/capture-core.mjs';
+import { SessionState } from '../core/session.mjs';
 
 export const DEFAULT_STALE_MS = 15 * 60 * 1000; // 15 min without a heartbeat → abandoned
 

package/zuzuu/sessions/git.mjs

@@ -0,0 +1,47 @@
+// zuzuu/sessions/git.mjs — git PLUMBING for session-git (no session policy here).
+//
+// Every helper is safe-by-construction: argv arrays only (no shell strings),
+// never throws, returns plain data. Session POLICY (open/checkpoint/close/
+// status and the safety gates) lives in session-git.mjs.
+
+import { spawnSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { join, isAbsolute, resolve } from 'node:path';
+
+/** One git call — argv array only (no shell), never throws. */
+export function git(args, cwd, input) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', input });
+    return { ok: r.status === 0 && !r.error, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+  } catch (e) {
+    return { ok: false, out: '', err: String(e) };
+  }
+}
+
+export function gitDir(cwd) {
+  const r = git(['rev-parse', '--git-dir'], cwd);
+  if (!r.ok || !r.out) return null;
+  return isAbsolute(r.out) ? r.out : resolve(cwd, r.out);
+}
+
+/** Current branch name, or null when detached / not a repo. */
+export function currentBranch(cwd) {
+  const r = git(['symbolic-ref', '--short', '-q', 'HEAD'], cwd);
+  return r.ok && r.out ? r.out : null;
+}
+
+export const branchExists = (cwd, name) => git(['rev-parse', '-q', '--verify', `refs/heads/${name}`], cwd).ok;
+export const isDirty = (cwd) => !!git(['status', '--porcelain'], cwd).out;
+
+/** Best-effort: drop squash leftovers so they can't leak into the user's next commit. */
+export function cleanupSquashState(cwd) {
+  const gd = gitDir(cwd);
+  if (!gd) return;
+  for (const f of ['SQUASH_MSG', 'MERGE_MSG']) {
+    try {
+      rmSync(join(gd, f), { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}