@zuzuucodes/cli 1.5.0 → 1.6.0

package/zuzuu/commands/migrations/home.mjs

@@ -0,0 +1,96 @@
+// zuzuu/commands/migrations/home.mjs — the home migrator (W1, 2026-06-12):
+// visible agent/ → hidden .zuzuu/ (byte-identical inner layout), plus the
+// follow-ups: traceRef rewrite, gitignore + deny-rule swap, host-block re-inject.
+// Pure core: migrateHome(root) → { migrated }. Idempotent + fail-soft.
+
+import { existsSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot } from '../../core/store.mjs';
+import { ensureGitignore } from '../../home/scaffold.mjs';
+import { injectBlock, BLOCK_VERSION } from '../../home/inject.mjs';
+
+// The denies the old visible-agent/ home installed; scrubbed here (NOT kept in
+// install.mjs — clean break) and replaced by the current narrow .zuzuu/ pair.
+const LEGACY_DENY_RULES = ['Read(./agent/.traces/**)', 'Read(./agent/.live/**)'];
+const NEW_DENY_RULES = ['Read(./.zuzuu/.traces/**)', 'Read(./.zuzuu/.live/**)'];
+
+/**
+ * One-shot HOME migration: visible `agent/` → hidden `.zuzuu/` (byte-identical
+ * inner layout). Gated on `agent/agent.json` — `agent/` is a common dir name,
+ * so an unrelated agent/ dir in a brownfield repo must NEVER be touched (the
+ * one place this differs from the old `.mns→agent` precedent). Idempotent +
+ * fail-soft; NEVER clobbers an existing .zuzuu/. Pure FS move (renameSync).
+ * @returns {{migrated: boolean}}
+ */
+export function migrateHome(root = repoRoot()) {
+  const legacy = join(root, 'agent');
+  const home = join(root, '.zuzuu');
+  if (existsSync(home) || !existsSync(join(legacy, 'agent.json'))) return { migrated: false };
+
+  renameSync(legacy, home); // move the whole home (atomic on same filesystem)
+
+  rewriteTraceRefs(home);
+  rewriteGitignore(root);
+  scrubLegacyDenies(root);
+  // derived index: drop, it rebuilds on the next recall/reindex
+  try { rmSync(join(home, 'knowledge', '.index.db'), { force: true }); } catch { /* fail-soft */ }
+  return { migrated: true };
+}
+
+/** sessions.json stores repo-relative traceRefs (`agent/.traces/…`) — re-point them. */
+function rewriteTraceRefs(home) {
+  const index = join(home, 'sessions.json');
+  if (!existsSync(index)) return;
+  try {
+    const idx = JSON.parse(readFileSync(index, 'utf8'));
+    for (const s of idx.sessions || []) {
+      if (typeof s.traceRef === 'string' && s.traceRef.startsWith('agent/')) {
+        s.traceRef = '.zuzuu/' + s.traceRef.slice('agent/'.length);
+      }
+    }
+    writeFileSync(index, JSON.stringify(idx, null, 2) + '\n');
+  } catch { /* fail-soft: a bad index never blocks the move */ }
+}
+
+/** Drop legacy `agent/` ignore lines, then append the canonical .zuzuu/ ones. */
+function rewriteGitignore(root) {
+  const path = join(root, '.gitignore');
+  if (existsSync(path)) {
+    const kept = readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((l) => !l.trim().startsWith('agent/'))
+      .join('\n');
+    writeFileSync(path, kept.endsWith('\n') || kept === '' ? kept : kept + '\n');
+  }
+  ensureGitignore(root); // appends .zuzuu/.traces/, .zuzuu/.live/, .zuzuu/knowledge/.index.db
+}
+
+/** Swap the old agent/ deny rules for the .zuzuu/ pair in any .claude settings file. */
+function scrubLegacyDenies(root) {
+  for (const f of ['settings.json', 'settings.local.json']) {
+    const path = join(root, '.claude', f);
+    if (!existsSync(path)) continue;
+    try {
+      const s = JSON.parse(readFileSync(path, 'utf8'));
+      const deny = s?.permissions?.deny;
+      if (!Array.isArray(deny)) continue;
+      const hadOurs = deny.some((r) => LEGACY_DENY_RULES.includes(r));
+      if (!hadOurs) continue;
+      s.permissions.deny = deny.filter((r) => !LEGACY_DENY_RULES.includes(r));
+      for (const rule of NEW_DENY_RULES) if (!s.permissions.deny.includes(rule)) s.permissions.deny.push(rule);
+      writeFileSync(path, JSON.stringify(s, null, 2) + '\n');
+    } catch { /* fail-soft: never break settings we can't parse */ }
+  }
+}
+
+/** Re-inject the current faculties block into any existing host instruction files. */
+export function reinjectHostBlocks(root) {
+  for (const f of ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
+    const p = join(root, f);
+    if (existsSync(p)) {
+      const text = readFileSync(p, 'utf8');
+      if (!text.includes(`zuzuu:faculties:v${BLOCK_VERSION}`)) writeFileSync(p, injectBlock(text));
+    }
+  }
+}
+

