# FORGED Scope Export

**Session:** forged_375e1af2adf1c81a
**Modus:** N/A
**Status:** N/A

## Urspruengliche Idee
CORE Build Engine — Zentraler Build-Agent fuer XXBILLION. Orchestriert den kompletten 14-Phasen-Entwicklungsprozess: Empfaengt Bauanleitungen von FORGED, erstellt Bauplaene, steuert MKB Reviews (Support-the-Best Checklisten mit wachsenden Spalten), baut Code, deployt auf VPS, testet gemaess Bauplan und 5ISCT, triggert JURY nach Review Live, dokumentiert in Genesis-Ordnern, meldet Freigabe. Python-Tool als Gatekeeper verifiziert Code-Aenderungen an exakten Zeilen. Stack: Python Flask, SQLite, Claude API. Port 5600, core.xxbillion.ai.

## Scope
### Was gebaut wird
CORE Build Engine als zentraler Build-Agent auf core.xxbillion.ai (Port 5600) mit Web-UI + API. Empfang von FORGED-Bauanleitungen per HTTP POST /api/core/receive-spec inkl. Schema-Validierung, Versionierung (monoton steigende version_number), Idempotenz-Key und HMAC-SHA256 (X-FORGED-Signature). Orchestrierung eines verbindlichen 14-Phasen-Prozesses (1–14) mit harter Regel: kein Skip, Pause/Resume erlaubt, Wiederholung einzelner Phasen erlaubt, Vorwärts nur bei 100%. Persistenter State in SQLite (WAL) inkl. Sessions/Phasen/Checklisten/Items/Gatekeeper-Resultaten/Dokument-Metadaten, crash-sicheres Resume (running -> paused bei Restart) und Reconciliation für „stuck running“. MKB-Review-Integration (Bridge API) mit wachsenden Spalten, 6/6-Controller-Logik für 100%, Rundenmodell (nur letzte Runde zählt, vorherige grüne Zeilen bleiben locked), UI für horizontales Spalten-Scrolling, Filter und Kompaktansicht für Johannes. Python-Gatekeeper als Gatekeeper für Checklisten-zu-Code-Verifikation: diff- und AST-basierte Prüfung mit refactor-stabilen Ankern (file + symbol_ref + body-hash), bindet jedes Checklist-Item an commit_before/commit_after; keine Overrides, Eskalation nach 5 Fehlversuchen an Johannes. Build/Deploy/Test-Pipeline: Build (Phase 5) führt Code-Änderungen im Service-Verzeichnis aus, Deploy (Phase 7) auf Hetzner Ubuntu 22.04 via systemd restart, Caddy Reverse Proxy bleibt vorgelagert, atomarer Deploy mit Pre-Deploy Backup (Code-Verzeichnis + SQLite Snapshot), Post-Deploy Healthcheck /health, automatischer Rollback auf letzte funktionierende Version (git tag/Backup) inkl. Timeline-Event. Testausführung gemäß Bauplan (Phase 8) + verpflichtender 5ISCT (Phase 9) mit Retries/Flake-WARN, Reports als Artefakte. Review Live (Phase 10) triggert automatisch JURY (Phase 11) bei 6/6 = 100% auf allen Zeilen, JURY-Statusmaschine (requested/running/completed_pass/completed_fail/timeout) mit Webhook/Polling, Findings werden als neue Checklisten-Zeilen zurückgeführt; JURY_BUG/KEIN_FEHLER werden dokumentiert, echte Fehler müssen zu 4x0 führen. Dokumentation (Phase 12) in Genesis-Ordnerstruktur inkl. Pflichtdokumente, Metadaten-Index in SQLite, Suche/Filter in Web-UI. Freigabe (Phase 14) automatisch bei: Review Plan 100%, Review Code 100%, Review Live 100%, JURY 4x0 (nur echte Fehler), Review Doku 100%; Status-Webhook an Genesis und grünes Signal im Dashboard. Budget-Management (pro Phase soft, pro Session hard 500ct, pro Projekt monitoring), Echtzeit-Kostentracking (Reservation vor Call, Buchung nach Call), UI-Budgetbalken + atomarer +500ct-Button für Johannes, Circuit-Breaker pausiert bei Hard-Limit. Observability: Live-Timeline (letzte 10 Events), Gatekeeper-Status, Checklistenstatus, Laufzeiten pro Phase, Kosten-Counter, strukturierte Logs mit Correlation (session_id/phase), Health-Endpoint und optional /metrics; Notification-Regeln (kritisch vs. Info) mit „rote Lampe“ im Genesis Dashboard und später WhatsApp.

### Akzeptanzkriterien
['CORE akzeptiert minimalen Bauauftrag (session_id, project_id, scope) und validiert tech_spec optional; invalide Payload -> HTTP 400 mit maschinenlesbarer Fehlerliste; gültige -> <5s bis Phase-Start', 'Webhook-Security: HMAC-SHA256 Signaturprüfung mit Replay-Protection (timestamp+nonce) und IP-Allowlist für FORGED; fehlerhafte Signatur -> 401/403 und Audit-Event', '14-Phasen-State-Machine ist implementiert und erzwingt: kein Skip; Phase startet nur wenn vorherige Phase 100% completed; Pause/Resume funktioniert nach Neustart ohne Datenverlust', 'SQLite-Datenmodell besitzt Constraints (Unique/Foreign Keys) für sessions/phases/checklists/items; WAL aktiv; Reconciliation-Job setzt „stuck running“ nach Restart deterministisch auf paused mit Hinweis', 'MKB-Review: Checkliste unterstützt wachsende Spalten, jede Runde hängt Spalten an (nie überschreiben); 100% ist strikt 6/6 pro Zeile; UI kann in <30s den Gesamtstatus erfassbar machen (Kompaktansicht)', 'Gatekeeper: jedes Checklist-Item enthält file_path + symbol_ref + commit_before/commit_after; Gatekeeper bestätigt Änderungen per git diff + AST/body-hash; reine Formatierung wird erkannt (AST unverändert) und nicht als Fix gezählt, blockiert aber nicht', 'Gatekeeper-Block: UI markiert rote Zeile mit Begründung; kein Override; nach 5 Fehlversuchen wird Johannes benachrichtigt und ein Audit-Record existiert', 'Deploy ist atomar: Pre-Deploy Snapshot (Code-Verzeichnis + SQLite .pre-deploy) wird erstellt; bei Healthcheck-Fail erfolgt automatischer Rollback und Service läuft wieder grün; Rollback-Event ist in Timeline sichtbar', 'Phase 8 Tests sind ausführbar und deterministisch genug für Alltag: Start/Stop der App im Test definiert, Seeds/Fixtures geregelt, Retries für Flakes; Ergebnis-Report als Artefakt gespeichert und im Dashboard 1-zeilig zusammengefasst', '5ISCT läuft immer, 3 Retries bei Flakes, danach WARN (nicht Blocker), JSON-Report pro Identität gespeichert', 'JURY-Trigger erfolgt ausschließlich nach Review Live = 100% (6/6 auf allen Zeilen); JURY-Statusmaschine verhindert falsches Weiterlaufen; Timeout (30min) führt zu retry-state statt „grün“', 'Freigabe wird automatisch gesetzt und an Genesis per Webhook gemeldet, sobald alle Freigabekriterien erfüllt sind; Johannes sieht im Dashboard sofort „freigegeben“ inkl. Links zu Bauplan/Checklisten/Reports', 'Budget: Session pausiert automatisch bei Hard-Limit 500ct; Johannes kann im UI +500ct freischalten ohne Session-Verlust; Kosten pro Phase/Session werden nachvollziehbar geloggt', 'Web-UI deckt Johannes’ Daily ab: Dashboard (alle Sessions, Phase, Ampel), Session-Detail (Timeline, Checklisten, Logs, Gatekeeper, Kosten) ohne SSH-Notwendigkeit']

### Nicht-Ziele
Kein CLI für Johannes (nur Web-UI + API). Kein Docker/Kubernetes/Blue-Green/Canary; Deploy ist systemctl restart mit Healthcheck. Kein Multi-User-RBAC v1 (nur Admin Johannes; Read-Only später). Keine automatische Secret-Rotation/Vault-Integration (nur .env + manuelle Rotation). Keine vollständige Cross-Service-Kollisionsprüfung beim Spec-Eingang (Caddy-Konflikte werden beim Deploy sichtbar). Kein Live-Monitoring-getriggerter JURY-Run; JURY nur automatisch nach Review Live 100%. Keine Lösch-/Retention-Policy außer „alles behalten“ (keine Dedupe/Kompression v1). Keine MKB-interne Parallelisierungs-/Kostensteuerung (nur Bridge-Aufruf und Cost-Tracking in CORE). Kein Mehrheitsentscheid bei Controllern und kein Override von 6/6-Regeln.

### Erfolgsbild
Johannes öffnet morgens das Dashboard und erkennt sofort pro Projekt/Session: aktuelle Phase, Ampelstatus, aktive Aufgabe, letzte Events, Kostenstand. CORE arbeitet autonom durch die Pipeline und fragt Johannes nur bei Eskalationen (z.B. Gatekeeper nach 5 Fehlversuchen, Service-Down, Budget-Pause). Standardprojekte deployen innerhalb von 30 Minuten, Tests laufen unter 15 Minuten. Der Service ist 24/7 erreichbar (Auto-Restart, Healthchecks), Ausfälle werden sichtbar gemeldet. Jeder Schritt ist nachvollziehbar: Bauplan, Checklisten (alle Runden), Gatekeeper-Reports, Test-/5ISCT-Reports, JURY-Protokolle und Changelog liegen strukturiert im Genesis-Ordner und sind über die UI such-/filterbar. Freigaben passieren nur bei echten 100%-Gates (Reviews + JURY 4x0 echte Fehler), und Johannes muss keine manuelle Koordination zwischen Tools mehr leisten.

### Risikostellen
Source of Truth & Reproduzierbarkeit: aktuelles „alles auf main auf VPS“ ist fragil; Gatekeeper braucht verlässliche commit_before/after und deterministische Replays/Rollbacks. Build/Test-Umgebung: ohne venv/Python-Pinning und klaren Test-Framework/DoD drohen Drift, nicht reproduzierbare Fehler und lange Debug-Zeiten. Phase-8-Teststrategie: muss konkret werden (Arten, Framework, deterministische Daten, Start/Stop, Mindestkriterien), sonst bleibt Phase 8 nicht automatisierbar. Deploy-Transaktionalität: Code+DB+Config müssen sauber gekapselt sein; Partial-Deploy-Erkennung, Rollback-Konsistenz und „resume“ dürfen keine alten Artefakte als neu interpretieren. Security Hardening: Webhook-Replay-Protection, CSRF/CSP, Least-Privilege (root vermeiden), Audit-Log-Unveränderlichkeit sind nötig für langlebigen Betrieb. State-Machine/DB-Constraints: ohne harte Enumerations/Transitions, Dead-letter/Poison-Handling und Reconciliation entstehen „hängende“ Sessions. Concurrency/Queue: Latest-Wins vs. Historie, Idempotenz, Cancel-Semantik und Fairness müssen sauber definiert sein bevor MAX_CONCURRENT_BUILDS>1 genutzt wird. Scope/Change-Control: klare Regel, was „Scope-Erweiterung“ ist vs. legitime Fixes aus MKB/JURY, sonst Endlosschleifen oder schleichende Feature-Expansion.

## Technische Spezifikation
**Service:** xxbillion-core-build-engine (Port 5600)
**Stack:** {'language': 'Python 3.10', 'framework': 'Flask 3.x', 'server': 'gunicorn', 'database': 'SQLite 3 (WAL)', 'templating': 'Jinja2', 'frontend': 'Vanilla HTML + minimal CSS, no SPA', 'realtime': 'Server-Sent Events (SSE)', 'http_client': 'requests', 'git': 'git CLI required on host', 'crypto': 'hmac + hashlib (HMAC-SHA256)', 'schema_validation': 'jsonschema', 'logging': 'python logging JSON lines', 'migrations': 'SQLite DDL on startup (idempotent) + schema_version table'}

