ruvnet-brain 4.0.36 → 4.2.2-dev

package/scripts/brain-score.mjs

@@ -0,0 +1,261 @@
+/**
+ * brain-score.mjs — the ONLY sanctioned source of a score about this product.
+ *
+ * THE DEFECT THIS REPLACES, measured 2026-08-13. Asked to grade the architecture, I counted files
+ * — stores/repos, cards/stores — called the result 52/100, and reported it as an architecture
+ * grade. Six graders sat unused in this same repo. The real numbers were nothing like 52, and they
+ * disagreed with each other in ways that mattered:
+ *
+ *     grounded  100/100   does it fabricate?              (evals/baseline.json)
+ *     routed     63/80    does it reach the right store?  same file, same run
+ *     panel      ~56      independent multi-vendor grade  (data/grade-*.json)
+ *
+ * A single number could not have carried that. My 52 did not measure quality at all; it measured
+ * CATALOGUE COVERAGE and wore a quality label. That is the specific error this file makes
+ * structurally impossible: dimensions carry a `kind`, and `composite()` REFUSES to average across
+ * kinds. A coverage percentage and a quality percentage are answers to different questions, and
+ * collapsing them tells the owner his working product is failing while his users report it works.
+ *
+ * THE SECOND DEFECT, committed while correcting the first. Having found `grounded 100/100`, I
+ * quoted it as current. It was recorded 2026-07-10 — 34 days and ~40 commits earlier. The existing
+ * claims gate passed it because it checks INTERNAL consistency (k<=n, lo<=p<=hi) and never asks
+ * WHEN. So every dimension here declares `maxAgeDays`, and a reading past it is `stale` — reported,
+ * never silently used, and never the basis of a claim.
+ *
+ * This is not new machinery. It is ADR-065's own rule — facts are GENERATED, behaviours are TESTED
+ * — applied to the one class of fact that was still being typed by hand. `orgTotalApprox: 248` was
+ * this exact bug about a repo count; it was wrong by 48 in two files at once. `sync-version.mjs`
+ * and `sync-census.mjs` fixed it for versions and counts. Scores were never brought along.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const DAY = 86_400_000;
+
+/**
+ * Every dimension names the QUESTION it answers, because a number whose question is unstated is
+ * the thing that produced the 52. `kind` is load-bearing: see `composite()`.
+ */
+export const DIMENSIONS = [
+  {
+    key: 'grounded',
+    kind: 'quality',
+    question: 'When it answers, is the answer bound to real retrieved source rather than invented?',
+    artifact: 'evals/baseline.json',
+    maxAgeDays: 14,
+    read: (j) => ({ value: pct(j?.score?.grounded), detail: frac(j?.score?.grounded), at: j?.recorded }),
+  },
+  {
+    key: 'routed',
+    kind: 'quality',
+    question: 'Does a by-description query reach the store that actually holds the answer?',
+    artifact: 'evals/baseline.json',
+    maxAgeDays: 14,
+    read: (j) => ({ value: pct(j?.score?.routed), detail: frac(j?.score?.routed), at: j?.recorded }),
+  },
+  {
+    key: 'abstained',
+    kind: 'quality',
+    question: 'When it does NOT know, does it decline instead of producing something?',
+    artifact: 'evals/baseline.json',
+    maxAgeDays: 14,
+    read: (j) => ({ value: pct(j?.score?.abstain), detail: frac(j?.score?.abstain), at: j?.recorded }),
+  },
+  {
+    key: 'panelStrict',
+    kind: 'quality',
+    question: 'How do INDEPENDENT-vendor graders score the answers, strictly? (ADR-0002 gate)',
+    artifact: 'data/grade-*.json',
+    maxAgeDays: 30,
+    read: null, // aggregated across files — see readPanel()
+  },
+  {
+    key: 'catalogue',
+    kind: 'coverage',
+    question: 'What FRACTION of rUv\'s live repos has a store at all? (NOT a quality measure)',
+    artifact: 'data/org-repo-count.json + the live store root',
+    maxAgeDays: 7,
+    read: null, // derived — see readCatalogue()
+  },
+  {
+    key: 'routable',
+    kind: 'coverage',
+    question: 'What fraction of BUILT stores can a by-description query actually reach?',
+    artifact: 'capability-cards.md at the store root',
+    maxAgeDays: 7,
+    read: null,
+  },
+];
+
+/**
+ * Is this store reachable by a by-description query? ALIAS-AWARE, because the router is.
+ *
+ * Pure and exported so the rule can be tested without a live store root — the previous version was
+ * an inline `cards.has(s)` buried in an async reader, which is why nobody noticed it disagreed with
+ * the router. `resolve` is injected rather than imported here so a fixture can supply its own
+ * registry; production passes `repositoryNames` from kb/card-lane.mjs, the router's own resolver.
+ */
+export function isRoutable(store, cards, root, resolve) {
+  return resolve(store, root).some((name) => cards.has(name));
+}
+
+const pct = (s) => (s && Number.isFinite(s.p) ? Math.round(s.p * 1000) / 10 : null);
+const frac = (s) => (s && Number.isFinite(s.k) ? `${s.k}/${s.n}` : null);
+
+function readJson(rel) {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, rel), 'utf8')); } catch { return null; }
+}
+
+/** Aggregate the multi-vendor panel across whatever stores have actually been graded. */
+function readPanel() {
+  const dir = path.join(ROOT, 'data');
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => /^grade-.*\.json$/.test(f)); } catch { /* none */ }
+  const rows = files.map((f) => ({ f, j: readJson(path.join('data', f)) })).filter((r) => r.j?.summary);
+  if (!rows.length) return { value: null, detail: null, at: null };
+  const strict = rows.map((r) => r.j.summary.avgStrict).filter(Number.isFinite);
+  if (!strict.length) return { value: null, detail: null, at: null };
+  const at = rows
+    .map((r) => { try { return fs.statSync(path.join(dir, r.f)).mtime.toISOString(); } catch { return null; } })
+    .filter(Boolean).sort().pop();
+  return {
+    value: Math.round((strict.reduce((a, b) => a + b, 0) / strict.length) * 10) / 10,
+    detail: `${strict.length} store(s) graded`,
+    at,
+  };
+}
+
+/**
+ * Coverage is DERIVED from the live store root, never from a number in a doc. Returns null rather
+ * than a guess when the denominator is unknown — a wrong denominator still renders, which is worse
+ * than an absent one.
+ */
+export async function readCoverage(rootOverride) {
+  const { storeRoot, storesAt, cardsAt } = await import('../kb/store-root.mjs');
+  // ROUTABILITY IS ALIAS-AWARE, BECAUSE THE ROUTER IS.
+  //
+  // `carded` was `stores.filter((s) => cards.has(s))` — a direct name match against card HEADINGS,
+  // while the real router resolves a store through `repositoryNames()` first. So a store reachable
+  // ONLY under an alias counted as unroutable, and this metric under-reported the brain's own
+  // reachability: measured 2026-08-19, 30 stores called unroutable when 26 actually are —
+  // `metaharness` among the four, which is reachable through the `agent-harness-generator` card.
+  //
+  // That is not a rounding error, it is the same alias-blindness ADR-058 records as open in
+  // `darkStores()`, and it already cost something real: a false "dark store" reading led to a
+  // DUPLICATE `## metaharness` card being added, which collided with `agent-harness-generator` and
+  // broke alias resolution outright. A metric that cannot see aliases manufactures work that
+  // damages the thing it measures.
+  const { repositoryNames } = await import('../kb/card-lane.mjs');
+  const root = rootOverride ?? storeRoot();
+  // NEVER-MATERIALIZED, THE SAME AMBIGUITY `restore-local-ingests.mjs`'s `classify()` WAS FIXED
+  // FOR (PR #143, Night 1) — but never carried here. `storesAt()`/`cardsAt()` silently return
+  // `[]` on ENOENT, so a host whose store root was never restored (a fresh checkout, this very
+  // nightly agent's own ephemeral container) reads IDENTICALLY to a materialized root that
+  // genuinely has zero coverage. Checked once, here, before either derived number is computed —
+  // a wrong `0` still renders, which is worse than an honestly unmeasured one.
+  const neverMaterialized = !fs.existsSync(root);
+  const stores = storesAt(root);
+  const cards = new Set(cardsAt(root));
+  const org = readJson('data/org-repo-count.json');
+  const total = Number.isFinite(org?.count) && org.count > 0 ? org.count : null;
+  const carded = stores.filter((s) => isRoutable(s, cards, root, repositoryNames)).length;
+  const absentDetail = 'store root does not exist on this host (never materialized) — not evidence of live coverage';
+  return {
+    catalogue: {
+      value: neverMaterialized ? null : (total ? Math.round((stores.length / total) * 1000) / 10 : null),
+      detail: neverMaterialized ? absentDetail
+        : (total ? `${stores.length}/${total} live repos` : `${stores.length} stores, org total UNKNOWN`),
+      at: neverMaterialized ? null : (org?.at ?? null),
+    },
+    routable: {
+      value: neverMaterialized || !stores.length ? null : Math.round((carded / stores.length) * 1000) / 10,
+      detail: neverMaterialized ? absentDetail : `${carded}/${stores.length} built stores have a card`,
+      // Derived from the live store root at this instant, so it is current BY CONSTRUCTION. A
+      // read-now value reported as stale would train the reader to ignore the stale flag, which
+      // costs more than the flag is worth.
+      at: neverMaterialized ? null : new Date().toISOString(),
+    },
+  };
+}
+
+/** A reading past its dimension's `maxAgeDays`, or with no timestamp at all, is not current. */
+export function staleness(at, maxAgeDays, now = Date.now()) {
+  if (!at) return { stale: true, ageDays: null, why: 'no timestamp recorded' };
+  const ms = now - Date.parse(at);
+  if (!Number.isFinite(ms)) return { stale: true, ageDays: null, why: 'unparseable timestamp' };
+  const ageDays = Math.round((ms / DAY) * 10) / 10;
+  return { stale: ageDays > maxAgeDays, ageDays, why: ageDays > maxAgeDays ? `${ageDays}d > ${maxAgeDays}d budget` : null };
+}
+
+export async function brainScore({ now = Date.now() } = {}) {
+  const cov = await readCoverage();
+  const out = [];
+  for (const d of DIMENSIONS) {
+    let r;
+    if (d.key === 'panelStrict') r = readPanel();
+    else if (cov[d.key]) r = cov[d.key];
+    else r = d.read ? d.read(readJson(d.artifact)) : { value: null, detail: null, at: null };
+    out.push({
+      ...d,
+      ...r,
+      ...staleness(r.at, d.maxAgeDays, now),
+      status: r.value === null ? 'unmeasured' : (staleness(r.at, d.maxAgeDays, now).stale ? 'stale' : 'current'),
+    });
+  }
+  return out;
+}
+
+/**
+ * THE STRUCTURAL GUARD. Averaging a coverage percentage with a quality percentage is precisely the
+ * 52. It is refused here rather than discouraged in prose, because prose did not stop me.
+ */
+export function composite(dims, kind) {
+  if (!kind) return { value: null, refused: 'a score must name WHICH question it answers — pass a kind' };
+  const mine = dims.filter((d) => d.kind === kind);
+  if (!mine.length) return { value: null, refused: `no dimensions of kind "${kind}"` };
+  const usable = mine.filter((d) => d.status === 'current' && d.value !== null);
+  if (usable.length < mine.length) {
+    return {
+      value: null,
+      refused: `${mine.length - usable.length} of ${mine.length} ${kind} dimension(s) are stale or unmeasured`,
+      missing: mine.filter((d) => !usable.includes(d)).map((d) => `${d.key} (${d.status})`),
+    };
+  }
+  return { value: Math.round((usable.reduce((a, d) => a + d.value, 0) / usable.length) * 10) / 10, of: usable.length };
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const dims = await brainScore();
+  const asJson = process.argv.includes('--json');
+  if (asJson) {
+    console.log(JSON.stringify({ recorded: new Date().toISOString(), dimensions: dims }, null, 2));
+  } else {
+    console.log('\nRUVNET-BRAIN — MEASURED, never typed. Each row names the question it answers.\n');
+    for (const kind of ['quality', 'coverage']) {
+      console.log(`  ${kind.toUpperCase()}`);
+      for (const d of dims.filter((x) => x.kind === kind)) {
+        const v = d.value === null ? 'UNMEASURED' : `${d.value}`.padStart(5);
+        const age = d.ageDays === null ? '' : ` ${d.ageDays}d old`;
+        const flag = d.status === 'current' ? '' : `  <-- ${d.status.toUpperCase()}${d.why ? ` (${d.why})` : ''}`;
+        console.log(`    ${d.key.padEnd(13)} ${v}  ${(d.detail ?? '').padEnd(26)}${age}${flag}`);
+        console.log(`      ${d.question}`);
+      }
+      const c = composite(dims, kind);
+      console.log(c.value === null ? `    => NO ${kind} COMPOSITE: ${c.refused}` : `    => ${kind} composite ${c.value} (mean of ${c.of})`);
+      console.log('');
+    }
+    console.log('  A quality number and a coverage number are NEVER averaged. That was the 52.\n');
+  }
+  const anyStale = dims.some((d) => d.status !== 'current');
+  if (process.argv.includes('--require-current') && anyStale) {
+    console.error('brain-score: refusing — at least one dimension is stale or unmeasured. Re-run the graders.');
+    process.exit(1);
+  }
+}

