@renoxar/koolie 1.25.0

package/.koolie/core/governance/change-requests/CR-2026-019-strukturentscheidungen-fortschreiben.md

@@ -0,0 +1,143 @@
+# Änderungsantrag `CR-2026-019`
+
+| Feld | Inhalt |
+|---|---|
+| Titel | Acht der zehn Strukturentscheidungen beschrieben einen Stand, den es nicht mehr gibt |
+| Antragstellende Rolle | `<FRAMEWORK_OWNER>` |
+| Datum | 2026-09-10 |
+| Betroffene Artefakte | `governance/DECISION_LOG.md` (Abschnitt 2, D-01 bis D-10) |
+| Ebene laut Entscheidungsbaum 6 | Governance-Dokumentation; keine Regelebene |
+| Art | Fortschreibung; Vorbedingung für Kriterium 4 aus D-11 |
+| Dringlichkeit | regulär |
+
+## 1. Anlass und Problem
+
+Kriterium 4 aus D-11 verlangt für Release 1.0.0, dass **kein** Decision Record mehr den Status
+`entschieden (Vorschlag)` trägt. Zehn tun es: D-01 bis D-10, sämtlich datiert auf den
+**2026-09-01**, den Tag der Erstfassung.
+
+Sie zu bestätigen setzt voraus, dass sie beschreiben, was gilt. Das taten sie nicht. Zwischen
+ihrer Niederschrift und heute liegen sechzehn Releases und die Decision Records D-11 bis D-27 –
+und die haben acht der zehn an mindestens einer Stelle überholt, ohne dass es jemand vermerkt
+hätte. Fortgeschrieben war genau **einer** (D-02, durch `CR-2026-002`); ein weiterer ist ersetzt
+(D-09 durch D-11).
+
+Das ist derselbe Befundtyp wie `FW-VN-01` und `CR-2026-018`, eine Ebene höher: **Eine Angabe, die
+sich nie bewegt, während sich ihr Gegenstand bewegt, sagt irgendwann nichts mehr.** Bei `FW-VN-01`
+waren es Versionsfelder, bei `CR-2026-018` die Quellenliste, hier die Grundentscheidungen selbst.
+
+Die acht Befunde fallen in zwei Gruppen.
+
+**Vier waren überholt – sie nannten Pfade und Produktnamen eines einzelnen Clients:**
+
+| ID | Was dort stand | Seit wann überholt |
+|---|---|---|
+| D-03 | „Skills liegen unter `.devin/skills/<skill-name>/`" | D-15 (Begriffe statt Pfade), D-16 (eine Quelle, je Client gerendert), D-26 (`triggers` wird abgebildet statt verworfen) |
+| D-04 | „Berechtigungen werden versioniert in `.devin/config.json`" | D-15, D-18 (Semantikabbildung, Kernregelintegrität), D-22 (Schreibverbot auf das gesamte Kernverzeichnis), D-26 (Pfadregeln nur für pfadauswertende Werkzeuge) |
+| D-05 | „Der Permission-Modus `Bypass` … `Smart` und `Accept Edits` … Standard ist `Normal`" | D-15; zusätzlich seit AP2 technisch sperrbar (AP2-CC-05), mit einer offenen Teilfrage (AP2-CC-12) |
+| D-10 | „Devin Cloud, Devin CLI und ACP-Fremdagenten" | D-15, D-19 (der Kern nennt keinen Produktnamen, wo er die Sache meint) |
+
+Das ist bemerkenswert, weil D-15 und D-19 genau das behoben haben – im **Kern**. 61 von 63
+Client-Bindungen wurden ersetzt, der Name des Frameworks wurde geändert, 994 Pfadnennungen
+angefasst. Das Decision Log lag außerhalb dieses Umfangs, und niemandem fiel auf, dass die
+Entscheidungen, die den werkzeugneutralen Kern begründen, selbst client-gebunden formuliert
+waren.
+
+**Vier waren richtig, aber unvollständig:**
+
+| ID | Was fehlte |
+|---|---|
+| D-01 | Die Zählung „vier Ebenen plus zwei Querschnittsebenen" meint die Regelebenen; die Prioritätshierarchie führt acht Stufen, weil zwischen den Packs und der Nutzeranweisung noch die **Skills** stehen |
+| D-06 | Das Verschärfungsprinzip ist seit D-18 an der Stelle, an der die Kernzusagen hängen, eine **geprüfte Eigenschaft** und keine Zusage mehr; D-27 zieht das für die Ladebedingung nach und zieht ihre Grenze |
+| D-07 | D-24 hat die K3-Definition um die **Auffangkategorie** nachgeschärft und festgelegt, dass eine normative Liste vollständig in der Laufzeitschicht stehen muss |
+| D-08 | Die Begründung war eine **Vorsichtsannahme** („Toleranz unbekannter Frontmatter-Schlüssel nicht belegt"). Für `claude-code` ist die Lage inzwischen geklärt und stützt die Entscheidung; für `devin-desktop` bleibt sie unbelegt |
+
+## 2. Vorgeschlagene Änderung
+
+**Jeder der acht Records bekommt eine Fortschreibung im Statusfeld**, nach dem Muster, das D-02
+seit `CR-2026-002` verwendet: Der ursprüngliche Wortlaut bleibt unverändert stehen, die
+Fortschreibung nennt, was seither gilt und durch welchen Record.
+
+Der ursprüngliche Wortlaut bleibt aus zwei Gründen stehen. Erstens ist ein Decision Log ein
+Verlaufsdokument: Wer wissen will, warum eine Entscheidung so getroffen wurde, braucht die
+Begründung von damals und nicht die von heute. Zweitens ist der Unterschied selbst die Aussage –
+dass D-04 am 2026-09-01 einen Client-Pfad nannte, erklärt, warum es D-15 gebraucht hat.
+
+**Die Statusänderung selbst ist nicht Gegenstand dieses Antrags.** Ob ein Record von
+`entschieden (Vorschlag)` auf `entschieden` geht, ist eine Entscheidung des
+`<FRAMEWORK_OWNER>` und nicht die Folge einer Textpflege. Abschnitt 4 legt sie je Record vor.
+
+**Was verworfen wurde:**
+
+- **Den Wortlaut korrigieren statt fortzuschreiben.** Dann stünde im Decision Log, D-04 habe am
+  2026-09-01 die Semantikabbildung aus D-18 vorgesehen. Das wäre falsch und würde die
+  Nachvollziehbarkeit zerstören, für die es das Dokument gibt.
+- **Die Records ersetzen, wie D-09 durch D-11 ersetzt wurde.** Angemessen, wenn eine Entscheidung
+  *anders* ausfällt – D-09 hatte 1.0.0 an eine Pilotauswertung gebunden, D-11 tut das
+  ausdrücklich nicht. Hier fällt keine Entscheidung anders aus; nur ihre Beschreibung ist
+  veraltet.
+- **Gleich auf `entschieden` setzen.** Die Fortschreibung ist die Vorbedingung, nicht die
+  Entscheidung. Ein Record, dessen Status ein Skript ändert, ist kein Governance-Artefakt mehr.
+- **Nur D-04 fortschreiben, wie in der Roadmap vorgesehen.** Er war der auffälligste, aber nicht
+  der einzige. Sieben weitere in demselben Zustand stehen zu lassen, hieße den Befund zu kennen
+  und nur seinen sichtbarsten Teil zu beheben.
+
+## 3. Was dieser Antrag nicht ändert
+
+Keine Entscheidung fällt anders aus. Kein Mechanismus, keine Regel, keine Einstufung ändert sich.
+Weder Installation noch Validator noch Laufzeitschicht sind betroffen; es gibt keine Sonde nach
+D-23, weil keine Prüfung hinzukommt oder sich ändert.
+
+Zwei Records bleiben unverändert: **D-02** ist seit `CR-2026-002` fortgeschrieben, **D-09** ist
+durch D-11 ersetzt und trägt deshalb keinen Vorschlagsstatus mehr.
+
+## 4. Vorlage zur Entscheidung: Statuswechsel je Record
+
+`<FRAMEWORK_OWNER>` entscheidet je Zeile. Die Spalte „Einwand" nennt, was einer Bestätigung
+heute entgegenstehen könnte – sie ist der eigentliche Gegenstand der Vorlage.
+
+| ID | Gegenstand | Einwand gegen eine Bestätigung |
+|---|---|---|
+| D-01 | Ebenenmodell | keiner erkennbar; die Ebenen tragen seit 0.1.0 unverändert |
+| D-02 | Lang- und Laufzeitform | keiner erkennbar; fortgeschrieben durch D-12 bis D-14 |
+| D-03 | Skill-Struktur | keiner erkennbar; die Vier-Dateien-Struktur ist über zwölf Skills und sechzehn Releases getragen |
+| D-04 | Berechtigungsdatei | keiner erkennbar; die Kernzusagen B1 bis B6 hängen daran und sind seit D-18 geprüft statt zugesagt |
+| D-05 | Berechtigungsmodi | **Ja:** Die Ausnahmeregel für den Modus mit automatischer Übernahme ist nie in einem realen Projekt angewandt worden, und AP2-CC-12 ist offen. Eine Bestätigung wäre vertretbar, eine Zurückstellung bis AP2 ebenfalls |
+| D-06 | Prioritätshierarchie | keiner erkennbar; seit D-18 und D-27 in ihrem tragenden Teil geprüft |
+| D-07 | Kontextklassen | **Ja, geringfügig:** K-20 (Codebasis-Indexierung) ist bei `devin-desktop` unbelegt; das Datenschutzmodell setzt eine Aussage darüber voraus. Bei `claude-code` ist die Abwesenheit belegt (X2) |
+| D-08 | Metadaten im Dateikörper | keiner erkennbar; für einen Client belegt, für den anderen weiterhin die sichere Annahme |
+| D-09 | Versionierung | entfällt – ersetzt durch D-11 |
+| D-10 | Erweiterungsmodule | **Ja:** K-04 (Nutzungsumfang Cloud/CLI) ist offen und liegt außerhalb des Frameworks. Solange die Organisation ihn nicht festgelegt hat, ist „vorgesehen, standardmäßig deaktiviert" eine Zusage ohne Gegenüber |
+
+Drei Records tragen damit einen benannten Einwand (D-05, D-07, D-10), sieben keinen. Kriterium 4
+aus D-11 ist erreichbar, sobald über diese drei entschieden ist – durch Bestätigung oder durch
+eine ausdrückliche Zurückstellung mit Bedingung.
+
+## 5. Prüffragen (durch Owner auszufüllen)
+
+- [x] Richtige Ebene nach Entscheidungsbaum 6? — Ja. Geändert wird ein Governance-Dokument. Keine Regel wird eingeführt, keine gelockert.
+- [x] Verschärfungsprinzip eingehalten? — Nicht berührt; keine Regel ändert sich.
+- [x] Widerspruchsfreiheit geprüft? — Der Widerspruch war der Anlass: Acht Records beschrieben einen Stand, den spätere Records ersetzt hatten. Nach der Fortschreibung nennt jeder Record den späteren, der ihn überholt.
+- [x] Laufzeitfassungen betroffen? — Nein.
+- [x] Belegstatus korrekt? — Jede Fortschreibung nennt den Record, aus dem sie folgt. Die einzige Aussage über einen Client stützt sich auf AP2 (D-05, D-08).
+- [x] Test- und Validierungsbedarf? — Keine Sonde; die Änderung fügt keine Prüfung hinzu und ändert keine. Validator und `install.py --check` laufen unverändert.
+- [x] Auswirkungen auf Overlays und laufende Onboardings? — Keine.
+- [x] Dokumentation? — CHANGELOG, Roadmap, Decision Log.
+
+## 6. Entscheidung
+
+| Feld | Inhalt |
+|---|---|
+| Entscheidung | angenommen |
+| Entscheidende Rolle | `<FRAMEWORK_OWNER>` |
+| Begründung | Ein Decision Log, dessen älteste Einträge einen Stand von vor sechzehn Releases beschreiben, ist keine Entscheidungsgrundlage, sondern ein Archiv, das sich für eine hält. Dass ausgerechnet die vier Records, die den werkzeugneutralen Kern begründen, selbst client-gebunden formuliert waren, ist der Befund – D-15 und D-19 haben den Kern von seinen Client-Bindungen befreit und das Dokument übersehen, das sie angeordnet hat. |
+| Ziel-Release | 0.17.0 |
+| Decision-Log-Eintrag | keiner – der Antrag schreibt bestehende Records fort und führt keine neue Festlegung ein |
+
+## 7. Umsetzung (nach Annahme)
+
+- [x] D-01, D-03 bis D-08 und D-10 fortgeschrieben; Wortlaut und Begründung von 2026-09-01 unverändert stehen gelassen
+- [x] Je Fortschreibung ist der spätere Record genannt, aus dem sie folgt
+- [x] Validator 0 Fehler, 0 Warnungen; `install.py --check` unverändert; Hauptdokument baut für beide Packs
+- [ ] **Zur Entscheidung offen:** der Statuswechsel je Record (Abschnitt 4). Drei tragen einen benannten Einwand: D-05 (AP2-CC-12 offen), D-07 (K-20 bei `devin-desktop` unbelegt), D-10 (K-04 offen)
+- [ ] **Folgearbeit:** Die Klärungspunkte K-04 und K-20 liegen außerhalb des Frameworks beziehungsweise an AP2. Solange sie offen sind, ist ein Statuswechsel bei D-07 und D-10 eine bewusste Entscheidung unter Unsicherheit, keine Formalie

package/.koolie/core/governance/change-requests/CR-2026-020-akteursbezeichnung.md

@@ -0,0 +1,118 @@
+# Änderungsantrag `CR-2026-020`
+
+| Feld | Inhalt |
+|---|---|
+| Titel | Der werkzeugneutrale Kern nannte einen Client als Handelnden |
+| Antragstellende Rolle | `<FRAMEWORK_OWNER>` |
+| Datum | 2026-09-10 |
+| Betroffene Artefakte | 93 Dateien des Kerns; `tests/scripts/validate-framework.py` (Prüfung 14 neu) |
+| Ebene laut Entscheidungsbaum 6 | Framework Core und Kerndokumentation; keine neue Regelebene |
+| Art | Neutralisierung mit Durchsetzung; Folgearbeit zu D-15 und D-19 |
+| Dringlichkeit | regulär |
+
+## 1. Anlass und Problem
+
+D-02 ordnet einen werkzeugneutralen Kern an. D-15 und D-19 haben ihn eingelöst, soweit es
+**Pfade** betraf: 63 Client-Bindungen und 994 Pfadnennungen ersetzt, ein Glossar als Abbildung.
+Die **Akteursbezeichnung** lag außerhalb dieses Umfangs und blieb stehen.
+
+Der Kern schrieb deshalb nicht vor, was ein KI-Client tun MUSS, sondern was **Devin** tut – in
+normativen Sätzen, in Rollenspalten, in der Delegationsverbotsliste, in den Abbruchbedingungen.
+Ein zweites Client Pack existiert seit 0.6.0; für dessen Nutzer benannten diese Regeln ein
+Produkt, das sie nicht einsetzen.
+
+**Der Umfang war größer als angenommen.** Die Roadmap führte den Punkt seit 0.13.0 mit „76
+Nennungen in elf Modulen" – gezählt allein in `framework/core/`. `docs/RUNTIME_GLOSSARY.md`
+definiert den Kern jedoch ausdrücklich weiter: `framework/`, `governance/`, `checklists/`,
+`prompts/`, `decision-trees/`, `onboarding/`, `docs/`, `templates/`, `examples/`, `tests/`.
+Danach gezählt waren es **248 Akteursnennungen in 78 Dateien**, dazu die Quellen des
+Hauptdokuments unter `build/doc/` und vier Skripte unter `tests/scripts/`.
+
+Der größte Einzelposten war `templates/project-overlay/OVERLAY.md` mit 19 Nennungen – die
+Vorlage, die **jedes aufnehmende Projekt** ausfüllt und in der der Produktname damit in jede
+Übernahme weitergereicht wurde.
+
+Derselbe Befundtyp wie `CR-2026-018` und `CR-2026-019`: eine Zusage, die nie vollständig gegen
+ihren eigenen Gegenstand gehalten wurde. Die Zählung, die den Rest offen hielt, war selbst zu
+klein – und niemand hat sie nachgerechnet.
+
+## 2. Vorgeschlagene Änderung
+
+**Der Kern nennt den Handelnden beim Begriff: „der KI-Client".** Der Begriff steht bereits in
+`docs/RUNTIME_GLOSSARY.md` und war im Kern an sieben Stellen in Gebrauch; er wird jetzt
+durchgängig verwendet. Komposita folgen dem im Kern schon vorhandenen Präfix `KI-`
+(`KI-Aufgabe`, `KI-Vorschlag`, `KI-Ergebnis`, `KI-Sitzung`) – die Kurzform verwendete
+`KI-Ergebnis` und `KI-Nutzung` bereits.
+
+**Der Produktname bleibt, wo ein Produkt gemeint ist.** „Devin Desktop", „Devin Local",
+„Devin-Desktop-Installation", die Pack-Kennungen, die Laufzeitpfade und die Quellen-Domains
+sind unverändert: Sie benennen ein Produkt, nicht den Handelnden. Muss ein Kerntext den Namen
+selbst tragen, steht dort `<CLIENT_NAME>`.
+
+**Historische Dokumente bleiben unverändert** – `CHANGELOG.md` (auch die der Skills),
+`governance/change-requests/`, `governance/DECISION_LOG.md`, `tests/protocols/`. Sie beschreiben
+einen vergangenen Zustand; ihn nachträglich zu glätten, zerstört die Nachvollziehbarkeit
+(`RUNTIME_GLOSSARY.md`, Abschnitt „Regel").
+
+**Prüfung 14 setzt das durch.** Ohne sie wäre die Neutralität eine Zusage, die beim nächsten
+von Hand geschriebenen Absatz verfällt – genau das Muster, das D-25 für Versionsfelder
+beschreibt. Die Prüfung leitet die Clientnamen aus den **Pack-Kennungen** ab, nicht aus einer
+gepflegten Liste: Ein künftiges Client Pack bringt seinen Namen damit selbst mit und wird ohne
+Änderung an der Prüfung erfasst.
+
+**62 Versionsfelder sind um eine PATCH-Stelle gehoben.** `08-skill-conventions.md` Abschnitt 7
+führt „Korrekturen und Formulierungen" als PATCH und verlangt bei jeder Versionsänderung die
+erneute Ausführung der Testfälle. Sechs Skills haben zusätzlich einen Eintrag in ihrem
+Änderungsverlauf; der Validator hat ihn eingefordert.
+
+## 3. Was dieser Antrag nicht ändert
+
+- **Keine Regel, keine Zusage, kein Mechanismus.** Die Sätze sagen dasselbe über einen anders
+  benannten Handelnden. Berechtigungsdatei, Hooks, Ladetrigger und Fähigkeitsmatrix sind
+  unberührt.
+- **Die Laufzeitschicht war schon frei davon** (seit 0.12.0, D-24). Was in eine Sitzung geladen
+  wird, ändert sich nicht – deshalb ist dies eine Konsistenz-, keine Verhaltensänderung.
+- **Die Pfadnennungen bleiben Sache von Prüfung 12.** `~/.devin/plans/` in
+  `05-working-model.md` und die clientspezifischen Inhalte der Zeile „Umsetzung beim KI-Client"
+  sind weiterhin client-gebunden; dieser Antrag benennt sie, löst sie nicht (siehe 5.).
+
+## 4. Vorlage zur Entscheidung
+
+Fünf Auflösungen mit Ermessensspielraum, jede einzeln. E1 und E2 sind bereits durch
+`<FRAMEWORK_OWNER>` entschieden und hier nur festgehalten.
+
+| Nr. | Frage | Auflösung | Preis |
+|---|---|---|---|
+| E1 | Welcher Begriff? | „der KI-Client" durchgängig – er steht im Glossar und war im Kern in Gebrauch | Sperriger als ein Eigenname; die Kurzform vermeidet den Akteur ganz, die Langform kann das nicht überall |
+| E2 | Nur `framework/core/` oder der ganze Kern? | Der ganze Kern nach der Definition des Glossars | Ein großes Release. Der halbe Weg hätte einen Kern hinterlassen, der seine eigene Zusage nachweislich nicht einlöst |
+| E3 | 62 Versionsfelder heben? | Ja – `08-skill-conventions.md` 7 führt Formulierungen als PATCH | Die Testpflicht je Artefakt wird erneuert. Sie ist seit 0.13.0 ohnehin offen und hängt an AP2; der Preis ist derselbe, den E2 aus `FW-VN-01` ausdrücklich akzeptiert hat |
+| E4 | AP2-Titel „Validierung der Devin-Funktionalitäten"? | Zu „Validierung der Clientfunktionalitäten" geändert | Der Titel war seit 0.14.0 falsch: AP2 ist für `claude-code` gefahren worden. Die Roadmap führte die Nennung unter „bewusst offen gelassen" – diese Begründung trägt nicht mehr |
+| E5 | Dateiname `decision-trees/02-may-devin-do-task.md`? | **Nicht** umbenannt | Der Name trägt die Akteursbezeichnung weiter, an vier Stellen verlinkt. Eine Umbenennung berührt Querverweise, `FW-KO-04` und die Assemblierung des Hauptdokuments – eigener Vorgang mit eigenem Nachweis |
+
+## 5. Nebenbefunde
+
+- **`<VERIFY AGAINST CURRENT DEVIN DOCUMENTATION>` ist an fünf Kernstellen weiter in Gebrauch**,
+  obwohl `docs/PLACEHOLDER_REGISTRY.md` die clientneutrale Form
+  `<VERIFY AGAINST CURRENT CLIENT DOCUMENTATION>` bereits führt. Ausgewiesen, nicht geschlossen:
+  Eine Markerumbenennung berührt Prüfung 7 und beide Client Packs.
+- **Prüfung 13 prüft die Versionsfelder der Kernartefakte nicht.** Der Kopfkommentar sagt
+  „jedes Versionsfeld gegen `MAJOR.MINOR.PATCH`" zu; tatsächlich deckt sie die Overlay-Version,
+  `VERSION` und die Steckbriefangabe ab. Ein Checklisten-Versionsfeld `0.1` oder `abc` läuft
+  glatt durch – belegt durch die Regressionsprobe R1. Derselbe Befundtyp wie `FW-KO-01`:
+  eine Prüfung, die mehr zusagt, als sie leistet. Ausgewiesen, nicht geschlossen.
+- **Ein Folgefehler im Code**, den Prüfung 14 aufgedeckt hat: `tests/scripts/validate-output.py`
+  suchte den Abschnittstitel `Devin-Ergebnisbericht`, der mit diesem Antrag zu `Ergebnisbericht`
+  wird. Ohne die Prüfung hätte das Skript ab sofort einen Abschnitt verlangt, den kein Skill
+  mehr erzeugt.
+
+## 6. Entscheidung
+
+| Feld | Inhalt |
+|---|---|
+| Entscheidung | **angenommen** |
+| Datum | 2026-09-10 |
+| Entscheidende Rolle | `<FRAMEWORK_OWNER>` |
+| Auflagen | **E1 bis E5 wie in Abschnitt 4 vorgelegt**: der Begriff „der KI-Client" durchgängig; Geltungsbereich ist der ganze Kern nach der Definition des Glossars; die Versionsfelder werden gehoben; der AP2-Titel wird neutralisiert; der Dateiname des Entscheidungsbaums bleibt. 🔴 **Abschnitt 6 sagte bis zu diesem Nachtrag „E1, E2 und E3 einzeln entscheiden", während Abschnitt 4 fünf Fragen vorlegt** – eine Aufzählung, die ihre eigene Tabelle unterzählt |
+| Umsetzung | **mit Release 0.18.0 bis 0.23.0** – Einzelheiten und Nachweise in `.koolie/core/CHANGELOG.md` |
+
+Abschnitt 6 ist am 2026-09-22 mit `CR-2026-124` (`AP11`) **nachgetragen**, nicht neu entschieden: Die Entscheidung selbst steht seit 2026-09-10 in **D-28**, die Umsetzung im `CHANGELOG.md` zu Release 0.18.0 bis 0.23.0. 🔴 **Der Releaseplan nannte für diesen Nachtrag zwei Anträge; gezählt am 2026-09-22 sind es sieben** – `CR-2026-020`, `-021`, `-023`, `-025`, `-026`, `-029` und `-030`.

package/.koolie/core/governance/change-requests/CR-2026-021-hook-interpreter.md

@@ -0,0 +1,113 @@
+# Änderungsantrag `CR-2026-021`
+
+| Feld | Inhalt |
+|---|---|
+| Titel | Der Schutz-Hook lief unter Windows nicht – eine Zusage, die dort nichts durchsetzte |
+| Antragstellende Rolle | `<FRAMEWORK_OWNER>` |
+| Datum | 2026-09-10 |
+| Betroffene Artefakte | `clientmap.py` (Semantikabbildung), `tests/scripts/validate-framework.py` (Prüfung 15 neu) |
+| Ebene laut Entscheidungsbaum 6 | Abbildungsschicht und Prüfung; keine Regeländerung |
+| Art | Behebung von `AP2-CC-13` (Schwere hoch) |
+| Dringlichkeit | erhöht – betrifft eine Sicherheitszusage der Fähigkeitsmatrix |
+
+## 1. Anlass und Problem
+
+Die Wirkungsnachweise zu AP2 (`tests/protocols/2026-09-10-AP2-claude-code-wirkungsnachweise.md`)
+haben `AP2-CC-13` aufgedeckt: **Beide Hooks des Frameworks laufen unter Windows nicht.**
+
+`clientmap.py` verdrahtete den Interpreter fest:
+
+```python
+return 'python3 "$' + variable + '/' + core_dir_name(man) + '/' + script + '"'
+```
+
+Auf einem Windows-System ohne installiertes `python3` ist dieser Name der
+**Microsoft-Store-Alias**. Er startet keinen Interpreter, gibt „Python wurde nicht gefunden" aus
+und endet mit **Exit-Code 49** – nachgestellt und im Sitzungsverlauf einer laufenden Sitzung
+sichtbar als `SessionStart:startup exit=49 outcome=error`.
+
+**Die Folgen betreffen zwei Zusagen:**
+
+- **`SessionStart`** – die Overlay-Statusmeldung erreicht die Sitzung nie. An ihr hängt die
+  Zusage „bei nicht aktivem Overlay ausschließlich Modus M1 Read-only Analysis".
+- **`PreToolUse`** – die Secret-Prüfung läuft nicht. **Zusage H2 der Fähigkeitsmatrix („Prüfung
+  kann blockieren") galt unter Windows nicht.** Ein fehlschlagender Hook blockiert nichts.
+
+Der Hook selbst war die ganze Zeit fehlerfrei. Mit dem funktionierenden Interpreter aufgerufen
+liefert er auf dieselbe Eingabe:
+
+```json
+{"decision": "block", "reason": "Framework-Regel: Werkzeugeingabe enthaelt ein Muster der
+ Kategorie 'Cloud-Zugangsschluessel (generisches Muster)' …"}
+```
+
+**Der Befund liegt in der gemeinsamen Semantikabbildung und betrifft daher beide Client Packs.**
+Windows ist keine Randumgebung des Frameworks – die Roadmap führt eigens den `MAX_PATH`-Hinweis
+für diese Plattform.
+
+Der Befundtyp ist bekannt: Eine Zusage wurde geprüft, indem ihre **Anwesenheit** festgestellt
+wurde – der Hook ist konfiguriert, das Skript existiert, der Validator ist grün –, nie ihre
+**Wirkung**. Genau daran ist der Store-Alias vorbeigekommen. Derselbe Typ wie `FW-KO-01`,
+`AP2-CC-09` und `AP2-CC-02`.
+
+## 2. Vorgeschlagene Änderung
+
+**Der Interpreter wird ermittelt, nicht angenommen.** `clientmap.python_interpreter()` prüft die
+Kandidaten `python3`, `python`, `py` in dieser Reihenfolge – und prüft sie an ihrer **Wirkung**:
+Der Kandidat muss eine Sonde ausgeben, nicht bloß im Pfad stehen. Der Store-Alias fällt damit
+durch, obwohl er auffindbar ist.
+
+Findet sich kein funktionierender Interpreter, **scheitert die Installation** mit einer Meldung,
+die sagt, welche Kandidaten geprüft wurden und was daran hängt. Das folgt D-26: Kann eine Zusage
+in der Zielumgebung nicht getragen werden, wird sie abgebildet oder die Installation scheitert –
+sie wird nicht stillschweigend zu einer Behauptung.
+
+**Prüfung 15 setzt es durch.** Sie liest die Hook-Kommandos aus der installierten Konfiguration –
+aus beiden Ablageformen, eigene Hook-Datei wie Berechtigungsdatei – und prüft den darin
+genannten Interpreter an derselben Sonde. Meldet sie einen Fehler, ist die Aussage konkret:
+Der Hook läuft hier nicht, und ein Schutz-Hook, der nicht läuft, blockiert nichts.
+
+Damit ist auch der plattformübergreifende Fall abgedeckt: Ein Repository, das unter Linux
+installiert und unter Windows ausgecheckt wird, trägt einen Interpreternamen, der dort nicht
+funktioniert. Vorher fiel das niemandem auf; jetzt meldet es der Validator, und
+`install.py --update` erzeugt den Aufruf passend zur Maschine.
+
+## 3. Was dieser Antrag nicht ändert
+
+- **Keine Regel, keine Zusage, kein Schwellenwert.** Die Hooks tun, was sie vorher tun sollten.
+- **Kein absoluter Pfad in einer versionierten Datei.** Geschrieben wird ein Interpretername
+  (`python`, `python3`, `py`), kein Maschinenpfad. `install.py --check` rendert auf derselben
+  Maschine denselben Wert und meldet deshalb keine Abweichung.
+- **Das fail-open-Verhalten des Schutz-Hooks bleibt.** Die Roadmap führt die Umstellung auf
+  fail-closed weiterhin als eigenen Punkt; dieser Antrag sorgt dafür, dass der Hook überhaupt
+  läuft.
+- **`AP2-CC-15` bleibt offen.** Die Lesesperre gilt für `Read`, nicht für Shell-Lesebefehle. Der
+  Befund wird durch diesen Antrag *entschärft* – der Schutz-Hook, der solche Fälle abfangen
+  würde, läuft jetzt –, aber nicht geschlossen.
+
+## 4. Vorlage zur Entscheidung
+
+| Nr. | Frage | Auflösung | Preis |
+|---|---|---|---|
+| E1 | Interpreter ermitteln oder im Manifest konfigurierbar machen? | Ermitteln. Der Interpretername ist eine Eigenschaft der **Maschine**, nicht des Clients; ein Manifestfeld hätte ihn an der falschen Stelle festgeschrieben | Die Ermittlung kostet bis zu drei Prozessstarts je Installationslauf |
+| E2 | Kandidatenreihenfolge `python3`, `python`, `py` | `python3` bleibt vorn – auf POSIX-Systemen ist es der verlässliche Name, und dort ist `python` häufig gar nicht oder auf Python 2 gesetzt | Auf Windows-Systemen **mit** echtem `python3` wird dieses genommen; das ist richtig, kann aber von der Erwartung „hier heißt es `python`" abweichen |
+| E3 | Prüfung 15 als Fehler oder Warnung? | **Fehler.** Ein Schutz-Hook, der nicht läuft, ist schlimmer als ein fehlender: Die Fähigkeitsmatrix weist ihn als `[TECHNISCH]` aus | Ein Repository, das auf einer Maschine ohne passenden Interpreter geprüft wird, ist rot statt gelb. Das ist beabsichtigt – die Zusage gilt dort tatsächlich nicht |
+
+## 5. Nebenbefund
+
+**Der Ort der Hook-Konfiguration stand dem Validator nicht zur Verfügung.** Prüfung 15 war im
+ersten Einbau wirkungslos, weil sie ein Manifestfeld `hooks_file` las, das es nicht gibt: Der
+Ort steht unter `runtime_placeholders["<HOOKS_FILE>"]`. Aufgefallen ist es allein durch die
+Sonden. Behoben; der Nebenbefund ist im Protokoll festgehalten.
+
+## 6. Entscheidung
+
+| Feld | Inhalt |
+|---|---|
+| Entscheidung | **angenommen** |
+| Datum | 2026-09-10 |
+| Entscheidende Rolle | `<FRAMEWORK_OWNER>` |
+| Auflagen | **E1 bis E3 wie in Abschnitt 4 vorgelegt**: Der Interpreter wird ermittelt und nicht im Manifest konfiguriert; die Kandidatenreihenfolge beginnt bei `python3`; Prüfung 15 meldet als **Fehler** – *ein Schutz-Hook, der nicht läuft, ist schlimmer als ein fehlender* |
+| Umsetzung | **mit Release 0.19.0** – Einzelheiten und Nachweise in `.koolie/core/CHANGELOG.md` |
+
+Abschnitt 6 ist am 2026-09-22 mit `CR-2026-124` (`AP11`) **nachgetragen**, nicht neu entschieden: Die Entscheidung selbst steht seit 2026-09-10 in **D-29**, die Umsetzung im `CHANGELOG.md` zu Release 0.19.0. 🔴 **Der Releaseplan nannte für diesen Nachtrag zwei Anträge; gezählt am 2026-09-22 sind es sieben** – `CR-2026-020`, `-021`, `-023`, `-025`, `-026`, `-029` und `-030`.

package/.koolie/core/governance/change-requests/CR-2026-022-artefaktversionen.md

@@ -0,0 +1,73 @@
+# Änderungsantrag `CR-2026-022`
+
+| Feld | Inhalt |
+|---|---|
+| Titel | Prüfung 13 sagte mehr zu, als sie prüfte – die Versionsfelder der Kernartefakte |
+| Antragstellende Rolle | `<FRAMEWORK_OWNER>` |
+| Datum | 2026-09-10 |
+| Betroffene Artefakte | `tests/scripts/validate-framework.py` (Prüfung 13 erweitert) |
+| Ebene laut Entscheidungsbaum 6 | Prüfung; keine Regeländerung |
+| Art | Behebung einer Blindstelle; Folgearbeit zu `CR-2026-020` |
+| Dringlichkeit | regulär |
+
+## 1. Anlass und Problem
+
+Der Kopfkommentar des Validators sagte zu Prüfung 13 seit 0.13.0 zu: „Versionsfelder in der
+Form `MAJOR.MINOR.PATCH`". Tatsächlich deckte sie drei Dinge ab – die Overlay-Version an ihren
+drei Ablageorten, `<CORE_DIR>/VERSION` und die Steckbriefangabe zur kompatiblen
+Framework-Version. **Die Versionsfelder der rund sechzig Kernartefakte prüfte sie nicht.**
+
+Belegt durch die Regressionsprobe R1 zu `CR-2026-020`: `| Version | 0.1 |` und
+`| Version | abc |` in `checklists/01-preflight.md` liefen beide mit **0 Fehlern** durch.
+
+**Der Zeitpunkt des Fundes ist der eigentliche Punkt.** Er fiel an, während `CR-2026-020`
+**62 Versionsfelder von Hand um eine PATCH-Stelle hob** – ohne dass irgendetwas geprüft hätte,
+ob das Ergebnis gültig ist. Ein Tippfehler in einem der 62 wäre unbemerkt geblieben, in genau
+dem Release, das die Versionspflege zum Thema hatte.
+
+Derselbe Befundtyp wie `FW-KO-01` (eine grüne Prüfung, die sechs von 22 Defekten durchließ) und
+`AP2-CC-13` (ein Hook, dessen Anwesenheit geprüft war, nie seine Wirkung): **eine Prüfung, die
+mehr zusagt, als sie leistet.** Das Muster ist inzwischen das häufigste im Fehlerbild dieses
+Frameworks.
+
+## 2. Vorgeschlagene Änderung
+
+Prüfung 13 erfasst zusätzlich das Versionsfeld **jedes Kernartefakts** und prüft es gegen
+`MAJOR.MINOR.PATCH`. Ausgenommen bleiben:
+
+- **Historische Dokumente** – dieselbe Abgrenzung, die Prüfung 14 seit D-28 verwendet
+  (`CHANGELOG.md` überall, `change-requests/`, `DECISION_LOG.md`, `tests/protocols/`).
+- **Client Packs** – sie führen eigene Versionsangaben mit eigener Bedeutung.
+- **Nicht ausgefüllte Vorlagen** (`<TBD: …>`) – eine Vorlage erklärt noch nichts.
+
+Erkannt wird die **Steckbriefzeile**, also genau zwei Spalten. Die Verankerung auf das
+Zeilenende ist notwendig: Der Änderungsverlauf eines Overlays beginnt mit der Kopfzeile
+`| Version | Datum | Änderung | … |`, und die ist kein Steckbrief. Ohne die Verankerung meldete
+die erste Fassung genau dort einen Fehlalarm.
+
+## 3. Was dieser Antrag nicht ändert
+
+- **Keine neue Entscheidung.** D-25 steht bereits: Ein Versionsfeld wird auf Stimmigkeit
+  geprüft, nicht auf Anwesenheit. Dieser Antrag löst die Zusage ein, er stellt sie nicht auf.
+- **Keine Prüfung, ob eine Version sich bewegt hat.** Das war der tragende Befund von
+  `FW-VN-01` – alle 13 Skills standen unverändert auf `0.1.0`, obwohl alle 13 geändert worden
+  waren. Diese Frage braucht die Versionsgeschichte, nicht die Datei; ein Validator, der `git`
+  voraussetzt, prüfte etwas anderes als die Struktur. Sie bleibt beim Release-Prozess
+  (`checklists/11-framework-release.md`).
+- **Kein Artefakt wird geändert.** Alle Versionsfelder des aktuellen Stands sind gültig.
+
+## 4. Vorlage zur Entscheidung
+
+| Nr. | Frage | Auflösung | Preis |
+|---|---|---|---|
+| E1 | Auch prüfen, ob die Version sich bei einer Änderung bewegt hat? | **Nein**, siehe 3. Der Validator prüft Struktur, nicht Historie | Der tragende Befund aus `FW-VN-01` bleibt außerhalb der Reichweite jeder Prüfung und hängt weiter am Release-Prozess |
+| E2 | Fehler oder Warnung? | **Fehler** – konsistent mit den übrigen Teilen von Prüfung 13, die Semantic Versioning ebenfalls als Fehler führen | Ein Artefakt mit unsauberem Versionsfeld blockiert das Release. Das ist die Aussage |
+
+## 5. Entscheidung
+
+| Feld | Inhalt |
+|---|---|
+| Entscheidung | `<TBD: angenommen / abgelehnt / mit Auflagen>` |
+| Datum | `<TBD>` |
+| Entscheidende Rolle | `<FRAMEWORK_OWNER>` |
+| Auflagen | `<TBD: E1 und E2 einzeln entscheiden>` |

package/.koolie/core/governance/change-requests/CR-2026-023-shell-lesesperre.md

@@ -0,0 +1,128 @@
+# Änderungsantrag `CR-2026-023`
+
+| Feld | Inhalt |
+|---|---|
+| Titel | Für Shell-Befehle bestand keine Lesesperre – die Abbildung erreichte den Matcher, nicht die Prüfung |
+| Antragstellende Rolle | `<FRAMEWORK_OWNER>` |
+| Datum | 2026-09-10 |
+| Betroffene Artefakte | `tests/scripts/hook-check-secrets.py`, `tests/scripts/validate-framework.py` (Prüfung 16 neu) |
+| Ebene laut Entscheidungsbaum 6 | Schutzmechanismus und Prüfung; keine Regeländerung |
+| Art | Behebung von `AP2-CC-16` (neu, Schwere hoch) und `AP2-CC-15` |
+| Dringlichkeit | erhöht – betrifft die Vertraulichkeit von Secrets |
+
+## 1. Anlass und Problem
+
+`AP2-CC-15` hielt fest: Die Lesesperre gilt für `Read`, nicht für Shell-Lesebefehle; die
+`deny`-Liste führt 21 Bash-Regeln und keine fürs Lesen. Aufgefangen würde das vom Schutz-Hook.
+Bei der Prüfung, ob der Hook das leistet, kam ein schwererer Befund zutage.
+
+### AP2-CC-16 – Die Abbildung erreichte den Matcher, nicht die Prüfung
+
+Das Manifest jedes Client Packs bildet die Verben der Kernquelle auf die Werkzeugnamen seines
+Clients ab:
+
+```json
+"hook_tools": {"exec": ["Bash"], "write": ["Edit", "Write", "NotebookEdit"]}
+```
+
+Diese Abbildung erzeugt den **Matcher** der Hook-Konfiguration – `"matcher":
+"Bash|Edit|Write|NotebookEdit"`. Der Hook wird also aufgerufen. Aber er verglich intern gegen
+die **generischen** Verbnamen:
+
+```python
+WRITE_TOOLS = ("edit", "write", "notebookedit")
+if tool_name in WRITE_TOOLS + ("exec",):
+```
+
+Der Client schickt `Bash`. Das Ergebnis, direkt nachgestellt:
+
+| Eingabe | Ergebnis |
+|---|---|
+| `{"tool_name": "Bash", "command": "cat .env"}` | **nicht blockiert**, Exit 0 |
+| `{"tool_name": "Write", "file_path": ".env"}` | blockiert, Exit 2 |
+
+**Der Verlust war clientspezifisch.** Bei `devin-desktop` heißt das Verb `exec`, dort griff die
+Prüfung. Bei `claude-code` nicht – seit acht Releases. Genau die Lage, gegen die D-26 gerichtet
+ist: eine Semantikabbildung, die eine Zusage verliert. Neu ist die Ebene: **Abgebildet wurde die
+erzeugte Konfiguration, nicht das Skript, das die Zusage durchsetzt.**
+
+### AP2-CC-15 – Die Pfadmuster treffen einen Pfad im Befehl nicht
+
+Selbst mit richtigem Werkzeugnamen hätte die Prüfung `cat .env` nicht getroffen. Die Muster
+verlangen vor dem Pfad einen Zeilenanfang oder ein Trennzeichen:
+
+| Zeichenkette | Treffer |
+|---|---|
+| `.env`, `./.env`, `cat /pfad/.env` | ja |
+| `cat .env`, `grep X .env` | **nein** |
+
+**Beide Ursachen zusammen heißen: Für Shell-Befehle bestand keine Lesesperre.**
+
+## 2. Vorgeschlagene Änderung
+
+**Die Werkzeugnamen kommen aus den Manifesten.** Der Hook liest `hook_tools` aus **allen**
+Client Packs – er liegt einmal im Kern und wird von allen geteilt; ein zusätzlich erkannter Name
+ist eine Verschärfung. Dasselbe Prinzip, mit dem Prüfung 14 seit D-28 die Clientnamen aus den
+Pack-Kennungen liest, statt sie zu pflegen. Fehlt jedes Manifest, gilt die bisherige Basisliste:
+Ein Hook, der wegen einer fehlenden Datei gar nichts mehr blockiert, wäre die schlechtere Lage.
+
+**Ein Shell-Befehl wird tokenisiert.** Für ausführende Werkzeuge wird die Eingabe an
+Shell-Trennzeichen zerlegt und jedes Token wie eine Pfadangabe geprüft. Keine neuen Muster – nur
+eine andere Zerlegung.
+
+**Die Pfadlisten werden nach Schutzziel getrennt.** Sie standen in einer, und das verwischte den
+Unterschied:
+
+| Liste | Schutzziel | Gilt für |
+|---|---|---|
+| `SECRET_PATH_PATTERNS` | **Vertraulichkeit** – darf auch nicht *gelesen* werden | alle Werkzeuge, auch ausführende |
+| `STRUCTURE_PATH_PATTERNS` | **Integrität** – darf nicht *geschrieben* werden | nur schreibende Werkzeuge |
+
+Ohne die Trennung hätte die Erweiterung ein `git diff leitwerk-core/framework/core/…` blockiert –
+eine Operation, die das Framework mit P4 („Befunde mit Fundstellen") ausdrücklich voraussetzt.
+
+**Prüfung 16 setzt es durch, und zwar an der Wirkung.** Der Validator ruft den Hook je
+abgebildetem Werkzeugnamen mit einer Sonde auf, die er blockieren muss. Ein Listenvergleich hätte
+genügt, um die beiden Listen gleichzuhalten – aber genau eine solche Prüfung ist an diesem Befund
+vorbeigekommen.
+
+## 3. Was dieser Antrag nicht ändert
+
+- **Keine Regel und keine Zusage.** Der Hook tut, was die Fähigkeitsmatrix seit jeher ausweist.
+- **Kein neues Muster.** Die Secret- und Strukturpfade sind unverändert; sie sind aufgeteilt,
+  nicht erweitert.
+- **Das fail-open-Verhalten bleibt.** Die Umstellung auf fail-closed ist weiterhin ein eigener
+  Punkt der Roadmap.
+- **Die `deny`-Liste bleibt unverändert.** Sie führt weiterhin keine Regel für Lesebefehle; der
+  Schutz kommt jetzt vom Hook, wo er hingehört.
+
+## 4. Grenze der Zusage
+
+**Die Sperre schützt gegen Versehen, nicht gegen Absicht.** Geprüft wird die Zeichenkette des
+Befehls. Wer den Pfad verschleiert – `cat .e''nv`, eine Variable, ein base64-Umweg, ein Skript,
+das die Datei öffnet – wird nicht erfasst. Das ist keine Lücke dieser Änderung, sondern die
+Grenze jeder textuellen Prüfung; sie ist hier ausgewiesen, damit die Fähigkeitsmatrix nicht mehr
+verspricht, als sie hält.
+
+Der Fall, gegen den die Sperre wirkt, ist der häufige: ein beiläufiges `cat .env`, ein
+`grep -r API .` über ein Verzeichnis mit Secret-Dateien.
+
+## 5. Vorlage zur Entscheidung
+
+| Nr. | Frage | Auflösung | Preis |
+|---|---|---|---|
+| E1 | Werkzeugnamen aus den Manifesten oder feste Liste? | **Aus den Manifesten**, aus allen Packs – wie D-28 es für die Clientnamen tut | Der Hook liest beim Start bis zu zwei kleine Dateien |
+| E2 | Schutzziele trennen? | **Ja.** Ohne die Trennung blockiert die Erweiterung lesende Kernzugriffe | Eine Lockerung gegenüber dem bisherigen `exec`-Verhalten bei `devin-desktop`, wo ein `git diff` auf `framework/core/` blockiert war. Begründet: Lesen war dort nie das Schutzziel |
+| E3 | Prüfung 16 durch Aufruf oder Listenvergleich? | **Durch Aufruf.** Ein Listenvergleich belegt Übereinstimmung, nicht Wirkung | Zwei bis acht Prozessstarts je Validatorlauf |
+
+## 6. Entscheidung
+
+| Feld | Inhalt |
+|---|---|
+| Entscheidung | **angenommen** |
+| Datum | 2026-09-10 |
+| Entscheidende Rolle | `<FRAMEWORK_OWNER>` |
+| Auflagen | **E1 bis E3 wie in Abschnitt 5 vorgelegt**: Die Werkzeugnamen stammen aus den Manifesten aller Packs; die Schutzziele werden getrennt; Prüfung 16 belegt die Wirkung durch **Aufruf** und nicht durch Listenvergleich. ⚠️ **Der Geltungsbereich war bis Release 0.25.0 zu eng beschrieben** und ist mit `CR-2026-037` nachgezogen – der Nachtrag steht in D-30 selbst |
+| Umsetzung | **mit Release 0.21.0** – Einzelheiten und Nachweise in `.koolie/core/CHANGELOG.md` |
+
+Abschnitt 6 ist am 2026-09-22 mit `CR-2026-124` (`AP11`) **nachgetragen**, nicht neu entschieden: Die Entscheidung selbst steht seit 2026-09-10 in **D-30**, die Umsetzung im `CHANGELOG.md` zu Release 0.21.0. 🔴 **Der Releaseplan nannte für diesen Nachtrag zwei Anträge; gezählt am 2026-09-22 sind es sieben** – `CR-2026-020`, `-021`, `-023`, `-025`, `-026`, `-029` und `-030`.