### Datenbank
- {"table": "schema_version", "fields": [{"name": "version", "type": "INTEGER NOT NULL"}, {"name": "applied_at", "type": "TEXT NOT NULL"}], "constraints": ["PRIMARY KEY(version)"], "indices": []}
- {"table": "sessions", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "project_id", "type": "TEXT NOT NULL"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "updated_at", "type": "TEXT NOT NULL"}, {"name": "status", "type": "TEXT NOT NULL"}, {"name": "current_phase", "type": "INTEGER NOT NULL"}, {"name": "active_run_id", "type": "TEXT NOT NULL"}, {"name": "scope_text", "type": "TEXT NOT NULL"}, {"name": "tech_spec_json", "type": "TEXT NULL"}, {"name": "spec_version_number", "type": "INTEGER NOT NULL DEFAULT 1"}, {"name": "forged_idempotency_key", "type": "TEXT NULL"}, {"name": "forged_spec_hash", "type": "TEXT NULL"}, {"name": "budget_hard_limit_cents", "type": "INTEGER NOT NULL DEFAULT 500"}, {"name": "budget_added_cents_total", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "budget_spent_cents", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "budget_reserved_cents", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "last_error_code", "type": "TEXT NULL"}, {"name": "last_error_message", "type": "TEXT NULL"}, {"name": "pause_reason", "type": "TEXT NULL"}, {"name": "service_repo_path", "type": "TEXT NULL"}, {"name": "service_name", "type": "TEXT NULL"}, {"name": "service_port", "type": "INTEGER NULL"}, {"name": "service_health_url", "type": "TEXT NULL"}, {"name": "jury_status", "type": "TEXT NOT NULL DEFAULT 'none'"}, {"name": "jury_session_id", "type": "TEXT NULL"}, {"name": "jury_last_completed_at", "type": "TEXT NULL"}], "constraints": ["CHECK(status IN ('new','running','paused','completed','failed','canceled','budget_paused'))", "CHECK(current_phase BETWEEN 1 AND 14)", "CHECK(jury_status IN ('none','requested','running','completed_pass','completed_fail','timeout'))", "UNIQUE(project_id, spec_version_number)"], "indices": ["idx_sessions_project ON sessions(project_id)", "idx_sessions_status ON sessions(status)", "idx_sessions_updated ON sessions(updated_at)"]}
- {"table": "phase_runs", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "phase_number", "type": "INTEGER NOT NULL"}, {"name": "run_number", "type": "INTEGER NOT NULL"}, {"name": "status", "type": "TEXT NOT NULL"}, {"name": "substatus", "type": "TEXT NULL"}, {"name": "started_at", "type": "TEXT NULL"}, {"name": "ended_at", "type": "TEXT NULL"}, {"name": "progress_percent", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "required_artifacts_json", "type": "TEXT NOT NULL"}, {"name": "artifact_index_json", "type": "TEXT NOT NULL DEFAULT '[]'"}, {"name": "error_code", "type": "TEXT NULL"}, {"name": "error_message", "type": "TEXT NULL"}], "constraints": ["FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE RESTRICT", "CHECK(phase_number BETWEEN 1 AND 14)", "CHECK(status IN ('queued','running','paused','completed','failed'))", "CHECK(progress_percent BETWEEN 0 AND 100)", "UNIQUE(session_id, phase_number, run_number)"], "indices": ["idx_phase_runs_session_phase ON phase_runs(session_id, phase_number)", "idx_phase_runs_status ON phase_runs(status)"]}
- {"table": "timeline_events", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "phase_run_id", "type": "TEXT NULL"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "level", "type": "TEXT NOT NULL"}, {"name": "event_type", "type": "TEXT NOT NULL"}, {"name": "message", "type": "TEXT NOT NULL"}, {"name": "data_json", "type": "TEXT NOT NULL DEFAULT '{}'"}], "constraints": ["FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE RESTRICT", "FOREIGN KEY(phase_run_id) REFERENCES phase_runs(id) ON DELETE SET NULL", "CHECK(level IN ('debug','info','warn','error','critical'))"], "indices": ["idx_timeline_session_time ON timeline_events(session_id, created_at DESC)", "idx_timeline_type ON timeline_events(event_type)"]}
- {"table": "audit_events", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "actor_type", "type": "TEXT NOT NULL"}, {"name": "actor_id", "type": "TEXT NULL"}, {"name": "action", "type": "TEXT NOT NULL"}, {"name": "session_id", "type": "TEXT NULL"}, {"name": "phase_run_id", "type": "TEXT NULL"}, {"name": "request_id", "type": "TEXT NULL"}, {"name": "ip", "type": "TEXT NULL"}, {"name": "user_agent", "type": "TEXT NULL"}, {"name": "data_json", "type": "TEXT NOT NULL DEFAULT '{}'"}], "constraints": ["CHECK(actor_type IN ('forged','mkb','jury','genesis','admin','system'))"], "indices": ["idx_audit_time ON audit_events(created_at DESC)", "idx_audit_session ON audit_events(session_id)"]}
- {"table": "webhook_nonces", "fields": [{"name": "nonce", "type": "TEXT PRIMARY KEY"}, {"name": "source", "type": "TEXT NOT NULL"}, {"name": "timestamp", "type": "INTEGER NOT NULL"}, {"name": "received_at", "type": "TEXT NOT NULL"}], "constraints": ["CHECK(source IN ('forged','mkb','jury','genesis'))"], "indices": ["idx_nonces_time ON webhook_nonces(timestamp)"]}
- {"table": "inbound_specs", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "received_at", "type": "TEXT NOT NULL"}, {"name": "source", "type": "TEXT NOT NULL"}, {"name": "idempotency_key", "type": "TEXT NOT NULL"}, {"name": "project_id", "type": "TEXT NOT NULL"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "version_number", "type": "INTEGER NOT NULL"}, {"name": "spec_hash", "type": "TEXT NOT NULL"}, {"name": "payload_json", "type": "TEXT NOT NULL"}, {"name": "status", "type": "TEXT NOT NULL"}, {"name": "error_json", "type": "TEXT NOT NULL DEFAULT '[]'"}], "constraints": ["CHECK(source IN ('forged','ui_upload'))", "CHECK(status IN ('queued','processed','rejected'))", "UNIQUE(source, idempotency_key)"], "indices": ["idx_inbound_specs_project_ver ON inbound_specs(project_id, version_number DESC)", "idx_inbound_specs_status ON inbound_specs(status)"]}
- {"table": "checklists", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "phase_number", "type": "INTEGER NOT NULL"}, {"name": "round_number", "type": "INTEGER NOT NULL"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "source", "type": "TEXT NOT NULL"}, {"name": "status", "type": "TEXT NOT NULL"}, {"name": "columns_json", "type": "TEXT NOT NULL"}, {"name": "summary_json", "type": "TEXT NOT NULL DEFAULT '{}'"}], "constraints": ["FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE RESTRICT", "CHECK(phase_number IN (4,6,10,13))", "CHECK(source IN ('mkb','system','jury_feedback'))", "CHECK(status IN ('open','completed'))", "UNIQUE(session_id, phase_number, round_number)"], "indices": ["idx_checklists_session_phase ON checklists(session_id, phase_number)", "idx_checklists_status ON checklists(status)"]}
- {"table": "checklist_items", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "checklist_id", "type": "TEXT NOT NULL"}, {"name": "row_number", "type": "INTEGER NOT NULL"}, {"name": "requirement_text", "type": "TEXT NOT NULL"}, {"name": "source_ref", "type": "TEXT NOT NULL"}, {"name": "locked_green", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "file_path", "type": "TEXT NULL"}, {"name": "symbol_ref", "type": "TEXT NULL"}, {"name": "anchor_type", "type": "TEXT NOT NULL DEFAULT 'symbol'"}, {"name": "anchor_body_hash_before", "type": "TEXT NULL"}, {"name": "anchor_body_hash_after", "type": "TEXT NULL"}, {"name": "commit_before", "type": "TEXT NULL"}, {"name": "commit_after", "type": "TEXT NULL"}, {"name": "formatting_only", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "controller_results_json", "type": "TEXT NOT NULL DEFAULT '{}'"}, {"name": "mkb_notes", "type": "TEXT NULL"}, {"name": "gatekeeper_status", "type": "TEXT NOT NULL DEFAULT 'not_run'"}, {"name": "gatekeeper_attempts", "type": "INTEGER NOT NULL DEFAULT 0"}, {"name": "gatekeeper_last_error", "type": "TEXT NULL"}], "constraints": ["FOREIGN KEY(checklist_id) REFERENCES checklists(id) ON DELETE CASCADE", "CHECK(anchor_type IN ('symbol','file_context'))", "CHECK(gatekeeper_status IN ('not_run','pass','fail'))", "UNIQUE(checklist_id, row_number)"], "indices": ["idx_items_checklist ON checklist_items(checklist_id, row_number)", "idx_items_gatekeeper ON checklist_items(gatekeeper_status)"]}
- {"table": "gatekeeper_results", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "phase_number", "type": "INTEGER NOT NULL"}, {"name": "checklist_item_id", "type": "TEXT NOT NULL"}, {"name": "attempt_number", "type": "INTEGER NOT NULL"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "repo_path", "type": "TEXT NOT NULL"}, {"name": "commit_before", "type": "TEXT NOT NULL"}, {"name": "commit_after", "type": "TEXT NOT NULL"}, {"name": "file_path", "type": "TEXT NOT NULL"}, {"name": "symbol_ref", "type": "TEXT NOT NULL"}, {"name": "anchor_hash_before", "type": "TEXT NULL"}, {"name": "anchor_hash_after", "type": "TEXT NULL"}, {"name": "diff_text", "type": "TEXT NOT NULL"}, {"name": "ast_changed", "type": "INTEGER NOT NULL"}, {"name": "formatting_only", "type": "INTEGER NOT NULL"}, {"name": "status", "type": "TEXT NOT NULL"}, {"name": "reason", "type": "TEXT NOT NULL"}], "constraints": ["FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE RESTRICT", "FOREIGN KEY(checklist_item_id) REFERENCES checklist_items(id) ON DELETE RESTRICT", "CHECK(status IN ('pass','fail'))", "UNIQUE(checklist_item_id, attempt_number)"], "indices": ["idx_gatekeeper_session_phase ON gatekeeper_results(session_id, phase_number)", "idx_gatekeeper_item ON gatekeeper_results(checklist_item_id)"]}
- {"table": "documents", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "phase_number", "type": "INTEGER NOT NULL"}, {"name": "doc_type", "type": "TEXT NOT NULL"}, {"name": "round_number", "type": "INTEGER NULL"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "path", "type": "TEXT NOT NULL"}, {"name": "sha256", "type": "TEXT NOT NULL"}, {"name": "size_bytes", "type": "INTEGER NOT NULL"}, {"name": "mime_type", "type": "TEXT NOT NULL"}, {"name": "title", "type": "TEXT NOT NULL"}, {"name": "tags_json", "type": "TEXT NOT NULL DEFAULT '[]'"}], "constraints": ["FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE RESTRICT", "CHECK(phase_number BETWEEN 1 AND 14)", "UNIQUE(session_id, phase_number, doc_type, COALESCE(round_number, -1), path)"], "indices": ["idx_docs_session_phase ON documents(session_id, phase_number)", "idx_docs_type ON documents(doc_type)"]}
- {"table": "budget_ledger", "fields": [{"name": "id", "type": "TEXT PRIMARY KEY"}, {"name": "session_id", "type": "TEXT NOT NULL"}, {"name": "created_at", "type": "TEXT NOT NULL"}, {"name": "kind", "type": "TEXT NOT NULL"}, {"name": "phase_run_id", "type": "TEXT NULL"}, {"name": "external_call_id", "type": "TEXT NULL"}, {"name": "amount_cents", "type": "INTEGER NOT NULL"}, {"name": "note", "type": "TEXT NOT NULL"}, {"name": "data_json", "type": "TEXT NOT NULL DEFAULT '{}'"}], "constraints": ["FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE RESTRICT", "CHECK(kind IN ('reserve','commit','release','manual_add'))"], "indices": ["idx_budget_session_time ON budget_ledger(session_id, created_at DESC)"]}
- {"table": "locks", "fields": [{"name": "name", "type": "TEXT PRIMARY KEY"}, {"name": "holder", "type": "TEXT NOT NULL"}, {"name": "acquired_at", "type": "TEXT NOT NULL"}, {"name": "expires_at", "type": "TEXT NOT NULL"}], "constraints": [], "indices": ["idx_locks_expires ON locks(expires_at)"]}

