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

---
type: design
status: gate-2
date: 2026-08-11
size: L
related:
  - "PROJECT.md"
  - "decisions/0005-pm-framework-kanban.md"
  - "decisions/0009-commit-konventionen-und-historien-anonymisierung.md"
  - "decisions/0010-haertung-eigener-meilenstein.md"
  - "docs/adr/0011-issues-im-repo-gitlab-als-spiegel.md"
  - "docs/adr/0012-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 10 Entscheidungen
   (`decisions/0001…0010`) liegen als ADRs mit schema-konformem
   Frontmatter unter `docs/adr/` — 10/10 validieren.
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](../../verfahren/refinement.md),
[verfahren/stillstandspruefung.md](../../verfahren/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-0012](../adr/0012-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-0012](../adr/0012-gruppenregeln-kanonisch-mit-pruefung.md) (Pointer + Prüfung) |
| 2 | Kein Komponenten-Artefakt | **Eingefaltet:** Schema-Typ `component`, `docs/components/` (ADR-0012) |
| 3 | Kein Meilenstein-Konzept | **Eingefaltet:** Pflichtfeld `milestone` im Issue-Schema ([ADR-0011](../adr/0011-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-0011) |
| **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-0012, 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/karpathy-guidelines.md`, aus AGENTS.md zitiert *(Freigabe sorb nötig — stehende Regel)* |
| `decisions/0001…0010` | `docs/adr/0001…0010`, 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/retro/*` (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/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/commit-zuordnung-2026-08-07.md` |
| — *(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-0011](../adr/0011-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-0012](../adr/0012-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.

### 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`.