ruvnet-brain 4.3.20 → 4.3.25

package/scripts/source-coverage.mjs

@@ -1,23 +1,47 @@
 #!/usr/bin/env node
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readRvfGenerations, sha256File } from './rvf-generation.mjs';
 import { canonicalJson, coverageGenerationFor, digest, validateGistAggregateReceipt } from './coverage-integrity.mjs';
 import { repositoryNames } from '../kb/card-lane.mjs';
+import { rootNeverMaterialized, storeRoot } from '../kb/store-root.mjs';
 
 export { canonicalJson, digest } from './coverage-integrity.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// SOURCE POLICY VERSION — sealed into every coverage as `policy.policyVersion` so a recorded
+// measurement produced under an older eligibility policy is DETECTABLE (main --check names the gap)
+// rather than silently compared row-for-row against a generator that classifies differently.
+//   1 — forks and archives INELIGIBLE by flag; anonymous gist fallback capped at 10 pages;
+//       no-corpus exclusions active on a pushedAt match alone.
+//   2 — ADR-086 Step 12 (2026-09-13). Archives eligible unconditionally. Forks dispositioned every run
+//       by the compare API pinned to both observed heads: ahead_by>0 → `fork:original-content`
+//       (ingestible, delta-only), ahead_by=0 → `fork:no-original-content` (recorded with the upstream
+//       identity). Gist fallback paginates to an empty page under a throwing ceiling. An active
+//       exclusion must carry source-file evidence bound to the observed head.
+export const SOURCE_POLICY_VERSION = 2;
+
+// Dispositions whose rows the corpus is expected to contain. `fork:original-content` is deliberately
+// NOT spelled `eligible`: scripts/corpus-reconcile.mjs full-clones every `eligible` repository row,
+// and a full clone of a fork ingests upstream authors' commits under rUv's name — the misattribution
+// the #286 RC3 repo-attribution guard exists to stop. The delta-only build that consumes this
+// disposition is corpus-reconcile's work; this layer records what it needs (`forkDelta`).
+const INGESTIBLE_DISPOSITIONS = new Set(['eligible', 'fork:original-content']);
+export function isIngestibleDisposition(disposition) { return INGESTIBLE_DISPOSITIONS.has(disposition); }
+
 const REPO_QUERY = `query($login:String!,$cursor:String){
   user(login:$login){
     publicRepositories:repositories(privacy:PUBLIC){totalCount}
     repositories(first:100,after:$cursor,privacy:PUBLIC,ownerAffiliations:OWNER,orderBy:{field:NAME,direction:ASC}){
       pageInfo{hasNextPage endCursor}
       nodes{databaseId name url description homepageUrl isFork isArchived isDisabled diskUsage updatedAt pushedAt
-        defaultBranchRef{name target{... on Commit{oid committedDate}}}}
+        defaultBranchRef{name target{... on Commit{oid committedDate}}}
+        parent{nameWithOwner isPrivate defaultBranchRef{name target{... on Commit{oid}}}}}
     }
   }
 }`;
@@ -28,6 +52,34 @@ function runGh(args) {
   return result.stdout;
 }
 
