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).
4. 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.
5. 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.