From 7104204b4e7ad669caf8f5335c603054f36a3406 Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Tue, 16 Jun 2026 12:10:15 +1000
Subject: [PATCH 1/2] Add fixture risk scan demo

---
 README.md                         |  8 +++++++
 demo/run-fixture-risk-scan.sh     | 25 ++++++++++++++++++++
 docs/tutorials/agent-risk-gate.md | 39 +++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+)
 create mode 100755 demo/run-fixture-risk-scan.sh
 create mode 100644 docs/tutorials/agent-risk-gate.md

diff --git a/README.md b/README.md
index 6426e33..91d3695 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,14 @@ node dist/cli.js scan \
   --format markdown
 ```
 
+Or run the fixture-backed demo script:
+
+```sh
+bash demo/run-fixture-risk-scan.sh
+```
+
+The tutorial in [docs/tutorials/agent-risk-gate.md](docs/tutorials/agent-risk-gate.md) shows how to use the generated Markdown and JSON reports in an agent handoff. Promotion hooks are in [docs/promo/social-hooks.md](docs/promo/social-hooks.md).
+
 Use in an agent handoff:
 
 ```sh
diff --git a/demo/run-fixture-risk-scan.sh b/demo/run-fixture-risk-scan.sh
new file mode 100755
index 0000000..5111470
--- /dev/null
+++ b/demo/run-fixture-risk-scan.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT="$ROOT/.tmp/demo-fixture-risk-scan"
+
+mkdir -p "$OUT"
+
+npm run build
+
+echo "== scan checked-in sample diff =="
+node "$ROOT/dist/cli.js" scan \
+  --diff "$ROOT/fixtures/simple-risk/sample.diff" \
+  --output "$OUT" \
+  --format markdown
+
+sed -n '1,80p' "$OUT/diffbudget-report.md"
+
+grep -Fq 'Status: **PASS**' "$OUT/diffbudget-report.md"
+grep -Fq 'package-lock.json' "$OUT/diffbudget-report.md"
+grep -Fq 'src/auth/login.ts' "$OUT/diffbudget-report.md"
+grep -Fq '"status": "pass"' "$OUT/diffbudget-report.json"
+
+echo
+echo "Demo artifacts written to $OUT"
diff --git a/docs/tutorials/agent-risk-gate.md b/docs/tutorials/agent-risk-gate.md
new file mode 100644
index 0000000..b565270
--- /dev/null
+++ b/docs/tutorials/agent-risk-gate.md
@@ -0,0 +1,39 @@
+# Use DiffBudget As An Agent Risk Gate
+
+This tutorial uses the checked-in `fixtures/simple-risk/sample.diff` file to show how an agent or maintainer can score a patch before continuing.
+
+## 1. Run The Fixture Demo
+
+```sh
+npm install
+bash demo/run-fixture-risk-scan.sh
+```
+
+The demo writes:
+
+- `.tmp/demo-fixture-risk-scan/diffbudget-report.md`
+- `.tmp/demo-fixture-risk-scan/diffbudget-report.json`
+
+## 2. Review The Human Report
+
+The Markdown report summarizes status, changed files, changed lines, risk score, and the riskiest files. In the fixture, the report calls out a dependency lockfile and an auth path.
+
+## 3. Hand JSON To Automation
+
+Agents and CI jobs should read `diffbudget-report.json` for status and findings instead of scraping the Markdown report. Treat `pass` as a signal to continue with normal checks, not as permission to skip review.
+
+## 4. Escalate On Strict Failure
+
+For uncommitted work, use:
+
+```sh
+diffbudget scan --base HEAD --output .diffbudget/latest --strict
+```
+
+When strict mode exits non-zero, capture the command, report path, and top findings before asking for maintainer review.
+
+## Boundaries
+
+- DiffBudget scores unified diffs; it does not prove semantic correctness.
+- Missing-test detection is heuristic.
+- Branch protection, test execution, and release approval remain separate controls.

From e13db3f935bfb5f909856c60aa203f40348a9151 Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Tue, 16 Jun 2026 12:10:15 +1000
Subject: [PATCH 2/2] Add diffbudget social hooks

---
 docs/promo/social-hooks.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 docs/promo/social-hooks.md

diff --git a/docs/promo/social-hooks.md b/docs/promo/social-hooks.md
new file mode 100644
index 0000000..70ac7db
--- /dev/null
+++ b/docs/promo/social-hooks.md
@@ -0,0 +1,24 @@
+# Social Hooks
+
+Grounded post drafts for the fixture risk scan.
+
+## Hooks
+
+1. Before an agent keeps editing, ask a simpler question: how risky is this diff? `diffbudget` turns a patch into Markdown and JSON risk reports.
+2. The fixture demo scores changed files, changed lines, dependency lockfile churn, and an auth-path change without uploading the repo anywhere.
+3. `bash demo/run-fixture-risk-scan.sh` writes a human report plus `diffbudget-report.json`, so CI and agents do not need to scrape Markdown.
+4. `diffbudget scan --base HEAD --strict` is a practical stop sign when a patch exceeds local budgets; the report gives reviewers the top findings to inspect.
+
+## Clip Outline
+
+- Open `fixtures/simple-risk/sample.diff`.
+- Run `bash demo/run-fixture-risk-scan.sh`.
+- Show `.tmp/demo-fixture-risk-scan/diffbudget-report.md`.
+- Point to the package-lock and auth-path findings.
+- Show the JSON status for automation handoff.
+
+## Guardrails
+
+- Do not call the score a security verdict.
+- Do not claim semantic understanding of the patch.
+- Keep the message on local budgets, review triage, and explicit reports.