@zuzuucodes/cli 1.4.0 → 1.6.0

package/zuzuu/faculties/instructions/index.mjs

@@ -0,0 +1,288 @@
+// zuzuu/faculties/instructions/index.mjs — the Instructions faculty module.
+//
+// Consolidates the adapter (steering-amendment proposals → envelope items),
+// the miner (recurring corrective user turns → amendment proposals, WS5-T4)
+// and the digest section (the steering text the agent grounds on) behind the
+// Faculty Module contract.
+//
+// An instructions proposal payload is a steering amendment:
+//   { id?, text }  — a line or paragraph of steering
+//
+// apply: writes the amendment as a Faculty Standard envelope item under
+//        .zuzuu/instructions/items/<id>.md (kind: amendment; body = the text).
+//        The pinned steering itself lives at items/steering.md; future
+//        amendments are MORE items, never edits to steering. Idempotent: a
+//        text already present in any instructions item is not duplicated.
+
+import { listFacultyItems, writeFacultyItem } from '../../faculty/items.mjs';
+import { deriveTitle } from '../../faculty/envelope.mjs';
+import { makeProposal, writeProposal, listProposals, isArchivedResolved } from '../../faculty/proposal.mjs';
+import { slugify } from '../../knowledge/items.mjs';
+
+const name = 'instructions';
+
+export const manifest = {
+  id: 'instructions',
+  title: 'Instructions',
+  tagline: 'who to BE — steering and project conventions',
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['steering', 'amendment'],
+  itemsDir: 'items',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: true, eval: false, gate: false },
+  ui: { icon: 'compass', accent: 'warning', teaching: 'The pinned steering the agent is told at session start; corrections graduate into amendments here.' },
+};
+
+// ---------------------------------------------------------------------------
+// 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[]}}
+ */
+export 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: write an amendment item (idempotent on
+ * identical text — won't duplicate steering already present in any item).
+ * @returns {{ok:boolean, action:string, itemIds:string[]}}
+ */
+function apply(agentDir, proposal) {
+  const text = String(proposal?.payload?.text ?? '').trim();
+
+  // Idempotence: skip if the exact text already lives in an instructions item
+  const { items } = listFacultyItems(agentDir, 'instructions');
+  if (items.some((i) => String(i.body ?? '').includes(text))) {
+    return { ok: true, action: 'amended instructions (already present)', itemIds: [] };
+  }
+
+  const id = proposal?.payload?.id || slugify(text, 50);
+  writeFacultyItem(agentDir, {
+    id,
+    faculty: name,
+    kind: 'amendment',
+    title: deriveTitle(text, id),
+    status: 'active',
+    created_at: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    provenance: Array.isArray(proposal?.provenance) ? proposal.provenance : [],
+    payload: { scope: 'project' },
+    body: text,
+  });
+
+  return { ok: true, action: 'amended instructions', itemIds: [id] };
+}
+
+export const applyProposal = apply;
+
+/**
+ * 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 };
+
+// ---------------------------------------------------------------------------
+// miner (WS5-T4 — recurring corrective turns → amendment proposals, unchanged)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+export const miner = { faculty: name, aggregate, propose };
+
+// ---------------------------------------------------------------------------
+// digest section (moved from the pre-module digest, byte-identical output)
+// ---------------------------------------------------------------------------
+
+const PLACEHOLDER_MARK = '<!-- Fill in:';
+
+const INTERVIEW = [
+  'Project steering is empty. Before substantive work, interview your human',
+  '(what is this project, its conventions, its priorities), draft the steering item',
+  '.zuzuu/instructions/items/steering.md from their answers, and get their approval.',
+].join(' ');
+
+/** Read the instructions items (steering first, then amendments); classify
+ *  empty vs steering text. Items are Faculty Standard envelopes (W24). */
+function readInstructions(agentDir) {
+  let items = [];
+  try {
+    items = listFacultyItems(agentDir, 'instructions').items;
+  } catch { /* missing or unreadable → treat as empty */ }
+  // steering pins the top; amendments follow in id order (already sorted)
+  items.sort((a, b) => (a.kind === 'steering' ? -1 : 1) - (b.kind === 'steering' ? -1 : 1));
+  const bodies = items
+    .map((i) => String(i.body ?? ''))
+    .map((raw) => (raw.includes(PLACEHOLDER_MARK) ? '' : raw.replace(/^#.*$/gm, '').trim() && raw.trim()))
+    .filter(Boolean);
+  const text = bodies.join('\n\n');
+  return { empty: !text, text };
+}
+
+/**
+ * The Instructions digest section: the pinned steering (or the interview
+ * prompt when empty). Always renders — grounding starts here.
+ * @param {string} agentDir
+ * @returns {{lines: string[], data: object}}
+ */
+export function digestSection(agentDir) {
+  const instr = readInstructions(agentDir);
+  return { lines: ['## Instructions', instr.empty ? INTERVIEW : instr.text], data: instr };
+}
+
+// ---------------------------------------------------------------------------
+// session signals (the observability surface — `zuzuu session inspect`)
+// ---------------------------------------------------------------------------
+
+/** Counts of the mined-signal superset slices this faculty grows from. */
+export function sessionSignals(signals = {}) {
+  return { correctionTurns: signals.correctionTurns?.length ?? 0 };
+}

package/zuzuu/faculties/knowledge/index.mjs

@@ -0,0 +1,185 @@
+// zuzuu/faculties/knowledge/index.mjs — the Knowledge faculty module.
+//
+// Consolidates the faculty's spine surface behind the Faculty Module contract
+// (faculty.json manifest + hook exports): the adapter (ingest/validate/apply/
+// render — wraps the EXISTING Knowledge pipeline: proposals/ER/registry/items/
+// index), the miner (the source-A distill path), and the digest section.
+// Substrate code stays in zuzuu/knowledge/ — this module is the contract face.
+
+import { resolve as erResolve } from '../../knowledge/er.mjs';
+import { loadRegistry, validateItem } from '../../knowledge/registry.mjs';
+import { allItems, slugify } from '../../knowledge/items.mjs';
+import { applyKnowledgeProposal, createProposal } from '../../knowledge/proposals.mjs';
+import { aggregate } from '../../knowledge/distill.mjs';
+
+const name = 'knowledge';
+
+export const manifest = {
+  id: 'knowledge',
+  title: 'Knowledge',
+  tagline: "what's TRUE — facts about this project",
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['fact', 'entity', 'command', 'decision'],
+  itemsDir: 'items',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: true, eval: false, gate: false },
+  ui: { icon: 'book', accent: 'info', teaching: 'Facts zuzuu learns from your sessions land here after your approval.' },
+};
+
+// ---------------------------------------------------------------------------
+// adapter (WS2-T2 — unchanged behaviour)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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[]}}
+ */
+export 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 ?? [],
+  };
+}
+
+export const applyProposal = apply;
+
+/**
+ * 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 };
+
+// ---------------------------------------------------------------------------
+// miner (WS5-T1 — the golden source-A distill path, unchanged)
+// ---------------------------------------------------------------------------
+
+/** 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: name, aggregate, propose };
+
+export { aggregate };
+
+// ---------------------------------------------------------------------------
+// digest section (moved from the pre-module digest, byte-identical output)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Knowledge digest section: most-recent items under the shared char budget.
+ * @param {string} agentDir
+ * @param {{limit:number, charBudget:number, priorLines:string[]}} ctx
+ * @returns {{lines: string[], data: object}}
+ */
+export function digestSection(agentDir, { limit, charBudget, priorLines }) {
+  let knowledge;
+  try {
+    const { items } = allItems(agentDir);
+    const ranked = [...items]
+      .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))
+      .slice(0, limit);
+    knowledge = { count: items.length, shown: ranked.map((i) => ({ id: i.id, type: i.type, body: i.body })) };
+  } catch {
+    knowledge = { count: 0, shown: [] };
+  }
+  const lines = ['## Knowledge'];
+  if (!knowledge.count) {
+    lines.push('(no items yet — propose facts to knowledge/inbox/)');
+    return { lines, data: { ...knowledge, renderedCount: 0 } };
+  }
+  lines.push(`${knowledge.count} item(s); most recent:`);
+  let shown = 0;
+  for (const it of knowledge.shown) {
+    const line = `- ${it.id} · ${it.type} · ${it.body.split('\n')[0].slice(0, 80)}`;
+    // join is O(items²) but trivial: once-per-session, limit default 5
+    if ([...priorLines, ...lines].join('\n').length + line.length > charBudget && shown > 0) break;
+    lines.push(line);
+    shown++;
+  }
+  const dropped = knowledge.count - shown;
+  if (dropped > 0) lines.push(`- … (${dropped} more — \`zuzuu recall\`)`);
+  // `shown` = items actually rendered (after budget); `count` = total available
+  return { lines, data: { ...knowledge, shown: knowledge.shown.slice(0, shown), renderedCount: shown } };
+}
+
+// ---------------------------------------------------------------------------
+// session signals (the observability surface — `zuzuu session inspect`)
+// ---------------------------------------------------------------------------
+
+/** Counts of the mined-signal superset slices this faculty grows from. */
+export function sessionSignals(signals = {}) {
+  return {
+    commands: signals.commands?.length ?? 0,
+    files: signals.files?.length ?? 0,
+    failures: signals.failures?.length ?? 0,
+  };
+}

