toadapt-validation-and-qa

name

toadapt-validation-and-qa

description

Validierung und Qualitätssicherung im ToAdapt-Repo: Was als Evidenz für eine Änderung zählt (CI < Smoke < Guardrail-Regression < Teacher-Alignment), Landkarte aller pytest-Tests, das Golden-Case-Inventar (alpes-bank-genai-001 + Rubric-JSONs als kalibrierte Artefakte), Copy-Paste-Muster zum Ergänzen neuer Tests, CI-Anatomie inkl. PYTHONPATH-Falle, Akzeptanz-Schwellen. Lade diese Skill, wenn du: (a) vor einem Commit/Push wissen willst, welche Prüfungen Pflicht sind und wie man sie lokal ausführt; (b) einen neuen Test schreiben willst (TestClient, Mongo-Env wegräumen, LLM mocken, Stores auf tmp_path patchen); (c) den Judge/Evaluator/Prompts geändert hast und wissen musst, welcher Nachweis akzeptiert wird; (d) Tests fehlschlagen (z. B. ModuleNotFoundError backend, 2-Sekunden-Hänger, 90-Tests-Baseline verletzt); (e) den Golden Case oder eine Rubric-JSON anfassen willst; (f) fragst "reicht dieser Beweis?" oder "welcher Test deckt X ab?". Keywords: pytest, ruff, CI, ci.yml, TestClient, monkeypatch, Golden Case, Rubric, Alignment, Pearson, MAE, Evidenz, Regression, QA, Testabdeckung.

ToAdapt — Validation & QA

Diese Skill definiert, was in diesem Repo als Beweis gilt, dass eine Änderung funktioniert — und wie man diesen Beweis erbringt.

Wann diese Skill NICHT gilt

Deine Frage	Richtige Skill
"Darf ich das überhaupt ändern? Welches Gate gilt?"	toadapt-change-control
"Warum schlägt X in Produktion fehl?" (401/503/429/Mongo/CORS)	toadapt-debugging-playbook
"Wie starte ich Backend/Frontend lokal, wie deploye ich?"	toadapt-run-and-operate
"Wie baue ich die Umgebung (venv, npm) von Null auf?"	toadapt-build-and-env
"Was bedeutet Bloom/TP/Canvas/Scaffolding fachlich?"	bwl-scaffolding-reference
"Wie messe ich Laufzeitverhalten (Diagnostics, Logs)?"	toadapt-diagnostics-and-tooling
"Wie verbessere ich konkret das q4-Judge-Alignment?"	toadapt-judge-alignment-campaign
"Welche Env-Variable steuert was?"	toadapt-config-and-flags

---

1. Evidenz-Staffelung: Was zählt als Beweis?

Von schwach nach stark. Wähle die Stufe nach dem, was du geändert hast — NICHT nach dem, was am bequemsten ist.

Stufe	Evidenz	Reicht für
1	CI grün (ruff + pytest; eslint + tsc + next build)	Refactorings ohne Verhaltensänderung, Doku, Tests selbst
2	Lokaler Smoke-Test (Backend starten, Endpoint real anfragen)	API-Routen-Änderungen, Auth-/Rate-Limit-Änderungen, neue Endpoints
3	Guardrail-Regressionstests (gezielte pytest-Fälle für neue verbotene/erlaubte Muster)	Änderungen an backend/agents/orchestrator.py (Guardrails, Prompts, Routing), an backend/evaluator/formative_feedback.py (Denkanstöße laufen durch guardrail_check) und am Feedback-Sanitizing des Evaluators
3b	Tutor-Eval-Regressionsvergleich (NAACL-Dimensionen vorher/nachher via scripts/evaluate_tutor_responses.py)	Studierendensichtbare Prompt-Änderungen an Agenten- oder Formative-Feedback-Prompts (Klasse A). Durchführung und Akzeptanzkriterien: toadapt-tutor-response-evaluation
4	Teacher-Alignment-Metriken (Vergleichs-Pipeline gegen Lehrkraft-Scores, siehe §6)	JEDE Änderung an EVALUATOR_SYSTEM, EVALUATE_PROMPT, den Kalibrierungsankern (calibration_notes im Case / BLOOM_CALIBRATION_ANCHORS) oder den Rubric-Daten (eingebettet oder JSON-Dateien)

