@renoxar/koolie 1.25.0

package/.koolie/core/templates/project-overlay/OVERLAY.md

@@ -0,0 +1,315 @@
+# Project Overlay – `<PROJECT_NAME>` (`<PROJECT_CODE>`)
+
+<!-- AUSFÜLLHINWEISE (vor Aktivierung entfernen oder belassen – sie sind für den KI-Client unschädlich):
+     - Diese Datei ist die einzige Stelle für projektspezifische Vorgaben (Ebene 4). Der Framework Core
+       wird nicht verändert. Ein Projektwechsel tauscht ausschließlich das Verzeichnis .koolie/project-overlay/
+       und die Laufzeitfassung <RULES_DIR>/20-project-overlay.md aus.
+     - Jedes Feld enthält einen Platzhalter <...> oder einen Ausfüllhinweis. Offene Entscheidungen bleiben
+       als <TBD: ...> stehen. Solange ein für den KI-Client sicherheitsrelevantes Feld (Abschnitte 4, 5, 6, 13, 14, 15)
+       offen ist, bleibt der Overlay-Status "inaktiv".
+     - Keine Secrets, keine Personen, keine internen Adressen, keine nicht öffentlichen Fachinformationen.
+       Rollen statt Personen. Beispiele sind als synthetisch zu kennzeichnen.
+     - Das Overlay darf Framework-Regeln konkretisieren oder verschärfen, nie lockern
+       (.koolie/core/governance/PRIORITY_HIERARCHY.md).
+     - Nach jeder Änderung: python3 .koolie/core/tests/scripts/validate-framework.py ausführen und die Laufzeitfassung
+       <RULES_DIR>/20-project-overlay.md synchron halten. Status, Version und die Pfadlisten übernimmt
+       python .koolie/core/mandat.py abgleichen (der Mensch, eigenes Terminal); fehlende Regeln der
+       Berechtigungsdatei nennt es (D-452).
+     - Ausfüllen lassen: Im Modus M6 trägt der KI-Client Entscheidungen des Menschen direkt hier ein – mit
+       Mandat (python .koolie/core/mandat.py erteilen …) und über den Skill fw-overlay-pflege (Einrichtung und
+       Framework-Update). Entscheiden bleibt Sache des Menschen; geprüft wird im Merge Request. -->
+
+## 1. Projektsteckbrief
+
+| Feld | Wert | Ausfüllhinweis |
+|---|---|---|
+| Projektname | `<PROJECT_NAME>` | neutraler Arbeitsname, kein Kunden- oder Behördenname |
+| Projektkürzel | `<PROJECT_CODE>` | für Ticket-Referenzen und Skill-Präfixe |
+| Overlay-Status | `<TBD: aktiv / inaktiv>` | `aktiv` erst nach Abschluss der Checkliste `.koolie/core/checklists/10-project-adoption.md` |
+| Overlay-Version | `<TBD: 0.1.0>` | Semantic Versioning, unabhängig von der Framework-Version |
+| Kompatible Framework-Version | `<TBD: z. B. 0.1.x>` | aus `.koolie/core/VERSION` des Frameworks |
+| Overlay Owner (Rolle) | `<APPROVAL_ROLE>` | Rolle, keine Person |
+| Fachlicher Kontext (abstrakt) | `<TBD: ein Satz ohne vertrauliche Details, z. B. „Fachanwendung zur Verwaltung von Anträgen">` | keine Fachinformationen mit Schutzbedarf |
+| Teamgröße / Rollen im Team | `<TBD: Anzahl und generische Rollen>` | Entwickler, Reviewer, PO, RE, Tester, QA, Architekt, DevOps, Projektleitung |
+| Aktivierte Role Packs (Ebene 6) | `<TBD: Liste, z. B. software-development Version, oder keine>` | jeweils Laufzeitfassung `<RULES_DIR>/30-role-<pack>.md`; Prüfung 110 hält die Zeile gegen die Regelablage |
+| Freigabe der KI-Nutzung durch Organisation | `<TBD: Referenz auf Freigabedokument oder „ausstehend">` | Voraussetzung für Status aktiv |
+| Ergebnis Datenschutz- und Vertragsprüfung | `<TBD: Referenz oder „ausstehend">` | siehe `.koolie/core/framework/core/02-privacy.md` Abschnitt 1 |
+| Planstufe / verfügbare Admin-Kontrollen | `<TBD: Teams / Enterprise; erzwungene Einstellungen>` | Klärungspunkt K-05 |
+| Nutzungsumfang | `<TBD: nur lokal / zusätzlich weitere Betriebsarten>` | Klärungspunkt K-04; Standard: nur lokal. Welche Betriebsarten der Client kennt, führt sein Client Pack |
+| Betriebssysteme der Arbeitsplätze | `<TBD>` | relevant für Sandbox-Verfügbarkeit (K-11) |
+
+## 2. Technische Architektur (für den KI-Client relevante Kurzfassung)
+
+| Feld | Wert | Ausfüllhinweis |
+|---|---|---|
+| Architekturstil | `<TBD: z. B. modularer Monolith, Services, Schichtenarchitektur>` | ein Begriff, keine Systemnamen |
+| Hauptkomponenten (logisch) | `<TBD: Liste logischer Komponenten mit Verzeichnis>` | keine Hostnamen, keine Umgebungen |
+| Schichtung und erlaubte Abhängigkeitsrichtungen | `<TBD: z. B. UI → Anwendung → Domäne → Infrastruktur>` | Der KI-Client prüft Vorschläge dagegen |
+| Kritische Komponenten (Änderung mindestens Stufe hoch) | `<TBD: Liste>` | Authentifizierung, Autorisierung, Zahlungs-/Fachkern, Schnittstellen zu Externen, Datenmigrationen |
+| Externe Schnittstellen (abstrakt) | `<TBD: Typ und Richtung, z. B. „REST-Schnittstelle zu externem Fachverfahren (ausgehend)">` | keine Partnernamen, keine Adressen |
+| Architekturvorgaben (Dokument) | `<TBD: Pfad im Overlay-Dokumentenverzeichnis, Kontextklasse>` | siehe Abschnitt 19 |
+| Architekturentscheidungen (ADR-Ablage) | `<TBD: Pfad oder „nicht vorhanden">` | Der KI-Client liest ADRs nur lesend |
+| Änderungsschwelle (`CHANGE_SIZE_THRESHOLD`) | `<TBD: Zahl geänderter Dateien, ab der aufgeteilt oder die Kontrollstufe erhöht wird>` | Pflicht vor der Aktivierung. Sie steht hier und nicht im Ausnahmeregister: Eine Schwelle, die erst im Ausnahmefall entsteht, ist keine (D-160) |
+
+## 3. Repository-Struktur
+
+```text
+<REPOSITORY_NAME>/
+├── <ROOT_INSTRUCTION_FILE>                      # Framework (nicht ändern)
+├── <RUNTIME_DIR>/                        # Framework-Laufzeitschicht + Overlay-Laufzeitfassung
+├── .koolie/core/framework/                     # Framework Core, Packs (nicht ändern)
+├── .koolie/project-overlay/               # dieses Overlay
+├── <TBD: src/>                    # Produktivcode – Beschreibung: <TBD>
+├── <TBD: test/>                   # Tests – Beschreibung: <TBD>
+├── <TBD: docs/>                   # Dokumentation – Beschreibung: <TBD>
+├── <TBD: weitere Verzeichnisse>   # Beschreibung: <TBD>
+└── <TBD: deploy/ infra/ config/>  # ausgeschlossen (siehe Abschnitt 4)
+```
+
+Ausfüllhinweis: Nur Verzeichnisse auf der obersten und gegebenenfalls zweiten Ebene beschreiben. Der KI-Client erschließt Details selbst (Skill `fw-repo-analyze`). Mehrere Repositories: **je Repository eine eigene Installation mit eigenem Overlay** – die Schutzschicht wirkt nur für eine Sitzung, die im Verzeichnis der Installation startet; ein Overlay über mehreren Repositories mit einem Abschnitt je Repository ist **nicht gleichwertig**, weil eine Sitzung im Repository darunter Berechtigungen und Hooks verliert, ohne dass es gemeldet wird (D-408, `.koolie/core/docs/ADOPTION_GUIDE.md` Abschnitt 4).
+
+## 4. Erlaubte und ausgeschlossene Verzeichnisse
+
+| Kategorie | Platzhalter | Wert | Ausfüllhinweis |
+|---|---|---|---|
+| Erlaubte Pfade (Lesen und Ändern in M3) | `<ALLOWED_PATHS>` | `<TBD: z. B. src/**, test/**, docs/**>` | Glob-Muster; alles Übrige ist nicht erlaubt |
+| Testpfade (Ändern in M4) | `<TEST_PATHS>` | `<TBD>` | Teilmenge der erlaubten Pfade |
+| Dokumentationspfade (Ändern in M5) | `<DOC_PATHS>` | `<TBD>` | Teilmenge der erlaubten Pfade |
+| Ausgeschlossene Pfade (weder lesen noch ändern) | `<EXCLUDED_PATHS>` | `<TBD: z. B. deploy/**, infra/**, config/prod/**, **/fixtures/real/**>` | **Vertraulichkeitsschutz.** Zusätzlich zum festen Framework-Ausschluss der Secret-Dateien. Die Strukturpfade des Frameworks gehören **nicht** hierher – sie sind schreibgeschützt, nicht lesegesperrt (nächste Zeile, D-55) |
+| Nur-Lese-Pfade (Lesen erlaubt, Ändern nie) | `<READ_ONLY_PATHS>` | `<TBD: z. B. api-contracts/**, db/migrations/**>` | **Integritätsschutz.** Schnittstellenverträge, Migrationen, generierter Code; wird in `<PERMISSIONS_FILE>` als `Write`-deny eingetragen (eigener Schlitz, D-356). Zusätzlich immer die Strukturpfade des Frameworks: `<ROOT_INSTRUCTION_FILE>`, `<RUNTIME_DIR>/`, `<CORE_DIR>/`, `.koolie/project-overlay/`. Sie MÜSSEN lesbar bleiben – der KI-Client lädt sie als Anweisungsquelle |
+| CI/CD-Konfiguration | `<CI_CONFIG_PATHS>` | `<TBD: z. B. .gitlab-ci.yml, .github/workflows/**, Jenkinsfile>` | wird in `<PERMISSIONS_FILE>` als `Write`-deny eingetragen |
+| Quality-Gate-Konfiguration | `<QUALITY_GATE_CONFIG_PATHS>` | `<TBD: z. B. Linter-, Coverage-, Analyse-Konfigurationsdateien>` | `Write`-deny |
+
+Diese Werte MÜSSEN in `<PERMISSIONS_FILE>` und in `<RULES_DIR>/20-project-overlay.md` übernommen werden; die Laufzeitfassung **bindet** den Platzhalter, statt seinen Wert einzusetzen (D-160). **Weicht ein Träger ab, ist das ein Befund und kein Auslegungsfall:** Maßgeblich ist diese Datei. Bis die Abweichung behoben ist, gilt die restriktivere Angabe – sie ist ein Notbehelf, keine Entscheidung, und der Widerspruch wird gemeldet. **Prüfung 59 des Validators findet ihn für `<EXCLUDED_PATHS>`, Prüfung 89 für `<ALLOWED_PATHS>`, `<TEST_PATHS>`, `<DOC_PATHS>` und `<READ_ONLY_PATHS>`** – beide lesen den Wert aus der Spalte **Wert** dieser Tabelle und verlangen, dass die Laufzeitfassung den Platzhalter **nennt**. `<CI_CONFIG_PATHS>` und `<QUALITY_GATE_CONFIG_PATHS>` führt die Laufzeitfassung nicht; für sie hält Prüfung 89 seit 1.20.1, dass jeder Glob dieser Tabelle seine eigene Schreibsperre in `<PERMISSIONS_FILE>` hat – ein zu eng gefüllter Schlitz wäre eine stille Lockerung (K-35).
+
+> **Eine Lesesperre und eine Schreibsperre sind zwei verschiedene Dinge.** `<EXCLUDED_PATHS>` wird in der Berechtigungsdatei zu einer `read`- **und** einer `write`-Verweigerung; die Strukturpfade des Frameworks stehen dort ausschließlich als `write`-Verweigerung, bei `read allow **`. Wer sie in `<EXCLUDED_PATHS>` einträgt, erzeugt eine Lesesperre auf die eigenen Regeldateien – und der KI-Client kann dann die Anweisungen nicht mehr laden, die er befolgen soll. **Prüfung 28 des Validators findet diesen Fall.** Ein Schreibschutz ist kein Leseverbot (D-55).
+
+## 5. Build-Befehle
+
+| Zweck | Platzhalter | Befehl | Laufzeit / Hinweise |
+|---|---|---|---|
+| Vollständiger Build | `<BUILD_COMMAND>` | `<TBD>` | `<TBD: erwartete Dauer, benötigte lokale Voraussetzungen>` |
+| Schneller Kompilier-/Syntaxcheck | – | `<TBD oder „nicht vorhanden">` | KANN für M3 freigegeben werden |
+| Build-Voraussetzungen (lokal) | – | `<TBD: Werkzeuge und Versionen ohne interne Registry-Adressen>` | Registry-Adressen gehören nicht in das Overlay |
+
+## 6. Test-, Prüf- und weitere freigegebene Befehle
+
+| Zweck | Platzhalter | Befehl | Freigegeben für Modus | Wirkungsort |
+|---|---|---|---|---|
+| Alle Unit-Tests | `<TEST_COMMAND>` | `<TBD>` | M3, M4 | `<PERMISSIONS_FILE>`, Korb ask – und Regelschicht |
+| Einzelner Test / Testklasse | – | `<TBD: Befehlsmuster mit Platzhalter für Testname>` | M3, M4 | **nur Regelschicht** |
+| Integrations-/Komponententests | – | `<TBD oder „nur in CI">` | `<TBD>` | **nur Regelschicht** |
+| Linting / Formatprüfung | `<LINT_COMMAND>` | `<TBD>` | M3, M4, M5 | `<PERMISSIONS_FILE>`, Korb ask – und Regelschicht |
+| Statische Codeanalyse (lokal) | – | `<TBD oder „nur in CI">` | M3 | **nur Regelschicht** |
+| Weitere freigegebene Befehle | – | `<TBD: Liste oder „keine">` | `<TBD>` | **nur Regelschicht** |
+| Prüfbefehle des Frameworks (lesend) | – | `python .koolie/core/tests/scripts/validate-framework.py` (auch mit `--strict-overlay`), `python .koolie/core/install.py --check`, `python .koolie/core/mandat.py status` | alle | `<PERMISSIONS_FILE>`, Korb allow – aus der Kernquelle, nicht aus diesem Overlay (D-453) |
+
+Alle nicht gelisteten Befehle sind nicht freigegeben. Befehle mit Fernwirkung (Push, Merge, Deployment, Veröffentlichung) werden hier nie gelistet.
+
+**Zum Wirkungsort (D-76).** Die Berechtigungsdatei hat für Befehle genau drei Platzhalter – `<BUILD_COMMAND>` aus Abschnitt 5 sowie `<TEST_COMMAND>` und `<LINT_COMMAND>` aus dieser Tabelle. **Einen vierten Eintrag kann ein Overlay dort nicht erzeugen, und das ist so gewollt:** Die Datei wird bei der Erstinstallation aus der Kernregelmenge erzeugt und danach nie wieder geschrieben; eine Erweiterungsquelle, die nur bei der Installation gelesen würde, wäre eine Zusage, die beim ersten Releasewechsel bricht. Alle übrigen Zeilen dieser Tabelle wirken deshalb über die **Regelschicht**: `.koolie/core/framework/core/05-working-model.md` Abschnitt 3.2 und die Wurzel-Anweisungsdatei binden den KI-Client daran, nur hier gelistete Befehle auszuführen. Das ist eine Anweisung und keine technische Schranke – die Tabelle sagt es, damit niemand mehr erwartet. Ein Eintrag von Hand in `<PERMISSIONS_FILE>` ist **kein** Ersatz, und der Validator meldet ihn: Prüfung 37 als Ausweitung, sobald alle drei Schlitze belegt sind, und Prüfung 42 unabhängig davon, sobald der eingetragene Befehl in keiner Platzhalterzeile dieser Tabelle oder des Abschnitts 5 steht (D-90). **Was auch Prüfung 42 nicht prüft:** die Pfadlisten dieser Datei. Mit dem `deny`-Korb verglichen werden `<EXCLUDED_PATHS>` (Prüfung 59) und `<READ_ONLY_PATHS>` (Prüfung 89); die beiden Konfigurationslisten vergleicht keine Prüfung.
+
+## 7. Qualitätsprüfungen (Quality Gates)
+
+| Prüfung | Werkzeugklasse | Wo | Verbindlich für KI-Änderungen | Ausfüllhinweis |
+|---|---|---|---|---|
+| Build | `<CI_CD_PLATFORM>` | lokal + CI | MUSS | – |
+| Linting / Formatierung | `<TBD>` | lokal + CI | MUSS | Konfigurationspfad in Abschnitt 4 |
+| Statische Codeanalyse | `<TBD>` | CI | MUSS, falls vorhanden | – |
+| Unit Tests | `<TEST_FRAMEWORK>` | lokal + CI | MUSS | Mindestabdeckung: `<TBD oder „nicht definiert">` |
+| Integrations-/Komponententests | `<TBD>` | CI | `<TBD>` | – |
+| Security Scan (Abhängigkeiten, Code) | `<TBD>` | CI | MUSS, falls vorhanden | – |
+| Quality Gate | `<QUALITY_GATE>` | CI | MUSS | Schwellenwerte werden vom KI-Client nie geändert |
+| Merge Request + Code Review | `<TBD: Plattform>` | Prozess | MUSS | Anzahl Reviewer: `<TBD>` |
+| Vier-Augen-Prinzip | Prozess | Prozess | MUSS ab Kontrollstufe mittel | projektspezifisch: `<TBD>` |
+| Fachliche Abnahme | Prozess | Prozess | `<TBD>` | – |
+
+## 8. Programmiersprachen und Frameworks
+
+| Element | Wert | Ausfüllhinweis |
+|---|---|---|
+| Technologie-Stack | `<TECH_STACK>` | Sprache(n) und Versionen, Hauptframeworks, Build-System |
+| Testframework | `<TEST_FRAMEWORK>` | inklusive Mocking-/Assertion-Bibliotheken |
+| Aktivierte Technology Packs | `<TBD: Liste, z. B. tech-<name> Version>` | jeweils Laufzeitfassung `<RULES_DIR>/40-tech-<name>.md` |
+| Erlaubte Paketquellen | `<TBD: „nur Artefakt-Repository der Organisation" – ohne Adresse>` | Adresse gehört nicht in das Overlay |
+| Abhängigkeitsverwaltung | `<TBD: Manifest- und Lockdatei>` | Änderungen nur durch den Menschen |
+
+## 9. Coding Conventions
+
+| Element | Wert | Ausfüllhinweis |
+|---|---|---|
+| Verbindliches Convention-Dokument | `<PROJECT_RULES_PATH>` | im Overlay-Dokumentenverzeichnis, Kontextklasse K1 |
+| Formatter / Linter als Quelle der Wahrheit | `<TBD>` | Der KI-Client folgt der Konfiguration, nicht Erinnerungen |
+| Benennungskonventionen (Kurzfassung) | `<TBD>` | maximal zehn Zeilen; Rest im Dokument |
+| Verbotene Muster | `<TBD>` | z. B. bestimmte Bibliotheken, Reflection, statische Zustände |
+| Sprache von Bezeichnern, Kommentaren, Commits | `<TBD>` | – |
+
+## 10. Branching- und Merge-Modell
+
+| Element | Platzhalter | Wert |
+|---|---|---|
+| Branching-Modell | `<BRANCHING_MODEL>` | `<TBD: z. B. Feature-Branches auf Standard-Branch, Release-Branches>` |
+| Standard-Branch | `<DEFAULT_BRANCH>` | `<TBD>` |
+| Branch-Namensschema | `<BRANCH_PREFIX>` | `<TBD: z. B. feature/<PROJECT_CODE>-<ticket>-kurzbeschreibung>` |
+| Commit-Konvention | `<COMMIT_CONVENTION>` | `<TBD: z. B. Conventional Commits mit Ticket-Referenz>` |
+| Merge-Strategie | – | `<TBD: Squash / Merge-Commit / Rebase – durch Menschen>` |
+| Merge-Request-Vorlage | `<MR_TEMPLATE_PATH>` | `<TBD>`; enthält den KI-Nutzungsvermerk (`.koolie/core/templates/MR_AI_DISCLOSURE.md`) |
+| Geschützte Branches | – | `<TBD>`; der KI-Client arbeitet nie direkt darauf |
+
+## 11. Definition of Ready (für KI-Aufgaben)
+
+Eine Aufgabe ist bereit für die Bearbeitung mit dem KI-Client, wenn zusätzlich zur projektweiten Definition of Ready (`<TBD: Pfad>`):
+
+1. Ziel und Akzeptanzkriterien schriftlich vorliegen (bereinigt, ohne K2/K3-Inhalte),
+2. Kontrollstufe und Betriebsmodus festgelegt sind,
+3. der Scope (Pfade) benannt ist,
+4. die benötigten Kontextquellen eingestuft und – bei K2 – freigegeben sind,
+5. `<TBD: projektspezifische Zusatzkriterien>`.
+
+## 12. Definition of Done (für KI-Aufgaben)
+
+Zusätzlich zur projektweiten Definition of Done (`<TBD: Pfad>`) gilt `.koolie/core/framework/core/04-quality.md` Abschnitt 3 (Ergebnisbericht, lokale Prüfungen, Selbstreview, Nutzungsvermerk, offene Punkte sichtbar). Projektspezifische Ergänzungen: `<TBD>`.
+
+## 13. Zulässige Kontexte und Werkzeuge
+
+| Kontextquelle | Kontextklasse | Freigabe | Bedingungen |
+|---|---|---|---|
+| Quellcode in `<ALLOWED_PATHS>` | K1 | pauschal | Least Context |
+| Quellcode in `<READ_ONLY_PATHS>` | K1 | pauschal (lesend) | – |
+| Overlay-Dokumente laut Manifest (Abschnitt 19) | K1 / K2 je Dokument | laut Manifest | K2 nur mit Freigabe in der Aufgabe |
+| Tickets aus `<ISSUE_TRACKER>` | K2 | je Aufgabe durch Bearbeiterin oder Bearbeiter | nur Titel, technische Beschreibung, Akzeptanzkriterien; bereinigt |
+| Inhalte aus `<DOCUMENTATION_PLATFORM>` | `<TBD: K1 nach Freigabe je Seite / K2>` | `<TBD>` | – |
+| Logauszüge, Stacktraces | K2 | je Aufgabe | bereinigt (keine personenbezogenen Daten, Hostnamen, Kennungen) |
+| Testdaten | K1 nur synthetisch | pauschal für synthetische Daten | Echtdaten nie |
+| Freigegebene MCP-Server | – | `<TBD: „keine" oder „siehe Abschnitt 13.2">` | Eintrag in `<MCP_FILE>` erst nach Freigabe; Standard ask; ein Server ohne Zweck und Werkzeugliste ist nicht freigegeben (`02-privacy.md` 3.8, D-455, D-459) |
+| Kommentarverläufe aus `<ISSUE_TRACKER>` | K2 | **„nicht freigegeben“** – oder Kategoriefreigabe im Overlay-Manifest | nur bereinigt und nur, soweit sie eine Anforderung oder Entscheidung tragen (`02-privacy.md` 3.4, D-455) |
+| Freigegebene externe Domains (Fetch) | K0 | **„keine"** | **Eine Freigabe je Domain ist nicht vorgesehen** (D-59): `deny` gewinnt, und bei einem Client ohne Musterunterstützung für die Abrufwerkzeuge ist sie nicht ausdrückbar. Das Verbot ist nur als Ganzes und nur über einen Änderungsantrag ersetzbar |
+| Cloud-Sessions / CLI / ACP-Fremdagenten | – | `<TBD: nicht freigegeben / freigegeben mit Auflagen>` | Standard: nicht freigegeben (D-10) |
+
+### 13.1 Ablage und führendes System
+
+Wo Änderungsanträge, Pläne, Freigaben und Architekturentscheidungen des Projekts leben (D-454). **Führend ist ein zentrales System**, sobald es über einen für *schreiben für Ablage* freigegebenen MCP-Server erreichbar ist: Es vergibt die Kennungen, und mehrere Arbeitsplätze können sich nicht in die Quere kommen. **Das Repositorium ist der Rückfall** – mit Kennungen, die ohne zentrale Nummernvergabe eindeutig sind, und einer Datei je Entscheidung, damit parallele Änderungen beim Merge nicht kollidieren.
+
+| Gegenstand | Führendes System | Rückfallablage im Repositorium | Kennung im Rückfall |
+|---|---|---|---|
+| Änderungsanträge des Projekts | `Repositorium` (Standard) – oder `<ISSUE_TRACKER>` | `docs/changes/` | `CR-<PROJECT_CODE>-<JJJJ-MM-TT>-<kurzname>` – Datum und Kurzname statt laufender Nummer |
+| Pläne und dokumentierte Freigaben (Kontrollstufe mittel und hoch) | wie Änderungsanträge | `docs/changes/<Kennung>/` | Kennung des Antrags |
+| Architekturentscheidungen | `Repositorium` (Standard) – oder `<DOCUMENTATION_PLATFORM>` | `.koolie/project-overlay/documents/architecture/decisions/` | `ADR-<JJJJ-MM-TT>-<kurzname>.md` – eine Datei je Entscheidung |
+| Ergebnisberichte | Merge Request | – | – |
+
+Ausfüllhinweis: Wer ein zentrales System einträgt, gibt dessen MCP-Server in Abschnitt 13.2 mit dem Zweck *schreiben für Ablage* frei. Die Architekturübersicht in `documents/architecture/` fasst den gültigen Stand zusammen; sie wird bei einem Release nachgezogen, nicht bei jeder Entscheidung.
+
+### 13.2 MCP-Server: Zweck und Werkzeuge
+
+Eine Zeile je freigegebenem Server (D-457, D-459). **Lesewerkzeuge** laufen ohne Rückfrage und stehen in `<PERMISSIONS_FILE>` einzeln auf `allow`; **Schreibwerkzeuge** verlangen bei jedem Aufruf die Bestätigung des Menschen und stehen einzeln auf `ask` – nie auf `allow`, auch nicht über ein Muster für den ganzen Server. Ein Werkzeug, das hier nicht steht, ruft der KI-Client nicht auf. Die Namen sind die des Servers (seine Werkzeugliste), ohne den Vorsatz des Clients. Prüfung 101 gleicht diese Tabelle mit `<PERMISSIONS_FILE>` ab; `python .koolie/core/mandat.py abgleichen` nennt fehlende Regeln, schreibt sie aber nicht (V6).
+
+| Server (Name in `<MCP_FILE>`) | System | Zweck | Lesewerkzeuge | Schreibwerkzeuge | Ablageziel |
+|---|---|---|---|---|---|
+| `<TBD: keine>` | – | – | – | – | – |
+
+- Höchstzahl der Treffer je Suche: `5` (Standard, `02-privacy.md` 3.8)
+- Anmeldung: `<TBD: interaktiv (OAuth) je Arbeitsplatz / Token aus einer Umgebungsvariablen>` – Zugangsdaten stehen nie in einer versionierten Datei
+
+Ausfüllhinweis: *System* ist `<ISSUE_TRACKER>` oder `<DOCUMENTATION_PLATFORM>`. *Zweck* ist *lesen für Planung*, *schreiben für Ablage* oder beides. *Ablageziel* nennt für *schreiben für Ablage* den Ort im System (etwa Projektschlüssel und Vorgangstyp, Bereich und Elternseite). Beispiel für einen Server zum Lesen: `getJiraIssue, searchJiraIssuesUsingJql` als Lesewerkzeuge, keine Schreibwerkzeuge. **Bei Clients, bei denen eine Rückfrageregel eine Freigabe schlägt, ersetzt eine Freigabe zum Lesen die pauschale MCP-Rückfrage** der Berechtigungsdatei durch diese Einzelregeln; welche Clients das sind, sagt Abschnitt 1 ihres Client Packs.
+
+## 14. Ausgeschlossene Daten (projektspezifische Ergänzung zu K3)
+
+Zusätzlich zu den festen K3-Kategorien (`.koolie/core/framework/core/02-privacy.md` Abschnitt 2.1):
+
+| Ausgeschlossen | Wo typischerweise anzutreffen | Technische Sperre |
+|---|---|---|
+| `<TBD: z. B. Fachdaten realer Vorgänge>` | `<TBD: Verzeichnisse>` | `Read`-deny in `<PERMISSIONS_FILE>` |
+| `<TBD: z. B. Umgebungskonfigurationen>` | `<TBD>` | `<EXCLUDED_PATHS>` |
+| `<TBD: z. B. Schnittstellenverträge externer Partner mit Vertraulichkeitsvermerk>` | `<TBD>` | Overlay-Manifest: nicht gelistet = K3 |
+
+## 15. Rollen und Freigaben
+
+| Rolle (generisch) | Platzhalter | Zuständigkeit im KI-Kontext |
+|---|---|---|
+| Freigabe Kontrollstufe hoch, Overlay Owner | `<APPROVAL_ROLE>` | schriftliche Freigaben, Overlay-Pflege, Ausnahmen |
+| Sicherheitskontakt | `<SECURITY_CONTACT>` | Sicherheitsfreigaben, Vorfälle, Abhängigkeiten |
+| Datenschutzkontakt | `<DATA_PROTECTION_CONTACT>` | Kontextfreigaben K2 mit Personenbezug, Vorfälle |
+| Product Owner | `<PRODUCT_OWNER_ROLE>` | fachliche Klärungen, Akzeptanzkriterien |
+| Softwarearchitektur | `<ARCHITECT_ROLE>` | Architekturentscheidungen, Review Stufe hoch |
+| Mandat für Modus M6 | `<APPROVAL_ROLE>`, für `documents/` auch `<ARCHITECT_ROLE>` | erteilt im eigenen Terminal das Mandat, mit dem der KI-Client getroffene Entscheidungen in das Overlay einträgt (`mandat.py`, D-446) |
+| Reviewerinnen und Reviewer | – | Review nach `.koolie/core/framework/core/07-review-rules.md` |
+| Mentorinnen und Mentoren | – | Onboarding, Freigabe zur selbstständigen Nutzung |
+| Modul-Owner projektspezifischer Skills | – | Pflege der `prj-*`-Skills |
+
+Ausfüllhinweis: Rollen bleiben generisch. Die Zuordnung zu Personen erfolgt außerhalb des Repositorys (zum Beispiel im Teamverzeichnis der Organisation).
+
+## 16. Eskalationsweg
+
+| Stufe (aus `.koolie/core/framework/core/10-error-escalation.md`) | Erreichbar über | Reaktionszeit (projektspezifisch) |
+|---|---|---|
+| E1 fachlich/technisch | `<PRODUCT_OWNER_ROLE>` / `<ARCHITECT_ROLE>` über `<TBD: Kanal, z. B. Ticket-Kommentar, Team-Chat>` | `<TBD>` |
+| E2 Freigabe Stufe hoch | `<APPROVAL_ROLE>` über `<TBD>` | `<TBD>` |
+| E3 Sicherheits-/Datenschutzvorfall | `<SECURITY_CONTACT>`, `<DATA_PROTECTION_CONTACT>` über den Meldeweg der Organisation `<TBD: Referenz>` | gemäß Organisation |
+| E4 Framework-Mangel | `<FRAMEWORK_OWNER>` über `.koolie/core/governance/FEEDBACK_PROCESS.md` | `<TBD>` |
+
+## 17. Projektspezifische Skills
+
+| Skill | ID | Status | Owner (Rolle) | Zweck | Ersetzt/ergänzt Framework-Skill |
+|---|---|---|---|---|---|
+| `prj-<TBD>` | `PRJ-SK-001` | entwurf | `<TBD>` | `<TBD>` | `<TBD: keiner / fw-...>` |
+
+Regeln: Projekt-Skills folgen dem Skill-Standard (`.koolie/core/framework/core/08-skill-conventions.md`), tragen das Präfix `prj-`, liegen unter `<SKILLS_DIR>/prj-<name>/` und DÜRFEN Framework-Skills ergänzen, aber deren Prüfschritte nicht entfernen.
+
+## 18. Dokumentierte Ausnahmen
+
+| ID | Ausnahme von Regel | Begründung | Kompensierende Maßnahme | Freigegeben durch (Rolle) | Gültig bis | Status |
+|---|---|---|---|---|---|---|
+| `EX-<PROJECT_CODE>-001` | `<TBD>` | `<TBD>` | `<TBD>` | `<APPROVAL_ROLE>` | `<TBD: Datum oder Ereignis>` | `<TBD>` |
+
+Ausnahmen folgen `.koolie/core/governance/EXCEPTION_PROCESS.md`. Ausnahmen von Delegationsverboten (V1–V12) und von der K3-Definition sind nicht zulässig.
+
+## 19. Eingebundene Projektdokumente (Overlay-Erweiterung)
+
+Projektspezifisches Wissen wird ausschließlich über diesen Mechanismus eingebunden; der Framework Core bleibt unverändert.
+
+**Mechanismus (normativ):**
+
+1. Das Dokument (oder ein bereinigter Auszug) wird unter `.koolie/project-overlay/documents/<dokumenttyp>/` abgelegt oder – falls es außerhalb des Repositorys bleibt – dort mit einem Verweisblatt (`REFERENCE.md`) beschrieben.
+2. Das Dokument wird in `.koolie/project-overlay/overlay-manifest.yaml` registriert: Typ, Pfad, Kontextklasse, Status, Freigabe (Rolle, Datum), Ladeverhalten.
+3. Ladeverhalten:
+   - `summary`: Kernaussagen (maximal zehn Zeilen) werden in `<RULES_DIR>/20-project-overlay.md` übernommen (immer aktiv, nur K1).
+   - `on-demand`: Der KI-Client liest das Dokument, wenn die Aufgabe es erfordert; K2-Dokumente nur nach Freigabe in der Aufgabe.
+   - `rule`: Das Projekt legt eine zusätzliche Overlay-Regeldatei `<RULES_DIR>/2N-overlay-<name>.md` (N = 1–9) mit `trigger: model_decision` oder `glob` an, die die Kernregeln des Dokuments enthält und auf das Dokument verweist (unter 12.000 Zeichen).
+   - `never`: Das Dokument ist registriert, aber nicht für den KI-Client bestimmt (Nachweiszweck).
+4. Nicht registrierte Dokumente gelten als K3.
+5. Änderungen an Dokumenten erhöhen die Overlay-Version; veraltete Dokumente werden im Manifest als `veraltet` markiert und nicht mehr geladen.
+
+**Vorgesehene Dokumenttypen:**
+
+| Typ (Manifest-Schlüssel) | Dokument | Empfohlenes Ladeverhalten | Typische Kontextklasse |
+|---|---|---|---|
+| `ai-governance` | KI-Governance-Rahmenwerk der Organisation oder des Projekts | `rule` (Kernregeln) | K1 |
+| `ai-process-model` | KI-Vorgehensmodell | `on-demand` | K1 |
+| `roadmap` | Projektroadmap | `never` oder `on-demand` (bereinigt) | K2 |
+| `architecture` | Architekturvorgaben | `rule` + `on-demand` | K1 nach Entfernung von Infrastrukturdetails, sonst K2 |
+| `coding-guidelines` | Coding Guidelines | `rule` (`glob`) | K1 |
+| `definition-of-ready` | Definition of Ready | `summary` | K1 |
+| `definition-of-done` | Definition of Done | `summary` | K1 |
+| `branching-strategy` | Branching-Strategie | `summary` | K1 |
+| `deployment` | Deployment-Vorgaben | `never` (der KI-Client deployt nicht) oder `on-demand` (bereinigt) | K2 |
+| `security` | Security-Vorgaben | `rule` (nur Entwicklungsregeln) | K1 nach Bereinigung; Schutzkonfigurationen K3 |
+| `quality` | Qualitätsrichtlinien | `rule` | K1 |
+| `roles` | Rollenbeschreibungen | `summary` (Rollen, keine Personen) | K1 |
+| `glossary` | Projektglossar | `on-demand` | K1 nach Prüfung auf vertrauliche Fachbegriffe |
+
+## 20. Änderungsverlauf des Overlays
+
+| Version | Datum | Änderung | Autor (Rolle) | Validierung bestanden |
+|---|---|---|---|---|
+| `<TBD: 0.1.0>` | `<TBD>` | Overlay angelegt | `<APPROVAL_ROLE>` | `<TBD>` |
+
+Ausfüllhinweis: Die neueste Zeile steht oben. Eine Eintragung im Modus M6 nennt in der Spalte Autor die Rolle, die das Mandat erteilt hat, und den Zusatz „eingetragen in M6“. Die Version im Steckbrief (Abschnitt 1) wird dabei **geändert, nicht ersetzt** – in ihrer Zeile steht nur die Versionsnummer.
+
+## 21. Aktivierung
+
+Die Reihenfolge ist bindend (D-57):
+
+1. **Ausfüllen.** Alle Pflichtwerte setzen, den Overlay-Status auf `inaktiv` – an **jeder** Stelle, an der das Overlay ihn erklärt (Steckbrief und dieser Abschnitt).
+2. **Kandidat prüfen:** `python3 .koolie/core/tests/scripts/validate-framework.py --check-overlay-ready` ohne Befund. Diese Prüfung erwartet einen Status, der **noch nicht** `aktiv` ist.
+3. **Checkliste abschließen:** `.koolie/core/checklists/10-project-adoption.md` vollständig, einschließlich der fachlichen Freigaben. Ein Skript kann sie nicht erteilen.
+4. **Aktivieren.** Der Mensch setzt den Status auf `aktiv` – an jeder Stelle.
+5. **Nachprüfen:** `python3 .koolie/core/tests/scripts/validate-framework.py --strict-overlay` ohne Befund. Erst danach beginnt der erste Agentenlauf mit Schreibrechten.