package/scripts/brain-stamp.mjs

@@ -10,6 +10,9 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { canonicalRvfStores, hasCanonicalRvfStore } from './rvf-generation.mjs';
 import { getVersionTag, stripTag } from './version.mjs';
+// The org total is DERIVED, never a literal: it was hardcoded 248 in this file and in its
+// sibling while the account actually had 200 — one stale fact, restated twice (2026-08-12).
+import { orgRepoCount } from './org-repo-count.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
@@ -70,11 +73,12 @@ for (const store of canonicalRvfStores(KB_DIR)) {
   });
 }
 const built = repos.filter((r) => r.status === 'built');
+const ORG = orgRepoCount();
 const manifest = {
   brainVersion: stripTag(BRAIN_VERSION), // FIELD = bare literal; the "v" tag is display-only (see version.mjs)
   generated: NOW,
   generatedHuman: new Date(NOW).toUTCString(),
-  coverage: { built: built.length, catalogued: repos.length, orgTotalApprox: 248, pending: repos.length - built.length },
+  coverage: { built: built.length, catalogued: repos.length, orgTotalApprox: ORG.count, orgTotalSource: ORG.source, orgTotalAt: ORG.at, pending: repos.length - built.length },
   builtRepos: built,
   pendingRepos: repos.filter((r) => r.status === 'pending').map((r) => ({ name: r.name, tier: r.tier })),
 };