Harte Regeln:

• "Sieht besser aus" zählt NIE als Evidenz für Judge-Änderungen. Für den LLM-Judge (der Rubric-Evaluator, der Studierenden-Antworten bepunktet) sind Alignment-Metriken (Pearson, MAE gegen Lehrkraft-Bewertungen) die EINZIGE akzeptierte Evidenz. Einzelbeispiele anschauen ist Exploration, kein Beweis.
• Jede höhere Stufe setzt die niedrigeren voraus (Alignment-Nachweis ersetzt keine grüne CI).
• Die Entscheidung, WELCHE Stufe eine konkrete Änderung verlangt, trifft toadapt-change-control — diese Skill beschreibt, WIE man die Stufe erfüllt.

Stufe 1+2 lokal ausführen (Kommandos, vom Repo-Root)

cd /Users/dianakozachek/ToAdapt   # Repo-Root; Pfade darunter sind repo-relativ

# Backend-Lint (ruff liegt NICHT im .venv — global installiert, Stand 2026-07-08)
ruff check .

# Backend-Tests — IMMER via `python -m pytest` (siehe PYTHONPATH-Falle, §7)
.venv/bin/python -m pytest tests/ -q
# Erwartung (Stand 2026-07-09): "90 passed"

# Frontend
cd frontend && npm run lint && npx tsc --noEmit && npm run build

Minimaler Smoke-Test (kein LLM-Key nötig für /health):

.venv/bin/python -m uvicorn backend.main:app --port 8000 &
curl -s http://localhost:8000/health   # erwartet {"status":"ok",...}

Für vollständige Start-Anleitung (Env-Variablen, Frontend-Kopplung, Mongo): toadapt-run-and-operate.

---

2. Test-Landkarte (Stand: 2026-07-11, 131 Tests)

Alle Tests liegen flach in tests/ (kein conftest.py, kein __init__.py). Konfiguration in pyproject.toml: asyncio_mode = "auto" (async-Tests brauchen keinen Decorator), testpaths = ["tests"].

