@renoxar/koolie 1.25.0

package/.koolie/core/checklists/10-project-adoption.md

@@ -0,0 +1,74 @@
+# Checkliste FW-CL-10 – Projektübernahme
+
+| Attribut | Wert |
+|---|---|
+| ID | `FW-CL-10` |
+| Version | `0.1.5` |
+| Status | `pilot` |
+| Owner (Rolle) | `<FRAMEWORK_OWNER>` |
+| Wann | bei Übernahme des Frameworks in ein neues Projekt, vor dem Setzen des Overlay-Status auf `aktiv` |
+| Wer | Overlay Owner (`<APPROVAL_ROLE>`) mit Framework Owner; Beteiligung `<SECURITY_CONTACT>` und `<DATA_PROTECTION_CONTACT>` |
+| Dauer (Richtwert, Erläuterung) | verteilt über die Einführungsphase – keine verbindlichen Aufwände |
+| Nachweis | ausgefüllte Checkliste als Anlage zur Overlay-Aktivierung; Eintrag im Overlay-Änderungsverlauf |
+
+## Zweck
+
+Stellt sicher, dass ein neues Projekt das Framework vollständig, unverändert im Core und mit ausgefülltem Overlay übernimmt (`.koolie/core/docs/ADOPTION_GUIDE.md`; Grundsatz: Ein Projektwechsel betrifft nur Ebene 4).
+
+## Prüfpunkte
+
+### Voraussetzungen der Organisation
+
+- [ ] **MUSS** Freigabe der KI-Nutzung durch die Organisation liegt vor (Referenz im Overlay Abschnitt 1).
+- [ ] **MUSS** Ergebnis der Datenschutz- und Vertragsprüfung liegt vor und ist im Overlay referenziert (K-06; ohne Ergebnis bleibt die restriktivste Auslegung nach `.koolie/core/framework/core/02-privacy.md` Abschnitt 1.3).
+- [ ] **MUSS** Planstufe und administrativ erzwungene Team-Einstellungen sind dokumentiert (`.koolie/core/framework/org-policies/`, K-05); Training-Opt-out beziehungsweise vertragliche Regelung nachgewiesen (`<TBD: Nachweis der Einstellung>`).
+- [ ] **SOLL** Abbildung des Klassifizierungsschemas der Organisation auf K0–K3 liegt vor (`.koolie/core/framework/org-policies/MAPPING_CLASSIFICATION.md`).
+
+### Technische Integration
+
+- [ ] **MUSS** Framework-Release in das Projekt-Repository integriert: Kernverzeichnis `.koolie/core/` übernommen (D-354) und mit `install.py` Wurzel-Anweisungsdatei und Laufzeitschicht des gewählten Client Packs angelegt; Framework-Version **und gewähltes Client Pack** im Overlay notiert.
+- [ ] **MUSS** Belegte Pfade vor der Erstinstallation geklärt: Bricht `install.py` ab, ist der
+      vorhandene Inhalt nach `ADOPTION_GUIDE.md` Schritt 3a übernommen – nicht gelöscht und
+      nicht überschrieben. Führt das Projekt ein anderes Agenten-Framework, ist die
+      Zuständigkeit für die Wurzel-Anweisungsdatei ausdrücklich entschieden (K-31).
+- [ ] **MUSS** Core-Dateien unverändert (Abgleich gegen das Release-Archiv; Änderungsbedarf läuft als Änderungsantrag an den Framework Owner, nie als lokale Änderung).
+- [ ] **MUSS** `.koolie/project-overlay/OVERLAY.md` vollständig ausgefüllt; sicherheitsrelevante Abschnitte 4, 5, 6, 13, 14, 15 ohne offene `<TBD>`.
+- [ ] **MUSS** `20-project-overlay.md` in der Regelablage synchron zur Overlay-Datei befüllt (bei Clients mit Zeichenlimit unter 6.000 Zeichen).
+- [ ] **MUSS** Berechtigungsdatei mit den Overlay-Werten befüllt (`<ALLOWED_PATHS>`, `<EXCLUDED_PATHS>`, Befehle, CI-/Gate-Pfade); bei einer Berechtigungsdatei im JSON-Format alle Kernregeln aus `_core_rules_integrity` unverändert enthalten (`openai-codex` führt den Block nicht, D-395).
+- [ ] **MUSS** `.koolie/project-overlay/overlay-manifest.yaml` gepflegt; eingebundene Dokumente bereinigt und freigegeben; nicht registrierte Dokumente gelten als K3.
+- [ ] **MUSS** Benötigte Role Packs und Technology Packs aktiviert (Laufzeitfassungen `30-*`, `40-*` erstellt); nicht benötigte nicht geladen.
+- [ ] **MUSS** `.koolie/project-overlay/forbidden-terms.txt` projektlokal mit den realen Namen des Projekts befüllt (Datei verbleibt projektlokal).
+- [ ] **MUSS** `python3 .koolie/core/tests/scripts/validate-framework.py
+      --check-overlay-ready` läuft ohne Fehler. **Das ist die Kandidatenprüfung**: Sie
+      erwartet einen Overlay-Status, der noch **nicht** `aktiv` ist, und prüft alles
+      übrige auf Vollständigkeit (B08, D-57).
+- [ ] **MUSS** Nach dem Setzen des Status auf `aktiv`:
+      `python3 .koolie/core/tests/scripts/validate-framework.py --strict-overlay`
+      läuft ohne Fehler. Erst danach beginnt der erste Agentenlauf mit
+      Schreibrechten.
+- [ ] **MUSS** `python3 .koolie/core/install.py --probe` endet ohne fehlende
+      Muss-Kontrolle: Der Schutz-Hook sperrt im Projekt, die Konfiguration lädt, und
+      der Client vertraut dem Projekt, wo das Pack es verlangt. Die Probe braucht kein
+      Modell (D-488). Warnungen und „unerhoben“ werden gelesen und, wo nötig, im Overlay
+      begründet.
+
+### Organisation im Projekt
+
+- [ ] **MUSS** Rollen zugeordnet (außerhalb des Repositorys): Overlay Owner, `<SECURITY_CONTACT>`, `<DATA_PROTECTION_CONTACT>`, `<PRODUCT_OWNER_ROLE>`, `<ARCHITECT_ROLE>`, Mentorinnen und Mentoren.
+- [ ] **MUSS** Eskalationswege (Overlay Abschnitt 16) mit erreichbaren Kanälen hinterlegt.
+- [ ] **MUSS** Basistests des Testkatalogs auf dem Übungsrepository ausgeführt (mindestens die Klassen PI, DS, SC aus `.koolie/core/tests/TEST_CATALOG.md`); Ergebnisse dokumentiert.
+- [ ] **MUSS** Onboarding für die ersten Nutzerinnen und Nutzer geplant (`.koolie/core/checklists/09-onboarding.md`); bis zur Freigabe arbeiten alle begleitet.
+- [ ] **SOLL** Pilotparameter festgelegt (`.koolie/core/pilot/PILOT_CONCEPT.md`: Referenzbasis, Pilotgruppe, `<PILOT_DURATION>`, Anwendungsfälle, Review-Punkte).
+- [ ] **SOLL** Ablageorte für Ergebnisberichte und Pläne bestimmt (`<TBD: Ablageort für Ergebnisberichte>`, `<TBD: Ablage von Plänen im Projekt>`).
+
+### Aktivierung
+
+- [ ] **MUSS** Overlay-Status in OVERLAY.md und `20-project-overlay.md` auf `aktiv` gesetzt; Version und Datum im Overlay-Änderungsverlauf; diese Checkliste als Nachweis abgelegt.
+
+## Abbruch- und Eskalationskriterien
+
+Fehlende Organisationsfreigabe oder Datenschutzprüfung stoppt die Übernahme (E2/E3-Vorstufe). Änderungsbedarf am Core, der die Übernahme blockiert, geht als Änderungsantrag an den Framework Owner (E4) – das Projekt wartet auf ein Release oder eine dokumentierte Ausnahme.
+
+## Ergebnis und Nachweis
+
+Vollständig abgehakte Liste mit Referenzen (Freigaben, Validierungslauf, Testkatalog-Ergebnisse) als Anlage der Overlay-Aktivierung; Eintrag im Overlay-Änderungsverlauf und Meldung an den Framework Owner (Bestandsliste der Projekte).

