@zuzuucodes/cli 1.4.0 → 1.6.0

package/zuzuu/instructions/adapter.mjs

@@ -1,93 +0,0 @@
-// zuzuu/instructions/adapter.mjs
-// The Instructions faculty adapter (WS2-T4). Wraps steering-amendment proposals
-// behind the faculty-spine adapter contract — { name, ingest, validate, apply,
-// render } — so `zuzuu review` can surface and approve them uniformly.
-//
-// An instructions proposal payload is a steering amendment:
-//   { text }  — a line or paragraph to append to project.md
-//
-// apply: appends the text as a line to .zuzuu/instructions/project.md (creates
-//        the file if absent; never duplicates an already-present line).
-//
-// Registers itself on import.
-
-import { join } from 'node:path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import * as registry from '../faculty/registry.mjs';
-
-const name = 'instructions';
-
-// ---------------------------------------------------------------------------
-// helpers
-// ---------------------------------------------------------------------------
-
-function projectMdPath(agentDir) {
-  return join(agentDir, 'instructions', 'project.md');
-}
-
-// ---------------------------------------------------------------------------
-// adapter contract
-// ---------------------------------------------------------------------------
-
-/**
- * Ingest a raw amendment object. Pass-through: the payload IS the amendment.
- */
-function ingest(_agentDir, raw) {
-  const payload = raw?.payload ?? raw ?? {};
-  return { payload, analysis: {} };
-}
-
-/**
- * Validate an amendment payload.
- * @returns {{ok:boolean, errors:string[], warnings:string[]}}
- */
-function validate(_agentDir, payload) {
-  const errors = [];
-  if (!payload?.text || !String(payload.text).trim()) {
-    errors.push('text is required (non-empty steering amendment)');
-  }
-  return { ok: errors.length === 0, errors, warnings: [] };
-}
-
-/**
- * Apply an approved amendment: append text to project.md (idempotent on
- * identical lines — won't duplicate a line already present).
- * @returns {{ok:boolean, action:string, itemIds:string[]}}
- */
-function apply(agentDir, proposal) {
-  const text = proposal?.payload?.text ?? '';
-
-  // Ensure the instructions dir exists
-  mkdirSync(join(agentDir, 'instructions'), { recursive: true });
-
-  const path = projectMdPath(agentDir);
-  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
-
-  // Idempotence: skip if the exact text is already present
-  if (existing.includes(text)) {
-    return { ok: true, action: 'amended instructions (already present)', itemIds: [] };
-  }
-
-  // Append (with trailing newline)
-  const separator = existing && !existing.endsWith('\n') ? '\n' : '';
-  writeFileSync(path, existing + separator + text + '\n');
-
-  return { ok: true, action: 'amended instructions', itemIds: [] };
-}
-
-/**
- * Render an amendment proposal for the human gate.
- * @returns {{line:string, card:string}}
- */
-function render(proposal) {
-  const text = proposal?.payload?.text ?? '';
-  const preview = text.slice(0, 80).replace(/\n/g, ' ');
-  return {
-    line: `[amendment]  ${preview}`,
-    card: text,
-  };
-}
-
-export const adapter = { name, ingest, validate, apply, render };
-
-registry.register(adapter);

package/zuzuu/knowledge/adapter.mjs