Datei	#	Deckt ab
tests/test_skeleton.py	7	/health minimal (keine Infra-Details im Body), /health/diagnostics + /dashboard/overview fail-closed ohne Key, Session-Erstellung gegen den Golden Case, current_tp_phase()-Fensterlogik (TP-Phase aus Datum)
tests/test_phase1_hardening.py	9	Studenten-Zugangscode (STUDENT_ACCESS_CODE offen/erzwungen), Rate-Limiter (429 + Retry-After, Keying per Path-Param), Session-/Dashboard-Store-Fallbacks ohne Mongo, geteilter OpenRouter-HTTP-Client, LLM-Concurrency-Semaphore
tests/test_case_editor.py	13	Case-Validator (Framework-Namen-Verbot, NORDIC-HOME-Sperre, Bloom-Coverage-Warnung), PATCH-Editor (Revision-Bump, Draft-Reset), Approve-Gate (422 + force-Override), Retire, Teil-Regenerierung mit gemocktem LLM, JSON-Fence-Stripping
tests/test_orchestrator_guardrails.py	3	guardrail_check(): blockt direkte Use-Case-Empfehlung, Case-Spekulation (FINMA/Azure), Slang + Emoji
tests/test_rubric_evaluator.py	11	JSON-Extraktion (plain/fenced/umschlossen), Feedback-Sanitizing (Antwort-Templates raus), Canvas-Rationale-Sanitizing, technical_fallback-Payload (0 Punkte, needs_human_review), Totals-Neuberechnung aus Scores; NEU (2026-07-09): Repair-Kette (zweiter LLM-Call rettet invalides erstes JSON), Typ-Fallback (awarded_points="acht" → technical_fallback statt 500), Parallel-Auswertung behält Fragen-Reihenfolge, Prompt-Pinning der Band-Anker (13.8/6.2 Punkte = 25 × 0.55/0.25)
tests/test_rubric_loader.py	1	Golden Case → alle 4 Rubrics ladbar, required_canvas_blocks pro q1–q4 korrekt verkettet
tests/test_case_package.py	13	Gate für den Golden Case: eingebettetes Bewertungspaket ≡ Datei-Rubric (Äquivalenz DE+EN), migrierte calibration_notes wortgleich gepinnt, generische BLOOM_CALIBRATION_ANCHORS (Bloom 2–6) für unkalibrierte Fragen, Embedded-vor-Datei-Vorrang + Datei-Fallback, Validator-Warnungen (fehlende Rubric/Glossar/Guidance, Glossar-Begriff nicht im Text), Generator parst Komplettpaket, Orchestrator bevorzugt case.agent_guidance (Golden Case: -agent.json-Fallback)
tests/test_formative_support.py	7	Formative Live-Unterstützung: Coverage-Endpoint (Canvas-Abdeckung, 404 bei unbekannter Frage), Denkanstoß-Feedback (max. 2 pro Frage → 429, Guardrail ersetzt verbotenen Output, leerer Draft abgelehnt), AnswerStats-Persistenz, paste_heavy-Schwellenlogik
tests/test_groups_and_privacy.py	10	Pseudonymisierung (HMAC stabil/irreversibel, ohne Secret roh), normalize_group_code, Session/Submission tragen Pseudonym + group_code, GET /tp-Schedule, /dashboard/groups ohne Einzelkennungen, Einzelpersonen-Endpoints verlangen X-Research-Key (fail-closed), scripts/generate_tutor_codes.py
tests/test_tutor_eval.py	8	NAACL-Taxonomie (8 Dimensionen), Judge-Prompt-Vollständigkeit, Annotation-Normalisierung, Desirability-Aggregation, Judge-JSON-Parsing, scripts/evaluate_tutor_responses.py (stabile Item-IDs, Annotation-Workbook, Summary) — inhaltlich: toadapt-tutor-response-evaluation
tests/test_submission_store.py	1	Submission-Recovery aus Store in den In-Memory-Cache (routes._get_submission)
tests/test_dashboard_difficulties.py	3	/dashboard/difficulties: API-Key-Pflicht, Priorisierung schwacher Studierender (attention_level, weak_objectives, Penalty-Aggregation case-insensitiv), Kohorten-Aggregation — mit synthetischen Submissions im tmp-Dateistore; seit 2026-07-09 zusätzlich mit X-Research-Key-Header (Endpoint verlangt RESEARCH_API_KEY)
tests/test_export_review_workbooks.py	1	Forschungs-Skript: Rubric-/Blind-/Chat-Workbooks (Blind-Sheet ohne Judge-Scores — Grundlage der Alignment-Studie)
tests/test_compare_teacher_rubric_scores.py	1	Forschungs-Skript: Lehrer-Workbook ist kanonischer Scope, rubric-only-Zeilen by design ausgeschlossen
tests/test_import_prolific_runs.py	1	Forschungs-Skript: Rohdaten-Import + SHA-256-Manifest, ignoriert .DS_Store
tests/test_publish_dashboard_scores.py	1	Forschungs-Skript: publiziert nur status=="evaluated" mit Scores, zählt Fallbacks/Review-Flags
tests/test_group_uploads.py (NEU 2026-07-10)	14	Master-Upload Gruppenarbeiten: ZIP-/PDF-Extraktion pur (minimales synthetisches PDF, Deckblatt-Parsing Gruppe 12→G12, Cover-only-Matching), fail-closed Auth (503/401), Upload-Flow mit gemocktem LLM (Zuordnung, TP-Punkteskala), technical_fallback bei Parse- UND Transportfehlern, unlesbares PDF → Report statt Crash, PATCH-Gruppenzuordnung, Dashboard-Merge beider Datenquellen (Gruppen ohne Individual-Submissions bleiben sichtbar, keine Einzelkennungen)
tests/test_llm_client.py (NEU 2026-07-10)	9	LLM-Client: Prompt-Caching-Verpackung (cache_control-Block, byte-identischer Inhalt), LLM_PROMPT_CACHING-Off-Switch, OPENROUTER_FALLBACK_MODELS-Parsing, models-Routing-Liste in extra_body, leere Antwort → RuntimeError — via Stub statt echtem LLM
tests/test_group_code_validation.py (NEU 2026-07-11)	9	GROUP_CODE_MAX: Grenzen (G1/G360 ok, G0/G361/Freitext nicht), leer/ungültig = Validierung aus, /auth/student/verify-Feedback (normalisiert + valid-Flag, ohne Body abwärtskompatibel), 422 bei Session-/Submission-Erstellung
tests/test_load_test_tools.py (NEU 2026-07-10)	6	Lasttest-Tooling: Stub-Chat-Antwort besteht guardrail_check (TP1–4), Stub-Judge-JSON besteht parse_evaluation_payload, Perzentil-/Status-Aggregation, GATE-W1-Auswertung im Report

