# Amendment Pipeline Demo

This directory contains a fully scripted, end-to-end run of the FablePool
amendment pipeline — the same lifecycle that GitHub Actions enforces on the
live repository, executed locally against a scratch copy.

## Run it

```bash
# from the repository root
pip install -e .
python demo/run_demo.py
```

The script exits `0` only if every constitutional expectation holds. It is
also run on every push by the `demo` job in `.github/workflows/ci.yml`, so a
regression in the pipeline breaks the build.

## What it demonstrates

| Step | What happens | Constitutional rule exercised |
|------|--------------|-------------------------------|
| 1 | Five citizens enroll with fresh ed25519 keypairs | Art. 2 (citizenship), one person one vote, duplicate-key rejection |
| 2 | A **minor userland** amendment gets 4 yes / 1 no, passes the gate, is ratified, and the constitution version bumps `x.y.z → x.(y+1).0` | Art. 3–5 (proposal lifecycle, quorum, simple majority for non-breaking changes), governance semver |
| 3 | A **major kernel** amendment gets 3 yes / 2 no (60%) and is **blocked**: 60% < the two-thirds supermajority a breaking kernel change requires | Art. 4 (supermajority ratification for kernel changes) |
| 4 | The ledger is dumped and its hash chain verified | Art. 8 (every vote and amendment on one public, append-only ledger) |

The scratch repo is rebuilt from scratch on every run in `demo/scratch/`
(git-ignored), so the demo is idempotent and side-effect free.

## Note on diffs

In the real pipeline, an amendment is a pull request: the proposal document
and the actual text change travel together in one git diff, and the PR gate
classifies the diff itself. The scratch demo has no remote, so proposals
*declare* their changed paths (`--change ...`) on the proposal document —
the classifier and gate grade those declarations identically.