@@ -1,99 +0,0 @@
-// zuzuu/knowledge/adapter.mjs
-// The Knowledge faculty adapter (WS2-T2). Wraps the EXISTING Knowledge pipeline
-// (proposals/ER/registry/items/index) behind the faculty-spine adapter contract
-// — { name, ingest, validate, apply, render } — without changing any behaviour.
-//
-//   ingest   — run ER on a candidate, mirroring createProposal's analysis step
-//   validate — registry-based validation of an item
-//   apply    — IS the extracted approve apply body (applyKnowledgeProposal)
-//   render   — the human card the `zuzuu review` gate shows for a knowledge proposal
-//
-// Registers itself on import.
-
-import { resolve as erResolve } from './er.mjs';
-import { loadRegistry, validateItem } from './registry.mjs';
-import { allItems, slugify } from './items.mjs';
-import { applyKnowledgeProposal } from './proposals.mjs';
-import * as registry from '../faculty/registry.mjs';
-
-const name = 'knowledge';
-
-/**
- * Ingest a raw candidate: run ER against existing items and return the
- * normalised payload + analysis. Mirrors what createProposal computes today.
- * @param {string} agentDir
- * @param {{candidate:object, source?:string, evidence?:object}} raw
- */
-function ingest(agentDir, raw) {
-  const { items } = allItems(agentDir);
-  const candidate = { ...raw.candidate };
-  candidate.id = candidate.id || slugify(candidate.body);
-  const er = erResolve(candidate, items);
-  return { payload: candidate, analysis: { er }, dedupeKey: candidate.id };
-}
-
-/**
- * Validate an item against the Knowledge registry.
- * @returns {{ok:boolean, errors:string[], warnings:string[]}}
- */
-function validate(agentDir, payload) {
-  const reg = loadRegistry(agentDir);
-  const v = validateItem(reg, payload);
-  const warnings = [
-    ...v.unknownKeys.attributes.map((k) => `unregistered attribute '${k}'`),
-    ...v.unknownKeys.relations.map((t) => `unregistered relation type '${t}'`),
-  ];
-  return { ok: v.ok, errors: v.errors, warnings };
-}
-
-/**
- * Apply an approved proposal — delegates to the extracted approve apply body.
- * @returns {{ok:boolean, action:string, itemIds:string[], warnings:string[]}}
- */
-function apply(agentDir, proposal) {
-  // Bridge spine-shaped records (payload/analysis.er) onto applyKnowledgeProposal's
-  // legacy shape (candidate/er). Records that still carry candidate/er pass through.
-  const legacy = {
-    ...proposal,
-    candidate: proposal.candidate ?? proposal.payload,
-    er: proposal.er ?? proposal.analysis?.er,
-  };
-  const r = applyKnowledgeProposal(agentDir, legacy);
-  return {
-    ok: r.ok,
-    action: r.action,
-    itemIds: r.item ? [r.item] : [],
-    warnings: r.warnings ?? [],
-  };
-}
-
-/**
- * Render a proposal for the human gate. `card` mirrors the multi-line summary
- * `zuzuu review` shows for knowledge proposals (id, type, attrs/relations, ER
- * verdict); `line` is the one-line list form (`zuzuu proposals list`).
- * @returns {{line:string, card:string}}
- */
-function render(proposal) {
-  if (proposal.kind === 'registry') {
-    const what = `register ${String(proposal.registry).slice(0, -1)} '${proposal.key}'`;
-    return {
-      line: `${proposal.id}  [${proposal.kind}]  ${what}`,
-      card: `${what}  (seen ${proposal.evidence?.occurrences}× in candidates)`,
-    };
-  }
-  const c = proposal.candidate ?? {};
-  const er = proposal.er ?? {};
-  const lines = [];
-  lines.push(`${c.id ?? ''} ── ${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}`);
-  lines.push(`  er: ${er.verdict}${er.match ? ` → ${er.match}` : ''}  (${(er.confidence ?? 0).toFixed(2)} · ${er.reason ?? ''})`);
-  return {
-    line: `${proposal.id}  [${er.verdict ?? proposal.kind}]  ${c.type}: ${c.body?.slice(0, 60).replace(/\n/g, ' ')}`,
-    card: lines.join('\n'),
-  };
-}
-
-export const adapter = { name, ingest, validate, apply, render };
-
-registry.register(adapter);

package/zuzuu/memory/adapter.mjs

