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):

• Steps 1–14 implemented; python3 scripts/validate_module.py passes.
• Full suite green in live Odoo 18 (--test-tags familylaw → 200/0/0).
• Module staged in prod addons path.
• 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)

# 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:

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)

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

# 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:

# 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).