Add controlled coding agent automation

README.md

@@ -1,2 +1,112 @@
-# lai_automatisierung
+# LAI Automatisierung
+
+Kontrollierter Coding-Agent fuer Failure Reports aus
+[`lai`](https://gitea.tisinfra.de/christian.meyer/lai). Der Orchestrator verwendet
+[Aider](https://aider.chat/) headless als austauschbaren Coding-Kern. Git-, Gitea-,
+Policy- und Freigabelogik bleiben in diesem Projekt.
+
+## Warum Aider?
+
+- scriptbarer Einmal-Auftrag mit `--message-file`
+- gute Git- und Repository-Map-Unterstuetzung
+- Mistral ueber LiteLLM nutzbar
+- automatische Commits koennen deaktiviert werden
+- deutlich kleinerer Betriebsumfang als OpenHands
+
+OpenHands bleibt eine moegliche spaetere Alternative fuer komplexere, mehrstufige
+Agentenlaeufe. Sein Headless-Modus arbeitet jedoch immer mit `always-approve`; deshalb
+muessen auch dort unsere externen Policy-Gates erhalten bleiben.
+
+## Ablauf
+
+```text
+failure_reports(open)
+	-> transaktionales Claiming (SKIP LOCKED)
+	-> anonymisierter Agentenauftrag
+	-> frischer Clone von lai.git
+	-> Aider-Aenderung ohne Commit
+	-> Pfad-, Groessen- und Sicherheitsgates
+	-> Tests
+	-> Commit
+	-> PR oder kontrollierter Push auf main
+	-> failure_reports(resolved/agent_failed)
+```
+
+Der Coding-Agent erhaelt keinen Zugang zur ERP- oder Kundendatenbank. Rohdaten und
+`.env`-Dateien sind ausgeschlossen. Repository-Pushes verwenden `GIT_ASKPASS`; Tokens
+werden nicht in Remote-URLs oder Prozessargumenten gespeichert. Der Orchestrator laeuft
+als privilegierter Containerprozess, startet Aider aber als separaten Benutzer `coder`.
+Dieser Unterprozess erhaelt nur Modell-Credentials, nicht die Failure-DB- oder
+Gitea-Zugangsdaten.
+
+Laravel-Tests laufen mit PHP und Composer direkt im isolierten Worker. Der Docker-Socket
+des Hosts wird nicht eingebunden. Abgebrochene Claims werden nach standardmaessig 90
+Minuten wieder freigegeben; `STALE_CLAIM_MINUTES` passt dieses Intervall an.
+
+## Schnellstart
+
+```bash
+cp .env.example .env
+# FAILURE_DB_PASSWORD und bei Bedarf MISTRAL_API_KEY eintragen
+docker compose build
+docker compose run --rm automation check
+docker compose run --rm automation once
+```
+
+Der Default `AUTOMATION_MODE=dry-run` claimt einen offenen Report, erzeugt den
+anonymisierten Auftrag und setzt ihn danach wieder auf `open`. Es wird weder ein Agent
+gestartet noch gepusht.
+
+## PR-Modus
+
+```dotenv
+AUTOMATION_MODE=pr
+GITEA_USERNAME=automation-bot
+GITEA_TOKEN=...
+MISTRAL_API_KEY=...
+```
+
+Der Bot benoetigt Schreibzugriff auf `christian.meyer/lai` und die Berechtigung,
+Branches sowie Pull Requests anzulegen. Jeder Lauf erstellt
+`ai/failure-{report_id}` und einen PR gegen `main`.
+
+## Direkter main-Modus
+
+```dotenv
+AUTOMATION_MODE=direct-main
+ALLOW_DIRECT_MAIN=true
+GITEA_TOKEN=...
+```
+
+Der zweite Schalter ist ein Kill-Switch. In diesem Modus sind Migrationen, Routes,
+Auth, Middleware, PermissionService und SQLValidatorService zusaetzlich blockiert.
+Branch Protection muss den Bot fuer direkte Pushes explizit zulassen. PR-Modus bleibt
+die empfohlene Betriebsart.
+
+## Modelle
+
+Default:
+
+```dotenv
+AGENT_MODEL=mistral/mistral-medium-latest
+```
+
+Das Chat-Modell und Coding-Modell sind bewusst getrennt. Fuer Coding-Agenten sollte ein
+agentisch/coding-optimiertes Modell verwendet werden. Ein Wechsel zu OpenHands oder
+einem anderen Backend erfordert nur einen neuen Adapter neben `AiderAgent`.
+
+## Tests
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install ".[dev]"
+ruff check src tests
+pytest -q
+```
+
+## Repositorys
+
+- Chat: `https://gitea.tisinfra.de/christian.meyer/lai.git`
+- Automatisierung: `https://gitea.tisinfra.de/christian.meyer/lai_automatisierung.git`