@zuzuucodes/cli 1.4.0 → 1.6.0

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/engine.mjs

@@ -0,0 +1,137 @@
+// The Guardrails faculty — v1 rule engine (pure; I/O lives in the hook command).
+//
+// Rules are DATA, not code: one envelope item per rule under
+// .zuzuu/guardrails/items/<id>.md (the Faculty Standard, W24) — *definitions*
+// in the pin-definitions sense (versioned in git, graduate via proposals like
+// every faculty's contents).
+//
+//   ---
+//   id: no-root-wipe
+//   faculty: guardrails
+//   kind: rule
+//   title: …
+//   payload:
+//     action: deny              # deny | ask | allow
+//     tool: Bash                # exact tool name, or "*"
+//     pattern: "rm\\s+-rf\\s+/" # regex over the tool INPUT (stringified)
+//     reason: destructive root delete
+//   ---
+//   (optional rationale prose)
+//
+// Evaluation: collect every matching rule, then severity wins — deny > ask >
+// allow (an explicit allow can whitelist past a later ask/deny only if it is
+// NOT outweighed; severity beats file order so a sloppy rule ordering can never
+// silently disarm a deny).
+//
+// FAIL-OPEN, per item: a malformed rule file is SKIPPED (and counted in
+// `skipped`), never a crash and never a block — the other rules still apply.
+// The gate runs per tool call, so loads are cached on the items dir's stat
+// signature (names+mtimes+sizes): re-parse only when something changed. No
+// derived file — the item files stay the single source of truth.
+
+import { join } from 'node:path';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { parseEnvelope } from '../faculty/envelope.mjs';
+
+const SEVERITY = { deny: 3, ask: 2, allow: 1 };
+const ACTIONS = new Set(Object.keys(SEVERITY));
+
+// dir → { sig, result } — tiny in-memory cache (per process; the spawned gate
+// pays one cold load, long-lived processes like `zuzuu web` skip re-parses).
+const cache = new Map();
+
+/** Compile one parsed envelope item into a rule, or null if malformed. */
+function compileRule(item) {
+  const p = item?.payload ?? {};
+  if (!item?.id || !ACTIONS.has(p.action) || typeof p.pattern !== 'string' || !p.pattern) return null;
+  try {
+    return { id: String(item.id), action: p.action, tool: p.tool || '*', re: new RegExp(p.pattern, 'i'), reason: String(p.reason ?? '') };
+  } catch {
+    return null; // uncompilable pattern → skip this rule only
+  }
+}
+
+/**
+ * Load the rules from a guardrails faculty dir (…/guardrails) by composing the
+ * envelope items under its items/ subdir. FAIL-OPEN: a missing dir is zero
+ * rules; a malformed item is skipped + counted, never a crash.
+ * @param {string} guardrailsDir  the faculty dir (e.g. <home>/guardrails)
+ * @returns {{ok: boolean, rules: Array, skipped: Array<{file: string, error: string}>}}
+ */
+export function loadRules(guardrailsDir) {
+  try {
+    const dir = join(guardrailsDir, 'items');
+    let names;
+    try {
+      names = readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+    } catch {
+      return { ok: true, rules: [], skipped: [] }; // no items dir → no rules (normal flow)
+    }
+    let sig = null;
+    try {
+      sig = names.map((n) => { const s = statSync(join(dir, n)); return `${n}:${s.mtimeMs}:${s.size}`; }).join('|');
+      const hit = cache.get(dir);
+      if (hit && hit.sig === sig) return hit.result;
+    } catch { sig = null; /* stat race → just load uncached */ }
+
+    const rules = [];
+    const skipped = [];
+    for (const f of names) {
+      try {
+        const { ok, item, errors } = parseEnvelope(readFileSync(join(dir, f), 'utf8'));
+        const rule = ok ? compileRule(item) : null;
+        if (rule) rules.push(rule);
+        else skipped.push({ file: f, error: ok ? 'malformed rule payload' : (errors[0] ?? 'parse error') });
+      } catch (e) {
+        skipped.push({ file: f, error: e.message });
+      }
+    }
+    const result = { ok: true, rules, skipped };
+    if (sig != null) cache.set(dir, { sig, result });
+    return result;
+  } catch (e) {
+    return { ok: false, rules: [], skipped: [], error: e.message }; // engine trouble → fail open
+  }
+}
+
+/**
+ * Evaluate a tool call against loaded rules.
+ * @param {Array} rules        from loadRules().rules
+ * @param {{tool:string, input:any}} call
+ * @returns {null | {action:'deny'|'ask'|'allow', rule:string, reason:string}}
+ *          null = no rule matched → defer to the host's normal permission flow
+ */
+export function evaluate(rules, { tool, input }) {
+  const haystack = typeof input === 'string' ? input : JSON.stringify(input ?? {});
+  let winner = null;
+  for (const r of rules) {
+    if (r.tool !== '*' && r.tool !== tool) continue;
+    if (!r.re.test(haystack)) continue;
+    if (!winner || SEVERITY[r.action] > SEVERITY[winner.action]) {
+      winner = { action: r.action, rule: r.id, reason: r.reason || `matched guardrail ${r.id}` };
+    }
+  }
+  return winner;
+}
+
+/**
+ * Gemini CLI block shape: stdout JSON { decision: "deny", reason } (exit 0).
+ * Gemini has no "ask" decision → defer (null) so its own approval flow runs.
+ * Only an explicit deny blocks.
+ */
+export function toGeminiDecision(verdict) {
+  if (!verdict || verdict.action !== 'deny') return null;
+  return { decision: 'deny', reason: `guardrail ${verdict.rule}: ${verdict.reason}` };
+}
+
+/** Map a verdict to Claude Code's PreToolUse hookSpecificOutput (verified schema). */
+export function toPreToolUseDecision(verdict) {
+  if (!verdict || verdict.action === 'allow') return null; // no output → normal flow (fail-open / explicit allow)
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: verdict.action, // 'deny' | 'ask'
+      permissionDecisionReason: `guardrail ${verdict.rule}: ${verdict.reason}`,
+    },
+  };
+}

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