package/zuzuu/faculties/memory/index.mjs

@@ -0,0 +1,124 @@
+// zuzuu/faculties/memory/index.mjs — the Memory faculty module.
+//
+// Consolidates the adapter (episode proposals → envelope entries) and the
+// miner STUB (WS5-T4, deferred — see the WHAT IT WOULD MINE note below) behind
+// the Faculty Module contract. No digest section today (the pre-module digest
+// never rendered one — preserved).
+//
+// A memory proposal payload is an episode record:
+//   { id, date, title, provenance: {sessions, hosts}, tags, body }
+//   id format: mem-<YYYY-MM-DD>-<slug>
+//
+// apply: writes .zuzuu/memory/entries/<id>.md as a Faculty Standard envelope
+//        (kind: episode; payload = {sessions, hosts, tags}; body = the
+//        Attempted / Resulted / Remember-next-time sections).
+//
+// MINER (when implemented): completed-session episodes — a Run that reached
+// `completed` in .zuzuu/sessions.json distilled into curated entries, emitted
+// as kind-'episode' proposals for `zuzuu review`. Deferred until the Memory
+// substrate decision lands and completed runs carry rich enough trace data.
+
+import { writeFacultyItem } from '../../faculty/items.mjs';
+
+const name = 'memory';
+
+export const manifest = {
+  id: 'memory',
+  title: 'Memory',
+  tagline: 'what HAPPENED — curated episodes from past sessions',
+  version: '1.0.0',
+  contract: 1,
+  kinds: ['episode'],
+  itemsDir: 'entries',
+  schema: 'schema.json',
+  hooks: { miner: true, digest: false, eval: false, gate: false },
+  ui: { icon: 'clock', accent: 'neutral', teaching: 'Curated episodes from past sessions — what was attempted, what resulted, what to remember.' },
+};
+
+// mem-<YYYY-MM-DD>-<slug>: the id must START with "mem-"
+const MEM_ID_RE = /^mem-/;
+
+// ---------------------------------------------------------------------------
+// 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[]}}
+ */
+export 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 envelope entry file.
+ * @returns {{ok:boolean, action:string, itemIds:string[]}}
+ */
+function apply(agentDir, proposal) {
+  const p = proposal?.payload ?? {};
+  const envPayload = {};
+  if (Array.isArray(p.provenance?.sessions) && p.provenance.sessions.length) envPayload.sessions = p.provenance.sessions.map(String);
+  if (Array.isArray(p.provenance?.hosts) && p.provenance.hosts.length) envPayload.hosts = p.provenance.hosts.map(String);
+  if (Array.isArray(p.tags) && p.tags.length) envPayload.tags = p.tags.map(String);
+
+  writeFacultyItem(agentDir, {
+    id: p.id,
+    faculty: name,
+    kind: 'episode',
+    title: p.title,
+    status: 'active',
+    created_at: p.date || new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+    provenance: Array.isArray(proposal?.provenance) ? proposal.provenance : [],
+    payload: envPayload,
+    body: p.body ?? '',
+  });
+
+  return { ok: true, action: `wrote memory ${p.id}`, itemIds: [p.id] };
+}
+
+export const applyProposal = apply;
+
+/**
+ * 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 };
+
+// ---------------------------------------------------------------------------
+// miner (registered no-op stub — deferred)
+// ---------------------------------------------------------------------------
+
+export const miner = {
+  faculty: name,
+  stub: true,
+  aggregate: () => [],
+  propose: () => 0,
+};