thumbgate 1.16.3 → 1.16.5

package/public/guide.html

@@ -31,7 +31,7 @@
     "url": "https://thumbgate-production.up.railway.app"
   },
   "datePublished": "2026-03-27",
-  "dateModified": "2026-03-27",
+  "dateModified": "2026-04-25",
   "mainEntityOfPage": "https://thumbgate-production.up.railway.app/guide",
   "about": [
     {"@type": "Thing", "name": "AI coding agents"},
@@ -184,8 +184,23 @@
   .comparison-table td:first-child { font-weight: 600; }
   .cta { display: inline-block; background: var(--cyan); color: #000; padding: 0.75rem 1.5rem; border-radius: 8px; text-decoration: none; font-weight: 600; margin: 1rem 0; }
   .cta:hover { opacity: 0.9; }
+  .cta-secondary { background: transparent; color: var(--text); border: 1px solid var(--border); margin-left: 0.75rem; }
+  .cta-secondary:hover { border-color: var(--cyan); color: var(--cyan); }
   .breadcrumb { color: var(--muted); font-size: 0.85rem; margin-bottom: 0.5rem; }
   .breadcrumb a { color: var(--muted); }
+  .proof-links { display: grid; gap: 0.85rem; margin: 1.25rem 0 0; }
+  .proof-links a {
+    display: block;
+    padding: 0.9rem 1rem;
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    text-decoration: none;
+    color: var(--text);
+    background: #111113;
+  }
+  .proof-links a strong { color: var(--cyan); display: block; margin-bottom: 0.2rem; }
+  .proof-links a span { color: var(--muted); font-size: 0.95rem; }
+  .buyer-paths { margin-top: 1rem; }
   @media (max-width: 600px) { h1 { font-size: 1.6rem; } .container { padding: 1rem; } }
 </style>
 </head>
@@ -306,10 +321,39 @@ npx thumbgate init --agent gemini</code></pre>
 <h3>Agent uses wrong API endpoint</h3>
 <p>Give a thumbs-down: "called staging API in production code." The check blocks tool calls that reference staging URLs in production contexts.</p>
 
+<h2>When ThumbGate becomes a paid decision</h2>
+<p>Stay on the free install path while one operator is proving the workflow locally. The paid motion starts when a workflow owner asks for proof, shared enforcement, or a safer rollout path.</p>
+<div class="card buyer-paths">
+  <h3>Three honest next steps</h3>
+  <ul>
+    <li><strong>Free:</strong> use <code>npx thumbgate init</code> to prove one workflow on one machine.</li>
+    <li><strong>Pro:</strong> buy the self-serve lane only when you want a personal local dashboard, DPO export, and proof-ready workflow review for the next risky flow.</li>
+    <li><strong>Workflow Hardening Sprint:</strong> use the team intake path once one workflow, one owner, and one repeated failure are already clear.</li>
+  </ul>
+</div>
+
+<h2>Proof before a buyer says yes</h2>
+<p>The repo sales plan is proof-led, not hype-led. Commercial claims stay anchored to the current truth file, and engineering claims stay anchored to verification evidence and machine-readable proof reports.</p>
+<div class="proof-links">
+  <a href="https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/COMMERCIAL_TRUTH.md" target="_blank" rel="noopener">
+    <strong>Commercial Truth</strong>
+    <span>Current pricing, traction guardrails, and what the product can honestly claim today.</span>
+  </a>
+  <a href="https://github.com/IgorGanapolsky/ThumbGate/blob/main/docs/VERIFICATION_EVIDENCE.md" target="_blank" rel="noopener">
+    <strong>Verification Evidence</strong>
+    <span>Human-readable proof log for the engineering and workflow claims used across the site.</span>
+  </a>
+  <a href="https://github.com/IgorGanapolsky/ThumbGate/blob/main/proof/automation/report.json" target="_blank" rel="noopener">
+    <strong>Automation Proof</strong>
+    <span>Machine-readable report for the feedback, enforcement, and automation surfaces behind ThumbGate.</span>
+  </a>
+</div>
+
 <h2>Get Started</h2>
 <pre><code>npx thumbgate init</code></pre>
 <p>One command. Works with Claude Code, Cursor, Codex, Gemini, Amp, and OpenCode. Claude Code can also call Codex for review, adversarial review, and second-pass handoffs through the repo-local bridge plugin.</p>
 <a href="https://thumbgate-production.up.railway.app/checkout/pro?utm_source=guide&utm_medium=cta_button&utm_campaign=pro_pack" class="cta">Get Pro — $19/mo or $149/yr</a>
+<a href="https://thumbgate-production.up.railway.app/#workflow-sprint-intake" class="cta cta-secondary">Start a Workflow Hardening Sprint</a>
 <p style="color:var(--muted); font-size:0.85rem;">Free keeps local enforcement with 3 daily feedback captures, 5 lesson searches, unlimited recall, blocking, and history-aware lesson distillation. Pro is $19/mo or $149/yr for a personal local dashboard and DPO export. Team rollout starts intake-first at $49/seat/mo with a 3-seat minimum for the hosted shared lesson DB, org dashboard, and generated review views.</p>
 
 </div>

package/public/index.html

@@ -24,7 +24,7 @@ __GOOGLE_SITE_VERIFICATION_META__
 <link rel="apple-touch-icon" href="/assets/brand/thumbgate-mark.svg">
 <meta property="og:image" content="/og.png">
 <title>ThumbGate — Stop paying for the same AI mistake twice</title>
-<meta name="description" content="Stop paying for the same AI mistake twice. ThumbGate is the enforcement layer for AI agent orchestration: 👍 thumbs up and 👎 thumbs down become history-aware lessons, shared lessons and org visibility, plus Pre-Action Checks that block repeat mistakes before the next tool call across Claude Code, Cursor, Codex, Gemini, Amp, Cline, and OpenCode.">
+<meta name="description" content="Stop paying for the same AI mistake twice. ThumbGate is machine-speed pre-action defense for AI coding agents: 👍 thumbs up and 👎 thumbs down become history-aware lessons, shared lessons and org visibility, actionable remediations, agent surface inventory, and Pre-Action Checks that block repeat mistakes before the next tool call across Claude Code, Cursor, Codex, Gemini, Amp, Cline, and OpenCode.">
 <meta property="og:title" content="ThumbGate — Stop paying for the same AI mistake twice">
 <meta property="og:description" content="Frontier LLMs are expensive, opaque, and unreliable in production. ThumbGate gates risky agent actions before they run: workflow shape, inspection evidence, token budget, and repeated-failure memory in one pre-action check.">
 <meta property="og:type" content="website">
@@ -53,7 +53,7 @@ __GA_BOOTSTRAP__
   "@type": "SoftwareApplication",
   "name": "ThumbGate",
   "alternateName": "thumbgate",
-  "description": "ThumbGate stops you from paying for the same AI mistake twice. Frontier LLMs are expensive, opaque, and unreliable in production — every repeated hallucination, retry loop, or known-bad tool call burns more tokens. ThumbGate's Pre-Action Checks inspect workflow shape, environment evidence, budget, and repeated-failure memory before the action runs. Works with Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode, and any MCP-compatible agent.",
+  "description": "ThumbGate stops you from paying for the same AI mistake twice. It is machine-speed pre-action defense for coding agents: thumbs-up/down feedback becomes history-aware lessons, shared lessons and org visibility, actionable remediations, agent surface inventory, and Pre-Action Checks that inspect workflow shape, environment evidence, budget, and repeated-failure memory before the next tool call across Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode, and any MCP-compatible agent.",
   "applicationCategory": "DeveloperApplication",
   "operatingSystem": "Cross-platform, Node.js >=18.18.0",
   "license": "https://opensource.org/licenses/MIT",
@@ -70,7 +70,9 @@ __GA_BOOTSTRAP__
     "Prevent expensive AI mistakes — catch bad commands, destructive database actions, unsafe publishes, and risky API calls before execution",
     "Make AI stop repeating mistakes — thumbs-down feedback becomes history-aware lessons and Pre-Action Checks",
     "Turn AI into a reliable operator — checkpoint risky actions, enforce safe patterns, and keep proof of what changed",
-    "ThumbGate GPT for ChatGPT — check proposed agent actions, capture thumbs-up/down lessons, and route users into local enforcement",
+    "Agent surface inventory — see which tools, MCP surfaces, and policy sources are actually active before rollout",
+    "Actionable remediations — rank the next highest-ROI fixes from real feedback and risk pressure",
+    "ThumbGate GPT for ChatGPT — preflight risky commands, refunds, deploys, and PR actions, capture typed thumbs-up/down lessons, and route users into local enforcement",
     "Workflow Sentinel — score blast radius before PR, merge, release, and publish actions fire",
     "Workflow architecture checks — distinguish predefined workflows, parallel fan-out, and open-ended agents before execution",
     "Environment inspection evidence — require read-before-write, screenshots, API response checks, tests, or output validation for open-ended agent loops",
@@ -572,9 +574,9 @@ __GA_BOOTSTRAP__
 <section class="hero">
   <div class="container">
     <div class="hero-thumbs">👍👎</div>
-    <div class="hero-badge">● Your AI coding bill has a leak</div>
+    <div class="hero-badge">● Machine-speed pre-action defense for coding agents</div>
     <h1>Stop paying $ for the same AI mistake.</h1>
-    <p style="font-size:18px;color:var(--text-muted);max-width:720px;margin:0 auto 20px;line-height:1.6;">Every retry loop, every hallucinated import, every "let me try a different approach" — those are billable tokens on every LLM vendor's bill. Thumbs-down once; ThumbGate blocks that exact mistake on every future call. Across Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode — any MCP-compatible agent, forever, including fast-moving vibe coding workflows.</p>
+    <p style="font-size:18px;color:var(--text-muted);max-width:720px;margin:0 auto 20px;line-height:1.6;">Every retry loop, every hallucinated import, every "let me try a different approach" — those are billable tokens on every LLM vendor's bill. ThumbGate is machine-speed pre-action defense: thumbs-down once, block that exact mistake on every future call, surface the next highest-ROI remediation, and show which agent surfaces are actually active before rollout. Across Claude Code, Cursor, Codex, Gemini, Amp, Cline, OpenCode — any MCP-compatible agent, forever, including fast-moving vibe coding workflows.</p>
     <p style="font-size:15px;color:var(--text-dim);max-width:760px;margin:0 auto 24px;line-height:1.6;">As desktop agents move into parallel sessions, terminals, and production workflows, ThumbGate checks the thing benchmarks miss: is this next action a known workflow, an open-ended agent, a costly fan-out, or a blind tool call with no way to verify it worked?</p>
 
     <!-- HERO PRICING CARD — visible in first viewport so $19/mo and $149/yr never get buried -->
@@ -611,12 +613,12 @@ __GA_BOOTSTRAP__
         <span style="display:inline-flex;align-items:center;gap:6px;color:#4ade80;"><span style="width:6px;height:6px;border-radius:50%;background:#4ade80;box-shadow:0 0 8px #4ade80;animation:pulse 1.6s ease-in-out infinite;"></span>enforcing</span>
       </div>
       <div style="font-size:13px;color:var(--text-muted);margin-bottom:4px;">💸 Tokens saved — since install (Sonnet-blended, conservative)</div>
-      <div id="hero-savings-counter" data-target="1247.82" style="font-size:44px;font-weight:700;color:#4ade80;letter-spacing:-0.02em;line-height:1;margin-bottom:18px;">$0.00</div>
+      <div id="hero-savings-counter" data-target="0" style="font-size:44px;font-weight:700;color:#4ade80;letter-spacing:-0.02em;line-height:1;margin-bottom:18px;">$0.00</div>
       <div style="font-size:12px;line-height:1.8;border-top:1px solid rgba(255,255,255,0.06);padding-top:12px;">
         <div style="color:#4ade80;">✅ check:no-force-push — blocked 12×</div>
         <div style="color:#4ade80;">✅ check:no-hallucinated-import — blocked 8×</div>
         <div style="color:#f87171;">❌ check:no-drop-prod — FIRED · saved ~$3.40</div>
-        <div style="color:var(--text-muted);font-size:11px;margin-top:8px;">Sample shown. Your own dashboard tracks live feedback log + blocked calls from day one. <span style="color:var(--cyan);">Open dashboard →</span></div>
+        <div style="color:var(--text-muted);font-size:11px;margin-top:8px;">Sample shown. Your own dashboard tracks live feedback log, actionable remediations, and agent surface inventory from day one. <span style="color:var(--cyan);">Open dashboard →</span></div>
       </div>
     </a>
     <style>@keyframes pulse{0%,100%{opacity:1}50%{opacity:0.4}}</style>
@@ -632,7 +634,8 @@ __GA_BOOTSTRAP__
     </script>
     <div class="hero-signals">
       <a class="signal-pill signal-down" href="#how-it-works" title="See how check interception works">Block repeat hallucinations before the model sees them</a>
-      <a class="signal-pill signal-up" href="#how-it-works" title="See the one-thumbs-down enforcement loop">Thumbs-down once, blocked forever, across every agent</a>
+      <a class="signal-pill signal-up" href="/dashboard" title="See the remediation and inventory dashboard">Thumbs-down once, blocked forever</a>
+      <a class="signal-pill" href="/dashboard" title="See the remediation and inventory dashboard">Actionable remediations + agent surface inventory</a>
       <a class="signal-pill" href="#install" title="Install the CLI">CLI-first workflow governance with a live tokens-saved counter</a>
     </div>
     <p class="hero-persona" style="display:none">For consultancies, platform teams, and AI product teams with one workflow owner, one repeated failure, and one buyer who needs proof before a wider rollout.</p>
@@ -784,15 +787,15 @@ __GA_BOOTSTRAP__
   <div class="container">
     <div class="gpt-panel">
       <div class="section-label" style="text-align:left;">ChatGPT Entry Point · Live ThumbGate GPT for ChatGPT</div>
-      <h2>Open the GPT. Give typed thumbs feedback. Turn the lesson into a check.</h2>
-      <p>ThumbGate should meet users where they already ask AI for help. The live GPT is the lowest-friction way to capture a useful thumbs-up/down lesson, check a risky action, and prove the enforcement loop before installing anything. As ChatGPT ads roll out, this matters more: ChatGPT can stay the discovery and checkpointing layer, while ThumbGate remains the hard execution boundary after <code>npx thumbgate init</code>.</p>
+      <h2>Use the GPT as a preflight desk for risky commands, refunds, deploys, and PR actions.</h2>
+      <p>ThumbGate should meet users where they already ask AI for help. The live GPT is the fastest way to preflight a risky action, capture a typed thumbs-up/down lesson, and prove the enforcement loop before installing anything. As ChatGPT ads roll out, this matters more: ChatGPT can stay the discovery and checkpointing layer, while ThumbGate remains the hard execution boundary after <code>npx thumbgate init</code>.</p>
       <div class="gpt-steps">
         <div class="gpt-step">
-          <strong>1. Try the live GPT</strong>
-          <p>Paste a proposed command, file edit, merge, deploy, or API call and ask whether to allow, block, or checkpoint it.</p>
+          <strong>1. Open the live GPT</strong>
+          <p>Paste a proposed command, file edit, merge, deploy, refund, invoice, or API call and ask whether to allow, block, or checkpoint it.</p>
         </div>
         <div class="gpt-step">
-          <strong>2. Save the signal</strong>
+          <strong>2. Save the typed signal</strong>
           <p>Reply in chat with <code>thumbs up:</code> or <code>thumbs down:</code> plus one concrete sentence. Do not rely on ChatGPT's native rating buttons for ThumbGate memory.</p>
         </div>
         <div class="gpt-step">
@@ -805,7 +808,7 @@ __GA_BOOTSTRAP__
         <a href="https://github.com/IgorGanapolsky/ThumbGate/blob/main/adapters/chatgpt/INSTALL.md" class="btn-free" target="_blank" rel="noopener" style="display:inline-flex;align-items:center;padding:12px 20px;border-radius:8px;">ChatGPT Actions setup</a>
         <a href="/guides/chatgpt-ads-trust" class="btn-free" style="display:inline-flex;align-items:center;padding:12px 20px;border-radius:8px;">Why ChatGPT ads need checks</a>
       </div>
-      <p class="gpt-note"><strong>Plain English rule:</strong> ChatGPT is the discovery and memory surface for advice, checkpointing, and typed feedback capture. One typed signal becomes one remembered rule. The hard Reliability Gateway still runs in the local agent or CI lane.</p>
+      <p class="gpt-note"><strong>Find it fast:</strong> if the direct link does not open, go to <strong>Explore GPTs</strong>, search <code>ThumbGate</code>, and choose the GPT by Igor Ganapolsky in <strong>Programming</strong>. <strong>Plain English rule:</strong> ChatGPT is the discovery and memory surface for advice, checkpointing, and typed feedback capture. One typed signal becomes one remembered rule. The hard Reliability Gateway still runs in the local agent or CI lane.</p>
     </div>
   </div>
 </section>
@@ -857,7 +860,7 @@ __GA_BOOTSTRAP__
       </a>
       <a class="compat-card" href="/go/gpt?utm_source=website&utm_medium=compatibility&utm_campaign=chatgpt_gpt&cta_id=compat_open_gpt&cta_placement=compatibility" target="_blank" rel="noopener">
         <h3>💬 ChatGPT GPT Actions</h3>
-        <p>Open the ThumbGate GPT to check proposed AI actions, capture thumbs-up/down lessons, and get setup guidance. Real blocking for coding agents still runs locally after <code>npx thumbgate init</code>.</p>
+        <p>Open the ThumbGate GPT to preflight risky commands, deploys, refunds, PR actions, and setup steps, capture thumbs-up/down lessons, and save typed signals. Real blocking for coding agents still runs locally after <code>npx thumbgate init</code>.</p>
         <div class="card-arrow">Open ThumbGate GPT →</div>
       </a>
     </div>
@@ -1079,7 +1082,7 @@ __GA_BOOTSTRAP__
 <!-- HOW IT WORKS -->
 <section class="how-it-works" id="how-it-works">
   <div class="container">
-    <div class="section-label">New in v1.16.3</div>
+    <div class="section-label">New in v1.16.5</div>
     <h2 class="section-title">Three steps to stop repeated AI failures</h2>
     <div class="steps">
       <div class="step">
@@ -1439,7 +1442,7 @@ __GA_BOOTSTRAP__
       <a href="https://www.linkedin.com/in/igorganapolsky" target="_blank" rel="noopener">LinkedIn</a>
       <a href="/blog">Blog</a>
     </div>
-    <span class="footer-copy">© 2026 Max Smith KDP LLC · MIT License · v1.16.3</span>
+    <span class="footer-copy">© 2026 Max Smith KDP LLC · MIT License · v1.16.5</span>
   </div>
 </footer>
 

package/scripts/background-agent-governance.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Background Agent Governance — the missing layer for Ramp/Ona-style agent stacks.
+ *
+ * Background agents run unattended (writing 57% of PRs at Ramp). They need:
+ * 1. Run tracking — what did each agent run do?
+ * 2. Governance gate — should this PR/action be allowed based on past failures?
+ * 3. Post-run audit — auto-capture feedback from CI results
+ * 4. Governance report — "X runs, Y blocked, Z lessons learned"
+ *
+ * Integrates with: MCP server, gates engine, org dashboard, lesson inference.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveFeedbackDir } = require('./feedback-paths');
+const { ensureParentDir, readJsonl } = require('./fs-utils');
+
+const RUNS_FILE = 'agent-runs.jsonl';
+
+function getFeedbackDir(feedbackDir) { return resolveFeedbackDir({ feedbackDir }); }
+function getRunsPath(feedbackDir) { return path.join(getFeedbackDir(feedbackDir), RUNS_FILE); }
+
+// ---------------------------------------------------------------------------
+// 1. Run Tracking
+// ---------------------------------------------------------------------------
+
+/**
+ * Record a background agent run.
+ * Called when a background agent starts or completes a task.
+ */
+function recordAgentRun({ agentId, runType, source, branch, prNumber, status, gatesChecked, gatesBlocked, filesChanged, ciPassed, duration, metadata } = {}, feedbackDir) {
+  const runsPath = getRunsPath(feedbackDir);
+  ensureParentDir(runsPath);
+  const run = {
+    id: `run_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: new Date().toISOString(),
+    agentId: agentId || 'unknown',
+    runType: runType || 'unknown', // 'pr', 'fix', 'refactor', 'ci-repair', 'migration'
+    source: source || 'background', // 'background', 'triggered', 'scheduled', 'manual'
+    branch: branch || null,
+    prNumber: prNumber || null,
+    status: status || 'started', // 'started', 'completed', 'blocked', 'failed'
+    gatesChecked: gatesChecked || 0,
+    gatesBlocked: gatesBlocked || 0,
+    filesChanged: filesChanged || 0,
+    ciPassed: ciPassed === undefined ? null : ciPassed,
+    durationMs: duration || null,
+    metadata: metadata || {},
+  };
+  fs.appendFileSync(runsPath, JSON.stringify(run) + '\n');
+  return run;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Governance Gate — pre-run check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a background agent run should proceed based on governance rules.
+ * Returns { allowed, blockers, warnings, governanceScore }.
+ */
+function checkRunGovernance({ agentId, runType, branch, filesChanged } = {}, feedbackDir) {
+  const runs = readJsonl(getRunsPath(feedbackDir));
+  const blockers = [];
+  const warnings = [];
+
+  // Rule 1: Block if this agent has > 50% failure rate in last 10 runs
+  const agentRuns = runs.filter((r) => r.agentId === agentId).slice(-10);
+  const failedRuns = agentRuns.filter((r) => r.status === 'failed' || r.status === 'blocked');
+  if (agentRuns.length >= 5 && failedRuns.length / agentRuns.length > 0.5) {
+    blockers.push({ rule: 'high_failure_rate', message: `Agent ${agentId} has ${failedRuns.length}/${agentRuns.length} failed runs (>50%)`, severity: 'critical' });
+  }
+
+  // Rule 2: Warn if agent has been blocked by gates in recent runs
+  const recentBlocked = agentRuns.filter((r) => r.gatesBlocked > 0);
+  if (recentBlocked.length >= 3) {
+    warnings.push({ rule: 'repeated_gate_blocks', message: `Agent ${agentId} has been gate-blocked in ${recentBlocked.length} recent runs`, severity: 'warning' });
+  }
+
+  // Rule 3: Block if targeting protected branch without CI passing
+  if (branch && /^(main|master|develop)$/.test(branch)) {
+    warnings.push({ rule: 'protected_branch', message: `Run targets protected branch "${branch}" — CI must pass before merge`, severity: 'warning' });
+  }
+
+  // Rule 4: Warn if too many files changed (large blast radius)
+  if (filesChanged > 20) {
+    warnings.push({ rule: 'large_blast_radius', message: `${filesChanged} files changed — consider splitting into smaller PRs`, severity: 'warning' });
+  }
+
+  const governanceScore = Math.max(0, 100 - blockers.length * 40 - warnings.length * 10);
+
+  return {
+    allowed: blockers.length === 0,
+    blockers,
+    warnings,
+    governanceScore,
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 3. Post-Run Audit — auto-capture feedback from CI
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-capture feedback from a completed background agent run.
+ * Converts CI pass/fail into structured feedback for the learning loop.
+ */
+function auditCompletedRun({ runId, agentId, ciPassed, ciOutput, prNumber, branch, filesChanged } = {}, feedbackDir) {
+  const signal = ciPassed ? 'positive' : 'negative';
+  const context = ciPassed
+    ? `Background agent run ${runId || 'unknown'} completed successfully. PR #${prNumber || '?'} on ${branch || '?'}. ${filesChanged || 0} files changed. CI passed.`
+    : `Background agent run ${runId || 'unknown'} failed. PR #${prNumber || '?'} on ${branch || '?'}. ${filesChanged || 0} files changed. CI failed.`;
+
+  const whatWentWrong = !ciPassed && ciOutput ? ciOutput.slice(0, 500) : null;
+
+  // Record the completed run
+  const run = recordAgentRun({
+    agentId,
+    runType: 'pr',
+    source: 'background',
+    branch,
+    prNumber,
+    status: ciPassed ? 'completed' : 'failed',
+    filesChanged,
+    ciPassed,
+  }, feedbackDir);
+
+  // Auto-capture feedback
+  let feedbackResult = null;
+  try {
+    const { captureFeedback } = require('./feedback-loop');
+    feedbackResult = captureFeedback({
+      signal: ciPassed ? 'up' : 'down',
+      context,
+      whatWentWrong,
+      whatWorked: ciPassed ? `Agent successfully completed PR #${prNumber || '?'}` : undefined,
+      tags: ['background-agent', ciPassed ? 'ci-pass' : 'ci-fail', `agent:${agentId || 'unknown'}`],
+    });
+  } catch { /* feedback capture is non-critical */ }
+
+  return { run, feedbackResult, signal, context };
+}
+
+// ---------------------------------------------------------------------------
+// 4. Governance Report
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a governance report for background agent runs.
+ * Shows: total runs, blocked, pass rate, top failing agents, lessons learned.
+ */
+function generateGovernanceReport({ periodHours = 24, feedbackDir } = {}) {
+  const runs = readJsonl(getRunsPath(feedbackDir));
+  const cutoff = Date.now() - periodHours * 60 * 60 * 1000;
+  const recent = runs.filter((r) => new Date(r.timestamp).getTime() > cutoff);
+
+  const total = recent.length;
+  const completed = recent.filter((r) => r.status === 'completed').length;
+  const failed = recent.filter((r) => r.status === 'failed').length;
+  const blocked = recent.filter((r) => r.status === 'blocked').length;
+  const started = recent.filter((r) => r.status === 'started').length;
+
+  const passRate = (completed + failed) > 0 ? Math.round((completed / (completed + failed)) * 1000) / 10 : 0;
+  const totalGatesChecked = recent.reduce((s, r) => s + (r.gatesChecked || 0), 0);
+  const totalGatesBlocked = recent.reduce((s, r) => s + (r.gatesBlocked || 0), 0);
+
+  // Per-agent breakdown
+  const byAgent = {};
+  for (const r of recent) {
+    if (!byAgent[r.agentId]) byAgent[r.agentId] = { completed: 0, failed: 0, blocked: 0, total: 0 };
+    byAgent[r.agentId].total++;
+    if (r.status === 'completed') byAgent[r.agentId].completed++;
+    if (r.status === 'failed') byAgent[r.agentId].failed++;
+    if (r.status === 'blocked') byAgent[r.agentId].blocked++;
+  }
+
+  const agentSummaries = Object.entries(byAgent).map(([id, counts]) => ({
+    agentId: id,
+    ...counts,
+    passRate: (counts.completed + counts.failed) > 0 ? Math.round((counts.completed / (counts.completed + counts.failed)) * 1000) / 10 : 0,
+  })).sort((a, b) => a.passRate - b.passRate);
+
+  // By run type
+  const byType = {};
+  for (const r of recent) {
+    if (!byType[r.runType]) byType[r.runType] = 0;
+    byType[r.runType]++;
+  }
+
+  return {
+    periodHours,
+    total, completed, failed, blocked, started,
+    passRate,
+    gatesChecked: totalGatesChecked,
+    gatesBlocked: totalGatesBlocked,
+    agents: agentSummaries,
+    topFailingAgent: agentSummaries.length > 0 && agentSummaries[0].passRate < 80 ? agentSummaries[0] : null,
+    byType,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Format governance report as a human-readable string.
+ */
+function formatGovernanceReport(report) {
+  const lines = [
+    `Background Agent Governance Report (${report.periodHours}h)`,
+    `Total runs: ${report.total} | Completed: ${report.completed} | Failed: ${report.failed} | Blocked: ${report.blocked}`,
+    `Pass rate: ${report.passRate}%`,
+    `Gates checked: ${report.gatesChecked} | Gates blocked: ${report.gatesBlocked}`,
+  ];
+  if (report.topFailingAgent) {
+    lines.push(`Top failing agent: ${report.topFailingAgent.agentId} (${report.topFailingAgent.passRate}% pass rate)`);
+  }
+  if (Object.keys(report.byType).length > 0) {
+    lines.push(`Run types: ${Object.entries(report.byType).map(([t, c]) => `${t}:${c}`).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  recordAgentRun, checkRunGovernance, auditCompletedRun,
+  generateGovernanceReport, formatGovernanceReport, getRunsPath,
+};