ruvnet-brain 4.7.20 → 4.7.22

package/plugin/scripts/kb-copy-proof.mjs

@@ -14,7 +14,18 @@
 //     listed with these exact bytes in the copy's own ARCHIVE-MANIFEST.json, or a public store family (named by either COVERAGE.json
 //     or the live SOURCE.json) that a newer release replaced or retired;
 //   * installer-written or reinstallable (node_modules/, the updater/validator files the installer places);
-//   * a symbolic link identical in the live brain (links are compared, never followed).
+//   * a symbolic link identical in the live brain (links are compared, never followed);
+//   * (#335) a regular file byte-identical at the same path in a KEPT sibling: another copy the caller has
+//     already decided to retain, or a `kb.archive/<stamp>/<copy>/` tree. The caller passes only copies that
+//     stay on disk, so duplicate preserved copies release down to one and no unique byte is lost.
+//   * an OPERATIONAL file the Brain's own processes (or a ruflo hook run with the KB as its cwd) wrote into
+//     the tree: a top-level update.log / forge-update.log / forge-guard-injection.log, or ruflo's
+//     .claude-flow/ scratch, each a regular file of at most RESCUE_CAP_BYTES (RESCUE_TOTAL_CAP_BYTES per
+//     copy). No bundle ships these and nothing reads them back, but a log can be the only trace of a failed
+//     night, so they are not just dropped: they are returned as `rescue` (with their bytes), and the caller
+//     copies them out with footprint-io.mjs rescueOperationalFiles BEFORE it removes the copy; a failed
+//     rescue keeps the copy. The rescued files are kept for the newest released copies (brain-footprint.mjs
+//     FOOTPRINT_POLICY.rescuedCopiesKept).
 // Anything else — a user's own file, an unfenced store, a link the live brain lacks — KEEPS the copy, and
 // is named. Paths are checked for symlink ancestors within both KB roots before any exemption; host
 // aliases above those roots (such as macOS /tmp) are not traversed as part of this check. Invalid metadata,