package/.koolie/core/templates/project-overlay/documents/README.md

@@ -0,0 +1,43 @@
+# Overlay-Dokumentenverzeichnis
+
+Ablage für projektspezifische Dokumente oder bereinigte Auszüge, die der KI-Client als Kontext erhalten darf. Jedes Dokument MUSS in `../overlay-manifest.yaml` registriert sein; nicht registrierte Dokumente gelten als K3 und werden nicht verwendet.
+
+## Verzeichnisstruktur (ein Unterverzeichnis je Dokumenttyp)
+
+```text
+documents/
+├── ai-governance/
+├── ai-process-model/
+├── roadmap/
+├── architecture/
+├── coding-guidelines/
+├── definition-of-ready/
+├── definition-of-done/
+├── branching-strategy/
+├── deployment/
+├── security/
+├── quality/
+├── roles/
+└── glossary/
+```
+
+## Regeln
+
+1. Vor der Ablage prüft die Overlay-Ownerin oder der Overlay-Owner das Dokument anhand `.koolie/core/checklists/02-privacy-context.md`. Bereinigungen werden im Manifest dokumentiert.
+2. Bleibt das Original außerhalb des Repositorys, wird ein Verweisblatt `REFERENCE.md` abgelegt (Titel, Zweck, Ablageort als Platzhalter `<DOCUMENTATION_PLATFORM>`, Kontextklasse, Freigabe). Der KI-Client kann Verweisblätter lesen, das Original nicht.
+3. Dokumente enthalten keine Personen, Kunden, Behörden, internen Adressen, Umgebungskennungen oder Secrets.
+4. Änderungen erhöhen die Overlay-Version (Abschnitt 20 des Overlays).
+5. Architekturentscheidungen liegen im Rückfall (Overlay Abschnitt 13.1) als **eine Datei je Entscheidung** unter `architecture/decisions/ADR-<JJJJ-MM-TT>-<kurzname>.md`: Kontext, Entscheidung, Alternativen, Folgen, Status. Zwei Arbeitsplätze, die zugleich entscheiden, erzeugen zwei Dateien statt eines Merge-Konflikts. Ist `<DOCUMENTATION_PLATFORM>` führend, liegt hier höchstens ein Verweisblatt.
+
+## Vorlage Verweisblatt
+
+```markdown
+# Verweisblatt – <Dokumenttitel>
+
+- Typ: <Manifest-Typ>
+- Zweck: <ein Satz>
+- Ablageort: <DOCUMENTATION_PLATFORM>, Bereich <TBD>
+- Kontextklasse des Originals: <K1 | K2 | K3>
+- Für den KI-Client nutzbarer Auszug: <Pfad im Dokumentenverzeichnis oder „keiner">
+- Freigabe: <Rolle>, <Datum>
+```