### API Endpoints
- {"method": "GET", "path": "/health", "description": "Healthcheck for reverse proxy and deploy validation. Must not require auth.", "request_body": null, "response": {"status": "string('ok')", "time_utc": "string(ISO8601)", "db": "string('ok'|'error')", "worker": "string('ok'|'stopped')", "version": "string"}, "auth_required": false, "status_codes": [200, 500]}
- {"method": "GET", "path": "/metrics", "description": "Optional Prometheus-like plaintext metrics. If disabled, return 404.", "request_body": null, "response": {"text/plain": "string"}, "auth_required": false, "status_codes": [200, 404]}
- {"method": "POST", "path": "/api/core/receive-spec", "description": "Receives build instruction/spec from FORGED. Validates schema, HMAC signature, replay protection, idempotency, version monotonicity per project_id, persists inbound_specs, starts/continues session workflow within <5s by enqueueing phase 3 if allowed.", "request_body": {"session_id": "string(min=3,max=64,pattern=^[a-zA-Z0-9_-]+$)", "project_id": "string(min=3,max=64,pattern=^[a-zA-Z0-9_-]+$)", "scope": "string(min=1,max=20000)", "version_number": "integer(min=1)", "tech_spec": "object|null"}, "request_schema_rules": ["Required fields: session_id, project_id, scope, version_number", "tech_spec is optional; if present must be JSON object and <= 500KB serialized", "Reject if Content-Type not application/json", "Reject if body > 600KB"], "response": {"accepted": "boolean", "session_id": "string", "project_id": "string", "version_number": "integer", "inbound_spec_id": "string", "session_status": "string", "current_phase": "integer", "errors": "array<object>{path:string,code:string,message:string}"}, "auth_required": false, "status_codes": [200, 202, 400, 401, 403, 409], "idempotency_rules": ["Idempotency-Key header required; same key returns same response body as first successful processing (200) or first rejection (4xx) with stored error_json", "If same Idempotency-Key but different payload hash -> 409 error_code='IDEMPOTENCY_KEY_REUSE_DIFFERENT_BODY'"], "versioning_rules": ["For each project_id, version_number must be strictly increasing compared to sessions.spec_version_number for latest session row with that project_id", "If version_number == current stored for project_id and spec_hash identical -> treated as duplicate; return 200 accepted=true without starting new run", "If version_number <= stored and spec_hash differs -> 409 error_code='SPEC_VERSION_NOT_MONOTONIC'"]}
- {"method": "POST", "path": "/api/admin/spec-upload", "description": "Manual upload of a spec (fallback). Same validation as FORGED but authenticated and without HMAC/IP checks.", "request_body": {"session_id": "string", "project_id": "string", "scope": "string", "version_number": "integer", "tech_spec": "object|null"}, "response": {"accepted": "boolean", "inbound_spec_id": "string", "session_id": "string", "current_phase": "integer", "errors": "array"}, "auth_required": true, "status_codes": [200, 400, 409]}
- {"method": "GET", "path": "/api/sessions", "description": "List sessions for dashboard.", "request_body": null, "response": {"sessions": "array<object>{id:string,project_id:string,status:string,current_phase:int,updated_at:string,ampel:string,last_event:string,budget_spent_cents:int,budget_hard_limit_cents:int}"}, "auth_required": true, "status_codes": [200]}
- {"method": "GET", "path": "/api/sessions/{session_id}", "description": "Get full session details including phase runs, last 10 events, budget, jury, and links.", "request_body": null, "response": {"session": "object", "phase_runs": "array<object>", "timeline_last_10": "array<object>", "checklist_overview": "array<object>{phase_number:int,latest_round:int,total_rows:int,green_rows:int,percent:int}", "budget": "object{spent:int,reserved:int,hard_limit:int,added_total:int}", "links": "object{ui_session:string,documents:string}"}, "auth_required": true, "status_codes": [200, 404]}
- {"method": "POST", "path": "/api/sessions/{session_id}/pause", "description": "Pause session; sets session.status=paused (or budget_paused stays budget_paused), and current running phase_run.status=paused. Must be idempotent.", "request_body": {"reason": "string(max=5000)"}, "response": {"ok": "boolean", "status": "string", "current_phase": "integer"}, "auth_required": true, "status_codes": [200, 404, 409]}
- {"method": "POST", "path": "/api/sessions/{session_id}/resume", "description": "Resume session from paused/budget_paused. If budget_paused, requires budget to be under limit. Starts worker processing within <5s.", "request_body": null, "response": {"ok": "boolean", "status": "string", "current_phase": "integer"}, "auth_required": true, "status_codes": [200, 404, 409]}
- {"method": "POST", "path": "/api/budget/{session_id}/add", "description": "Atomically adds +500 cents to hard limit. Only admin. Must be atomic and idempotent per request_id header.", "request_body": {"amount_cents": "integer(enum=[500])"}, "response": {"ok": "boolean", "new_hard_limit_cents": "integer", "added_total_cents": "integer"}, "auth_required": true, "status_codes": [200, 404, 409], "idempotency_rules": ["Requires header X-Request-Id; unique per action; stored in audit_events.request_id; duplicates return same response"]}
- {"method": "GET", "path": "/api/checklists/{session_id}/{phase_number}", "description": "Returns latest checklist round for phase 4/6/10/13 including column model and rows. Used by UI for horizontal scrolling table.", "request_body": null, "response": {"checklist": "object{id:string,phase_number:int,round_number:int,status:string,columns:array<object>,rows:array<object>}"}, "auth_required": true, "status_codes": [200, 404, 409]}
- {"method": "POST", "path": "/api/mkb/webhook", "description": "Webhook receiver for MKB Bridge results. Must validate replay-protection headers (X-MKB-Timestamp, X-MKB-Nonce) and HMAC header X-MKB-Signature using CORE_MKB_BRIDGE_TOKEN as secret. Updates checklist round results and locks green rows.", "request_body": {"session_id": "string", "phase_number": "integer(enum=[4,6,10,13])", "round_number": "integer(min=1)", "columns": "array<object>", "rows": "array<object>{row_number:int,requirement_text:string,controller_results:object,notes:string|null,file_path:string|null,symbol_ref:string|null,commit_before:string|null,commit_after:string|null,anchor_body_hash_before:string|null,anchor_body_hash_after:string|null}"}, "response": {"ok": "boolean"}, "auth_required": false, "status_codes": [200, 400, 401, 403, 404, 409]}
- {"method": "POST", "path": "/api/jury/webhook", "description": "Webhook receiver for JURY completion. Validates replay-protection + HMAC (X-JURY-Signature, X-JURY-Timestamp, X-JURY-Nonce). Writes findings as documents and potentially as new checklist rows for phase 10 or 6 based on mapping.", "request_body": {"session_id": "string", "jury_session_id": "string", "status": "string(enum=['completed_pass','completed_fail','timeout'])", "completed_at": "string(ISO8601)", "findings": "array<object>{severity:string(enum=['critical','major','minor','info']),title:string,description:string,is_jury_bug:boolean,is_false_positive:boolean,affected_url:string|null,suggested_fix:string|null,source_locator:string|null}"}, "response": {"ok": "boolean"}, "auth_required": false, "status_codes": [200, 400, 401, 403, 404, 409]}
- {"method": "GET", "path": "/api/events/stream", "description": "SSE stream for live dashboard/session updates. Emits JSON per event with session_id correlation. Auth required.", "request_body": null, "response": {"event_stream": "text/event-stream; data: {type:string,session_id:string,phase:int,level:string,message:string,created_at:string}"}, "auth_required": true, "status_codes": [200, 401]}
- {"method": "GET", "path": "/api/documents/{session_id}", "description": "List documents with filters query params: phase_number, doc_type, q (substring in title), tag.", "request_body": null, "response": {"documents": "array<object>{id:string,phase_number:int,doc_type:string,round_number:int|null,created_at:string,title:string,path:string,size_bytes:int,tags:array<string>}"}, "auth_required": true, "status_codes": [200, 404]}

### UI Seiten
- {"path": "/", "title": "CORE Dashboard", "elements": ["Top bar: Service name + current time (UTC) + global health indicator (green if /health db=ok and worker=ok)", "Table 'Sessions' with columns: Project, Session, Phase (1-14), Status, Ampel, Last Event (single line), Updated, Budget (spent/hard), Actions", "Actions per row: Open, Pause (if running), Resume (if paused/budget_paused)"], "layout": "Single column; table full width; no modals; actions are inline buttons.", "interactions": ["Open -> navigates to /sessions/{session_id}", "Pause -> POST /api/sessions/{id}/pause then refresh row", "Resume -> POST /api/sessions/{id}/resume then refresh row", "Page opens SSE /api/events/stream and updates Last Event + Status live"]}
- {"path": "/sessions/{session_id}", "title": "Session Detail", "elements": ["Header: Project ID, Session ID, Status badge, Current Phase, Ampel", "Buttons: Pause, Resume, +500ct Budget", "Budget bar: percent=spent/hard, labels at 80% (yellow) and 95% (red), values spent/reserved/hard", "Panel 'Timeline (last 10)' list with timestamp, level, event_type, message; link 'all events' anchors to /sessions/{id}#events", "Panel 'Phases' vertical list 1..14 with each latest run status (queued/running/paused/completed/failed), runtime (ended-started), progress%", "Panel 'Checklists' with links for phases 4/6/10/13 to open latest checklist view", "Panel 'Gatekeeper' with counters: items pass/fail/not_run and list of failing items with reason and link to checklist row", "Panel 'Documents' list latest 10 docs with filters: phase dropdown, type dropdown, search input; opens file path via download endpoint (served as static file)"], "layout": "Two columns on desktop: left=timeline+phases, right=budget+checklists+gatekeeper+documents; collapses to single column under 900px.", "interactions": ["+500ct -> POST /api/budget/{id}/add amount=500, then refresh budget bar", "Checklist link -> navigates to /sessions/{id}/checklists/{phase_number}", "Failing gatekeeper item click -> scrolls checklist table to that row and highlights it"]}
- {"path": "/sessions/{session_id}/checklists/{phase_number}", "title": "Checklist Viewer", "elements": ["Header: Phase number, latest round number, percent complete, counts green/total", "Controls row: Filter (All / Only open / Only failing / Only green), Compact toggle (compact shows only: row_number, requirement, status, failing controller names), Search input (substring over requirement_text)", "Checklist table with frozen first 2 columns (Row#, Requirement) and horizontally scrollable remaining columns", "Columns must be rendered in exact order as checklists.columns_json; never re-ordered by UI", "Each row shows: requirement_text, file_path, symbol_ref, commit_before, commit_after, gatekeeper_status, then controller columns (DEV-1, DEV-5, DEV-6, DEV-9, DEV-3, DEV-15) and any additional MKB columns as provided", "Row coloring: green only if 6/6 controllers = 100% AND gatekeeper_status=pass (if file_path/symbol_ref present); red otherwise; gray if no controller results"], "layout": "Full-width; table header sticky; horizontal scroll with visible scrollbar.", "interactions": ["Filter changes update table client-side only (no API call)", "Compact toggle hides all non-essential columns but keeps controller pass/fail summary", "If a row is red, UI must show a 'Why blocked' expandable area with: failing controllers + gatekeeper reason (if fail) + latest mkb_notes"]}
- {"path": "/admin/spec-upload", "title": "Manual Spec Upload", "elements": ["Form fields: session_id, project_id, version_number, scope textarea, tech_spec JSON textarea (optional)", "Submit button", "Result area showing accepted/rejected and errors list"], "interactions": ["Submit -> POST /api/admin/spec-upload; on 400 show error list exactly as returned"]}

