Karpathy-Wiki-Audit & docs/-Pflicht via Pre-Commit-Hook

Treue-Audit gegen Karpathys LLM-Wiki-Gist: welche Karpathy-Mechaniken sind in docs/ implementiert, welche fehlen, welche werden nicht durchgesetzt. Plus: Mechanik, mit der die identifizierten Lücken nicht nur dokumentiert, sondern per Git-Pre-Commit-Hook erzwungen werden.

1. Ausgangslage: Karpathy vs. solcom

Karpathy beschreibt ein dreischichtiges Wissens-System (Raw / Wiki / Schema) mit drei Operationen (Ingest / Query / Lint) plus zwei Spezialfiles (index.md, log.md). Im solcom-Repo ist die Grundstruktur bereits da — siehe CLAUDE.md → Karpathy-Wiki-Adaption.

Drei Karpathy-Mechaniken sind nicht (oder nur teilweise) abgebildet: Multi-Page-Updates beim Ingest, Refile von Query-Antworten als Wiki-Pages, und der Suggestion-Style-Anteil des Lints (Karpathy-Regeln 1, 4, 5, 6). Zusätzlich: keinerlei Pflicht-Durchsetzung — alles ist opt-in pro Skill-Goodwill.

2. Lücken-Befunde (Grilling 2026-05-11)

3. Entscheidungen aus dem Grilling

4. Phasen-Plan

Fünf Phasen, eine PR pro Phase. Reihenfolge so, dass jede Phase ihre Vorgänger nutzt — der Hook (P2) braucht das CLI-Script aus P1, der Curator-Skill (P5) baut auf die Wiki-Stitch-Mechanik aus P3.

5. Spec-Schärfungen für die neuen Lint-Regeln

Regel missing-entities (deterministisch)

• Sammle alle solcom:tags aus docs/adr/*.html + docs/stories/*.html + docs/context/*.html.
• Bilde Frequenz pro Tag.
• Für jeden Tag mit Frequenz ≥ N=3: prüfe, ob eine Wiki-Entity mit diesem Tag in solcom:tags existiert.
• Wenn nein → Flag [missing-entities] tag=<tag> — Vorkommen in N ADRs/Stories/Context, keine passende Wiki-Page.

Threshold N=3 kongruent zu wiki/INVENTORY.html-Boundary („drei oder mehr Strang-Verweise rechtfertigen eine Wiki-Page").

Regel missing-cross-refs (deterministisch)

• Pro Wiki-Page unter docs/wiki/:
• Body-Pass: grep -oE 'ADR-[0-9]{4}|adr/0[0-9]{3}-' <file> → Set von erwähnten ADR-Nummern.
• Frontmatter-Pass: solcom:related-adrs-Meta → Set von deklarierten ADR-Nummern.
• Wenn Body-Set ⊄ Frontmatter-Set: Flag [missing-cross-refs] wiki/<page> → ADR-NNNN im Body erwähnt, aber nicht in related-adrs-Meta.

6. Wiki-Entity-Kandidaten

Aktuell: 3 Entities (mittwald-stack, card-family, canvas-integration). Karpathys impliziter Ziel-Range: 10–20+ bei vergleichbarer Source-Anzahl. Erste Kandidaten — pro Kandidat: aggregierte Refs + 1-Satz-Begründung. Reihenfolge ist Vorschlag, nicht Pflicht.

7. Out-of-Scope

• qmd-Search-Engine — bei aktueller Skala (≈64 Files) reicht docs/index.html + grep. Cross-platform via npm/bun lauffähig, aber Node-Toolchain im Repo nicht etabliert. Re-Evaluierung bei >200 docs/-Files.
• LOG.json-Mirror — Karpathys grep-Trick bleibt als Bash-Snippet im LOG-Header dokumentiert; eigene strukturierte Mirror-Datei verdoppelt nur die Wartung.
• Claude PostToolUse-Hook für docs/ — Git-Pre-Commit ist robuster (greift auch außerhalb Claudes), wird beim eigentlichen Commit ausgelöst statt bei jedem Mini-Edit.
• Voller CLI-Port von solcom-docs-lint — fokussiertes .hooks/docs-lint.sh reicht für Pre-Commit-Zweck. Skill bleibt für interaktive Full-Sweeps.
• Wiki-Bau direkt im Audit — Wiki-Entity-Kandidaten in Sektion 6 sind Vorschläge, nicht Auftrag dieser Phase. Bau läuft via html-doc-authoring einzeln.

8. Offene Fragen

• Trockenlauf-Reaktion: Was, wenn .hooks/docs-lint.sh beim ersten Lauf gegen bestehenden Repo > 10 false positives pro Klasse zeigt? — Pre-Commit-Hook wird nicht aktiviert, Regeln werden geschärft. Iterativ.
• Bestehende Drift vor Hook-Aktivierung: Vorhandene Verstöße (z. B. ADRs ohne LOG-Eintrag) bewusst akzeptieren oder erst aufräumen? — Empfehlung: Hook nur für staged Files, alte Drift wird durch reguläre solcom-docs-lint-Läufe sichtbar gemacht, nicht durch Commit-Block.
• Curator-Skill Trigger-Phrasen: Wann genau soll der LLM-Lint laufen? Manuell („docs curator", „contradictions check") oder als optionaler Pre-PR-Step? — Erstmal nur manuell; PR-Hook wäre Phase 6.