management/docs/design/done/2026-08-11-neckbeard-migration.md

---
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/<host>.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<br/>+ PROJECT.md + STATUS.md]
    A --> W[Arbeit nach Gates<br/>Artefakte in docs/]
    W --> C[Commit 12:00Z]
    C --> V{CI: validate.py +<br/>gen_status --check}
    V -- rot --> W
    V -- grün --> M[Spiegel-Skript<br/>dry-run → sorb triggert]
    M --> B[GitLab-Board/Meilensteine<br/>= Ansicht, nicht Wahrheit]
    B --> R[Refinement sonntags<br/>Board + STATUS.md]
    R --> W
    P[Stillstandsprüfung + Gruppen-Checks<br/>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
`<!-- projektabschnitt -->`, 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).