### Business Logic
- {"rule": "Wenn /api/core/receive-spec valide ist, dann wird inbound_specs.status='queued' gespeichert und eine Session angelegt/aktualisiert, und innerhalb von <5s ein Phase-Run für Phase 3 queued.", "details": "Session upsert: Wenn sessions.id existiert -> update scope_text, tech_spec_json, spec_version_number=version_number, updated_at=now. Wenn nicht existiert -> insert mit status='new', current_phase=1, active_run_id=uuid. Danach enqueue_work(session_id) setzt sessions.status='running' falls nicht paused/budget_paused."}
- {"rule": "Wenn CORE neu startet, dann werden alle Sessions mit status='running' deterministisch auf status='paused' gesetzt und die aktuell laufende phase_runs.status='paused' gesetzt.", "details": "Beim Startup: Transaktion: UPDATE sessions SET status='paused', pause_reason='restart_reconciliation', updated_at=now WHERE status='running'; UPDATE phase_runs SET status='paused', substatus='reconciled_from_running', ended_at=now WHERE status='running'. Timeline + Audit event erzeugen."}
- {"rule": "Es gibt kein Skip: Phase N darf nur starten, wenn Phase N-1 in irgendeinem Run status='completed' hat (progress_percent=100) und validate_phase_completion(session_id,N-1) true ist.", "details": "Worker wählt nächsten startbaren Phase-Run: kleinste phase_number mit nicht completed. Start ist verboten wenn vorherige Phase nicht completed. Wiederholung: Wenn eine Phase failed oder Review/JURY neue Items erzeugt, wird ein neuer run_number für die betroffene Phase erstellt und erneut ausgeführt; previous completed run bleibt unverändert."}
- {"rule": "Phase-Completion ist atomar: Artefakte werden zuerst in tmp geschrieben, validiert, nach Ziel verschoben, dann DB in einer Transaktion auf completed gesetzt.", "details": "Für jedes Artefakt: write tmp file, fsync, validate (exists, size>0, parseable if JSON), atomic rename to artifacts_root/session_id/phase_{n}/run_{r}/...; erst danach BEGIN; update phase_runs.status='completed', progress_percent=100, artifact_index_json includes final paths; COMMIT."}
- {"rule": "MKB Review 100%: Eine Checklisten-Zeile ist nur grün wenn alle 6 Controller exakt '100%' melden; 5/6 reicht nicht.", "details": "controller_results_json muss Keys enthalten: DEV-1,DEV-5,DEV-6,DEV-9,DEV-3,DEV-15. Grün wenn alle Werte genau String '100%'. Jede andere Zeichenkette ist ein Fehlertext. 100% für Phase = alle Zeilen grün. Locked-green: Wenn eine Zeile in einer früheren Runde 6/6 grün war, wird locked_green=1 und muss in späteren Runden nicht erneut angefragt werden; bleibt grün."}
- {"rule": "Rundenmodell: Nur die letzte Runde zählt für nicht-locked Zeilen; frühere Runden bleiben als Historie unverändert.", "details": "Neue Runde = checklists.round_number +1, neue Spalten werden nur angehängt: columns_json der neuen Runde ist columns_json der alten Runde + new_columns; niemals Spalten entfernen/überschreiben. checklist_items in neuer Runde übernehmen requirement_text+source_ref; locked_green rows werden kopiert mit locked_green=1 und controller_results_json unverändert."}
- {"rule": "Gatekeeper: Für jedes Checklist-Item mit file_path+symbol_ref+commit_before+commit_after muss Gatekeeper pass liefern, sonst blockiert es Phase-Advance.", "details": "Gatekeeper wird bei Abschluss von Phase 5 und bei jeder Review-Runde von Phase 6 automatisch für alle nicht-locked Items ausgeführt. Kein Override. gatekeeper_attempts++ pro Run. Nach 5 fails für dasselbe checklist_item_id: Session wird pausiert und es wird ein critical Timeline+Audit Event 'gatekeeper_escalation' erstellt."}
- {"rule": "Gatekeeper semantische Prüfung: Wenn AST unverändert, ist es formatting_only=1; wird akzeptiert (gatekeeper pass), zählt aber nicht als Fix-Indikator.", "details": "Python-Dateien: parse AST für symbol_ref; compute body hash from AST dump. ast_changed = (hash_before != hash_after). Wenn diff vorhanden aber ast_changed=false -> formatting_only=1, status pass. Nicht-Python-Dateien: ast_changed wird 1 wenn diff nicht leer ist."}
- {"rule": "Deploy ist atomar: Pre-Deploy Snapshot von Code-Verzeichnis und SQLite Snapshot; Healthcheck entscheidet über Rollback.", "details": "Phase 7 flow: (1) Acquire deploy lock 'deploy:{service_name}'. (2) Create snapshot dir artifacts_root/session_id/deploy_snapshots/{ts}/code/ by rsync --exclude .env and --exclude artifacts; copy SQLite db files from service_repo_path to snapshot dir with suffix .pre-deploy. (3) Apply code changes already present in repo_path. (4) systemctl restart {service_systemd_unit}. (5) Healthcheck GET service_health_url, 3 tries, 2s delay, timeout 2s. If fail -> restore code from snapshot to repo_path, restore sqlite from .pre-deploy, systemctl restart, re-check health. If still fail -> phase_run failed with error_code='DEPLOY_ROLLBACK_FAILED'. Always write timeline event for snapshot, restart, health result, rollback."}
- {"rule": "Budget Circuit Breaker: Vor jedem externen Call muss reserviert werden; bei Überschreitung wird Session budget_paused.", "details": "reserve_cents = estimated_max_output_tokens * price_per_token + fixed_overhead_cents. Wenn budget_spent_cents + budget_reserved_cents + reserve_cents > budget_hard_limit_cents -> set sessions.status='budget_paused', pause_reason='budget_hard_limit', create timeline+audit, do not start call. Nach Call: replace reservation with committed actual cost from usage; update ledger entries reserve->commit/release."}
- {"rule": "JURY Trigger: Nur wenn Phase 10 Review Live 100% ist, dann set jury_status requested und starte JURY.", "details": "On Phase 10 completion: verify checklist pass criteria. Then: update sessions.jury_status='requested'; POST CORE_JURY_BASE_URL + '/api/jury/start' with body {session_id,project_id,url:service_public_url}. On 200: store jury_session_id, set jury_status='running'. Poll every 60s until completed_* or timeout at 1800s. Timeout sets jury_status='timeout' and creates retry event; worker retries start after 300s by re-requesting /api/jury/status then /api/jury/retry if supported; if not supported, re-run /api/jury/start with new jury_session_id and keep history as document."}
- {"rule": "JURY Findings Rückführung: echte Fehler erzeugen neue Checklisten-Zeilen; JURY_BUG und KEIN_FEHLER erzeugen nur Dokumentation und blockieren 4x0 nicht.", "details": "Finding mapping: if is_jury_bug=true OR is_false_positive=true -> document only; else -> create new checklist item in phase 10 checklist (if UI/UX issue) or phase 6 checklist (if code defect) with requirement_text prefixed 'JURY:' and source_ref='jury:{jury_session_id}'. Freigabe-Check zählt nur echte Fehler: 4x0 bedeutet count(findings where is_jury_bug=false and is_false_positive=false and severity in critical/major/minor/info)==0."}
- {"rule": "Freigabe (Phase 14) wird automatisch gesetzt und an Genesis gemeldet, wenn alle Gates erfüllt sind.", "details": "Gates: Phase4=100%, Phase6=100%, Phase10=100%, Phase11 jury_status=completed_pass with 4x0 echte Fehler, Phase13=100%. Dann set sessions.status='completed', current_phase=14, create documents: release_note.md, and POST to CORE_GENESIS_WEBHOOK_URL with HMAC using CORE_GENESIS_WEBHOOK_SECRET."}

### Dateistruktur
- {"file": "app.py", "purpose": "Flask app factory, route registration, error handlers, middleware (auth header, rate limit), SSE endpoint."}
- {"file": "core/config.py", "purpose": "Load env vars, defaults, validation on startup; fail-fast if missing required env."}
- {"file": "core/db.py", "purpose": "SQLite connection (WAL), migrations/DDL, transaction helpers, row dict helpers."}
- {"file": "core/models.py", "purpose": "Typed constants/enums for statuses, phase definitions, validation helpers."}
- {"file": "core/security.py", "purpose": "HMAC verification, replay protection, IP allowlist parsing, CSP header."}
- {"file": "core/spec_schema.py", "purpose": "JSONSchema for receive-spec payload, validation and error normalization."}
- {"file": "core/worker.py", "purpose": "Background worker loop, queue selection, phase execution orchestration, reconciliation job."}
- {"file": "core/phases/phase03_planning.py", "purpose": "Claude call for build plan, validation against tech_spec, artifact writes."}
- {"file": "core/phases/phase05_build.py", "purpose": "Repo writes + git commit + gatekeeper run stub invocation."}
- {"file": "core/phases/phase07_deploy.py", "purpose": "Snapshot, systemd restart, healthcheck, rollback logic."}
- {"file": "core/phases/phase08_tests.py", "purpose": "pytest execution, report capture, artifact registration."}
- {"file": "core/phases/phase09_5isct.py", "purpose": "5ISCT Claude prompts, retries, warn handling, JSON report."}
- {"file": "core/phases/phase11_jury.py", "purpose": "JURY start/poll/timeout, webhook handler helpers."}
- {"file": "core/phases/phase12_docs.py", "purpose": "Genesis folder writes, required docs generation, indexing in documents table."}
- {"file": "core/mkb_bridge.py", "purpose": "Outgoing calls to MKB bridge to request reviews, polling (if used), webhook processing."}
- {"file": "core/gatekeeper.py", "purpose": "Diff + AST verification, anchor extraction, ignore patterns."}
- {"file": "core/git_tools.py", "purpose": "git diff, commit sha retrieval, follow renames, safe command execution."}
- {"file": "core/budget.py", "purpose": "Reservation/commit/release ledger logic, hard limit enforcement."}
- {"file": "core/genesis.py", "purpose": "Genesis webhook client + document path conventions + HMAC signing."}
- {"file": "templates/dashboard.html", "purpose": "Dashboard page server-rendered."}
- {"file": "templates/session_detail.html", "purpose": "Session detail page server-rendered."}
- {"file": "templates/checklist_view.html", "purpose": "Checklist viewer with horizontal scroll table."}
- {"file": "templates/spec_upload.html", "purpose": "Manual spec upload page."}
- {"file": "static/core.css", "purpose": "Minimal CSS for table scrolling, sticky headers, color states."}
- {"file": "static/core.js", "purpose": "SSE client, table filtering, compact toggle, row highlight."}

### Akzeptanz-Checks
- {"check": "Minimaler Bauauftrag wird akzeptiert und startet Phase-Queue in <5s.", "how_to_verify": "curl -X POST https://core.xxbillion.ai/api/core/receive-spec mit gültiger HMAC+Headers und body {session_id,project_id,scope,version_number}. Zeit messen bis sessions.status='running' und phase_runs für phase=3 status='queued' via GET /api/sessions/{id} sichtbar ist; muss <5s sein."}
- {"check": "Ungültiges JSON Schema liefert 400 mit maschinenlesbarer Fehlerliste.", "how_to_verify": "POST ohne project_id; Response 400 JSON enthält errors[0].path == '/project_id' und code == 'REQUIRED'."}
- {"check": "Webhook Security: falsche HMAC Signatur -> 401 und Audit-Event.", "how_to_verify": "POST mit falschem X-FORGED-Signature; Response 401; audit_events latest action='forged_webhook_rejected' data_json.error_code='FORGED_SIGNATURE_INVALID'."}
- {"check": "Replay Protection: gleicher Nonce erneut -> 403.", "how_to_verify": "Sende identischen Request zweimal mit gleichem X-FORGED-Nonce; zweiter Response 403 error_code='FORGED_REPLAY_DETECTED'."}
- {"check": "Keine Skip-Regel: Phase 4 kann nicht starten ohne completed Phase 3.", "how_to_verify": "Manipulationsversuch durch POST /api/sessions/{id}/resume oder internes Triggern; System muss 409 error_code='PHASE_PREREQUISITE_NOT_MET' und Phase 4 bleibt queued/running=false."}
- {"check": "Restart-Reconciliation: running -> paused deterministisch.", "how_to_verify": "Session auf running setzen (Phase 5 running), Service neu starten, dann GET /api/sessions/{id} zeigt status='paused' und phase_runs.status='paused' mit substatus='reconciled_from_running'."}
- {"check": "MKB 6/6-Logik: 5/6 ist nicht grün.", "how_to_verify": "Sende MKB webhook mit einer Zeile wo ein Controller !='100%'; UI zeigt rot; Phase bleibt blockiert."}
- {"check": "Gatekeeper: Item bindet an commit_before/after und bestätigt AST-Änderung oder formatting-only korrekt.", "how_to_verify": "Erzeuge Commit A->B mit nur Black formatting in function; Gatekeeper status pass und formatting_only=1. Erzeuge Commit C->D mit semantischer Änderung; Gatekeeper status pass und ast_changed=1."}
- {"check": "Gatekeeper Eskalation nach 5 Fehlversuchen pausiert Session und erzeugt critical Event.", "how_to_verify": "Führe 5 mal Gatekeeper fail für gleiche checklist_item_id aus; session.status wird 'paused' oder 'budget_paused' bleibt, und timeline_events enthält event_type='gatekeeper_escalation' level='critical'."}
- {"check": "Deploy atomar mit Rollback bei Health-Fail.", "how_to_verify": "Simuliere Deploy mit absichtlich kaputter app import; Healthcheck fail -> Rollback; danach /health der Ziel-App liefert 200 und timeline enthält deploy_rollback event."}
- {"check": "Phase 8 Tests ausführbar und Report als Artefakt gespeichert.", "how_to_verify": "Vorhandene tests/ ausführen; artifacts Pfad enthält pytest_report.json; Dashboard zeigt 1-zeilige Zusammenfassung 'pytest: pass' oder 'pytest: fail' in Last Event."}
- {"check": "5ISCT läuft immer, 3 Retries bei Flakes, danach WARN, nicht Blocker.", "how_to_verify": "Simuliere 5ISCT Antwort mit flaky Marker 3x; Phase 9 completed mit warn in timeline_events, nicht failed."}
- {"check": "JURY Trigger nur nach Review Live 100%.", "how_to_verify": "Solange Phase 10 nicht 100% ist, darf sessions.jury_status nicht 'requested' werden. Nach 100% muss automatisch 'requested'->'running' erscheinen."}
- {"check": "Freigabe setzt Status completed und sendet Genesis Webhook.", "how_to_verify": "Erfülle alle Gates; CORE erstellt audit_event action='release_sent' und sessions.status='completed', current_phase=14; Genesis webhook request im audit log gespeichert (ohne Secret)."}
- {"check": "Budget Hard-Limit pausiert Session automatisch; +500ct Button setzt neue Grenze ohne Session-Verlust.", "how_to_verify": "Setze budget_spent nahe hard_limit und starte externen Call; CORE setzt budget_paused. Danach POST /api/budget/{id}/add amount=500; Resume möglich und Session bleibt konsistent."}

