@renoxar/koolie 1.25.0

package/.koolie/core/docs/DOCUMENTATION_STANDARD.md

@@ -0,0 +1,91 @@
+# Dokumentationsstandard – Klassen, Kriterien und Prüfungen
+
+| Attribut | Wert |
+|---|---|
+| ID | `FW-DOC-STANDARD` |
+| Version | `0.2.0` |
+| Status | `pilot` |
+| Owner (Rolle) | `<FRAMEWORK_OWNER>` |
+| Entscheidungen | D-371 bis D-380 (`CR-2026-142`), D-437 (`CR-2026-154`) |
+
+## Zweck
+
+Dieses Dokument legt fest, **wann ein Dokument des Frameworks in Ordnung ist**: welche Dokumente es gibt, welche Kriterien je Dokument gelten und welche davon eine Maschine prüft. Es gilt für jedes Release; `.koolie/core/checklists/11-framework-release.md` verweist darauf.
+
+Ohne vorab festgelegte Kriterien hat eine Durchsicht kein Ende (D-370) – und ohne Prüfung ist derselbe Befund in drei Releases wieder da.
+
+## 1. Die vier Klassen (D-371)
+
+Jedes Markdown-Dokument des Kerns gehört genau einer Klasse an, oder es ist Nachweis. **Die Zuordnung steht an einer Stelle:** in der Funktion `dokumentklasse()` von `.koolie/core/tests/scripts/validate-framework.py`. Dieses Dokument beschreibt sie, es zählt sie nicht ein zweites Mal auf.
+
+| Klasse | Was | Beispiele |
+|---|---|---|
+| **A – Einstieg** | was jemand liest, der das Framework zum ersten Mal einsetzt | die Einstiegsdokumente der Wurzel – `README.md`, `QUICKSTART.md` und ihre englischen Fassungen `README.en.md`, `QUICKSTART.en.md` (nur im Framework-Repositorium, D-437) –, `onboarding/`, `examples/`, `pilot/`, `docs/ADOPTION_GUIDE.md`, `docs/RUNTIME_GLOSSARY.md`, `clients/README.md`, die `CLIENT_PACK.md` der Packs |
+| **B – Regeln** | was gilt | Core-Module, Laufzeitschicht, Governance-Prozesse, Checklisten, Entscheidungsbäume, Prompts, Vorlagen, Skills, dieses Dokument |
+| **C – Register** | Belege und Verzeichnisse | `CHANGELOG.md`, `governance/DECISION_LOG.md`, `docs/ROADMAP.md`, `tests/TEST_CATALOG.md`, `tests/EDGE_CASES.md`, `docs/PLACEHOLDER_REGISTRY.md`, `governance/ADOPTION_REGISTRY.md`, die `TESTS.md`, `EXAMPLES.md` und `CHANGELOG.md` der Skills |
+| **D – Hauptdokument** | die Kapitelquellen unter `build/doc/` | `00-kopf.md` bis `32-abschluss.md` |
+
+**Nachweis** sind Änderungsanträge, Protokolle, Erhebungen und `build/` (`clientmap.NACHWEIS_ABLAGEN`, D-367). Sie werden nicht umgeschrieben. **Einzige Ausnahme:** `build/doc/` liegt in der Nachweisschicht, weil `build/` nicht zur Nutzung gehört – und ist doch das Hauptdokument, also Klasse D.
+
+## 2. Die Kriterien je Klasse
+
+| Kriterium | A Einstieg | B Regeln | C Register | D Hauptdokument |
+|---|---|---|---|---|
+| **aktuell** | voll | voll | nur die laufenden Zeilen | voll |
+| **schlüssig** | voll | voll | maschinell | voll, gegen A und B |
+| **verständlich** | voll, mit Kaltleser-Probe | Stichprobe | – | voll |
+| **Form** | voll | voll | voll | voll |
+
+### 2.1 Aktuell
+
+Keine Aussage **in Gegenwartsform** widerspricht dem Stand in `.koolie/core/VERSION`. **Datierte Aussagen** – *„gemessen am 2026-09-13“*, *„Stand Release 0.89.0“* – veralten nicht; sie müssen nur für ihr Datum stimmen (D-318). Hinweise *„🆕 neu mit x.y.z“* entfallen nach dem nächsten MINOR-Release.
+
+**Zahlen:** Eine Zahl in Gegenwartsform wird entweder **ausgerechnet** (vom Validator verlangt wie in Prüfung 46 und 78, oder beim Bau eingesetzt wie in Kapitel 31, D-377) oder **weggelassen**. Eine von Hand gepflegte Gegenwartszahl veraltet mit dem nächsten Release.
+
+### 2.2 Schlüssig
+
+In sich widerspruchsfrei und nicht im Widerspruch zu einem Dokument höherer Verbindlichkeit (`governance/PRIORITY_HIERARCHY.md`). Bei einem Widerspruch gilt das Regeldokument; der Einstiegstext wird angeglichen. Findet die Durchsicht zwei Regeln, die einander widersprechen, **entscheidet sie nichts**, sondern legt einen Änderungsantrag an.
+
+### 2.3 Verständlich (D-376)
+
+Regeltext nennt **die geltende Regel mit Verweis auf ihren Decision Record**, nicht ihre Herleitung. Sätze wie *„Bis `1.0.0` stand hier das Gegenteil“* oder *„berichtigt mit …“* gehören in `governance/DECISION_LOG.md` und `CHANGELOG.md`. **Belegzellen bleiben:** die Einstufung `[TECHNISCH]` oder `[DOK]`, der Protokollverweis, die datierte Messung. Eine Warnung darf auffallen – gestapelte Hervorhebungen in jedem zweiten Satz tun es nicht mehr.
+
+Für Klasse A misst das eine **Kaltleser-Probe** (D-379): Eine frische Sitzung ohne weiteren Kontext bekommt nur das Dokument und beantwortet feste Fragen; die Antworten werden gegen ein Soll gezählt. Fragen, Soll und Ergebnis stehen im Protokoll des Releases.
+
+### 2.4 Form
+
+- **Rechtschreibung nach dem geltenden Duden** in den Klassen A, B und D (D-373): *dass, muss, misst, lässt, Messbaum*. Register bleiben, wie sie geschrieben wurden. Code ist Zitat und bleibt.
+- **Gestalt** (D-374): genau eine Hauptüberschrift, keine übersprungene Ebene, jeder Codeblock geschlossen, jede Tabellenzeile mit der Spaltenzahl ihres Kopfes.
+- **Steckbrief** (D-375): Klassen A und B tragen vor dem ersten Abschnitt eine Tabelle `| Attribut | Wert |` mit Kennung, Version und Status. Ausgenommen sind README-Verzeichnisse, die Laufzeitschicht, Ausfüllvorlagen und Beispielausgaben. Wer ein Dokument ändert, hebt seine Version nach `governance/RELEASE_PROCESS.md` Abschnitt 1.
+- **Zeilenenden** wie der Rest des Repositoriums (Prüfung 81).
+
+## 3. Was eine Maschine prüft – und was nicht
+
+| Prüfung | Gegenstand | Klassen |
+|---|---|---|
+| 13 | Form jedes Versionsfeldes | A, B |
+| 46 | die D-11-Standzeile der Roadmap, ausgerechnet | C |
+| 55 | das Statusvokabular | A, B |
+| 77 | die Dokumentversion des Hauptdokuments gegen `VERSION` | D |
+| 78 | der Satz über den Prüfapparat, ausgerechnet | D |
+| 83, 85 | Chronikspanne und Zielangaben der Roadmap | C |
+| **91** | die Standüberschrift der Roadmap gegen `VERSION` (D-372) | C |
+| **92** | Rechtschreibung nach dem geltenden Duden (D-373) | A, B, D |
+| **93** | Gestalt: Codeblöcke, Hauptüberschrift, Ebenen, Tabellenspalten (D-374) | A, B, C, D |
+| **94** | Steckbrief mit Kennung, Version und Status (D-375) | A, B |
+
+**Keine Maschine prüft:** ob eine Gegenwartsaussage stimmt, ob zwei Dokumente einander widersprechen, ob ein Text verständlich ist und ob er Geschichte statt Regel erzählt. Eine Prüfung auf Geschichtsmarken ist verworfen, weil ihre Muster datierte Belege genauso träfen (D-376). Diese Kriterien bleiben Durchsicht – nach Abschnitt 4.
+
+## 4. Die Durchsicht
+
+- **Bei jedem Release:** Wer ein Dokument ändert, hält es gegen die Kriterien seiner Klasse. Die Prüfungen 91 bis 94 laufen mit dem Validator.
+- **Bei jedem MINOR-Release:** Entfallen die *„🆕 neu mit …“*-Hinweise des vorletzten MINOR-Releases.
+- **Eine vollständige Durchsicht** einer Klasse ist ein eigener Posten der Roadmap mit Ziel-Release. `1.9.0` hat die Klassen A und D durchgesehen und die Roadmap gekürzt (D-378); die Klasse B folgt je Bereich (D-380).
+
+## 5. Sprachen und Übersetzungsbedarf (D-437)
+
+**Deutsch ist die maßgebliche Sprache der gesamten Dokumentation.** Englisch gibt es nur für den Einstieg: `README.en.md` und `QUICKSTART.en.md` in der Wurzel des Framework-Repositoriums. Eine weitere englische Dokumentationsstruktur wird nicht angelegt.
+
+- **Beide Fassungen verweisen aufeinander**, und die englische nennt die deutsche maßgeblich. Ein Verweis aus einer englischen Fassung auf ein deutsches Dokument trägt den Zusatz *(German)*.
+- **Eine englische Fassung sagt nicht mehr zu als die deutsche.** Sie darf kürzen; sie darf keine Fähigkeit, keinen Reifegrad und kein Ergebnis nennen, das die deutsche Fassung nicht trägt.
+- **Wer `README.md` oder `QUICKSTART.md` ändert, prüft im selben Release, ob die englische Fassung nachgezogen werden muss**, und zieht sie nach oder hält im Änderungsantrag fest, warum nicht. Die Deckung der Fassungen prüft keine Maschine – Prüfung 12 hält nur die Verweise, Prüfung 93 die Form, und Prüfung 92 ist für englischen Text wirkungslos.