Was NICHT abgedeckt ist (ehrlich)

• Keine echten LLM-Pfade. Chat (POST /sessions/{id}/chat), Case-Generierung und die eigentliche LLM-Evaluation laufen in Tests nur gemockt oder gar nicht. Ob ein Prompt gute Antworten produziert, beweist KEIN Test — dafür gibt es nur Stufe 4 (Alignment) bzw. manuelle Smokes.
• Kein E2E-Test (Frontend→Backend durchgeklickt). Frontend-CI prüft nur Lint/Typen/Build.
• Kein Load-Test. Rate-Limiter ist unit-getestet, Verhalten unter echter Parallellast (Railway, mehrere Worker) ist unbelegt.
• Kein Mongo-Integrationstest — alle Tests laufen bewusst OHNE Mongo (Datei-/No-op-Fallback). Mongo-Verhalten wird nur in Produktion via /health/diagnostics beobachtet (→ toadapt-diagnostics-and-tooling).
• retry_technical_fallback_scores.py ist das einzige Skript ohne Test — es macht echte LLM-Calls (nur mit --dry-run gefahrlos).

---

3. Golden-Inventar: Fixtures mit eigener Gate-Stufe

Der Golden Case: alpes-bank-genai-001

Der EINZIGE kuratierte, freigegebene Case im Pool (backend/cases/pool/), Stand 2026-07-09. Vier Dateien gehören zusammen:

Datei	Rolle
backend/cases/pool/alpes-bank-genai-001.json	Deutscher Case: Sections, Exhibits, q1–q4
backend/cases/pool/alpes-bank-genai-001-en.json	Englische Variante (Suffix -en schaltet EN-Agenten-Prompts)
backend/cases/pool/alpes-bank-genai-001-agent.json	Agent-Guidance (key_tensions, common_mistakes → fließen in Agenten-Prompts)
backend/cases/pool/alpes-bank-genai-001-en-agent.json	dito EN

Fragenstruktur (Fixture-Anker — Tests und Kalibrierung hängen daran):

Frage	Bloom	max_points	rubric_reference
q1	4	25	tp1_rubric.json
q2	5	24	tp2_rubric.json
q3	4	22	tp3_rubric.json
q4	6	30	tp4_rubric.json

Seit 2026-07-09 trägt der Golden Case (DE und EN) ein eingebettetes Bewertungspaket pro Frage: evaluation_focus, required_canvas_blocks, calibration_notes, exemplar_threshold_pct/score_floor_pct. Der rubric_loader arbeitet EMBEDDED-FIRST; die tp{n}_rubric.json-Dateien sind nur noch Fallback für Cases ohne eingebettetes Paket.

Warum eigene Gate-Stufe: Eine Änderung an diesem Case ist gleichzeitig (a) eine Fixture-Änderung — tests/test_rubric_loader.py (asserted konkrete Canvas-Blöcke pro Frage), tests/test_skeleton.py und tests/test_submission_store.py referenzieren die case_id hart —, (b) eine studierendensichtbare Verhaltensänderung (der Case IST das Produkt) und (c) potenziell eine Kalibrierungs-Invalidierung (siehe unten). Das technische Gate für Änderungen am eingebetteten Paket sind die Äquivalenz-Tests in tests/test_case_package.py: sie beweisen, dass das eingebettete Paket dem Datei-Rubric entspricht und die migrierten Kalibrierungsanker wortgleich erhalten sind — wer das Paket ändert, bricht sie bewusst und braucht Stufe-4-Evidenz. Zusätzlich ist das Glossar pro Case im Frontend hartkodiert (CASE_GLOSSARY["alpes-bank-genai-001"] in frontend/app/cases/[id]/page.tsx; Alpes-Hardcode hat Vorrang, neue Cases bringen case.glossary mit) — Case-Inhalt und Glossar können auseinanderlaufen. Vor jeder Änderung: toadapt-change-control laden.

Die 4 Rubric-JSONs sind KALIBRIERTE Artefakte

