docs: design doc Gate 2 (architecture) with ADR-0011 and ADR-0012

Two-way harvest as mandated by the Session-1 handoff: failure patterns
of both approaches tabled with the mechanism that closes each, all
seven neckbeard gaps dispositioned (plus two new ones found this
session), and the old approach's proven value folded into the target
architecture. Two directional decisions filed as proposed ADRs: issues
live in-repo with GitLab as a deterministically mirrored view (0011),
group rules canonical here with pointer components and a checkable
components artifact (0012). Migration map, check architecture split
offline/runtime, constraints, upstream feedback candidates.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

@@ -1,6 +1,6 @@
 ---
 type: design
-status: gate-1
+status: gate-2
 date: 2026-08-11
 size: L
 related:
@@ -8,6 +8,8 @@ related:
   - "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
@@ -127,3 +129,166 @@ Quelle starten, die sich nicht selbst widerspricht.
 
 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`.