@@ -1,121 +0,0 @@
-// zuzuu/memory/adapter.mjs
-// The Memory faculty adapter (WS2-T4). Wraps episode proposals behind the
-// faculty-spine adapter contract — { name, ingest, validate, apply, render } —
-// so `zuzuu review` can surface and approve memory entries uniformly.
-//
-// A memory proposal payload is an episode record matching the WS1 Memory schema:
-//   { id, date, title, provenance, body }
-//   id format: mem-<YYYY-MM-DD>-<slug>
-//
-// apply: writes .zuzuu/memory/entries/<id>.md with YAML frontmatter (status: curated)
-//        and the body sections (Attempted / Resulted / Remember next time).
-//
-// Registers itself on import.
-
-import { join } from 'node:path';
-import { writeFileSync, mkdirSync } from 'node:fs';
-import * as registry from '../faculty/registry.mjs';
-
-const name = 'memory';
-
-// mem-<YYYY-MM-DD>-<slug>: the id must START with "mem-"
-const MEM_ID_RE = /^mem-/;
-
-// ---------------------------------------------------------------------------
-// helpers
-// ---------------------------------------------------------------------------
-
-function entriesDir(agentDir) {
-  return join(agentDir, 'memory', 'entries');
-}
-
-function entryPath(agentDir, id) {
-  return join(entriesDir(agentDir), `${id}.md`);
-}
-
-/** Render YAML frontmatter block from the payload fields. */
-function renderFrontmatter(payload) {
-  const lines = ['---'];
-  lines.push(`id: ${payload.id}`);
-  if (payload.date) lines.push(`date: ${payload.date}`);
-  if (payload.title) lines.push(`title: ${payload.title}`);
-  if (payload.provenance) {
-    lines.push('provenance:');
-    const p = payload.provenance;
-    if (Array.isArray(p.sessions)) lines.push(`  sessions: [${p.sessions.join(', ')}]`);
-    if (Array.isArray(p.hosts)) lines.push(`  hosts: [${p.hosts.join(', ')}]`);
-  }
-  if (Array.isArray(payload.tags) && payload.tags.length) {
-    lines.push(`tags: [${payload.tags.join(', ')}]`);
-  }
-  lines.push('status: curated');
-  lines.push('---');
-  return lines.join('\n');
-}
-
-// ---------------------------------------------------------------------------
-// adapter contract
-// ---------------------------------------------------------------------------
-
-/**
- * Ingest a raw episode. Pass-through: the payload IS the episode.
- */
-function ingest(_agentDir, raw) {
-  const payload = raw?.payload ?? raw ?? {};
-  return { payload, analysis: {}, dedupeKey: payload.id };
-}
-
-/**
- * Validate an episode payload.
- * @returns {{ok:boolean, errors:string[], warnings:string[]}}
- */
-function validate(_agentDir, payload) {
-  const errors = [];
-  if (!payload?.id || typeof payload.id !== 'string') {
-    errors.push('id is required');
-  } else if (!MEM_ID_RE.test(payload.id)) {
-    errors.push(`id must match mem-<YYYY-MM-DD>-<slug> format (got '${payload.id}')`);
-  }
-  if (!payload?.title || !String(payload.title).trim()) {
-    errors.push('title is required');
-  }
-  return { ok: errors.length === 0, errors, warnings: [] };
-}
-
-/**
- * Apply an approved episode proposal: write the entry Markdown file.
- * @returns {{ok:boolean, action:string, itemIds:string[]}}
- */
-function apply(agentDir, proposal) {
-  const payload = proposal?.payload ?? {};
-  const id = payload.id;
-
-  mkdirSync(entriesDir(agentDir), { recursive: true });
-
-  const frontmatter = renderFrontmatter(payload);
-  const body = payload.body ?? '';
-  const content = frontmatter + '\n' + body + (body.endsWith('\n') ? '' : '\n');
-
-  writeFileSync(entryPath(agentDir, id), content);
-
-  return { ok: true, action: `wrote memory ${id}`, itemIds: [id] };
-}
-
-/**
- * Render an episode proposal for the human gate.
- * @returns {{line:string, card:string}}
- */
-function render(proposal) {
-  const p = proposal?.payload ?? {};
-  const title = p.title ?? '';
-  const date = p.date ?? '';
-  const id = p.id ?? '';
-  return {
-    line: `${id}  [episode]  ${title} (${date})`,
-    card: `${title}\n  id: ${id}  date: ${date}`,
-  };
-}
-
-export const adapter = { name, ingest, validate, apply, render };
-
-registry.register(adapter);

