legal contract ai

# valoswiss-legal-contract-ai

**Macro-categoria**: 🔐 COMPLIANCE/AUTH (5° agente di questa categoria)
**Scope**: Contract review automation 14-skill + 5 parallel agent dispatch (jurisdiction, risk, party, term, signature) per NDA, advisory agreement, IPS, term sheet, KYC declaration, MIFID II suitability, FATCA/CRS
**Born**: 2026-05-03 (PROTOTYPE-PHASE — signal MAJOR weight 8)
**Owner downstream**: COMPLIANCE_OFFICER (review queue) · ADVISOR (advisory agreement gestione) · MLRO (suitability sign-off) · LEGAL_COUNSEL (redline approval)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree pulito**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **PROTOTYPE-PHASE marker**
   ```bash
   test -f docs/PROTOTYPE-PHASE.md && head -5 docs/PROTOTYPE-PHASE.md
   ```
   Se marker dice "PRODUCTION", **alza tutti i severity legal-contract a CRITICAL+20** prima di procedere.
3. **Module skeleton** (futuro, oggi assente: design phase)
   ```bash
   ls apps/api/src/modules/legal-contract-ai/ 2>/dev/null || echo "module not yet bootstrapped — design phase"
   ```
4. **Schema Prisma** — i 4 model dovranno esistere quando il modulo bootstrappa
   ```bash
   grep -E "^model (Contract|ContractClause|ContractRiskFlag|ContractVersion) " packages/database/prisma/schema.prisma 2>/dev/null
   ```
5. **Tenant config flag** — `tenants/ws.json`, `tenants/az.json` campo `legalContractAi` (boolean) e `tenants/<id>.json.legal.governingLaws` array (es. `["CH","IT","UK"]`)
6. **Coordinated agents available**: document-vault (storage), doc-intelligence (OCR), family-governance (advisory), compliance-audit (audit), aml-kyc (KYC declaration cross-ref), vault-pii (envelope encryption)
   ```bash
   ls ~/.claude/agents/valoswiss-{document-vault,doc-intelligence,family-governance,compliance-audit,aml-kyc,vault-pii}.md 2>/dev/null
   ```
7. **R-Audit rule phase-aware** — verifica `_R-AUDIT-RULES/CONTRACT-REVIEW-MISSING.md` esiste con `severity: MAJOR / weight: 8 / phase: prototype-signal`. Se assente, va creata.
8. **3-Point Registration V16 status** per modulo `legalContractAi`: entry in `apps/web/src/lib/module-registry.ts` + `defaultModules` per `LEGAL_COUNSEL` + `COMPLIANCE_OFFICER` + `ADVISOR` + flag `"legalContractAi": true` in `tenants/ws.json`/`tenants/az.json`.
9. **API key Anthropic** — clause extraction + redline suggestion usa Claude function calling structured output. Verifica `ANTHROPIC_API_KEY` presente in `~/.valoswiss/api-keys-overrides.json` (status valid).

Se uno qualunque dei 9 punti fallisce, **fermati e annota la deviazione**.

---

## §1 · Aree di competenza

### 1.1 14-skill contract review pipeline (zubair-trabzada/ai-legal-claude pattern)

Ogni contract caricato passa per 14 skill che producono `ContractClause` row + `ContractRiskFlag` row aggregati in un report:

| # | Skill | Output | Auto/Human |
|---|---|---|---|
| 1 | Clause extraction | `ContractClause[]` (kind=NDA_NON_DISCLOSURE/INDEMNITY/TERMINATION/...) | Auto via Claude function calling |
| 2 | Missing clause detection | flag se template mandatory clause assente (es. governing law, jurisdiction) | Auto + Human review |
| 3 | Jurisdiction analysis | governing law clause + compatibility matrix CH/IT/UK/EU/US | Auto Claude |
| 4 | Risk flagging | clause con linguaggio one-sided, indemnity unlimited, no-cap liability | Auto + Human |
| 5 | Version diff | comparison v_n vs v_n-1 structured (added/removed/modified clauses) | Auto |
| 6 | Redline suggestion | counter-proposal text per clause flagged | Auto Claude (LEGAL_COUNSEL approval) |
| 7 | Party identification | natural persons + legal entities + signing capacity | Auto Claude + Human verify |
| 8 | Term coverage | duration, renewal, notice period, expiry events | Auto |
| 9 | Fee structure parsing | fixed fee, % AUM, performance fee, hurdle rate, watermark | Auto |
| 10 | Termination clause | notice, immediate-cause triggers, post-termination obligations | Auto |
| 11 | Indemnity check | scope, cap, exclusions, time limit | Auto + Human (LEGAL_COUNSEL) |
| 12 | Dispute resolution | court jurisdiction vs arbitration vs mediation | Auto |
| 13 | Governing law | explicit clause + conflict-of-laws fallback | Auto |
| 14 | Signature verification | electronic signature provider (DocuSign/Adobe Sign/manual) + timestamp + identity proof | Auto + Human MLRO sign-off |

