famlaw_v2/GO_LIVE_RUNBOOK.md

# Go-Live Runbook — `activeblue_familylaw_v2`

Deploying the Active Blue Family Law platform (Odoo 18 Community module
`activeblue_familylaw_v2`, version `18.0.14.0.0`) into production.

This runbook is environment-specific to the current prod stack and assumes the build
state already verified: **200 tests green in live Odoo 18**, module **staged** in the
prod addons path, and a **clean dry-run install on a clone of `db1`** with the legacy
module untouched. See `BUILD_STATUS.md` for verification details.

> **Coexistence guarantee.** Prod already runs a *different, legacy* module named
> `activeblue_familylaw` (models `fl.*`, real data). This module is
> `activeblue_familylaw_v2` with `familylaw.*` models and its own security groups, so it
> installs **alongside** the legacy app. Verified on a `db1` clone: installing `_v2`
> left the legacy module installed and its `fl.*` data intact.

---

## 0. Environment reference (current prod)

| Thing | Value |
|---|---|
| Odoo web container | `odoo-web-1` (image `odoo:18.0`, `workers=0`) |
| Postgres container | `odoo-db-1` (image `postgres:16`) |
| Production database | `db1` |
| DB host / user (from prod env) | `db` / `odoo` (password in the container env — not in this doc) |
| Docker network | `odoo_default` |
| Addons path (host → container) | `/root/odoo/odoo-ai/addons` → `/mnt/extra-addons` |
| Config (host → container) | `/root/odoo/config` → `/etc/odoo` |
| Module location (staged) | `/root/odoo/odoo-ai/addons/activeblue_familylaw_v2` |

Other modules on the path: `activeblue_ai` (unrelated), `activeblue_familylaw` (legacy).

---

## 1. Pre-flight checklist

**Code / install (all ✅ as of this runbook):**
- [x] Steps 1–14 implemented; `python3 scripts/validate_module.py` passes.
- [x] Full suite green in live Odoo 18 (`--test-tags familylaw` → 200/0/0).
- [x] Module staged in prod addons path.
- [x] Dry-run install on a `db1` clone: clean, legacy intact.

