# Stappenplan — naar het einddoel

> **Einddoel (zie AGENTS.md):** Notary.AI is een autonome, ervaren notariële
> medewerker die — uit de aangeleverde (bron)documenten — zelfstandig
> (1) de ontwerpdocumenten opstelt, (2) de modelmails klaarmaakt en
> (3) de afrekeningen berekent (aktekosten/ereloon én schenk-/erfbelasting),
> telkens als **werkdocument** dat de notaris naleest en valideert.

Dit stappenplan vertaalt dat einddoel naar concrete, controleerbare fasen. Het
respecteert het **governend principe** (genereren/berekenen = vrij & autonoom;
muteren van de kantoorbibliotheek = altijd via wijzigingsvoorstel) en de
**GDPR-regel** (nooit persoonsgegevens naar de API/MCP).

---

## Noordster-metriek

Eén meetbaar getal stuurt de prioriteiten: **hoeveel van het werkdocument is
correct, deterministisch ingevuld zonder dat de notaris moet kiezen of aanvullen?**

Operationeel meten we per gouden-pad-scenario:
- **# open `[KIES DE HYPOTHESE]`-blokken** (doel: 0 zodra de feiten gekend zijn);
- **# `[AAN TE VULLEN]`-velden** die uit de brongegevens hadden kunnen komen;
- **# onzekerheden** in het `AutonoomWerkdossier` (uit `werkdossier.ts`).

Elke fase hieronder verlaagt dit getal voor een groeiende set dossiertypes.

---

## Fase 0 — Fundament (✅ aanwezig)

Het skelet van het einddoel staat en werkt:
- **Autonome motor**: `lib/dossier/werkdossier.ts` orkestreert de vier pijlers
  (`autonoom.ts`, `modelmails.ts`, `afrekening.ts`, `opvolging.ts`) tot één
  `AutonoomWerkdossier` met gebundelde onzekerheden.
- **Deterministische hypothese-engine**: `lib/dossier/kenmerken.ts`
  (`kenmerkenNaarKeuzes` + `heldereTaalKeuzes`) — niet-persoonsgebonden feiten →
  hypothesekeuzes, reproduceerbaar, met veilige default (bij twijfel niets
  schrappen).
- **MCP/API**: `lib/openapi.ts` (één bron van waarheid) + `app/api/mcp/route.ts`.
- **Validatie-flow**: wijzigingsvoorstellen → tab "Te valideren"
  (`voorstellen.ts`, Supabase).
- **GDPR-aanpak**: placeholders + lokale invulling (`handoff.ts`, `ai-prompts.ts`).

➡️ De rest van het stappenplan verbreedt en verdiept dit fundament.

---

## Fase 1 — Het gouden pad perfectioneren (verkoop/compromis)

**Doel:** één dossiertype tot het einde "af" maken, als referentie-implementatie
en kwaliteitslat voor alle volgende. Het heldere-taal-compromis is dat pad.

1. **Determinisme afdichten.** Voor elk resterend `[KIES]`-blok: ofwel een
   deterministisch kenmerk toevoegen (zoals recent: keuring elektrische
   installatie, syndicus-info, groenestroomcertificaten), ofwel uitdrukkelijk
   documenteren waarom het een notariskeuze blijft.
   _Meet met de noordster-metriek; streefdoel = 0 open blokken bij een volledig
   dossier._
   _Gerealiseerd (2026-07, detail in de git-historie van dit bestand):_
   ✅ intake-contract verbreed (betaling, kredietofferte, notarissen,
   eigendomstitel, medeEigendom, attest-deelvelden) — de flessenhals bleek het
   aantal *slots*, niet het model; bewaakt door ratchet-plafonds in
   `noordster-metriek.test.ts`.
   ✅ beschrijvings-/kavelslots + deterministische P/G-score-overstromings-
   hypothese (NL+FR).
   ✅ autonome afrekening verdiept: eigen-woning-tarief
   (`koperEnigeEigenWoning`), `hypothecaireLasten[]`, kredietaktekosten mee in
   het werkdossier.
   ✅ vierde pijler `opvolging.ts`: termijnen (opschortende voorwaarde,
   uiterste aktedatum), vaste route per dossierfase en ontbrekende stukken —
   met "vandaag" als parameter; bewaakt door `opvolging.test.ts`.
   _Resterende hefbomen: verdiepingsbeschrijvingen per kavel (§2), de
   Brusselse/Waalse overstromings-hypothese zodra een cartografie-uitslag als
   attestveld bestaat, en de mailketen-inhoud per fase (E)._