package/.koolie/core/docs/PLACEHOLDER_REGISTRY.md

@@ -0,0 +1,79 @@
+# Platzhalterregister
+
+Alle im Framework verwendeten Platzhalter. Neue Platzhalter werden hier registriert, bevor sie verwendet werden (`.koolie/core/tests/scripts/validate-framework.py` meldet unbekannte Platzhalter als Warnung). Platzhalter werden ausschließlich durch das Project Overlay oder die Organisation befüllt – niemals im Framework Core. Beispiele sind synthetisch.
+
+**Die Spalte „Wird gesetzt in" ist bei drei Platzhaltern durchgesetzt, bei allen übrigen ist sie eine Angabe.** `<BUILD_COMMAND>`, `<TEST_COMMAND>` und `<LINT_COMMAND>` werden von **Prüfung 42** in der hier genannten Overlay-Tabelle gelesen – über die Platzhalterzelle, nicht über eine Spaltennummer – und gegen die installierte Berechtigungsdatei gehalten (D-90, D-91). Bei den übrigen Platzhaltern sagt die Spalte, wo der Wert **hingehört**; dass er dort steht, prüft niemand nach.
+
+## Vom Arbeitsauftrag vorgegebene Platzhalter
+
+| Platzhalter | Bedeutung | Wird gesetzt in | Beispiel (synthetisch) | Pflicht vor Aktivierung |
+|---|---|---|---|---|
+| `<PROJECT_NAME>` | Neutraler Projektname | Overlay 1 | „Antragsverwaltung" | ja |
+| `<PROJECT_CODE>` | Projektkürzel | Overlay 1 | „AVW" | ja |
+| `<REPOSITORY_NAME>` | Name des Projekt-Repositorys | Overlay 3 | „avw-backend" | ja |
+| `<TECH_STACK>` | Sprachen, Frameworks, Build-System mit Versionen | Overlay 8 | „Sprache X 21, Framework Y 3, Build Z" | ja |
+| `<ISSUE_TRACKER>` | Werkzeugklasse Issue Tracking | Overlay 13 | „Jira" | ja |
+| `<CI_CD_PLATFORM>` | Werkzeugklasse CI/CD | Overlay 7 | „GitLab CI" | ja |
+| `<DOCUMENTATION_PLATFORM>` | Werkzeugklasse Dokumentation/Wiki | Overlay 13 | „Confluence" | nein |
+| `<TEST_FRAMEWORK>` | Testframework | Overlay 8 | „Testframework T 5" | ja |
+| `<QUALITY_GATE>` | Quality-Gate-Werkzeug oder -Regelwerk | Overlay 7 | „Statische Analyse S, Gate ‚Standard'" | ja |
+| `<SECURITY_CONTACT>` | Rolle für Sicherheitsfreigaben und Vorfälle | Overlay 15 | „Informationssicherheitsbeauftragte Rolle des Projekts" | ja |
+| `<APPROVAL_ROLE>` | Rolle für Freigaben Stufe hoch und Overlay | Overlay 15 | „Technische Projektleitung" | ja |
+| `<PROJECT_RULES_PATH>` | Pfad des verbindlichen Convention-Dokuments | Overlay 9 | „.koolie/project-overlay/documents/coding-guidelines/guidelines.md" | ja |
+
+## Laufzeit-Platzhalter (durch `install.py` aufgelöst)
+
+Diese Platzhalter unterscheiden sich von allen anderen: Sie werden **nicht vom Menschen** befüllt, sondern beim Installieren aus dem `manifest.json` des gewählten Client Packs aufgelöst. Sie stehen in den Quelltexten des Kerns – vor allem in `.koolie/core/framework/skills/` – dort, wo ein Text auf ein Artefakt der Laufzeitschicht verweist.
+
+Die Begriffsfassung derselben Abbildung steht in `.koolie/core/docs/RUNTIME_GLOSSARY.md`: Fließtext nennt den Begriff, ein Quelltext, der gerendert wird, den Platzhalter.
+
+| Platzhalter | Bedeutung | `devin-desktop` | `claude-code` | `openai-codex` | `kiro` | `cursor` |
+|---|---|---|---|---|---|---|
+| `<CLIENT_NAME>` | Produktname des Clients. **Nur zum Nennen, nie zum Zuschreiben** (D-129): Sagt ein Text etwas *über* das Produkt, gehört es in dessen Client Pack. Und er hilft **nur in einer gerenderten Quelle** – einziger angewandter Fall: der Titel von `framework/runtime/root-instruction.md` | `Devin Desktop` | `Claude Code` | `OpenAI Codex CLI` | `Kiro` | `Cursor` |
+| `<RUNTIME_DIR>` | Laufzeitschicht | `.devin` | `.claude` | `.codex` | `.kiro` | `.cursor` |
+| `<ROOT_INSTRUCTION_FILE>` | Wurzel-Anweisungsdatei | `AGENTS.md` | `CLAUDE.md` | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` |
+| `<ROOT_INSTRUCTION_LOCAL>` | Nutzerlokale Ergänzung dazu | `AGENTS.local.md` | `CLAUDE.local.md` | `AGENTS.override.md` – **verdrängt** die Wurzel-Anweisung, statt sie zu ergänzen (D-341) | `AGENTS.local.md` – **kein Mechanismus des Clients**; der Name steht nur, weil die Kernquelle ein Schreibverbot auf ihn führt (D-414) | `AGENTS.local.md` – **kein Mechanismus des Clients**; der Name steht nur, weil die Kernquelle ein Schreibverbot auf ihn führt (D-440) |
+| `<PERMISSIONS_FILE>` | Berechtigungsdatei | `.devin/config.json` | `.claude/settings.json` | `.codex/config.toml` | `.kiro/agents/koolie.json` – das Agentenprofil, gewählt durch `.kiro/settings/cli.json` (D-414) | `.cursor/cli.json` – trägt **nur** `permissions`; dazu `.cursorignore` für Lesen und Suchen (D-440, D-443) |
+| `<SKILLS_DIR>` | Skill-Ablage | `.devin/skills` | `.claude/skills` | `.codex/skills` | `.kiro/skills` | `.cursor/skills` |
+| `<RULES_DIR>` | Regelablage | `.devin/rules` | `.claude/rules` | `.codex/rules` | `.kiro/steering` | `.cursor/rules` – Regeldateien mit der Endung `.mdc` (D-440) |
+| `<AGENTS_DIR>` | Agentenprofile | `.devin/agents` | `.claude/agents` | `.codex/agents` | `.kiro/agents` | `.cursor/agents` |
+| `<HOOKS_FILE>` | Hook-Konfiguration | `.devin/config.json` | `.claude/settings.json` | `.codex/hooks.json` | `.kiro/hooks/koolie.json` | `.cursor/hooks.json` |
+| `<MCP_FILE>` | MCP-Konfiguration | `.devin/mcp_config.json` | `.mcp.json` | `.codex/config.toml` | `.kiro/settings/mcp.json` | `.cursor/mcp.json` |
+| `<CORE_DIR>` | Name des Kernverzeichnisses | `.koolie/core` | `.koolie/core` | `.koolie/core` | `.koolie/core` | `.koolie/core` |
+
+Ein Client Pack MUSS jeden dieser Platzhalter in seinem `manifest.json` unter `runtime_placeholders` belegen; ein unaufgelöster Laufzeit-Platzhalter in einer Installation ist ein Fehler.
+
+Einzige Ausnahme ist `<CORE_DIR>`: Der Name des Kernverzeichnisses ist keine Eigenschaft eines Clients, sondern dieser Installation. `install.py` und der Validator setzen ihn aus dem tatsächlichen Verzeichnisnamen; ein Client Pack darf ihn nicht belegen. Damit berührt eine spätere Umbenennung des Kernverzeichnisses (Roadmap P3) die Client Packs nicht.
+
+## Vom Framework ergänzte Platzhalter
+
+| Platzhalter | Bedeutung | Wird gesetzt in | Beispiel (synthetisch) | Pflicht vor Aktivierung |
+|---|---|---|---|---|
+| `<FRAMEWORK_OWNER>` | Rolle mit Gesamtverantwortung für das Framework | `.koolie/core/OWNERS.md` | „Leitung Entwicklungsmethodik" | ja |
+| `<DATA_PROTECTION_CONTACT>` | Rolle für Datenschutzfreigaben | Overlay 15 / Organisation | „Datenschutzkoordination" | ja |
+| `<PRODUCT_OWNER_ROLE>` | Rolle für fachliche Klärungen | Overlay 15 | „Product Owner" | ja |
+| `<ARCHITECT_ROLE>` | Rolle für Architekturentscheidungen | Overlay 15 | „Softwarearchitektur" | ja |
+| `<ALLOWED_PATHS>` | Für den KI-Client erlaubte Pfade (Glob) | Overlay 4 | „src/**, test/**, docs/**" | ja |
+| `<EXCLUDED_PATHS>` | Ausgeschlossene Pfade (weder lesen noch ändern) | Overlay 4 | „deploy/**, infra/**, config/prod/**" | ja |
+| `<READ_ONLY_PATHS>` | Nur lesbare Pfade | Overlay 4 | „api-contracts/**, db/migrations/**" | ja (oder „keine") |
+| `<TEST_PATHS>` | Pfade, in denen M4 schreiben darf | Overlay 4 | „test/**" | ja |
+| `<DOC_PATHS>` | Pfade, in denen M5 schreiben darf | Overlay 4 | „docs/**" | ja |
+| `<CI_CONFIG_PATHS>` | CI/CD-Konfigurationsdateien (Schreibverbot) | Overlay 4 | „.gitlab-ci.yml" | ja |
+| `<QUALITY_GATE_CONFIG_PATHS>` | Quality-Gate-Konfiguration (Schreibverbot) | Overlay 4 | „config/lint/**, coverage.config" | ja |
+| `<BUILD_COMMAND>` | Freigegebener Build-Befehl | Overlay 5 | „build-tool compile" | ja |
+| `<TEST_COMMAND>` | Freigegebener Testbefehl | Overlay 6 | „build-tool test" | ja |
+| `<LINT_COMMAND>` | Freigegebener Lint-/Formatprüfbefehl | Overlay 6 | „build-tool lint" | ja |
+| `<COMMIT_CONVENTION>` | Commit-Nachrichtenkonvention | Overlay 10 | „Conventional Commits + Ticket-Kennung" | ja |
+| `<BRANCHING_MODEL>` | Branching-Modell | Overlay 10 | „Feature-Branches auf Standard-Branch" | ja |
+| `<DEFAULT_BRANCH>` | Standard-Branch | Overlay 10 | „main" | ja |
+| `<BRANCH_PREFIX>` | Branch-Namensschema | Overlay 10 | „feature/`<PROJECT_CODE>`-123-kurz" | nein |
+| `<MR_TEMPLATE_PATH>` | Pfad der Merge-Request-Vorlage | Overlay 10 | „.gitlab/merge_request_templates/default.md" | nein |
+| `<CHANGE_SIZE_THRESHOLD>` | Schwellenwert geänderter Dateien für R1/Q8 | Overlay 2 oder Ausnahmeregister | „10" | ja |
+| `<CRITICAL_MODULE>` | Beispielhafte Bezeichnung einer kritischen Komponente (nur in Erläuterungen) | Overlay 2 | „auth-core" | – |
+| `<PILOT_DURATION>` | Dauer des Piloten | `.koolie/core/pilot/PILOT_CONCEPT.md` | „8 Wochen" | vor Pilotstart |
+| `<TECH_PACK_NAME>` / `<TECH_PACK_CODE>` | Name und Kürzel eines Technology Packs | Pack-Vorlage | „Sprache X" / „LX" | bei Pack-Erstellung |
+| `<ROLE_PACK_NAME>` / `<ROLE_PACK_CODE>` | Name und Kürzel eines Role Packs | Pack-Vorlage | „Requirements Engineering" / „RE" | bei Pack-Erstellung |
+| `<CLIENT_PACK_NAME>` / `<CLIENT_PACK_CODE>` | Name und Kürzel eines Client Packs (Abbildung auf einen KI-Client, `.koolie/core/clients/`) | Pack-Vorlage | „Client C" / „CC" | bei Pack-Erstellung |
+| `<FORM_NAME>`, `<PLACEHOLDER>`, `<PACK>` | Generische Platzhalter in Erläuterungen und Beispielen | – | – | – |
+| `<JAHR>`, `<JJJJ>`, `<NNN>` | Schema-Platzhalter für Jahres- und Laufnummern in IDs (`CR-<JAHR>-<NNN>`, `INC-<PROJECT_CODE>-<JJJJ>-<NNN>`) | Vorlagen in `.koolie/core/governance/` | „CR-2026-001" | – |
+| `<TBD: …>` | Offene projekt- oder organisationsspezifische Entscheidung | überall | – | Overlay-Abschnitte 4, 5, 6, 13, 14, 15: ja |