package/.koolie/core/templates/project-overlay/documents/ai-governance/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: ai-governance
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/ai-process-model/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: ai-process-model
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/architecture/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: architecture
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/architecture/decisions/README.md

@@ -0,0 +1,3 @@
+# Architekturentscheidungen (Rückfallablage)
+
+Eine Datei je Entscheidung: `ADR-<JJJJ-MM-TT>-<kurzname>.md` mit Kontext, Entscheidung, Alternativen, Folgen und Status. Zwei Arbeitsplätze, die zugleich entscheiden, erzeugen zwei Dateien statt eines Merge-Konflikts (Overlay Abschnitt 13.1, D-454). Jede Datei wird im Overlay-Manifest registriert. Ist `<DOCUMENTATION_PLATFORM>` führend, liegt hier höchstens ein Verweisblatt.

package/.koolie/core/templates/project-overlay/documents/branching-strategy/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: branching-strategy
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/coding-guidelines/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: coding-guidelines
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/definition-of-done/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: definition-of-done
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/definition-of-ready/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: definition-of-ready
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/deployment/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: deployment
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/glossary/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: glossary
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/quality/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: quality
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/roadmap/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: roadmap
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/roles/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: roles
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/documents/security/.gitkeep.md

@@ -0,0 +1,3 @@
+# Platzhalterverzeichnis: security
+
+Hier werden freigegebene Dokumente oder bereinigte Auszüge dieses Typs abgelegt und in ../../overlay-manifest.yaml registriert. Siehe ../README.md.

