ci(backend): Ruff-Scope zwischen PR- und Pre-Push-Gate angleichen

[arn0ld87]

Root Cause

Das verpflichtende CI-PR-Gate und das lokale Pre-Push-Gate prüften unterschiedliche Ruff-Scopes:

• .github/workflows/ci.yml (backend-pr-gate, läuft auf jedem PR): uv run ruff check app/
• scripts/pre-push-gate.sh → run_backend(): uv run ruff check app/ tests/

Das lokale Gate war strenger als der verpflichtende CI-Check. Lint-Verstöße unter backend/tests/ passierten CI unbemerkt und landeten auf main, wo sie danach jeden lokalen Backend-Slice blockierten.

Belegter Vorfall: PR #859 (bf80dd09) brachte backend/tests/scripts/test_bert_memory_profile.py mit 6 Ruff-Verstößen (2× F401, 4× E101) nach main. CI war grün. Aufgefallen erst, als ein Worker an #868 daran hängenblieb. Symptom behoben in PR #879 — die Ursache blieb bis jetzt offen.

Scope

• .github/workflows/ci.yml: Ruff-Step in backend-pr-gate → uv run ruff check app/ tests/ (genau eine Zeile)
• backend/tests/contracts/test_ci_gate_parity.py (neu): struktureller Regressionstest gegen erneutes Auseinanderlaufen
• docs/STATUS.md: Autogen-Test-Zähler 3570 → 3573 via scripts/sync-status.sh

Out-of-Scope

• scripts/pre-push-gate.sh bleibt unberührt. Das lokale Gate wurde bewusst nicht auf app/ abgeschwächt — die Angleichung zieht das strengere Gate nach vorn.
• ci.yml:181 (Job backend, push:main) behält ruff check ..
• Kein Wechsel auf ruff check . im PR-Gate: das würde scripts/, generierte Dateien u. a. ungefragt in einen bereits etablierten Contract ziehen. YAGNI.
• ROADMAP.md / CHANGELOG.md: reine CI-/Tooling-Änderung ohne ausgeliefertes Nutzer- oder Betriebsverhalten.

Verifikationsstrategie (TDD)

RED — Test gegen unverändertes ci.yml:

test_ci_pr_gate_and_pre_push_gate_ruff_scope_match           FAILED
test_ci_pr_gate_ruff_scope_covers_tests_dir                  FAILED
test_status_drift_check_step_runs_after_pytest_contracts_step PASSED

AssertionError: ... ci.yml (backend-pr-gate / 'Ruff lint') prueft ['app/'],
pre-push-gate.sh (run_backend) prueft ['app/', 'tests/'].

GREEN — nach der Angleichung: 3 passed.

Empirischer Beleg für Akzeptanzkriterium 2 (Probe-Datei mit F401 unter backend/tests/, bewusst nicht committed, danach gelöscht):

uv run ruff check app/ tests/  → F401 'os' imported but unused, Found 1 error, Exit 1
uv run ruff check app/         → All checks passed!, Exit 0    ← der belegte Blindfleck

Kein absichtlich kaputter Python-Code im Repository.

Tests

Der neue Guard deckt drei Achsen ab:

1. Scope-Parität CI ↔ run_backend() — schlägt an, sobald eine Seite driftet
2. tests/ im PR-Gate-Scope — greift auch dann, wenn jemand künftig beide Gates gemeinsam auf app/ abschwächt (Fall 1 bliebe dabei grün)
3. Step-Reihenfolge aus PR ci(status): STATUS.md-Drift im PR-Gate prüfen statt nach dem Merge #884 — sync-status.sh --check muss nach den Contract-Tests stehen; geschützt wird die Definition des Jobs backend-pr-gate als Ganzes, nicht nur die Ruff-Zeile

stdlib-only, kein import yaml. pyyaml ist im Repo keine deklarierte Dependency (weder [project].dependencies noch [dependency-groups].dev) und käme rein transitiv über huggingface-hub/transformers/jsonschema-path/pre-commit. Ein Test im verpflichtenden Gate darf keine lautlos entfernbare transitive Kopplung eingehen. Der Test folgt damit der bestehenden Repo-Konvention backend/tests/dependencies/test_dependency_ssot.py (Rohtext/Regex, stdlib).

Ablageort tests/contracts/: bewusst, weil genau dieses Verzeichnis im verpflichtenden PR-Gate läuft (uv run pytest tests/contracts/ -q) — anderswo wäre der Guard wirkungslos.

Gate

uv run pytest tests/contracts/ -x -q                 → 387 passed, Exit 0
uv run python -m app.contracts.dump_schemas --check  → alle 46 Schemas matchen, Exit 0
uv run ruff check app/ tests/                        → All checks passed, Exit 0
uv run mypy app                                      → no issues in 230 source files, Exit 0
bash scripts/pre-push-gate.sh backend                → ALL GREEN, Exit 0

Dokumentationssync

