@renoxar/koolie 1.25.0

package/.koolie/core/tests/erhebungen/ablage.py

@@ -0,0 +1,357 @@
+# -*- coding: utf-8 -*-
+"""Sagt den Skripten dieser Ablage, WOHIN ihre Belege und Prompts gehoeren.
+
+🔴 DER ANLASS IST D-222 SELBST. Bis zum Meßtag von Buendel 4 lag der Apparat in
+`devpacks/leitwerk-erhebungen-2026-09-19-b4/skripte/`, und fuenf Skripte legten
+ihre Belege schlicht *neben sich*:
+
+    BELEGE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "belege")
+
+Das war richtig, solange das Skript daneben lag. **Mit 0.79.0 ist der Apparat ins
+Repositorium gewandert - und derselbe Ausdruck zeigt seither HINEIN.** Ein
+Nachlauf haette 44 Belegdateien samt Sitzungsmitschriften mit Werkzeugeingaben
+unter `<CORE_DIR>/tests/erhebungen/belege/` angelegt; `lauf.py` erzeugt das
+Verzeichnis selbst. Genau das hat D-222 verworfen:
+
+    "Verworfen: auch die Belege zu versionieren (203 Dateien, darunter fuenfzig
+    Sitzungstranskripte mit Werkzeugeingaben; sie sind AUFZEICHNUNG, nicht
+    Anweisung - dieselbe Trennlinie, die D-141 fuer den Kontrollzuschnitt zieht)."
+
+  Wer einen Apparat umzieht, zieht seine relativen Pfade mit um - oder er
+  verschiebt ihr Ziel, ohne es zu merken.
+
+DIE ABLAGE WIRD GESAGT, NICHT ABGELEITET - dieselbe Lehre wie `--ziel` beim
+Baumbau (D-218). Ein Standardwert im Quelltext waere eine gepflegte Zahl: Er
+stimmt fuer die Erhebung, fuer die er geschrieben wurde, und fuer keine danach.
+
+    set LW_ERHEBUNG=C:\\Users\\...\\devpacks\\leitwerk-erhebungen-2026-09-20-b4n   # SYNTHETISCH
+
+Fehlt die Angabe, bricht jedes Skript ab, das eine Belegablage braucht. Ein
+Abbruch ist billiger als ein Beleg am falschen Ort.
+"""
+import io
+import os
+import re
+import sys
+
+UMGEBUNG = "LW_ERHEBUNG"
+
+# Die Kennung einer Blattzelle, ausgeschrieben und zusammengezogen. Sie steht
+# seit 0.82.0 an EINER Stelle; bis dahin uebersetzte `baeume-b4.py` sie mit
+# `kern[:2].upper()` und `dossier-b4.py` gar nicht zurueck.
+_KENNUNG_RE = re.compile(r"^([A-Z]{2,3}-[0-9]{3})-[PN][0-9]{2}$")
+_KURZ_RE = re.compile(r"^([a-z]{2,3})([0-9]{3})([pn][0-9]{2})$")
+
+# Die Wurzel des Repositoriums: dieses Modul liegt in
+# <wurzel>/.koolie/core/tests/erhebungen/ - also VIER Ebenen unter der Wurzel.
+#
+# 0.88.0: Bis dahin waren es drei, weil der Kern ein einziges Verzeichnissegment
+# war (`leitwerk-core`). Der Umzug nach `.koolie/core` haette WURZEL auf `.koolie/`
+# gesetzt, und jeder abgeleitete Kernpfad haette ein Segment zu wenig getragen.
+# Die Zahl wird deshalb aus CORE_TIEFE gerechnet und nicht im Quelltext gezaehlt
+# (D-299).
+CORE_REL = ".koolie/core"
+CORE_TIEFE = CORE_REL.count("/") + 1
+
+_HIER = os.path.dirname(os.path.abspath(__file__))
+_KERN = os.path.dirname(os.path.dirname(_HIER))      # die Lage aus CORE_REL
+WURZEL = _KERN
+for _ in range(CORE_TIEFE):
+    WURZEL = os.path.dirname(WURZEL)
+
+
+def _innerhalb(pfad, wurzel):
+    """True, wenn `pfad` unter `wurzel` liegt - ohne Praefixvergleich auf Text.
+
+    Ein Praefixvergleich auf der Zeichenkette nimmt ein GESCHWISTERverzeichnis,
+    dessen Name mit dem der Wurzel beginnt, faelschlich als deren Kind:
+    `...\\koolie-erhebungen` neben `...\\koolie`. Das ist genau die Bauform von
+    D-219, eine Ebene tiefer: ein Praefix, das mehr erfasst als sein Gegenstand.
+
+    0.88.0: Der Satz nannte bis dahin `...\\leitwerk-erhebungen` neben
+    `...\\leitwerk`. Die Belegablagen behalten ihren alten Namen (sie sind
+    datierte Aufzeichnungen und werden nicht umbenannt), das Repositorium nicht -
+    damit ist GENAU DIESES Paar kein Beispiel mehr. Der Fall bleibt herstellbar,
+    sobald eine Ablage neben dem Repositorium liegt und dessen Namen als Praefix
+    traegt; deshalb steht hier ein Beispiel mit dem neuen Namen und nicht der
+    alte Satz.
+    """
+    try:
+        gemeinsam = os.path.commonpath([os.path.abspath(pfad),
+                                        os.path.abspath(wurzel)])
+    except ValueError:          # verschiedene Laufwerke
+        return False
+    return gemeinsam == os.path.abspath(wurzel)
+
+
+def erhebung():
+    """Der Wurzelpfad der Erhebungsablage - mit zwei Waechtern."""
+    wert = os.environ.get(UMGEBUNG, "").strip().strip('"')
+    if not wert:
+        raise SystemExit(
+            "ABBRUCH: %s ist nicht gesetzt.\n"
+            "Die Belege einer Erhebung sind AUFZEICHNUNG und liegen ausserhalb\n"
+            "des Repositoriums (D-222). Seit der Apparat im Kern liegt, gibt es\n"
+            "keinen ableitbaren Ort mehr - er wird gesagt:\n"
+            "    set %s=<Pfad der Erhebungsablage>" % (UMGEBUNG, UMGEBUNG))
+    wert = os.path.abspath(wert)
+    if _innerhalb(wert, WURZEL):
+        raise SystemExit(
+            "ABBRUCH: %s zeigt mit %r INS Repositorium (%s).\n"
+            "Belege und Prompts einer Erhebung gehoeren daneben, nicht hinein\n"
+            "(D-222)." % (UMGEBUNG, wert, WURZEL))
+    return wert
+
+
+def kernversion():
+    """Die Version, die das Uebungsrepositorium tragen MUSS.
+
+    🔴 DREI WAECHTER DERSELBEN VORBEDINGUNG, DREI SOLLWERTE, KEINER STIMMTE
+    (2026-09-20, Vorbedingungsdurchgang des Nachlaufs). `umgebungen-bauen-b4.py`
+    und `baeume-b4.py` fuehrten `--erwarte 0.78.0`, `historie-bauen-b4.py`
+    fuehrte `0.77.0` - waehrend das Uebungsrepositorium auf `0.78.2` stand und
+    der Kern auf `0.79.1`. Ein Sollwert im Quelltext ist eine gepflegte Zahl,
+    und eine Zahl, die gepflegt werden muss, wird nicht gepflegt (D-153).
+
+    Er wird deshalb ABGELEITET: Sollstand ist die Version DIESES Kerns. Damit
+    beantwortet der Waechter zugleich die erste Frage jedes
+    Vorbedingungsdurchgangs - hat ein Release den Gegenstand der Messung
+    angefasst? -, statt sie einem gepflegten Wert zu ueberlassen.
+    `--erwarte` bleibt als Uebersteuerung erhalten.
+    """
+    p = os.path.join(WURZEL, ".koolie/core", "VERSION")
+    with open(p, encoding="utf-8") as f:
+        return f.read().strip()
+
+
+UMGEBUNG_UEBUNG = "LW_UEBUNG"
+
+
+def uebungsrepositorium():
+    """Der Pfad des Uebungsrepositoriums - GESAGT, nicht im Quelltext.
+
+    🔴 DER ANLASS IST GEMESSEN (2026-09-21, D-231). Acht Werkzeuge dieses Kerns
+    trugen einen Arbeitsplatzpfad im Quelltext, und der Pfad enthaelt den
+    Kontonamen einer natuerlichen Person:
+
+        UEB = r"C:\\Users\\<konto>\\Documents\\devpacks\\test-devin-framework"   # SYNTHETISCH
+
+    Solange der Apparat NEBEN dem Repositorium lag, stand das in einer
+    unversionierten Ablage. **Mit D-222 ist er hineingewandert und hat den Pfad
+    mitgebracht** - in genau das Repositorium, dessen Overlay-Manifest *"keine
+    Secrets, keine Personen, keine internen Adressen"* verlangt und fuer das
+    `0.78.1` eigens `UEBERGABE.local.md` eingefuehrt hat. **Keine der siebzig
+    Pruefungen sah es**: Pruefung 6 kennt Secret-Muster, E-Mail-Adressen,
+    IP-Adressen und Hostnamen - keinen Benutzerprofilpfad.
+
+      Wer einen Apparat umzieht, zieht seine Arbeitsplatzpfade mit um - und
+      veroeffentlicht sie, ohne es zu entscheiden.
+
+    Dieselbe Loesung wie bei D-224: Der Ort wird gesagt. Ein Standardwert waere
+    wieder ein Arbeitsplatz im Quelltext.
+    """
+    wert = os.environ.get(UMGEBUNG_UEBUNG, "").strip().strip('"')
+    if not wert:
+        raise SystemExit(
+            "ABBRUCH: %s ist nicht gesetzt.\n"
+            "Das Uebungsrepositorium liegt NEBEN diesem Repositorium, und sein\n"
+            "Pfad gehoert keinem Quelltext - er wird gesagt (D-231):\n"
+            "    set %s=<Pfad des Uebungsrepositoriums>"
+            % (UMGEBUNG_UEBUNG, UMGEBUNG_UEBUNG))
+    wert = os.path.abspath(wert)
+    if not os.path.isdir(wert):
+        raise SystemExit(
+            "ABBRUCH: %s zeigt mit %r auf kein Verzeichnis." % (UMGEBUNG_UEBUNG, wert))
+    return wert
+
+
+def belege(anlegen=True):
+    """`<Erhebungsablage>/belege` - der Ort aller Belegquellen eines Laufs."""
+    p = os.path.join(erhebung(), "belege")
+    if anlegen:
+        os.makedirs(p, exist_ok=True)
+    return p
+
+
+def prompts(anlegen=True):
+    """`<Erhebungsablage>/prompts` - der Ort der Promptdateien."""
+    p = os.path.join(erhebung(), "prompts")
+    if anlegen:
+        os.makedirs(p, exist_ok=True)
+    return p
+
+
+def sollmenge(promptordner, baumordner):
+    """Die Kennungen, die DIESE Erhebung schuldet - und die, die sie nicht schuldet.
+
+    🔴 DER ANLASS IST GEMESSEN (2026-09-21, D-230). Der Nachlauf von Buendel 4 misst
+    vierzehn Zellen. Sein Promptverzeichnis traegt die **fuenfzig** Prompts des
+    Messtags, weil `prompts-schreiben-b4.py` sie alle schreibt und keine Zelle
+    kennt. `stand-b4.py` leitete seine Sollmenge daraus ab und meldete am halb
+    gefahrenen Nachlauf **35 fehlende Laeufe und rund 37 USD** - faellig waren
+    fuenfzehn und rund achtzehn. Und `reihe-b4.py` ohne Argumente - der Befehl, den
+    `stand-b4.py` selbst als naechsten nennt - brach am ersten Baum ab, den es in
+    dieser Erhebung nie gab, und fuhr **keinen einzigen** Lauf.
+
+    Die Sollmenge kommt deshalb aus den **Messbaeumen**: `baeume-b4.py` legt genau
+    die Baeume an, die der Zuschnitt dieser Erhebung nennt. Ein Prompt ohne Baum ist
+    eine Zelle einer anderen Erhebung - derselbe Grund, aus dem `LW_ERHEBUNG` gesagt
+    wird (D-224) und `--ziel` beim Baumbau (D-218): **Ein Ort, der aus der Umgebung
+    erschlossen wird, gehoert dem, der ihn zuletzt gefuellt hat.**
+
+      Ein Verzeichnis ist kein Zuschnitt. Es ist der Zuschnitt von gestern.
+
+    Gibt zwei sortierte Listen zurueck: die Kennungen mit Baum (ein `-t2.txt` ist
+    kein eigener Eintrag - er ist der zweite Turn seiner Zelle) und die Prompts ohne
+    Baum, die die Aufrufer NENNEN muessen, statt sie stillschweigend zu uebergehen.
+    """
+    einfach, zwei = set(), set()
+    for x in sorted(os.listdir(promptordner)):
+        if not x.endswith(".txt"):
+            continue
+        n = x[:-4]
+        # 🔴 Eine NACHMESSUNG (`n<kennung>`) gehoert nicht zur Sollmenge. Sie faehrt
+        # einen weiteren Turn im Baum ihrer Zelle und hat keinen eigenen Baum; wer
+        # sie mitzaehlt, meldet einen Fehlbestand, den es nicht gibt. Praezedenz:
+        # `nsk004p01` und `nsk009p01` aus Buendel 2.
+        if n.startswith("n"):
+            continue
+        if n.endswith("-t2"):
+            zwei.add(n[:-3])
+        else:
+            einfach.add(n)
+    vorhanden = set()
+    if os.path.isdir(baumordner):
+        vorhanden = {x for x in os.listdir(baumordner)
+                     if os.path.isdir(os.path.join(baumordner, x))}
+    mit, ohne = [], []
+    for k in sorted(einfach):
+        (mit if k in vorhanden else ohne).append(k)
+    return mit, zwei, ohne
+
+
+def blaetter(wurzel=None):
+    """Je Kennungspraefix eines Testblatts (`SK-012`, `RE-001`) sein Skill und sein Ort.
+
+    🔴 ABGELEITET, NICHT GEPFLEGT - und der Anlass ist derselbe zum dritten Mal.
+    `umgebungen-bauen-b4.py` fuehrte die drei Skills von Buendel 4 BEIM NAMEN, und
+    alle drei lagen auch im Baum von Buendel 5: Der Waechter haette geschwiegen,
+    waehrend der gemessene Skill fehlte (D-237). `dossier-b4.py` fuehrte dieselbe
+    Zuordnung ein zweites Mal als Handliste.
+
+      Marken, Wurzeln und Namenslisten gehoeren abgeleitet, nicht gepflegt.
+
+    Gesucht wird jede `TESTS.md` unter `framework/skills/` und unter
+    `framework/<art>/<pack>/skills/`; der Praefix kommt aus der ersten Spalte ihrer
+    Tabellenzeilen, also aus dem Blatt selbst und nicht aus seinem Dateinamen.
+    Rueckgabe: Praefix -> dict(skill, blatt, pack, art).
+    """
+    wurzel = wurzel or WURZEL
+    rahmen = os.path.join(wurzel, ".koolie/core", "framework")
+    orte = [(os.path.join(rahmen, "skills"), None, None)]
+    for art in ("role-packs", "tech-packs"):
+        basis = os.path.join(rahmen, art)
+        if not os.path.isdir(basis):
+            continue
+        for pack in sorted(os.listdir(basis)):
+            unter = os.path.join(basis, pack, "skills")
+            if os.path.isdir(unter):
+                orte.append((unter, pack, art))
+    aus = {}
+    for ablage, pack, art in orte:
+        if not os.path.isdir(ablage):
+            continue
+        for skill in sorted(os.listdir(ablage)):
+            blatt = os.path.join(ablage, skill, "TESTS.md")
+            if not os.path.isfile(blatt):
+                continue
+            with io.open(blatt, encoding="utf-8", newline="") as fh:
+                text = fh.read()
+            for zeile in text.replace("\r\n", "\n").split("\n"):
+                if not zeile.startswith("| "):
+                    continue
+                kennung = zeile.split("|")[1].strip()
+                treffer = _KENNUNG_RE.match(kennung)
+                if not treffer:
+                    continue
+                praefix = treffer.group(1)
+                fruehere = aus.get(praefix)
+                if fruehere and fruehere["skill"] != skill:
+                    raise SystemExit(
+                        "ABBRUCH: der Kennungspraefix %s steht in zwei Blaettern "
+                        "(%s und %s) - eine Zelle laesst sich dann keinem Skill "
+                        "zuordnen" % (praefix, fruehere["skill"], skill))
+                aus[praefix] = {
+                    "skill": skill,
+                    "blatt": os.path.relpath(blatt, wurzel).replace(os.sep, "/"),
+                    "pack": pack,
+                    "art": art,
+                }
+    if not aus:
+        raise SystemExit("ABBRUCH: kein Testblatt unter framework/ gefunden - die "
+                         "Ableitung haette ihren Gegenstand verloren und bliebe "
+                         "leise leer (D-23)")
+    return aus
+
+
+def zellkennung(kurz):
+    """`sk012p01` -> `SK-012-P01`, `re001n09` -> `RE-001-N09`.
+
+    Der Apparat fuehrt die Kennung einer Zelle zusammengezogen und klein; das
+    Testblatt fuehrt sie ausgeschrieben. Die Ruecknahme stand bis 0.81.0 an zwei
+    Stellen im Quelltext.
+    """
+    treffer = _KURZ_RE.match(kurz)
+    if not treffer:
+        raise SystemExit("ABBRUCH: %r ist keine Zellkennung des Apparats" % kurz)
+    a, b, c = treffer.groups()
+    return "%s-%s-%s" % (a.upper(), b, c.upper())
+
+
+def skillmenge(zellen, wurzel=None):
+    """Welche Skills eine Zellmenge misst - und welche Packs dafuer aktiv sein muessen.
+
+    Rueckgabe: (skills, packs). `skills` ist die sortierte Namensliste, `packs` die
+    sortierte Liste der (Art, Packname) - leer, wenn alle gemessenen Skills im Kern
+    liegen. Genau diese beiden Listen ersetzen die Handliste des Waechters (D-237).
+    """
+    karte = blaetter(wurzel)
+    skills, packs, unbekannt = set(), set(), []
+    for kurz in zellen:
+        voll = zellkennung(kurz) if "-" not in kurz else kurz
+        praefix = "-".join(voll.split("-")[:2])
+        eintrag = karte.get(praefix)
+        if not eintrag:
+            unbekannt.append(voll)
+            continue
+        skills.add(eintrag["skill"])
+        if eintrag["pack"]:
+            packs.add((eintrag["art"], eintrag["pack"]))
+    if unbekannt:
+        raise SystemExit("ABBRUCH: zu %d Zelle(n) traegt kein Testblatt des Frameworks "
+                         "den Kennungspraefix: %s" % (len(unbekannt),
+                                                      ", ".join(sorted(unbekannt))))
+    return sorted(skills), sorted(packs)
+
+
+def laeufe(zellen, zwei):
+    """Die Laufkennungen einer Zellmenge - eine Zelle mit zweitem Turn hat ZWEI."""
+    aus = []
+    for k in zellen:
+        if k in zwei:
+            aus += [k + "t1", k]
+        else:
+            aus.append(k)
+    return aus
+
+
+if __name__ == "__main__":
+    sys.stdout.reconfigure(encoding="utf-8")
+    print("Kernversion:    ", kernversion())
+    print("Erhebungsablage:", erhebung())
+    print("Belege:         ", belege(anlegen=False))
+    print("Prompts:        ", prompts(anlegen=False))
+    karte = blaetter()
+    print("Testblaetter:   %d (%s)"
+          % (len(karte), ", ".join("%s=%s" % (k, v["skill"])
+                                   for k, v in sorted(karte.items()))))

