docs: import qa workflow knowledge from grilling session

docs/state-machines.md

@@ -0,0 +1,49 @@
+---
+last_updated: 2025-07-15
+tags: [state-machines, domain-model, yara724]
+source: import-knowledge
+---
+
+# State Machines — Yara724 Case Lifecycle
+
+A Case has three independent state machines that run sequentially (Blame first, then Claim).
+
+## Case Status
+
+The top-level lifecycle of the entire Case.
+_Avoid_: Case State, Case Phase
+
+| Status | Description |
+|---|---|
+| OPEN | Initial state. Persists from creation through inviting the second party. |
+| WAITING_FOR_SECOND_PARTY | Second party has been invited, awaiting their response. |
+| WAITING_FOR_EXPERT | Blame resulted in disagreement; case escalated to Expert. |
+| WAITING_FOR_DOCUMENT_RESEND | Expert or system requests additional documents from user. |
+| WAITING_FOR_SIGNATURES | Awaiting signatures from relevant parties. |
+| COMPLETED | Case fully resolved (Blame decided + Claim processed if applicable). |
+| CANCELLED | Case voluntarily cancelled by a party. |
+| AUTO_CLOSED | Case closed automatically (e.g., timeout, policy expired). |
+
+## Blame Status
+
+Determines whether the case proceeds between the parties or requires Expert intervention.
+_Avoid_: Blame State, Fault Status
+
+| Status | Description |
+|---|---|
+| UNKNOWN | Initial state. Awaiting first party's fault attribution. |
+| AGREED | Parties agree on fault attribution. Case proceeds directly to Claim without Expert. |
+| DISAGREEMENT | Parties disagree on fault. Case escalates to Expert for determination. |
+
+## Claim Status
+
+The financial compensation track — only active after Blame is resolved and a Claim is filed.
+_Avoid_: Claim State
+
+| Status | Description |
+|---|---|
+| PENDING | Claim filed, awaiting initial review. |
+| UNDER_REVIEW | Expert or Insurer actively reviewing the Claim. |
+| APPROVED | Claim approved for payout. |
+| REJECTED | Claim denied. |
+| NEEDS_REVISION | Claim returned to user for corrections or additional information. |