docs: add Space README body for Governance Bench

README.md

@@ -9,3 +9,90 @@ pinned: false
 license: apache-2.0
 short_description: Interactive benchmark for AI agent governance primitives
 ---
+
+# Governance-Bench Agent Reasoning Audit
+
+Interactive demo for **HUMMBL Governance Bench** — a Harbor-compatible benchmark that tests **operational AI agent governance** (what agents *do*), not content safety (what models *say*). The Space browses the 70-task suite, shows Base120 governance mental models, runs task verification scripts, and surfaces dimension scores.
+
+**Live app:** [hummbl-research-governance-bench-space.hf.space](https://hummbl-research-governance-bench-space.hf.space)
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| Dataset | [hummbl-hf/governance-bench](https://huggingface.co/datasets/hummbl-hf/governance-bench) |
+| Collection | [hummbl-research/hummbl-governance-bench](https://huggingface.co/collections/hummbl-research/hummbl-governance-bench-6a799d546ec60e99c82528cf) |
+| Org | [hummbl-research](https://huggingface.co/hummbl-research) |
+
+The benchmark dataset lives on the sister org **hummbl-hf**; this Space (Docker SDK) is published under **hummbl-research**.
+
+## What this Space does
+
+A FastAPI + uvicorn + Jinja2 UI over the baked-in benchmark checkout (`BENCH_ROOT=/bench`):
+
+1. **Overview** — task counts by category and difficulty; Base120 model cards
+2. **Tasks** — browse by category, read `instruction.md`, inspect metadata (`difficulty`, scoring model)
+3. **Run Verification** — execute each task’s `tests/verify.py` and show overall score plus four dimensions (correctness, governance awareness, safety–utility tradeoff, audit trail quality)
+4. **Base120 Models** — seven governance mental models mapped to primitives (e.g. interruptibility → KillSwitch / CircuitBreaker)
+5. **Leaderboard** — reads agent result JSON from `BENCH_ROOT/results` when present
+
+JSON APIs: `GET /api/tasks`, `GET /api/task/{category}/{task_id}`, `POST /api/task/{category}/{task_id}/run`, `GET /api/base120/models`, `GET /api/leaderboard`, `GET /health`.
+
+### How to use
+
+1. Open the live Space (or run locally — see below).
+2. On **Overview**, click a category card to open the task browser.
+3. Select a task to read the instruction and Base120 analysis.
+4. Click **Run Verification** to execute the task’s verify script and view scores.
+
+## Task categories (7 × 10 = 70)
+
+| Category | What it tests |
+|----------|----------------|
+| `kill_switch` | Emergency halt, mode transitions, critical task exemptions |
+| `circuit_breaker` | Failure detection, state transitions, recovery |
+| `delegation_chains` | HMAC-signed tokens, scope narrowing, depth limits |
+| `authority_boundaries` | Authority-class validation, DCT cross-links, hash chains |
+| `taint_tracking` | Data provenance, propagation, sink policy enforcement |
+| `execution_boundary` | Fail-closed behavior, risk scoring, path restrictions |
+| `behavioral_drift` | Reward gaming, convergence detection, drift quantification |
+
+Difficulty mix (dataset card): 21 easy, 28 medium, 21 hard. Each task is Harbor `task.toml` v1.3 compatible (`task.toml`, `instruction.md`, environment Dockerfile, verification script).
+
+## Runtime & local / Docker notes
+
+- **SDK:** Docker; app listens on port **7860**
+- **Stack:** FastAPI, uvicorn, Jinja2; depends on `hummbl-governance>=1.1.0`
+- **Data:** Dataset snapshot is fetched at **image build time** into `/bench` (immutable; updates require a rebuild — intentional supply-chain hardening vs. runtime fetch)
+- **Env:** `BENCH_ROOT=/bench` (override for local mounts)
+
+```bash
+# From this Space repo
+docker build -t governance-bench-space .
+docker run --rm -p 7860:7860 governance-bench-space
+# Then open http://localhost:7860
+```
+
+Local (without Docker), after installing `requirements.txt` and pointing at a local dataset checkout:
+
+```bash
+export BENCH_ROOT=/path/to/governance-bench   # must contain tasks/
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+For full agent evaluation against the dataset (outside this Space), see the dataset card’s Harbor usage examples.
+
+## License & credit
+
+- **This Space:** Apache-2.0 (YAML `license`)
+- **Dataset:** CC-BY-4.0 with evaluation-only restriction (not for training / fine-tuning) — see [dataset card](https://huggingface.co/datasets/hummbl-hf/governance-bench)
+- **Credit:** HUMMBL, LLC — HUMMBL Governance Bench
+
+```bibtex
+@dataset{hummbl2026governancebench,
+  title={HUMMBL Governance Bench: First Benchmark for Operational AI Agent Governance},
+  author={HUMMBL, LLC},
+  year={2026},
+  url={https://huggingface.co/datasets/hummbl-hf/governance-bench}
+}
+```