famlaw_v2/CLAUDE.md

# CLAUDE.md — Active Blue Family Law Platform

> **Handoff document for Claude Code.** This is the single source of truth for the
> project: what it is, how it's architected, the decisions already made, what's been
> built, and what to build next. Read this fully before writing code. Companion
> design docs (`00`–`11`) live in the design package; this file is the operational
> brief that ties them together.

---

## 1. What we're building (and the one rule that governs everything)

A **case-management platform for a Florida family-law practice** in **Miami-Dade
(11th Judicial Circuit)**, built on **Odoo 18 Community**. A staff member with
**little legal knowledge** enters case data through guided intake; the software
**assembles the case** — manages it, attaches verified case law, tracks
statutory/procedural requirements and evidence, and flags what's needed for
success — and routes a **finished, draft case package to a licensed attorney who
reads it, verifies it, and signs it.** The attorney owns the output.

**THE GOVERNING RULE — non-negotiable, enforced in code, not policy:**

> The software **builds, verifies, organizes, and flags.** A **licensed attorney
> judges, decides, and signs.** Nothing reaches a client, a clerk, or a courtroom
> without attorney approval. The AI is the paralegal who never sleeps — **it is not
> the lawyer.**

**Claude's specific role = the quality-elevation layer.** Claude exists to produce
*high-quality, verified, fully-assembled* work product — drafted documents, extracted
facts, completeness-checked files, and **verified** case-law research — and **move it
UP to the licensed attorney for sign-off**. The point of using a frontier model is the
quality of what gets elevated: the attorney receives something strong enough to approve
with minor edits, fast. Claude *intervenes* by supplying verified case law and the
available next steps/avenues — **not** by deciding strategy or rendering the legal
opinion. The intervention makes the attorney faster; it never replaces them.

This exists because the platform must **not** practice law. Two structural gates
enforce it everywhere:
1. **The review gate** — AI-produced work is born in a draft state; only a licensed
   attorney (group) can approve it; nothing can be filed/sent/signed unapproved.
2. **The citation gate** — every case-law citation is born `unverified` and must
   pass verification (exists / on-point / good-law) against a real database before
   it can enter a filing. (Lawyers have been sanctioned for AI-hallucinated cites;
   this makes that mechanically impossible.)

**The product goal is a high attorney-approval rate achieved by producing genuinely
good, complete, citation-verified work — NOT by making review shallow.** The win
condition is "approve with minor edits, fast," like a senior partner redlining a
strong associate draft.

**How the software improves over time — the SAFE loop (read this carefully).** The
near-term improvement mechanism is **prompt and few-shot-example refinement plus the
regression eval suite** — NOT model fine-tuning on live matters. Family-law work
product is full of **confidential, privileged client data** (Bar Rule 4-1.6); feeding
attorney-corrected drafts into model training risks leaking one client's information
into another client's matter, which is far worse than any bad draft. Therefore:
- The default loop is: attorney edits → those edits inform **curated, hand-written
  exemplars and prompt tweaks** + new regression test cases → output improves. No
  client data enters any training process by default.
- **Fine-tuning is a FUTURE, GATED capability**, not part of this build, and only ever
  on a **de-identified, attorney-approved, consented** corpus held separately that
  **never auto-ingests live matters**. (See doc 09 §10 cautions.)
The attorney is the quality bar and the source of curated examples — never an
unwitting training-data faucet, and never a bottleneck to engineer around.

---

## 2. Capabilities the platform must deliver

Derived backward from the outcome: **a non-lawyer enters facts → a complete,
verified, attorney-signable case package comes out, fast enough that the attorney's
review is confirmatory, not corrective.** Every capability earns its place by serving
that outcome. **Grouped by RISK, not feature area** — the tier tells you what's safe
to build now vs. what needs attorney-validated legal content first.

### Tier 1 — The spine (capture & manage) — *safe to build now; data + deterministic rules*
1. **Guided intake & fact capture** — the adaptive questionnaire (triage routes by
   case type; branches collect exactly the facts each matter needs, in plain
   language). **Highest-leverage capability in the system** — everything downstream
   is only as good as the facts captured here; bad capture is the #1 cause of a draft
   getting sent back.
2. **Case management & system of record** — matter, parties, children, issues,
   **proceedings** (each modification/enforcement is a child `familylaw.proceeding`
   under the case — see §4), lifecycle state, team. The Odoo spine; the container
   everything fills.
3. **Automated conflict-of-interest screening** — when intake captures the opposing
   party, the system **searches every party across every matter** and surfaces
   potential conflicts (opposing party was a past client; is adverse to a current
   client) **for the attorney to clear**. A human ticking a checkbox across hundreds
   of matters *will* miss structural conflicts; an undetected conflict can disqualify
   the firm and void work (Bar Rules 4-1.7/4-1.9). The software does the search a
   human can't do reliably; the **attorney still decides** (the Step 1
   `conflict_check_cleared` gate stays). Belongs in Step 2 (needs the party model).