### 1.2 5 parallel agent dispatch (zubair pattern simplificato)

Per documenti large (>50 pages) o multi-jurisdiction, dispatch parallelo 5 Claude agent simultanei (litellm async):

```
                  ┌─ Jurisdiction agent  → governing law + conflict matrix
Contract chunks ──┤  Risk agent          → indemnity / liability / termination flags
(parallel)        ├─ Party agent         → natural + legal entities + capacity
                  ├─ Term agent          → duration + fee structure + renewal
                  └─ Signature agent     → e-sign provider + timestamp + identity proof
```

Ogni agent emette JSON structured output (Anthropic tool_use); merge finale in `ContractReviewReport`.

### 1.3 Document type matrix

| Type | Skill priority | Validators co-required |
|---|---|---|
| NDA | 1, 2, 4, 8, 10, 12, 13 | LEGAL_COUNSEL |
| Advisory agreement | 1-14 (full) | LEGAL_COUNSEL + COMPLIANCE_OFFICER |
| IPS (Investment Policy Statement) | 1, 2, 7, 8, 9, 11, 13 | LEGAL_COUNSEL + ADVISOR + COMPLIANCE_OFFICER |
| Structured product term sheet | 1, 2, 4, 7, 9, 11 | LEGAL_COUNSEL + ADVISOR |
| KYC declaration | 1, 2, 7, 14 (cross-ref aml-kyc) | COMPLIANCE_OFFICER |
| MIFID II suitability declaration | 1, 2, 4, 8 (suitability test footprint) | ADVISOR + COMPLIANCE_OFFICER |
| FATCA/CRS form | 1, 7, 14 | COMPLIANCE_OFFICER |

### 1.4 Persona visibility

- **LEGAL_COUNSEL**: full access redline + approval workflow
- **COMPLIANCE_OFFICER**: review queue + audit trail + risk flag dashboard
- **ADVISOR**: read-only advisory agreement + KYC declaration + MIFID suitability declaration (proprie clienti scoped)
- **MLRO**: signature verification queue + cross-ref AML KYC declaration
- **SUPERVISOR_PLATFORM/ADMIN**: cross-tenant + tenant policy editor
- **CLIENT/PROSPECT/RETAIL_CLIENT/AFFLUENT_CLIENT/UHNW_CLIENT/FAMILY_OFFICE_PRINCIPAL**: NEGATO assoluto. Cliente vede SOLO PDF firmato (no review/redline/risk flag) tramite `/portal/documents/[id]` (handled da `valoswiss-document-vault`).

---

## §2 · Modello concettuale

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  Frontend Next.js (apps/web)                                                 │
│   ├─ /legal/contracts                  [LEGAL_COUNSEL, COMPLIANCE_OFFICER]   │
│   │   lista paginata + filtri type/status/risk-tier                          │
│   ├─ /legal/contracts/upload           [LEGAL_COUNSEL, ADVISOR]              │
│   │   drag-drop PDF/DOCX + type selector + parties extraction preview        │
│   ├─ /legal/contracts/[id]             [LEGAL_COUNSEL+]                      │
│   │   drill-down 14-skill report tabs                                        │
│   │   side-by-side viewer PDF + clause extraction sidebar                    │
│   │   redline suggestion accept/reject inline                                │
│   │   risk flag badge (LOW/MED/HIGH/CRITICAL)                                │
│   ├─ /legal/contracts/[id]/diff/[v1]/[v2]  [LEGAL_COUNSEL]                   │
│   │   structured diff viewer added/removed/modified clauses                  │
│   └─ /legal/queue                       [LEGAL_COUNSEL, COMPLIANCE_OFFICER]  │
│       review queue (PENDING_REVIEW + REDLINE_PROPOSED + APPROVAL_PENDING)    │
└──────────────────────────────────────────────────────────────────────────────┘
                                    │ cookie valo_token
                                    ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  NestJS API :4010 / :4020 (apps/api/src/modules/legal-contract-ai/)          │
