ruvnet-brain 4.0.36 → 4.0.90-dev

package/plugin/scripts/identifier-preflight.mjs

@@ -0,0 +1,134 @@
+/**
+ * identifier-preflight.mjs — an external identifier is CHECKED before it is committed to, or the
+ * failure is silent and expensive.
+ *
+ * THE COST, measured 2026-08-13. I launched a 50-minute adversarial audit with
+ * `codex exec --model gpt-5.6`. The real model is `gpt-5.6-sol`, and it was sitting in
+ * `~/.codex/config.toml` where two seconds of reading would have found it. What made it expensive
+ * was not the typo:
+ *
+ *     codex printed `ERROR: 400 The 'gpt-5.6' model is not supported` AND EXITED 0,
+ *     into a file I had redirected and was not reading.
+ *
+ * So there was no exit code to catch, no exception, and no output on screen. Fifty minutes of the
+ * owner's time bought nothing, and the loss surfaced only because he asked why the result was late.
+ * The typo is a two-second fix; the SILENCE is the defect.
+ *
+ * WHY THIS IS THE FOURTH INSTANCE OF ONE PATTERN, not a new bug. This repo already owns
+ * `scripts/verify-model-catalog.mjs`, whose own header calls it "THE WALL for model facts … the
+ * enforcement of Rule 0 for the one place it kept getting skipped: model/version claims" (ADR-0016).
+ * It verifies models written into `data/model-catalog.json`. It has never verified a model NAME
+ * PASSED TO A COMMAND. Same shape as the freshness machinery pointed at coverage but not the eval,
+ * `resolveBash()` present but unused at a new call site, and `findInvocations()` existing while a
+ * ship glob greps raw text. The machinery keeps existing and keeps pointing one surface away from
+ * where the failure happens.
+ *
+ * DESIGN, corrected against an adversarial review of my other hooks earlier the same day:
+ *   · FAIL OPEN. An identifier this cannot resolve is ALLOWED, silently. The reviewed sibling turned
+ *     a missing `sqlite3` into "the memory store is not durably persisting writes" — a fabricated
+ *     diagnosis is worse than no check, because it burns the credibility the channel runs on.
+ *   · NO CACHE. The same review found a cache keyed by $USER but probing a per-project path, so one
+ *     project's verdict refused work in another. There is nothing here worth caching.
+ *   · REFUSE ONLY ON A KNOWN-WRONG VALUE, never on an unknown one, and SAY THE RIGHT ANSWER — a wall
+ *     that reports a problem without the fix is one the user routes around.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Each entry knows how to enumerate the identifiers its CLI actually accepts on THIS machine.
+ * `known()` returning an empty list means "cannot tell" and the check stands down — that is the
+ * fail-open path and it is the common one.
+ */
+export const CLIS = [
+  {
+    id: 'codex',
+    // `codex exec --model X`, `codex -m X`. The flag may appear anywhere in the command.
+    matches: (cmd) => /\bcodex\b/.test(cmd),
+    flag: /(?:--model|(?<![\w-])-m)[= ]+["']?([\w.:-]+)["']?/,
+    known: (home = os.homedir()) => {
+      // The config's `model` is the one identifier PROVEN to work on this account — codex rejects
+      // others per-account ("not supported when using Codex with a ChatGPT account"), so a static
+      // list of "models that exist" would be exactly the stale-memory fact ADR-0016 forbids.
+      try {
+        const txt = fs.readFileSync(path.join(home, '.codex', 'config.toml'), 'utf8');
+        const m = txt.match(/^\s*model\s*=\s*["']([^"']+)["']/m);
+        return m ? [m[1]] : [];
+      } catch { return []; }
+    },
+  },
+];
+
+/**
+ * QUOTED TEXT IS AN ARGUMENT, NOT A FLAG. `codex exec "explain the --model gpt-5.6 error"` passes
+ * that string as a PROMPT; refusing it would block asking about the very mistake this file exists
+ * to prevent. Caught by testing the edge instead of assuming, minutes after an adversarial review
+ * found a sibling fix greping raw command text for `git push` and matching
+ * `grep -n "npm publish" docs/…`. Same defect, same day, two files apart: the truth-maker is the
+ * EXECUTABLE POSITION, and a prompt is always quoted, so the quoted regions come out first.
+ */
+const unquoted = (cmd) => cmd.replace(/"[^"]*"/g, ' ').replace(/'[^']*'/g, ' ');
+
+/** Pull the identifier a command commits to, if any. */
+export function identifierIn(command, clis = CLIS) {
+  const raw = String(command || '');
+  const cmd = unquoted(raw);
+  for (const c of clis) {
+    if (!c.matches(cmd)) continue;
+    const m = cmd.match(c.flag);
+    if (m) return { cli: c, value: m[1] };
+  }
+  return null;
+}
+
+/**
+ * The verdict. `unknown` is a first-class answer and it ALLOWS — this refuses only when the machine
+ * can positively enumerate what the CLI accepts and the requested value is not among them.
+ */
+export function check(command, opts = {}) {
+  const hit = identifierIn(command, opts.clis ?? CLIS);
+  if (!hit) return { verdict: 'not-applicable' };
+  const known = hit.cli.known(opts.home);
+  if (!known.length) return { verdict: 'unknown', why: `cannot enumerate ${hit.cli.id} models on this machine` };
+  if (known.includes(hit.value)) return { verdict: 'ok', value: hit.value };
+  // A CONFIGURED MODEL IS A DEFAULT, NOT AN ALLOWLIST — and an audit was right to call the first
+  // version a false-refusal waiting to happen: an account may accept several models, so `o3` or
+  // `gpt-5.1-codex` are UNKNOWN here, not wrong, and must pass. What is knowably wrong is a NEAR MISS
+  // of the configured value, because that is a typo rather than a choice — and it is exactly what
+  // happened: `gpt-5.6` for `gpt-5.6-sol`, a truncation, 400 + exit 0, fifty minutes lost.
+  const nearMiss = known.find((k) => k.startsWith(hit.value) || hit.value.startsWith(k)
+    || k.replace(/[-._]/g, '') === hit.value.replace(/[-._]/g, ''));
+  if (!nearMiss) return { verdict: 'unknown', why: `${hit.value} is not this machine's configured model, but may still be valid for the account` };
+  return {
+    verdict: 'wrong',
+    nearMiss,
+    value: hit.value,
+    known,
+    reason:
+      `⛔ BLOCKED — "${hit.value}" is not a model this machine's ${hit.cli.id} accepts.\n`
+      + `  configured and proven to work: ${known.join(', ')}\n`
+      + `  source: ~/.codex/config.toml\n\n`
+      + 'Checked because an unverified identifier fails SILENTLY here: on 2026-08-13 `codex exec\n'
+      + '--model gpt-5.6` printed a 400 and EXITED 0 into a redirected file, and 50 minutes of a\n'
+      + 'long-running audit produced nothing. There was no exit code to catch. Use the name above,\n'
+      + 'or read the live source if you believe it is wrong — never retype one from memory.',
+  };
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  let payload = '';
+  try { payload = fs.readFileSync(0, 'utf8'); } catch { /* no stdin is not a refusal */ }
+  let command = '';
+  try { command = JSON.parse(payload)?.tool_input?.command ?? ''; } catch { /* malformed degrades to allow */ }
+  const r = check(command);
+  if (r.verdict !== 'wrong') process.exit(0);
+  process.stderr.write(`${r.reason}\n`);
+  process.exit(2);
+}

package/plugin/scripts/learn-capture.sh

@@ -15,6 +15,19 @@ set -uo pipefail
 # RUVNET_LEARNING_SCOPE so the two halves cannot disagree during one hook invocation.
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
 SCOPE="${RUVNET_LEARNING_SCOPE:-}"
+# CONFIGURED vs DEFAULTED, and this must be captured BEFORE the preferences fallback below.
+#
+# `project` is the DEFAULT scope, and `runtime-preferences.mjs --learning-scope` RESOLVES it —
+# measured 2026-08-19 against an empty config root, it returns "project", not "". So after the
+# fallback runs, an explicit opt-in and a bare default are indistinguishable. The first version of
+# this guard read SCOPE afterwards and was therefore always "configured", which let the
+# stranger-project mutation straight back in.
+#
+# The env var is the one signal that is unambiguously explicit: nothing sets it by default. A
+# project that opted in through the console instead is still covered by the `.swarm` clause below,
+# because adopting Ruflo's convention is itself the opt-in.
+SCOPE_CONFIGURED=0
+[ -n "$SCOPE" ] && SCOPE_CONFIGURED=1
 if [ -z "$SCOPE" ] && [ -f "$HERE/runtime-preferences.mjs" ] && command -v node >/dev/null 2>&1; then
   SCOPE=$(node "$HERE/runtime-preferences.mjs" --learning-scope 2>/dev/null) || SCOPE=""
 fi
@@ -122,8 +135,44 @@ SID="${SID//[^A-Za-z0-9_-]/}"           # a filename COMPONENT, never a path
 if [ "$SCOPE" = "user" ]; then
   DIR="$HOME/.cache/ruvnet-brain/learn"
 else
-  DIR="$PWD/.swarm/ruvnet-brain-learn"
+  # ISSUE #134 — THE SAME PROJECT ROOT THE READER COMPUTES, BY THE SAME RULE.
+  #
+  # This was bare `$PWD` while learn-flush.mjs:26 and health-repair.mjs:32 both resolve
+  # `RUVNET_BRAIN_PROJECT_DIR || cwd`. This hook is wired on PostToolUse, so it runs after EVERY tool
+  # call — and any command that leaves the shell below the project root (a test run, a build, any
+  # tooling that cd's) made the WRITER create a queue in a directory the READER never looks in. Those
+  # events are not misfiled, they are orphaned: nothing ever drains them.
+  #
+  # This is issue #104's residual. #104 fixed the two halves of the FLUSH to agree about which project
+  # they mean; the component that actually creates the queue was not brought along, so the invariant
+  # held for two of three participants and was violated by the one doing the writing. Same shape as
+  # ADR-066: a writer and a reader that disagree about the store make the recording theatre.
+  DIR="${RUVNET_BRAIN_PROJECT_DIR:-$PWD}/.swarm/ruvnet-brain-learn"
 fi
+# PROJECT SCOPE MEANS THE PROJECT MUST HAVE OPTED IN. In project scope $DIR sits under `.swarm`,
+# which is Ruflo's own convention and is created by `ruflo init` — so its PRESENCE is the project's
+# opt-in and its ABSENCE is a project that has not adopted the brain. This hook runs machine-wide on
+# every PostToolUse, so an unconditional mkdir planted `.swarm/` in EVERY repository the user opened.
+# Measured 2026-08-14 by the both-hosts conformance gate in a temp project with no git and no brain
+# artifacts; ADR-058 D5 — never touch what we do not own. User scope is unaffected: that queue lives
+# under the brain's OWN cache directory, which we do own and may create.
+# CREATE THE QUEUE ONLY WHERE THE PROJECT ACTUALLY OPTED IN.
+#
+# First attempt required an existing `.swarm`, which stopped the stranger-project mutation but ALSO
+# broke a legitimate first run: a project that explicitly sets RUVNET_LEARNING_SCOPE=project before
+# it has ever captured anything got nothing, and `learning-scope-policy` went red. Presence of
+# `.swarm` was the wrong discriminator — it answers "has Ruflo run here", not "did this project ask
+# for learning".
+#
+# The right one is whether the scope was CONFIGURED (env or runtime-preferences) rather than
+# inherited from the default. A stranger's repo sets neither, so nothing is created there; a project
+# that opted in gets its queue on the very first capture, `.swarm` or not. An existing `.swarm` is
+# still honoured on its own, because a repo already carrying Ruflo's convention has plainly adopted it.
+case "$DIR" in
+  */.swarm/*)
+    if [ "$SCOPE_CONFIGURED" != "1" ] && [ ! -d "$(dirname "$DIR")" ]; then exit 0; fi
+    ;;
+esac
 # Owner-only (0700 dir / 0600 file). This queue was 0644 inside a 0755 dir: on macOS every local
 # account is normally in `staff`, so any other user on a shared or corporate machine could read it.
 ( umask 077 && mkdir -p "$DIR" ) 2>/dev/null || exit 0

package/plugin/scripts/learn-flush.mjs

@@ -13,7 +13,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { readStdinBounded } from './hook-input.mjs';
-import { loadRuntimePreferences } from './runtime-preferences.mjs';
+import { learningScope, loadRuntimePreferences } from './runtime-preferences.mjs';
 import { resolveRuflo, RUFLO_MISSING } from './ruflo-bin.mjs';
 
 // ONE BOUNDED LINE ON STDERR. stderr because a SessionEnd hook's stdout is not surfaced, and bounded
@@ -24,10 +24,10 @@ const warn = (msg) => { try { process.stderr.write(`learn-flush: ${msg}\n`); } c
 
 const HOME = os.homedir();
 const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || process.cwd();
-const configuredScope = process.env.RUVNET_LEARNING_SCOPE
-  || loadRuntimePreferences({ cwd: PROJECT }).values.learningScope;
-const LEARNING_SCOPE = ['off', 'project', 'user'].includes(configuredScope)
-  ? configuredScope : 'project';
+// ISSUE #139 — this WRITER resolved scope correctly while two READERS hardcoded it, so they agreed
+// only by coincidence. The resolution moved into runtime-preferences.mjs and all three now call it;
+// a future scope is one edit, not three. Behaviour here is unchanged by design.
+const LEARNING_SCOPE = learningScope({ cwd: PROJECT });
 if (LEARNING_SCOPE === 'off') process.exit(0);
 
 // THE SESSION ID COMES OFF THE PAYLOAD, exactly as it does in learn-capture.sh (fixed 2026-07-27).

package/plugin/scripts/lesson-bridge.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * lesson-bridge.mjs — carry AgentDB's tagged lessons into the store lesson-gate already reads.
+ *
+ * WHY: two stores of "what we learned" existed with nothing connecting them. The full measurement,
+ * the trust-boundary reasoning, and what it cost to learn are in docs/adr/0066 — not repeated here.
+ *
+ * THE ONE RULE THAT SURPRISES PEOPLE: the trigger lives as a TAG ON THE AGENTDB ROW, never inferred
+ * from the text. An untagged lesson does not bridge and is reported by name. Guessing which moment a
+ * lesson belongs to is the keyword-classifier mistake ADR-065 recorded in its own numbers.
+ *
+ * Bridged lessons are origin:imported, so makeLesson structurally forbids them from blocking work.
+ * Fail-safe both ways: no store → no-op; zero candidates → REFUSES to write (a read failure must not
+ * silently strip installed lessons; removal is explicit via --prune).
+ *
+ *   node plugin/scripts/lesson-bridge.mjs            # report what would bridge, and what is untagged
+ *   node plugin/scripts/lesson-bridge.mjs --apply    # merge (locked, atomic, backed up)
+ *   node plugin/scripts/lesson-bridge.mjs --json     # machine-readable
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { makeLesson, updateLessons, loadLessons, ENFORCEMENT, ORIGIN, STATUS, TRIGGERS } from './lesson-store.mjs';
+
+/** Every bridged lesson id starts with this. It is how a merge knows which rows it owns. */
+export const BRIDGE_PREFIX = 'G-';
+/** Project-tier ids. Distinct prefix so a merge can own both sets without confusing them. */
+export const PROJECT_PREFIX = 'P-';
+/** Any id this bridge owns and may replace wholesale on the next run. */
+export const isBridged = (id) => String(id).startsWith(BRIDGE_PREFIX) || String(id).startsWith(PROJECT_PREFIX);
+
+const GLOBAL_DB = process.env.RUVNET_GLOBAL_MEMORY_DB
+  || path.join(os.homedir(), '.claude', 'global-memory', '.swarm', 'memory.db');
+const GLOBAL_NS = process.env.RUVNET_GLOBAL_MEMORY_NS || 'global';
+
+/**
+ * THE PROJECT TIER (ADR-067). Global memory holds lessons that already won twice; a project's own
+ * `.swarm/memory.db` holds the ones learned HERE. Both are knowledge with no way to speak, and the
+ * bridge was reading only one of them.
+ *
+ * The difference that matters is SCOPE, and lesson-gate already enforces it: a lesson carrying
+ * `projects: [name]` speaks only in that project, while an unscoped one speaks anywhere. So a global
+ * row bridges unscoped and a project row bridges scoped to its own directory — no new mechanism, the
+ * existing `isHome` check does the work. Without that, a ruvnet-brain lesson would interrupt someone
+ * working in a different repo, which is precisely the breakage recorded in lesson-gate.mjs on
+ * 2026-07-22: "I've got other repos that are using this thing, and they're breaking."
+ */
+const PROJECT_DB = process.env.RUVNET_PROJECT_MEMORY_DB
+  || path.join(process.cwd(), '.swarm', 'memory.db');
+
+const TRIGGER_KEYS = new Set(Object.values(TRIGGERS).map((t) => t.key));
+const ENFORCEMENTS = new Set(Object.values(ENFORCEMENT));
+
+/** A local, one-shot read query. Generous for a wedged lock; still a hard ceiling on a hook path. */
+const SQLITE_CLI_TIMEOUT_MS = Number(process.env.RUVNET_SQLITE_CLI_TIMEOUT_MS) || 5_000;
+
+// ── Reading the store ────────────────────────────────────────────────────────────────────────────
+// node:sqlite is preferred: in-process, no shell, exact bytes, no quoting hazard on multi-paragraph
+// lesson text. It is stable on Node 22.5+/24 but absent on older runtimes, so the sqlite3 CLI is the
+// fallback — and if neither exists this returns [] and the whole bridge becomes a no-op rather than
+// an error. A tool that fails loudly on a machine that simply has no global memory would be noise.
+const SQL = `SELECT key, content, COALESCE(tags,'') AS tags, COALESCE(provenance_type,'unknown') AS provenance,
+             COALESCE(updated_at, created_at) AS ts
+             FROM memory_entries WHERE namespace = ? ORDER BY key`;
+
+export function readGlobalRows(dbPath = GLOBAL_DB, ns = GLOBAL_NS) {
+  if (!fs.existsSync(dbPath)) return [];
+  try {
+    const { DatabaseSync } = require$('node:sqlite');
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try { return db.prepare(SQL).all(ns); } finally { db.close(); }
+  } catch { /* fall through to the CLI */ }
+  try {
+    // Unbounded: an execFileSync with no `timeout` blocks the ENTIRE main thread on a synchronous
+    // syscall, which stalls vitest's own async testTimeout too (it can't fire without a free event
+    // loop) — measured as two consecutive 6h GitHub Actions job-ceiling kills, no error, no test
+    // name, after this file's own tests started using this path (2026-08-10). A busy/locked
+    // sqlite3 CLI, or one waiting on a lock this process already holds via node:sqlite above, must
+    // die on its own schedule, not the host's.
+    const out = execFileSync('sqlite3', ['-json', dbPath, SQL.replace('?', `'${ns.replace(/'/g, "''")}'`)],
+      { encoding: 'utf8', maxBuffer: 1 << 24, timeout: SQLITE_CLI_TIMEOUT_MS });
+    const rows = JSON.parse(out || '[]');
+    return Array.isArray(rows) ? rows : [];
+  } catch { return []; }
+}
+/**
+ * Every `lesson*` row in a store, across ALL namespaces — the project tier scatters them (`lessons`,
+ * the project dirname, `default`), and enumerating namespaces by hand is the restatement this repo
+ * keeps paying for. The key prefix is the selector, exactly as the promotion tooling already uses it.
+ */
+export function readProjectRows(dbPath = PROJECT_DB) {
+  const sql = `SELECT key, content, COALESCE(tags,'') AS tags, COALESCE(provenance_type,'unknown') AS provenance,
+               COALESCE(updated_at, created_at) AS ts
+               FROM memory_entries WHERE key LIKE 'lesson%' ORDER BY key`;
+  if (!fs.existsSync(dbPath)) return [];
+  try {
+    const { DatabaseSync } = require$('node:sqlite');
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try { return db.prepare(sql).all(); } finally { db.close(); }
+  } catch { /* fall through */ }
+  try {
+    const out = execFileSync('sqlite3', ['-json', dbPath, sql],
+      { encoding: 'utf8', maxBuffer: 1 << 24, timeout: SQLITE_CLI_TIMEOUT_MS });
+    const rows = JSON.parse(out || '[]');
+    return Array.isArray(rows) ? rows : [];
+  } catch { return []; }
+}
+
+/** Indirection so a missing node:sqlite is a caught throw rather than a module-load crash. */
+function require$(id) { return process.getBuiltinModule ? process.getBuiltinModule(id) : null; }
+
+// ── Row → lesson ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `trigger:write-code` tags → { trigger: 'write-code', … }
+ *
+ * BOTH WIRE SHAPES, and the first one is the one that matters. `ruflo memory store --tags "a,b"`
+ * accepts a comma string on the command line and PERSISTS a JSON array:
+ *
+ *     ["trigger:write-code","enforce:inject","severity:high"]
+ *
+ * Measured 2026-08-10, after this parser was written to the comma form and the bridge read 0 of 30
+ * freshly-tagged rows while the CLI reported success on every one. The test fixture had been built to
+ * the same assumption, so it would have stayed green while the product read nothing — which is
+ * `lesson-fixture-cannot-falsify-its-own-choice` happening to the file that exists to carry that
+ * lesson. The fixture now writes what the CLI writes.
+ */
+export function parseTags(tags) {
+  const raw = String(tags || '').trim();
+  let parts;
+  try {
+    const parsed = JSON.parse(raw);
+    parts = Array.isArray(parsed) ? parsed.map(String) : null;
+  } catch { parts = null; }
+  if (!parts) parts = raw.split(',');
+  const out = {};
+  for (const part of parts) {
+    const [k, v] = String(part).split(':').map((s) => (s || '').trim());
+    if (k && v) out[k.toLowerCase()] = v.toLowerCase();
+  }
+  return out;
+}
+
+/**
+ * The statement is DERIVED from the row, never restated beside it (ADR-065). Global lessons are
+ * written headline-first in imperative caps, so the first sentence is the instruction; the rest is
+ * the evidence that earned it, which belongs in the store, not in a nudge with a 1200-char budget.
+ */
+export function statementOf(content) {
+  const text = String(content || '').replace(/\s+/g, ' ').trim();
+  const stop = text.search(/(?<=[.!?])\s(?=[A-Z(])/);
+  const first = stop > 20 ? text.slice(0, stop) : text;
+  return first.length > 300 ? `${first.slice(0, 297).trimEnd()}…` : first;
+}
+
+/** `lesson-tests-that-cannot-fail-on-broken-code` → `G-tests-that-cannot-fail-on-broken-code` */
+export const idFor = (key) => BRIDGE_PREFIX + String(key).replace(/^lesson-/, '');
+
+/**
+ * Build a lesson from one AgentDB row, or explain in one line why it cannot be built.
+ * Returns { lesson } or { skip: '<reason>' } — never throws, so one bad row cannot stop the bridge.
+ */
+export function lessonFromRow(row, { projects = [], idPrefix = BRIDGE_PREFIX, source = 'global' } = {}) {
+  const key = String(row?.key || '');
+  if (!key) return { skip: 'row has no key' };
+  const tags = parseTags(row.tags);
+  if (!tags.trigger) return { skip: 'no trigger: tag — add one to bridge it' };
+  if (!TRIGGER_KEYS.has(tags.trigger)) {
+    return { skip: `unknown trigger "${tags.trigger}" (expected one of: ${[...TRIGGER_KEYS].join(', ')})` };
+  }
+  // `checklist` is the default because it is the strongest level that is honest for imported
+  // content: it reaches the model at the moment, and it refuses nothing.
+  const enforcement = ENFORCEMENTS.has(tags.enforce) ? tags.enforce : ENFORCEMENT.CHECKLIST;
+  // Typed provenance is rUv's own field (ADR-323). `user_claim` is the only value that means a human
+  // said it; everything else — agent_output, tool_result, system_observation, unknown — is imported.
+  const origin = row.provenance === 'user_claim' ? ORIGIN.USER_STATED : ORIGIN.IMPORTED;
+  const when = Number(row.ts) > 0 ? new Date(Number(row.ts)).toISOString().slice(0, 10) : 'unknown date';
+  try {
+    return {
+      lesson: makeLesson({
+        id: idPrefix + String(key).replace(/^lesson-/, ''),
+        statement: statementOf(row.content),
+        trigger: tags.trigger,
+        enforcement,
+        // Real provenance, not a sentence invented to satisfy a non-empty check: where the row is and
+        // when it was last written. Anyone can go read it.
+        evidence: [`AgentDB ${source}/${key} — ${source === 'global' ? 'machine-wide' : 'project'} lesson store, recorded ${when}`],
+        // SCOPE IS THE WHOLE DIFFERENCE BETWEEN THE TIERS. Empty = "applies anywhere by
+        // declaration" (Tier 1 earned that by winning twice in projects that could not see each
+        // other). A project row carries its own directory, so lesson-gate's isHome() keeps it home.
+        projects,
+        // NOT invented. Repetition is only used to order lessons of equal force, and a bridged lesson
+        // has no per-project repeat count to honestly claim — so it sorts behind the user's directly
+        // taught native lessons, which is the correct precedence.
+        repeatCount: 0,
+        severity: tags.severity === 'high' ? 'high' : 'normal',
+        origin,
+        // A TAG IS NOT A HUMAN ACT. This said `STATUS.RATIFIED`, commented "the tag on the row IS the
+        // human act of ratification" — but `ruflo memory store --tags` runs in every session, from
+        // hooks and from the model itself. I wrote a tagged row by hand on 2026-08-13, which under
+        // the old line would have RATIFIED MY OWN LESSON. Combined with nightly-wrapper.sh running
+        // `lesson-bridge --apply` unattended, any process able to write a `lesson-*` row could inject
+        // standing instructions into every later session, stamped as ratified policy — the injection
+        // path ADR-066/067 closed at the front door, left open on a timer at the side.
+        //
+        // The distinction was already computed eight lines up. rUv's typed provenance (ADR-323,
+        // v3/@claude-flow/cli/src/commands/memory.ts) marks `user_claim` as the one value meaning a
+        // human said it; `origin` honoured that and `status` ignored it. Both now read the same fact.
+        // Anything else arrives CANDIDATE, which lessonsFor() will not deliver and makeLesson() will
+        // not let block.
+        status: origin === ORIGIN.USER_STATED ? STATUS.RATIFIED : STATUS.CANDIDATE,
+        ratifiedBy: origin === ORIGIN.USER_STATED ? `agentdb-provenance:user_claim ${source}/${key}` : null,
+      }),
+    };
+  } catch (e) { return { skip: String(e?.message || e).slice(0, 160) }; }
+}
+
+// ── Merge ────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Replace every bridged row with the current set; leave every other row byte-identical.
+ * Pure, so the test can assert the merge without touching a real store.
+ */
+export function mergeBridged(existing, bridged) {
+  return [...existing.filter((l) => !isBridged(l.id)), ...bridged];
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+/**
+ * "Am I the entrypoint?" — and it must NEVER be able to crash the caller that merely imported this.
+ *
+ * The first version had both Windows defects at once, and CI found them: `new URL(import.meta.url)
+ * .pathname` yields `/D:/…` on Windows, which `path`/`fs` then mangle into `D:\D:` — the exact
+ * `ENOENT: lstat 'D:\D:'` that failed this module's whole test SUITE at import time. And
+ * `realpathSync` THROWS on anything that does not resolve, which under vitest `process.argv[1]`
+ * does not.
+ *
+ * `fileURLToPath` is the fix for the first (hook-shim.mjs learned this in issue #38: "on Windows,
+ * pathname yields '/C:/…' which path.resolve mangles into 'C:\\C:\\…'"), and try/catch for the
+ * second. Both were ALREADY correct in scripts/selfcheck.mjs:660 and plugin/scripts/hook-input.mjs
+ * — the pattern existed in this repo and I wrote a new one instead of reading it.
+ */
+function isMain() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch { return false; }
+}
+if (isMain()) {
+  const apply = argv.includes('--apply');
+  const prune = argv.includes('--prune');
+  const json = argv.includes('--json');
+
+  const here = path.basename(process.cwd());
+  const sources = [
+    { name: 'global', rows: readGlobalRows(), opts: { projects: [], idPrefix: BRIDGE_PREFIX, source: 'global' } },
+    // Scoped to THIS project by name, so lesson-gate's isHome() keeps it from speaking elsewhere.
+    { name: `project:${here}`, rows: readProjectRows(), opts: { projects: [here], idPrefix: PROJECT_PREFIX, source: `project:${here}` } },
+  ];
+  const bridged = [];
+  const skipped = [];
+  const seen = new Set();
+  for (const src of sources) {
+    for (const row of src.rows) {
+      const r = lessonFromRow(row, src.opts);
+      if (!r.lesson) { skipped.push({ key: `${src.name}/${row.key}`, why: r.skip }); continue; }
+      // A lesson promoted from a project to global exists in BOTH stores. The global copy wins: it
+      // is the one that earned the right to travel, and surfacing the same correction twice teaches
+      // the reader to skim (lesson-gate's own dedupe reasoning, applied across sources).
+      const slug = String(row.key).replace(/^lesson-/, '');
+      if (seen.has(slug)) { skipped.push({ key: `${src.name}/${row.key}`, why: 'already bridged from a higher tier' }); continue; }
+      seen.add(slug);
+      bridged.push(r.lesson);
+    }
+  }
+
+  const alreadyBridged = loadLessons().filter((l) => isBridged(l.id)).length;
+  // THE ANTI-WIPE GUARD. A read failure (store moved, sqlite missing, permissions) produces zero
+  // candidates, and without this a "successful" apply would quietly delete every lesson the bridge
+  // had previously installed. Nothing about that would look like an error.
+  const wouldWipe = bridged.length === 0 && alreadyBridged > 0;
+
+  if (json) {
+    console.log(JSON.stringify({
+      sources: sources.map((s) => ({ name: s.name, rows: s.rows.length })),
+      bridged: bridged.map((l) => ({ id: l.id, trigger: l.trigger, enforcement: l.enforcement, origin: l.origin })),
+      untagged: skipped, alreadyBridged, wouldWipe, applied: false,
+    }, null, 2));
+    process.exit(0);
+  }
+
+  console.log('\n  lesson-bridge');
+  for (const s of sources) console.log(`    ${s.name.padEnd(24)} ${s.rows.length} row(s)`);
+  console.log(`  ${bridged.length} carry a trigger tag.\n`);
+  const byTrigger = new Map();
+  for (const l of bridged) byTrigger.set(l.trigger, [...(byTrigger.get(l.trigger) || []), l]);
+  for (const [trigger, ls] of [...byTrigger].sort()) {
+    console.log(`  ▸ ${trigger}`);
+    for (const l of ls) console.log(`      ${l.enforcement.padEnd(9)} ${l.id}`);
+  }
+  // BRIDGED BUT NOT DELIVERED IS ITS OWN STATE, AND IT MUST BE LOUD. A candidate is merged into the
+  // store and then filtered out by lessonsFor(), so counting it under "bridged" would report 43
+  // lessons in force while 20 of them never fire — the same lie as the flywheel's "configured"
+  // reported as "operational". These are the rows the model wrote about itself (`agent_output`);
+  // self-ratification is the hole, but going quiet about it would be the bigger one.
+  const candidates = bridged.filter((l) => l.status === STATUS.CANDIDATE);
+  if (candidates.length) {
+    console.log(`\n  BRIDGED BUT NOT DELIVERED (${candidates.length}) — provenance is not user_claim, so`);
+    console.log('  these merge as CANDIDATES: lessonsFor() will not surface them and they cannot block.');
+    for (const l of candidates) console.log(`      ${l.trigger.padEnd(24)} ${l.id}`);
+    console.log('\n      To put one in force, the HUMAN restates it — a tag the model can write is not');
+    console.log('      a human act, which is why these are held:');
+    console.log(`      ruflo memory store --path ${GLOBAL_DB} -n ${GLOBAL_NS} \\`);
+    console.log('        -k "<key>" --value "<text>" --tags "trigger:<key>,enforce:checklist" --provenance user_claim');
+  }
+
+  if (skipped.length) {
+    // NAMED, never a count. A list that says "12 skipped" and stops is the truncation that reads as
+    // completeness — the exact failure Rule 23 was written about.
+    console.log(`\n  NOT bridged (${skipped.length}) — each needs a trigger tag on its AgentDB row:`);
+    for (const s of skipped) console.log(`      ${s.key.padEnd(48)} ${s.why}`);
+    console.log(`\n      ruflo memory store --path ${GLOBAL_DB} -n ${GLOBAL_NS} \\`);
+    console.log('        -k "<key>" --value "<text>" --tags "trigger:<key>,enforce:checklist" --provenance user_claim');
+  }
+
+  if (!apply) {
+    console.log(`\n  read-only. Re-run with --apply to merge ${bridged.length} lesson(s) into the store.\n`);
+    process.exit(0);
+  }
+  if (wouldWipe && !prune) {
+    console.error(`\n  REFUSING to apply: 0 lessons readable but ${alreadyBridged} bridged lesson(s) are already`);
+    console.error('  installed. That is a read failure, not an empty store. Pass --prune if removal is intended.\n');
+    process.exit(1);
+  }
+  const before = loadLessons().length;
+  updateLessons((current) => mergeBridged(current, bridged));
+  const after = loadLessons().length;
+  console.log(`\n  applied: store ${before} → ${after} lesson(s) (${bridged.length} bridged, ${after - bridged.length} native)\n`);
+}

package/plugin/scripts/lesson-hooks.sh

@@ -183,6 +183,32 @@ fi
 if [ "$EVENT" = "PreToolUse-bash" ] && [ -f "$HOOK_INPUT_JS" ]; then
   CMD=$(printf '%s' "$INPUT" | node "$HOOK_INPUT_JS" command 2>/dev/null) || CMD=""
   ARGS+=(--command "$CMD")
+
+  # SHIP RIDES ON THE BASH PAYLOAD, BECAUSE NOTHING EVER SENDS "PreToolUse-push".
+  #
+  # The `PreToolUse-push) TRIGGERS="ship"` branch above has never executed. hooks.json emits only
+  # `unprompted-speech UserPromptSubmit`, and decision-gate.mjs maps EVERY PreToolUse to exactly
+  # `PreToolUse-bash` or `PreToolUse-write` — so `git push` has always arrived here as
+  # `mutate-machine`, never as `ship`. Measured 2026-08-13: FIVE ratified ship lessons in the live
+  # store had therefore never fired once, among them `G-remote-ci-gates-shipping` and
+  # `G-test-the-artifact-not-the-checkout` — the two that would have spoken up before I shipped a
+  # test that broke windows-unit and red-lit someone else's dependabot PR.
+  #
+  # Worse, wired-check's Check C greps THIS FILE's case labels to decide which triggers are wired, so
+  # it read "ship" off the dead branch and reported it green — an audit that cannot fail on the exact
+  # defect class it was written for. The dispatcher is the truth-maker for what fires; a case label
+  # nobody sends is not a wire.
+  # THE SAME PATTERNS AS degradation-watch.mjs DEPENDENT_COMMANDS, and a test asserts they agree.
+  # Two audits noted these two definitions of "is this a ship?" shipped already disagreeing on day
+  # one — one fact restated in two files, which is the defect this repo keeps paying for. They also
+  # caught both directions of the original glob being wrong: `git -C <abs> push` (the form an agent
+  # with absolute paths writes) matched NOTHING, while `grep -n "npm publish" docs/` matched, so
+  # reading ABOUT shipping counted as shipping. Quoted regions are stripped first because the
+  # truth-maker is what will EXECUTE — a commit message is not a command.
+  CMD_EXEC=$(printf '%s' "$CMD" | sed -e 's/"[^"]*"/ /g' -e "s/'[^']*'/ /g")
+  if printf '%s' "$CMD_EXEC" | grep -qE '\bgit\b[^|;&]*\bpush\b|\b(npm|yarn|pnpm) publish\b|\bgh release create\b|release\.mjs'; then
+    ARGS+=(--trigger ship)
+  fi
 fi
 
 # A hard timeout, because this runs on every matching event and must never add perceptible latency.