package/zuzuu/miners/actions.mjs

@@ -1,118 +0,0 @@
-// zuzuu/miners/actions.mjs
-// Actions miner (WS5-T2) — detect recurring Bash 2-gram sequences across
-// sessions and scaffold runbook proposals into actions/inbox/<slug>/.
-//
-// Shape: { faculty:'actions', aggregate(sessions, opts), propose(agentDir, aggregated) }
-// Self-registers on import.
-
-import { join } from 'node:path';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { slugify } from '../knowledge/items.mjs';
-import { isSafeSlug, actionsDir, inboxDir } from '../actions/manifest.mjs';
-import { register } from './registry.mjs';
-
-// 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.json — minimal manifest (no run.mjs; this is a runbook action).
-    const manifest = {
-      slug,
-      title,
-      description: `Recurring command sequence detected from session traces: ${steps.join(' → ')}.`,
-      promptSnippet,
-    };
-    writeFileSync(join(inboxSlug, 'action.json'), JSON.stringify(manifest, null, 2) + '\n');
-
-    // SKILL.md — numbered runbook steps.
-    const stepsBlock = steps.map((cmd, i) => `${i + 1}. \`${cmd}\``).join('\n');
-    const skillMd = `---
-name: ${title}
-description: ${manifest.description}
----
-
-## Steps
-
-${stepsBlock}
-`;
-    writeFileSync(join(inboxSlug, 'SKILL.md'), skillMd);
-
-    count++;
-  }
-  return count;
-}
-
-export const miner = { faculty: 'actions', aggregate, propose };
-
-register(miner);

package/zuzuu/miners/guardrails.mjs

@@ -1,179 +0,0 @@
-// zuzuu/miners/guardrails.mjs
-// Guardrails miner (WS5-T3) — detect repeated destructive-command failures
-// across sessions and propose ask-only guardrail rules.
-//
-// MANDATORY 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.
-//
-// Shape: { faculty:'guardrails', aggregate(sessions, opts), propose(agentDir, aggregated) }
-// Self-registers on import.
-
-import { join } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
-import { slugify } from '../knowledge/items.mjs';
-import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../faculty/proposal.mjs';
-import { register } from './registry.mjs';
-
-// ---------------------------------------------------------------------------
-// escapeRegex — the ONLY safe way to build a pattern from a literal command.
-// Escapes all RegExp metacharacters so the pattern matches the exact string.
-
-/**
- * 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, '\\$&');
-}
-
-// ---------------------------------------------------------------------------
-// helpers
-
-/** 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);
-}
-
-/** Load rules.json; returns { version, rules:[] } if absent/unreadable. */
-function loadRules(agentDir) {
-  const path = join(agentDir, 'guardrails', 'rules.json');
-  if (!existsSync(path)) return { version: 1, rules: [] };
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return { version: 1, rules: [] };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// aggregate
-
-/**
- * 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;
-}
-
-// ---------------------------------------------------------------------------
-// propose
-
-/**
- * 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 rules.json already has a rule with that id
- *   - 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));
-
-  // Load existing rules (ids already applied).
-  const rulesData = loadRules(agentDir);
-  const rulesIds = new Set((rulesData.rules ?? []).map((r) => r.id).filter(Boolean));
-
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// self-register
-
-export const miner = { faculty: 'guardrails', aggregate, propose };
-
-register(miner);