# Version History — Empower Guyana Canvass / Data Platform

A consolidated record of how the platform reached **v1.0**. This is the appendix to
the spec (see `FEATURES.md`, `SPECS_OVERVIEW_v3.md`); it absorbs the now-completed
planning documents so the working `docs/` set stays lean. Every archived plan below
remains recoverable from git history.

---

## v1.0 (2026-05-29) — pilot reference implementation, security-reviewed

The deployable reference build. Feature-complete, hardened, security-reviewed, and
tagged `v1.0`.

**What it is:** an election canvassing + voter-data platform for Guyana (~773,165
voters). Node 22 + `node:sqlite` (pilot) hand-rolled HTTP server; vanilla-JS SPA;
the SQLite build is the reference implementation the IT team productionizes onto
Postgres (the `encryptField` interface stubs production crypto; heavy-scale + real
KMS are the deferred "X-slices").

### Milestones that produced v1.0

1. **Pilot (Phases A–D).** The original canvassing app: roles/auth/RBAC, voter
   master + canvass overlay, turf/field workflow, offline packs + sync, analytics +
   region explorer, GIS crosswalk wizard, messaging/GOTV scaffold, notifications,
   hotline CRM, election-day modules, GECOM export placeholders. Field-hardened
   through pilot-acceptance gates (Phases B & C) and a deployment runbook (Phase D).

2. **Data Platform programme — 98 slices, Waves 0–4 (locked 2026-05-28, completed).**
   - **W0 foundations:** the `voter_uid` spine (773,165), overlay-table pattern,
     `field-crypto`/`match-engine` (shared), the append-only `change-log`, and the
     universal `edit-framework` (preview→commit→rollback).
   - **W1 results + admin-editability + reconciliation:** results-review queue +
     audited corrections, a config-driven admin entity editor, voter-list
     reconciliation (match-engine tiers, report buckets, reversible apply).
   - **W2 voter lifecycle + identity/PII + vote history:** lifecycle states,
     dispute/dedup/merge, the encrypted `voter_identity` store (masked-by-default,
     gated reveal/export), ID-as-match-key, doorstep verify, previous-ID lineage,
     official-turnout vs self-reported history.
   - **W3 attributes + elections/candidates:** the flexible tag model (sensitive
     tags manager-only), bulk tagging, segmentation, the elections/parties/
     candidates/contests/candidacies/results model + historical backfill (LGE2023,
     GE2025).
   - **W4 messaging + LAA command surfaces + admin-edit extension + sweeps:**
     message authoring/publish/feed, LAA summary/activity, reversible bulk campaign
     edits, and the writer/export guardrail sweep (`verify:guardrails`).

3. **EDAY hardening + hosting resiliency.** Security headers + CSP, rate-limiting,
   MFA step-up, body cap, dependency patch (npm audit 0), backup/restore + off-box
   replication, graceful shutdown, `/api/ready`, metrics + JSON logs, schema
   preflight (`verify:schema`), index audit, runbooks, exact LAA scoping (HB-4),
   the read-mostly degradation switch (HE-2).

4. **Multi-agent QA scour + pre-v1.0 security review.** A 17-agent QA pass (10
   verified fixes) followed by a 42-agent security review across 12 threat
   dimensions → 24 confirmed findings, all exploitable/contained ones fixed:
   - **Critical:** the raw plaintext voter roll had been committed to git — purged
     from working tree **and all history**, gitignored.
   - **High:** stored XSS in the admin Users view — escaped + server-side guards.
   - **Medium/Low:** id_hash made a keyed HMAC (off by default; prod pepper +
     `migrate:id-hash-rekey`), reconcile id_hash leak closed, DoS/rate-limit gaps
     closed, admin-status routes gated, security headers on all responses,
     constant-time login, audit_events folded into the mutation transaction,
     append-only crosswalk rollback, and more.
   - Production prod-gates (KMS swap, id_hash pepper, production CSP, off-box
     backup encryption, monitoring, external pen-test, Postgres cutover) are
     documented in `DATA_PLATFORM_EDAY_HARDENING.md §Security review`.

5. **Post-v1.0 cleanup.** Cross-cutting concision refactors (shared `guards.mjs`;
   reconciliation diff/scope helpers) and the two low-severity fix-forwards.

**Gates at v1.0:** `smoke:pilot` 296 pass / 3 pre-existing-unrelated;
`verify:guardrails` clean; `verify:schema` 23/23 tables + 4/4 migration flags;
`npm audit` 0.

---

## Appendix — archived planning documents

These planning/process artifacts described work that is now **complete or
superseded**. They were removed from `docs/` in the v1.0 consolidation; their
outcomes are recorded here and the full text remains in git history.

| Archived doc | Outcome |
|---|---|
| `DATA_PLATFORM_ROADMAP.md` | The 9-domain / 98-slice programme rationale — fully delivered; living feature set now in `FEATURES.md`. |
| `BREAKDOWN_ANALYTICS_PLAN.md` | Regional analytics + region-explorer slices — shipped. |
| `NEXT_10_SLICES.md` | Pre-demo work plan — 8 of 10 shipped (crosswalk, compare mode, badges, handbook); 2 deferred. |
| `PHASE_B_ACCEPTANCE.md` | Phase B pilot acceptance gate — passed. |
| `PHASE_C_ACCEPTANCE.md` | Phase C field-hardened pilot acceptance — passed. |
| `PILOT_CHECKLIST.md` | Pre-trial pilot environment validation — done. |
| `UI_REVAMP_PLAN.md` | Six UI quick-win proposals — implemented. |
| `UI_POLISH_PLAN.md` | Six pre-LGE polish slices — shipped/merged. |
| `UI_SCREENS.md` | Role-based screen inventory — superseded by `UI_AUDIT.md` / `UI_IMPROVEMENTS.md`. |
| `SPECS_OVERVIEW_v2.md` | Pre-LGE2023 spec baseline — superseded by `SPECS_OVERVIEW_v3.md`. |
| `GIS_MAPPER_REVIEW.md` | Map-viewer integration review — viewer now integrated into the SPA. |
| `DEMO_PREP_THURSDAY.md` | 2026-05-28 leadership-demo prep checklist — event passed. |
| `DEMO_SCRIPT.md` | 2026-05-28 leadership-demo script (5/15/25-min) — event passed. |