ruvnet-brain 4.7.20 → 4.7.22

package/scripts/corpus-qa.mjs

@@ -50,6 +50,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { FULL_HINTS } from './full-hints.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = path.join(ROOT, 'kb');
@@ -245,7 +246,7 @@ export function discoverStores(dir) {
 }
 
 // ---------------- CLI ----------------
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectInvocation(import.meta.url)) {
   const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
   const has = (f) => process.argv.includes(f);
   const DIR = path.resolve(arg('--dir', KB));

package/scripts/corpus-reconcile.mjs

@@ -26,6 +26,7 @@ import { captureGistSources } from './gist-receipts.mjs';
 import { projectSourceStore, RUNTIME_LEDGER_KIND } from './rvf-generation.mjs';
 import { compareKnowledgeInputs, fromCoverage as knowledgeFromCoverage, fromSeed as knowledgeFromSeed } from './knowledge-input-digest.mjs';
 import { defaultBaseDelayMs } from './transient-gh.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export { rebuildCorpusAggregates };
 
@@ -1306,8 +1307,7 @@ export async function main(argv = process.argv.slice(2), {
 // with no archive and no receipt on disk. Same defect, same fix as plugin/scripts/hook-input.mjs:518.
 function isMain() {
   try {
-    if (!process.argv[1]) return false;
-    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    return isDirectInvocation(import.meta.url);
   } catch {
     return false;
   }

package/scripts/corpus-watchdog.mjs

@@ -48,6 +48,7 @@ import { AGGREGATE_ASSET, SIGNING_PUBLIC_KEY_FILE } from './approved-runtime.mjs
 import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
 import { parseCorpusGeneration } from './corpus-promotion.mjs';
 import { retryTransientResult } from './transient-gh.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const RED = 'RED';
@@ -496,6 +497,6 @@ async function main(argv = process.argv.slice(2)) {
   return result.verdict === RED ? 1 : 0;
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   main().then((code) => { process.exitCode = code; });
 }

package/scripts/count-chunks.mjs

@@ -23,6 +23,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyFix } from './claims-verify.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const CHECK = process.argv.includes('--check');
 
@@ -49,6 +50,6 @@ async function main() {
   console.log(`\n[count-chunks] done — ${want} chunks is the live count; ${drifted.length} surface(s) rewritten.`);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   await main();
 }

package/scripts/customer-state-matrix.mjs

@@ -34,6 +34,7 @@ import { customerEnv, customerManifestUrl, installCustomer, installedModules } f
 import { addPrivateStore, resolveRuntime } from './customer-seams.mjs';
 export { resolveRuntime };
 import { doctorSmokeArgs } from './installed-brain-health.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const REPO = 'stuinfla/ruvnet-brain';
 const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -358,6 +359,6 @@ async function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   main().then((code) => { process.exitCode = code; }, (error) => { console.error(error.stack || error.message); process.exitCode = 1; });
 }

package/scripts/derive-passage-content-map.mjs

@@ -16,6 +16,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { digest } from './coverage-integrity.mjs';
 import { CONTENT_MAP_FILE, CONTENT_MAP_KIND, passageContentDigest } from './retrieval-passage-identity.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const sha256File = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
@@ -68,4 +69,4 @@ function main(argv) {
   console.log(JSON.stringify({ out, resolved: Object.keys(map.entries).length, unresolved: map.unresolved.length }));
 }
 
-if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+if (isDirectInvocation(import.meta.url)) main(process.argv.slice(2));

package/scripts/development-push-check.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export function inspectPush(root, input) {
   const checked = [];
@@ -27,7 +28,7 @@ export function inspectPush(root, input) {
   return { ok: true, checked, scope: 'unpublished-commit-secret-scan' };
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   try {
     const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
     console.log(JSON.stringify(inspectPush(root, fs.readFileSync(0, 'utf8'))));

package/scripts/dispatch-receipt.mjs

@@ -26,6 +26,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { CLAUDE_MODEL_IDS, CLAUDE_TIERS, PRICING, estTokens, estimateCosts, receiptLine, receiptsPath, priceOf } from './route-cheap.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 // Default input share when only a MEASURED TOTAL is known. A subagent's tokens are dominated by input
 // (it re-reads files and tool output on every turn); its final report is small. 0.9 is an assumption,
@@ -109,4 +110,4 @@ function main() {
   console.log(receiptLine(receipt.model, { cost: receipt.est_cost, frontier: receipt.est_frontier_cost, saved: receipt.saved, ref: receipt.inherited }));
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
+if (isDirectInvocation(import.meta.url)) main();

package/scripts/doc-currency.mjs

@@ -3,7 +3,8 @@
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { main } from '../plugin/scripts/doc-currency.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 export * from '../plugin/scripts/doc-currency.mjs';
 let direct = false;
-try { direct = Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch {}
+try { direct = isDirectInvocation(import.meta.url); } catch {}
 if (direct) process.exit(main());

package/scripts/dream-issue-gate.mjs

@@ -5,6 +5,7 @@
 // the caller supplies the finding and the current open issues, and receives a disposition before
 // invoking any GitHub write operation.
 
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 const HEX_SHA = /^[0-9a-f]{7,64}$/i;
 const ISSUE_MARKER = 'dream-fingerprint:';
 
@@ -98,7 +99,7 @@ export function buildIssueBody(finding, decision = assessFinding(finding)) {
 // Adapter contract for the Dream Machine runner. Input is JSON on stdin:
 // { "finding": { ... }, "openIssues": [{ "number", "title", "body" }] }
 // Output is the disposition JSON. This command intentionally cannot create or mutate GitHub data.
-if (process.argv[1] === new URL(import.meta.url).pathname) {
+if (isDirectInvocation(import.meta.url)) {
   let input = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });

package/scripts/dual-host-deliberation.mjs

@@ -6,6 +6,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { probeSubscriptionHosts, subscriptionOnlyEnv } from './subscription-hosts.mjs';
 import { DUAL_HOST_MODEL_IDS } from './review-model-defaults.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HOSTS = Object.freeze(['claude-code', 'codex']);
 // Top subscription models verified on the native hosts on 2026-09-10.
@@ -322,21 +323,6 @@ export async function main(argv = process.argv.slice(2), {
   }
 }
 
-// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
-// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
-// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
-// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
-// from "ran, found nothing", which is how prepareCorpusCandidate once reported SUCCESS with no
-// archive on disk. Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
-function isDirectInvocation() {
-  try {
-    if (!process.argv[1]) return false;
-    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-}
-
-if (isDirectInvocation()) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = await main();
 }

package/scripts/dual-host-suggest.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
 import { hardProblem } from './dual-host-deliberation.mjs';
 import { probeSubscriptionHosts } from './subscription-hosts.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HOSTS = Object.freeze([
   ['claude', 'claude-code'],
@@ -54,21 +55,6 @@ export function main(argv = process.argv.slice(2), {
   return 0;
 }
 
-// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
-// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
-// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
-// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
-// from "ran, found nothing", which is how prepareCorpusCandidate once reported SUCCESS with no
-// archive on disk. Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
-function isDirectInvocation() {
-  try {
-    if (!process.argv[1]) return false;
-    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-}
-
-if (isDirectInvocation()) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = main();
 }

package/scripts/eval-brain.mjs

@@ -32,6 +32,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
@@ -91,8 +92,11 @@ export function gradeQuestion(q, { grounded, citations, bannerPresent, receipt,
       return { grounded, routed: null, abstained, pass: abstained };
     case 'provenance':
       // The mechanism under test: IF a gist chunk wins, it must carry its own status banner.
-      // A better hit from the real repo is not a failure — it is better grounding.
-      return { grounded, routed: null, abstained, pass: !!grounded && !abstained && (top?.repo !== 'ruv-gists' || bannerPresent) };
+      // A better hit from the real repo is not a failure — it is better grounding. "Wins" means
+      // the citation verify-citation.mjs actually resolved (`routedRepo`, the same signal `routed`
+      // uses below) — not merely the raw top-ranked citation, which citationResolves() can walk
+      // past when it is unverified/fabricated (the sibling gap already closed for `routed`).
+      return { grounded, routed: null, abstained, pass: !!grounded && !abstained && (routedRepo !== 'ruv-gists' || bannerPresent) };
     default:
       // Abstention is correct only for the adversarial stratum. A negative cross-encoder score on
       // an answerable question is an answer miss, even when an unrelated existing path resolves.
@@ -279,6 +283,6 @@ async function main() {
   }
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   await main();
 }

package/scripts/execution-policy.mjs

@@ -2,6 +2,7 @@
 // One deterministic boundary between Brain knowledge and consequential execution.
 // This module is deliberately pure: it never loads credentials, calls a provider, or mutates state.
 
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 const NATIVE_HOSTS = new Set(['claude', 'codex']);
 const API_EXECUTORS = new Set(['agent_execute', 'sdk', 'openrouter', 'api']);
 const ACTIONS = new Set(['read', 'write', 'delegate', 'release', 'external']);
@@ -111,7 +112,7 @@ export function classifyExecutionPolicy(input = {}) {
   };
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectInvocation(import.meta.url)) {
   const raw = process.argv[2] || '{}';
   let input;
   try { input = JSON.parse(raw); } catch { process.stderr.write('execution-policy: input must be JSON\n'); process.exit(2); }

package/scripts/execution-preflight.mjs

@@ -3,12 +3,13 @@
 // live Brain search and exact project AgentDB retrieval; prose, memory, and guessed host state do
 // not satisfy this command.
 import { classifyExecutionPolicy } from './execution-policy.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export function runExecutionPreflight(input = {}) {
   return classifyExecutionPolicy({ ...input, enforceEvidence: true });
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectInvocation(import.meta.url)) {
   let input;
   try { input = JSON.parse(process.argv[2] || '{}'); }
   catch { process.stderr.write('execution-preflight: input must be JSON\n'); process.exit(2); }

package/scripts/falsify.mjs

@@ -29,6 +29,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveRuflo, RUFLO_MISSING } from '../plugin/scripts/ruflo-bin.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const sh = (cmd, args) => spawnSync(cmd, args, { cwd: ROOT, encoding: 'utf8' });
@@ -238,4 +239,4 @@ function main() {
   process.exit(0);
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();
+if (isDirectInvocation(import.meta.url)) main();

package/scripts/fix-metaharness-memretrieve.mjs

@@ -28,6 +28,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const TARGET_DIR =
   process.env.METAHARNESS_SCRIPTS_DIR ||
@@ -113,7 +114,7 @@ export function check(dir = TARGET_DIR, log = console.log) {
 // Only act when run directly, so tests can import the pure functions above.
 // Compare in URL space (pathToFileURL), not by decoding a URL into a path: `new URL(...).pathname`
 // yields "/D:/..." on Windows and never matches, so `--apply` would silently no-op there.
-const invokedDirectly = process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+const invokedDirectly = isDirectInvocation(import.meta.url);
 if (invokedDirectly) {
   const mode = process.argv.includes('--check') ? 'check' : 'apply';
   console.log(`metaharness memRetrieve ${mode} — ${TARGET_DIR}\n`);

package/scripts/fix-workstream.mjs

@@ -7,6 +7,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const FULL_SHA = /^[a-f0-9]{40}$/i;
 const SCOPED_BRANCH = /^(fix|bugfix|hotfix|issue|codex)\/[A-Za-z0-9][A-Za-z0-9._/-]*$/;
@@ -288,4 +289,4 @@ export function main(args = process.argv.slice(2)) {
   }
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) process.exitCode = main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = main();

package/scripts/full-hints.mjs

@@ -16,6 +16,7 @@
 // v2/crates — without --keep v2 those repos index almost nothing (open-claude-code: 68 passages
 // total) and their FULL_HINTS can never match.
 
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 export const FULL_HINTS = {
   'ruflo': 'v3/@claude-flow,v3/mcp,ruflo/src',
   'synthlang': 'proxy/src/cli/synthlang,proxy/src/app/synthlang',
@@ -81,7 +82,7 @@ export const KEEP_DIRS = {
 };
 
 // CLI helper so shell drivers can read the config:  node scripts/full-hints.mjs <kb-name>
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectInvocation(import.meta.url)) {
   const kb = (process.argv[2] || '').toLowerCase();
   console.log(JSON.stringify({ full: FULL_HINTS[kb] || null, keep: KEEP_DIRS[kb] || null }));
 }

package/scripts/full-suite-gate.mjs

@@ -17,6 +17,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const key = (file, name) => `${file} :: ${name}`;
@@ -132,7 +133,7 @@ export function summaryMarkdown(result) {
   ].join('\n');
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   const args = process.argv.slice(2);
   const value = (flag) => { const i = args.indexOf(flag); return i < 0 ? null : args[i + 1]; };
   const out = value('--report') || path.join(os.tmpdir(), `full-suite-${process.pid}.json`);

package/scripts/grok-host.mjs

@@ -0,0 +1,68 @@
+/**
+ * Grok CLI status for the installer summary and `--doctor` (#301).
+ *
+ * Grok has no install step of its own: it discovers the Claude Code plugin (measured with
+ * `grok inspect --json` on grok 1.0.58: plugin ruvnet-brain, 10 skills, its MCP server, and the
+ * hook file plugin/hooks/grok-hooks.json selected by plugin/.grok-plugin/plugin.json). Grok
+ * discards an allowing UserPromptSubmit hook's context (~/.grok/docs/user-guide/10-hooks.md), so the
+ * prompt-time "search first" directive never reaches its model; a line in ~/.grok/AGENTS.md (loaded
+ * as a global rule — same inspect run) is what makes Grok ground itself. That line is OPT-IN only.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const GROK_MD_START = '<!-- ruvnet-brain:start -->';
+export const GROK_MD_END = '<!-- ruvnet-brain:end -->';
+export const GROK_AGENTS_LINE = 'For anything about the RuvNet / rUv stack (Ruflo, RuVector/RVF, AgentDB, agentic-flow, and the rest), '
+  + 'call the `search_ruvnet` MCP tool first and cite the source paths it returns. Do not answer from memory. '
+  + 'If it fails, say so and run `npx ruvnet-brain --doctor`.';
+export const GROK_AGENTS_BLOCK = `${GROK_MD_START}\n${GROK_AGENTS_LINE}\n${GROK_MD_END}`;
+
+export function grokPaths(home = os.homedir()) {
+  const bin = path.join(home, '.grok', 'bin');
+  return { bin: [path.join(bin, 'grok'), path.join(bin, 'grok.exe')], agents: path.join(home, '.grok', 'AGENTS.md') };
+}
+
+/** What is true about Grok on this machine. Never runs grok; reads files only. */
+export function grokStatus({ home = os.homedir(), pluginInstalled = false, hookCount = null } = {}) {
+  const p = grokPaths(home);
+  const present = p.bin.some((file) => fs.existsSync(file));
+  let agentsText = '';
+  try { agentsText = fs.readFileSync(p.agents, 'utf8'); } catch { /* absent */ }
+  return { present, pluginInstalled: Boolean(pluginInstalled), hookCount, agentsFile: p.agents,
+    groundingLine: /search_ruvnet/.test(agentsText) };
+}
+
+/** One honest line: what reaches Grok, and whether the grounding line is there. null when no Grok. */
+export function grokStatusLine(s) {
+  if (!s.present) return null;
+  if (!s.pluginInstalled) {
+    return 'Grok CLI detected — the Brain reaches Grok only through the Claude Code plugin, which is not installed here (run npx ruvnet-brain).';
+  }
+  const hooks = Number.isInteger(s.hookCount) ? `${s.hookCount} lifecycle hooks` : 'its lifecycle hooks';
+  return `Grok CLI detected — search_ruvnet, the Brain skills and ${hooks} (grok-hooks.json) load from the Claude Code plugin. `
+    + 'Grok drops prompt-time context, so grounding relies on a search-first line in ~/.grok/AGENTS.md: '
+    + (s.groundingLine ? 'present.' : 'absent (opt in: npx ruvnet-brain --grok-agents-md).');
+}
+
+/**
+ * Add the search-first line to ~/.grok/AGENTS.md ONLY if no search_ruvnet line is there already.
+ * Marker-wrapped (removed by --uninstall), backed up, written atomically. Returns
+ * 'added' | 'present' | 'no-grok' | 'failed'.
+ */
+export function addGrokAgentsLine({ home = os.homedir(), now = new Date() } = {}) {
+  const s = grokStatus({ home });
+  if (!s.present) return 'no-grok';
+  if (s.groundingLine) return 'present';
+  const file = s.agentsFile;
+  try {
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    if (existing) fs.copyFileSync(file, `${file}.bak-${now.toISOString().replace(/[:.]/g, '-')}`);
+    const next = existing ? `${existing.replace(/\s*$/, '')}\n\n${GROK_AGENTS_BLOCK}\n` : `${GROK_AGENTS_BLOCK}\n`;
+    const tmp = `${file}.ruvnet-tmp`;
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, file);
+    return 'added';
+  } catch { return 'failed'; }
+}

package/scripts/hook-qualify-core.mjs

@@ -127,7 +127,9 @@ export function makeWorld(host, { root = REPO, label = 'qual' } = {}) {
 }
 export function worldEnv(w, extra = {}) {
   const env = {};
-  for (const k of ['PATH', 'LANG', 'LC_ALL', 'SHELL', 'USER']) if (process.env[k] !== undefined) env[k] = process.env[k];
+  // RUVNET_STOP_NUDGES is forwarded: with it stripped, a qualification run under `full` never executed the
+  // hooks that hook-shim.mjs runs only in that mode (grounding-turn-gate exited 0 unrun and "qualified").
+  for (const k of ['PATH', 'LANG', 'LC_ALL', 'SHELL', 'USER', 'RUVNET_STOP_NUDGES']) if (process.env[k] !== undefined) env[k] = process.env[k];
   env.PATH = `${path.dirname(process.execPath)}${path.delimiter}${env.PATH || '/usr/bin:/bin'}`;
   Object.assign(env, { HOME: w.home, USERPROFILE: w.home, TMPDIR: w.tmp, CLAUDE_PROJECT_DIR: w.cwd, RUVNET_BRAIN_HOME: path.join(w.home, '.cache', 'ruvnet-brain') });
   if (w.host === 'codex') env.CODEX_HOME = path.join(w.home, '.codex');

package/scripts/hook-qualify.mjs

@@ -17,6 +17,7 @@ import {
   CASES, HOSTS, auditWrites, fixturesFor, measureInjection, registrations, runCase, runConcurrent, runRepeat,
   sandboxAvailable, staticFindings,
 } from './hook-qualify-core.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 function arg(name, dflt = null) {
   const i = process.argv.indexOf(`--${name}`);
@@ -98,4 +99,4 @@ async function main() {
   return rows.every((r) => r.pass) ? 0 : 1;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().then((c) => process.exit(c), (e) => { console.error(e); process.exit(2); });
+if (isDirectInvocation(import.meta.url)) main().then((c) => process.exit(c), (e) => { console.error(e); process.exit(2); });

package/scripts/hook-retirement-check.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { automaticHookRetirementStatus } from '../bin/install.mjs';
 import { continuityRegistrations } from '../plugin/scripts/continuity-hook-policy.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -24,6 +25,6 @@ export function main() {
   return 0;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = main();
 }

package/scripts/host-registry.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { canonicalJson, digest } from './coverage-integrity.mjs';
 import { HOST_MODES, MODE_HOSTS } from './host-install-matrix.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const HOST_ADAPTER_FILES = Object.freeze([
   'plugin/host-adapters/claude.json',
@@ -115,4 +116,4 @@ export function main(args = process.argv.slice(2)) {
   }
 }
 
-if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) process.exitCode = main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = main();

package/scripts/independent-review-receipt.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { canonicalJson, digest } from './coverage-integrity.mjs';
 import { transactionIdFor } from './release-transaction.mjs';
 import { CLAUDE_FABLE_5_ID, GPT_5_6_SOL_ID, LEGACY_REVIEWER_IDENTITIES } from './review-model-defaults.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 const HEX40 = /^[a-f0-9]{40}$/;
 const HEX64 = /^[a-f0-9]{64}$/;
 const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
@@ -495,4 +496,4 @@ export function main(args = process.argv.slice(2), runtime = {}) {
   }
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = main();

package/scripts/ingest-new-repos.mjs

@@ -35,6 +35,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { storeRoot, storesAt, darkStores } from '../kb/store-root.mjs';
 import { assertIsolatedMutationWorktree } from './worktree-integrity.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
@@ -77,7 +78,7 @@ export function pendingRepos(orgRepos, root = storeRoot()) {
 }
 
 const isMain = (() => {
-  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 })();
 

package/scripts/ingest-repo.mjs

@@ -21,6 +21,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { FULL_HINTS, KEEP_DIRS } from './full-hints.mjs';
 import { storeRoot } from '../kb/store-root.mjs';
+import { repositoryNames } from '../kb/card-lane.mjs';
 import { applyPrivateOverlay } from './private-overlay.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -103,11 +104,20 @@ const ok = fs.existsSync(path.join(KB, `${kb}.big.rvf`))
 // cannot reach it. 26 of 66 stores are in exactly that state. The 2026-08-12 incident (three repos
 // ingested, all reporting success, none findable) was read as a path bug; the path was only half of
 // it. A store with no card is BUILT AND DARK, and saying "searchable" of it is the product lying.
+// ALIAS-AWARE, BECAUSE THE ROUTER IS (kb/store-root.mjs's darkStores(), same fix). A raw heading
+// match against `kb` alone reports DARK for a store only reachable through an alias card — e.g.
+// `metaharness` is built as `metaharness.big.rvf` but described under `## agent-harness-generator`.
+// That exact false positive once caused a DUPLICATE `## metaharness` card to be hand-added, which
+// collided with the alias card and broke routing outright (see kb/store-root.mjs's own account).
+// This CLI is where a user/agent decides whether to write a new card off this message, so it is
+// the highest-leverage place to get alias resolution right.
 const carded = (() => {
+  let headings;
   try {
-    return new RegExp(`^##\\s+${kb}\\s*$`, 'im')
-      .test(fs.readFileSync(path.join(KB, 'capability-cards.md'), 'utf8'));
+    const raw = fs.readFileSync(path.join(KB, 'capability-cards.md'), 'utf8');
+    headings = [...raw.matchAll(/^##\s+(\S+)\s*$/gm)].map((m) => m[1].toLowerCase());
   } catch { return false; }
+  return repositoryNames(kb, KB).some((name) => headings.includes(String(name).toLowerCase()));
 })();
 // AN ARTIFACT WITH NO COMMITTED RECIPE IS NOT DURABLE WORK — it is a local side effect with a
 // countdown on it. Proven overnight 2026-08-13 -> 08-14: a scheduled bundle apply extracted an

package/scripts/integration-evidence.mjs

@@ -4,6 +4,7 @@ import { validateQualificationReceipt } from './release-qualification.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const EXCLUSION_POLICY = 'release-linux-v1';
 
@@ -67,7 +68,7 @@ export function buildQualifiedIntegrationEvidence(report, identity) {
     qualificationReceiptSha256: report.receiptSha256, requirements: report.requirements };
 }
 
-const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isCli = isDirectInvocation(import.meta.url);
 if (isCli) {
   const value = (name) => process.argv[process.argv.indexOf(name) + 1];
   const build = process.argv.includes('--qualified') ? buildQualifiedIntegrationEvidence : buildIntegrationEvidence;