package/zuzuu/commands/migrations/index.mjs

@@ -0,0 +1,48 @@
+// zuzuu/commands/migrations/index.mjs — `zuzuu migrate` dispatch.
+//
+//   (default)  proposal schema: legacy {candidate, er} → spine {payload, analysis, faculty}
+//   --home     faculty home: visible agent/ → hidden .zuzuu/
+//   --items    Faculty Standard: legacy faculty shapes → the envelope standard
+//
+// Pure cores live beside this file (proposals/home/items.mjs); this is the CLI
+// surface — resolves paths, runs a core, prints the summary.
+
+import { paths, repoRoot } from '../../core/store.mjs';
+import { BLOCK_VERSION } from '../../home/inject.mjs';
+import { migrateProposals } from './proposals.mjs';
+import { migrateHome, reinjectHostBlocks } from './home.mjs';
+import { migrateItems, needsItemsMigration } from './items.mjs';
+
+export { migrateProposals } from './proposals.mjs';
+export { migrateHome } from './home.mjs';
+export { migrateItems, needsItemsMigration } from './items.mjs';
+
+export function migrate(args = {}) {
+  if (args.items) {
+    const agentDir = paths().dir;
+    const r = migrateItems(agentDir);
+    const total = r.knowledge + r.memory + r.guardrails + r.actions + r.instructions;
+    console.log(`migrate --items: ${total} item(s) → the Faculty Standard envelope — knowledge ${r.knowledge} · memory ${r.memory} · guardrails ${r.guardrails} · actions ${r.actions} · instructions ${r.instructions} (${r.skipped} already standard)`);
+    if (r.manifests) console.log(`  seeded ${r.manifests} faculty manifest(s) (faculty.json — the Faculty Module contract)`);
+    for (const e of r.errors) console.log(`  ✗ ${e.file}: ${e.error}`);
+    if (!total && !r.manifests && !r.errors.length) console.log('  nothing to migrate (the home already speaks the envelope)');
+    return;
+  }
+  if (args.home) {
+    const root = repoRoot(process.cwd());
+    const { migrated } = migrateHome(root);
+    if (!migrated) { console.log('migrate --home: nothing to do (already .zuzuu/, or no zuzuu home at agent/)'); return; }
+    try { reinjectHostBlocks(root); } catch { /* fail-open */ }
+    console.log(`migrate --home: agent/ → .zuzuu/ (hidden, like .git; block v${BLOCK_VERSION}, gitignore + deny rules rewritten)`);
+    console.log('  transparency lives in porcelain now: zuzuu status · explain · digest');
+    return;
+  }
+  const agentDir = paths().dir;
+  const { scanned, migrated, skipped } = migrateProposals(agentDir);
+  console.log(`migrate: scanned ${scanned} proposal(s) — migrated ${migrated}, skipped ${skipped}`);
+  if (migrated > 0) {
+    console.log('  legacy candidate/er keys rewritten to payload/analysis.er + faculty:knowledge');
+  } else {
+    console.log('  nothing to migrate (all records already in new shape)');
+  }
+}

package/zuzuu/commands/{migrate.mjs → migrations/items.mjs}

