@zuzuucodes/cli 1.0.0

package/zuzuu/knowledge/index.mjs

@@ -0,0 +1,194 @@
+// The Knowledge index — SQLite (node:sqlite, zero-dep), fully DERIVED from the
+// item files and regenerable at any time: files are truth, this is the
+// search/query plane ("pin definitions, observe data").
+//
+// Triple search on one store (the Apache-AGE pattern — graph inside relational —
+// plus a vector column):
+//   relational: SQL over items/attrs            (type/attribute filters)
+//   graph:      recursive CTEs over rels        (neighbors/paths; Cypher syntax
+//                                                arrives at the real AGE rung)
+//   semantic:   vecs + cosine                   (populated when an embedding
+//                                                source exists — see embed.mjs)
+
+import { join, dirname } from 'node:path';
+import { mkdirSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { allItems } from './items.mjs';
+
+const require = createRequire(import.meta.url);
+export const indexPath = (agentDir) => join(agentDir, 'knowledge', '.index.db');
+
+function open(agentDir, { readOnly = false } = {}) {
+  const { DatabaseSync } = require('node:sqlite');
+  const path = indexPath(agentDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path, readOnly && existsSync(path) ? { readOnly: true } : {});
+  return db;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS items(id TEXT PRIMARY KEY, type TEXT, text TEXT, created_at TEXT, status TEXT);
+CREATE TABLE IF NOT EXISTS attrs(item TEXT, key TEXT, value TEXT, PRIMARY KEY(item, key));
+CREATE TABLE IF NOT EXISTS rels(src TEXT, type TEXT, dst TEXT, PRIMARY KEY(src, type, dst));
+CREATE TABLE IF NOT EXISTS vecs(item TEXT PRIMARY KEY, model TEXT, vec BLOB);
+CREATE INDEX IF NOT EXISTS attrs_kv ON attrs(key, value);
+CREATE INDEX IF NOT EXISTS rels_dst ON rels(dst);
+`;
+
+function ensureSchema(db) {
+  db.exec(SCHEMA);
+}
+
+/** Upsert one item into the index (keeps any existing vector). */
+export function upsertItem(agentDir, item) {
+  const db = open(agentDir);
+  try {
+    ensureSchema(db);
+    db.prepare('INSERT OR REPLACE INTO items(id,type,text,created_at,status) VALUES(?,?,?,?,?)').run(
+      item.id, item.type, item.body ?? '', item.created_at ?? '', item.status ?? 'active');
+    db.prepare('DELETE FROM attrs WHERE item=?').run(item.id);
+    for (const [k, v] of Object.entries(item.attributes ?? {}))
+      db.prepare('INSERT OR REPLACE INTO attrs(item,key,value) VALUES(?,?,?)').run(item.id, k, String(v));
+    db.prepare('DELETE FROM rels WHERE src=?').run(item.id);
+    for (const r of item.relations ?? [])
+      db.prepare('INSERT OR REPLACE INTO rels(src,type,dst) VALUES(?,?,?)').run(item.id, r.type, r.target);
+  } finally {
+    db.close();
+  }
+}
+
+/** Full rebuild from the item files. Deterministic. Returns counts. */
+export function reindex(agentDir) {
+  const { items, errors } = allItems(agentDir);
+  const db = open(agentDir);
+  try {
+    ensureSchema(db);
+    db.exec('DELETE FROM items; DELETE FROM attrs; DELETE FROM rels;'); // vecs kept (re-embedding is separate)
+    const insI = db.prepare('INSERT INTO items(id,type,text,created_at,status) VALUES(?,?,?,?,?)');
+    const insA = db.prepare('INSERT OR REPLACE INTO attrs(item,key,value) VALUES(?,?,?)');
+    const insR = db.prepare('INSERT OR REPLACE INTO rels(src,type,dst) VALUES(?,?,?)');
+    for (const it of items) {
+      insI.run(it.id, it.type, it.body ?? '', it.created_at ?? '', it.status ?? 'active');
+      for (const [k, v] of Object.entries(it.attributes ?? {})) insA.run(it.id, k, String(v));
+      for (const r of it.relations ?? []) insR.run(it.id, r.type, r.target);
+    }
+    // prune vectors for items that no longer exist
+    db.exec('DELETE FROM vecs WHERE item NOT IN (SELECT id FROM items)');
+    return { indexed: items.length, parseErrors: errors };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Lexical + relational search (Notes-style scoring: id hit +10, attribute hit +5,
+ * body occurrences ×2 capped at 8). Filters: type, attribute k=v.
+ */
+export function search(agentDir, query, { type = null, attr = null, limit = 10 } = {}) {
+  if (!existsSync(indexPath(agentDir))) return [];
+  const db = open(agentDir, { readOnly: true });
+  try {
+    ensureSchema(db);
+    let rows = db.prepare('SELECT id, type, text, status FROM items').all();
+    if (type) rows = rows.filter((r) => r.type === type);
+    if (attr) {
+      const [k, v] = attr;
+      const ids = new Set(db.prepare('SELECT item FROM attrs WHERE key=? AND value=?').all(k, v).map((r) => r.item));
+      rows = rows.filter((r) => ids.has(r.id));
+    }
+    const attrRows = db.prepare('SELECT item, key, value FROM attrs').all();
+    const attrText = new Map();
+    for (const a of attrRows) attrText.set(a.item, (attrText.get(a.item) ?? '') + ' ' + a.key + ' ' + a.value);
+    const terms = String(query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    const scored = rows.map((r) => {
+      let score = 0;
+      const id = r.id.toLowerCase();
+      const body = (r.text ?? '').toLowerCase();
+      const attrs = (attrText.get(r.id) ?? '').toLowerCase();
+      for (const t of terms) {
+        if (id.includes(t)) score += 10;
+        if (attrs.includes(t)) score += 5;
+        const hits = body.split(t).length - 1;
+        score += Math.min(hits * 2, 8);
+      }
+      return { ...r, score };
+    });
+    return scored
+      .filter((r) => (terms.length ? r.score > 0 : true))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Graph traversal: items within `depth` hops of `id` (optionally one relation
+ * type), via a recursive CTE — both directions (relations are conceptually
+ * bidirectional; inverses live in the registry).
+ */
+export function neighbors(agentDir, id, { relType = null, depth = 1 } = {}) {
+  if (!existsSync(indexPath(agentDir))) return [];
+  const db = open(agentDir, { readOnly: true });
+  try {
+    ensureSchema(db);
+    const typeCond = relType ? 'AND r.type = ?' : '';
+    const params = relType ? [id, relType, relType, depth] : [id, depth];
+    const sql = `
+      WITH RECURSIVE walk(node, via, hop) AS (
+        SELECT CASE WHEN r.src = ? THEN r.dst ELSE r.src END, r.type, 1
+        FROM rels r WHERE (r.src = walk_start() OR r.dst = walk_start()) ${typeCond}
+        UNION
+        SELECT CASE WHEN r.src = w.node THEN r.dst ELSE r.src END, r.type, w.hop + 1
+        FROM rels r JOIN walk w ON (r.src = w.node OR r.dst = w.node) ${typeCond ? 'AND r.type = ?' : ''}
+        WHERE w.hop < ?
+      ) SELECT DISTINCT node, via, MIN(hop) AS hop FROM walk GROUP BY node, via`;
+    // node:sqlite has no custom functions; inline the start id instead of walk_start()
+    const inlined = sql.replaceAll('walk_start()', '?');
+    // param order: src-case ?, (start, start), [relType], [relType], depth
+    const finalParams = relType ? [id, id, id, relType, relType, depth] : [id, id, id, depth];
+    const rows = db.prepare(inlined).all(...finalParams);
+    return rows.filter((r) => r.node !== id);
+  } finally {
+    db.close();
+  }
+}
+
+/** Store / fetch embedding vectors (Float32 LE blobs). */
+export function putVector(agentDir, itemId, model, floats) {
+  const db = open(agentDir);
+  try {
+    ensureSchema(db);
+    const buf = Buffer.from(new Float32Array(floats).buffer);
+    db.prepare('INSERT OR REPLACE INTO vecs(item,model,vec) VALUES(?,?,?)').run(itemId, model, buf);
+  } finally {
+    db.close();
+  }
+}
+
+export function allVectors(agentDir) {
+  if (!existsSync(indexPath(agentDir))) return [];
+  const db = open(agentDir, { readOnly: true });
+  try {
+    ensureSchema(db);
+    return db.prepare('SELECT item, model, vec FROM vecs').all().map((r) => ({
+      item: r.item,
+      model: r.model,
+      vec: new Float32Array(r.vec.buffer, r.vec.byteOffset, r.vec.byteLength / 4),
+    }));
+  } finally {
+    db.close();
+  }
+}
+
+/** Items in the index but lacking a vector (embedding backlog). */
+export function unembedded(agentDir) {
+  if (!existsSync(indexPath(agentDir))) return [];
+  const db = open(agentDir, { readOnly: true });
+  try {
+    ensureSchema(db);
+    return db.prepare('SELECT id, type, text FROM items WHERE id NOT IN (SELECT item FROM vecs)').all();
+  } finally {
+    db.close();
+  }
+}

package/zuzuu/knowledge/items.mjs

@@ -0,0 +1,154 @@
+// Knowledge items — files as truth. One item per markdown file under
+// agent/knowledge/items/<id>.md: a constrained-YAML frontmatter (we control both
+// writer and reader; grammar below) + a prose body (the fact in your voice).
+//
+//   ---
+//   id: test-command
+//   type: command
+//   created_at: 2026-06-10T12:00:00Z
+//   status: active
+//   attributes:
+//     command: npm test
+//   relations:
+//     - type: relates-to
+//       target: ci-pipeline
+//       commentary: optional
+//   provenance:
+//     - session: ses_abc
+//       ref: occurrences=12
+//   ---
+//   Body prose.
+//
+// Grammar (deliberately small): top-level scalar keys; ONE nested map
+// (`attributes`); arrays of flat maps (`relations`, `provenance`). Values are
+// single-line strings (quotes optional). Anything outside this grammar is a
+// parse error — git-diffable simplicity beats YAML completeness here.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+
+export const itemsDir = (agentDir) => join(agentDir, 'knowledge', 'items');
+
+export function slugify(text, max = 60) {
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, max)
+    .replace(/-+$/, '') || 'item';
+}
+
+const unquote = (s) => {
+  const t = s.trim();
+  return (t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")) ? t.slice(1, -1) : t;
+};
+const quoteIfNeeded = (s) => {
+  const t = String(s);
+  if (t.includes('\n')) throw new Error('item values must be single-line');
+  return /[:#'"\[\]{}]|^\s|\s$/.test(t) ? JSON.stringify(t) : t;
+};
+
+/** Parse an item file's text → item object. Throws on grammar violations. */
+export function parseItem(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) throw new Error('no frontmatter block');
+  const [, fm, body] = m;
+  const item = { attributes: {}, relations: [], provenance: [], body: body.trim() };
+  let section = null; // 'attributes' | 'relations' | 'provenance'
+  let current = null; // current array entry
+  for (const raw of fm.split('\n')) {
+    if (!raw.trim()) continue;
+    const indent = raw.match(/^ */)[0].length;
+    const line = raw.trim();
+    if (indent === 0) {
+      current = null;
+      const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+      if (!kv) throw new Error(`bad line: ${line}`);
+      const [, key, val] = kv;
+      if (['attributes', 'relations', 'provenance'].includes(key)) {
+        section = key;
+        if (val) throw new Error(`${key} must be a block`);
+      } else {
+        section = null;
+        item[key] = unquote(val);
+      }
+    } else if (section === 'attributes') {
+      const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+      if (!kv) throw new Error(`bad attribute line: ${line}`);
+      item.attributes[kv[1]] = unquote(kv[2]);
+    } else if (section === 'relations' || section === 'provenance') {
+      if (line.startsWith('- ')) {
+        current = {};
+        item[section].push(current);
+        const kv = line.slice(2).match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+        if (!kv) throw new Error(`bad ${section} entry: ${line}`);
+        current[kv[1]] = unquote(kv[2]);
+      } else {
+        if (!current) throw new Error(`${section} entry continuation without "-": ${line}`);
+        const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+        if (!kv) throw new Error(`bad ${section} line: ${line}`);
+        current[kv[1]] = unquote(kv[2]);
+      }
+    } else {
+      throw new Error(`unexpected indented line: ${line}`);
+    }
+  }
+  if (!item.id) throw new Error('item missing id');
+  if (!item.type) throw new Error('item missing type');
+  return item;
+}
+
+/** Serialize an item object → file text (the exact grammar parseItem reads). */
+export function serializeItem(item) {
+  const lines = ['---'];
+  for (const key of ['id', 'type', 'created_at', 'status']) {
+    if (item[key] != null) lines.push(`${key}: ${quoteIfNeeded(item[key])}`);
+  }
+  const attrs = Object.entries(item.attributes ?? {});
+  if (attrs.length) {
+    lines.push('attributes:');
+    for (const [k, v] of attrs) lines.push(`  ${k}: ${quoteIfNeeded(v)}`);
+  }
+  for (const section of ['relations', 'provenance']) {
+    const arr = item[section] ?? [];
+    if (!arr.length) continue;
+    lines.push(`${section}:`);
+    for (const entry of arr) {
+      const keys = Object.keys(entry);
+      keys.forEach((k, i) => lines.push(`  ${i === 0 ? '- ' : '  '}${k}: ${quoteIfNeeded(entry[k])}`));
+    }
+  }
+  lines.push('---', '');
+  return lines.join('\n') + (item.body ? item.body.trim() + '\n' : '');
+}
+
+/** Write an item to its canonical file. Returns the path. */
+export function writeItem(agentDir, item) {
+  const dir = itemsDir(agentDir);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${item.id}.md`);
+  writeFileSync(path, serializeItem(item));
+  return path;
+}
+
+export function readItem(agentDir, id) {
+  const path = join(itemsDir(agentDir), `${id}.md`);
+  if (!existsSync(path)) return null;
+  return parseItem(readFileSync(path, 'utf8'));
+}
+
+/** All items (parse errors collected, not thrown — audit surfaces them). */
+export function allItems(agentDir) {
+  const dir = itemsDir(agentDir);
+  if (!existsSync(dir)) return { items: [], errors: [] };
+  const items = [];
+  const errors = [];
+  for (const f of readdirSync(dir).filter((f) => f.endsWith('.md')).sort()) {
+    try {
+      items.push(parseItem(readFileSync(join(dir, f), 'utf8')));
+    } catch (e) {
+      errors.push({ file: f, error: e.message });
+    }
+  }
+  return { items, errors };
+}

