Documentation: accurate README + full /docs tree

The README described intent; the repo is now real. Rewrote it to reflect what actually exists — 17,506 validated files across four entity types, the deterministic pipeline, the commands — and added the /docs tree: government-as-code.md the philosophy: git primitives -> government data-model.md entity types, IDs, file format, the tree, determinism sources.md where every fact comes from, and how current roadmap.md done / next / later, honest about what isn't built contributing.md the disciplines, and how to add a source Plus data/sources/sources.yaml — the machine-readable source registry. Every count, path, and source claim is grounded in the current tree, not the aspirational brief. Internal links verified; validation still clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-04 08:38:06 -04:00
parent 2e5197d1a3
commit 316c4e563c
7 changed files with 429 additions and 7 deletions
@@ -0,0 +1,56 @@
+# Contributing
+
+Republic OS is a mirror maintained mostly by agents, but its rules are simple enough that anyone can work in it. This page covers the disciplines that keep the mirror trustworthy and the practical steps for adding to it.
+
+## The disciplines
+
+Three rules govern everything, and they are won by subtraction — by declining to destroy:
+
+1. **Never overwrite.** A change is a new commit, not a clobbered file. Deletes are diffs.
+2. **Never rewrite history.** No force-push, no squash. The past is load-bearing — it *is* the changelog.
+3. **Always push off-box.** One copy is a single point of failure; more is not.
+
+And one rule that makes every diff meaningful:
+
+4. **The build is deterministic.** Entity files change only when the government changes. Never introduce pipeline noise (run timestamps, unstable ordering, reformatting) into an entity file. If `make build` run twice produces a diff, that is a bug.
+
+## The shape of a change
+
+Everything flows one direction:
+
+```
+official source ──► raw export (data/*.jsonl) ──► build.py ──► entity tree
+```
+
+- **Raw first.** A new source lands in `data/<source>.jsonl` committed *as-is*, before any transformation. The origin must always be recoverable.
+- **Build, don't hand-edit.** Entity files under `data/jurisdictions/` are generated. To change them, change the source or the generator — never edit a generated file by hand, or the next build will overwrite it (and you'll have created noise, not signal).
+- **Validate before committing.** `make check` runs the build and then validates all files. It must pass.
+
+## Adding a source
+
+1. Obtain the data as JSONL (one JSON object per line) and commit it to `data/<source>.jsonl` untouched.
+2. Register it in [`data/sources/sources.yaml`](../data/sources/sources.yaml) and note it in [docs/sources.md](sources.md).
+3. Extend [`scripts/build.py`](../scripts/build.py) to read it and emit entities. Follow the existing patterns:
+   - Emit frontmatter keys in a **fixed order**; sort all iteration.
+   - Carry **field-level `sources`** and a `confidence` level on every record.
+   - Use **path-based IDs** with lowercase slugs and stable government identifiers where available.
+   - Reconcile to existing entities by a shared key, or by normalized name where none exists.
+4. If it's a new entity type, add a JSON Schema to [`/schemas`](../schemas) — a stricter profile over OKF (required fields, property types, enums), tolerating unknown keys.
+5. Run `make check`. Fix anything it reports.
+6. Commit with a message that describes the *civic* change, not just the code change (see the existing history for the tone).
+
+## Reading a change
+
+You do not need deep git knowledge to read the mirror — four commands cover it:
+
+```bash
+git log -- <path>     # the timeline of any official, body, or place
+git diff <a>..<b>     # what changed between two states
+git show <commit>     # one change, in full
+git blame <path>      # where each fact came from
+make changelog        # the same, rendered as a plain-language civic changelog
+```
+
+## A note on truth
+
+When the mirror disagrees with an official record, the official record is right and the mirror has a bug. Report it as a finding — the gap between the model and reality is information, not embarrassment. This repository never claims to be the authority; it only makes the authority easier to read.