From 4aeaf6a36ae663a063407b77cecbe88957a9656a Mon Sep 17 00:00:00 2001
From: Madhura68 <janpetervisser2@gmail.com>
Date: Thu, 14 May 2026 02:20:27 +0200
Subject: [PATCH] docs(make-plan): documenteer backtick-format voor
 implementation_plan-paden
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 lib/idea-prompts/make-plan.md | 51 +++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/lib/idea-prompts/make-plan.md b/lib/idea-prompts/make-plan.md
index a45500b..d4852cb 100644
--- a/lib/idea-prompts/make-plan.md
+++ b/lib/idea-prompts/make-plan.md
@@ -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.