3. **Document & evidence repository** — every document on the matter, versioned,
   checksummed, with legal metadata (type, privilege, retention). The case file as
   one organized source of truth.
4. **Deadline & calendar engine** — statutory/procedural clocks (answer, disclosure,
   discovery, objection windows) computed deterministically, surfaced on a layered,
   filterable calendar. Pure rules + date math; a real differentiator (a missed
   family-law deadline is malpractice).

### Tier 2 — The assembly (build the case) — *safe to build now; assembly + deterministic scoring*
5. **Document drafting** — first drafts of pleadings/motions/forms from captured
   facts, with placeholders for unknowns, born as drafts for attorney review. Where
   the non-lawyer's facts become legal documents.
6. **Procedural avenue mapping + decision graph** — given case type + what changed,
   surface the *available* procedural paths with their required elements and deadlines,
   rendered as a **branching decision graph** the attorney can compare at a glance. The
   menu, **not** the decision. Suggests; never strategizes. **Each path node shows a
   STRENGTH-OF-SUPPORT comparison — NOT a success percentage:**
   - procedural requirements (forms, elements, proof needed);
   - **strength factors present / missing**, drawn factually from the case data (e.g.
     "income change exceeds 15% threshold ✓; underemployment evidence not gathered ✗;
     financial affidavit on file ✓");
   - effort + timeline (deterministic: deadlines, steps, typical duration);
   - key risks / unknowns ("outcome depends on whether the court imputes income — a
     judgment call for the attorney");
   - what would strengthen the path (the gaps to close).
   **This deliberately does NOT output a win probability.** A "% chance of success" is
   fabricated precision (no honest dataset of comparable sealed/settled Miami-Dade
   outcomes exists), it is functionally the legal *opinion* only a licensed attorney may
   give, it becomes Bar-complaint/malpractice evidence if the case loses, and it anchors
   the attorney into shallow review. The graph compares **which path the facts on hand
   best support**; the attorney converts that into a probability using their own
   judgment and license. (See EXCLUDED, below.)
7. **Requirements & completeness scoring** — the readiness engine: score the file
   against what a complete case of that type/stage needs (forms, proven facts,
   evidentiary foundations, met deadlines) and surface gaps **before** the attorney
   sees it. **The capability that most directly drives approval rate** — it catches
   the omissions that cause rejections. (Feeds the "strength factors" in capability 6.)

### Tier 3 — The legal support (high-risk, high-value core) — *NEEDS attorney-validated legal content before shipping*
8. **Case-law research & verified citations** — propose authority, draft argument,
   and **verify every citation against a real reporter (CourtListener) before it can
   enter a filing**; unverified = mechanically blocked. Most valuable *and* most
   dangerous — the part that makes the software feel like it knows law, and the part
   that gets people sanctioned if built wrong.
9. **Prior-judgment interpretation** — extract structured facts from an existing
   order, summarize it plainly, and **flag** legal-interpretation questions **without
   ruling** on them. Central to the modification/enforcement work this practice
   focuses on.

### Tier 4 — The output & the loop (close it safely) — *the machinery that makes all the above defensible*
10. **Attorney review & approval workflow** — the GATE made into a workflow:
    assembled package → attorney reads, verifies, edits, signs → only then does
    anything move. **Non-negotiable; the capability that makes every other one safe.**
11. **E-signature & filing preparation** — client-facing docs via DocuSeal; court
    filings prepared for `/s/` + Portal upload (prepare-and-upload). The last mile
    from approved draft to going out.
12. **Audit trail** — every fact, AI action, citation verification status, and
    approval reconstructable. Protects the attorney and the practice when anyone asks
    "who did what, and was it checked."
13. **Communications drafting** — plain-language, attorney-reviewed client updates;
    never auto-sends. Keeps clients informed without the attorney writing every email.
14. **Nonlawyer supervision & access control** — the operator is a *low-legal-knowledge
    staffer handling privileged client data*, which triggers the attorney's duty to
    supervise nonlawyer assistants (Bar Rule 4-5.3). So: **matter-scoped access**
    (staff see only their assigned matters, not the whole client base), a nonlawyer-
    conduct acknowledgment, and the hard principle that **staff capture and assemble
    but never communicate legal positions to a client** (extends "never advises" from
    the AI to the human operator). This is a confidentiality + ethics requirement, not
    a nicety.
15. **Data retention & destruction** — Florida imposes file-retention obligations, and
    "keep everything forever in an audit log" is itself a liability (more data = more
    breach surface; some data shouldn't be kept indefinitely). So: **attorney-configured
    retention classes**, a defined **closed-matter lifecycle** (retain → eligible for
    destruction → destroyed, with the action logged), and **client-file return at
    matter close**. The audit trail (12) records *that* destruction happened without
    retaining the destroyed content.

### Deliberately EXCLUDED (these cross from *assist* into *judge* → UPL/liability)
- **Outcome / success-percentage prediction** — NO "% chance of winning" on any path,
  graph, or report. There is no honest dataset of comparable Miami-Dade family-law
  outcomes (cases are sealed, settlements private, "success" isn't binary), so any
  percentage is **fabricated precision**; it is functionally the legal *opinion* only a
  licensed attorney may give; it becomes evidence if a case loses; and it anchors the
  attorney into shallow review. **What IS allowed (capability 6): a strength-of-support
  decision graph** that compares which path the *facts on hand* best support — present/
  missing factors, requirements, effort, risks — leaving the probability judgment to the
  attorney. The distinction is load-bearing: "72% likely to win" = excluded;
  "threshold met, 4 of 5 supporting elements documented" = allowed.
- **Evidence admissibility rulings** — admissibility is a contextual legal ruling.
  The software surfaces an evidence **completeness checklist** ("missing the
  foundation for exhibit C"); it does **not** rule the exhibit admissible.

**Build order implication:** Tiers 1, 2, and 4 are safe to build now (no legal
judgment — data, assembly, deterministic rules, safety machinery). **Tier 3 is gated
behind attorney validation of the underlying legal logic** (the requirements/
elicitation content is the artifact to put in front of a Florida attorney). Build
Tiers 1/2/4 first and gate Tier 3 → genuinely useful product quickly, on the right
side of the line. This maps onto §7: capabilities 1–7 and 10–15 ride Steps 1–14
(conflict screening 3 → Step 2; supervision/access 14 → Steps 2–3; retention 15 →
Step 12); capabilities 8–9 are the Tier-3 pieces (Steps 6, 7, 9) the attorney
questionnaire validates.

---

## 3. Architecture (decided)

- **Odoo 18 Community is the spine:** system of record, workflow/state machines,
  RBAC, audit (`mail.thread`), deadlines (`ir.cron` + `base.automation`), documents,
  calendar, UI. ~70% of needs are Odoo plumbing — **do not rebuild from scratch.**
- **AI = Odoo's own HTTPS call to the Claude API** at `api.anthropic.com/v1/messages`.
  - **No Odoo "AI" feature is used** — Odoo Community has none; this is a plain
    outbound HTTP call from our module.
  - API key in `ir.config_parameter` (encrypted, attorney-group readable only).
  - Model **pinned in config** (`familylaw.model`), recorded per task for audit.
  - Calls run **async via `queue_job`** (OCA) so they never block the web worker.
  - **Provider is pluggable.** Local **Ollama** is a *future* routing option, not
    wired now. Build `_route_model()` so flipping high-confidentiality work to local
    is a **config change, not a redesign**.
  - **Trust/billing reconciliation NEVER reaches any model** — the routing layer
    raises before any such call. (IOTA, Bar Rule 5-1.1 — human-only.)
- **One external service:** an optional **FastAPI orchestrator** for the multi-step
  **research loop** (search → propose citations → verify each → synthesize). Mirrors
  the owner's existing `odoo-ai` pattern. Single-shot AI tasks (drafting, summaries,
  extraction) run **from Odoo directly**; only the agentic research chain goes
  external. Running even that as sequenced `queue_job` steps inside Odoo is an
  acceptable alternative — complexity-vs-consolidation call, not correctness.
- **Satellites:**
  - **DocuSeal** — self-hosted e-signature for *client-facing* docs (court filings use
    the `/s/` convention via the FL E-Filing Portal, **NOT** DocuSeal). **Two material
    caveats (do not bury these):** (1) the **API/embedding needed for the Odoo
    integration requires DocuSeal *Pro* (~$200/yr / ~$20-per-user-mo)** — the free tier
    does core signing but not the programmatic integration; (2) the **DocuSeal signing
    host must be internet-facing**, unlike the rest of the NetBird-internal,
    privacy-first stack — so it must be **isolated and hardened** (its Postgres not
    exposed, audit trail backed up). For a HIPAA-adjacent operator these are design
    facts, not footnotes.
  - **MinIO or Synology NAS** — file archive behind `ir.attachment`.
  - **CourtListener** — citation verification. **It is a single point of failure for
    the citation gate (capability 8 — the thing that prevents sanctions), so:**
    (1) **fail CLOSED** — if CourtListener is down, rate-limited, or has no record for a
    cite, the citation **stays `unverified` and remains blocked**; the system NEVER
    "assumes good" or waves anything through on a verification failure; (2) define at
    least **one fallback source** (e.g. Google Scholar / a secondary API) before relying
    solely on it; (3) **confirm Florida appellate (DCA + Supreme Court) coverage is
    adequate BEFORE building on it** — verify the tool actually works for FL family-law
    authority, don't assume.
- **AI cost & latency (model this from day one):** a fully-assembled matter can mean
  *many* calls (drafting + research + per-citation verification), so a research loop can
  run minutes and cost real money per case. Set a **per-task token ceiling**, and
  **record token cost + latency on each `ai.task`** so the economics are measurable and
  capped, not discovered later. Budget the cost-per-assembled-case explicitly.
- **Court e-filing reality:** the FL Courts E-Filing Portal has **no public push
  API**. The model is **prepare-and-upload**: software prepares, attorney signs
  `/s/`, a human uploads through the Portal, confirmation recorded back in Odoo.

### Tech/environment notes
- **Odoo 18 view syntax:** use `<list>` (NOT `<tree>` — removed in 18). `attrs=`
  and `states=` are **removed**; use direct attributes (`invisible="..."`,
  `readonly="..."`, `required="..."`). Chatter: explicit `oe_chatter` div used for
  cross-release safety (v18 also supports the `<chatter/>` shorthand).
- Owner runs Odoo 18 in production (Docker/Proxmox stack, Postgres, Traefik,
  NetBird). The orchestrator/Ollama/GPU box already exist.
- **Verify volatile legal facts at build time.** Florida renumbers forms and amends
  rules/statutes regularly (e.g., the 2023 alimony overhaul removed permanent
  alimony; Rule 12.410 subpoena amendment effective Oct 1 2025). Never bake a
  specific statute version into code as if permanent; keep "verify current rule"
  in the flow.

---

## 4. Decisions locked (apply these — do not re-litigate)

| Decision | **Choice** | Consequence for the build |
|---|---|---|
| **Intake front door** | **Intake creates a draft case directly** | The intake questionnaire fills a `familylaw.case` that starts in `intake` state. No separate lead/convert step. |
| **Case creation strictness** | **Conditional: strict for standard intake, FAST-PATH for emergencies** | Standard intake = **strict** (require matter name, client, case type, county/court + triage essentials before the draft case commits — the friction is fine and keeps data clean). **Emergency intake = fast-path:** if the urgency screen trips (child withheld / removal threat / violence), creation requires only the bare minimum to act (who, which child, what's happening) and **defers** the rest. Rationale: in a genuine emergency the procedural clock and the child's safety beat data completeness; a bare "strict" rule would block opening the matter exactly when speed matters most. The urgency screen runs first, so it gates which creation path applies. |
| **Modification: how Case A is handled** | **One continuous case; each new proceeding is a child `familylaw.proceeding`** | A modification/enforcement **reopens the same `familylaw.case`** (continuity, full history in one place) **BUT** spawns a new **`familylaw.proceeding`** record under it. **Deadlines, documents, and proceeding-state attach to the PROCEEDING, not the case.** This resolves the flaw in a bare "reopen": without it, the deadline engine can't tell the 2024 dissolution's disclosure clock from a 2027 modification's, and documents/audit from distinct legal proceedings pile together. The case is the client-matter spine; the proceeding is the unit of legal action. (Reconciles with doc 03's parent/child structure — same idea, named `proceeding`.) |
| **"Interpret the prior judgment"** | **Extraction + plain summary + legal interpretation (flagged, not concluded)** | The AI extracts structured facts, writes a plain-language summary, **and** may surface legal interpretation of provisions — but interpretation is **flagged for the attorney, never stated as a conclusion/ruling.** Born as draft; attorney decides. |

Other standing choices from design: **native Odoo models** for the questionnaire
(NOT the Survey app) — answers must land as typed case data the workflow can use,
with no survey→case mapping layer. Markdown for docs; module version-controlled in
Gitea by the owner.

---

## 5. The build method — VERIFIABLE STEPS (follow strictly)

Build in small, independently verifiable slices. **Do not start step N+1 until step
N's tests are green and its walkthrough passes.** Every step delivers, in order:

1. **Installable code** — installs/upgrades cleanly (`-u activeblue_familylaw`).
2. **A walkthrough** — a UI click-path that shows the new behaviour end to end.
3. **Tagged unit tests** — under `tests/`, tagged `familylaw_step<N>`, proving the
   step's guarantees (especially the gates).
4. **Done-when** — explicit pass condition: green tests + clean walkthrough → ship,
   then advance.

### Test harness
- Tests subclass `TransactionCase` (savepoint rollback; DB stays clean).
- Tag: `@tagged("post_install", "-at_install", "familylaw", "familylaw_step<N>")`.
- Group-gated actions: `new_test_user(..., groups="base.group_user,activeblue_familylaw.group_familylaw_attorney")`; call with `.with_user(attorney)` / `.with_user(paralegal)`.
- **External APIs are ALWAYS mocked** (`unittest.mock.patch`) — Claude, DocuSeal,
  CourtListener. Tests must never hit the network. Assert on what got written to
  Odoo (e.g. "document born `ai_draft`", "citation born `unverified`").
- **Date math tested with fixed dates**, never `today()`, for determinism.

Run all: `odoo -d <db> -i activeblue_familylaw --test-enable --stop-after-init`
Run one step: `odoo -d <db> -u activeblue_familylaw --test-enable --test-tags familylaw_step1 --stop-after-init`

---

## 6. What's already built — STEP 1 ✅ (delivered, validated)

Module: `activeblue_familylaw` (in the Step 1 zip; layout below).

**`familylaw.case`** — the matter spine:
- Identity: `name`, `client_id` (res.partner), `case_type` (selection: dissolution
  w/ & w/o children, paternity, support/parenting/alimony modification, enforcement,
  DV injunction, other).
- Team: `attorney_id`, `paralegal_id` (res.users).
- **`representation`** (attorney / pro_se) — drives the Step 8 subpoena branch.
- **`conflict_check_cleared`** (attorney-only gate, readonly, tracked).
- **`state`** lifecycle: `intake → engaged → disclosure → discovery → mediation →
  hearing → closed`, with **guarded transitions** (each checks current state, rejects
  illegal jumps) and **attorney-only** actions (`action_mark_conflict_cleared`,
  `action_close`, `action_reopen`) enforced in **Python AND** via `groups=` on buttons.
- `mail.thread` / `mail.activity.mixin` — every transition + clearance posts to the
  chatter (the audit trail).

**Security:** groups `group_familylaw_user` (Staff) and `group_familylaw_attorney`
(Attorney, implies Staff implies internal). Access rules: staff can't delete; attorney can.

**Views:** list (`<list>`), form (statusbar + transition buttons + chatter), search
(filters: My Cases, Open, Awaiting Conflict Clearance; group-by: stage/attorney/type).
**Menu:** Family Law → Cases (+ Configuration placeholder).

**Tests (`tests/test_case_lifecycle.py`, tag `familylaw_step1`):** 10 tests — initial
state, conflict-clearance gate (engage blocked until cleared; only attorney clears),
illegal-transition rejection, full forward path, attorney-only close/reopen, audit
logging. Statically validated: Python compiles, XML well-formed, manifest is a dict,
every button maps to a method, every view field exists on the model, zero
Odoo-18-forbidden constructs.

### Module layout
```
activeblue_familylaw/
  __init__.py
  __manifest__.py            # depends: base, mail
  models/
    __init__.py
    familylaw_case.py        # the spine + state machine + gates
  security/
    familylaw_security.xml   # groups + module category
    ir.model.access.csv      # staff (no unlink) / attorney (full)
  views/
    familylaw_case_views.xml # list, form, search, action
    familylaw_menus.xml      # app menu
  tests/
    __init__.py
    test_case_lifecycle.py   # familylaw_step1
```

---

## 7. The step sequence (roadmap)

| Step | Slice | Key models / files | Proves (tests) | Doc |
|---|---|---|---|---|
| **1 ✅** | Case spine + lifecycle + attorney gates | `familylaw.case`, security, views | transitions, conflict gate, attorney-only, audit | 02,03 |
| **2 → NEXT** | **Parties, children, issues + `proceeding` + conflict screening + `case_number` + search + intake questionnaire** | `familylaw.party`, `.child`, `.issue`, **`familylaw.proceeding`**; indexed `case_number`; conflict-search method; intake wizard | relations, DOB constraints, **find by party/child/case number**, **conflict search surfaces a past-client opposing party**, questionnaire creates draft case (strict) / emergency fast-path, urgency flag raised, "good case?" captured not answered | 02,03 |
| 3 | **Documents + the review gate** | `familylaw.document` (`ai_draft→attorney_review→approved`), attached to a **proceeding** | only attorney approves; can't file/send unapproved (GATE 1) | 03,04 |
| 4 | Deadline engine | `familylaw.deadline` (**FK to `proceeding`, not case**) + `base.automation` + `ir.cron` + `calendar.event` mirror | 20/45/30-day math, weekend roll, overdue, **deadlines isolated per proceeding** | 02,11 |
| 5 | Mandatory disclosure (Rule 12.285) | `disclosure.item`, `financial.affidavit`, `fin.line` (per proceeding) | 12.902(b) vs (c) by income, 45-day due, can't-waive | 02,11 |
| 6 | **Claude client + `ai.task` ledger** (single-shot) | `familylaw.ai.client`, `ai.task` (**logs model + token cost + latency**), drafting agent, `queue_job` | (mocked) doc born `ai_draft`, task logged w/ cost, cites born `unverified` | 04,09 |
| 7 | **Citation ledger + filing gate** + research loop | `familylaw.citation`, `action_request_filing`, FastAPI orchestrator; **fail-closed verification + fallback source** | filing blocked on any unverified cite (GATE 2); verification failure keeps cite blocked | 06 |
| 8 | **Discovery + subpoena** (12.351 gate + pro-se/attorney branch) | `discovery.request`, objection-window gate | objection-window hard gate, same-day Notice of Issuance, clerk-vs-attorney routing | 11 A.6,C |
| 9 | **Child-support modification** workflow (end to end) | wires 1–8 for `support_modification`; **new `proceeding` under the reopened case** | 15%/$50 threshold, 20-day answer, DOR-case flag, retroactivity note, **prior-judgment extraction+summary+flagged interpretation** | 11 B.2 |
| 10 | **Emergency** workflow (12.941 pick-up/removal) | emergency motion records + required-attachment checks; **uses the intake fast-path** | have-order-vs-not fork; missing-attachment block; fast-path opens matter on minimum facts | 11 B.1 |
| 11 | DocuSeal e-signature | `action_send_for_signature`, webhook controller (**Pro tier; isolated internet-facing host**) | (mocked) only `approved` sends; webhook → `signed` | 05 |
| 12 | File archive + calendar layers + **retention lifecycle** | `ir.attachment` + `familylaw.archive` metadata; calendar categories; retention classes + closed-matter destruction | SHA-256 checksum, **retention class drives destruction-eligibility**, client-file-return at close, **per-layer filter toggles** | new |
| 13 | Miami-Dade auto-seed (AO 14-13) | Status Quo Order, parenting-course + mediation obligations on case open | obligations seed on open; course-before-judgment guard | 11 D |
| 14 | Comms agent + AI-assisted billing flag + hardening + **matter-scoped access** | `comms` drafts, `time.entry.ai_assisted`, record rules scoping staff to assigned matters, encryption/backup | (mocked) comms never auto-sends; AI ratio reportable; **staff can't see unassigned matters** | 04,08 |

**Intake questionnaire** (native models; intake-creates-draft-case; **conditional
strictness — strict for standard, fast-path for emergencies**) is the high-leverage
elicitation layer. It belongs with **Step 2** (it needs the party/child fields) and is
built **triage section + ONE case-type branch (child-support modification first)**,
then more branches added incrementally. The triage **urgency screen runs FIRST** and
selects strict vs. fast-path creation. It captures facts only — it **never answers**
"do I have a good case?" (logs that as a question for the attorney).

**MVP to run a solo practice:** Steps 1–6 + 8 + 11, then add 7. Steps 9/10 are the
headline workflows; 12–14 round it out.

---

## 8. STEP 2 — the immediate task (build this next)

**Goal:** the related records that make a matter real, the **proceeding** layer that
keeps modifications/enforcements cleanly separated, **automated conflict screening**,
search the way a practice actually searches (by people + court case number), and the
intake questionnaire front door (conditional strict / emergency fast-path).

**Build:**
1. **`familylaw.party`** — a party to the matter (`res.partner` + role: client /
   opposing party / opposing counsel / other). Opposing-party capture feeds conflict
   screening (#6).
2. **`familylaw.child`** — a minor child (name, DOB **with validation: reject future
   or implausible dates**, link to case); searchable.
3. **`familylaw.issue`** — a contested issue (time-sharing, support, equitable
   distribution, alimony, etc.) — the spine for later requirements scoring.
4. **`familylaw.proceeding`** — **the unit of legal action under a case.** A case can
   have many proceedings over time (original dissolution, later modification, later
   enforcement). Fields: `case_id` (FK), `proceeding_type`, `state` (its own
   lifecycle), open/close dates. **From here on, deadlines and documents attach to a
   proceeding, not directly to the case** (Steps 3–5 build on this). On case creation,
   open an initial proceeding for the originating matter.
5. **`case_number`** on `familylaw.case` — court-assigned (e.g. 2024-DR-001234),
   **indexed + searchable**. (A proceeding may also carry its own number if the court
   assigns one.)
6. **Automated conflict screening** — a method that, given the captured opposing
   party, **searches `familylaw.party` across ALL cases** and returns potential
   conflicts (opposing party matches a past/current client; or is already an opposing
   party elsewhere). Surface the hits **on the case for the attorney to clear** — it
   does **not** auto-clear or auto-block; the Step 1 `conflict_check_cleared` attorney
   gate remains the decision point. (Name-match can be fuzzy; flag for human review,
   never auto-resolve.)
7. **Search-by-person / by-number:** extend case search so a matter is findable by
   party name, child name, and `case_number` — not just title/client.
8. **Intake questionnaire (native; creates draft case; conditional strictness):** a
   guided multi-step flow that (a) runs **triage FIRST** (caller + contact, opposing
   party, minor children y/n, county/court, existing case/order, **urgency screen:
   child withheld / removal threat / violence**), (b) **branches on urgency**:
   *standard* → strict (require name, client, case type, county + triage essentials
   before commit); *emergency* → **fast-path** (commit on minimum facts: who, which
   child, what's happening; defer the rest), (c) branches into the **child-support
   modification** question set, and (d) on completion **creates a draft
   `familylaw.case` in `intake` state** (and its initial proceeding). Runs conflict
   screening (#6) as part of completion. Collects facts only.

**Tests (`familylaw_step2`):** relation integrity (party/child/issue/proceeding ↔
case); DOB constraint rejects future/implausible dates; **find case by party name /
child name / case_number** returns the right matter; **conflict screening surfaces a
past-client opposing party** and does NOT auto-clear; a case can hold **multiple
proceedings** and each carries its own state; questionnaire triage sets case type;
**standard path enforces strict creation** (rejects incomplete submission);
**emergency path commits on minimum facts** and raises the urgency flag; "do I have a
good case?" is **captured as an attorney question, never answered**.

**Constraints:** Odoo 18 syntax (`<list>`, direct attributes — no `<tree>`, no
`attrs`/`states`). **No external/network calls in Step 2** (questionnaire is pure data
capture; AI extraction of an uploaded judgment is Step 6+; conflict screening is a
local DB search, not an AI call). Keep the gate philosophy intact — nothing here
advises, decides, or auto-clears a conflict.

**Done-when:** `familylaw_step2` tests green + a walkthrough where you (a) complete a
*standard* modification intake and land on a new draft case with an initial
proceeding; (b) complete an *emergency* intake and get a matter opened on minimum
facts with the urgency flag set; (c) see a conflict flag when the opposing party
matches an existing client; and (d) find an existing case by opposing-party name, by
child name, and by case number.

---

## 9. Working agreements for Claude Code

- **Read the relevant design doc (`00`–`11`) before each step**; this file says
  *what/next*, the docs say *why/detail*.
- **One verifiable step at a time.** Don't scaffold ahead. Deliver code + tests +
  walkthrough, stop, confirm green, then continue.
- **The two gates are sacred.** Never add a code path that lets AI output be
  filed/sent/signed without attorney approval, or lets an unverified citation into a
  filing. If a request would breach this, flag it instead of building it.
- **Mock all external APIs in tests.** Never hit Claude/DocuSeal/CourtListener from a
  test.
- **Verify volatile legal facts** (forms, rules, statutes) against current sources at
  build time; keep "verify current rule" in the flow rather than hardcoding a version
  as permanent.
- **Owner profile:** experienced infra/dev (Proxmox, Docker, Postgres, Python,
  Odoo 18 in prod). Be direct and technical; prefer CLI; the owner version-controls
  in Gitea. Plan fully, validate each stage.
- **This is not legal advice** and the platform must not practice law; a licensed
  attorney reviews, verifies, and signs all output.

---

## 10. Design-revision changelog (audit fixes applied to this revision)

Nine flaws were found in a critical design review and fixed in this document:

1. **Training-data flywheel → safe improvement loop (§1).** The "attorney corrections
   become training data" claim risked leaking privileged client data (Rule 4-1.6) and
   assumed nonexistent fine-tuning infra. Replaced with prompt/example refinement +
   regression evals as the default; fine-tuning is future/gated on a de-identified,
   consented, separate corpus.
2. **Bare "reopen" → `familylaw.proceeding` model (§4, §7, §8).** Reopening one case
   repeatedly would conflate deadlines/documents/audit across distinct legal
   proceedings and contradicted doc 03. Now: one continuous case, each
   modification/enforcement is a child proceeding that owns its own deadlines/docs/state.
3. **Conflict checkbox → automated conflict screening (capability 3, Step 2).** A human
   ticking a box misses structural conflicts across many matters. Added a DB-wide
   party search that surfaces conflicts for the attorney to clear (attorney still decides).
4. **Strict creation vs. emergencies → conditional strictness (§4, Step 2/10).** Strict
   field requirements would block opening a genuine emergency matter. Now strict for
   standard intake, fast-path (minimum facts) when the urgency screen trips.
5. **AI cost/latency unmodeled → budgeted (§3, Step 6).** Added per-task token ceiling
   and cost+latency logging on `ai.task`; budget cost-per-assembled-case explicitly.
6. **CourtListener single point of failure → fail-closed + fallback + FL-coverage check
   (§3, Step 7).** Verification failure now keeps a cite blocked (never "assume good"),
   a fallback source is required, and Florida appellate coverage must be confirmed first.
7. **Non-lawyer operator confidentiality → supervision + matter-scoped access
   (capability 14, Step 14).** Added Rule 4-5.3 supervision layer, matter-scoped record
   rules, and the principle that staff never communicate legal positions to clients.
8. **DocuSeal caveats restored (§3, Step 11).** Surfaced the Pro-tier cost (~$200/yr for
   the API) and the internet-facing/isolated-host requirement at the architecture level.
9. **No retention policy → retention & destruction capability (capability 15, Step 12).**
   Added attorney-configured retention classes, a closed-matter destruction lifecycle,
   and client-file return at close (audit logs *that* destruction occurred, not the content).

**Note:** none of these were defects in the delivered Step 1 *code* — they were in the
surrounding design. Step 1 remains valid. The structural change that most affects
forthcoming work is the `familylaw.proceeding` model (fix 2), which Step 2 introduces
and Steps 3–5 build on.

**Later additions (this revision):**
10. **Strength-of-support decision graph, NOT a success-percentage predictor
    (capability 6, EXCLUDED).** A requested "% chance of success per path" was declined
    as fabricated precision / functional legal opinion / liability, and replaced with a
    factual path-comparison graph (present-missing factors, requirements, effort, risks)
    that leaves the probability judgment to the attorney.
11. **Claude's role clarified as the quality-elevation layer (§1)** and a new **§11
    "Requirements for Success"** added — the non-code gaps (engaged licensed attorney,
    practice-ownership model, malpractice insurance, engagement-letter AI clause,
    security/breach plan, operator UPL guardrails, content-maintenance process, the
    elicitation content, FL-proven citation source, eval/QA, cost model). #1 (attorney)
    and #2 (ownership) gate the venture; both are non-coding and run parallel to Steps 2–5.

---

## 11. Requirements for SUCCESS (non-code gaps that must be closed)

The 15 capabilities make the software *function*. These items make the venture
*succeed and stay legal*. Several are **launch-blockers**, not enhancements. They are
not optional, and most cannot be solved by writing code.

### Critical — blocks the whole model
1. **A named, engaged, licensed Florida family-law attorney — NOW, not at launch.**
   The entire architecture routes assembled cases to a reviewing/signing attorney; with
   no such attorney, there is no one to hand the case to and the product cannot legally
   operate. This attorney must (a) **validate the legal logic** in docs 02/11 (forms,
   deadlines, avenues, 11th-Circuit specifics), (b) be the **actual reviewing/signing
   attorney**, and (c) **own the malpractice and Bar exposure**. *First concrete step:
   the attorney-review questionnaire (below) — it turns the researched-but-unvalidated
   legal logic into something a Florida attorney can confirm and sign off.*
2. **Settle "whose practice is this?" (ownership / business model).** Florida prohibits
   nonlawyer ownership of law firms and fee-splitting with nonlawyers. Clean model:
   **Active Blue builds/operates the software; a licensed firm uses it.** Problematic
   model: **Active Blue runs the practice** — no code fixes that. Resolve before
   building the Tier-3 legal-reasoning pieces, because the answer shapes how they're
   built and who the "attorney" in the workflow legally is.

### Launch-blockers — required before a single real client matter
3. **Malpractice insurance that contemplates AI-assisted work**, carried by the
   responsible attorney/firm.
4. **Engagement-letter framework with an AI-disclosure clause** — the client is told AI
   assists their matter and a licensed attorney reviews and is responsible.
5. **Security review + breach-response plan for privileged data.** The privacy-first
   stack is a head start, but privileged legal data + a non-lawyer operator + an
   internet-facing DocuSeal host needs an actual review, encryption-at-rest for case
   data, and an incident plan — not just good instincts.
6. **UPL guardrails for the human operator** (pairs with capability 14): the non-lawyer
   never communicates legal positions/opinions to clients; all legal questions route to
   the attorney; this is trained and enforced, not assumed.

### Ongoing — required to stay correct over time
7. **A legal-content maintenance process.** Florida changed alimony (2023) and subpoena
   rules (2025); forms get renumbered. Someone must **watch for rule/form/statute
   changes and update the logic** on a schedule. A case built on a repealed form is a
   malpractice event. "Verify current rule" handles point-in-time; this handles drift.
8. **The requirements/elicitation content itself** (unblocks capabilities 7 & 8). The
   per-case-type definition of "what a complete, winnable file requires" — elements,
   proof, forms, the strength factors the decision graph reads — **does not exist yet**.
   This is the artifact the attorney validates and the engine consumes; without it,
   completeness-scoring and research have nothing authoritative to check against.
9. **A citation-verification source proven for Florida** (pairs with §3 architecture):
   confirm CourtListener (+ fallback) actually covers FL DCA + Supreme Court family-law
   authority adequately before relying on the citation gate in production.
10. **A real evaluation/QA process before anything is client-facing.** The regression
    eval suite (doc 09 §9) wired to run before every prompt/model change; a defined bar
    the assembled output must clear; attorney spot-audits of approved work.

### Strongly recommended — for the product to actually deliver its promise
11. **Cost-per-assembled-case model** (pairs with §3 / Step 6): know the token cost and
    latency of a full matter so pricing and the economics hold; cap per-task spend.
12. **Client intake/consent for AI involvement** captured in the record (distinct from
    the engagement letter): the client's informed acknowledgment, logged.
13. **A "human-in-the-loop won't be skipped" enforcement audit**: periodic proof that no
    code path and no operator habit lets unreviewed/unsigned work reach a client, clerk,
    or court — the two gates verified in practice, not just in tests.

**Bottom line:** of everything above, **#1 (the attorney) and #2 (the ownership model)
gate the venture** — neither is a coding task, both should be moving in parallel with
Steps 2–5, and #1 starts with the attorney-review questionnaire. The software can be
~80–90% built and validated and still cannot run a real matter until #1–#6 are closed.