ruvnet-brain 4.0.1 → 4.0.2

package/scripts/agentdb-context.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// scripts/agentdb-context.mjs — AGENTDB IS THE FIRST-PARTY KEEPER OF CONTEXT.
+//
+//   node scripts/agentdb-context.mjs --session-start   full recent context, for the SessionStart hook
+//   node scripts/agentdb-context.mjs --window 48       last N hours, FULL text of every entry
+//   node scripts/agentdb-context.mjs --grep "latency"  full text of every entry matching
+//   node scripts/agentdb-context.mjs --key <key>       one entry, complete
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY THIS EXISTS — the owner, 2026-07-27, after the third time in one day:
+//
+//   "I am tired of you going 'oh, I checked and it was there', but I didn't bother to read it, or I
+//    looked at one line even though there were 10,000 words. Whatever you need to do to make AgentDB
+//    the first-party keeper of all the knowledge you rely on and you go to all the time, deeply,
+//    completely, fully, totally."
+//
+// THE THREE FAILURES THIS CLOSES, all on 2026-07-27, all the same shape:
+//   1. Told him Agentic-QE "did not run today" — from ONE `ls` of .agentic-qe/. It HAD run. AgentDB
+//      and the session transcripts both held the record; neither was opened.
+//   2. Re-derived the search-latency root cause from scratch at 19:00, having already measured and
+//      WRITTEN it at 11:50 (`brain-search-latency-rootcause`). Two hours of duplicated work because
+//      a crash ate the context and nothing reloaded it.
+//   3. Reported "4 branches unmerged" from a checkpoint, when one had already landed as PR #50.
+//
+// Every one of those was a SKIM: a directory listing, a key name, a one-line summary — never the
+// 1,824-byte entry that held the answer. So the fix is NOT another instruction telling me to read
+// carefully. Instructions decay; today proved it three times before dinner. The fix is to put the
+// FULL TEXT in the context window automatically, so there is nothing left to skim.
+//
+// DESIGN LAW (ADR-055): substance, never ceremony. A recall that records "a lookup happened" is the
+// grounding-stamp failure in a new costume — "The Brain did its job. I ignored it." This prints the
+// CONTENT. The test of success is not that it ran; it is that the answer was already on screen.
+//
+// NO SILENT CAPS. There is a byte budget, because a context window is finite. When it binds, this
+// says SO, out loud, with the exact count of what was withheld and the command to read it. A quiet
+// truncation reads as "that's all there is", which is the same lie one layer down.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(HERE, '..');
+
+// Budget. Generous on purpose: the failure mode being fixed is starvation, not excess. ~48KB is a
+// small fraction of the window and buys the entire recent history at FULL fidelity.
+const DEFAULT_BUDGET = 48_000;
+
+// Entry classes, most load-bearing first. Ordering matters: when the budget binds, what survives
+// should be the findings and the negatives, not the routine checkpoints.
+const PRIORITY = [
+  { re: /rootcause|root-cause|ROOT-CAUSE/i, label: 'ROOT CAUSE', rank: 0 },
+  { re: /^NORTH-STAR|north-star/i, label: 'NORTH STAR', rank: 0 },
+  { re: /lesson-/i, label: 'LESSON', rank: 1 },
+  { re: /project-state-current/i, label: 'CHECKPOINT', rank: 2 },
+  { re: /session-(precompact|sessionend)/i, label: 'SESSION SNAPSHOT', rank: 3 },
+];
+function classify(key) {
+  for (const p of PRIORITY) if (p.re.test(key)) return p;
+  return { label: 'NOTE', rank: 1 };
+}
+
+export function dbPath(root = REPO_ROOT) { return path.join(root, '.swarm', 'memory.db'); }
+
+// -json, never a delimiter. `content` is multi-line prose containing every punctuation mark there
+// is; the first draft framed rows with control characters and returned ZERO rows because they did
+// not survive the shell. JSON is the only framing sqlite3 offers that the payload cannot break.
+function sqliteJson(db, sql) {
+  const r = spawnSync('sqlite3', ['-json', db, sql], { encoding: 'utf8', maxBuffer: 128 * 1024 * 1024 });
+  if (r.status !== 0) return { ok: false, rows: [], err: (r.stderr || '').trim() || `sqlite3 exit ${r.status}` };
+  const out = (r.stdout || '').trim();
+  if (!out) return { ok: true, rows: [] };
+  try { return { ok: true, rows: JSON.parse(out) }; }
+  catch (e) { return { ok: false, rows: [], err: `unparseable sqlite3 -json output: ${e.message}` }; }
+}
+
+/**
+ * TWO SCHEMA GENERATIONS EXIST IN THE WILD, and a loader that knows only one is a loader that
+ * silently returns nothing. Measured across all 54 stores on this machine, 2026-07-28:
+ *
+ *   LEGACY  payload in `value`; `content` exists but DEFAULTS TO '' and is empty in every row.
+ *           created_at = strftime('%s','now')          -> epoch SECONDS
+ *   CURRENT payload in `content`.
+ *           created_at = strftime('%s','now') * 1000   -> epoch MILLISECONDS
+ *
+ * The first draft read `content` and assumed millis. Result: 8 projects holding 14,000+ entries —
+ * Red Clover Inn (6,358), AI Retirement Analyzer (7,198), XrAy-I, MedReview, partsourcepurchase,
+ * stratasocial, Christina Massuh, Fin Decision Website — loaded ABSOLUTELY NOTHING, and did so
+ * quietly. Their dates rendered as 1970-01-21, which is what a seconds timestamp looks like after
+ * you divide it by 1000 a second time.
+ *
+ * Both facts are DERIVED per store, never configured: columns from PRAGMA table_info, and the epoch
+ * unit from the magnitude of the value itself. Anything below 1e12 cannot be a modern millisecond
+ * timestamp (1e12 ms = 2001-09-09), so it is seconds.
+ */
+export function readEntries(db, { sinceMs, grep, key } = {}) {
+  if (!fs.existsSync(db)) return { ok: false, entries: [], err: `no AgentDB at ${db}` };
+
+  const cols = sqliteJson(db, "PRAGMA table_info(memory_entries);");
+  if (!cols.ok) return { ok: false, entries: [], err: cols.err };
+  const have = new Set(cols.rows.map((c) => String(c.name)));
+  if (!have.has('key')) return { ok: false, entries: [], err: 'no memory_entries.key — not an AgentDB store' };
+
+  // Payload: prefer a non-empty `content`, fall back to `value`. COALESCE+NULLIF handles the legacy
+  // rows where `content` is present-but-'' rather than NULL.
+  const payload = have.has('content') && have.has('value') ? "COALESCE(NULLIF(content,''), value)"
+    : have.has('content') ? 'content'
+    : have.has('value') ? 'value' : "''";
+  const nsCol = have.has('namespace') ? 'namespace' : "'default'";
+  const tsCol = have.has('created_at') ? 'created_at' : (have.has('updated_at') ? 'updated_at' : '0');
+
+  let where = `TRIM(${payload}) <> ''`;
+  if (key) where += ` AND key = '${String(key).replace(/'/g, "''")}'`;
+  if (grep) {
+    const g = String(grep).replace(/'/g, "''");
+    where += ` AND (lower(${payload}) LIKE lower('%${g}%') OR lower(key) LIKE lower('%${g}%'))`;
+  }
+  // NOTE: the time window is applied in JS, AFTER normalizing the epoch unit — doing it in SQL would
+  // require knowing the unit before reading a single row, which is the bug this function exists to fix.
+  const sql = `SELECT key AS k, ${nsCol} AS ns, ${tsCol} AS ts, ${payload} AS body
+               FROM memory_entries WHERE ${where} ORDER BY ${tsCol} DESC LIMIT 4000;`;
+  const r = sqliteJson(db, sql);
+  if (!r.ok) return { ok: false, entries: [], err: r.err };
+
+  const MILLIS_FLOOR = 1e12;   // 1e12 ms = 2001-09-09; anything smaller is seconds
+  let entries = r.rows.map((row) => {
+    const raw = Number(row.ts ?? 0);
+    return {
+      key: String(row.k ?? ''),
+      namespace: String(row.ns ?? ''),
+      at: raw > 0 && raw < MILLIS_FLOOR ? raw * 1000 : raw,
+      content: String(row.body ?? ''),
+    };
+  }).filter((e) => e.key && e.content);
+
+  if (sinceMs) entries = entries.filter((e) => e.at >= sinceMs);
+  return { ok: true, entries };
+}
+
+const stamp = (ms) => new Date(ms).toISOString().replace('T', ' ').slice(0, 16);
+
+export function render(entries, { budget = DEFAULT_BUDGET, header = '' } = {}) {
+  const ranked = entries
+    .map((e) => ({ ...e, cls: classify(e.key) }))
+    .sort((a, b) => (a.cls.rank - b.cls.rank) || (b.at - a.at));
+
+  const lines = [];
+  if (header) lines.push(header);
+  let used = header.length;
+  let shown = 0;
+  const withheld = [];
+
+  for (const e of ranked) {
+    const block = `\n── [${e.cls.label}] ${e.key}  (${stamp(e.at)}, ${e.content.length}B)\n${e.content}\n`;
+    if (used + block.length > budget) { withheld.push(e); continue; }
+    lines.push(block);
+    used += block.length;
+    shown++;
+  }
+
+  if (withheld.length) {
+    // NO SILENT CAPS. Name the count, the bytes, and exactly how to read them.
+    const bytes = withheld.reduce((n, e) => n + e.content.length, 0);
+    lines.push(`\n── ⚠ BUDGET BOUND — ${withheld.length} further entr${withheld.length === 1 ? 'y' : 'ies'} `
+      + `(${bytes.toLocaleString()} bytes) NOT shown above. This is a cap, not an absence — do not `
+      + `read the list above as complete. Read any of them in FULL with:\n`
+      + withheld.slice(0, 12).map((e) => `     node scripts/agentdb-context.mjs --key "${e.key}"`).join('\n')
+      + (withheld.length > 12 ? `\n     …and ${withheld.length - 12} more (--window <hours> to widen).` : ''));
+  }
+  return { text: lines.join('\n'), shown, withheld: withheld.length };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const arg = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+  const db = arg('--db', dbPath());
+
+  const sessionStart = argv.includes('--session-start');
+  const hours = Number(arg('--window', sessionStart ? 36 : 48));
+  const grep = arg('--grep', null);
+  const key = arg('--key', null);
+  const budget = Number(arg('--budget', DEFAULT_BUDGET));
+
+  const sinceMs = key || grep ? null : Date.now() - hours * 3600_000;
+  const r = readEntries(db, { sinceMs, grep, key });
+
+  if (!r.ok) {
+    // Fail SILENT for the hook (an absent store in another project is normal), loud for a human.
+    if (!sessionStart) console.error(`[agentdb-context] ${r.err}`);
+    return 0;
+  }
+  if (!r.entries.length) {
+    if (!sessionStart) console.log('[agentdb-context] no entries matched.');
+    return 0;
+  }
+
+  const header = sessionStart
+    ? `[AgentDB — FULL PROJECT CONTEXT, last ${hours}h. THIS IS THE RECORD. Read it before you assert `
+      + `anything about what happened, what was measured, what was decided, or what is still open. `
+      + `It exists because "I checked and it was there" — after reading one line of a 10,000-word `
+      + `entry — cost this project three duplicated investigations in a single day. Do not skim it; `
+      + `it is already the summary. Where it disagrees with your memory, IT is right.]`
+    : `[AgentDB — ${r.entries.length} entr${r.entries.length === 1 ? 'y' : 'ies'}, full text]`;
+
+  const out = render(r.entries, { budget, header });
+  console.log(out.text);
+  if (!sessionStart) console.error(`\n[agentdb-context] ${out.shown} shown, ${out.withheld} withheld by budget.`);
+  return 0;
+}
+
+function isMain() {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+}
+if (isMain()) process.exit(main());

package/scripts/agentdb-fleet-doctor.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// agentdb-fleet-doctor.mjs — per-project AgentDB health: AUDIT everything, FIX only what is
+// provably safe, VERIFY with a real round-trip, and REPORT the rest loudly.
+//
+// Born 2026-07-13 after the Helix finding: a project's store can be mechanically healthy while
+// its contents are useless at session start — entries fragmented across namespaces the
+// session-start hook never reads, including OTHER PROJECTS' namespaces (cross-contamination).
+//
+// WHAT IT FIXES (safe, additive only):
+//   • seeds a canonical `project-state-current-<ts>` checkpoint from git history when a project
+//     has none (the session-start hook surfaces it from then on)
+//   • runs `ruflo memory distill run` (ADR-174: incremental, non-destructive, $0)
+// WHAT IT ONLY REPORTS (never guesses):
+//   • foreign-project namespaces (moving another project's truth is how contamination
+//     COMPOUNDS — that data belongs elsewhere, a human decides)
+//   • fragmentation: how much of the store the session-start hook can actually see
+// VERIFY: a real store→search round-trip through the ruflo CLI in the project's own namespace.
+// Every fix is preceded by a timestamped .bak copy of the DB. Artifacts, never exit codes.
+
+import { spawnSync, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const RUFLO = path.join(os.homedir(), '.npm-global/bin/ruflo');
+const SYSTEM_NS = new Set(['sessions', 'feedback', 'default', 'patterns', 'adr-patterns', 'adr-edges', 'metaharness-audit']);
+
+function sql(db, q) {
+  try { return execFileSync('sqlite3', ['-noheader', db, q], { encoding: 'utf8', timeout: 15000 }).trim(); }
+  catch { return null; }
+}
+
+function ruflo(cwd, args) {
+  const r = spawnSync(RUFLO, args, { cwd, encoding: 'utf8', timeout: 120000 });
+  return { out: (r.stdout || '') + (r.stderr || ''), status: r.status };
+}
+
+async function doctor(proj) {
+  const name = path.basename(proj);
+  const db = path.join(proj, '.swarm', 'memory.db');
+  const row = { project: name, entries: 0, visible: 0, checkpoint: false, seeded: false, episodes: null, roundtrip: false, foreign: '', notes: [] };
+  if (!fs.existsSync(db)) { row.notes.push('no db'); return row; }
+
+  row.entries = Number(sql(db, 'SELECT count(*) FROM memory_entries;') ?? 0);
+  const hasSchema = sql(db, 'SELECT count(*) FROM episodes;') !== null;
+  if (!hasSchema) row.notes.push('OLD SCHEMA — needs export/init/import migration (see migrate-agentdb-schema.sh)');
+
+  // What can the session-start hook actually see?
+  row.visible = Number(sql(db, `SELECT count(*) FROM memory_entries WHERE namespace='${name}';`) ?? 0);
+  row.checkpoint = Number(sql(db, `SELECT count(*) FROM memory_entries WHERE namespace='${name}' AND key LIKE 'project-state-current%';`) ?? 0) > 0;
+
+  // Foreign-project namespaces: REPORT, never migrate.
+  const nsRows = (sql(db, 'SELECT namespace, count(*) FROM memory_entries GROUP BY namespace;') || '')
+    .split('\n').filter(Boolean).map((l) => l.split('|'));
+  row.foreign = nsRows.filter(([ns]) => ns !== name && !SYSTEM_NS.has(ns)).map(([ns, n]) => `${ns}=${n}`).join(',');
+
+  // FIX 1 (safe): seed a canonical checkpoint from git history when none exists.
+  if (!row.checkpoint) {
+    let gitlog = '';
+    try { gitlog = execFileSync('git', ['-C', proj, 'log', '--oneline', '-8'], { encoding: 'utf8', timeout: 10000 }).trim(); } catch { /* not a repo */ }
+    const val = `SEEDED CHECKPOINT ${new Date().toISOString()} (agentdb-fleet-doctor — no canonical checkpoint existed; the session-start hook had nothing to surface). Recent git history:\n${gitlog || '(not a git repo)'}\nMaintain from now on: append a NEW project-state-current-<epochms> row after meaningful work; never overwrite.`;
+    fs.copyFileSync(db, `${db}.bak-fleet-doctor-${Date.now()}`);
+    const r = ruflo(proj, ['memory', 'store', '-k', `project-state-current-${Date.now()}`, '--value', val, '-n', name]);
+    row.seeded = r.status === 0 && /stored successfully/i.test(r.out);
+    row.checkpoint = row.seeded;
+  }
+
+  // FIX 2 (safe): distill — incremental, non-destructive, $0.
+  if (hasSchema) {
+    ruflo(proj, ['memory', 'distill', 'run']);
+    row.episodes = Number(sql(db, 'SELECT count(*) FROM episodes;') ?? 0);
+  }
+
+  // VERIFY: real round-trip through the real CLI in the project's own namespace.
+  const canaryKey = `fleet-doctor-canary-${Date.now()}`;
+  const canaryVal = `round-trip canary ${new Date().toISOString()}`;
+  const stored = ruflo(proj, ['memory', 'store', '-k', canaryKey, '--value', canaryVal, '-n', name]);
+  if (stored.status === 0) {
+    const found = ruflo(proj, ['memory', 'search', '-q', 'fleet-doctor round-trip canary', '-n', name, '--limit', '3']);
+    // The result table TRUNCATES keys (`fleet-doctor-cana...`) — asserting on the full key was a
+    // false-negative bug (caught on first run, 2026-07-13, SpotOn: store fine, MY check wrong —
+    // the exact lesson-agentdb-was-never-broken defect class). Match what the table can show.
+    row.roundtrip = found.out.includes('fleet-doctor-cana') || found.out.includes('round-trip canary');
+  }
+  return row;
+}
+
+const targets = process.argv.slice(2);
+if (!targets.length) { console.error('usage: agentdb-fleet-doctor.mjs <project-dir> [...]'); process.exit(2); }
+
+const results = [];
+for (const t of targets) results.push(await doctor(path.resolve(t)));
+
+console.log('\nproject | entries | visible-at-start | checkpoint | episodes | round-trip | foreign-ns | notes');
+console.log('-'.repeat(110));
+for (const r of results) {
+  console.log([r.project, r.entries, r.visible, r.checkpoint ? (r.seeded ? 'SEEDED' : 'yes') : 'NO',
+    r.episodes ?? 'no-schema', r.roundtrip ? 'PASS' : 'FAIL', r.foreign || '-', r.notes.join('; ') || '-'].join(' | '));
+}
+const bad = results.filter((r) => !r.roundtrip || !r.checkpoint);
+console.log(`\n${results.length - bad.length}/${results.length} projects fully verified${bad.length ? ` — NEEDS ATTENTION: ${bad.map((r) => r.project).join(', ')}` : ''}`);

package/scripts/ascii-drift.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// scripts/ascii-drift.mjs — ADR-055 §8. The DETERMINISTIC half of the owner's second rule.
+//
+//   node scripts/ascii-drift.mjs            report: stale tracked diagrams + untracked candidates
+//   node scripts/ascii-drift.mjs --json     machine-readable, same evaluation
+//   node scripts/ascii-drift.mjs --quiet    one line, or nothing at all — for the session-start hook
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY THIS IS NOT A CONVERTER, AND WHY IT IS NOT A HOOK THAT CONVERTS.
+//
+// The `ascii-to-svg` skill has advertised, since 2026-01-08, that it is "Fully automatic via global
+// PostToolUse hook ~/.claude/hooks/ascii-svg-auto-sync.sh … set-and-forget." Measured 2026-07-27:
+// THAT FILE DOES NOT EXIST and never did; the manifest was last written 2026-06-29. It could not
+// have existed — converting a diagram needs a model, and a PostToolUse hook has a ~5s budget, no
+// session and no tokens.
+//
+// The first draft of ADR-055 then proposed conversion "at pre-push" and reproduced the identical
+// impossibility one chokepoint over: a pre-push git hook is also a shell process with no model. Both
+// duel reviewers caught it. So the work is SPLIT along the line that actually exists:
+//
+//   DETERMINISTIC (this file)  hashing, scoring, comparing. No model, no network, no writes.
+//   GENERATIVE  (the skill)    the conversion itself, invoked by a model that is actually present.
+//
+// and the deterministic half reports AT SESSION START — the one chokepoint where a model is in the
+// room and can act on what it is told.
+//
+// THIS FILE OWNS NO FORMAT. Every rule below is the SKILL's, read from its own files, because
+// naming our own would be the silent substitution `substitution:check` exists to prevent:
+//   · confidence scoring + negative signals + thresholds  -> the skill's detection.md
+//   · override markers                                    -> the skill's SKILL.md ("Override Markers")
+//   · manifest schema + ASCII normalization               -> the skill's change-tracking.md
+// If the skill changes its spec, this file is wrong and must follow it, not the other way round.
+//
+// IT NEVER BLOCKS AND NEVER WRITES. A stale picture is not a correctness defect, and a gate that
+// refuses a push over a diagram is a gate removed within the week (DDD-0008, the cut Diagram
+// aggregate). Worst case here is a line of text nobody acts on.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(HERE, '..');
+export const MANIFEST = '.ascii-to-svg-manifest.json';
+
+// Generated / vendored markdown is not authored — same exclusion list as the stamp sweep.
+const EXCLUDED = ['node_modules', '.git', 'kb', 'dist', 'clones', 'archive', '.agentic-qe', 'coverage', 'build', 'tmp', '.swarm'];
+
+// ── the skill's normalization (change-tracking.md, "Hash Calculation") ────────────────────────────
+// 1. trim leading/trailing whitespace from each line · 2. drop empty lines at start/end
+// 3. normalize line endings to \n · 4. remove the fence markers themselves
+export function normalizeAscii(block) {
+  const lines = String(block).replace(/\r\n?/g, '\n').split('\n')
+    .filter((l) => !/^\s*(```|~~~)/.test(l))
+    .map((l) => l.trim());
+  while (lines.length && !lines[0]) lines.shift();
+  while (lines.length && !lines[lines.length - 1]) lines.pop();
+  return lines.join('\n');
+}
+
+export function hashAscii(block) {
+  return 'sha256:' + crypto.createHash('sha256').update(normalizeAscii(block), 'utf8').digest('hex');
+}
+
+// ── the skill's confidence scoring (detection.md, "Detection Signals") ────────────────────────────
+const STRONG = [/[─│┌┐└┘├┤┬┴┼╔╗╚╝║═]/, /[→←↑↓↔↕▶◀▲▼►◄]/];
+const MEDIUM = [/\+-{1,}\+/, /(-->|<--|->|<-|=>|<=|~>)/, /^\s*([-=_]{3,})\s*$/m];
+const WEAK = [/[│┌└├].*[A-Za-z0-9]/, /^\s*[\^v]\s*$/m];
+// Negative signals — the half a naive "has box characters" test throws away, and the reason
+// terminal transcripts, tables and `tree` output do not become permanent false candidates.
+const NEGATIVE = [
+  { re: /^\s*\|.*\|\s*$[\s\S]*?^\s*\|[\s:-]+\|\s*$/m, why: 'markdown table' },
+  { re: /\b(function|const|let|var|def|class|import|return|if|for|while)\b/, why: 'source code' },
+  { re: /^\s*[$#>%]\s+\S/m, why: 'shell transcript' },
+  { re: /\b\d{4}-\d{2}-\d{2}\b|\[(INFO|WARN|ERROR|DEBUG)\]/, why: 'log output' },
+  { re: /^\s*[\w.-]+\s*[=:]\s*\S+\s*$/m, why: 'config key/value' },
+];
+const CONTEXT_WORDS = /(diagram|architecture|flow|structure|overview|schema|layout|design)/i;
+
+export function scoreBlock(body, { lang = '', preceding = '' } = {}) {
+  const reasons = [];
+  let score = 0;
+  for (const re of STRONG) if (re.test(body)) { score += 25; reasons.push('+25 box/arrow glyphs'); }
+  for (const re of MEDIUM) if (re.test(body)) { score += 15; reasons.push('+15 ascii box/arrow pattern'); }
+  for (const re of WEAK) if (re.test(body)) { score += 10; reasons.push('+10 weak layout signal'); }
+  for (const n of NEGATIVE) if (n.re.test(body)) { score -= 20; reasons.push(`-20 ${n.why}`); }
+  if (CONTEXT_WORDS.test(preceding)) { score += 15; reasons.push('+15 diagram-ish context'); }
+  if (/^(diagram|ascii|art|chart|graph)$/i.test(lang)) { score += 15; reasons.push('+15 fence language hint'); }
+  if (normalizeAscii(body).split('\n').length < 3) { score -= 20; reasons.push('-20 fewer than 3 lines'); }
+  return { confidence: Math.max(0, Math.min(100, score)), reasons };
+}
+
+// ── the skill's override markers (SKILL.md, "Override Markers") ───────────────────────────────────
+const SKIP_MARKER = /<!--\s*skip-ascii-to-svg\s*-->/;
+const FORCE_MARKER = /<!--\s*convert-to-svg(?::\s*[\w-]+)?\s*-->/;
+
+/** Every fenced block in a document, with the two lines of context that precede it. */
+export function fencedBlocks(text) {
+  const out = [];
+  const lines = String(text).replace(/\r\n?/g, '\n').split('\n');
+  let open = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*(```|~~~)(\w*)/);
+    if (!open && m) { open = { fence: m[1], lang: m[2] || '', start: i, body: [] }; continue; }
+    if (open && m && m[1] === open.fence) {
+      const preceding = lines.slice(Math.max(0, open.start - 3), open.start).join('\n');
+      out.push({ line: open.start + 1, lang: open.lang, body: open.body.join('\n'), preceding });
+      open = null; continue;
+    }
+    if (open) open.body.push(lines[i]);
+  }
+  return out;
+}
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  return { ok: r.status === 0, out: (r.stdout || '').trim() };
+}
+
+export function authoredDocs(root = REPO_ROOT) {
+  const ls = git(root, ['ls-files', '--', '*.md']);
+  if (!ls.ok) return [];
+  return ls.out.split('\n').filter(Boolean)
+    .filter((rel) => !rel.split('/').some((s) => EXCLUDED.includes(s)));
+}
+
+export function readManifest(root = REPO_ROOT) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, MANIFEST), 'utf8')); }
+  catch { return { version: '1.0.0', diagrams: [] }; }
+}
+
+/**
+ * STALE = a tracked diagram whose stored asciiHash matches NO block in its source file any more.
+ * Matched by hash across the whole file rather than by `sourceLine`, deliberately: line numbers
+ * drift on every edit above the block, and a line-anchored check would report drift for edits that
+ * never touched the diagram — the false-positive shape that gets a channel ignored.
+ */
+export function evaluate(root = REPO_ROOT, { threshold = 40 } = {}) {
+  const manifest = readManifest(root);
+  const tracked = Array.isArray(manifest.diagrams) ? manifest.diagrams : [];
+  const stale = [];
+  const candidates = [];
+  const byFile = new Map();
+
+  for (const rel of authoredDocs(root)) {
+    let text; try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { continue; }
+    byFile.set(rel, fencedBlocks(text).map((b) => ({ ...b, hash: hashAscii(b.body) })));
+  }
+
+  // THREE OUTCOMES, NOT TWO — and getting this wrong is how the channel dies on day one.
+  // First run of this detector reported all 5 tracked README diagrams as STALE. They are not:
+  // README carries NO box-drawing characters at all, the ASCII fallbacks were removed when the
+  // diagrams were converted, and all 5 SVGs exist (2.5-4KB) and are referenced 7 times from the
+  // page. That is the HEALTHY END STATE of a conversion, reported as a defect. Five false alarms
+  // out of five tracked items, on the very first run, in a channel whose only job is to be believed.
+  //   · SVG missing                      -> BROKEN, always worth saying
+  //   · hash gone + no ASCII left in file -> CONVERTED, the fallback was removed. Silent.
+  //   · hash gone + ASCII still in file   -> genuinely STALE: the source is there and it differs.
+  for (const d of tracked) {
+    const blocks = byFile.get(d.sourceFile);
+    if (!blocks) { stale.push({ ...d, why: 'source file is gone or no longer scanned' }); continue; }
+    if (blocks.some((b) => b.hash === d.asciiHash)) continue;             // exact match: current
+    if (!fs.existsSync(path.join(root, d.svgFile || ''))) {
+      stale.push({ ...d, why: 'the SVG file is MISSING — the page renders a broken image' });
+      continue;
+    }
+    // The SVG is present. Is any ASCII still sitting in the source that could have drifted from it?
+    const leftover = blocks.some((b) => scoreBlock(b.body, { lang: b.lang, preceding: b.preceding }).confidence >= threshold);
+    if (leftover) stale.push({ ...d, why: 'ASCII source is still present in the file and no longer matches the generated SVG' });
+    // else: converted and the fallback was removed — the intended end state. Say nothing.
+  }
+
+  const trackedHashes = new Set(tracked.map((d) => d.asciiHash));
+  for (const [rel, blocks] of byFile) {
+    for (const b of blocks) {
+      if (trackedHashes.has(b.hash)) continue;                 // already converted
+      if (SKIP_MARKER.test(b.preceding)) continue;             // the skill's explicit opt-out
+      const forced = FORCE_MARKER.test(b.preceding);
+      const s = scoreBlock(b.body, { lang: b.lang, preceding: b.preceding });
+      const confidence = forced ? 100 : s.confidence;
+      if (confidence >= threshold) {
+        candidates.push({ file: rel, line: b.line, confidence, forced, reasons: s.reasons, lines: normalizeAscii(b.body).split('\n').length });
+      }
+    }
+  }
+  candidates.sort((a, b) => b.confidence - a.confidence);
+  return { stale, candidates, trackedCount: tracked.length, scanned: byFile.size };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const r = evaluate();
+
+  if (argv.includes('--json')) { console.log(JSON.stringify(r, null, 2)); return 0; }
+
+  if (argv.includes('--quiet')) {
+    // The session-start voice: say something ONLY when there is something to do, and say it in one
+    // line. A channel that speaks every session about nothing is a channel that gets tuned out.
+    const bits = [];
+    if (r.stale.length) bits.push(`${r.stale.length} SVG diagram(s) out of date with their ASCII source`);
+    if (r.candidates.length) bits.push(`${r.candidates.length} ASCII block(s) that look like diagrams and have no SVG`);
+    if (bits.length) {
+      console.log(`[ASCII→SVG] ${bits.join(' · ')}. Say "convert the ascii diagrams" and the `
+        + `ascii-to-svg skill will render them (it owns the conversion; this check only measures).`);
+    }
+    return 0;
+  }
+
+  console.log(`\nascii→svg drift — ${r.scanned} authored document(s), ${r.trackedCount} tracked diagram(s)\n`);
+  if (r.stale.length) {
+    console.log(`  ${r.stale.length} STALE — the SVG no longer matches its ASCII source:\n`);
+    for (const s of r.stale) console.log(`    ▲ ${s.id}  (${s.sourceFile} → ${s.svgFile})\n       ${s.why}`);
+    console.log('');
+  }
+  if (r.candidates.length) {
+    console.log(`  ${r.candidates.length} CANDIDATE(S) — scored by the skill's own heuristics, never auto-converted:\n`);
+    for (const c of r.candidates) {
+      console.log(`    ○ ${c.file}:${c.line}  confidence ${c.confidence}${c.forced ? ' (forced by marker)' : ''}, ${c.lines} lines`);
+      console.log(`       ${c.reasons.join(' · ')}`);
+    }
+    console.log('\n  To decline one permanently, put the skill\'s own marker above the block:');
+    console.log('      <!-- skip-ascii-to-svg -->');
+    console.log('  That is the skill\'s convention, not ours — a candidate you have judged stays judged.');
+  }
+  if (!r.stale.length && !r.candidates.length) console.log('  nothing stale, nothing unconverted worth flagging.');
+  console.log('\nThis check never converts and never blocks. Conversion belongs to the ascii-to-svg skill.\n');
+  return 0;
+}
+
+function isMain() {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+}
+if (isMain()) process.exit(main());