package/.koolie/core/templates/project-overlay/exceptions/EXCEPTIONS.md

@@ -0,0 +1,9 @@
+# Ausnahmeregister – `<PROJECT_NAME>`
+
+Register aller genehmigten Ausnahmen von Framework-Regeln für dieses Projekt. Prozess: `.koolie/core/governance/EXCEPTION_PROCESS.md`. Ausnahmen von Delegationsverboten (V1–V12) und von der K3-Definition sind nicht möglich.
+
+| ID | Regel (Modul, Abschnitt) | Ausnahme | Begründung | Kompensierende Maßnahme | Risiko | Freigegeben durch (Rolle) | Datum | Gültig bis | Überprüfung am | Status |
+|---|---|---|---|---|---|---|---|---|---|---|
+| `EX-<PROJECT_CODE>-001` | `<TBD>` | `<TBD>` | `<TBD>` | `<TBD>` | `<TBD: niedrig/mittel/hoch>` | `<APPROVAL_ROLE>` | `<TBD>` | `<TBD>` | `<TBD>` | `<TBD: beantragt/aktiv/abgelaufen/widerrufen>` |
+
+**Beispiel (synthetisch):** `EX-<PROJECT_CODE>-002` – Regel `05-working-model.md` 3.1.2 (nur Sitzungsfreigaben) – Ausnahme: `Exec(<TEST_COMMAND>)` dauerhaft auf `allow` – Begründung: Testläufe mehrmals je Stunde bei Kontrollstufe niedrig – Kompensation: Befehl ohne Parameter, Testpfade ohne Netzwerkzugriff – Risiko niedrig – gültig bis zum nächsten Overlay-Review.