package/.koolie/core/tests/erhebungen/apparat/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""Der Messapparat als Paket (CR-2026-160, D-473, K-174).
+
+Bis 1.18.2 entstand je Release eine Handvoll kopierter Skripte in der Erhebungsablage -
+67 Stueck in elf Ablagen, ohne einen einzigen Test (D-436). Dieses Paket ersetzt sie fuer
+jede NEUE Reihe:
+
+  * reihe.py        die Reihe als DATEN (eine JSON-Datei in der Erhebungsablage) - Laeufe,
+                    Prompts, Erwartungen, Client, Modell, Gruppe, Kontingent
+  * baum.py         Messbaum: bauen, herrichten, auf den Sollstand zuruecksetzen, Baum-Hash
+  * vorpruefung.py  deterministisch VOR jedem bezahlten Lauf - Abbruch statt Lauf
+  * kontingent.py   ein Buch je Lauf, die Summe wird gerechnet (Falle 8 aus 1.17.0)
+  * clients.py      je Client ein Adapter; was nicht erhoben ist, sagt es
+  * belege.py       sichern und auswerten
+  * stand.py        die Standmarke einer Ergebniszelle (Pruefung 103, K-61)
+  * selbsttest.py   der Apparat gegen einen Attrappen-Client - ohne Kontingent
+
+Aufruf: python tests/erhebungen/messen.py REIHE.json BEFEHL (siehe messen.py).
+
+Die Skripte der Buendel 4 und 5 bleiben liegen: Sie sind Beleg vergangener Protokolle und
+bauen weiterhin deren Messbaeume; eine neue Reihe faehrt mit diesem Paket (D-473).
+"""

package/.koolie/core/tests/erhebungen/apparat/baum.py

@@ -0,0 +1,214 @@
+# -*- coding: utf-8 -*-
+"""Der Messbaum: bauen, herrichten, zuruecksetzen - und sein Zustand als EINE Zahl.
+
+FESTER PFAD STATT NEUER VERZEICHNISSE (K-174, Frage d). Der Client stellt jeder Anfrage
+einen Anfang voran, in dem auch das Arbeitsverzeichnis steht. Ein neues Verzeichnis je
+Lauf ist ein neuer Anfang - und jeder Lauf legte rund 35.000 Token Cache NEU an (D-436).
+Im Modus 'fest' laeuft jede Reihe in DEMSELBEN Verzeichnis, und zwischen zwei Laeufen
+wird zurueckgesetzt statt neu kopiert.
+
+DAS ZURUECKSETZEN MUSS VOLLSTAENDIG SEIN - sonst misst der naechste Lauf den vorigen mit
+(das Rauschen aus D-213). Deshalb wird es nicht geglaubt, sondern gemessen: baumhash()
+ueber jede Datei ausser .git und den genannten Ausnahmen, vor jedem Lauf gegen den Hash
+der Basis (vorpruefung.py). Ignorierte Dateien der Basis (.env ist eine) werden aus der
+Basis zurueckkopiert; git allein wuerde sie nicht wiederherstellen.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import stat
+import subprocess
+import sys
+
+AUTOR = ["-c", "user.name=Messung", "-c", "user.email=messung@example.invalid"]
+
+
+def git(baum: str, *args: str, pruefen: bool = True) -> str:
+    p = subprocess.run(["git", "-C", baum, *args], capture_output=True, text=True,
+                       encoding="utf-8", errors="replace")
+    if pruefen and p.returncode != 0:
+        raise RuntimeError(f"git {' '.join(args)} in {baum}: {p.stderr.strip()}")
+    return p.stdout.strip()
+
+
+def _ist_verbindung(pfad: str) -> bool:
+    """Symlink oder Verzeichnisverbindung (Windows-Junction) - wird nie betreten."""
+    if os.path.islink(pfad):
+        return True
+    try:
+        return bool(os.lstat(pfad).st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT)
+    except (AttributeError, OSError):
+        return False
+
+
+def dateien(baum: str, ohne=()) -> list:
+    """Alle Dateien relativ zum Baum, sortiert - ohne .git, ohne Ausnahmen, ohne Verbindungen."""
+    aus = []
+    ausnahmen = {".git", *ohne}
+    for wurzel, verz, files in os.walk(baum):
+        verz[:] = sorted(d for d in verz
+                         if d not in ausnahmen and not _ist_verbindung(os.path.join(wurzel, d)))
+        for f in sorted(files):
+            voll = os.path.join(wurzel, f)
+            if _ist_verbindung(voll):
+                continue
+            aus.append(os.path.relpath(voll, baum).replace(os.sep, "/"))
+    return aus
+
+
+def baumhash(baum: str, ohne=()) -> str:
+    """Pfad und Inhalt jeder Datei - ein Zustand, keine Zaehlung (D-218)."""
+    h = hashlib.sha256()
+    for rel in dateien(baum, ohne):
+        h.update(rel.encode("utf-8") + b"\0")
+        with open(os.path.join(baum, *rel.split("/")), "rb") as fh:
+            h.update(hashlib.sha256(fh.read()).digest())
+    return h.hexdigest()[:16]
+
+
+def sollstand(basis: str, ohne=()) -> dict:
+    return {"commit": git(basis, "rev-parse", "HEAD"),
+            "branch": git(basis, "symbolic-ref", "--short", "HEAD"),
+            "hash": baumhash(basis, ohne)}
+
+
+def _schreibschutz_weg(func, pfad, _info) -> None:
+    os.chmod(pfad, stat.S_IWRITE)
+    func(pfad)
+
+
+def entfernen(pfad: str) -> None:
+    """Loeschen, ohne einer Verzeichnisverbindung in ihr Ziel zu folgen (D-262)."""
+    if not os.path.lexists(pfad):
+        return
+    for wurzel, verz, _ in os.walk(pfad):
+        for d in list(verz):
+            voll = os.path.join(wurzel, d)
+            if _ist_verbindung(voll):
+                os.rmdir(voll) if not os.path.islink(voll) else os.unlink(voll)
+                verz.remove(d)
+    if sys.version_info >= (3, 12):
+        shutil.rmtree(pfad, onexc=_schreibschutz_weg)
+    else:
+        shutil.rmtree(pfad, onerror=_schreibschutz_weg)
+
+
+def basis_bauen(ziel: str, kern_quelle: str, client: str, praeparation: list) -> dict:
+    """Eine frische Installation als git-Baum - fuer Schrankenreihen ohne Uebungsrepositorium.
+
+    Schritte der Praeparation: {"art": "datei", "pfad", "inhalt"} | {"art": "entferne",
+    "pfad"} | {"art": "commit", "nachricht"}. Am Ende steht ein Commit 'Basis' mit
+    synthetischem Autor; ignorierte Dateien (etwa .env) liegen daneben und gehoeren zum
+    Sollstand, weil der Baum-Hash sie mitzaehlt.
+    """
+    if os.path.exists(ziel):
+        raise RuntimeError(f"{ziel} besteht schon - eine Basis wird nicht ueberschrieben")
+    os.makedirs(ziel)
+    git(ziel, "init", "-q", "-b", "main")
+    git(ziel, "config", "core.autocrlf", "false")
+    p = subprocess.run([sys.executable, "-B", os.path.join(kern_quelle, "install.py"),
+                        "--target", ziel, "--client", client],
+                       capture_output=True, text=True, encoding="utf-8", errors="replace")
+    if p.returncode != 0:
+        raise RuntimeError(f"install.py --target: Exit {p.returncode}\n{p.stdout[-800:]}\n{p.stderr[-800:]}")
+    for schritt in praeparation:
+        art = schritt.get("art")
+        pfad = os.path.join(ziel, *schritt.get("pfad", "").split("/")) if schritt.get("pfad") else ""
+        if art == "datei":
+            os.makedirs(os.path.dirname(pfad), exist_ok=True)
+            with open(pfad, "w", encoding="utf-8", newline="\n") as fh:
+                fh.write(schritt.get("inhalt", ""))
+        elif art == "entferne":
+            if os.path.isdir(pfad):
+                entfernen(pfad)
+            elif os.path.exists(pfad):
+                os.remove(pfad)
+        elif art == "commit":
+            git(ziel, "add", "-A")
+            git(ziel, *AUTOR, "commit", "-q", "--allow-empty", "-m", schritt.get("nachricht", "Schritt"))
+        else:
+            raise RuntimeError(f"unbekannter Praeparationsschritt '{art}'")
+    git(ziel, "add", "-A")
+    git(ziel, *AUTOR, "commit", "-q", "--allow-empty", "-m", "Basis")
+    return sollstand(ziel)
+
+
+def _remote_neu(baum: str, basis: str, hooks: str = "") -> None:
+    """Ein Wegwerf-Remote je Baum - ein durchgelassener Push landet dort und nirgends sonst.
+
+    Mit 'hooks' traegt das Remote Branch-Schutz und CI der Referenzgruppe (1.21.0): Die
+    Hooks liegen ausserhalb des Messbaums, der Agent erreicht sie nur ueber einen Push.
+    """
+    remote = baum.rstrip("\\/") + ".remote.git"
+    entfernen(remote)
+    subprocess.run(["git", "clone", "-q", "--bare", basis, remote], check=True,
+                   capture_output=True)
+    if hooks:
+        for name in sorted(os.listdir(hooks)):
+            ziel = os.path.join(remote, "hooks", name)
+            shutil.copy2(os.path.join(hooks, name), ziel)
+            os.chmod(ziel, 0o755)
+    git(baum, "remote", "remove", "origin", pruefen=False)
+    git(baum, "remote", "add", "origin", remote)
+
+
+def verbinden(baum: str, verbindungen: dict) -> None:
+    """Verzeichnisverbindungen, die weder Hash noch Zuruecksetzen betreten (1.21.0).
+
+    Der geteilte node_modules-Bestand (node-waechter.py): 118 MB je Baum waeren der Preis
+    einer Kopie. Eine vorhandene Verbindung bleibt; ein echtes Verzeichnis an ihrer Stelle
+    ist ein Abbruch - es waere ein Rest oder eine Kopie.
+    """
+    for rel, quelle in (verbindungen or {}).items():
+        ziel = os.path.join(baum, *rel.replace("\\", "/").split("/"))
+        if os.path.lexists(ziel):
+            if _ist_verbindung(ziel):
+                continue
+            raise RuntimeError(f"{rel} besteht im Baum und ist keine Verbindung")
+        os.makedirs(os.path.dirname(ziel), exist_ok=True)
+        if os.name == "nt":
+            subprocess.run(["cmd", "/c", "mklink", "/J", ziel, os.path.abspath(quelle)],
+                           check=True, capture_output=True)
+        else:
+            os.symlink(os.path.abspath(quelle), ziel, target_is_directory=True)
+
+
+def herrichten(basis: str, baum: str, branch: str, soll: dict, remote: bool, ohne=(),
+               verbindungen=None, remote_hooks: str = "") -> None:
+    """Den Baum auf den Sollstand der Basis bringen - neu kopiert oder zurueckgesetzt.
+
+    Fehlt er, wird die Basis kopiert (mit .git und ignorierten Dateien). Besteht er, setzt
+    git die versionierten Dateien zurueck, und was die Basis ignoriert fuehrt, wird aus ihr
+    zurueckkopiert; jede Datei, die die Basis nicht kennt, faellt weg. Danach steht HEAD auf
+    dem gesagten Branch - bei einem Arbeitsbranch frisch vom Sollcommit (K-172).
+    """
+    if not os.path.exists(baum):
+        shutil.copytree(basis, baum, symlinks=True,
+                        ignore=shutil.ignore_patterns(*ohne) if ohne else None)
+    else:
+        git(baum, "checkout", "-q", "-f", soll["branch"])
+        git(baum, "reset", "-q", "--hard", soll["commit"])
+        soll_dateien = set(dateien(basis, ohne))
+        for rel in dateien(baum, ohne):
+            if rel not in soll_dateien:
+                os.remove(os.path.join(baum, *rel.split("/")))
+        for rel in soll_dateien:
+            quelle = os.path.join(basis, *rel.split("/"))
+            ziel = os.path.join(baum, *rel.split("/"))
+            if not os.path.exists(ziel) or open(quelle, "rb").read() != open(ziel, "rb").read():
+                os.makedirs(os.path.dirname(ziel), exist_ok=True)
+                shutil.copy2(quelle, ziel)
+        # leere Verzeichnisse, die ein Lauf angelegt hat
+        for wurzel, verz, files in os.walk(baum, topdown=False):
+            if ".git" in wurzel.split(os.sep) or any(a in wurzel.split(os.sep) for a in ohne):
+                continue
+            if wurzel != baum and not os.listdir(wurzel) and not os.path.isdir(
+                    os.path.join(basis, os.path.relpath(wurzel, baum))):
+                os.rmdir(wurzel)
+    if branch != soll["branch"]:
+        git(baum, "checkout", "-q", "-B", branch, soll["commit"])
+    verbinden(baum, verbindungen)
+    if remote:
+        _remote_neu(baum, basis, remote_hooks)