phase: 33_gateway_route_switching

Phase 33 completion pass is done. Final report:

## Phase 33 — completion report

**All 8 task files complete** (`.agents/phases/complete/33_gateway_route_switching/`), full gate green, docs verified.

### Work in this pass

1. **`tests/test_routectl.py` added** (17 tests, all green) — exercises the *real* helper binary unprivileged against a fake tree (`--root`), the real agent parser, the captured gateway fixtures, and stubbed `nginx`/`haproxy`/`systemctl` on `PATH`. Pins the full protocol (locate → state → dry-run → temp-file/fsync/`os.replace` write → checker → restore on checker failure → reload-never-restart → re-read proof → sidecar record), all three route shapes (haproxy `server`, nginx `proxy_pass`, nginx stream `map` via its sink-value id), `drift` / unknown-id / `map-default` refusals, `list`/`verify`, and the `--serve` peer gate (`SO_PEERCRED` uid check, one JSON line per request, exact body shape).

2. **Real helper defect fixed** — `deploy/dashboards-routectl.py`: `main()`'s early-return paths returned `({"ok": False, …}, EXIT_*)` tuples, so `sys.exit()` printed a Python repr instead of a JSON line (usage errors, agent-import refusal). Now prints `json.dumps(…)` and returns only the code, keeping the one-JSON-line contract.

3. **Documentation consistency fixes** (task 08 criterion 6):
   - `README.md`: garbled verdict-colour sentence on the switch ("green and to the position") → "in the **on** position and tinted `--gate-on`" (the existence-pair contract).
   - `README.md`: audit sentence now names all three event kinds — `route-disabled` / `route-enabled` / **`route-denied`** (the code stores one per refused call; dry runs store none).
   - `page-gateway.js`: replaced the stale pre-33 module docstring ("the switch is not wired") with the two-arm `GATEWAY_ALLOW_WRITES` contract.
   - `AGENTS.md`: every phase-33 claim re-verified against code (the ten gates, the 35 s/30 s budget pair, `gateway.writes_enabled`, `/api/summary`'s `disabled`, the 1.4.0 agent bullet, the gap list) — no changes needed.

### Verification
- `uv run pytest --cov`: **1970 passed**, 18 skipped — coverage **98.74%** (floor 94%)
- `ruff` clean · `pyright` 0 errors · `bash .agents/validate.sh` **exit 0** (incl. `node --check` on every page script)
- Dev server running; all 10 sources `ok`; bundles exported

### Live infrastructure
**No live changes made.** The live drill remains unexecuted per `data/logs/NOTES-33-switching.md` (no operator approval; checker binaries unavailable in the podman proxy units). All routes stay enabled, config hashes unchanged, and the sandbox rehearsal + backup tree are in place for the operator's own `DANGER` call. All changes are in the working tree only.

tests/test_auth_docs.py

@@ -124,6 +124,39 @@ def test_the_local_testing_password_is_prose_and_never_an_assignment(template: P
         )
 
 
+#: The write gate phase 33 added. The pin is the **declaration** — a comment that names
+#: the variable (with its default and what enabling it authorises) — never an assignment:
+#: a value in a tracked template is a decision made for everyone who copies the file, and
+#: the configuration table refuses that trap (the two writes are two decisions, and one
+#: flag does not carry the other).
+WRITE_GATES = ("GATEWAY_ALLOW_WRITES",)
+
+
+@pytest.mark.parametrize("template", TEMPLATES, ids=lambda p: p.name)
+def test_every_write_gate_is_declared_and_never_assigned_in_the_template(template: Path) -> None:
+    """A write gate no template names is a gate nobody finds.
+
+    The declaration is a comment (a commented-out line, or prose naming the variable with
+    its default and what enabling it authorises). An *active* assignment in a tracked
+    template is the gate armed by default for everyone who copies the file —
+    `GATEWAY_ALLOW_WRITES=1` in a template is a route switch waiting in a fresh
+    deployment.
+    """
+    text = template.read_text()
+    for name in WRITE_GATES:
+        commented = [ln for ln in text.splitlines()
+                    if name in ln and ln.lstrip().startswith("#")]
+        assert commented, (
+            f"{template.name} never names {name} in a comment — a write gate nobody finds "
+            "is a gate whose default nobody can see"
+        )
+        active = re.search(rf"^[ \t]*(?:export[ \t]+)?{name}[ \t]*=(?!=)", text, re.MULTILINE)
+        assert active is None, (
+            f"{template.name} actively assigns {name} — a value in a tracked template is a "
+            "decision for everyone who copies it; the pin is the declaration, never a value"
+        )
+
+
 def test_the_dev_template_points_at_where_the_local_password_lives() -> None:
     """A dev copying the template needs to know what to type at the first login prompt."""
     text = ENV_DEV_EXAMPLE.read_text().lower()