package/.koolie/core/templates/project-overlay/forbidden-terms.txt

@@ -0,0 +1,8 @@
+# Sperrbegriffe für die Inhaltsprüfung (.koolie/core/tests/scripts/validate-framework.py)
+# Ein Begriff je Zeile; Zeilen mit # sind Kommentare. Groß-/Kleinschreibung wird ignoriert.
+# Zweck: Projekte tragen hier ihre realen Projekt-, Kunden-, Behörden-, Produkt- und
+# Systemnamen ein, damit ein versehentliches Einsickern in generische Framework-Bestandteile
+# (Core, Packs, Skills, Prompts, Checklisten) automatisch erkannt wird.
+# Die Datei selbst darf nicht in das Framework-Release übernommen werden, wenn sie reale Namen
+# enthält; sie bleibt projektlokal (Projekt entscheidet über Versionierung).
+# Im Framework-Release ist die Liste leer.

package/.koolie/core/templates/project-overlay/overlay-manifest.yaml

@@ -0,0 +1,73 @@
+# Overlay-Manifest – Register der eingebundenen Projektdokumente (Ebene 4)
+# Mechanismus: .koolie/project-overlay/OVERLAY.md Abschnitt 19. Nicht registrierte Dokumente gelten als K3.
+# Keine Secrets, keine Personen, keine internen Adressen. Rollen statt Personen.
+# Validierung: python3 .koolie/core/tests/scripts/validate-framework.py prüft Schema und Pflichtfelder.
+
+manifest_version: 1
+project_code: "<PROJECT_CODE>"
+overlay_version: "<TBD: 0.1.0>"
+
+# Entscheidungsprotokoll des Schutz-Hooks (D-487): Standard an, eine Zeile je Entscheidung in
+# .git/koolie-hook.jsonl, ohne Inhalt und ohne Pfad. Abschalten mit:
+# hook_protokoll: aus
+#
+# Fremde Agenten-Rahmenwerke (K-31, D-514): Skills eines anderen Rahmenwerks in der Skill-Ablage
+# des Clients (etwa OpenSpec, GitHub Spec Kit) hier mit ihrem Praefix deklarieren - der Validator
+# prueft sie dann nicht als Koolie-Skills (Pruefung 111); den Korb der Berechtigungsdatei
+# verlangt er weiter (Pruefung 72). install.py nennt erkannte Rahmenwerke. Beispiel:
+# fremde_skills: openspec-, speckit-
+
+# Zulässige Werte
+#   type:          ai-governance | ai-process-model | roadmap | architecture | coding-guidelines |
+#                  definition-of-ready | definition-of-done | branching-strategy | deployment |
+#                  security | quality | roles | glossary | other
+#   context_class: K1 | K2          (K3-Dokumente werden nicht registriert)
+#   status:        entwurf | aktuell | veraltet
+#   load:          summary | on-demand | rule | never
+#   approved_by:   generische Rolle
+
+# Kategoriefreigaben (02-privacy.md Abschnitt 3.4 und 4, Schritt 3; D-455). Ohne Eintrag gilt der Ausschluss.
+# Eine Freigabe gilt nie für eine Kategorie aus 02-privacy.md Abschnitt 2.1.
+# category_releases:
+#   - category: "Kommentarverläufe aus <ISSUE_TRACKER>"
+#     approved_by: "<APPROVAL_ROLE>"
+#     approved_on: "<TBD: Datum>"
+#     sanitization: "Personen, Kontaktdaten und Kundenangaben entfernen; nur Anforderung oder Entscheidung übernehmen"
+
+documents:
+  - id: "DOC-001"
+    type: "coding-guidelines"
+    title: "<TBD: Titel ohne Projekt- oder Kundenbezug>"
+    path: ".koolie/project-overlay/documents/coding-guidelines/<TBD: datei>.md"
+    context_class: "K1"
+    status: "entwurf"
+    load: "rule"
+    rule_file: "<RULES_DIR>/21-overlay-coding-guidelines.md"
+    approved_by: "<APPROVAL_ROLE>"
+    approved_on: "<TBD: Datum>"
+    sanitization: "<TBD: was vor der Einbindung entfernt wurde, oder 'nicht erforderlich'>"
+    notes: "<TBD>"
+
+  - id: "DOC-002"
+    type: "architecture"
+    title: "<TBD>"
+    path: ".koolie/project-overlay/documents/architecture/<TBD>.md"
+    context_class: "K2"
+    status: "entwurf"
+    load: "on-demand"
+    approved_by: "<ARCHITECT_ROLE>"
+    approved_on: "<TBD>"
+    sanitization: "<TBD: z. B. Kapitel Infrastruktur und Betriebsumgebungen entfernt>"
+    notes: "K2: Freigabe je Aufgabe erforderlich"
+
+  - id: "DOC-003"
+    type: "definition-of-done"
+    title: "<TBD>"
+    path: ".koolie/project-overlay/documents/definition-of-done/<TBD>.md"
+    context_class: "K1"
+    status: "entwurf"
+    load: "summary"
+    approved_by: "<APPROVAL_ROLE>"
+    approved_on: "<TBD>"
+    sanitization: "nicht erforderlich"
+    notes: "Kernaussagen in <RULES_DIR>/20-project-overlay.md übernehmen"

