Add fixture risk scan demo and promo hooks

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

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"

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.

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.