## Interview-Runden
### Runde ?
**F:** Wie sieht der kleinste gültige Bauauftrag aus, den CORE akzeptieren muss (Schema, Pflichtfelder, Versionierung), und wie werden ungültige/teilweise Bauanleitungen von FORGED behandelt?
**A:** Minimaler Bauauftrag: JSON mit session_id, project_id, scope (Freitext), tech_spec (strukturiert: endpoints, db_schema, dependencies). Pflichtfelder: session_id, project_id, scope. Versionierung: Jeder Bauauftrag hat eine monoton steigende version_number. CORE validiert Schema beim Empfang und lehnt invalide Auftraege mit 400 + Fehlerbeschreibung ab.

**F:** Über welchen Transport kommen Bauanleitungen von FORGED zu CORE (HTTP/Webhook/Event/Datei), wie erfolgt AuthN/AuthZ, und wie werden Retries/Idempotenz gewährleistet?
**A:** Transport: HTTP POST Webhook von FORGED an CORE /api/core/receive-spec. Auth: HMAC-SHA256 Signatur im Header X-FORGED-Signature, Shared Secret in .env. Kein polling — FORGED pushed aktiv. Fallback: Manueller Upload ueber CORE Web-UI.

**F:** Welche 14 Phasen sind verbindlich, welche Ein-/Ausgaben (Artefakte) hat jede Phase, und welche Phasen sind manuell vs. vollautomatisch?
**A:** Alle 14 Phasen sind verbindlich. Phase 1 (Genesis): Input=Projektname, Output=Solution-Ordner. Phase 2 (FORGED): Input=Idee, Output=Tech-Spec. Phase 3 (Planung): Input=Tech-Spec, Output=Bauplan. Phase 4 (Review Plan): Input=Bauplan, Output=100%-Checkliste. Phase 5 (Build): Input=100%-Plan, Output=Code. Phase 6 (Review Code): Input=Code, Output=100%-Checkliste. Phase 7 (Deploy): Input=Code, Output=Live-URL. Phase 8 (Test Bauplan): Input=Testanforderungen, Output=Testergebnisse. Phase 9 (5ISCT): Input=Live-App, Output=Self-Test-Report. Phase 10 (Review Live): Input=Live-App, Output=100%-Checkliste. Phase 11 (JURY): Input=Live-URL, Output=4x0-Findings. Phase 12 (Doku): Input=Alles, Output=Doku-Ordner. Phase 13 (Review Doku): Input=Doku, Output=100%-Checkliste. Phase 14 (Freigabe): Automatisch bei 100%. Phasen 1-2 manuell, 3-14 automatisiert mit Gatekeeper-Checks.

**F:** Dürfen Phasen pausiert/übersprungen/teilweise erneut ausgeführt werden (z.B. Phase 3–7), und welche Regeln verhindern inkonsistente Zustände?
**A:** Phasen duerfen NICHT uebersprungen werden — das ist eine Kernregel. Pausen ja, Skip nein. Erneute Ausfuehrung: Eine Phase kann wiederholt werden (z.B. neuer Build nach Review-Feedback). Der Gatekeeper verhindert Vorwaerts-Springen: Jede Phase muss 100% erreichen bevor die naechste startet. Rollback auf vorherige Phase ist moeglich, springt aber immer zur letzte nicht-100%-Phase.

**F:** Welche täglichen Jobs führt Johannes konkret in CORE aus (Start/Review/Deploy/Rollback), und welche müssen in unter 2 Minuten erledigt sein?
**A:** Johannes nutzt CORE primaer zum Ueberwachen, nicht zum aktiven Arbeiten. Sein Daily: 1) Dashboard checken (Status aller Projekte), 2) Bei Rueckfragen antworten, 3) Freigaben pruefen. CORE arbeitet autonom — Johannes greift nur ein wenn CORE eine Frage stellt (rote Lampe/Sprechblase). Kein CLI noetig fuer Johannes.

**F:** Wie definiert Johannes 'alltagstauglich' operational (max. Build-/Testdauer, maximale Ausfallzeit, erlaubte manuelle Eingriffe pro Woche, Lern-/Wartungsaufwand)?
**A:** Alltagstauglich = Johannes kann morgens das Dashboard oeffnen, sieht sofort welche Projekte wo stehen, und muss nur bei Rueckfragen reagieren. Max Build-Dauer: 30min. Max Test-Dauer: 15min. Ausfallzeit: 0 (Service muss 24/7 laufen). Manuelle Eingriffe: Nur bei Agent-Rueckfragen und Freigabe-Bestaetigungen.

**F:** Welche Pain Points im aktuellen Prozess sind die härtesten No-Gos, die CORE zwingend lösen muss (Kontextwechsel, manuelle Checklisten, JURY-Rückfragen, Debugging)?
**A:** Haerteste Pain Points: 1) Fehlerquote durch fehlende Reviews — CORE muss IMMER durch MKB. 2) Kontext-Verlust bei langen Sessions — CORE muss alles dokumentieren. 3) Manuelle Koordination zwischen Tools — CORE automatisiert die komplette Pipeline. 4) Keine Verifikation ob Fixes wirklich umgesetzt — Python-Tool Gatekeeper loest das.

**F:** Wie soll Johannes CORE bedienen (Web-UI auf Port 5600, CLI, API, Mischung) und welche tägliche Primäransicht braucht er (Dashboard, Pipeline-Status, letzte Fehler)?
**A:** Web-UI auf core.xxbillion.ai (Port 5600). Primaer-Ansicht: Dashboard mit allen aktiven Projekten/Sessions, aktuelle Phase, Status-Ampel. Sekundaer: Session-Detail mit Timeline, Checklisten, Logs. API fuer Tool-Integration (FORGED, Genesis, JURY). Kein CLI fuer Johannes noetig, aber API fuer andere Agents.

**F:** Welche Informationen müssen in der Web-UI in Echtzeit sichtbar sein (aktuelle Phase, Laufzeit pro Schritt, Logs/Events, Gatekeeper-Abweichungen), um Entscheidungen ohne SSH/Logsuche zu treffen?
**A:** Echtzeit sichtbar: Aktuelle Phase (mit Fortschrittsbalken), aktiver Agent-Task, letzte 10 Events (Timeline), Gatekeeper-Status (gruen/rot), Review-Checkliste mit aktuellen Spalten, Kosten-Counter (Token-Verbrauch), Fehlermeldungen mit Kontext. SSE oder WebSocket fuer Live-Updates.

**F:** Wie viele parallele Builds sind erforderlich, wie werden sie priorisiert (FIFO/manuell/ressourcenbasiert), und welche Ressourcen-Isolierung ist auf VPS/Runner-Ebene nötig?
**A:** Aktuell: 1 Build gleichzeitig (FIFO). Spaeter bei Grossprojekten: Units parallel, aber jede Unit sequenziell durch Phasen. Priorisierung: Manuell durch Johannes oder automatisch nach Abhaengigkeitsgraph. Ressourcen-Limit: MAX_CONCURRENT_BUILDS=3, MAX_SESSION_COST_CENTS=500.

**F:** Welche konkreten Performance-Ziele gelten (Trigger-Antwortzeit, Build-/Test-Latenz, 24/7-Zuverlässigkeit), und was ist die Schmerzgrenze bevor Johannes abbricht?
**A:** Trigger-Antwortzeit: <5s (Webhook-Empfang bis Phase-Start). Build-Latenz: <30min fuer Standard-Projekte. Test-Latenz: <15min. 24/7-Zuverlaessigkeit: Service muss permanent laufen, auto-restart bei Crash. Graceful Degradation: Bei MKB-Ausfall → warten und retry, nicht skippen.

**F:** Welche Deploy-Ziele sind 'VPS' konkret (Provider/OS/Anzahl), wie wird authentifiziert (SSH-Keys/Vault), und welche Deploy-Strategien müssen unterstützt werden (restart, rolling, blue/green, canary)?
**A:** VPS: Hetzner Cloud, Ubuntu 22.04, 1 Server (89.167.60.201). Auth: SSH-Key (root). Deploy-Strategie: systemctl restart nach Code-Push, kein Docker (direkt Python). Deploy-Script pro Service (deploy.sh mit Pre/Post-Checks). Caddy als Reverse Proxy mit portal_auth.

**F:** Wie sieht der Recovery-Flow bei Build-/Deploy-Fehlern aus (Retry-Policy, Idempotenz pro Phase, auto-heal vs. manuelle Intervention, Eskalationspfad)?
**A:** Recovery-Flow: 1) Build-Fehler → automatisch 3 Retries mit exponential backoff. 2) Deploy-Fehler → Rollback auf letzte funktionierende Version. 3) Test-Fehler → zurueck zu Build-Phase mit Fehlerbericht. 4) Review-Fehler → Agent arbeitet Checkliste ab, neuer Review-Zyklus. Idempotenz: Jede Phase kann sicher wiederholt werden ohne Seiteneffekte.

**F:** Wie genau funktioniert Rollback (Trigger, Zielversion, Datenintegrität), bis zu welchem Punkt kann zurückgerollt werden, und wie wird das für Johannes bedienbar gemacht?
**A:** Rollback: Trigger = Deploy-Fehler oder JURY-Findings > 0. Zielversion = letzter erfolgreicher Commit (git tag). Rollback-Tiefe: Bis Phase 5 (Build). Datenintegritaet: SQLite DB wird vor Deploy gesnapshoted. Johannes sieht Rollback im Dashboard als Event in der Timeline.

**F:** Was bedeutet operativ 'Python-Gatekeeper verifiziert Code-Änderungen an exakten Zeilen' (Diff-Spezifikation, Kontext vs. Zeilennummern, Referenz, Umgang mit Reformatting/Imports/Generated Files)?
**A:** Python-Gatekeeper operativ: 1) Agent meldet 'Aenderung an Datei X, Zeile Y'. 2) Gatekeeper fuehrt git diff auf diese Datei aus. 3) Prueft ob Zeile Y tatsaechlich geaendert wurde (diff-Kontext +-3 Zeilen). 4) Ergebnis: 'Aenderung bestaetigt' oder 'Keine Aenderung erkennbar'. Variante A (Diff-Check) ist Ziel, Variante B (Vollstaendigkeits-Check) als Fallback wenn Diff nicht moeglich.

**F:** Welche Dateitypen/Repos/Scopes prüft der Gatekeeper (nur Projektfiles, auch Dependencies), und welche Regeln sind Pflicht vs. konfigurierbar (Lint, AST, Syntax, Policy)?
**A:** Gatekeeper prueft: Alle Dateien im Projekt-Repository (Python, HTML, CSS, JS, Config). Ausnahmen: .env, node_modules, __pycache__, .git. Pflichtregeln: 1) Jede Checklisten-Zeile muss eine Codezeile haben. 2) Codezeile muss existieren. 3) Aenderung muss verifizierbar sein. Dependencies (requirements.txt etc.) werden mit geprueft.

**F:** Wie ist der Workflow, wenn der Gatekeeper blockiert (UI/CLI-Feedback, vorgeschlagene Fixes, Override-Mechanismus, Audit), und wie schnell kann Johannes wieder in einen grünen Zustand kommen?
**A:** Gatekeeper-Block-Workflow: 1) UI zeigt rote Zeile in Checkliste mit Erklaerung. 2) Agent sieht welche Zeilen blockiert sind und warum. 3) Agent muss die Zeile korrigieren und erneut einreichen. 4) Kein Override-Mechanismus — 100% ist 100%. 5) Jeder Block wird in Audit-Log geschrieben. 6) Nach 5 erfolglosen Versuchen: Eskalation an Johannes.

**F:** Was sind 'MKB Reviews' genau, wie wird 'Support-the-Best' gemessen, und wie funktionieren wachsende Spalten (Wer pflegt Spalten, Versionierung, Gate-Regeln pro Spalte)?
**A:** MKB Reviews = Multi-KI-Broadcast: 100+ KIs bewerten parallel. Support-the-Best = ChatGPT konsolidiert alle Antworten, behaelt ALLE Punkte, entfernt nur Duplikate, loest Widersprueche. Wachsende Spalten: Runde 1 hat 3 Spalten (Anforderung, Codezeile, Python-Tool). Ab Runde 2 kommen 8 Spalten dazu (Codezeile, Python-Tool, 6x Controller: DEV-1/5/6/9/3/15). Jede Runde haengt Spalten AN, ueberschreibt nie.