package/zuzuu/knowledge/proposals.mjs

@@ -0,0 +1,196 @@
+// Proposals — the human gate, as files. The first build of DESIGN's Proposal
+// entity: { candidate, source, evidence, er-verdict, status }. Pending under
+// agent/knowledge/proposals/<id>.json; resolved ones move to proposals/archive/
+// (an auditable history — approvals also show up as item-file diffs in git).
+//
+// Registry governance rides the same gate: an unregistered attribute/relation
+// key seen ≥3 times across proposals becomes a REGISTRY proposal (where Notes
+// silently auto-registered, we ask).
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, renameSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { loadRegistry, validateItem } from './registry.mjs';
+import { allItems, readItem, writeItem, slugify } from './items.mjs';
+import { upsertItem } from './index.mjs';
+import { resolve as erResolve, merge } from './er.mjs';
+import { mechanicalScore } from '../eval/score.mjs';
+
+export const proposalsDir = (agentDir) => join(agentDir, 'knowledge', 'proposals');
+const archiveDir = (agentDir) => join(proposalsDir(agentDir), 'archive');
+
+const shortHash = (s) => createHash('sha256').update(s).digest('hex').slice(0, 6);
+
+function writeProposal(agentDir, p) {
+  mkdirSync(proposalsDir(agentDir), { recursive: true });
+  writeFileSync(join(proposalsDir(agentDir), `${p.id}.json`), JSON.stringify(p, null, 2) + '\n');
+  return p;
+}
+
+/** Run ER for a candidate and file a pending proposal (deduped per candidate). */
+export function createProposal(agentDir, { candidate, source, evidence = {} }) {
+  const { items } = allItems(agentDir);
+  candidate.id = candidate.id || slugify(candidate.body);
+  const er = erResolve(candidate, items);
+  const id = `${candidate.id}-${shortHash(candidate.id + source)}`;
+  const existing = join(proposalsDir(agentDir), `${id}.json`);
+  if (existsSync(existing)) {
+    // refresh evidence on the pending proposal instead of duplicating it
+    const prev = JSON.parse(readFileSync(existing, 'utf8'));
+    prev.evidence = { ...prev.evidence, ...evidence };
+    prev.er = er;
+    // keep analysis in sync so scorer can use updated er verdict
+    prev.analysis = { ...(prev.analysis ?? {}), er: { verdict: er.verdict } };
+    prev.score = scoreProposal(prev);
+    return writeProposal(agentDir, prev);
+  }
+  const proposal = { id, kind: 'item', status: 'pending', created_at: new Date().toISOString(), source, candidate, evidence, er, analysis: { er: { verdict: er.verdict } } };
+  proposal.score = scoreProposal(proposal);
+  return writeProposal(agentDir, proposal);
+}
+
+/** Compute mechanicalScore for a proposal — fail-open (returns null on error). */
+function scoreProposal(proposal) {
+  try {
+    const { score, confidence, rationale } = mechanicalScore(proposal, {});
+    return { score, confidence, rationale };
+  } catch {
+    return null;
+  }
+}
+
+export function listProposals(agentDir) {
+  const dir = proposalsDir(agentDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')))
+    .sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)));
+}
+
+export function getProposal(agentDir, id) {
+  const p = join(proposalsDir(agentDir), `${id}.json`);
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null;
+}
+
+function archive(agentDir, proposal, status, extra = {}) {
+  mkdirSync(archiveDir(agentDir), { recursive: true });
+  const resolved = { ...proposal, status, resolved_at: new Date().toISOString(), ...extra };
+  writeFileSync(join(archiveDir(agentDir), `${proposal.id}.json`), JSON.stringify(resolved, null, 2) + '\n');
+  const pending = join(proposalsDir(agentDir), `${proposal.id}.json`);
+  if (existsSync(pending)) renameSync(pending, join(archiveDir(agentDir), `${proposal.id}.json`));
+  writeFileSync(join(archiveDir(agentDir), `${proposal.id}.json`), JSON.stringify(resolved, null, 2) + '\n');
+  return resolved;
+}
+
+/**
+ * Apply an approved proposal's effects — the canonical write path, extracted so
+ * the Knowledge faculty adapter (WS2-T2) can call the *same* logic. This is the
+ * registry-branch + ER-merge + writeItem + upsertItem body; it does NOT archive
+ * (the caller decides lifecycle). Behaviour is identical to the old inline body.
+ * @returns {{ok:boolean, action:string, item?:string, warnings:string[]}}
+ */
+export function applyKnowledgeProposal(agentDir, proposal) {
+  const warnings = [];
+  const id = proposal.id;
+
+  if (proposal.kind === 'registry') {
+    const file = join(agentDir, 'knowledge', 'registry', `${proposal.registry}.json`);
+    const defs = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : [];
+    if (proposal.registry === 'attributes') defs.push({ key: proposal.key, value: 'string', description: `registered via proposal ${id}` });
+    else defs.push({ name: proposal.key, inverse: proposal.key, description: `registered via proposal ${id} (symmetric — edit inverse if directional)` });
+    writeFileSync(file, JSON.stringify(defs, null, 2) + '\n');
+    return { ok: true, action: `registered ${proposal.registry.slice(0, -1)} '${proposal.key}'`, warnings };
+  }
+
+  const registry = loadRegistry(agentDir);
+  const cand = proposal.candidate;
+  const v = validateItem(registry, cand);
+  for (const k of v.unknownKeys.attributes) {
+    warnings.push(`dropped unregistered attribute '${k}' (approve its registry proposal first, then re-propose)`);
+    delete cand.attributes[k];
+  }
+  cand.relations = (cand.relations ?? []).filter((r) => {
+    if (registry.relations.has(r.type)) return true;
+    warnings.push(`dropped relation with unregistered type '${r.type}'`);
+    return false;
+  });
+  const v2 = validateItem(registry, cand);
+  if (!v2.ok) return { ok: false, action: 'invalid', warnings: [...warnings, ...v2.errors] };
+
+  let item;
+  let action;
+  if ((proposal.er?.verdict === 'enrich' || proposal.er?.verdict === 'duplicate') && proposal.er.match) {
+    const existing = readItem(agentDir, proposal.er.match);
+    if (existing) {
+      item = merge(existing, cand);
+      action = `enriched ${existing.id}`;
+    }
+  }
+  if (!item) {
+    item = { created_at: new Date().toISOString().replace(/\.\d+Z$/, 'Z'), status: 'active', attributes: {}, relations: [], provenance: [], ...cand };
+    action = `created ${item.id}`;
+  }
+  writeItem(agentDir, item);
+  upsertItem(agentDir, item);
+  return { ok: true, action, item: item.id, warnings };
+}
+
+/**
+ * Approve: registry proposals append their key; item proposals write/merge the
+ * item (unknown keys are DROPPED with warnings — knowledge stays registry-clean).
+ * Delegates the effect to applyKnowledgeProposal, then archives.
+ * @returns {{ok:boolean, action:string, item?:string, warnings:string[]}}
+ */
+export function approveProposal(agentDir, id) {
+  const proposal = getProposal(agentDir, id);
+  if (!proposal) return { ok: false, action: 'not-found', warnings: [] };
+
+  const r = applyKnowledgeProposal(agentDir, proposal);
+  if (!r.ok) return r;
+
+  if (proposal.kind === 'registry') archive(agentDir, proposal, 'approved');
+  else archive(agentDir, proposal, 'approved', { applied: r.action });
+  return r;
+}
+
+export function rejectProposal(agentDir, id, reason = '') {
+  const proposal = getProposal(agentDir, id);
+  if (!proposal) return { ok: false };
+  archive(agentDir, proposal, 'rejected', { reason });
+  return { ok: true };
+}
+
+/**
+ * Registry governance: unknown keys appearing ≥3 times across all proposals
+ * (pending + archive) get a registry proposal filed — once.
+ */
+export function fileRegistryProposals(agentDir) {
+  const registry = loadRegistry(agentDir);
+  const counts = { attributes: {}, relations: {} };
+  const dirs = [proposalsDir(agentDir), archiveDir(agentDir)];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+      let p;
+      try {
+        p = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      } catch {
+        continue;
+      }
+      if (p.kind !== 'item') continue;
+      for (const k of Object.keys(p.candidate?.attributes ?? {})) if (!registry.attributes.has(k)) counts.attributes[k] = (counts.attributes[k] ?? 0) + 1;
+      for (const r of p.candidate?.relations ?? []) if (!registry.relations.has(r.type)) counts.relations[r.type] = (counts.relations[r.type] ?? 0) + 1;
+    }
+  }
+  const filed = [];
+  for (const [kind, tally] of Object.entries(counts)) {
+    for (const [key, n] of Object.entries(tally)) {
+      if (n < 3) continue;
+      const id = `register-${kind.slice(0, 3)}-${slugify(key)}`;
+      if (getProposal(agentDir, id) || existsSync(join(archiveDir(agentDir), `${id}.json`))) continue;
+      filed.push(writeProposal(agentDir, { id, kind: 'registry', registry: kind, key, status: 'pending', created_at: new Date().toISOString(), evidence: { occurrences: n } }));
+    }
+  }
+  return filed;
+}

