# Draaiboek — een nieuw gouden pad uitbouwen (credit-efficiënt)

Doel: een nieuw dossiertype/aktetype (bv. kredietakte, basisakte, verdeling)
van nul naar "autonoom werkdossier" brengen met zo weinig mogelijk verkenning.
Het compromis (verkoop) is de referentie-implementatie; dit draaiboek wijst per
laag naar de exacte bestanden om te klonen. Volg de volgorde — ze is gekozen
zodat elke stap meteen door een test bewaakt wordt en niets tweemaal wordt
gedaan.

## Stap 0 — Kies het gat (geen verkenning) en claim de werf

Er werken meerdere agents parallel op `main`: claim een gouden-pad-werf eerst
in `WERVEN.md` (één regel, meteen pushen met `npm run duw`) zodat niemand
hetzelfde pad dubbel bouwt.

Lees `HUIDIGE_GATEN` in `lib/dossier/uitbouw.test.ts`: dat is de actuele,
geprioriteerde werklijst (ontwerp eerst). De volledige catalogus van de
notariële praktijk staat in `UITBOUW_KANDIDATEN` (`lib/dossier/uitbouw.ts`),
gegroepeerd per domein (vastgoed / familie / vennootschappen / algemeen) en in
frequentie/impact-volgorde — de declaratievolgorde ís de prioriteit. Gebruik
exact de conventie-string als `akteType` van het nieuwe model, dan slaat de
dekking automatisch om; `briefCategorie` en `ereloonAkteType` wijzen naar de
bouwstenen die het pad meteen kan hergebruiken.

## De lagen van het gouden pad (referentie = compromis)