backend/config/rubrics/tp{1..4}_rubric.json enthalten pro Frage evaluation_focus (worauf der Judge achtet) und required_canvas_blocks (Business-Model-Canvas-Blöcke mit accepted_keywords und weight), plus Schwellen (exemplar_threshold_pct/score_floor_pct: 80/75, 82/75, 80/72, 82/75 für tp1–tp4). Seit 2026-07-09 sind sie nur noch Datei-Fallback für Alt-Cases ohne eingebettetes Paket (per lru_cache gecacht) — der Golden Case liest de facto sein eingebettetes Paket, das per Äquivalenz-Test mit den Dateien identisch gehalten wird. Kalibrierte Artefakte bleiben BEIDE.

Entscheidend — Kalibrierungsanker, Stand 2026-07-09 (zweistufig):

1. Case-spezifische Anker liegen in question.calibration_notes DIREKT im Case-JSON (für den Golden Case: die wörtlich migrierten Anker der Teacher-Alignment-Studie, §6 — gepinnt durch tests/test_case_package.py::test_golden_case_calibration_notes_unchanged). Sie ERSETZEN bei Vorhandensein alles andere.
2. Fehlen sie, greifen generische BLOOM_CALIBRATION_ANCHORS (pro Bloom 2–6) in backend/evaluator/rubric_evaluator.py.

BEHOBEN (2026-07-09): Die früher in _format_calibration_notes HARTKODIERTEN q1–q4-Anker existieren nicht mehr im Code — damit erben NEUE Cases nicht mehr automatisch Anker, die für den Alpes-Case formuliert wurden (die frühere bekannte Design-Schwäche). Unverändert gilt:

1. Rubric-Daten (eingebettet oder Datei), calibration_notes oder Case-Fragen ändern → Kalibrierung potenziell hinfällig → Stufe-4-Evidenz nötig.

---

4. Tests ergänzen — die hiesigen Muster (Copy-Paste)

Neue Tests: Datei tests/test_<thema>.py, Funktionen test_*. Async-Tests einfach als async def schreiben (asyncio_mode = "auto"). Keine echten LLM-Calls, keine echten Teilnehmerdaten — immer synthetische Daten.

Muster A: API-Test mit TestClient + sauberer Env

Seit 2026-07-17 zentral erledigt: tests/conftest.py räumt die MONGODB_*-Env pro Test autouse weg und neutralisiert die beim Import initialisierten Singletons (experiment_logger, submission_store, mongo._client). Anlass: Zwei lokale pytest-Läufe hatten über die Root-.env real in die Produktions-Collections geschrieben (48 Test-Dokumente; Cleanup: scripts/cleanup_test_artifacts_20260717.py) — gleicher Mechanismus wie die find_dotenv-Falle beim Lasttest (2026-07-10). Nebeneffekt des Fixes: Suite läuft in ~2 s statt ~20 s (die 2-Sekunden-Stalls waren echte Atlas-Verbindungsversuche). Einzelne Tests müssen die Env also nicht mehr selbst wegräumen; das explizite Muster unten bleibt korrekt und schadet nicht.

Hintergrund, warum das nötig war: Die Stores verbinden sich sonst real (backend/db/mongo.py baut die URI aus MONGODB_URI ODER MONGODB_MAS_NAME+MONGODB_MAS_KEY+MONGODB_HOST/_CLUSTER_HOST/ _CLUSTER; MongoClient(..., serverSelectionTimeoutMS=2000)).

import pytest
from fastapi.testclient import TestClient
from backend.main import app

API_KEY = "test-admin-key"

@pytest.fixture()
def client(monkeypatch):
    for var in ("MONGODB_URI", "MONGODB_MAS_NAME", "MONGODB_MAS_KEY", "MONGODB_HOST"):
        monkeypatch.delenv(var, raising=False)
    monkeypatch.delenv("STUDENT_ACCESS_CODE", raising=False)  # sonst 401 im Studenten-Flow
    monkeypatch.setenv("TOADAPT_API_KEY", API_KEY)            # sonst 503 auf Admin-Routen (fail-closed)
    return TestClient(app)

def test_example(client):
    res = client.get("/dashboard/overview", headers={"X-API-Key": API_KEY})
    assert res.status_code == 200

Vorlage im Repo: tests/test_case_editor.py (Fixture env).

