@zuzuucodes/cli 1.4.0 → 1.6.0

package/zuzuu/commands/enable.mjs

@@ -6,7 +6,7 @@
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
-import { repoRoot } from '../store.mjs';
+import { repoRoot } from '../core/store.mjs';
 import { addHooks, removeHooks, isInstalled, LIFECYCLE_EVENTS, GATE_EVENTS, addHookEntries, removeHookEntries } from '../live/install.mjs';
 
 const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'zuzuu.mjs');

package/zuzuu/commands/eval.mjs

@@ -7,16 +7,11 @@
 // a one-line eval annotation per proposal card.
 
 import { join } from 'node:path';
-import { paths, readIndex } from '../store.mjs';
+import { paths } from '../core/store.mjs';
 import * as registry from '../faculty/registry.mjs';
-import { listProposals as spineListProposals } from '../faculty/proposal.mjs';
+import { buildSessionMtimes, facultyPending } from '../faculty/pending.mjs';
 import { rank } from '../eval/rank.mjs';
 import { getScorer } from '../eval/score.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
 
 /**
  * Format one eval annotation line for a proposal card in `zuzuu review`.
@@ -30,34 +25,6 @@ export function evalLine({ score, confidence, rationale }) {
   return `eval: ${score} [${confidence}] · ${rationale}${warn}`;
 }
 
-/**
- * Build sessionMtimes from the sessions index — cheap best-effort.
- * Falls back to {} on any error.
- * @param {string} [cwd]
- * @returns {Record<string, number>}
- */
-function buildSessionMtimes(cwd) {
-  try {
-    const idx = readIndex(cwd);
-    const map = {};
-    for (const s of idx.sessions ?? []) {
-      if (!s.id) continue;
-      // prefer startedAt ms; fall back to 0 (neutral recency)
-      const ms = s.startedAt ? Date.parse(s.startedAt) : 0;
-      if (!isNaN(ms) && ms > 0) map[s.id] = ms;
-    }
-    return map;
-  } catch {
-    return {};
-  }
-}
-
-/** Collect proposals for a given adapter (mirrors review.mjs's facultyPending). */
-function collectProposals(agentDir, adapter) {
-  if (typeof adapter.listProposals === 'function') return adapter.listProposals(agentDir);
-  return spineListProposals(agentDir, adapter.name);
-}
-
 /**
  * Pure: gather + rank all pending proposals, returning structured data for JSON output.
  * The zuzuu-web /eval source.
@@ -77,7 +44,7 @@ export function evalData(agentDir, { faculty: onlyFaculty = null } = {}) {
   const allEntries = [];
   for (const adapter of adapters) {
     if (onlyFaculty && adapter.name !== onlyFaculty) continue;
-    const proposals = collectProposals(agentDir, adapter);
+    const proposals = facultyPending(agentDir, adapter);
     for (const proposal of proposals) {
       allEntries.push({ proposal, faculty: adapter.name });
     }

package/zuzuu/commands/explain.mjs

@@ -26,12 +26,12 @@ const FACULTY_CONTRACTS = {
     'Propose one with `zuzuu act propose <slug>` (lands in actions/inbox/); on approval ' +
     'it becomes an active action you can run with `zuzuu act <slug>`.',
   instructions:
-    'instructions — the directive faculty: who to BE. The pinned steering artifact ' +
-    '(instructions/project.md) that grounds every session. Empty by default — the ' +
+    'instructions — the directive faculty: who to BE. The pinned steering item ' +
+    '(instructions/items/steering.md) that grounds every session. Empty by default — the ' +
     'digest tells the agent to interview you and draft it for your approval.',
   guardrails:
-    'guardrails — the protective faculty: what NOT to do, ENFORCED. Rules in ' +
-    'guardrails/rules.json gate tool calls (deny > ask > allow) before they run. ' +
+    'guardrails — the protective faculty: what NOT to do, ENFORCED. One rule per item in ' +
+    'guardrails/items/ gates tool calls (deny > ask > allow) before they run. ' +
     'A refusal here is policy, not preference. The gate fails open — never breaks the host.',
 };
 

package/zuzuu/commands/faculty.mjs

@@ -0,0 +1,158 @@
+// zuzuu/commands/faculty.mjs — `zuzuu faculty` (W24 Faculty Standard + the
+// 2026-06-13 Faculty Module contract).
+//
+// The read surface over the one envelope format + the module contract:
+//   zuzuu faculty items <f> [--json|--jsonl]   list a faculty's envelope items
+//   zuzuu faculty schema <f> [--json]          print its payload schema
+//   zuzuu faculty manifest <f> [--json]        print its faculty.json manifest
+//   zuzuu faculty overview [--json]            ALL faculties in ONE process:
+//                                              manifest.ui + counts + top-3 item
+//                                              titles + pending counts (the
+//                                              daemon's batching endpoint)
+//
+// `--json` = one document; `--jsonl` = one item per line (streaming consumers).
+// Declarative faculties (manifest-only folders) are first-class here: items
+// list from manifest.itemsDir, schemas serve from the home, the overview and
+// digest include them. Fail-soft like everything on the serve path.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from '../core/store.mjs';
+import { listFacultyItems } from '../faculty/items.mjs';
+import { listProposals } from '../faculty/proposal.mjs';
+import { PAYLOAD_SCHEMAS, FACULTY_KINDS } from '../faculty/envelope.mjs';
+import { facultiesOf, facultyOf, get as getAdapter } from '../faculty/registry.mjs';
+
+/** Pure: one faculty's envelope items + parse errors (the --json document). */
+export function facultyItemsData(agentDir, faculty, manifest = null) {
+  const m = manifest ?? facultyOf(agentDir, faculty)?.manifest;
+  const { items, errors } = listFacultyItems(agentDir, faculty, { itemsDir: m?.itemsDir });
+  return { faculty, count: items.length, items, errors };
+}
+
+/**
+ * Pure: the payload schema served for a faculty — the home's seeded
+ * `<faculty>/schema.json` when present and parseable (humans may extend it),
+ * else the built-in default. Never throws.
+ */
+export function facultySchemaData(agentDir, faculty) {
+  const seeded = join(agentDir, faculty, 'schema.json');
+  if (existsSync(seeded)) {
+    try { return { faculty, source: 'home', schema: JSON.parse(readFileSync(seeded, 'utf8')) }; }
+    catch { /* fall through to the built-in */ }
+  }
+  return { faculty, source: 'builtin', schema: PAYLOAD_SCHEMAS[faculty] ?? null };
+}
+
+/**
+ * Pure: one faculty's manifest document (home faculty.json when present,
+ * built-in fallback), or null for an unknown faculty.
+ */
+export function facultyManifestData(agentDir, faculty) {
+  const entry = facultyOf(agentDir, faculty);
+  if (!entry) return null;
+  return {
+    faculty: entry.id,
+    source: entry.manifestSource,
+    declarative: entry.declarative,
+    ...(entry.manifestError ? { error: entry.manifestError } : {}),
+    manifest: entry.manifest,
+  };
+}
+
+/** Pending-proposal count for one faculty (dir-shaped adapters override). */
+function pendingCount(agentDir, entry) {
+  try {
+    const a = getAdapter(entry.id);
+    if (a && typeof a.listProposals === 'function') return a.listProposals(agentDir).length;
+    return listProposals(agentDir, entry.id).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Pure: the overview document — EVERY faculty (built-in + declarative) with
+ * manifest/ui, item + pending counts and the top-3 item titles, computed in
+ * ONE process (the web daemon's batching endpoint — kills 5-spawn cycles).
+ * Fail-soft per faculty: a broken one reports zeros + its manifestError.
+ */
+export function facultyOverviewData(agentDir) {
+  const faculties = facultiesOf(agentDir).map((entry) => {
+    let items = [], errors = [];
+    try {
+      ({ items, errors } = listFacultyItems(agentDir, entry.id, { itemsDir: entry.manifest?.itemsDir }));
+    } catch { /* unreadable → zeros */ }
+    return {
+      id: entry.id,
+      title: entry.manifest?.title ?? entry.id,
+      tagline: entry.manifest?.tagline ?? '',
+      ui: entry.manifest?.ui ?? {},
+      kinds: entry.manifest?.kinds ?? [],
+      declarative: entry.declarative,
+      ...(entry.manifestError ? { manifestError: entry.manifestError } : {}),
+      counts: { items: items.length, pending: pendingCount(agentDir, entry), errors: errors.length },
+      top: items.slice(0, 3).map((i) => i.title ?? i.id),
+    };
+  });
+  return { faculties };
+}
+
+/** `zuzuu faculty <sub> [<f>]` — items | schema | manifest | overview. */
+export function faculty(args = {}, log = console.log) {
+  const [sub, f] = args._ ?? [];
+  if (!sub || !['items', 'schema', 'manifest', 'overview'].includes(sub)) {
+    console.error('usage: zuzuu faculty items <faculty> [--json|--jsonl] · faculty schema <faculty> [--json] · faculty manifest <faculty> [--json] · faculty overview [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const agentDir = paths().dir;
+
+  if (sub === 'overview') {
+    const d = facultyOverviewData(agentDir);
+    if (args.json) { log(JSON.stringify(d, null, 2)); return; }
+    for (const fac of d.faculties) {
+      const pending = fac.counts.pending ? ` · ${fac.counts.pending} pending` : '';
+      const flag = fac.declarative ? ' [declarative]' : '';
+      log(`${fac.id.padEnd(13)} ${String(fac.counts.items).padStart(3)} item(s)${pending}${flag}${fac.manifestError ? `  ✗ ${fac.manifestError}` : ''}`);
+    }
+    return;
+  }
+
+  const entry = facultyOf(agentDir, f);
+  if (!entry) {
+    const known = facultiesOf(agentDir).map((x) => x.id);
+    console.error(`unknown faculty: ${f ?? '(none)'} — one of ${known.join(' · ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (sub === 'manifest') {
+    const d = facultyManifestData(agentDir, entry.id);
+    log(JSON.stringify(args.json ? d : d.manifest, null, 2));
+    return;
+  }
+
+  if (sub === 'schema') {
+    const { schema } = facultySchemaData(agentDir, entry.id);
+    log(JSON.stringify(schema, null, 2));
+    return;
+  }
+
+  const data = facultyItemsData(agentDir, entry.id, entry.manifest);
+  if (args.jsonl) {
+    for (const item of data.items) log(JSON.stringify(item));
+    return;
+  }
+  if (args.json) {
+    log(JSON.stringify(data, null, 2));
+    return;
+  }
+  const kinds = FACULTY_KINDS[entry.id] ?? (entry.declarative && entry.manifest?.kinds?.length ? entry.manifest.kinds : null);
+  log(`${entry.id} — ${data.count} item(s)${kinds ? ` [${kinds.join('|')}]` : ''}`);
+  for (const it of data.items) {
+    log(`  ${it.id}  ${it.kind} · ${it.status ?? 'active'} — ${it.title}`);
+  }
+  for (const e of data.errors) log(`  ✗ ${e.file}: ${e.error}`);
+  if (!data.count && !data.errors.length) log('  (none yet)');
+}

package/zuzuu/commands/generation.mjs

@@ -4,10 +4,9 @@
 //   zuzuu generation mint             manually mint a generation from the current faculty state
 //   zuzuu generation rollback <id>    restore a past generation by content (flip active + restore)
 
-import { paths, repoRoot } from '../store.mjs';
-import {
-  listGenerations, readGeneration, activeGeneration, mintGeneration, rollback, diffGenerations,
-} from '../faculty/generation.mjs';
+import { paths, repoRoot } from '../core/store.mjs';
+import { listGenerations, readGeneration, activeGeneration, diffGenerations } from '../faculty/generation/read.mjs';
+import { mintGeneration, rollback } from '../faculty/generation/write.mjs';
 
 function agentDir() {
   return paths(repoRoot(process.cwd())).dir;
@@ -86,7 +85,8 @@ export function showLines(dir, id) {
   lines.push(`  forkedFrom: ${d.forkedFrom ?? '(none — first generation)'}`);
   lines.push(`  mintedFrom: ${d.mintedFrom.length} proposal(s)`);
   lines.push('  changes vs parent:');
-  for (const f of ['knowledge', 'actions', 'memory']) {
+  // all five faculties are envelope-item lists under the Faculty Standard (W24)
+  for (const f of ['knowledge', 'actions', 'memory', 'guardrails', 'instructions']) {
     const x = d.faculties[f] || { added: [], changed: [], removed: [] };
     const parts = [];
     if (x.added.length) parts.push(`+${x.added.length} added`);
@@ -95,9 +95,6 @@ export function showLines(dir, id) {
     if (f === 'knowledge' && x.registryChanged) parts.push('registry changed');
     lines.push(`    ${f}: ${parts.length ? parts.join(' · ') : 'no change'}`);
   }
-  for (const f of ['guardrails', 'instructions']) {
-    lines.push(`    ${f}: ${d.faculties[f]?.changed ? 'changed' : 'no change'}`);
-  }
   return lines.join('\n');
 }
 

package/zuzuu/commands/hook.mjs

@@ -14,14 +14,14 @@
 import { readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 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';
 import { openLive, touchLive, closeLive, updateLive } from '../live/live-store.mjs';
-import { sessionGitEnabled, openSession, checkpoint, closeSession } from '../session-git.mjs';
-import { loadRules, evaluate, toPreToolUseDecision, toGeminiDecision } from '../guardrails.mjs';
-import { paths, liveDir as liveDirOf } from '../store.mjs';
-import { computeDigest } from '../digest.mjs';
-import { activeGeneration } from '../faculty/generation.mjs';
+import { sessionGitEnabled, openSession, checkpoint, closeSession } from '../sessions/session-git.mjs';
+import { loadRules, evaluate, toPreToolUseDecision, toGeminiDecision } from '../guardrails/engine.mjs';
+import { paths, liveDir as liveDirOf } from '../core/store.mjs';
+import { computeDigest } from '../digest/compose.mjs';
+import { activeGeneration } from '../faculty/generation/read.mjs';
 
 // Lifecycle events, normalized across hosts (verified by observing each host):
 //   open  — session starts
@@ -110,8 +110,9 @@ export function handleHook({ event, payload = {}, cwd = process.cwd(), now = Dat
 }
 
 /**
- * The Guardrails gate (PreToolUse). Evaluates the tool call against
- * .zuzuu/guardrails/rules.json and prints Claude's hookSpecificOutput decision —
+ * The Guardrails gate (PreToolUse). Evaluates the tool call against the
+ * envelope rule items in .zuzuu/guardrails/items/ and prints Claude's
+ * hookSpecificOutput decision —
  * or NOTHING (exit 0, no JSON = defer to the host's normal permission flow).
  * That silence is the fail-open: engine errors and rule-file problems can slow
  * nothing down and block nothing. Matched decisions are logged for the trace.
@@ -127,14 +128,15 @@ function guardrailsLogName(sessionId) {
 const GATE_EVENTS = new Set(['PreToolUse', 'BeforeTool']);
 
 /**
- * Evaluate a tool call against rules.json and return the host's block decision
- * (or null = fail-open / no match → host's normal flow). Logs matched decisions.
+ * Evaluate a tool call against the guardrail rule items and return the host's
+ * block decision (or null = fail-open / no match → host's normal flow). Logs
+ * matched decisions.
  *   codex + claude-code → hookSpecificOutput · gemini-cli → {decision,reason}
  */
 export function gateDecision({ host = 'claude-code', payload = {}, cwd = process.cwd() } = {}) {
   try {
     const { dir } = paths(cwd);
-    const loaded = loadRules(join(dir, 'guardrails', 'rules.json'));
+    const loaded = loadRules(join(dir, 'guardrails'));
     if (!loaded.ok) return null;
     const verdict = evaluate(loaded.rules, { tool: payload.tool_name, input: payload.tool_input });
     if (verdict) {

package/zuzuu/commands/inbox.mjs

@@ -5,15 +5,10 @@
 // points at `zuzuu review`. Fail-soft per faculty — a broken adapter or unreadable
 // proposal never sinks the whole view.
 
-import { paths } from '../store.mjs';
+import { paths } from '../core/store.mjs';
 import { FACULTIES } from '../faculty/contract.mjs';
 import { listProposals } from '../faculty/proposal.mjs';
 import * as registry from '../faculty/registry.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
 
 /** Best-effort one-line title for a proposal (adapter.render → payload → id). */
 function titleOf(faculty, p) {

package/zuzuu/commands/init.mjs

@@ -12,11 +12,12 @@
 
 import { join, basename } from 'node:path';
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { applyScaffold, ensureGitignore, homeExists } from '../scaffold.mjs';
-import { injectBlock, facultiesBlock, hasBlock, BLOCK_VERSION } from '../inject.mjs';
+import { applyScaffold, ensureGitignore, homeExists } from '../home/scaffold.mjs';
+import { injectBlock, facultiesBlock, hasBlock, BLOCK_VERSION } from '../home/inject.mjs';
 import { detected } from '../capture/adapters/registry.mjs';
-import { repoRoot } from '../store.mjs';
-import { migrateHome } from './migrate.mjs';
+import { repoRoot } from '../core/store.mjs';
+import { migrateHome } from './migrations/home.mjs';
+import { migrateItems, needsItemsMigration } from './migrations/items.mjs';
 
 const HOST_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
 // dotfiles/dirs that don't make a directory "a project" for emptiness purposes
@@ -80,6 +81,19 @@ export function init(args = {}) {
     }
   } catch { /* fail-open */ }
 
+  // One-shot items migration (W24): pre-standard faculty shapes (rules.json /
+  // project.md / action.json / legacy item frontmatter) become Faculty Standard
+  // envelopes. Gated on detection, idempotent, fail-open — like migrateHome.
+  try {
+    const home = join(cwd, '.zuzuu');
+    if (existsSync(home) && needsItemsMigration(home)) {
+      const r = migrateItems(home);
+      const total = r.knowledge + r.memory + r.guardrails + r.actions + r.instructions;
+      if (total) console.log(`Migrated ${total} faculty item(s) to the envelope standard (knowledge ${r.knowledge} · memory ${r.memory} · guardrails ${r.guardrails} · actions ${r.actions} · instructions ${r.instructions})`);
+      for (const e of r.errors) console.log(`  ✗ ${e.file}: ${e.error} — left in place; fix and rerun \`zuzuu migrate --items\``);
+    }
+  } catch { /* fail-open */ }
+
   const reinit = homeExists(cwd);
   const greenfield = !reinit && isEmptyDir(cwd);
 

package/zuzuu/commands/knowledge.mjs

@@ -1,7 +1,7 @@
 // Knowledge CLI: `zuzuu remember` (human-direct write — the human IS the gate),
 // `zuzuu recall` (one command, three search modes), `zuzuu knowledge reindex|audit`.
 
-import { paths } from '../store.mjs';
+import { paths } from '../core/store.mjs';
 import { loadRegistry, validateItem } from '../knowledge/registry.mjs';
 import { slugify, writeItem, readItem, allItems } from '../knowledge/items.mjs';
 import { upsertItem, reindex, search, neighbors, indexPath, putVector, allVectors, unembedded } from '../knowledge/index.mjs';

package/zuzuu/commands/migrations/home.mjs

@@ -0,0 +1,96 @@
+// zuzuu/commands/migrations/home.mjs — the home migrator (W1, 2026-06-12):
+// visible agent/ → hidden .zuzuu/ (byte-identical inner layout), plus the
+// follow-ups: traceRef rewrite, gitignore + deny-rule swap, host-block re-inject.
+// Pure core: migrateHome(root) → { migrated }. Idempotent + fail-soft.
+
+import { existsSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot } from '../../core/store.mjs';
+import { ensureGitignore } from '../../home/scaffold.mjs';
+import { injectBlock, BLOCK_VERSION } from '../../home/inject.mjs';
+
+// The denies the old visible-agent/ home installed; scrubbed here (NOT kept in
+// install.mjs — clean break) and replaced by the current narrow .zuzuu/ pair.
+const LEGACY_DENY_RULES = ['Read(./agent/.traces/**)', 'Read(./agent/.live/**)'];
+const NEW_DENY_RULES = ['Read(./.zuzuu/.traces/**)', 'Read(./.zuzuu/.live/**)'];
+
+/**
+ * One-shot HOME migration: visible `agent/` → hidden `.zuzuu/` (byte-identical
+ * inner layout). Gated on `agent/agent.json` — `agent/` is a common dir name,
+ * so an unrelated agent/ dir in a brownfield repo must NEVER be touched (the
+ * one place this differs from the old `.mns→agent` precedent). Idempotent +
+ * fail-soft; NEVER clobbers an existing .zuzuu/. Pure FS move (renameSync).
+ * @returns {{migrated: boolean}}
+ */
+export function migrateHome(root = repoRoot()) {
+  const legacy = join(root, 'agent');
+  const home = join(root, '.zuzuu');
+  if (existsSync(home) || !existsSync(join(legacy, 'agent.json'))) return { migrated: false };
+
+  renameSync(legacy, home); // move the whole home (atomic on same filesystem)
+
+  rewriteTraceRefs(home);
+  rewriteGitignore(root);
+  scrubLegacyDenies(root);
+  // derived index: drop, it rebuilds on the next recall/reindex
+  try { rmSync(join(home, 'knowledge', '.index.db'), { force: true }); } catch { /* fail-soft */ }
+  return { migrated: true };
+}
+
+/** sessions.json stores repo-relative traceRefs (`agent/.traces/…`) — re-point them. */
+function rewriteTraceRefs(home) {
+  const index = join(home, 'sessions.json');
+  if (!existsSync(index)) return;
+  try {
+    const idx = JSON.parse(readFileSync(index, 'utf8'));
+    for (const s of idx.sessions || []) {
+      if (typeof s.traceRef === 'string' && s.traceRef.startsWith('agent/')) {
+        s.traceRef = '.zuzuu/' + s.traceRef.slice('agent/'.length);
+      }
+    }
+    writeFileSync(index, JSON.stringify(idx, null, 2) + '\n');
+  } catch { /* fail-soft: a bad index never blocks the move */ }
+}
+
+/** Drop legacy `agent/` ignore lines, then append the canonical .zuzuu/ ones. */
+function rewriteGitignore(root) {
+  const path = join(root, '.gitignore');
+  if (existsSync(path)) {
+    const kept = readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((l) => !l.trim().startsWith('agent/'))
+      .join('\n');
+    writeFileSync(path, kept.endsWith('\n') || kept === '' ? kept : kept + '\n');
+  }
+  ensureGitignore(root); // appends .zuzuu/.traces/, .zuzuu/.live/, .zuzuu/knowledge/.index.db
+}
+
+/** Swap the old agent/ deny rules for the .zuzuu/ pair in any .claude settings file. */
+function scrubLegacyDenies(root) {
+  for (const f of ['settings.json', 'settings.local.json']) {
+    const path = join(root, '.claude', f);
+    if (!existsSync(path)) continue;
+    try {
+      const s = JSON.parse(readFileSync(path, 'utf8'));
+      const deny = s?.permissions?.deny;
+      if (!Array.isArray(deny)) continue;
+      const hadOurs = deny.some((r) => LEGACY_DENY_RULES.includes(r));
+      if (!hadOurs) continue;
+      s.permissions.deny = deny.filter((r) => !LEGACY_DENY_RULES.includes(r));
+      for (const rule of NEW_DENY_RULES) if (!s.permissions.deny.includes(rule)) s.permissions.deny.push(rule);
+      writeFileSync(path, JSON.stringify(s, null, 2) + '\n');
+    } catch { /* fail-soft: never break settings we can't parse */ }
+  }
+}
+
+/** Re-inject the current faculties block into any existing host instruction files. */
+export function reinjectHostBlocks(root) {
+  for (const f of ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
+    const p = join(root, f);
+    if (existsSync(p)) {
+      const text = readFileSync(p, 'utf8');
+      if (!text.includes(`zuzuu:faculties:v${BLOCK_VERSION}`)) writeFileSync(p, injectBlock(text));
+    }
+  }
+}
+

package/zuzuu/commands/migrations/index.mjs

@@ -0,0 +1,48 @@
+// zuzuu/commands/migrations/index.mjs — `zuzuu migrate` dispatch.
+//
+//   (default)  proposal schema: legacy {candidate, er} → spine {payload, analysis, faculty}
+//   --home     faculty home: visible agent/ → hidden .zuzuu/
+//   --items    Faculty Standard: legacy faculty shapes → the envelope standard
+//
+// Pure cores live beside this file (proposals/home/items.mjs); this is the CLI
+// surface — resolves paths, runs a core, prints the summary.
+
+import { paths, repoRoot } from '../../core/store.mjs';
+import { BLOCK_VERSION } from '../../home/inject.mjs';
+import { migrateProposals } from './proposals.mjs';
+import { migrateHome, reinjectHostBlocks } from './home.mjs';
+import { migrateItems, needsItemsMigration } from './items.mjs';
+
+export { migrateProposals } from './proposals.mjs';
+export { migrateHome } from './home.mjs';
+export { migrateItems, needsItemsMigration } from './items.mjs';
+
+export function migrate(args = {}) {
+  if (args.items) {
+    const agentDir = paths().dir;
+    const r = migrateItems(agentDir);
+    const total = r.knowledge + r.memory + r.guardrails + r.actions + r.instructions;
+    console.log(`migrate --items: ${total} item(s) → the Faculty Standard envelope — knowledge ${r.knowledge} · memory ${r.memory} · guardrails ${r.guardrails} · actions ${r.actions} · instructions ${r.instructions} (${r.skipped} already standard)`);
+    if (r.manifests) console.log(`  seeded ${r.manifests} faculty manifest(s) (faculty.json — the Faculty Module contract)`);
+    for (const e of r.errors) console.log(`  ✗ ${e.file}: ${e.error}`);
+    if (!total && !r.manifests && !r.errors.length) console.log('  nothing to migrate (the home already speaks the envelope)');
+    return;
+  }
+  if (args.home) {
+    const root = repoRoot(process.cwd());
+    const { migrated } = migrateHome(root);
+    if (!migrated) { console.log('migrate --home: nothing to do (already .zuzuu/, or no zuzuu home at agent/)'); return; }
+    try { reinjectHostBlocks(root); } catch { /* fail-open */ }
+    console.log(`migrate --home: agent/ → .zuzuu/ (hidden, like .git; block v${BLOCK_VERSION}, gitignore + deny rules rewritten)`);
+    console.log('  transparency lives in porcelain now: zuzuu status · explain · digest');
+    return;
+  }
+  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)');
+  }
+}