package/.koolie/core/checklists/11-framework-release.md

@@ -0,0 +1,71 @@
+# Checkliste FW-CL-11 – Framework-Release
+
+| Attribut | Wert |
+|---|---|
+| ID | `FW-CL-11` |
+| Version | `0.4.3` |
+| Status | `pilot` |
+| Owner (Rolle) | `<FRAMEWORK_OWNER>` |
+| Wann | vor jedem Framework-Release (auch Patch-Releases) |
+| Wer | Framework Owner; Zuarbeit Modul-Owner |
+| Dauer (Richtwert, Erläuterung) | abhängig vom Änderungsumfang – keine verbindlichen Aufwände |
+| Nachweis | Release-Eintrag in `.koolie/core/CHANGELOG.md`; abgelegte Checkliste; Testkatalog-Protokoll |
+
+## Zweck
+
+Sichert, dass ein Release konsistent, projektneutral, getestet und für übernehmende Projekte nachvollziehbar ist (`.koolie/core/governance/RELEASE_PROCESS.md`).
+
+Die mit **(ab 1.0.0, D-11)** gekennzeichneten Prüfpunkte gelten erst für das Release 1.0.0 und darüber; sie bilden die Kriterien aus Decision Record D-11 ab (`CR-2026-001`). Pilot, Onboarding und organisatorische Freigabe sind **keine** Prüfpunkte dieser Checkliste – sie liegen projektseitig (`.koolie/core/checklists/10-project-adoption.md`).
+
+## Prüfpunkte
+
+### Inhalt und Konsistenz
+
+- [ ] **MUSS** Alle für das Release vorgesehenen Änderungsanträge sind abgeschlossen oder ausdrücklich verschoben (`.koolie/core/governance/DECISION_LOG.md` aktualisiert).
+- [ ] **MUSS** Konsistenz Core ↔ Laufzeitfassung geprüft: `.koolie/core/framework/core/*` gegen die Wurzel-Anweisungsdatei und die Regelablage `00-*, 10-*, 15-*` **jedes Client Packs** (Stichproben je geändertem Modul; keine widersprüchlichen Anweisungen).
+- [ ] **MUSS** Skills konsistent zum Skill-Standard (`.koolie/core/framework/core/08-skill-conventions.md`); Versionen, Status und CHANGELOG je geändertem Skill gepflegt; Deprecations mit Nachfolger dokumentiert.
+- [ ] **MUSS** Version je geänderter Checkliste und je geändertem Prompt gepflegt (Metadatentabelle, Semantic Versioning wie in `.koolie/core/governance/RELEASE_PROCESS.md` Abschnitt 1; Testfall `FW-VN-01`). **Ein reiner Statuswechsel ist keine Änderung im Sinne dieses Prüfpunkts** (`.koolie/core/framework/core/01-governance.md` Abschnitt 5 Punkt 5, D-106), weil er keine Anweisung ändert.
+- [ ] **MUSS** Prioritätshierarchie unverändert oder Änderung begründet und in `.koolie/core/governance/PRIORITY_HIERARCHY.md` nachgezogen.
+- [ ] **SOLL** Templates, Checklisten und Entscheidungsbäume gegen geänderte Module abgeglichen (Querverweise, Begriffe).
+- [ ] **MUSS** Jedes geänderte Dokument gegen die Kriterien seiner Klasse gehalten (`.koolie/core/docs/DOCUMENTATION_STANDARD.md`, D-371); die Prüfungen 91 bis 94 laufen mit dem Validator.
+- [ ] **SOLL** Bei einem wesentlich geänderten Dokument der Klasse A (Einstieg) die Kaltleser-Probe gefahren und im Protokoll festgehalten (D-379).
+
+### Projektneutralität
+
+- [ ] **MUSS** `python3 .koolie/core/tests/scripts/validate-framework.py` ohne Fehler; Warnungen bewertet.
+- [ ] **MUSS** `.koolie/project-overlay/forbidden-terms.txt` ist im Release leer (projektlokale Sperrlisten verbleiben in den Projekten).
+- [ ] **MUSS** Manuelle Stichprobe auf projekt-, kunden- oder personenspezifische Inhalte in geänderten Dateien (zusätzlich zur automatischen Prüfung).
+- [ ] **MUSS** Beispiele sind synthetisch gekennzeichnet; Platzhalterregister aktuell.
+
+### Produktstand der KI-Client
+
+- [ ] **MUSS** Aktualitätsprüfung gegen die offizielle Clientdokumentation durchgeführt (Changelog des Produkts gesichtet; betroffene `[DOK]`-Aussagen und Belegzellen mit `BELEG OFFEN` aktualisiert; Quellenliste im Hauptdokument nachgezogen).
+- [ ] **MUSS** Produktänderungen mit Regelwirkung (neue Berechtigungen, geänderte Pfade, entfallene Mechanismen) sind als Änderungsanträge behandelt (`.koolie/core/governance/RELEASE_PROCESS.md` Abschnitt 6).
+
+### Tests
+
+- [ ] **MUSS** Testkatalog vollständig ausgeführt (`.koolie/core/tests/TEST_CATALOG.md`): Konsistenz-, Positiv-, Negativ-, Datenschutz-, Prompt-Injection-, Scope-, Fehlende-Informationen-, Zugriffs-, Regressions-, Versions- und Aktualitätstests; Ergebnisse je Test-ID dokumentiert.
+- [ ] **MUSS** (ab 1.0.0, D-11) Kein Testfall des Katalogs steht auf Ergebnisstatus `offen`; jeder trägt `bestanden`, `fehlgeschlagen (Referenz)` oder `nicht anwendbar (Begründung)`.
+- [ ] **MUSS** Skill-Testfälle (`TESTS.md` je Skill) für alle geänderten Skills erneut ausgeführt.
+- [ ] **MUSS** Hook- und Validierungsskripte laufen fehlerfrei (Selbsttest der Skripte).
+- [ ] **MUSS** Jedes **Abnahmeprotokoll des Testkatalogs** trägt einen Abschnitt *Gegenzeichnung* ohne offenes `<TBD>` (Prüfung 80). **Die Pflicht gilt ausschließlich für diese Protokolle** – Dateiname `JJJJ-MM-TT-FW-<Klasse>-<NN>.md` –, nicht für Arbeits- und Messprotokolle, weil eine Gegenzeichnung eine Abnahme bestätigt und ein Messprotokoll seinen Beleg in sich trägt (D-319, `CR-2026-127` E1). **Ist keine zweite Rolle vorhanden, wird selbst gegengezeichnet und der Abschnitt weist das ausdrücklich als „Selbstgegenzeichnung“ aus** – die Zusage der zweiten Rolle ist damit zurückgenommen, nicht erfüllt.
+- [ ] **SOLL** Mindestens ein vollständiger Durchlauf des Standardarbeitsablaufs auf dem Übungsrepository (M1 → M2 → M3 → M4) ohne Regelverstoß.
+
+### Abschluss
+
+- [ ] **MUSS** `.koolie/core/VERSION` nach Semantic Versioning erhöht; `.koolie/core/CHANGELOG.md` mit Änderungen, Migrationshinweisen für Overlays und bekannten Einschränkungen ergänzt.
+- [ ] **MUSS** **Als letzter Eingriff in den Kern, vor dem Release-Commit:** Übernehmende Projekte gehoben – Kern aus dem **Arbeitsbaum** kopiert, beschränkt auf das Verfolgte (D-333), dann `install.py --update` (beides in einem Aufruf mit `--target`, D-362), Overlay-Wert in **drei** Trägern nachgezogen, `validate-framework.py --strict-overlay` dort gefahren **und im übernehmenden Projekt committet** (D-343) – und die Bestandsliste `.koolie/core/governance/ADOPTION_REGISTRY.md` **vorher** auf den Zielstand fortgeschrieben (Prüfung 82). **Ausnahmslos, auch bei einem Patch-Release, das kein ausgeliefertes Artefakt berührt** (D-330), weil das Heben ein Lauf gegen eine fremde Installation ist und findet, was kein Validatorlauf im Framework findet.
+- [ ] **MUSS** **Vor dem Release-Commit:** Erzeugnisse der Lieferung gebaut – Hauptdokument und Word-Fassung **je Client Pack** – und **im Erzeugnis nachgezählt** (D-332). Keine Prüfung erreicht sie, weil sie unter `build/out/` liegen und in der `.gitignore` stehen (`K-110`).
+- [ ] **MUSS** Freigabe des Releases durch den Framework Owner dokumentiert – **in der Nachricht der signierten Marke** (`RELEASE_PROCESS.md` Abschnitt 4.1 Schritt 4). **Die Marke trägt die Unterschrift, der Release-Commit nicht** (D-334); deshalb setzt sie der Mensch und nicht ein Werkzeug. Keine Prüfung erreicht den Markentext – er liegt im Tag-Objekt, nicht im Arbeitsbaum (`K-111`).
+- [ ] **MUSS** **Nach dem Release-Commit:** Release-Archiv aus der signierten Marke erzeugt, **im Erzeugnis nachgezählt** und samt Prüfsumme außerhalb des Repositoriums abgelegt; Mitteilung mit Migrationshinweisen und betroffenen Overlay-Feldern an die übernehmenden Projekte. **Das Archiv kann vor dem Commit nicht erzeugt werden** – es entsteht aus der Marke, und die sitzt auf dem Release-Commit (D-329). Ablauf: `.koolie/core/governance/RELEASE_PROCESS.md` Abschnitt 4.1 Schritte 5 bis 7.
+- [ ] **MUSS** (ab 1.0.0, D-11) Alle Core-Module, Skills und Packs tragen einen Status oberhalb von `entwurf`; die Statuszeile jedes Modulträgers setzt Prüfung 47 durch (D-105).
+- [ ] **MUSS** (ab 1.0.0, D-11) Kein Decision Record in `.koolie/core/governance/DECISION_LOG.md` trägt den Status `entschieden (Vorschlag)`.
+- [ ] **MUSS** (ab 1.0.0, D-11) Übernahme in mindestens ein zweites Projekt nach `.koolie/core/checklists/10-project-adoption.md` nachgewiesen.
+
+## Abbruch- und Eskalationskriterien
+
+Fehlschläge im Testkatalog, offene Konsistenzbefunde oder Projektneutralitätsverstöße stoppen das Release (E4). Sicherheitsrelevante Befunde folgen `.koolie/core/governance/INCIDENT_HANDLING.md`.
+
+## Ergebnis und Nachweis
+
+Release-Eintrag im `.koolie/core/CHANGELOG.md`, Testkatalog-Protokoll, abgelegte Checkliste und Archivreferenz bilden zusammen den Audit-Nachweis des Releases.

