ruvnet-brain 4.0.1 → 4.0.2

package/scripts/goal-match.mjs

@@ -0,0 +1,398 @@
+// goal-match.mjs — L4 ANTICIPATORY: infer the GOAL, name the capability that serves it, and
+// otherwise SAY NOTHING.
+//
+// PURE. No I/O, no network, no filesystem, no process.exit — same discipline as console-engine.mjs,
+// and for the same reason: this file only DECIDES. It is a total function of (prompt, capabilities),
+// so it is testable by table and can never, by construction, change the machine.
+//
+// ── THE CONSTRAINT THAT IS THE ENTIRE DESIGN ────────────────────────────────────────────────────
+//
+// ADR-027 (the constraint that keeps it honest) and ADR-028 (anti-goals) say the same thing twice,
+// because it is the failure mode that kills this feature:
+//
+//   "This is goal-aware capability matching, NOT evangelism. Recommending a tool to someone whose
+//    problem it does not fit is the same failure in the opposite direction, and it is the FASTER
+//    way to destroy trust, because it is indistinguishable from salesmanship."
+//
+// ADR-028's metric table makes it numeric and non-negotiable: false-alarm rate target is **0**,
+// annotated "one false alarm costs more trust than ten true ones earn." Recall's target is 0.80 —
+// deliberately lower. **The asymmetry is the specification.** This module is therefore built to
+// return [] and treats every match as something it must earn. If you are ever choosing between a
+// miss and a false positive here, take the miss; that choice is already made, in the ADR, on
+// purpose.
+//
+// ── WHY KEYWORD MATCHING ALONE WOULD SHIP A LIAR ────────────────────────────────────────────────
+//
+// Look at the actual vocabulary of the eleven capabilities in capability-registry.auditAll():
+// memory, hooks, routing, sessions, context, patterns, gates, cache, nightly, learning. **Every
+// single one of those words is a homonym for something in ordinary software work**, and the other
+// meaning is far more common in a developer's prompt:
+//
+//     "fix the memory leak"        → C heap, not AgentDB
+//     "my useEffect hook fires 2x" → React, not ruflo hooks
+//     "set up routing for /admin"  → a router, not cheap-model routing
+//     "the session cookie expires" → HTTP, not a Claude session
+//     "our nightly build failed"   → CI, not the KB refresh
+//     "the model isn't learning"   → gradient descent, not workflow learning
+//
+// A bag-of-words detector fires on all six and is wrong all six times. That is not a hypothetical:
+// this project already shipped exactly this bug in a different costume — a detector that read a
+// CLI's human-readable table and announced "26 hooks off" while the learner held 457 trajectories.
+// It matched a surface pattern and reported the match as a fact.
+//
+// So a goal here requires TWO INDEPENDENT KEYS, and one alone is never enough:
+//
+//   1. INTENT  — the prompt describes the problem the capability actually solves.
+//   2. SUBJECT — the thing being discussed is the user's AI/agent workflow, not their application.
+//
+// plus a VETO list that only ever contains disambiguators for words this file genuinely uses. A
+// veto for a word we never match on would be superstition, not engineering.
+//
+// The two-key rule is what makes "fix the memory leak in my C++ parser" silent: INTENT plausibly
+// matches, SUBJECT does not match at all, and the veto catches it a second time. Belt and braces,
+// because the cost of being wrong here is measured in trust rather than in a stack trace.
+
+/**
+ * SUBJECT — evidence that the conversation is about the user's AI assistant and how it works,
+ * rather than about code the user is writing.
+ *
+ * This is the load-bearing half of the two-key rule. Every entry names the ASSISTANT or the
+ * ASSISTANT'S WORKFLOW explicitly. Nothing here can be satisfied by a prompt about a web app, which
+ * is the property that produces silence on the negative table.
+ */
+const SUBJECT = Object.freeze([
+  /\bclaude\b/,
+  /\b(my|the|this) (ai|assistant|agent|llm|copilot)\b/,
+  /\b(coding|ai) (agent|assistant)\b/,
+  /\bcursor\b/,
+  /\bruflo\b/, /\bruvnet\b/, /\bruvector\b/, /\bagentdb\b/, /\bmcp\b/,
+  /\bclaude[ .-]?md\b/,
+  /\b(every|each|new|another) (chat|conversation|session)\b/,
+  /\bacross (sessions|chats|conversations|projects)\b/,
+  /\bcontext window\b/,
+  /\bcompact(s|ed|ion|ing)?\b/,
+  /\b(my|our) (workflow|setup|harness|stack|tooling)\b/,
+  /\bit keeps\b/,          // "it keeps forgetting" — the assistant, in the user's own voice
+  /\bit forgets\b/,
+  /\bit never\b/,
+  /\bit doesn'?t\b/,
+]);
+
+/**
+ * GLOBAL_VETO — the prompt is about building or operating SOFTWARE, so our whole vocabulary is
+ * being used in its other sense.
+ *
+ * DELIBERATELY OVER-BROAD. Some of these ("deploy", "production") could appear in a prompt that was
+ * genuinely about the user's AI workflow, and vetoing it costs us a true positive. That trade is
+ * made knowingly and in one direction only, per ADR-028: recall 0.80, false alarms 0. A miss is
+ * invisible. A false alarm reads as salesmanship, and you only get to do that once.
+ */
+const GLOBAL_VETO = Object.freeze([
+  // — the assistant's words used as an application's words —
+  /\bmemory leak\b/, /\bheap\b/, /\bmalloc\b/, /\bvalgrind\b/, /\bgarbage collect/, /\boom\b/, /\bram\b/,
+  /\buse(effect|state|context|memo|callback|ref)\b/, /\breact hook/, /\bcustom hook/, /\blifecycle hook/,
+  /\b(react|next|vue|express|api) rout/, /\brouter\b/, /\b\/api\//, /\bendpoint\b/, /\bmiddleware\b/,
+  /\bsession (cookie|token|id|storage)\b/, /\bjwt\b/, /\bexpress-session\b/, /\bcookie\b/,
+  // Auth owns the word "session" at least as strongly as we do. These began as a veto private to
+  // the losing-work goal, and a test proved that scoping WRONG: suppressing one goal simply handed
+  // "forgets the login state and starts over from scratch" to a different goal, which recommended
+  // the learning capabilities instead. A prompt about authentication is application work outright,
+  // so the disambiguation belongs here, once, globally — not per-goal, where it silences one
+  // claimant and leaves ten others holding the same bad match.
+  /\blogin\b/, /\bauth(entication)?\b/, /\bsign ?(in|out)\b/, /\blogged (in|out)\b/,
+  /\bnightly (build|release)\b/, /\bci (pipeline|gate|job)\b/, /\bgithub actions\b/, /\bquality gate\b/,
+  /\bcache-control\b/, /\bhttp cache\b/, /\bcdn\b/, /\bredis\b/, /\bmemcached\b/,
+  /\bnpm outdated\b/, /\bdependabot\b/, /\bdependenc(y|ies)\b/,
+  /\bregex(p)? pattern\b/, /\bdesign pattern\b/,
+  // — machine learning, which owns "learn", "train", "model" and "pattern" outright —
+  /\btraining (loss|data|set)\b/, /\boverfit/, /\bepochs?\b/, /\bgradient\b/, /\bhyperparameter/,
+  /\bpytorch\b/, /\btensorflow\b/, /\bneural net/, /\bdataset\b/, /\bfine-?tun/,
+  // — building AGAINST an AI API is app work, not workflow work; "claude" appears in both —
+  /\bsdk\b/, /\bapi key\b/, /\brate limit/, /\b429\b/, /\bmy app\b/, /\bproduction\b/,
+  /\bend users\b/, /\bcustomers\b/, /\bdeploy(ing|ment)?\b/,
+]);
+
+/**
+ * GOALS — the closed taxonomy.
+ *
+ * EVERY goal here is reverse-engineered from a real capability's own `whatItBuysYou` string in
+ * capability-registry.auditAll(). None was invented from a sense of what would be nice to detect.
+ * That direction of derivation is the point: a goal no shipped capability serves is a goal whose
+ * only possible outcome is a recommendation we cannot fulfil, which is the salesmanship failure
+ * arriving by a side door.
+ *
+ * `serves` holds capability KEYS, not labels — labels are prose for humans and drift; keys are the
+ * registry's identity.
+ */
+export const GOALS = Object.freeze([
+  {
+    id: 'reteaching-every-project',
+    because: 'You are re-teaching the same rule in project after project',
+    serves: ['cross-project-lessons'],
+    intent: [
+      /\bre-?(explain|teach|state|specify)/,
+      /\b(every|each|another|a new) (new )?(project|repo|repository|codebase)\b/,
+      /\bsame (rule|standard|convention|instruction|correction|preference|guideline)/,
+      /\bkeep (telling|reminding|explaining)/,
+      /\b(over and over|again and again)\b/,
+      /\bproject by project\b/,
+    ],
+  },
+  {
+    id: 'corrections-not-obeyed',
+    because: 'You are correcting the same behaviour more than once',
+    serves: ['lessons-in-force'],
+    intent: [
+      /\bignor(es|ing|ed) (my|the|these)\b/,
+      /\balready (told|asked|corrected)\b/,
+      /\bsame mistake\b/,
+      /\bkeeps? (doing|making|repeating)\b/,
+      /\b(won'?t|doesn'?t|does not) (follow|listen|respect|obey)\b/,
+      /\bcorrected (it|this|that) (again|twice|three times|\d+ times)\b/,
+    ],
+  },
+  {
+    id: 'losing-work-between-sessions',
+    because: 'Work you established in one session is not surviving into the next',
+    serves: ['session-capture'],
+    intent: [
+      /\bforget(s|ting)?\b/,
+      /\bdoesn'?t remember\b/,
+      /\blos(e|es|ing|t) (the |all )?(context|thread|history|everything)\b/,
+      /\bstart(s|ing)? (over|from scratch)\b/,
+      /\bafter (a |the )?(compact|restart)/,
+      /\bwhen the (session|conversation) ends\b/,
+    ],
+  },
+  {
+    id: 'spend-too-high',
+    because: 'You are paying top-tier model prices for work that does not need them',
+    serves: ['cheap-model-routing'],
+    intent: [
+      /\b(bill|costs?|spend(ing)?|expensive|pricey)\b/,
+      /\btoken (spend|usage|burn)\b/,
+      /\bcheaper model\b/,
+      /\bsave money\b/,
+      /\bburning (through )?(credits|tokens|cash)\b/,
+      /\bhow much (am i|i'?m) (paying|spending)\b/,
+    ],
+  },
+  {
+    id: 'notes-that-teach-nothing',
+    because: 'You have accumulated notes and history that are never actually reused',
+    serves: ['memory-distillation'],
+    intent: [
+      /\bdistill/,
+      /\breusable patterns?\b/,
+      /\bnever (recalls?|reuses?|surfaces?)\b/,
+      /\b(notes|memories|decisions) (are )?(just )?(sitting|piling|pile)/,
+      /\bdoesn'?t (use|recall|remember) (my|the|past|previous|old)\b/,
+      /\bpast (sessions|work|decisions|notes)\b/,
+    ],
+  },
+  {
+    id: 'resolving-the-same-problem',
+    because: 'You are solving the same problem from scratch instead of building on what worked',
+    serves: ['learning-hooks', 'workflow-pattern-learning'],
+    intent: [
+      /\bsolv(e|es|ed|ing) the same\b/,
+      /\bfrom scratch (every|each)\b/,
+      /\b(doesn'?t|does not|never) (learn|improve|get better)\b/,
+      /\bsame (problem|approach|bug|issue) (again|every)\b/,
+      /\breinvent/,
+      /\bwhat (worked|we did) last time\b/,
+    ],
+  },
+  {
+    id: 'catching-bad-writes-in-review',
+    because: 'You are catching in review what should have been refused at write time',
+    serves: ['write-gates'],
+    intent: [
+      /\bcatch(ing)? (it|them|this|that) in review\b/,
+      /\b(stop|prevent|block) (it|claude|the agent|the ai) (from )?writ/,
+      /\bkeeps? writing\b/,
+      /\bguard ?rails?\b/,
+      /\benforce (a|my|our|the) (rule|standard|convention|policy)\b/,
+      /\bshould have (been )?(refused|blocked|stopped)\b/,
+    ],
+  },
+  {
+    id: 'needs-an-external-service',
+    because: 'You want your AI to reach a service it currently cannot see',
+    serves: ['mcp-servers'],
+    intent: [
+      /\bconnect (claude|it|the ai|the agent) to\b/,
+      /\bhook (it|claude) up to\b/,
+      /\b(access|read|see) my (notion|gmail|email|calendar|drive|slack|linear|jira|figma|notes)\b/,
+      /\bcan'?t (see|reach|access) (my|our)\b/,
+      /\bgive (it|claude) access to\b/,
+    ],
+  },
+  {
+    id: 'knowledge-going-stale',
+    because: 'What your AI knows about your tools is drifting out of date',
+    serves: ['nightly-refresh'],
+    intent: [
+      /\b(stale|outdated|out of date)\b/,
+      /\bdoesn'?t know about the (new|latest)\b/,
+      /\bold version of\b/,
+      /\bknowledge ?base\b/,
+      /\bkeeps? (citing|using) the old\b/,
+    ],
+  },
+  {
+    id: 'tuning-the-harness-itself',
+    because: 'You are trying to work out which set of rules actually performs better',
+    serves: ['harness-evolution'],
+    intent: [
+      /\bimprove (my|the) (prompt|rules|instructions|harness|setup)\b/,
+      /\bwhich (prompt|rule|policy|version) (works|performs) better\b/,
+      /\ba\/b test/,
+      /\btune (my|the) (rules|instructions|prompt)\b/,
+      /\bmeasure (which|whether) .{0,20}(prompt|rule)/,
+    ],
+  },
+]);
+
+/**
+ * The floor, and the reason it sits where it does.
+ *
+ * BASE is deliberately BELOW the floor. That single fact encodes the rule that matters: one intent
+ * cue plus one subject cue scores 0.55 and is therefore SILENT. A goal must be CORROBORATED — a
+ * second intent cue or a second subject cue — before this module will say anything at all.
+ *
+ * One cue is a coincidence. Two is a statement.
+ */
+export const CONFIDENCE_FLOOR = 0.6;
+const BASE = 0.55;
+const PER_EXTRA_CUE = 0.12;
+const MAX_EXTRA_CUES = 2;
+
+/**
+ * An 'unknown' capability is discounted, and this is the honesty rule from capability-registry's own
+ * header made arithmetic: "'unknown' is a first-class state, and it outranks 'off' every single time
+ * a probe could not run."
+ *
+ * We do not KNOW an unknown capability is dormant. Surfacing one is a guess about the machine on top
+ * of a guess about the goal, so it must clear a higher bar of evidence — 0.85 pushes the minimum
+ * corroborated score (0.67) back below the floor, meaning an unknown capability needs strictly more
+ * than an 'off' one before it may be named. The `why` string never calls it "off" either.
+ */
+const UNKNOWN_DISCOUNT = 0.85;
+
+/**
+ * At most two. The nudge principle ("correct, clear, confident, proactive, deferential, never
+ * pushy") does not survive a bulleted list of five things the user should turn on — that reads as a
+ * pitch no matter how each line is worded. Anticipation that dumps its whole inventory is evangelism
+ * with better targeting.
+ */
+const MAX_RESULTS = 2;
+
+const hits = (text, patterns) => patterns.reduce((n, re) => (re.test(text) ? n + 1 : n), 0);
+const any = (text, patterns) => patterns.some((re) => re.test(text));
+
+/**
+ * Which goals the prompt supports, with a score. Exported for testing and introspection: a scorer
+ * that cannot be examined in isolation is a scorer whose threshold nobody can defend.
+ *
+ * @param {string} promptText
+ * @returns {Array<{goal: object, confidence: number, intentHits: number, subjectHits: number}>}
+ */
+export function classifyGoals(promptText) {
+  if (typeof promptText !== 'string' || !promptText.trim()) return [];
+  const text = promptText.toLowerCase();
+
+  // Veto first, and veto globally. If the prompt is about software rather than about the assistant,
+  // nothing below can rescue it and nothing below should get the chance to try.
+  if (any(text, GLOBAL_VETO)) return [];
+
+  const subjectHits = hits(text, SUBJECT);
+  if (subjectHits === 0) return [];   // key 2 absent ⇒ every goal fails, no exceptions
+
+  const out = [];
+  for (const goal of GOALS) {
+    const intentHits = hits(text, goal.intent);
+    if (intentHits === 0) continue;   // key 1 absent
+
+    const extra = Math.min(intentHits - 1, MAX_EXTRA_CUES) + Math.min(subjectHits - 1, MAX_EXTRA_CUES);
+    const confidence = Math.min(0.95, BASE + extra * PER_EXTRA_CUE);
+    out.push({ goal, confidence: +confidence.toFixed(4), intentHits, subjectHits });
+  }
+  return out.sort((a, b) => b.confidence - a.confidence);
+}
+
+/**
+ * matchGoal — the L4 surface.
+ *
+ * Given what the user says they are trying to do, name the capability that serves THAT goal, and
+ * only if it is not already serving them. Returns [] far more often than not; that is the feature.
+ *
+ * Three independent conditions must ALL hold before a single row comes back:
+ *   1. the prompt clears the two-key test and the vetoes (classifyGoals),
+ *   2. a capability the goal actually names is present in the audit, and is off or unknown,
+ *   3. the resulting confidence clears CONFIDENCE_FLOOR after any state discount.
+ *
+ * @param {string} promptText            what the user said they are trying to do
+ * @param {Array}  capabilities          rows from capability-registry.auditAll()
+ * @returns {Array<{capability: object, why: string, confidence: number, goal: string}>}
+ */
+export function matchGoal(promptText, capabilities) {
+  if (!Array.isArray(capabilities) || capabilities.length === 0) return [];
+
+  const scored = classifyGoals(promptText);
+  if (scored.length === 0) return [];
+
+  const byKey = new Map();
+  for (const c of capabilities) if (c && typeof c.key === 'string') byKey.set(c.key, c);
+
+  // Best row per capability. Two goals can legitimately point at the same capability; the user is
+  // owed one sentence about it, from whichever goal explains it best — not the same suggestion twice
+  // wearing different rationales.
+  const best = new Map();
+
+  for (const { goal, confidence } of scored) {
+    for (const key of goal.serves) {
+      const cap = byKey.get(key);
+      if (!cap) continue;
+
+      // Never advocate for something already working. A recommendation to switch on what is already
+      // on is not merely useless — it proves to the reader that we did not look, and every other
+      // claim we make is downgraded accordingly.
+      const state = cap.state;
+      if (state !== 'off' && state !== 'unknown') continue;
+
+      const adjusted = +(confidence * (state === 'unknown' ? UNKNOWN_DISCOUNT : 1)).toFixed(4);
+      if (adjusted < CONFIDENCE_FLOOR) continue;
+
+      const prior = best.get(key);
+      if (prior && prior.confidence >= adjusted) continue;
+      best.set(key, { capability: cap, why: explain(goal, cap), confidence: adjusted, goal: goal.id });
+    }
+  }
+
+  return [...best.values()]
+    .sort((a, b) => b.confidence - a.confidence)
+    .slice(0, MAX_RESULTS);
+}
+
+/**
+ * The sentence the user reads.
+ *
+ * Every clause is DERIVED — the goal's own `because`, the registry's own `label`, the registry's own
+ * `whatItBuysYou`, and the registry's own `evidence` string verbatim. Nothing here is written to be
+ * persuasive, because the moment this function starts generating copy it starts generating claims,
+ * and a claim about the machine that did not come from a probe is the thing this repo exists to
+ * refuse.
+ *
+ * The state clause is the specific guard: an 'unknown' capability is described as unreadable, never
+ * as off. Reporting "off" for something we failed to measure is the exact defect that shipped as
+ * "26 hooks off" against a learner holding 457 trajectories.
+ */
+function explain(goal, cap) {
+  const stateClause = cap.state === 'unknown'
+    ? 'whether this is already switched on could not be read on this machine'
+    : 'it is switched off';
+  const evidence = cap.evidence ? ` — ${cap.evidence}` : '';
+  return `${goal.because}. ${cap.label} is the part of your stack that serves that: `
+    + `${cap.whatItBuysYou} Right now ${stateClause}${evidence}.`;
+}

package/scripts/goldie-research.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// goldie-research.mjs — Goldie's DETERMINISTIC core: keep the model-router catalog verifiably fresh.
+//
+// Stuart's standing mandate (2026-07-12): the router must never run on stale beliefs about the model
+// landscape. Goldie runs WEEKLY (scripts/goldie-weekly.sh via launchd) and answers, with live data:
+//   • what do the router's candidate models ACTUALLY cost right now (OpenRouter /models, public API)?
+//   • did any price drift >20% since the catalog was last verified (ruflo ADR-149's own re-measure
+//     trigger — that threshold is rUv's, not invented here)?
+//   • which Codex tiers exist on this machine right now (~/.codex/models_cache.json, fetched live
+//     by Codex itself)?
+//   • which cheap, tool-capable OpenRouter models exist that we DON'T track (the "worth a look" radar)?
+//
+// It updates ONLY prices + verified-stamps in ~/.claude/model-router/catalog.json. It NEVER adds an
+// execution path (harness/subscription fields) — the catalog's own rule: an engine that "chooses" a
+// model it can't run is worse than one that doesn't know it exists. New-model adoption and bucket
+// taxonomy are JUDGMENT calls: goldie-weekly.sh layers a headless-Claude research pass on top, and
+// its output lands in the same brief as a PROPOSAL for a human/session to apply.
+//
+// Output: ~/.claude/model-router/goldie/YYYY-MM-DD.md (the brief) + updated catalog.json.
+// Exit 0 = brief written; exit 1 = could not produce a brief (wrapper alerts loudly — no silent death).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const CONFIG_DIR = path.join(os.homedir(), '.claude', 'model-router');
+const CATALOG = path.join(CONFIG_DIR, 'catalog.json');
+const GOLDIE_DIR = path.join(CONFIG_DIR, 'goldie');
+const DECISIONS = path.join(os.homedir(), '.claude', 'metaharness', 'routing-decisions.jsonl');
+const TODAY = new Date().toISOString().slice(0, 10);
+const DRIFT_THRESHOLD = 0.20; // ADR-149 open question #3: re-measure when pricing moves >20%
+
+async function fetchOpenRouterModels() {
+  const res = await fetch('https://openrouter.ai/api/v1/models', { signal: AbortSignal.timeout(20000) });
+  if (!res.ok) throw new Error(`OpenRouter /models HTTP ${res.status}`);
+  const j = await res.json();
+  if (!Array.isArray(j.data) || !j.data.length) throw new Error('OpenRouter /models returned no data');
+  return j.data;
+}
+
+// OpenRouter pricing is $/token as strings; catalog speaks $/MTok.
+const perMTok = (v) => (v == null || isNaN(+v) ? null : +(+v * 1e6).toFixed(4));
+
+function refreshCatalogPrices(catalog, orModels) {
+  const byId = new Map(orModels.map((m) => [m.id, m]));
+  const changes = [];
+  for (const c of catalog.candidates) {
+    if (c.provider !== 'openrouter') continue;
+    const live = byId.get(c.id);
+    if (!live) { changes.push({ id: c.id, note: 'NOT FOUND on OpenRouter anymore — investigate before next route' }); continue; }
+    const fresh = { in: perMTok(live.pricing?.prompt), out: perMTok(live.pricing?.completion) };
+    if (fresh.in == null || fresh.out == null) { changes.push({ id: c.id, note: 'listed but pricing unparsable — left as-is' }); continue; }
+    const old = c.costPerMTok;
+    if (old && typeof old.out === 'number') {
+      const drift = Math.max(Math.abs(fresh.in - old.in) / old.in, Math.abs(fresh.out - old.out) / old.out);
+      if (drift > DRIFT_THRESHOLD) changes.push({ id: c.id, note: `PRICE DRIFT ${(drift * 100).toFixed(0)}%: in $${old.in}->$${fresh.in}, out $${old.out}->$${fresh.out} /MTok (>${DRIFT_THRESHOLD * 100}% — ADR-149 says re-measure quality/cost now)` });
+      else if (fresh.in !== old.in || fresh.out !== old.out) changes.push({ id: c.id, note: `price updated: in $${old.in}->$${fresh.in}, out $${old.out}->$${fresh.out} /MTok` });
+    }
+    c.costPerMTok = fresh;
+    c.verified = `${TODAY} OpenRouter API (goldie)`;
+  }
+  catalog.updated = TODAY;
+  return changes;
+}
+
+// The radar: cheap, tool-capable models we don't track. Tool support matters because agentic work
+// (the router's whole domain) is useless without it. Deterministic shortlist only — adoption is a
+// judgment call for the brief's reader / the judgment layer.
+function radar(catalog, orModels) {
+  const tracked = new Set(catalog.candidates.map((c) => c.id));
+  return orModels
+    .filter((m) => !tracked.has(m.id))
+    .filter((m) => (m.supported_parameters || []).includes('tools'))
+    .map((m) => ({ id: m.id, in: perMTok(m.pricing?.prompt), out: perMTok(m.pricing?.completion), ctx: m.context_length }))
+    .filter((m) => m.in != null && m.in >= 0 && m.in <= 0.5 && m.out != null && m.out >= 0) // negative = OpenRouter's dynamic-pricing sentinel, not a price
+    .sort((a, b) => a.in - b.in)
+    .slice(0, 8);
+}
+
+function codexTiers() {
+  try {
+    const cache = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.codex', 'models_cache.json'), 'utf8'));
+    const models = cache.models || cache.data || [];
+    const names = models.map((m) => m.id || m.slug || m.name).filter(Boolean);
+    // `models` (below) is truncated to 20 for the brief's display list; `allModels` is the FULL set,
+    // kept separately so the gpt-5.6 reinstate check (reinstateGpt56, below) can never miss a real
+    // slug just because it landed past position #20 in the cache.
+    return { fetchedAt: cache.fetched_at || cache.fetchedAt || 'unknown', models: names.slice(0, 20), allModels: names };
+  } catch { return null; }
+}
+
+// GPT-5.6 auto-reinstate (Stuart's mandate, 2026-07-12): gpt-5.6-sol/terra/luna were demoted to
+// landscape-only THAT SAME DAY because their "verified live" stamps were false — two independent
+// reads of models_cache.json showed only gpt-5.5/5.4/5.4-mini/codex-auto-review. The demotion note
+// on each entry says: reinstate ONLY when a fresh read of models_cache.json actually shows the slug.
+// This is that fresh read, automated, every week Goldie runs — no more relying on a human to notice.
+//
+// Inverse direction (any 'codex' harness entry whose gpt-* id vanishes from this week's cache) is
+// FLAG-ONLY, never auto-demote: a cache miss could be rollout timing or a transient cache staleness,
+// not proof the model is gone — the same false-confidence mistake in reverse. Demotion stays a
+// judgment call for a human/Goldie's judgment pass, same as the 2026-07-12 demotion itself was.
+function reinstateGpt56(catalog, codex) {
+  const result = { reinstated: [], warnings: [] };
+  if (!codex) return result; // no live cache this run (codexTiers() returned null) — skip both checks silently
+  const live = new Set(codex.allModels);
+  for (const c of catalog.candidates) {
+    if (c.id.startsWith('gpt-5.6') && Array.isArray(c.harness) && c.harness.length === 0 && live.has(c.id)) {
+      c.harness = ['codex'];
+      c.subscription = ['codex'];
+      c.verified = `${TODAY} ~/.codex/models_cache.json live (goldie auto-reinstate)`;
+      c.note = `auto-reinstated by goldie on ${TODAY}; was demoted for false verification 2026-07-12`;
+      result.reinstated.push(c.id);
+    }
+    if (c.id.startsWith('gpt-') && Array.isArray(c.harness) && c.harness.includes('codex') && !live.has(c.id)) {
+      result.warnings.push(c.id);
+    }
+  }
+  return result;
+}
+
+// models.env cross-check (pure informational drift-detection between the two model registries —
+// ~/.claude/models.env auto-refreshes provider pins independently of the router's own catalog.json,
+// so the two can silently drift apart; this just surfaces that, it never edits either file).
+function parseModelsEnv() {
+  try {
+    const lines = fs.readFileSync(path.join(os.homedir(), '.claude', 'models.env'), 'utf8').split('\n');
+    const pins = [];
+    for (const line of lines) {
+      const t = line.trim();
+      if (!t || t.startsWith('#')) continue;
+      const eq = t.indexOf('=');
+      if (eq === -1) continue;
+      pins.push({ key: t.slice(0, eq).trim(), value: t.slice(eq + 1).trim() });
+    }
+    return pins;
+  } catch { return null; }
+}
+
+// Loose match: models.env pins bare model names (e.g. 'deepseek-v4-flash') while the catalog often
+// prefixes openrouter candidates with a provider ('deepseek/deepseek-v4-flash') — compare both the
+// raw id and the segment after the last '/' in either direction.
+function pinMatchesCatalog(pinValue, candidates) {
+  const norm = pinValue.toLowerCase();
+  return candidates.some((c) => {
+    const cid = c.id.toLowerCase();
+    const short = cid.split('/').pop();
+    return cid === norm || short === norm;
+  });
+}
+
+function modelsEnvCrossCheck(catalog) {
+  const pins = parseModelsEnv();
+  if (!pins) return null;
+  return pins.map((p) => ({ ...p, known: pinMatchesCatalog(p.value, catalog.candidates) }));
+}
+
+function decisionStats() {
+  try {
+    const lines = fs.readFileSync(DECISIONS, 'utf8').trim().split('\n').filter(Boolean);
+    const byModel = {};
+    for (const l of lines) { try { const d = JSON.parse(l); byModel[d.model] = (byModel[d.model] || 0) + 1; } catch { /* skip */ } }
+    return { total: lines.length, byModel };
+  } catch { return { total: 0, byModel: {} } }
+}
+
+async function main() {
+  const catalog = JSON.parse(fs.readFileSync(CATALOG, 'utf8'));
+  const orModels = await fetchOpenRouterModels();
+  const changes = refreshCatalogPrices(catalog, orModels);
+  const watch = radar(catalog, orModels);
+  const codex = codexTiers();
+  const gpt56 = reinstateGpt56(catalog, codex);
+  for (const id of gpt56.reinstated) changes.push({ id, note: `AUTO-REINSTATED: harness/subscription set to ['codex'] — slug now confirmed live in models_cache.json (goldie auto-reinstate)` });
+  const envCross = modelsEnvCrossCheck(catalog);
+  const stats = decisionStats();
+
+  fs.writeFileSync(CATALOG, JSON.stringify(catalog, null, 2) + '\n');
+  fs.mkdirSync(GOLDIE_DIR, { recursive: true });
+
+  const brief = [
+    `# Goldie weekly model-landscape brief — ${TODAY}`,
+    '',
+    `Live sources: OpenRouter /api/v1/models (${orModels.length} models), ~/.codex/models_cache.json, routing-decisions.jsonl.`,
+    '',
+    `## Catalog price refresh (${changes.length ? changes.length + ' change(s)' : 'no changes'})`,
+    ...(changes.length ? changes.map((c) => `- ${c.id}: ${c.note}`) : ['- all tracked OpenRouter prices unchanged; verified-stamps refreshed to today']),
+    '',
+    '## Radar: cheap tool-capable models we do NOT track (≤$0.50/MTok in, top 8 by input price)',
+    ...(watch.length ? watch.map((m) => `- ${m.id} — in $${m.in}, out $${m.out} /MTok, ctx ${m.ctx}`) : ['- none matched the filter this week']),
+    '',
+    '## Codex tiers on this machine (live cache)',
+    codex ? `- fetched_at: ${codex.fetchedAt}` : '- no ~/.codex/models_cache.json found',
+    ...(codex ? codex.models.map((m) => `- ${m}`) : []),
+    '',
+    `## GPT-5.6 auto-reinstate check (${gpt56.reinstated.length} reinstated this run)`,
+    ...(!codex ? ['- skipped: no live ~/.codex/models_cache.json this run'] :
+      gpt56.reinstated.length ? gpt56.reinstated.map((id) => `- ${id}: REINSTATED — harness/subscription set to ['codex'], now confirmed live`) :
+      ['- none reinstated: no gpt-5.6-* landscape entry appeared in this week\'s live cache']),
+    ...(gpt56.warnings.length ? gpt56.warnings.map((id) => `- WARNING: ${id} has harness:['codex'] but is NOT in this week's live models_cache.json — verify manually before trusting it (flag only, not auto-demoted)`) : []),
+    '',
+    '## models.env cross-check (informational drift-detection between the two model registries; never edits either file)',
+    ...(!envCross ? ['- ~/.claude/models.env not found'] : envCross.map((p) => `- ${p.key}=${p.value}${p.known ? '' : ' — NOT recognized in catalog.json (provider the router doesn\'t track, or the two registries have drifted — worth a look)'}`)),
+    '',
+    `## Router decision log so far (${stats.total} decisions)`,
+    ...Object.entries(stats.byModel).map(([m, n]) => `- ${m}: ${n}`),
+    '',
+    '## Standing questions for the judgment layer (goldie-weekly.sh appends its answers below)',
+    '1. How many BUCKETS should prompts be classified into, given this landscape? (current policy: 3-tier placeholder)',
+    '2. What is the best model per bucket right now, per the public evals (Artificial Analysis, LMArena, SWE-bench)?',
+    '3. Should any radar model be wired up (needs: route-cheap PRICING entry + catalog harness path + a measured quality check)?',
+    '',
+  ].join('\n');
+
+  const briefPath = path.join(GOLDIE_DIR, `${TODAY}.md`);
+  fs.writeFileSync(briefPath, brief);
+  console.log(`[goldie] catalog refreshed (${changes.length} change(s)); brief: ${briefPath}`);
+  if (changes.some((c) => c.note.startsWith('PRICE DRIFT') || c.note.startsWith('NOT FOUND'))) {
+    console.log('[goldie] ATTENTION: drift or delisting detected — see brief');
+    process.exitCode = 0; // informational; the wrapper reads the brief for the push
+  }
+}
+
+main().catch((e) => { console.error(`goldie-research: ${e.message}`); process.exit(1); });