package/scripts/build-bundle.mjs

@@ -19,6 +19,10 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { getVersion, getVersionTag, stripTag } from './version.mjs';
 import { auditRvfIndexes } from './rvf-index-audit.mjs';
+import { validateSelectedRvfGenerations } from './rvf-generation.mjs';
+// The org total is DERIVED, never a literal: it was hardcoded 248 in this file and in its
+// sibling while the account actually had 200 — one stale fact, restated twice (2026-08-12).
+import { orgRepoCount } from './org-repo-count.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = path.join(ROOT, 'kb');
@@ -159,6 +163,15 @@ if (built.length === 0) {
   console.error('[build-bundle] FATAL: zero public RVF stores are eligible for release. Refusing to publish an empty brain bundle.');
   process.exit(1);
 }
+const generationValidation = validateSelectedRvfGenerations(ASSETS, {
+  selectedStores: built,
+  privateStores: [...PRIVATE_STORES],
+});
+if (generationValidation.failures.length) {
+  console.error('[build-bundle] FATAL: RVF generation ledger does not exactly bind selected roots:');
+  for (const failure of generationValidation.failures) console.error(`  ${failure}`);
+  process.exit(1);
+}
 const rvfIndexAudit = await auditRvfIndexes(
   built.map((name) => path.join(ASSETS, `${name}.big.rvf`)),
 );
