@rightkit/release 0.6.5 → 0.6.7

package/app-check.mjs

@@ -16,13 +16,65 @@
 //   qa-platform      G13  a Rust `"platform:<x>"` requirement that is not darwin or windows, the words rightkit-qa emits (it skips forever)
 //   test-harness     G14  a Cargo.toml [[test]] whose file defines `fn main(` but lacks `harness = false` (libtest ignores it: 0 tests)
 //   scenario-skip    G15  a `.scenario(` test that prints SKIP and returns: a skip that reports green
-//   release-config   G16  right-release.config.mjs: a provider publish-update.mjs refuses, an updater keyFile, an undefined Cargo profile
+//   release-config   G16  right-release.config.json (or a legacy .mjs): a provider publish-update.mjs refuses, an updater keyFile, an
+//                         undefined Cargo profile, JSON right-release cannot load
 //   skip-checks      G17  a package.json script that runs right-release with --skip-checks
 //   qa-dev-server    G18  a package.json qa* script that runs `tauri dev` (QA would test the dev server, not the app)
-//   ffmpeg-release-escape G19 `allow_in_release_builds` in non-test Rust outside crates/rightkit-ffmpeg
-//   switches-inventory G20 a right-release.config.mjs directory without a switches.json (or its releaseSwitches.inventory)
+//   ffmpeg-release-escape G19 `allow_in_release_builds` or a use of `DevFfmpeg::unverified` (call or path) in non-test Rust
+//                         outside crates/rightkit-ffmpeg (an item or file gated on feature "dev-overrides" is excused)
+//   switches-inventory G20 a right-release.config.json (or .mjs) directory without a switches.json (or its releaseSwitches.inventory)
 //   speech-link      G21  `import Speech` anywhere under swift/RightKitSwift/Sources or Tests (Apple Speech is removed, rightkit#978;
 //                         the LinkProbes control fixture is the one sanctioned import)
+//   e2e-under-cargo-test G22 `cargo test|run|nextest` (also as `rustright cargo`, or the retired `rightkit`) that runs an end-to-end
+//                         crate (rightkit-qa driver modules) in the broker without --no-run: it holds the compile slot for the whole run
+//
+// Suite trust roots (lane C3; logic in suite-trust-roots.mjs). The licence and updater public keys have one owner,
+// contracts/right-suite-api.v1.json (generated into suite-api.generated.mjs):
+//   suite-key-literal C3-04  the licence public key pasted as a byte array, 64 hex digits or base64, or the updater key text outside
+//                         a tauri.conf.json, in a non-test file
+//   suite-updater-key C3-14  a tauri*.conf.json plugins.updater.pubkey that is not a copy of a contract key (missing, a placeholder,
+//                         another key, or an unparseable file)
+//   engine-record-store C3-05 a call to from_record_store outside crates/rightkit-license: the owner binary hands the engine a
+//                         snapshot through rightkit_credentials::handoff instead
+// The shell contract (shell-contract.mjs, SHELL_CONTRACT_RULES, appended after e2e-under-cargo-test) reads an app's Tauri config, capabilities,
+// Rust and renderer sources:
+//   shell-window-hidden      SC-R1  a startup window of any platform config that is not `visible: false`
+//   shell-plugin-order       SC-R2  the shell plugin installed from setup, or after a non-QA plugin
+//   shell-handler            SC-R3  an invoked rk_shell_* command that no handler registers
+//   shell-csp                SC-R4  a CSP without default-src 'self', frame-ancestors 'none', connect-src, or with script unsafe-inline/eval
+//   shell-grants             SC-R5  a core:window:allow-* grant that the shell's own window command mirrors
+//   qa-window-label          SC-R6  the shell's main_label, the QA Control's window and the created windows disagree
+//   devtools-declaration     SC-R7  the five DevTools declaration sites (config, allow-list, Cargo feature, ACL manifest, runtime policy) disagree
+//   shell-lifecycle-external SC-R8  lifecycle_only() in an app that also opens an external webview (hardening and navigation policy are off)
+//   legal-receipt-native     SC-R9  an Onboarding legal gate whose receipt is not the native service
+// The consumer input contracts (consumer-input-contracts.mjs, CONSUMER_INPUT_RULES, appended after the shell contract) read workflow YAML,
+// JSON and Markdown as data for inputs a committed tree declares but a later step cannot reach:
+//   checkout-step-input      CA-07  a workflow step reads a tracked path its job's cone-mode sparse checkout does not materialize
+//   source-relation          CA-09  a value in one committed file names a row another committed file does not have (SOURCE_RELATIONS
+//                                   plus an app's .rightkit/source-relations.json)
+//   checkout-longpaths       CA-11  a GitHub-hosted Windows job checks out tracked paths over the Win32 limit without Git long paths
+// Legion's semantic catalog and provenance contracts (legion-semantic-contracts.mjs, LEGION_SEMANTIC_RULES, after the consumer source contracts; each
+// applies only to a tree holding its Legion producer or data file):
+//   legion-schema-projection LG-02  a schema Legion's generator byte-compares that .gitattributes leaves to eol conversion, or whose
+//                                   enum is not the code-owned Rust list it projects
+//   legion-legacy-tokens     LG-03  a legacy token in a path or file that src/config/naming-legacy-allowlist.json does not classify
+//                                   with its exact occurrence count
+//   legion-retirement-ledger LG-04  a ledger-surface file deleted after c1d80c9d with no docs/provenance/retirements.md row
+//   legion-authority-body    LG-05  an agent card without its doctrine (and, for a variant, roster) body verbatim
+// Consumer semantic policy (consumer-policy.mjs, CONSUMER_POLICY_RULES, after Legion's semantic contracts) reads an app's own declared contracts from
+// .rightkit/consumer-policy.json, as data: retired-token, route-deny-policy, layer-reach and spec-route-parity (CA-13).
+// Sealed source closures (source-closure-rules.mjs, SOURCE_CLOSURE_RULES, after the shell contract):
+//   source-closure           SF-01  a committed JSON record { sourceClosure: { sources: { path: sha256 }, digest } } whose sources are
+//                                   missing or changed since sealing, or whose digest does not cover them (normalised digests are
+//                                   declared in .rightkit/source-closures.json)
+// The ownership class rules (ownership-class-rules.mjs, OWNERSHIP_CLASS_RULES, appended last; code is placed by class, never by
+// consumer count):
+//   mandatory-foundation     OW-05  an app (root rightkit-mandatory.json, or a release config that ships a desktop app) whose profile
+//                                   requires a foundation owner (ownership-mandatory-set.json) it does not use, that selects an unknown
+//                                   or unratified profile, that has no declaration, or that excuses a row without a ratified ruling
+//   ownership-exceptions     OW-06  a .rightkit/ownership-exceptions.json entry without capability, package, reason, owner, approvedBy,
+//                                   date, expires and a RightKit issue, past its expires date (never baselineable), or that no
+//                                   ratified ruling (appAmendments.<app>.exceptions) covers
 //
 // Ratchet: findings that exist today may be listed so they print as KNOWN and do not fail; an unlisted finding fails; a listed
 // identity (`${rule}|${file}|${subject}`, no line numbers) that is gone fails as STALE, so the list only shrinks. The baseline is
@@ -43,6 +95,15 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
+import { LEGION_SEMANTIC_RULES } from "./legion-semantic-contracts.mjs";
+import { CONSUMER_INPUT_RULES } from "./consumer-input-contracts.mjs";
+import { CONSUMER_CONTRACT_RULES } from "./consumer-contracts.mjs";
+import { OWNERSHIP_CLASS_RULES } from "./ownership-class-rules.mjs";
+import { SOURCE_CLOSURE_RULES } from "./source-closure-rules.mjs";
+import { SHELL_CONTRACT_RULES } from "./shell-contract.mjs";
+import { CONSUMER_SOURCE_RULES } from "./consumer-source-contracts.mjs";
+import { CONSUMER_POLICY_RULES } from "./consumer-policy.mjs";
+import { engineRecordStore, suiteKeyLiteral, suiteUpdaterKey } from "./suite-trust-roots.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const readText = (root, rel) => { try { return fs.readFileSync(path.join(root, rel), "utf8"); } catch { return null; } };
@@ -178,7 +239,7 @@ function fileUrls({ root, files }) {
   return out;
 }
 
