@zuzuucodes/cli 1.3.1 → 1.5.0

package/zuzuu/faculty/envelope.mjs

@@ -0,0 +1,290 @@
+// zuzuu/faculty/envelope.mjs — the Faculty Standard envelope (W24).
+//
+// ONE storage format across all five faculties: one file per item, markdown
+// prose + a strict constrained-YAML frontmatter we control on both ends (no
+// YAML lib — grown from the knowledge items grammar):
+//
+//   ---
+//   id: test-command          # required, slug
+//   faculty: knowledge        # required, one of the 5
+//   kind: command             # required; per-faculty kinds (FACULTY_KINDS)
+//   title: "Test command"     # required, single line
+//   status: active            # active | archived
+//   created_at: 2026-06-12T00:00:00Z
+//   updated_at: …             # optional
+//   provenance:               # optional list of flat maps {session, ref}
+//     - session: ses_abc
+//       ref: occurrences=12
+//   payload:                  # faculty-typed machine fields
+//     type: command           #   scalar
+//     attributes:             #   one-level map of scalars
+//       command: npm test
+//     relations:              #   list of flat maps
+//       - type: relates-to
+//         target: ci-pipeline
+//   ---
+//   <markdown prose body>
+//
+// Grammar (deliberately small): top-level scalar keys; `provenance` = a list of
+// flat maps; `payload` = a block of scalars, one-level maps of scalars, lists
+// of flat maps, or lists of scalars. Values are single-line strings (JSON
+// double-quoting when they carry specials — round-trip exact, incl. backslashes
+// in guardrail regexes). Anything outside this grammar is a parse error.
+//
+// API: parseEnvelope(text) → {ok, item, errors} (never throws) ·
+//      serializeEnvelope(item) → text · validateEnvelope(item, payloadSchema).
+// Payload validation rides the shared JSON-Schema-subset checker
+// (actions/schema.mjs — type/required/enum/pattern on flat fields).
+
+import { FACULTIES } from './contract.mjs';
+import { validate as validateSchema } from '../actions/schema.mjs';
+
+/** Per-faculty item kinds. `null` = open set (knowledge kinds are governed by
+ *  the knowledge registry's types.json, not pinned here). */
+export const FACULTY_KINDS = {
+  knowledge: null, // registry-governed (seed: fact|entity|command|decision)
+  memory: ['episode'],
+  actions: ['runbook', 'script'],
+  instructions: ['steering', 'amendment'],
+  guardrails: ['rule'],
+};
+
+/** Default payload schemas (JSON-Schema subset) — also seeded to
+ *  .zuzuu/<faculty>/schema.json by `zuzuu init`. We author both ends. */
+export const PAYLOAD_SCHEMAS = {
+  knowledge: {
+    type: 'object',
+    required: ['type'],
+    properties: {
+      type: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$' },
+      attributes: { type: 'object' },
+      relations: {
+        type: 'array',
+        items: { type: 'object', required: ['type', 'target'], properties: { type: { type: 'string' }, target: { type: 'string' }, commentary: { type: 'string' } } },
+      },
+    },
+  },
+  memory: {
+    type: 'object',
+    properties: {
+      sessions: { type: 'array', items: { type: 'string' } },
+      hosts: { type: 'array', items: { type: 'string' } },
+      tags: { type: 'array', items: { type: 'string' } },
+    },
+  },
+  actions: {
+    type: 'object',
+    properties: {
+      exec: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._-]*$' }, // sibling file name, no path escape
+      args: { type: 'object' },
+    },
+  },
+  instructions: {
+    type: 'object',
+    properties: { scope: { type: 'string' } },
+  },
+  guardrails: {
+    type: 'object',
+    required: ['action', 'pattern', 'reason'],
+    properties: {
+      action: { type: 'string', enum: ['deny', 'ask', 'allow'] },
+      tool: { type: 'string' },
+      pattern: { type: 'string', minLength: 1 },
+      reason: { type: 'string', minLength: 1 },
+    },
+  },
+};
+
+const ID_RE = /^[a-z0-9][a-z0-9_-]*$/; // spec is [a-z0-9-]; `_` tolerated for action slugs
+const ISO_RE = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+const STATUSES = new Set(['active', 'archived']);
+const TOP_KEYS = ['id', 'faculty', 'kind', 'title', 'status', 'created_at', 'updated_at'];
+
+// --- scalar quoting (round-trip exact, incl. backslashes) --------------------
+
+const unquote = (s) => {
+  const t = s.trim();
+  if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
+    try { return JSON.parse(t); } catch { return t.slice(1, -1); }
+  }
+  if (t.startsWith("'") && t.endsWith("'") && t.length >= 2) return t.slice(1, -1);
+  return t;
+};
+
+const quoteIfNeeded = (s) => {
+  const t = String(s);
+  if (t.includes('\n')) throw new Error('envelope values must be single-line');
+  return /[:#'"\\\[\]{}]|^-\s|^\s|\s$/.test(t) || t === '' ? JSON.stringify(t) : t;
+};
+
+const KV = /^([A-Za-z_][\w-]*):\s*(.*)$/;
+
+// --- parse -------------------------------------------------------------------
+
+/**
+ * Parse an envelope file's text. Never throws.
+ * @returns {{ok: boolean, item: object|null, errors: string[]}}
+ */
+export function parseEnvelope(text) {
+  const errors = [];
+  const m = String(text).match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { ok: false, item: null, errors: ['no frontmatter block'] };
+  const [, fm, body] = m;
+  const item = { provenance: [], payload: {}, body: body.trim() };
+
+  let section = null;     // 'provenance' | 'payload' | null
+  let payloadKey = null;  // current sub-block key inside payload
+  let current = null;     // current list entry (flat map) being filled
+
+  for (const raw of fm.split('\n')) {
+    if (!raw.trim()) continue;
+    const indent = raw.match(/^ */)[0].length;
+    const line = raw.trim();
+
+    if (indent === 0) {
+      section = null; payloadKey = null; current = null;
+      const kv = line.match(KV);
+      if (!kv) { errors.push(`bad line: ${line}`); continue; }
+      const [, key, val] = kv;
+      if (key === 'provenance' || key === 'payload') {
+        if (val) { errors.push(`${key} must be a block`); continue; }
+        section = key;
+      } else {
+        item[key] = unquote(val);
+      }
+    } else if (section === 'provenance') {
+      if (line.startsWith('- ')) {
+        const kv = line.slice(2).match(KV);
+        if (!kv) { errors.push(`bad provenance entry: ${line}`); continue; }
+        current = { [kv[1]]: unquote(kv[2]) };
+        item.provenance.push(current);
+      } else {
+        const kv = line.match(KV);
+        if (!current || !kv) { errors.push(`bad provenance line: ${line}`); continue; }
+        current[kv[1]] = unquote(kv[2]);
+      }
+    } else if (section === 'payload') {
+      if (indent === 2 && !line.startsWith('- ')) {
+        current = null;
+        const kv = line.match(KV);
+        if (!kv) { errors.push(`bad payload line: ${line}`); continue; }
+        const [, key, val] = kv;
+        if (val === '') { payloadKey = key; /* shape resolved by first child */ }
+        else { payloadKey = null; item.payload[key] = unquote(val); }
+      } else if (indent >= 4 && payloadKey) {
+        const slot = item.payload[payloadKey];
+        if (line.startsWith('- ')) {
+          const rest = line.slice(2);
+          if (!Array.isArray(slot)) {
+            if (slot !== undefined && typeof slot === 'object') { errors.push(`payload ${payloadKey}: mixed map/list`); continue; }
+            item.payload[payloadKey] = [];
+          }
+          const kv = rest.match(KV);
+          if (kv) {
+            current = { [kv[1]]: unquote(kv[2]) };
+            item.payload[payloadKey].push(current);
+          } else {
+            current = null;
+            item.payload[payloadKey].push(unquote(rest));
+          }
+        } else if (current && Array.isArray(slot)) {
+          const kv = line.match(KV);
+          if (!kv) { errors.push(`bad payload ${payloadKey} entry line: ${line}`); continue; }
+          current[kv[1]] = unquote(kv[2]);
+        } else {
+          // one-level map of scalars
+          if (slot === undefined) item.payload[payloadKey] = {};
+          else if (Array.isArray(item.payload[payloadKey])) { errors.push(`payload ${payloadKey}: mixed list/map`); continue; }
+          const kv = line.match(KV);
+          if (!kv) { errors.push(`bad payload ${payloadKey} line: ${line}`); continue; }
+          item.payload[payloadKey][kv[1]] = unquote(kv[2]);
+        }
+      } else {
+        errors.push(`unexpected indented line: ${line}`);
+      }
+    } else {
+      errors.push(`unexpected indented line: ${line}`);
+    }
+  }
+
+  // empty sub-blocks (key with no children) resolve to {} — already the default
+  if (!item.id) errors.push('item missing id');
+  if (!item.faculty) errors.push('item missing faculty');
+  if (!item.kind) errors.push('item missing kind');
+  return { ok: errors.length === 0, item, errors };
+}
+
+// --- serialize ----------------------------------------------------------------
+
+/** Serialize an envelope item → file text (the exact grammar parseEnvelope reads). */
+export function serializeEnvelope(item) {
+  const lines = ['---'];
+  for (const key of TOP_KEYS) {
+    if (item[key] != null && item[key] !== '') lines.push(`${key}: ${quoteIfNeeded(item[key])}`);
+  }
+  const prov = item.provenance ?? [];
+  if (prov.length) {
+    lines.push('provenance:');
+    for (const entry of prov) {
+      Object.keys(entry).forEach((k, i) => lines.push(`  ${i === 0 ? '- ' : '  '}${k}: ${quoteIfNeeded(entry[k])}`));
+    }
+  }
+  const payload = item.payload ?? {};
+  const pkeys = Object.keys(payload).filter((k) => payload[k] != null);
+  if (pkeys.length) {
+    lines.push('payload:');
+    for (const k of pkeys) {
+      const v = payload[k];
+      if (Array.isArray(v)) {
+        if (!v.length) continue;
+        lines.push(`  ${k}:`);
+        for (const entry of v) {
+          if (entry !== null && typeof entry === 'object') {
+            Object.keys(entry).forEach((ek, i) => lines.push(`    ${i === 0 ? '- ' : '  '}${ek}: ${quoteIfNeeded(entry[ek])}`));
+          } else {
+            lines.push(`    - ${quoteIfNeeded(entry)}`);
+          }
+        }
+      } else if (v !== null && typeof v === 'object') {
+        const entries = Object.entries(v);
+        if (!entries.length) continue;
+        lines.push(`  ${k}:`);
+        for (const [mk, mv] of entries) lines.push(`    ${mk}: ${quoteIfNeeded(mv)}`);
+      } else {
+        lines.push(`  ${k}: ${quoteIfNeeded(v)}`);
+      }
+    }
+  }
+  lines.push('---', '');
+  return lines.join('\n') + (item.body ? String(item.body).trim() + '\n' : '');
+}
+
+// --- validate -----------------------------------------------------------------
+
+/**
+ * Validate an envelope item: required envelope fields + (optionally) its payload
+ * against a JSON-Schema-subset payload schema.
+ * @returns {{ok: boolean, errors: string[]}}
+ */
+export function validateEnvelope(item, payloadSchema = null) {
+  const errors = [];
+  if (!item || typeof item !== 'object') return { ok: false, errors: ['not an item'] };
+  if (!item.id || !ID_RE.test(item.id)) errors.push(`id must match ${ID_RE} (got '${item.id}')`);
+  if (!FACULTIES.includes(item.faculty)) errors.push(`faculty must be one of ${FACULTIES.join('|')} (got '${item.faculty}')`);
+  const kinds = FACULTY_KINDS[item.faculty];
+  if (!item.kind || !/^[a-z0-9][a-z0-9-]*$/.test(item.kind)) errors.push(`kind must be a slug (got '${item.kind}')`);
+  else if (Array.isArray(kinds) && !kinds.includes(item.kind)) errors.push(`kind must be one of ${kinds.join('|')} for ${item.faculty} (got '${item.kind}')`);
+  if (!item.title || typeof item.title !== 'string' || item.title.includes('\n')) errors.push('title is required (single line)');
+  if (item.status != null && !STATUSES.has(item.status)) errors.push(`status must be active|archived (got '${item.status}')`);
+  if (!item.created_at || !ISO_RE.test(String(item.created_at))) errors.push(`created_at must be ISO (got '${item.created_at}')`);
+  if (item.updated_at != null && !ISO_RE.test(String(item.updated_at))) errors.push(`updated_at must be ISO (got '${item.updated_at}')`);
+  if (item.provenance != null && !Array.isArray(item.provenance)) errors.push('provenance must be a list');
+  if (payloadSchema) errors.push(...validateSchema(payloadSchema, item.payload ?? {}, 'payload'));
+  return { ok: errors.length === 0, errors };
+}
+
+/** Derive a single-line title (first body line, de-markdowned) — fallback id. */
+export function deriveTitle(body, id) {
+  const first = String(body ?? '').split('\n').map((l) => l.replace(/^#+\s*/, '').trim()).find(Boolean);
+  return (first || String(id || 'item')).slice(0, 80);
+}

package/zuzuu/faculty/generation.mjs

@@ -61,13 +61,14 @@ function knowledgeFiles(agentDir) {
 function actionFiles(agentDir) {
   const dir = join(agentDir, 'actions');
   return sortDirents(dir)
-    .filter((e) => e.isDirectory() && e.name !== 'inbox' && e.name !== 'proposals')
+    .filter((e) => e.isDirectory() && e.name !== 'inbox' && e.name !== 'proposals' && e.name !== '_rolledback')
     .map((e) => {
       const adir = join(dir, e.name);
-      // Hash the dir's defining files concatenated (action.json + run.mjs/SKILL.md).
-      const parts = ['action.json', 'run.mjs', 'SKILL.md']
-        .map((f) => join(adir, f))
-        .filter((p) => existsSync(p));
+      // Hash the dir's defining files concatenated: the ACTION.md envelope
+      // (W24) + sibling scripts (*.mjs — run.mjs and any payload.exec module).
+      const parts = sortDirents(adir)
+        .filter((f) => f.isFile() && (f.name === 'ACTION.md' || f.name.endsWith('.mjs')))
+        .map((f) => join(adir, f.name));
       const concat = Buffer.concat(parts.map((p) => readFileSync(p)));
       return {
         id: e.name, faculty: 'actions', files: parts.map((p) => p.slice(adir.length + 1)),
@@ -76,6 +77,20 @@ function actionFiles(agentDir) {
     });
 }
 
+/** Flat envelope-item faculties share one enumerator. */
+function mdItemFiles(agentDir, faculty, ...segments) {
+  const dir = join(agentDir, ...segments);
+  return sortDirents(dir)
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => {
+      const src = join(dir, e.name);
+      return { id: e.name.replace(/\.md$/, ''), faculty, src, rel: e.name, hash: sha256(readFileSync(src)) };
+    });
+}
+
+const guardrailFiles = (agentDir) => mdItemFiles(agentDir, 'guardrails', 'guardrails', 'items');
+const instructionFiles = (agentDir) => mdItemFiles(agentDir, 'instructions', 'instructions', 'items');
+
 function memoryFiles(agentDir) {
   const dir = join(agentDir, 'memory', 'entries');
   return sortDirents(dir)
@@ -93,10 +108,6 @@ function registryHash(agentDir) {
   return sha256(Buffer.concat(files.map((e) => readFileSync(join(dir, e.name)))));
 }
 
-function fileHashOrNull(p) {
-  return existsSync(p) ? sha256(readFileSync(p)) : null;
-}
-
 /**
  * Snapshot the current faculty state → the `faculties` manifest object.
  * Tolerates missing files (empty arrays / null hashes).
@@ -111,10 +122,10 @@ export function snapshotFaculties(agentDir) {
       items: actionFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
     },
     guardrails: {
-      rulesHash: fileHashOrNull(join(agentDir, 'guardrails', 'rules.json')),
+      items: guardrailFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
     },
     instructions: {
-      projectHash: fileHashOrNull(join(agentDir, 'instructions', 'project.md')),
+      items: instructionFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
     },
     memory: {
       items: memoryFiles(agentDir).map(({ id, hash }) => ({ id, hash })),
@@ -169,9 +180,6 @@ export function readGeneration(agentDir, id) {
   return existsSync(p) ? readJson(p) : null;
 }
 
-/** Item-list faculties carry {id,hash}[]; single-file faculties a *Hash scalar. */
-const HASH_KEYS = { knowledge: 'registryHash', instructions: 'projectHash', guardrails: 'rulesHash' };
-
 /** Diff two item-manifest arrays → {added, changed, removed} (id lists). */
 function diffItems(parentItems = [], childItems = []) {
   const p = new Map(parentItems.map((i) => [i.id, i.hash]));
@@ -187,11 +195,10 @@ function diffItems(parentItems = [], childItems = []) {
 
 /**
  * Per-faculty diff of generation `id` against its forkedFrom parent (pure).
- * For item-list faculties (knowledge/actions/memory) reports added/changed/removed
- * id lists. For hash-only faculties (guardrails/instructions, and knowledge's
- * registry) reports a `changed` boolean when the scalar hash differs. When there
- * is no parent (forkedFrom null), everything present counts as added.
- * Returns null for an unknown id.
+ * ALL five faculties are item lists under the Faculty Standard (W24) —
+ * added/changed/removed id lists per faculty; knowledge additionally reports
+ * registryChanged. When there is no parent (forkedFrom null), everything
+ * present counts as added. Returns null for an unknown id.
  */
 export function diffGenerations(agentDir, id) {
   const child = readGeneration(agentDir, id);
@@ -200,17 +207,13 @@ export function diffGenerations(agentDir, id) {
   const cf = child.faculties || {};
   const pf = parent?.faculties || {};
   const faculties = {};
-  for (const f of ['knowledge', 'actions', 'memory']) {
+  for (const f of ['knowledge', 'actions', 'memory', 'guardrails', 'instructions']) {
     faculties[f] = diffItems(pf[f]?.items, cf[f]?.items);
     // knowledge also has a registry hash
     if (f === 'knowledge') {
       faculties[f].registryChanged = (cf.knowledge?.registryHash ?? null) !== (pf.knowledge?.registryHash ?? null);
     }
   }
-  for (const f of ['guardrails', 'instructions']) {
-    const key = HASH_KEYS[f];
-    faculties[f] = { changed: (cf[f]?.[key] ?? null) !== (pf[f]?.[key] ?? null) };
-  }
   return {
     id,
     forkedFrom: child.forkedFrom ?? null,
@@ -247,18 +250,15 @@ function copySnapshot(agentDir, id) {
       writeFileSync(dest, readFileSync(join(a.adir, rel)));
     }
   }
-  // single-file faculties
-  const rules = join(agentDir, 'guardrails', 'rules.json');
-  if (existsSync(rules)) {
-    const dest = join(base, 'guardrails', 'rules.json');
+  for (const it of guardrailFiles(agentDir)) {
+    const dest = join(base, 'guardrails', it.rel);
     mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, readFileSync(rules));
+    writeFileSync(dest, readFileSync(it.src));
   }
-  const proj = join(agentDir, 'instructions', 'project.md');
-  if (existsSync(proj)) {
-    const dest = join(base, 'instructions', 'project.md');
+  for (const it of instructionFiles(agentDir)) {
+    const dest = join(base, 'instructions', it.rel);
     mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, readFileSync(proj));
+    writeFileSync(dest, readFileSync(it.src));
   }
 }
 
@@ -369,20 +369,26 @@ export function rollback(agentDir, id) {
     }
   }
 
-  // 4) restore single-file faculties from the snapshot
-  const grules = join(base, 'guardrails', 'rules.json');
-  if (existsSync(grules)) {
-    const dest = join(agentDir, 'guardrails', 'rules.json');
-    mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, readFileSync(grules));
-    restored++;
-  }
-  const proj = join(base, 'instructions', 'project.md');
-  if (existsSync(proj)) {
-    const dest = join(agentDir, 'instructions', 'project.md');
-    mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, readFileSync(proj));
-    restored++;
+  // 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

package/zuzuu/faculty/items.mjs

@@ -0,0 +1,75 @@
+// 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). */
+export function itemsDirFor(agentDir, faculty) {
+  const rel = ITEM_DIRS[faculty];
+  return rel ? join(agentDir, ...rel) : null;
+}
+
+/** 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.
+ * @returns {{items: object[], errors: Array<{file: string, error: string}>}}
+ */
+export function listFacultyItems(agentDir, faculty) {
+  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);
+  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/guardrails/adapter.mjs

@@ -1,43 +1,24 @@
 // zuzuu/guardrails/adapter.mjs
-// The Guardrails faculty adapter (WS2-T4). Wraps the rules engine behind the
+// The Guardrails faculty adapter. Wraps the rules engine behind the
 // faculty-spine adapter contract — { name, ingest, validate, apply, render } —
 // so `zuzuu review` can surface and approve/reject rule proposals the same way it
 // does Knowledge proposals.
 //
 // A guardrails proposal payload is a single rule record:
-//   { id, action: deny|ask|allow, tool, pattern, reason }
+//   { id, action: deny|ask|allow, tool, pattern, reason, body? }
 //
-// apply: loads .zuzuu/guardrails/rules.json (seeding {version:1,rules:[]} if
-//        absent), appends the rule or replaces an existing one with the same id,
-//        then writes the file back.
+// apply: writes the rule as a Faculty Standard envelope item at
+//        .zuzuu/guardrails/items/<id>.md (upsert — same id replaces the file).
 //
 // Registers itself on import.
 
-import { join } from 'node:path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import * as registry from '../faculty/registry.mjs';
+import { writeFacultyItem } from '../faculty/items.mjs';
+import { deriveTitle } from '../faculty/envelope.mjs';
 
 const name = 'guardrails';
 const VALID_ACTIONS = new Set(['deny', 'ask', 'allow']);
 
-// ---------------------------------------------------------------------------
-// helpers
-// ---------------------------------------------------------------------------
-
-function rulesPath(agentDir) {
-  return join(agentDir, 'guardrails', 'rules.json');
-}
-
-function loadRulesFile(agentDir) {
-  const path = rulesPath(agentDir);
-  if (!existsSync(path)) return { version: 1, rules: [] };
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return { version: 1, rules: [] };
-  }
-}
-
 // ---------------------------------------------------------------------------
 // adapter contract
 // ---------------------------------------------------------------------------
@@ -84,35 +65,23 @@ function validate(_agentDir, payload) {
 }
 
 /**
- * Apply an approved rule proposal: upsert into rules.json.
+ * Apply an approved rule proposal: write the envelope item (upsert by id).
  * @returns {{ok:boolean, action:string, itemIds:string[]}}
  */
 function apply(agentDir, proposal) {
   const rule = proposal?.payload ?? {};
   const id = rule.id;
-
-  // Ensure the guardrails dir exists
-  mkdirSync(join(agentDir, 'guardrails'), { recursive: true });
-
-  const data = loadRulesFile(agentDir);
-  if (!Array.isArray(data.rules)) data.rules = [];
-
-  const idx = data.rules.findIndex((r) => r.id === id);
-  // Store only the canonical fields (id, action, tool, pattern, reason)
-  const entry = {
-    id: rule.id,
-    action: rule.action,
-    tool: rule.tool,
-    pattern: rule.pattern,
-    reason: rule.reason,
-  };
-  if (idx >= 0) {
-    data.rules[idx] = entry;
-  } else {
-    data.rules.push(entry);
-  }
-
-  writeFileSync(rulesPath(agentDir), JSON.stringify(data, null, 2) + '\n');
+  writeFacultyItem(agentDir, {
+    id,
+    faculty: name,
+    kind: 'rule',
+    title: deriveTitle(rule.reason, id),
+    status: 'active',
+    created_at: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    provenance: Array.isArray(proposal?.provenance) ? proposal.provenance : [],
+    payload: { action: rule.action, tool: rule.tool || '*', pattern: rule.pattern, reason: rule.reason },
+    body: rule.body ?? '',
+  });
   return { ok: true, action: `added rule ${id}`, itemIds: [id] };
 }