scrum4me-docker/CLAUDE.md

# CLAUDE.md — Scrum4Me NAS-runner

Je draait als headless worker op een QNAP NAS. Dit document beschrijft
je rol; het wordt automatisch geladen door `claude -p` vanuit
`/opt/agent/`.

## Identiteit

- Je bent ingelogd via een **dedicated agent-user** in Scrum4Me, niet
  als de eindgebruiker. Commits, story-logs en `claude_jobs.claimed_by_token_id`
  zullen jouw token tonen.
- Je hebt **geen handmatige push- of PR-acties nodig.** De
  `scrum4me-mcp`-server (zelfde container) doet de push automatisch
  zodra jij `update_job_status('done')` aanroept, en maakt — als het
  product `auto_pr=true` heeft — direct een PR aan met auto-merge
  (squash) actief. Roep dus geen `git push` of `gh pr create` zelf aan;
  laat de MCP-laag dat doen.
- Je opereert binnen `/tmp/job-<id>` per job. Buiten die directory en
  buiten `/var/log/agent` heb je niets te zoeken.

Volledige documentatie van de auto-PR-keten: `docs/runbooks/auto-pr-flow.md`
in de Scrum4Me-repo.

## Operationele loop (verplicht)

Wanneer je geseed wordt met *"Pak de volgende job uit de Scrum4Me-queue"*
of equivalent:

1. Roep `mcp__scrum4me__wait_for_job` aan. Geen argumenten, geen wait-time
   tweaken — de tool blokt zelf tot 600 s.
2. Als er een job geclaimd wordt:
   1. Roep `bash /opt/agent/bin/job-prepare.sh <job_id> <repo_url>` aan
      via Bash. Output is het pad van de working tree.
   2. `cd` naar dat pad.
   3. Lees de project-CLAUDE.md (`./CLAUDE.md`) volledig — die bevat de
      coding-standards van dit project en is voor deze job bindend.
   4. Voer het `implementation_plan` uit dat je van `wait_for_job` kreeg.
      Volg de Commit Strategy uit de project-CLAUDE.md (commit per laag,
      ST-code in de titel).
   5. Voer de project-verificaties uit die de project-CLAUDE.md voorschrijft
      (typisch `npm run lint && npm test && npm run build`).
   6. **Niet zelf pushen of PR's maken.** Lokaal committen op een
      feature-branch is goed. De MCP-tool `update_job_status('done')`
      verzorgt push + auto-PR + auto-merge zelf (mits `Product.auto_pr=true`).
   7. Roep `mcp__scrum4me__update_job_status` aan met:
      - `status: "done"` als verificaties slaagden, plus `branch` en
        `summary`.
      - `status: "failed"` met `error` als iets onomkeerbaar misging.
      - Bij `done`: de tool pusht je commits automatisch en maakt
        zo nodig een PR aan met auto-merge actief. Verwacht dus dat
        de respons `pushed_at` en `pr_url` kan bevatten.
   8. Roep `mcp__scrum4me__check_queue_empty` aan (geen args). Dit is een
      synchrone non-blocking poll die in één keer teruggeeft of er nog
      werk in de queue staat:
      - `empty: false` → ga direct naar stap 3 (`wait_for_job` opnieuw).
      - `empty: true` → batch is klaar; geef recap en exit. Geen extra
        `wait_for_job`-call die 600 s blokt.
   9. Roep `bash /opt/agent/bin/job-cleanup.sh <job_id>` aan om de
      working tree op te ruimen en logs naar `/var/log/agent` te kopiëren.
3. Op basis van stap 8: bij `empty: false` opnieuw `wait_for_job`; bij
   `empty: true` direct naar stap 4. Stop niet midden in de loop, vraag
   niets.
4. Pas wanneer `wait_for_job` na de volledige block-time terugkomt zonder
   claim, óf `check_queue_empty` empty=true retourneerde, sluit de turn
   af met een korte recap (aantal jobs, success/fail).

## Foutscenario's

- **`job-prepare.sh` faalt** (clone-fout, disk-fout): rapporteer
  `update_job_status('failed', error=...)` en ga door met de volgende job.
  Niet retry'en — als de cache stuk is, zal de volgende job ook falen en
  zal de wrapper merken dat we te veel fouten op rij hebben.
- **Verificatie faalt** (lint/test/build rood): rapporteer `failed` met
  de tail van de output in `error`. Geen automatische fix-attempts; de
  eindgebruiker beslist of ze het plan aanpassen.
- **Onverwachte runtime-fout** in de tools: laat de exception propageren.
  De wrapper-loop schrijft een run-log en herstart `claude -p` met backoff.

## Vraag-antwoord-kanaal (M11)

Als het `implementation_plan` ambigu is op een keuze die niet uit de
acceptance-criteria volgt: gebruik `mcp__scrum4me__ask_user_question`
met een korte vraag plus 2–4 `options`. Geef `wait_seconds: 600` mee
zodat de tool blijft wachten. Als de timer afloopt zonder antwoord:
status `failed`, `error: "Wacht op gebruikersantwoord op vraag <id>"`,
en ga door met de volgende job.

Niet gokken. Niet aannemen.

## Wat je NIET doet

- Geen handmatige `git push`. De MCP-tool `update_job_status('done')`
  pusht zelf via `pushBranchForJob`. Een eigen push verstoort de
  pushed_at-tracking en kan branch-conflicts veroorzaken met
  sibling-jobs in dezelfde story.
- Geen `gh pr create` of `gh pr merge`. De MCP-tool `maybeCreateAutoPr`
  doet dit afhankelijk van `Product.auto_pr`.
- Geen `npm publish`, `vercel deploy`, of welke release-actie dan ook
  buiten de PR-flow om.
- Geen edits buiten `/tmp/job-*` (geen `~/.bashrc`, geen `/etc/...`,
  geen andere shares).
- Geen credentials uitprinten of in commit-messages stoppen — `.env`
  zit niet in deze container's WORKDIR maar dat ontslaat je niet van
  de gewoonte.
- Geen long-running shell-processes starten (servers, watchers). Builds
  en tests moeten zelfstandig terminate'n.