@@ -54,11 +65,25 @@ const stemOf = (file) => path.basename(String(file)).replace(/(?:\.big)?\.rvf$/i
 const storeStem = (file) => path.basename(String(file)).toLowerCase()
   .replace(/-primer\.md$/, '').replace(/(?:\.big)?\.rvf(?:\.[a-z]+\.json)?$/, '')
   .replace(/(?:\.big)?(?:\.(?:meta|symbols)\.json|\.passages\.jsonl)$/, '');
+// Operational files (see the header). Top-level logs by exact name: plugin/scripts/nightly-scheduler.mjs
+// installScheduler (update.log), kb/forge-guard-injection.mjs LOG_PATH, kb/forge-update.mjs's documented
+// cron line (forge-update.log). .claude-flow/ is ruflo's working state, the same debris brain-footprint.mjs
+// RUFLO_DEBRIS removes from ruflo-cwd. A larger file, a link, or anything else (.swarm/ included) stays unique,
+// and so does every operational file past RESCUE_TOTAL_CAP_BYTES per copy (the rescue itself is bounded).
+const OPERATIONAL_LOG = /^(?:update|forge-update|forge-guard-injection)\.log$/;
+export const RESCUE_CAP_BYTES = 2 * 1024 * 1024;
+export const RESCUE_TOTAL_CAP_BYTES = 16 * 1024 * 1024;
+const isOperational = (relative) => (!relative.includes(path.sep) && OPERATIONAL_LOG.test(relative))
+  || (relative.split(path.sep)[0] === '.claude-flow' && relative.includes(path.sep));
 // Files the installer/updater writes into a KB that no bundle ships (bin/install.mjs placeUpdater,
 // placeTrustedCoverageValidator, ensureVerifier; the updater's snapshot receipt). Re-created on every install.
-const INSTALLER_WRITTEN = new Set(['coverage-integrity.mjs', 'RUNTIME-IDENTITY.json', '.refresh-snapshot.json',
+// Every bin/install.mjs UPDATER_FILES name must be here (tests/unit/kb-copy-proof-unknown-content.test.mjs holds the
+// two lists together): download-retry.mjs and forge-guard-injection.mjs were placed but missing, so an old copy whose
+// placed version differed from both the live file and its own manifest was kept as "unique" (review round 2, Opus #5).
+export const INSTALLER_WRITTEN = new Set(['coverage-integrity.mjs', 'RUNTIME-IDENTITY.json', '.refresh-snapshot.json',
   'forge-update.mjs', 'zip-extract.mjs', 'brain-profile.mjs', 'refresh-run.mjs', 'update-storage-transaction.mjs',
-  'lifecycle-evidence-retention.mjs', 'corpus-release-identity.mjs', 'verify-citation.mjs', 'package-lock.json', '.DS_Store']);
+  'lifecycle-evidence-retention.mjs', 'corpus-release-identity.mjs', 'download-retry.mjs', 'forge-guard-injection.mjs',
+  'verify-citation.mjs', 'package-lock.json', '.DS_Store']);
 
 /** A directory that is a knowledge-base tree (SOURCE.json plus a store or the search entry point). */
 export const isKbTree = (dir) => Boolean(lstat(path.join(dir, 'SOURCE.json')))
@@ -140,10 +165,11 @@ function metadataFailure(root) {
 }
 
 /**
- * @returns {{disposable: boolean, unique: {file: string, why: string}[], reason: string}} — a kept copy
- * always names the files that keep it.
+ * @returns {{disposable: boolean, unique: {file: string, why: string}[], rescue?: {file: string, bytes: number,
+ * sha256: string}[], reason: string}} — a kept copy always names the files that keep it; a disposable copy
+ * lists the operational files that must be rescued before it is removed.
  */
-export function kbCopyProof({ copyDir, liveDir }) {
+export function kbCopyProof({ copyDir, liveDir, keptSiblings = [] }) {
   const copy = lstat(copyDir);
   if (!copy || copy.isSymbolicLink() || !copy.isDirectory()) return { disposable: false, unique: [], reason: 'not a real directory (a link is never entered)' };
   const live = lstat(liveDir);
@@ -172,7 +198,19 @@ export function kbCopyProof({ copyDir, liveDir }) {
   // it lists with these exact bytes is a public, re-downloadable release file.
   const shipped = new Map((readJson(path.join(copyDir, 'ARCHIVE-MANIFEST.json'))?.files || [])
     .filter((f) => typeof f?.path === 'string').map((f) => [path.normalize(f.path), f]));
-  const unique = [];
+  // #335: retained siblings that may account for a file. Only real directories, never the copy or live itself.
+  const siblings = (Array.isArray(keptSiblings) ? keptSiblings : []).filter((dir) => {
+    const st = lstat(dir);
+    return st && st.isDirectory() && !st.isSymbolicLink() && path.resolve(dir) !== path.resolve(copyDir)
+      && path.resolve(dir) !== path.resolve(liveDir);
+  });
+  let bySibling = 0;
+  const inKeptSibling = (relative) => {
+    const hit = siblings.some((dir) => safeAncestors(dir, relative) && sameBytes(path.join(copyDir, relative), path.join(dir, relative)));
+    if (hit) bySibling += 1;
+    return hit;
+  };
+  const unique = []; const rescue = []; let rescueBytes = 0;
   let files;
   try { files = walk(copyDir); } catch (error) { return { disposable: false, unique, reason: `unreadable copy: ${error.message}` }; }
   for (const { relative, link, size } of files) {
@@ -183,7 +221,7 @@ export function kbCopyProof({ copyDir, liveDir }) {
       continue;
     }
     if (isPrivate) {
-      if (!sameBytes(path.join(copyDir, relative), inLive)) {
+      if (!sameBytes(path.join(copyDir, relative), inLive) && !inKeptSibling(relative)) {
         unique.push({ file: relative, why: lstat(inLive) ? 'private file differs from the live brain' : 'private file absent from the live brain' });
       }
       continue;
@@ -202,9 +240,19 @@ export function kbCopyProof({ copyDir, liveDir }) {
     if (listed && listed.bytes === size && listed.sha256 === sha256File(path.join(copyDir, relative))) continue;
     if (sameBytes(path.join(copyDir, relative), inLive)) continue; // existence alone proves no ownership or redundancy
     if (publicNames.has(storeStem(relative))) continue; // a public store family a newer release replaced or retired
+    if (inKeptSibling(relative)) continue; // #335: these exact bytes stay in a retained sibling copy or the archive
+    if (isOperational(relative) && size <= RESCUE_CAP_BYTES && rescueBytes + size <= RESCUE_TOTAL_CAP_BYTES) {
+      rescue.push({ file: relative, bytes: size, sha256: sha256File(path.join(copyDir, relative)) });
+      rescueBytes += size;
+      continue;
+    }
+    if (isOperational(relative)) { unique.push({ file: relative, why: 'an operational file past the rescue cap (2 MiB each, 16 MiB per copy)' }); continue; }
     unique.push({ file: relative, why: 'not in the live brain, not in this copy\'s release manifest, not a public store' });
   }
   return unique.length
     ? { disposable: false, unique, reason: `holds ${unique.length} file(s) the live brain does not: ${unique.slice(0, 4).map((u) => u.file).join(', ')}${unique.length > 4 ? ', …' : ''}` }
-    : { disposable: true, unique, reason: 'every private file is byte-identical in the live brain; public bytes are re-downloadable' };
+    : { disposable: true, unique, rescue, reason: `${bySibling
+      ? `${bySibling} file(s) the live brain lacks are byte-identical in a kept copy or kb.archive; the rest is in the live brain or re-downloadable`
+      : 'every private file is byte-identical in the live brain; public bytes are re-downloadable'}${
+      rescue.length ? `; ${rescue.length} operational log/scratch file(s) are rescued to the brain home first` : ''}` };
 }

package/plugin/scripts/learn-capture.mjs

@@ -9,6 +9,7 @@ import { learningContext } from './runtime-preferences.mjs';
 import { recordLearningObservation, distillObservations, observationKey } from './learning-store.mjs';
 import { resolveRuflo } from './ruflo-bin.mjs';
 import { recordHookFailure } from './hook-failures.mjs';
+import { isDirectInvocation } from './entrypoint.mjs';
 
 // LOAD BOUNDS (measured 2026-10-21: one busy session spawned hundreds of concurrent detached `ruflo memory store`
 // children, which timed out against each other and wrote 826 ledger rows in a day). Owner ruling 2026-10-12 stands:
@@ -148,7 +149,7 @@ function runDetached(mode) {
   } catch (error) { fail(error); } finally { if (process.env.RUVNET_LEARN_SLOT) releaseObserveSlot(process.env.RUVNET_LEARN_SLOT); }
 }
 
-const isMain = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain && ['--observe', '--distill'].includes(process.argv[2])) {
   runDetached(process.argv[2]);
   process.exit(0);

package/plugin/scripts/learning-store.mjs

@@ -17,23 +17,29 @@ export function learningTarget(context, { env = process.env, explicitLegacyApply
   const root = path.join(context.home, '.claude', 'global-memory');
   const chosen = loadRuntimePreferences({ env, cwd: context.projectDir }).values.learningScope === 'user';
   if (!chosen && !explicitLegacyApply) throw new Error('user learning requires persisted user consent or explicit legacy Apply');
-  const rootStat = fs.lstatSync(root);
-  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('user learning root is not a real directory');
+  // #377: the user store is a FIXED path, validated directly. It is not a project, so no Git root is
+  // resolved (a ~/.claude that is itself a Git checkout made every user write "foreign global learner
+  // root"), and a missing store says so instead of surfacing a raw lstat ENOENT.
   const db = path.join(root, '.swarm', 'memory.db');
-  if (!fs.lstatSync(db).isFile()) throw new Error('user store not adopted');
-  const resolved = resolveProjectStore({ projectDir: root, requestedStorePath: db, gitTimeoutMs: 1000 });
-  if (resolved.projectRoot !== root) throw new Error('foreign global learner root');
-  return resolved.canonicalAgentDbPath;
+  const entry = (file) => { try { return fs.lstatSync(file); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+  const [rootStat, swarmStat, dbStat] = [root, path.dirname(db), db].map(entry);
+  if (!rootStat || !swarmStat || !dbStat) throw new Error(`user store not adopted (no ${db})`);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('user learning root is not a real directory');
+  if (!swarmStat.isDirectory() || swarmStat.isSymbolicLink()) throw new Error('user learning .swarm is not a real directory');
+  if (!dbStat.isFile() || dbStat.isSymbolicLink() || dbStat.nlink !== 1) throw new Error('user store is not an exclusive regular file');
+  const canonicalRoot = path.join(fs.realpathSync.native(context.home), '.claude', 'global-memory');
+  if (fs.realpathSync.native(root) !== canonicalRoot) throw new Error('user learning root is reached through a link');
+  return path.join(canonicalRoot, '.swarm', 'memory.db');
 }
 
-export function runLearningRuflo(binary, args, db, { env = process.env, deadline = Date.now() + 18_000, maxStepMs = 6000 } = {}) {
+export function runLearningRuflo(binary, args, db, { env = process.env, deadline = Date.now() + 18_000, maxStepMs = 6000, maxBuffer = 65536 } = {}) {
   const remaining = deadline - Date.now();
   if (remaining <= 0) throw new Error('learning deadline exhausted');
   const cwd = rufloRunDir(db, { root: env.RUVNET_RUFLO_CWD_ROOT || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.cache', 'ruvnet-brain', 'learning-ruflo') });
   try {
     const invocation = rufloInvocation(binary, args);
     return spawnSync(invocation.executable, invocation.args, { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_AUTO_UPDATE: 'false' },
-      encoding: 'utf8', shell: false, timeout: Math.min(maxStepMs, remaining), killSignal: 'SIGKILL', maxBuffer: 65536, windowsHide: true });
+      encoding: 'utf8', shell: false, timeout: Math.min(maxStepMs, remaining), killSignal: 'SIGKILL', maxBuffer, windowsHide: true });
   } finally { fs.rmSync(cwd, { force: true, recursive: true }); }
 }
 
@@ -73,15 +79,53 @@ export function recordLearningObservation(binary, context, { tool, action, sessi
   return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true };
 }
 
-/** Observation count through `ruflo memory list` (no direct SQLite). Unknown stays unknown. */
-export function learningStoreStatus(db, { binary = resolveRuflo(), env = process.env } = {}) {
-  if (!binary) return { known: false, observations: 0, patterns: null, lastDistillAt: null };
+/**
+ * The namespace's last distillation from `ruflo memory distill status --db` (#377). That command has
+ * only a table output: the `distill_state cursor` table's Namespace column is 20 wide, so
+ * `learning-observations` prints as `learning-observat...`; a truncated cell matches by prefix, and
+ * an ambiguous or unreadable answer stays unknown. `null` with known=true means never distilled.
+ */
+export function parseDistillStatus(text, namespace = LEARNING_NAMESPACE) {
+  const lines = String(text || '').replace(/\u001b\[[0-9;]*m/g, '').split(/\r?\n/);
+  const start = lines.findIndex((line) => /distill_state cursor/.test(line));
+  if (start < 0) return /No distill_state cursor rows yet/.test(lines.join('\n')) ? { known: true, lastDistillAt: null } : { known: false, lastDistillAt: null };
+  const rows = [];
+  for (const line of lines.slice(start + 1)) {
+    const cells = line.split('|').map((cell) => cell.trim());
+    if (cells.length < 5 || cells[1] === 'Namespace') continue;
+    rows.push({ name: cells[1], lastRun: cells[3] });
+  }
+  const exact = rows.filter((row) => row.name === namespace);
+  const truncated = rows.filter((row) => row.name.endsWith('...') && namespace.startsWith(row.name.slice(0, -3)));
+  const matches = exact.length ? exact : truncated;
+  if (!matches.length) return { known: true, lastDistillAt: null };
+  if (matches.length > 1) return { known: false, lastDistillAt: null };
+  if (matches[0].lastRun === 'never') return { known: true, lastDistillAt: null };
+  const at = Date.parse(matches[0].lastRun);
+  return Number.isFinite(at) ? { known: true, lastDistillAt: new Date(at).toISOString() } : { known: false, lastDistillAt: null };
+}
+
+/** Observation count through `ruflo memory list` and the last distillation through `ruflo memory distill status` (no direct SQLite). Unknown stays unknown. */
+export function learningStoreStatus(db, { binary = resolveRuflo(), env = process.env, run = runLearningRuflo } = {}) {
+  const unknown = { known: false, observations: 0, patterns: null, lastDistillAt: null, distillKnown: false, pendingObservations: null, oldestPendingAt: null };
+  if (!binary) return unknown;
   try {
-    const listed = runLearningRuflo(binary, ['memory', 'list', '--namespace', LEARNING_NAMESPACE, '--limit', '100000', '--format', 'json', '--path', db], db, { env });
+    const listed = run(binary, ['memory', 'list', '--namespace', LEARNING_NAMESPACE, '--limit', '100000', '--format', 'json', '--path', db], db, { env, maxBuffer: 64 * 1024 * 1024 });
     const text = String(listed.stdout || ''); const at = text.indexOf('[');
-    if (listed.status !== 0 || at < 0) return { known: false, observations: 0, patterns: null, lastDistillAt: null };
-    return { known: true, observations: JSON.parse(text.slice(at)).length, patterns: null, lastDistillAt: null };
-  } catch { return { known: false, observations: 0, patterns: null, lastDistillAt: null }; }
+    if (listed.status !== 0 || at < 0) return unknown;
+    const rows = JSON.parse(text.slice(at));
+    let distill = { known: false, lastDistillAt: null };
+    try {
+      const status = run(binary, ['memory', 'distill', 'status', '--db', db], db, { env });
+      if (!status.error && status.status === 0) distill = parseDistillStatus(status.stdout);
+    } catch { /* distillation state stays unknown */ }
+    const since = distill.lastDistillAt ? Date.parse(distill.lastDistillAt) : -Infinity;
+    // Observations recorded after the last distillation are the ones still waiting for it.
+    const pending = distill.known ? rows.filter((row) => !(Number(row?.createdAt) <= since)) : null;
+    const oldest = pending ? Math.min(...pending.map((row) => Number(row?.createdAt)).filter(Number.isFinite)) : Infinity;
+    return { known: true, observations: rows.length, patterns: null, lastDistillAt: distill.lastDistillAt, distillKnown: distill.known,
+      pendingObservations: pending ? pending.length : null, oldestPendingAt: Number.isFinite(oldest) ? new Date(oldest).toISOString() : null };
+  } catch { return unknown; }
 }
 
 /** `ruflo memory backup` then `ruflo memory distill run`; both are rUv's own commands. */
@@ -118,9 +162,11 @@ export function observeLearning(options = {}) {
   if (!context.enabled) return result;
   try {
     result.learningDb = learningTarget(context, { env });
-    const state = learningStoreStatus(result.learningDb, { env });
+    const state = learningStoreStatus(result.learningDb, { env, ...(options.binary ? { binary: options.binary } : {}), ...(options.run ? { run: options.run } : {}) });
     result.statusKnown = state.known; result.trajectories = state.observations; result.observations = state.observations;
     result.patterns = state.patterns; result.lastDistillAt = state.lastDistillAt;
+    result.distillKnown = state.distillKnown; result.pendingObservations = state.pendingObservations; result.oldestPendingAt = state.oldestPendingAt;
+    if (state.lastDistillAt) result.lastTrainSeconds = Math.max(0, Math.round(((options.now ?? Date.now()) - Date.parse(state.lastDistillAt)) / 1000));
   } catch { /* Missing consent/store/readback remains unknown. */ }
   return result;
 }

package/plugin/scripts/lesson-bridge.mjs

@@ -24,6 +24,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { makeLesson, updateLessons, loadLessons, ENFORCEMENT, ORIGIN, STATUS, TRIGGERS } from './lesson-store.mjs';
 import { loadNodeSqlite } from './node-sqlite.mjs';
+import { isDirectInvocation } from './entrypoint.mjs';
 
 /** Every bridged lesson id starts with this. It is how a merge knows which rows it owns. */
 export const BRIDGE_PREFIX = 'G-';
@@ -250,8 +251,7 @@ const argv = process.argv.slice(2);
  */
 function isMain() {
   try {
-    if (!process.argv[1]) return false;
-    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    return isDirectInvocation(import.meta.url);
   } catch { return false; }
 }
 if (isMain()) {

package/plugin/scripts/lesson-gate.mjs

@@ -80,6 +80,8 @@ import {
   CONFIG_ROOT,
   loadLessons,
   lessonsFor,
+  projectNameFor,
+  lessonApplies,
   ENFORCEMENT,
   STATUS,
   ORIGIN,
@@ -263,42 +265,8 @@ const gateState = event ? readGateState() : {};
  * the fastest way to make someone uninstall a nudge is to nudge them about something that has
  * nothing to do with what they are doing.
  */
-const HERE = (() => {
-  let d = process.cwd();
-  for (let i = 0; i < 12; i++) {
-    if (fs.existsSync(path.join(d, '.git'))) break;
-    const up = path.dirname(d);
-    if (up === d) { d = process.cwd(); break; }
-    d = up;
-  }
-  return path.basename(d);
-})();
-/**
- * A "suffix match" for project names, bounded so it cannot fire on a bare shared tail. `a` matches
- * `b` when `b` is a whole path/name SEGMENT suffix of `a` — the character immediately before it must
- * be a separator, never a mid-word letter. Without this, "Sentry" matched inside "WhitSentry" and any
- * project name that merely happens to end another's, which is the exact cross-project leak the
- * 2026-07-22 project-scope fix (this same function, below) was written to close.
- */
-const segmentSuffixMatch = (a, b) => {
-  if (a === b) return true;
-  if (a.length <= b.length || !a.endsWith(b)) return false;
-  return /[-_/]/.test(a[a.length - b.length - 1]);
-};
-
-/** Does this lesson belong to the project we are standing in? Match is loose on purpose — stored
- *  names carry prefixes like `Code-` that the directory name does not — but bounded to a real
- *  delimiter so it cannot match a bare, accidental shared suffix between unrelated projects. */
-const isHome = (l) => {
-  const ps = Array.isArray(l.projects) ? l.projects : [];
-  if (!ps.length) return true;                       // unscoped: applies anywhere, by declaration
-  return ps.some((p) => {
-    const n = String(p).replace(/^Code-/, '');
-    return n === HERE || String(p) === HERE
-      || segmentSuffixMatch(HERE, n) || segmentSuffixMatch(n, HERE);
-  });
-};
-const isUniversal = (l) => Array.isArray(l.projects) && l.projects.length >= 2;
+const HERE = projectNameFor(process.cwd());
+const applies = (l) => lessonApplies(l, HERE);
 
 // Apply the mutate-machine predicate defined above. `mutate-machine` is requested for EVERY Bash
 // call (plugin/scripts/lesson-hooks.sh:98) — it is the ONLY trigger the dispatcher fires unconditionally
@@ -313,10 +281,10 @@ const effectiveTriggers = command === null
 const seen = new Set();
 const candidates = [];
 for (const t of effectiveTriggers) {
-  for (const l of lessonsFor(t, lessons.filter((l) => isHome(l) || isUniversal(l)), { limit: 3 })) {
+  for (const l of lessonsFor(t, lessons.filter(applies), { limit: 3 })) {
     if (seen.has(l.id)) continue;
-    // Away from home, only a lesson with cross-project evidence may speak.
-    if (!isHome(l) && !isUniversal(l)) continue;
+    // Away from home, only a lesson with cross-project evidence may speak (lessonApplies: one rule, shared with the Console).
+    if (!applies(l)) continue;
     seen.add(l.id); candidates.push(l);
   }
 }

package/plugin/scripts/lesson-promote.mjs

@@ -36,6 +36,8 @@
  *   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
+ *   node scripts/lesson-promote.mjs --demote-theme <key>   # reject a theme — sticky, never re-proposed
+ *   node scripts/lesson-promote.mjs --restore-theme <key>  # undo a demotion
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -124,34 +126,55 @@ export function collectLessons(root = PROJECTS) {
  * other project's context.
  */
 /**
- * Themes the user has explicitly rejected. Read from the lesson store's demoted rows.
+ * THE DEMOTED-THEMES FILE — where "reject this theme, permanently" is recorded, and why it is not a
+ * field on a lesson row.
  *
- * 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.
+ * The original design (2026-07-22) stored a `themeKey` on a demoted lesson inside `lessons.json` and
+ * read it back here. It never worked, and could not have: `makeLesson()` (`lesson-store.mjs`)
+ * destructures a FIXED field set and freezes the result, so an unknown key — `themeKey` included — is
+ * silently dropped the moment a row passes through it. Verified 2026-09-07 by construction: a
+ * hand-edited row carrying `themeKey` survives only until the very next legitimate write ANYWHERE in
+ * the store (`lesson-ratify.mjs --demote`, `updateLessons()`, any `loadLessons()` → `saveLessons()`
+ * round trip) — at that point every row, not just the one touched, has been re-serialized through
+ * `makeLesson()` and the field is gone. There was also no writer at all: `lesson-ratify.mjs --demote`
+ * only ever demotes by lesson `id`, never by theme. `demotedThemeKeys()` therefore always returned an
+ * empty set in every real invocation, and the sticky-demotion guard in `analyze()` below could never
+ * fire — the exact "demotion is theatre" failure ADR-030 §5 names, just for a different reason than
+ * the 2026-07-22 comment this replaces described.
  *
- * 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.
+ * `lesson-gate.mjs`'s `OPTIN_PATH` documents the identical failure shape for a different field
+ * (`userOptedIntoBlocking`) and moved that consent to its own file for exactly this reason. That
+ * precedent was never applied here; it is now. Theme demotion gets its own small file, written only
+ * by `--demote-theme` / `--restore-theme` below, and never touched by the mining or lesson-store
+ * write paths — so no future lesson-store write can silently erase it.
  */
-function demotedThemeKeys() {
+export const DEMOTED_THEMES_PATH = process.env.RUVNET_DEMOTED_THEMES
+  || path.join(HOME, '.config', 'ruvnet-brain', 'demoted-themes.json');
+
+function demotedThemeKeys(file = DEMOTED_THEMES_PATH) {
   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(); }
+    // Tolerant of both shapes, same reasoning as OPTIN_PATH: this file is expected to be hand-edited.
+    const list = Array.isArray(raw) ? raw : Array.isArray(raw?.demoted) ? raw.demoted : [];
+    return new Set(list.filter((x) => typeof x === 'string' && x.length));
+  } catch { return new Set(); }   // absent or unparseable → nothing demoted. Never fail INTO hiding a theme.
+}
+
+/** The only writer of DEMOTED_THEMES_PATH. Demotes or restores one theme key. */
+export function setThemeDemoted(key, demoted, file = DEMOTED_THEMES_PATH) {
+  const current = demotedThemeKeys(file);
+  if (demoted) current.add(key); else current.delete(key);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ demoted: [...current].sort() }, null, 2) + '\n');
+  return current;
 }
 
-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();
+export function analyze(lessons, { minProjects = MIN_PROJECTS, rejected = null, demotedThemesFile } = {}) {
+  // `rejected` is a pre-built Set, injectable for pure clustering tests.
+  // `demotedThemesFile` redirects the REAL disk reader (`demotedThemeKeys()`) to a fixture path — for
+  // tests that must exercise the actual read/write round trip, not a Set built by hand. Neither
+  // option is used by the CLI, which always takes the real default file for a real process.
+  const demoted = rejected instanceof Set ? rejected : demotedThemeKeys(demotedThemesFile);
   const eligible = lessons.filter((l) => l.type === 'feedback');
   const themes = [];
   for (const t of THEMES) {
@@ -227,12 +250,50 @@ export function applyPromotion(result, { file, now }) {
     ? 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}` }; }
+  // ATOMIC write — temp sibling then rename, never in place. The same discipline bin/install.mjs's
+  // offerClaudeMd() already applies to this exact file (ADR-063 lineage): an in-place writeFileSync
+  // leaves the real file truncated if the process dies mid-write (disk full, SIGKILL, power loss).
+  // A rename within the same directory is atomic on every OS this project ships to, so CLAUDE.md is
+  // always either fully the old content or fully the new content, never a torn hybrid.
+  const tmp = `${file}.ruvnet-tmp`;
+  try {
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* best effort — the real file is untouched either way */ }
+    return { ok: false, log: `write failed: ${e.message}; backup at ${backup}` };
+  }
+
+  // ROUND-TRIP PROOF, not an inferred success: a successful rename proves the bytes landed at
+  // `file`'s path, but not that they are the bytes this call intended — read the real path back
+  // and compare, the same discipline degradation-watch.mjs's proveMemoryDurable() applies to every
+  // other durable write in this repo.
+  let onDisk = '';
+  try { onDisk = fs.readFileSync(file, 'utf8'); } catch (e) {
+    return { ok: false, log: `wrote ${file.replace(HOME, '~')} but could not read it back to verify (${e.message}); backup at ${backup}` };
+  }
+  if (onDisk !== next) {
+    return { ok: false, log: `wrote ${file.replace(HOME, '~')} but the read-back did not match — refusing to report success; 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 && (has('--demote-theme') || has('--restore-theme'))) {
+  const demoting = has('--demote-theme');
+  const key = arg(demoting ? '--demote-theme' : '--restore-theme');
+  if (!THEMES.some((t) => t.key === key)) {
+    console.error(`\n  ✗ unknown theme "${key}". Known keys: ${THEMES.map((t) => t.key).join(', ')}\n`);
+    process.exit(1);
+  }
+  setThemeDemoted(key, demoting);
+  console.log(`\n  ${demoting ? '✓ demoted' : '✓ restored'} theme "${key}" — `
+    + `${demoting ? 'will never be re-proposed by a future scan' : 'eligible again on the next scan'} `
+    + `(${DEMOTED_THEMES_PATH.replace(HOME, '~')})\n`);
+  process.exit(0);
+}
 if (invokedDirectly) {
   const result = analyze(collectLessons());
   if (has('--json')) { console.log(JSON.stringify(result, null, 2)); process.exit(0); }

package/plugin/scripts/lesson-scope.mjs

@@ -0,0 +1,51 @@
+/**
+ * Where a lesson applies: the ONE project-identity and applicability rule, shared by plugin/scripts/lesson-gate.mjs and
+ * the Console (scripts/onboarding-console.mjs). Re-exported from lesson-store.mjs. Pure apart from the git/fs reads
+ * projectNameFor makes, which are bounded.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+
+/**
+ * THE project identity lessons are scoped by: the folder name of the CANONICAL project root (the primary checkout,
+ * the same root resolveProjectStore uses for the store), so a linked worktree `feature-x` is the project it belongs to,
+ * not its own name. Falls back to the nearest folder holding a `.git`, then to the folder itself, when the resolver
+ * refuses (the name is only a lesson-scope label; a refusal must not silence the gate).
+ */
+export function projectNameFor(cwd = process.cwd()) {
+  try { return path.basename(resolveProjectStore({ projectDir: cwd, gitTimeoutMs: 500 }).projectRoot); } catch { /* fall through */ }
+  let d = cwd;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(d, '.git'))) return path.basename(d);
+    const up = path.dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return path.basename(cwd);
+}
+
+/**
+ * `a` matches `b` when `b` is a whole path/name SEGMENT suffix of `a`: the character before it must be a separator,
+ * never a mid-word letter ("Sentry" must not match inside "WhitSentry").
+ */
+export function segmentSuffixMatch(a, b) {
+  if (a === b) return true;
+  if (a.length <= b.length || !a.endsWith(b)) return false;
+  return /[-_/]/.test(a[a.length - b.length - 1]);
+}
+
+/**
+ * THE applicability rule (lesson-gate and the Console share it): a lesson applies to a project when it is unscoped,
+ * scoped to that project (stored names may carry a `Code-` prefix the folder lacks), or proven in two or more
+ * projects (cross-project rediscovery is what makes it universal, ADR-029).
+ */
+export function lessonApplies(lesson, projectName) {
+  const ps = Array.isArray(lesson?.projects) ? lesson.projects : [];
+  if (!ps.length || ps.length >= 2) return true;
+  const here = String(projectName);
+  return ps.some((p) => {
+    const n = String(p).replace(/^Code-/, '');
+    return n === here || String(p) === here || segmentSuffixMatch(here, n) || segmentSuffixMatch(n, here);
+  });
+}

package/plugin/scripts/lesson-store.mjs

@@ -24,7 +24,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { SOURCE_CLASS, STATUS, isUntouchedOwnerSeedRow } from './lesson-provenance.mjs';
-
+export { projectNameFor, segmentSuffixMatch, lessonApplies } from './lesson-scope.mjs';
 export { BUNDLED_OWNER_SEED_IDS, SOURCE_CLASS, STATUS, isUntouchedOwnerSeedRow } from './lesson-provenance.mjs';
 
 /** Resolve fixture/plugin configuration without mutating the child process account HOME. */

package/plugin/scripts/md-stamp.mjs

@@ -36,6 +36,7 @@ import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { parseHookEvent, toolName, field, readStdinBounded } from './hook-input.mjs';
 import { contains, projectDirectory } from './project-identity.mjs';
+import { isDirectInvocation } from './entrypoint.mjs';
 
 // ── date, from the system clock, formatted in the repo's standard timezone ─────────────────────────
 // Same idiom as scripts/self-update.mjs's README badge stamp: Intl.DateTimeFormat is a Node builtin
@@ -312,7 +313,7 @@ async function main() {
 }
 
 function isMain() {
-  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 }