@zuzuucodes/cli 1.4.0 → 1.6.0

package/zuzuu/faculties/actions/index.mjs

@@ -0,0 +1,283 @@
+// zuzuu/faculties/actions/index.mjs — the Actions faculty module.
+//
+// Consolidates the adapter (the inbox gate over dir-shaped proposals, WS2-T3),
+// the miner (recurring Bash 2-gram sequences → runbook proposals, WS5-T2) and
+// the digest section behind the Faculty Module contract. Substrate code stays
+// in zuzuu/actions/ — this module is the contract face.
+//
+// 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
+// record via `getProposal`, lists pending via `listProposals`, and — because
+// the payload is dir-shaped — archives rejections via `rejectDir` (a dir move
+// into actions/proposals/archive/, not a JSON archive).
+
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { listActions, allActions, inboxDir, actionsDir, isSafeSlug } from '../../actions/manifest.mjs';
+import { activateAction, rejectAction } from '../../actions/inbox.mjs';
+import { parseEnvelope, validateEnvelope, serializeEnvelope, PAYLOAD_SCHEMAS } from '../../faculty/envelope.mjs';
+import { slugify } from '../../knowledge/items.mjs';
+
+const name = 'actions';
+
+export const manifest = {
+  id: 'actions',
+  title: 'Actions',
+  tagline: 'how to DO things — runbooks + runnable scripts',
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['runbook', 'script'],
+  itemsDir: '.',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: true, eval: false, gate: false },
+  ui: { icon: 'play', accent: 'success', teaching: 'Reusable runbooks and scripts, mined from how you actually work and approved by you.' },
+};
+
+// ---------------------------------------------------------------------------
+// adapter contract
+// ---------------------------------------------------------------------------
+
+/** Build a spine-shaped proposal record for one proposed action. */
+function recordFor(a) {
+  return {
+    id: a.slug,
+    faculty: name,
+    kind: 'action',
+    status: 'pending',
+    source: 'agent',
+    payload: { slug: a.slug, kind: a.kind, dir: `inbox/${a.slug}` },
+    // carry render hints alongside the payload (cheap, dir read already done)
+    title: a.title,
+    promptSnippet: a.promptSnippet,
+    analysis: {},
+    evidence: {},
+    provenance: [],
+  };
+}
+
+/**
+ * Pending action proposals (dirs in .zuzuu/actions/inbox/), surfaced as
+ * spine-shaped records so the gate can render/approve/reject them uniformly.
+ */
+function listProposals(agentDir) {
+  return listActions(inboxDir(agentDir)).map(recordFor);
+}
+
+/** Resolve a single proposed action by slug → spine-shaped record, or null. */
+function getProposal(agentDir, slug) {
+  if (!isSafeSlug(slug)) return null;
+  return listProposals(agentDir).find((p) => p.id === slug) ?? null;
+}
+
+/**
+ * Ingest is a pass-through for Actions: proposing scaffolds a dir
+ * (zuzuu act propose / act-author). Kept for adapter-contract symmetry.
+ */
+function ingest(_agentDir, raw) {
+  return { payload: raw?.payload ?? raw ?? {}, analysis: {} };
+}
+
+/**
+ * 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[]}}
+ */
+export 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.md');
+  if (!existsSync(manPath)) return { ok: true, 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: [] };
+}
+
+/**
+ * Apply an approved action proposal: activate it (move inbox/<slug> → <slug>).
+ * Preserves the "already exists" guard from activateAction.
+ * @returns {{ok:boolean, action:string, itemIds:string[], warnings:string[]}}
+ */
+function apply(agentDir, proposal) {
+  const slug = proposal?.payload?.slug ?? proposal?.id;
+  const r = activateAction(agentDir, slug);
+  if (!r.ok) return { ok: false, action: r.error, itemIds: [], warnings: [] };
+  return { ok: true, action: `activated ${slug}`, itemIds: [slug], warnings: [] };
+}
+
+export const applyProposal = apply;
+
+/**
+ * Reject path: dir-shaped, so the gate calls this instead of the JSON archive.
+ * Moves inbox/<slug> → actions/proposals/archive/<slug> (archive, not delete).
+ */
+function rejectDir(agentDir, slug, _reason = '') {
+  return rejectAction(agentDir, slug);
+}
+
+/**
+ * Render a proposed action for the human gate. `card` mirrors the current review
+ * card (slug ── kind, then the prompt snippet); `line` is the one-line list form.
+ * @returns {{line:string, card:string}}
+ */
+function render(proposal) {
+  const slug = proposal?.id ?? proposal?.payload?.slug ?? '';
+  const kind = proposal?.payload?.kind ?? proposal?.kind ?? 'action';
+  const snippet = proposal?.promptSnippet ?? '';
+  return {
+    line: `${slug}  [${kind}]  ${snippet}`,
+    card: `${slug} ── ${kind}\n  ${snippet}`,
+  };
+}
+
+export const adapter = { name, ingest, validate, apply, render, listProposals, getProposal, rejectDir };
+
+// ---------------------------------------------------------------------------
+// miner (WS5-T2 — recurring Bash 2-grams → runbook proposals, unchanged)
+// ---------------------------------------------------------------------------
+
+// Must match the constant in knowledge/distill.mjs (adjacent Bash separator).
+const SEQ_SEP = ' && ';
+
+/**
+ * Derive a safe slug from a raw sequence string (bounded, safe chars only).
+ * e.g. "npm ci && npm test" → "npm-ci-npm-test" (max 50 chars).
+ */
+function slugFromSequence(seq) {
+  const raw = slugify(seq.replace(/ && /g, ' '), 50);
+  // slugify already returns safe chars [a-z0-9-]; isSafeSlug allows upper too,
+  // but we keep lower for readability. Force-safe just in case.
+  return raw || 'action-sequence';
+}
+
+/**
+ * Aggregate recurring Bash 2-gram sequences from mined sessions.
+ *
+ * @param {Array<{sessionId:string, sequences:string[]}>} sessions
+ *   The per-session mineTranscript output array.
+ * @param {object} opts
+ * @param {number} [opts.minSeqCount=3]    min total occurrences across all sessions
+ * @param {number} [opts.minSeqSessions=2] min distinct sessions the sequence appears in
+ * @returns {Array<{payload:{slug,title,steps,promptSnippet,sequence}, evidence:{occurrences,sessions,sequence}}>}
+ */
+export function aggregate(sessions, { minSeqCount = 3, minSeqSessions = 2 } = {}) {
+  // Count occurrences per sequence string, tracking distinct session ids.
+  const stats = new Map(); // rawSeq → { count, sessions: Set<sessionId> }
+  for (const s of sessions) {
+    if (!Array.isArray(s.sequences)) continue;
+    for (const seq of s.sequences) {
+      const st = stats.get(seq) ?? { count: 0, sessions: new Set() };
+      st.count++;
+      st.sessions.add(s.sessionId);
+      stats.set(seq, st);
+    }
+  }
+
+  const candidates = [];
+  for (const [seq, st] of stats) {
+    if (st.count < minSeqCount || st.sessions.size < minSeqSessions) continue;
+    const steps = seq.split(SEQ_SEP);
+    const slug = slugFromSequence(seq);
+    // Make sure the slug is safe; if not, skip rather than emit a bad slug.
+    if (!isSafeSlug(slug)) continue;
+    const title = `Run sequence: ${steps.join(' → ')}`;
+    const promptSnippet = `Runs: ${steps.join(' then ')}`;
+    candidates.push({
+      payload: { slug, title, steps, promptSnippet, sequence: seq },
+      evidence: { occurrences: st.count, sessions: st.sessions.size, sequence: seq },
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Write a runbook action proposal into actions/inbox/<slug>/ for each candidate.
+ * Idempotent: skips if inbox/<slug>/ OR active actions/<slug>/ already exists.
+ *
+ * @param {string} agentDir
+ * @param {ReturnType<typeof aggregate>} aggregated
+ * @returns {number} count of new proposals written
+ */
+export function propose(agentDir, aggregated) {
+  const actDir = actionsDir(agentDir);
+  const ibDir = inboxDir(agentDir);
+  let count = 0;
+  for (const c of aggregated) {
+    const { slug, title, steps, promptSnippet } = c.payload;
+    const inboxSlug = join(ibDir, slug);
+    const activeSlug = join(actDir, slug);
+    // Idempotent: skip if already proposed or already active.
+    if (existsSync(inboxSlug) || existsSync(activeSlug)) continue;
+
+    mkdirSync(inboxSlug, { recursive: true });
+
+    // ACTION.md — a runbook envelope (no run.mjs; the body IS the procedure).
+    // The body's first line is the digest one-liner (promptSnippet).
+    const stepsBlock = steps.map((cmd, i) => `${i + 1}. \`${cmd}\``).join('\n');
+    writeFileSync(join(inboxSlug, 'ACTION.md'), serializeEnvelope({
+      id: slug,
+      faculty: 'actions',
+      kind: 'runbook',
+      title,
+      status: 'active',
+      created_at: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+      provenance: [],
+      payload: {},
+      body: `${promptSnippet}\n\nRecurring command sequence detected from session traces.\n\n## Steps\n\n${stepsBlock}`,
+    }));
+
+    count++;
+  }
+  return count;
+}
+
+export const miner = { faculty: name, aggregate, propose };
+
+// ---------------------------------------------------------------------------
+// digest section (moved from the pre-module digest, byte-identical output)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Actions digest section: available actions under the shared char budget.
+ * Renders NOTHING when no actions exist (preserved pre-module behaviour).
+ * @param {string} agentDir
+ * @param {{limit:number, charBudget:number, priorLines:string[]}} ctx
+ * @returns {{lines: string[], data: object}}
+ */
+export function digestSection(agentDir, { limit, charBudget, priorLines }) {
+  let actions;
+  try {
+    const list = allActions(agentDir);
+    actions = { count: list.length, shown: list.slice(0, limit).map((a) => ({ slug: a.slug, kind: a.kind, promptSnippet: a.promptSnippet })) };
+  } catch {
+    actions = { count: 0, shown: [] };
+  }
+  if (!actions.count) return { lines: [], data: { ...actions, renderedCount: 0 } };
+  const lines = ['## Actions'];
+  lines.push(`${actions.count} available; run with \`zuzuu act <slug>\`:`);
+  let shownA = 0;
+  for (const a of actions.shown) {
+    const line = `- ${a.slug} · ${a.promptSnippet}`;
+    if ([...priorLines, ...lines].join('\n').length + line.length > charBudget && shownA > 0) break;
+    lines.push(line);
+    shownA++;
+  }
+  const droppedA = actions.count - shownA;
+  if (droppedA > 0) lines.push(`- … (${droppedA} more — \`zuzuu act list\`)`);
+  // mirror the Knowledge contract: shown reflects what actually rendered
+  return { lines, data: { ...actions, shown: actions.shown.slice(0, shownA), renderedCount: shownA } };
+}
+
+// ---------------------------------------------------------------------------
+// session signals (the observability surface — `zuzuu session inspect`)
+// ---------------------------------------------------------------------------
+
+/** Counts of the mined-signal superset slices this faculty grows from. */
+export function sessionSignals(signals = {}) {
+  return { sequences: signals.sequences?.length ?? 0 };
+}

package/zuzuu/faculties/guardrails/index.mjs

@@ -0,0 +1,320 @@
+// zuzuu/faculties/guardrails/index.mjs — the Guardrails faculty module.
+//
+// Consolidates the adapter (rule proposals → envelope items), the miner
+// (repeated destructive-command failures → ask-only rules, WS5-T3), the digest
+// section and the GATE hook (the only faculty with one — the enforced
+// PreToolUse engine) behind the Faculty Module contract. The rule engine
+// itself stays in zuzuu/guardrails/engine.mjs (the gate's hot path imports it
+// directly too); this module is the contract face.
+//
+// A guardrails proposal payload is a single rule record:
+//   { id, action: deny|ask|allow, tool, pattern, reason, body? }
+//
+// MANDATORY MINER SAFETY PROPERTIES (enforced in aggregate):
+//   1. action is ALWAYS 'ask' — never 'deny'. Auto-proposed rules only escalate
+//      to the human prompt, they never hard-block.
+//   2. Patterns are LITERAL-ESCAPED from the observed command — never a broad/
+//      free regex.  escapeRegex() handles this.
+//   3. Cross-session corroboration required — a destructive command must fail
+//      ≥minFailures (default 3) times across ≥minSessions (default 2) DISTINCT
+//      sessions.  A single session — no matter how many failures — produces
+//      NOTHING.
+
+import { join } from 'node:path';
+import { writeFacultyItem } from '../../faculty/items.mjs';
+import { deriveTitle } from '../../faculty/envelope.mjs';
+import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../../faculty/proposal.mjs';
+import { loadRules, evaluate } from '../../guardrails/engine.mjs';
+import { slugify } from '../../knowledge/items.mjs';
+
+const name = 'guardrails';
+
+export const manifest = {
+  id: 'guardrails',
+  title: 'Guardrails',
+  tagline: 'what NOT to do — enforced rules on every tool call',
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['rule'],
+  itemsDir: 'items',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: true, eval: false, gate: true },
+  ui: { icon: 'shield', accent: 'danger', teaching: 'Hard rules enforced by the zuzuu gate on every tool call — a refusal here is policy, not preference.' },
+};
+
+const VALID_ACTIONS = new Set(['deny', 'ask', 'allow']);
+
+// ---------------------------------------------------------------------------
+// adapter contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Ingest a raw rule object. Pass-through: rule fields are the payload.
+ * @param {string} agentDir
+ * @param {object} raw  — expected shape: { id, action, tool, pattern, reason }
+ *                         or { payload: { ... } } from the spine
+ */
+function ingest(_agentDir, raw) {
+  const payload = raw?.payload ?? raw ?? {};
+  return { payload, analysis: {}, dedupeKey: payload.id };
+}
+
+/**
+ * Validate a rule payload.
+ * @returns {{ok:boolean, errors:string[], warnings:string[]}}
+ */
+export function validate(_agentDir, payload) {
+  const errors = [];
+  if (!payload?.id || typeof payload.id !== 'string' || !payload.id.trim()) {
+    errors.push('rule id is required (non-empty string slug)');
+  }
+  if (!VALID_ACTIONS.has(payload?.action)) {
+    errors.push(`action must be one of deny|ask|allow (got '${payload?.action}')`);
+  }
+  if (!payload?.tool || typeof payload.tool !== 'string') {
+    errors.push('tool is required (exact tool name or \'*\')');
+  }
+  if (typeof payload?.pattern !== 'string' || !payload.pattern) {
+    errors.push('pattern is required (a non-empty regex string)');
+  } else {
+    try {
+      new RegExp(payload.pattern); // eslint-disable-line no-new
+    } catch (e) {
+      errors.push(`pattern does not compile as a RegExp: ${e.message}`);
+    }
+  }
+  if (!payload?.reason || !String(payload.reason).trim()) {
+    errors.push('reason is required (non-empty)');
+  }
+  return { ok: errors.length === 0, errors, warnings: [] };
+}
+
+/**
+ * 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;
+  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] };
+}
+
+export const applyProposal = apply;
+
+/**
+ * Render a rule proposal for the human gate.
+ * @returns {{line:string, card:string}}
+ */
+function render(proposal) {
+  const r = proposal?.payload ?? {};
+  const summary = `${r.action ?? '?'} ${r.tool ?? '*'} /${r.pattern ?? ''}/ — ${r.reason ?? ''}`;
+  return {
+    line: `${r.id ?? ''}  [rule]  ${summary}`,
+    card: summary,
+  };
+}
+
+export const adapter = { name, ingest, validate, apply, render };
+
+// ---------------------------------------------------------------------------
+// gate hook — the ONLY faculty with one; same fail-open law as the engine
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate one tool call against this home's rule items.
+ * @param {string} agentDir
+ * @param {{tool:string, input:any}} toolCall
+ * @returns {null | {action:'deny'|'ask'|'allow', rule:string, reason:string}}
+ *          null = no rule matched / engine trouble → host's normal flow (fail-open)
+ */
+export function gate(agentDir, toolCall) {
+  try {
+    const loaded = loadRules(join(agentDir, 'guardrails'));
+    if (!loaded.ok) return null;
+    return evaluate(loaded.rules, toolCall);
+  } catch {
+    return null; // fail open
+  }
+}
+
+// ---------------------------------------------------------------------------
+// miner (WS5-T3 — destructive-failure clusters → ask-only rules, unchanged)
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape all regex metacharacters in `s` so that `new RegExp(escapeRegex(s))`
+ * matches exactly the string `s` and nothing broader.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function escapeRegex(s) {
+  // Standard set of regex metacharacters that need escaping.
+  return String(s).replace(/[.*+?^${}()|[\]\\\/\-]/g, '\\$&');
+}
+
+/** Normalise a command string (trim + collapse whitespace). */
+const norm = (cmd) => String(cmd).trim().replace(/\s+/g, ' ').slice(0, 200);
+
+/** Derive a guardrails-miner id for a command. */
+function guardId(cmd) {
+  return 'guard-' + slugify(cmd, 50);
+}
+
+/** Ids of live rule items (guardrails/items/*.md); absent/unreadable → none. */
+function liveRuleIds(agentDir) {
+  try {
+    return new Set(loadRules(join(agentDir, 'guardrails')).rules.map((r) => r.id));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Group destructiveFailures by normalised command; emit a candidate ONLY when
+ * both the occurrence count and distinct-session count meet their thresholds.
+ *
+ * SAFETY: a single-session cluster, no matter how large, produces NOTHING.
+ *
+ * @param {Array<{sessionId:string, destructiveFailures:{cmd:string,tool:string}[]}>} sessions
+ * @param {object} opts
+ * @param {number} [opts.minFailures=3]   min total failures across all sessions
+ * @param {number} [opts.minSessions=2]  min distinct sessions with ≥1 failure each
+ * @returns {Array<{payload:{id,action,tool,pattern,reason}, evidence:{occurrences,sessions}}>}
+ */
+export function aggregate(sessions, { minFailures = 3, minSessions = 2 } = {}) {
+  // cmd (normalized) → { count: number, sessions: Set<sessionId>, tool: string }
+  const stats = new Map();
+
+  for (const s of sessions) {
+    if (!Array.isArray(s.destructiveFailures)) continue;
+    for (const { cmd, tool } of s.destructiveFailures) {
+      const key = norm(cmd);
+      const st = stats.get(key) ?? { count: 0, sessions: new Set(), tool: tool ?? 'Bash' };
+      st.count++;
+      st.sessions.add(s.sessionId);
+      // Keep first observed tool name (they should all be 'Bash' for destructive cmds).
+      stats.set(key, st);
+    }
+  }
+
+  const candidates = [];
+  for (const [cmd, st] of stats) {
+    // SAFETY: enforce BOTH thresholds — cross-session gate is the key one.
+    if (st.count < minFailures) continue;
+    if (st.sessions.size < minSessions) continue; // ← single-session always rejected here
+
+    const id = guardId(cmd);
+    const pattern = escapeRegex(cmd);
+    const tool = st.tool ?? 'Bash';
+
+    candidates.push({
+      payload: {
+        id,
+        // SAFETY: ALWAYS 'ask', never 'deny'.
+        action: 'ask',
+        tool,
+        pattern,
+        reason: `auto-proposed: '${cmd}' failed repeatedly across sessions — confirm before running`,
+      },
+      evidence: {
+        occurrences: st.count,
+        sessions: st.sessions.size,
+      },
+    });
+  }
+
+  return candidates;
+}
+
+/**
+ * Write a guardrails proposal into .zuzuu/guardrails/proposals/ for each candidate.
+ * Idempotent:
+ *   - skips if a guardrails proposal with the same payload.id already exists
+ *   - skips if a live rule item (guardrails/items/<id>.md) already exists
+ *   - skips if the id is already resolved in proposals/archive/ — a rejection
+ *     is remembered; re-distilling never resurrects it
+ *
+ * The proposals flow through `zuzuu review` → guardrails adapter on approval.
+ *
+ * @param {string} agentDir
+ * @param {ReturnType<typeof aggregate>} aggregated
+ * @returns {number} count of new proposals written
+ */
+export function propose(agentDir, aggregated) {
+  // Load existing proposals (ids already pending).
+  const existing = listProposals(agentDir, 'guardrails');
+  const existingIds = new Set(existing.map((p) => p.payload?.id).filter(Boolean));
+
+  // Live rule items (ids already applied).
+  const rulesIds = liveRuleIds(agentDir);
+
+  let count = 0;
+  for (const c of aggregated) {
+    const { payload, evidence } = c;
+
+    // Idempotent: skip if already proposed or already a live rule.
+    if (existingIds.has(payload.id)) continue;
+    if (rulesIds.has(payload.id)) continue;
+
+    const proposal = makeProposal({
+      faculty: 'guardrails',
+      kind: 'rule',
+      source: 'distill',
+      payload,
+      evidence,
+    });
+
+    // A rejection is remembered: never resurrect an archive-resolved id.
+    if (isArchivedResolved(agentDir, 'guardrails', proposal.id)) continue;
+
+    writeProposal(agentDir, proposal);
+    count++;
+  }
+
+  return count;
+}
+
+export const miner = { faculty: name, aggregate, propose };
+
+// ---------------------------------------------------------------------------
+// digest section (moved from the pre-module digest, byte-identical output)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Guardrails digest section: rule count + the enforcement reminder.
+ * @param {string} agentDir
+ * @returns {{lines: string[], data: object}}
+ */
+export function digestSection(agentDir) {
+  let guardrails;
+  try {
+    const loaded = loadRules(join(agentDir, 'guardrails'));
+    guardrails = { ok: loaded.ok, count: loaded.ok ? loaded.rules.length : 0, skipped: loaded.skipped?.length ?? 0 };
+  } catch {
+    guardrails = { ok: false, count: 0, skipped: 0 };
+  }
+  const lines = ['## Guardrails'];
+  lines.push(guardrails.count ? `${guardrails.count} rule(s) — the enforced gate is on; refusals are policy.` : 'no rules configured.');
+  return { lines, data: guardrails };
+}
+
+// ---------------------------------------------------------------------------
+// session signals (the observability surface — `zuzuu session inspect`)
+// ---------------------------------------------------------------------------
+
+/** Counts of the mined-signal superset slices this faculty grows from. */
+export function sessionSignals(signals = {}) {
+  return { destructiveFailures: signals.destructiveFailures?.length ?? 0 };
+}