**Non-code LAUNCH-BLOCKERS — do NOT run a real client matter until these are closed**
(see `CLAUDE.md` §11; #1–#6 gate the venture, and most are not coding tasks):
- [ ] **Named, engaged, licensed Florida family-law attorney** who validates the legal
      logic and is the reviewing/signing attorney.
- [ ] **Ownership/business model** settled (no nonlawyer firm ownership / fee-split).
- [ ] **Malpractice insurance** contemplating AI-assisted work.
- [ ] **Engagement-letter framework** with an AI-disclosure clause.
- [ ] **Security review + breach-response plan** (privileged data; internet-facing
      DocuSeal host).
- [ ] **UPL guardrails** for the non-lawyer operator (no legal positions to clients).
- [ ] **Legal content validated** for the Tier-3 pieces; `VERIFY`-flagged volatile
      values confirmed (deadline day-counts, $50k 12.902(b)/(c) threshold, 15%/$50
      modification presumption, Rule 12.410 subpoena (eff. 2025-10-01), AO 14-13,
      retention periods).

> Installing the software is safe and reversible. **Operating it on a real matter is
> what the blockers above govern.** You can install and configure now; gate real use
> behind the attorney.

---

## 2. Back up `db1` first (always)

```bash
# Custom-format dump (fast restore); writes inside the db container, then copy out.
docker exec odoo-db-1 sh -c "pg_dump -U odoo -Fc db1 -f /tmp/db1_preinstall_$(date +%F).dump"
docker cp odoo-db-1:/tmp/db1_preinstall_$(date +%F).dump ./
# also snapshot the filestore volume if you keep attachments on disk
# (volume: odoo_odoo-web-data → /var/lib/odoo)
```
Keep the dump until the install is confirmed good.

---

## 3. Stage the module (already done)

The folder is already at `/root/odoo/odoo-ai/addons/activeblue_familylaw_v2`. If
re-staging from the repo:
```bash
docker cp activeblue_familylaw_handoff/activeblue_familylaw_build/activeblue_familylaw_v2 \
  odoo-web-1:/mnt/extra-addons/
# optional: consistent ownership with the other modules (run on the HOST as root)
sudo chown -R root:root /root/odoo/odoo-ai/addons/activeblue_familylaw_v2
```
Files only — staging never installs or touches a database.

---

## 4. Install into `db1`

Pick ONE method.

### Method A — Apps UI (recommended, no downtime)
1. Log into prod Odoo as an administrator.
2. **Apps → Update Apps List** (this refreshes `ir.module.module`; installs nothing).
3. Remove the "Apps" filter, search **"Active Blue Family Law v2"**.
4. Click **Activate / Install**.

### Method B — CLI (requires stopping the web container to avoid two Odoo processes on `db1`)
```bash
docker stop odoo-web-1
docker run --rm --network odoo_default \
  -e HOST=db -e PORT=5432 -e USER=odoo -e PASSWORD=<db_password> \
  -v /root/odoo/odoo-ai/addons:/mnt/extra-addons:ro \
  -v /root/odoo/config:/etc/odoo:ro \
  odoo:18.0 \
  odoo -d db1 -i activeblue_familylaw_v2 --stop-after-init --no-http
docker start odoo-web-1
```
> Do **not** run Method B while `odoo-web-1` is up — two processes installing on the
> same DB can corrupt state.

The module depends only on `base`, `mail`, `calendar` (all standard) — no OCA deps.

---

## 5. Post-install verification

```bash
# module states — v2 installed, legacy untouched
docker exec odoo-db-1 psql -U odoo -d db1 -tc \
 "SELECT name,state,latest_version FROM ir_module_module
  WHERE name IN ('activeblue_familylaw','activeblue_familylaw_v2') ORDER BY name;"

# legacy data still intact (spot check)
docker exec odoo-db-1 psql -U odoo -d db1 -tAc "SELECT count(*) FROM fl_caselaw;"

# v2 artifacts created
docker exec odoo-db-1 psql -U odoo -d db1 -tAc \
 "SELECT count(*) FROM ir_model WHERE model LIKE 'familylaw.%';"          # expect 30
docker exec odoo-db-1 psql -U odoo -d db1 -tAc \
 "SELECT count(*) FROM ir_model_data
  WHERE module='activeblue_familylaw_v2' AND model='res.groups';"          # expect 2
docker exec odoo-db-1 psql -U odoo -d db1 -tAc \
 "SELECT to_regclass('public.familylaw_case') IS NOT NULL;"               # expect t
```
Expected (matches the dry run): `activeblue_familylaw_v2 installed 18.0.14.0.0`,
`activeblue_familylaw installed 18.0.1.0.0`, 30 `familylaw.*` models, 2 groups,
2 crons (overdue-deadline + retention), `familylaw_case` table present.

**UI smoke test (5 min):**
1. **Family Law (v2) → New Intake** → run a standard child-support-modification intake
   → confirms a draft case + initial proceeding are created; conflict screening runs.
2. Open the case → assign attorney → **Clear Conflict Check** (attorney only) →
   **Engage**.
3. **Documents** → create a manual doc → confirm it cannot be filed until approved
   (Gate 1).
4. Assign two security groups to a test staff user and a test attorney user; confirm
   staff see only assigned matters (matter-scoped access).

---

## 6. Configuration (after install)

Set as **System Parameters** (Settings → Technical → System Parameters), readable by
the attorney group only. Without these, the AI / verification / e-signature features
are **inert but harmless** — the spine (intake, cases, deadlines, disclosure,
documents, the gates) works fully without them.

| Key | Purpose | Needed for |
|---|---|---|
| `familylaw.anthropic_api_key` | Claude API key | AI drafting/research (Steps 6/7/9) |
| `familylaw.model` | pinned model id (default `claude-sonnet-4-6`) | AI tasks |
| `familylaw.token_ceiling` | per-task max_tokens (default 4096) | AI cost cap |
| `familylaw.anthropic_endpoint` | override (default `api.anthropic.com/v1/messages`) | AI tasks |
| `familylaw.courtlistener_token` | CourtListener API token | citation verification (Gate 2) |
| `familylaw.courtlistener_endpoint` | override default v4 citation-lookup URL | citation verification |
| `familylaw.docuseal_url` | DocuSeal **Pro** base URL | e-signature (Step 11) |
| `familylaw.docuseal_api_key` | DocuSeal API token | e-signature |
| `familylaw.docuseal_template_id` | default template | e-signature |
| `familylaw.docuseal_webhook_secret` | shared secret for the webhook | e-signature callbacks |

**DocuSeal note:** the API needs **DocuSeal Pro (~$200/yr)**, and its signing host must
be **internet-facing + isolated/hardened** (its Postgres not exposed). Webhook endpoint:
`POST /familylaw/docuseal/webhook` (set `X-Docuseal-Secret` to the shared secret).

**The two sacred gates work regardless of config:**
- Gate 1 (review) — AI/draft docs born unapproved; only an attorney approves; nothing
  files/sends unapproved.
- Gate 2 (citation) — citations born unverified; verification fails CLOSED (down /
  no-record ⇒ stays blocked); filing blocked on any unverified cite.

---

## 7. Rollback / uninstall

If anything looks wrong, the fastest clean rollback is the pre-install dump:
```bash
# restore db1 from the backup (DESTRUCTIVE: drops current db1)
docker stop odoo-web-1
docker exec odoo-db-1 psql -U odoo -d postgres -c "DROP DATABASE db1;"
docker exec odoo-db-1 psql -U odoo -d postgres -c "CREATE DATABASE db1 OWNER odoo;"
docker cp ./db1_preinstall_<DATE>.dump odoo-db-1:/tmp/restore.dump
docker exec odoo-db-1 pg_restore -U odoo -d db1 /tmp/restore.dump
docker start odoo-web-1
```
Alternative (no restore): **Apps → Active Blue Family Law v2 → Uninstall**. Because the
module is isolated (`familylaw.*` models, own groups), uninstalling removes only its
tables/records and leaves the legacy app intact. The pre-install dump is still the
safest path.

To remove the staged files: `rm -rf /root/odoo/odoo-ai/addons/activeblue_familylaw_v2`
(host, as root) — only after it is uninstalled from `db1`.

---

## 8. Known follow-ups (non-blocking)

- **Tier-3 legal content is unvalidated** until the attorney signs off (Steps 6/7/9).
  Build is structural; do not present its legal reasoning as authoritative.
- **Failed-AI-call logging** is durable via an independent transaction; the in-flight
  `running` task row still rolls back on failure (one durable `failed` row results).
- **Legacy `activeblue_familylaw` data** (`fl.*`: ~174 support-schedule entries, 26
  statutes, 25 caselaw, etc.) is *not* migrated into `_v2`. If any is worth carrying
  over, do a separate data-migration pass — it is orthogonal to this install.
- **Real external integrations** (CourtListener coverage for FL DCA/Supreme Court,
  Claude prompts/evals, DocuSeal Pro host) per `CLAUDE.md` §11 #8–#10.

---

## 9. One-line summary for the change log

> Installed `activeblue_familylaw_v2` 18.0.14.0.0 on `db1` (coexists with legacy
> `activeblue_familylaw`; pre-install dump taken; post-install checks green).