package/.koolie/core/checklists/README.md

@@ -0,0 +1,28 @@
+# Checklisten
+
+Operative Prüf- und Arbeitslisten des Frameworks. Checklisten sind normative Kurzform der Core-Regeln für einen konkreten Moment im Arbeitsablauf; bei Widerspruch gilt das jeweilige Core-Modul. Prüfpunkte tragen die Verbindlichkeit **MUSS**, **SOLL** oder **KANN**; die Nachweisführung steht je Liste im Kopf.
+
+| ID | Datei | Wann | Wer |
+|---|---|---|---|
+| FW-CL-01 | `01-preflight.md` | vor jeder KI-Aufgabe | Bearbeiterin oder Bearbeiter |
+| FW-CL-02 | `02-privacy-context.md` | im Preflight und vor jeder Kontextbereitstellung | Bearbeiterin oder Bearbeiter; Freigaben `<APPROVAL_ROLE>` / `<DATA_PROTECTION_CONTACT>` |
+| FW-CL-03 | `03-before-code-change.md` | vor dem ersten Schreib- oder Ausführungsschritt (M3/M4/M5) | Bearbeiterin oder Bearbeiter |
+| FW-CL-04 | `04-review-ai-code.md` | Selbstreview vor Commit; unabhängiges Review im Merge Request | Bearbeiter und Reviewer |
+| FW-CL-05 | `05-testing.md` | nach Testerstellung; vor Merge Requests mit Logikänderung | Bearbeiter; Reviewer (RV4) |
+| FW-CL-06 | `06-security.md` | bei R3/R10/R11-Bezug; ergänzend bei Stufe hoch | Bearbeiter; `<SECURITY_CONTACT>` |
+| FW-CL-07 | `07-new-dependency.md` | vor Einführung neuer Abhängigkeiten oder Major-Updates | Mensch (nie der KI-Client); Freigaben `<APPROVAL_ROLE>` / `<SECURITY_CONTACT>` |
+| FW-CL-08 | `08-merge-request.md` | vor Erstellen und vor Mergen eines Merge Requests | Bearbeiter; Reviewer und freigebende Rollen |
+| FW-CL-09 | `09-onboarding.md` | während des Onboardings bis zur Freigabe | Mentorin oder Mentor mit der oder dem Neuen |
+| FW-CL-10 | `10-project-adoption.md` | Übernahme in ein neues Projekt, vor Overlay-Aktivierung | Overlay Owner mit Framework Owner |
+| FW-CL-11 | `11-framework-release.md` | vor jedem Framework-Release | Framework Owner |
+
+## Verwendung
+
+1. Die Liste wird zum genannten Zeitpunkt vollständig durchgegangen; nicht zutreffende Punkte werden als „n. z." markiert, nicht übersprungen.
+2. Unerfüllte MUSS-Punkte stoppen den jeweiligen Schritt; die Abbruch- und Eskalationskriterien der Liste verweisen auf `.koolie/core/framework/core/10-error-escalation.md`.
+3. Der Nachweis erfolgt an der im Kopf der Liste genannten Stelle (Ergebnisbericht, Merge Request, Protokoll) – Checklisten werden nicht als Kopien im Repository abgelegt.
+4. Projekte KÖNNEN Punkte ergänzen (Verschärfung über das Overlay), DÜRFEN aber keine MUSS-Punkte entfernen.
+
+## Pflege
+
+Checklisten sind versioniert (Metadatentabelle) und folgen dem Framework-Release-Prozess. Verbesserungsvorschläge laufen über `.koolie/core/governance/FEEDBACK_PROCESS.md`.