# Website versioning integration — handoff

Branch: `feat/v3-website-versioning` (based on `feat/v3-prompt-completion-integration`)
Scope: additive website compatibility layer for V2/V3 versioning. Not deployed,
not published, no production config change, no V2 route or behavior change.

## Key paths

| Path | Purpose |
| --- | --- |
| `baseline/deployments.json` | Canonical, single source of truth for 134 V2 deployments |
| `pr9/website/scripts/generate_website_addresses.py` | Generator (`--check` = CI drift gate) |
| `pr9/website/generated/website-addresses.generated.ts` | Generated address constants — never hand-edit |
| `pr9/website/src/version-flags.ts` | Default-off V3 feature/write flags, version resolution |
| `pr9/website/src/truth-labels.ts` | The five allowed truth labels |
| `pr9/website/src/v3-action-gate.ts` | Fail-closed gate for versioned actions |
| `pr9/website/src/v2-legacy-adapter.ts` | Behavior-neutral replacement for the site's V2 map |
| `pr9/website/tests/` | Vitest suite (default-off, generation, labels, gate, parity) |
| `pr9/website/README.md` | Full integration doc and follow-up wiring snippet |
| `ci/release-gates.sh` | Runs the generator check plus the PR9 test/typecheck gates |
| `v2-repo/repos/theloopbreaker-site` | Nested website mirror (git-ignored here; untouched) |

## Conventions for later edits

1. **Addresses.** Never add an address literal to website code. Edit
   `baseline/deployments.json`, rerun the generator, commit the regenerated file.
   `DEPLOYMENTS_SHA256` pins the source; stale output fails CI.
2. **V3 defaults.** New V3 capability starts as a new `false` field in
   `V3FeatureFlags` with its own env key. Only the literal `"true"` enables it.
   Never derive a flag from another flag, from `NODE_ENV`, or from a truthy cast.
3. **Version selection.** V3 is reachable only via explicit in-session selection.
   Do not add an "auto", "latest", or remembered-preference default.
4. **Labels.** Use only `TRUTH_LABELS`. Adding a label means updating
   `src/truth-labels.ts`, the generator's `_baseline_truth_label`, and
   `tests/truth-labels.spec.ts` together.
5. **Money movement.** Route every V3 fund-moving action through
   `evaluateVersionedAction`. Missing evidence must stay a blocker; never default
   a status report or pilot gate to a healthy value, and never fall back to V2.
6. **V2 untouched.** The V2 branch of the gate takes no V3 evidence and cannot be
   blocked by V3 flags. Keep it that way.
7. **Nested site.** `v2-repo/` is git-ignored. Website-side edits belong in the
   site repository; keep this package free of website imports (ABI resolution is
   injected).

## Open items / blockers for enabling anything

- No verified V3 addresses exist in `baseline/deployments.json`, so V3 money
  movement is blocked by design (`v3-deployment-address-missing`).
- `pr7/api/v3/protocol-status.ts` returns HTTP 503 `degraded` until live readers
  are configured, which keeps the status gate blocked.
- `pr8/pilot/check_pilot_gate.py` reports `pilotReady: false` until executable
  evidence is recorded, which keeps the pilot gate blocked.
- The one-file swap inside the nested site (`app/lib/contracts.ts`) is documented
  but not applied here, because that tree is a git-ignored vendored mirror.