Muster B: Datei-Stores auf tmp_path isolieren

Die Datei-Fallback-Stores schreiben sonst in den Working Tree (backend/cases/pool/, backend/db/submissions/). Modul-Konstanten patchen:

import backend.cases.manager as manager_module
import backend.db.dashboard_store as dashboard_store_module

monkeypatch.setattr(manager_module, "POOL_DIR", tmp_path)            # Case-Pool
monkeypatch.setattr(dashboard_store_module, "RESULTS_DIR", tmp_path) # Dashboard-Ergebnisse

(Analog existiert RUNTIME_SUBMISSIONS_DIR in backend/db/submission_store.py.)

Muster C: LLM mocken

Genau EIN Interceptions-Punkt: OpenRouterClient.complete. Signatur ist keyword-only — exakt so übernehmen:

monkeypatch.setenv("OPENROUTER_API_KEY", "test-key")  # Konstruktor wirft sonst ValueError

async def fake_complete(self, *, system, messages, max_tokens):
    return '{"section_id": "s1", "title": "Neuer Titel", "content": "Neuer Inhalt."}'

monkeypatch.setattr("backend.llm.OpenRouterClient.complete", fake_complete)

Vorlage: tests/test_case_editor.py::test_regenerate_section_replaces_content.

Muster D: Synthetische Submissions für Dashboard-/Aggregations-Tests

Ergebnis-JSONs direkt in den (auf tmp_path gepatchten) Dateistore legen — mit erfundenen Matrikelnummern, nie mit echten Daten:

(tmp_path / "r0.json").write_text(json.dumps({
    "submission_id": "sub-1001-38.0", "matrikelnummer": "1001",
    "case_id": "case-1", "target_tp": 1, "percentage": 38.0,
    "evaluated_at": "2026-07-01T10:00:00",
    "scores": [{"question_id": "q1", "bloom_level": 4, "max_points": 8,
                "awarded_points": 2, "feedback": "…",
                "learning_objective_tags": ["wirkungskette"],
                "main_penalties": [], "missing_canvas_blocks": [],
                "needs_human_review": False, "evaluation_status": "ok"}],
}), encoding="utf-8")

Vorlage: tests/test_dashboard_difficulties.py.

Muster E: scripts/ testen (kein Package)