**F:** Wie wird die MKB-Review-Oberfläche gestaltet, damit Spaltenwachstum skalierbar bleibt (Filter, Scroll, Tabs), und der Status in unter 30 Sekunden erfassbar ist?
**A:** MKB-Review-UI: Horizontales Scrolling fuer Spalten mit frozen-Header (Zeile 1 immer sichtbar). Filter: Nur offene Zeilen / Alle / Nur gruene. Farbkodierung: Gruen=100%, Rot=Fehler, Grau=noch nicht geprueft. Kompaktansicht fuer Johannes (nur Status-Zusammenfassung) und Detail-Ansicht fuer Agents.

**F:** Welche 5ISCT-Tests sind Pflicht vs. optional, wie werden sie definiert (YAML/JSON/Config), wie werden Flakes behandelt, und wann gilt ein Build trotz Instabilität als 'grün'?
**A:** 5ISCT = 5 Identity Self-Check Test. 5 verschiedene Perspektiven pruefen die eigene Arbeit. Alle 5 sind Pflicht. Definiert per Prompt-Template in CORE config. Flakes: 3 Retries, wenn trotzdem flaky → als WARN loggen, nicht als Blocker. Ergebnis: JSON-Report mit pass/fail pro Identitaet und Gesamtergebnis.

**F:** Wie werden Testergebnisse für Johannes aufbereitet (Kurzbericht <2 Minuten, Root-Cause-Hinweise, Links zu Artefakten), und gibt es einen geregelten Emergency-Bypass?
**A:** Testergebnisse fuer Johannes: 1-Zeilen-Zusammenfassung im Dashboard (z.B. '8/8 Tests bestanden' oder '2 Fehler in Phase 8'). Detail-View: Tabelle mit Test-Name, Status, Laufzeit, Fehler-Link. Root-Cause wird vom Agent analysiert und als Kurztext beigefuegt. Alles in Genesis-Ordner gespeichert.

**F:** Was triggert 'JURY nach Review Live' genau (Event/Status/Threshold), welche Inputs bekommt JURY, und welche Outputs/Entscheidungen müssen zurück nach CORE geschrieben werden?
**A:** JURY-Trigger: Automatisch wenn Review Live (Phase 10) = 100% von allen 6 Controllern. CORE sendet POST an JURY /api/jury/start mit {url, project_id, session_id}. JURY testet 10 Identitaeten x 2 Viewports = 20 Tests. Output: Findings in 4 Kategorien (Critical/Major/Minor/Info). Ziel: 4x 0 = 100%.

**F:** Welche Metriken/Signale aus dem Live-System lösen ein manuelles JURY-Review aus, und wie wird das priorisiert bzw. optional manuell angestoßen?
**A:** Kein manuelles JURY-Review — JURY wird NUR automatisch nach Review Live 100% getriggert. Wenn JURY Findings > 0: Zurueck zu Agent mit Checkliste, Python-Tool prueft Fixes, dann naechster JURY-Zyklus. Kein Live-Monitoring-Trigger — JURY testet die deployete App zum definierten Zeitpunkt.

**F:** Welche Freigabekriterien definiert CORE, wie werden sie an Stakeholder kommuniziert (Webhook/Slack/Dashboard), und was bedeutet 'Freigabe melden' technisch?
**A:** Freigabekriterien: 1) Review Plan = 100%. 2) Review Code = 100%. 3) Review Live = 100%. 4) JURY = 4x0 Fehler. 5) Review Doku = 100% (ChatGPT). Kommunikation: Genesis bekommt Webhook mit Freigabe-Status. Gruene Lampe im Genesis Dashboard. Spaeter: WhatsApp-Benachrichtigung an Johannes.

**F:** Wie werden Genesis-Ordner strukturiert (Namenskonvention, Hierarchie pro Phase), welche Inhalte sind essenziell, und was wird automatisch erzeugt vs. manuell ergänzt?
**A:** Genesis-Ordner Namenskonvention: 001-CORE.1-Genesis-Projektanlage.md, 001-CORE.3-Planung-Bauplan.md, 001-CORE.4-ReviewPlan-1-Checkliste.md etc. Punkt = Ebenensprung. Zahl = chronologisch. Pflicht-Dokumente: Bauplan, Checklisten (alle Runden), Test-Reports, JURY-Reports, Changelog, Architektur-Doku.

**F:** Welche Genesis-Inhalte müssen später sofort such-/filterbar sein (Build-Logs, Gatekeeper-Reports, Testreports, JURY-Protokolle), und über welche UI/CLI erfolgt der Zugriff?
**A:** Such-/filterbar: Build-Logs (nach Datum, Phase), Gatekeeper-Reports (nach Status gruen/rot), Test-Reports (nach pass/fail), JURY-Protokolle (nach Severity), Checklisten (nach Runde, Controller). SQLite DB indiziert alle Dokumente mit Metadaten. Web-UI hat Suchfeld mit Filteroptionen.

**F:** Welche Archivierungs- und Aufräumstrategie gilt für Genesis (Retention, Größenlimits, Backups), und wie wird Nachvollziehbarkeit über Monate sichergestellt?
**A:** Archivierung: Keine Loeschung — alles bleibt erhalten. Retention: Unbegrenzt. Backups: Taeglicher SQLite-Snapshot in /opt/xxbillion-portal/data/backups/. Genesis-Ordner sind Teil des regulaeren Server-Backups. Nachvollziehbarkeit: Jedes Dokument hat Timestamp, Source-Tool, Session-ID.

**F:** Welche Auth- und Rechteanforderungen gibt es (Rollen, SSO/API-Keys), welche Aktionen müssen auditierbar sein (wer hat was wann freigegeben/übersteuert), und welche Audit-Logs sind zwingend?
**A:** Auth: Portal-Login mit 2FA (Caddy forward_auth). API: X-MKB-Key Header oder Bearer Token fuer Service-zu-Service. Rollen: Aktuell nur Johannes (Admin). Spaeter: Read-Only fuer Stakeholder. Auditierbar: Jede Phase-Transition, Deploy, Review-Ergebnis, Gatekeeper-Entscheidung wird in Timeline geloggt.

**F:** Wie werden Secrets (Claude API-Keys, VPS-Creds, Webhooks) verwaltet (Env/Vault/Key-Store), rotiert und gegen Leak abgesichert?
**A:** Secrets: .env Dateien pro Service (NIE hardcoded). Claude API-Key in .env. VPS SSH-Key auf Mac gespeichert. Webhook-Secrets als Shared Secrets in .env beider Services. Rotation: Manuell bei Verdacht. Leak-Schutz: .env in .gitignore, .rsync-exclude bei Deploy.

**F:** Welche Sicherheitsmaßnahmen schützen core.xxbillion.ai und Port 5600 (Auth, Netzwerk, Rate-Limits), und welche Daten dürfen lokal vs. nur in der Cloud verarbeitet/gespeichert werden?
**A:** Schutz: Caddy mit portal_auth (forward_auth an Portal). HTTPS only (Caddy TLS). Rate-Limit: 200/min (MKB API). Port 5600 nur ueber Caddy erreichbar (nicht direkt). Daten die NICHT nach aussen duerfen: API-Keys, SSH-Keys, interne Session-IDs. Logs enthalten keine Secrets.

**F:** Welche Benachrichtigungen braucht Johannes (kritischer Alarm vs. stiller Log), über welche Kanäle (Slack/Email/Push), und welche Events sind notification-worthy (Build fail, Deploy fail, Gatekeeper block, JURY Ergebnis)?
**A:** Benachrichtigungen: Kritisch (Build-Fehler, Gatekeeper-Block nach 5 Versuchen, Service-Down) → Rote Lampe im Genesis Dashboard + spaeter WhatsApp. Info (Phase abgeschlossen, Review gestartet) → Timeline-Event im Dashboard. Stille Logs: Debug-Infos, Token-Verbrauch, Performance-Metriken.

**F:** Welche Monitoring/Alerting-Anforderungen gelten im Produktivbetrieb (Dashboards, Prometheus o.ä.), und welche KPIs sollen dauerhaft getrackt werden (Erfolgsrate, Dauer pro Phase, Wiederholungen)?
**A:** Monitoring: Flask-internes Logging (RotatingFileHandler). Health-Endpoint GET /health. Spaeter: Prometheus-Metrics via /metrics. KPIs: Build-Erfolgsrate, Durchschnittliche Review-Runden bis 100%, JURY-Zyklen bis 4x0, Kosten pro Projekt (Token-Verbrauch). Dashboard zeigt KPIs pro Solution.

**F:** Welche Daten persistiert CORE (z.B. in SQLite), wie robust ist das bei Neustarts/Concurrency, und welche Zustände müssen für Traceability und Recovery zwingend gespeichert werden?
**A:** Persistenz: SQLite in /opt/xxbillion-core/data/core.db. Tabellen: sessions, phases, checklists, checklist_items, gatekeeper_results, documents. WAL-Modus fuer Concurrency. Bei Restart: Laufende Session wird in 'paused' gesetzt, kann resumed werden. Kritische Zustaende (aktuelle Phase, Checklisten) muessen crash-sicher sein.

**F:** Welche Integrationen mit bestehenden Tools sind zwingend (Git/CI/CD/IDE/Tickets/ChatOps), und was ersetzt CORE konkret in Johannes’ Workflow?
**A:** Integrationen: Git (für Diff-Check im Gatekeeper), Genesis (Webhook fuer Status-Updates), MKB (API fuer Reviews), FORGED (Webhook fuer Bauanleitungen), JURY (API fuer Auto-Trigger). CORE ersetzt: Manuelles Copy-Paste zwischen Tools, manuelle Review-Koordination, manuelles Deployment.

**F:** Wie wird die Integration mit der Claude API gehandhabt (welche Aufgaben/Phasen, Kostenkontrolle/Rate-Limits, Fallback bei Ausfall), ohne den Build-Prozess zu blockieren?
**A:** Claude API: Genutzt fuer Phase 3 (Bauplan erstellen), Phase 5 (Code schreiben), Phase 8-9 (Tests), Phase 12 (Doku). Model: claude-sonnet-4-20250514 (Standard), claude-opus-4-20250514 (fuer komplexe Architektur). Kostenkontrolle: MAX_SESSION_COST_CENTS=500 pro Session. Fallback: Bei Rate-Limit → exponential backoff + retry.

**F:** Welche Fehlerarten sollen automatisch kategorisiert und priorisiert werden, und welche Informationen braucht Johannes zuerst, um einen Fail in unter 2 Minuten einordnen zu können?
**A:** Fehler-Kategorien: 1) Build-Error (Syntax, Import, Compile), 2) Test-Error (Assertion, Timeout), 3) Deploy-Error (Port conflict, Permission), 4) Review-Error (Checklisten-Fehler), 5) Gatekeeper-Error (Diff nicht verifizierbar). Johannes sieht: Kategorie, betroffene Datei/Zeile, Agent-Erklaerung, vorgeschlagener Fix. Alles in Timeline.

**F:** Welche Devices/Browser nutzt Johannes primär, und gibt es Anforderungen an Mobile/Offline-Fähigkeit bzw. lokale Ausführung ohne Cloud-Abhängigkeit?
**A:** Johannes nutzt primaer MacBook Pro mit Chrome. Mobile ist Nice-to-have aber kein Muss. Kein Offline-Bedarf — alles laeuft auf VPS. Lokale Ausfuehrung: Nur Claude Code Terminal fuer direkte Agent-Interaktion. Web-UI muss responsive sein (Tablet-tauglich), aber Mobile-First ist nicht erforderlich.

### Runde ?
**F:** Wie wird in Phase 3 der Bauplan konkret aus der tech_spec generiert (Prompt-Template, Input/Output-Beispiel, Validierung gegen Tech-Spec), und wie verhindert CORE inkonsistente Baupläne bei unvollständiger/ambiger tech_spec? Welche Qualitätsmetriken gelten (z.B. Endpoint-Abdeckung)?
**A:** Phase 3 Bauplan: CORE nimmt tech_spec und fuettert sie in Claude API mit einem Prompt-Template das sagt: 'Erstelle einen detaillierten technischen Bauplan mit Dateistruktur, Endpoints, DB-Schema, Abhaengigkeiten, Reihenfolge der Implementierung.' Output: Strukturiertes JSON/Markdown mit allen Dateien die erstellt/geaendert werden muessen. Validierung: Bauplan wird gegen tech_spec geprueft — jeder Endpoint und jedes DB-Feld aus der Spec muss im Plan vorkommen.

**F:** Wie wird Rollback bei Datenbank-Migrationen umgesetzt (Down-Scripts, DB-Snapshot-Strategie, versioniertes Schema), und wie wird Datenverlust bei fehlgeschlagenen Migrationen verhindert?
**A:** DB-Migrationen: SQLite hat keine klassischen Migrationen. Strategie: 1) Pre-Deploy: cp db.db db.db.backup_$(date). 2) Schema-Aenderungen via ALTER TABLE in init_db(). 3) Bei Fehler: Backup wiederherstellen. Kein Down-Script noetig da SQLite-Aenderungen idempotent (CREATE TABLE IF NOT EXISTS, ALTER TABLE ADD COLUMN IF NOT EXISTS).