-// ---- G13-G20: app defects found from files alone ----------------------------------------------------------------------------
+// ---- G13-G22: app defects found from files alone ----------------------------------------------------------------------------
 // Each finding is { problem, fix, file, subject }; `${rule}|${file}|${subject}` (no line numbers, so an edit above it does not
 // change it) is its identity in ci/app-check-baseline.json.
 const SKIPPED_TREE = /(^|\/)(node_modules|vendor|target)\//;
@@ -187,7 +248,17 @@ const lineOf = (text, offset) => text.slice(0, offset).split("\n").length;
 /** `text` with every whole-line `//` comment blanked, offsets and line numbers kept (a URL inside a string is untouched). */
 const blankComments = (text) => text.replace(/^[ \t]*\/\/.*$/gm, (m) => " ".repeat(m.length));
 const rustFiles = (files) => files.filter((f) => f.endsWith(".rs") && scanned(f));
-const configFiles = (files) => files.filter((f) => /(^|\/)right-release\.config\.mjs$/.test(f) && scanned(f));
+// The release config: the data config (right-release.config.json, M24) or a legacy module (right-release.config.mjs) not yet moved.
+const configFiles = (files) => files.filter((f) => /(^|\/)right-release\.config\.(?:mjs|json)$/.test(f) && scanned(f));
+const isJsonConfig = (file) => file.endsWith(".json");
+/** Every `[key, value, parentKey]` of a parsed JSON value, depth first (the walk the JSON release config rules read). */
+function* jsonEntries(node, parentKey = null) {
+  if (Array.isArray(node)) { for (const item of node) yield* jsonEntries(item, parentKey); return; }
+  if (!node || typeof node !== "object") return;
+  for (const [key, value] of Object.entries(node)) { yield [key, value, parentKey]; yield* jsonEntries(value, key); }
+}
+/** The offset of the first `"key"` in JSON text that is followed by `:` (a key, not a string value), else 0. */
+const jsonKeyOffset = (text, key) => Math.max(0, text.search(new RegExp(`"${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\s*:`)));
 const dirOf = (file) => path.posix.dirname(file);
 
 // G13: rightkit-qa's util::platform() emits "darwin" or "windows"; a requirement spelled any other way never matches, so the
