@zuzuucodes/cli 1.5.0 → 1.6.0

package/zuzuu/miners/actions.mjs

@@ -1,112 +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 { serializeEnvelope } from '../faculty/envelope.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.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: 'actions', aggregate, propose };
-
-register(miner);

package/zuzuu/miners/guardrails.mjs

@@ -1,176 +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 { slugify } from '../knowledge/items.mjs';
-import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../faculty/proposal.mjs';
-import { loadRules as loadRuleItems } from '../guardrails.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);
-}
-
-/** Ids of live rule items (guardrails/items/*.md); absent/unreadable → none. */
-function liveRuleIds(agentDir) {
-  try {
-    return new Set(loadRuleItems(join(agentDir, 'guardrails')).rules.map((r) => r.id));
-  } catch {
-    return new Set();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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 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;
-}
-
-// ---------------------------------------------------------------------------
-// self-register
-
-export const miner = { faculty: 'guardrails', aggregate, propose };
-
-register(miner);

package/zuzuu/miners/instructions.mjs

@@ -1,157 +0,0 @@
-// zuzuu/miners/instructions.mjs
-// Instructions miner (WS5-T4) — detect recurring corrective user turns across
-// sessions and propose steering-amendment blocks for the Instructions faculty.
-//
-// Corrective turns are captured by mineTranscript as:
-//   correctionTurns: [{ text }]  — user turns following an assistant tool action
-//   that contain corrective lexicon (e.g. "always", "never", "don't", etc.)
-//
-// Shape: { faculty:'instructions', aggregate(sessions, opts), propose(agentDir, aggregated) }
-// Self-registers on import.
-
-import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../faculty/proposal.mjs';
-import { listFacultyItems } from '../faculty/items.mjs';
-import { register } from './registry.mjs';
-
-// ---------------------------------------------------------------------------
-// helpers
-
-/**
- * Normalise a correction text for grouping:
- * lowercase, collapse whitespace, truncate to 200 chars.
- *
- * v1 grouping: near-identical normalised text (exact key match). Simple and
- * deterministic; a fuzzy grouper can be earned later.
- *
- * @param {string} text
- * @returns {string}
- */
-function normText(text) {
-  return String(text).toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 200);
-}
-
-/**
- * Derive a proposal id fragment from a normalised text key.
- * Keep it stable, short, and filesystem-safe.
- */
-function instrId(normKey) {
-  // Use a slugified version of the first 60 chars of the normalised text,
-  // prefixed to make collisions with other faculties impossible.
-  const slug = normKey.slice(0, 60).replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 50) || 'instr';
-  return 'instr-' + slug;
-}
-
-// ---------------------------------------------------------------------------
-// aggregate
-
-/**
- * Group correctionTurns from mined sessions; propose when a similar correction
- * recurs across ≥minSessions (default 2) distinct sessions.
- *
- * @param {Array<{sessionId:string, correctionTurns:{text:string}[]}>} sessions
- * @param {object} opts
- * @param {number} [opts.minSessions=2] min distinct sessions with the same normalised correction
- * @returns {Array<{payload:{text:string}, evidence:{occurrences:number, sessions:number}}>}
- */
-export function aggregate(sessions, { minSessions = 2 } = {}) {
-  // normalised text → { count, sessions: Set<sessionId>, rawText: string }
-  const stats = new Map();
-
-  for (const s of sessions) {
-    if (!Array.isArray(s.correctionTurns)) continue;
-    // Track distinct normalised texts per session to avoid double-counting
-    // the same session for the same correction text.
-    const seenInSession = new Set();
-    for (const { text } of s.correctionTurns) {
-      const key = normText(text);
-      if (!key) continue;
-      const st = stats.get(key) ?? { count: 0, sessions: new Set(), rawText: text };
-      st.count++;
-      st.sessions.add(s.sessionId);
-      seenInSession.add(key);
-      stats.set(key, st);
-    }
-  }
-
-  const candidates = [];
-  for (const [, st] of stats) {
-    if (st.sessions.size < minSessions) continue;
-
-    // Phrase the raw correction as an instruction for the steering amendment.
-    // The corrective turn text already reads like user guidance; use it directly
-    // (trimmed to 500 chars to match mineTranscript's cap).
-    const amendmentText = st.rawText.slice(0, 500).trim();
-    const id = instrId(normText(amendmentText));
-
-    candidates.push({
-      payload: { id, text: amendmentText },
-      evidence: { occurrences: st.count, sessions: st.sessions.size },
-    });
-  }
-
-  return candidates;
-}
-
-// ---------------------------------------------------------------------------
-// propose
-
-/**
- * Write an instructions proposal into .zuzuu/instructions/proposals/ for each
- * candidate.
- *
- * Idempotent:
- *   - skips if an instructions proposal with the same derived id already exists
- *   - skips if the text is already present in an instructions item (steering
- *     or a prior amendment)
- *   - skips if the id is already resolved in proposals/archive/ — a rejection
- *     is remembered; re-distilling never resurrects it
- *
- * @param {string} agentDir
- * @param {ReturnType<typeof aggregate>} aggregated
- * @returns {number} count of new proposals written
- */
-export function propose(agentDir, aggregated) {
-  // Collect ids of existing pending proposals for this faculty.
-  const existing = listProposals(agentDir, 'instructions');
-  const existingIds = new Set(existing.map((p) => p.payload?.id).filter(Boolean));
-
-  // Read the instructions items (steering + amendments) to skip applied text.
-  let appliedText = '';
-  try {
-    appliedText = listFacultyItems(agentDir, 'instructions').items.map((i) => i.body ?? '').join('\n');
-  } catch { appliedText = ''; }
-
-  let count = 0;
-  for (const c of aggregated) {
-    const { payload, evidence } = c;
-
-    // Idempotent: skip if already proposed.
-    if (existingIds.has(payload.id)) continue;
-
-    // Idempotent: skip if text already present in an instructions item.
-    if (appliedText.includes(payload.text)) continue;
-
-    const proposal = makeProposal({
-      faculty: 'instructions',
-      kind: 'block',
-      source: 'distill',
-      payload,
-      evidence,
-    });
-
-    // A rejection is remembered: never resurrect an archive-resolved id.
-    if (isArchivedResolved(agentDir, 'instructions', proposal.id)) continue;
-
-    writeProposal(agentDir, proposal);
-    count++;
-  }
-
-  return count;
-}
-
-// ---------------------------------------------------------------------------
-// self-register
-
-export const miner = { faculty: 'instructions', aggregate, propose };
-
-register(miner);