package/.koolie/core/templates/rules/21-overlay-TEMPLATE.md.template

@@ -0,0 +1,28 @@
+---
+description: Overlay-Regelerweiterung <TBD: Kurzbezeichnung, z. B. Coding Guidelines> für <PROJECT_NAME>. Anwenden bei <TBD: Situationen, z. B. Aufgaben in Modus M3 oder M4>.
+trigger: model_decision
+---
+
+<!-- AUSFÜLLHINWEIS: Kopiere diese Datei nach 2N-overlay-<name>.md (N = 1–9, ohne .template).
+     Mechanismus: .koolie/project-overlay/OVERLAY.md Abschnitt 19, Ladeverhalten "rule".
+     Für Coding Guidelines ist eine Bindung an die Dateimuster der Sprache geeignet; wie
+     sie bei diesem Client notiert wird, steht in der README der Regelablage. Kennt der
+     Client keine Bindung an Dateimuster, lädt die Regel immer (Zeilen R2 und R3 der
+     Fähigkeitsmatrix seines Packs).
+     Unter 12.000 Zeichen bleiben.
+     Inhalt: nur Kernregeln des registrierten Dokuments (Manifest-ID nennen), keine Lockerung
+     von Framework-Regeln, keine Personen, keine internen Adressen, keine Secrets. -->
+
+# Overlay-Regel: <TBD: Titel>
+
+Quelle: Manifest-Eintrag `<TBD: DOC-00N>`, Dokument `.koolie/project-overlay/documents/<typ>/<datei>.md` (Kontextklasse `<K1/K2>`). Diese Regel konkretisiert das Framework für `<PROJECT_NAME>`; bei Widerspruch gilt die restriktivere Regel.
+
+## Kernregeln
+
+1. `<TBD>`
+2. `<TBD>`
+3. `<TBD>`
+
+## Bei Bedarf vollständig lesen
+
+`<TBD: Pfad des Dokuments>` – nur, wenn die Aufgabe Details erfordert, die über die Kernregeln hinausgehen.