@@ -1,217 +1,15 @@
-// zuzuu/commands/migrate.mjs
-// `zuzuu migrate` — one-time migrators.
-//
-//   (default)  proposal schema: legacy {candidate, er} → spine {payload, analysis, faculty} (WS2-T5)
-//   --home     faculty home: visible agent/ → hidden .zuzuu/ (W1, 2026-06-12)
-//   --items    Faculty Standard (W24): legacy per-faculty shapes → one envelope —
-//              knowledge/memory frontmatter keys standardised, rules.json
-//              exploded into guardrails/items/, action.json+SKILL.md → ACTION.md,
-//              instructions/project.md → items/steering.md. Idempotent,
-//              fail-soft per item. Auto-runs from `zuzuu init` when old shapes
-//              are detected (like migrateHome).
-//
-// Pure cores:  migrateProposals(agentDir) → { scanned, migrated, skipped }
-//              migrateHome(root) → { migrated }
-//              migrateItems(agentDir) → { knowledge, memory, guardrails, actions, instructions, skipped, errors }
-// CLI surface: migrate(args) — resolves paths, runs the core, prints summary.
+// zuzuu/commands/migrations/items.mjs — the Faculty Standard migrator (W24):
+// legacy per-faculty shapes → one envelope. knowledge/memory frontmatter keys
+// standardised, rules.json exploded into guardrails/items/, action.json+SKILL.md
+// → ACTION.md, instructions/project.md → items/steering.md. Idempotent,
+// fail-soft per item. Auto-runs from `zuzuu init` when old shapes are detected.
 
