docs: README.md + CONTRIB.md ergaenzt (Mesh-Setup, Aenderungsregeln, Review-Korrekturen)

2026-10-08 20:52:54 +02:00
parent 8c92824663
commit 0eec139a93
2 changed files with 154 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 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).