scripts/*.py sind keine importierbaren Module — per importlib laden:

import importlib.util, sys
from pathlib import Path

SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "mein_skript.py"
SPEC = importlib.util.spec_from_file_location("mein_skript", SCRIPT_PATH)
MODULE = importlib.util.module_from_spec(SPEC)
sys.modules[SPEC.name] = MODULE
SPEC.loader.exec_module(MODULE)

Vorlage: tests/test_publish_dashboard_scores.py.

Guardrail-Regressionstests (Stufe 3)

Wenn du Guardrail-Patterns oder Agenten-Prompts änderst: Für JEDES neue verbotene Muster einen Fall in tests/test_orchestrator_guardrails.py ergänzen (und einen Positivfall, der NICHT blocken darf):

from backend.agents.orchestrator import guardrail_check

def test_guardrail_blocks_neues_muster():
    ok, reason = guardrail_check("<verbotener Beispieltext>", 2)  # 2 = TP-Phase
    assert ok is False

Achtung, bekannte Lücke: TP_CONFIGS[4] hat keinen forbidden_framework_names-Key — in TP4 greifen nur die globalen Patterns. Tests für TP-spezifische Verbote also mit tp 1–3 schreiben oder die Lücke bewusst adressieren (dann: toadapt-change-control).

---

5. CI-Anatomie (.github/workflows/ci.yml, Stand 2026-07-08)

Läuft bei jedem Push auf main und bei Pull Requests. Zwei Jobs:

Job	Umgebung	Schritte
backend	Python 3.11 (Prod-Version; lokal läuft 3.13)	pip install -r requirements.txt pytest pytest-asyncio ruff → ruff check . → pytest tests/ -q mit PYTHONPATH: .
frontend	Node 22, cwd frontend/	npm ci → npm run lint (eslint) → npx tsc --noEmit → npm run build

Wissenswert:

• pytest/pytest-asyncio/ruff sind dev-only — bewusst NICHT in requirements.txt (die ist die Prod-Dependency-Liste für Railway). CI installiert sie explizit dazu. Neue Test-Dependencies müssen in die CI-Install-Zeile, nicht in requirements.txt.
• Die PYTHONPATH-Falle: tests/ hat kein __init__.py und es gibt kein conftest.py im Root — ein nacktes pytest tests/ -q findet das Package backend NICHT (8 Collection-Errors, lokal am 2026-07-08 reproduziert). Zwei funktionierende Varianten: python -m pytest tests/ -q vom Repo-Root (fügt CWD zu sys.path hinzu) oder PYTHONPATH=. pytest tests/ -q (so macht es CI). Wenn CI-pytest scheitert, lokal aber läuft: zuerst prüfen, ob der env: PYTHONPATH: .-Block im Workflow noch da ist.
• Ruff-Konfig in pyproject.toml: line-length 100, target py311, und absichtliche E402-Ignores für backend/main.py und backend/db/submission_store.py (dort MUSS load_dotenv() vor den Imports laufen — Hintergrund: toadapt-failure-archaeology). Diese Ignores nicht "aufräumen".
• CI ersetzt keine Stufe-2–4-Evidenz: sie startet keinen Server, ruft kein LLM und misst kein Alignment.

---

6. Akzeptanz-Schwellen

Test-Baseline

• 131 Tests grün ist die Basis (Stand 2026-07-11; vorher 48→90) — nie unterschreiten. Tests dürfen nur ersetzt/entfernt werden, wenn das getestete Feature selbst entfernt wird (dann: toadapt-change-control). Neue Features ohne neuen Test sind ein Review-Smell.
• ruff check . und Frontend-Lint/tsc/build müssen sauber sein, bevor gepusht wird — CI läuft auf jedem Push auf main (Solo-Workflow, keine PR-Pflicht, d. h. rote CI landet sonst direkt "in Produktion").

Alignment-Bar (für Judge-/Rubric-/Prompt-Änderungen, Stufe 4)

ACHTUNG Scope-Differenz: Es gibt ZWEI Baseline-Zahlensätze für dieselbe Studie. Der Report (docs/teacher_alignment_report_20260531_17submissions.md; Dateiname sagt 17, Scope sind 16 Submissions / 64 Frage-Zeilen) nennt r 0.796 / MAE 2.711 / RMSE 3.897 / Mean Diff −2.07 — aber sein 64er-Filter existiert NICHT als Skript im Repo (ad-hoc, nicht reproduzierbar). Die unten stehende Pipeline rechnet über alle 67 gematchten Lehrer-Zeilen und liefert für den UNVERÄNDERTEN Judge r 0.777 / MAE 2.784 / RMSE 3.921 / Mean Diff −1.784 (am 2026-07-08 real reproduziert, siehe toadapt-judge-alignment-campaign §2 — dort ist auch das exakte GATE). Maßgeblich für den Vergleich ist die reproduzierbare 67er-Skript-Baseline; wer die 64er-Report-Werte als Bar nimmt, lehnt eine neutrale Änderung fälschlich als "Verschlechterung" ab. q4 ist in beiden Scopes deckungsgleich.

Metrik	67er-Skript-Baseline (kalibrierter Judge)	Bar für jede neue Judge-Version
Pearson r (gesamt)	0.777	≥ 0.78 halten (Gate der Kampagne) — keine Verschlechterung akzeptieren
MAE (Punkte, gesamt)	2.784	nicht verschlechtern
RMSE (Punkte)	3.921	nicht verschlechtern (sekundär)
Mean Diff Judge−Teacher	−1.784 (Judge systematisch strenger)	nicht weiter ins Negative
q4 (Bloom 6): MAE	4.969 (in beiden Scopes identisch), systematische Unterbewertung	Zielwerte und Vorgehen: toadapt-judge-alignment-campaign

Pipeline, um die Metriken für eine geänderte Judge-Version zu erzeugen (Details und Datenherkunft: toadapt-run-and-operate; NIE mit echten Teilnehmerdaten im Repo arbeiten — die liegen unter ~/ToAdapt_sensitive_data/ und bleiben dort):

# 1) Judge-Scores als Workbooks exportieren (liest Submissions/Events-JSON)
python scripts/export_review_workbooks.py \
  --submissions <submission_states.json> --events <experiment_events.json> \
  --cases-dir backend/cases/pool --output-dir <out> --prefix review

# 2) Gegen das ausgefüllte Lehrkraft-Blind-Workbook vergleichen
python scripts/compare_teacher_rubric_scores.py \
  --teacher-workbook <teacher.xlsx> --rubric-workbook <out>/review_*_rubric.xlsx \
  --output-dir <out>
# → Excel mit summary-Blatt (Pearson, MAE, RMSE, within_2pt, …) + CSV

Das Lehrer-Workbook ist der kanonische Scope: Zeilen, die nur der Judge bewertet hat, werden by design ausgeschlossen (getestet in tests/test_compare_teacher_rubric_scores.py).

Deploy einer Judge-Änderung OHNE diesen Durchlauf verstößt gegen die Projekt-Doktrin — siehe toadapt-change-control.

---

Provenance und Wartung

Update 2026-07-11 (HEAD 324d937): Test-Baseline 90 → 131; Landkarte um test_group_uploads (14), test_llm_client (9), test_group_code_validation (9), test_load_test_tools (6) ergänzt. Neues Muster darin: LLM-Stub-Antworten werden gegen die ECHTEN Pfade getestet (guardrail_check, parse_evaluation_payload), damit Lasttests reale Verarbeitung messen.

Erstellt: 2026-07-08. Alle Fakten am 2026-07-08 gegen das Repo verifiziert (48/48 Tests lokal grün, ruff sauber, PYTHONPATH-Falle reproduziert).

Update 2026-07-09 (HEAD 64b62f9): Test-Baseline 48 → 90 (lokal reproduziert); Landkarte um test_case_package (13), test_formative_support (7), test_groups_and_privacy (10), test_tutor_eval (8) ergänzt; test_rubric_evaluator 7 → 11 (Repair-Kette, Typ-Fallback, Parallel-Reihenfolge, Prompt-Pinning); Golden Case trägt eingebettetes Bewertungspaket, Äquivalenz-Tests in test_case_package.py sind das Gate; Kalibrierungsanker aus dem Evaluator-Code in die Case-JSONs migriert (+ generische BLOOM_CALIBRATION_ANCHORS) — Anker-Vererbungs-Schwäche BEHOBEN; Evidenz-Staffel um Stufe 3b (Tutor-Eval-Regressionsvergleich, Querverweis toadapt-tutor-response-evaluation) erweitert; /dashboard/difficulties verlangt zusätzlich X-Research-Key.

Re-Verifikation drift-anfälliger Fakten (je ein Kommando, vom Repo-Root):

Fakt	Kommando
Testanzahl (Baseline 90)	.venv/bin/python -m pytest tests/ -q | tail -1
Test-Dateiliste	ls tests/test_*.py
CI-Schritte + PYTHONPATH-Env	cat .github/workflows/ci.yml
Golden Case einziger Pool-Inhalt	ls backend/cases/pool/
q1–q4 Bloom/Punkte des Golden Case	python3 -c "import json;[print(q['question_id'],q['bloom_level'],q['max_points'],q['rubric_reference']) for q in json.load(open('backend/cases/pool/alpes-bank-genai-001.json'))['questions']]"
Kalibrierungsanker zweistufig (Case-Notes vor Bloom-Ankern)	grep -n 'calibration_notes|BLOOM_CALIBRATION_ANCHORS' backend/evaluator/rubric_evaluator.py
Golden-Case-Anker im Case-JSON gepinnt	grep -c calibration_notes backend/cases/pool/alpes-bank-genai-001.json (>0)
Rubric-Schwellen	grep -n 'threshold_pct|score_floor_pct' backend/config/rubrics/*.json
TP4-Guardrail-Lücke besteht noch	grep -c forbidden_framework_names backend/config/tp_configs.py (3 = Lücke besteht, 4 = geschlossen)
LLM-Mock-Signatur unverändert	grep -n 'async def complete' -A 6 backend/llm.py
Mongo-2s-Timeout	grep -n serverSelectionTimeoutMS backend/db/mongo.py
Alignment-Referenzmetriken	grep -nE 'Pearson|MAE' docs/teacher_alignment_report_20260531_17submissions.md
Glossar weiterhin frontend-hartkodiert	grep -n CASE_GLOSSARY "frontend/app/cases/[id]/page.tsx"