feat: slice 3 - wiki, sources and AARs in their neckbeard homes

Gate 4, slice 3: verfahren/, hosts/, vision/ and shared/ moved via git
mv - six AARs to docs/aar/ (four harvested by the 2026-08-09 retro,
two open), procedures and host knowledge to docs/wiki/ (admin,
deployment, architecture, new area vision), the retro protocol and the
commit mapping table to docs/sources/ (protokolle/, migration/). New:
the wiki index linking every page, and the mirror-topology page
carrying the why-two-places reasoning verbatim from the old CLAUDE.md
(F-013 preserved). All moved-path references retargeted; the link
checker drove the sweep to zero.

pruefe_prosa.py added (pattern C+D): SHA citations resolve via repo,
mapping table, optional component clones or a curated exemption list
(documented dead Gitea-force-push commits, a vendor-repo tag, an
Authentik uid that is hex but no git SHA, the external neckbeard
reference); wiki task prose without an issue reference errors, with a
visible pragma for deliberate checklists; the dead-tracker denylist
now covers every mirrored repo's retired Gitea tracker (F-005) - two
links re-verified against live GitLab titles and retargeted, five
defused into honest historical citations.

Verified: validate 0/0, gen_status --check current, drift 0. Demo on
the pre-migration state fires 6 findings (3 orphaned SHAs, 3 task
blocks); on the current tree exactly the 3 F-004 task blocks remain -
they turn green in slice 4 when the issues exist, which is why
pruefe_prosa joins CI only then.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Thore Cimbal
2026-08-11 12:00:00 +00:00
co-authored by Claude Fable 5
parent 70e81e2ff1
commit 92b448fe30
37 changed files with 424 additions and 120 deletions
+100
View File
@@ -0,0 +1,100 @@
---
type: wiki-page
area: deployment
related: []
---
# Verfahren: Deploy-Übergabe
Für die Konstellation „einer baut, ein anderer rollt aus". Zweck ist nicht mehr
Prozess, sondern **weniger Rückfragen und weniger stille Fehlschläge**.
Eingeführt am 2026-08-01 nach dem Deploy der CVE-Pipeline (`gitops#47`), siehe
[aar/2026-08-01-cve-pipeline-gitops47.md](../../aar/2026-08-01-cve-pipeline-gitops47.md).
## Ablauf
1. Wer baut, öffnet **auf git.lab** ein Issue aus der Vorlage **Deploy-Übergabe**
(`.gitlab/issue_templates/Deploy-Übergabe.md`, im Feld *Description template*).
2. Wer ausrollt, arbeitet die Prüfliste unten ab und deployt.
3. Wer ausrollt, hängt den **AAR** als Kommentar an dasselbe Issue
(Vorlage: [docs/aar/template.md](../../aar/template.md)). Bei Befunden ab MEDIUM
zusätzlich als Datei unter `docs/aar/`.
## Die vier Punkte, die den Unterschied machen
### 1. Mengengerüst vor dem Deploy
Bei allem, was etwas erzeugt — Nachrichten, Alarme, Zeitreihen, Requests —
gehört die erwartete Anzahl beim **ersten** Lauf in die Übergabe. Geschätzt ist
in Ordnung, gemessen ist besser; welches von beidem, muss dabeistehen.
Der Grund: „ein Alarm pro Fund" ist eine völlig unauffällige Zeile im Code und
harmlos bei 5 Funden. Bei 126 ist es ein Ausfall. Der Unterschied steht nirgends
im Diff — er ergibt sich erst aus den Daten, gegen die das Ding läuft.
Eine Stichprobe reicht: drei repräsentative Elemente von 29 messen und
hochrechnen kostet Minuten und liefert die Größenordnung.
### 2. Verifikation dort, wo der Dienst liest
Ein grüner Linter belegt, dass eine Datei **gültig** ist — nicht, dass sie
**geladen** wurde. Diese beiden Aussagen sind bei Bind-Mounts, Caches und
Reload-Semantiken regelmäßig verschieden.
Also im Container prüfen, in der laufenden API, im tatsächlich geladenen
Regelwerk. Ein Blick auf die Platte beweist nichts über den Prozess.
### 3. Deploy-Kommando vollständig übergeben
Inklusive Reload-, Restart- und Recreate-Schritten. Ein `docker compose up -d`,
das `Running` meldet und dabei nichts aktiviert, ist der häufigste stille
Fehlschlag: kein Fehler, kein Log, falscher Zustand.
Konkret auf dem Monitoring-Stack (CFGMON): Einzeldatei-Mounts hängen am Inode,
`git pull` benennt beim Schreiben um und erzeugt damit einen neuen — der
Container zeigt danach weiter auf die alte Datei. Es braucht
`--force-recreate`. Details: `gitops#52`.
### 4. Zustellwege stumm schalten statt Deploy verschieben
Datensammlung und Außenwirkung lassen sich fast immer getrennt scharf schalten.
Wenn der Zustellweg das Risiko ist, wird **er** abgeklemmt — nicht der ganze
Deploy verschoben.
So läuft die Datensammlung ab sofort, das Dashboard steht, echte Zahlen
ersetzen die Schätzung, und die Entscheidung über die Zustellung fällt auf
Basis von Messwerten statt Vermutungen. Wichtig: die Stummschaltung gehört
committet und dokumentiert, sonst ist sie in zwei Wochen ein Rätsel.
## Prüfliste für den Ausrollenden
<!-- pruefe-prosa:ok (Checkliste des Verfahrens, keine offene Aufgabe) -->
- [ ] Diff gelesen, nicht nur die Beschreibung
- [ ] Mengengerüst plausibel? Bei Zweifel an einer Stichprobe selbst messen
- [ ] Configs mit den jeweiligen Werkzeugen validiert (`promtool`, `amtool`,
`compose config`, `py_compile` …)
- [ ] Außenwirkung identifiziert — was verlässt beim ersten Lauf das System?
- [ ] Nach dem Deploy **im Container** verifiziert, dass die neue Config aktiv ist
- [ ] Geprüft, ob vorher gesunde Dinge noch gesund sind (keine stille Regression)
- [ ] AAR geschrieben, Folge-Issues angelegt, Stummschaltungen dokumentiert
## Abgrenzung
Das Verfahren gilt für Übergaben zwischen Personen. Wer baut **und** ausrollt,
braucht kein Issue — der AAR lohnt trotzdem, sobald es Befunde ab MEDIUM gab.
## Kanonisierung nach CFGMON-Deploys (Topologie-Pflichtschritt)
CFGMON erreicht git.lab nicht — Commits aus Deploy-Sessions landen zwangsläufig
direkt auf dem Gitea-Mirror und werden vom nächsten Mirror-Lauf **kommentarlos
überschrieben** (zweimal passiert: dfe04c4→6ffab68 am 01.08. nachts,
2b715ca→0bd77e2 am 01.08. nachmittags). Deshalb gehört zu jeder Übergabe:
1. **CFGMON-Seite** vermerkt den Commit-Hash im Übergabe-Issue (Feld „Stand").
2. **Mac-Seite** kanonisiert zeitnah: Patch per
`https://rohana.axion1337.de/sorb/<repo>/commit/<sha>.patch` ziehen
(verwaiste Objekte bleiben eine Weile abrufbar), `git am`, Push nach git.lab.
Der Hash ändert sich dabei — **Autorschaft und Inhalt bleiben erhalten**.
3. **CFGMON** vor dem nächsten Pull: `git fetch && git reset --hard origin/main`
(inhaltsgleich, nur neuer Hash).