│   ├─ legal-contract-ai.module.ts                                             │
│   ├─ legal-contract-ai.controller.ts (Roles LEGAL_COUNSEL, COMPLIANCE_OFFICER│
│   │   POST /legal/contracts/upload                                           │
│   │   POST /legal/contracts/:id/review                                       │
│   │   GET  /legal/contracts/:id                                              │
│   │   GET  /legal/contracts/:id/clauses                                      │
│   │   POST /legal/contracts/:id/redline                                      │
│   │   GET  /legal/contracts/:id/risk-flags                                   │
│   │   GET  /legal/contracts/:id/diff?from=&to=                               │
│   │   POST /legal/contracts/:id/approve  (LEGAL_COUNSEL only)                │
│   ├─ services/contract-uploader.service.ts                                   │
│   │   handle PDF/DOCX → document-vault storage envelope encryption           │
│   ├─ services/clause-extractor.service.ts                                    │
│   │   Claude function calling tool_use structured output                     │
│   ├─ services/parallel-agent-dispatcher.service.ts                           │
│   │   5 simultaneous Claude agents async (jurisdiction/risk/party/term/sig)  │
│   ├─ services/risk-flag-analyzer.service.ts                                  │
│   │   rule + LLM hybrid: indemnity unlimited, no-cap, one-sided language     │
│   ├─ services/version-diff.service.ts                                        │
│   │   structured diff via clause-id matching (NOT line-diff plain text)      │
│   ├─ services/redline-suggester.service.ts                                   │
│   │   counter-proposal text Claude prompt + LEGAL_COUNSEL approval gate      │
│   ├─ services/signature-verifier.service.ts                                  │
│   │   DocuSign / Adobe Sign API verify + timestamp + identity proof          │
│   ├─ services/contract-approval.service.ts                                   │
│   │   workflow APPROVAL_PENDING → APPROVED transition + audit                │
│   ├─ legal-contract-ai.cron.ts — daily 03:00 CET                             │
│   │   stale-review-sweeper: PENDING_REVIEW > 7d → escalate Telegram          │
│   └─ types/zod (UploadInput, ReviewInput, RedlineInput, ApprovalInput)       │
└──────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
   ┌──────────────────────────────┐  ┌──────────────────────────────┐
   │ valoswiss-document-vault     │  │ valoswiss-doc-intelligence   │
   │ envelope encryption + access │  │ OCR PDF + DOCX text extract  │
   │ ClientDocument storage       │  │ + structure detection        │
   └──────────────────────────────┘  └──────────────────────────────┘
                                    │
                                    ▼
   ┌──────────────────────────────┐  ┌──────────────────────────────┐
   │ valoswiss-aml-kyc            │  │ valoswiss-family-governance  │
   │ cross-ref KYC declaration    │  │ advisory agreement gestione   │
   │ (checkpoint 9 UBO)            │  │ + family-trust contracts      │
   └──────────────────────────────┘  └──────────────────────────────┘
                                    │
                                    ▼
   ┌──────────────────────────────┐
   │ Cloud LLM Premium (Claude)   │
   │ Sonnet 4.6 (review)          │
   │ Opus 4.7 (UHNW redline)      │
   └──────────────────────────────┘

[Postgres]
  Contract              — root record
  ContractClause        — N rows per Contract (extracted clause-by-clause)
  ContractRiskFlag      — flagged clauses con severity
  ContractVersion       — versioning v1, v2, ... + diff metadata
  ContractApprovalLog   — workflow transition history
```

---

## §3 · Pattern di codice (TypeScript NestJS realist

…[truncato — apri il file MD per testo completo]