• docs/runbooks/pre-push-gate.md: NICHT BETROFFEN — Zeile 30 führte im Gate-Katalog bereits ruff check app/ tests/ mit CI-Mirror „Backend PR smoke gate". Diese Aussage war vor diesem PR unwahr; die Code-Änderung macht sie korrekt. Das Akzeptanzkriterium fordert Korrektheit, kein Edit.
• docs/STATUS.md: aktualisiert (Autogen-Zähler, +3 durch die neuen Testfälle)
• ROADMAP.md / CHANGELOG.md: NICHT BETROFFEN (s. Out-of-Scope)

Subagents, Modelle, Skills

• Implementierung: Agora Backend-Refactor-Worker-Regelwerk (.claude/agents/agora-refactor-worker-m3.md), Modell sonnet
• Read-only Inventur aller Ruff-Gates: Agora Evidence-Auditor-Regelwerk, Modell opus — deckte auf, dass pyyaml nicht deklariert ist und dass bereits eine Konvention für strukturelle Workflow-Tests existiert; führte zu einem Korrekturlauf
• Matt-Pocock code-review (Standards + Spec, parallel)
• Abschluss: agora-opus-reviewer — APPROVE, mit unabhängig reproduziertem RED-Nachweis und selbst nachgemessenem Test-Zähler

Risiken

• Gering. Die Änderung verschärft ein Gate und schwächt nirgends ab. uv run ruff check app/ tests/ ist auf main bereits grün — das PR-Gate wird durch die Angleichung nicht sofort rot.
• Parser-Fehlerrichtung geprüft: Ein künftiges Ruff-Flag mit separatem Wert (--select E501) oder ein umformatierter Job-Block führen zu lautem Falsch-Rot (Set-Ungleichheit bzw. AssertionError), nie zu stillem Grün.
• Einziger bekannter Anpassungsfall: Würden beide Gates künftig auf ruff check . umgestellt, liefe Testfall 2 falsch rot, obwohl . tests/ einschließt. Fällt laut auf, Anpassung trivial.

Closes #881

🤖 Generated with Claude Code

Summary by CodeRabbit

• Verbesserungen

  • Die automatisierte Codeprüfung berücksichtigt nun zusätzlich den Testcode.
  • CI- und lokale Prüfungen verwenden denselben Prüfungsumfang.
  • Die Reihenfolge der Prüfungen im Backend-Gate wurde abgesichert.

• Tests

  • Neue Prüfungen stellen die Übereinstimmung der CI- und lokalen Qualitätsprüfungen sicher.

• Dokumentation

  • Die dokumentierte Anzahl der gesammelten Backend-Tests wurde aktualisiert.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7a34cc7a-69b5-4e23-b46b-dfb187f391bb

📥 Commits

Reviewing files that changed from the base of the PR and between 7cb7a73 and 3232c07.

📒 Files selected for processing (3)

• .github/workflows/ci.yml
• backend/tests/contracts/test_ci_gate_parity.py
• docs/STATUS.md

---

📝 Walkthrough

Walkthrough

Das Backend-PR-Gate lintet nun app/ und tests/. Neue Vertragstests vergleichen diesen Scope mit dem Pre-Push-Gate, prüfen die tests/-Abdeckung sowie die Reihenfolge des Status-Drift-Schritts. Die Statusdokumentation aktualisiert die Testanzahl.

Changes

CI-Gate-Parität

Layer / File(s)	Summary
Ruff-Scope im PR-Gate erweitern .github/workflows/ci.yml	Der Ruff-Schritt im backend-pr-gate prüft nun app/ und tests/.
Vertragsparser für Gate-Befehle backend/tests/contracts/test_ci_gate_parity.py	Hilfsfunktionen extrahieren den CI-Job, seine Steps sowie die Ruff-Befehle aus CI und Pre-Push-Skript und bestimmen deren Pfad-Scope.
Paritäts- und Reihenfolgeprüfungen backend/tests/contracts/test_ci_gate_parity.py, docs/STATUS.md	Tests erzwingen identische Ruff-Scopes, die Abdeckung von tests/ und die Reihenfolge des Status-Checks; die dokumentierte Backend-Testanzahl wird auf 3573 aktualisiert.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: backend, needs-backend-ci

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Die Kernforderung von #881 ist umgesetzt, aber die geforderte Doku-Aktualisierung in docs/runbooks/pre-push-gate.md ist im PR nicht sichtbar.	Ergänze eine Aktualisierung von docs/runbooks/pre-push-gate.md, damit der Backend-Pre-Push-Scope korrekt dokumentiert ist.
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.64% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Der Titel beschreibt klar die Angleichung des Ruff-Scope zwischen PR- und Pre-Push-Gate.
Out of Scope Changes check	✅ Passed	Die Änderungen beschränken sich auf CI, einen Paritäts-Test und den Status-Block und wirken damit thematisch konsistent.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}