@zuzuucodes/cli 1.4.0 → 1.5.0

package/zuzuu/actions/adapter.mjs

@@ -4,7 +4,7 @@
 // adapter contract — { name, ingest, validate, apply, render } — so the generic
 // `zuzuu review` gate can drive Actions the same way it drives Knowledge.
 //
-// Actions payloads are DIRECTORIES (run.mjs/SKILL.md + action.json), not JSON.
+// Actions payloads are DIRECTORIES (ACTION.md + sibling scripts), not JSON.
 // Strategy (lowest-risk): the inbox stays a dir; this adapter emits/reads a
 // spine-shaped proposal RECORD that REFERENCES the dir
 // (payload = { slug, kind, dir:'inbox/<slug>' }). The gate resolves a single
@@ -18,7 +18,7 @@ import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { listActions, inboxDir, isSafeSlug } from './manifest.mjs';
 import { activateAction, rejectAction } from './inbox.mjs';
-import { validateInputs } from './schema.mjs';
+import { parseEnvelope, validateEnvelope, PAYLOAD_SCHEMAS } from '../faculty/envelope.mjs';
 import * as registry from '../faculty/registry.mjs';
 
 const name = 'actions';
@@ -64,30 +64,22 @@ function ingest(_agentDir, raw) {
 }
 
 /**
- * Validate a proposed action's manifest against the schema subset and confirm
- * the manifest slug matches the dir. Missing manifest → accept (slug fallback).
+ * Validate a proposed action's ACTION.md envelope (id matches the dir; the
+ * payload validates against the actions schema). Missing ACTION.md → accept
+ * (slug fallback, mirrors the historical missing-manifest tolerance).
  * @returns {{ok:boolean, errors:string[], warnings:string[]}}
  */
 function validate(agentDir, payload) {
   const slug = payload?.slug;
   if (!isSafeSlug(slug)) return { ok: false, errors: [`invalid slug '${slug}'`], warnings: [] };
-  const manPath = join(inboxDir(agentDir), slug, 'action.json');
+  const manPath = join(inboxDir(agentDir), slug, 'ACTION.md');
   if (!existsSync(manPath)) return { ok: true, errors: [], warnings: [] };
-  let man;
-  try { man = JSON.parse(readFileSync(manPath, 'utf8')); }
-  catch { return { ok: false, errors: ['manifest is not valid JSON'], warnings: [] }; }
-  if (man.slug && man.slug !== slug) return { ok: false, errors: [`manifest slug '${man.slug}' ≠ dir '${slug}'`], warnings: [] };
-  const errors = [];
-  // the manifest schema is itself JSON-Schema-subset shaped; sanity-check both ends
-  if (man.inputs) {
-    const vi = validateInputs(man.inputs, man.default_args, {});
-    // inputs schema is for caller args, not the manifest — only flag a structurally
-    // broken schema (validateInputs is permissive on empty args), so this is a no-op
-    // for well-formed manifests. Kept for symmetry with the knowledge adapter.
-    if (vi.ok === false && !/required/i.test(vi.error ?? '')) errors.push(vi.error);
-  }
-  if (man.outputs && typeof man.outputs !== 'object') errors.push('outputs schema must be an object');
-  return { ok: errors.length === 0, errors, warnings: [] };
+  const { ok, item, errors: parseErrors } = parseEnvelope(readFileSync(manPath, 'utf8'));
+  if (!ok) return { ok: false, errors: [`ACTION.md is not a valid envelope: ${parseErrors[0]}`], warnings: [] };
+  if (item.id && item.id !== slug) return { ok: false, errors: [`ACTION.md id '${item.id}' ≠ dir '${slug}'`], warnings: [] };
+  if (item.faculty !== 'actions') return { ok: false, errors: [`ACTION.md faculty must be 'actions' (got '${item.faculty}')`], warnings: [] };
+  const v = validateEnvelope(item, PAYLOAD_SCHEMAS.actions);
+  return { ok: v.ok, errors: v.errors, warnings: [] };
 }
 
 /**

package/zuzuu/actions/convert.mjs

@@ -1,7 +1,9 @@
 // zuzuu/actions/convert.mjs
 // Pure manifest → tool-definition converters (the _labs tool-definition pattern).
-// The manifest's `inputs` JSON Schema is already the right shape for each format,
-// so conversion is a thin re-wrap.
+// Manifests are ACTION.md envelopes (W24): name = the envelope id, description =
+// the prompt snippet (body first line) or title. The envelope carries no
+// inputs/outputs JSON-schemas (clean break) — tool definitions expose the
+// permissive object schema; the runner validates the same way.
 //
 // STATUS (2026-06-11): used today only by `zuzuu act schema <slug> [--mcp|--openai|
 // --anthropic]` for inspection. There is NO runtime MCP/native-tool *serving* yet —
@@ -9,19 +11,18 @@
 // agent in the digest. Live "Actions over MCP" serving is DEFERRED (DESIGN §6 /
 // Stage 2 / OpenCode bundle); these converters are the seam for it, not the thing.
 
-const desc = (m) => m.description ?? m.title ?? m.slug;
-const inputs = (m) => m.inputs ?? { type: 'object' };
+const name = (m) => m.id ?? m.slug;
+const desc = (m) => m.promptSnippet ?? m.title ?? name(m);
+const inputs = () => ({ type: 'object' });
 
 export function toMcpTool(m) {
-  const t = { name: m.slug, description: desc(m), inputSchema: inputs(m) };
-  if (m.outputs) t.outputSchema = m.outputs;
-  return t;
+  return { name: name(m), description: desc(m), inputSchema: inputs() };
 }
 
 export function toOpenAITool(m) {
-  return { type: 'function', function: { name: m.slug, description: desc(m), parameters: inputs(m) } };
+  return { type: 'function', function: { name: name(m), description: desc(m), parameters: inputs() } };
 }
 
 export function toAnthropicTool(m) {
-  return { name: m.slug, description: desc(m), input_schema: inputs(m) };
+  return { name: name(m), description: desc(m), input_schema: inputs() };
 }

package/zuzuu/actions/dispatch.mjs

@@ -8,7 +8,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
-import { loadManifest, actionsDir } from './manifest.mjs';
+import { loadManifest, execOf, actionsDir } from './manifest.mjs';
 import { MARKER } from './marker.mjs';
 
 const MAX_DEPTH = 8;
@@ -51,16 +51,21 @@ export function runAction(agentDir, slug, callerArgs = {}, { timeoutMs = ACTION_
   if (depth >= MAX_DEPTH) return { ok: false, error: 'depth_exceeded', detail: `depth ${depth} ≥ ${MAX_DEPTH}`, logs: '' };
 
   const manifest = loadManifest(agentDir, slug);
-  if (!manifest) return { ok: false, error: 'not_found', detail: `no action '${slug}' (missing action.json)`, logs: '' };
+  if (!manifest) return { ok: false, error: 'not_found', detail: `no action '${slug}' (missing ACTION.md)`, logs: '' };
 
-  const runPath = join(actionsDir(agentDir), slug, 'run.mjs');
-  if (!existsSync(runPath)) return { ok: false, error: 'not_runnable', detail: `'${slug}' has no run.mjs`, logs: '' };
+  const exec = execOf(manifest);
+  if (!exec) return { ok: false, error: 'not_runnable', detail: `'${slug}' has an unsafe exec entry`, logs: '' };
+  const runPath = join(actionsDir(agentDir), slug, exec);
+  if (!existsSync(runPath)) return { ok: false, error: 'not_runnable', detail: `'${slug}' has no ${exec}`, logs: '' };
 
+  // The envelope carries no inputs/outputs JSON-schemas (clean break, W24) —
+  // the runner validates against the permissive object schema; payload.args
+  // are the default args (caller args win).
   const payload = JSON.stringify({
     runPath,
-    inputs: manifest.inputs ?? { type: 'object' },
-    outputs: manifest.outputs ?? { type: 'object' },
-    default_args: manifest.default_args ?? {},
+    inputs: { type: 'object' },
+    outputs: { type: 'object' },
+    default_args: manifest.payload?.args ?? {},
     args: callerArgs ?? {},
   });
 

package/zuzuu/actions/inbox.mjs

@@ -7,6 +7,7 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync, renameSync, mkdirSync, rmSync } from 'node:fs';
 import { actionsDir, inboxDir, listActions, isSafeSlug } from './manifest.mjs';
+import { parseEnvelope } from '../faculty/envelope.mjs';
 
 /** Archive dir for rejected action proposals: .zuzuu/actions/proposals/archive/. */
 const archiveBaseDir = (agentDir) => join(actionsDir(agentDir), 'proposals', 'archive');
