docs: design doc Gate 3 (program design)
Complete target file map, exact schema extensions, script signatures without bodies, CI flow, per-check assertions including the four pattern demonstrations and negative tests, DO NOT CHANGE boundaries, and the six shakiest calls named. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Thore Cimbal
co-authored by
Claude Fable 5
Claude Fable 5
parent
bff1ca4477
commit
0cce6f641c
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
type: design
|
type: design
|
||||||
status: gate-2
|
status: gate-3
|
||||||
date: 2026-08-11
|
date: 2026-08-11
|
||||||
size: L
|
size: L
|
||||||
related:
|
related:
|
||||||
@@ -314,3 +314,161 @@ Lücken 1–5 und 7 mit Feldtest-Evidenz, dazu +8 (Verzeichnis-Links), +9
|
|||||||
Ausnahmen, und als Erfahrungswert: die Stillstandsprüfungs-Prinzipien
|
Ausnahmen, und als Erfahrungswert: die Stillstandsprüfungs-Prinzipien
|
||||||
(Prüfungen nur aus realen Fällen; Abbruch statt Skip) als Muster für
|
(Prüfungen nur aus realen Fällen; Abbruch statt Skip) als Muster für
|
||||||
eine künftige Laufzeit-Prüf-Familie neben `validate.py`.
|
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…0010` portiert (Frontmatter ergänzt; Datum =
|
||||||
|
Original-Datum; Body unverändert bis auf umgezogene Link-Ziele),
|
||||||
|
`0011`/`0012` (accepted), `template.md` (v0.1.1).
|
||||||
|
**`docs/aar/`:** die 5 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` `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); 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user