From 6bbab4ef8800a592d9f3d4c79149180e21b0199f Mon Sep 17 00:00:00 2001
From: Madhura68 <janpetervisser2@gmail.com>
Date: Wed, 6 May 2026 04:29:18 +0200
Subject: [PATCH] docs(M13 T-520b): pre-flight quota-check sectie in
 mcp-integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documenteert de batch-loop-uitbreiding:
1. get_worker_settings → min_quota_pct
2. bin/worker-quota-probe.sh → pct + reset
3. worker_heartbeat naar server (NavBar stand-by-badge)
4. Sleep tot reset bij low quota; anders wait_for_job

Verwijst naar bin/worker-quota-probe.sh in scrum4me-docker (zie
PR daar).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/INDEX.md                    |  2 +-
 docs/runbooks/mcp-integration.md | 37 ++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/INDEX.md b/docs/INDEX.md
index 9dd6afc..d156bcd 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -2,7 +2,7 @@
 
 # Documentation Index
 
-Auto-generated on 2026-05-05 from front-matter and headings.
+Auto-generated on 2026-05-06 from front-matter and headings.
 
 ## Architecture Decision Records
 
diff --git a/docs/runbooks/mcp-integration.md b/docs/runbooks/mcp-integration.md
index 61e5f39..865016a 100644
--- a/docs/runbooks/mcp-integration.md
+++ b/docs/runbooks/mcp-integration.md
@@ -70,6 +70,43 @@ Wanneer je als agent draait (na een instructie als *"pak de volgende job uit de
 
 Dit blijft gelden als je tussen jobs door commits, branches of pushes hebt gedaan — die afsluiting hoort bij de individuele job, niet bij het einde van de batch.
 
+## Pre-flight quota-check (M13)
+
+Vóór elke `wait_for_job`-aanroep doet de worker een pre-flight quota-check
+om te voorkomen dat-ie 600 s blokkeert terwijl Anthropic-quota toch op
+0 staat. Loop:
+
+1. `mcp__scrum4me__get_worker_settings()` → `{ min_quota_pct }`
+2. `bash bin/worker-quota-probe.sh` → JSON `{ pct, reset_at_iso, ... }`
+3. `mcp__scrum4me__worker_heartbeat({ last_quota_pct: pct, last_quota_check_at })`
+   — server emit een SSE-event zodat NavBar realtime de stand-by-badge
+   kan tonen
+4. **Als `pct < min_quota_pct`**: log "stand-by, wachten tot
+   `reset_at_iso`", sleep tot reset (cap op 1 uur), spring naar stap 2
+5. **Anders**: ga door met `wait_for_job`
+
+Pseudo-bash:
+
+```bash
+QUOTA_JSON=$(/opt/agent/bin/worker-quota-probe.sh)
+PCT=$(echo "$QUOTA_JSON" | jq -r '.pct')
+RESET=$(echo "$QUOTA_JSON" | jq -r '.reset_at_iso')
+
+# Stuur naar server (best-effort; failure niet-fataal)
+mcp_call worker_heartbeat "{\"last_quota_pct\": $PCT}"
+
+if [[ "$PCT" -lt "$MIN_PCT" ]]; then
+    log "stand-by until $RESET (pct=$PCT < min=$MIN_PCT)"
+    sleep_until "$RESET"
+    continue
+fi
+```
+
+**Beperking**: de probe kost ~1 outputtoken per check. 12 checks/uur =
+12 tokens/uur overhead — verwaarloosbaar. De `min_quota_pct`-setting
+staat per default op 20% — bij vrije Pro/Max-plans typisch ruim genoeg
+om dagelijks werk niet te verstoren.
+
 **Code koppelen aan app**
 - 'Pak de volgende job uit de Scrum4Me-queue' / 'draai de queue leeg' / 'batch agent' — Server-startup registreert een ClaudeWorker-record + heartbeat (5s); SIGTERM/SIGINT ruimt 'm op. UI in NavBar telt actieve workers via `last_seen_at < now() - 15s`.