ruvnet-brain 4.0.90-dev → 4.3.1-dev

package/scripts/ingest-new-repos.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * ingest-new-repos.mjs — load what rUv shipped, without being asked.
+ *
+ * THE GAP THIS CLOSES, and it is embarrassing rather than subtle. The owner asked on 2026-08-20
+ * why `ruvnet/ultrasonic` was not in the brain: *"aren't you loading everything Ruv creates every
+ * day?????"* The honest answer was no, and nothing ever had. `nightly-wrapper.sh` refreshed
+ * lessons, health, the release watchdog and the replay proof — and contained ZERO references to
+ * ingestion. New rUv repos only ever entered the brain when a human typed `ingest-repo.mjs` by
+ * hand, so the corpus drifted behind the org silently and the only symptom was a question the
+ * brain could not answer.
+ *
+ * `brain-stamp.mjs` already COMPUTES built-vs-pending every night. Nothing acted on it. Measuring
+ * a gap and never closing it is how 137 repos stayed uningested while the scorecard reported the
+ * number cheerfully.
+ *
+ * WHY IT IS BOUNDED. Ingestion embeds a whole repository; doing 137 in one night would run for
+ * hours and starve everything after it in the nightly. `--max` (default 3) keeps the nightly
+ * bounded and lets the corpus converge over days instead of blocking on one enormous run. That is
+ * a deliberate trade, and the run SAYS how many remain rather than implying it finished.
+ *
+ * WHAT IT WILL NOT DO. It does not write capability cards. An ingested store with no card is DARK —
+ * valid bytes that no by-description query can reach — and `ingest-repo.mjs` already says so on
+ * every run. Inventing a card from a repo name would put a confident description in the routing
+ * layer that nobody grounded in the source, which is worse than an honest gap: it would route real
+ * questions to a corpus that cannot answer them. So this reports the dark stores it created and
+ * leaves the card to someone who reads the repo.
+ *
+ *   node scripts/ingest-new-repos.mjs                 # report only
+ *   node scripts/ingest-new-repos.mjs --apply         # ingest up to --max new repos
+ *   node scripts/ingest-new-repos.mjs --apply --max 5
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+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';
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const OWNER = process.env.RUVNET_ORG_OWNER || 'ruvnet';
+const APPLY = process.argv.includes('--apply');
+const arg = (n, d) => {
+  const i = process.argv.indexOf(n);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d;
+};
+const MAX = Number(arg('--max', '3'));
+
+/** Every repo the org actually has right now. Live, never a remembered list. */
+function liveOrgRepos() {
+  try {
+    const out = execFileSync('gh', [
+      'repo', 'list', OWNER, '--limit', '500', '--no-archived', '--json', 'name,isFork,pushedAt,diskUsage',
+    ], { cwd: ROOT, encoding: 'utf8', maxBuffer: 1 << 26 });
+    return JSON.parse(out)
+      .filter((r) => !r.isFork)
+      // AN EMPTY REPO IS NOT A FAILURE TO RETRY FOREVER (measured 2026-08-20).
+      //
+      // The first bulk run reported 7 failures; six of them are size=0KB — genuinely empty
+      // repositories (socket, Auto-GPT, CodeGPT, ruvGPT2, rUvGPT, AIConverse). `git fetch` succeeds
+      // and there is simply nothing to embed, so ingestion fails correctly and then the repo stays
+      // "missing", so the NEXT night retries it, forever. A permanent nightly failure that is
+      // actually correct behaviour trains the reader to ignore the failure line — which is how a
+      // real failure would then hide inside it.
+      .filter((r) => Number(r.diskUsage ?? 1) > 0)
+      // Newest first: if the budget only allows a few tonight, spend it on what rUv shipped most
+      // recently, which is what a question is most likely to be about.
+      .sort((a, b) => String(b.pushedAt).localeCompare(String(a.pushedAt)))
+      .map((r) => r.name);
+  } catch (error) {
+    return { error: error?.message || String(error) };
+  }
+}
+
+export function pendingRepos(orgRepos, root = storeRoot()) {
+  const have = new Set(storesAt(root).map((s) => String(s).toLowerCase()));
+  return orgRepos.filter((name) => !have.has(String(name).toLowerCase()));
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  if (APPLY) {
+    try { assertIsolatedMutationWorktree(ROOT, 'ingest-new-repos --apply'); }
+    catch (error) { console.error(error?.message || String(error)); process.exit(2); }
+  }
+  const repos = liveOrgRepos();
+  if (!Array.isArray(repos)) {
+    // A LIST WE COULD NOT FETCH IS NOT AN EMPTY LIST. Reporting "0 new repos" here would read as
+    // "the brain is current" when the truth is "I could not look" — the exact conflation this
+    // repository keeps paying for.
+    console.error(`[ingest-new] could NOT list ${OWNER}'s repos: ${repos.error}`);
+    console.error('[ingest-new] this is NOT "nothing new" — it is "I could not look". Exiting 1.');
+    process.exit(1);
+  }
+
+  const root = storeRoot();
+  const missing = pendingRepos(repos, root);
+  console.log(`[ingest-new] ${OWNER}: ${repos.length} live repos, ${storesAt(root).length} ingested, ${missing.length} missing`);
+  if (!missing.length) { console.log('[ingest-new] corpus is level with the org.'); process.exit(0); }
+
+  console.log(`[ingest-new] next up (newest first): ${missing.slice(0, MAX).join(', ')}`);
+  if (!APPLY) {
+    console.log(`[ingest-new] report only. Re-run with --apply to ingest up to ${MAX}.`);
+    process.exit(0);
+  }
+
+  let done = 0; let failed = 0;
+  for (const name of missing.slice(0, MAX)) {
+    console.log(`\n[ingest-new] ingesting ${name}`);
+    const r = spawnSync(process.execPath, [path.join(ROOT, 'scripts', 'ingest-repo.mjs'), '--name', name],
+      { cwd: ROOT, stdio: 'inherit', env: process.env, timeout: 45 * 60_000 });
+    if (r.status === 0) done += 1;
+    else { failed += 1; console.log(`[ingest-new] ${name} FAILED — left missing so the next run retries it`); }
+  }
+
+  const stillMissing = missing.length - done;
+  const dark = darkStores(root);
+  console.log(`\n[ingest-new] ingested ${done}, failed ${failed}, ${stillMissing} still missing.`);
+  if (dark.length) {
+    console.log(`[ingest-new] ${dark.length} store(s) are DARK — valid bytes no by-description query can reach.`);
+    console.log('[ingest-new] a card is a claim about what a repo is FOR; write it from the source, not the name.');
+  }
+  process.exit(failed ? 1 : 0);
+}