@@ -303,19 +374,33 @@ function releaseConfig({ root, files }) {
   for (const file of configFiles(files)) {
     const raw = readText(root, file);
     if (raw === null) continue;
-    const text = blankComments(raw);
+    const text = isJsonConfig(file) ? raw : blankComments(raw);
     const add = (kind, value, offset, why, fix) => out.push({ file, subject: `${kind}:${value}`, problem: `${file}:${lineOf(text, offset)} ${why}`, fix });
-    for (const m of text.matchAll(/\bprovider\s*:\s*(["'`])([^"'`]+)\1/g)) {
-      if (!RELEASE_PROVIDERS.has(m[2])) add("provider", m[2], m.index, `distribution provider "${m[2]}" is refused by packages/release/publish-update.mjs (it takes r2-rightapps or github-releases)`, 'set provider: "r2-rightapps" (private) or "github-releases" (public)');
-    }
-    for (const m of text.matchAll(/\bupdater\s*:\s*\{/g)) {
-      const block = braceBlock(text, m.index + m[0].length - 1);
-      const key = /\bkeyFile\s*:\s*([^,\n}]+)/.exec(block);
-      if (key) add("keyFile", key[1].trim().slice(0, 60), m.index + key.index, "updater keyFile: sign-updater.mjs refuses --key-file; updater keys come from the OS credential provider", "remove keyFile; the updater key is read from the credential store");
+    const badProvider = (provider, offset) => add("provider", provider, offset, `distribution provider "${provider}" is refused by packages/release/publish-update.mjs (it takes r2-rightapps or github-releases)`, 'set provider: "r2-rightapps" (private) or "github-releases" (public)');
+    const keyFile = (value, offset) => add("keyFile", value.slice(0, 60), offset, "updater keyFile: sign-updater.mjs refuses --key-file; updater keys come from the OS credential provider", "remove keyFile; the updater key is read from the credential store");
+    const profiles = [];
+    if (isJsonConfig(file)) {
+      let config;
+      try { config = JSON.parse(raw.replace(/^\uFEFF/, "")); } catch (error) {
+        add("json", "invalid", 0, `is not valid JSON (${error.message}): right-release refuses to load it`, "fix the JSON; the release config is strict JSON (no comments or trailing commas)");
+        continue;
+      }
+      for (const [key, value, parent] of jsonEntries(config)) {
+        if (key === "provider" && parent === "distribution" && typeof value === "string" && !RELEASE_PROVIDERS.has(value)) badProvider(value, text.indexOf(JSON.stringify(value)));
+        if (key === "keyFile" && parent === "updater") keyFile(JSON.stringify(value), jsonKeyOffset(text, "keyFile"));
+        if (key === "profile" && (parent === "winPackage" || parent === "macPackage") && typeof value === "string") profiles.push([value, text.indexOf(JSON.stringify(value))]);
+      }
+    } else {
+      for (const m of text.matchAll(/\bprovider\s*:\s*(["'`])([^"'`]+)\1/g)) if (!RELEASE_PROVIDERS.has(m[2])) badProvider(m[2], m.index);
+      for (const m of text.matchAll(/\bupdater\s*:\s*\{/g)) {
+        const block = braceBlock(text, m.index + m[0].length - 1);
+        const key = /\bkeyFile\s*:\s*([^,\n}]+)/.exec(block);
+        if (key) keyFile(key[1].trim(), m.index + key.index);
+      }
     }
-    const profiles = [...text.matchAll(/(["'])--profile\1\s*,\s*(["'])([^"']+)\2/g)].map((m) => [m[3], m.index])
+    profiles.push(...[...text.matchAll(/(["'])--profile\1\s*,\s*(["'])([^"']+)\2/g)].map((m) => [m[3], m.index])
       .concat([...text.matchAll(/(["'])--profile=([^"']+)\1/g)].map((m) => [m[2], m.index]))
-      .concat([...text.matchAll(/\bPROFILE\s*(?:\?\?|\|\|)\s*(["'])([^"']+)\1/g)].map((m) => [m[2], m.index]));
+      .concat([...text.matchAll(/\bPROFILE\s*(?:\?\?|\|\|)\s*(["'])([^"']+)\1/g)].map((m) => [m[2], m.index])));
     if (profiles.length) {
       const defined = profilesFor(root, files, dirOf(file));
       for (const [name, offset] of profiles) {
@@ -352,17 +437,82 @@ function qaDevServer({ root, files }) {
   return out;
 }
 
-// G19: ffmpeg's release gate is the point of crates/rightkit-ffmpeg; allow_in_release_builds outside it and its tests opens a
-// path that ships a build the gate would have refused.
+// G19: ffmpeg's release gate is the point of crates/rightkit-ffmpeg; allow_in_release_builds and a use of DevFfmpeg::unverified (a call,
+// or the path itself, as in .map(DevFfmpeg::unverified)) outside it and its tests open a path that ships a build the gate would have refused. An app pinned to an older rightkit-ffmpeg still
+// compiles both, so the names stay refused after the crate stops exporting them. UnverifiedRequest is not named here: it is the
+// argument of resolve_ffmpeg_handle(_with), which refuses in release builds, so refusing it would refuse the sanctioned fix.
+// DevFfmpeg::try_unverified is the mode-checked constructor and never matches (nor does any other name that merely starts with "unverified").
+const DEV_UNVERIFIED = /\bDevFfmpeg\s*::\s*unverified\b/g;
+// cfg(feature = "dev-overrides") and cfg(any(test, feature = "dev-overrides")): what they gate is not compiled without the feature.
+const DEV_OVERRIDES_PREDICATE = String.raw`(?:feature\s*=\s*"dev-overrides"|any\s*\(\s*(?:test\s*,\s*feature\s*=\s*"dev-overrides"|feature\s*=\s*"dev-overrides"\s*,\s*test)\s*\))`;
+const DEV_OVERRIDES_GATE = new RegExp(String.raw`#\s*\[\s*cfg\s*\(\s*${DEV_OVERRIDES_PREDICATE}\s*\)\s*\]`, "g");
+// The same gate as an inner attribute that opens the file (only other inner attributes may come before it): the whole file is gated.
+const DEV_OVERRIDES_FILE_GATE = new RegExp(String.raw`^(?:\s*#\s*!\s*\[[^\]]*\])*\s*#\s*!\s*\[\s*cfg\s*\(\s*${DEV_OVERRIDES_PREDICATE}\s*\)\s*\]`);
+// What starts a gated item or statement (the item rule: ends at its ';' or its closing '}'); anything else is a match arm, a struct field or an expression, which a depth-0 ',' ends too.
+const ITEM_START = /^(?:(?:pub|fn|const|static|mod|impl|struct|enum|union|trait|type|use|unsafe|async|extern|let|macro_rules)\b|\{)/;
+// A comment or a string or char literal: its text is prose or a message, and its braces are not code.
+const NON_CODE = /\/\/[^\n]*|\/\*[\s\S]*?\*\/|b?r(#*)"[\s\S]*?"\1|"(?:\\[\s\S]|[^"\\])*"|'(?:\\(?:u\{[0-9a-fA-F_]+\}|x[0-9a-fA-F]{2}|[^\n])|[^\\'\n])'/g;
+/** Rust `text` with every comment and string or char literal blanked, offsets and line numbers kept. */
+const blankNonCode = (text) => text.replace(NON_CODE, (m) => m.replace(/[^\n]/g, " "));
+
+/** [from, to) spans of `text` that a dev-overrides gate covers (`prose` is its blanked copy, same offsets). The gated item is what
+ * follows the attribute, stacked attributes included, up to the first `;` outside brackets or the `}` that closes the first `{`:
+ * an fn, mod, impl or block, or a `let` or const that ends at its `;`. A gated match arm or struct field (it starts with no item
+ * keyword and no `{`) ends at its `,` outside brackets as well, so an arm with no block never excuses the arms after it.
+ * Limits: a gate on `mod x;` covers that line only (x.rs is checked on its own, so a call there is still refused); any other
+ * predicate (`all(...)`, `not(...)`, another feature) is no gate; an inner `#![cfg(...)]` is not a span (ffmpegReleaseEscape excuses the whole file for it);
+ * a `let` whose value goes on after a block (`if a { b } else { c }`) is covered to that block's end; a gated arm or field
+ * whose value has a `,` outside brackets (generics such as `f::<A, B>(...)`) is covered to that comma; a tail whose braces
+ * never balance is covered to the end of the file. A hit it misses is refused: gate the call itself. */
+function devOverrideItems(text, prose) {
+  const spans = [];
+  for (const gate of text.matchAll(DEV_OVERRIDES_GATE)) {
+    if (prose[gate.index] !== "#") continue; // the attribute is itself inside a comment or a string
+    let brackets = 0;
+    let braces = 0;
+    let end = prose.length;
+    let first = gate.index + gate[0].length;
+    for (let attribute = /^\s*#\s*\[/.exec(prose.slice(first)); attribute; attribute = /^\s*#\s*\[/.exec(prose.slice(first))) {
+      let depth = 1;
+      first += attribute[0].length;
+      for (; first < prose.length && depth > 0; first++) depth += prose[first] === "[" ? 1 : prose[first] === "]" ? -1 : 0;
+    }
+    const item = ITEM_START.test(prose.slice(first).trimStart());
+    for (let i = gate.index + gate[0].length; i < prose.length; i++) {
+      const c = prose[i];
+      if (c === "(" || c === "[") brackets += 1;
+      else if (c === ")" || c === "]") brackets -= 1;
+      else if (c === "{") braces += 1;
+      else if (c === "}") braces -= 1;
+      if (braces < 0 || brackets < 0) { end = i; break; } // the block or call the attribute sits in closes first
+      if (!item && c === "," && brackets === 0 && braces === 0) { end = i + 1; break; } // a match arm or field ends at its comma
+      if (brackets === 0 && braces === 0 && (c === ";" || c === "}")) { end = i + 1; break; }
+    }
+    spans.push([gate.index, end]);
+  }
+  return spans;
+}
+
 function ffmpegReleaseEscape({ root, files }) {
   const out = [];
   for (const file of rustFiles(files)) {
     if (/(^|\/)tests\//.test(file) || /(^|\/)(?:tests|[^/]*_tests?)\.rs$/.test(file) || /(^|\/)crates\/rightkit-ffmpeg\//.test(file)) continue;
     const text = readText(root, file);
-    if (!text || !text.includes("allow_in_release_builds") || /^\s*#!\[cfg\(test\)\]/m.test(text)) continue;
+    if (!text || !/allow_in_release_builds|DevFfmpeg\s*::\s*unverified/.test(text) || /^\s*#!\[cfg\(test\)\]/m.test(text)) continue;
     const testModule = /^#\[cfg\(test\)\]/m.exec(text)?.index ?? Infinity;
-    const hit = [...blankComments(text).matchAll(/allow_in_release_builds/g)].find((m) => m.index < testModule);
-    if (hit) out.push({ file, subject: file, problem: `${file}:${lineOf(text, hit.index)} uses allow_in_release_builds outside test code: a release build could ship what the ffmpeg gate refuses`, fix: "remove it from non-test code; only tests and crates/rightkit-ffmpeg itself may name it" });
+    const prose = blankNonCode(text);
+    const gated = devOverrideItems(text, prose);
+    const allow = [...blankComments(text).matchAll(/allow_in_release_builds/g)].find((m) => m.index < testModule);
+    // Only DevFfmpeg::unverified is excused under a dev-overrides gate: allow_in_release_builds is being removed from the crate
+    // and from every app, gated or not.
+    // A file that opens with the inner attribute #![cfg(feature = "dev-overrides")] is not compiled without the feature at all.
+    const fileGated = DEV_OVERRIDES_FILE_GATE.test(text.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")));
+    const unverified = fileGated ? undefined : [...prose.matchAll(DEV_UNVERIFIED)].find((m) => m.index < testModule && !gated.some(([from, to]) => m.index >= from && m.index < to));
+    const uses = [];
+    const fixes = [];
+    if (allow) { uses.push(`${file}:${lineOf(text, allow.index)} uses allow_in_release_builds`); fixes.push("remove it from non-test code; only tests and crates/rightkit-ffmpeg itself may name it"); }
+    if (unverified) { uses.push(`${file}:${lineOf(text, unverified.index)} uses DevFfmpeg::unverified`); fixes.push('resolve the binary with rightkit_ffmpeg::resolve_ffmpeg_handle, which refuses in release builds; keep DevFfmpeg::unverified in tests or under #[cfg(any(test, feature = "dev-overrides"))] (or #![cfg(...)] at the top of the file)'); }
+    if (uses.length) out.push({ file, subject: file, problem: `${uses.join(" and ")} outside test code: a release build could ship what the ffmpeg gate refuses`, fix: fixes.join("; ") });
   }
   return out;
 }
@@ -374,10 +524,20 @@ function switchesInventory({ root, files }) {
   for (const file of configFiles(files)) {
     const raw = readText(root, file);
     if (raw === null) continue;
-    const text = blankComments(raw);
+    const text = isJsonConfig(file) ? raw : blankComments(raw);
     const dir = dirOf(file);
-    const block = /\breleaseSwitches\s*:\s*\{/.exec(text);
-    const named = block ? /\binventory\s*:\s*(["'`])([^"'`]+)\1/.exec(braceBlock(text, block.index + block[0].length - 1))?.[2] : undefined;
+    let block;
+    let named;
+    if (isJsonConfig(file)) {
+      let config;
+      try { config = JSON.parse(raw.replace(/^\uFEFF/, "")); } catch { config = null; }
+      const switches = config?.releaseSwitches;
+      if (switches && typeof switches === "object") block = { index: jsonKeyOffset(text, "releaseSwitches") };
+      if (typeof switches?.inventory === "string") named = switches.inventory;
+    } else {
+      block = /\breleaseSwitches\s*:\s*\{/.exec(text);
+      named = block ? /\binventory\s*:\s*(["'`])([^"'`]+)\1/.exec(braceBlock(text, block.index + block[0].length - 1))?.[2] : undefined;
+    }
     const inventory = path.posix.normalize(path.posix.join(dir, named ?? "switches.json"));
     if (fs.existsSync(path.join(root, inventory))) continue;
     out.push({ file, subject: dir, problem: `${file}:${block ? lineOf(text, block.index) : 1} has no switches inventory (${inventory} does not exist)`, fix: named ? `commit ${inventory} or point releaseSwitches.inventory at the app's inventory` : `add ${path.posix.join(dir, "switches.json")} listing the app's QA and dev switches (see packages/release/fixtures/release-switches/app/switches.json)` });
@@ -403,6 +563,509 @@ function speechLink({ root, files }) {
   return out;
 }
 
+// G22: the broker compiles; it does not run end-to-end tests. `cargo test`, `cargo run` and `cargo nextest` (plain, through the
+// RustRight client as `rustright cargo`, or as `rightkit` while the retired alias lasts) run the test binary or the program inside the
+// broker job, which holds the compile slot for the whole run (Pulse, 2026-10-23: 55 minutes with 15 builds queued) and has no GUI
+// session or unscrubbed environment a real-app test needs. The fix is `--no-run` to compile and `rightkit-qa run-tests` to run
+// outside the broker (crates/rightkit-qa/docs/run-tests.md); for `cargo run`, which has no --no-run, `cargo build --bin` in the broker and the
+// built binary outside it (or `rightkit-qa journeys run`); for a whole-workspace run, also leaving the crate out (--exclude).
+// Found from files alone, in three steps:
+//   1. the end-to-end crates: a Cargo package that depends on rightkit-qa not optionally (the optional dependency is the in-app control
+//      server behind a qa-native / dev-control feature) and has a .rs file, outside examples/, that names a driver module of it;
+//   2. the commands: `cargo test|run|nextest` in a package.json script, a shell, PowerShell, batch, Node or Python script, a Makefile
+//      or justfile recipe, a GitHub workflow `run:` step, a git hook, or a code span of a runbook document;
+//   3. the selection: a command that is not `--no-run` or a rightkit-qa run-tests / journeys run, and names an end-to-end crate by
+//      -p / --package, --manifest-path, --workspace / --all (a member of the workspace in the working directory), --test or --bin, or by
+//      naming nothing in a virtual workspace (`cargo test`, `cargo test --manifest-path Cargo.toml`: every member, or the default-members).
+// Known limits, deliberate for an offline check: no cargo binary (a path dependency that cargo adds to a workspace implicitly is not
+// a member here), a command assembled from variables is matched on its literal text only, a package.json script that calls another
+// script is judged where the cargo text is, a cargo alias (`cargo t`) is not matched, and a bare `cargo test` selects nothing unless the
+// directory's manifest is a virtual workspace (a [workspace] with no [package]): there it tests every member, or the default-members.
+// A code span of a runbook that is only the command (no argument) is a mention unless it is told to be run (INSTRUCTION_VERB), and a PowerShell
+// `<# #>` block is a comment: the same command in a fenced block, a script, a package.json script, a recipe, a workflow or a hook is a command line.
+const E2E_DRIVER_MODULES = new Set(["harness", "control", "suite", "scenario", "engine", "in_app", "interactive", "page", "browser", "android"]);
+const E2E_GUARD_TARGET = "qa_surface_guard"; // the one test target of an end-to-end crate that only runs the static guard
+const E2E_NAME_ONLY = /-e2e$|^qa-/; // a name is not evidence: crates that match only this are listed for a reviewer by e2eCrates()
+
+const unquote = (text) => String(text).replace(/^(["'])(.*)\1$/, "$2");
+const escapeRegExp = (text) => String(text).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** A dotted TOML key split at the dots outside quotes: `target.'cfg(unix)'.dependencies` is three parts. */
+const tomlPath = (text) => [...String(text).matchAll(/"([^"]*)"|'([^']*)'|([^\s.'"]+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
+const tomlStrings = (text) => [...String(text).matchAll(/"([^"]*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2]);
+const uncomment = (line) => line.replace(/^\s*#.*$/, "").replace(/\s+#.*$/, "");
+
+/**
+ * What the end-to-end check reads from a Cargo manifest, literal values only: the package name, whether it holds a [workspace] and its
+ * members, exclude and default-members (null when it declares none), the dependencies of [dependencies], [dev-dependencies] and their [target.*] tables (inline, dotted-key and
+ * `[dependencies.name]` forms, each with optional, package and workspace), [workspace.dependencies] as key -> package, and the
+ * [[test]] and [[bin]] tables. Build dependencies are not dependencies of the tests.
+ */
+function parseCargoManifest(text) {
+  const manifest = { name: null, workspace: false, members: [], exclude: [], defaultMembers: null, dependencies: [], workspaceDependencies: new Map(), tests: [], bins: [] };
+  const entries = new Map();
+  const dependency = (table, key) => {
+    const id = `${table}\0${key}`;
+    if (!entries.has(id)) { const entry = { key, optional: false, package: undefined, workspace: false }; entries.set(id, entry); manifest.dependencies.push(entry); }
+    return entries.get(id);
+  };
+  const setAttribute = (entry, attribute, value) => {
+    if (attribute === "optional") entry.optional = entry.optional || value === "true";
+    else if (attribute === "package") entry.package = tomlStrings(value)[0] ?? entry.package;
+    else if (attribute === "workspace") entry.workspace = entry.workspace || value === "true";
+  };
+  const setInline = (entry, value) => {
+    if (/\boptional\s*=\s*true\b/.test(value)) entry.optional = true;
+    const renamed = /\bpackage\s*=\s*(?:"([^"]+)"|'([^']+)')/.exec(value);
+    if (renamed) entry.package = renamed[1] ?? renamed[2];
+    if (/\bworkspace\s*=\s*true\b/.test(value)) entry.workspace = true;
+  };
+  const lines = String(text ?? "").split("\n");
+  let section = { kind: "other" };
+  for (let i = 0; i < lines.length; i++) {
+    const line = uncomment(lines[i]);
+    const header = /^\s*(\[\[?)\s*(.+?)\s*\]\]?\s*$/.exec(line);
+    if (header) {
+      const parts = tomlPath(header[2]);
+      if (header[1] === "[[") {
+        const item = parts[0] === "test" || parts[0] === "bin" ? { name: undefined, path: undefined } : null;
+        if (item) manifest[parts[0] === "test" ? "tests" : "bins"].push(item);
+        section = item ? { kind: "target", item } : { kind: "other" };
+        continue;
+      }
+      const at = parts[0] === "dependencies" || parts[0] === "dev-dependencies" ? 0 : parts[0] === "target" && (parts[2] === "dependencies" || parts[2] === "dev-dependencies") ? 2 : -1;
+      if (parts[0] === "package" && parts.length === 1) section = { kind: "package" };
+      else if (parts[0] === "workspace") {
+        manifest.workspace = true;
+        section = parts.length === 1 ? { kind: "workspace" } : parts[1] === "dependencies" ? (parts.length === 2 ? { kind: "workspace-dependencies" } : { kind: "workspace-dependency", key: parts[2] }) : { kind: "other" };
+      } else if (at >= 0) section = parts.length === at + 1 ? { kind: "dependencies", table: parts.join(".") } : { kind: "dependency", table: parts.slice(0, at + 1).join("."), key: parts[at + 1] };
+      else section = { kind: "other" };
+      continue;
+    }
+    const kv = /^\s*("[^"]+"|'[^']+'|[A-Za-z0-9_-]+)(?:\s*\.\s*("[^"]+"|'[^']+'|[A-Za-z0-9_-]+))?\s*=\s*(.*?)\s*$/.exec(line);
+    if (!kv) continue;
+    const key = unquote(kv[1]);
+    const attribute = kv[2] === undefined ? undefined : unquote(kv[2]);
+    const value = kv[3];
+    switch (section.kind) {
+      case "package":
+        if (key === "name" && attribute === undefined) manifest.name = tomlStrings(value)[0] ?? null;
+        break;
+      case "workspace":
+        if ((key === "members" || key === "exclude" || key === "default-members") && attribute === undefined) {
+          let list = value;
+          if (list.startsWith("[")) while (!list.includes("]") && i + 1 < lines.length) list += ` ${uncomment(lines[++i])}`;
+          if (key === "default-members") manifest.defaultMembers = [...(manifest.defaultMembers ?? []), ...tomlStrings(list)];
+          else manifest[key].push(...tomlStrings(list));
+        }
+        break;
+      case "target":
+        if ((key === "name" || key === "path") && attribute === undefined) section.item[key] = tomlStrings(value)[0];
+        break;
+      case "dependencies":
+        if (attribute === undefined) setInline(dependency(section.table, key), value); else setAttribute(dependency(section.table, key), attribute, value);
+        break;
+      case "dependency":
+        if (attribute === undefined) setAttribute(dependency(section.table, section.key), key, value);
+        break;
+      case "workspace-dependencies":
+        if (attribute === undefined) manifest.workspaceDependencies.set(key, /\bpackage\s*=\s*(?:"([^"]+)"|'([^']+)')/.exec(value)?.slice(1).find(Boolean) ?? key);
+        else if (attribute === "package") manifest.workspaceDependencies.set(key, tomlStrings(value)[0] ?? key);
+        break;
+      case "workspace-dependency":
+        if (key === "package" && attribute === undefined) manifest.workspaceDependencies.set(section.key, tomlStrings(value)[0] ?? section.key);
+        else if (!manifest.workspaceDependencies.has(section.key)) manifest.workspaceDependencies.set(section.key, section.key);
+        break;
+      default:
+    }
+  }
+  return manifest;
+}
+
+/** A `[workspace] members` pattern (`crates/*`, `apps/**`, `./x`) as a regular expression over a posix path; a pattern that is no
+ * valid glob matches nothing (the rule must not throw on a manifest cargo would refuse). */
+function memberPattern(glob) {
+  const source = String(glob).replace(/^\.\//, "").replace(/\/+$/, "").split("**").map((part) => part.replace(/[.+^$(){}|\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*");
+  try { return new RegExp(`^${source}$`); } catch { return /$^/; }
+}
+
+/** True when the Rust source names a driver module of rightkit-qa through any of `names` (its crate identifier(s) in this package):
+ * `rightkit_qa::harness`, or a `use rightkit_qa::{...}` list with a driver module among its top-level items. Comments do not count. */
+function namesDriverModule(source, names) {
+  const text = source.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/\/\/[^\n]*/g, "");
+  for (const name of names) {
+    for (const m of text.matchAll(new RegExp(`(?<!\\w)${escapeRegExp(name)}\\s*::\\s*(\\{|[A-Za-z_]\\w*)`, "g"))) {
+      if (m[1] !== "{") { if (E2E_DRIVER_MODULES.has(m[1])) return true; continue; }
+      const list = braceBlock(text, m.index + m[0].length - 1).slice(1, -1);
+      let depth = 0, item = "";
+      const items = [];
+      for (const ch of list) {
+        if (ch === "{") depth += 1; else if (ch === "}") depth -= 1;
+        if (ch === "," && depth === 0) { items.push(item); item = ""; } else item += ch;
+      }
+      items.push(item);
+      if (items.some((it) => E2E_DRIVER_MODULES.has(/^\s*([A-Za-z_]\w*)/.exec(it)?.[1]))) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The Cargo layout of a tree and the end-to-end crates in it. `crates` are the end-to-end ones as { name, dir, tests, bins } (a
+ * package that depends on rightkit-qa not optionally and has a non-example .rs file naming one of its driver modules); `nameOnly`
+ * lists packages named like one (`*-e2e`, `qa-*`) that are not, for a reviewer: a name is not evidence.
+ */
+export function e2eCrates(root, files) {
+  const manifests = new Map();
+  for (const file of files.filter((f) => /(^|\/)Cargo\.toml$/.test(f) && scanned(f))) {
+    const text = readText(root, file);
+    if (text !== null) manifests.set(dirOf(file), parseCargoManifest(text));
+  }
+  /** The package directory a file belongs to: the nearest directory above it with a Cargo.toml, when that holds a [package]. */
+  const ownerOf = (file) => {
+    for (let dir = dirOf(file); ; dir = dirOf(dir)) {
+      const manifest = manifests.get(dir);
+      if (manifest) return manifest.name === null ? null : dir;
+      if (dir === ".") return null;
+    }
+  };
+  const packageOf = (dep, dir) => {
+    if (dep.package) return dep.package;
+    if (dep.workspace) {
+      for (let d = dir; ; d = dirOf(d)) {
+        const inherited = manifests.get(d)?.workspaceDependencies.get(dep.key);
+        if (inherited) return inherited;
+        if (d === ".") break;
+      }
+    }
+    return dep.key;
+  };
+  const identifiers = new Map(); // package dir -> how Rust code names rightkit-qa there (the key, with - as _)
+  for (const [dir, manifest] of manifests) {
+    if (manifest.name === null) continue;
+    const names = manifest.dependencies.filter((dep) => !dep.optional && packageOf(dep, dir) === "rightkit-qa").map((dep) => dep.key.replaceAll("-", "_"));
+    if (names.length) identifiers.set(dir, [...new Set(names)]);
+  }
+  const driving = new Set();
+  if (identifiers.size) {
+    for (const file of rustFiles(files)) {
+      const dir = ownerOf(file);
+      if (dir === null || !identifiers.has(dir) || driving.has(dir) || (dir === "." ? file : file.slice(dir.length + 1)).startsWith("examples/")) continue;
+      const text = readText(root, file);
+      if (text !== null && identifiers.get(dir).some((name) => text.includes(name)) && namesDriverModule(text, identifiers.get(dir))) driving.add(dir);
+    }
+  }
+  const crates = [...driving].sort().map((dir) => {
+    const manifest = manifests.get(dir);
+    const within = (file) => (dir === "." ? file : file.startsWith(`${dir}/`) ? file.slice(dir.length + 1) : null);
+    const tests = new Set(manifest.tests.map((t) => t.name).filter(Boolean));
+    const bins = new Set(manifest.bins.map((b) => b.name).filter(Boolean));
+    for (const file of files) {
+      const rel = within(file);
+      if (rel === null || !scanned(file) || ownerOf(file) !== dir) continue;
+      const test = /^tests\/([^/]+)(?:\.rs|\/main\.rs)$/.exec(rel);
+      if (test) tests.add(test[1]);
+      const bin = /^src\/bin\/([^/]+)(?:\.rs|\/main\.rs)$/.exec(rel);
+      if (bin) bins.add(bin[1]);
+      if (rel === "src/main.rs") bins.add(manifest.name);
+    }
+    return { name: manifest.name, dir, tests, bins };
+  });
+  const nameOnly = [...manifests].filter(([dir, m]) => m.name !== null && E2E_NAME_ONLY.test(m.name) && !driving.has(dir)).map(([, m]) => m.name).sort();
+  /** The end-to-end crates that are members of the workspace rooted at `wsDir`: its root package, and every crate that matches a
+   * `members` glob (or, with `defaultOnly`, the `default-members` list when there is one), is not under `exclude` and is not a workspace root
+   * itself (a nested [workspace] makes a crate its own root). */
+  const membersOf = (wsDir, { defaultOnly = false } = {}) => {
+    const ws = manifests.get(wsDir);
+    if (!ws?.workspace) return [];
+    // `defaultOnly`: what a bare `cargo test` in a virtual workspace selects, its default-members when it declares them, else every member.
+    const included = (defaultOnly && ws.defaultMembers !== null ? ws.defaultMembers : ws.members).map(memberPattern);
+    const excluded = ws.exclude.map((x) => String(x).replace(/^\.\//, "").replace(/\/+$/, ""));
+    return crates.filter((c) => {
+      if (c.dir === wsDir) return true;
+      const rel = wsDir === "." ? c.dir : c.dir.startsWith(`${wsDir}/`) ? c.dir.slice(wsDir.length + 1) : null;
+      return rel !== null && !manifests.get(c.dir).workspace && included.some((re) => re.test(rel)) && !excluded.some((x) => rel === x || rel.startsWith(`${x}/`));
+    });
+  };
+  return { crates, nameOnly, manifests, membersOf };
+}
+
+const CARGO_COMMAND = /(?<![\w-])((?:(?:rustright|rightkit)\s+)?cargo)\s+(?:\+\S+\s+)?(test|run|nextest)\b([^&;|`\n]*)/g;
+const CD_COMMAND = /(?<![\w./-])(?:cd|Set-Location)\s+(?:-(?:Path|LiteralPath)\s+)?("[^"]*"|'[^']*'|[^\s;&|)]+)/gi;
+const COMMENT_LINE = /^\s*(?:#|\/\/|\/?\*|;|::|REM\b)/i;
+const QA_RUNNER = /\brightkit-qa(?:\.exe)?\s+(?:run-tests|journeys\s+run)\b/;
+const NEXTEST_NO_TESTS = new Set("list archive show-config self help".split(" ")); // nextest subcommands that run no test
+const HISTORY_DOC = /^docs\/(?:archive|plans|provenance|handoff[^/]*)\/|(?:^|\/)(?:tasks|evidence)\/|(?:^|\/)(?:changelog|pending|status|state)\.md$/i;
+const HOOK_FILE = /(?:^|\/)(?:\.githooks|\.husky|githooks)\/(?!_\/)[^/]+/;
+const WORKFLOW_FILE = /^\.github\/(?:workflows\/[^/]+|actions\/.+\/action)\.ya?ml$/;
+const BUILD_FILE = /(?:^|\/)(?:Makefile|makefile|GNUmakefile|[Jj]ustfile|\.justfile)$|\.mk$/;
+const SCRIPT_FILE = /\.(?:sh|bash|zsh|ps1|psm1|bat|cmd|mjs|cjs|js|py)$/i;
+// A code span in running text that is only the cargo command (`cargo test`, `rustright cargo test`: no argument) names the command as often as it
+// tells a reader to run it ("`cargo test` unit tests: ...", "`cargo test` would hold the compile slot", "only CI runs `cargo test`", a list item
+// "`cargo test`: Rust unit tests"). It is a command line only where an imperative verb stands right before it in its clause and nothing in that
+// clause negates it: "Run `cargo test` before you push", not "Do not run `cargo test`". With an argument, in a fenced block, a script, a package.json
+// script, a recipe, a workflow step or a hook, the same words are a command line whatever stands around them.
+const INSTRUCTION_VERB = /\b(?:run|use|execute|invoke|call|type)[*_]*\s*$/i;
+const NEGATION = /\b(?:not|never|no longer|avoid|without|instead of|rather than)\b|n't\b/i;
+const instructsToRun = (before) => {
+  const clause = String(before ?? "").split(/[.;!?]\s+|:\s+/).pop();
+  return INSTRUCTION_VERB.test(clause) && !NEGATION.test(clause);
+};
+
+/** The physical lines ({ no, text }) of a PowerShell script with its `<# ... #>` block comments blanked, line numbers kept. A block opens only
+ * where `<#` is the first thing on a line, so a `<#` met after code (in a string, say) never hides what follows it; code after the `#>` that
+ * closes a block on the same line is kept. */
+function withoutPowerShellBlockComments(lines) {
+  let inBlock = false;
+  return lines.map(({ no, text }) => {
+    let rest = text;
+    for (;;) {
+      if (!inBlock) {
+        const open = /^\s*<#/.exec(rest);
+        if (!open) break;
+        inBlock = true;
+        rest = rest.slice(open[0].length);
+      }
+      const end = rest.indexOf("#>");
+      if (end < 0) { rest = ""; break; }
+      inBlock = false;
+      rest = rest.slice(end + 2);
+    }
+    return { no, text: rest };
+  });
+}
+
+/** A script's `cd` / `Set-Location` target applied to `cwd` (a posix path from the repository root). A target that is not a plain
+ * relative path (a variable, a substitution, an absolute path, one that leaves the repository) leaves the directory as it was: the
+ * `cd "$(dirname "$0")/.."` of a script under scripts/ is the repository root, where a script starts. */
+function changeDirectory(cwd, target) {
+  const t = unquote(target);
+  if (!t || /[$`(%~]/.test(t) || /^([\\/]|[A-Za-z]:)/.test(t) || t === "-") return cwd;
+  const next = path.posix.normalize(path.posix.join(cwd, t.replaceAll("\\", "/")));
+  return next === ".." || next.startsWith("../") ? cwd : next;
+}
+
+/** The logical lines of physical `lines` ({ no, text }): comment lines dropped, and a line that ends with `continuation` joined to the
+ * next, numbered by the line the command starts on. */
+function logicalLines(lines, continuation) {
+  const out = [];
+  let pending = null;
+  for (const line of lines) {
+    if (!pending && COMMENT_LINE.test(line.text)) continue;
+    const text = line.text.replace(/\s+$/, "");
+    const joined = pending ? `${pending.text} ${text.trim()}` : text;
+    const no = pending?.no ?? line.no;
+    if (continuation && text.endsWith(continuation)) { pending = { no, text: joined.slice(0, -continuation.length) }; continue; }
+    pending = null;
+    out.push({ no, text: joined });
+  }
+  if (pending) out.push(pending);
+  return out;
+}
+
+/** The `run:` steps of a GitHub workflow or composite action: { lines, cwd } where cwd is the step's working-directory (the
+ * repository root when it has none, or one that is an expression). */
+function workflowSteps(text) {
+  const lines = text.split("\n");
+  const indent = (l) => l.length - l.trimStart().length;
+  const steps = [];
+  lines.forEach((raw, i) => {
+    const m = /^(\s*)(-\s+)?run:\s*(.*?)\s*$/.exec(raw);
+    if (!m) return;
+    const keyColumn = m[1].length + (m[2]?.length ?? 0);
+    const value = m[3];
+    let block;
+    if (/^[|>][+-]?\d*(?:\s+#.*)?$/.test(value)) {
+      block = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === "") continue;
+        if (indent(lines[j]) <= keyColumn) break;
+        block.push({ no: j + 1, text: lines[j].trim() });
+      }
+      // A folded scalar (`>`) is one line to the shell.
+      if (value.startsWith(">") && block.length) block = [{ no: block[0].no, text: block.map((l) => l.text).join(" ") }];
+    } else {
+      const plain = /^(["'])(.*)\1$/.test(value) ? unquote(value) : value.replace(/\s+#.*$/, "");
+      block = plain ? [{ no: i + 1, text: plain }] : [];
+    }
+    // The step's own working-directory sits beside `run:` (same column), on either side of it.
+    const sibling = (j) => { const k = /^(\s*)(-\s+)?working-directory:\s*(.*?)\s*$/.exec(lines[j]); return k && k[1].length + (k[2]?.length ?? 0) === keyColumn ? unquote(k[3].replace(/\s+#.*$/, "")) : null; };
+    let directory = null;
+    for (let j = i - 1; j >= 0 && directory === null; j--) {
+      if (lines[j].trim() === "") continue;
+      directory = sibling(j);
+      if (indent(lines[j]) < keyColumn) break;
+    }
+    for (let j = i + 1; j < lines.length && directory === null; j++) {
+      if (lines[j].trim() === "") continue;
+      if (indent(lines[j]) < keyColumn) break;
+      directory = sibling(j);
+    }
+    steps.push({ lines: block, cwd: directory === null ? "." : changeDirectory(".", directory) });
+  });
+  return steps;
+}
+
+/** The command-bearing units of a runbook document: each fenced code block ({ lines }) and each inline code span ({ lines: one line, inline, before: the
+ * text before it on its line }). Prose outside code is never a command. */
+function markdownUnits(text) {
+  const units = [];
+  let fence = null;
+  text.split("\n").forEach((raw, i) => {
+    if (fence) {
+      const close = /^\s*(`{3,}|~{3,})\s*$/.exec(raw);
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length) { units.push({ lines: fence.lines }); fence = null; } else fence.lines.push({ no: i + 1, text: raw });
+      return;
+    }
+    const open = /^\s*(`{3,}|~{3,})/.exec(raw);
+    if (open) { fence = { char: open[1][0], length: open[1].length, lines: [] }; return; }
+    for (const span of raw.matchAll(/(`+)(.+?)\1(?!`)/g)) units.push({ lines: [{ no: i + 1, text: span[2].trim() }], inline: true, before: raw.slice(0, span.index) });
+  });
+  if (fence) units.push({ lines: fence.lines });
+  return units;
+}
+
+// G22: see the block comment above.
+function e2eUnderCargoTest({ root, files }) {
+  const layout = e2eCrates(root, files);
+  if (!layout.crates.length) return [];
+  const out = [];
+  const seen = new Set();
+  const flagValues = (tokens, ...names) => tokens.flatMap((t, i) => names.flatMap((name) => (t === name ? (i + 1 < tokens.length ? [tokens[i + 1]] : []) : name.startsWith("--") && t.startsWith(`${name}=`) ? [t.slice(name.length + 1)] : [])));
+  /** The directory of the manifest a --manifest-path names (relative to the cwd, then to the repository root), when it holds one. */
+  const manifestDirectory = (value, cwd) => {
+    const base = value.replaceAll("\\", "/").replace(/(^|\/)Cargo\.toml$/, "") || ".";
+    if (path.posix.isAbsolute(base) || /^[A-Za-z]:/.test(base)) return null;
+    for (const from of [cwd, "."]) {
+      const dir = path.posix.normalize(path.posix.join(from, base));
+      if (dir !== ".." && !dir.startsWith("../") && layout.manifests.has(dir)) return dir;
+    }
+    return null;
+  };
+  /** The nearest directory at or above `cwd` that holds a Cargo.toml, as cargo finds the manifest with no --manifest-path; null when none. */
+  const nearestManifestDirectory = (cwd) => {
+    for (let dir = cwd; ; dir = dirOf(dir)) {
+      if (layout.manifests.has(dir)) return dir;
+      if (dir === "." || dir === "") return null;
+    }
+  };
+  /**
+   * The end-to-end crates a cargo command selects, each with the flag that did it: [{ crate, selector, wide, manifestPath }], first rule first.
+   * `wide` marks a selection of a whole workspace (--workspace / --all, or a bare test run in a virtual workspace), whose fix is to leave the crate
+   * out of the run; `manifestPath` is the --manifest-path the selection went through, if any.
+   */
+  const selected = (tokens, verb, cwd) => {
+    const isRun = verb === "run";
+    const picks = new Map();
+    const pick = (crate, selector, how = {}) => { if (!picks.has(crate)) picks.set(crate, { selector, ...how }); };
+    const packages = flagValues(tokens, "--package", "-p");
+    const manifestPaths = flagValues(tokens, "--manifest-path");
+    const tests = flagValues(tokens, "--test");
+    const wholeWorkspace = tokens.includes("--workspace") || tokens.includes("--all");
+    const excluded = new Set(flagValues(tokens, "--exclude"));
+    const guardOnly = tests.length > 0 && tests.every((t) => t === E2E_GUARD_TARGET); // `--test qa_surface_guard` runs the static guard only
+    const members = (dir, defaultOnly = false) => layout.membersOf(dir, { defaultOnly }).filter((c) => !excluded.has(c.name));
+    if (!guardOnly) {
+      for (const p of packages) for (const c of layout.crates.filter((crate) => crate.name === p)) pick(c, `-p ${p}`);
+      for (const mp of manifestPaths) {
+        const dir = manifestDirectory(mp, cwd);
+        if (dir === null) continue;
+        for (const c of layout.crates.filter((crate) => crate.dir === dir)) pick(c, `--manifest-path ${mp}`, { manifestPath: mp });
+        if (wholeWorkspace) for (const c of members(dir)) pick(c, `--manifest-path ${mp} ${tokens.includes("--workspace") ? "--workspace" : "--all"}`, { wide: true, manifestPath: mp });
+      }
+      if (wholeWorkspace && !manifestPaths.length) for (const c of members(cwd)) pick(c, tokens.includes("--workspace") ? "--workspace" : "--all", { wide: true });
+      // No -p, no --workspace, no named target: in a virtual workspace (a [workspace] with no [package]) cargo tests every member, or the
+      // default-members when it declares them. GenRight's `rustright cargo test --manifest-path Cargo.toml`, its root a virtual workspace that holds
+      // genright-e2e, names no crate and no flag, and runs the end-to-end crate in the broker all the same. A root with a package of its own tests
+      // that package only, so it selects nothing here (the limit below). `cargo run` needs a target, which --bin/-p already select.
+      const targeted = tests.length > 0 || flagValues(tokens, "--bin", "--example", "--bench").length > 0;
+      if (!isRun && !packages.length && !wholeWorkspace && !targeted) {
+        for (const [dir, mp] of manifestPaths.length ? manifestPaths.map((m) => [manifestDirectory(m, cwd), m]) : [[nearestManifestDirectory(cwd), null]]) {
+          const manifest = dir === null ? undefined : layout.manifests.get(dir);
+          if (!manifest?.workspace || manifest.name !== null) continue;
+          for (const c of members(dir, true)) pick(c, mp === null ? "" : `--manifest-path ${mp}`, { wide: true, ...(mp === null ? {} : { manifestPath: mp }) });
+        }
+      }
+    }
+    if (!packages.length && !manifestPaths.length) {
+      for (const t of tests) {
+        const owners = t === E2E_GUARD_TARGET ? [] : layout.crates.filter((c) => c.tests.has(t));
+        if (owners.length === 1) pick(owners[0], `--test ${t}`);
+      }
+    }
+    if (isRun) for (const b of flagValues(tokens, "--bin")) for (const c of layout.crates.filter((crate) => crate.bins.has(b))) pick(c, `--bin ${b}`);
+    return [...picks].map(([crate, how]) => ({ crate, ...how }));
+  };
+  /**
+   * What to do about a finding. The test binary of `cargo test` / `nextest` is compiled with --no-run and run by rightkit-qa outside the broker; a
+   * workspace-wide run must also leave the crate out (a --no-run on the whole workspace compiles it all and tests none). `cargo run` has no --no-run:
+   * the program is built in the broker and the built binary runs outside it.
+   */
+  const fixFor = (crate, verb, tokens, { wide, manifestPath }) => {
+    if (verb === "run") {
+      const named = flagValues(tokens, "--bin").find((b) => crate.bins.has(b));
+      const bin = named ?? (crate.bins.size === 1 ? [...crate.bins][0] : "<bin>");
+      return `build it in the broker (rustright cargo build${manifestPath === undefined ? "" : ` --manifest-path ${manifestPath}`} -p ${crate.name} --bin ${bin}) and run the built binary outside the broker (or rightkit-qa journeys run)`;
+    }
+    const runner = `rightkit-qa run-tests -p ${crate.name} [--test <target>] -- <libtest args>`;
+    return wide
+      ? `leave it out of the workspace run (--workspace --exclude ${crate.name}), compile it with --no-run and run it outside the broker: ${runner}`
+      : `compile it with --no-run and run it outside the broker: ${runner}`;
+  };
+  /** Scan logical lines ({ no, text }) that run in order from `cwd`; `what` names the place and `subject` overrides the crate name in the identity. */
+  const scan = (file, lines, cwd, what, subject, span = null) => {
+    for (const { no, text } of lines) {
+      if (!/cargo|\bcd\b|Set-Location/i.test(text)) continue; // a line with neither a command nor a directory change cannot matter
+      const events = [...text.matchAll(CD_COMMAND)].map((m) => ({ at: m.index, cd: m[1] })).concat([...text.matchAll(CARGO_COMMAND)].map((m) => ({ at: m.index, m })));
+      for (const event of events.sort((a, b) => a.at - b.at)) {
+        if (event.cd !== undefined) { cwd = changeDirectory(cwd, event.cd); continue; }
+        const [, client, verb] = event.m;
+        // A command inside a string literal ends at the quote that closes it: `run("rustright cargo test -p x")`.
+        let rest = event.m[3];
+        for (const quote of ['"', "'"]) {
+          if ((rest.split(quote).length - 1) % 2 === 1 && (text.slice(0, event.at).split(quote).length - 1) % 2 === 1) rest = rest.slice(0, rest.indexOf(quote));
+        }
+        const tokens = (rest.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((t) => t.replace(/["']/g, "").replace(/\)+$/, ""));
+        const ownArguments = tokens.indexOf("--") < 0 ? tokens : tokens.slice(0, tokens.indexOf("--"));
+        const segment = text.slice(Math.max(text.lastIndexOf("&", event.at), text.lastIndexOf(";", event.at), text.lastIndexOf("|", event.at), text.lastIndexOf("`", event.at)) + 1, event.at + event.m[0].length);
+        // A code span in running text that is only the command is a mention unless it is told to be run (INSTRUCTION_VERB).
+        if (span && tokens.length === 0 && text.trim() === event.m[0].trim() && !instructsToRun(span.before)) continue;
+        if (ownArguments.includes("--no-run") || QA_RUNNER.test(segment)) continue;
+        if (ownArguments.some((t) => t === "--help" || t === "-h" || t === "--version" || t === "-V")) continue;
+        if (verb === "nextest" && NEXTEST_NO_TESTS.has(tokens[0])) continue;
+        for (const { crate, selector, wide, manifestPath } of selected(ownArguments, verb, cwd)) {
+          const key = `${file}\0${no}\0${crate.name}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          const via = [client.replace(/\s+/g, " "), verb, selector].filter(Boolean).join(" ");
+          out.push({ file, subject: subject ?? crate.name, problem: `${file}:${no} ${what} runs the end-to-end crate ${crate.name} under cargo test (${via}): the test binary runs in the broker's context and holds its compile slot for the whole run`, fix: fixFor(crate, verb, ownArguments, { wide, manifestPath }) });
+        }
+      }
+    }
+  };
+  for (const { file, text, manifest } of packageManifests(root, files)) {
+    for (const [name, command] of Object.entries(manifest.scripts)) {
+      if (typeof command === "string") scan(file, [{ no: scriptLine(text, name), text: command }], dirOf(file), `script "${name}"`, name);
+    }
+  }
+  for (const file of files.filter(scanned)) {
+    const base = path.posix.basename(file);
+    const runbook = (file === "README.md" || file === "AGENTS.md" || file === "CLAUDE.md" || /^docs\/.+\.md$/.test(file)) && !HISTORY_DOC.test(file) && !/\d{4}-\d{2}-\d{2}/.test(base);
+    const workflow = WORKFLOW_FILE.test(file);
+    const hook = !workflow && HOOK_FILE.test(file);
+    const recipe = !workflow && !hook && BUILD_FILE.test(file);
+    const script = !workflow && !hook && !recipe && SCRIPT_FILE.test(file);
+    if (!(runbook || workflow || hook || recipe || script) || base === "package.json") continue;
+    const content = readText(root, file);
+    if (content === null || !/cargo/.test(content)) continue;
+    const continuation = /\.(?:ps1|psm1)$/i.test(file) ? "`" : /\.(?:bat|cmd)$/i.test(file) ? "^" : "\\";
+    const physical = content.split("\n").map((line, i) => ({ no: i + 1, text: line }));
+    if (workflow) for (const step of workflowSteps(content)) scan(file, logicalLines(step.lines, continuation), step.cwd, "workflow step");
+    else if (runbook) for (const unit of markdownUnits(content)) scan(file, logicalLines(unit.lines, continuation), ".", "runbook command", undefined, unit.inline ? unit : null);
+    else scan(file, logicalLines(/\.(?:ps1|psm1)$/i.test(file) ? withoutPowerShellBlockComments(physical) : physical, continuation), ".", hook ? "git hook" : recipe ? "recipe" : "command");
+  }
+  return out;
+}
+
 export const RULES = Object.freeze([
   { id: "eol-policy", gap: "G04", run: eolPolicy },
   { id: "file-url", gap: "G12", run: fileUrls },
@@ -416,6 +1079,18 @@ export const RULES = Object.freeze([
   { id: "ffmpeg-release-escape", gap: "G19", run: ffmpegReleaseEscape },
   { id: "switches-inventory", gap: "G20", run: switchesInventory },
   { id: "speech-link", gap: "G21", run: speechLink },
+  { id: "e2e-under-cargo-test", gap: "G22", run: e2eUnderCargoTest },
+  { id: "suite-key-literal", gap: "C3-04", run: ({ root, files }) => suiteKeyLiteral(root, files) },
+  { id: "suite-updater-key", gap: "C3-14", run: ({ root, files }) => suiteUpdaterKey(root, files) },
+  { id: "engine-record-store", gap: "C3-05", run: ({ root, files }) => engineRecordStore(root, files) },
+  ...SHELL_CONTRACT_RULES,
+  ...CONSUMER_CONTRACT_RULES,
+  ...CONSUMER_INPUT_RULES,
+  ...CONSUMER_SOURCE_RULES,
+  ...LEGION_SEMANTIC_RULES,
+  ...CONSUMER_POLICY_RULES,
+  ...SOURCE_CLOSURE_RULES,
+  ...OWNERSHIP_CLASS_RULES,
 ]);
 
 // ---- export: the committed files, by git alone ----------------------------------------------------------------------------------
@@ -510,14 +1185,14 @@ export function resolveCommit(repo, rev) {
 }
 
 /** Run the selected rules over an exported tree. Returns { failures: [{ rule, gap, problem, fix, file?, subject?, identity? }], timings }. */
-export function runRules({ root, commit, files, repo = process.cwd(), only = null, rules = RULES }) {
+export function runRules({ root, commit, files, repo = process.cwd(), only = null, rules = RULES, now = new Date() }) {
   const failures = [];
   const timings = [];
   for (const rule of rules) {
     if (only && !only.includes(rule.id)) continue;
     const started = Date.now();
     let found;
-    try { found = rule.run({ root, commit, files, repo }); }
+    try { found = rule.run({ root, commit, files, repo, now }); }
     catch (error) { found = [{ problem: `the rule itself failed: ${error.message}` }]; }
     timings.push({ rule: rule.id, ms: Date.now() - started, failures: found.length });
     for (const f of found) failures.push({ rule: rule.id, gap: rule.gap, ...f, ...(f.file && f.subject !== undefined ? { identity: `${rule.id}|${f.file}|${f.subject}` } : {}) });
@@ -659,7 +1334,7 @@ export function runAppCheck({ repo, mode = "commit", commit, only = null, baseli
     return finish(2);
   }
   try {
-    const { failures: found } = runRules({ root, commit: checked, files, repo, only, rules });
+    const { failures: found } = runRules({ root, commit: checked, files, repo, only, rules, now });
     if (printBaseline) {
       lines.push(JSON.stringify([...new Set(found.map((f) => f.identity).filter(Boolean))].sort(), null, 2));
       const unkeyed = found.filter((f) => !f.identity).length;
@@ -740,6 +1415,7 @@ export const BUILD_REFUSES = Object.freeze(["switches-inventory"]);
  * classification test in app-check.test.mjs, so a new command cannot appear unclassified. */
 export const UNCHECKED_COMMANDS = new Map([
   ["check", "is the check"],
+  ["update", "runs @rightkit/outdated over the app's RightKit pins (right-update); reads no release inputs and builds nothing"],
   ["deps", "the shared dependency lane: reads and updates dependency pins, not the app's release inputs"],
   ["hardening", "scans artifacts named on the command line; reads no source tree"],
   ["harden", "alias of hardening"],