@ionivetech/mugiwara 0.7.0 → 0.8.1

package/scripts/gate-selftest.ts

@@ -6,6 +6,8 @@ import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync, unlinkSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { tmpdir } from 'node:os';
+import { gatesForLane } from '../src/policy.ts';
+import { budgetForLane } from '../src/cost.ts';
 
 const root = join(import.meta.dirname, '..');
 let passed = 0;
@@ -91,9 +93,11 @@ console.log('\nCost gate — measured vs stated index chars');
   const costFile = join(root, 'docs', 'concepts', 'cost.md');
   const original = readFileSync(costFile, 'utf8');
   try {
-    const drifted = original.replace(/\*\*Current:\*\* \d[\d,]* chars/, '**Current:** 1 chars');
-    if (drifted === original) {
-      console.log('  ⚠  "**Current:** N chars" pattern not found in cost.md — skipping');
+    const costPattern = /\*\*Current:\*\* \d[\d,]* chars/;
+    const drifted = original.replace(costPattern, '**Current:** 1 chars');
+    if (!costPattern.test(original) || drifted === original) {
+      console.error('✗ COST: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
       writeFileSync(costFile, drifted);
       assert('drifted stated index chars → exit 1', false, () => run('COST', 'bun scripts/validate-content.ts'));
@@ -134,12 +138,14 @@ if (!existsSync(savepointFile)) {
   const original = readFileSync(savepointFile, 'utf8');
   try {
     // reintroduce the D1 defect: read lane_prev with require() of a relative path
+    const d1Pattern = /PREV_JSON=\$\(node -e "try\{const fs=require\('fs'\);const s=JSON\.parse\(fs\.readFileSync\(process\.argv\[1\],'utf8'\)\);process\.stdout\.write\(JSON\.stringify\(\{mission:s\.mission\|\|'',lane:s\.lane\|\|'',peak:s\.lane_peak\|\|''\}\)\)\}catch\(e\)\{process\.stdout\.write\('\{\}'\)\}" "\$STATE_FILE" 2>\/dev\/null \|\| true\)/;
     const broken = original.replace(
-      /PREV_JSON=\$\(node -e "try\{const fs=require\('fs'\);const s=JSON\.parse\(fs\.readFileSync\(process\.argv\[1\],'utf8'\)\);process\.stdout\.write\(JSON\.stringify\(\{mission:s\.mission\|\|'',lane:s\.lane\|\|'',peak:s\.lane_peak\|\|''\}\)\)\}catch\(e\)\{process\.stdout\.write\('\{\}'\)\}" "\$STATE_FILE" 2>\/dev\/null \|\| true\)/,
+      d1Pattern,
       "PREV_JSON=$(node -e \"try{const s=require(process.argv[1]);process.stdout.write(JSON.stringify({mission:s.mission||'',lane:s.lane||'',peak:s.lane_peak||''}))}catch(e){process.stdout.write('{}')}\" \"$STATE_FILE\" 2>/dev/null || true)"
     );
-    if (broken === original) {
-      console.log('  ⚠  D1 mutation pattern not found — skipping');
+    if (!d1Pattern.test(original) || broken === original) {
+      console.error('✗ D1: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
       writeFileSync(savepointFile, broken);
       assert('broken LANE_PREV resolve → lane-integrity fails', false, () => run('D1', 'bun run test -- lane-integrity -t "lane_prev"'));
@@ -158,12 +164,14 @@ if (!existsSync(savepointFile)) {
   const original = readFileSync(savepointFile, 'utf8');
   try {
     // neuter the clamp: make lane_rank always return 0 so a drop never holds
+    const d2Pattern = /lane_rank\(\) \{\n  case "\$1" in\n    direct\) echo 0 ;;[\s\S]*?\n  esac\n\}/;
     const broken = original.replace(
-      /lane_rank\(\) \{\n  case "\$1" in\n    direct\) echo 0 ;;[\s\S]*?\n  esac\n\}/,
+      d2Pattern,
       'lane_rank() {\n  echo 0\n}'
     );
-    if (broken === original) {
-      console.log('  ⚠  D2 mutation pattern not found — skipping');
+    if (!d2Pattern.test(original) || broken === original) {
+      console.error('✗ D2: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
       writeFileSync(savepointFile, broken);
       assert('broken clamp → lane-integrity fails', false, () => run('D2', 'bun run test -- lane-integrity -t "clamp"'));
@@ -183,12 +191,14 @@ if (!existsSync(patternsFile)) {
   const original = readFileSync(patternsFile, 'utf8');
   try {
     // reintroduce the D3 defect: singular-only list (no payments/, migrations/)
+    const d3Pattern = /SENSITIVE_PATS=.*/;
     const broken = original.replace(
-      /SENSITIVE_PATS=.*/,
+      d3Pattern,
       'SENSITIVE_PATS="auth/|payment/|billing/|crypto/|secrets/|\\.env$|config/.*key|migration/|\\.sql$|schema\\.|\\.prisma$|\\.terraform|\\.tf$"'
     );
-    if (broken === original) {
-      console.log('  ⚠  D3 mutation pattern not found — skipping');
+    if (!d3Pattern.test(original) || broken === original) {
+      console.error('✗ D3: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
       writeFileSync(patternsFile, broken);
       assert('singular sensitive patterns → lane-integrity fails', false, () => run('D3', 'bun run test -- lane-integrity -t "payments"'));
@@ -218,10 +228,12 @@ if (!existsSync(patternsFile)) {
     const live = original.match(/SENSITIVE_PATS="([^"]+)"/)?.[1] ?? '';
     const broken = live.split('|').filter(t => !D3B_FAMILY_TOKENS.has(t)).join('|');
     const brokenLine = `SENSITIVE_PATS="${broken}"`;
-    if (broken === live || !live) {
-      console.log('  ⚠  D3b: no D3 family tokens found in live SENSITIVE_PATS — skipping');
+    const d3bPattern = /SENSITIVE_PATS="[^"]*"/;
+    if (!d3bPattern.test(original) || broken === live || !live) {
+      console.error('✗ D3b: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
-      writeFileSync(patternsFile, original.replace(/SENSITIVE_PATS="[^"]*"/, brokenLine));
+      writeFileSync(patternsFile, original.replace(d3bPattern, brokenLine));
       assert('missing new categories → lane-integrity fails', false, () => run('D3b', 'bun run test -- lane-integrity -t "sensitive-paths"'));
     }
   } finally {
@@ -238,12 +250,14 @@ if (!existsSync(savepointFile)) {
   const original = readFileSync(savepointFile, 'utf8');
   try {
     // revert to delta-based (0 on deletions/refactors)
+    const d4Pattern = /LOC_TOKENS=\$\(\( LOC_CHURN \* 12 \)\)/;
     const broken = original.replace(
-      /LOC_TOKENS=\$\(\( LOC_CHURN \* 12 \)\)/,
+      d4Pattern,
       'LOC_TOKENS=$(( LOC_DELTA > 0 ? LOC_DELTA * 12 : 0 ))'
     );
-    if (broken === original) {
-      console.log('  ⚠  D4 mutation pattern not found — skipping');
+    if (!d4Pattern.test(original) || broken === original) {
+      console.error('✗ D4: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
       writeFileSync(savepointFile, broken);
       assert('zero churn tokens → lane-integrity fails', false, () => run('D4', 'bun run test -- lane-integrity -t "churn"'));
@@ -263,12 +277,14 @@ if (!existsSync(savepointFile)) {
   try {
     // silently drop the continue writer block (make it a no-op). Anchor on the
     // D10 header comment so the regex hits the writer, not the STATE_FILE if.
+    const d10Pattern = /# --- continue.*\(D10\): machine-written resume point ---[\s\S]*?\nfi\n\n/;
     const broken = original.replace(
-      /# --- continue\/<mission>\/<member>\.json \(D10\): machine-written resume point ---[\s\S]*?\nfi\n\n/,
+      d10Pattern,
       '# --- continue writer disabled (D10) ---\n\n'
     );
-    if (broken === original) {
-      console.log('  ⚠  D10 mutation pattern not found — skipping');
+    if (!d10Pattern.test(original) || broken === original) {
+      console.error('✗ D10: mutation target not found — the gate it guards may be dead.');
+      failed++;
     } else {
       writeFileSync(savepointFile, broken);
       assert('broken continue writer → savepoint fails', false, () => run('D10', 'bun run test -- savepoint -t "D10"'));
@@ -578,6 +594,26 @@ console.log('\nT7 — evidence-thin gate');
   }
 }
 
+// --- Benchmark governor — tamper thresholds, prove harness goes red ---
+console.log('\nBenchmark governor — thresholds tamper');
+{
+  const threshFile = join(root, 'scripts', 'benchmark-thresholds.json');
+  if (!existsSync(threshFile)) {
+    console.log('  ⚠  benchmark-thresholds.json not found, skipping');
+  } else {
+    const original = readFileSync(threshFile, 'utf8');
+    try {
+      const data = JSON.parse(original);
+      data.workloads = data.workloads.map((w: Record<string, unknown>) => ({ ...w, projected: 0, overhead: 0 }));
+      writeFileSync(threshFile, JSON.stringify(data, null, 2));
+      assert('tampered thresholds → benchmark-governor fails', false, () => run('bench', 'bun scripts/benchmark-governor.ts'));
+    } finally {
+      writeFileSync(threshFile, original);
+      assert('restored → benchmark-governor passes', true, () => run('bench', 'bun scripts/benchmark-governor.ts'));
+    }
+  }
+}
+
 // --- DOCLINKS: a relative .md link that does not resolve must fail the gate ---
 console.log('\nDOCLINKS — doc link resolution');
 {
@@ -592,5 +628,52 @@ console.log('\nDOCLINKS — doc link resolution');
   }
 }
 
+// --- T3: lane-aware gates — direct 3 steps, full 12 steps ---
+console.log('\nT3 — lane-aware gates');
+{
+  const policyFile = join(root, 'src', 'policy.ts');
+  const originalPolicy = readFileSync(policyFile, 'utf8');
+  try {
+    assert('direct lane → 3 steps', true, () => gatesForLane('direct').length === 3);
+    assert('direct lane includes typecheck+build', true, () => {
+      const s = gatesForLane('direct');
+      return s.includes('typecheck') && s.includes('build');
+    });
+    assert('lean lane → 6 steps with validate-content', true, () => {
+      const s = gatesForLane('lean');
+      return s.length === 6 && s.includes('validate-content');
+    });
+    assert('standard lane → 9 steps', true, () => gatesForLane('standard').length === 9);
+    assert('full lane → 12 steps with evals/retrieval/conformance', true, () => {
+      const s = gatesForLane('full');
+      return s.length === 12 && s.includes('run-evals') && s.includes('retrieval-eval') && s.includes('conformance');
+    });
+    assert('budget direct → 0, full → 50000', true, () => budgetForLane('direct') === 0 && budgetForLane('full') === 50000);
+    assert('budget spike → 3000 (direct fixture 3k)', true, () => budgetForLane('spike') === 3000);
+    // mutation: break direct step count → should fail (file content shows not 3)
+    const broken = originalPolicy.replace(
+      "direct: ['build-hooks:check', 'typecheck', 'build']",
+      "direct: ['typecheck']"
+    );
+    if (broken !== originalPolicy) {
+      writeFileSync(policyFile, broken);
+      assert('broken direct gate → not 3 steps', false, () => readFileSync(policyFile, 'utf8').includes("direct: ['build-hooks:check', 'typecheck', 'build']"));
+    } else {
+      console.error('✗ T3: mutation target not found — the gate it guards may be dead.');
+      failed++;
+    }
+  } finally {
+    writeFileSync(policyFile, originalPolicy);
+    assert('restored → direct 3 steps', true, () => {
+      const txt = readFileSync(policyFile, 'utf8');
+      return txt.includes("direct: ['build-hooks:check', 'typecheck', 'build']");
+    });
+  }
+  assert('full still includes conformance (conformance 71→74)', true, () => {
+    const txt = readFileSync(policyFile, 'utf8');
+    return txt.includes("'conformance'") && txt.includes("full:");
+  });
+}
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/lane-base.sh

@@ -7,10 +7,10 @@
 # LANE_BASE: token estimate for skills/agents loaded in this lane. Derived
 # from content word-sums × 1.35 (see scripts/lane-base.ts). spike is a
 # resize, not a rise — small base, tiny budget.
-LANE_BASE_lean=7000
-LANE_BASE_standard=13000
-LANE_BASE_full=23000
-LANE_BASE_spike=1000
+LANE_BASE_lean=8421
+LANE_BASE_standard=13325
+LANE_BASE_full=22016
+LANE_BASE_spike=5411
 
 # BUDGET: warn at 1.5×, stop at 3×.
 BUDGET_lean=12000

package/scripts/retrieval-eval.ts

@@ -93,14 +93,20 @@ interface Probe {
 // --- build index ---
 const index = buildIndex();
 
-// --- load cases ---
+// --- load cases (root + retrieval/ subdir for per-skill probes) ---
 const skills = readdirSync(skillsDir).filter(d => statSync(join(skillsDir, d)).isDirectory());
-const files = readdirSync(evalsDir).filter(f => f.endsWith('.json'));
+const rootCases = readdirSync(evalsDir).filter(f => f.endsWith('.json'));
+const retrievalDir = join(evalsDir, 'retrieval');
+const retrievalCases = existsSync(retrievalDir)
+  ? readdirSync(retrievalDir).filter(f => f.endsWith('.json')).map(f => join('retrieval', f))
+  : [];
+const files = [...rootCases, ...retrievalCases];
 const probes: Probe[] = [];
 const noSkillProbes: Probe[] = [];
 const covered = new Set<string>();
 
-for (const f of files) {
+for (const rel of files) {
+  const f = rel.includes('/') ? rel : rel;
   let c: CaseFile;
   try {
     c = JSON.parse(readFileSync(join(evalsDir, f), 'utf8'));

package/scripts/savepoint.sh

@@ -331,6 +331,13 @@ if [ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ]; then
   TASKS_TOTAL=$(grep -cE '^\s*-\s*\[[ xX]\]' "$PLAN_FILE" 2>/dev/null || true)
   TASKS_DONE=$(grep -c '\[x\]' "$PLAN_FILE" 2>/dev/null || true)
 fi
+# Fallback for large campaigns (>3 phases, >1500 lines) where master plan.md is an index
+# and tasks live in sub-plan/*.md — only when plan.md has zero checkbox tasks to
+# keep simple missions unchanged.
+if [ "${TASKS_TOTAL:-0}" -eq 0 ] 2>/dev/null && [ -d "$MISSION_DIR/sub-plan" ]; then
+  TASKS_TOTAL=$(grep -rcE '^\s*-\s*\[[ xX]\]' "$MISSION_DIR/sub-plan" 2>/dev/null | awk -F: '{s+=$2} END {print s+0}' || true)
+  TASKS_DONE=$(grep -rc '\[x\]' "$MISSION_DIR/sub-plan" 2>/dev/null | awk -F: '{s+=$2} END {print s+0}' || true)
+fi
 
 # blocker count
 BLOCKERS_FILE="$MISSION_DIR/blockers.md"
@@ -365,6 +372,32 @@ if [ "$HEAL_CYCLE" -ge "$HEAL_MAX_CYCLES" ] 2>/dev/null; then
   HEAL_HALT=true
 fi
 
+# slop — context (repeated reads) per cost-governor §§21-24,31-32 — T5 wire all crews Luffy/Nami/Zoro/Brook
+REPEATED_READS=0
+REPEATED_THRESHOLD=3
+REGISTRY_FILE="$MISSION_DIR/context-registry.jsonl"
+if [ -f "$REGISTRY_FILE" ]; then
+  REPEATED_READS=$(node -e "try{const fs=require('fs');const t=fs.readFileSync(process.argv[1],'utf8');let s=0;for(const l of t.split(/\r?\n/)){if(!l.trim())continue;try{const e=JSON.parse(l);if(typeof e.reads==='number'&&e.reads>=2)s+=Math.floor(e.reads)-1}catch{}}console.log(s)}catch(e){console.log(0)}" "$REGISTRY_FILE" 2>/dev/null || echo 0)
+  REPEATED_READS=$(( ${REPEATED_READS:-0} + 0 ))
+fi
+# repeated_reads > threshold → context slop — crew must skip re-read/compress before dispatch (§22,31); heal_cycle≥max → halt/escalate (§21.7/32) — cost-governor §§20,21-24
+
+# depth flags — advisory → measured (roadmap v0.8 item 4). Read from config
+# like the other keys; computed into state.json so enforcement is a fact the
+# gates flow stage can read, not prose.
+DEPTH_REVIEW="full"; DEPTH_QUALITY="full"; DEPTH_VERIFY="off"
+if [ -f "$MUGIWARA_DIR/config" ]; then
+  _cfg_r=$(grep -E '^review_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$_cfg_r" ] && DEPTH_REVIEW="$_cfg_r"
+  _cfg_q=$(grep -E '^quality_depth=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$_cfg_q" ] && DEPTH_QUALITY="$_cfg_q"
+  _cfg_v=$(grep -E '^verify_merged=' "$MUGIWARA_DIR/config" 2>/dev/null | head -1 | cut -d= -f2- | tr -d '[:space:]')
+  [ -n "$_cfg_v" ] && DEPTH_VERIFY="$_cfg_v"
+fi
+case "$DEPTH_REVIEW" in full|standard|lean) ;; *) DEPTH_REVIEW="full" ;; esac
+case "$DEPTH_QUALITY" in full|standard|lean) ;; *) DEPTH_QUALITY="full" ;; esac
+case "$DEPTH_VERIFY" in on|off) ;; *) DEPTH_VERIFY="off" ;; esac
+
 # evidence paths — the mission's flow folder (quoted printf, no sed — mission
 # name is allowlisted above, but avoid sed metacharacter semantics entirely).
 # New missions use flows/; a legacy mission that already keeps waves/ stays on
@@ -498,13 +531,18 @@ const data = {
   heal_halt: process.argv[34] === 'true',
   delegate_threshold: parseInt(process.argv[35], 10) || 60,
   delegate_due: process.argv[36] === 'true',
+  review_depth: process.argv[38] || 'full',
+  quality_depth: process.argv[39] || 'full',
+  verify_merged: process.argv[40] || 'off',
   tokens_est: parseInt(process.argv[17], 10) || 0,
   tokens_source: process.argv[26] || 'computed',
   budget: parseInt(process.argv[18], 10) || 0,
   budget_status: process.argv[19],
   skill_version: process.argv[20],
   evidence: process.argv[21] ? process.argv[21].split(',').filter(Boolean) : [],
-  updated_at: process.argv[22]
+  updated_at: process.argv[22],
+  schema_version: 2,
+  repeated_reads: parseInt(process.argv[41], 10) || 0
 };
 require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\n');
 " \
@@ -517,7 +555,8 @@ require('fs').writeFileSync(process.argv[23], JSON.stringify(data, null, 2) + '\
   "$STATE_FILE" "$LANE_PREV" "$LANE_ROSE" "$TOKENS_SOURCE" "$LANE_PEAK" \
   "$LOC_INS" "$LOC_DEL" "$LOC_CHURN" "$MEMBER" "$VERBOSITY" \
   "$HEAL_MAX_CYCLES" "$HEAL_HALT" "$DELEGATE_THRESHOLD" "$DELEGATE_DUE" \
-  "$MODEL"
+  "$MODEL" "$DEPTH_REVIEW" "$DEPTH_QUALITY" "$DEPTH_VERIFY" \
+  "$REPEATED_READS"
 
 if [ "$LANE_ROSE" = true ]; then
   echo "⚠ LANE ROSE: $LANE_PREV → $LANE ($LANE_REASON) — escalate per check-in protocol"

package/scripts/validate-content.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 // scripts/validate-content.ts
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join, basename, dirname } from 'node:path';
 import { parseFrontmatter } from '../src/frontmatter.ts';
 
 const root = join(import.meta.dirname, '..', 'content');
@@ -28,6 +28,25 @@ function checkFile(file: string, wantName: string, kind: 'skill' | 'agent'): Rec
     if (bullets.length > 4) errors.push(`skill ${file}: "## Skip when" block exceeds 4 bullets`);
   }
   if (kind === 'skill' && !body.includes('## Red flags')) errors.push(`skill ${file}: missing required "## Red flags" block`);
+  if (kind === 'skill') {
+    // gate_artifact (roadmap item 2): a declared artifact must name a
+    // verifiable path (flows/ mission evidence, plan.md, or a references/
+    // file that must actually exist beside the skill).
+    const ga = (data as Record<string, unknown>).gate_artifact;
+    if (ga !== undefined) {
+      const v = String(ga).trim();
+      if (!v) errors.push(`skill ${file}: gate_artifact declared but empty`);
+      else if (!/(flows\/|plan\.md|references\/)/.test(v)) {
+        errors.push(`skill ${file}: gate_artifact "${v}" must name a flows/, plan.md, or references/ path`);
+      } else {
+        const refMatch = v.match(/(references\/[\w./-]+\.md)/);
+        if (refMatch) {
+          const refPath = join(dirname(file), refMatch[1]);
+          if (!existsSync(refPath)) errors.push(`skill ${file}: gate_artifact references "${refMatch[1]}" but file does not exist`);
+        }
+      }
+    }
+  }
   if (kind === 'skill') {
     const lines = body.split(/\r?\n/);
     const headingRe = /^## /;
@@ -357,7 +376,7 @@ if (integrityArg !== -1) {
     const constants = readFileSync(src, 'utf8');
     const docs = ['docs/concepts/cost.md', 'docs/concepts/lanes.md', 'README.md'];
     const expected: [string, string][] = [
-      ['lean', '7,000'], ['standard', '13,000'], ['full', '23,000'],
+      ['lean', '8,000'], ['standard', '13,000'], ['full', '22,000'],
       ['lean', '12,000'], ['standard', '25,000'], ['full', '50,000'],
     ];
     for (const doc of docs) {
@@ -393,11 +412,71 @@ if (integrityArg !== -1) {
         }
       }
     }
-  if (!constants.includes('LANE_BASE_lean=7000')) errors.push('doc-integrity: source lane-base.sh lean base drifted (expected 7000)');
+  if (!constants.includes('LANE_BASE_lean=8421')) errors.push('doc-integrity: source lane-base.sh lean base drifted (expected 8421)');
   if (!constants.includes('BUDGET_full=50000')) errors.push('doc-integrity: source lane-base.sh full budget drifted (expected 50000)');
 }
 }
 
+// --- README metrics gate (D3): README table must match .metrics/latest.json ---
+if (process.argv.includes('--check-readme-metrics')) {
+  const metricsPath = join(import.meta.dirname, '..', '.metrics', 'latest.json');
+  if (!existsSync(metricsPath)) {
+    errors.push(`README metrics: ${metricsPath} not found — run bun scripts/write-metrics.ts`);
+  } else {
+    let metrics: any;
+    try { metrics = JSON.parse(readFileSync(metricsPath, 'utf8')); }
+    catch (e) { errors.push(`README metrics: invalid JSON in ${metricsPath}: ${e}`); }
+    if (metrics) {
+      const readmePath = join(import.meta.dirname, '..', 'README.md');
+      if (!existsSync(readmePath)) {
+        errors.push('README metrics: README.md not found');
+      } else {
+        const readme = readFileSync(readmePath, 'utf8');
+        // rank-1: **95.9%**, 216 probes
+        const rankMatch = readme.match(/Retrieval routing rank-1[^\n]*?(\d+\.\d+)%[^\n]*?(\d+)\s+probes/i);
+        if (!rankMatch) {
+          errors.push('README metrics: could not parse Retrieval routing rank-1 row (expected "**X.Y%**, N probes")');
+        } else {
+          const readmeRank = parseFloat(rankMatch[1]);
+          const readmeProbes = parseInt(rankMatch[2], 10);
+          const wantRank = Number(metrics.retrieval_rank1);
+          const wantProbes = Number(metrics.retrieval_probes);
+          if (Math.abs(readmeRank - wantRank) > 0.05) {
+            errors.push(`README metrics: rank-1 ${readmeRank}% != metrics ${wantRank}% (probes ${readmeProbes} vs ${wantProbes}) — run bun scripts/write-metrics.ts and update README`);
+          }
+          if (readmeProbes !== wantProbes) {
+            errors.push(`README metrics: probes ${readmeProbes} != metrics ${wantProbes} (rank ${readmeRank}% vs ${wantRank}%) — run bun scripts/write-metrics.ts and update README`);
+          }
+        }
+        // pointers: **286/286**, 9 targets (or tiers)
+        const ptrMatch = readme.match(/Reference pointers resolve[^\n]*?\*\*(\d+)\/(\d+)\*\*[^\n]*?(\d+)\s+(tiers|targets)/i);
+        if (!ptrMatch) {
+          errors.push('README metrics: could not parse Reference pointers row (expected "**N/N**, M targets")');
+        } else {
+          const a = parseInt(ptrMatch[1], 10);
+          const b = parseInt(ptrMatch[2], 10);
+          const count = parseInt(ptrMatch[3], 10);
+          const wantTotal = Number(metrics.pointers_total);
+          const wantTargets = Number(metrics.pointers_targets);
+          if (a !== wantTotal || b !== wantTotal) {
+            errors.push(`README metrics: pointers ${a}/${b} != metrics ${wantTotal}/${wantTotal} — run bun scripts/write-metrics.ts and update README`);
+          }
+          if (count !== wantTargets) {
+            errors.push(`README metrics: targets/tiers ${count} != metrics ${wantTargets} — run bun scripts/write-metrics.ts and update README (expected ${wantTargets} targets)`);
+          }
+        }
+        // sanity: table still claims "Nothing in this table is an estimate"
+        if (!readme.includes('Nothing in this table is an estimate')) {
+          errors.push('README metrics: missing "Nothing in this table is an estimate" line');
+        }
+        if (errors.filter(e => e.startsWith('README metrics:')).length === 0) {
+          console.log(`✓ README metrics match .metrics/latest.json (rank-1 ${metrics.retrieval_rank1}% ${metrics.retrieval_probes} probes, ${metrics.pointers_total}/${metrics.pointers_total} pointers, ${metrics.pointers_targets} targets)`);
+        }
+      }
+    }
+  }
+}
+
 // Conditional-assertion guard: an expect() reachable only inside a truthiness
 // check silently passes when the value is absent. This class produced 9 defects.
 // Allowed: checks keyed on a declared invariant (tier, fixture keys).

package/scripts/verify-install.ts

@@ -18,6 +18,7 @@ import { targets, TARGET_IDS } from '../src/targets/index.ts';
 
 const repoRoot = join(import.meta.dirname, '..');
 const fail: string[] = [];
+const isJson = process.argv.includes('--json');
 
 function findMd(root: string, out: string[] = []): string[] {
   if (!existsSync(root)) return out;
@@ -169,6 +170,25 @@ if (orphans.length > ORPHAN_BASELINE) {
 }
 
 // ---------------------------------------------------------------------------
+if (isJson) {
+  const payload = {
+    pointers_total: pointers,
+    pointers_targets: TARGET_IDS.length,
+    pointers_broken: brokenPointers,
+    prose_paths: prosePaths,
+    prose_files: proseFiles.length,
+    orphans,
+    orphans_count: orphans.length,
+    ref_files: refFiles.length,
+    targets: TARGET_IDS.length,
+    pointers: pointers,
+    broken_pointers: brokenPointers,
+  };
+  console.log(JSON.stringify(payload, null, 2));
+  if (fail.length) process.exit(1);
+  process.exit(0);
+}
+
 console.log(`  ${pointers} pointers checked across ${TARGET_IDS.length} targets`);
 console.log(`  ${prosePaths} prose paths checked in ${proseFiles.length} files`);
 console.log(`  ${orphans.length}/${refFiles.length} reference files unreachable (baseline ${ORPHAN_BASELINE})`);

package/scripts/write-metrics.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+// scripts/write-metrics.ts — generate .metrics/latest.json from gate outputs
+// Deterministic, no network. Runs retrieval-eval --json and verify-install --json.
+
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = join(import.meta.dirname, '..');
+
+function extractJson(output: string): any {
+  const idx = output.indexOf('{');
+  if (idx === -1) throw new Error('no JSON found in output: ' + output.slice(0, 200));
+  return JSON.parse(output.slice(idx));
+}
+
+function runJson(cmd: string): any {
+  // execSync returns stdout only; retrieval prints a rank line before JSON on stdout
+  // so we slice from first '{'
+  const out = execSync(cmd, { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  return extractJson(out);
+}
+
+// retrieval: need probes, rank1_rate, index_size
+let ret: any;
+let ver: any;
+try {
+  ret = runJson('bun scripts/retrieval-eval.ts --json');
+} catch (e: any) {
+  // if process exits non-zero, stdout still contains JSON + rank line; try to parse from error stdout
+  const out = e.stdout?.toString() ?? e.message ?? '';
+  if (out.includes('{')) ret = extractJson(out);
+  else throw e;
+}
+
+try {
+  ver = runJson('bun scripts/verify-install.ts --json');
+} catch (e: any) {
+  const out = e.stdout?.toString() ?? e.message ?? '';
+  if (out.includes('{')) ver = extractJson(out);
+  else throw e;
+}
+
+const rank1Str: string = ret.rank1_rate ?? ret.rank1 ?? '';
+const rank1Num = typeof rank1Str === 'string' ? parseFloat(rank1Str.replace('%', '')) : Number(rank1Str);
+const probes = ret.probes ?? ret.totalProbes ?? 0;
+const pointersTotal = ver.pointers_total ?? ver.pointers ?? 0;
+const pointersTargets = ver.pointers_targets ?? ver.targets ?? 0;
+const indexSize = ret.index_size ?? 0;
+const updated = new Date().toISOString().split('T')[0];
+
+const metrics = {
+  retrieval_rank1: rank1Num,
+  retrieval_rank1_rate: rank1Str,
+  retrieval_probes: probes,
+  retrieval_rank1_count: ret.rank1_count ?? null,
+  retrieval_positives: ret.positives ?? null,
+  retrieval_negatives: ret.negatives ?? null,
+  retrieval_index_size: indexSize,
+  retrieval_index_terms: ret.index_terms ?? null,
+  pointers_total: pointersTotal,
+  pointers_targets: pointersTargets,
+  pointers_broken: ver.pointers_broken ?? ver.broken_pointers ?? 0,
+  index_size: indexSize,
+  updated,
+};
+
+const outDir = join(root, '.metrics');
+mkdirSync(outDir, { recursive: true });
+const outPath = join(outDir, 'latest.json');
+writeFileSync(outPath, JSON.stringify(metrics, null, 2) + '\n');
+console.log(`✓ wrote ${outPath}`);
+console.log(JSON.stringify(metrics, null, 2));