-import { existsSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, statSync, mkdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync, statSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { paths, repoRoot } from '../store.mjs';
-import { proposalsDir, archiveDir } from '../faculty/contract.mjs';
-import { ensureGitignore } from '../scaffold.mjs';
-import { injectBlock, BLOCK_VERSION } from '../inject.mjs';
-import { serializeEnvelope, deriveTitle } from '../faculty/envelope.mjs';
-import { serializeItem } from '../knowledge/items.mjs';
-
-// ---------------------------------------------------------------------------
-// pure core — testable without process.*
-// ---------------------------------------------------------------------------
-
-/**
- * Determine whether a parsed JSON record is already in the new shape.
- * A record is "new" when it has `payload` AND `faculty` set.
- * If it only has `candidate` and/or lacks `faculty` it is legacy.
- */
-function isLegacy(rec) {
-  if (!rec || typeof rec !== 'object') return false;
-  // already migrated: has payload and faculty
-  if (rec.payload !== undefined && rec.faculty !== undefined) return false;
-  // legacy if it has candidate or er keys, or is simply missing faculty/payload
-  return rec.candidate !== undefined || rec.er !== undefined || rec.faculty === undefined;
-}
-
-/**
- * Convert a legacy record to the new unified shape.
- * Returns the migrated record (caller writes it back).
- */
-function migrateRecord(rec) {
-  const out = { ...rec };
-
-  // payload = candidate (drop candidate)
-  if (out.candidate !== undefined) {
-    if (out.payload === undefined) out.payload = out.candidate;
-    delete out.candidate;
-  }
-
-  // analysis = { er } (drop er)
-  if (out.er !== undefined) {
-    if (out.analysis === undefined) out.analysis = { er: out.er };
-    delete out.er;
-  }
-
-  // faculty defaults to 'knowledge' (only knowledge proposals exist pre-spine)
-  if (!out.faculty) out.faculty = 'knowledge';
-
-  return out;
-}
-
-/**
- * Scan one directory of *.json files and migrate legacy records in-place.
- * Fail-soft: bad JSON files are counted as skipped and never throw.
- * Returns { migrated, scanned, skipped } for this directory.
- */
-function migrateDir(dir) {
-  if (!existsSync(dir)) return { migrated: 0, scanned: 0, skipped: 0 };
-
-  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
-  let migrated = 0;
-  let skipped = 0;
-
-  for (const file of files) {
-    const fpath = join(dir, file);
-    let rec;
-    try {
-      rec = JSON.parse(readFileSync(fpath, 'utf8'));
-    } catch {
-      skipped++;
-      continue;
-    }
-
-    if (!isLegacy(rec)) {
-      skipped++;
-      continue;
-    }
-
-    try {
-      const migrated_rec = migrateRecord(rec);
-      writeFileSync(fpath, JSON.stringify(migrated_rec, null, 2) + '\n');
-      migrated++;
-    } catch {
-      skipped++;
-    }
-  }
-
-  return { migrated, scanned: files.length, skipped };
-}
-
-/**
- * Scan both pending and archived Knowledge proposals.
- * Returns { scanned, migrated, skipped }.
- */
-export function migrateProposals(agentDir) {
-  const pending = migrateDir(proposalsDir(agentDir, 'knowledge'));
-  const archived = migrateDir(archiveDir(agentDir, 'knowledge'));
-
-  return {
-    scanned: pending.scanned + archived.scanned,
-    migrated: pending.migrated + archived.migrated,
-    skipped: pending.skipped + archived.skipped,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// home migration — agent/ → .zuzuu/ (W1, 2026-06-12)
-// ---------------------------------------------------------------------------
-
-// The denies the old visible-agent/ home installed; scrubbed here (NOT kept in
-// install.mjs — clean break) and replaced by the current narrow .zuzuu/ pair.
-const LEGACY_DENY_RULES = ['Read(./agent/.traces/**)', 'Read(./agent/.live/**)'];
-const NEW_DENY_RULES = ['Read(./.zuzuu/.traces/**)', 'Read(./.zuzuu/.live/**)'];
-
-/**
- * One-shot HOME migration: visible `agent/` → hidden `.zuzuu/` (byte-identical
- * inner layout). Gated on `agent/agent.json` — `agent/` is a common dir name,
- * so an unrelated agent/ dir in a brownfield repo must NEVER be touched (the
- * one place this differs from the old `.mns→agent` precedent). Idempotent +
- * fail-soft; NEVER clobbers an existing .zuzuu/. Pure FS move (renameSync).
- * @returns {{migrated: boolean}}
- */
-export function migrateHome(root = repoRoot()) {
-  const legacy = join(root, 'agent');
-  const home = join(root, '.zuzuu');
-  if (existsSync(home) || !existsSync(join(legacy, 'agent.json'))) return { migrated: false };
-
-  renameSync(legacy, home); // move the whole home (atomic on same filesystem)
-
-  rewriteTraceRefs(home);
-  rewriteGitignore(root);
-  scrubLegacyDenies(root);
-  // derived index: drop, it rebuilds on the next recall/reindex
-  try { rmSync(join(home, 'knowledge', '.index.db'), { force: true }); } catch { /* fail-soft */ }
-  return { migrated: true };
-}
-
-/** sessions.json stores repo-relative traceRefs (`agent/.traces/…`) — re-point them. */
-function rewriteTraceRefs(home) {
-  const index = join(home, 'sessions.json');
-  if (!existsSync(index)) return;
-  try {
-    const idx = JSON.parse(readFileSync(index, 'utf8'));
-    for (const s of idx.sessions || []) {
-      if (typeof s.traceRef === 'string' && s.traceRef.startsWith('agent/')) {
-        s.traceRef = '.zuzuu/' + s.traceRef.slice('agent/'.length);
-      }
-    }
-    writeFileSync(index, JSON.stringify(idx, null, 2) + '\n');
-  } catch { /* fail-soft: a bad index never blocks the move */ }
-}
-
-/** Drop legacy `agent/` ignore lines, then append the canonical .zuzuu/ ones. */
-function rewriteGitignore(root) {
-  const path = join(root, '.gitignore');
-  if (existsSync(path)) {
-    const kept = readFileSync(path, 'utf8')
-      .split('\n')
-      .filter((l) => !l.trim().startsWith('agent/'))
-      .join('\n');
-    writeFileSync(path, kept.endsWith('\n') || kept === '' ? kept : kept + '\n');
-  }
-  ensureGitignore(root); // appends .zuzuu/.traces/, .zuzuu/.live/, .zuzuu/knowledge/.index.db
-}
-
-/** Swap the old agent/ deny rules for the .zuzuu/ pair in any .claude settings file. */
-function scrubLegacyDenies(root) {
-  for (const f of ['settings.json', 'settings.local.json']) {
-    const path = join(root, '.claude', f);
-    if (!existsSync(path)) continue;
-    try {
-      const s = JSON.parse(readFileSync(path, 'utf8'));
-      const deny = s?.permissions?.deny;
-      if (!Array.isArray(deny)) continue;
-      const hadOurs = deny.some((r) => LEGACY_DENY_RULES.includes(r));
-      if (!hadOurs) continue;
-      s.permissions.deny = deny.filter((r) => !LEGACY_DENY_RULES.includes(r));
-      for (const rule of NEW_DENY_RULES) if (!s.permissions.deny.includes(rule)) s.permissions.deny.push(rule);
-      writeFileSync(path, JSON.stringify(s, null, 2) + '\n');
-    } catch { /* fail-soft: never break settings we can't parse */ }
-  }
-}
-
-/** Re-inject the current faculties block into any existing host instruction files. */
-function reinjectHostBlocks(root) {
-  for (const f of ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
-    const p = join(root, f);
-    if (existsSync(p)) {
-      const text = readFileSync(p, 'utf8');
-      if (!text.includes(`zuzuu:faculties:v${BLOCK_VERSION}`)) writeFileSync(p, injectBlock(text));
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// items migration — the Faculty Standard (W24)
-// ---------------------------------------------------------------------------
+import { serializeEnvelope, deriveTitle } from '../../faculty/envelope.mjs';
+import { serializeItem } from '../../knowledge/items.mjs';
+import { FACULTIES } from '../../faculty/contract.mjs';
+import { BUILTIN_MODULES } from '../../faculty/registry.mjs';
 
 /** Does this file's frontmatter already carry the envelope (a `faculty:` key)? */
 function isEnvelopeText(text) {
@@ -493,10 +291,31 @@ function migrateInstructions(agentDir, out) {
   }
 }
 
+/** Seed missing <faculty>/faculty.json manifests into an existing home (the
+ *  Faculty Module contract, 2026-06-13). Only faculties whose dir exists get
+ *  one — a migrator repairs, it never scaffolds. Idempotent, fail-soft. */
+function seedFacultyManifests(agentDir, out) {
+  for (const f of FACULTIES) {
+    try {
+      const dir = join(agentDir, f);
+      if (!existsSync(dir)) continue;
+      const p = join(dir, 'faculty.json');
+      if (existsSync(p)) continue;
+      writeFileSync(p, JSON.stringify(BUILTIN_MODULES[f].manifest, null, 2) + '\n');
+      out.manifests++;
+    } catch (e) {
+      out.errors.push({ file: `${f}/faculty.json`, error: e.message });
+    }
+  }
+}
+
 /**
  * Are pre-standard shapes present? Cheap checks gate the init auto-run.
  */
 export function needsItemsMigration(agentDir) {
+  for (const f of FACULTIES) {
+    if (existsSync(join(agentDir, f)) && !existsSync(join(agentDir, f, 'faculty.json'))) return true;
+  }
   if (existsSync(join(agentDir, 'guardrails', 'rules.json'))) return true;
   if (existsSync(join(agentDir, 'instructions', 'project.md'))) return true;
   for (const base of [join(agentDir, 'actions'), join(agentDir, 'actions', 'inbox')]) {
@@ -526,47 +345,16 @@ export function needsItemsMigration(agentDir) {
  * files are skipped) and fail-soft per item (an unconvertible item is reported,
  * never fatal; its legacy source is left in place).
  * @returns {{knowledge:number, memory:number, guardrails:number, actions:number,
- *            instructions:number, skipped:number, errors:Array<{file,error}>}}
+ *            instructions:number, manifests:number, skipped:number, errors:Array<{file,error}>}}
  */
 export function migrateItems(agentDir) {
-  const out = { knowledge: 0, memory: 0, guardrails: 0, actions: 0, instructions: 0, skipped: 0, errors: [] };
+  const out = { knowledge: 0, memory: 0, guardrails: 0, actions: 0, instructions: 0, manifests: 0, skipped: 0, errors: [] };
   migrateKnowledgeItems(agentDir, out);
   migrateMemoryEntries(agentDir, out);
   migrateGuardrails(agentDir, out);
   migrateActions(agentDir, out);
   migrateInstructions(agentDir, out);
+  seedFacultyManifests(agentDir, out);
   return out;
 }
 
-// ---------------------------------------------------------------------------
-// CLI surface
-// ---------------------------------------------------------------------------
-
-export function migrate(args = {}) {
-  if (args.items) {
-    const agentDir = paths().dir;
-    const r = migrateItems(agentDir);
-    const total = r.knowledge + r.memory + r.guardrails + r.actions + r.instructions;
-    console.log(`migrate --items: ${total} item(s) → the Faculty Standard envelope — knowledge ${r.knowledge} · memory ${r.memory} · guardrails ${r.guardrails} · actions ${r.actions} · instructions ${r.instructions} (${r.skipped} already standard)`);
-    for (const e of r.errors) console.log(`  ✗ ${e.file}: ${e.error}`);
-    if (!total && !r.errors.length) console.log('  nothing to migrate (the home already speaks the envelope)');
-    return;
-  }
-  if (args.home) {
-    const root = repoRoot(process.cwd());
-    const { migrated } = migrateHome(root);
-    if (!migrated) { console.log('migrate --home: nothing to do (already .zuzuu/, or no zuzuu home at agent/)'); return; }
-    try { reinjectHostBlocks(root); } catch { /* fail-open */ }
-    console.log(`migrate --home: agent/ → .zuzuu/ (hidden, like .git; block v${BLOCK_VERSION}, gitignore + deny rules rewritten)`);
-    console.log('  transparency lives in porcelain now: zuzuu status · explain · digest');
-    return;
-  }
-  const agentDir = paths().dir;
-  const { scanned, migrated, skipped } = migrateProposals(agentDir);
-  console.log(`migrate: scanned ${scanned} proposal(s) — migrated ${migrated}, skipped ${skipped}`);
-  if (migrated > 0) {
-    console.log('  legacy candidate/er keys rewritten to payload/analysis.er + faculty:knowledge');
-  } else {
-    console.log('  nothing to migrate (all records already in new shape)');
-  }
-}

package/zuzuu/commands/migrations/proposals.mjs

@@ -0,0 +1,100 @@
+// zuzuu/commands/migrations/proposals.mjs — legacy proposal-schema migrator.
+// {candidate, er} → spine {payload, analysis, faculty} (WS2-T5). Pure core:
+// migrateProposals(agentDir) → { scanned, migrated, skipped }. Fail-soft per file.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { proposalsDir, archiveDir } from '../../faculty/contract.mjs';
+
+/**
+ * Determine whether a parsed JSON record is already in the new shape.
+ * A record is "new" when it has `payload` AND `faculty` set.
+ * If it only has `candidate` and/or lacks `faculty` it is legacy.
+ */
+function isLegacy(rec) {
+  if (!rec || typeof rec !== 'object') return false;
+  // already migrated: has payload and faculty
+  if (rec.payload !== undefined && rec.faculty !== undefined) return false;
+  // legacy if it has candidate or er keys, or is simply missing faculty/payload
+  return rec.candidate !== undefined || rec.er !== undefined || rec.faculty === undefined;
+}
+
+/**
+ * Convert a legacy record to the new unified shape.
+ * Returns the migrated record (caller writes it back).
+ */
+function migrateRecord(rec) {
+  const out = { ...rec };
+
+  // payload = candidate (drop candidate)
+  if (out.candidate !== undefined) {
+    if (out.payload === undefined) out.payload = out.candidate;
+    delete out.candidate;
+  }
+
+  // analysis = { er } (drop er)
+  if (out.er !== undefined) {
+    if (out.analysis === undefined) out.analysis = { er: out.er };
+    delete out.er;
+  }
+
+  // faculty defaults to 'knowledge' (only knowledge proposals exist pre-spine)
+  if (!out.faculty) out.faculty = 'knowledge';
+
+  return out;
+}
+
+/**
+ * Scan one directory of *.json files and migrate legacy records in-place.
+ * Fail-soft: bad JSON files are counted as skipped and never throw.
+ * Returns { migrated, scanned, skipped } for this directory.
+ */
+function migrateDir(dir) {
+  if (!existsSync(dir)) return { migrated: 0, scanned: 0, skipped: 0 };
+
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  let migrated = 0;
+  let skipped = 0;
+
+  for (const file of files) {
+    const fpath = join(dir, file);
+    let rec;
+    try {
+      rec = JSON.parse(readFileSync(fpath, 'utf8'));
+    } catch {
+      skipped++;
+      continue;
+    }
+
+    if (!isLegacy(rec)) {
+      skipped++;
+      continue;
+    }
+
+    try {
+      const migrated_rec = migrateRecord(rec);
+      writeFileSync(fpath, JSON.stringify(migrated_rec, null, 2) + '\n');
+      migrated++;
+    } catch {
+      skipped++;
+    }
+  }
+
+  return { migrated, scanned: files.length, skipped };
+}
+
+/**
+ * Scan both pending and archived Knowledge proposals.
+ * Returns { scanned, migrated, skipped }.
+ */
+export function migrateProposals(agentDir) {
+  const pending = migrateDir(proposalsDir(agentDir, 'knowledge'));
+  const archived = migrateDir(archiveDir(agentDir, 'knowledge'));
+
+  return {
+    scanned: pending.scanned + archived.scanned,
+    migrated: pending.migrated + archived.migrated,
+    skipped: pending.skipped + archived.skipped,
+  };
+}
+