package/zuzuu/knowledge/registry.mjs

@@ -0,0 +1,115 @@
+// The Knowledge registry — governance for item types, attribute keys, and
+// relation types. Refined from the Notes vault's registry (types/dimensions/
+// relations JSONL): relations keep their INVERSES; unlike Notes, unknown keys
+// are never silently auto-registered — repeated use files a registry *proposal*
+// (human-gated, like everything in this system).
+//
+// Files (tracked, seeded by `zuzuu init`): agent/knowledge/registry/
+//   types.json       [{name, description}]
+//   attributes.json  [{key, value, description}]   value: "string"|"number"|"date"|"url"|{"enum":[...]}
+//   relations.json   [{name, inverse, description}]
+
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+
+export const SEED_TYPES = [
+  { name: 'fact', description: 'A declarative truth about the project/domain' },
+  { name: 'entity', description: 'A named thing — file, module, service, person, system' },
+  { name: 'command', description: 'A canonical command for this project (test, build, deploy…)' },
+  { name: 'decision', description: 'A decision made, with its why' },
+];
+
+export const SEED_ATTRIBUTES = [
+  { key: 'status', value: { enum: ['active', 'superseded'] }, description: 'Item lifecycle state' },
+  { key: 'domain', value: 'string', description: 'Subject area the item belongs to' },
+  { key: 'command', value: 'string', description: 'The literal command line (command items)' },
+  { key: 'path', value: 'string', description: 'Filesystem path (entity items that are files/dirs)' },
+  { key: 'url', value: 'url', description: 'External reference' },
+  { key: 'decided_on', value: 'date', description: 'When a decision was made' },
+];
+
+export const SEED_RELATIONS = [
+  { name: 'relates-to', inverse: 'relates-to', description: 'Generic association (symmetric)' },
+  { name: 'part-of', inverse: 'has-part', description: 'Composition' },
+  { name: 'depends-on', inverse: 'blocks', description: 'A needs B' },
+  { name: 'supersedes', inverse: 'superseded-by', description: 'A replaces B' },
+  { name: 'derived-from', inverse: 'source-of', description: 'A was distilled/derived from B' },
+];
+
+const REG_FILES = { types: 'types.json', attributes: 'attributes.json', relations: 'relations.json' };
+
+export function registryDir(agentDir) {
+  return join(agentDir, 'knowledge', 'registry');
+}
+
+/** Load the registry from agent/knowledge/registry/. Missing files → empty sets. */
+export function loadRegistry(agentDir) {
+  const dir = registryDir(agentDir);
+  const read = (f) => {
+    const p = join(dir, f);
+    if (!existsSync(p)) return [];
+    try {
+      const data = JSON.parse(readFileSync(p, 'utf8'));
+      return Array.isArray(data) ? data : [];
+    } catch {
+      return null; // unparseable — caller surfaces via audit
+    }
+  };
+  const types = read(REG_FILES.types);
+  const attributes = read(REG_FILES.attributes);
+  const relations = read(REG_FILES.relations);
+  const broken = [types, attributes, relations].some((x) => x === null);
+  return {
+    ok: !broken,
+    types: new Map((types || []).map((t) => [t.name, t])),
+    attributes: new Map((attributes || []).map((a) => [a.key, a])),
+    relations: new Map((relations || []).map((r) => [r.name, r])),
+  };
+}
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/** Validate one attribute value against its registry definition. */
+export function validateAttribute(def, value) {
+  if (!def) return { ok: false, error: 'unregistered attribute key' };
+  const v = def.value;
+  const s = String(value);
+  if (v === 'string') return { ok: true };
+  if (v === 'number') return Number.isFinite(Number(s)) ? { ok: true } : { ok: false, error: 'not a number' };
+  if (v === 'date') return ISO_DATE.test(s) ? { ok: true } : { ok: false, error: 'not an ISO date' };
+  if (v === 'url') return /^https?:\/\/\S+$/.test(s) ? { ok: true } : { ok: false, error: 'not a URL' };
+  if (v && typeof v === 'object' && Array.isArray(v.enum)) {
+    return v.enum.includes(s) ? { ok: true } : { ok: false, error: `not in enum [${v.enum.join(', ')}]` };
+  }
+  return { ok: true }; // unknown validator kind: permissive (fail-open governance)
+}
+
+/**
+ * Validate an item against the registry.
+ * @returns {{ok: boolean, errors: string[], unknownKeys: {attributes: string[], relations: string[]}}}
+ *   unknownKeys are surfaced separately — they're proposal fodder, not hard errors
+ *   for *candidates*; items.mjs treats them as errors for canonical items.
+ */
+export function validateItem(registry, item) {
+  const errors = [];
+  const unknownAttrs = [];
+  const unknownRels = [];
+  if (!registry.types.has(item.type)) errors.push(`unregistered type: ${item.type}`);
+  for (const [key, value] of Object.entries(item.attributes ?? {})) {
+    const def = registry.attributes.get(key);
+    if (!def) {
+      unknownAttrs.push(key);
+      continue;
+    }
+    const r = validateAttribute(def, value);
+    if (!r.ok) errors.push(`attribute ${key}: ${r.error}`);
+  }
+  for (const rel of item.relations ?? []) {
+    if (!rel.type || !rel.target) {
+      errors.push(`relation missing type/target: ${JSON.stringify(rel)}`);
+      continue;
+    }
+    if (!registry.relations.has(rel.type)) unknownRels.push(rel.type);
+  }
+  return { ok: errors.length === 0, errors, unknownKeys: { attributes: unknownAttrs, relations: unknownRels } };
+}