| # | Laag | Referentiebestand(en) | Bewakende test |
|---|------|----------------------|----------------|
| 1 | **Model** (structuur + slots) | `data/modeldocumenten/modellen/vastgoed.ts` → `verkoopovereenkomst-heldere-taal` | `data/modeldocumenten/*.test.ts` (samenstelling) |
| 2 | **Onderdelen/clausules** met `{{parameter}}`-placeholders en hypothese-varianten | `data/modeldocumenten/onderdelen/` (bv. `ht-*`-onderdelen); de beschrijving van een onroerend goed MOET via `beschrijving-onroerend-goed` (AGENTS.md) | idem |
| 3 | **FR-spiegel**: `-fr`-model en -onderdelen met `vertalingVanId` en IDENTIEKE variant-id's | zelfde bestanden, `-fr`-varianten | `data/modeldocumenten/nl-fr-pariteit.test.ts` — vangt scheefgroei automatisch, geen eigen test nodig |
| 4 | **akteType-detectie** uit het dossier | `lib/dossier/akteType.ts` (switch op dossiertype; exhaustiviteitscontrole dwingt de mapping af) | `lib/dossier/akteType.test.ts` |
| 5 | **Deterministische hypothesekeuzes** (feit → variant, nooit gokken) | **nieuw domein: een declaratieve regeltabel in `lib/dossier/kenmerken-regels.ts`** (`KenmerkRegel[]` + `pasKenmerkRegelsToe`, drieledig true/false/onbekend, FR-spiegel automatisch — zie `SCHENKING_REGELS` als voorbeeld) + een afleidingsfunctie dossier→kenmerken in `parameters.ts` (zie `schenkingKenmerkenUitDossier`); enkel complexe kruisregels (gewest×goedType) horen nog imperatief in `lib/dossier/kenmerken.ts` | `lib/dossier/kenmerken-regels.test.ts`, `lib/dossier/kenmerken.test.ts` |
| 6 | **Intake-slots → parameters** (NL én FR-spiegelnamen in één beweging) | `lib/dossier/intake.ts` (contract, additief uitbreiden) → **één regel per veld in `DOSSIER_PARAMETER_MAPPING` (`lib/dossier/parameter-mapping.ts`)**; enkel afleidingslogica (defaults, vergelijkingen) hoort nog in `parameters.ts` | `lib/dossier/parameters.test.ts`, `noordster-metriek.test.ts` |
| 7 | **Modelmail-keten** per fase | `data/modelbrieven/brieven/` + categorie-mapping in `lib/dossier/modelmails.ts` (`bepaalBasisCategorieen`) | `lib/dossier/modelmails.test.ts` |
| 8 | **Afrekening** | `data/ereloon.ts` (`akteMeta`, barema's) + `lib/dossier/afrekening.ts` | `lib/dossier/afrekening.test.ts` |
| 9 | **Opvolging** (route + termijnen tot ondertekening) | `lib/dossier/opvolging.ts` (nu enkel verkoop; nieuw dossiertype = route + termijnen toevoegen) | `lib/dossier/opvolging.test.ts` |
| 10 | **Gouden-pad-regressietest + ratchet** | voeg ÉÉN scenario-object toe aan `GOUDEN_PADEN` (`lib/dossier/gouden-paden.ts`): intake-JSON + verwacht akteType/model + gemeten plafonds (open velden/keuzes, NL én FR) + pijler-vlaggen. Het harnas (`gouden-pad.ts`) meet alles via de echte motor; testdossiers lopen automatisch via `maakDossierUitIntakeResultaat` — nooit een eigen spread-bouwer. Padspecifieke inhouds-asserties (zoals `gouden-pad-compromis.test.ts`) enkel toevoegen waar de inhoud dat echt vraagt | `lib/dossier/gouden-paden.test.ts` (bewaakt élk scenario automatisch) |

## Werkvolgorde die credits minimaliseert

1. **Ontwerp eerst** (lagen 1–3): model + onderdelen + FR in dezelfde sessie —
   de FR-spiegel meteen meenemen is veel goedkoper dan hem later reconstrueren,
   en de pariteitstest bewaakt hem gratis.
2. **Detectie + kenmerken** (lagen 4–5): kleine, mechanische switch-uitbreidingen;
   de exhaustiviteitscontroles (`never`-checks) wijzen zelf aan waar code moet
   bijkomen zodra een dossiertype wordt toegevoegd.
3. **Slots + parameters** (laag 6): breid het intake-contract additief uit; map
   elk nieuw slot in `parameters.ts` meteen op de NL- én FR-parameternaam.
   De flessenhals van het compromis-pad bleek hier te zitten (velden zonder
   slot blijven eeuwig `[AAN TE VULLEN]`).
4. **Mails, afrekening, opvolging** (lagen 7–9).
5. **Ratchet vastzetten** (laag 10): één scenario toevoegen aan
   `GOUDEN_PADEN` (`lib/dossier/gouden-paden.ts`) met de gemeten plafonds, en
   het gat schrappen uit `HUIDIGE_GATEN` in `lib/dossier/uitbouw.test.ts` — de
   test faalt tot je dat doet, en dat is de bedoeling.
6. **Poort + push**: `npm run poort` (tests + tsc + eslint + build in één
   opdracht), commit op `main` en push met `npm run duw` (rebase + snelle
   herpoort + push, racebestendig). CI draait dezelfde poort.

## Vuistregels (uit de compromis-ervaring)

- **Nooit een blinde gok**: een hypothese wordt enkel deterministisch gekozen
  op een expliciet, traceerbaar feit; anders blijft de keuze open voor de
  notaris. Onzekerheden eerlijk melden mét suggestie (`werkdossier.ts`).
- **Ratchet-plafonds nooit stilzwijgend verhogen**; verlagen bij elke
  verbetering.
- **Seed-bibliotheek in code wijzigen mag rechtstreeks in de repo** (de commit
  op main ís het valideerbare voorstel); het twee-regimes-principe van
  AGENTS.md geldt voor runtime-agenten via MCP, die dienen wijzigingsvoorstellen
  in via `voegModel*VoorstelToe`.
- **E2E-verificatie** van UI-wijzigingen: volg het recept in
  `.claude/skills/verifier-web/SKILL.md` (build, start, import-JSON-flow,
  Playwright-screenshot) in plaats van het opnieuw uit te vinden.