+// A fork's disposition depends on how many commits it carries that its upstream does not. The
+// compare is pinned to the two heads THIS observation recorded (never to branch names, which move),
+// and is run against the upstream repository in GitHub's documented cross-fork form
+// `BASE...FORK_OWNER:HEAD` (verified live 2026-09-13: ahead_by/behind_by/status/merge_base_commit).
+// Any failure here — 403, 404, an upstream GitHub cannot name — is required content that is
+// inaccessible, and it fails the observation rather than skipping the fork.
+function observeForkDelta(owner, node, gh) {
+  const forkHeadSha = node.defaultBranchRef?.target?.oid;
+  const upstream = node.parent?.nameWithOwner;
+  if (!upstream) throw new Error(`fork ${node.name} has no upstream parent GitHub can name — its original-content delta cannot be established`);
+  const upstreamHeadSha = node.parent.defaultBranchRef?.target?.oid;
+  if (!upstreamHeadSha) throw new Error(`fork ${node.name}: upstream ${upstream} has no default-branch head to compare against`);
+  let compare;
+  try {
+    compare = JSON.parse(gh(['api', `repos/${upstream}/compare/${upstreamHeadSha}...${owner}:${forkHeadSha}`]));
+  } catch (error) {
+    throw new Error(`fork ${node.name}: compare against upstream ${upstream} failed — ${error.message}`);
+  }
+  if (!Number.isInteger(compare?.ahead_by) || !Number.isInteger(compare?.behind_by)) {
+    throw new Error(`fork ${node.name}: compare against upstream ${upstream} returned no ahead_by/behind_by`);
+  }
+  return {
+    upstream, upstreamDefaultBranch: node.parent.defaultBranchRef.name, upstreamHeadSha, forkHeadSha,
+    mergeBaseSha: compare.merge_base_commit?.sha || null,
+    aheadBy: compare.ahead_by, behindBy: compare.behind_by, status: compare.status || null,
+  };
+}
+
 export function observeRepositories(owner, { gh = runGh } = {}) {
   const rows = [];
   const pages = [];
@@ -45,7 +97,10 @@ export function observeRepositories(owner, { gh = runGh } = {}) {
   } while (cursor);
   const expected = rows.length ? Number(JSON.parse(gh(['api', `users/${owner}`])).public_repos) : 0;
   if (rows.length !== expected) throw new Error(`repository enumeration incomplete: ${rows.length}/${expected}`);
-  return { rows, expected, pages };
+  // A fork with no head has nothing to compare; classifyRepository records it as `empty`.
+  const withDeltas = rows.map((node) => (node?.isFork && node.defaultBranchRef?.target?.oid
+    ? { ...node, forkDelta: observeForkDelta(owner, node, gh) } : node));
+  return { rows: withDeltas, expected, pages };
 }
 
 export function observeExternalRepositories(sources, { gh = runGh } = {}) {
@@ -128,6 +183,13 @@ export function canonicalRepositoryRows(rows = []) {
     homepageUrl: repo?.homepageUrl ?? null,
     isFork: repo?.isFork === true,
     ...(repo?.upstreamIsFork === undefined ? {} : { upstreamIsFork: repo.upstreamIsFork === true }),
+    // Sealed into the source identity: the delta baseline (both heads, ahead/behind) IS what was observed.
+    ...(repo?.forkDelta === undefined ? {} : { forkDelta: {
+      upstream: repo.forkDelta.upstream, upstreamDefaultBranch: repo.forkDelta.upstreamDefaultBranch ?? null,
+      upstreamHeadSha: repo.forkDelta.upstreamHeadSha, forkHeadSha: repo.forkDelta.forkHeadSha,
+      mergeBaseSha: repo.forkDelta.mergeBaseSha ?? null,
+      aheadBy: repo.forkDelta.aheadBy, behindBy: repo.forkDelta.behindBy, status: repo.forkDelta.status ?? null,
+    } }),
     isArchived: repo?.isArchived === true,
     isDisabled: repo?.isDisabled === true,
     diskUsage: repo?.diskUsage,
@@ -188,11 +250,64 @@ export function gistVersion(gist) {
   return versions.length && new Set(versions).size === 1 ? versions[0] : null;
 }
 
-export function observeGists(owner, { gh = runGh } = {}) {
-  const raw = gh(['api', `users/${owner}/gists?per_page=100`, '--paginate', '--slurp']);
-  const parsed = JSON.parse(raw);
-  const pages = Array.isArray(parsed[0]) ? parsed : [parsed];
+// Test seam: same injection pattern as `gh = runGh` above, so the fallback's failure path is
+// exercisable with a fake HTTP layer instead of the live API or even real loopback networking.
+// Reads the API base fresh per call (not frozen at module load) for the same reason.
+function runCurl(url) {
+  const result = spawnSync('curl', ['-sS', '--max-time', '30', '-H', 'accept: application/vnd.github+json',
+    '-H', 'user-agent: ruvnet-brain-source-coverage', url],
+    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 35_000 });
+  if (result.status !== 0) throw new Error(`unauthenticated gists list failed: ${(result.stderr || '').trim()}`);
+  return result.stdout;
+}
+
+// Actions' GITHUB_TOKEN is a GitHub App token, and the gists list API is closed to those
+// ("Resource not accessible by integration", HTTP 403 — confirmed live 2026-09-13, corpus-seed.yml's
+// first-ever run). Public gists need no auth, so fall back to curl against the plain API on that
+// specific failure, mirroring ingest-gists.mjs's already-working listGists/listGistsPublic split
+// (kept synchronous here, matching this module's existing gh-injection style, rather than
+// threading async through observeSourceUniverse/buildCoverage's whole synchronous call chain).
+//
+// ADR-086 Step 12 (A1): the former `page <= 10` bound was NOT a silent-omission bug — observeGists
+// throws on rows.length !== public_gists, so beyond 1000 gists the run failed closed — but it was a
+// ceiling the account could grow into. Pagination now runs to the ACTUAL end: the only terminator is
+// an EMPTY page (a short page followed by more must not stop early), under a hard ceiling that
+// THROWS rather than truncating. The rows.length === public_gists check below remains the one and
+// only completeness proof; nothing here adds a second invariant.
+const GIST_PAGE_CEILING = 100; // 10,000 gists at per_page=100
+
+function listGistsUnauthenticated(owner, curl) {
+  const apiBase = process.env.RUVNET_GISTS_API || 'https://api.github.com';
+  const pages = [];
+  for (let page = 1; ; page++) {
+    if (page > GIST_PAGE_CEILING) {
+      throw new Error(`unauthenticated gists list exceeded ${GIST_PAGE_CEILING} pages without reaching an empty page`);
+    }
+    const parsed = JSON.parse(curl(`${apiBase}/users/${owner}/gists?per_page=100&page=${page}`));
+    if (parsed?.message) throw new Error(`unauthenticated gists list failed: ${parsed.message}`);
+    if (!Array.isArray(parsed)) throw new Error('unauthenticated gists list returned an unexpected shape');
+    pages.push(parsed); // the empty terminal page is kept: it is the receipt that the end was reached
+    if (parsed.length === 0) break;
+  }
+  return pages;
+}
+
+export function observeGists(owner, { gh = runGh, curl = runCurl } = {}) {
+  let pages;
+  try {
+    const raw = gh(['api', `users/${owner}/gists?per_page=100`, '--paginate', '--slurp']);
+    const parsed = JSON.parse(raw);
+    pages = Array.isArray(parsed[0]) ? parsed : [parsed];
+  } catch (error) {
+    if (!/resource not accessible by integration|HTTP 403/i.test(String(error.message))) throw error;
+    pages = listGistsUnauthenticated(owner, curl);
+  }
   const rows = pages.flat().filter((gist) => gist?.id);
+  // Identity, not completeness (A1 forbids a second completeness invariant): a gist listed twice is
+  // collection-time source movement shifting pages under the cursor, and the same id could then mask
+  // a missed one inside an equal count. Mirrors the duplicate-repository check in observeSourceUniverse.
+  const ids = rows.map((gist) => String(gist.id));
+  if (new Set(ids).size !== ids.length) throw new Error('gist enumeration returned duplicate gist identities (collection-time source movement)');
   const expected = Number(JSON.parse(gh(['api', `users/${owner}`])).public_gists);
   if (rows.length !== expected) throw new Error(`gist enumeration incomplete: ${rows.length}/${expected}`);
   return {
@@ -205,17 +320,50 @@ export function observeGists(owner, { gh = runGh } = {}) {
 
 function storeName(name) { return String(name).toLowerCase(); }
 
+// A no-corpus exclusion is admissible only with INDEPENDENT source-file evidence bound to the exact
+// revision it excludes: the file inventory actually read from the repository tree at the observed
+// head. "0 chunks produced" is an extraction outcome, not proof of an empty source (Dual, Step 12).
+// A record that matches pushedAt but carries no such evidence is a malformed policy entry, and it
+// throws — it must never quietly remove a source from the collected set.
+function assertExclusionEvidence(repo, exclusion, upstreamSha) {
+  const evidence = exclusion?.evidence;
+  const sha = String(evidence?.headSha || '');
+  if (!evidence || typeof evidence !== 'object' || !Array.isArray(evidence.files) || typeof evidence.inspectedAt !== 'string'
+      || typeof evidence.method !== 'string') {
+    throw new Error(`no-corpus exclusion for ${repo.name} is active but carries no source-file evidence ` +
+      '(zero extracted chunks is not proof of an empty source)');
+  }
+  if (!/^[0-9a-f]{40}$/i.test(sha) || sha.toLowerCase() !== String(upstreamSha || '').toLowerCase()) {
+    throw new Error(`no-corpus exclusion for ${repo.name}: evidence headSha ${sha || '(none)'} is not the observed head ${upstreamSha}`);
+  }
+}
+
 export function classifyRepository(repo, evidence, exclusion = null) {
-  const activeExclusion = exclusion && String(exclusion.pushedAt || '') !== ''
-    && String(exclusion.pushedAt) === String(repo.pushedAt || '');
-  const disposition = activeExclusion ? 'excluded-no-corpus' : repo.isFork ? 'fork' : repo.isArchived ? 'archived' :
-    repo.isDisabled ? 'disabled' : !repo.defaultBranchRef ? 'empty' : 'eligible';
   const upstreamSha = repo.defaultBranchRef?.target?.oid || null;
+  const activeExclusion = Boolean(exclusion && String(exclusion.pushedAt || '') !== ''
+    && String(exclusion.pushedAt) === String(repo.pushedAt || ''));
+  if (activeExclusion) assertExclusionEvidence(repo, exclusion, upstreamSha);
+  if (repo.isFork && repo.defaultBranchRef && !repo.forkDelta) {
+    throw new Error(`fork ${repo.name} was observed without a fork delta — the observation predates policy ${SOURCE_POLICY_VERSION} or skipped the compare`);
+  }
+  // Policy 2: archives are eligible unconditionally (no `archived` branch); forks are dispositioned
+  // by their delta. Order: an explicit exclusion wins, then GitHub-side unavailability, then emptiness
+  // (a fork with no head has nothing to compare), then the fork delta, then eligible.
+  const disposition = activeExclusion ? 'excluded-no-corpus'
+    : repo.isDisabled ? 'disabled'
+      : !repo.defaultBranchRef ? 'empty'
+        : repo.isFork ? (repo.forkDelta.aheadBy > 0 ? 'fork:original-content' : 'fork:no-original-content')
+          : 'eligible';
   const reasons = [];
   let status = 'CURRENT';
-  if (disposition !== 'eligible') {
+  if (!isIngestibleDisposition(disposition)) {
     status = 'INELIGIBLE';
-    if (activeExclusion && exclusion?.reason) reasons.push(exclusion.reason);
+    if (disposition === 'excluded-no-corpus' && exclusion?.reason) reasons.push(exclusion.reason);
+    else if (disposition === 'disabled') reasons.push('repository is disabled by GitHub');
+    else if (disposition === 'empty') reasons.push('repository has no default branch — no commits to collect');
+    else if (disposition === 'fork:no-original-content') {
+      reasons.push(`fork of ${repo.forkDelta.upstream}: 0 commits ahead of upstream ${repo.forkDelta.upstreamHeadSha.slice(0, 12)} — contains no original content`);
+    }
   }
   else if (!evidence.rvfPresent) { status = 'MISSING'; reasons.push('canonical RVF is absent'); }
   else if (!evidence.receipt?.sourceCommit) { status = 'UNVERIFIED'; reasons.push('RVF receipt has no sourceCommit'); }
@@ -230,6 +378,8 @@ export function classifyRepository(repo, evidence, exclusion = null) {
     routing: { description: repo.description || null, homepageUrl: repo.homepageUrl || null,
       capabilityCardPresent: evidence.cardPresent === true },
     disposition,
+    archived: repo.isArchived === true,
+    ...(repo.forkDelta ? { forkDelta: { ...repo.forkDelta } } : {}),
     upstream: { sha: upstreamSha, committedAt: repo.defaultBranchRef?.target?.committedDate || null,
       pushedAt: repo.pushedAt, updatedAt: repo.updatedAt },
     artifact: { store: storeName(repo.storeName || repo.name), sourceCommit: evidence.receipt?.sourceCommit || null,
@@ -243,12 +393,19 @@ export function classifyRepository(repo, evidence, exclusion = null) {
 
 export function classifyGist(gist, evidence) {
   const source = evidence.sources?.gists?.[gist.id] || null;
-  const ingestedAt = source?.ingestedAt || evidence.cache?.[gist.id] || null;
+  const ingestedAt = source?.ingestedAt || null;
   // The list API does not expose gist history.version. A just-fetched individual source receipt is
   // still the authoritative version when the live list's updated_at is unchanged; otherwise the
   // list proves drift and the row is stale until the individual gist is refreshed.
+  //
+  // 2026-09-13 (Step 4, rule 2): a flat timestamp cache (`.ruv-gists.cache.json` -- "we last saw
+  // this updated_at at some point") is NEVER consulted here anymore. It used to OR into
+  // `currentByDate`, so a gist could be classified CURRENT purely because a bare cache file claimed
+  // a date matched -- with no binding whatsoever to the gist's actual captured/rendered content.
+  // Currency is now provable ONLY from the real, already-validated per-gist source receipt (Step 2's
+  // schema-3 `ruv-gists.sources.json`): its own `updatedAt` field must equal the live list's.
   const version = source?.updatedAt === gist.updated_at ? source.versionSha : gistVersion(gist);
-  const currentByDate = source?.updatedAt === gist.updated_at || evidence.cache?.[gist.id] === gist.updated_at;
+  const currentByDate = source?.updatedAt === gist.updated_at;
   let status = 'CURRENT';
   const reasons = [];
   if (!evidence.rvfPresent) { status = 'MISSING'; reasons.push('ruv-gists RVF is absent'); }
@@ -303,6 +460,7 @@ export function renderMarkdown(coverage) {
     '# RuvNet Brain source coverage', '',
     `Generated: ${coverage.observedAt}  `,
     `Coverage generation: \`${coverage.coverageGeneration}\`  `,
+    `Source policy version: ${coverage.policy?.policyVersion ?? 1}  `,
     `Repositories: ${coverage.totals.repositories} · Gists: ${coverage.totals.gists} · ` +
       Object.entries(counts).sort().map(([state, count]) => `${state} ${count}`).join(' · '), '',
     '> `CURRENT` is artifact-bound. Clone state and timestamps alone never establish freshness.', '',
@@ -311,7 +469,8 @@ export function renderMarkdown(coverage) {
     '|---|---:|---|---:|---|---|---|',
   ];
   for (const row of coverage.rows.filter((entry) => entry.kind === 'repository')) {
-    lines.push(`| [${row.name}](${row.url}) | ${row.upstream.committedAt || row.upstream.updatedAt || '—'} | ${row.upstream.sha || '—'} | ${row.artifact.ingestedAt || '—'} | ${row.artifact.sourceCommit || '—'} | ${row.status} | ${row.reasons.join('; ') || row.disposition} |`);
+    const marker = row.archived ? ' _(archived)_' : '';
+    lines.push(`| [${row.name}](${row.url})${marker} | ${row.upstream.committedAt || row.upstream.updatedAt || '—'} | ${row.upstream.sha || '—'} | ${row.artifact.ingestedAt || '—'} | ${row.artifact.sourceCommit || '—'} | ${row.status} | ${row.reasons.join('; ') || row.disposition} |`);
   }
   lines.push('', '## Public gists', '',
     '| Gist | Upstream updated | Version SHA | Ingested update | State | Reason |',
@@ -337,14 +496,79 @@ export function sealCoverage({ owner, repositories, gists, rows, generatorSource
     .map((status) => [status, orderedRows.filter((row) => row.status === status).length]));
   return { schemaVersion: 1, kind: 'ruvnet-brain-corpus-coverage', owner, observedAt, generatorSourceSha,
     sourceObservationSha256, snapshotRoot,
-    policy: { policyDispositionDigests, exemptionDigests },
+    policy: { policyVersion: SOURCE_POLICY_VERSION, policyDispositionDigests, exemptionDigests },
     coverageGeneration: coverageGenerationFor({ generatorSourceSha, snapshotRoot, sourceObservationSha256, rows: orderedRows,
       enumerationReceipt, policyDispositionDigests, exemptionDigests }), enumerationReceipt, rows: orderedRows,
     totals: { repositories: repositories.expected, gists: gists.expected, rows: orderedRows.length, byStatus } };
 }
 
-export function buildCoverage({ owner = 'ruvnet', kbDir = path.join(ROOT, 'kb'), policyDir = kbDir,
+// IDENTITY ACCOUNTING between a recorded coverage and a fresh one. Row keys are the stable identity
+// (`repo:<databaseId>` for the owner's repositories — a rename keeps the key and changes the name;
+// `repo:<owner/name>` for configured external sources, where a rename reads as remove + add; `gist:<id>`).
+// This is how "zero unexplained omissions" is made checkable: every repository or gist that left the
+// set since the recorded measurement is NAMED, never silently absent from a diff.
+export function diffCoverageIdentities(recorded, current) {
+  const index = (coverage, kind) => new Map((coverage?.rows || []).filter((row) => row.kind === kind)
+    .map((row) => [row.key, row.name]));
+  const identity = ([key, name]) => ({ key, name });
+  const account = (kind, withRenames) => {
+    const before = index(recorded, kind);
+    const after = index(current, kind);
+    const result = {
+      added: [...after].filter(([key]) => !before.has(key)).map(identity),
+      removed: [...before].filter(([key]) => !after.has(key)).map(identity),
+    };
+    if (withRenames) {
+      result.renamed = [...after].filter(([key, name]) => before.has(key) && before.get(key) !== name)
+        .map(([key, to]) => ({ key, from: before.get(key), to }));
+    }
+    return result;
+  };
+  return { repositories: account('repository', true), gists: account('gist', false) };
+}
+
+// What `--check` prints when the recorded projection differs from the live observation: the named
+// identity differences and the policy-version gap. A recorded coverage produced under an older
+// SOURCE_POLICY_VERSION is stale BY CONSTRUCTION — its rows were classified by different rules — and
+// that must be said out loud, not left as an unexplained byte mismatch.
+export function explainCoverageDrift(recorded, current) {
+  const diff = diffCoverageIdentities(recorded, current);
+  const list = (rows) => (rows.length ? ` (${rows.map((row) => `${row.key} ${row.name}`).join(', ')})` : '');
+  const recordedPolicy = recorded?.policy?.policyVersion ?? 1;
+  const currentPolicy = current?.policy?.policyVersion ?? SOURCE_POLICY_VERSION;
+  const recordedRows = new Map((recorded?.rows || []).map((row) => [row.key, canonicalJson(row)]));
+  const changed = (current?.rows || []).filter((row) => recordedRows.has(row.key) && recordedRows.get(row.key) !== canonicalJson(row));
+  const lines = [
+    `recorded ${recorded?.observedAt || '(unknown)'} vs live ${current?.observedAt || '(unknown)'}`,
+    `rows changed in content: ${changed.length}${changed.length ? ` (first: ${changed.slice(0, 5).map((row) => row.key).join(', ')})` : ''}`,
+    `repositories: +${diff.repositories.added.length} added${list(diff.repositories.added)}, ` +
+      `-${diff.repositories.removed.length} removed${list(diff.repositories.removed)}, ` +
+      `${diff.repositories.renamed.length} renamed${diff.repositories.renamed.length
+        ? ` (${diff.repositories.renamed.map((row) => `${row.key} ${row.from} -> ${row.to}`).join(', ')})` : ''}`,
+    `gists: +${diff.gists.added.length} added, -${diff.gists.removed.length} removed${list(diff.gists.removed)}`,
+  ];
+  if (recordedPolicy !== currentPolicy) {
+    lines.push(`recorded policyVersion ${recordedPolicy} != current policyVersion ${currentPolicy}: the recorded ` +
+      'measurement was classified under an older eligibility policy and is stale by construction; the next pipeline ' +
+      'run will produce the new shape (archives eligible, forks dispositioned by compare, exclusions evidence-bound)');
+  }
+  return lines;
+}
+
+// The measured directory defaults to THE store root (kb/store-root.mjs) — the one every reader,
+// writer and installer resolves — never `<repo>/kb`, which store-root.mjs declares a build workspace
+// and "never a second brain". Measured 2026-09-11: three commits projected a dirty workspace as the
+// brain (476 of 719 rows FAILED) while the canonical root matched every receipt. Policy files stay
+// where they are source-controlled (`<repo>/kb`) unless the caller names both directories, as the
+// release path does with `--assets`.
+export function buildCoverage({ owner = 'ruvnet', env = process.env, home = os.homedir(), kbDir = null, policyDir = null,
   observation = null, gh = runGh, now = () => new Date().toISOString() } = {}) {
+  policyDir ??= kbDir ?? path.join(ROOT, 'kb');
+  kbDir ??= storeRoot(env, home);
+  if (rootNeverMaterialized(kbDir)) {
+    throw new Error(`store root ${kbDir} does not exist — set RUVNET_BRAIN_KB or pass --assets <dir>; ` +
+      'the build workspace <repo>/kb is never measured by default');
+  }
   const externalPath = path.join(policyDir, 'external-sources.json');
   const externalPolicy = fs.existsSync(externalPath) ? JSON.parse(fs.readFileSync(externalPath, 'utf8')) : { sources: [] };
   if (!Array.isArray(externalPolicy.sources)) throw new Error('external-sources.json has no sources array');
@@ -362,8 +586,6 @@ export function buildCoverage({ owner = 'ruvnet', kbDir = path.join(ROOT, 'kb'),
   const ledger = readRvfGenerations(kbDir);
   const cards = fs.readFileSync(path.join(kbDir, 'capability-cards.md'), 'utf8');
   const cardStores = new Set([...cards.matchAll(/^##\s+(.+?)\s*$/gm)].map((match) => storeName(match[1])));
-  const gistCachePath = path.join(kbDir, '.ruv-gists.cache.json');
-  const gistCache = fs.existsSync(gistCachePath) ? JSON.parse(fs.readFileSync(gistCachePath, 'utf8')) : {};
   const gistSourcesPath = path.join(kbDir, 'ruv-gists.sources.json');
   const gistSources = fs.existsSync(gistSourcesPath) ? JSON.parse(fs.readFileSync(gistSourcesPath, 'utf8')) : null;
   const exclusionsPath = path.join(policyDir, 'no-corpus-repos.json');
@@ -372,7 +594,7 @@ export function buildCoverage({ owner = 'ruvnet', kbDir = path.join(ROOT, 'kb'),
     const store = storeName(repo.storeName || repo.name);
     return classifyRepository(repo, artifactEvidence(kbDir, ledger, cardStores, store), exclusions[store] || null);
   });
-  const gistEvidence = { ...artifactEvidence(kbDir, ledger, cardStores, 'ruv-gists'), cache: gistCache, sources: gistSources };
+  const gistEvidence = { ...artifactEvidence(kbDir, ledger, cardStores, 'ruv-gists'), sources: gistSources };
   try {
     validateGistAggregateReceipt({ receipt: gistSources,
       passagesFile: path.join(kbDir, 'ruv-gists.passages.jsonl'),
@@ -396,20 +618,27 @@ export async function main(argv = process.argv.slice(2)) {
   const ownerIndex = argv.indexOf('--owner');
   const owner = ownerIndex >= 0 ? argv[ownerIndex + 1] : 'ruvnet';
   const assetsIndex = argv.indexOf('--assets');
-  const kbDir = path.resolve(assetsIndex >= 0 ? argv[assetsIndex + 1] : path.join(ROOT, 'kb'));
+  // `--assets <dir>` names a release candidate: measure it and take policy from it, exactly as before.
+  // Otherwise measure the installed brain and take policy from the repository.
+  const kbDir = assetsIndex >= 0 ? path.resolve(argv[assetsIndex + 1]) : storeRoot();
+  const policyDir = assetsIndex >= 0 ? kbDir : path.join(ROOT, 'kb');
   const jsonPath = path.join(ROOT, 'data', 'source-coverage.json');
   const markdownPath = path.join(ROOT, 'docs', 'RUVNET-COVERAGE.md');
   const recorded = argv.includes('--check') && fs.existsSync(jsonPath)
     ? JSON.parse(fs.readFileSync(jsonPath, 'utf8')) : null;
-  const coverage = buildCoverage({ owner, kbDir,
+  console.error(`measuring ${kbDir} (policy from ${policyDir})`);
+  const coverage = buildCoverage({ owner, kbDir, policyDir,
     now: recorded?.observedAt ? () => recorded.observedAt : () => new Date().toISOString() });
   const json = `${JSON.stringify(coverage, null, 2)}\n`;
   const markdown = renderMarkdown(coverage);
   if (argv.includes('--check')) {
     const matches = fs.existsSync(jsonPath) && fs.readFileSync(jsonPath, 'utf8') === json &&
       fs.existsSync(markdownPath) && fs.readFileSync(markdownPath, 'utf8') === markdown;
-    const blockers = coverage.rows.filter((row) => row.disposition === 'eligible' && row.status !== 'CURRENT');
-    if (!matches) console.error('source coverage projections differ from live observation');
+    const blockers = coverage.rows.filter((row) => isIngestibleDisposition(row.disposition) && row.status !== 'CURRENT');
+    if (!matches) {
+      console.error('source coverage projections differ from live observation');
+      for (const line of explainCoverageDrift(recorded, coverage)) console.error(`  ${line}`);
+    }
     if (argv.includes('--strict') && blockers.length) console.error(`strict coverage: ${blockers.length} eligible row(s) are not CURRENT`);
     return matches && (!argv.includes('--strict') || blockers.length === 0) ? 0 : 1;
   }

package/scripts/status-honesty.mjs

@@ -49,6 +49,30 @@ const DERIVATION_MARKERS = [
   'remoteBranchExists', 'installedVersion', 'verifyOutcome', 'delivered', 'succeeded ?', 'sent ===',
 ];
 
+// Guard-clause derivation: `if (!x.ok) return {...failed...}; ... return { state: 'ok', ... };` gates
+// the terminal literal on an earlier validator call's `.ok` result — a real derivation — but the guard
+// can sit many lines above the literal (one guard per precondition, e.g. refreshRunHealth() checking
+// registration, identity, and envelope validity in turn before its one unconditional success return).
+// That is outside the local ±2-line window designed for inline ternaries, so it false-positived on
+// plugin/scripts/nightly-scheduler.mjs:271 (caught by the 2026-09-12 consistency audit; state:'ok' IS
+// gated, just structurally distant). Recognize the guard-clause idiom explicitly instead of widening
+// the generic window — widening would also swallow unrelated markers anywhere in the function and
+// could hide a genuinely naked literal sitting next to unrelated derivation-looking text.
+const OK_GUARD_RE = /\bif\s*\(\s*!\s*[\w$]+(?:\.[\w$]+)*\.ok\b\s*\)\s*return\b/;
+const FUNCTION_START_RE = /^\s*(export\s+)?(default\s+)?(async\s+)?function\b/;
+
+/** True if an earlier `if (!validator(...).ok) return ...;` guard, within the innermost enclosing
+ * top-level function, precedes line `matchIndex` — i.e. the function cannot reach `matchIndex`
+ * without that validator call having already passed. */
+function hasEnclosingOkGuard(lines, matchIndex) {
+  let start = 0;
+  for (let j = matchIndex - 1; j >= 0; j--) {
+    if (FUNCTION_START_RE.test(lines[j])) { start = j; break; }
+  }
+  for (let j = start; j < matchIndex; j++) if (OK_GUARD_RE.test(lines[j])) return true;
+  return false;
+}
+
 /** Scan one source text. Returns violations: [{line, text}] — success literal with no derivation. */
 export function scanSource(src, _name = '(inline)') {
   const violations = [];
@@ -61,6 +85,7 @@ export function scanSource(src, _name = '(inline)') {
     // The statement window: this line ± 2 (multi-line object literals / sh case arms).
     const windowText = lines.slice(Math.max(0, i - 2), i + 3).join('\n');
     if (DERIVATION_MARKERS.some((m) => windowText.includes(m))) continue;
+    if (hasEnclosingOkGuard(lines, i)) continue;
     violations.push({ line: i + 1, text: t.slice(0, 160) });
   }
   return violations;

package/scripts/sync-version.mjs

@@ -175,6 +175,8 @@ if (CHECK) {
     'tests/unit/version.test.mjs', 'tests/unit/sync-version-drift.test.mjs', 'tests/unit/self-update-plan.test.mjs',
     // Asserts stripTag('v1.14.1-dev') === '1.14.1-dev' — the literals ARE the fixture.
     'tests/unit/version-tag-vs-field.test.mjs',
+    // MCP reload tests carry version literals in fixture manifests — these are test payloads, not production code.
+    'tests/unit/mcp-graceful-reload.test.mjs', 'tests/integration/mcp-reload-no-restart-required.test.mjs',
   ]);
   const litRe = /['"`](v?\d+\.\d+\.\d+(?:-dev)?)['"`]/g;
 

package/scripts/trismart.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/** First-class RuvNet Brain entry point for Dual/TriSmart reviews. */
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const DUAL = path.join(ROOT, 'dual-host-deliberation.mjs');
+const TRISMART = path.resolve(ROOT, '..', 'tri-smart-skill', 'tri-smart', 'scripts', 'review.mjs');
+
+function usage() {
+  console.log('Usage: node scripts/trismart.mjs [--mode=auto|dual|tri] [--dry-run] <architecture task>');
+  console.log('Dual uses Claude Code + Codex; TriSmart adds Grok when its native CLI subscription is verified.');
+  console.log('All provider API-key variables are removed before a provider process starts.');
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) { usage(); process.exit(0); }
+const mode = args.find((arg) => arg.startsWith('--mode='))?.slice(7) ?? 'auto';
+if (!['auto', 'dual', 'tri'].includes(mode)) { console.error('mode must be auto, dual, or tri'); process.exit(2); }
+const dryRun = args.includes('--dry-run');
+const task = args.filter((arg) => !arg.startsWith('--')).join(' ').trim();
+if (!task) { usage(); process.exit(2); }
+
+if (dryRun) {
+  const providers = mode === 'dual' ? ['claude', 'codex'] : ['claude', 'codex', 'grok'];
+  console.log(JSON.stringify({ status: 'ready', mode, providers, models: {
+    claude: 'claude-fable-5-1', codex: 'gpt-6-astra', grok: 'grok-4.6',
+  }, billingPath: 'native subscription/OAuth CLI; API-key variables unset', taskHash: task.length }, null, 2));
+  process.exit(0);
+}
+
+// The portable TriSmart runner owns three-provider probing and truthful degraded output.
+// The brain's Dual path remains the native two-host implementation and is kept separate so
+// a missing Grok CLI can never silently downgrade a requested TriSmart review.
+if (mode === 'tri' || mode === 'auto') {
+  const result = spawnSync(process.execPath, [TRISMART, `--mode=${mode}`, task], { stdio: 'inherit' });
+  process.exitCode = result.status ?? 1;
+} else {
+  const result = spawnSync(process.execPath, [DUAL, task], { stdio: 'inherit' });
+  process.exitCode = result.status ?? 1;
+}