package/.koolie/core/templates/rules/40-tech-TEMPLATE.md.template

@@ -0,0 +1,33 @@
+---
+description: Technology Pack <TECH_PACK_NAME> (Ebene 5). Wird geladen, wenn der KI-Client Dateien liest oder ändert, die auf die unten stehenden Muster passen.
+trigger: glob
+globs: "<TBD: Dateimuster, zum Beispiel **/*.java oder src/**/*.ts>"
+---
+
+<!-- AUSFÜLLHINWEIS: Kopiere diese Datei nach 40-tech-<tech-pack-name>.md (ohne .template),
+     ersetze alle Platzhalter und entferne diesen Hinweis. Quelle und Detailfassung:
+     .koolie/core/framework/tech-packs/<tech-pack-name>/TECH_PACK.md. Ein Technology Pack enthält
+     ausschließlich technologische Konventionen – keine Governance-Regeln, keine Projektwerte. -->
+
+# Technology Pack <TECH_PACK_NAME> (Laufzeitfassung)
+
+## Sprach- und Framework-Konventionen
+
+- Sprachversion / Framework-Version: `<TBD>` (nur Funktionen dieser Version verwenden; Fundstelle in der Build-Konfiguration nennen)
+- Formatierung und Stil: `<TBD: Verweis auf Formatter-/Linter-Konfiguration im Repository>`
+- Bevorzugte Idiome: `<TBD>`
+- Zu vermeidende Muster: `<TBD>`
+
+## Build und Test
+
+- Build-System: `<TBD>` · Testframework: `<TEST_FRAMEWORK>`
+- Testkonventionen (Ablage, Benennung, Fixtures): `<TBD>`
+- Umgang mit Abhängigkeiten (Manifestdatei, Lockfile, Quelle): `<TBD>` – Änderungen nur durch den Menschen.
+
+## Typische Fehlerquellen bei KI-generiertem Code in dieser Technologie
+
+`<TBD: zum Beispiel veraltete APIs, nicht existierende Methoden bestimmter Bibliotheksversionen, falsche Null-Behandlung>`
+
+## Sicherheitsrelevante Muster dieser Technologie
+
+`<TBD: zum Beispiel Injection-Vektoren, Deserialisierung, Ressourcenfreigabe>`