# FablePool Constitution — Governance as Code

> The US Constitution last shipped a release in 1992. That release was drafted in
> 1789 and sat unratified for 203 years. This repository is an experiment in
> giving governance the iteration loop of software: version control, review,
> tests, releases.

This repository contains:

1. **A machine-parseable constitution** (`constitution/`) — a kernel of ten
   meta-articles (how rules change, who votes, quorum, the right to fork, hard
   invariants) plus userland modules any group can fork and parameterize.
2. **`govtool`** (`src/govtool/`) — the governance-as-code toolchain: proposal
   lifecycle, signed ballots, eligibility and quorum checks, tally, a semver
   classifier for amendments, fork tooling, and a hash-chained public audit
   ledger.
3. **CI vote gates** (`.github/workflows/`) — every amendment is a pull
   request; ratification is a vote gate in CI. A PR that fails quorum, fails
   its threshold, or violates a constitutional invariant **cannot merge**.
4. **A test suite** (`tests/`) — the tooling is tested end-to-end, including a
   full demo of one amendment passing and one failing the gate.

The project's own funding pool operates under this constitution. Backers are
the first citizens. One person, one vote, no capital weighting. Every vote and
every amendment lands in the same public ledger as the money.

---

## Quickstart

Requires Python 3.10+.

```bash
git clone https://github.com/fablepool/constitution
cd constitution
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run the test suite
pytest

# Run the end-to-end demo: one amendment passes the gate, one fails
python demo/run_demo.py
```

> **Note on lockfiles:** this repository intentionally does not ship a
> lockfile. After your first successful install, generate one with your tool
> of choice (e.g. `pip freeze > requirements.lock` or `uv lock`) and commit it
> if you want reproducible installs.

The CLI is installed as `govtool`. Run `govtool --help` for the full command
tree. The major command groups:

| Command group     | Purpose                                                        |
|-------------------|----------------------------------------------------------------|
| `govtool keys`    | Generate and inspect Ed25519 citizen keypairs                  |
| `govtool propose` | Open, inspect, and close amendment proposals                   |
| `govtool vote`    | Cast and verify signed ballots                                 |
| `govtool tally`   | Tally ballots against eligibility, quorum, and thresholds      |
| `govtool classify`| Label an amendment as kernel-major / kernel-minor / userland   |
| `govtool gate`    | Run the full vote gate (what CI runs on every amendment PR)    |
| `govtool fork`    | Clone, parameterize, and track upstream                        |
| `govtool ledger`  | Append to and verify the hash-chained audit ledger             |

## Repository layout

```
constitution/
  version.yaml              # current constitutional version (semver)
  kernel/                   # the ten meta-articles, machine-parseable YAML
  invariants.yaml           # hard invariants no amendment may violate
  userland/                 # substantive modules (e.g. funding-pool.yaml)
citizens/
  registry.yaml             # the citizen registry: ids + public keys + status
src/govtool/                # the toolchain
.github/workflows/          # CI: lint/tests, PR vote gate, ratification merge
demo/                       # end-to-end demo of the amendment pipeline
docs/                       # developer documentation
tests/                      # full test suite
```

## How an amendment ships

The short version (the long version is [docs/pipeline.md](docs/pipeline.md)):

1. **Propose.** A citizen opens a PR changing files under `constitution/` and
   registers the proposal with `govtool propose`. The proposal record — id,
   author, diff digest, opened-at timestamp — is appended to the ledger.
2. **Classify.** The semver classifier inspects the diff and labels it
   `kernel-major`, `kernel-minor`, or `userland-patch`. The label determines
   the quorum and threshold the proposal must clear
   ([docs/semver.md](docs/semver.md)).
3. **Vote.** Citizens cast Ed25519-signed ballots during the voting window.
   One person, one vote. Ballots are appended to the ledger as they arrive.
4. **Gate.** CI runs `govtool gate` on the PR: it verifies every ballot
   signature, checks eligibility against the registry, checks quorum, tallies,
   checks the threshold for the classified tier, and runs the invariant checks
   against the amended text. Any failure blocks the merge with a
   machine-readable verdict.
5. **Ratify.** On a passing gate, the ratification workflow merges the PR,
   bumps `constitution/version.yaml` per the classification, tags the release,
   and appends a ratification record to the ledger binding the vote outcome to
   the merge commit.

Everything that matters is in the ledger: proposals, ballots, tallies,
ratifications, fork declarations. The ledger is a hash-chained, append-only
JSONL file; anyone can verify it offline with `govtool ledger verify`
([docs/ledger-format.md](docs/ledger-format.md)).

## Governance semver

| Bump  | What it means                                                   | Default gate (v0)            |
|-------|------------------------------------------------------------------|------------------------------|
| MAJOR | Breaking kernel change: amendment procedure, voting rules, citizenship, invariants, the right to fork | 2/3 supermajority, 50% quorum |
| MINOR | Additive kernel change or a new userland module                  | simple majority, 33% quorum  |
| PATCH | Userland parameter change, clarification, typo                   | simple majority, 25% quorum  |

The classifier is code, not vibes: see [docs/semver.md](docs/semver.md) for
the exact rules and how to dispute a label.

## Forking

The right to fork is Article 7 of the kernel — exit is a first-class
constitutional right, and the tooling makes it cheap. `govtool fork init`
clones the constitution into a new repository with a `fork.yaml` manifest that
records the upstream, the upstream version forked from, and your parameter
overrides. `govtool fork diff` and `govtool fork sync` track upstream
releases. See [docs/forking.md](docs/forking.md).

## Documentation

- [docs/pipeline.md](docs/pipeline.md) — the amendment pipeline, end to end
- [docs/semver.md](docs/semver.md) — governance semver and the classifier
- [docs/forking.md](docs/forking.md) — fork tooling and upstream tracking
- [docs/ledger-format.md](docs/ledger-format.md) — the audit ledger format spec
- [demo/README.md](demo/README.md) — running the end-to-end demo
- [CONTRIBUTING.md](CONTRIBUTING.md) — contributing code and amendments

## Design stance

Optimism in the defaults, paranoia in the tests. The constitution assumes good
faith; the CI assumes bad faith. Every scenario in the (future) adversarial
suite is graded first on how the worst-off participant fares under stress.

## License

MIT for the tooling. The constitution text is dedicated to the public domain —
fork it, live under it, improve it, send the patch upstream.