diff --git a/docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md b/docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md new file mode 100644 index 00000000..f5204bb0 --- /dev/null +++ b/docs-src/architecture/adr/ADR-001-runtime-deploy-policy.md @@ -0,0 +1,63 @@ +# ADR-001: Runtime Deploy Policy + +- **Status:** Accepted +- **Datum:** 2026-06-27 +- **Typ:** Architektur-/Release-Entscheidung (keine Entwicklerkonvention) + +## Kernsatz + +> Ein dev-Deploy muss immer einen verifizierbaren Runtime-Effekt haben. +> +> Auf die Frage „warum wurde dieser Build ausgelöst?" muss die Antwort immer lauten können: „weil sich das Laufzeitverhalten geändert hat." + +## Kontext + +Der dev-Deploy (Orca) wird durch einen Push auf den `gitea`-Remote (`gitea.meghsakha.com`) +ausgelöst und baut das Backend als amd64-Image (~5–15 min). In der Praxis entstehen regelmäßig +Änderungen **ohne** Laufzeit-Effekt: Dokumentation, Architekturtexte, Ownership-Modelle, +Koordinations-/Board-Dateien und Referenzartefakte (z. B. die Reference Scenario Suite unter +`backend-compliance/reference_scenarios/`, die vom Backend nicht importiert wird). + +Würde jeder solche Commit deployt, verliert die CI/CD-Historie ihre Aussagekraft: Ein Build +entspräche dann nicht mehr eindeutig einer Laufzeit-Änderung, und die Frage „warum wurde dieser +Build ausgelöst?" ließe sich nicht mehr verlässlich beantworten. + +## Entscheidung + +**Ein dev-Deploy (Orca-Build) wird nur ausgelöst, wenn die Änderung einen verifizierbaren +Laufzeit-Effekt hat.** + +Deployen, wenn **mindestens eines** zutrifft: + +- Runtime-Code geändert +- öffentliche API geändert (Pfad/Methode/Status/Request-/Response-Schema) +- Datenmodell geändert +- Reasoning-Verhalten geändert +- Sicherheitsfix + +**Nicht** deployen bei (nicht abschließend): + +- Dokumentation +- Reference Suites (z. B. `backend-compliance/reference_scenarios/`) +- ADRs (inkl. dieser) +- Board-/Koordinationsdateien +- Ownership-/Architektur-Texte + +Solche Änderungen werden auf `origin/main` gemergt (via PR, **kein** direkter Push), aber **nicht** +auf den `gitea`-Remote gepusht. `origin/main` darf dem dev-Stand damit vorauslaufen; die Parität +wird beim nächsten echten Runtime-Schnitt mitgezogen. + +## Konsequenzen + +- Die CI/CD-Historie bleibt aussagekräftig: jeder Build entspricht einer Laufzeit-Änderung. +- Build-Zeit und Ressourcen werden gespart. +- `origin/main` (Source of Truth) und dev (Laufzeit) dürfen temporär divergieren — das ist + **beabsichtigt und kein Defekt**. Der `last-build/main`-Tag auf dem `gitea`-Remote bezeichnet den + zuletzt deployten Runtime-Stand. +- Vor jedem Push auf `gitea` ist zu prüfen, ob der Diff einen Laufzeit-Effekt hat. + +## Beispiel + +Die Reference Scenario Suite v1 (`8a51db92`) und das Ownership-Dokument +`session_ownership_model_v1.md` (`c7339e68`) wurden auf `origin/main` gemergt, aber bewusst **nicht** +auf dev deployt — beide ohne Laufzeit-Effekt. Diese ADR selbst fällt unter dieselbe Regel.