package/scripts/metaharness-gate.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/** Compose measured MetaHarness read surfaces into one fail-closed gate. */
+import crypto from 'node:crypto';
+
+const REQUIRED_SCORE_FIELDS = Object.freeze(['harnessFit', 'compileConfidence', 'taskCoverage', 'toolSafety', 'memoryUsefulness']);
+function unwrap(value) { return value && value.data && typeof value.data === 'object' ? value.data : value; }
+function finite(value) { return typeof value === 'number' && Number.isFinite(value) ? value : null; }
+function severity(value) { const key = String(value ?? '').toLowerCase(); return ['clean', 'low', 'medium', 'high'].includes(key) ? key : null; }
+function digest(value) { return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+
+export function summarizeScore(input) {
+  const score = unwrap(input);
+  if (!score || score.degraded === true) return { status: 'unmeasured', degraded: true, reason: score?.reason || 'score unavailable' };
+  const dimensions = Object.fromEntries(REQUIRED_SCORE_FIELDS.map((key) => [key, finite(score[key])]));
+  const missing = REQUIRED_SCORE_FIELDS.filter((key) => dimensions[key] === null);
+  return { status: missing.length ? 'unmeasured' : 'measured', dimensions, missing, costPerRunUsd: finite(score.estCostPerRunUsd), recommendedMode: typeof score.recommendedMode === 'string' ? score.recommendedMode : null, scaffoldReady: typeof score.scaffoldReady === 'boolean' ? score.scaffoldReady : null };
+}
+
+export function summarizeAudit(input) {
+  const audit = unwrap(input);
+  const worst = severity(audit?.composite?.worst ?? audit?.worst);
+  const degraded = audit?.degraded === true || Object.values(audit?.components || {}).some((v) => v?.degraded === true);
+  return { status: worst ? 'measured' : 'unmeasured', worst, degraded, fingerprint: typeof audit?.fingerprint === 'string' ? audit.fingerprint : null };
+}
+
+export function summarizeDrift(input) {
+  const drift = unwrap(input);
+  const alert = typeof drift?.alert === 'boolean' ? drift.alert : null;
+  const verdict = typeof drift?.verdict === 'string' ? drift.verdict : null;
+  return { status: alert === null && !verdict ? 'unmeasured' : 'measured', alert, verdict, similarity: finite(drift?.similarity), reason: drift?.reason || null };
+}
+
+export function summarizeRoutingReceipts(rows = []) {
+  if (!Array.isArray(rows)) return { status: 'unmeasured', count: 0, costUsd: null, savedUsd: null };
+  const valid = rows.filter((r) => r && typeof r === 'object' && typeof r.model === 'string');
+  const withCost = valid.filter((r) => finite(r.est_cost) !== null);
+  const withSaved = valid.filter((r) => finite(r.saved) !== null);
+  return { status: valid.length ? 'measured' : 'unmeasured', count: valid.length, costUsd: withCost.length ? withCost.reduce((sum, r) => sum + r.est_cost, 0) : null, savedUsd: withSaved.length ? withSaved.reduce((sum, r) => sum + r.saved, 0) : null, unpriced: valid.length - withCost.length };
+}
+
+/** Read-only composition. `allowMetered` defaults false: readiness never authorizes spend. */
+export function buildGateReceipt({ score, audit, drift, routingReceipts = [], candidate = null, allowMetered = false, now = new Date().toISOString() } = {}) {
+  const measuredScore = summarizeScore(score), measuredAudit = summarizeAudit(audit), measuredDrift = summarizeDrift(drift), routing = summarizeRoutingReceipts(routingReceipts);
+  const reasons = [];
+  if (measuredScore.status !== 'measured') reasons.push('score is missing required measured dimensions');
+  if (measuredAudit.status !== 'measured') reasons.push('OIA audit has no measured composite severity');
+  if (measuredAudit.degraded) reasons.push('OIA audit is degraded');
+  if (measuredDrift.status !== 'measured') reasons.push('drift result is unmeasured');
+  if (measuredDrift.alert === true || /major|high|regress/i.test(measuredDrift.verdict || '')) reasons.push('drift is alerting');
+  if (measuredAudit.worst === 'high') reasons.push('OIA audit is high severity');
+  const ready = reasons.length === 0;
+  const candidateVerified = candidate?.bundle_verified === true && candidate?.data_source === 'SYNTHETIC';
+  const receipt = { schemaVersion: 1, kind: 'metaharness-gate', ts: now, score: measuredScore, audit: measuredAudit, drift: measuredDrift, routing, readiness: ready ? 'ready' : 'blocked', evolution: { allowed: ready && allowMetered === true, reason: ready ? (allowMetered ? 'measured preflight passed and metered spend explicitly allowed' : 'metered spend is disabled') : reasons.join('; ') }, promotion: { allowed: ready && candidateVerified, reason: !ready ? reasons.join('; ') : candidateVerified ? 'verified synthetic replay candidate' : 'candidate is absent or not a verified synthetic replay' } };
+  return { ...receipt, evidenceDigest: digest(receipt) };
+}
+
+export function assertEvolutionAllowed(receipt) { if (!receipt?.evolution?.allowed) throw new Error(`MetaHarness evolution blocked: ${receipt?.evolution?.reason || 'missing gate receipt'}`); return receipt; }
+export function assertPromotionAllowed(receipt) { if (!receipt?.promotion?.allowed) throw new Error(`MetaHarness promotion blocked: ${receipt?.promotion?.reason || 'missing gate receipt'}`); return receipt; }

package/scripts/nightly-gists.sh

@@ -10,9 +10,9 @@
 #   3. re-embed        — the expensive step (~18 min, 8 shards). SKIPPED ENTIRELY when step 2
 #                        reports "nothing to do". A quiet night costs seconds, not minutes.
 #
-# PATH is set explicitly: launchd does not inherit a login shell's environment, which is why the
-# sibling agent com.ruvnet.brain-nightly has been dying on `spawnSync gh ENOENT` — gh lives in
-# /opt/homebrew/bin and launchd never saw it.
+# PATH is set explicitly because launchd does not inherit a login shell's environment. The retired
+# com.ruvnet.brain-nightly source writer previously exposed this exact failure mode: gh lived in
+# /opt/homebrew/bin and launchd could not see it.
 
 set -eu
 

package/scripts/nightly-wrapper.sh

@@ -1,5 +1,9 @@
 #!/bin/bash
-# nightly-wrapper.sh — the ONLY thing launchd invokes for the nightly. Per Stuart's standing order
+# nightly-wrapper.sh — author-side maintenance, intentionally NOT a primary-checkout scheduler.
+# The old com.ruvnet.brain-nightly LaunchAgent invoked this in the primary checkout and accumulated
+# generated source changes beside active human work. That job is retired. The supported scheduled
+# updater is com.ruvnet.brain-update and mutates only the installed cache. If this author harness is
+# run manually, every source-writing command below requires a clean linked worktree.
 # (2026-07-12): no noise for success or no-op — only ACTIVE alerts for real failure, and the system
 # must attempt to self-heal before escalating, then make failure impossible to miss next session.
 #
@@ -7,26 +11,69 @@
 # class a blind retry can fix) -> if it fails AGAIN, loud phone alert + a durable marker file that
 # ground-ruvnet.sh surfaces at the top of the very next session, unprompted. Success or a legitimate
 # "nothing was due tonight" no-op: log only, phone stays silent.
+
+# WHICH NODE RUNS THIS DECIDES WHETHER TONIGHT'S WRITES SURVIVE (measured 2026-08-20).
+#
+# This file hardcoded "$NODE_BIN" in eight places. That is node v22.13.1 (ABI 127), and the
+# better-sqlite3 binding agentdb needs is built for ABI 137 — so under it agentdb SILENTLY falls
+# back to non-persistent sql.js and every write is lost. Silently, because better-sqlite3 is an
+# OPTIONAL dependency (ruvnet/ruflo#2219): the failure never errors and the CLI still prints a
+# success table. `lesson-bridge.mjs --apply` and `learning-replay.mjs` both write, so the nightly
+# was discarding its own results. Measured, same command, same DB, only the interpreter differing:
+#   "$NODE_BIN"   v22.13.1  ->  2 sql.js fallback msgs, DURABLE=NO
+#   /opt/homebrew/bin/node v24.18.0 ->  0 fallback msgs,        DURABLE=YES
+# Resolve a node whose ABI matches the binding, and fail loudly rather than silently losing data.
+NODE_BIN=""
+for _cand in /opt/homebrew/opt/node@24/bin/node /opt/homebrew/bin/node "$(command -v node 2>/dev/null)"; do
+  [ -x "$_cand" ] || continue
+  if [ "$("$_cand" -p 'process.versions.modules' 2>/dev/null)" = "137" ]; then NODE_BIN="$_cand"; break; fi
+done
+if [ -z "$NODE_BIN" ]; then
+  echo "[nightly] FATAL: no node with ABI 137 found — agentdb writes would silently not persist." >&2
+  echo "[nightly] checked: /opt/homebrew/opt/node@24/bin/node /opt/homebrew/bin/node \$(command -v node)" >&2
+  exit 1
+fi
+
 set -u
 # kb/models-cache (the fallback) starts cold every time -> every nightly re-downloads the ONNX
 # embedder from HuggingFace. Point at the already-warm cache instead (verified present).
 export KB_MODEL_CACHE="/Users/stuartkerr/Code/PowerPlatePulse/scripts/models-cache"
-cd /Users/stuartkerr/Code/ruvnet-brain 2>/dev/null || {
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd)
+WORKTREE_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." 2>/dev/null && pwd)
+cd "$WORKTREE_ROOT" 2>/dev/null || {
   curl -sS --max-time 10 -H "Title: 🔴 Nightly CRASHED before it could even start" \
     -H "Priority: urgent" -H "Tags: rotating_light" \
     -d "cd into the repo failed — filesystem or mount problem. Investigate the machine directly." \
     "https://ntfy.sh/$(grep -m1 '^NTFY_TOPIC=' /Users/stuartkerr/Code/ruvnet-brain/.env 2>/dev/null | cut -d= -f2)" >/dev/null 2>&1
   exit 1
 }
-mkdir -p logs .ruvnet-brain
-LOG=logs/nightly.log
-MARKER=.ruvnet-brain/nightly-failure.json
-LOCK=.ruvnet-brain/nightly.lock
-
-# Single-instance guard (2026-07-12): the plist has no built-in one. The updater is incremental now,
-# but a very large upstream change, a slow model, or a stalled gate can still outlive the window and
-# overlap the NEXT scheduled 3:15am fire. A stale lock from a crashed run (PID no longer alive) is
-# treated as no lock.
+GIT_COMMON_DIR=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || exit 1
+PRIMARY_ROOT=$(dirname "$GIT_COMMON_DIR")
+export RUVNET_PROJECT_MEMORY_DB="$PRIMARY_ROOT/.swarm/memory.db"
+mkdir -p "$PRIMARY_ROOT/logs" "$PRIMARY_ROOT/.ruvnet-brain"
+LOG="$PRIMARY_ROOT/logs/nightly.log"
+MARKER="$PRIMARY_ROOT/.ruvnet-brain/nightly-failure.json"
+LOCK="$PRIMARY_ROOT/.ruvnet-brain/nightly.lock"
+PRIMARY_SNAPSHOT=$(mktemp "${TMPDIR:-/tmp}/ruvnet-brain-primary-snapshot.XXXXXX") || exit 1
+if ! "$NODE_BIN" scripts/worktree-integrity.mjs snapshot "$WORKTREE_ROOT" > "$PRIMARY_SNAPSHOT"; then
+  rm -f "$PRIMARY_SNAPSHOT"
+  exit 2
+fi
+
+finish() {
+  rc=$?
+  trap - EXIT
+  rm -f "$LOCK"
+  if ! "$NODE_BIN" scripts/worktree-integrity.mjs verify "$WORKTREE_ROOT" "$PRIMARY_SNAPSHOT" >> "$LOG" 2>&1; then
+    echo "===== FATAL: primary checkout changed during isolated author maintenance =====" >> "$LOG"
+    rc=3
+  fi
+  rm -f "$PRIMARY_SNAPSHOT"
+  exit "$rc"
+}
+
+# Single-instance guard for explicit author invocations. A stale lock from a crashed run (PID no
+# longer alive) is treated as no lock.
 if [ -f "$LOCK" ]; then
   OLD_PID=$(cat "$LOCK" 2>/dev/null)
   if [ -n "$OLD_PID" ] && kill -0 "$OLD_PID" 2>/dev/null; then
@@ -38,26 +85,22 @@ if [ -f "$LOCK" ]; then
   echo "===== $(date -u +%FT%TZ) — stale lock from pid $OLD_PID (not running) — clearing =====" >> "$LOG"
 fi
 echo $$ > "$LOCK"
-trap 'rm -f "$LOCK"' EXIT
-
-# NIGHTLY_SMOKE=1 — prove this whole chain (launchd -> heartbeat wrapper -> here -> node -> the repo
-# scan -> the log) WITHOUT a multi-hour rebuild. self-update.mjs is dry-run by default, so dropping
-# --apply exercises every link except the build itself. Publication is never part of this job.
-# WHY IT EXISTS (2026-07-13): the 03:15 fire on 07-12 died before it could even write its own log
-# ("/bin/bash: logs/nightly.log: No such file or directory" — relative path, no working directory) and
-# NOBODY KNEW, because the only way to test this chain was to wait until 03:15 and hope. A scheduled job
-# you can only test by waiting for it is a job you are not testing. Now: `NIGHTLY_SMOKE=1 <the exact
-# plist command>` proves it on demand, any time, in seconds.
+trap finish EXIT
+
+# NIGHTLY_SMOKE=1 exercises the author harness and source planner without a multi-hour rebuild. It
+# still requires an isolated clean linked worktree: a diagnostic escape hatch must not reopen the
+# primary-checkout writer. Publication is never part of this job.
 SMOKE="${NIGHTLY_SMOKE:-0}"
+"$NODE_BIN" scripts/worktree-integrity.mjs "$WORKTREE_ROOT" "nightly author maintenance" >> "$LOG" 2>&1 || exit 2
 
 run_once() {
   local rc
   { echo "===== nightly-wrapper rebuild attempt $1 — $(date -u +%FT%TZ) ====="
     if [ "$SMOKE" = "1" ]; then
       echo "[SMOKE] dry-run: exercising the full chain, NOT building"
-      /usr/local/bin/node scripts/self-update.mjs --fresh-window 60
+      "$NODE_BIN" scripts/self-update.mjs --fresh-window 60
     else
-      /usr/local/bin/node scripts/self-update.mjs --apply --fresh-window 60
+      "$NODE_BIN" scripts/self-update.mjs --apply --fresh-window 60
     fi
   } >> "$LOG" 2>&1
   rc=$?
@@ -75,13 +118,42 @@ run_once() {
   return 0
 }
 
+# Prepare the source candidate before any optional evidence refresh that writes tracked artifacts.
+# Otherwise learning-replay dirties the isolated lane first and self-update correctly refuses it.
+if run_once 1; then
+  if [ "$SMOKE" = "1" ]; then exit 0; fi
+else
+  echo "===== first attempt failed — waiting 3 min, retrying once (self-heal for transient issues) =====" >> "$LOG"
+  sleep 180
+  if run_once 2; then
+    echo "===== SELF-HEALED on retry — no escalation needed =====" >> "$LOG"
+  else
+    # Both attempts genuinely failed. Escalate loudly AND leave a marker the next session cannot miss.
+    AFTER=$(gh release view --json tagName -q .tagName 2>/dev/null || echo "unknown")
+    TAIL=$(tail -25 "$LOG" | tr '\n' ' ' | cut -c1-2000)
+    mkdir -p "$(dirname "$MARKER")"
+    python3 -c "
+import json, datetime
+json.dump({
+  'at': datetime.datetime.utcnow().isoformat() + 'Z',
+  'last_release_tag_observed': '$AFTER',
+  'tail': '''$TAIL''',
+  'note': 'Author candidate rebuild failed twice (immediate + 3min retry). See logs/nightly.log.'
+}, open('$MARKER', 'w'), indent=2)
+"
+    sh scripts/notify.sh "🔴 Author candidate rebuild FAILED twice" "candidate rebuild failed; last release remains $AFTER. Last: $TAIL" urgent "rotating_light"
+    echo "===== ESCALATED: marker written at $MARKER =====" >> "$LOG"
+    exit 1
+  fi
+fi
+
 # Memory distillation (ADR-174) had gone stale 3 days — same silent-death pattern as everything
 # else tonight. Independent of rebuild success/failure: mine raw memory_entries into structured
 # episodes/reasoning_patterns on every nightly run. Best-effort, never blocks the real job.
-RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory distill run --path .swarm/memory.db >> "$LOG" 2>&1 || true
+RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory distill run --path "$RUVNET_PROJECT_MEMORY_DB" >> "$LOG" 2>&1 || true
 # Durability: was a one-off manual snapshot before tonight. Now recurring — WAL-safe, rotates
 # automatically (keeps last 14), zero risk to the live DB (reads only).
-RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory backup --db .swarm/memory.db --keep 14 >> "$LOG" 2>&1 || true
+RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory backup --db "$RUVNET_PROJECT_MEMORY_DB" --keep 14 >> "$LOG" 2>&1 || true
 
 # LESSON BRIDGE (ADR-066, 2026-08-10) — carry newly-tagged machine-wide lessons into the store the
 # hooks actually read. Without this the bridge is a command someone has to remember, and a learning
@@ -93,7 +165,7 @@ RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory backup --db .swarm/memor
 # it REFUSES to apply when it reads zero rows while bridged lessons are installed — so a transient
 # read failure can never strip the store. Best-effort, never blocks the rebuild.
 echo "===== lesson-bridge — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node plugin/scripts/lesson-bridge.mjs --apply >> "$LOG" 2>&1 \
+"$NODE_BIN" plugin/scripts/lesson-bridge.mjs --apply >> "$LOG" 2>&1 \
   || echo "===== lesson-bridge: SKIPPED (see line above) =====" >> "$LOG"
 
 # AgentDB drift canary (2026-07-23, P7 wiring sweep) — scripts/memdb-health.sh existed unwired since
@@ -101,7 +173,7 @@ echo "===== lesson-bridge — $(date -u +%FT%TZ) =====" >> "$LOG"
 # while in WAL mode. Best-effort, same shape as its brain-health/key-health siblings below: never
 # blocks the real rebuild, just makes a WAL-mode/integrity regression loud instead of silent.
 echo "===== memdb-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
-sh scripts/memdb-health.sh .swarm/memory.db >> "$LOG" 2>&1 \
+sh scripts/memdb-health.sh "$RUVNET_PROJECT_MEMORY_DB" >> "$LOG" 2>&1 \
   && echo "===== memdb-health canary: OK =====" >> "$LOG" \
   || echo "===== memdb-health canary: UNHEALTHY (see line above) =====" >> "$LOG"
 
@@ -141,15 +213,15 @@ sh scripts/memdb-health.sh .swarm/memory.db >> "$LOG" 2>&1 \
 # REPORTS ONLY. It cannot push, merge, close or publish (asserted by test). Exit 1 means a human
 # needs to look, and the reasons print in full rather than as a count.
 echo "===== GITHUB-HEALTH watch — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node scripts/github-health-watch.mjs >> "$LOG" 2>&1 \
+"$NODE_BIN" scripts/github-health-watch.mjs >> "$LOG" 2>&1 \
   || echo "[github-health] findings above need attention" >> "$LOG"
 
 echo "===== RELEASE-CONVERGENCE watchdog — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node scripts/release-convergence-watchdog.mjs --dispatch >> "$LOG" 2>&1 \
+"$NODE_BIN" scripts/release-convergence-watchdog.mjs --dispatch >> "$LOG" 2>&1 \
   || echo "[release-watchdog] exited non-zero — see above; nightly continues" >> "$LOG"
 
 echo "===== LEARNING-REPLAY counterfactual trap — $(date -u +%FT%TZ) =====" >> "$LOG"
-/usr/local/bin/node scripts/learning-replay.mjs --n 3 --model haiku >> "$LOG" 2>&1
+"$NODE_BIN" scripts/learning-replay.mjs --n 3 --model haiku >> "$LOG" 2>&1
 LR_RC=$?
 case "$LR_RC" in
   0) echo "===== LEARNING-REPLAY: PASS =====" >> "$LOG" ;;
@@ -165,7 +237,7 @@ esac
 BRAIN_KB="$HOME/.cache/ruvnet-brain/kb"
 if [ -f "$BRAIN_KB/forge-ask-all.mjs" ]; then
   echo "===== brain-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
-  if (cd "$BRAIN_KB" && /usr/local/bin/node forge-ask-all.mjs --dir . --q "HNSW vector index" --k 1) >> "$LOG" 2>&1; then
+  if (cd "$BRAIN_KB" && "$NODE_BIN" forge-ask-all.mjs --dir . --q "HNSW vector index" --k 1) >> "$LOG" 2>&1; then
     echo "===== brain-health canary: OK =====" >> "$LOG"
   else
     echo "===== brain-health canary: DOWN — escalating =====" >> "$LOG"
@@ -181,39 +253,8 @@ fi
 # The canary itself handles urgent pushes on alive->DEAD transitions (and recovery notices), so a
 # known-dead key doesn't re-alarm every night; here we only log.
 echo "===== key-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
-zsh -lc 'cd /Users/stuartkerr/Code/ruvnet-brain && /usr/local/bin/node scripts/key-canary.mjs --notify' >> "$LOG" 2>&1 \
+zsh -lc 'cd "$1" && "$2" scripts/key-canary.mjs --notify' _ "$WORKTREE_ROOT" "$NODE_BIN" >> "$LOG" 2>&1 \
   && echo "===== key-health canary: all present keys alive =====" >> "$LOG" \
   || echo "===== key-health canary: at least one key DEAD (push sent on new deaths) =====" >> "$LOG"
 
-if run_once 1; then
-  exit 0
-fi
-
-echo "===== first attempt failed — waiting 3 min, retrying once (self-heal for transient issues) =====" >> "$LOG"
-sleep 180
-
-if run_once 2; then
-  echo "===== SELF-HEALED on retry — no escalation needed =====" >> "$LOG"
-  exit 0
-fi
-
-# Both attempts genuinely failed. Escalate loudly AND leave a marker the next session cannot miss.
-AFTER=$(gh release view --json tagName -q .tagName 2>/dev/null || echo "unknown")
-# Was `tail -8 | cut -c1-600`. self-update's [FATAL] block is 4+ lines on its own and now carries a
-# 'reason:' line per failed repo, so 8 lines / 600 chars truncated the alert mid-argv — every one of
-# the six identical 2026-08-03..08-06 failures escalated with no reason in it. Widen enough that the
-# whole [FATAL] block, reasons included, reaches the marker file and the push.
-TAIL=$(tail -25 "$LOG" | tr '\n' ' ' | cut -c1-2000)
-mkdir -p .ruvnet-brain
-python3 -c "
-import json, datetime
-json.dump({
-  'at': datetime.datetime.utcnow().isoformat() + 'Z',
-  'last_release_tag_observed': '$AFTER',
-  'tail': '''$TAIL''',
-  'note': 'Nightly failed twice (immediate + 3min retry). Needs a live session to diagnose — see logs/nightly.log.'
-}, open('$MARKER', 'w'), indent=2)
-"
-sh scripts/notify.sh "🔴 Nightly FAILED twice — needs you" "candidate rebuild failed; last release remains $AFTER. Last: $TAIL" urgent "rotating_light"
-echo "===== ESCALATED: marker written at $MARKER =====" >> "$LOG"
-exit 1
+exit 0

package/scripts/product-integrity-contract.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  buildSourceScopeReceipt,
+  canonicalJson,
+  digest,
+  validateSourceScopeReceipt,
+} from './source-scope-receipt.mjs';
+
+export const PRODUCT_INTEGRITY_SCHEMA_VERSION = 1;
+export const PRODUCT_INTEGRITY_TEST_CLASSES = Object.freeze(['essential', 'supporting', 'obsolete']);
+export const PRODUCT_INTEGRITY_PROOF_STRENGTH = Object.freeze(['unit', 'integration', 'packed-artifact', 'candidate-host', 'public-byte']);
+export const PRODUCT_INTEGRITY_PROCESSES = Object.freeze([
+  { id: 'SourceCoverage', upstream: [] }, { id: 'CorpusGeneration', upstream: ['SourceCoverage'] },
+  { id: 'ReleaseProjection', upstream: ['CorpusGeneration'] }, { id: 'RefreshLifecycle', upstream: ['ReleaseProjection'] },
+  { id: 'HostConvergence', upstream: ['ReleaseProjection'] }, { id: 'ReleaseTransaction', upstream: ['ReleaseProjection'] },
+  { id: 'PublicVerification', upstream: ['ReleaseTransaction', 'HostConvergence'] },
+  { id: 'ProductIntegrityCase', upstream: ['RefreshLifecycle', 'PublicVerification'] },
+]);
+export const PRODUCT_INTEGRITY_CONTEXTS = Object.freeze(PRODUCT_INTEGRITY_PROCESSES.map(({ id }) => id));
+const ARCHITECTURE = Object.freeze([
+  { id: 'ADR-072', path: 'docs/adr/0072-whole-product-integrity-conformance.md', status: 'Accepted' },
+  { id: 'DDD-0018', path: 'docs/ddd/0018-product-integrity-context.md', status: 'Accepted' },
+  { id: 'ADR-073', path: 'docs/adr/0073-agentdb-perennial-project-continuity.md', status: 'Accepted' },
+  { id: 'DDD-0019', path: 'docs/ddd/0019-project-continuity-context.md', status: 'Accepted' },
+  { id: 'ADR-074', path: 'docs/adr/0074-ruvnet-capability-claim-integrity.md', status: 'Accepted' },
+  { id: 'DDD-0020', path: 'docs/ddd/0020-capability-claim-integrity-context.md', status: 'Accepted' },
+]);
+const proofStrength = (file) => file.startsWith('tests/acceptance/') ? 'packed-artifact'
+  : file.startsWith('tests/integration/') ? 'integration' : file.startsWith('tests/qe/') ? 'candidate-host' : 'unit';
+const make = (id, statement, owner, contributors, implementation, tests, receiptKinds, supportingArchitecture = []) => Object.freeze({
+  id, statement, owner, contributors: Object.freeze(contributors),
+  architecture: Object.freeze(['ADR-072', 'DDD-0018', ...supportingArchitecture]),
+  implementation: Object.freeze(implementation), behaviors: Object.freeze([Object.freeze({
+    id: `${id}.essential`, class: 'essential', commands: Object.freeze(tests.map((file) => `npx vitest run ${file}`)),
+    positive: Object.freeze(tests.map((file) => Object.freeze({ file, strength: proofStrength(file) }))),
+    adversarial: Object.freeze(tests.map((file) => Object.freeze({ file, strength: proofStrength(file) }))),
+    receiptKinds: Object.freeze(receiptKinds),
+  })]),
+});
+export const PRODUCT_INTEGRITY_OBLIGATIONS = Object.freeze([
+  make('S-1', 'One complete public corpus', 'CorpusGeneration', ['SourceCoverage'], ['scripts/source-coverage.mjs', 'scripts/corpus-reconcile.mjs', 'scripts/corpus-candidate.mjs'], ['tests/unit/source-coverage.test.mjs', 'tests/unit/corpus-reconcile.test.mjs'], ['ruvnet-brain-source-observation', 'ruvnet-brain-corpus-candidate']),
+  make('S-2', 'One immutable public release projection', 'ReleaseProjection', ['CorpusGeneration'], ['scripts/build-bundle.mjs', 'scripts/coverage-integrity.mjs', 'scripts/public-inventory.mjs'], ['tests/integration/build-bundle-fence.test.mjs', 'tests/unit/public-inventory.test.mjs'], ['ruvnet-brain-release-coverage']),
+  make('S-3', 'Recall at 10 is at least 98 percent and delta citations are complete', 'PublicVerification', ['SourceCoverage', 'CorpusGeneration'], ['scripts/retrieval-canary.mjs', 'scripts/packed-retrieval-canary.mjs'], ['tests/unit/retrieval-canary.test.mjs', 'tests/unit/packed-retrieval-canary.test.mjs'], ['ruvnet-brain-retrieval-canary-plan', 'ruvnet-brain-retrieval-canary-receipt']),
+  make('S-4', 'Native nightly runs are ordered, idempotent, and retained within budget', 'RefreshLifecycle', [], ['bin/nightly-refresh.mjs', 'plugin/scripts/nightly-scheduler.mjs', 'scripts/nightly-two-run-proof.mjs', 'kb/refresh-run.mjs'], ['tests/unit/nightly-scheduler.test.mjs', 'tests/unit/nightly-two-run-proof.test.mjs'], ['ruvnet-brain-refresh-run', 'ruvnet-brain-native-two-run-nightly-proof']),
+  make('S-5', 'One active corpus preserves private stores and bounded recovery', 'RefreshLifecycle', ['CorpusGeneration'], ['kb/update-storage-transaction.mjs', 'kb/forge-update.mjs', 'kb/brain-profile.mjs', 'bin/install.mjs'], ['tests/unit/update-storage-transaction.test.mjs', 'tests/unit/brain-profile.test.mjs'], ['ruvnet-brain-update-storage-transaction', 'ruvnet-brain-installed-profile']),
+  make('S-6', 'Every supported OS and host loader converges on exact public bytes', 'HostConvergence', ['PublicVerification'], ['scripts/host-registry.mjs', 'scripts/host-install-matrix.mjs', 'scripts/public-verification-aggregate.mjs'], ['tests/unit/host-registry.test.mjs', 'tests/integration/dual-host-install.test.mjs'], ['ruvnet-brain-host-registry', 'ruvnet-brain-public-verification-leaf']),
+  make('S-7', 'Publication ends only after signed public verification', 'PublicVerification', ['ReleaseTransaction'], ['scripts/release-transaction.mjs', 'scripts/public-verification-finalizer.mjs', '.github/workflows/protected-release.yml'], ['tests/qe/release/release-transaction-faults.test.mjs', 'tests/unit/public-verification-finalizer.test.mjs'], ['ruvnet-brain-release-transaction-receipt', 'ruvnet-brain-public-verification-aggregate']),
+  make('S-8', 'Accepted architecture has one executable owner and source-bound trace', 'ProductIntegrityCase', [], ['scripts/product-integrity-contract.mjs', 'scripts/source-scope-receipt.mjs'], ['tests/unit/product-integrity-contract.test.mjs', 'tests/unit/source-scope-receipt.test.mjs'], ['ruvnet-brain-product-integrity-contract', 'ruvnet-brain-product-integrity-trace']),
+  make('S-9', 'Every essential behavior has positive and adversarial proof', 'ProductIntegrityCase', [], ['scripts/product-integrity-contract.mjs', 'scripts/adr-072-completion.mjs'], ['tests/unit/product-integrity-contract.test.mjs', 'tests/unit/adr-072-completion.test.mjs'], ['ruvnet-brain-product-integrity-trace', 'ruvnet-brain-adr-072-completion']),
+  make('S-10', 'Fable 5 and GPT-5.6-Sol review identical immutable inputs', 'ProductIntegrityCase', ['PublicVerification'], ['scripts/public-verification-aggregate.mjs', '.github/workflows/protected-release.yml'], ['tests/unit/public-verification-aggregate.test.mjs', 'tests/unit/protected-release-workflow.test.mjs'], ['ruvnet-brain-independent-review', 'ruvnet-brain-public-verification-aggregate']),
+  make('S-11', 'Project continuity is complete and host-neutral', 'ProductIntegrityCase', ['HostConvergence', 'RefreshLifecycle'], ['plugin/scripts/project-progression-contract.mjs', 'plugin/scripts/project-progression-hook.mjs'], ['tests/unit/project-progression-contract.test.mjs', 'tests/acceptance/cross-host-project-resume.test.mjs'], ['ruvnet-brain-project-progression', 'ruvnet-brain-cross-host-resume'], ['ADR-073', 'DDD-0019']),
+  make('S-12', 'RuvNet capability claims are bound to live evidence before delivery', 'ProductIntegrityCase', ['HostConvergence', 'PublicVerification'], [
+    'plugin/scripts/capability-inventory-receipt.mjs',
+    'plugin/scripts/capability-claim-evidence.mjs',
+    'plugin/scripts/continuation-gate.mjs',
+    'plugin/mcp/managed-cli-interface.mjs',
+    'kb/forge-evidence.mjs',
+  ], [
+    'tests/unit/capability-inventory-receipt.test.mjs',
+    'tests/unit/capability-claim-evidence.test.mjs',
+    'tests/unit/continuation-gate-capability-truth.test.mjs',
+    'tests/unit/managed-cli-interface.test.mjs',
+    'tests/unit/grounding-receipt-lanes.test.mjs',
+    'tests/acceptance/adr-074-packed-capability-claims.acceptance.test.mjs',
+  ], [
+    'ruvnet-brain-capability-inventory',
+    'ruvnet-brain-capability-claim-audit',
+    'ruvnet-brain-source-claim',
+    'ruvnet-brain-live-surface',
+    'ruvnet-brain-capability-claim-aggregate',
+  ], ['ADR-074', 'DDD-0020']),
+]);
+const IDS = Object.freeze(Array.from({ length: 12 }, (_, index) => `S-${index + 1}`));
+const safePath = (value) => typeof value === 'string' && value.length > 0 && !path.isAbsolute(value) && !value.split(/[\\/]/).includes('..');
+
+function validateProcesses(processes) {
+  if (!Array.isArray(processes) || canonicalJson(processes.map(({ id }) => id)) !== canonicalJson(PRODUCT_INTEGRITY_CONTEXTS)) throw new Error('product integrity contract must contain the exact eight processes');
+  const ids = new Set(processes.map(({ id }) => id)); const visiting = new Set(); const visited = new Set();
+  const visit = (id) => { if (visiting.has(id)) throw new Error('product integrity process graph contains a cycle'); if (visited.has(id)) return;
+    visiting.add(id); const row = processes.find((entry) => entry.id === id);
+    if (!Array.isArray(row?.upstream) || new Set(row.upstream).size !== row.upstream.length || row.upstream.some((upstream) => !ids.has(upstream) || upstream === id)) throw new Error(`${id} has invalid upstream processes`);
+    row.upstream.forEach(visit); visiting.delete(id); visited.add(id); };
+  processes.forEach(({ id }) => visit(id));
+}
+
+export function validateProductIntegrityContract(input = {}) {
+  const processes = Array.isArray(input) ? PRODUCT_INTEGRITY_PROCESSES : input.processes || PRODUCT_INTEGRITY_PROCESSES;
+  const obligations = Array.isArray(input) ? input : input.obligations || PRODUCT_INTEGRITY_OBLIGATIONS;
+  const architecture = input.architecture || ARCHITECTURE;
+  validateProcesses(processes);
+  if (!Array.isArray(architecture) || new Set(architecture.map(({ id }) => id)).size !== architecture.length || architecture.some((row) => row.status !== 'Accepted' || !safePath(row.path))) throw new Error('governing architecture is missing or not Accepted');
+  if (!Array.isArray(obligations) || canonicalJson(obligations.map(({ id }) => id)) !== canonicalJson(IDS)) throw new Error('product integrity obligations are missing, duplicated, or out of order');
+  const contexts = new Set(processes.map(({ id }) => id)); const architectureIds = new Set(architecture.map(({ id }) => id)); const behaviorIds = new Set();
+  for (const row of obligations) {
+    if (!contexts.has(row.owner)) throw new Error(`${row.id} has no valid sole owner`);
+    if (!Array.isArray(row.contributors) || new Set(row.contributors).size !== row.contributors.length || row.contributors.some((context) => !contexts.has(context)) || row.contributors.includes(row.owner)) throw new Error(`${row.id} has an invalid contributor`);
+    if (!Array.isArray(row.architecture) || row.architecture.some((id) => !architectureIds.has(id))) throw new Error(`${row.id} has missing architecture`);
+    if (!Array.isArray(row.implementation) || !row.implementation.length || row.implementation.some((file) => !safePath(file))) throw new Error(`${row.id} has no implementation`);
+    if (!Array.isArray(row.behaviors) || !row.behaviors.length) throw new Error(`${row.id} has no behaviors`);
+    for (const behavior of row.behaviors) {
+      if (!behavior.id || behaviorIds.has(behavior.id)) throw new Error(`${row.id} has duplicate behavior identity`); behaviorIds.add(behavior.id);
+      if (!PRODUCT_INTEGRITY_TEST_CLASSES.includes(behavior.class)) throw new Error(`${behavior.id} has invalid test class`);
+      if (behavior.class === 'essential') {
+        for (const field of ['commands', 'positive', 'adversarial', 'receiptKinds']) if (!Array.isArray(behavior[field]) || !behavior[field].length) throw new Error(`${behavior.id} has no ${field}`);
+        for (const proof of [...behavior.positive, ...behavior.adversarial]) if (!safePath(proof.file) || !PRODUCT_INTEGRITY_PROOF_STRENGTH.includes(proof.strength)) throw new Error(`${behavior.id} has invalid proof`);
+      }
+    }
+  }
+  return { schemaVersion: 1, kind: 'ruvnet-brain-product-integrity-contract', architecture,
+    processes: processes.map((row) => ({ ...row, owns: obligations.filter(({ owner }) => owner === row.id).map(({ id }) => id), contributes: obligations.filter(({ contributors }) => contributors.includes(row.id)).map(({ id }) => id) })), obligations };
+}
+
+export function productIntegrityGovernedPaths(contract = validateProductIntegrityContract()) {
+  return [...new Set([...contract.architecture.map(({ path: file }) => file), ...contract.obligations.flatMap(({ implementation, behaviors }) => [...implementation, ...behaviors.flatMap(({ positive, adversarial }) => [...positive, ...adversarial].map(({ file }) => file))])])].sort();
+}
+export function buildProductIntegrityTrace({ root = '.', sourceSha, contract = validateProductIntegrityContract(), inventory } = {}) {
+  if (!/^[a-f0-9]{40}$/.test(String(sourceSha || ''))) throw new Error('product integrity trace requires an exact source SHA');
+  const validated = validateProductIntegrityContract(contract);
+  const unsigned = { schemaVersion: 1, kind: 'ruvnet-brain-product-integrity-trace', sourceSha, contractSha256: digest(validated), sourceScope: buildSourceScopeReceipt({ root, sourceSha, governedPaths: productIntegrityGovernedPaths(validated), inventory }), contract: validated, verdict: 'PASS', untested: [] };
+  return { ...unsigned, traceSha256: digest(unsigned) };
+}
+export function validateProductIntegrityTrace(trace, { root = '.', sourceSha = trace?.sourceSha, inventory } = {}) {
+  const { traceSha256, ...unsigned } = trace || {};
+  if (trace?.schemaVersion !== 1 || trace?.kind !== 'ruvnet-brain-product-integrity-trace' || trace.sourceSha !== sourceSha || trace.verdict !== 'PASS' || canonicalJson(trace.untested) !== '[]' || trace.contractSha256 !== digest(trace.contract) || traceSha256 !== digest(unsigned)) throw new Error('product integrity trace identity is invalid');
+  validateSourceScopeReceipt(trace.sourceScope, { root, inventory });
+  const rebuilt = buildProductIntegrityTrace({ root, sourceSha, contract: trace.contract, inventory });
+  if (canonicalJson(rebuilt) !== canonicalJson(trace)) throw new Error('product integrity trace differs from the exact source');
+  return trace;
+}
+export function renderProductIntegrityTraceMarkdown(contract = validateProductIntegrityContract()) {
+  const lines = ['# ADR-072 generated traceability', '', '> Generated from `scripts/product-integrity-contract.mjs`; do not hand-edit.', '', '## Processes', '', '| Process | Upstream | Owns | Contributes |', '|---|---|---|---|'];
+  for (const row of contract.processes) lines.push(`| ${row.id} | ${row.upstream.join(', ') || '—'} | ${row.owns.join(', ') || '—'} | ${row.contributes.join(', ') || '—'} |`);
+  lines.push('', '## Obligations', '', '| ID | Statement | Owner | Contributors |', '|---|---|---|---|');
+  for (const row of contract.obligations) lines.push(`| ${row.id} | ${row.statement} | ${row.owner} | ${row.contributors.join(', ') || '—'} |`);
+  lines.push('', '## Essential behavior proofs', '', '| Behavior | Positive | Adversarial | Receipts |', '|---|---|---|---|');
+  for (const row of contract.obligations) for (const behavior of row.behaviors.filter(({ class: type }) => type === 'essential')) lines.push(`| ${behavior.id} | ${behavior.positive.map(({ file, strength }) => `${file} (${strength})`).join('<br>')} | ${behavior.adversarial.map(({ file, strength }) => `${file} (${strength})`).join('<br>')} | ${behavior.receiptKinds.join('<br>')} |`);
+  return `${lines.join('\n')}\n`;
+}
+const valueAfter = (argv, flag) => { const index = argv.indexOf(flag); return index >= 0 ? argv[index + 1] : null; };
+export function runProductIntegrityCli(argv = process.argv.slice(2), io = { stdout: process.stdout }) {
+  const known = new Set(['--markdown', '--check-markdown', '--trace', '--source-sha', '--out', '--verify-trace']);
+  if (argv.some((arg) => arg.startsWith('--') && !known.has(arg))) throw new Error('unknown product integrity argument');
+  if (!argv.length) { io.stdout.write(`${canonicalJson(validateProductIntegrityContract())}\n`); return 0; }
+  if (argv.length === 1 && argv[0] === '--markdown') { io.stdout.write(renderProductIntegrityTraceMarkdown()); return 0; }
+  const check = valueAfter(argv, '--check-markdown');
+  if (check) { if (fs.readFileSync(path.resolve(check), 'utf8') !== renderProductIntegrityTraceMarkdown()) throw new Error('generated traceability Markdown differs'); io.stdout.write('product integrity Markdown: PASS\n'); return 0; }
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); const sourceSha = valueAfter(argv, '--source-sha'); const out = valueAfter(argv, '--out');
+  if (argv.includes('--trace') && sourceSha && out) { fs.writeFileSync(path.resolve(out), `${canonicalJson(buildProductIntegrityTrace({ root, sourceSha }))}\n`, { flag: 'wx', mode: 0o600 }); return 0; }
+  const verify = valueAfter(argv, '--verify-trace');
+  if (verify && sourceSha) { const trace = JSON.parse(fs.readFileSync(path.resolve(verify), 'utf8')); validateProductIntegrityTrace(trace, { root, sourceSha }); io.stdout.write(`${canonicalJson({ verdict: 'PASS', traceSha256: trace.traceSha256 })}\n`); return 0; }
+  throw new Error('invalid product integrity argument combination');
+}
+if (path.resolve(process.argv[1] || '') === fileURLToPath(import.meta.url)) { try { process.exitCode = runProductIntegrityCli(); } catch (error) { console.error(`[product-integrity-contract] ${error.message}`); process.exitCode = 1; } }