@zuzuucodes/cli 1.5.0 → 1.6.0

package/zuzuu/digest/compose.mjs

@@ -0,0 +1,96 @@
+// zuzuu/digest/compose.mjs
+// The grounding digest — a pure, deterministic, zero-network, no-model brief of
+// the faculty home, injected at session start. Returns { text, sections }.
+// I/O-free: callers (the CLI + the SessionStart hook) handle output.
+//
+// Composition (the Faculty Module contract): each built-in module exports its
+// own digestSection(agentDir, ctx); this file iterates the registry and stacks
+// the sections in the canonical order — instructions → knowledge → actions →
+// proposals (spine-level) → guardrails — then a default "N item(s)" section
+// for every DECLARATIVE faculty. Every hook call rides registry.invoke
+// (fail-soft): a single broken faculty never sinks the whole digest.
+
+import { listProposals } from '../knowledge/proposals.mjs';
+import { listFacultyItems } from '../faculty/items.mjs';
+import { facultiesOf, invoke } from '../faculty/registry.mjs';
+
+// The canonical section order (instructions/knowledge/actions render above the
+// proposals block; guardrails closes the brief — preserved pre-module layout).
+const HEAD_SECTIONS = ['instructions', 'knowledge', 'actions'];
+const TAIL_SECTIONS = ['guardrails'];
+
+function proposalsSection(agentDir) {
+  try {
+    // count only pending — defensive if listProposals ever returns archived too
+    const pending = listProposals(agentDir).filter((p) => p.status === 'pending');
+    return { pending: pending.length };
+  } catch {
+    return { pending: 0 };
+  }
+}
+
+/** Run one faculty's digestSection hook fail-soft; null = no section. */
+function sectionOf(entry, agentDir, ctx) {
+  const r = invoke(entry, 'digestSection', agentDir, ctx);
+  if (!r.ok || !r.value || !Array.isArray(r.value.lines)) return null;
+  return r.value;
+}
+
+/** The default section a faculty WITHOUT a digest hook gets: "N item(s)". */
+function defaultSection(agentDir, entry) {
+  let count = 0;
+  try {
+    count = listFacultyItems(agentDir, entry.id, { itemsDir: entry.manifest?.itemsDir }).items.length;
+  } catch { /* unreadable → 0 */ }
+  return { lines: [`## ${entry.manifest?.title ?? entry.id}`, `${count} item(s)`], data: { count } };
+}
+
+/**
+ * Compute the digest for a faculty home.
+ * @param {string} agentDir  path to the .zuzuu/ directory
+ * @param {{ knowledgeLimit?: number, budget?: number }} options
+ * @returns {{ text: string, sections: object }}
+ */
+export function computeDigest(agentDir, { knowledgeLimit = 5, budget = 1500 } = {}) {
+  const charBudget = budget * 4;
+  const sections = {};
+  const lines = ['# zuzuu faculty digest', ''];
+
+  const faculties = facultiesOf(agentDir);
+  const byId = new Map(faculties.map((f) => [f.id, f]));
+  const ctx = () => ({ limit: knowledgeLimit, charBudget, priorLines: lines });
+
+  for (const id of HEAD_SECTIONS) {
+    const s = sectionOf(byId.get(id), agentDir, ctx());
+    if (!s) continue;
+    sections[id] = s.data;
+    if (s.lines.length) lines.push(...s.lines, '');
+  }
+
+  // Proposals — spine-level (cross-faculty pending count lives with the gate).
+  const proposals = proposalsSection(agentDir);
+  sections.proposals = proposals;
+  if (proposals.pending > 0) {
+    lines.push('## Proposals');
+    lines.push(`${proposals.pending} proposal(s) await your approval — run \`zuzuu review\`; approving mints a generation (your checkpoint).`);
+    lines.push('');
+  }
+
+  for (const id of TAIL_SECTIONS) {
+    const s = sectionOf(byId.get(id), agentDir, ctx());
+    if (!s) continue;
+    sections[id] = s.data;
+    if (s.lines.length) lines.push(...s.lines, '');
+  }
+
+  // Declarative faculties (manifest-only): the default "N item(s)" line each —
+  // a faculty you drop into the home is mentioned in the very next brief.
+  for (const entry of faculties) {
+    if (!entry.declarative || entry.manifestError) continue;
+    const s = sectionOf(entry, agentDir, ctx()) ?? defaultSection(agentDir, entry);
+    sections[entry.id] = s.data;
+    if (s.lines.length) lines.push(...s.lines, '');
+  }
+
+  return { text: lines.join('\n').trimEnd() + '\n', sections };
+}

package/zuzuu/eval/score.mjs

@@ -1,8 +1,14 @@
 // zuzuu/eval/score.mjs
 // Mechanical scorer — weighted sum of normalized signals → { score, confidence, rationale, signals }.
 // Pure; deterministic; no FS, no Date.now(), no Math.random().
+//
+// Faculty Module hook: a module may export evalSignals(proposal) → PARTIAL
+// signals; those overlay the mechanical extraction (fail-soft via the
+// registry's invoke — a broken hook leaves the default scorer untouched).
+// No built-in implements it today, so behavior is unchanged.
 
 import { extractSignals } from './signals.mjs';
+import { BUILTIN_MODULES, invoke } from '../faculty/registry.mjs';
 
 // Weight vector (must sum to 1.0).
 const W = {
@@ -60,7 +66,14 @@ function buildRationale(s) {
  * @returns {{ score: number, confidence: string, rationale: string, signals: object }}
  */
 export function mechanicalScore(proposal, opts = {}) {
-  const s = extractSignals(proposal, opts);
+  let s = extractSignals(proposal, opts);
+
+  // Optional per-faculty evalSignals hook — partial overlay, fail-soft.
+  const mod = BUILTIN_MODULES[proposal?.faculty];
+  if (mod && typeof mod.evalSignals === 'function') {
+    const r = invoke({ id: proposal.faculty, module: mod }, 'evalSignals', proposal);
+    if (r.ok && r.value && typeof r.value === 'object') s = { ...s, ...r.value };
+  }
 
   const raw =
     W.occurrence       * s.occurrence +

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 };
+}