@@ -15,9 +15,15 @@
 
 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 { 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 = 3;
+export const MANIFEST_VERSION = 4;
+
+// Deterministic seed timestamp (the Faculty Standard date) — seeds are pinned
+// definitions, so idempotent re-inits must produce byte-identical files.
+const SEED_AT = '2026-06-12T00:00:00Z';
 
 const AGENT_README = `# .zuzuu/ — your agent's home (hidden, like .git — yours to read & version)
 
@@ -70,17 +76,23 @@ Curated recollections of past sessions, distilled from the observability traces
 - **Who writes:** zuzuu (distillation — *not built yet*), human (curation). Raw traces stay in traces/ — this is the *curated* layer.
 - **Where:** one Markdown file per entry under \`entries/\`, named \`<id>.md\`.
 
-## Record schema (Markdown + YAML frontmatter)
+## Record schema (the Faculty Standard envelope)
 \`\`\`markdown
 ---
 id: mem-2026-06-11-flaky-ci-retry      # mem-<YYYY-MM-DD>-<slug>, stable
-date: 2026-06-11                        # ISO date the episode occurred
+faculty: memory
+kind: episode
 title: Flaky CI fixed by pinning node 22
-provenance:                            # links back to observability
-  sessions: [ses_abc123]               # ids that exist in .zuzuu/sessions.json
-  hosts: [claude-code]
-tags: [ci, flaky-test]                 # optional
-status: curated                        # curated (human) | proposed (reserved — future distiller)
+status: active
+created_at: 2026-06-11                 # ISO date the episode occurred
+payload:
+  sessions:                            # ids that exist in .zuzuu/sessions.json
+    - ses_abc123
+  hosts:
+    - claude-code
+  tags:                                # optional
+    - ci
+    - flaky-test
 ---
 ## Attempted
 What was tried.
@@ -89,7 +101,6 @@ What happened (outcome / error / fix).
 ## Remember next time
 The durable lesson.
 \`\`\`
-\`status: proposed\` and the distiller→review pipeline are **reserved** (not built this pass).
 `;
 
 const ACTIONS_README = `# actions/ — procedural faculty (how to DO things)
@@ -104,55 +115,115 @@ const INSTRUCTIONS_README = `# instructions/ — the Instructions faculty (direc
 
 Cognition steering: identity, conventions, priorities — the project-level seed of
 the pinned system prompt. The host agent reads and follows this.
-- \`project.md\` — project-specific steering (what this is, conventions, priorities).
+- \`items/steering.md\` — the pinned steering item (what this is, conventions, priorities).
+- Approved amendments land as further items in \`items/\` (kind: amendment).
 - Hard *enforced* rules live in \`../guardrails/\` (a separate faculty), not here.
 `;
 
-const PROJECT_SEED = `# Project steering
-
-<!-- Fill in: what this project is, conventions, priorities. The host agent reads this. -->
-`;
+const STEERING_SEED = serializeEnvelope({
+  id: 'steering',
+  faculty: 'instructions',
+  kind: 'steering',
+  title: 'Project steering',
+  status: 'active',
+  created_at: SEED_AT,
+  payload: { scope: 'project' },
+  body: '<!-- Fill in: what this project is, conventions, priorities. The host agent reads this. -->',
+});
 
 const GUARDRAILS_README = `# guardrails/ — the Guardrails faculty (enforced, not advisory)
 
-Declarative rules in \`rules.json\`, evaluated on every tool call by the zuzuu
-PreToolUse gate (installed by \`zuzuu enable\`). Severity wins: deny > ask > allow;
-no match → the host's normal permission flow. The engine FAILS OPEN — a
-guardrail bug can block nothing — and matched decisions are logged for the trace.
-
-Rule shape: \`{ id, action: deny|ask|allow, tool: "Bash"|"*", pattern: <regex
-over the tool input>, reason }\`. Edit, commit, done — rules are definitions,
+One rule per envelope item in \`items/\` (markdown + frontmatter; payload =
+\`{ action: deny|ask|allow, tool: "Bash"|"*", pattern: <regex over the tool
+input>, reason }\`; the body is optional rationale prose). Every tool call is
+evaluated by the zuzuu PreToolUse gate (installed by \`zuzuu enable\`). Severity
+wins: deny > ask > allow; no match → the host's normal permission flow. The
+engine FAILS OPEN — a malformed item is skipped, never a block — and matched
+decisions are logged for the trace. Edit, commit, done — rules are definitions,
 versioned in git like everything else.
 `;
 
-const RULES_SEED =
-  JSON.stringify(
-    {
-      version: 1,
-      rules: [
-        { id: 'no-root-wipe', action: 'deny', tool: 'Bash', pattern: 'rm\\s+-[a-z]*r[a-z]*\\s+/(\\s|$)', reason: 'destructive delete at filesystem root' },
-        { id: 'no-secret-reads', action: 'deny', tool: '*', pattern: '\\.env(\\.|\\b)|id_rsa|\\.pem\\b', reason: 'secret material should not enter the context' },
-        // \b.*\bpush, not push adjacent to git: a real session bypassed the
-        // adjacent form with `git -C /path push --force-with-lease` (exp-8).
-        { id: 'confirm-force-push', action: 'ask', tool: 'Bash', pattern: 'git\\b.*\\bpush\\b.*--force', reason: 'force-push rewrites shared history' },
-      ],
+/** Seeded rules, one envelope item each (the Faculty Standard, W24). */
+const ruleSeed = ({ id, title, action, tool, pattern, reason, body }) =>
+  serializeEnvelope({
+    id, faculty: 'guardrails', kind: 'rule', title, status: 'active', created_at: SEED_AT,
+    payload: { action, tool, pattern, reason }, body,
+  });
+
+const RULE_SEEDS = {
+  'no-root-wipe': ruleSeed({
+    id: 'no-root-wipe', title: 'No destructive delete at filesystem root', action: 'deny', tool: 'Bash',
+    pattern: 'rm\\s+-[a-z]*r[a-z]*\\s+/(\\s|$)', reason: 'destructive delete at filesystem root',
+    body: 'Blocks `rm -rf /` and flag-order variants targeting the filesystem root.',
+  }),
+  'no-secret-reads': ruleSeed({
+    id: 'no-secret-reads', title: 'No reading secret material', action: 'deny', tool: '*',
+    pattern: '\\.env(\\.|\\b)|id_rsa|\\.pem\\b', reason: 'secret material should not enter the context',
+    body: 'Keys and env files must not enter the model context — across every tool, not just Bash.',
+  }),
+  'confirm-force-push': ruleSeed({
+    id: 'confirm-force-push', title: 'Confirm before force-push', action: 'ask', tool: 'Bash',
+    pattern: 'git\\b.*\\bpush\\b.*--force', reason: 'force-push rewrites shared history',
+    // \b.*\bpush, not push adjacent to git: a real session bypassed the
+    // adjacent form with `git -C /path push --force-with-lease` (exp-8).
+    body: 'Asks (never blocks) on any force-push. The loose `git\\b.*\\bpush` form catches the real exp-8 bypass: `git -C /path push --force-with-lease`.',
+  }),
+};
+
+/** Envelope spec seed (.zuzuu/schema.json) — descriptive, for humans + tools. */
+const ENVELOPE_SPEC = JSON.stringify(
+  {
+    standard: 'zuzuu-faculty-envelope',
+    version: 1,
+    description: 'One file per item: markdown body + strict frontmatter. One rigid envelope across all five faculties; payload is faculty-typed and validated by <faculty>/schema.json.',
+    envelope: {
+      id: 'required — slug [a-z0-9-]',
+      faculty: 'required — knowledge|memory|actions|instructions|guardrails',
+      kind: 'required — per-faculty kinds (see kinds)',
+      title: 'required — single line',
+      status: 'active|archived (default active)',
+      created_at: 'required — ISO date/datetime',
+      updated_at: 'optional — ISO date/datetime',
+      provenance: 'optional list of {session, ref}',
+      payload: 'faculty-typed machine fields (see <faculty>/schema.json)',
     },
-    null,
-    2,
-  ) + '\n';
+    kinds: { ...FACULTY_KINDS, knowledge: 'registry-governed (knowledge/registry/types.json)' },
+  },
+  null,
+  2,
+) + '\n';
+
+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/inbox', '.zuzuu/instructions/proposals', '.zuzuu/guardrails', '.zuzuu/guardrails/inbox', '.zuzuu/guardrails/proposals', '.zuzuu/generations', '.zuzuu/generations/snapshots'],
+  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'],
   files: {
     '.zuzuu/README.md': AGENT_README,
+    '.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/project.md': PROJECT_SEED,
+    '.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/rules.json': RULES_SEED,
+    '.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'],
     '.zuzuu/knowledge/registry/types.json': JSON.stringify(SEED_TYPES, null, 2) + '\n',
     '.zuzuu/knowledge/registry/attributes.json': JSON.stringify(SEED_ATTRIBUTES, null, 2) + '\n',
     '.zuzuu/knowledge/registry/relations.json': JSON.stringify(SEED_RELATIONS, null, 2) + '\n',

package/zuzuu/knowledge/items.mjs

@@ -1,31 +1,35 @@
-// Knowledge items — files as truth. One item per markdown file under
-// .zuzuu/knowledge/items/<id>.md: a constrained-YAML frontmatter (we control both
-// writer and reader; grammar below) + a prose body (the fact in your voice).
+// Knowledge items — files as truth, in the Faculty Standard envelope (W24).
+// One item per markdown file under .zuzuu/knowledge/items/<id>.md:
 //
 //   ---
 //   id: test-command
-//   type: command
-//   created_at: 2026-06-10T12:00:00Z
+//   faculty: knowledge
+//   kind: command
+//   title: The test command
 //   status: active
-//   attributes:
-//     command: npm test
-//   relations:
-//     - type: relates-to
-//       target: ci-pipeline
-//       commentary: optional
+//   created_at: 2026-06-10T12:00:00Z
 //   provenance:
 //     - session: ses_abc
 //       ref: occurrences=12
+//   payload:
+//     type: command
+//     attributes:
+//       command: npm test
+//     relations:
+//       - type: relates-to
+//         target: ci-pipeline
 //   ---
 //   Body prose.
 //
-// Grammar (deliberately small): top-level scalar keys; ONE nested map
-// (`attributes`); arrays of flat maps (`relations`, `provenance`). Values are
-// single-line strings (quotes optional). Anything outside this grammar is a
-// parse error — git-diffable simplicity beats YAML completeness here.
+// This module is a thin wrapper over faculty/envelope.mjs: the ON-DISK format
+// is the envelope; the IN-MEMORY item shape stays the historical knowledge one
+// ({id, type, created_at, status, attributes, relations, provenance, body}) so
+// the registry/ER/index/digest pipeline is untouched. Ids are unchanged by the
+// standard — only frontmatter keys moved (type/attributes/relations → payload).
 
 import { join } from 'node:path';
 import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { parseEnvelope, serializeEnvelope, deriveTitle } from '../faculty/envelope.mjs';
 
 export const itemsDir = (agentDir) => join(agentDir, 'knowledge', 'items');
 
@@ -38,88 +42,49 @@ export function slugify(text, max = 60) {
     .replace(/-+$/, '') || 'item';
 }
 
-const unquote = (s) => {
-  const t = s.trim();
-  return (t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")) ? t.slice(1, -1) : t;
-};
-const quoteIfNeeded = (s) => {
-  const t = String(s);
-  if (t.includes('\n')) throw new Error('item values must be single-line');
-  return /[:#'"\[\]{}]|^\s|\s$/.test(t) ? JSON.stringify(t) : t;
-};
-
-/** Parse an item file's text → item object. Throws on grammar violations. */
+/**
+ * Parse an item file's text → the in-memory knowledge item. Throws on grammar
+ * violations (callers catch — allItems collects, inbox falls back to prose).
+ */
 export function parseItem(text) {
-  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!m) throw new Error('no frontmatter block');
-  const [, fm, body] = m;
-  const item = { attributes: {}, relations: [], provenance: [], body: body.trim() };
-  let section = null; // 'attributes' | 'relations' | 'provenance'
-  let current = null; // current array entry
-  for (const raw of fm.split('\n')) {
-    if (!raw.trim()) continue;
-    const indent = raw.match(/^ */)[0].length;
-    const line = raw.trim();
-    if (indent === 0) {
-      current = null;
-      const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
-      if (!kv) throw new Error(`bad line: ${line}`);
-      const [, key, val] = kv;
-      if (['attributes', 'relations', 'provenance'].includes(key)) {
-        section = key;
-        if (val) throw new Error(`${key} must be a block`);
-      } else {
-        section = null;
-        item[key] = unquote(val);
-      }
-    } else if (section === 'attributes') {
-      const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
-      if (!kv) throw new Error(`bad attribute line: ${line}`);
-      item.attributes[kv[1]] = unquote(kv[2]);
-    } else if (section === 'relations' || section === 'provenance') {
-      if (line.startsWith('- ')) {
-        current = {};
-        item[section].push(current);
-        const kv = line.slice(2).match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
-        if (!kv) throw new Error(`bad ${section} entry: ${line}`);
-        current[kv[1]] = unquote(kv[2]);
-      } else {
-        if (!current) throw new Error(`${section} entry continuation without "-": ${line}`);
-        const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
-        if (!kv) throw new Error(`bad ${section} line: ${line}`);
-        current[kv[1]] = unquote(kv[2]);
-      }
-    } else {
-      throw new Error(`unexpected indented line: ${line}`);
-    }
-  }
-  if (!item.id) throw new Error('item missing id');
+  const { ok, item: env, errors } = parseEnvelope(text);
+  if (!ok) throw new Error(errors[0] ?? 'invalid envelope');
+  if (env.faculty !== 'knowledge') throw new Error(`not a knowledge item (faculty: ${env.faculty})`);
+  const p = env.payload ?? {};
+  const item = {
+    attributes: p.attributes ?? {},
+    relations: p.relations ?? [],
+    provenance: env.provenance ?? [],
+    body: env.body,
+  };
+  item.id = env.id;
+  item.type = p.type ?? env.kind;
+  if (env.created_at != null) item.created_at = env.created_at;
+  if (env.updated_at != null) item.updated_at = env.updated_at;
+  if (env.status != null) item.status = env.status;
   if (!item.type) throw new Error('item missing type');
   return item;
 }
 
-/** Serialize an item object → file text (the exact grammar parseItem reads). */
+/** Serialize an in-memory knowledge item → envelope file text. */
 export function serializeItem(item) {
-  const lines = ['---'];
-  for (const key of ['id', 'type', 'created_at', 'status']) {
-    if (item[key] != null) lines.push(`${key}: ${quoteIfNeeded(item[key])}`);
-  }
-  const attrs = Object.entries(item.attributes ?? {});
-  if (attrs.length) {
-    lines.push('attributes:');
-    for (const [k, v] of attrs) lines.push(`  ${k}: ${quoteIfNeeded(v)}`);
-  }
-  for (const section of ['relations', 'provenance']) {
-    const arr = item[section] ?? [];
-    if (!arr.length) continue;
-    lines.push(`${section}:`);
-    for (const entry of arr) {
-      const keys = Object.keys(entry);
-      keys.forEach((k, i) => lines.push(`  ${i === 0 ? '- ' : '  '}${k}: ${quoteIfNeeded(entry[k])}`));
-    }
-  }
-  lines.push('---', '');
-  return lines.join('\n') + (item.body ? item.body.trim() + '\n' : '');
+  if (!item.id) throw new Error('item missing id');
+  if (!item.type) throw new Error('item missing type');
+  const payload = { type: item.type };
+  if (Object.keys(item.attributes ?? {}).length) payload.attributes = item.attributes;
+  if ((item.relations ?? []).length) payload.relations = item.relations;
+  return serializeEnvelope({
+    id: item.id,
+    faculty: 'knowledge',
+    kind: item.type,
+    title: item.title ?? deriveTitle(item.body, item.id),
+    status: item.status,
+    created_at: item.created_at,
+    updated_at: item.updated_at,
+    provenance: item.provenance ?? [],
+    payload,
+    body: item.body,
+  });
 }
 
 /** Write an item to its canonical file. Returns the path. */

package/zuzuu/live/install.mjs

@@ -13,7 +13,7 @@ const DENY_RULES = ['Read(./.zuzuu/.traces/**)', 'Read(./.zuzuu/.live/**)'];
 
 // Minimal hook set: lifecycle (Design B re-captures the transcript — no
 // PostToolUse needed) + the PreToolUse Guardrails GATE (the one place we *do*
-// sit on the hot path: it evaluates .zuzuu/guardrails/rules.json per tool call,
+// sit on the hot path: it evaluates the .zuzuu/guardrails/items/ rules per tool call,
 // fails open, and stays silent unless a rule matches).
 export const LIFECYCLE_EVENTS = ['SessionStart', 'Stop', 'SessionEnd'];
 export const GATE_EVENTS = ['PreToolUse'];

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