ruvnet-brain 4.0.2 → 4.0.5

package/plugin/skills/release-proof/scripts/release-proof.mjs

@@ -6,13 +6,59 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
-export const REQUIRED_CHECKS = ['ci', 'integration-linux', 'stranger-matrix', 'ux-qe'];
+export const REQUIRED_CHECKS = ['ci', 'integration-linux', 'stranger-matrix', 'ux-qe', 'release-qe'];
 
 const fail = (code, detail) => ({ code, detail });
 const cleanHex = (value, length) => new RegExp(`^[a-f0-9]{${length}}$`, 'i').test(String(value || ''));
 const digestOf = (receipt) => String(receipt?.artifact?.sha256 || '').replace(/^sha256:/, '');
+const versionField = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+
+function versionIdentityFailures(expectedVersion, expectedTag, fields) {
+  const mismatches = [];
+  if (!versionField(expectedVersion)) mismatches.push('version is missing');
+  if (expectedTag !== `v${expectedVersion}`) mismatches.push(`tag=${expectedTag ?? 'missing'}`);
+  for (const [name, value, expected = expectedVersion] of fields) {
+    if (value !== expected) mismatches.push(`${name}=${value ?? 'missing'}`);
+  }
+  return mismatches;
+}
+
+export function evaluateStabilizationCandidateReceipt(receipt) {
+  const failures = [];
+  const sha = String(receipt?.sha || '');
+  const digest = digestOf(receipt);
+  if (receipt?.schemaVersion !== 1 || receipt?.phase !== 'stabilization-candidate' || receipt?.mode !== 'stabilization') {
+    failures.push(fail('INVALID_STABILIZATION_RECEIPT', 'schemaVersion=1, phase=stabilization-candidate, and mode=stabilization are required'));
+  }
+  if (receipt?.targetScore !== 95 || receipt?.scoreClaimed !== false) {
+    failures.push(fail('STABILIZATION_SCORE_MISREPRESENTED', 'stabilization must preserve the 95 target and explicitly make no 95 claim'));
+  }
+  if (!cleanHex(sha, 40) || !cleanHex(receipt?.tree, 40) || receipt?.dirty !== false) {
+    failures.push(fail('INVALID_LINEAGE', 'clean candidate SHA and tree are required'));
+  }
+  if (!cleanHex(digest, 64) || receipt?.artifact?.sourceSha !== sha) {
+    failures.push(fail('INVALID_ARTIFACT_DIGEST', 'sealed package digest must be bound to the candidate SHA'));
+  }
+  const version = versionField(receipt?.version);
+  const identityMismatches = versionIdentityFailures(version, receipt?.tag, [
+    ['source package', receipt?.sourceVersions?.package],
+    ['source Claude plugin', receipt?.sourceVersions?.claudePlugin],
+    ['source Codex plugin', receipt?.sourceVersions?.codexPlugin],
+    ['packed npm artifact', receipt?.artifact?.version],
+  ]);
+  if (identityMismatches.length) failures.push(fail('VERSION_IDENTITY_MISMATCH', identityMismatches.join(', ')));
+  if (receipt?.security?.status !== 'PASS' || receipt?.security?.critical !== 0 || receipt?.security?.high !== 0) {
+    failures.push(fail('SECURITY_NOT_PASS', 'stabilization requires zero critical/high dependency findings'));
+  }
+  if (!(receipt?.qe?.total > 0) || receipt?.qe?.status !== 'PASS' || receipt?.qe?.failed !== 0
+    || receipt?.qe?.skipped !== 0 || receipt?.qe?.passed !== receipt?.qe?.total) {
+    failures.push(fail('QE_NOT_PASS', 'release QE must execute nonzero work with zero failed/skipped tests'));
+  }
+  return { verdict: failures.length === 0 ? 'PASS' : 'FAIL', sha, artifactSha256: digest, failures };
+}
 
 export function evaluateCandidateReceipt(receipt) {
+  if (receipt?.phase === 'stabilization-candidate') return evaluateStabilizationCandidateReceipt(receipt);
   const failures = [];
   const sha = String(receipt?.sha || '');
   const digest = digestOf(receipt);
@@ -23,6 +69,22 @@ export function evaluateCandidateReceipt(receipt) {
   if (!cleanHex(digest, 64)) failures.push(fail('INVALID_ARTIFACT_DIGEST', 'artifact SHA-256 is missing or malformed'));
   if (receipt?.artifact?.sourceSha !== sha) failures.push(fail('ARTIFACT_SOURCE_MISMATCH', 'packed artifact is not bound to the candidate SHA'));
 
+  const version = versionField(receipt?.version);
+  const tag = version ? `v${version}` : null;
+  const identityMismatches = versionIdentityFailures(version, receipt?.tag, [
+    ['source package', receipt?.sourceVersions?.package],
+    ['source Claude plugin', receipt?.sourceVersions?.claudePlugin],
+    ['source Codex plugin', receipt?.sourceVersions?.codexPlugin],
+    ['packed npm artifact', receipt?.artifact?.version],
+    ['bundle brainVersion', receipt?.artifact?.bundle?.brainVersion],
+    ['bundle releaseTag', receipt?.artifact?.bundle?.releaseTag, tag],
+    ['installed Claude host', receipt?.hosts?.claude?.version],
+    ['installed Codex host', receipt?.hosts?.codex?.version],
+  ]);
+  if (identityMismatches.length > 0) {
+    failures.push(fail('VERSION_IDENTITY_MISMATCH', `candidate surfaces must identify one generation: ${identityMismatches.join(', ')}`));
+  }
+
   const vector = receipt?.releaseVector || {};
   if (vector.verdict !== 'PASS' || vector.sha !== sha || vector.unknown !== 0 || vector.skipped !== 0) {
     failures.push(fail('RELEASE_VECTOR_NOT_PASS', 'release vector must PASS on the exact SHA with zero UNKNOWN/SKIP'));
@@ -85,6 +147,20 @@ export function evaluatePublicationReceipt(candidate, publication) {
   const digest = candidateResult.artifactSha256;
   if (publication?.schemaVersion !== 1 || publication?.phase !== 'publication') failures.push(fail('INVALID_PUBLICATION_RECEIPT', 'schemaVersion=1 and phase=publication are required'));
   if (publication?.sha !== sha || publication?.artifactSha256 !== digest) failures.push(fail('PUBLICATION_SEAL_MISMATCH', 'publication does not reference candidate seal'));
+  const version = versionField(candidate?.version);
+  const tag = version ? `v${version}` : null;
+  const identityMismatches = versionIdentityFailures(version, candidate?.tag, [
+    ['publication version', publication?.version],
+    ['npm version', publication?.npm?.version],
+    ['GitHub release tag', publication?.githubRelease?.tag, tag],
+    ['bundle brainVersion', publication?.bundle?.brainVersion],
+    ['bundle releaseTag', publication?.bundle?.releaseTag, tag],
+    ['installed Claude host', publication?.installed?.claude?.version],
+    ['installed Codex host', publication?.installed?.codex?.version],
+  ]);
+  if (identityMismatches.length > 0) {
+    failures.push(fail('PUBLIC_VERSION_IDENTITY_MISMATCH', `public surfaces must identify candidate ${version ?? 'UNKNOWN'}: ${identityMismatches.join(', ')}`));
+  }
   for (const surface of ['npm', 'githubRelease']) {
     const item = publication?.[surface];
     if (item?.sha !== sha || item?.artifactSha256 !== digest) failures.push(fail('PUBLIC_ARTIFACT_MISMATCH', `${surface} differs from candidate seal`));

package/plugin/skills/ruvnet-brain/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ruvnet-brain
 description: Use whenever a task involves the RuvNet / rUv ecosystem (Ruflo, RuVector/RVF, AgentDB, RuLake, RuView, agentic-flow, agenticow, SAFLA, QuDAG, DAA, ruv-fann, FACT, SynthLang, SPARC, or any of rUv's 20+ repos) — OR whenever you are asked to build, implement, add, refactor, enhance, or fix ANYTHING, in any repo, on any stack. Grounds every RuvNet capability claim in real source via search_ruvnet before asserting, actively considers the FULL toolkit (not just the 2-3 most-cited tools) for whichever one or two would genuinely help THIS project, and TAKES THE LEAD the Ruv way on every build regardless of stack — proposes the right architecture + why, gets one go/no-go, then orchestrates end-to-end (SPARC, parallel swarms, persistent memory, QA gates, proof) instead of acting like a passive answer-bot.
-updated: 2026-07-28
+updated: 2026-08-01
 ---
 
 # RuvNet Brain
@@ -127,7 +127,10 @@ When asked to build, implement, add, refactor, enhance, or fix anything, do NOT
 
 **2. On a yes (or when clearly authorized / low-risk), orchestrate end-to-end:**
    - **SPARC** the non-trivial features: Specification → Pseudocode → Architecture → Refinement → Completion, with a QA gate between phases.
-   - **Parallelize** with Ruflo: `swarm_init` + `agent_spawn` to register tracked agents, then execute — Claude Code Task for hands-on file work, `agent_execute` for research/reasoning. Run independent streams concurrently; don't serialize what can be parallel.
+   - **Parallelize** with Ruflo: use `swarm_init` + `agent_spawn` to coordinate and register tracked agents; those calls do not select the execution billing path. Execute every normal swarm task through the active host's subscription-backed native agents — Claude Code's native Task tool or Codex's native collaboration agents — for research, reasoning, and hands-on file work. Run independent streams concurrently; don't serialize what can be parallel.
+   - **Isolate every non-trivial fix:** give each writing lane one dedicated git worktree and a scoped branch rooted at the current integration base. Never let two writers share a worktree. A read-only lane may share a checkout. Preserve any dirty or failed worktree as recovery evidence; never force-remove it to make the status look clean.
+   - **Promote through one rail:** require the lane's focused tests and failure-path mutant first, then hand its exact diff and evidence to one clean integration owner. The integration owner reconciles dependency order, runs the impacted regression gate, and creates one reviewable commit per fix. A passing lane is not shipped, and a dirty shared checkout is never a release candidate.
+   - **Seal before publication:** run the installed `release-proof` skill against an immutable packed artifact from the clean integration SHA. Only the protected release workflow may publish; only the post-publication seal permits `shipped` or `verified`. If any source, test, issue, host, grader, digest, or workflow evidence is absent, report the exact status (`NOT READY`, `SEALED, NOT SHIPPED`, or `PUBLISHED, NOT VERIFIED`) and keep working from the preserved workstream.
    - **Persist** decisions + state to AgentDB (`memory_store` / `memory_search`) so nothing is lost across sessions or compaction. Recall before deciding — and write memory AT THE MOMENT a decision lands (an ADR accepted, a correction from the user, an architecture call), not reactively when someone asks why memory is empty. "I hadn't been writing memory, only checking it" is a real field failure; proactive capture is the fix.
    - **Ground** every RuvNet capability claim via `search_ruvnet` before asserting, and prefer RuvNet building blocks over generic defaults — but only when the build actually touches the RuvNet stack. For a build with no RuvNet angle, ground in the user's own codebase and official docs instead, the normal way, without mentioning search_ruvnet or RuvNet at all.
    - **Capture** key decisions as ADRs; QA each gate.
@@ -137,9 +140,13 @@ When asked to build, implement, add, refactor, enhance, or fix anything, do NOT
 
 **4. Keep the user confident.** Say what you're doing and why as you go, signal progress, and explain any esoteric concept in one plain line before you lean on it. Narrate *decisions and progress* — never your own compliance with an internal rule (e.g. don't announce that a rule "doesn't apply here"; just proceed as if it were never mentioned). The user should always feel a sharp engineer is in charge and moving — never stalled, never guessing, and never explaining its own instructions to itself out loud.
 
-## Cost-optimal model routing — the verified default (not aspirational)
+## Cost-optimal model routing — subscription execution is the default
 
-Two separate questions, don't conflate them: (1) which Claude tier for a subagent you're about to dispatch, (2) whether a task can skip Claude entirely and go to a cheap third-party model. Both verified live, end-to-end, on 2026-07-07 — by reading the actual source across `ruflo`, `agentic-flow`, and `agent-harness-generator` (not their ADRs, which drift from the code in both directions), then running real commands. Apply both by default whenever you dispatch a subagent — this is the standard way the brain works, not an opt-in per project.
+Two separate questions, don't conflate them: (1) which tier to use inside the active Claude Code or
+Codex subscription, and (2) whether the user has explicitly chosen a separately billed provider.
+The first is the default. Provider-backed execution requires explicit user opt-in; it is never an
+implicit fallback. Never ask for an API key for normal swarm work. Ruflo coordinates the swarm;
+the active host's native subscription agents execute it.
 
 **0. HARD RULE — mechanical work does not run in the main loop (2026-07-13, replaces the advisory version).**
 
@@ -154,7 +161,7 @@ The first version of this rule said "consult the engine before dispatching." Adv
 | Mechanical | grep/glob sweeps, reading CI logs, mechanical edits (rename, path fix, import swap), test-fixture rewrites, file inventories | Subagent, `model: haiku` |
 | Analytical | tracing a bug across files, summarizing a subsystem, drafting tests from a spec | Subagent, `model: sonnet` |
 | Judgment | architecture, root-cause reasoning, security/correctness calls, anything user-facing | Main loop (whatever the user chose) |
-| Pure text, no repo access | research, summarize, classify, transform | `scripts/route-cheap.mjs` → OpenRouter |
+| Pure text, no repo access | research, summarize, classify, transform | Native subscription subagent on the active host |
 
 **Every dispatch leaves a receipt — no exceptions, or this is decorative again.** Subagent dispatches were invisible until `dispatch-receipt.mjs` existed (route-cheap only logged OpenRouter calls), which is why the log looked dead even when routing happened. After the Agent returns, with the REAL sizes:
 
@@ -192,13 +199,21 @@ If `profile.json` is missing, ask the two subscription questions (Claude Pro/Max
 
 Don't expect this specific tool to ever reach GLM/DeepSeek/anything non-Anthropic: its handler never computes an embedding, the one thing that unlocks Ruflo's separate neural router (`neural-router.ts`) — that router is real, well-built code (verified by installing its native FastGRNN backend and watching real training run), with real 2026-06-15 measured benchmark data, but its candidate pool is Ling-2.6-Flash / Gemini-2.5-Flash-Lite / GPT-4.1 / Llama-3.3-70B (not GLM/DeepSeek), it's reachable only via `agent_spawn`, gated behind an off-by-default env var, and has a live NaN bug on sparse per-candidate scoring. Don't wire around those gates — the payoff on rUv's own dataset is thin (n=20, near-tied margins), and a separate rUv benchmark (`ROUTER-PILOT.md`, 2026-06-28) found this whole class of embedding-based difficulty routing scores at chance (ROC-AUC 0.38) on real data. Not the lever to reach for.
 
-**2. True cheap-model delegation.** `mcp__ruflo__agent_execute` cannot do this — its own description says it runs "via the Anthropic Messages API," Anthropic-only, no provider override. The real, working path is agentic-flow's own CLI (genuinely wired OpenRouter integration, real HTTP client):
+**2. Explicit provider-backed delegation (opt-in only).** This section is inactive unless the user
+explicitly asks to spend through an external provider for the current task. It is never selected
+because a subscription is missing, logged out, quota-limited, or temporarily unavailable; those
+conditions degrade or stop the native run without requesting a provider key. `mcp__ruflo__agent_execute`
+is also provider-API execution, not a subscription-backed Ruflo worker, and must follow the same
+explicit-consent boundary. For a user-authorized OpenRouter run, agentic-flow's CLI is the working
+provider path:
 
 ```bash
 npx agentic-flow@latest --agent researcher --model "deepseek/deepseek-chat" --task "<task>"
 npx agentic-flow@latest --agent researcher --model "z-ai/glm-4.6" --task "<task>"
 ```
-Any `--model` containing `/` auto-routes through OpenRouter. Verified live: both returned correct answers in ~5s using the key already in `.env`.
+Any `--model` containing `/` routes through OpenRouter. Invoke it only after the explicit opt-in
+above and only when the required provider credential is already configured; do not request one as
+part of routine swarm setup.
 
 Use this for read-only work with no file mutation — research, summarization, classification, simple text transforms — where a cheap model is good enough. Real, current pricing (pulled live from the OpenRouter API):
 

package/plugin/skills/whats-new/SKILL.md

@@ -8,10 +8,10 @@ updated: 2026-07-28
 
 Ground the answer in files that exist now; do not recite release claims from memory.
 
-1. Read the installed plugin version from `.codex-plugin/plugin.json` relative to this skill's
-   plugin root. If that is unavailable, read the current checkout's `plugin/.codex-plugin/plugin.json`.
-2. Locate `docs/RELEASE-NOTES-4.0.md` in the current repository, then
-   `~/Code/ruvnet-brain/docs/RELEASE-NOTES-4.0.md`. Read it before summarizing.
+1. Run the installed plugin's `scripts/whats-new.mjs` executable. It reads the version manifest and
+   curated notes from the same immutable plugin payload and exits nonzero if either asset is missing.
+   Do not substitute a checkout, download, or another installed version when it fails.
+2. Read that command's output before summarizing it.
 3. State the installed version exactly. Do not say the user is on 4.0 unless it starts with `4.`.
    For a 3.9 development version, describe verified items as "4.0-line enhancements landing in
    3.9.x", using the release note's own status language.

package/scripts/build-bundle.mjs

@@ -10,19 +10,24 @@
 // Idempotent: re-run any time as new variants/primers/grades land — it copies whatever exists now
 // and records honestly what is still missing. Does NOT embed or grade; pure assembly.
 //
-//   node scripts/build-bundle.mjs [--out dist/ruvnet-brain] [--version v0.2.0-dev]
+//   node scripts/build-bundle.mjs [--assets /path/to/release-assets]
+//                                 [--out dist/ruvnet-brain] [--version v0.2.0-dev]
 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 { getVersionTag, stripTag } from './version.mjs';
+import { getVersion, getVersionTag, stripTag } from './version.mjs';
 import { auditRvfIndexes } from './rvf-index-audit.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = path.join(ROOT, 'kb');
 const DATA = path.join(ROOT, 'data');
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+// RVF binaries are intentionally release assets, not Git blobs. A clean worktree therefore has
+// zero stores unless the release operator supplies the canonical external asset directory. Keep
+// source/runtime files rooted in this exact checkout; only generated RVF families come from ASSETS.
+const ASSETS = path.resolve(ROOT, arg('--assets', 'kb'));
 const OUT = path.resolve(ROOT, arg('--out', 'dist/ruvnet-brain'));
 const BRAIN_VERSION = arg('--version', getVersionTag()); // inherits the single source of truth
 
@@ -79,7 +84,9 @@ const PRIVATE_STORES = loadPrivateStores();
 function discoverBuilt() {
   const names = new Set();
   const excludedPrivate = [];
-  for (const f of fs.readdirSync(KB)) {
+  if (!fs.existsSync(ASSETS)) return [];
+  for (const f of fs.readdirSync(ASSETS)) {
+    if (f.startsWith('._')) continue; // AppleDouble metadata is never a vector store.
     const m = f.match(/^(.+?)\.big\.rvf$/);
     if (!m) continue;
     if (/\.(idmap|embed)\b/.test(f)) continue;
@@ -111,8 +118,8 @@ function gradeFor(name) {
 
 // ---- file copy helper ---------------------------------------------------------------------------
 let copied = 0, missing = [];
-function cp(src, destDir, { required = false } = {}) {
-  const s = path.isAbsolute(src) ? src : path.join(KB, src);
+function cp(src, destDir, { required = false, asset = false } = {}) {
+  const s = path.isAbsolute(src) ? src : path.join(asset ? ASSETS : KB, src);
   if (!fs.existsSync(s)) { if (required) missing.push(path.basename(src)); return false; }
   fs.copyFileSync(s, path.join(destDir, path.basename(s)));
   copied++;
@@ -153,7 +160,7 @@ if (built.length === 0) {
   process.exit(1);
 }
 const rvfIndexAudit = await auditRvfIndexes(
-  built.map((name) => path.join(KB, `${name}.big.rvf`)),
+  built.map((name) => path.join(ASSETS, `${name}.big.rvf`)),
 );
 const missingIndexes = rvfIndexAudit.filter(({ state }) => state !== 'PASS');
 if (missingIndexes.length) {
@@ -168,16 +175,16 @@ const builtRepos = [];
 for (const name of built) {
   // One canonical computer-focused vector store per repository. The unsuffixed passages/meta
   // sidecars are shared with the .big RVF so source text and metadata are packaged once.
-  cp(`${name}.big.rvf`, OUT, { required: true });
-  cp(`${name}.big.rvf.idmap.json`, OUT, { required: true });
-  cp(`${name}.big.rvf.embed.json`, OUT, { required: true });
-  cp(`${name}.passages.jsonl`, OUT, { required: true });
-  cp(`${name}.meta.json`, OUT, { required: true });
-  const hasSymbols = cp(`${name}.symbols.json`, OUT);
+  cp(`${name}.big.rvf`, OUT, { required: true, asset: true });
+  cp(`${name}.big.rvf.idmap.json`, OUT, { required: true, asset: true });
+  cp(`${name}.big.rvf.embed.json`, OUT, { required: true, asset: true });
+  cp(`${name}.passages.jsonl`, OUT, { required: true, asset: true });
+  cp(`${name}.meta.json`, OUT, { required: true, asset: true });
+  const hasSymbols = cp(`${name}.symbols.json`, OUT, { asset: true });
   const hasPrimer = cp(`${name}-primer.md`, OUT);
   // metadata
   let chunks = null, model = null, dims = null;
-  try { const m = JSON.parse(fs.readFileSync(path.join(KB, `${name}.meta.json`), 'utf8')); chunks = m.entries ? Object.keys(m.entries).length : null; model = m.model; dims = m.dimensions; } catch { /* */ }
+  try { const m = JSON.parse(fs.readFileSync(path.join(ASSETS, `${name}.meta.json`), 'utf8')); chunks = m.entries ? Object.keys(m.entries).length : null; model = m.model; dims = m.dimensions; } catch { /* */ }
   const reg = regByLower.get(name.toLowerCase()) || {};
   const grade = gradeFor(name);
   builtRepos.push({
@@ -194,7 +201,7 @@ for (const name of built) {
 // the machine-wide ledger wholesale would leak private store names/hashes even though their RVFs
 // were correctly excluded.
 {
-  const generationsFile = path.join(KB, 'RVF-GENERATIONS.json');
+  const generationsFile = path.join(ASSETS, 'RVF-GENERATIONS.json');
   if (!fs.existsSync(generationsFile)) {
     missing.push('RVF-GENERATIONS.json');
   } else {
@@ -222,15 +229,15 @@ cpDir(path.join(ROOT, 'primer'), path.join(OUT, 'primer'));
 // CONCEPTS store (L2 + primers embedded as prose; big-only) — the cross-repo tool unions it at query
 // time so code-implemented capabilities are retrievable as high-confidence prose. discoverRepos in the
 // bundle finds concepts.big.rvf automatically, so search_ruvnet searches it with no extra config.
-const hasConcepts = fs.existsSync(path.join(KB, 'concepts.big.rvf'));
-if (hasConcepts) for (const suf of ['concepts.big.rvf', 'concepts.big.rvf.idmap.json', 'concepts.big.rvf.embed.json', 'concepts.big.passages.jsonl', 'concepts.big.meta.json', 'concepts.passages.jsonl', 'concepts.meta.json']) cp(suf, OUT);
+const hasConcepts = fs.existsSync(path.join(ASSETS, 'concepts.big.rvf'));
+if (hasConcepts) for (const suf of ['concepts.big.rvf', 'concepts.big.rvf.idmap.json', 'concepts.big.rvf.embed.json', 'concepts.big.passages.jsonl', 'concepts.big.meta.json', 'concepts.passages.jsonl', 'concepts.meta.json']) cp(suf, OUT, { asset: true });
 
 // RUV-GISTS store (rUv's public gists — release notes / integration dossiers; big-only, same shape as
 // concepts, unioned by search_ruvnet at query time). BUG FIX: only `concepts` was special-cased above,
 // so ruv-gists — a PUBLIC store, not private-fenced — was silently omitted from EVERY bundle ever
 // shipped. Include it, WITH .big.passages.jsonl (the big variant opens it by name, same as concepts).
-const hasGists = fs.existsSync(path.join(KB, 'ruv-gists.big.rvf'));
-if (hasGists) for (const suf of ['ruv-gists.big.rvf', 'ruv-gists.big.rvf.idmap.json', 'ruv-gists.big.rvf.embed.json', 'ruv-gists.big.passages.jsonl', 'ruv-gists.big.meta.json', 'ruv-gists.passages.jsonl', 'ruv-gists.meta.json']) cp(suf, OUT);
+const hasGists = fs.existsSync(path.join(ASSETS, 'ruv-gists.big.rvf'));
+if (hasGists) for (const suf of ['ruv-gists.big.rvf', 'ruv-gists.big.rvf.idmap.json', 'ruv-gists.big.rvf.embed.json', 'ruv-gists.big.passages.jsonl', 'ruv-gists.big.meta.json', 'ruv-gists.passages.jsonl', 'ruv-gists.meta.json']) cp(suf, OUT, { asset: true });
 
 // capability-cards.md — the FAST LANE's zero-ML answer source (kb/card-lane.mjs, the first
 // responder search_ruvnet consults before the heavy cross-repo search). Ships as its own small
@@ -358,18 +365,20 @@ console.log(`[build-bundle] module graph: ${derivedTools.length} modules from ${
 for (const t of tools) cp(t, OUT, { required: true });
 // self-update provenance (where this bundle came from + the canonical manifest URL). Optional: a build
 // without it simply ships a brain whose `forge-update.mjs --check` reports "self-update not configured".
-cp('SOURCE.json', OUT);
+cp('SOURCE.json', OUT, { required: true });
 
-// releaseTag stamp (2026-07-17). Without this SOURCE.json carries NO version, so every install's
-// telemetry ping sent v:"unknown" and the admin page could never show who is stale — the whole point
-// of the counter. Stamp the product version here so installs report a real number; a release workflow
-// that knows the exact git tag may overwrite this with the bundle's own Release tag.
+// Rebind copied SOURCE.json to this build. The external RVFs may come from the previous release,
+// but the installed product identity belongs to the source generation that assembled them.
 try {
   const sj = path.join(OUT, 'SOURCE.json');
   const doc = JSON.parse(fs.readFileSync(sj, 'utf8'));
-  doc.releaseTag = getVersionTag(); // the real product version tag — never the literal "unknown"
+  doc.brainVersion = getVersion();
+  doc.releaseTag = getVersionTag();
   fs.writeFileSync(sj, JSON.stringify(doc, null, 2));
-} catch (e) { console.error(`[build-bundle] WARN: could not stamp releaseTag into SOURCE.json (${e.message}) — installs will report 'unknown' until fixed.`); }
+} catch (e) {
+  console.error(`[build-bundle] FATAL: could not stamp SOURCE.json identity (${e.message}).`);
+  process.exit(1);
+}
 
 // SIGNED AUTO-APPLY trust root (SEC-0010 #6, 2026-07-17). The self-updater must VERIFY a downloaded
 // bundle's Ed25519 signature before extracting executable code over the user's install. For that it

package/scripts/fix-workstream.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// Supervised fix lifecycle boundary: create one isolated writer lane, then seal a clean,
+// content-bound handoff. This command intentionally cannot merge, push, publish, promote,
+// delete, reset, or force-remove anything. Immutable release authority remains release-proof.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const FULL_SHA = /^[a-f0-9]{40}$/i;
+const SCOPED_BRANCH = /^(fix|bugfix|hotfix|issue|codex)\/[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+const SAFE_SCOPE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const RELEASE_COMMAND = 'node scripts/release-proof.mjs --candidate <candidate-receipt.json>';
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function command(commandName, args, options = {}) {
+  return spawnSync(commandName, args, {
+    encoding: options.encoding ?? 'utf8',
+    cwd: options.cwd,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+function git(cwd, args, { allowFailure = false, binary = false } = {}) {
+  const result = command('git', ['-C', cwd, ...args], {
+    cwd,
+    encoding: binary ? null : 'utf8',
+  });
+  if (!allowFailure && result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || result.error?.message || 'unknown git failure').trim();
+    fail(`git ${args.join(' ')} failed: ${detail}`);
+  }
+  return result;
+}
+
+function output(cwd, args) {
+  return String(git(cwd, args).stdout || '').trim();
+}
+
+function parseArgs(args) {
+  const parsed = { evidence: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith('--')) fail(`unexpected argument: ${token}`);
+    const key = token.slice(2);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) fail(`missing value for --${key}`);
+    index += 1;
+    if (key === 'evidence') parsed.evidence.push(value);
+    else if (['integration', 'base', 'branch', 'worktree', 'scope', 'out'].includes(key)) parsed[key] = value;
+    else fail(`unknown option: --${key}`);
+  }
+  return parsed;
+}
+
+function requireAbsolute(value, label) {
+  if (!value) fail(`${label} is required`);
+  if (!path.isAbsolute(value)) fail(`${label} must be an absolute path`);
+  return path.resolve(value);
+}
+
+function requireScope(value) {
+  if (!SAFE_SCOPE.test(String(value || ''))) fail('scope must be a bounded identifier using letters, digits, dot, underscore, or dash');
+  return value;
+}
+
+function requireClean(cwd, role) {
+  const dirty = output(cwd, ['status', '--porcelain=v1', '--untracked-files=all']);
+  if (dirty) fail(`${role} worktree is dirty; preserve it and reconcile before continuing`);
+}
+
+function commonDirectory(cwd) {
+  const raw = output(cwd, ['rev-parse', '--git-common-dir']);
+  return fs.realpathSync(path.resolve(cwd, raw));
+}
+
+function currentBranch(cwd) {
+  const branch = output(cwd, ['branch', '--show-current']);
+  if (!branch) fail(`${cwd} is detached; a named branch is required`);
+  return branch;
+}
+
+function validateBase(cwd, base) {
+  if (!FULL_SHA.test(String(base || ''))) fail('base lineage must be an explicit full 40-character commit SHA');
+  const resolved = output(cwd, ['rev-parse', '--verify', `${base}^{commit}`]);
+  if (resolved !== base) fail('base lineage does not resolve to the explicit commit SHA');
+}
+
+function requireScopedBranch(branch, integrationBranch) {
+  if (!SCOPED_BRANCH.test(String(branch || '')) || branch === integrationBranch) {
+    fail('writer must use a scoped non-main branch (fix/, bugfix/, hotfix/, issue/, or codex/) distinct from integration');
+  }
+}
+
+function worktrees(cwd) {
+  const text = output(cwd, ['worktree', 'list', '--porcelain']);
+  return text.split(/\n\n+/).filter(Boolean).map((block) => {
+    const fields = {};
+    for (const line of block.split('\n')) {
+      const space = line.indexOf(' ');
+      fields[space === -1 ? line : line.slice(0, space)] = space === -1 ? true : line.slice(space + 1);
+    }
+    return fields;
+  });
+}
+
+function sameFilesystemEntry(left, right) {
+  try {
+    const leftStat = fs.statSync(left, { bigint: true });
+    const rightStat = fs.statSync(right, { bigint: true });
+    return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+  } catch {
+    return false;
+  }
+}
+
+function assertSingleOwner(cwd, branch, expectedPath, role) {
+  const ref = `refs/heads/${branch}`;
+  const owners = worktrees(cwd).filter((item) => item.branch === ref);
+  if (owners.length !== 1 || !sameFilesystemEntry(owners[0].worktree, expectedPath)) {
+    fail(`${role} branch has a shared writer or is not owned by the declared worktree`);
+  }
+}
+
+function receipt(payload) {
+  const encoded = JSON.stringify(payload);
+  return { ...payload, receiptId: `sha256:${createHash('sha256').update(encoded).digest('hex')}` };
+}
+
+function emit(value, outPath = null) {
+  const rendered = `${JSON.stringify(value, null, 2)}\n`;
+  if (outPath) {
+    const target = requireAbsolute(outPath, 'out');
+    if (fs.existsSync(target)) fail(`refusing to overwrite existing receipt: ${target}`);
+    fs.writeFileSync(target, rendered, { flag: 'wx', mode: 0o600 });
+  }
+  process.stdout.write(rendered);
+}
+
+function pendingRealPath(value, label) {
+  const absolute = requireAbsolute(value, label);
+  const parent = path.dirname(absolute);
+  if (!fs.existsSync(parent) || !fs.statSync(parent).isDirectory()) fail(`${label} parent directory does not exist: ${parent}`);
+  return path.join(fs.realpathSync(parent), path.basename(absolute));
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(fs.realpathSync(root), candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+export function startFixWorkstream(options) {
+  const integration = requireAbsolute(options.integration, 'integration');
+  const writer = requireAbsolute(options.worktree, 'worktree');
+  const scope = requireScope(options.scope);
+  validateBase(integration, options.base);
+  requireClean(integration, 'integration');
+  const integrationSha = output(integration, ['rev-parse', 'HEAD']);
+  if (integrationSha !== options.base) fail('base lineage must equal the current integration HEAD');
+  const integrationBranch = currentBranch(integration);
+  requireScopedBranch(options.branch, integrationBranch);
+  assertSingleOwner(integration, integrationBranch, integration, 'integration');
+
+  if (writer === integration || writer.startsWith(`${integration}${path.sep}`)) fail('writer worktree must be isolated from the integration worktree');
+  if (fs.existsSync(writer)) fail('writer worktree path already exists; it will not be removed or overwritten');
+  const branchRef = git(integration, ['show-ref', '--verify', `refs/heads/${options.branch}`], { allowFailure: true });
+  if (branchRef.status === 0) {
+    const owner = worktrees(integration).find((item) => item.branch === `refs/heads/${options.branch}`);
+    fail(owner ? `branch is already checked out at ${owner.worktree}; shared writers are forbidden` : 'writer branch already exists; branch reuse is forbidden');
+  }
+
+  const created = git(integration, ['worktree', 'add', '-b', options.branch, writer, options.base], { allowFailure: true });
+  if (created.status !== 0) {
+    const detail = String(created.stderr || created.stdout || created.error?.message || 'unknown git failure').trim();
+    fail(`git worktree add failed without cleanup or force removal: ${detail}`);
+  }
+
+  if (commonDirectory(writer) !== commonDirectory(integration)) fail('created writer is not in the integration repository lineage');
+  if (output(writer, ['rev-parse', 'HEAD']) !== options.base) fail('created writer HEAD does not match the explicit integration base');
+  requireClean(writer, 'writer');
+  assertSingleOwner(writer, options.branch, writer, 'writer');
+
+  return receipt({
+    schemaVersion: 1,
+    phase: 'workstream-start',
+    scope,
+    branch: options.branch,
+    worktree: writer,
+    integrationWorktree: integration,
+    integrationBranch,
+    baseSha: options.base,
+    baseTree: output(integration, ['rev-parse', `${options.base}^{tree}`]),
+    repositoryCommonDir: commonDirectory(integration),
+    publishAuthorized: false,
+    promotionAuthorized: false,
+    releaseGate: { authority: 'release-proof', command: RELEASE_COMMAND },
+  });
+}
+
+function requireAncestor(cwd, ancestor, descendant, message) {
+  const result = git(cwd, ['merge-base', '--is-ancestor', ancestor, descendant], { allowFailure: true });
+  if (result.status !== 0) fail(message);
+}
+
+function evidenceFiles(values) {
+  if (!Array.isArray(values) || values.length === 0) fail('at least one focused test or review evidence file is required');
+  return values.map((value) => {
+    const absolute = requireAbsolute(value, 'evidence');
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) fail(`evidence file does not exist or is not a file: ${absolute}`);
+    const bytes = fs.readFileSync(absolute);
+    return { path: absolute, sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length };
+  });
+}
+
+export function sealFixHandoff(options) {
+  const integration = requireAbsolute(options.integration, 'integration');
+  const writer = requireAbsolute(options.worktree, 'worktree');
+  const scope = requireScope(options.scope);
+  if (options.out) {
+    const out = pendingRealPath(options.out, 'out');
+    if (isWithin(integration, out) || isWithin(writer, out)) fail('handoff receipt must be outside the integration and writer worktrees');
+    if (fs.existsSync(out)) fail(`refusing to overwrite existing receipt: ${out}`);
+  }
+  validateBase(integration, options.base);
+  validateBase(writer, options.base);
+  requireClean(integration, 'integration');
+  requireClean(writer, 'writer');
+  if (commonDirectory(writer) !== commonDirectory(integration)) fail('writer and integration do not share repository lineage');
+
+  const integrationBranch = currentBranch(integration);
+  const writerBranch = currentBranch(writer);
+  requireScopedBranch(writerBranch, integrationBranch);
+  assertSingleOwner(integration, integrationBranch, integration, 'integration');
+  assertSingleOwner(writer, writerBranch, writer, 'writer');
+  const integrationSha = output(integration, ['rev-parse', 'HEAD']);
+  const writerSha = output(writer, ['rev-parse', 'HEAD']);
+  requireAncestor(integration, options.base, integrationSha, 'integration lineage does not descend from the declared base');
+  requireAncestor(writer, options.base, writerSha, 'writer lineage does not descend from the declared base');
+  if (writerSha === options.base) fail('writer contains no committed change to hand off');
+
+  const patchBytes = git(writer, ['diff', '--binary', `${options.base}..${writerSha}`], { binary: true }).stdout;
+  const changedPaths = output(writer, ['diff', '--name-status', `${options.base}..${writerSha}`])
+    .split('\n').filter(Boolean).map((line) => {
+      const [status, ...names] = line.split('\t');
+      return { status, path: names.join(' -> ') };
+    });
+  if (changedPaths.length === 0) fail('writer commit has no content change to hand off');
+
+  return receipt({
+    schemaVersion: 1,
+    phase: 'fix-handoff',
+    scope,
+    branch: writerBranch,
+    worktree: writer,
+    integrationWorktree: integration,
+    baseSha: options.base,
+    integrationSha,
+    writerSha,
+    writerTree: output(writer, ['rev-parse', `${writerSha}^{tree}`]),
+    patchSha256: createHash('sha256').update(patchBytes).digest('hex'),
+    changedPaths,
+    evidence: evidenceFiles(options.evidence),
+    publishAuthorized: false,
+    promotionAuthorized: false,
+    nextAuthority: 'integration-owner',
+    releaseGate: { authority: 'release-proof', command: RELEASE_COMMAND },
+  });
+}
+
+export function main(args = process.argv.slice(2)) {
+  const [operation, ...rest] = args;
+  if (!['start', 'handoff'].includes(operation)) {
+    console.error('fix-workstream: supported commands are start and handoff; this tool cannot merge, publish, promote, or clean up');
+    return 2;
+  }
+  try {
+    const options = parseArgs(rest);
+    const result = operation === 'start' ? startFixWorkstream(options) : sealFixHandoff(options);
+    emit(result, operation === 'handoff' ? options.out : null);
+    return 0;
+  } catch (error) {
+    console.error(`fix-workstream: ${error.message}`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) process.exitCode = main();