2. **Volledige mailketen verkoop.** Controleer dat elke fase een modelmail heeft
   (eerste contact → opvraging stukken → ontwerp → afrekening → ondertekening →
   na de akte) in `data/modelbrieven/brieven/` en correct gemapt wordt in
   `lib/dossier/modelmails.ts`.
3. **Afrekening verkoop sluitend.** Aktekosten + verkooprecht volledig, met
   bronvermelding (KB-datum) zichtbaar in het werkdocument.
4. **Brongegevens → dossier robuust.** Versterk `lib/dossier/intake.ts` (v2) voor
   meerbronnen-conflicten (`extraWaarnemingen`, `alternatieven`) en de
   tegenstrijdigheden-detectie (`tegenstrijdigheden.ts`).
5. **Gouden-pad regressietest.** Eén end-to-end test (zie `einddoel-loop.test.ts`)
   die de noordster-metriek voor het compromis bewaakt en faalt bij regressie.

**Definition of done:** een realistisch verkoopdossier levert in één keer een
compromis + mails + afrekening op met nul open hypotheses en enkel onzekerheden
die écht aanvullende brongegevens vereisen.

---

## Fase 2 — Aktetype-dekking uitbreiden (herhaalbaar recept)

**Doel:** méér rechtshandelingen autonoom kunnen produceren. Elk nieuw aktetype
volgt hetzelfde **recept**, zodat uitbreiding routine wordt.

> **Machineleesbaar dashboard:** `lib/dossier/uitbouw.ts`
> (`bepaalUitbouwDekking`) berekent de dekking van dit recept uit het echte
> gedrag; de actuele, geprioriteerde werklijst (ontwerp eerst) staat als
> `HUIDIGE_GATEN` in `lib/dossier/uitbouw.test.ts` (ratchet: gedicht gat =
> schrappen, nieuwe gaten falen de test). **Begin een uitbouwsessie dáár**,
> niet met verkennen.

> **Recept per aktetype**
> 1. Model in `data/modeldocumenten/modellen/` (structuur + slots).
> 2. Onderdelen/clausules in `data/modeldocumenten/onderdelen/` met
>    `{{parameter}}`-placeholders en hypothese-varianten.
> 3. **FR-spiegel** (`-fr`) met identieke variant-id's + pariteitstest.
> 4. Deterministische kenmerken bijwerken in `lib/dossier/kenmerken.ts`.
> 5. akteType-detectie in `lib/dossier/akteType.ts`.
> 6. Modelmail-keten in `data/modelbrieven/` + mapping in `modelmails.ts`.
> 7. Afrekening (kosten + eventuele belasting) in `data/ereloon.ts` /
>    `data/belastingen.ts` + `lib/dossier/afrekening.ts`.
> 8. Tests (samenstelling, pariteit, gouden-pad-metriek).

**Prioritaire ontbrekende aktetypes** (volgorde = frequentie/impact):
1. **Kredietakte / hypotheekvestiging** — barema's staan al deels actief
   (`akteMeta.hypotheek`), maar model + onderdelen + mails ontbreken.
2. **Basisakte / statuten mede-eigendom.**
3. **Verdeling uit onverdeeldheid** (incl. berekening, zie Fase 4).
4. **Erfovereenkomst (familieplanning).**
5. **Aangifte van nalatenschap.**
6. **Huwelijkscontract.**

De volledige catalogus — tientallen rechtshandelingen over vastgoed, familie,
vennootschappen en algemeen, elk met conventie-akteType en de herbruikbare
bouwstenen (briefcategorie, ereloon-akteType) — staat machineleesbaar in
`UITBOUW_KANDIDATEN` (`lib/dossier/uitbouw.ts`). Elk pad dat gaat werken,
wordt vastgezet als één scenario in het gouden-paden-register
(`lib/dossier/gouden-paden.ts`, bewaakt door `gouden-paden.test.ts`) — geen
gekloonde testbestanden per aktetype.

---

## Fase 3 — FR-pariteit overal

