@renoxar/koolie 1.25.0

package/.koolie/core/build/assemble.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""Assembliert das Hauptdokument aus <CORE>/build/doc/*.md und Repository-Artefakten.
+
+Direktiven in den Kapiteldateien:
+  {{EMBED:relpfad}}            -> Datei als Markdown-Codeblock (4 Backticks, Sprache markdown)
+  {{EMBED:relpfad:lang}}       -> wie oben mit Sprachangabe (json, yaml, python, text);
+                                  lang "permissions_format" = Ausgabeform der Berechtigungsdatei
+                                  aus dem Manifest des Packs (json oder toml, K-127, D-396)
+  {{EMBED-RAW:relpfad:shift}}  -> Datei als gerenderten Inhalt einfuegen, Ueberschriften um <shift> Ebenen
+                                  verschoben; YAML-Frontmatter wird als Hinweisblock dargestellt
+  {{ZAHL:muster[,muster...]}}  -> (im Fliesstext) Zahl der versionierten Kerndateien, die eines der
+                                  Muster treffen; "*" = alle, "." = direkt im Kern, "x/" = unter x/,
+                                  sonst fnmatch relativ zum Kern; "installiert" = Dateien der
+                                  Referenzinstallation (D-377)
+  {{VERSION}}, {{CLIENT}}      -> Inhalt von VERSION, Client Pack dieses Baus
+
+Zwei Quellen fuer eingebettete Dateien:
+
+  1. Das Repository. Fuer alles, was dort versioniert liegt - Core-Module, Checklisten,
+     Prompts, Vorlagen. Der Pfad ist relativ zum Wurzelverzeichnis.
+
+  2. Eine Referenzinstallation. Fuer die Laufzeitschicht, die es im Repository gar nicht
+     gibt: Sie entsteht erst bei der Installation und sieht je Client Pack anders aus.
+     Enthaelt ein Pfad einen Laufzeit-Platzhalter (<RUNTIME_DIR>, <SKILLS_DIR>,
+     <PERMISSIONS_FILE>, ...), wird er gegen das gewaehlte Client Pack aufgeloest und aus
+     einer frisch erzeugten Installation in einem temporaeren Verzeichnis gelesen.
+
+Der zweite Weg ist der Grund, weshalb das Dokument aus einem frischen Auscheckstand baut.
+Vorher zeigten 28 Einbettungen auf .devin/ und AGENTS.md im Arbeitsverzeichnis - Pfade,
+die in der .gitignore stehen. Der Bau gelang nur, wenn zufaellig eine Installation daneben
+lag, und er zeigte deren Client, ohne das zu sagen.
+
+Aufruf:
+    python3 build/assemble.py                     # Referenzclient: devin-desktop
+    python3 build/assemble.py --client claude-code
+
+Ausgabe: <CORE>/build/out/hauptdokument.md
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+# CORE = <CORE_DIR>/ (dieses Skript liegt in CORE/build/). Zwei dirname-Aufrufe
+# sind hier richtig und bleiben es: Sie zaehlen den Weg vom Skript zum Kern, und
+# der ist unabhaengig davon, wie tief der Kern unter der Projektwurzel liegt.
+CORE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DOC = os.path.join(CORE, "build", "doc")
+OUT = os.path.join(CORE, "build", "out")
+EMBED_RE = re.compile(r"^\{\{(EMBED|EMBED-RAW):([^:}]+)(?::([^}]+))?\}\}\s*$", re.M)
+LOKAL_RE = re.compile(r"^\{\{LOKALE-ERGAENZUNG\}\}[ \t]*$", re.M)
+ZAHL_RE = re.compile(r"\{\{(ZAHL:([^}]+)|VERSION|CLIENT)\}\}")
+
+sys.path.insert(0, CORE)
+import clientmap  # noqa: E402  (liegt im Kernverzeichnis)
+
+# REPO = Wurzelverzeichnis des Projekts; EMBED-Pfade sind dazu relativ, weil die
+# Wurzel-Anweisungsdatei, die Laufzeitschicht und das Overlay dort liegen.
+#
+# 0.89.0: Bis dahin stand hier ein DRITTER dirname-Aufruf auf CORE - ein im
+# Quelltext gezaehlter Weg zur Projektwurzel und damit die Bauform aus D-299 an
+# einer siebten Stelle. Sie hat die Umbenennung nicht ueberlebt: Seit der Kern
+# unter `.koolie/core` liegt, lieferte sie `.koolie/` statt der Wurzel, und JEDE
+# Einbettung schlug fehl. Das Hauptdokument war damit seit 0.88.0 nicht baubar,
+# ohne dass es eine Pruefung gemeldet haette - Pruefung 76 haelt vier Werkzeuge
+# gegeneinander, und dieses ist keines davon. Der Nachfolger ist dieselbe
+# benannte Ableitung, die die anderen vier verwenden.
+REPO = clientmap.projektwurzel(CORE)
+
+REFERENZ_CLIENT = "devin-desktop"
+
+
+def lade_manifest(client: str) -> dict:
+    pfad = os.path.join(CORE, "clients", client, "manifest.json")
+    if not os.path.exists(pfad):
+        print(f"FEHLER: unbekanntes Client Pack: {client}", file=sys.stderr)
+        sys.exit(1)
+    with open(pfad, encoding="utf-8") as fh:
+        man = json.load(fh)
+    # 0.88.0: os.path.basename(CORE) lieferte hier "core" statt ".koolie/core" -
+    # der Kern ist seit diesem Release zwei Segmente tief (D-299).
+    man.setdefault("runtime_placeholders", {})["<CORE_DIR>"] = clientmap.CORE_REL
+    return man
+
+
+def referenzinstallation(client: str) -> str:
+    """Legt eine frische Installation dieses Client Packs in einem temporaeren Verzeichnis an.
+
+    Die Laufzeitschicht ist kein Repository-Inhalt: Sie entsteht bei der Installation, und
+    ihre Form haengt vom Client ab. Das Dokument soll sie in der Fassung zeigen, die ein
+    Projekt tatsaechlich vorfindet - also wird sie erzeugt, statt sie aus dem
+    Arbeitsverzeichnis zu borgen.
+    """
+    ziel = tempfile.mkdtemp(prefix="koolie-referenz-")
+    ergebnis = subprocess.run(
+        [sys.executable, os.path.join(CORE, "install.py"), "--root", ziel, "--client", client],
+        capture_output=True, text=True)
+    if ergebnis.returncode != 0:
+        shutil.rmtree(ziel, ignore_errors=True)
+        print(f"FEHLER: Referenzinstallation ({client}) fehlgeschlagen:", file=sys.stderr)
+        print(ergebnis.stderr, file=sys.stderr)
+        sys.exit(1)
+    return ziel
+
+
+def shift_headings(text: str, shift: int) -> str:
+    def repl(m):
+        return "#" * min(6, len(m.group(1)) + shift) + m.group(2)
+    out_lines = []
+    in_fence = False
+    for line in text.split("\n"):
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            out_lines.append(line)
+            continue
+        if not in_fence:
+            line = re.sub(r"^(#{1,6})(\s)", repl, line)
+        out_lines.append(line)
+    return "\n".join(out_lines)
+
+
+def strip_frontmatter(text: str):
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            fm = parts[1].strip()
+            return fm, parts[2].lstrip("\n")
+    return None, text
+
+
+def quelle(rel: str, man: dict, installation: str):
+    """Aufgeloester Pfad, Basisverzeichnis und Herkunft einer Einbettung.
+
+    Ein Pfad mit Laufzeit-Platzhalter meint die Laufzeitschicht und wird aus der
+    Referenzinstallation gelesen; jeder andere Pfad meint das Repository.
+    """
+    aufgeloest = clientmap.resolve_placeholders(rel, man)
+    if aufgeloest != rel:
+        # Eine Regeldatei der Ablage traegt die Endung des Packs - bei cursor .mdc
+        # (CR-2026-155, D-440); die Kapitelquelle nennt sie mit .md.
+        if rel.startswith("<RULES_DIR>/"):
+            kopf, _, name = aufgeloest.rpartition("/")
+            aufgeloest = kopf + "/" + clientmap.regeldatei(man, name)
+        return aufgeloest, installation, True
+    return rel, REPO, False
+
+
+def process(text: str, man: dict, installation: str) -> str:
+    # Zwei Platzhalter koennen auf dieselbe Datei zeigen - bei einem Client ohne eigene
+    # Hook-Datei etwa <HOOKS_FILE> und <PERMISSIONS_FILE>. Sie zweimal im selben Kapitel
+    # abzudrucken waere in jedem Fall falsch: Der Leser sucht den Unterschied, den es
+    # nicht gibt. Die zweite Stelle bekommt deshalb einen Verweis.
+    gesehen: dict[str, str] = {}
+
+    def repl(m):
+        kind, roh, arg = m.group(1), m.group(2).strip(), (m.group(3) or "").strip()
+        rel, basis, aus_installation = quelle(roh, man, installation)
+        if rel in gesehen and gesehen[rel] != roh:
+            return (f"> Diese Angabe steht bei diesem Client Pack in derselben Datei wie "
+                    f"`{gesehen[rel]}` – siehe `{rel}` weiter oben.\n")
+        gesehen[rel] = roh
+        path = os.path.join(basis, rel)
+        if not os.path.exists(path):
+            woher = f"Referenzinstallation {man['client']}" if aus_installation else "Repository"
+            print(f"FEHLER: eingebettete Datei fehlt ({woher}): {rel}", file=sys.stderr)
+            sys.exit(1)
+        content = open(path, encoding="utf-8").read().rstrip("\n")
+        # Woher eine Laufzeitdatei stammt, gehoert an die Datei und nicht in eine Fussnote:
+        # Bei einem anderen Client Pack sieht sie anders aus.
+        herkunft = (f" · aus einer Referenzinstallation des Client Packs `{man['client']}`"
+                    if aus_installation else "")
+        if kind == "EMBED":
+            lang = arg or "markdown"
+            # Die Berechtigungsdatei ist nicht bei jedem Pack JSON; bei openai-codex bettete
+            # der Bau bis 1.9.3 eine TOML-Datei als JSON ein (K-127, D-396).
+            if lang == "permissions_format":
+                lang = clientmap.permissions_format(man)
+                # Das Agentenprofil von kiro ist JSON (D-414).
+                # Die Berechtigungsdatei von cursor ebenso (D-440).
+                if lang in ("kiro-agent", "cursor-json"):
+                    lang = "json"
+            if "````" in content:
+                print(f"FEHLER: {rel} enthaelt 4 Backticks", file=sys.stderr)
+                sys.exit(1)
+            return f"**Datei:** `{rel}`{herkunft}\n\n````{lang}\n{content}\n````\n"
+        shift = int(arg or "1")
+        fm, body = strip_frontmatter(content)
+        prefix = f"> **Datei:** `{rel}`{herkunft}"
+        if fm:
+            fm_compact = "; ".join(l.strip() for l in fm.splitlines() if l.strip())
+            prefix += f" · **Frontmatter (Laufzeit):** `{fm_compact}`"
+        return prefix + "\n\n" + shift_headings(body, shift) + "\n"
+    return EMBED_RE.sub(repl, LOKAL_RE.sub(lambda m: lokale_ergaenzung(man), text))
+
+
+def kerndateien() -> list:
+    """Die versionierten Dateien des Kerns, relativ zum Kern, mit '/'.
+
+    Aus git, wenn der Kern in einem Arbeitsbaum liegt; sonst aus dem Verzeichnis ohne
+    Bytecode und ohne build/out/ - dieselbe Unterscheidung wie install.py --target.
+    """
+    try:
+        roh = subprocess.run(["git", "-C", CORE, "ls-files", "-z", "."], capture_output=True,
+                             check=True).stdout.decode("utf-8")
+        dateien = [p for p in roh.split("\0") if p]
+        if dateien:
+            return sorted(dateien)
+    except (OSError, subprocess.CalledProcessError):
+        pass
+    dateien = []
+    for dirpath, dirnames, filenames in os.walk(CORE):
+        dirnames[:] = [d for d in dirnames if d != "__pycache__"]
+        rel = os.path.relpath(dirpath, CORE).replace(os.sep, "/")
+        if rel == "build/out" or rel.startswith("build/out/"):
+            dirnames[:] = []
+            continue
+        for fn in filenames:
+            dateien.append(fn if rel == "." else f"{rel}/{fn}")
+    return sorted(dateien)
+
+
+def zahlen(text: str, dateien: list, man: dict, installation: str) -> str:
+    """Setzt {{ZAHL:...}}, {{VERSION}} und {{CLIENT}} ein (D-377).
+
+    🔴 WARUM DAS HIER STEHT UND NICHT IN EINER PRUEFUNG: Kapitel 31 nannte bis 1.8.0 "502
+    versionierte Dateien" und "123 Aenderungsantraege", gezaehlt zu 0.89.0 - acht Releases
+    alt, bei 559 Dateien. Pruefung 78 haelt EINEN Satz des Dokuments gegen den Bestand und
+    zahlt dafuer, dass die Zahl erst am Ende des Releases feststeht (D-315). Eine Zahl, die
+    der Bau einsetzt, muss niemand setzen - und was niemand setzen muss, veraltet nicht.
+    Ein Muster, das NICHTS trifft, bricht den Bau ab: Es ist fast sicher ein Tippfehler,
+    und eine stille Null im Dokument waere eine falsche Zahl mit gutem Gewissen.
+    """
+    import fnmatch
+
+    def zaehle(muster: str) -> int:
+        if muster == "installiert":
+            return sum(len(f) for _d, _s, f in os.walk(installation))
+        treffer = set()
+        for m in (x.strip() for x in muster.split(",")):
+            if m == "*":
+                t = set(dateien)
+            elif m == ".":
+                t = {d for d in dateien if "/" not in d}
+            elif m.endswith("/"):
+                t = {d for d in dateien if d.startswith(m)}
+            else:
+                t = {d for d in dateien if fnmatch.fnmatchcase(d, m)}
+            if not t:
+                print(f"FEHLER: {{{{ZAHL:{muster}}}}} - '{m}' trifft keine Kerndatei",
+                      file=sys.stderr)
+                sys.exit(1)
+            treffer |= t
+        return len(treffer)
+
+    def repl(m):
+        if m.group(1) == "VERSION":
+            return open(os.path.join(CORE, "VERSION"), encoding="utf-8").read().strip()
+        if m.group(1) == "CLIENT":
+            return man["client"]
+        return str(zaehle(m.group(2)))
+    return ZAHL_RE.sub(repl, text)
+
+
+def lokale_ergaenzung(man: dict) -> str:
+    """Die persoenliche Ergaenzungsdatei - oder die Erklaerung, weshalb es sie nicht gibt.
+
+    🔴 BIS 1.4.1 WAR DAS HAUPTDOKUMENT FUER `openai-codex` NICHT BAUBAR (CR-2026-135).
+    Kapitel 16 bettete `<ROOT_INSTRUCTION_LOCAL>.example` fuer jedes Pack ein; dieses Pack
+    liefert die Vorlage bewusst NICHT aus, weil die Datei bei ihm die Wurzel-Anweisung
+    VERDRAENGT statt sie zu ergaenzen (D-341). Der Bau brach ab - und `1.4.0` hat Schritt
+    3 aus RELEASE_PROCESS.md 4.1 fuer das neue Pack nie gefahren.
+
+    Die Weiche ist das Manifestfeld `root_instruction_override`, nicht das Fehlen der
+    Datei: Fehlt sie bei einem Pack OHNE dieses Feld, bricht der Bau weiter ab. Eine
+    Einbettung, die bei jedem Fehlen still eine Erklaerung einsetzte, waere die Ausnahme,
+    die alles ausnimmt.
+    """
+    if man.get("root_instruction_local_absent"):
+        # Seit 1.13.0 (D-414): Ein Client ohne nutzerlokale Wurzel-Anweisung (kiro). Die
+        # Weiche ist wieder ein Manifestfeld und nicht das Fehlen der Datei.
+        return (f"🔴 **Eine persönliche Ergänzungsdatei gibt es bei diesem Client Pack nicht** "
+                f"(`{man['client']}`): Der Hersteller dokumentiert keine nutzerlokale "
+                f"Wurzel-Anweisung, und das Pack liefert keine Vorlage aus. Der Name "
+                f"`{man['runtime_placeholders']['<ROOT_INSTRUCTION_LOCAL>']}` steht nur im "
+                f"`deny`-Korb, weil die Kernquelle ein Schreibverbot auf ihn führt.")
+    if not man.get("root_instruction_override"):
+        return ("Ergänzend gehört zur Vorlage die persönliche, nicht versionierte "
+                "Ergänzungsdatei – zulässig nur zum Einschränken und für "
+                "Arbeitsvorlieben, nie zum Erweitern von Freigaben:\n\n"
+                "{{EMBED:<ROOT_INSTRUCTION_LOCAL>.example}}")
+    lokal = man["runtime_placeholders"]["<ROOT_INSTRUCTION_LOCAL>"]
+    return (f"🔴 **Eine persönliche Ergänzungsdatei gibt es bei diesem Client Pack nicht** "
+            f"(`{man['client']}`). Die Datei an ihrer Stelle, `{lokal}`, ergänzt "
+            f"`{man['root_instruction_file']}` nicht, sondern **verdrängt** sie vollständig: "
+            f"Liegt sie im Projekt, steht die Wurzel-Anweisung des Frameworks in keiner "
+            f"Nachricht der Sitzung (D-341, gemessen mit Gegenprobe). Das Pack liefert "
+            f"deshalb keine Vorlage aus, der `deny`-Korb stellt die Datei schreibgeschützt, "
+            f"der Schutz-Hook führt sie in seinen Mustern, und Prüfung 88 meldet sie, wenn "
+            f"sie trotzdem im Projektbaum liegt.")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Assembliert das Hauptdokument.")
+    ap.add_argument("--client", default=REFERENZ_CLIENT,
+                    help=f"Client Pack der Referenzinstallation (Standard: {REFERENZ_CLIENT})")
+    args = ap.parse_args()
+
+    man = lade_manifest(args.client)
+    # Ein abgebrochener Bau darf kein Erzeugnis des VORIGEN Baus stehen lassen: Sonst
+    # setzt build-docx.py daraus eine Word-Fassung zusammen und benennt sie nach dem
+    # vorigen Pack - gemessen am 2026-09-24, als der Bau fuer openai-codex abbrach und
+    # danach die Fassung fuer devin-desktop ein zweites Mal entstand (CR-2026-135).
+    for alt in ("hauptdokument.md", "referenzclient.txt"):
+        if os.path.exists(os.path.join(OUT, alt)):
+            os.remove(os.path.join(OUT, alt))
+    installation = referenzinstallation(args.client)
+    try:
+        os.makedirs(OUT, exist_ok=True)
+        parts = []
+        dateien = kerndateien()
+        for fn in sorted(os.listdir(DOC)):
+            if fn.endswith(".md"):
+                roh = open(os.path.join(DOC, fn), encoding="utf-8").read().rstrip("\n")
+                # Die Zahlen VOR den Einbettungen: Eine eingebettete Datei, die die
+                # Direktive nennt, wird zitiert und nicht ausgerechnet.
+                parts.append(process(zahlen(roh, dateien, man, installation), man, installation))
+        result = "\n\n".join(parts) + "\n"
+        out_path = os.path.join(OUT, "hauptdokument.md")
+        with open(out_path, "w", encoding="utf-8") as fh:
+            fh.write(result)
+        # 🔴 WELCHES PACK DIESER BAU ABBILDET, MUSS NEBEN DEM ERZEUGNIS STEHEN (D-314).
+        # Beide Packs schreiben nach derselben Datei, und die beiden Fassungen sind NICHT
+        # gleich - am 2026-09-23 gemessen: 1.956.225 gegen 1.959.896 Zeichen. Ohne diese
+        # Marke traegt die Word-Fassung beider Baeue denselben Dateinamen, und welche
+        # Lieferung man in der Hand haelt, steht nirgends. Der Dateiname selbst bleibt,
+        # wie er ist: Chronik und Entscheidungen nennen ihn, und ein Erzeugnis umzubenennen
+        # macht aus richtigen Verweisen tote.
+        with open(os.path.join(OUT, "referenzclient.txt"), "w", encoding="utf-8") as fh:
+            fh.write(args.client + "\n")
+    finally:
+        shutil.rmtree(installation, ignore_errors=True)
+    print(f"Referenzclient: {args.client}")
+    print(f"geschrieben: {out_path} ({len(result)} Zeichen, {result.count(chr(10))} Zeilen)")
+
+
+if __name__ == "__main__":
+    main()

package/.koolie/core/build/build-docx.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Erzeugt die Word-Fassung des Hauptdokuments.
+
+Schritte:
+1. Mermaid-Bloecke aus build/out/hauptdokument.md nach PNG rendern (mmdc) und im
+   Markdown durch Bildverweise ersetzen (die normative Textbeschreibung bleibt erhalten).
+2. pandoc-Konvertierung nach DOCX (markdown ohne raw_html, Inhaltsverzeichnis, deutsche
+   Metadaten).
+
+🔴 DIE METADATEN WERDEN AUS DEM DOKUMENT GELESEN, NICHT HIER GESCHRIEBEN (D-314).
+Bis 0.89.0 standen Titel, Untertitel und Datum als feste Zeichenketten in diesem Skript:
+"Framework fuer den professionellen Einsatz von <Clientname>", "Version 0.1.0",
+"2026-09-02". Das Dokument selbst heisst seit 0.88.0 anders, steht seit 0.89.0 auf
+0.89.0 - und dieses Werkzeug haette den ueberholten Titel samt CLIENTNAMEN in die
+Dokumenteigenschaften der Lieferung gestempelt. Pruefung 77 haelt die Versionszeile des
+Dokuments, erreicht dieses Werkzeug aber nicht; Pruefung 14 erreichte es bis 0.89.0
+ebenfalls nicht (D-313). ➡️ Eine Angabe, die zweimal dasteht, veraltet einmal.
+
+🔴 BROWSER UND ARBEITSVERZEICHNIS SIND NICHT MEHR FEST VERDRAHTET (D-314). Bis 0.89.0
+schrieb dieses Skript seine Puppeteer-Konfiguration nach "/tmp/..." und nannte darin
+einen Chromium-Pfad einer Container-Umgebung ("/opt/pw-browsers/..."). Auf einem
+Windows-Arbeitsplatz existiert beides nicht - das Werkzeug war dort nicht lauffaehig,
+und das ist zwei Releases lang niemandem aufgefallen, weil es nie gelaufen ist.
+"""
+import glob
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+OUT = os.path.join(ROOT, "build", "out")
+IMG = os.path.join(OUT, "img")
+SRC = os.path.join(OUT, "hauptdokument.md")
+MD_DOCX = os.path.join(OUT, "hauptdokument.docx.md")
+PPTR = os.path.join(OUT, "puppeteer-config.json")
+
+# Browsersuche und Puppeteer-Konfiguration teilt dieses Werkzeug mit dem Validator
+# (`--mermaid`); bis 1.9.3 standen sie nur hier, und der Validator scheiterte ohne sie an
+# jedem Diagramm (K-145, D-398).
+sys.path.insert(0, os.path.join(ROOT, "tests", "scripts"))
+import mermaid_renderer  # noqa: E402
+
+# --- Vorbedingungen, benannt statt vermutet ---------------------------------------
+#
+# Ein Werkzeug, das ohne seine Vorbedingung startet, scheitert irgendwo in der Mitte und
+# laesst ein halbes Erzeugnis liegen. Die Pruefung steht deshalb VOR dem ersten Schritt
+# und nennt beide fehlenden Namen auf einmal - nicht den ersten und dann den zweiten.
+fehlend = [name for name in ("mmdc", "pandoc") if shutil.which(name) is None]
+if not os.path.exists(SRC):
+    sys.exit(f"FEHLER: {SRC} fehlt. Zuerst build/assemble.py fahren - die Word-Fassung "
+             f"entsteht aus der Markdown-Fassung und nicht aus den Kapitelquellen.")
+if fehlend:
+    sys.exit("FEHLER: auf diesem Arbeitsplatz nicht gefunden: " + ", ".join(fehlend)
+             + ".\n       pandoc: ueber den Paketverwalter des Arbeitsplatzes"
+             + "\n       mmdc:   npm install -g @mermaid-js/mermaid-cli")
+
+
+def kopfangaben(text: str) -> dict:
+    """Titel, Untertitel, Dokumentversion und Stand - aus dem Dokument selbst.
+
+    Der Kopf ist build/doc/00-kopf.md, und Pruefung 77 haelt seine Versionszeile gegen
+    <CORE_DIR>/VERSION. Wer hier liest, erbt diese Pruefung; wer die Werte abschreibt,
+    erbt sie nicht.
+    """
+    angaben = {}
+    m = re.search(r"^#\s+(.+?)\s*$", text, re.M)
+    if m:
+        angaben["title"] = m.group(1)
+    m = re.search(r"^\*\*(.+?)\*\*\s*$", text, re.M)
+    if m:
+        angaben["subtitle"] = m.group(1)
+    m = re.search(r"^\|\s*Dokumentversion\s*\|\s*([0-9]+\.[0-9]+\.[0-9]+)", text, re.M)
+    if m:
+        angaben["version"] = m.group(1)
+    m = re.search(r"^\|\s*Stand\s*\|\s*([0-9]{4}-[0-9]{2}-[0-9]{2})", text, re.M)
+    if m:
+        angaben["date"] = m.group(1)
+    return angaben
+
+
+text = open(SRC, encoding="utf-8").read()
+kopf = kopfangaben(text)
+fehlende_angaben = [k for k in ("title", "subtitle", "version", "date") if k not in kopf]
+if fehlende_angaben:
+    sys.exit("FEHLER: im Dokumentkopf nicht gefunden: " + ", ".join(fehlende_angaben)
+             + ".\n       Die Metadaten der Word-Fassung stammen aus dem Dokument. "
+               "Fehlt eine Angabe,\n       traegt die Lieferung lieber keine als eine "
+               "erfundene (D-314).")
+
+# Alte Bilder wegraeumen: Ein Lauf mit weniger Diagrammen als der vorige liesse sonst
+# die ueberzaehligen liegen, und der naechste Lauf faende sie vor.
+os.makedirs(IMG, exist_ok=True)
+for alt in glob.glob(os.path.join(IMG, "diagramm-*.png")) + \
+        glob.glob(os.path.join(IMG, "diagramm-*.mmd")):
+    os.remove(alt)
+
+browser = mermaid_renderer.browserpfad()
+if browser is None:
+    sys.exit("FEHLER: kein Chromium-artiger Browser gefunden. Der Mermaid-Renderer "
+             "braucht einen.\n       Pfad ueber PUPPETEER_EXECUTABLE_PATH angeben.")
+mermaid_renderer.puppeteer_konfiguration(PPTR, browser)
+
+blocks = re.findall(r"```mermaid\n(.*?)```", text, re.S)
+print(f"Mermaid-Bloecke: {len(blocks)}")
+
+counter = 0
+
+
+def render(match):
+    global counter
+    counter += 1
+    src_path = os.path.join(IMG, f"diagramm-{counter:02d}.mmd")
+    png_path = os.path.join(IMG, f"diagramm-{counter:02d}.png")
+    with open(src_path, "w", encoding="utf-8") as fh:
+        fh.write(match.group(1))
+    r = subprocess.run([shutil.which("mmdc"), "-i", src_path, "-o", png_path, "-q",
+                        "-p", PPTR, "-b", "white", "-s", "2"],
+                       capture_output=True, text=True, encoding="utf-8",
+                       errors="replace", shell=os.name == "nt")
+    if r.returncode != 0:
+        print(f"FEHLER Diagramm {counter}: {(r.stderr or '')[:300]}", file=sys.stderr)
+        sys.exit(1)
+    # 🔴 RELATIV UND MIT SCHRAEGSTRICH, und beides ist gemessen (D-314). Bis 0.89.0 stand
+    # hier der ABSOLUTE Pfad. Unter Windows enthaelt der Rueckstriche, und pandoc liest
+    # einen Rueckstrich in einem Markdown-Link als MASKIERUNG: aus "...\koolie\.koolie\..."
+    # wurde "...koolie.koolie\..." - eine Datei, die es nicht gibt. Am 2026-09-23 hat der
+    # erste Lauf dieses Werkzeugs auf einem Windows-Arbeitsplatz ACHT VON ACHT Diagrammen
+    # verloren, mit Exit 0 und einer geschriebenen Datei. Der Pfad ist jetzt relativ zu
+    # --resource-path, und unten bricht der Lauf ab, wenn pandoc eine Ressource meldet.
+    rel_png = os.path.relpath(png_path, OUT).replace(os.sep, "/")
+    return (f"![Diagramm {counter} (Mermaid-Quelltext im Referenz-Repository)]"
+            f"({rel_png})")
+
+
+text = re.sub(r"```mermaid\n(.*?)```", render, text, flags=re.S)
+with open(MD_DOCX, "w", encoding="utf-8") as fh:
+    fh.write(text)
+print(f"vorverarbeitet: {MD_DOCX}")
+
+# Das Pack gehoert in den Namen der Lieferung, nicht nur in die Meldung des Baus: Beide
+# Packs schreiben nach derselben Markdown-Datei, und ohne diese Marke truege die
+# Word-Fassung beider Baeue denselben Namen (D-314). Fehlt die Marke, traegt der Name
+# sie nicht - eine erfundene waere schlimmer als keine.
+_marke = os.path.join(OUT, "referenzclient.txt")
+_client = (open(_marke, encoding="utf-8").read().strip()
+           if os.path.exists(_marke) else "")
+DOCX = os.path.join(OUT, f"Koolie_v{kopf['version']}"
+                         + (f"_{_client}" if _client else "") + ".docx")
+cmd = ["pandoc", MD_DOCX,
+       "-f", "markdown-raw_html+pipe_tables",
+       "-t", "docx",
+       "--toc", "--toc-depth=2",
+       "--metadata", "toc-title=Inhaltsverzeichnis",
+       "--metadata", "lang=de-DE",
+       "--metadata", f"title={kopf['title']}",
+       "--metadata", f"subtitle={kopf['subtitle']} - Version {kopf['version']}",
+       "--metadata", f"date={kopf['date']}",
+       "--reference-doc", os.path.join(ROOT, "build", "ref-a4.docx"),
+       "--resource-path", OUT,
+       "-o", DOCX]
+r = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8",
+                   errors="replace")
+if r.returncode != 0:
+    print("pandoc-Fehler:", (r.stderr or "")[:2000], file=sys.stderr)
+    sys.exit(1)
+
+# 🔴 EINE NICHT GEHOLTE RESSOURCE IST EIN FEHLER, KEINE WARNUNG (D-314). pandoc ersetzt
+# ein Bild, das es nicht findet, durch seine Beschreibung und endet mit Exit 0. Am
+# 2026-09-23 sind auf diese Weise ACHT VON ACHT Diagrammen aus der Lieferung gefallen,
+# und die einzige Spur war eine Warnzeile. Ein Erzeugnis, dem ein zugesagter Bestandteil
+# fehlt, gilt hier als nicht erzeugt.
+verloren = re.findall(r"Could not fetch resource ([^\r\n:]+)", r.stderr or "")
+if verloren:
+    print(f"FEHLER: pandoc hat {len(verloren)} Ressource(n) nicht geholt - die "
+          f"Word-Fassung traegt sie nicht:", file=sys.stderr)
+    for pfad in sorted(set(verloren))[:10]:
+        print("        " + pfad, file=sys.stderr)
+    os.remove(DOCX)
+    sys.exit(1)
+
+diagramme = len(re.findall(r"!\[Diagramm \d+", text))
+if diagramme != len(blocks):
+    print(f"FEHLER: {len(blocks)} Mermaid-Bloecke, aber {diagramme} Bildverweise im "
+          f"vorverarbeiteten Markdown.", file=sys.stderr)
+    os.remove(DOCX)
+    sys.exit(1)
+
+size = os.path.getsize(DOCX)
+print(f"geschrieben: {DOCX} ({size / 1024 / 1024:.1f} MB), "
+      f"{diagramme} Diagramme eingebettet")
+if (r.stderr or "").strip():
+    print("pandoc-Warnungen (Auszug):", r.stderr[:800])

package/.koolie/core/build/doc/00-kopf.md

@@ -0,0 +1,18 @@
+# Koolie – Framework für den professionellen Einsatz von KI-Codierassistenten in Softwareentwicklungsteams
+
+**Vorgehensmodell und technische Referenzimplementierung – projektneutral, wiederverwendbar, erweiterbar**
+
+| | |
+|---|---|
+| Dokumentversion | 1.25.0 (entspricht Framework-Release 1.25.0) |
+| Stand | 2026-09-28 |
+| Status | **Kein Modulträger steht auf `entwurf`.** Gezählt am 2026-09-22 über den ganzen Kern: 81 Träger führen eine Steckbriefzeile, davon **77 auf `pilot`** und vier als Ausfüllschlitz einer Vorlage – Kriterium 3 der 1.0.0-Definition ist seit Release 0.53.0 erfüllt und wird bei jedem Validatorlauf nachgerechnet (Prüfung 46). Die technische Validierung gegen reale Installationen ist als Roadmap-Arbeitspaket AP2 **gefahren und mit Release 0.86.0 zu Ende geführt**; die Protokolle liegen unter `.koolie/core/tests/protocols/`. Was zwischen diesem Stand und 1.0.0 liegt, steht im Releaseplan der Roadmap (Kap. 30) |
+| Vertraulichkeit | projektneutral – enthält keine organisations-, kunden-, personen- oder infrastrukturspezifischen Inhalte; Beispiele sind synthetisch |
+| Zielprodukt | Kein einzelnes. Der Kern ist werkzeugneutral; die Bindung an einen KI-Client leistet ein **Client Pack** (`.koolie/core/clients/`). Ausgeliefert werden fünf: `devin-desktop`, `claude-code`, `openai-codex`, `kiro` und `cursor` (Reifegrad `pilot`). **Welches Produkt ein Pack abbildet, gegen welche verbindliche Zielversion und mit welchem Stand der Produktbeobachtung, steht im Pack selbst** (Kap. 7a, 15.1) – nicht hier: Diese Angaben ändern sich mit dem Produkt, und der Kern soll sich nicht mit ihm ändern. |
+| **Reproduzierbarkeit** | Das Dokument wird aus dem Repository assembliert und baut aus einem frischen Auscheckstand. Laufzeitdateien stammen aus einer Referenzinstallation, die beim Bau entsteht; jede trägt die Angabe, aus welchem Client Pack sie kommt. |
+| Bestandteile der Lieferung | dieses Hauptdokument (Markdown und Word) und das Referenz-Repository – das Repository ist die maßgebliche, versionierte Quelle aller eingebetteten Artefakte |
+| Autorenschaft | erstellt als beauftragte Ausarbeitung; Verantwortungsübernahme durch `<FRAMEWORK_OWNER>` bei Übernahme |
+
+**Warum Koolie?** Ein **Koolie** ist ein australischer Hütehund, und das Bild ist die Aufgabenbeschreibung dieses Frameworks: Ein Hütehund treibt die Herde nicht, und er ersetzt den Schäfer nicht – er hält sie beisammen und in Richtung. Er arbeitet selbständig, aber auf Anweisung, und er hält Grenzen, ohne zu beißen. Genau das tut dieses Framework mit einem KI-Client: Es macht ihn nicht besser, und es entscheidet nichts an seiner Stelle – es hält ihn in der Spur, an den Grenzen und an den Stellen, an denen ein Mensch entscheidet. Ein Koolie ist außerdem eine **Gebrauchsrasse, kein Schauhund**, und das ist hier ein Anspruch: Was in diesem Dokument steht, muss im Alltag eines Projekts tragen, nicht in einer Vorführung gut aussehen. Die Namensentscheidung mit ihrer Begründung und den verworfenen Alternativen steht als D-125 im Decision Log (Kap. 29.2).
+
+**Lesehinweise:** Verbindlichkeit wird durchgängig über **MUSS / SOLL / KANN / DARF NICHT** ausgedrückt; normative Abschnitte sind als solche gekennzeichnet, Erläuterungen tragen den Zusatz „(Erläuterung)", Beispiele sind stets „**Beispiel (synthetisch)**". Jede Aussage über Produktfunktionen eines KI-Clients trägt einen Belegstatus: `[DOK]` offiziell dokumentiert (Quellen in Anhang 31.4), `[EMPF]` technisch begründete, noch nicht in einer Installation ausgeführte Empfehlung, `[KONZ]` konzeptioneller Vorschlag ohne Produktbezug; offene Prüfpunkte tragen den Belegstand `BELEG OFFEN` mit Grund und Datum. Variable Inhalte erscheinen ausschließlich als Platzhalter in spitzen Klammern (Register in Anhang 31.3); offene Projektentscheidungen als `<TBD: …>`. Verweise der Form `.koolie/core/framework/core/…` bezeichnen Dateien des Referenz-Repositorys. Bestandteile der Laufzeitschicht werden im Fließtext mit **Begriffen** benannt (Wurzel-Anweisungsdatei, Regelablage, Berechtigungsdatei …); ihre Pfade je Client Pack führt Anhang 31.2.

package/.koolie/core/build/doc/01-executive-summary.md

@@ -0,0 +1,24 @@
+# 1 Executive Summary
+
+Dieses Dokument liefert ein projektneutrales, wiederverwendbares und erweiterbares Framework für den professionellen Einsatz von **KI-Codierassistenten** in Softwareentwicklungsteams – als methodisches Vorgehensmodell **und** als sofort nutzbare technische Referenzimplementierung in Form eines Repositorys. Erster Einsatzzweck ist die strukturierte Einführung des Werkzeugs und das Onboarding neuer Entwicklerinnen und Entwickler in einem bestehenden Projekt; die Übertragung auf weitere Teams und Projekte ist konstruktiv vorgesehen und beschränkt sich auf den Austausch einer einzigen Ebene, des Project Overlays.
+
+**Der Kern ist werkzeugneutral, und das ist nachprüfbar gemeint.** Welcher Assistent zum Einsatz kommt, legt ein **Client Pack** fest (Kap. 7a) – eine Abbildungsschicht, die keine Regel einführt und keine lockert. Ausgeliefert werden vier: `claude-code`, `devin-desktop`, `openai-codex` und – mit Reifegrad `pilot` – `kiro`; die Regelmenge ist bei allen dieselbe. Jedes Pack führt eine **Fähigkeitsmatrix**: jede technische Zusage des Frameworks, eingestuft als `[TECHNISCH]` (die Engine erzwingt sie), `[TEXTUELL]` (nur Anweisung im Kontext) oder `[NICHT ABBILDBAR]`. Damit wird sichtbar, was ein Werkzeug tatsächlich durchsetzt – denn ein Framework, dessen Schutzzusagen bei einem Client von der Engine erzwungen werden und bei einem anderen nur als Prosa im Prompt stehen, erzeugt sonst falsche Sicherheit. Die Matrizen sind unterschiedlich lang, weil eine Zusage, für die ein Client keinen Mechanismus hat, bei ihm keine Zeile bekommt; ihre Gesamtzahlen lassen sich deshalb nicht vergleichen (Kap. 7a.3).
+
+Das Framework beantwortet die zehn Leitfragen des Auftrags so:
+
+- **Sicherer und kontrollierter Einsatz:** Vier Kontrollschichten wirken zusammen – organisationsweite Einstellungen, versionierte Repository-Konfiguration (Berechtigungen mit `deny`-Vorrang, Hooks, Regeln), Sitzungsdisziplin (rückfragender Standardmodus, Einzelbestätigungen) und menschliche Prüfung entlang bestehender Quality Gates.
+- **Was der Assistent darf**, regeln sechs Betriebsmodi (M1 Analyse bis M5 Dokumentation, dazu M6 für das Eintragen von Entscheidungen des Menschen in das Overlay – nur mit Mandat) in Verbindung mit einer dreistufigen Risikoklassifizierung (niedrig/mittel/hoch, Maximumprinzip über dreizehn Faktoren); **was er nie darf**, fixiert eine zwölfteilige Delegationsverbotsliste (Freigaben, Merges, Releases, Architekturentscheidungen, Secrets, Echtdaten und weitere).
+- **Kontext** wird über vier Klassen (K0–K3) aufgabenbezogen bereitgestellt – mit technischer Absicherung gegen die häufigsten Fehler.
+- **Regeln, Skills und Prompts** sind über eine Vier-plus-zwei-Ebenen-Architektur strukturiert (Framework Core, Role Packs, Technology Packs, Project Overlay, dazu Organisationsvorgaben und flüchtiger Aufgabenkontext) und über eine achtstufige, widerspruchsgeprüfte Prioritätshierarchie geordnet.
+- **Onboarding** erfolgt über ein Programm mit Übungen, Negativübungen (Ködern) und dokumentierter Freigabe.
+- **Prüfung und Freigabe** von KI-Ergebnissen laufen ausschließlich über die bestehenden Reviews und Gates, ergänzt um KI-spezifische Prüfpunkte.
+- **Versionierung, Pflege und Übertragung** regelt ein Governance-Betriebsmodell mit Release-Prozess, Testkatalog und Übernahmeleitfaden.
+- **Nutzen und Risiken** misst ein Pilotkonzept mit ausdrücklich projektspezifisch festzulegenden Zielwerten.
+
+Die Referenzimplementierung liefert die zentrale Agentenanweisung, eine vollständige Project-Overlay-Vorlage mit Manifest-Mechanismus für dreizehn projektspezifische Dokumenttypen, zwölf Referenz-Skills mit Testfällen, ein Role Pack mit einem dreizehnten Skill, zwölf Prompt-Vorlagen, elf Checklisten, sechs validierte Entscheidungsbäume, das Onboarding-Paket, einen Testkatalog mit Prüf-Skripten sowie RACI-, Prozess- und Roadmap-Vorlagen. Die **Laufzeitschicht** – das, was der Assistent tatsächlich liest – wird dabei nicht von Hand gepflegt, sondern bei der Installation aus dem Kern in die Form des gewählten Client Packs erzeugt. Installiert wird über einen Starter für Windows oder macOS, der Projektverzeichnis, Client Pack und auf Wunsch ein Overlay-Muster abfragt und den Kern in das Projekt kopiert (Kap. 15.2, 28).
+
+**Was das Framework kostet, ist gemessen** (Kap. 28, Abschnitt 7): Eine kleine Aufgabe wird mit dem Framework rund zwei- bis dreimal so teuer, eine größere rund doppelt so teuer – bei Listenpreisen von 2026-09-26 einige Cent je Aufgabe. Die feste Last je Modellaufruf (4.400 bis 15.000 Token je Client Pack) kommt fast immer aus dem Cache; den Unterschied macht die Arbeitsweise – Fundstellen, Skill, Ergebnisbericht. **Und die Schutzschicht wirkt nur für eine Sitzung, die im Verzeichnis der Installation startet**; bei mehreren Repositories gehört je Repository eine Installation dazu (Kap. 28, Abschnitt 4).
+
+**Wesentliche Grenze der Aussagen:** Die fünf Fähigkeitsmatrizen sind unterschiedlich weit belegt. Für `devin-desktop` ist die Validierung an einer realen Installation (Roadmap-AP2) abgeschlossen; offen ist genau eine Zeile, und zwar dauerhaft, weil ihre Frage von außen nicht beobachtbar ist. Für `claude-code` liegt ein Abgleich mit der Herstellerdokumentation einer benannten Clientversion vor, dazu Messungen für einen Teil der Zeilen; die übrigen Wirkungsnachweise stehen aus. Für `openai-codex` stammen alle Belege aus Messungen am Client selbst; einige Zeilen sind noch offen, und eine Beobachtung der Herstellerdokumentation fehlt. Für `kiro` ist die Kommandozeile gemessen, die Zeilen der IDE sind es nicht, und die Hooks laufen nur in der interaktiven Sitzung. Für `cursor` ist die Kommandozeile unter Windows gemessen; die Zeilen der IDE und die Schreibweise der Pfadmuster für macOS und Linux sind es nicht. Welche Zeile wie belegt ist, sagt die Belegspalte der jeweiligen Matrix. Alle produktbezogenen Aussagen tragen Belegstatus; Offenes sagt `BELEG OFFEN` **mit Grund und Datum und ohne Frist** – ein Belegstand sagt, was heute belegt ist, nicht, bis wann es belegt sein muss.
+
+**Empfohlene nächste Schritte für ein aufnehmendes Projekt:** Rollen besetzen und Datenschutz-/Vertragsprüfung beauftragen (AP1), Client Pack wählen und Overlay ausfüllen (AP4), Sicherheits- und Datenschutzfreigabe einholen (AP6) – der Weg steht in Kap. 30 und im Abschlussteil.

package/.koolie/core/build/doc/02-zielbild.md

@@ -0,0 +1,13 @@
+# 2 Zielbild
+
+Das Framework beschreibt einen Zustand, in dem KI-Unterstützung ein normaler, unaufgeregter Teil des Entwicklungsprozesses ist – so selbstverständlich und so kontrolliert wie eine Build-Pipeline:
+
+**Für Entwicklerinnen und Entwickler:** Eine Aufgabe beginnt mit einem kurzen Preflight (Stufe, Modus, Scope, Kontext) und läuft dann entlang vertrauter Skills: verstehen, planen, klein ändern, testen, dokumentieren. Der Assistent liefert belegte Befunde statt Behauptungen; Rückfragen des Agenten sind Alltag und willkommen. Die Prüfarbeit verlagert sich dorthin, wo menschliches Urteil zählt: Aufgaben zuschneiden, Fundstellen verifizieren, Diffs verstehen. Niemand übernimmt Code, den er nicht erklären kann – und niemand muss, denn der Prozess lässt dafür Raum.
+
+**Für neue Teammitglieder:** Der KI-Client ist vom ersten Tag an ein geduldiges Erschließungswerkzeug: Codebasis analysieren, Abläufe erklären lassen, Fragenlisten für das Mentorengespräch aufbauen – nur lesend, auf einem Übungsrepository auch schreibend. Das Onboarding vermittelt ausdrücklich, dass souveräne Nutzung an der Qualität der Abgrenzung, der Kontextauswahl und der Prüfung gemessen wird, nicht an der Menge delegierter Aufgaben. Die Freigabe zur selbstständigen Nutzung ist ein definierter, dokumentierter Punkt.
+
+**Für Reviewer, Architektur, Sicherheit und Datenschutz:** Jede KI-unterstützte Änderung ist als solche gekennzeichnet (Nutzungsvermerk mit Stufe, Modus, Skills, Kontext), klein geschnitten und mit Ergebnisbericht unterlegt. Die bestehenden Gates gelten unverändert; KI-spezifische Prüfpunkte (Fundstellen-Treue, Testaussagekraft, API-Existenz) sind Checklisten-Routine. Sicherheits- und Datenschutzgrenzen sind doppelt gezogen – als Regel und als technische Sperre – sodass ein einzelner Fehler nicht genügt, um sie zu reißen.
+
+**Für Projektleitung und Organisation:** Der Einsatz ist auditierbar (Versionen, Vermerke, Register), messbar (Pilotmetriken als Bündel, ohne Personenbewertung) und steuerbar (Kontrollstufen, Freigaben, Ausnahme- und Vorfallprozess). Ein neues Projekt übernimmt das Framework als Release, füllt ein Overlay und ist arbeitsfähig, ohne den Kern anzufassen; ein Produktwechsel des Werkzeugs trifft nur die Abbildung auf den Client – ein anderes Client Pack –, nicht die Regeln (Kap. 7a).
+
+**Für das Framework selbst:** Es ist ein gepflegtes Produkt mit Owner, Feedbackkanal, Testkatalog und Release-Zyklus – es lernt aus Reviews, Vorfällen und Produktänderungen, statt zu veralten.

package/.koolie/core/build/doc/03-ziele-nichtziele.md

@@ -0,0 +1,28 @@
+# 3 Ziele und Nicht-Ziele
+
+## 3.1 Ziele
+
+| Nr. | Ziel | Umgesetzt durch |
+|---|---|---|
+| Z1 | Sicherer, kontrollierter, effizienter Assistenz-Einsatz mit klaren Grenzen | Kontrollschichten (Kap. 12), Betriebsmodi (Kap. 9), Risikoklassifizierung (Kap. 13), Delegationsverbote |
+| Z2 | Konsistentes, schnelles Onboarding neuer Entwicklerinnen und Entwickler | Onboarding-Paket (Kap. 24), lesende Skills, Erklärvorlagen |
+| Z3 | Kontrollierte, aufgabenbezogene Kontextbereitstellung | Kontextklassen K0–K3, Overlay-Manifest, technische Sperren (Kap. 11) |
+| Z4 | Wiederverwendbarkeit über Projekte mit minimalem Anpassungsaufwand | Ebenenarchitektur, austauschbares Overlay, Adoption Guide (Kap. 7, 8, 28) |
+| Z5 | Unveränderte Geltung bestehender Qualitäts- und Freigabeprozesse | P6, Review-Regeln, MR-Vermerk (Kap. 10, 14, 22) |
+| Z6 | Nachvollziehbarkeit und Auditierbarkeit jedes KI-Einsatzes | Ergebnisberichte, Nutzungsvermerke, Versionsketten (Kap. 25) |
+| Z7 | Pflegbarkeit und Prüfbarkeit des Frameworks selbst | Governance, Testkatalog, Validierungsskripte (Kap. 25, 26) |
+| Z8 | Messbarkeit von Nutzen, Qualität, Risiken und Akzeptanz | Pilotkonzept und Metriken (Kap. 27) |
+| Z9 | Übertragbarkeit der Prinzipien auf andere KI-Werkzeuge | Tool Independence: kanonische Ebene getrennt von der Laufzeitschicht (Kap. 8, 15) |
+
+## 3.2 Nicht-Ziele
+
+| Nr. | Nicht-Ziel | Begründung und Abgrenzung |
+|---|---|---|
+| N1 | Maximierung des Automatisierungsgrads oder „autonome" Entwicklung | Human Accountability ist Grundprinzip; Autonomie-Modi sind untersagt beziehungsweise ausnahmepflichtig |
+| N2 | Ersatz bestehender Prozesse, Reviews, Gates oder Rollen | Das Framework ergänzt; es ersetzt nichts (P6) |
+| N3 | Rechtliche Bewertung oder Compliance-Freigabe (Datenschutzrecht, Lizenzrecht, KI-Regulierung) | Liegt bei den zuständigen Rollen der Organisation; das Framework liefert operative Anschlusspunkte und benennt Prüfbedarfe (K-06) |
+| N4 | Bewertung oder Überwachung von Personen anhand von Nutzungs- oder Pilotdaten | Ausdrücklich ausgeschlossen (V7, Metrik-Grundsätze) |
+| N5 | Produktdokumentation oder Schulung für einen KI-Client als Produkt | Das Framework referenziert die offizielle Dokumentation; es dupliziert sie nicht |
+| N6 | Vollständige technologie- oder branchenspezifische Regelwerke in der Erstfassung | Technology Packs entstehen projektbezogen; die Struktur dafür ist Teil des Frameworks |
+| N7 | Abdeckung anderer Einsatzformen (Cloud-Sitzungen, Läufe ohne beobachtende Person, Fremdagenten) im Kern der Erstfassung | Als Erweiterung vorgesehen, standardmäßig deaktiviert (D-10, D-386, K-04). Ein Kommandozeilen-Client in einer beobachteten Sitzung gehört zum Kern |
+| N8 | Garantie fehlerfreier KI-Ergebnisse | Unerreichbar; das Framework macht Fehler früh sichtbar und begrenzt ihre Wirkung |