Add spec-driven architecture review page

.github/workflows/spec-graph.yml

@@ -0,0 +1,29 @@
+name: Spec graph
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  generated-spec-graph:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Regenerate production-backed spec graph
+        run: python3 scripts/generate_spec_graph.py
+
+      - name: Check generated graph is committed
+        run: git diff --exit-code -- data/spec-graph.json
+
+      - name: Validate graph, HTML, and renderer
+        run: python3 scripts/check_spec_graph.py

README.md

@@ -4,16 +4,35 @@ Landing site for **populace** — an open-source stack for building weighted
 synthetic populations from survey and administrative data.
 
 - The stack: https://github.com/PolicyEngine/populace
-- The site: a single static page (`index.html` + `style.css` + `field.js`),
-  no build step.
+- The site: static HTML/CSS/JS pages, no framework build step.
 
 ## Develop
 
 ```bash
 python3 -m http.server 4399
 # open http://localhost:4399
+# local static route for the spec page: http://localhost:4399/spec.html
 ```
 
+## Spec Graph
+
+`/spec` reads `data/spec-graph.json`, which is generated from production
+Populace and Ledger source contracts plus Populace country package manifests.
+Do not edit the graph JSON by hand. CI regenerates it and fails if the
+committed artifact drifts.
+
+```bash
+python3 scripts/generate_spec_graph.py
+```
+
+By default the generator reads `PolicyEngine/populace@main` and
+`PolicyEngine/arch-data@main` from GitHub raw URLs. Set `POPULACE_REPO_DIR` or
+`LEDGER_REPO_DIR` to point at a local checkout while developing against an
+unmerged branch.
+
+See `docs/spec-source-audit.md` for the current production-backed surfaces and
+the remaining country-pack work.
+
 ## Design
 
 Typography: Fraunces (display) · Newsreader (body) · IBM Plex Mono (labels).