**F:** Wie schützt Phase 7 (Deploy) stateful Daten (SQLite, Uploads, Sessions) während Restart-Deployments: exaktes Pre-Deploy-Backup/Snapshot-Timing, Idempotenz, und verpflichtende Post-Deploy-Checks (Health, DB-Integrität)?
**A:** Stateful Data Schutz: 1) Pre-Deploy: SQLite DB wird kopiert (cp *.db *.db.pre-deploy). 2) Uploads-Ordner wird NIE geloescht bei Deploy. 3) Sessions: Flask-Sessions in Cookies (nicht server-seitig), also kein Verlust. 4) Deploy-Script prueft ob DB-Datei existiert BEVOR restart. 5) Bei Fehler: Automatischer Rollback auf .pre-deploy Backup.

**F:** Wie geht der Gatekeeper mit nicht-deterministischen Änderungen um (generierte Files, Timestamps, randomisierte Testdaten): Ignore/Whitelist-Regeln, Schutz vor Missbrauch, und Auditierbarkeit der Ausnahmen?
**A:** Nicht-deterministische Aenderungen: Gatekeeper hat eine Whitelist fuer bekannte dynamische Patterns: Timestamps (*.log, migration timestamps), generierte IDs (session_*, uuid), Build-Artefakte (__pycache__, .pyc). Config: gatekeeper_ignore.json definiert Patterns die der Gatekeeper nicht prueft. Fuer den Rest gilt: Wenn eine Aenderung behauptet wird, muss sie im Diff sichtbar sein.

**F:** Wie verhindert der Python-Gatekeeper Race Conditions, wenn zwei Agents zeitgleich dieselben Dateien ändern: Locking/Queueing, konsistente Referenzen trotz Refactor/Formatting, und ggf. AST-basierte statt zeilenbasierte Verifikation?
**A:** Race Conditions: Aktuell kein Problem da MAX_CONCURRENT_BUILDS=1 (sequenziell). Bei spaeterer Parallelisierung: File-Level Locking via fcntl.flock() auf dem Git-Repo. Jeder Build arbeitet in einem eigenen Branch. Merge erst nach Gatekeeper-Freigabe. Referenz: Immer HEAD des Build-Branches.

**F:** Wie werden reine Formatierungsänderungen (Black/isort/PEP8) in Gatekeeper-Checks behandelt, damit semantisch identischer Code nicht blockiert: Whitespace-Ignoring, Semantic-Diff/AST-Äquivalenz, Kontext-Regeln?
**A:** Formatierungsaenderungen: Gatekeeper-Config hat semantic_only=True Option. Black/isort/PEP8 Aenderungen werden als 'formatting' taggt und NICHT als inhaltliche Aenderung gewertet. Der Gatekeeper prueft: Hat sich die AST (Abstract Syntax Tree) geaendert? Wenn nein → nur Formatierung, wird akzeptiert aber nicht als Fix gezaehlt.

**F:** Wie wird die '100%-Checkliste' in Phase 4 technisch validiert (Schema vs. Regeln aus Tech-Spec), und wie wird sichergestellt, dass jede neu hinzugefügte MKB-Spalte in der Checkliste abgebildet ist?
**A:** 100%-Checkliste Validierung: Checkliste hat Schema {id, requirement, source_phase, code_line, python_tool_status, controller_results[]}. Validierung: 1) Jede Anforderung aus tech_spec muss als Zeile existieren. 2) Neue Anforderungen die waehrend Review entstehen werden als neue Zeilen hinzugefuegt. 3) Scope darf NIE erweitert werden — nur bestehende Anforderungen + Fehler die durch Aenderungen entstehen.

**F:** Wie werden Cross-Referenzen zwischen Genesis-Dokumenten gepflegt/validiert (z.B. Zeilennummern im Bauplan): Auto-Update vs. harter Fail 'Referenz nicht gefunden', und wie wird das robust gegen Refactors?
**A:** Cross-Referenzen: Soft-Reference System. Dokumente referenzieren sich ueber {doc_type, phase, round}. Beispiel: Checkliste Phase 6 Runde 2 referenziert Bauplan Phase 3. Wenn referenziertes Dokument sich aendert: WARN im Log, aber kein harter Fail. Zeilennummern in Bauplan sind NICHT referenziert da sie sich aendern — statt Zeilennummern wird Funktionsname/Endpoint referenziert.

**F:** Wie wird der Übergang von 'Review Live = 100%' zum JURY-Trigger synchronisiert: müssen alle 6 Controller gleichzeitig 100% haben oder einzeln, wie werden Timeouts/Drift gehandhabt, und wie wird Deadlock vermieden?
**A:** JURY-Trigger Synchronisation: ALLE 6 Controller muessen 100% haben bei ALLEN Zeilen. Pruefung: Python-Tool iteriert ueber Checkliste, zaehlt Zeilen wo alle 6 Controller-Spalten = '100%'. Erst wenn count_green == total_rows → Status 'review_live_complete' → automatischer JURY-Trigger. Zeitversatz zwischen Controllern ist OK — es wird gewartet bis der letzte fertig ist.

**F:** Wie wird mit False Positives/Negatives aus JURY umgegangen: gibt es einen dokumentierten manuellen Override-Pfad (z.B. 'Won’t Fix'), wie bleibt die 4x0-Regel konsistent, und ab welcher Override-Häufigkeit eskaliert CORE?
**A:** JURY False Positives: Aus dem V2-Report gelernt: 47 JURY-Bugs identifiziert (Kontrast-Checker pauschal, SPA-Navigation, Scope-Mismatch, Performance-Schwellenwert). Handling: Agent analysiert JURY-Finding und klassifiziert als KORRIGIERT/KEIN_FEHLER/JURY_BUG. JURY_BUG = kein Code-Fix noetig, wird in JURY-Verbesserungsliste aufgenommen. KEIN_FEHLER braucht Begruendung. Die 4x0-Regel gilt nur fuer echte Fehler, nicht JURY-Bugs.

**F:** Wie werden Konflikte zwischen Controller-Entscheidungen in wachsenden MKB-Review-Spalten aufgelöst (Protokoll: Mehrheit/Seniority/Schiedsrichter), und wie wird das in UI + Audit-Log transparent gemacht?
**A:** Controller-Konflikte: Es gibt KEINE Konflikte im klassischen Sinne. Jeder Controller bewertet jede Zeile binaer: 100% oder Fehlerbeschreibung. Wenn 5/6 sagen 100% und 1 sagt Fehler → Zeile ist NICHT bestanden. Es braucht 6/6 = 100%. Kein Mehrheitsentscheid, kein Schiedsrichter. Der eine Controller der Fehler sieht hat Recht bis der Agent es gefixt hat.

**F:** Wie werden 100+ parallele KI-Calls im MKB-Review technisch und kostenseitig gehandhabt (Rate-Limits, Queueing/Backoff, Key-Management), und welche erwarteten Kosten entstehen pro Review-Runde?
**A:** 100+ KI-Calls: Das ist ein MKB-internes Problem, nicht CORE. CORE sendet Review-Request an MKB Bridge API. MKB handhabt intern: Concurrent-Limits pro Provider, Queueing, Rate-Limiting (200/min). CORE wartet auf Ergebnis (polling oder webhook). Kosten: Ca. 5-15 USD pro voller Review-Runde (100 KIs). CORE trackt Kosten pro Session.

**F:** Wie wird die Kostenobergrenze (MAX_SESSION_COST_CENTS=500) in Echtzeit durchgesetzt: Abbruch laufender API-Calls vs. Budget-Reservierung pro Phase, Overshoot-Schutz bei Streaming, und Reaktion wenn während Phase 5 überschritten wird?
**A:** Kostenobergrenze: Circuit-Breaker in CORE. Vor jedem Claude API-Call: check_budget(session_id). Wenn verbrauchte Tokens + geschaetzte Kosten > MAX_SESSION_COST → Session wird pausiert mit Status 'budget_exceeded'. Johannes entscheidet: Budget erhoehen oder Session abbrechen. Laufende API-Calls werden NICHT abgebrochen (zu teuer/komplex), stattdessen wird der naechste Call blockiert.

**F:** Wie ist der Retry-Mechanismus bei Claude-Rate-Limits definiert (Backoff-Parameter, Max-Retries), welcher Session/Phase-Status wird währenddessen gesetzt, und gibt es ein Timeout für 'waiting_for_api'?
**A:** Claude Rate-Limit Retry: Exponential backoff starting at 2s, doubling each retry, max 5 retries, max wait 60s. Waehrend Retry: Phase-Status bleibt 'running', Sub-Status 'api_retry'. Nach max retries: Phase-Status → 'api_error', Agent meldet Problem. Session wird NICHT automatisch abgebrochen — Agent kann retry manuell oder automatisch nach Cooldown.

**F:** Wie wird die Isolation paralleler Builds (MAX_CONCURRENT_BUILDS=3) technisch umgesetzt (Container/User/Instanzen), wie werden Port-Konflikte verhindert, und welche Daten sind explizit geteilt vs. strikt isoliert?
**A:** Isolation paralleler Builds: Kein Container — stattdessen: Separate Working Directories pro Session (/opt/xxbillion-core/workspaces/session_xyz/). Port-Management: Jeder Build benutzt einen dynamischen Port aus einem Pool (5601-5620). Process-Isolation: Separate Python-Prozesse per subprocess. Cleanup: Workspace wird nach Freigabe geloescht.

**F:** Wie wird die zustandslose/async Validierung von Bauanleitungen/Checks umgesetzt, wenn FORGED Änderungen parallel oder schnell hintereinander meldet: Dedup/Run-ID, Zuordnung von Checklist-Item-ID zu Commit-SHA, Diff-Replay und 'keine Verifikation übersehen'?
**A:** Async Validierung: CORE hat eine Inbound-Queue (SQLite-basiert). Jede eingehende Bauanleitung bekommt eine Queue-ID und wird sequenziell abgearbeitet. Wenn FORGED schnell hintereinander sendet: Nur die letzte Version zaehlt (Latest-Wins fuer gleiche project_id). Deduplizierung ueber Idempotency-Key im Header.

**F:** Was passiert beim Pausieren/Stoppen einer Session: wie werden laufende Tasks (API-Calls, Deploy, JURY) zuverlässig gecancelt, welche Zustände müssen atomar in SQLite persistiert werden, und wie funktioniert ein sicheres Resume nach Stunden/Tagen?
**A:** Session Pause/Stop: 1) Status → 'pausing'. 2) Laufende API-Calls: Werden zu Ende gefuehrt (nicht gecancelt — Kosten bereits entstanden). 3) Laufende Deploys: Werden zu Ende gefuehrt (Rollback waere schlimmer). 4) JURY-Tests: JURY wird informiert per Cancel-API. 5) Alle bisherigen Ergebnisse bleiben in DB gespeichert. 6) Resume: Startet bei der Phase wo pausiert wurde.

**F:** Wie erkennt CORE Name-Kollisionen zwischen eingehender tech_spec (Endpunkte/DB/Dependencies) und bereits existierenden Portal-Routes/PortalDB: benötigter API-Katalog pro Solution, Clash-Detection, und Rückmeldung an FORGED/Johannes?
**A:** Name-Kollisionen: CORE prueft beim Empfang einer tech_spec NICHT gegen andere Services. Jeder Service hat seinen eigenen Port und eigene DB. Kollisionen bei Caddy-Routes werden beim Deploy erkannt (Caddy wirft Fehler). Fuer DB-Namen: Jeder Service hat eigene SQLite-Datei. Endpoint-Kollisionen innerhalb eines Services: Wird im Code-Review (Phase 6) erkannt.

**F:** Sind die aktuellen Limits (500 Cent/Session, 3 parallele Builds) realistisch für 14-Phasen-Projekte mit mehreren Review- und JURY-Zyklen: wann pausiert CORE aus Kostengründen, wer wird benachrichtigt, und kann Johannes Budget erhöhen ohne Build-Verlust?
**A:** Limits-Realismus: 500 Cent (5 USD) pro Session ist fuer einen einzelnen Build-Zyklus realistisch (1x Claude Sonnet fuer Plan + Build + Tests = ca. 2-3 USD). Fuer den vollen 14-Phasen-Prozess mit mehreren Review-Runden: Koennten 10-20 USD werden. Loesung: MAX_SESSION_COST ist pro Phase, nicht pro Gesamtprozess. Oder: Budget wird pro Projekt gesetzt, nicht pro Session. 3 parallele Builds: Aktuell nicht noetig (1 reicht), Limit ist Zukunftssicherung.

