⭐ STAR Voting — Score, Then Automatic Runoff

What this library is

A library for learning, teaching, and debating better voting methods — STAR and its bloc and proportional forms, Approval, Ranked Robin — with choose-one, RCV-IRV and STV taught alongside them for honest comparison. STAR gets the most shelf space; no method here gets a free pass. Every claim is backed by a runnable example election, counted by real tabulation engines — including ones nobody here wrote, so a result is never just this library agreeing with itself. The even-handedness is the argument: you can check every claim yourself.

Looking for something specific? → Start Here routes you by what you want — learn STAR, see what's broken about voting today, compare methods even-handedly, or run the engine yourself.

Under the hood it does three things:

1. Teaches — concept pages and worked examples, organized by level: Voting 101 (the basics) · 201 (reading results & comparisons) · 301 (proportional, criteria, theory).
2. Proves — every claim is backed by a runnable election: a single YAML file a person reads and the engine runs.
3. Cross-verifies with BetterVoting — import a real election from BetterVoting (the Equal Vote Coalition's free STAR platform), re-tabulate it independently, and confirm the official winner — turning real elections into regression cases that catch and guard BetterVoting's bugs (turnout undercounts, tie mislabels, abstention miscounts).

Built on a vendored fork of Larry Hastings' starvote engine.

---

The YAML election file

Every claim in this library is backed by one of these — a whole election in a file a person can read and the engine can count:

voting_method: STAR
num_winners: 1
ballots: |-
  Ann,Bob,Cal
  5,4,0
  3,5,2
  0,3,5
expected_winners:
- Bob

This exact election is the repo's canonical leading example — it lives as a runnable file (bv2187_qrw6wb_ann-bob-cal.yaml · reader page), is reused verbatim across the intro docs, and runs live on BetterVoting ↗ (election qrw6wb). The registry of all reusable teaching elections (and the freeze rule that keeps them stable) is TIPS — Canonical Elections.

Why the format is YAML, what every field does, and what happens to the file once you run it → YAML election files — why, what, how — the format's front door, with the fill-in authoring template one click further. House style keeps examples small (how many voters?), and the ladder that settles a dead heat is STAR Tie-Breaking — The Full Chain.

---

Browse the library

The same ten sections as the sidebar, in the same order — each one's landing page says what's inside and indexes its runnable cases.

Section	What's in it
⭐ 01 STAR	The headline method, one seat. The lessons first — the ballot, the two rounds, tie-breaking, the honest limits — then the runnable examples, the real BetterVoting elections, and the criteria pages.
02 STAR Bloc	Several seats at once, majoritarian: the same ballot, run once per seat — and, just as importantly, when not to use it.
03 STAR PR	Several seats at once, proportional: the same score ballot counted so seats reflect the electorate's proportions (sss · allocated · rrv).
04 Approval	Approve or don't — Score voting at one bit of resolution. Enormous gain in expressiveness over choose-one, for almost no ballot complexity.
05 Ranked Robin	Ranked ballots counted head-to-head, so the candidate who beats the most rivals wins — the friendly upgrade for people who like ranking.
06 Other methods	Taught, not promoted: Choose-One (Plurality), RCV-IRV, STV, Range/Score, and the historical also-rans — here for honest comparison.
07 Concepts	The cross-method half: the curriculum (101 / 201 / 301), the glossary, the topic pages (center squeeze, monotonicity, summability…), and the voting paradoxes.
STARVote LH tabulation engine	The engine that counts every example here — Larry Hastings' starvote, vendored and forked, plus what this fork adds.
YAML library	The election-file format itself: why YAML, what every field does, the BetterVoting importer, and the deliberately-broken files that prove bad input fails politely.
Method comparisons	The crown jewels — same ballots, different methods, where the contrast between them is the lesson.

Two indexes cut across those ten: Browse by tag sorts the concept pages by what kind of question they answer rather than which method, and the Glossary defines every term the rest of the library uses.

Contributors / running it locally → start at CONTRIBUTING.md (setup + the edit-regenerate-test loop). The Repository & Engine Guide has the repository map, quick-start commands, how the voting methods dispatch, the validation philosophy, and what the vendored engine adds. House conventions: CLAUDE.md.