@@ -205,7 +218,7 @@ for (const name of built) {
   if (!fs.existsSync(generationsFile)) {
     missing.push('RVF-GENERATIONS.json');
   } else {
-    const source = JSON.parse(fs.readFileSync(generationsFile, 'utf8'));
+    const source = generationValidation.manifest;
     const stores = {};
     for (const { name } of builtRepos) {
       if (!source.stores?.[name]) missing.push(`RVF-GENERATIONS.json:${name}`);
@@ -213,8 +226,8 @@ for (const name of built) {
     }
     fs.writeFileSync(path.join(OUT, 'RVF-GENERATIONS.json'), `${JSON.stringify({
       schemaVersion: source.schemaVersion,
-      brainVersion: source.brainVersion,
-      releaseTag: source.releaseTag,
+      brainVersion: stripTag(BRAIN_VERSION),
+      releaseTag: BRAIN_VERSION,
       stores,
     }, null, 2)}\n`);
     copied++;
@@ -263,6 +276,26 @@ if (hasGists) for (const suf of ['ruv-gists.big.rvf', 'ruv-gists.big.rvf.idmap.j
     fs.writeFileSync(path.join(OUT, 'capability-cards.md'), parts[0] + kept.join(''));
     copied++;
     if (filteredAny) console.log('[build-bundle] filtered private repo card(s) out of shipped capability-cards.md');
+
+    // repo-aliases.json TRAVELS WITH THE CARDS OR EVERY ALIAS IS DEAD ON ARRIVAL.
+    //
+    // card-lane.mjs reads it (REPO_ALIASES_FILE) to resolve a PRODUCT name to its installed store:
+    // `agent-harness-generator -> metaharness`, `ruvnet-brain -> brain`, `ruvector -> rvf`,
+    // `agentic-qe -> qe`. The bundle never copied it, so on every install those mappings were absent
+    // and the fast lane could not route them. Measured 2026-08-19 against the live store root:
+    // repo-aliases.json ABSENT, and `search_ruvnet("metaharness: what does Darwin mode mutate?")`
+    // answered "card router was ambiguous" — the product cannot be found by its own name.
+    //
+    // `forge-update.mjs:505` already lists this file among the ones it manages, so the updater knew
+    // about it and the builder did not — one fact, two shipping paths, only one of them told. Same
+    // shape as the reader/writer store-root split and the ingest `--out` bug fixed this week.
+    const aliasesSrc = path.join(KB, 'repo-aliases.json');
+    if (fs.existsSync(aliasesSrc)) {
+      fs.copyFileSync(aliasesSrc, path.join(OUT, 'repo-aliases.json'));
+      copied++;
+    } else {
+      console.log('[build-bundle] note: kb/repo-aliases.json absent — product-name aliases will not resolve on install');
+    }
   } else {
     console.log('[build-bundle] note: kb/capability-cards.md absent — the fast lane ships with no card source and will honestly fall through on every query');
   }
@@ -395,11 +428,12 @@ cp(path.join(ROOT, 'keys', 'ruvnet-brain-signing.pub.pem'), path.join(OUT, 'keys
 const builtLower = new Set(built.map((b) => b.toLowerCase()));
 const pendingRepos = regFlat.filter((r) => !builtLower.has(r.name.toLowerCase())).map((r) => ({ name: r.name, tier: r.tier }));
 const now = new Date();
+const ORG = orgRepoCount();
 const manifest = {
   brainVersion: stripTag(BRAIN_VERSION), // FIELD = bare literal; BRAIN_VERSION stays the v-prefixed Release tag
   generated: now.toISOString(),
   generatedHuman: now.toUTCString(),
-  coverage: { built: builtRepos.length, catalogued: regFlat.length, orgTotalApprox: 248, pending: pendingRepos.length },
+  coverage: { built: builtRepos.length, catalogued: regFlat.length, orgTotalApprox: ORG.count, orgTotalSource: ORG.source, orgTotalAt: ORG.at, pending: pendingRepos.length },
   crossRepoTool: { mcp: 'forge-mcp-all.mjs', cli: 'forge-ask-all.mjs', tool: 'search_ruvnet' },
   conceptsStore: hasConcepts ? { store: 'concepts.big.rvf', note: 'L2 synthesis + per-repo primers embedded as prose; unioned by search_ruvnet so code-implemented capabilities are retrievable as high-confidence prose.' } : null,
   builtRepos,

package/scripts/card-from-source.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * card-from-source.mjs — give a DARK store a card written from the repo's own words.
+ *
+ * A store with no capability card is DARK: the bytes are valid and no by-description query can
+ * reach them. `ingest-repo.mjs` says so on every run. After the 2026-08-20 bulk ingest the brain
+ * held ~111 stores and ~71 of them were dark — loaded, and unusable for anything except a query
+ * that already knew the repo's name, which is precisely the query a knowledge base is least needed
+ * for.
+ *
+ * THE LINE THIS DOES NOT CROSS. `ingest-new-repos.mjs` deliberately refuses to write cards, because
+ * a card invented from a repo NAME is a confident claim in the routing layer that nobody grounded —
+ * it routes real questions to a corpus that cannot answer them, which is worse than an honest gap.
+ * That refusal stands. This is a different act: it copies the repo's OWN description and the
+ * opening of its OWN README. Every content word in the card came from the repository. Nothing here
+ * infers what a project is "probably" for.
+ *
+ * AND IT SAYS WHAT IT IS. Each generated card carries a marker so a reader can tell it apart from
+ * the hand-written ones, which are richer — they say when to REACH for a tool and what it is NOT.
+ * An auto-derived card is a floor, not a substitute: it makes a store reachable and invites a
+ * better card later. Claiming otherwise would be the overselling this file exists to avoid.
+ *
+ *   node scripts/card-from-source.mjs                 # report which stores are dark
+ *   node scripts/card-from-source.mjs --apply         # write cards for them
+ *   node scripts/card-from-source.mjs --apply --max 20
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { storeRoot, darkStores } from '../kb/store-root.mjs';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
+const APPLY = process.argv.includes('--apply');
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const MAX = Number(arg('--max', '500'));
+export const MARKER = 'Auto-derived from the repository\'s own description and README';
+
+/** The repo's own description + README opening. Never a guess about what the name implies. */
+export function sourceFacts(repo) {
+  let description = '';
+  let readme = '';
+  try {
+    const meta = JSON.parse(execFileSync('gh', ['api', `repos/${OWNER}/${repo}`], { encoding: 'utf8', maxBuffer: 1 << 24 }));
+    description = String(meta?.description || '').trim();
+  } catch { /* a repo can legitimately have no description */ }
+  try {
+    const raw = execFileSync('gh', ['api', `repos/${OWNER}/${repo}/readme`, '-H', 'Accept: application/vnd.github.raw'],
+      { encoding: 'utf8', maxBuffer: 1 << 24 });
+    readme = raw;
+  } catch { /* and no README */ }
+  return { description, readme };
+}
+
+/** First real prose of a README: skip badges, HTML, headings, and link-only lines. */
+export function firstProse(readme, limit = 600) {
+  const lines = String(readme || '').split('\n');
+  const out = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) { if (out.length) break; continue; }
+    if (t.startsWith('#') || t.startsWith('<') || t.startsWith('|') || t.startsWith('---')) continue;
+    if (/^!?\[[^\]]*\]\([^)]*\)$/.test(t)) continue;          // a lone badge or image
+    if (/^\[!\[/.test(t)) continue;                            // badge-wrapped link
+    out.push(t);
+    if (out.join(' ').length > limit) break;
+  }
+  return out.join(' ').replace(/\s+/g, ' ').slice(0, limit).trim();
+}
+
+export function buildCard(repo, { description, readme }) {
+  const prose = firstProse(readme);
+  if (!description && !prose) return null;   // nothing grounded to say — leave it dark, honestly
+  const body = [description, prose].filter(Boolean).join(' — ');
+  return `## ${repo.toLowerCase()}\n${body}\n(${MARKER}; a hand-written card saying when to reach for it, and when not to, would be better.)\n`;
+}
+
+function insertSorted(file, card, name) {
+  const s = fs.readFileSync(file, 'utf8');
+  if (new RegExp(`^## ${name}$`, 'mi').test(s)) return false;
+  const heads = [...s.matchAll(/^## (.+)$/gm)].map((m) => [m.index, m[1].trim().toLowerCase()]);
+  const pos = heads.find(([, n]) => n > name)?.[0];
+  fs.writeFileSync(file, pos === undefined ? `${s.replace(/\n+$/, '')}\n\n${card}` : s.slice(0, pos) + card + '\n' + s.slice(pos));
+  return true;
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  const root = storeRoot();
+  const dark = darkStores(root);
+  console.log(`[card] ${dark.length} dark store(s) — valid bytes no by-description query can reach`);
+  if (!dark.length) process.exit(0);
+  if (!APPLY) {
+    console.log(`[card] ${dark.slice(0, 20).join(', ')}${dark.length > 20 ? ' …' : ''}`);
+    console.log('[card] report only. Re-run with --apply to write cards from each repo\'s own source.');
+    process.exit(0);
+  }
+  const repoCards = path.join(ROOT, 'kb', 'capability-cards.md');
+  const liveCards = path.join(root, 'capability-cards.md');
+  let wrote = 0; let skipped = 0;
+  for (const name of dark.slice(0, MAX)) {
+    const card = buildCard(name, sourceFacts(name));
+    if (!card) { skipped += 1; console.log(`[card] ${name}: no description and no README prose — left dark rather than invented`); continue; }
+    for (const f of [repoCards, liveCards]) { try { insertSorted(f, card, name.toLowerCase()); } catch { /* keep going */ } }
+    wrote += 1;
+  }
+  const remaining = darkStores(root).length;
+  console.log(`\n[card] wrote ${wrote}, left ${skipped} dark for lack of grounded source text, ${remaining} still dark.`);
+}

package/scripts/console-engine.mjs

@@ -126,7 +126,7 @@ export function buildHealthRecommendations({ memory = null, learning = null } =
   if (Number.isFinite(age) && age > STALE_TRAIN_SECONDS) {
     recs.push(makeRecommendation({
       id: 'learning:train',
-      scope: 'user',
+      scope: 'project',
       title: 'Your learner has gone quiet',
       rationale: 'It is installed and switched on, but it has not learned anything recently — so it is not getting smarter.',
       severity: 'SUGGESTED',