feat: AI-suggesties tijdens het editen van een wet

[anneschuth]

Doel

Tijdens het bewerken van een wet in de editor op de achtergrond met claude -p
(headless Claude Code) suggesties genereren, op twee sporen:

1. Aanwijzingen voor de regelgeving — toets de wettekst tegen de KCBR-richtlijnen en lever concrete edit-suggesties.
2. Machine-uitvoerbare YAML — genereer concept-machine_readable-secties terwijl je schrijft.

Suggesties verschijnen als annotaties (RFC-018): gestippelde spans in de wettekst
plus een "Aanwijzingen"-pane met accepteren/afwijzen. De trigger is opslaan.

Aanpak

Vooral bestaande, geteste onderdelen aan elkaar knopen:

• De enrichworker (packages/pipeline/src/enrich.rs) draait al claude -p via de
  PostgreSQL job-queue. De suggestie-tak hergebruikt dat patroon via een gedeelde
  llm.rs, met job-types SuggestGuidelines / SuggestMachineReadable, op de
  traject-branch i.p.v. enrich/*.
• Het notes/annotatie-systeem (W3C Web Annotations, TextQuoteSelector,
  WASM-resolver, creator: Agent → gestippeld in AnnotatedText.vue) is de sink.
• Transport = polling (zoals harvest-status), geïsoleerd in useSuggestions.js.

Fasen (alle gemerged in deze branch)

• Skill + contract — law-aanwijzingen skill (SKILL.md + reference.md). Solo
  gevalideerd met claude -p op de zorgtoeslagwet: valide JSON met verankerbare quotes.
• Pipeline kern — JobType-varianten (migratie 0018), gedeelde llm.rs,
  suggest.rs (skill-output → W3C-annotatie-sidecar), 12 unit-tests.
• Worker + API — run_suggest_worker (draait mee in de enrich-binary),
  pipeline-api /suggest + /suggest/status, dedup-helper.
• Editor-api — enqueue-na-save (fire-and-forget), /suggestions lees-route,
  /suggestions/status proxy, traject-branch resolutie.
• Frontend — panel.suggestions flag (off, dark-launch), useSuggestions.js,
  SuggestionsPane.vue (nldd-componenten), poll-na-save, accept/reject.
• machine_readable-tak — zelfde infra, kind=machine_readable + law-generate-prompt.

Verankering (geverifieerd)

Wetteksten zijn block scalars met harde regelafbrekingen midden in zinnen. De skill
levert quotes met genormaliseerde witruimte; de fuzzy resolver-tier (threshold 0.7)
verankert ze betrouwbaar (~0.97 similarity). Geen engine-wijziging nodig.

Wat is geverifieerd

• Skill solo via claude -p → valide JSON, exacte quotes.
• cargo test -p regelrecht-pipeline: 43 tests groen (incl. 12 suggest/llm).
• cargo check/clippy op pipeline + editor-api lib: groen.
• Frontend vite build + 238 vitest tests: groen.

Wat nog een live stack nodig heeft

End-to-end op een draaiende stack (editor + pipeline + DB + ANTHROPIC_API_KEY in de
worker): save → job enqueued → worker draait claude -p → sidecar op traject-branch →
pane vult. Vereist ANTHROPIC_API_KEY in de enrich/suggest-worker en SKILLS_DIR
met de nieuwe skill in het container-image.

Bewust uit scope (follow-ups)

• One-click apply van een machine_readable-suggestie patcht nu nog niet automatisch
  machineReadable.value; accept zet de suggestie op resolved (human-in-the-loop).
• Gedeelde llm.rs wordt door suggest.rs gebruikt; enrich.rs houdt voorlopig zijn
  eigen runner (geen risicovolle refactor van productiecode in deze PR).

[github-actions]

Preview Deployment — enrichworker

Your changes have been deployed to a preview environment:

URL: https://enrichworker-pr735-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[github-actions]

Preview Deployment — harvester-admin

Your changes have been deployed to a preview environment:

URL: https://harvester-admin-pr735-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[github-actions]

Preview Deployment — harvester-worker

Your changes have been deployed to a preview environment:

URL: https://harvester-worker-pr735-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[github-actions]

Preview Deployment — editor — editor

Your changes have been deployed to a preview environment:

URL: https://editor-pr735-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[uittenbroekrobbert]

🛑 Migration 0018 crashes the harvester on startup

Heads-up from the RIG/ZAD platform side: this PR's preview deployment (regel-k4c-pr735) has its harvester / admin / enrich pods in CrashLoopBackOff (1481 restarts on harvester-admin, 831 on harvester-worker). The volume of restart → reconnect → retry attempts tripped our monitoring alerts, which is how this surfaced.

The problem

packages/pipeline/migrations/0018_suggest_job_types.sql fails on every run:

migration error: while executing migration 18:
operator does not exist: job_type = job_type_old

The migration never applies → the worker exits on startup → CrashLoopBackOff. This is the migration failing deterministically, not a preview-env glitch.

Why it happens

The migration recreates the job_type enum via rename/swap (since ALTER TYPE … ADD VALUE can't run in a transaction). That's the same pattern used safely for law_status — but job_type is referenced by the predicates of two partial indexes from earlier migrations:

• idx_unique_active_enrich_job … WHERE job_type = 'enrich' … (0003)
• idx_unique_active_harvest_job … WHERE job_type = 'harvest' … (0011)

When ALTER COLUMN … TYPE rebuilds those indexes, their predicate literals are still bound to the renamed job_type_old, so there's no comparison operator between the new column type and the old type → the error. The migration is transactional, so it rolls back cleanly (no half-migrated DB) — it just never succeeds. law_status has no such dependent indexes, which is why the pattern looked proven.

How to fix

Drop the two dependent indexes before the swap, recreate them after:

DROP INDEX idx_unique_active_enrich_job;
DROP INDEX idx_unique_active_harvest_job;

ALTER TYPE job_type RENAME TO job_type_old;
CREATE TYPE job_type AS ENUM ('harvest','enrich','suggest_guidelines','suggest_machine_readable');
ALTER TABLE jobs ALTER COLUMN job_type TYPE job_type USING job_type::text::job_type;
DROP TYPE job_type_old;

-- recreate against the new type (confirm exact defs against 0003/0011)
CREATE UNIQUE INDEX idx_unique_active_enrich_job
    ON jobs (law_id, job_type, (payload->>'provider'))
    WHERE job_type = 'enrich' AND status IN ('pending','processing');
CREATE UNIQUE INDEX idx_unique_active_harvest_job
    ON jobs (law_id, job_type)
    WHERE job_type = 'harvest' AND status IN ('pending','processing');

-- the new suggest index (unchanged from this PR)
CREATE UNIQUE INDEX idx_unique_active_suggest_job
    ON jobs (law_id, job_type, (payload->>'traject_ref'))
    WHERE job_type IN ('suggest_guidelines','suggest_machine_readable')
      AND status IN ('pending','processing');