ruvnet-brain 4.0.1 → 4.0.4

package/scripts/lesson-promote.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * lesson-promote.mjs — mine project-scoped lessons, find the UNIVERSAL ones, promote them.
+ *
+ * THE PROBLEM, MEASURED (2026-07-22, on the owner's own machine — this is not hypothetical):
+ *
+ *     736 lessons across 48 project memory stores.
+ *     284 of them are `type: feedback` — "how I want you to WORK", which is almost never
+ *     project-specific — and they are scattered across 33 separate stores.
+ *
+ *     "Test before claiming done"      taught 87 times across 19 projects
+ *     "Versioning / release discipline" taught 52 times across 14 projects
+ *     "Never fabricate / be honest"     taught 37 times across 14 projects
+ *
+ * The owner did not repeat himself because he forgot. He repeated himself because a lesson learned
+ * in project A physically cannot reach project B: Claude Code scopes memory to
+ * ~/.claude/projects/<project>/memory/, and nothing promotes upward. His words: "I shouldn't ever
+ * have to tell you twice." He has had to tell us 87 times.
+ *
+ * THE PROMOTION RULE IS NOT OURS. It is rUv's, from ruflo ADR-G008 ("Win Twice to Promote",
+ * Accepted/implemented): a rule may not enter the constitution on one good result, because one
+ * result is noise. We apply the same test with the strongest evidence available here — INDEPENDENT
+ * REDISCOVERY. A lesson the user taught in two or more separate projects has already won twice, in
+ * the only arena that matters: he needed it more than once, in places that could not see each other.
+ *
+ * That is deliberately NOT a similarity score or an LLM judgment call. It is a count of how many
+ * times a human independently arrived at the same instruction. Cheap, explainable, and impossible
+ * to fudge — which matters, because a promotion engine that guesses will pollute the global rules
+ * that govern every project, and a bad global rule is far more expensive than a missing one.
+ *
+ * READ-ONLY BY DEFAULT. Promotion writes to the user's global instructions, which is the highest
+ * blast-radius write this project performs. It requires --apply, backs up first, and is reversible.
+ *
+ * Usage:
+ *   node scripts/lesson-promote.mjs                 # report only — what WOULD be promoted, and why
+ *   node scripts/lesson-promote.mjs --json          # machine-readable, for the console
+ *   node scripts/lesson-promote.mjs --apply         # write the promotion block (backs up first)
+ *   node scripts/lesson-promote.mjs --min-projects 3
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const HOME = os.homedir();
+const PROJECTS = path.join(HOME, '.claude', 'projects');
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const arg = (f, d) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+
+// A lesson must have been independently learned in at least this many DISTINCT projects to be
+// considered universal. 2 is ADR-G008's "win twice"; the flag exists so a cautious user can demand
+// more evidence, never less — the floor is enforced below.
+const MIN_PROJECTS = Math.max(2, parseInt(arg('--min-projects', '2'), 10) || 2);
+
+/**
+ * Themes are the unit of promotion, not individual files.
+ *
+ * Promoting 87 near-identical "test first" lessons verbatim would be worse than promoting none —
+ * it would bury the global instructions under duplicates and make them unreadable, which is how a
+ * constitution stops being read. We cluster to the PROCESS, then promote one canonical statement of
+ * it, citing the projects that independently discovered it as the evidence.
+ *
+ * Deliberately keyword-based rather than embedding-based. An embedding cluster is a black box the
+ * user cannot audit, and this writes to the file that governs every project he owns. He must be able
+ * to read the rule that decided, disagree with it, and edit it. Legibility beats cleverness here.
+ */
+const THEMES = [
+  { key: 'release-discipline', label: 'Versioning and release discipline',
+    match: /version|semver|bump|release|ship|deploy|publish|rollback/i },
+  { key: 'proof-before-done', label: 'Prove it works before calling it done',
+    match: /test|verify|prove|validat|\bqa\b|gate|green|passes/i },
+  { key: 'honesty', label: 'Never fabricate, never assume, never inflate',
+    match: /honest|lie|fabricat|assum|guess|placeholder|inflat|real data|made up/i },
+  { key: 'docs-upkeep', label: 'Keep docs and README current with the code',
+    match: /readme|document|changelog|\bdocs?\b|narrative/i },
+  { key: 'people', label: 'How to communicate with people',
+    match: /thank|contributor|personal|tone|nudge|deferential|communicat/i },
+  { key: 'tooling-discipline', label: 'Use the real tool; never hand-roll a substitute',
+    match: /hand-roll|impersonat|substitut|reinvent|use the tool|existing tool|ruvnet wins/i },
+  { key: 'cost-routing', label: 'Route work to the cheapest capable model',
+    match: /cheap|cost|route|routing|model selection|budget|spend/i },
+];
+
+/** Every lesson file on this machine, with its project, type, and text. */
+export function collectLessons(root = PROJECTS) {
+  const out = [];
+  let dirs = [];
+  try { dirs = fs.readdirSync(root); } catch { return out; }
+  for (const p of dirs) {
+    const md = path.join(root, p, 'memory');
+    if (!fs.existsSync(md)) continue;
+    let files = [];
+    try { files = fs.readdirSync(md); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.md') || f === 'MEMORY.md') continue;
+      let s = '';
+      try { s = fs.readFileSync(path.join(md, f), 'utf8'); } catch { continue; }
+      const type = (s.match(/^\s*type:\s*(\w+)/m) || [])[1] || 'unknown';
+      const desc = (s.match(/^description:\s*"?(.*?)"?\s*$/m) || [])[1] || '';
+      out.push({
+        project: p.replace(/^-Users-[^-]+-/, ''),
+        file: f.replace(/\.md$/, ''),
+        type, desc,
+        // name + description only — never the body. The body can hold project specifics (paths,
+        // client names, URLs); the identity of a PROCESS lives in its title. Classifying on the body
+        // would drag project facts into a global rule, which is the one thing promotion must not do.
+        text: `${f} ${desc}`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Cluster lessons into themes and decide which have won often enough to be universal.
+ *
+ * Only `feedback` lessons are eligible. `project` lessons are, by their own declared type, about one
+ * codebase; promoting them would be a category error and would leak one client's details into every
+ * other project's context.
+ */
+/**
+ * Themes the user has explicitly rejected. Read from the lesson store's demoted rows.
+ *
+ * WITHOUT THIS, DEMOTION WAS THEATRE. `lesson-ratify.mjs --demote` set a flag the miner never
+ * looked at, so the next mining run would re-propose the exact rule the user had just deleted.
+ * ADR-030 §5 states the requirement plainly — "a one-click demote that the next nightly silently
+ * undoes is worse than no demote at all, because the user stops trusting the control and, correctly,
+ * stops using it" — and the code did not implement it. Verified 2026-07-22: zero references to
+ * `demoted` in this file.
+ *
+ * Read defensively: the store may be absent, locked, or from a newer schema. A miner that throws
+ * because it could not read an optional file is worse than one that proposes a rejected theme.
+ */
+function demotedThemeKeys() {
+  try {
+    const file = process.env.RUVNET_LESSON_STORE
+      || path.join(os.homedir(), '.config', 'ruvnet-brain', 'lessons.json');
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return new Set(
+      (raw.lessons || [])
+        .filter((l) => l && l.demoted === true && typeof l.themeKey === 'string')
+        .map((l) => l.themeKey),
+    );
+  } catch { return new Set(); }
+}
+
+export function analyze(lessons, { minProjects = MIN_PROJECTS, rejected = null } = {}) {
+  // Injectable for tests; defaults to the real store so the CLI honours real demotions.
+  const demoted = rejected instanceof Set ? rejected : demotedThemeKeys();
+  const eligible = lessons.filter((l) => l.type === 'feedback');
+  const themes = [];
+  for (const t of THEMES) {
+    const hits = eligible.filter((l) => t.match.test(l.text));
+    if (!hits.length) continue;
+    const projects = [...new Set(hits.map((h) => h.project))].sort();
+    // A theme the user has demoted is NEVER re-proposed. Sticky across every future run.
+    if (demoted.has(t.key)) continue;
+    themes.push({
+      key: t.key,
+      label: t.label,
+      lessons: hits.length,
+      projects,
+      projectCount: projects.length,
+      // The whole verdict, in one line anyone can check by hand.
+      universal: projects.length >= minProjects,
+      evidence: `taught ${hits.length} time${hits.length === 1 ? '' : 's'} across ${projects.length} independent project${projects.length === 1 ? '' : 's'}`,
+      examples: hits.slice(0, 4).map((h) => `${h.project}: ${h.file}`),
+    });
+  }
+  themes.sort((a, b) => b.projectCount - a.projectCount || b.lessons - a.lessons);
+
+  const promotable = themes.filter((t) => t.universal);
+  return {
+    scanned: { projects: new Set(lessons.map((l) => l.project)).size, lessons: lessons.length, feedback: eligible.length },
+    minProjects,
+    themes,
+    promotable,
+    // The headline the console should say out loud, computed rather than written.
+    headline: promotable.length
+      ? `${promotable.length} process${promotable.length === 1 ? '' : 'es'} you have taught in ${minProjects}+ separate projects are still trapped at project level`
+      : 'no cross-project process has met the promotion bar yet',
+  };
+}
+
+/** Render the promotion block. Idempotent, fenced, and safe to regenerate. */
+export function renderBlock(result, now) {
+  const lines = [];
+  lines.push(BEGIN);
+  lines.push('<!-- Generated by scripts/lesson-promote.mjs. Regeneration REPLACES this fenced block');
+  lines.push('     wholesale on the next --apply — do NOT hand-edit between the markers, those changes');
+  lines.push('     are overwritten. Everything OUTSIDE the markers is left untouched. -->');
+  lines.push('');
+  lines.push(`## Cross-project lessons (promoted ${now})`);
+  lines.push('');
+  lines.push('These processes were learned independently in multiple projects. Per ruflo ADR-G008');
+  lines.push('("win twice to promote"), independent rediscovery IS the evidence — each one below was');
+  lines.push('needed more than once, in places that could not see each other.');
+  lines.push('');
+  for (const t of result.promotable) {
+    lines.push(`- **${t.label}** — ${t.evidence}.`);
+    lines.push(`  <sub>projects: ${t.projects.slice(0, 6).join(', ')}${t.projects.length > 6 ? `, +${t.projects.length - 6} more` : ''}</sub>`);
+  }
+  lines.push('');
+  lines.push(END);
+  return lines.join('\n');
+}
+
+const BEGIN = '<!-- BEGIN ruvnet-brain: promoted-lessons -->';
+const END = '<!-- END ruvnet-brain: promoted-lessons -->';
+
+/** Write the block into the user's global CLAUDE.md, backing up first. Reversible by design. */
+export function applyPromotion(result, { file, now }) {
+  if (!result.promotable.length) return { ok: true, noop: true, log: 'nothing met the promotion bar — nothing written' };
+  let existing = '';
+  try { existing = fs.readFileSync(file, 'utf8'); } catch { return { ok: false, log: `cannot read ${file}` }; }
+
+  const backup = `${file}.bak-promote-${now.replace(/[:.]/g, '-')}`;
+  try { fs.copyFileSync(file, backup); } catch (e) { return { ok: false, log: `refusing to write — backup failed: ${e.message}` }; }
+
+  const block = renderBlock(result, now);
+  const next = existing.includes(BEGIN)
+    ? existing.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}`), block)   // replace ONLY our fence
+    : `${existing.trimEnd()}\n\n${block}\n`;                            // first run: append
+
+  try { fs.writeFileSync(file, next); } catch (e) { return { ok: false, log: `write failed: ${e.message}; backup at ${backup}` }; }
+  return { ok: true, backup, promoted: result.promotable.length, log: `promoted ${result.promotable.length} process(es) into ${file.replace(HOME, '~')}` };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]).endsWith('lesson-promote.mjs');
+if (invokedDirectly) {
+  const result = analyze(collectLessons());
+  if (has('--json')) { console.log(JSON.stringify(result, null, 2)); process.exit(0); }
+
+  console.log(`\n  Scanned ${result.scanned.lessons} lessons across ${result.scanned.projects} projects `
+    + `(${result.scanned.feedback} are about how you want work done).\n`);
+  console.log(`  ${result.headline}.\n`);
+  const w = 42;
+  for (const t of result.themes) {
+    const mark = t.universal ? '  ⬆ PROMOTE ' : '  · project ';
+    console.log(`${mark}${t.label.padEnd(w)} ${String(t.lessons).padStart(3)} lessons · ${t.projectCount} projects`);
+  }
+  if (result.promotable.length) {
+    console.log(`\n  Evidence for each (independent rediscovery — ADR-G008 "win twice"):`);
+    for (const t of result.promotable) {
+      console.log(`\n    ${t.label}`);
+      console.log(`      ${t.evidence}`);
+      for (const ex of t.examples) console.log(`        · ${ex}`);
+    }
+  }
+
+  if (has('--apply')) {
+    const file = arg('--file', path.join(HOME, '.claude', 'CLAUDE.md'));
+    const res = applyPromotion(result, { file, now: new Date().toISOString().slice(0, 10) });
+    console.log(`\n  ${res.ok ? '✓' : '✗'} ${res.log}`);
+    if (res.backup) console.log(`     backup: ${res.backup.replace(HOME, '~')}`);
+    process.exit(res.ok ? 0 : 1);
+  } else {
+    console.log(`\n  This was a REPORT — nothing was written.`);
+    console.log(`  To promote these into your global instructions:  node scripts/lesson-promote.mjs --apply\n`);
+  }
+}

package/scripts/lesson-ratify.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * lesson-ratify.mjs — the human control over what the machine is allowed to enforce.
+ *
+ * The owner's requirement, verbatim (2026-07-22): "I should be able to see them all at a global
+ * level, and I should be able to go delete any ones on a global level that you thought were global
+ * but are really project-based."
+ *
+ * That is not a nice-to-have. ADR-029's promotion bar is evidence-based but not infallible — a
+ * keyword cluster can absolutely lift something local, and ADR-031's trust boundary exists because
+ * an adversarial review found that a hallucinated session summary could otherwise reach the
+ * objective function. A rule the user cannot see, audit, and delete is a rule imposed on them.
+ *
+ * Three verbs, and the asymmetry between them is the design:
+ *
+ *   --list            every lesson, its trigger, force, provenance, and evidence
+ *   --ratify <id>     a human agrees: raise it to the enforcement it was proposed at
+ *   --demote <id>     a human disagrees: it stops firing, PERMANENTLY
+ *
+ * Ratification is the ONLY path from candidate to enforcement, and `ratify()` refuses to raise a
+ * model-inferred lesson to `block` no matter what is asked of it. If the model could ratify its own
+ * inferences, the trust boundary would be a comment rather than a control.
+ *
+ * Demotion is STICKY — it survives every future mining run. A one-click reject that the next
+ * nightly quietly undoes is worse than no control at all, because the user stops trusting it and,
+ * correctly, stops using it.
+ */
+import os from 'node:os';
+import { loadLessons, saveLessons, ratify, demote, weightOf, pending, ENFORCEMENT, STATUS, ORIGIN, TRIGGERS } from './lesson-store.mjs';
+
+const argv = process.argv.slice(2);
+const arg = (f) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : null; };
+const has = (f) => argv.includes(f);
+
+const lessons = loadLessons();
+if (!lessons.length) {
+  console.log('\n  No lessons stored yet. Seed them with:  node scripts/lesson-seed.mjs --apply\n');
+  process.exit(0);
+}
+
+const FORCE = { block: '⛔ BLOCKS', checklist: '☑ checklist', inject: '· context', review: '👁 review only' };
+
+function list() {
+  const pend = pending(lessons);
+  console.log(`\n  ${lessons.length} lessons — ${pend.length} awaiting your decision.\n`);
+  console.log('  Nothing here refuses your work until YOU ratify it. The model does not get to');
+  console.log('  ratify its own rules — that is the whole trust boundary.\n');
+
+  for (const t of Object.values(TRIGGERS)) {
+    const group = lessons.filter((l) => l.trigger === t.key);
+    if (!group.length) continue;
+    console.log(`  ▸ WHEN ${t.label}`);
+    for (const l of group) {
+      const now = FORCE[l.enforcement] || l.enforcement;
+      const becomes = l.intendedEnforcement && l.intendedEnforcement !== l.enforcement
+        ? ` → ${FORCE[l.intendedEnforcement]} once ratified` : '';
+      const flag = l.demoted ? ' [DEMOTED — will never fire]' : '';
+      const who = l.origin === ORIGIN.USER_STATED ? 'you said it' : `${l.origin} — quarantined, can never block`;
+      console.log(`      ${l.id}${flag}`);
+      console.log(`        ${l.statement.slice(0, 110)}${l.statement.length > 110 ? '…' : ''}`);
+      console.log(`        ${now}${becomes}  ·  ${who}  ·  taught ${l.repeatCount}×  ·  weight ${weightOf(l)}`);
+    }
+    console.log('');
+  }
+  console.log('  node scripts/lesson-ratify.mjs --ratify <id>    # agree: let it enforce');
+  console.log('  node scripts/lesson-ratify.mjs --demote <id>    # disagree: silence it for good');
+  console.log('  node scripts/lesson-ratify.mjs --ratify-all-user-stated\n');
+}
+
+function show(next, id, verb) {
+  const l = next.find((x) => x.id === id);
+  if (!l) { console.log(`\n  No lesson with id "${id}". Run --list to see them.\n`); process.exit(1); }
+  saveLessons(next);
+  console.log(`\n  ✓ ${verb} ${l.id}`);
+  console.log(`      now: ${FORCE[l.enforcement] || l.enforcement}${l.demoted ? '  (demoted — will never fire again, including after future mining runs)' : ''}`);
+  console.log(`      stored at ${(process.env.RUVNET_LESSON_STORE || '~/.config/ruvnet-brain/lessons.json').replace(os.homedir(), '~')}\n`);
+}
+
+if (has('--ratify')) {
+  const id = arg('--ratify');
+  show(ratify(id, lessons), id, 'ratified');
+} else if (has('--demote')) {
+  const id = arg('--demote');
+  show(demote(id, lessons), id, 'demoted');
+} else if (has('--ratify-all-user-stated')) {
+  // Bulk convenience, deliberately scoped: it can only touch lessons the USER stated. Model-inferred
+  // lessons are never swept up by a bulk action — that would be exactly the hole the boundary closes.
+  let next = lessons;
+  const targets = lessons.filter((l) => l.origin === ORIGIN.USER_STATED && l.status === STATUS.CANDIDATE && !l.demoted);
+  for (const l of targets) next = ratify(l.id, next);
+  saveLessons(next);
+  const nowBlocking = next.filter((l) => l.enforcement === ENFORCEMENT.BLOCK).length;
+  console.log(`\n  ✓ ratified ${targets.length} lesson(s) you stated yourself.`);
+  console.log(`      ${nowBlocking} now BLOCK at their decision point. Model-inferred lessons were left`);
+  console.log(`      as candidates — a bulk action may never promote something the model inferred.\n`);
+} else {
+  list();
+}

package/scripts/lesson-seed.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// lesson-seed.mjs — the lessons of 2026-07-21/22, as executable objects.
+//
+// Every one has a dated, measured failure behind it from a single session, and each is classified by
+// what could ACTUALLY have caught it. Several are declared `review`/`checklist`, meaning no hook can
+// fully observe them — saying so is the honest move; claiming otherwise would be the
+// under-enumeration failure (L10) committed while recording L10.
+//
+// PROVENANCE IS REAL HERE, not decorative. Lessons where the owner's words can be quoted are
+// `user-stated`; lessons the model inferred about its OWN behaviour are `model-inferred` and are
+// quarantined — they can never block, no matter how convincing they sound. Nothing here is ratified,
+// because the model does not get to ratify its own rules. That is the point of the boundary.
+//
+//   node scripts/lesson-seed.mjs           # preview: what fires when, and at what force
+//   node scripts/lesson-seed.mjs --apply   # store as CANDIDATES awaiting ratification
+
+import os from 'node:os';
+import {
+  makeLesson, saveLessons, loadLessons, lessonsFor, unenforceable, pending, weightOf,
+  TRIGGERS as T, ENFORCEMENT as E, ORIGIN as O,
+} from './lesson-store.mjs';
+
+// Shipped at CHECKLIST; `intendedEnforcement` records what it becomes once a human ratifies it.
+const blocking = { enforcement: E.CHECKLIST, intendedEnforcement: E.BLOCK };
+
+export const SEED = [
+  makeLesson({
+    id: 'L01-verify-with-a-capable-channel',
+    ...blocking,
+    origin: O.USER_STATED,
+    severity: 'high',
+    statement: 'Before claiming something works, verify through a channel CAPABLE of observing the change — an independent tool, a re-measurement, a read-write connection. Never the exit code of the thing being tested.',
+    trigger: T.CLAIM_DONE.key,
+    check: 'a measurement was taken AFTER the change by something other than the process that made it',
+    evidence: [
+      { observed: 'distillation wrote 684 patterns; the success check used a read-only connection that structurally cannot see another process\'s WAL, and reported "produced no new patterns"' },
+      { observed: 'the queue flush deleted 60 of 68 distinct lessons and reported success' },
+      { observed: 'the capture flush fired on an exact modulo, so the queue reached 491 while both ends reported healthy' },
+      { observed: 'a repair promised an undo the console had no branch for, and answered "nothing to undo"' },
+      { observed: 'the installer compared versions with !== and told a user who was AHEAD they were out of date' },
+    ],
+    repeatCount: 25,
+    projects: ['Code-PowerPlatePulse', 'Code-ruvnet-brain', 'Code-AppealArmor'],
+  }),
+
+  makeLesson({
+    id: 'L02-check-before-you-assert',
+    ...blocking,
+    origin: O.USER_STATED,
+    severity: 'high',
+    statement: 'Before stating any fact about the world — a version, an API, what a tool does, how an architecture works — read a live source THIS TURN and name it. Recalling is not checking. The urge to skip the check IS the signal you are about to be wrong.',
+    trigger: T.ASSERT_FACT.key,
+    check: 'a source was read this turn (tool call, file read, or command output) for the specific claim, and it is cited',
+    evidence: [
+      { observed: 'owner, 2026-07-22: "I ask you questions about architecture, and you immediately do a casual look and come back and tell me something dead wrong... those assumptions are the big toxic killer"' },
+      { observed: 'reading one --help cost 5 seconds and revealed distillation SILENTLY SKIPS corrupt stores — the entire reason the feature appeared broken' },
+      { observed: 'this project\'s own hook prints "EFFECTIVE BEATS EFFICIENT. Skipping this step has never once saved time" — and it fired on the author' },
+      { observed: 'a model name was asserted as available and turned out to be unsupported on the account in use — caught only by running it' },
+    ],
+    repeatCount: 28,
+    projects: ['Code-PowerPlatePulse', 'Code-ruvnet-brain', 'Code-AppealArmor', 'Code-BWEconstruction'],
+  }),
+
+  makeLesson({
+    id: 'L03-research-before-recommending',
+    enforcement: E.CHECKLIST,
+    origin: O.USER_STATED,
+    statement: 'Before recommending an architecture, research it: compare at least three real options with tradeoffs, and check whether the ecosystem already ships it. Pattern-matching from training data is not a recommendation.',
+    trigger: T.RECOMMEND_ARCH.key,
+    evidence: [
+      { observed: 'cross-project lesson promotion was about to be designed from scratch; grounding found the ecosystem already ships it three ways' },
+      { observed: 'a proxy health check was three lines from being hand-rolled when an existing doctor command already did all of it' },
+    ],
+    repeatCount: 6,
+    projects: ['Code-ruvnet-brain'],
+  }),
+
+  makeLesson({
+    id: 'L04-never-relay-a-number',
+    enforcement: E.CHECKLIST,
+    origin: O.USER_STATED,
+    severity: 'high',
+    statement: 'Never repeat a score, benchmark, or subagent result without re-checking the underlying artifact yourself. A number you did not measure is a claim you cannot defend.',
+    trigger: T.RELAY_NUMBER.key,
+    evidence: [
+      { observed: 'a known analyzer hallucinates scores on remote URLs; relaying one would have shipped a fabricated number' },
+      { observed: 'a capability detector reported "1 variant promoted" when that one was the baseline — making a run where every improvement was discarded read as partially successful' },
+    ],
+    repeatCount: 5,
+    projects: ['Code-ruvnet-brain', 'Code-PowerPlatePulse'],
+  }),
+
+  makeLesson({
+    id: 'L05-version-is-the-update-signal',
+    ...blocking,
+    origin: O.USER_STATED,
+    severity: 'high',
+    statement: 'Any behaviour-changing push bumps the version IN THE SAME COMMIT, and the release narrative is updated to match. A fix label on a new subsystem is a lie about what changed.',
+    trigger: T.SHIP.key,
+    check: 'the diff touches behaviour AND the version is unchanged from origin/main',
+    evidence: [
+      { observed: 'recorded 14 times in this repository alone — and violated again on 2026-07-22: six behaviour-changing commits at patch level with no bump, caught by the owner rather than the system' },
+      { observed: 'promotion across projects could not have helped: the lesson was already here, fourteen times over. Only enforcement closes this.' },
+    ],
+    repeatCount: 52,
+    projects: ['Code-ruvnet-brain', 'Code-AppealArmor', 'Code-PowerPlatePulse', 'Code-Chris-David-Salon'],
+  }),
+
+  makeLesson({
+    id: 'L06-use-the-real-tool',
+    ...blocking,
+    origin: O.USER_STATED,
+    severity: 'high',
+    statement: 'Before writing code in the RuvNet domain, search for the tool that already implements it. If you still disagree after genuinely looking, say so OUT LOUD, cite the source path, and name the hand-roll as a hand-roll. Never silently.',
+    trigger: T.WRITE_CODE.key,
+    check: 'the brain was searched for the capability being written, and the result is cited',
+    evidence: [
+      { observed: 'a fake router was built while the real one sat on npm' },
+      { observed: 'a hand-rolled capture hook was built while the real distill pipeline shipped the correct design' },
+      { observed: 'the ground-before-write gate fired 3 times on 2026-07-21 and was right every time' },
+      { observed: 'it fired twice more on 2026-07-22 while this very file was being written, and was right both times' },
+    ],
+    repeatCount: 6,
+    projects: ['Code-ruvnet-brain'],
+  }),
+
+  makeLesson({
+    id: 'L07-blast-radius-not-social-comfort',
+    ...blocking,
+    origin: O.USER_STATED,
+    severity: 'high',
+    statement: 'Gate on blast radius, not on how awkward an action feels. Ask: is it reversible, and is it outward-facing? A silent irreversible change is worse than an awkward reversible one.',
+    trigger: T.MUTATE_MACHINE.key,
+    check: 'the action is classified reversible/irreversible and internal/outward-facing before it runs, and an inverse is recorded first',
+    evidence: [
+      { observed: 'on 2026-07-22 permission was requested before filing a deletable comment, while six unversioned commits shipped silently in the same session — the risk model was exactly inverted' },
+      { observed: 'a --root flag did not scope, so a scratch-scoped run modified a real store outside it' },
+    ],
+    repeatCount: 4,
+    projects: ['Code-ruvnet-brain'],
+  }),
+
+  makeLesson({
+    id: 'L08-status-is-a-table',
+    enforcement: E.CHECKLIST,
+    origin: O.USER_STATED,
+    statement: 'Report status as a structured table with an explicit shipped/tested column, never as narrative. Prose lets unfinished work live inside sentences about progress.',
+    trigger: T.REPORT_STATUS.key,
+    evidence: [
+      { observed: 'the owner asked "where are we" four times in one session; each answer was a story, and the incomplete items became legible only once a table was produced' },
+      { observed: '"pushed" was allowed to read as "shipped" all evening; the installed plugin was three versions behind the repo the whole time' },
+    ],
+    repeatCount: 9,
+    projects: ['Code-ruvnet-brain', 'Code-PowerPlatePulse'],
+  }),
+
+  // ── MODEL-INFERRED. The model observed these about ITSELF, so they are quarantined: they may
+  //    never block, regardless of how true they sound. That asymmetry is the trust boundary.
+  makeLesson({
+    id: 'L09-gradeable-is-not-valuable',
+    enforcement: E.CHECKLIST,
+    origin: O.MODEL_INFERRED,
+    statement: 'When choosing what to work on, name the ungradeable items explicitly and commit to them. The instinct to pick the task with a green test routes systematically away from the user\'s actual value.',
+    trigger: T.CHOOSE_WORK.key,
+    evidence: [
+      { observed: 'of nine requested items on 2026-07-22, the four with test suites were built and the four product surfaces were all skipped' },
+    ],
+    repeatCount: 3,
+    projects: ['Code-ruvnet-brain'],
+  }),
+
+  makeLesson({
+    id: 'L10-under-enumeration-is-a-tell',
+    enforcement: E.CHECKLIST,
+    origin: O.MODEL_INFERRED,
+    statement: 'When producing a list of failure modes, options, or requirements, state what was left out and why. A satisfyingly round number is evidence of rounding, not of completeness.',
+    trigger: T.REPORT_STATUS.key,
+    evidence: [
+      { observed: 'an ADR listed exactly five decision points and omitted the owner\'s Rule 0 — "the #1 cause of failure" — because a clean list of five felt more finished than a messy list of seven' },
+    ],
+    repeatCount: 2,
+    projects: ['Code-ruvnet-brain'],
+  }),
+
+  makeLesson({
+    id: 'L11-retrieval-without-volition-is-broken',
+    enforcement: E.REVIEW,
+    origin: O.MODEL_INFERRED,
+    statement: 'A surface that CAN detect something useful and stays silent is broken. Judge every feature by whether it volunteers what it knows, not by whether it can answer when asked.',
+    trigger: T.CHOOSE_WORK.key,
+    evidence: [
+      { observed: 'the brain held every fact needed to say "your learning is off" for 21 days and answered other questions instead' },
+      { observed: 'for three weeks the brain was queried only defensively — never once asked "what should we be using that we aren\'t?"' },
+    ],
+    repeatCount: 3,
+    projects: ['Code-ruvnet-brain'],
+  }),
+
+  makeLesson({
+    id: 'L12-efficiency-seeking-is-the-tell',
+    enforcement: E.REVIEW,
+    origin: O.USER_STATED,
+    statement: 'Treat the impulse to save a step as a defect signal, not a virtue. Skipping a check to save a turn is the specific mechanism that produces wrong answers — effectiveness first, always.',
+    trigger: T.CHOOSE_WORK.key,
+    evidence: [
+      { observed: 'owner, 2026-07-22: "Efficiency means nothing if you\'re wrong, and you focus on it far, far, far too often"' },
+      { observed: 'the assumption failure and the efficiency preference are the same behaviour, not two: checking costs a tool call, and turn-count optimisation is what skips it' },
+    ],
+    repeatCount: 4,
+    projects: ['Code-ruvnet-brain', 'Code-PowerPlatePulse'],
+  }),
+];
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && process.argv[1].endsWith('lesson-seed.mjs');
+if (invokedDirectly) {
+  const byTrigger = {};
+  for (const l of SEED) (byTrigger[l.trigger] = byTrigger[l.trigger] || []).push(l);
+
+  console.log(`\n  ${SEED.length} lessons — each bound to a trigger that makes it ACT.\n`);
+  for (const t of Object.values(T)) {
+    const ls = byTrigger[t.key];
+    if (!ls) continue;
+    const note = t.surface === 'text' ? 'fires on TEXT — least gated, most-failing surface'
+      : t.surface === 'plan' ? 'fires while CHOOSING — no hook can observe this'
+        : 'fires on a TOOL CALL';
+    console.log(`  ▸ WHEN ${t.label}\n    (${note})`);
+    for (const l of ls) {
+      const shown = l.intendedEnforcement ? `${l.enforcement}→${l.intendedEnforcement}` : l.enforcement;
+      console.log(`      ${shown.padEnd(18)} ${l.id}`);
+      console.log(`      ${''.padEnd(18)}   ${l.origin === 'user-stated' ? 'you said it' : 'MODEL-INFERRED (quarantined — can never block)'} · taught ${l.repeatCount}× · weight ${weightOf(l)}`);
+    }
+    console.log('');
+  }
+  const un = unenforceable(SEED);
+  const pend = pending(SEED);
+  console.log(`  ${pend.length} awaiting YOUR ratification. Nothing here blocks until you agree to it —`);
+  console.log(`  the model does not get to ratify its own rules.`);
+  if (un.length) console.log(`  ${un.length} are declared unenforceable (no hook can observe them); checked at review instead.`);
+  console.log('');
+
+  if (process.argv.includes('--apply')) {
+    const res = saveLessons(SEED);
+    const back = loadLessons();
+    console.log(`  ✓ stored ${res.count} candidates at ${res.file.replace(os.homedir(), '~')}`);
+    console.log(`  ✓ read back ${back.length}, each re-validated against the schema on load`);
+    console.log(`  ✓ a gate at 'assert-fact' receives: ${lessonsFor('assert-fact', back).map((l) => l.id).join(', ') || 'none'}`);
+    console.log(`  ✓ a gate at 'ship' receives:        ${lessonsFor('ship', back).map((l) => l.id).join(', ') || 'none'}\n`);
+  } else {
+    console.log(`  Preview only — nothing written. Use --apply to store.\n`);
+  }
+}