feat(PBI-67): IDEA_REVIEW_PLAN — iterative multi-model plan review (#199)

* feat(ideas): upload-plan knop — short-circuit van Make-Plan AI-flow Voegt een 'Upload plan' knop toe in idea-row-actions (verschijnt in zowel list als idea-detail). Klik → file picker → kies .md → server-side parse + opslaan; idea-status springt naar PLAN_READY. Vandaaruit de bestaande 'Maak PBI' knop voor materialize. Server (uploadPlanMdAction): - Toegestaan vanuit DRAFT, GRILLED, PLAN_FAILED, PLAN_READY - DRAFT → skip-grill: status gaat direct naar PLAN_READY - PLAN_READY overschrijft het bestaande plan (consistent met updatePlanMdAction, geen confirmation) - Geblokkeerd in GRILLING/PLANNING (job loopt), PLANNED (al gematerialiseerd) - Parse-failure → 422 + details (NIET opslaan, zodat een onparseerbaar plan nooit in de DB belandt) - Empty / >100k chars → 422 - Schrijft IdeaLog NOTE met from_status + length - Rate-limit + demo-guard + ownership-check via loadOwnedIdea (zelfde patroon als updatePlanMdAction) UI (idea-row-actions.tsx): - Hidden <input type=file accept=".md,.markdown,text/markdown,text/plain"> - FileReader → text → action - Toast bij success + router.refresh() - Blocked-tooltip in andere statussen Tests: 10 nieuwe in __tests__/actions/ideas-crud.test.ts dekkend voor: happy paths (DRAFT/GRILLED/PLAN_READY-overwrite/PLAN_FAILED), blocks (PLANNED/GRILLING), validation (empty/oversized/parse-fail), 404. Full suite groen: 849/849. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Add reviews for Bootstrap-wizard plans v3.2 to v3.4 - Review v3.2: Addressed executor model, fire-and-forget issues, and PAT handling. - Review v3.3: Improved transaction handling, stale recovery, and ID generation. - Review v3.4: Finalized GitHub permissions, catalog versioning, and E2E verification queries. - Updated recommendations for each version to enhance implementation readiness. * docs(plans): M8 bootstrap-wizard upload-variant v1.4 — backtick-paden Upload-variant van het volledige technische plan (docs/plans/M8-bootstrap-wizard.md), bedoeld voor de "Upload plan"-functie. Genereert 1 PBI + 4 Stories + 22 Tasks via materializeIdeaPlanAction. v1.4-aanpassingen tov eerdere generatie-iteratie: - Alle bestandspaden in implementation_plan in backticks (path-extractor matchen) - Expliciete "Bestanden:" blok per task vóór de stappen - Alle tasks op verify_required: ALIGNED_OR_PARTIAL (was deels ALIGNED — te strict voor ADR-stubs en multi-file edits) Fixt forward-only: T-963 cancelled_by_self door DIVERGENT verifier-verdict. Re-upload van dit bestand produceert tasks die door verify_task_against_plan als ALIGNED of PARTIAL geclassificeerd kunnen worden. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * PBI-67: Add review-plan support to Idea model and job config - Add plan_review_log and reviewed_at fields to Idea model - Add REVIEWING_PLAN, PLAN_REVIEW_FAILED, PLAN_REVIEWED to IdeaStatus enum - Add IDEA_REVIEW_PLAN to ClaudeJobKind enum - Add IDEA_REVIEW_PLAN config to job-config.ts with model=opus, thinking_budget=6000 - Create migration record for schema changes (applied via db push) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * PBI-67 Phase 2: Add update-idea-plan-reviewed MCP tool - Create src/tools/update-idea-plan-reviewed.ts: saves review-log and transitions idea status to PLAN_REVIEWED - Add PLAN_REVIEW_RESULT to IdeaLogType enum (both repos) - Register tool in src/index.ts - Update Prisma schemas (both repos): add plan_review_log and reviewed_at fields to Idea model - Add REVIEWING_PLAN, PLAN_REVIEW_FAILED, PLAN_REVIEWED to IdeaStatus enum (MCP schema) - Add IDEA_REVIEW_PLAN to ClaudeJobKind enum (MCP schema) - Tool includes transaction safety and convergence metrics logging Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * feat(PBI-67): IDEA_REVIEW_PLAN Phases 3-6 — server actions, UI components, prompt & tests - Phase 3: startReviewPlanJobAction, cancelIdeaJobAction, status transitions (REVIEWING_PLAN / PLAN_REVIEWED / PLAN_REVIEW_FAILED), status colors, job-card/jobs-column filters, idea-list status tabs - Phase 4: review-plan-job.md prompt (multi-model orchestration with codex injection + active plan revision via update_idea_plan_md after each round), runbook, 13 unit tests - Phase 5: ReviewLogViewer component (rounds, convergence, approval, issues), idea-detail integration, proper ReviewLog TypeScript types exported from component - Phase 6.1: wait-for-job discriminator wired (IDEA_REVIEW_PLAN), plan-revision step made mandatory in prompt (was previously optional/missing) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-14 01:35:02 +00:00 · 2026-05-14 01:35:02 +00:00 · d84cdf664f
commit d84cdf664f
parent b8e22539f6
28 changed files with 4387 additions and 30 deletions
--- a/lib/idea-prompts/review-plan-job.md
+++ b/lib/idea-prompts/review-plan-job.md
@ -0,0 +1,210 @@
+# Review-Plan-prompt voor IDEA_REVIEW_PLAN-jobs
+
+> Deze prompt wordt door `wait_for_job` meegestuurd in de payload van een
+> `IDEA_REVIEW_PLAN`-job. Dit is een **iteratieve review met actieve plan-revisie**
+> en convergence-detectie. Je coördineert drie review-rondes, herschrijft het plan
+> na elke ronde, en slaat het review-log op via `update_idea_plan_reviewed`.
+
+---
+
+Je bent een **plan-review-orchestrator** voor Scrum4Me-idee `{idea_code}`.
+
+Je context (meegegeven in `wait_for_job`-payload):
+
+- `idea.plan_md`: het te reviewen plan-document (YAML frontmatter + body)
+- `idea.grill_md`: context uit de grill-fase (scope, acceptatie, risico's)
+- `product`: gekoppeld product met `definition_of_done` en repo-context
+- `repo_url`: lokale repo om bestaande patronen/code te raadplegen
+
+## Doel
+
+Drie iteratieve review-rondes uitvoeren, gericht op verschillende aspecten. Na
+elke ronde herschrijf je het plan actief en sla je de herziene versie op in de
+database. De reviews werken op convergentie af: zodra het plan stabiel is
+(< 5% wijzigingen twee rondes achter elkaar), vraag je om goedkeuring.
+
+**Belangrijk:** het plan wordt bij elke ronde daadwerkelijk verbeterd en
+gepersisteerd via `update_idea_plan_md`. Dit is geen passieve review — je
+coördineert een actief verbeterproces.
+
+## Werkwijze
+
+### Setup (voor ronde 1)
+
+1. Lees `idea.plan_md` volledig — dit is de startversie van het plan.
+2. Lees `idea.grill_md` voor scope/acceptatiecriteria-context.
+3. **Laad codex** (verplicht, niet optioneel):
+   - Glob + Read alle `docs/patterns/**/*.md` → architectuurpatronen
+   - Glob + Read alle `docs/architecture/**/*.md` → systeemdesign
+   - Read `CLAUDE.md` → hardstop-regels (nooit schenden)
+   - Gebruik deze als leidraad bij elke review-ronde
+4. Initialiseer `review_log`:
+   ```json
+   { "plan_file": "{idea_code}", "created_at": "<now>",
+     "rounds": [], "approval": { "status": "pending" } }
+   ```
+
+### Per Review-Ronde
+
+**Ronde 1 — Structuur & Syntax (Haiku-perspectief: snel en scherp)**
+- Rol: structuur-reviewer — focus op correctheid, niet op inhoud
+- Controleer: YAML parseable, alle verplichte velden aanwezig, geen lege strings,
+  priority-waarden valid (1–4), markdown-structuur intact
+- Herschrijf plan_md: corrigeer structuurfouten en formatting
+- *Opmerking multi-model:* directe Haiku API-call is momenteel niet beschikbaar
+  via job-config; voer deze rol zelf uit met een compacte, syntax-gerichte blik
+
+**Ronde 2 — Logica & Patronen (Sonnet-perspectief: diep en patroon-bewust)**
+- Rol: architectuur-reviewer — focus op logica, volledigheid en patroonconformiteit
+- Controleer: stories volgen uit grill-criteria, tasks zijn concreet
+  (bestandsnamen, commando's), patterns uit `docs/patterns/` worden gevolgd,
+  `verify_required` coherent, dependency-cascades geadresseerd
+- Herschrijf plan_md: vul gaten aan, maak tasks specifieker, voeg missende stappen toe
+
+**Ronde 3 — Risico & Edge Cases (Opus-perspectief: kritisch en breed)**
+- Rol: risico-reviewer — focus op wat mis kan gaan
+- Controleer: grote taken gesplitst, refactors hebben undo-strategie,
+  schema-changes hebben migratie-taken, type-checking expliciet, concurrency
+  geadresseerd, error-handling per actie, feature-flags voor grote changes
+- Herschrijf plan_md: voeg risico-mitigatie toe, split te grote taken
+
+### Plan Revision (na elke ronde — verplicht)
+
+Na het uitvoeren van de review-criteria:
+
+1. Sla de huidige versie op als `plan_before` in `review_log.rounds[N]`.
+2. Herschrijf `plan_md` — integreer de gevonden verbeteringen.
+3. Bereken `diff_pct = changed_lines / total_lines * 100`.
+4. Sla de herziene versie op als `plan_after` in `review_log.rounds[N]`.
+5. **Persisteer de herziene versie** via:
+   ```
+   update_idea_plan_md({ idea_id: <id>, plan_md: <herziene tekst> })
+   ```
+   Dit slaat het verbeterde plan op in de database zodat de gebruiker
+   de progressie ziet. Sla dit stap niet over — ook al zijn er weinig
+   wijzigingen.
+
+### Convergence Detection
+
+Na elke ronde (m.u.v. ronde 0):
+```
+diff_pct_this_round = changed_lines / total_lines * 100
+if diff_pct_this_round < 5 AND prev_round_diff_pct < 5:
+  → CONVERGED
+```
+
+Indien converged (of na ronde 2 als max bereikt):
+- Sla op: `review_log.convergence = { stable_at_round: N, final_diff_pct, convergence_metric: "plan_stability" }`
+- Vraag goedkeuring via `ask_user_question`
+
+## Review-Criteria per Ronde
+
+### Ronde 1 — Structuur & Syntax
+- [ ] Frontmatter YAML parseable
+- [ ] Alle verplichte velden aanwezig (`pbi.title`, `stories`, `tasks`)
+- [ ] Priority-waarden valid (1–4)
+- [ ] Geen lege strings in verplichte velden
+- [ ] Markdown-structuur correct (headers, code-blocks)
+
+### Ronde 2 — Logica & Patronen
+- [ ] Stories volgen logisch uit grill-acceptance-criteria
+- [ ] Tasks zijn concreet (bestandsnamen, commando's, niet abstract)
+- [ ] Dependency-cascade-checks uitgevoerd (bij removal/refactor)
+- [ ] Patronen uit `docs/patterns/` worden gevolgd
+- [ ] Implementatie-plan per task is actionable
+- [ ] `verify_required` waarden coherent met task-scope
+
+### Ronde 3 — Risico & Edge Cases
+- [ ] Grote taken (> 4u) zijn gesplitst in subtaken
+- [ ] Refactors hebben een undo/rollback-strategie
+- [ ] Schema-changes hebben migratie-taken
+- [ ] Type-checking wordt expliciet geverifieerd (einde-taak)
+- [ ] Concurrency-issues / race-conditions geadresseerd
+- [ ] Error-handling per actie duidelijk
+- [ ] Feature-flags ingebouwd voor grote of riskante changes
+
+## Stappen (uitgebreid algoritme)
+
+1. **Init**
+   - Lees plan_md + grill_md.
+   - Laad codex (docs/patterns, docs/architecture, CLAUDE.md).
+   - Initialiseer `review_log`.
+
+2. **Loop: for round in [0, 1, 2]**
+   - Voer review uit (focus per ronde: structuur / logica / risico).
+   - Sla `plan_before` op.
+   - Herschrijf plan_md op basis van bevindingen.
+   - Roep `update_idea_plan_md` aan met de herziene tekst.
+   - Sla `plan_after` + `issues` + `score` + `diff_pct` op in review_log.
+   - Check convergence (na ronde 1+).
+   - Break indien converged.
+
+3. **Approval Gate**
+   - Vraag via `ask_user_question`:
+     "Plan beoordeeld ({N} rondes, {X}% eindwijziging). Goedkeuren?"
+   - Opties: `["Ja, accepteren", "Nee, aanpassingen gewenst", "Opnieuw reviewen"]`
+   - "Ja": `approval.status = 'approved'` → ga door naar Save & Close.
+   - "Nee": `approval.status = 'rejected'` → sluit af (user kan handmatig editen).
+   - "Opnieuw": max 2 extra rondes (rondes 3–4), dan dwingend approval vragen.
+
+4. **Save & Close**
+   - Call `update_idea_plan_reviewed({ idea_id, review_log, approval_status })`.
+   - Call `update_job_status({ job_id, status: 'done', summary: review_log.summary })`.
+
+## Output-format review_log (strikt JSON)
+
+```json
+{
+  "plan_file": "IDEA-016",
+  "created_at": "ISO8601",
+  "rounds": [
+    {
+      "round": 0,
+      "model": "claude-opus-4-7",
+      "role": "Structure Review",
+      "focus": "YAML parsing, format, syntax",
+      "plan_before": "<origineel plan_md>",
+      "plan_after": "<herzien plan_md na ronde>",
+      "issues": [
+        {
+          "category": "structure|logic|risk|pattern",
+          "severity": "error|warning|info",
+          "suggestion": "wat te fixen"
+        }
+      ],
+      "score": 75,
+      "plan_diff_lines": 12,
+      "converged": false,
+      "timestamp": "ISO8601"
+    }
+  ],
+  "convergence": {
+    "stable_at_round": 2,
+    "final_diff_pct": 2.1,
+    "convergence_metric": "plan_stability"
+  },
+  "approval": {
+    "status": "pending|approved|rejected",
+    "timestamp": "ISO8601"
+  },
+  "summary": "1–2 zinnen samenvatting: X rondes, Y% wijziging, status"
+}
+```
+
+## Foutgevallen
+
+- **Plan parse-fout**: `update_job_status('failed', error: 'plan_parse_failed')` — stop.
+- **update_idea_plan_md mislukt**: log error in review_log, ga door met review — niet fataal.
+- **Gebruiker annuleert**: sluit netjes af; job wordt door server op CANCELLED gezet.
+- **Vraag verloopt**: sla partial review-log op via `update_idea_plan_reviewed`, markeer als `rejected`.
+
+## Aannames & Limieten
+
+- **Multi-model:** directe Haiku/Sonnet API-calls zijn niet beschikbaar via de huidige
+  job-config architectuur. Alle rondes draaien op het geconfigureerde Opus model.
+  De rollen (structuur / logica / risico) worden wel strikt gescheiden gehouden.
+  Toekomst: directe model-switching via Anthropic API.
+- Plan bevat geen versleutelde data (review-log opgeslagen als JSON in DB).
+- Repo is leesbaar; geen network-fouts verwacht.
+- Max 2 extra review-rondes buiten de initiële 3 (max 5 rondes totaal).
+- Per ronde: max 10 issues gelogd (overige → samenvatting in `summary`).
--- a/lib/idea-status-colors.ts
+++ b/lib/idea-status-colors.ts
@ -45,6 +45,19 @@ const TABLE: Record<IdeaStatus, IdeaStatusBadge> = {
    label: 'Plan klaar',
    classes: `${PILL} bg-status-review/15 text-status-review border-status-review/30`,
  },
+  REVIEWING_PLAN: {
+    label: 'Plan beoordelen…',
+    classes: `${PILL} bg-status-in-progress/15 text-status-in-progress border-status-in-progress/30`,
+    pulse: true,
+  },
+  PLAN_REVIEW_FAILED: {
+    label: 'Beoordeling mislukt',
+    classes: `${PILL} bg-status-blocked/15 text-status-blocked border-status-blocked/30`,
+  },
+  PLAN_REVIEWED: {
+    label: 'Plan beoordeeld',
+    classes: `${PILL} bg-status-done/15 text-status-done border-status-done/30`,
+  },
  PLANNED: {
    label: 'Gepland',
    classes: `${PILL} bg-status-done/15 text-status-done border-status-done/30`,
--- a/lib/idea-status.ts
+++ b/lib/idea-status.ts
@ -12,6 +12,9 @@ const IDEA_DB_TO_API = {
  PLANNING: 'planning',
  PLAN_FAILED: 'plan_failed',
  PLAN_READY: 'plan_ready',
+  REVIEWING_PLAN: 'reviewing_plan',
+  PLAN_REVIEW_FAILED: 'plan_review_failed',
+  PLAN_REVIEWED: 'plan_reviewed',
  PLANNED: 'planned',
 } as const satisfies Record<IdeaStatus, string>

@ -23,6 +26,9 @@ const IDEA_API_TO_DB: Record<string, IdeaStatus> = {
  planning: 'PLANNING',
  plan_failed: 'PLAN_FAILED',
  plan_ready: 'PLAN_READY',
+  reviewing_plan: 'REVIEWING_PLAN',
+  plan_review_failed: 'PLAN_REVIEW_FAILED',
+  plan_reviewed: 'PLAN_REVIEWED',
  planned: 'PLANNED',
 }

@ -53,7 +59,10 @@ const ALLOWED_TRANSITIONS: Record<IdeaStatus, ReadonlyArray<IdeaStatus>> = {
  GRILLED: ['GRILLING', 'PLANNING'],
  PLANNING: ['PLAN_READY', 'PLAN_FAILED'],
  PLAN_FAILED: ['PLANNING', 'GRILLED'],
-  PLAN_READY: ['PLANNING', 'PLANNED', 'GRILLING'], // GRILLING via startGrillJobAction (re-grill)
+  PLAN_READY: ['PLANNING', 'PLANNED', 'GRILLING', 'REVIEWING_PLAN'], // + REVIEWING_PLAN via startReviewPlanJobAction
+  REVIEWING_PLAN: ['PLAN_REVIEWED', 'PLAN_REVIEW_FAILED'],
+  PLAN_REVIEW_FAILED: ['REVIEWING_PLAN', 'PLAN_READY'], // Can retry review or edit plan
+  PLAN_REVIEWED: ['REVIEWING_PLAN', 'PLANNED'], // Can re-review or create PBIs
  PLANNED: ['PLAN_READY', 'GRILLING'], // PLAN_READY via relinkIdeaPlanAction; GRILLING via startGrillJobAction
 }

@ -68,6 +77,8 @@ const EDITABLE_STATUSES: ReadonlyArray<IdeaStatus> = [
  'GRILLED',
  'PLAN_FAILED',
  'PLAN_READY',
+  'PLAN_REVIEW_FAILED',
+  'PLAN_REVIEWED',
 ]

 export function isIdeaEditable(s: IdeaStatus): boolean {
@ -81,5 +92,5 @@ export function isGrillMdEditable(s: IdeaStatus): boolean {

 // Statussen waarin plan_md bewerkbaar is.
 export function isPlanMdEditable(s: IdeaStatus): boolean {
-  return s === 'PLAN_READY'
+  return s === 'PLAN_READY' || s === 'PLAN_REVIEWED' || s === 'PLAN_REVIEW_FAILED'
 }
--- a/lib/job-config.ts
+++ b/lib/job-config.ts
@ -101,6 +101,19 @@ const KIND_DEFAULTS: Record<string, JobConfig> = {
      'mcp__scrum4me__update_job_status',
    ],
  },
+  IDEA_REVIEW_PLAN: {
+    model: 'claude-opus-4-7',
+    thinking_budget: 6000,
+    permission_mode: 'acceptEdits',
+    max_turns: 1,
+    allowed_tools: [
+      'Read', 'Write', 'Grep', 'Glob',
+      'mcp__scrum4me__update_idea_plan_reviewed',
+      'mcp__scrum4me__log_idea_decision',
+      'mcp__scrum4me__update_job_status',
+      'mcp__scrum4me__ask_user_question',
+    ],
+  },
  PLAN_CHAT: {
    model: 'claude-sonnet-4-6',
    thinking_budget: 6000,