--- type: design status: done date: 2026-08-11 size: L related: - "PROJECT.md" - "docs/adr/0005-pm-framework-kanban.md" - "docs/adr/0009-commit-konventionen-und-historien-anonymisierung.md" - "docs/adr/0010-haertung-eigener-meilenstein.md" - "docs/adr/0012-issues-im-repo-gitlab-als-spiegel.md" - "docs/adr/0013-gruppenregeln-kanonisch-mit-pruefung.md" --- # Design: Migration des Management-Systems auf neckbeard Grundlage: der Feldtest-Report auf dem Branch `Neckbeard-v0.1.1-analyse-1` (Session 1, eingefroren; Befunde F-001…F-017), gemessen gegen neckbeard v0.1.1 @ `823a08cac6b03a47d7e2f661200a49ac6e09d38d`. Bindende Vorgabe aus der Übergabe: **erst die Fehlermuster beider Ansätze durcharbeiten und den Wert des alten Ansatzes in neckbeard einfalten — Übernahme erst danach.** ## Gate 1 — Produkt ### Problem Das Management-Repo steuert fünf Komponenten-Repos und sich selbst mit einem eigenen Regelwerk. Der Feldtest zeigt: Das Regelwerk ist nicht verfallen, sondern **ungleich durchgesetzt**. Wo ein Werkzeug die Regel hält, hält sie vollständig — alle 71 offenen Issues haben genau einen Meilenstein, das WIP-Limit steht, 0 von 161 Dokument-Links sind tot (F-014). Wo nichts prüft — Prosa, Git-Metadaten, Übereinstimmung zweier Dateien — versagt dasselbe Regelwerk wiederholt, in vier Mustern: - **A** — Entscheidung im Werkzeug vollzogen, Doku nicht nachgezogen: M5 existiert und trägt 14 Issues, aber `roadmap.md` stellt ihn als offene Frage dar und die kanonische Arbeitsgrundlage bindet Issues an „M1–M4" (F-001; ferner F-005, F-007, F-010, F-017). - **B** — Regel repo-weit erklärt, auf eine Teilmenge angewandt: Zeitstempel-Anonymisierung erreicht 1 von 6 Repos, 5 Autor-Identitäten einer Person überleben, 4 von 5 Komponenten haben kein versprochenes CLAUDE.md, fünf Komponenten tragen vier Namensschemata (F-002, F-003, F-008, F-011). - **C** — zwei Backlogs, eine Regel: fünf offene Arbeitspunkte leben nur in `hosts/`-Markdown, unsichtbar für Board, Meilenstein und Priorität (F-004, F-009). - **D** — Artefakte überleben ihren Zweck ohne Eigentümer: verwaiste Branches publizieren Vor-Rewrite-Historie, zitierte SHAs sind unauflösbar (F-006, F-012). Betroffen sind sorb und jede Agenten-Session: Jede neue Session wird von der kanonischen Datei falsch geprimt und würde vollzogene Entscheidungen rückgängig machen. Neckbeard adressiert genau diese Klasse — hält aber selbst sieben im Feldtest belegte Lücken, allen voran: ADR-0001 löst „ein Repo, viele Harnesse", dieses Projekt ist „viele Repos, ein Regelwerk", und für die Frage, wo die 71 offenen GitLab-Issues nach der Migration leben, existiert nur eine aufgeschobene Option C. Beide Entscheidungen fallen in Gate 2, jeweils als ADR. Das Produkt dieser Undertaking: das Management-System dieses Repos auf neckbeard umziehen, so dass die vorhandene Disziplin von Stellen, die nur ein Mensch prüfen kann, an Stellen wandert, die ein Skript prüft — nachdem der Wert des alten Ansatzes (F-013…F-016, Meilenstein-/ Prioritäts-Evidenz, Mirror-Topologie-Prosa) in neckbeard eingefaltet wurde. ### Akzeptanzkriterien (verifizierbar) 1. **Deterministische Gates grün:** `scripts/validate.py` meldet auf dem migrierten Repo 0 Fehler; `scripts/gen_status.py --check` meldet STATUS.md aktuell. 2. **Entscheidungen portiert:** alle Entscheidungen aus `decisions/` liegen als ADRs mit schema-konformem Frontmatter unter `docs/adr/` — 11/11 validieren *(bei Gate-1-Freigabe 10; `decisions/0011` kam am 2026-08-11 hinzu, siehe Nachtrag in Gate 3)*. 3. **Ein Backlog:** die fünf Arbeitspunkte aus F-004 (OVERMIND-01, CFGMON-11/12/13, MATRIX-05) existieren als Issues im kanonischen System — 5/5; 0 offene „Nächste Schritte" in `hosts/` ohne Issue-Referenz. 4. **Generierte statt behaupteter Zustand:** 0 handgepflegte Zählungen und „Stand"-Etiketten in kanonischen Dateien, wo ein Generat sie ersetzt; kein kanonisches Dokument widerspricht dem Werkzeugstand bei den Meilensteinen (M1–M5). 5. **Muster → Mechanismus:** für jedes Driftmuster A–D benennt das Design mindestens einen deterministischen Check, und pro Muster feuert mindestens ein Check nachweislich auf dem Vor-Migrations-Stand — 4/4 demonstriert. 6. **Ernte dokumentiert:** 7/7 neckbeard-Lücken mit Disposition (eingefaltet / als Framework-Issue notiert / verworfen mit Grund); 4/4 Works-well-Befunde mit benanntem Erhaltungsmechanismus oder begründetem Verzicht. ### Nicht-Ziele - **Keine Historien-Umschreibung.** Die F-002/F-003-Remediation ist ein eigener Vorgang mit eigener bindender Auflage (Zuordnung im Stil von `shared/commit-zuordnung-2026-08-07.md`); diese Undertaking darf ihr nur nicht im Weg stehen. - **Kein Push** nach git.lab oder Gitea; der Branch bleibt lokal bis zur Freigabe durch sorb. - **Keine Änderung am neckbeard-Upstream.** Lücken werden hier dispositioniert; sie dort einzureichen ist ein eigener Akt. - **Kein Rollout in die fünf Komponenten-Repos** über das hinaus, was die Shared-Ruleset-Entscheidung (Gate 2) zwingend erfordert; der Rollout wird als Folge-Issues angelegt, nicht hier gebaut. - **Kein Forge-Zustand wird zerstört:** keine Löschung von GitLab-Issues, Labels, Meilensteinen oder dem Board durch die Migration selbst. - **`analysis/` bleibt eingefroren** — der Branch von Session 1 wird weder verändert noch umgebaut. - **Kein inhaltliches Umschreiben** des Host-/Visions-/Verfahrenswissens: Umzug, Frontmatter und Korrektur werkzeugwidersprechender Aussagen ja, Neuformulierung nein. ### Ankündigung Das Management-Repo der Gruppe axion1337.chat zieht auf das neckbeard-Framework um. Die vorhandene Disziplin — Meilensteinpflicht, Status-Disziplin, ADR-Pflicht, AARs — bleibt erhalten, wandert aber von Stellen, die nur ein Mensch prüfen kann, an Stellen, die ein Skript prüft: Frontmatter statt Prosa, generiertes STATUS.md statt handgepflegter Zählungen, `validate.py` statt Konventionstreue aus dem Gedächtnis. Die vier Driftmuster des Feldtests bekommen je einen deterministischen Check, und was der alte Ansatz besser kann als neckbeard, wird zuerst ins Framework eingefaltet statt verworfen. Zielgruppe sind sorb und alle Agenten-Sessions, die künftig von einer Quelle starten, die sich nicht selbst widerspricht. ### UI Keine UI beteiligt — Artefakte sind Markdown-Dateien, die Oberfläche bleibt GitLab/Obsidian/Editor. Mockups entfallen. ## Gate 2 — Architektur ### Gelesen (Pflichtlektüre vor den Optionen) Alt-Ansatz: `CLAUDE.md`, `roadmap.md`, `decisions/README.md` und die tragenden Entscheidungen 0001, 0002, 0005, 0009, 0010, [verfahren/refinement.md](../../wiki/admin/refinement.md), [verfahren/stillstandspruefung.md](../../wiki/admin/stillstandspruefung.md), `.gitlab-ci.yml`, Auszüge aus `hosts/`. Neckbeard v0.1.1: AGENTS.md, WORKFLOW.md, ADR-0001…0004/0006, `schema.yaml`, `validate.py`, `gen_status.py`, Schöpfungs-AAR, `docs/wiki/index.md`. Session-1-Daten (lesend vom Analyse-Branch): `gitlab_issues.json` — 111 Issues, 71 offen; **71/71 mit genau einem Meilenstein (M1 19 · M2 22 · M3 4 · M4 12 · M5 14) und 71/71 mit genau einer Priorität** (low 32, medium 34, high 5). Die Entscheidungen 0003/0004/0006/0007/0008 werden bei der Portierung (Gate 4) vollständig gelesen; sie tragen keine Architekturfrage dieser Undertaking. ### Ernte, Teil 1 — die Fehlermuster beider Ansätze Wo genau versagte der alte Ansatz, was hält neckbeard dagegen, und wo bleibt auch mit neckbeard ein Loch: | Muster | Wurzel im Alt-Ansatz | Neckbeard-Gegenstück | Verbleibendes Loch → Mechanismus dieser Migration | |---|---|---|---| | **A** — Doku nicht nachgezogen (F-001, F-005, F-007, F-010, F-017) | Zustand steht als behauptete Zahl/Prosa an mehreren Stellen; nichts vergleicht | Generiertes STATUS.md (`gen_status.py --check` in CI), ADRs nie editiert nur abgelöst | Prosa, die *Forge*-Zustand behauptet, prüft neckbeard nicht → Drift-Prüfung Repo↔GitLab; Meilenstein-Satz als Schema-Enum (eine Quelle); „Stand"-Etiketten entfallen ersatzlos (git log antwortet) | | **B** — Regel repo-weit, Anwendung Teilmenge (F-002, F-003, F-008, F-011) | Regel gilt „für alle Repos", kein Artefakt zählt die Repos auf, kein Skript läuft über alle | **Lücke** — ADR-0001 endet an der Repo-Grenze | Komponenten-Artefakt + Abgleich gegen die zur Laufzeit gelesene Gruppenliste ([ADR-0013](../../adr/0013-gruppenregeln-kanonisch-mit-pruefung.md)); Git-Hygiene-Prüfung (12:00Z-Zeitstempel, kanonische Identität) über alle deklarierten Repos | | **C** — zwei Backlogs (F-004, F-009) | `hosts/`-Markdown hielt „Nächste Schritte" neben dem Board | In-Repo-Issues, ein Ort | Wiki-Seiten können wieder Aufgabenprosa ansammeln → Prüfregel: Aufgaben-Marker („Nächster Schritt", offene Checkboxen) in Wiki-Seiten ohne Issue-Verweis sind ein Befund | | **D** — Artefakte ohne Eigentümer überleben (F-006, F-012) | Branches/SHA-Zitate hat niemand je gelesen | `warn_if_orphan` nur für Wiki-Seiten | Branch-Hygiene (Alter/Divergenz verwaister Branches) und SHA-Auflösung inkl. Zuordnungstabelle in der Prüf-Familie; Refinement-Agenda erhält den Punkt | Die sieben neckbeard-Lücken, Disposition (Akzeptanzkriterium 6, 7/7): | # | Lücke | Disposition | |---|---|---| | 1 | Viele Repos, ein Regelwerk | **Eingefaltet:** [ADR-0013](../../adr/0013-gruppenregeln-kanonisch-mit-pruefung.md) (Pointer + Prüfung) | | 2 | Kein Komponenten-Artefakt | **Eingefaltet:** Schema-Typ `component`, `docs/components/` (ADR-0013) | | 3 | Kein Meilenstein-Konzept | **Eingefaltet:** Pflichtfeld `milestone` im Issue-Schema ([ADR-0012](../../adr/0012-issues-im-repo-gitlab-als-spiegel.md)) | | 4 | SHA-Zitate unaufgelöst | **Eingefaltet (projektseitig):** Prüfskript nach Vorbild `inv_shas.py`; Upstream-Kandidat | | 5 | Git-Hygiene außerhalb des Blickfelds | **Eingefaltet (projektseitig):** Hygiene-Prüfung in der CI-Familie; Upstream-Kandidat | | 6 | Externe Link-Ziele ungeprüft | **Teilweise eingefaltet:** Sperrliste stillgelegter Ziele (toter Gitea-Tracker, F-005) als deterministische Prüfung; echte Erreichbarkeitsprüfung **verworfen** (netzabhängig, nichtdeterministisch — widerspricht validate-Philosophie) | | 7 | Prioritätsfeld als YAGNI verworfen | **Eingefaltet:** Pflichtfeld `priority` — der Feldtest liefert die Evidenz (71/71, klar getrennt vom Meilenstein), die das Schöpfungs-AAR fürs Wiedervorlegen verlangte | | +8 | *(neu, diese Session)* `validate.py` lehnt Verzeichnis-Links ab | Migration ersetzt Verzeichnis- durch Datei-Ziele; Upstream-Kandidat (Meinungsfrage) | | +9 | *(neu)* Kein definierter Ort für Projektregeln im übernommenen AGENTS.md | Projektregeln als ausgewiesener eigener Abschnitt unter den unveränderten Upstream-Abschnitten; Upstream-Kandidat | ### Ernte, Teil 2 — Wert des Alt-Ansatzes, eingefaltet (4/4 + Zusatz) | Wert | Erhaltungsmechanismus | |---|---| | **F-014** Issue-Hygiene (Meilensteinpflicht, eine Priorität, ein Status, WIP-Limit, keine ID-Wiederverwendung) | Wird von Konvention zu Schema: `milestone`/`priority` Pflichtfelder, Status-Enum, WIP-Limit als Validator-Regel, Duplikat-ID-Prüfung existiert in `validate.py` bereits; Board bleibt via Spiegel erhalten (ADR-0012) | | **F-013** Mirror-Topologie mit Begründung, Gegenargument, Rettungspfad | Alt-ADRs 0001/0004 werden unverändert portiert; die „Warum zwei Orte"-Prosa und der Rettungspfad ziehen als Wiki-Seiten um; Mirror-Sync bleibt Stillstandsprüfung | | **F-015** Rewrite-Zuordnung, 251/251 verifiziert | `shared/commit-zuordnung-2026-08-07.md` → `docs/sources/` (unveränderlich, agentenschreibgeschützt); SHA-Prüfung löst über die Tabelle auf; die Zuordnungs-Auflage für künftige Rewrites steht im portierten ADR-0009 | | **F-016** Redliche Selbstdokumentation | „Redlichkeit"-Regeln ziehen in den Projektabschnitt von AGENTS.md; AAR-/Retro-Kultur bleibt (AARs → `docs/aar/`, Retro-Protokolle → `docs/sources/`) | | Stillstandsprüfungs-Prinzipien | Bleiben wörtlich: Prüfungen nur aus realen Fällen; „kann nicht prüfen" ist Befund, nicht Skip; Abbruch statt stillem Überspringen; Projektliste zur Laufzeit. Die neuen Gruppen-Prüfungen (ADR-0013, Hygiene, Drift) treten dieser Familie bei | | Board-Pflege-Rechte (Zusage-Spalten nur sorb) | Prozessregel im AGENTS.md-Projektabschnitt; Refinement-Ablauf zieht als Wiki-Seite um und instanziiert die WORKFLOW-Agenda (Board rechts-nach-links, Nachziehen, Entscheidungsvorlagen mit Empfehlung, Datumspflicht) | | ADR-Pflicht bei dauerhaften Ausnahmen | Übernommen in den Projektabschnitt — neckbeard kennt diese Regel selbst nicht (Upstream-Kandidat) | ### Zielarchitektur **Migrationslandkarte** (alt → neu; Inhalte unverändert, sofern nicht werkzeugwidersprechend — Nicht-Ziel „kein Umschreiben"): | Alt | Neu | |---|---| | `CLAUDE.md` | Ein-Zeilen-Pointer; Regeln → `AGENTS.md` (Upstream-Abschnitte wörtlich + Abschnitt „Gruppenregeln"); Karpathy-Block wortgleich → `docs/sources/regelwerk/karpathy-guidelines.md`, aus AGENTS.md zitiert *(freigegeben von sorb, 2026-08-11)* | | `decisions/0001…0011` | `docs/adr/0001…0011`, Frontmatter ergänzt, Text unverändert; `decisions/` entfällt, Verweise nachgezogen | | `roadmap.md` | Bleibt als Linien/Reihenfolge-Prosa; alle Zählungen und „Stand"-Blöcke raus (→ generiertes STATUS.md); M5 statt „offene Frage" (F-001) | | `verfahren/aar/*` (5) | `docs/aar/*`, Frontmatter (`open`/`harvested` nach Retro-Lage) | | `verfahren/retro/*` | `docs/sources/protokolle/*` (unveränderliche Protokolle) | | `verfahren/refinement.md` | `docs/wiki/admin/refinement.md` | | `verfahren/deploy-uebergabe.md` | `docs/wiki/deployment/deploy-uebergabe.md` | | `verfahren/stillstandspruefung.md` | `docs/wiki/admin/stillstandspruefung.md` | | `verfahren/textbloecke.md` | `docs/wiki/admin/textbloecke.md` (Pfade angepasst) | | `verfahren/issue-migration/` | `docs/sources/migration/issue-migration/` | | `verfahren/aar-vorlage.md` | ersetzt durch neckbeards `docs/aar/template.md` | | `hosts/*` (4) | `docs/wiki/admin/.md`; offene Arbeitspunkte → Issues (F-004, 5/5) | | `vision/*` (3) | `docs/wiki/vision/*` (neue Wiki-Area `vision` — Alt-Wert „eine Datei je Linie", altes ADR-0005) | | `shared/branding.md`, `lab-netzwerk.md`, `zone-axion1337.md` | `docs/wiki/architecture/*` | | `shared/commit-zuordnung-2026-08-07.md` | `docs/sources/migration/commit-zuordnung-2026-08-07.md` | | — *(neu)* | `docs/sources/upstream/neckbeard-v0.1.1/` — gepinnte Originale als Baseline für den Drift-Check | | — *(neu)* | `PROJECT.md` ✓, `WORKFLOW.md` (wörtlich v0.1.1), `schema.yaml` (v0.1.1 + ausgewiesene Erweiterungen), `STATUS.md` (generiert), `docs/components/` (6 Deklarationen: 5 Komponenten + management; `game-operating`/`gameserver` als `external`), `docs/issues/` (importierte offene management-Issues + F-004-Nachzügler) | | `scripts/stillstandspruefung.py`, `ci/` | Bleiben; dazu `validate.py`, `gen_status.py` (v0.1.1) und die neuen Prüfskripte; `.gitlab-ci.yml` erhält einen Offline-Job `validate` (jeder Push) neben der geplanten Stillstandsprüfung | **Prüf-Architektur — zwei Familien, scharfe Grenze:** - **Offline & deterministisch** (`validate.py`, `gen_status.py --check`, SHA-Auflösung, Wiki-Aufgabenmarker, Sperrlisten-Check): läuft bei jedem Push, braucht nur den Baum. Kein Netz, keine Uhrzeit. - **Verbund & Laufzeit** (Stillstandsprüfungs-Familie: Mirror-Sync, Issue-Drift Repo↔GitLab, Pointer-Präsenz, Gruppenliste↔`docs/components/`, Git-Hygiene über die Gruppe): geplant/manuell in der Lab-CI, Token über maskierte Variablen, **Abbruch statt stillem Skip**, Befund = rote Pipeline = Alarmanlage. ```mermaid flowchart LR S[Session-Start] --> A[CLAUDE.md → AGENTS.md
+ PROJECT.md + STATUS.md] A --> W[Arbeit nach Gates
Artefakte in docs/] W --> C[Commit 12:00Z] C --> V{CI: validate.py +
gen_status --check} V -- rot --> W V -- grün --> M[Spiegel-Skript
dry-run → sorb triggert] M --> B[GitLab-Board/Meilensteine
= Ansicht, nicht Wahrheit] B --> R[Refinement sonntags
Board + STATUS.md] R --> W P[Stillstandsprüfung + Gruppen-Checks
geplant, Lab-CI] -. Befund = Issue .-> R ``` ### Entscheidungen Die zwei tragenden Richtungsentscheidungen stehen als ADRs (Status `proposed`, werden mit diesem Gate wirksam): - **[ADR-0012](../../adr/0012-issues-im-repo-gitlab-als-spiegel.md)** — Issues im Repo kanonisch (Management-Scope), GitLab als deterministisch bespielter Spiegel; Optionen A/B/C abgewogen im ADR. - **[ADR-0013](../../adr/0013-gruppenregeln-kanonisch-mit-pruefung.md)** — Gruppenregeln kanonisch hier, Komponenten tragen Pointer, ein Komponenten-Artefakt macht die Gruppe prüfbar; Kopie/Submodule verworfen im ADR. Feature-lokale Entscheidungen (bleiben hier): 1. **Framework-Dateien wörtlich** übernehmen (AGENTS.md-Abschnitte 1–5, WORKFLOW.md, Templates, Skripte) — jede Abweichung vom Upstream bleibt per Diff gegen v0.1.1 sichtbar; Projektspezifika leben ausschließlich im ausgewiesenen AGENTS-Abschnitt, in ADRs, Wiki und `schema.yaml`-Erweiterungen. 2. **Issue-Nummern:** GitLab-iid = Datei-id für Importierte; neue Issues zählen ab Maximum weiter; `gitlab_iid`-Feld hält die Spiegelung. Keine dritte Nummernwelt, keine ID-Wiederverwendung. 3. **Status-Enum erweitert** um `next` und `waiting` (Grund-Pflicht bei `waiting`) — die Board-Spalten sind belegter Alt-Wert; ein Mapping auf nur `open/in-progress` würde die einzige Zusage-Semantik (`status:next`) wegwerfen. 4. **Slugs werden nicht umbenannt** (F-008): Rename = Forge-Eingriff, eigenes Issue; das Komponenten-Artefakt dokumentiert den Ist-Stand. 5. **Verzeichnis-Links** in Prosa werden auf Datei-Ziele umgestellt (Lücke +8). 6. **`analysis/` und `drafts/`** des Analyse-Branches bleiben dort; nichts davon wird auf diesen Branch geholt. 7. **`docs/sources/` wird nach Quellenart untergliedert** (Vorschlag sorb, 2026-08-11): `regelwerk/` (wortgleiche Regeltexte), `upstream/` (gepinnte Framework-Originale), `protokolle/` (Retro-/Workshop-Protokolle), `migration/` (Zuordnungen, Umzugsunterlagen). Kriterium bleibt *lebendig → Wiki, unveränderlich → sources*; AARs sind Artefakte mit Lebenszyklus, keine Quellen. 8. **Drift-Check gegen Upstream-Baseline:** die v0.1.1-Originale liegen unter `docs/sources/upstream/neckbeard-v0.1.1/`; ein Offline-Check vergleicht die Instruktionsdateien (CLAUDE.md-Pointer, AGENTS.md bis zur Projektabschnitts-Marke, WORKFLOW.md, Templates) byteweise. Stilles Umschreiben durch eine Session wird damit roter Befund; Framework-Upgrade = bewusste Baseline-Aktualisierung. `schema.yaml` und die Skripte sind **erklärt projekterweitert** — Original liegt zur Diffbarkeit bei, wird aber nicht byte-erzwungen. 9. **AGENTS.md-Änderungsschutz:** die alte Fußzeilen-Regel zieht in den Projektabschnitt um — Änderungen an AGENTS.md nur mit sorb abgestimmt. 10. **Issue-Import liest Beschreibungstexte** der offenen management-Issues read-only über den Token (freigegeben von sorb, 2026-08-11); Kommentare bleiben auf GitLab, der Tokenwert erscheint nirgends. ### Constraints - Mirror-Topologie unangetastet: Flux-Quelle bleibt Gitea, keine direkten Gitea-Pushes, Kanonisierungs-Verfahren gilt weiter. - Kein API-Schreibzugriff ohne menschlichen Trigger; das Spiegel-Skript hat `--dry-run` als Default. Diese Session pusht nichts. - Commit-Konventionen (englisch, 12:00:00 UTC, kanonische Identität) gelten für jeden Migrations-Commit. - Artefaktsprache Deutsch (`PROJECT.md`), Upstream-Framework-Texte bleiben englisch — der Diff-Abgleich gegen v0.1.1 wiegt schwerer als Sprachreinheit. - Secrets-Regeln unverändert (Token nur per Pfad/maskierter Variable). - Die Historien-Remediation (F-002/F-003) bleibt draußen; jedes künftige Rewrite trägt die Zuordnungs-Auflage (portiertes ADR-0009). ### Rückmeldungen an neckbeard (Kandidaten, eigener Akt — nicht Teil dieser Undertaking) Lücken 1–5 und 7 mit Feldtest-Evidenz, dazu +8 (Verzeichnis-Links), +9 (Ort für Projektregeln), die fehlende ADR-Pflicht bei dauerhaften Ausnahmen, und als Erfahrungswert: die Stillstandsprüfungs-Prinzipien (Prüfungen nur aus realen Fällen; Abbruch statt Skip) als Muster für eine künftige Laufzeit-Prüf-Familie neben `validate.py`. ## Gate 3 — Programm-Design ### Dateiorte (vollständig) **Wurzel — neu:** `AGENTS.md` (Upstream §1–5 wörtlich, dann Marke ``, dann „§6 Gruppenregeln"), `WORKFLOW.md` (wörtlich v0.1.1), `schema.yaml` (v0.1.1 + Erweiterungen, im Kopf ausgewiesen), `STATUS.md` (generiert). **Wurzel — geändert:** `CLAUDE.md` → Pointer (wörtlich v0.1.1), `roadmap.md` (Zahlen/„Stand" raus, M5 rein, Datei-Links), `README.md` (Pfade/Struktur nachgezogen, Datei-Links), `.gitlab-ci.yml` (+ Job `validate`, Stage `pruefen`, bei jedem Push). **Wurzel — entfällt (git mv):** `decisions/`, `hosts/`, `verfahren/`, `vision/`, `shared/`. **`docs/adr/`:** `0001…0011` portiert (Frontmatter ergänzt; Datum = Original-Datum; Body unverändert bis auf umgezogene Link-Ziele), `0012`/`0013` (accepted), `template.md` (v0.1.1). **`docs/aar/`:** die 6 AARs aus `verfahren/aar/` (Dateinamen bleiben, Frontmatter: die vier vom 2026-08-01/02 `harvested` — von der Retro 2026-08-09 geerntet; `2026-08-09-refinement-und-betrieb.md` und `2026-08-11-apo-calls-profile-zeile.md` `open`), `template.md` (v0.1.1; ersetzt `aar-vorlage.md`). **`docs/issues/`:** Import aller offenen management-Issues als `NNNN-slug.md` (NNNN = GitLab-iid, vierstellig; Slug deterministisch aus dem Titel: Kleinbuchstaben, Umlaute ae/oe/ue/ss, sonst `-`, Alt-IDs bleiben im Titel), plus 5 neue Issues für die F-004-Arbeitspunkte (IDs ab max(iid)+1), `template.md` (v0.1.1). **`docs/components/`:** `management.md`, `threadnet-call.md`, `thread-net-git.md`, `threadnet-operating.md`, `axion1337.chat-gitops.md`, `ThreadNet-Web.md` (Dateiname = Slug, buchstabengetreu), dazu `game-operating.md`, `gameserver.md` (`phase: external`). **`docs/wiki/`:** `index.md` (projektangepasst: Area-Tabelle + `vision`; nicht in der Baseline), `admin/`: `cfgmon.md`, `game.md`, `matrix.md`, `overmind.md`, `refinement.md`, `stillstandspruefung.md`, `textbloecke.md`; `deployment/`: `deploy-uebergabe.md`; `architecture/`: `branding.md`, `lab-netzwerk.md`, `zone-axion1337.md`; `vision/`: `axion1337-chat.md`, `homelab.md`, `threadnet.md`. **`docs/sources/`:** `regelwerk/karpathy-guidelines.md`; `upstream/neckbeard-v0.1.1/` (AGENTS.md, CLAUDE.md, WORKFLOW.md, schema.yaml, die 4 Templates, validate.py, gen_status.py, dazu `HERKUNFT.md` mit Tag/SHA); `protokolle/retro-2026-08-09.md`; `migration/commit-zuordnung-2026-08-07.md`, `migration/issue-migration/README.md`, `migration/import_issues.py` + `migration/issue-import-protokoll.md` (Einmal-Werkzeug und sein Protokoll — Aufzeichnung, kein Dauerbetrieb). **`scripts/`:** `validate.py` (v0.1.1 + 3 Regeln), `gen_status.py` (v0.1.1 + Meilenstein-/Prioritätsspalten und -verteilung), `pruefe_upstream_drift.py` (neu), `pruefe_prosa.py` (neu), `gruppenpruefung.py` (neu), `spiegel_issues.py` (neu); `stillstandspruefung.py` unangetastet. ### Schema-Erweiterungen (exakt) ```yaml # issue — zusätzlich: required: [type, id, status, created, milestone, priority] status: { enum: [open, next, in-progress, waiting, done, rejected] } milestone: { enum: [M1, M2, M3, M4, M5] } priority: { enum: [high, medium, low] } due: { kind: date, nullable: true } host: { enum: [cfgmon, overmind, matrix, game], nullable: true } area: { enum: [security, infrastructure, database, element], nullable: true } wartegrund: { kind: str, nullable: true } gitlab_iid: { pattern: "^\\d+$", nullable: true } rules: [waiting_requires_reason] # + global: wip_limit # component — neuer Typ: component: dir: "docs/components" filename: "^[A-Za-z0-9.-]+\\.md$" required: [type, slug, anzeigename, phase] fields: slug: { kind: str } # rule: slug_matches_filename anzeigename: { kind: str } phase: { enum: [active, staged, external] } gitlab: { kind: str } mirror: { kind: str, nullable: true } related: { kind: links } rules: [slug_matches_filename] # wiki-page.area — Enum + vision ``` ### Signaturen (keine Rümpfe) ```text validate.py [repo-root] # + Regeln: wip_limit (≤2 in-progress, repoweit), # waiting_requires_reason, slug_matches_filename gen_status.py [--check] [repo-root] # Issues-Tabelle + Spalten milestone/priority # + Verteilungszeile je Meilenstein pruefe_upstream_drift.py [repo-root] # Byte-Vergleich Arbeitsdatei ↔ sources/upstream; # AGENTS.md: Präfix bis Marke; exit 1 bei Abweichung pruefe_prosa.py [repo-root] # (a) SHA-Zitate in docs/** + Wurzel-*.md auflösen # (git cat-file, sonst Zuordnungstabelle, sonst FEHLER) # (b) Aufgabenmarker in docs/wiki/** ohne Issue-Verweis # (c) Sperrliste stillgelegter URL-Muster (toter Gitea-Tracker) gruppenpruefung.py # Lab-CI, Token aus Umgebung, Abbruch ohne Token: # Gruppenliste (Laufzeit) ↔ docs/components/; # Pointer-Präsenz je active/staged-Komponente; # Issue-Drift docs/issues ↔ GitLab (Titel/Status/ # Meilenstein/Priorität); Meilenstein- und # Prioritätspflicht über ALLE offenen Gruppen-Issues # (realer Fall: gitops#61, siehe Nachtrag); # Git-Hygiene (Commits nach # 2026-08-07 ≠ 12:00:00Z oder fremde Identität = Befund) spiegel_issues.py [--ausfuehren] # Default Dry-Run: druckt geplante API-Aufrufe; # --ausfuehren nur durch sorb; Repo → GitLab, nie zurück ``` **CI-Fluss:** Job `validate` (jeder Push, offline): `validate.py && gen_status.py --check && pruefe_upstream_drift.py && pruefe_prosa.py`. Job `stillstandspruefung` (geplant/manuell) wie bisher; `gruppenpruefung` daneben, gleiche Regeln (rot = Alarm, Abbruch statt Skip). ### Was die Prüfungen zusichern (inkl. Muster-Demonstration, Kriterium 5) | Prüfung | Zusicherung / Demo | |---|---| | Negativtests (Scratch-Bäume, je Regel einer) | 3× in-progress → Fehler; `waiting` ohne `wartegrund` → Fehler; Component-Slug ≠ Dateiname → Fehler; 1 Byte Abweichung in WORKFLOW.md → Fehler; Schöpfungs-AAR-Lehre: grüner Validator ohne Negativtest zählt nicht | | **Muster A** | Meilenstein-Abgleich gegen den eingefrorenen Session-1-Export: Alt-`CLAUDE.md` („M1–M4") ↔ Export (M5 existiert) → feuert | | **Muster B** | Git-Hygiene über die lokalen Komponenten-Klone → feuert (Erwartung: die 237 Echtzeit-Commits aus F-002) | | **Muster C** | `pruefe_prosa.py` auf dem Vor-Migrations-Stand von `hosts/` → feuert auf die 5 F-004-Punkte; nach Migration: 0 | | **Muster D** | SHA-Auflösung auf Vor-Migrations-Stand → feuert auf die 6 verwaisten Zitate aus F-012; Auflösung über die Zuordnungstabelle nachgewiesen | ### DO NOT CHANGE - Der Analyse-Branch und alles unter `analysis/`. - Substanz der portierten Texte: ADR-Bodies, AARs, Retro, Zuordnung, Karpathy-Block, Hosts-/Visions-Prosa — nur Umzug, Frontmatter, Link-Ziele; inhaltliche Korrektur **nur** wo ein Dokument dem Werkzeugstand widerspricht (roadmap M5, Alt-CLAUDE-Regeln gehen in AGENTS §6 in korrigierter Fassung). - `scripts/stillstandspruefung.py`, `ci/lab-ca-chain.crt`, `.gitlab/issue_templates/` — unangetastet. - GitLab-Zustand: kein Issue, Label, Meilenstein, Board wird verändert; `spiegel_issues.py` läuft in dieser Undertaking nur als Dry-Run. - Kein `git push`; Tokenwert erscheint in keiner Ausgabe. - Upstream-Framework-Texte §1–5 / WORKFLOW / Templates: byte-treu. ### Wackligste Annahmen (benannt, Stand Gate 3) 1. **AAR-Erntestatus**: „die vier alten AARs sind geerntet" schließe ich aus der Retro-Existenz, nicht aus einer Erntemarke — sorb kann das im Refinement kippen. 2. **Enums aus dem Ist-Stand eingefroren** (host/area/M1–M5): jeder neue Host oder Meilenstein braucht künftig einen Schema-Commit. Gewollt (sichtbare Änderung), aber Reibung. 3. **Slug-Erzeugung aus deutschen Titeln** muss deterministisch und kollisionsfrei sein; bei Kollision entscheidet die iid, nicht der Slug. 4. **Git-Hygiene per API vs. lokale Klone**: die Demo läuft auf den lokalen Klonen; die CI-Fassung per API kann bei großen Historien paginieren müssen — begrenzt auf Commits seit 2026-08-07. 5. **Verdichtung von Alt-CLAUDE.md nach AGENTS §6**: Welche Sätze Regelrang behalten und welche ins Wiki wandern, ist Urteilssache; Volltext überlebt in ADRs/Wiki/sources, aber eine tragende Nuance könnte aus dem Immer-geladen-Teil fallen. 6. **`gen_status.py`-Fork-Tiefe**: je mehr das Generat zeigt, desto weiter entfernt es sich vom Upstream; gewählt ist die kleinste Erweiterung, die die Roadmap-Zahlen ersetzt. ### Nachtrag 2026-08-11 — die Realität lief nach Gate-3-Freigabe weiter Hinweis von sorb bei der Gate-3-Freigabe, per Fetch und Live-API (read-only) verifiziert: - **management `main` +3 Commits:** AAR `2026-08-11-apo-calls-profile-zeile.md` (+ Nachtrag) und — kritisch — **`decisions/0011`** (Enrollment-Localpart-Kollision). Das alte Schema zählt parallel weiter; die Session-ADRs kollidierten mit der Nummer und wurden zu **0012/0013** umnummeriert (genau die Duplikat-ID-Klasse, die `validate.py` künftig mechanisch meldet). Branch auf `origin/main` rebasiert. - **gitops +2 Commits** (MAS-Fix, Runbook); beide und alle drei management-Commits halten die Hygiene-Regeln (12:00:00Z, kanonische Identität) — geprüft. - **Live-Backlog: 72 offen** (Import zählt beim Lauf, nicht aus diesem Text). **gitops#61 trägt keinen Meilenstein** und das neue Label `area:authentik` — die 100%-Meilenstein-Disziplin (F-014) ist binnen zwei Tagen real gerissen. Konsequenz: `gruppenpruefung.py` prüft die Meilenstein-/Prioritätspflicht über alle offenen Gruppen-Issues (der reale Fall, den die Stillstandsprüfungs-Regel für neue Prüfungen verlangt, existiert hiermit). Management-Scope: 26 offene Issues, iids 1–32. - Zahlen im Dokument nachgezogen: 11 Alt-ADRs, 6 AARs, Akzeptanzkriterium 2 = 11/11. Die Enums bleiben, wie in Annahme 2 benannt, aus dem management-Scope abgeleitet; `area:authentik` liegt außerhalb (gitops) und wird erst bei dessen Adoption Schema-Thema. ## Gate 4 — Vertikale Slices Jeder Slice endet mit Nachweis, Status und **STOP**. **Slice 1 — Tracer Bullet: die Framework-Kette läuft Ende-zu-Ende.** Baseline (`docs/sources/upstream/neckbeard-v0.1.1/` + `HERKUNFT.md`), Karpathy-Block wortgleich nach `docs/sources/regelwerk/`, `AGENTS.md` (§1–5 byte-treu + §6 Gruppenregeln), `CLAUDE.md`-Pointer, `WORKFLOW.md`, Templates, erweitertes `schema.yaml`, `validate.py` (+3 Regeln), `gen_status.py` (Fork), `pruefe_upstream_drift.py`, generiertes `STATUS.md`, CI-Job `validate`, README-Verzeichnis-Link entschärft. *Verify:* validate 0 Fehler · gen_status --check aktuell · Drift-Check grün · vier Negativtests feuern · Baseline byte-identisch zur Referenz. **Slice 2 — ADR-Port.** `decisions/0001…0011` → `docs/adr/` mit Frontmatter, Verweise nachgezogen, `decisions/` entfällt. *Verify:* 11/11 validieren, Duplikat-ID-Prüfung greift, validate grün. **Slice 3 — Wiki, Sources, AARs.** `verfahren/`/`hosts/`/`vision/`/ `shared/` an ihre Zielorte, Wiki-Index, `pruefe_prosa.py`; Demos Muster C (F-004-Punkte auf Vor-Stand) und D (6 verwaiste SHAs). *Verify:* validate + pruefe_prosa grün auf Endstand, Demos feuern auf Vor-Stand, alte Wurzelordner leer. **Slice 4 — Issue-Import.** `import_issues.py` liest die offenen management-Issues live (read-only), 26+ Dateien + 5 F-004-Issues, `roadmap.md` verliert Zahlen an STATUS.md. *Verify:* alle Issue-Dateien validieren (Pflicht-Meilenstein/-Priorität), Import-Protokoll unter sources/migration, Muster-C-Endstand = 0. **Slice 5 — Komponenten, Gruppenprüfung, Spiegel.** 8 Komponenten-Deklarationen, `gruppenpruefung.py` (+ CI-Job), `spiegel_issues.py` (Dry-Run-Demo); Demos Muster A (eingefrorener Export ↔ Alt-CLAUDE) und B (Hygiene über lokale Klone), Live-Befund gitops#61. *Verify:* Dry-Run-Ausgabe plausibel, Demos feuern, kein API-Write. Alle fünf Slices sind mit Nachweis und STOP abgenommen worden (Freigaben sorb, 2026-08-11); die Commits `e36ed33`…`865d761` tragen die Evidenz je Slice im Commit-Text. ## Gate 5 — Closeout (AAR) ### Geplant Gate 0–5 nach WORKFLOW.md; Zwei-Wege-Ernte vor Übernahme (bindende Vorgabe der Session-1-Übergabe); fünf Slices; sechs Akzeptanzkriterien. ### Tatsächlich Alle Gates und Slices wie geplant, mit vier realitätsgetriebenen Abweichungen: 1. **Die Realität lief während der Undertaking weiter** (Hinweis sorb bei Gate-3-Freigabe): `main` +3 Commits mit `decisions/0011` → Nummernkollision mit den Session-ADRs, Umnummerierung auf 0012/0013, Rebase; gitops#61 entstand **ohne Meilenstein** und riss die 100%-Disziplin aus F-014 binnen zwei Tagen — es wurde der reale Fall für die neue gruppenweite Pflicht-Prüfung. 2. **F-004 war feiner als der Befund:** MATRIX-05 seit 2026-08-01 erledigt (kein Issue nötig — „Alles *Offene* ist ein Issue"), CFGMON-12/13 bereits per git.lab-Issues verfolgt (nur die toten Gitea-Links verdeckten das). Statt 5/5 neuen Issues: 2 neue (0033, 0034), 2 verifizierte Verweise, 1 begründeter Verzicht — mit sorb abgestimmt; Details im [Import-Protokoll](../../sources/migration/issue-import-protokoll.md). 3. **F-005 war größer als der Befund:** nicht ein toter Tracker-Link, sondern acht, quer durch Host-Seiten und einen importierten Issue-Fußtext; zwei per Live-Titelabgleich verifiziert umgezogen, sechs zu ehrlichen Historien-Zitaten entschärft. 4. **Hex ist nicht gleich Git-SHA:** die SHA-Prüfung fand eine Authentik-uid und zwei Alertmanager-Silence-IDs — gelöst über die kuratierte Ausnahmenliste mit Grund je Zeile statt über eine schlauere Heuristik. Akzeptanzkriterien: **6/6 erfüllt** — (1) alle deterministischen Gates grün; (2) 11/11 ADRs portiert; (3) 0 issuelose Arbeitspunkte im Wiki, F-004-Disposition dokumentiert; (4) 0 Handzählungen, kein Dokument widerspricht dem Werkzeugstand M1–M5; (5) 4/4 Muster-Demos gefeuert (A: „M1–M4"↔M5-Export; B: 222 Echtzeit-Commits, deckungsgleich mit den Session-1-Zahlen; C: 6→0 Aufgabenblöcke; D: verwaiste SHAs aufgelöst oder kuratiert); (6) 9/9 Lücken-Dispositionen und 4/4 Erhaltungsmechanismen in Gate 2, final abgehakt. ### Warum die Differenz Die Undertaking hat einen lebenden Verbund migriert, keinen eingefrorenen: Jede Abweichung entstand daraus, dass zwischen Analyse (2026-08-09/10) und Bau (2026-08-11) weitergearbeitet wurde. Genau die Driftklassen, die die Migration schließen soll, traten währenddessen frisch auf — und wurden zu Testfällen statt zu Störungen. ### Lehren (geerntet nach [Stolpersteine](../../wiki/stolpersteine/neckbeard-migration.md)) - Ein hexförmiges Wort ist nicht automatisch ein Git-SHA; kuratierte Ausnahmen mit Grund schlagen schlauere Raterei. - Der Link-Checker ist das beste Umzugswerkzeug: erst bewegen, dann die gemeldeten Ziele reihum fixen — kein Verweis blieb offen. - Frische Importe sind Prüfmaterial: beide Prosa-Prüfungen fanden auf den eben importierten Texten sofort echte Fälle. - Bestätigt aus dem Upstream-Schöpfungs-AAR: ein grüner Validator zählt erst mit Negativtests (vier gebaut, alle feuern). - `gen_status.py` braucht lokal Python ≥ 3.10 (`write_text(newline=)`); CI nutzt 3.12, lokal läuft ein venv. - Session-1-Lehre erneut bestätigt: `TZ` gehört an den git-Prozess (`--date=format-local` + `TZ=UTC` in `gruppenpruefung.py`). ### Wackligste Entscheidungen dieser Session (WORKFLOW.md, Session-Ende) 1. **AAR-Erntestatus der vier alten AARs** aus der Retro-Existenz geschlossen, nicht aus einer Erntemarke — beim nächsten Refinement gegenprüfen. 2. **Die §6-Verdichtung der Alt-CLAUDE.md**: von sorb quergelesen und freigegeben, aber ob jede tragende Nuance den Sprung geschafft hat, zeigt erst der Betrieb. 3. **Generische `wartegrund`-Platzhalter** bei 7 importierten waiting-Issues — Issue 0041. 4. **Die fünf eigenen Identitäten stehen als Konstante im Hygiene-Skript** — bei einer künftigen Identitäts-Remediation (F-003) muss die Liste mitgepflegt werden. 5. **Spiegelumfang bewusst schmal** (keine Beschreibungen): richtig für Kommentar-Erhalt, heißt aber, dass Beschreibungs-Änderungen im Repo auf GitLab nicht sichtbar werden — Board-Nutzer sehen den Stand der Migration, nicht jede Textpflege. ### Offene Folgearbeit (als Issues, nicht als Prosa) [0035–0039](../../issues/0035-rollout-agents-pointer-axion1337-chat-gitops.md) Pointer-Rollout je Komponente (fünf Issues) · [0040](../../issues/0040-neckbeard-rueckmeldungen-einreichen.md) neckbeard-Rückmeldungen einreichen · [0041](../../issues/0041-wartegrund-der-importierten-waiting-issues.md) wartegrund präzisieren · [0042](../../issues/0042-migration-in-betrieb-nehmen-push-spiegel-schedule.md) Inbetriebnahme (Push, erster Spiegel-Lauf, CI-Schedule).