# Canon — Source-of-Truth Chain and Terminology

**Status:** Canonical. Every other artifact (doc, website copy, video script, social post) inherits from this chain. An artifact that contradicts an upstream document is wrong by definition and must be fixed or archived.

**Enforcement:** `tools/check_canon.py` scans canonical docs, frontend content, and video files for deprecated terms and retired figures. Run it before any commit that touches content (it is also installed as a git pre-commit hook). This file is the human-readable contract; the script is the machine check.

---

## 1. Inheritance order

When two documents disagree, the one higher in this chain wins. Fix or archive the lower one — never "interpret around" the conflict.

| Rank | Document | Owns |
|---|---|---|
| 1 | `party_constitution.md` | Mechanisms: selection (Stage 4A/4B), institutions, funding caps, goals |
| 2 | `evidence_stats.md` | Every public number. No statistic appears anywhere unless it is here |
| 3 | `neocracy_definition.md` | The canonical definition of Neocracy (synced with frontend `neocracy.ts`) |
| 4 | `narrative_architecture.md` | Sequencing: what gets said first, what gets hidden early |
| 5 | `communication_charter.md` | Tone and ethics of all public communication |
| 6 | This file (`canon.md`) | Terminology, naming, visual tokens, deprecation list |
| 7 | Everything else | Marketing, pitch, video scripts, website copy, manuals |

**Visual source of truth:** `web/neocrates-frontend/DESIGN.md` (palette, typography). All media — website, video, thumbnails, slides — inherits it. See §4.

**Website primary sources:** Canonical markdown copies under `web/neocrates-frontend/public/research/` are synced from `docs/` via `npm run sync-research` (runs automatically before `npm run build`).

---

## 2. Canonical terminology (glossary)

| Canonical term | Use for | Deprecated synonyms (do not use) |
|---|---|---|
| **Four mechanisms** (Certification, Measurement, Transparency, Research) | First-contact public comms: video, homepage, social | "four pillars" |
| **Four institutions** (Pravesh Parishad, Gati Parishad, Satyanishtha Aayog, Niti Shakha) | Constitutional/structural contexts: constitution, institutions page, deep docs | "four pillars" |
| **Stage 4A — panel evaluation** | Published expert scores, completed first | — |
| **Stage 4B — constituency public vote** | Final candidate selection from the certified pool | "sortition" (for *final* selection) |
| **Sortition** | ONLY the citizen seat on Stage 4 panels (drawn from trained Jan Karya volunteers) | any use implying it picks candidates |
| **Neocracy** | The governance framework/model | — |
| **Neocrates** | The standards organization developing the framework | — |
| **NNP (Nava Niti Party)** | The pilot/reference implementation; a 30-year experiment | introducing NNP before Neocrates in any narrative (per `narrative_architecture.md`) |
| **Social Mobility Index (SMI)** | The binding outcome metric | "mobility score" without definition |
| **Bottom-half upward mobility ~38 (India) / ~47 (Denmark) / ~42 (US)** | The mobility evidence | 0.45 correlation; 67% MPs; 4%/12% quintile figures (all retired — see `evidence_stats.md`) |
| **Rs. 10,000/year** | The constitutional individual donation cap | confusing it with the Rs. 500 founding-supporter pledge (different thing; always distinguish) |
| **neocrates.org** | The canonical public domain | mixed references to neocracy.in etc. without a domain-strategy decision |

### Naming rule of thumb

- Talking to the public for the first time → **mechanisms** (what it does).
- Talking about structure and governance → **institutions** (what it is).
- Never **pillars** — the word appears in no canonical document.

---

## 3. Numbers rule

1. A statistic may only be used if it appears in `evidence_stats.md` with a source.
2. New statistic? Add it to `evidence_stats.md` (with citation) *first*, then use it.
3. Retired statistic resurfaces anywhere → that is a canon violation, not a style issue.
4. Canonical citation for mobility: **Asher, S., Novosad, P., & Rafkin, C. (2024)**, AEJ: Applied 16(2), doi:10.1257/app.20210686 — never "Asher et al., 2021".

---

## 4. Visual tokens (inherited from `web/neocrates-frontend/DESIGN.md`)

| Token | Value | Meaning in media |
|---|---|---|
| Paper | `#F7F6F2` | Background |
| Ink | `#0C0C0C` | Primary text, end cards |
| Navy (primary) | `#1A3C5E` | Institutions, mechanisms, structure |
| Muted red (secondary) | `#8B3A32` | Problems, misalignment, failure |
| Gold (accent) | `#9A7B2E` | Principles, goals, highlights |
| Muted text | `#5C6570` | Captions, sources |
| Headings | Source Serif 4 | All media including video |
| Body | Source Sans 3 | All media including video |
| Numbers/stats | IBM Plex Mono | Evidence on screen |

**Deprecated:** teal `#00A8A8` (early storyboard draft); the Blue/Gold/Muted Red/Gray language in the video production manual Part IV; any font other than the three above (including DejaVu render fallbacks — install the real fonts in the render environment).

For video-specific direction see `media/intro-video/VISUAL_DIRECTION.md`.

---

## 5. Change-propagation workflow

The sortition incident happened because a mechanism changed upstream and the change relied on human memory to propagate. The workflow that replaces memory:

1. **Change upstream first.** Mechanism changes go to the constitution; numbers go to `evidence_stats.md`; terminology goes to this file.
2. **Deprecate, don't just replace.** When a term/number/color is retired, add it to the deprecation tables here **and** to the `RULES` list in `tools/check_canon.py` in the same commit. This is the step that makes the change self-enforcing forever.
3. **Run the checker.** `python3 tools/check_canon.py` — it fails loudly on any live file containing a deprecated term. The pre-commit hook runs it automatically.
4. **Log it.** One entry in `refinement_changelog.md` per semantic change; tick off `alignment_backlog.md` items it resolves.
5. **Never bulk-regenerate** canonical `.md` from `.docx` (per `PROJECT_OVERVIEW.md`).

The principle is the project's own thesis applied to itself: don't rely on the virtue (or memory) of the maintainer — design the rule so the bad state cannot pass silently.

---

## 6. Known open decisions (do not paper over)

These are real forks awaiting a deliberate decision, tracked here so nobody "resolves" them accidentally in downstream copy:

- **Caste/diversity within merit:** constitution Art. 16 says "not through quota"; `NNP_Strategic_Framework.md` proposes within-merit quotas. Until decided, downstream copy must not assert either position as settled.
- **Beachhead states:** Strategic Framework says "let the data decide"; older docs name Delhi/Karnataka/Maharashtra. Until decided, do not name states in new public copy.
- **Domain strategy:** neocrates.org vs JanKarya.in vs nnp.neocrates.org — one decision doc needed.