package/zuzuu/miners/knowledge.mjs

@@ -1,25 +0,0 @@
-// Knowledge miner (WS5-T1) — the existing source-A distill path, wrapped as a
-// registry miner. NO behavior change: `aggregate` is the same function the
-// golden distill test asserts on; `propose` mirrors `distillSessions` (one
-// `createProposal` per aggregated candidate). Self-registers on import.
-
-import { aggregate } from '../knowledge/distill.mjs';
-import { createProposal } from '../knowledge/proposals.mjs';
-import { register } from './registry.mjs';
-
-/** File one knowledge proposal per aggregated candidate; return the count of
- *  actually-filed proposals (archive-resolved ids are skipped, not re-filed). */
-export function propose(agentDir, aggregated) {
-  let count = 0;
-  for (const c of aggregated) {
-    const p = createProposal(agentDir, { candidate: c.candidate, source: 'distill', evidence: c.evidence });
-    if (p && p.status !== 'archived-skip') count++;
-  }
-  return count;
-}
-
-export const miner = { faculty: 'knowledge', aggregate, propose };
-
-register(miner);
-
-export { aggregate };

package/zuzuu/miners/memory.mjs

@@ -1,27 +0,0 @@
-// zuzuu/miners/memory.mjs
-// Memory miner STUB (WS5-T4) — registered no-op; deferred this pass.
-//
-// WHAT IT WOULD MINE (when implemented):
-//   Completed-session episodes — a Run that reached `completed` status in
-//   .zuzuu/sessions.json — would be distilled into curated episode entries at
-//   .zuzuu/memory/entries/<id>.md. Each entry captures: what was attempted,
-//   key decisions made, outcome, and a set of durable learnings. The miner
-//   would emit `memory` proposals of kind 'episode' into
-//   .zuzuu/memory/proposals/ for human review via `zuzuu review`. Deferred until
-//   the Memory substrate (off-edge Postgres/Neon or local Markdown) is
-//   established and the session lifecycle state machine is stable enough to
-//   reliably produce `completed` runs with rich enough trace data to distill.
-//
-// Shape: { faculty:'memory', aggregate, propose, stub:true }
-// Self-registers on import (no-op).
-
-import { register } from './registry.mjs';
-
-export const miner = {
-  faculty: 'memory',
-  stub: true,
-  aggregate: () => [],
-  propose: () => 0,
-};
-
-register(miner);

package/zuzuu/miners/registry.mjs

@@ -1,31 +0,0 @@
-// Miner registry (WS5-T1) — the faculty-mining plugin table.
-//
-// Each miner is `{ faculty, aggregate(sessions, opts) -> candidates,
-// propose(agentDir, candidates) -> count }`. The `--all-faculties` distill driver
-// mines every transcript once into a shared `sessions` array, then runs each
-// registered miner's aggregate + propose. Miners self-register on import.
-
-const miners = [];
-
-/** Register a miner. Re-registering the same faculty replaces it (idempotent import). */
-export function register(miner) {
-  const i = miners.findIndex((m) => m.faculty === miner.faculty);
-  if (i >= 0) miners[i] = miner;
-  else miners.push(miner);
-  return miner;
-}
-
-/** All registered miners. */
-export function all() {
-  return miners.slice();
-}
-
-/** The miner for a faculty, or undefined. */
-export function get(faculty) {
-  return miners.find((m) => m.faculty === faculty);
-}
-
-/** Clear the registry — tests only. */
-export function reset() {
-  miners.length = 0;
-}