docs(make-plan): documenteer backtick-format voor implementation_plan-paden

verify_task_against_plan extraheert paden uit implementation_plan via twee
regex-patronen (backticks + bullet). Paden inline in genummerde tekst-stappen
worden niet herkend → planPaths.length=0 → bij diff >50 regels DIVERGENT.

Voeg sectie "Bestandspaden in implementation_plan — verplicht format" toe
die uitlegt welke formats werken (backticks, bullets) en welke niet (inline).
Plus verband met verify_required-keuze: default ALIGNED_OR_PARTIAL behouden
voor ADR-stubs en multi-file edits.

Voorkomt herhaling van T-963 cancelled_by_self-symptoom waar implementatie
slaagde maar verifier DIVERGENT teruggaf.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-05-14 02:20:27 +02:00
parent 0a040b721f
commit 4aeaf6a36a

View file

@ -170,3 +170,54 @@ regelnummers; de gebruiker kan re-plan klikken of `plan_md` handmatig fixen.
**Slecht**: "Maak de feature werkend"
**Goed**: "Voeg `actions/ideas.ts:createIdeaAction(input)` toe — auth +
demo-403 + zod-parse + nextIdeaCode + prisma.idea.create + revalidatePath"
## Bestandspaden in `implementation_plan` — verplicht format
`verify_task_against_plan` extraheert bestandspaden uit `implementation_plan`
om de git-diff tegen het plan te valideren. Zonder herkenbare paden valt de
verifier terug op een line-count-heuristiek (`> 50 regels → DIVERGENT`),
waardoor zelfs correct uitgevoerde tasks `cancelled_by_self` kunnen worden
(verify-gate weigert `DONE` te zetten).
De path-extractor herkent twee formats:
1. **Backticks** (aanbevolen voor inline-paden binnen een zin of stap):
`lib/foo.ts`, `app/(app)/products/[id]/page.tsx`, `docs/adr/0009-foo.md`
2. **Bullet-lijst** (aanbevolen voor doel-bestanden vóór de stappen):
- `lib/foo.ts`
- `app/(app)/products/[id]/page.tsx`
**Werkt NIET** (paden inline in genummerde tekst zonder markup):
```
1. Maak docs/adr/0009-foo.md aan op basis van templates/nygard.md
2. Update docs/INDEX.md via npm run docs
```
→ Path-extractor herkent geen pad → `planPaths.length=0` → bij diff >50 regels
→ verifier returnt **DIVERGENT** → task met `verify_required=ALIGNED` faalt.
**Werkt WEL** (zelfde stappen, paden in backticks):
```
1. Maak `docs/adr/0009-foo.md` aan op basis van `docs/adr/templates/nygard.md`
2. Update `docs/INDEX.md` via `npm run docs`
```
→ Path-extractor vindt 3 paden → diff bevat dezelfde 3 paden → coverage 100%
→ verifier returnt **ALIGNED** → task gaat naar DONE.
**Regel**: noem **elk** bestand dat de task aanmaakt, bewerkt of regenereert
in backticks of als bullet. Vermeld ook `docs/INDEX.md` als die regenereerd
wordt door `npm run docs`, en `README.md`-achtige updates.
**Verband met `verify_required`**:
- `ALIGNED`: alle plan-paden moeten in de diff zitten + ratio diff/plan <3
- `ALIGNED_OR_PARTIAL`: PARTIAL toegestaan mits worker summary ≥20 chars geeft
- `ANY`: geen verifier-gate
Default = `ALIGNED_OR_PARTIAL` (schema). Kies `ALIGNED` alleen wanneer
plan-paden 1-op-1 matchen met te-wijzigen-bestanden en de diff klein is
(<50 regels typisch). Voor ADR-stubs, schema-migraties of multi-file refactors:
laat `ALIGNED_OR_PARTIAL` staan.