### Runde ?
**F:** Wie definiert und erzwingt CORE das Budget über einen kompletten 14-Phasen-Prozess hinweg (pro Phase, pro Session, pro Projekt), inklusive Warn-/Pause-Schwellen, UI-Flow für atomare Budget-Erhöhung während einer laufenden Session, und Overshoot-Schutz bei Streaming-Responses, damit z.B. ein JURY-Zyklus nicht unerwartet mitten drin blockiert?
**A:** Budget-Management: 3 Ebenen. 1) Pro Phase: Soft-Limit basierend auf Phase-Typ (Plan=200ct, Build=300ct, Test=100ct). Bei Ueberschreitung: WARN + weiter. 2) Pro Session: MAX_SESSION_COST_CENTS=500. Hard-Pause bei Erreichen. 3) Pro Projekt: Summe aller Sessions, nur Monitoring (kein Hard-Limit). UI: Budget-Balken im Session-Detail, gelb ab 80%, rot ab 95%. Johannes kann per 'Budget erhoehen' Button +500ct freischalten. Jeder API-Call loggt Token-Count und Kosten in DB BEVOR Ergebnis verarbeitet wird.

**F:** Wie stellt CORE atomare Phase-Transitions sicher, wenn sowohl SQLite-Status als auch Filesystem-Artefakte (Bauplan, Checklisten, Reports) geschrieben werden: welche Transaktions-/Journal-Strategie (WAL, Outbox/Inbox, Two-Phase-Commit, Idempotency-Keys) verhindert nach Crash/Rollback einen 'halbfertigen' Zustand?
**A:** Atomare Phase-Transitions: SQLite-Transaction wrapping: BEGIN → Status-Update + Artefakt-Pfad in DB → COMMIT. Filesystem-Writes passieren VOR dem DB-Commit. Pattern: 1) Artefakt in /tmp schreiben. 2) Validieren (Datei existiert, nicht leer, JSON parseable). 3) mv /tmp/artefakt → Zielordner. 4) DB-Transaction: phase_status='completed', artifact_path=Zielordner. Bei Fehler: /tmp-Datei bleibt, DB-Status unveraendert. Journal-Mode: WAL fuer Crash-Safety.

**F:** Wie definiert CORE '100%' für Review-Phasen technisch: ist es strikt 6/6 Controller pro Checklisten-Zeile, wie werden mehrere Review-Runden aggregiert (zählt nur die letzte Runde oder ein akkumuliertes Best-of), und welche Guardrails verhindern Endlosschleifen durch chronisch blockierende Controller (Eskalation/Rotation/Timeout, ohne Mehrheitsentscheid)?
**A:** 100% Definition: Strikt 6/6 Controller = '100%' pro Zeile, UND alle Zeilen muessen 100% sein. Aggregation: NUR die letzte Runde zaehlt. Gruende: 1) Wenn Zeile in Runde 2 gefixt wurde, zaehlt nur Runde-2-Ergebnis. 2) Neue Zeilen die durch Fixes entstehen muessen auch 100% erreichen. 3) 'Bereits gruen' Zeilen (6/6 in Vorrunde) werden in Folgerunden NICHT mehr abgefragt — ihr Status bleibt '100%'. Formel: total_green = count(rows where latest_round_all_6_are_100) + count(rows_locked_green_from_previous). 100% = total_green == total_rows.

**F:** Wie macht CORE Gatekeeper-Verifikationsreferenzen refactor-stabil (statt Zeilennummern): nutzt ihr AST-basierte Anker (file + symbol + node-hash), Diff-Kontext-Hashes oder Funktions-/Methoden-Scope-Anker, und wie wird eine Checklisten-Zeile über Phasen hinweg eindeutig an das korrekte Code-Fragment gebunden?
**A:** Refactor-stabile Referenzen: Funktionsname + Dateiname als Primaer-Anker. Format: 'file:path/to/file.py::function_name' oder 'file:path/to/file.py::class.method'. Kein Zeilennummer-basierter Anker. Gatekeeper prueft: 1) Existiert die Funktion in der Datei? 2) Hat sich der Funktions-Body geaendert (AST-Diff)? 3) Fallback bei nicht-Funktions-Aenderungen (z.B. Config): Datei + Kontext-Suche (3 Zeilen um die gemeldete Stelle). Hash: SHA256 des Funktions-Bodies vor und nach Aenderung.

**F:** Wie wird die Durchsetzung von MAX_SESSION_COST_CENTS bei Streaming-API-Calls operational umgesetzt (laufendes Token-/Cost-Tracking, Reservierung vor Call, Reaktion bei Überschreitung: sofort abbrechen vs. nach Call-Ende), und wie wird verhindert, dass bereits gestartete Schritte unkontrolliert über das Budget hinauslaufen?
**A:** Streaming-Cost-Tracking: Claude SDK liefert Token-Count im Response-Header/Body (usage.input_tokens, usage.output_tokens). CORE trackt nach JEDEM API-Call: session_cost += (input * input_price + output * output_price). Reservierung: VOR jedem Call wird max_tokens * output_price als Reservation gebucht. Nach Call: Reservation durch echte Kosten ersetzt. Bei Ueberschreitung: Naechster Call wird blockiert, Status → 'budget_pause'. Kein Mid-Stream-Abbruch (zu riskant/teuer).

**F:** Welche Vorbedingungen und Persistenzregeln müssen erfüllt sein, bevor eine Phase als '100%' in SQLite gespeichert wird (z.B. benötigte Artefakte, Gatekeeper-Reports, Checklisten-Status pro Runde), und wie wird verhindert, dass ein früher erfolgreicher Durchlauf später durch neue Anforderungen/Zeilen inkonsistent wird?
**A:** Phase-Completion Vorbedingungen: Tabelle phase_requirements definiert pro Phase: required_artifacts (Liste von Dateitypen), required_status (z.B. gatekeeper_all_green=True), required_checklists (Anzahl Zeilen > 0 mit Status 100%). Vor phase_status='completed' wird validate_phase_completion(session_id, phase) aufgerufen. Prueft: 1) Alle required_artifacts existieren als Dateien. 2) Gatekeeper-Report existiert und ist 100% gruen. 3) Alle Checklisten-Zeilen haben Status in letzter Runde. 4) Kein offener Error in phase_errors Tabelle. Erst wenn alle Checks bestanden → DB-Update.

**F:** Wie garantiert CORE die Korrektheit des Übergangs von Phase 10 (Review Live) zu Phase 11 (JURY) bei asynchroner JURY-Ausführung: welche Statusmaschine (requested/running/succeeded/failed), Webhook-Idempotenz, Timeouts und Reconciliation verhindern ein fälschliches '100%' trotz späterer JURY-Fehler oder verspäteter Findings?
**A:** Phase 10→11 Statusmaschine: Phase 10 Status-Flow: review_live_running → review_live_round_N → review_live_complete. Bei 'complete': CORE setzt jury_status='requested' in sessions Tabelle. Dann POST /api/jury/start an JURY-Service. JURY antwortet mit jury_session_id. CORE setzt jury_status='running'. CORE pollt JURY /api/jury/status/{id} alle 60s ODER empfaengt Webhook. Moegliche JURY-Statusse: running → completed_pass (4x0) | completed_fail (findings > 0). Bei completed_pass: Phase 11 = 100%, weiter zu Phase 12. Bei completed_fail: Findings als neue Checklisten-Zeilen, zurueck zu Agent, Gatekeeper prueft, naechster JURY-Zyklus. Timeout: 30min. Bei Timeout: jury_status='timeout', retry nach 5min.

### Runde ?
**F:** Welches verbindliche Git-Repository- und Branching-Modell ist pro CORE-Session der „Source of Truth“ (Monorepo vs. Multi-Repo, session-Branch je Session, protected main/master, Tagging-Regeln für Deploy-Punkte), wer erzeugt Commits/Tags (Agent vs. CORE), und wie werden Rebase/Force-Push so gehandhabt, dass Deploy-Reproduzierbarkeit, Diff-/Rollback-Logik und „Safe Resume“ nach Pause/Neustart garantiert sind?
**A:** Git-Modell: Multi-Repo (jeder Service hat eigenes Repo/Verzeichnis auf VPS). Kein klassisches Branching fuer CORE-Sessions — stattdessen: Alle Aenderungen direkt auf main (VPS hat kein Push/Pull zu GitHub). Source of Truth = Dateisystem auf VPS (/opt/xxbillion-core/). Backups via cp + Timestamp. Gatekeeper referenziert git diff HEAD~1 fuer Verifikation. Tags: Nach jeder Freigabe (Phase 14) wird ein git tag v{number} gesetzt. Protected Branch: Nicht relevant da Single-Developer (Agent) auf VPS.

**F:** Wie bindet CORE/Python-Gatekeeper jedes Checklisten-Item eindeutig und refactor-stabil an eine konkrete Git-Referenz (Commit-SHA/Ref) und ein Code-Fragment (z.B. file+symbol+AST-hash oder diff-kontext-hash), sodass AST/Diff-Verifikation, Audit-Trail und spätere Replays/Rollbacks zuverlässig funktionieren?
**A:** Checklisten-Item Bindung: Jedes Item hat: {file_path, symbol_ref, commit_before, commit_after}. symbol_ref = 'datei.py::funktionsname' oder 'datei.py::Klasse.methode'. Gatekeeper prueft: 1) git diff commit_before..commit_after -- file_path | grep symbol_ref. 2) AST-Parse der Datei, Extraktion des Symbol-Bodies, SHA256-Hash. 3) Hash-before != Hash-after = Aenderung bestaetigt. Bei Refactoring (Rename): Gatekeeper erkennt Rename via git diff --follow und aktualisiert symbol_ref automatisch.

**F:** Wie ist die Build- und Runtime-Isolation auf dem VPS pro Solution/Session verbindlich definiert (Python-Version-Pinning, venv/pyenv/poetry/pip, Dependency-Caching, Clean-Build-Flag), wo laufen Builds (direkt VPS vs. dedizierte Runner), und wie werden Build-Artefakte pro Session isoliert, versioniert und wiederverwendet, inkl. Schutz vor Ressourcenkonflikten bei parallelen Builds (Ports/CPU/DB)?
**A:** Build/Runtime Isolation: Python 3.10 (System-Python auf Ubuntu 22.04). Kein venv pro Session (zu viel Overhead fuer Flask-Monolithen). Dependencies: requirements.txt, pip install bei Deploy. Clean-Build: Nicht noetig (Python ist interpretiert, kein Compile-Cache). Dependency-Caching: pip cache auf VPS. Pro Solution: Eigenes Verzeichnis (/opt/xxbillion-{service}/), eigene requirements.txt, eigener systemd Service. Keine Cross-Contamination da separate Prozesse.

**F:** Wie werden Deploy-Ziele und der Service-Lifecycle auf VPS-Ebene technisch spezifiziert (systemd-Unit-Template: Name, WorkingDirectory, User/Permissions, EnvironmentFile, ExecStart/Pre/Post, Restart-Policy, Log-Pfade, Port-Binding, Healthcheck), sodass CORE Deployments deterministisch steuern und prüfen kann?
**A:** systemd-Unit-Template: [Unit] Description=XXBILLION {SERVICE} After=network.target [Service] Type=simple WorkingDirectory=/opt/xxbillion-{service} EnvironmentFile=/opt/xxbillion-{service}/.env ExecStart=/usr/bin/python3 app.py Restart=always RestartSec=3 [Install] WantedBy=multi-user.target. User: root (vereinfacht, spaeter eigener User). Health-Check: GET /health nach Restart, 3 Retries mit 2s Delay. Caddy-Route: {service}.xxbillion.ai -> localhost:{port}.

**F:** Wie wird ein Deploy als atomare Transaction über Code + Config (z.B. Caddy) + Umgebungsvariablen umgesetzt, und welcher exakte automatische Rollback-Flow wird bei Fehlern ausgelöst (Trigger, Zielversion/Tag, Restore von Config/Env/DB-Snapshot, Timeline-Logging), sodass kein „halb-deployter“ Zustand verbleibt?
**A:** Atomarer Deploy: 1) Pre-Deploy: cp -r /opt/xxbillion-{service} /opt/xxbillion-{service}.rollback. 2) Code-Update: rsync oder direkte Datei-Aenderung. 3) Config-Check: python3 -c 'import app' (Syntax-Pruefung). 4) systemctl restart. 5) Health-Check: curl localhost:{port}/health (3 Versuche, 2s Delay). 6) Bei Health-Fail: Automatischer Rollback = mv /opt/xxbillion-{service}.rollback /opt/xxbillion-{service} + systemctl restart. Caddy-Aenderungen: Separat, manuell geprueft, caddy reload. Env-Vars: .env wird NIE automatisch ueberschrieben (in .rsync-exclude).