@@ -26,12 +27,11 @@ export function activateAction(agentDir, slug) {
   const to = join(actionsDir(agentDir), slug);
   if (!existsSync(from)) return { ok: false, error: `no proposed action '${slug}'` };
   if (existsSync(to)) return { ok: false, error: `an active action '${slug}' already exists — reject or rename first` };
-  const manPath = join(from, 'action.json');
+  const manPath = join(from, 'ACTION.md');
   if (existsSync(manPath)) {
-    let man;
-    try { man = JSON.parse(readFileSync(manPath, 'utf8')); }
-    catch { return { ok: false, error: `manifest is not valid JSON` }; }
-    if (man.slug && man.slug !== slug) return { ok: false, error: `manifest slug '${man.slug}' ≠ dir '${slug}'` };
+    const { ok, item } = parseEnvelope(readFileSync(manPath, 'utf8'));
+    if (!ok) return { ok: false, error: 'ACTION.md is not a valid envelope' };
+    if (item.id && item.id !== slug) return { ok: false, error: `ACTION.md id '${item.id}' ≠ dir '${slug}'` };
   }
   renameSync(from, to);
   return { ok: true };

package/zuzuu/actions/manifest.mjs

@@ -1,10 +1,17 @@
 // zuzuu/actions/manifest.mjs
-// Reads the Actions faculty off disk: one action per dir under .zuzuu/actions/.
-// Two kinds — `script` (has run.mjs + action.json) and `runbook` (SKILL.md prose).
+// Reads the Actions faculty off disk: one action per dir under .zuzuu/actions/,
+// described by an ACTION.md envelope (the Faculty Standard, W24 — SKILL.md-shaped:
+// frontmatter + instruction prose body; scripts stay siblings):
+//
+//   actions/<slug>/ACTION.md   kind: script|runbook; payload.exec (script entry,
+//                              default run.mjs) + payload.args (default args)
+//   actions/<slug>/run.mjs     the script (kind: script)
+//
 // Pure-ish: filesystem reads only, no logging, no process control.
 
 import { join } from 'node:path';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { parseEnvelope, deriveTitle } from '../faculty/envelope.mjs';
 
 // Action slugs: letters/digits start, then letters/digits/-/_. No dots or slashes
 // → cannot escape .zuzuu/actions/ via path traversal.
@@ -13,60 +20,71 @@ export function isSafeSlug(slug) {
   return typeof slug === 'string' && SAFE_SLUG.test(slug);
 }
 
+// payload.exec must be a plain sibling filename — never a path.
+const SAFE_EXEC = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
 export const actionsDir = (agentDir) => join(agentDir, 'actions');
 export const inboxDir = (agentDir) => join(actionsDir(agentDir), 'inbox');
 const actionDir = (agentDir, slug) => join(actionsDir(agentDir), slug);
 
-/** Read action.json for a slug → object, or null if absent/unparseable. */
+/** First non-empty body line — the one-liner the digest shows. */
+function snippetOf(item) {
+  const first = String(item.body ?? '').split('\n').map((l) => l.trim()).find(Boolean);
+  return first || item.title || item.id;
+}
+
+/**
+ * Read and parse ACTION.md for a slug → envelope manifest, or null if
+ * absent/unparseable. Shape: { id, kind, title, status, created_at,
+ * payload: {exec?, args?}, body } + promptSnippet derived from the body.
+ */
 export function loadManifest(agentDir, slug) {
-  const path = join(actionDir(agentDir, slug), 'action.json');
+  const path = join(actionDir(agentDir, slug), 'ACTION.md');
   try {
-    return JSON.parse(readFileSync(path, 'utf8'));
+    const { ok, item } = parseEnvelope(readFileSync(path, 'utf8'));
+    if (!ok || item.faculty !== 'actions') return null;
+    item.title = item.title ?? deriveTitle(item.body, item.id);
+    item.promptSnippet = snippetOf(item);
+    return item;
   } catch {
     return null;
   }
 }
 
-/** Pull `name` / `description` from a SKILL.md YAML-ish frontmatter (best-effort). */
-function skillFrontmatter(text) {
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  const fm = {};
-  if (m) {
-    for (const line of m[1].split('\n')) {
-      const kv = line.match(/^(\w+):\s*(.*)$/);
-      if (kv) fm[kv[1]] = kv[2].trim();
-    }
-  }
-  return fm;
+/** The script entry file for a manifest (validated sibling name), or null. */
+export function execOf(manifest) {
+  const exec = manifest?.payload?.exec ?? 'run.mjs';
+  return SAFE_EXEC.test(exec) ? exec : null;
 }
 
 /**
  * List actions in a base dir as {slug, kind, title, promptSnippet}.
- * `script` = dir has run.mjs; `runbook` = dir has SKILL.md; other entries skipped.
- * Reads the manifest directly from each entry dir (works for any baseDir, e.g. the inbox).
+ * An action is a dir carrying ACTION.md; kind comes from its envelope
+ * (`script` | `runbook`). Other entries are skipped (READMEs, stray files,
+ * unparseable envelopes — the latter surface via `zuzuu faculty items actions`).
+ * Reads directly from each entry dir (works for any baseDir, e.g. the inbox).
  */
 export function listActions(baseDir) {
   if (!existsSync(baseDir)) return [];
   const out = [];
-  for (const name of readdirSync(baseDir)) {
+  for (const name of readdirSync(baseDir).sort()) {
     const d = join(baseDir, name);
     let isDir = false;
     try { isDir = statSync(d).isDirectory(); } catch { /* skip */ }
     if (!isDir) continue; // ignores README.md and any stray files
-    if (existsSync(join(d, 'run.mjs'))) {
-      let man = {};
-      try { man = JSON.parse(readFileSync(join(d, 'action.json'), 'utf8')); } catch { /* slug fallback */ }
-      out.push({ slug: name, kind: 'script', title: man.title ?? name, promptSnippet: man.promptSnippet ?? man.description ?? name });
-    } else if (existsSync(join(d, 'SKILL.md'))) {
-      let fm = {};
-      try { fm = skillFrontmatter(readFileSync(join(d, 'SKILL.md'), 'utf8')); } catch { /* slug fallback */ }
-      out.push({ slug: name, kind: 'runbook', title: fm.name ?? name, promptSnippet: fm.description ?? name });
-    }
+    const actionMd = join(d, 'ACTION.md');
+    if (!existsSync(actionMd)) continue;
+    try {
+      const { ok, item } = parseEnvelope(readFileSync(actionMd, 'utf8'));
+      if (!ok) continue;
+      const kind = item.kind === 'script' ? 'script' : 'runbook';
+      out.push({ slug: name, kind, title: item.title ?? name, promptSnippet: snippetOf(item) });
+    } catch { /* unreadable → skip */ }
   }
   return out;
 }
 
-/** Active actions under .zuzuu/actions/ (the inbox subdir is excluded). */
+/** Active actions under .zuzuu/actions/ (inbox/proposals subdirs excluded). */
 export function allActions(agentDir) {
-  return listActions(actionsDir(agentDir)).filter((a) => a.slug !== 'inbox');
+  return listActions(actionsDir(agentDir)).filter((a) => a.slug !== 'inbox' && a.slug !== 'proposals' && a.slug !== '_rolledback');
 }

package/zuzuu/actions/schema.mjs

@@ -1,9 +1,10 @@
 // zuzuu/actions/schema.mjs
 // A hand-rolled JSON-Schema *subset* validator — zero-dep (no Ajv), matching the
 // project's node-builtins-only policy. Supports: object (properties, required),
-// array (items), string/number/integer/boolean scalars, enum, and basic length/
-// range constraints. Returns an array of error strings ([] = valid). No coercion:
-// values are expected to already carry real JSON types.
+// array (items), string/number/integer/boolean scalars, enum, pattern, and basic
+// length/range constraints. Returns an array of error strings ([] = valid). No
+// coercion: values are expected to already carry real JSON types. Shared by the
+// actions runner AND the faculty envelope (payload validation — W24).
 
 function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -41,6 +42,11 @@ export function validate(schema, value, path = '$') {
   if (typeof value === 'string') {
     if (schema.minLength != null && value.length < schema.minLength) errors.push(`${path}: shorter than minLength ${schema.minLength}`);
     if (schema.maxLength != null && value.length > schema.maxLength) errors.push(`${path}: longer than maxLength ${schema.maxLength}`);
+    if (schema.pattern != null) {
+      try {
+        if (!new RegExp(schema.pattern).test(value)) errors.push(`${path}: does not match pattern ${schema.pattern}`);
+      } catch { /* an unparseable authored pattern never blocks (fail-open) */ }
+    }
   }
   if (typeof value === 'number') {
     if (schema.minimum != null && value < schema.minimum) errors.push(`${path}: below minimum ${schema.minimum}`);

package/zuzuu/commands/act-author.mjs

@@ -1,23 +1,33 @@
 // zuzuu/commands/act-author.mjs
 // `zuzuu act new <slug>` — scaffold a script action (idempotent, no-clobber).
 // `zuzuu act schema <slug> [--mcp|--openai|--anthropic]` — convert the manifest.
+// Actions are described by ACTION.md (the Faculty Standard envelope, W24).
 
 import { mkdirSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { actionsDir, inboxDir, loadManifest, isSafeSlug } from '../actions/manifest.mjs';
 import { toMcpTool, toOpenAITool, toAnthropicTool } from '../actions/convert.mjs';
+import { serializeEnvelope } from '../faculty/envelope.mjs';
 
-function manifestStub(slug) {
-  return JSON.stringify({
-    slug,
+function actionMdStub(slug) {
+  return serializeEnvelope({
+    id: slug,
+    faculty: 'actions',
+    kind: 'script',
     title: slug,
-    description: 'what this action does',
-    promptSnippet: `one line the digest shows for ${slug}`,
-    inputs: { type: 'object', properties: {}, required: [] },
-    outputs: { type: 'object', properties: {} },
-    default_args: {},
-    requires: [],
-  }, null, 2) + '\n';
+    status: 'active',
+    created_at: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    payload: { exec: 'run.mjs' },
+    body: [
+      `What ${slug} does — the first line is the one-liner the digest shows.`,
+      '',
+      '## Usage',
+      '',
+      `\`zuzuu act ${slug} --args '{"key":"value"}'\``,
+      '',
+      'Describe inputs, outputs, and when to reach for this action here.',
+    ].join('\n'),
+  });
 }
 
 const RUN_TEMPLATE = `// run.mjs — implement the action. Export async main(args) → a JSON object.
@@ -26,7 +36,7 @@ const RUN_TEMPLATE = `// run.mjs — implement the action. Export async main(arg
 // export function prepareArguments(args) { return args; }
 
 export async function main(args) {
-  // args is validated against action.json "inputs"; return must match "outputs".
+  // args = ACTION.md payload.args defaults merged with caller --args (caller wins).
   return { ok: true };
 }
 `;
@@ -41,7 +51,7 @@ function scaffoldInto(baseDir, slug) {
     const p = join(dir, name);
     if (!existsSync(p)) { writeFileSync(p, body); created.push(name); }
   };
-  write('action.json', manifestStub(slug));
+  write('ACTION.md', actionMdStub(slug));
   write('run.mjs', RUN_TEMPLATE);
   return { created };
 }
@@ -66,7 +76,7 @@ export function newAction(agentDir, slug) {
 export function schema(agentDir, slug, args = {}) {
   if (!slug) { console.error('usage: zuzuu act schema <slug> [--mcp|--openai|--anthropic]'); process.exit(1); }
   const man = loadManifest(agentDir, slug);
-  if (!man) { console.error(`no action '${slug}' (missing action.json)`); process.exit(1); }
+  if (!man) { console.error(`no action '${slug}' (missing ACTION.md)`); process.exit(1); }
   const def = args.openai ? toOpenAITool(man) : args.anthropic ? toAnthropicTool(man) : toMcpTool(man);
   console.log(JSON.stringify(def, null, 2));
 }

package/zuzuu/commands/act.mjs

@@ -10,7 +10,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { paths } from '../store.mjs';
-import { allActions, loadManifest, actionsDir, isSafeSlug } from '../actions/manifest.mjs';
+import { allActions, actionsDir, isSafeSlug } from '../actions/manifest.mjs';
 import { runAction } from '../actions/dispatch.mjs';
 import { MARKER } from '../actions/marker.mjs';
 import { newAction, schema as schemaCmd, proposeAction } from './act-author.mjs';
@@ -35,10 +35,8 @@ function list(agentDir) {
 
 function show(agentDir, slug) {
   if (!slug) { console.error('usage: zuzuu act show <slug>'); process.exit(1); }
-  const man = loadManifest(agentDir, slug);
-  if (man) return console.log(JSON.stringify(man, null, 2));
-  const skill = join(actionsDir(agentDir), slug, 'SKILL.md');
-  if (existsSync(skill)) return process.stdout.write(readFileSync(skill, 'utf8'));
+  const actionMd = join(actionsDir(agentDir), slug, 'ACTION.md');
+  if (existsSync(actionMd)) return process.stdout.write(readFileSync(actionMd, 'utf8'));
   console.error(`no action '${slug}'`);
   process.exit(1);
 }

package/zuzuu/commands/doctor.mjs

@@ -40,8 +40,8 @@ export function detectDrift(agentDir) {
     const pinned = lockfile.faculties || {};
     const drifted = [];
 
-    // Compare per-faculty item arrays (knowledge, actions, memory).
-    for (const faculty of ['knowledge', 'actions', 'memory']) {
+    // Compare per-faculty item arrays — all five are envelope-item lists (W24).
+    for (const faculty of ['knowledge', 'actions', 'memory', 'guardrails', 'instructions']) {
       const pinnedItems = (pinned[faculty]?.items ?? []);
       const currentItems = (current[faculty]?.items ?? []);
 
@@ -65,19 +65,6 @@ export function detectDrift(agentDir) {
       }
     }
 
-    // Compare single-file faculties (guardrails.rulesHash, instructions.projectHash)
-    const singleFile = [
-      { faculty: 'guardrails', field: 'rulesHash' },
-      { faculty: 'instructions', field: 'projectHash' },
-    ];
-    for (const { faculty, field } of singleFile) {
-      const pinnedHash = pinned[faculty]?.[field] ?? null;
-      const currentHash = current[faculty]?.[field] ?? null;
-      if (pinnedHash !== currentHash) {
-        drifted.push({ id: field, faculty, reason: 'hash_changed', pinned: pinnedHash, current: currentHash });
-      }
-    }
-
     // Compare knowledge.registryHash
     const pinnedReg = pinned.knowledge?.registryHash ?? null;
     const currentReg = current.knowledge?.registryHash ?? null;

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,75 @@
+// zuzuu/commands/faculty.mjs — `zuzuu faculty` (W24, the Faculty Standard).
+//
+// The read surface over the one envelope format:
+//   zuzuu faculty items <f> [--json|--jsonl]   list a faculty's envelope items
+//   zuzuu faculty schema <f> [--json]          print its payload schema
+//
+// `--json` = one document; `--jsonl` = one item per line (streaming consumers).
+// Fail-soft like everything on the serve path: unparseable items are listed as
+// errors next to the good ones, never thrown.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from '../store.mjs';
+import { FACULTIES } from '../faculty/contract.mjs';
+import { listFacultyItems } from '../faculty/items.mjs';
+import { PAYLOAD_SCHEMAS, FACULTY_KINDS } from '../faculty/envelope.mjs';
+
+/** Pure: one faculty's envelope items + parse errors (the --json document). */
+export function facultyItemsData(agentDir, faculty) {
+  const { items, errors } = listFacultyItems(agentDir, faculty);
+  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] };
+}
+
+/** `zuzuu faculty <sub> <f>` — items | schema. */
+export function faculty(args = {}, log = console.log) {
+  const [sub, f] = args._ ?? [];
+  if (!sub || !['items', 'schema'].includes(sub)) {
+    console.error('usage: zuzuu faculty items <faculty> [--json|--jsonl] · faculty schema <faculty> [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  if (!FACULTIES.includes(f)) {
+    console.error(`unknown faculty: ${f ?? '(none)'} — one of ${FACULTIES.join(' · ')}`);
+    process.exitCode = 1;
+    return;
+  }
+  const agentDir = paths().dir;
+
+  if (sub === 'schema') {
+    const { schema } = facultySchemaData(agentDir, f);
+    log(JSON.stringify(schema, null, 2));
+    return;
+  }
+
+  const data = facultyItemsData(agentDir, f);
+  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[f];
+  log(`${f} — ${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

@@ -86,7 +86,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 +96,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

@@ -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/init.mjs

@@ -16,7 +16,7 @@ import { applyScaffold, ensureGitignore, homeExists } from '../scaffold.mjs';
 import { injectBlock, facultiesBlock, hasBlock, BLOCK_VERSION } from '../inject.mjs';
 import { detected } from '../capture/adapters/registry.mjs';
 import { repoRoot } from '../store.mjs';
-import { migrateHome } from './migrate.mjs';
+import { migrateHome, migrateItems, needsItemsMigration } from './migrate.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 +80,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);