**Doel:** elk NL-model heeft zijn Franstalige spiegel met dezelfde varianten en
structuur (cf. de verplichte beschrijvingsclausule en de bestaande
pariteitstest).

1. Inventariseer NL-modellen/onderdelen zonder `-fr`-spiegel.
2. Voeg per ontbrekend stuk de FR-spiegel toe (zelfde variant-id's).
3. Breid de pariteit-tests uit (zoals
   `beschrijving-onroerend-goed-parity.test.ts`) zodat scheefgroei automatisch
   faalt.
4. Zorg dat `vertaalMarkeringenFR` alle interne werk-markeringen dekt.

---

## Fase 4 — Afrekeningen compleet & gezaghebbend

**Doel:** elke afrekening die bij een gedekt aktetype hoort, klopt en is
navolgbaar.

1. **Kredietakte-kosten** koppelen aan het nieuwe kredietakte-model (Fase 2.1).
2. **Verdeling**: verdeelrecht/miserie­taks-formules implementeren.
3. **Partner-vrijstellingen erfbelasting** expliciteren in de intake-flow
   (`bepaalPartnerVrijstelling`), zodat ze niet impliciet blijven.
4. **Bron & geldigheid** (KB-/decreetdatum) standaard in elk afrekeningsblok
   tonen; jaarlijkse indexatie-check inplannen (`ERELOON_META`, `BELASTINGEN_META`).

---

## Fase 5 — Brondocument → feiten (de intake-brug)

**Doel:** de stap van ruwe brondocumenten naar gestructureerde, geanonimiseerde
feiten zo betrouwbaar mogelijk maken. (De PDF-/OCR-lezing zelf blijft bij de
externe agent — GDPR-conform, lokaal.)

1. **Scherper intake-contract.** Documenteer per brontype (compromis, bod, titel,
   attest) welke velden de agent moet extraheren; verrijk het JSON-schema en de
   `KENMERKEN_HANDLEIDING` zodat twee agents met dezelfde bron identiek
   uitkomen.
2. **Conflict- & volledigheidsrapport.** Geef in het werkdossier expliciet terug
   welke feiten ontbreken/conflicteren en wélke modelmail die opvraagt.
3. **Werkwijze-loop.** Versterk `/api/werkwijze` zodat de agent stap voor stap
   weet: feiten aanleveren → werkdossier ophalen → onzekerheden wegwerken →
   finaliseren.
4. **Observability.** Gebruik `/api/gebruikslog` om onbekende id's, genegeerde
   facultatieve onderdelen en veelvoorkomende onzekerheden te volgen → voedt de
   volgende uitbreidingen.

---

## Fase 6 — Vertrouwen, kwaliteit en opschaling

**Doel:** de notaris vertrouwt het werkdocument en de bibliotheek blijft gezond.

1. **Gouden-pad-metriek per aktetype** als CI-bewaakte test (regressie =
   bouwfout).
2. **Citaten/bronvermelding** bij regelgeving en afrekeningen consequent.
3. **Validatie-UX** ("Te valideren") verfijnen: diff-weergave, samenvoegen,
   opsplitsen — altijd via wijzigingsvoorstel, nooit rechtstreeks.
4. **Periodieke barema-/regelgevingsupdate** als terugkerende taak.

---

## Werkvolgorde in één oogopslag

| Fase | Focus | Resultaat |
|------|-------|-----------|
| 1 | Gouden pad (verkoop/compromis) perfect | Referentie-implementatie, 0 open hypotheses |
| 2 | Aktetype-dekking via herhaalbaar recept | Kredietakte, basisakte, verdeling, erfovereenkomst, … |
| 3 | FR-pariteit overal | Elk model NL+FR, bewaakt door tests |
| 4 | Afrekeningen compleet | Elke gedekte akte heeft een kloppende afrekening |
| 5 | Intake-brug betrouwbaar | Bron → feiten reproduceerbaar, conflicten zichtbaar |
| 6 | Kwaliteit & vertrouwen | CI-bewaakte metriek, nette validatie-flow |

**Leidend principe bij elke stap:** verlaag de noordster-metriek (minder open
keuzes, minder aan te vullen, minder onzekerheden) zonder ooit een blinde gok te
maken — bij twijfel blijft de keuze bij de notaris.