# CONTRIB.md — Regeln für Änderungen am Mesh

Verbindlich für Master **und** alle Sub-Agenten. Abgeleitet aus den
Betriebsvorgaben des Betreibers (Stand 2026-10-08).

## 1. Grundsatz: ein Fix pro Schritt

- **Eine** Änderung, dann **testen**, dann die nächste. Keine Sammeländerungen.
- Jede Änderung wird einzeln nachgewiesen (Messwert, HTTP-Code, Programmausgabe).
- Die Messung muss zur Aussage passen: Bei Pipelines den Exitcode des
  **Scripts** messen, nicht den des letzten Pipe-Glieds (`| tail` liefert sonst
  immer 0).

## 2. Backup und Rollback

- Vor **jeder** Änderung ein Backup mit Datum im Dateinamen:
  `cp -p <datei> <datei>.bak-JJJJMMTT-HHMMSS`
- Der **Rollback-Weg** wird im Kopf der geänderten Datei als Kommentar notiert
  und im Abschlussbericht genannt.
- Keine Löschung von Daten, Prozessen oder Konfigurationen ohne Backup.
- Beim Editieren von Dateien per Werkzeug **Eigentümer und Rechte danach prüfen**.
  Beispiel: `/var/spool/cron/crontabs/root` muss `root:crontab 600` bleiben —
  ein Editor kann die Gruppe auf `root` zurücksetzen und die crontab damit
  unbrauchbar machen.

## 3. Selbstcheck vor dem Einsatz

1. Syntax: `bash -n <script>` bzw. `python3 -m py_compile <script>`
2. Dry-Run / Testlauf mit **erwartetem** Ergebnis (Negativfall einschliessen:
   Was passiert bei fehlender Datei, fehlendem Key, ungültiger Eingabe?)
3. Code danach noch einmal vollständig lesen
4. Erst dann produktiv einsetzen
5. **Passenden Interpreter verwenden.** Der Agenten-PATH stellt Hermes' Python 3.14
   voran (ohne `yaml`), Cron nutzt `/usr/bin/python3` (3.12, mit `yaml`). Scripts, die
   im Cron laufen, deshalb **explizit mit `/usr/bin/python3`** starten — und zum Testen
   denselben Interpreter nehmen. Sonst entsteht ein Fehler, den es im Cron gar nicht gibt.

## 4. Infrastruktur-Regeln

- **Task-Austausch nur über NFS.** Samba/CIFS ist blockiert.
- **SSH ausschliesslich key-basiert** und nur innerhalb des ZeroTier-Netzes.
  Kein Passwort-Fallback: `-o BatchMode=yes -o NumberOfPasswordPrompts=0`
  zusammen mit `-o IdentitiesOnly=yes` verhindert endlose Fehlversuche.
  Jeder Host nutzt **seinen eigenen** Key — kein Default, der auf einen fremden
  Key zeigt. Fehlt der Key, bricht das Script mit klarer Meldung ab.
- **Keine Sicherheitseinstellungen ändern**, um einen Fehler zu umgehen
  (fail2ban, Ignore-Listen, Dateirechte).
- Der Master bedient ein Host-Gateway für alle Profile; **lokale Gateways auf
  Sub-Agenten nicht ohne Abstimmung** zusätzlich starten (Doppelversorgung).

## 5. Budget

- Hartes Tageslimit **1 USD pro Agent**; Überschreitungen vermeiden, Arbeit
  lieber verschieben.
- Bei Guthaben 0 stoppen die Sub-Agenten automatisch.
- Modelle nur aus dem freigegebenen Satz in `/srv/work/costs/budget.yaml`
  (`modelle.erlaubt`). Abweichungen werden **gemeldet**, nicht eigenständig
  umgestellt.

## 6. Code-Änderungen

- Vor Code-Änderungen an Web-/Projekt-Repos: Review durch einen Sub-Agenten
  (Diff senden, Freigabe abwarten).
- Pull/Push ohne Force. Bei Branch-Fehlern die **Ursache** angleichen
  (z. B. `git init -b main`), nicht erzwingen.

## 7. Grenzen ehrlich melden

Wenn ein Fix an fehlenden Rechten, einer Plattform-Sperre oder einer dieser
Regeln scheitert: **nicht darum herum arbeiten.** Stattdessen stoppen, genau
dokumentieren, wo die Grenze liegt, und ein bis zwei Optionen vorschlagen.
Entschieden wird vom Betreiber.

## 8. Dokumentation

- Änderungen an Setup oder Ablauf: `README.md` und `CONTRIB.md` mitziehen.
- Betriebsberichte als HTML auf `dokumentationen.perfekt-ohne-en.de` ablegen
  (eigener Dateiname — `index.html` wird minütlich vom Report überschrieben).