lib.sh

#!/usr/bin/env bash
# Bahn: bash | Gegenstueck: lib.psm1
# team/lib.sh — gemeinsame Bibliothek der T.E.A.M.-Rollen (siehe CLAUDE.md, Anhang A).
# Wird per `source` eingebunden, nicht direkt ausgeführt.

# --- Projekt-Konfiguration (T.E.A.M.-Starterkit) ------------------------------
# Alle projektspezifischen Werte stehen in team.config.sh. Sie wird ZUERST
# gesourct, damit die ${VAR:-default}-Zuweisungen unten sie stehen lassen.
# Fehlt die Datei, laufen die Rollen mit den Defaults dieser Bibliothek weiter —
# so bricht ein Lauf nie an einer fehlenden Konfigdatei ab (gleiche Logik wie
# der Pflicht-Fallback in team_briefing).
# lib.sh liegt in team/, team.config.sh eine Ebene darüber in der Repo-Wurzel.
if [ -f "$(dirname "${BASH_SOURCE[0]}")/../team.config.sh" ]; then
    # shellcheck source=../team.config.sh disable=SC1091
    source "$(dirname "${BASH_SOURCE[0]}")/../team.config.sh"
else
    echo "[team-lib] WARNUNG: team.config.sh fehlt — Bibliotheks-Defaults aktiv." >&2
fi

# --- Ein Platzhalter ist kein Befehl (BL-149) ---------------------------------
# Jede Weiche unterhalb unterscheidet "konfiguriert" von "nicht konfiguriert"
# ueber leer/nicht-leer. Das ist richtig — nur ist "noch nicht ausgefuellt" im
# Kit jahrelang als TODO-SATZ geschrieben worden, und der ist nicht leer.
#
# Im Feld traf das jede erste Kaskade: Der Satz "TODO: noch keiner — Stufe 1
# der ersten Kaskade" stand als Vorbelegung in team.config.sh, galt damit als
# Befehl, landete im Prompt jeder bauenden Rolle ("Smoke-Test ausfuehren:
# TODO: …"), in der Werkzeug-Allowlist des Red Teams (Bash(TODO …)) und wurde
# von team_quittung_selbstpruefung WOERTLICH ausgefuehrt — Exit 127, Meldung
# "ist ROT". Der vierte Ausgang aus BL-41 konnte in Stufe 1 damit nie
# automatisch quittieren, obwohl genau diese Stufe die Aufgabe hat, den
# Smoke-Test ueberhaupt erst zu bauen.
#
# Die Vorbelegung ist weg (der Installer fuellt team.config.* jetzt LEER). Diese
# Weiche steht trotzdem hier, und zwar aus zwei Gruenden: Ein Mensch traegt in
# eine leere Zeile gern selbst ein "TODO" ein, und ein Platzhalter dieser Sorte
# wird im Kit erfahrungsgemaess an anderer Stelle wieder eingefuehrt. Sie
# normalisiert EINMAL, oben, statt an drei Verbrauchsstellen einzeln.
#
# Bewusst nur der Praefix und bewusst gross geschrieben: "TODO" am Anfang ist
# im ganzen Kit die Marke fuer "noch nicht ausgefuellt". Ein echter Pruefbefehl
# faengt nicht so an; ein Skript namens ./todo.sh bleibt unangetastet.
case "${TEAM_SMOKE_TEST:-}" in
    TODO*) TEAM_SMOKE_TEST="" ;;
esac

# --- Wie lange der Verifikationsbefehl im Vordergrund laufen darf (BL-207) ----
# Die Auflage "im Vordergrund, nie als Hintergrund-Task" (unten) ist richtig,
# war aber NICHT ERFUELLBAR, sobald die Suite laenger lief als die
# Vordergrundgrenze des Agenten-Werkzeugs (120 s Default). Feld B, 2026-08-28:
# Suite 149-220 s, in EINEM Lauf dreimal in den vierten Ausgang gelaufen
# (Ralph einmal, Frank zweimal), zusammen 4,9480 USD = 32 % der Rollenkosten.
# Die Rolle stand vor der Wahl zwischen Regelverletzung und Werkzeug-Timeout
# und waehlte in drei von drei Faellen dieselbe Verletzung.
#
# BL-201 hatte dieselbe Bauform zweimal mit einer SCHAERFEREN Auflage
# beantwortet. Das hier ist der Beleg, dass Schaerfe nicht hilft: Es ist kein
# Disziplinproblem. Eine Auflage, die die Rolle nicht einhalten KANN, erzeugt
# genau das Verhalten, das sie verbieten soll. Deshalb bekommt die Auflage eine
# Zahl, die die Rolle im Werkzeug einstellen kann — und die Zahl steht im
# Prompt, nicht nur in der Konfiguration.
#
# Default 600 s: grosszuegig gegenueber der 120-s-Wand des Werkzeugs und immer
# noch eine Grenze. Wer laenger braucht, traegt es in team.config.sh ein.
TEAM_SMOKE_TEST_TIMEOUT="${TEAM_SMOKE_TEST_TIMEOUT:-600}"
# BL-232 (2): Der schnelle STUFEN-Befehl. Leer = die Stufen verifizieren mit
# TEAM_SMOKE_TEST selbst (wie bisher). Gesetzt = je Stufe dieser Befehl, und
# die Vollautomatik faehrt den vollen Smoke-Test verbindlich am Phasenende.
TEAM_SMOKE_TEST_SCHNELL="${TEAM_SMOKE_TEST_SCHNELL:-}"
# BL-300: Die Zielstand-Pruefung (siehe team.config.sh). Leer = aus.
TEAM_ZIELSTAND_PRUEFUNG="${TEAM_ZIELSTAND_PRUEFUNG:-}"
# BL-325: Wo das laufende Programm seine Belege schreibt (siehe team.config.sh).
# Leer = aus.
TEAM_LAUFZEIT_BELEG="${TEAM_LAUFZEIT_BELEG:-}"

# --- Der Suitenstand ueberlebt die Rolle, die ihn gemessen hat (BL-256) -------
# WARUM ES DIESE DATEI GIBT. Im Feld aktivierte ein KORREKTER Frank-Fix einen
# latenten Defekt in einem aelteren Waechter. Frank trug den Beifang als
# eigenen Fund ein und belegte regelkonform, dass SEIN Fix keinen NEUEN
# Fehlschlag erzeugt (BL-205). Der Fund bekam Status `offen`; die Fixphase
# fragt nach `an Frank uebergeben` und meldete folgerichtig *nichts zu tun*.
# Der Abschlussbericht meldete den Lauf als fertig, waehrend der Baum seit
# einer Stunde rot war.
#
# JEDE ROLLE HAT SICH REGELKONFORM VERHALTEN. Strukturell fehlte ein ORT: Jede
# Rolle misst den Suitenstand einzeln und keine gibt ihn weiter - und was
# nirgends steht, kann keine Zusammenfassung lesen. Die Regel *ein Fix
# scheitert nicht an fremdem Flackern* bleibt unangetastet; was hier entsteht,
# ist ihre GEGENRICHTUNG: Der Lauf darf weiterlaufen, aber er darf sich nicht
# als fertig melden.
#
# WARUM DIE FUND-EBENE NICHT REICHT: Ein rotes Gate kann ohne Fundeintrag
# entstehen, und ein offener Fund heisst umgekehrt nicht, dass die Suite rot
# ist. Der Suitenstand gehoert an den Suitenstand gebunden.
#
# STEHT HIER und nicht bei den Funktionen weiter unten: Der Prompt-Baustein
# gleich darunter NENNT die Datei. Auf der bash-Bahn faellt eine spaetere
# Definition unter `set -u` sofort auf; auf der pwsh-Bahn waere sie still zu
# einem Leerstring geworden - eine Auflage ohne Ziel.
TEAM_GATE_DATEI="${TEAM_GATE_DATEI:-.team-gate-rot}"

# --- Abgeleitete Prompt-Bausteine (Starterkit) --------------------------------
# Smoke-Test-Zeile für die bauenden Rollen. Ist kein Befehl konfiguriert, wird
# der Schritt AUSDRÜCKLICH als offener Punkt benannt, statt still zu
# verschwinden — sonst merkt niemand, dass das Sicherheitsnetz fehlt.
#
# BL-283: Eine FUNKTION statt eines Blocks beim Laden. Die erste Kaskade eines
# Projekts baut den Smoke-Test in Stufe 1 und traegt ihn in team.config.sh
# ein — Ralph laedt die Bibliothek aber EINMAL und faehrt dann alle Stufen.
# Die Stufen 2…N bauten deshalb mit "Kein Smoke-Test konfiguriert", und die
# BL-41-Selbstpruefung hielt an statt zu quittieren. team_smoke_auffrischen
# (unten) liest den Wert je Stufe nach und baut die Zeilen dann neu.
team_smoke_bausteine() {
if [ -n "${TEAM_SMOKE_TEST:-}" ]; then
    # BL-232 (2): Zweistufige Verifikation als Kit-Begriff. Ist ein schneller
    # Stufen-Befehl konfiguriert, verifizieren die Rollen JE STUFE mit ihm, und
    # die Vollautomatik faehrt den vollen Smoke-Test verbindlich am Phasenende.
    # Bis hierher erfand das jedes Projekt selbst und schwaechte dabei
    # unbemerkt die Stufenverifikation, weil keine Regel sagte, wann der volle
    # Lauf faellig ist.
    local stufe="${TEAM_SMOKE_TEST_SCHNELL:-$TEAM_SMOKE_TEST}"
    local stufe_hinweis=""
    [ -n "${TEAM_SMOKE_TEST_SCHNELL:-}" ] && stufe_hinweis=" (die schnelle Stufen-Fassung; den vollen Smoke-Test ${TEAM_SMOKE_TEST} fährt die Vollautomatik am Phasenende, Kit-BL-232)"
    # BL-273/BL-281: Die Frist des Werkzeugs ist eine OBERGRENZE — darueber
    # schiebt es den Befehl selbst in den Hintergrund. Der Ausweg wird
    # mitgeliefert statt jedem Feld ueberlassen, samt der Falle eine Ebene
    # hoeher (die Warteschleife selbst im Hintergrund).
    # Der Interpreter wie beim Kosten-Werkzeug — beide Bahnen nennen damit
    # dieselbe Zeile (BL-117), und unter Windows ist ein blankes python3 der
    # Store-Alias (BL-130).
    local py="${TEAM_PYTHON:-${TEAM_KOSTEN_TOOL%% *}}"
    [ -n "$py" ] || py=python3
    local zwei_schritte="Reicht die Höchstfrist deines Werkzeugs nicht (oft 600000 Millisekunden), gilt der Zwei-Schritt-Weg (Kit-BL-273): '${py} team/tools/smoke_warten.py start --befehl \"${stufe}\"' startet den Testlauf im Hintergrund; danach rufst du '${py} team/tools/smoke_warten.py warten' IM VORDERGRUND auf, so oft, bis es nicht mehr mit 75 endet — sein Exit-Code ist der des Smoke-Tests. Nur der Testlauf gehört in den Hintergrund: 'Ich warte, bis sich der Warteruf meldet' ist derselbe Fehler eine Ebene höher (Kit-BL-281). Den Warteruf startest du NIE mit run_in_background oder einer anderen Hintergrund-Option deines Werkzeugs — er kehrt nach höchstens 540 Sekunden von selbst zurück (Kit-BL-315)."
    # Der Nachsatz ist eine Notbremse gegen einen teuren Fehlermodus, nicht
    # Ausschmückung (BL-41, Feld A K27/K28): Eine bauende Rolle
    # startete den Smoke-Test als HINTERGRUND-Task und wartete danach auf eine
    # Benachrichtigung, die in einer headless-Sitzung nie eintrifft. Der Lauf
    # endet mit subtype=success und is_error=false — er SIEHT AUS WIE EIN
    # ERFOLG —, gibt aber kein Promise und committet nicht. Dreimal passiert,
    # zusammen 13,25 USD, jedes Mal für Arbeit, die bereits fertig und grün
    # war. Der Satz steht hier statt in den Rollen-Briefings, weil er hier
    # JEDE bauende Rolle trifft statt nur eine. Die Begründung gehört in den
    # Prompt, damit die Regel nicht als willkürlich gelesen wird.
    SMOKE_ZEILE="Smoke-Test ausführen: ${stufe}${stufe_hinweis} — muss grün sein.
   Führe ihn im VORDERGRUND aus und warte auf seine Ausgabe. Starte ihn
   NIEMALS als Hintergrund-Task oder Monitor und plane keinen Wakeup darauf:
   Diese Sitzung ist headless, es kommt keine Benachrichtigung, und du wartest
   bis zum Zeitlimit auf ein Ereignis, das nicht eintreten kann (Kit-BL-265).
   Er darf dafür bis zu ${TEAM_SMOKE_TEST_TIMEOUT} Sekunden brauchen: Erhöhe das
   Zeitlimit deines Werkzeugs entsprechend, soweit es das zulässt,
   statt in den Hintergrund auszuweichen — viele Werkzeuge erwarten MILLISEKUNDEN, das
   wären ${TEAM_SMOKE_TEST_TIMEOUT}000 (Kit-BL-258). ${zwei_schritte}
   Läuft er länger als diese Frist, ist das ein Befund für den Menschen —
   melde ihn, weiche nicht aus.
   War der Baum schon VOR deiner Arbeit rot, hänge eine Zeile
   '<ISO-Zeit> | <deine Rolle> | <Namen der roten Tests>' an
   ${TEAM_GATE_DATEI} an (Kit-BL-256). Dein Auftrag scheitert daran NICHT — aber
   ohne diese Zeile meldet sich der Lauf am Ende als fertig, während das Gate
   aus ist. Ist der Baum am Ende grün, lösche die Datei wieder."
    # BL-207: Frank bekommt NUR diesen Nachsatz, nicht SMOKE_ZEILE — und er
    # faehrt den Smoke-Test oefter als Ralph. Im Feld endeten 10 von 28
    # Frank-Laeufen ohne Promise, bei 9 davon stand das Warten auf einen
    # Hintergrundlauf woertlich im Log-Feld `result` (10,7249 USD an EINEM
    # Tag). Bei ihm kostet der vierte Ausgang zusaetzlich einen
    # Fehlversuch (.frank-attempts) und eskaliert ab dem dritten an Axel —
    # das teure Modell wird also fuer einen Formfehler gerufen. Deshalb
    # steht die Auflage hier ausgeschrieben statt nur bei Ralph.
    SMOKE_SUFFIX=" Smoke-Test grün: ${stufe}${stufe_hinweis}. Führe ihn im VORDERGRUND aus und warte auf seine Ausgabe — er darf bis zu ${TEAM_SMOKE_TEST_TIMEOUT} Sekunden brauchen, erhöhe das Zeitlimit deines Werkzeugs entsprechend, soweit es das zulässt (viele Werkzeuge erwarten MILLISEKUNDEN — das wären ${TEAM_SMOKE_TEST_TIMEOUT}000, Kit-BL-258). ${zwei_schritte} NIEMALS als Hintergrund-Task, als Monitor oder mit einem Wakeup darauf (Kit-BL-265): Diese Sitzung ist headless, es kommt keine Benachrichtigung, und der Lauf endet als Erfolg ohne Quittung (Kit-BL-41). War die Suite schon VOR deinem Fix rot, brich nicht ab: Miss beide Staende und belege, dass durch DEINEN Fix kein NEUER Fehlschlag entsteht (Kit-BL-205) — und haenge die Zeile '<ISO-Zeit> | frank | <Namen der roten Tests>' an ${TEAM_GATE_DATEI} an, sonst meldet sich der Lauf am Ende als fertig, waehrend das Gate aus ist (Kit-BL-256). Ist der Baum am Ende gruen, loesche die Datei wieder."
else
    SMOKE_ZEILE="(Kein Smoke-Test konfiguriert — Schritt entfällt. Das Team arbeitet ohne Sicherheitsnetz; TEAM_SMOKE_TEST in team.config.sh nachtragen.)"
    SMOKE_SUFFIX=""
fi
# BL-300: Das Gepruefte muss das Gebaute sein. Die Regel haengt an der
# Handlung (nach dem Bauen), nicht an einer Erinnerung — ein Merksatz "vor
# jeder Handpruefung aufrufen" hat im Feld genau einmal gegriffen, naemlich
# als er neu war.
if [ -n "${TEAM_ZIELSTAND_PRUEFUNG:-}" ]; then
    local zielstand="Zielstand-Prüfung nach jeder Änderung an baubarem Code: ${TEAM_ZIELSTAND_PRUEFUNG} — sie prüft, ob das, woran geprüft wird (Gerät, Emulator, installierte Fassung), der Stand ist, den du eben gebaut hast. Rot heißt: Das Geprüfte ist nicht das Gebaute — bring den Stand aufs Ziel und prüfe erneut (Kit-BL-300)."
    SMOKE_ZEILE="${SMOKE_ZEILE}
   ${zielstand}"
    SMOKE_SUFFIX="${SMOKE_SUFFIX} ${zielstand}"
fi
# BL-325: Was ein Programm erst im LAUF zeigt, belegt das Log, nicht der
# Bildschirm. Wunsch des Owners: Der Mensch beobachtet und beraet, er liest
# keine Werte ab. Die bauenden Rollen bekommen die Auflage zur Laufzeit, wie
# die Zielstand-Pruefung — ihre Briefings liegen am 45-Zeilen-Limit.
if [ -n "${TEAM_LAUFZEIT_BELEG:-}" ]; then
    local laufzeit="Laufzeit-Belege (Kit-BL-325): Was dieses Programm tut, zeigt sich erst im Lauf; seine Belege stehen in: ${TEAM_LAUFZEIT_BELEG}. Baust oder fixt du Laufzeitverhalten, schreib an jedem Entscheidungspunkt eine kurze Logzeile mit festem Präfix und wenigen Werten und liefere die Auswerteregel mit, die sie liest — geprüft an einer Testdatei im ECHTEN Logformat und mit einer Mutation, die sie rot macht. Ein Fix an Laufzeitverhalten bringt die Logzeile mit, an der der nächste Lauf ihn belegt. Was nur ein Mensch sehen kann (Look and Feel), meldest du als Frage an ihn, nicht als erledigt."
    SMOKE_ZEILE="${SMOKE_ZEILE}
   ${laufzeit}"
    SMOKE_SUFFIX="${SMOKE_SUFFIX} ${laufzeit}"
fi
}
team_smoke_bausteine

# team_smoke_auffrischen: Ist (noch) kein Smoke-Test bekannt, liest es
# TEAM_SMOKE_TEST frisch aus team.config.sh — in einer Subshell, damit kein
# anderer Wert dieses Laufs angefasst wird — und baut die Zeilen neu, sobald
# einer eingetragen ist (BL-283). Ein schon bekannter Wert bleibt: Ihn hat die
# Umgebung oder die Konfiguration beim Start gesetzt, und ein Lauf wechselt
# ein laufendes Sicherheitsnetz nicht still aus.
team_smoke_auffrischen() {
    [ -n "${TEAM_SMOKE_TEST:-}" ] && return 0
    local konf neu
    konf="$(dirname "${BASH_SOURCE[0]}")/../team.config.sh"
    [ -f "$konf" ] || return 0
    neu="$( unset TEAM_SMOKE_TEST; source "$konf" >/dev/null 2>&1; printf '%s' "${TEAM_SMOKE_TEST:-}" )"
    [ -n "$neu" ] || return 0
    TEAM_SMOKE_TEST="$neu"
    team_smoke_bausteine
    echo "[team-lib] Smoke-Test seit dieser Stufe konfiguriert: $neu — die folgenden Stufen bauen mit ihm (Kit-BL-283)." >&2
    return 0
}

# --- Bedienung: Hilfe und Zurueckweisung (BL-223) -----------------------------
# Warum das in der Bibliothek steht und nicht siebenmal daneben: Eine
# Konvention, die nur dasteht, wird an der Haelfte der Stellen nicht befolgt —
# und genau so ist BL-223 entstanden. Von vierzehn Einstiegspunkten hatten
# DREI eine Hilfe, und die Rollen-Skripte lasen ihre Argumente ueberhaupt
# nicht: `./ralph.sh --hilfe` zeigte keine Hilfe, wies nichts zurueck und
# startete einen bezahlten Rollenlauf. Das ist BL-222 eine Stufe teurer — dort
# war die Folge eine falsche Statusausgabe, hier ein Modellaufruf, den niemand
# bestellt hat.

# team_hilfe_kopf [datei]: der DATEIKOPF ist der Hilfetext, keine zweite
# Fassung daneben (dieselbe Bauart wie `install.sh --hilfe`, BL-154/BL-156) —
# eine Abschrift laeuft irgendwann auseinander, und dann sagt --hilfe etwas
# anderes als die Datei. Gelesen wird ab Zeile 3 (1 = Shebang, 2 =
# Bahn-Kopfzeile, beides Maschinensache) bis zur ersten Zeile, die kein
# Kommentar mehr ist. Waechst der Kopf, waechst die Hilfe mit.
#
# Default ist der BASENAME: Jeder Entrypoint wechselt vorher in sein eigenes
# Verzeichnis, ein relativer Pfad zeigt danach ins Leere.
team_hilfe_kopf() {
    local datei="${1:-$0}"
    [ -f "$datei" ] || datei="$(basename "$datei")"
    sed -n '3,${
        /^#/!q
        s/^# \{0,1\}//
        p
    }' "$datei"
}

# team_argumente_pruefen "$@": fuer Skripte, die KEINE Argumente kennen.
# --hilfe/--help/-h druckt den Kopf und endet mit 0; jedes andere Argument
# endet mit 2 auf stderr. Der argumentlose Aufruf laeuft unveraendert durch.
#
# Der EXIT-CODE ist die Zusicherung, nicht der Text: Er ist das, was ein
# aufrufendes Skript auswerten kann (dieselbe Trennung wie bei den
# Buchungsverben aus BL-222).
team_argumente_pruefen() {
    case "${1:-}" in
        "") return 0 ;;
        --hilfe|--help|-h) team_hilfe_kopf; exit 0 ;;
        *) echo "$(basename "$0"): unbekanntes Argument '$1' — dieses Skript nimmt keine Argumente. '--hilfe' zeigt den Dateikopf." >&2
           exit 2 ;;
    esac
}

# team_hilfe_wenn_gefragt "$@": fuer Skripte, die ihre uebrigen Argumente
# WEITERREICHEN (team-test.sh und kit-test.sh reichen an pytest durch). Hier
# darf nichts zurueckgewiesen werden — sonst faengt der Riegel genau die
# Argumente, wegen derer es die Durchreiche gibt. Abgefangen wird deshalb nur
# `--hilfe`: die deutsche Schreibweise, die pytest nicht kennt. `--help`/`-h`
# gehen bewusst weiter an pytest, das dafuer eine eigene, bessere Hilfe hat.
team_hilfe_wenn_gefragt() {
    [ "${1:-}" = "--hilfe" ] || return 0
    team_hilfe_kopf
    exit 0
}

# team_allowed_tools <redteam|axel>: Werkzeug-Allowlist für Guard-Linie 2.
# Axel bekommt NUR den Plan-Ordner, das Red Team zusätzlich den Test-Ordner.
#
# BL-292: Jede Schreibregel steht zusaetzlich ABSOLUT da. Die CLI loest eine
# relative Regel (`Edit(plans/**)`) gegen das AKTUELLE Arbeitsverzeichnis der
# Shell auf — nach einem erlaubten `cd <Unterordner>` lehnte sie im Feld jeden
# Schreibversuch nach plans/ und tests/ ab, und vier Funde standen nur noch im
# `result`. Die absolute Form `//<pfad>/<ordner>/**` haengt nicht am `cd`
# (unter Git Bash ist `pwd` schon `/c/Users/...`, die Form, die im Feld trug).
# Ein Leerzeichen im Projektpfad zerlegte die leerzeichengetrennte Liste —
# dann bleibt es bei der relativen Form, mit einer Meldung statt still.
team_schreibregeln() {
    local ordner="${1%/}" wurzel="$2"
    printf 'Edit(%s/**) Write(%s/**)' "$ordner" "$ordner"
    [ -n "$wurzel" ] && printf ' Edit(//%s/%s/**) Write(//%s/%s/**)' \
        "$wurzel" "$ordner" "$wurzel" "$ordner"
    return 0
}

team_allowed_tools() {
    local -a befehle=("${TEAM_BEUTEBUCH_TOOL}:*" "git log:*" "git diff:*" "git show:*")
    [ -n "${TEAM_SMOKE_TEST:-}" ] && befehle+=("${TEAM_SMOKE_TEST}")
    # BL-232/BL-273: der schnelle Stufen-Befehl und der Zwei-Schritt-Weg —
    # eine Read-Only-Rolle, die den Weg aus ihrem Auftrag nicht gehen darf,
    # haette nur die Wahl zwischen Fristriss und Hintergrund.
    [ -n "${TEAM_SMOKE_TEST_SCHNELL:-}" ] && befehle+=("${TEAM_SMOKE_TEST_SCHNELL}")
    if [ -n "${TEAM_SMOKE_TEST:-}" ]; then
        local py="${TEAM_PYTHON:-${TEAM_KOSTEN_TOOL%% *}}"
        befehle+=("${py:-python3} team/tools/smoke_warten.py:*")
    fi
    # BL-319: Jede Freigabe gilt fuer BEIDE Shell-Werkzeuge der CLI. Unter
    # Windows liegt einer Rolle das PowerShell-Werkzeug naeher als Bash, und
    # eine Bash-Regel deckt es nicht: Im Feld startete Marv den Smoke-Test
    # woertlich, aber in PowerShell — abgelehnt, und in keinem Sweep des Laufs
    # lief er. Wo es das Werkzeug nicht gibt, ist die Regel wirkungslos.
    local basis="Read Grep Glob" b
    for b in "${befehle[@]}"; do basis="$basis Bash($b)"; done
    for b in "${befehle[@]}"; do basis="$basis PowerShell($b)"; done
    # Unter Git Bash ist `pwd` nicht immer `/c/...`: Gemountete Ordner heissen
    # `/tmp/...` — und `//tmp/...` versteht die native CLI nicht. `pwd -W`
    # liefert dort den Windows-Pfad (`C:/...`); unter Linux gibt es -W nicht.
    local wurzel; wurzel="$(pwd -W 2>/dev/null || pwd)"
    case "$wurzel" in
        [A-Za-z]:/*) wurzel="$(printf '%s' "${wurzel%%:*}" | tr 'A-Z' 'a-z')/${wurzel#?:/}" ;;
        *) wurzel="${wurzel#/}" ;;
    esac
    wurzel="${wurzel%/}"
    case "$wurzel" in
        *" "*) echo "[team-lib] WARNUNG: Der Projektpfad enthält ein Leerzeichen — die Schreibregeln gelten nur relativ. Wechselt eine Rolle mit cd in einen Unterordner, lehnt die CLI ihre Schreibversuche ab (Kit-BL-292)." >&2
               wurzel="" ;;
    esac
    local plan; plan="$(team_schreibregeln "$TEAM_PLAN_ORDNER" "$wurzel")"
    case "$1" in
        axel) echo "$basis $plan" ;;
        *)    echo "$basis $plan $(team_schreibregeln "$TEAM_TEST_ORDNER" "$wurzel")" ;;
    esac
}

# --- Modelle -----------------------------------------------------------------
# Loop-Rollen (Ralph, Harry, Marv, Frank): günstiges Modell.
# Axel & Der Architekt: starkes Modell, immer API.
TEAM_MODEL_LOOP="${TEAM_MODEL_LOOP:-sonnet}"
TEAM_MODEL_STRONG="${TEAM_MODEL_STRONG:-opus}"

# --- Budget pro Rolle (Zwei-Schwellen-Modell) --------------------------------
# Stakeholder-Entscheid 2026-07-12 (realer Auslöser HM-32): Ein zu tiefes
# Pro-Rolle-Budget ist ökonomisch absurd — der alte 1-USD-Frank-Cap griff ERST
# NACH dem (bereits bezahlten) Claude-Aufruf und warf über den Rollback die
# schon bezahlte Arbeit weg, der nächste Versuch kostete erneut: der Cap
# "sparte" nichts, er vervielfachte die Kosten und blockierte obendrein den Fund.
#
# Neues Modell — EINE zentrale Basiszahl statt drei divergierender Defaults:
#   TEAM_ROLE_BUDGET_USD   (Default 20) — Soft-Cap, gilt für ALLE Rollen.
#   TEAM_ROLE_HARDCAP_USD  (Default 40) — Hard-Cap für die iterierenden
#                          "Sorgenkinder" Frank & Axel (2× Soft).
#   BL-286: bis hierher 5/10 — angehoben auf Entscheid des Owners. Zu tiefe
#   Caps werfen bezahlte Arbeit weg (HM-32), und die Rollen wurden teurer.
#
# Zwei Schwellen (siehe team_budget_check):
#   - Frank & Axel: SOFT-Cap = nur deutlicher Hinweis, KEIN Rollback, der Fix
#     bleibt gültig und wird normal geprüft; erst der HARD-Cap (Ausreißer:
#     Endlosschleife/kaputter Prompt) bricht mit Rollback+Cleanup ab.
#   - Ralph/Harry/Marv: sofortiger HART-Cap beim Soft-Wert (kein Soft-Fenster) —
#     Ralph hat nach dem Commit ohnehin Feierabend (kein Rollback, Mensch
#     schaltet weiter), Harry/Marv sind read-only (nichts Bezahltes geht verloren).
# BL-131: Wie der Python-Interpreter heisst, ist eine Eigenschaft der
# MASCHINE, nicht der Bahn. Bis hierher stand `python3` dreizehnmal fest im
# Text — mit der Begruendung, diese Bahn laufe unter Linux. Unter Git-Bash auf
# Windows laeuft sie das nicht, und dort ist `python3` der App-Execution-Alias
# aus dem Microsoft Store: Er startet den Store, schreibt "Python was not
# found" und endet mit 49. Jeder dieser dreizehn Aufrufe war damit tot.
# Die pwsh-Bahn hatte das Problem nie — sie hat dieselben dreizehn Bloecke
# durch native Ausdruecke ersetzt. Der Default hier bleibt `python3`, weil er
# unter POSIX richtig ist; der Installer traegt in team.config.sh ein, was er
# auf der Maschine wirklich gefunden hat.
TEAM_PYTHON="${TEAM_PYTHON:-python3}"
TEAM_ROLE_BUDGET_USD="${TEAM_ROLE_BUDGET_USD:-20}"
TEAM_ROLE_HARDCAP_USD="${TEAM_ROLE_HARDCAP_USD:-40}"
# BL-297: team_budget_check prueft den Hard-Cap nur, wenn er UEBER dem
# Soft-Cap liegt. Hebt ein Projekt nur den Soft-Cap (der dokumentierte Weg),
# greift Franks und Axels harter Abbruch nie mehr — und nichts sagte es. Im
# Feld fiel es nur auf, weil vorher jemand in den Quelltext sah.
if awk -v s="$TEAM_ROLE_BUDGET_USD" -v h="$TEAM_ROLE_HARDCAP_USD" \
       'BEGIN { exit !(h + 0 <= s + 0) }' 2>/dev/null; then
    echo "[team-lib] WARNUNG: TEAM_ROLE_HARDCAP_USD ($TEAM_ROLE_HARDCAP_USD) liegt nicht über TEAM_ROLE_BUDGET_USD ($TEAM_ROLE_BUDGET_USD) — Frank und Axel haben damit KEINEN harten Abbruch mehr (Kit-BL-297). Wer den Soft-Cap hebt, hebt den Hard-Cap mit." >&2
fi

# --- Auth-Modus --------------------------------------------------------------
# team_resolve_auth_mode [rollen-default]
#
# Auflösung (Prio absteigend):
#   1. Env AUTH_MODE            — explizite Übersteuerung pro Aufruf
#   2. ~/.config/claude-team/auth-mode  — maschinenlokaler Default
#   3. Rollen-Default ($1)      — Loop-Rollen übergeben "abo",
#                                 starke Rollen (Axel/Architekt) nichts → "api"
#
# "abo" = Claude-Abo via `claude login`. Der API-Key wird aus der Umgebung
#         entfernt, damit die CLI sicher über das Abo abrechnet.
# "api" = Pay-per-Use. Key-Quelle: Env ANTHROPIC_API_KEY, sonst
#         ~/.config/claude-team/api-key (eine Zeile, chmod 600).
#         Der Key gehört bewusst NICHT in .bashrc — sonst greifen ihn auch
#         interaktive Abo-Sessions auf.
# team_auth_mode_effektiv [rollen-default] — löst NUR den Modus auf
# (Env AUTH_MODE → ~/.config/claude-team/auth-mode → Rollen-Default) und gibt ihn
# auf stdout aus. KEINE Seiteneffekte (kein unset, kein Key-Laden). Erlaubt
# Orchestratoren (vollautomatik.sh/halbautomatik.sh), den effektiven Modus zu
# prüfen, ohne die Prozess-Umgebung anzufassen.
team_auth_mode_effektiv() {
    local rollen_default="${1:-api}"
    local cfg="$HOME/.config/claude-team/auth-mode"
    if [ -n "${AUTH_MODE:-}" ]; then
        printf '%s\n' "$AUTH_MODE"
    elif [ -f "$cfg" ]; then
        head -n1 "$cfg" | tr -d '[:space:]'
    else
        printf '%s\n' "$rollen_default"
    fi
}

# team_warnung_abo_key — warnt EINMAL pro Prozessbaum, wenn im Abo-Modus ein
# ANTHROPIC_API_KEY in der Umgebung liegt (das Abo-first-Design still aushebelt).
# Idempotent: setzt beim ersten Auslösen TEAM_ABO_KEY_WARNUNG_GEZEIGT=1
# (exportiert), sodass alle NACHKOMMEN-Prozesse schweigen. Damit „einmal pro
# Prozessbaum" auch über die SIBLING-Rollenprozesse von vollautomatik.sh/
# halbautomatik.sh hält (HM-32), seeden die Orchestratoren diese Funktion selbst
# EINMAL im eigenen Prozess — analog team_lock/TEAM_LOCK_HELD.
team_warnung_abo_key() {
    if [ -n "${ANTHROPIC_API_KEY:-}" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG:-1}" != "0" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG_GEZEIGT:-0}" != "1" ] \
        && [ "${TEAM_KEY_AUS_FALLBACK:-0}" = "1" ]; then
        # BL-48 (Feld K29/136): Der Key stammt NICHT aus der Umgebung des
        # Menschen, sondern aus einem API-Fallback derselben Prozesskette —
        # team_resolve_auth_mode hat ihn selbst exportiert und dort bleibt er
        # für die Folgestufe stehen. Die .bashrc-Empfehlung unten zeigt dann
        # auf eine Datei, in der nichts steht, und beschreibt eine Ursache, die
        # nicht vorlag; im Feld wurde real per /proc/<pid>/environ nachgesehen.
        # Deshalb: eigener Satz, der sagt was wirklich passiert ist — und
        # KEIN TEAM_ABO_KEY_WARNUNG_GEZEIGT. Das eine Warnfenster pro
        # Prozessbaum gehört dem echten Fall (Key aus .bashrc, ~13,8 USD
        # Leerlauf über API), nicht diesem Fehlalarm.
        echo "Hinweis: ANTHROPIC_API_KEY liegt in der Prozess-Umgebung, gesetzt vom API-Fallback" >&2
        echo "  eines vorigen Aufrufs (nicht aus .bashrc). Er wird für diesen Abo-Aufruf" >&2
        echo "  unmittelbar entfernt — kein Handlungsbedarf (Kit-BL-48)." >&2
        return 0
    fi
    if [ -n "${ANTHROPIC_API_KEY:-}" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG:-1}" != "0" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG_GEZEIGT:-0}" != "1" ]; then
        echo "WARNUNG: AUTH_MODE=abo, aber ANTHROPIC_API_KEY liegt in der Prozess-Umgebung —" >&2
        echo "  die Claude-CLI kann dann den (teuren) API-Weg dem Abo vorziehen." >&2
        echo "  Empfohlen: den Key aus .bashrc/der Shell-Env nehmen und stattdessen in" >&2
        echo "  ~/.config/claude-team/api-key (chmod 600) ablegen — siehe CLAUDE.md 'Auth-Modi'." >&2
        echo "  Selbstprüfen: echo \"\${ANTHROPIC_API_KEY:+gesetzt}\" (leer = ok)." >&2
        export TEAM_ABO_KEY_WARNUNG_GEZEIGT=1
    fi
}

# team_api_weg_vorhanden: Gibt es ueberhaupt einen API-Schluessel? (0 = ja)
#
# BL-174: Reine ABFRAGE, ohne etwas zu setzen und ohne zu meckern. Sie
# beantwortet die Frage, die team_claude vor dem Fallback stellen muss —
# `team_resolve_auth_mode` kann das nicht, weil sie im Fehlerfall MELDET und
# der Aufrufer ihren Rueckgabewert bisher als Abbruch gelesen hat.
#
# In einer reinen Abo-Installation ist ein fehlender Schluessel kein Fehler,
# sondern der ERWARTETE Zustand — seit dem Entscheid "keine Rolle ist fest
# api" ist das der empfohlene Normalfall.
# BL-173: WIE die Agenten-CLI heisst, entscheidet die Maschine — nicht diese
# Datei. Dieselbe Lehre wie TEAM_PYTHON (BL-131), und sie wiegt hier schwerer:
# Claude Code wird legitim IDE-GEBUENDELT ausgeliefert (VS Code / VSCodium,
# Binary unter resources/native-binary/claude). Eine Maschine kann eine
# vollstaendig eingerichtete, angemeldete Installation haben, ohne dass
# `claude` in irgendeinem PATH aufloesbar ist — genau die Lage lag im Feld vor:
# ~/.claude/.credentials.json vorhanden, Abo aktiv, Erweiterung lief, und
# `command -v claude` leer.
TEAM_CLAUDE_BIN="${TEAM_CLAUDE_BIN:-claude}"

# team_cli_vorhanden: Ist die Agenten-CLI ueberhaupt aufloesbar? (0 = ja)
#
# BL-173, die WICHTIGERE Haelfte. Ohne diese Pruefung war der Ablauf:
# `claude: command not found` (eine Zeile, scrollt vorbei) -> ein 0-Byte-Log
# -> team_bewerte_ergebnis schreibt einen ERSATZZETTEL fuer einen Aufruf, der
# nie stattgefunden hat -> der Abo-Fehler loest planmaessig den API-Fallback
# aus -> und der bricht mit der Meldung ab, die stehen bleibt und die der
# Mensch liest: "FEHLER: AUTH_MODE=api, aber weder ANTHROPIC_API_KEY gesetzt
# noch …/api-key lesbar."
#
# Diagnostiziert wird ein Auth-Problem; vorliegt ein PATH-Problem. Wer dieser
# Meldung folgt, besorgt einen API-Schluessel — und scheitert ein zweites Mal
# an derselben Stelle, weil auch der API-Weg dasselbe `claude` aufruft.
#
# Eine fehlende Programmdatei ist KEINE Fehlerklasse, die ein Auth-Fallback
# heilen kann. Dieselbe Erwaegung wie bei Exit 42/43: eine eigene Klasse, die
# man BENENNT, statt sie in eine bestehende zu pressen.
team_cli_vorhanden() {
    case "$TEAM_CLAUDE_BIN" in
        */*) [ -x "$TEAM_CLAUDE_BIN" ] && return 0 ;;
        *)   command -v "$TEAM_CLAUDE_BIN" >/dev/null 2>&1 && return 0 ;;
    esac
    return 1
}

team_cli_fehlt_melden() {
    local rolle="${1:-team}"
    echo "[$rolle] FEHLER: Die Agenten-CLI ist nicht auffindbar (gesucht: '$TEAM_CLAUDE_BIN')." >&2
    echo "  Das ist KEIN Auth-Problem — ein API-Schluessel hilft hier nicht." >&2
    echo "  Ist Claude Code als IDE-Erweiterung installiert, liegt die Binaerdatei" >&2
    echo "  meist unter <erweiterung>/resources/native-binary/claude und nicht im PATH." >&2
    echo "  Trag den vollen Pfad als TEAM_CLAUDE_BIN in team.config.sh ein." >&2
}

team_api_weg_vorhanden() {
    [ -n "${ANTHROPIC_API_KEY:-}" ] && return 0
    [ -r "$HOME/.config/claude-team/api-key" ] && return 0
    return 1
}

team_resolve_auth_mode() {
    local rollen_default="${1:-api}"
    local keyfile="$HOME/.config/claude-team/api-key"

    AUTH_MODE="$(team_auth_mode_effektiv "$rollen_default")"

    case "$AUTH_MODE" in
        api)
            if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
                if [ -r "$keyfile" ]; then
                    ANTHROPIC_API_KEY="$(head -n1 "$keyfile" | tr -d '[:space:]')"
                    export ANTHROPIC_API_KEY
                    # BL-48: Merken, dass DIESE Kette den Key gesetzt hat. Ein
                    # späterer Abo-Aufruf im selben Prozessbaum erbt ihn und
                    # bekäme sonst die .bashrc-Warnung für eine Ursache, die
                    # nie vorlag (siehe team_warnung_abo_key).
                    export TEAM_KEY_AUS_FALLBACK=1
                else
                    echo "FEHLER: AUTH_MODE=api, aber weder ANTHROPIC_API_KEY gesetzt noch $keyfile lesbar." >&2
                    return 1
                fi
            fi
            ;;
        abo)
            team_warnung_abo_key
            # Abo-Abrechnung erzwingen: API-Key aus der Umgebung nehmen.
            unset ANTHROPIC_API_KEY
            ;;
        *)
            echo "FEHLER: Unbekannter AUTH_MODE '$AUTH_MODE' (erlaubt: api|abo)." >&2
            return 1
            ;;
    esac
    echo "Auth-Modus: $AUTH_MODE"
}

# --- Zentraler Claude-Aufruf ---------------------------------------------------
# team_claude <rolle> <modell> <outfile> <prompt> [weitere claude-Flags …]
#
# Abo-first mit automatischem API-Fallback (Stakeholder-Entscheid 2026-07-10:
# gilt für ALLE Rollen, auch Axel): Auth wird pro Aufruf frisch aufgelöst;
# scheitert der Abo-Aufruf (Exit ≠ 0 oder is_error), folgt genau EIN API-Retry.
# Nach dem Aufruf stehen TEAM_LAST_COST (USD) und TEAM_LAST_OUT (Log-Datei).
# TEAM_LAST_COST ist die Summe ALLER Versuche dieses Aufrufs (gescheiterter
# Abo-Versuch + API-Fallback + 429-Retries), nicht nur des letzten — sonst waere
# der Pro-Stufe-Budget-Cap durch einen teuren Fehlversuch umgehbar (BL-55).
# TEAM_LAST_OUT bleibt das FINALE Log (Promise-Pruefung, HM-20).
#
# Session-Limit (429, Kaskade 9 / Stufe 30, Strategie A+B; API-Fallback-Reihenfolge
# per Stakeholder-Entscheid 2026-07-11 umgestellt, Commit f787936): Bei JEDEM
# Abo-Fehler — Timeout, normaler Fehler ODER 429/Session-Limit — versucht
# team_claude SOFORT den einmaligen API-Fallback (eigenes, separates Kontingent;
# hilft auch bei einem Abo-429). Erst wenn AUCH das finale (ggf. API-)Ergebnis
# noch ein 429 ist (team_result_is_429), greift die Warte-und-Wiederhol-Logik
# (A). Ist der Reset unbekannt, zu weit in der Zukunft, oder sind die Retries
# erschöpft, gibt team_claude ein eindeutiges Pausen-Signal zurück (B):
# Exit-Code 42, TEAM_LAST_PAUSE=1 und TEAM_LAST_RESET="HH:MM". Ein normaler
# (nicht-429) Fehler, der auch über API scheitert, endet mit Exit 1.
#
#   TEAM_429_MAX_RETRIES  Anzahl Warte-und-Wiederhol-Zyklen (Default 2).
#   TEAM_429_MAX_WARTEN   Harte Obergrenze der Wartezeit in Sekunden
#                         (Default 1800 = 30 Min); 0 schaltet A komplett ab
#                         (nur B, reiner Pausen-Exit).
#   TEAM_429_PUFFER       Sicherheitspuffer nach dem Reset-Zeitpunkt in
#                         Sekunden (Default 30).
#
# TEAM_DRY_RUN=1: kein echter Aufruf — schreibt ein Stub-JSON mit dem Inhalt
# von TEAM_DRY_RESULT (Default leer) für Mechanik-Tests der Pipeline.
TEAM_AUTH_USER="${AUTH_MODE:-}"
TEAM_429_MAX_RETRIES="${TEAM_429_MAX_RETRIES:-2}"
TEAM_429_MAX_WARTEN="${TEAM_429_MAX_WARTEN:-1800}"
TEAM_429_PUFFER="${TEAM_429_PUFFER:-30}"

# team_429_env_int <variablenname> <default>
# Erzwingt, dass die benannte TEAM_429_*-Variable eine reine, nicht-negative
# Ganzzahl ist, BEVOR sie in $(( … ))/[ … ] verwendet wird. Ein aus der
# Umgebung übernommener Wert wie "$(beliebiger Befehl)" würde in einer
# Bash-Arithmetik-Expansion sonst ausgeführt (Command-Injection, HM-17); ein
# nicht-numerischer Wert wie "abc" ließe `test` stillschweigend scheitern und
# den TEAM_429_MAX_WARTEN-Deckel fail-open statt fail-safe wirkungslos werden
# (ebenfalls HM-17). Bei ungültigem Wert: Fehlermeldung + Fallback auf Default.
team_429_env_int() {
    local name="$1" default="$2" wert
    eval "wert=\"\${$name}\""
    case "$wert" in
        ''|*[!0-9]*)
            echo "[team_claude] Ungültiger Wert für ${name}=\"${wert}\" (muss eine nicht-negative Ganzzahl sein) — falle auf Default ${default} zurück." >&2
            eval "$name=\"$default\""
            ;;
    esac
}
team_429_env_int TEAM_429_MAX_RETRIES 2
team_429_env_int TEAM_429_MAX_WARTEN 1800
team_429_env_int TEAM_429_PUFFER 30

# team_429_sleep <sekunden>
# Kapselt `sleep` fürs Warten auf einen Session-Limit-Reset. TEAM_DRY_RUN=1
# oder TEAM_429_SKIP_SLEEP=1 überspringen das echte Warten — so darf ein Test
# niemals real bis zu 30 Minuten blockieren (Verifikationspflicht Stufe 30).
team_429_sleep() {
    local sekunden="$1"
    if [ "${TEAM_DRY_RUN:-0}" = "1" ] || [ "${TEAM_429_SKIP_SLEEP:-0}" = "1" ]; then
        echo "[429] (Test) sleep ${sekunden}s übersprungen." >&2
        return 0
    fi
    sleep "$sekunden"
}

# team_versuch_sichern <rolle> <json-datei> <dauer-sekunden>
# BL-46 (Feld K29/135, 2026-08-10): Ein gescheiterter Abo-Anlauf hinterließ ein
# Log von 0 Byte — nach 47 Minuten Laufzeit. Eine Quittung über null ist von
# „hat nichts gekostet" nicht zu unterscheiden: `kosten.py summe` addierte
# stillschweigend 0.0000, der Pro-Stufe-Deckel bekam auf diese Hälfte keinen
# Griff, und die Stufe erschien in der Kostentabelle als die BILLIGSTE der
# Kaskade, obwohl sie als teuerste angesetzt war. Wer diese Tabelle später als
# Vergleichsband liest, schreibt eine Zahl fort, die eine halbe Stufe beschreibt.
#
# Deshalb: Ist das Versuchslog nicht als JSON lesbar, tritt an seine Stelle ein
# ERSATZZETTEL mit dem, was belegbar ist — Dauer und die ausdrückliche Aussage
# „Kosten unbekannt". NICHT geschätzt: Der Zettel behauptet keine Zahl, er macht
# die Lücke sichtbar. `is_error` bleibt gesetzt, damit der bestehende
# Fehlerpfad (API-Fallback) unverändert greift — vorher war die unlesbare Datei
# über team_result_is_error genau das, und das soll sie bleiben.
# Rückgabe 0, wenn ein Zettel geschrieben wurde (Aufrufer meldet es).
team_versuch_sichern() {
    local rolle="$1" out="$2" dauer="$3"
    "$TEAM_PYTHON" - "$out" "$dauer" <<'PY'
import json, sys
pfad, dauer = sys.argv[1], sys.argv[2]
try:
    with open(pfad) as fh:
        json.load(fh)
    sys.exit(1)          # brauchbares Log — nichts zu tun
except Exception:
    pass
try:
    sekunden = int(float(dauer))
except (TypeError, ValueError):
    sekunden = None
json.dump({"is_error": True, "result": "", "total_cost_usd": None,
           "team_versuch": "verworfen", "team_dauer_s": sekunden},
          open(pfad, "w"))
sys.exit(0)
PY
}

# team_versuch_melden <rolle> <json-datei> <start-epoch>
# Bequemer Aufrufer von team_versuch_sichern: rechnet die Dauer selbst aus und
# sagt laut, dass hier ein bezahlter Anlauf ohne Quittung liegt. Die Meldung ist
# der eigentliche Zweck — im Feld fiel die 0-Byte-Datei nur auf, weil ein Mensch
# den Ordner ansah (BL-46).
team_versuch_melden() {
    local rolle="$1" out="$2" t0="$3" dauer
    dauer=$(( $(date +%s) - t0 ))
    if team_versuch_sichern "$rolle" "$out" "$dauer"; then
        echo "[$rolle] VERWORFENER VERSUCH: '$out' war nach ${dauer}s nicht als JSON lesbar (0 Byte/abgeschnitten)." >&2
        echo "  Ersatzzettel geschrieben — die Dauer ist belegt, die Kosten sind UNBEKANNT und werden" >&2
        echo "  in keiner Summe geschätzt. Der Aufruf gilt weiter als Fehler (API-Fallback greift)." >&2
    fi
}

# team_abo_fehlergrund <json>: druckt "anmeldung", "schutzregeln[ <kategorie>]"
# oder nichts (BL-316).
#
# Bis hierher hiess JEDER Fehler eines Abo-Aufrufs "Timeout/Limit/429?" und lief
# in den API-Fallback. Zwei Ursachen sehen im Log genauso aus und verlangen
# etwas anderes:
#   - Eine ABGELAUFENE ANMELDUNG ("Failed to authenticate: OAuth session expired
#     and could not be refreshed") geht nicht von selbst vorueber. Im Feld
#     rettete der Fallback die eine Stufe, und die naechsten liefen nach einem
#     Turn im Abo ganz ueber die API — rund 12,5 USD fuer Stunden, in denen ein
#     Mensch sich nur haette neu anmelden muessen.
#   - Eine ABLEHNUNG DURCH DIE SCHUTZREGELN des Modells ("API Error: … safeguards
#     flagged this message … [cyber]") traf einen Sweep ueber Sicherheitscode.
#     Der Fallback half dort — aber die Zeile nannte Timeout oder Limit, und wer
#     sie liest, sucht das Kontingent.
# Geprueft wird nur ein Log mit is_error und nur der ANFANG von `result`: Ein
# Erklaertext des Modells, der eine solche Meldung zitiert, faellt heraus —
# dieselbe Vorsicht wie beim 429-Muster (HM-21). Die Regel steht EINMAL, in
# kosten.py (abo_fehlergrund); die pwsh-Bahn traegt sie in PowerShell, und
# test_bl316 haelt alle Fassungen gegen dieselben Faelle. Liegt das Werkzeug
# nicht daneben, wird nichts behauptet — es bleibt beim alten Fallback.
team_abo_fehlergrund() {
    local werkzeug
    werkzeug="$(dirname "${BASH_SOURCE[0]}")/tools/kosten.py"
    [ -f "$werkzeug" ] || return 0
    "$TEAM_PYTHON" "$werkzeug" fehlergrund "$1" 2>/dev/null || true
}

# team_pause_grund — der Grund des letzten Pausen-Signals (Exit 42), in der
# Form, in der ihn die Rollen dem Menschen melden (BL-316). Seit dort heisst 42
# nicht mehr nur "Session-Limit": Eine abgelaufene Abo-Anmeldung haelt den Lauf
# genauso an, und der Mensch muss etwas anderes tun.
TEAM_LAST_PAUSE_GRUND=""
team_pause_grund() {
    if [ "${TEAM_LAST_PAUSE_GRUND:-}" = "anmeldung" ]; then
        echo "Abo-Anmeldung abgelaufen — neu anmelden (claude starten, /login)"
    else
        echo "Session-Limit (Reset: ${TEAM_LAST_RESET:-unbekannt})"
    fi
}

team_claude() {
    local rolle="$1" modell="$2" out="$3" prompt="$4"
    shift 4
    TEAM_LAST_PAUSE=0
    TEAM_LAST_PAUSE_GRUND=""
    TEAM_LAST_RESET=""
    TEAM_LAST_KEIN_ZUG=0

    if [ "${TEAM_DRY_RUN:-0}" = "1" ]; then
        "$TEAM_PYTHON" - "$out" "${TEAM_DRY_RESULT:-}" <<'PY'
import json, sys
json.dump({"result": sys.argv[2], "total_cost_usd": 0.01, "is_error": False},
          open(sys.argv[1], "w"))
PY
        TEAM_LAST_COST="0.01"; TEAM_LAST_OUT="$out"
        echo "[$rolle] DRY-RUN — kein Claude-Aufruf."
        return 0
    fi

    # BL-173: VOR dem ersten Aufruf pruefen, ob es die CLI ueberhaupt gibt.
    # Kein API-Fallback, kein Ersatzzettel, kein Fehlversuchs-Zaehler —
    # nichts davon passt auf "das Programm gibt es nicht".
    if ! team_cli_vorhanden; then
        team_cli_fehlt_melden "$rolle"
        return 1
    fi

    AUTH_MODE="$TEAM_AUTH_USER"
    team_resolve_auth_mode abo || return 1

    local fehler=0 cli_exit=0 t0=0
    # Alle Logs DIESES Aufrufs — auch die gescheiterten Vorversuche. TEAM_LAST_COST
    # ist die Summe darueber, nicht nur der letzte Versuch (BL-55).
    local -a versuch_logs=()
    t0="$(date +%s)"
    "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
    team_versuch_melden "$rolle" "$out" "$t0"
    versuch_logs+=("$out")
    if team_bewerte_ergebnis "$rolle" "$out" "$cli_exit"; then fehler=0; else fehler=1; fi

    # Stakeholder-Entscheid (2026-07-11): Bei JEDEM Abo-Fehler — egal ob
    # Timeout, normaler Fehler ODER 429/Session-Limit — SOFORT den API-Fallback
    # versuchen. Der API-Key hat ein eigenes, separates Kontingent (bewiesen
    # 2026-07-11: bei erschöpftem Abo-Kontingent liefert derselbe Prompt mit dem
    # Key erfolgreich `result:ok`), daher hilft der Fallback auch bei einem
    # Abo-429. Erst wenn AUCH der API-Weg scheitert, greift die 429-Warte-/
    # Retry-/Pausen-Logik weiter unten.
    #
    # WICHTIG (Bugfix 2026-07-11): Der Key wird dem `claude`-Aufruf EXPLIZIT als
    # Aufruf-lokales Environment vorangestellt (ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
    # claude …). Ein bloßes `export` über team_resolve_auth_mode reicht NICHT:
    # die CLI bevorzugte im selben Prozess weiterhin die (limitierte) Abo-Session
    # und ignorierte den frisch exportierten Key — der Fallback lief real erneut
    # ins Abo-429. Mit dem vorangestellten Key greift der API-Weg zuverlässig.
    # BL-174: ZUERST fragen, ob es ueberhaupt einen API-Weg gibt.
    #
    # Vorher stand hier `team_resolve_auth_mode || return 1`. In einer reinen
    # Abo-Installation gibt die Funktion fuer AUTH_MODE=api eine 1 zurueck —
    # das `|| return 1` verliess team_claude also SOFORT, und die gesamte
    # 429-Sonderbehandlung darunter wurde nie erreicht. Ein Session-Limit,
    # also genau die Klasse, fuer die BL-20/BL-25 den Exit 42 eingefuehrt
    # haben ("weder ein sauberer Erfolg noch ein echter Fehler, sondern eine
    # eigene, klar benannte Klasse"), kam als Exit 1 heraus: "ECHTER Fehler,
    # Mensch gefragt". Kein Warten bis zum Reset, kein Pausen-Signal, keine
    # der drei dokumentierten Zusicherungen.
    #
    # Der Airbag war damit ausgerechnet im empfohlenen Normalfall ausgebaut,
    # und zwar unsichtbar: Der Fehler zeigt sich erst, wenn das Kontingent
    # voll ist — nach Stunden Laufzeit, an der teuersten Stelle.
    #
    # Ein fehlender Schluessel ist hier kein Fehler, sondern der erwartete
    # Zustand. Er darf den Ablauf nicht abschneiden.
    #
    # BL-316: Erst fragen, WARUM der Abo-Aufruf scheiterte (team_abo_fehlergrund).
    local grund="" kategorie="" auszug=""
    if [ "$fehler" -eq 1 ] && [ "$AUTH_MODE" = "abo" ]; then
        grund="$(team_abo_fehlergrund "$out")"
        kategorie="${grund#schutzregeln}"; kategorie="${kategorie# }"
        grund="${grund%% *}"
        auszug="$(team_result_auszug "$out")"; auszug="${auszug:0:160}"
    fi
    if [ "$grund" = "anmeldung" ]; then
        # Kein Fallback, mit oder ohne Schluessel: Die Anmeldung geht nicht von
        # selbst vorueber, und jeder weitere Aufruf liefe still ueber die API.
        # Exit 42 haelt den Lauf an, wo alle Aufrufer ihn ohnehin anhalten —
        # kein Fehlversuch, State steht.
        TEAM_LAST_PAUSE=1
        TEAM_LAST_PAUSE_GRUND="anmeldung"
        TEAM_LAST_RESET="nach neuer Anmeldung"
        TEAM_LAST_COST="$(team_summe_cost_usd "${versuch_logs[@]}")"
        TEAM_LAST_OUT="$out"
        echo "[$rolle] Abo-Anmeldung abgelaufen oder ungültig: „${auszug}“" >&2
        echo "  KEIN API-Fallback (Kit-BL-316): Eine Anmeldung geht nicht von selbst vorüber — jeder" >&2
        echo "  weitere Aufruf dieses Laufs liefe sonst über die API. Der Lauf hält an wie beim" >&2
        echo "  Session-Limit (Exit 42). Neu anmelden (claude starten, /login), dann denselben Lauf" >&2
        echo "  erneut starten. Log: $out" >&2
        return 42
    fi
    if [ "$fehler" -eq 1 ] && [ "$AUTH_MODE" = "abo" ] && ! team_api_weg_vorhanden; then
        echo "[$rolle] Abo-Aufruf fehlgeschlagen (${auszug:-kein Grund im Log}) — kein API-Schluessel hinterlegt, also kein Fallback. Weiter mit der regulaeren Limit-Behandlung." >&2
    elif [ "$fehler" -eq 1 ] && [ "$AUTH_MODE" = "abo" ]; then
        if [ "$grund" = "schutzregeln" ]; then
            echo "[$rolle] Abo-Aufruf von den Schutzregeln des Modells abgelehnt${kategorie:+ ($kategorie)} — einmaliger API-Fallback; ob der API-Weg durchkommt, ist nicht zugesichert (Kit-BL-316). Log: $out"
        else
            echo "[$rolle] Abo-Aufruf fehlgeschlagen (${auszug:-kein Grund im Log}) — einmaliger API-Fallback. Log: $out"
        fi
        AUTH_MODE=api
        team_resolve_auth_mode || return 1
        out="${out%.json}-api-fallback.json"
        cli_exit=0
        t0="$(date +%s)"
        ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
        team_versuch_melden "$rolle" "$out" "$t0"
        versuch_logs+=("$out")
        if team_bewerte_ergebnis "$rolle" "$out" "$cli_exit"; then fehler=0; else fehler=1; fi
    fi

    # 429-Sonderbehandlung jetzt auf dem FINALEN (ggf. API-)Ergebnis: nur wenn
    # auch der API-Weg noch einen 429 liefert, wird gewartet/gepausiert.
    if [ "$fehler" -eq 1 ] && team_result_is_429 "$out"; then
        local versuch=1 reset_epoch jetzt warten reset_hhmm pausieren=1
        while [ "$versuch" -le "$TEAM_429_MAX_RETRIES" ]; do
            reset_epoch="$(team_429_reset_epoch "$out")" || reset_epoch=""
            if [ -z "$reset_epoch" ]; then
                echo "[$rolle] 429 erkannt, Reset-Zeit unbekannt — kein Warten, Pausen-Signal." >&2
                break
            fi
            jetzt="$(date +%s)"
            warten=$(( reset_epoch - jetzt + TEAM_429_PUFFER ))
            reset_hhmm="$(date -d "@$reset_epoch" +%H:%M 2>/dev/null || date -r "$reset_epoch" +%H:%M)"
            if [ "$TEAM_429_MAX_WARTEN" -le 0 ] || [ "$warten" -gt "$TEAM_429_MAX_WARTEN" ]; then
                echo "[$rolle] 429 erkannt, Reset erst in ${warten}s (> TEAM_429_MAX_WARTEN=${TEAM_429_MAX_WARTEN}s) — kein Warten, Pausen-Signal." >&2
                break
            fi

            echo "[$rolle] 429/Session-Limit erkannt (Versuch $versuch/$TEAM_429_MAX_RETRIES) — warte ${warten}s bis Reset (${reset_hhmm}) + Puffer." >&2
            team_429_sleep "$warten"

            out="${out%.json}-429-retry${versuch}.json"
            cli_exit=0
            t0="$(date +%s)"
            # Wie beim API-Fallback oben: Key explizit voranstellen, falls der
            # aktuelle AUTH_MODE api ist (sonst greift die CLI ggf. die Abo-Session).
            if [ "$AUTH_MODE" = "api" ]; then
                ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
            else
                "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
            fi
            team_versuch_melden "$rolle" "$out" "$t0"
            versuch_logs+=("$out")
            if team_bewerte_ergebnis "$rolle" "$out" "$cli_exit"; then fehler=0; else fehler=1; fi

            if [ "$fehler" -eq 0 ]; then
                echo "[$rolle] Retry nach 429 erfolgreich. Log: $out" >&2
                pausieren=0
                break
            fi
            if ! team_result_is_429 "$out"; then
                echo "[$rolle] Retry lieferte einen normalen (nicht-429) Fehler — weiter im normalen Fehlerpfad." >&2
                pausieren=0
                break
            fi
            versuch=$((versuch + 1))
        done

        if [ "$fehler" -eq 1 ] && [ "$pausieren" -eq 1 ]; then
            TEAM_LAST_PAUSE=1
            TEAM_LAST_PAUSE_GRUND="limit"
            TEAM_LAST_RESET="${reset_hhmm:-unbekannt}"
            TEAM_LAST_COST="$(team_summe_cost_usd "${versuch_logs[@]}")"
            TEAM_LAST_OUT="$out"
            echo "[$rolle] 429/Session-Limit — Retries erschöpft oder Reset zu weit entfernt. Pausen-Signal (Reset: $TEAM_LAST_RESET)." >&2
            return 42
        fi
    fi

    TEAM_LAST_COST="$(team_summe_cost_usd "${versuch_logs[@]}")"
    TEAM_LAST_OUT="$out"
    if [ "$fehler" -eq 1 ]; then
        # BL-228: Kam überhaupt ein Modell zum Zug? Der Rückgabewert bleibt 1 —
        # ein Lauf ohne Ergebnis ist ein Lauf ohne Ergebnis, und die
        # Stagnations-Bremse der Vollautomatik muss ihn weiter sehen. Was sich
        # ändert, ist die ZURECHNUNG: Der Aufrufer erfährt über
        # TEAM_LAST_KEIN_ZUG, dass die Rolle nichts dafür kann.
        if team_kein_zug "${versuch_logs[@]}"; then
            TEAM_LAST_KEIN_ZUG=1
            echo "[$rolle] Kein Modell kam zum Zug (0 Turns, 0.0000 USD) — Netz/Proxy vor dem ersten Token. Log: $out" >&2
        else
            echo "[$rolle] Claude-Aufruf endgültig fehlgeschlagen, Log: $out" >&2
        fi
        return 1
    fi
    return 0
}

# team_kein_zug <json-datei>...
# War in diesem Aufruf überhaupt ein Modell am Zug? (BL-228)
#
# Ein Netzfehler VOR dem ersten Token — Proxy nicht gesetzt, VPN-Aussetzer,
# kurzer Abriss — endet mit `num_turns: 0` und `total_cost_usd: 0.0000`: Kein
# Modell hat den Auftrag je gesehen. Für die Rolle ist das derselbe Fall wie
# das Session-Limit (Exit 42, HM-24) — kein INHALTLICHER Fehlversuch, sondern
# gar keiner. Im Feld standen nach zwei solchen Aussetzern zwei Fehlversuche
# gegen einen Fund, den nie ein Modell gelesen hatte; nach dreien hätte der
# Fund auf „an Axel übergeben" gestanden, also auf der teuersten Rolle.
#
# WARUM AN DEN ZAHLEN UND NICHT AM FEHLERTEXT: Der Text der CLI ist ihre Sache
# und ändert sich ("Connection refused", "a firewall or proxy may be blocking
# it"); die beiden Zahlen sind der Vertrag. Es ist zudem die dritte Variante
# desselben Musters (Session-Limit, unquittierte Sitzung, Netzfehler) — ein
# dritter Textzweig wäre genau die Bauform, die BL-214 beim Abtragen eng
# ziehen musste. „0 Turns und 0.0000 USD" trifft alle drei und ist maschinell
# prüfbar.
#
# BEWEISLAST STATT VERMUTUNG: Verlangt werden BEIDE Zahlen, in JEDEM Log dieses
# Aufrufs (Abo-Versuch, API-Fallback, 429-Retries). Fehlt `num_turns` — etwa im
# Ersatzzettel nach einem abgeschnittenen Log (BL-46) — oder fehlt die Datei,
# sind die Kosten UNBEKANNT, und dann bleibt es ein gewöhnlicher Fehlversuch.
# Die Fehlerrichtung ist gewollt: lieber einen Fehlversuch zu viel zählen als
# einen echten verschlucken (BL-160).
team_kein_zug() {
    [ "$#" -gt 0 ] || return 1
    "$TEAM_PYTHON" - "$@" <<'PY'
import json, sys
for pfad in sys.argv[1:]:
    try:
        daten = json.load(open(pfad))
    except Exception:
        sys.exit(1)
    turns, kosten = daten.get("num_turns"), daten.get("total_cost_usd")
    if turns is None or kosten is None:
        sys.exit(1)
    try:
        if float(turns) != 0 or float(kosten) != 0:
            sys.exit(1)
    except (TypeError, ValueError):
        sys.exit(1)
sys.exit(0)
PY
}

# team_promise_in <json-datei> <promise-text>
# Rückgabe 0, wenn das Ergebnis <promise>TEXT</promise> enthält.
team_promise_in() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)
result = data.get("result", "") or ""
sys.exit(0 if f"<promise>{sys.argv[2]}</promise>" in result else 1)
' "$1" "$2"
}

# --- Planmaessig uebersprungene Stufe (BL-255) ---------------------------------
# WARUM ES DIE ZWEITE QUITTUNGSFORM GIBT. Eine Stufe mit im Plan
# ausgeschriebener ABBRUCHBEDINGUNG trat im Feld ein: Die Rolle hat gemessen,
# die Konfiguration unangetastet gelassen, den Befund in den [Unreleased]-Block
# eingetragen, committet — und REGELKONFORM kein Promise gegeben, weil die
# Stufe nicht abgeschlossen, sondern abgebrochen wurde.
#
# Fuer diese Lage gab es keine Vokabel. Es gab Promise oder kein Promise, und
# *kein Promise* ist mit dem teuersten Bericht des Werkzeugs belegt (BL-41,
# Exit 43). Die Selbstpruefung machte es nicht besser, sondern zweideutig:
# Pruefung 1 (*hat die Sitzung Arbeit hinterlassen*) trifft zu, Pruefung 2
# (*gibt es eine beruehrte Testdatei*) in der Regel nicht — also faellt sie
# durch, und der Lauf landet im Exit 43 mit der Begruendung *Produktivcode ohne
# Zusicherung*, die ebenfalls nicht zutrifft. Der Mensch bekommt in BEIDEN
# Zweigen eine falsche Diagnose; eine abgebrochene Stufe, die zufaellig doch
# eine Testdatei angefasst hat, wuerde sogar still als abgeschlossen
# durchgewunken.
#
# WARUM DAS MEHR IST ALS KOSMETIK: Der vierte Ausgang ist die teuerste Meldung
# des Werkzeugs. Wird sie bei einem GEORDNETEN Abschluss gedruckt, stumpft sie
# ab und wird beim naechsten echten Fall weggeklickt.
#
# team_plan_erlaubt_uebersprung <stufe> [plan-datei]
# Rueckgabe 0, wenn der PLAN die zweite Quittungsform fuer genau diese Stufe
# ausschreibt. Das ist der Riegel (a) gegen ein Schlupfloch: Die Vokabel gilt
# nur dort, wo der Architekt die Abbruchbedingung vorher hingeschrieben hat.
# Geprueft wird die Zeichenkette selbst — sie traegt die Stufennummer, kann
# also nicht aus dem Block einer anderen Stufe stammen.
# team_result_auszug <log>: der Anfang des `result`-Feldes, in einer Zeile.
# BL-301: Dort sagt eine Rolle, die nichts gebaut hat, meist selbst warum —
# im Feld stand die richtige Antwort ("`.ralph-state` muss auf 34") nur im
# Log, und die Konsole zeigte daneben einen falschen Rat.
team_result_auszug() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    r = json.load(open(sys.argv[1], encoding="utf-8")).get("result") or ""
except Exception:
    sys.exit(0)
r = " ".join(str(r).split())
sys.stdout.buffer.write((r[:700] + (" …" if len(r) > 700 else "")).encode("utf-8"))
' "$1" 2>/dev/null || true
}

team_plan_erlaubt_uebersprung() {
    local stufe="$1" plan="${2:-$(team_plan_datei)}"
    [ -n "$plan" ] && [ -f "$plan" ] || return 1
    grep -q "STUFE_${stufe}_UEBERSPRUNGEN" "$plan"
}

# team_plan_stufen [plan]: die Nummern, fuer die der Plan einen Block
# `## Stufe N` hat — eine je Zeile, aufsteigend; leer, wenn er keinen hat.
#
# BL-301: Eine Stufennummer ohne Block ist keine baubare Aufgabe, und das
# steht VOR dem ersten Token fest. Im Feld zeigte .ralph-state nach einem
# Closeout versehentlich auf 17, der Plan kannte nur 28–33; Ralph startete
# trotzdem einen bezahlten Aufruf, und die Selbstpruefung empfahl danach
# `echo 18 > .ralph-state` — eine nie gebaute Stufe zu quittieren.
# Ebene 2–4 und ein Titel hinter der Nummer sind erlaubt; ein Plan ganz ohne
# solche Bloecke liefert LEER, und dann prueft der Aufrufer nicht (geraten
# wird nicht — ein fremdes Format ist kein Befund).
team_plan_stufen() {
    local plan="${1:-$(team_plan_datei)}"
    [ -n "$plan" ] && [ -f "$plan" ] || return 0
    { grep -E '^#{2,4}[[:space:]]*Stufe[[:space:]]+[0-9]+([^0-9]|$)' "$plan" || true; } \
        | sed -E 's/^#{2,4}[[:space:]]*Stufe[[:space:]]+([0-9]+).*/\1/' \
        | sort -n -u
}


# team_gate_rot_seit: erste Zeile der Gate-Datei, oder leer. Der Aufrufer
# entscheidet, was er damit tut — gelesen wird an genau einer Stelle.
team_gate_rot_seit() {
    [ -s "$TEAM_GATE_DATEI" ] || return 1
    head -n1 "$TEAM_GATE_DATEI"
}

# --- Vierte Fehlerklasse: Sitzung beendet, Auftrag unquittiert (BL-41) --------
# Neben Erfolg, echtem Fehler und Session-Limit gibt es einen vierten Ausgang:
# Die Rolle beendet ihre Antwort freiwillig, ohne den Auftrag zu quittieren —
# typischerweise, weil sie einen Hintergrund-Task/Monitor/Wakeup gestartet hat
# und auf eine Benachrichtigung wartet, die in einer headless-Sitzung nie
# eintrifft. Das Ergebnis-JSON trägt dann `subtype: "success"`, `is_error:
# false`, `stop_reason: end_turn` — für team_result_is_error ein sauberer
# Erfolg. Nur das fehlende Promise verrät den Fall, und die bisherige Meldung
# ("KEIN Promise — Log prüfen") schickte den Menschen ins Log, das Erfolg meldet,
# und von dort in den PLAN statt in den Fehlermodus.
#
# Vier Vorfälle im Feld (K27/125, K28/131, K28/133, K33/154), zusammen
# 19,47 USD — jedes Mal für Arbeit, die fertig und grün war. Der Neustart wirft
# sie weg; von Hand quittieren rettet sie (im Feld belegt, Commit 458f660).
#
# WARUM NICHT AUF VOKABELN GEPRÜFT WIRD: Die drei Vorfälle formulierten es
# dreimal anders ("background pytest run and monitor", "fallback check /
# wakeup", "set up a monitor to catch its completion") — die vierte Variante
# schreibt jemand morgen. Geprüft wird deshalb die STRUKTUR: kein Promise, aber
# das Log erklärt sich selbst für erfolgreich.
#
# Abgrenzung zur Prävention (SMOKE_ZEILE, oben): Die Auflage steht am
# Prompt-Anfang, der Vorfall passiert nach 65 Turns — Prävention per Prompt
# skaliert gegenläufig zur Stufenlänge. Sie senkt die Wahrscheinlichkeit; DIESE
# Erkennung fängt den Rest.

# team_result_meldet_erfolg <json-datei>
# Rückgabe 0, wenn das Log sich selbst für erfolgreich erklärt (lesbar,
# is_error falsch und subtype "success" — beides muss zutreffen, sonst wäre
# jedes lesbare Log ohne is_error-Feld schon ein "Erfolg").
team_result_meldet_erfolg() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)
if data.get("is_error"):
    sys.exit(1)
sys.exit(0 if data.get("subtype") == "success" else 1)
' "$1"
}

# team_quittung_fehlt_melden <rolle> <json-datei> <was-fehlt> <weiterweg…>
# Druckt die BENANNTE Meldung für den Fall oben. Der Aufrufer ruft sie NUR,
# wenn die Quittung fehlt; ob der Fall vorliegt, entscheidet diese Funktion.
# Rückgabe 0 = benannter Fall erkannt und gemeldet, 1 = gewöhnlicher Fehlschlag
# (der Aufrufer meldet dann wie bisher).
team_quittung_fehlt_melden() {
    local rolle="$1" out="$2" was="$3"; shift 3
    team_result_meldet_erfolg "$out" || return 1
    echo "[$rolle] STUFE FERTIG, QUITTUNG FEHLT (Kit-BL-41) — $was" >&2
    echo "  Das Log meldet sich selbst als Erfolg (subtype=success, is_error=false), gibt aber" >&2
    echo "  keine Quittung. Das ist der benannte vierte Ausgang: Die Sitzung hat sich beendet," >&2
    echo "  meist im Warten auf einen Hintergrund-Task/Monitor/Wakeup, den es headless nicht gibt." >&2
    echo "  Die Arbeit ist in diesem Fall meist FERTIG — viermal im Feld, 19,47 USD. Prüfe in" >&2
    echo "  dieser Reihenfolge, BEVOR du neu startest (ein Neulauf wirft die bezahlte Arbeit weg):" >&2
    local schritt
    for schritt in "$@"; do
        echo "    - $schritt" >&2
    done
    # BL-201: Der kuerzeste Weg zur richtigen Diagnose, und er kostet eine
    # Zeile. Im Feld loeste den Fall ALLEIN das Feld `result` im Lauf-Log —
    # dort stand die Ursache woertlich ("waiting for the background test
    # run"). Die Anleitung erwaehnte es an keiner Stelle; ohne den Hinweis
    # sucht der Mensch in der Pruefreihenfolge weiter, deren beide Zweige
    # einen roten Baum voraussetzen, und wirft im zweiten eine fertige,
    # bezahlte Stufe weg.
    echo "  Log: $out" >&2
    echo "  Lies dort ZUERST das Feld \`result\` — die Rolle sagt darin meist selbst," >&2
    echo "  worauf sie gewartet hat. Neunmal im Feld stand dort das Warten auf einen" >&2
    echo "  Hintergrundlauf, und kein einziger erfolgreicher Lauf zeigte dieses Muster." >&2
    return 0
}

# --- Laeuft der Verifikationsbefehl schon? (BL-207) ---------------------------
# team_smoke_parallel_lauf
#   0 = ein ZWEITER Lauf des Verifikationsbefehls ist nachweisbar
#   1 = keiner nachweisbar (das schliesst "auf diesem Wirt nicht feststellbar"
#       ein — im Zweifel bleibt es beim bisherigen Verhalten)
#
# WARUM ES SIE GIBT (Feld B, 2026-08-28): Die Selbstpruefung startete den
# Verifikationsbefehl bedingungslos ein zweites Mal. Im Feld lief der
# Hintergrund-pytest der Rolle noch, als die Selbstpruefung IHREN eigenen
# startete. Zwei gleichzeitige Testlaeufe kollidieren (Datenbankdateien, Ports,
# App-Nutzerverzeichnisse); die Selbstpruefung meldete daraufhin ROT fuer einen
# Baum, der allein gefahren gruen war (199 passed, im Closeout nachgemessen) —
# und schickte den Menschen per BL-61-Text ausdruecklich auf die falsche
# Faehrte "Testaufbau". Wer ihr geglaubt und die Stufe neu gebaut haette,
# haette 2,36 USD bezahlte, fertige Arbeit weggeworfen.
#
# Eine Selbstpruefung, die im Zweifel "rot" BEHAUPTET, ist schlimmer als eine,
# die schweigt. Deshalb: erkannter Parallellauf ⇒ UNBEKANNT, nicht rot.
#
# Die gefundene Zeile wird mitgegeben (TEAM_SMOKE_PARALLEL_ZEILE), damit ein
# Fehlalarm — ein Dauerlaeufer wie pytest-watch, der den Befehl in seiner
# Kommandozeile traegt — in einem Blick als solcher erkennbar ist statt als
# Raetsel.
TEAM_SMOKE_PARALLEL_ZEILE=""
team_smoke_parallel_lauf() {
    local tabelle treffer="" muster
    TEAM_SMOKE_PARALLEL_ZEILE=""
    [ -z "${TEAM_SMOKE_TEST:-}" ] && [ -z "${TEAM_SMOKE_TEST_SCHNELL:-}" ] && return 1
    tabelle="$(ps -eo args= 2>/dev/null || ps ax 2>/dev/null || true)"
    [ -z "$tabelle" ] && return 1
    # BL-315: Seit BL-232 verifizieren die Stufen mit TEAM_SMOKE_TEST_SCHNELL
    # — der verwaiste Lauf einer Rolle traegt dann DIESEN Befehl.
    for muster in "${TEAM_SMOKE_TEST:-}" "${TEAM_SMOKE_TEST_SCHNELL:-}"; do
        [ -n "$muster" ] || continue
        treffer="$(echo "$tabelle" | grep -F -- "$muster" | head -1 || true)"
        [ -n "$treffer" ] && break
    done
    [ -z "$treffer" ] && return 1
    TEAM_SMOKE_PARALLEL_ZEILE="$treffer"
    return 0
}

# team_selbstpruefung_wartefrist — BL-315: Wie lange die Selbstpruefung auf
# einen laufenden Verifikationslauf wartet, bevor sie UNBEKANNT meldet.
# Default ist die Frist, die ein Smoke-Test ueberhaupt brauchen darf; der
# verwaiste Lauf hat davon schon einen Teil hinter sich.
# TEAM_SELBSTPRUEFUNG_WARTEN=0 schaltet das Warten ab (altes Verhalten).
team_selbstpruefung_wartefrist() {
    local kandidat
    for kandidat in "${TEAM_SELBSTPRUEFUNG_WARTEN:-}" "${TEAM_SMOKE_TEST_TIMEOUT:-}"; do
        case "$kandidat" in
            ''|*[!0-9]*) ;;
            *) echo "$kandidat"; return 0 ;;
        esac
    done
    echo 600
}

# team_smoke_umgebung_pruefen <befehl> — BL-320: Kann der Befehl in dieser
# Umgebung ueberhaupt laufen? Traegt er pytest-xdist-Optionen und fehlt xdist
# im Interpreter, bricht pytest am Parser ab — und die Selbstpruefung meldete
# "ROT, kein Flackern" und schickte den Menschen in den Produktivcode. Im
# Feld dreimal lokal nachgetragen und dreimal von einem Update entfernt.
# team_smoke_umgebung_befund druckt den Befund auf stdout (leer = keiner oder
# nicht feststellbar — im Zweifel wird nichts behauptet); die Pruefung steckt
# im geteilten Werkzeug, damit beide Bahnen dieselbe fahren.
# team_smoke_umgebung_pruefen: 0 = kein Befund, 1 = Befund, Text auf stderr.
team_smoke_umgebung_befund() {
    local werkzeug aus rc=0
    werkzeug="$(dirname "${BASH_SOURCE[0]}")/tools/smoke_warten.py"
    [ -f "$werkzeug" ] || return 0
    aus="$("$TEAM_PYTHON" "$werkzeug" umgebung --befehl "$1" 2>/dev/null)" || rc=$?
    [ "$rc" -eq 3 ] && printf '%s\n' "$aus"
    return 0
}
team_smoke_umgebung_pruefen() {
    local befund
    befund="$(team_smoke_umgebung_befund "$1")"
    [ -z "$befund" ] && return 0
    printf '%s\n' "$befund" | sed 's/^/    /' >&2
    return 1
}

# --- Der vierte Ausgang, selbst geprüft (BL-41 automatisiert) -----------------
# team_quittung_selbstpruefung <rolle> <stufe>
#
# WARUM ES SIE GIBT: Die Erkennung oben ist richtig, aber sie hält den Lauf an
# und legt einem Menschen eine Prüfliste vor, deren drei Schritte IMMER
# dieselben sind. Im Feld (Feld A) ist der Fall in neun Kaskaden
# aufgetreten — K27, K28, K29, K33, K34, K35 (dort dreimal), K36, K37 — und
# JEDES Mal lautete das Ergebnis "Arbeit fertig, nur die Quittung fehlt". Eine
# Prüfliste, die neunmal dasselbe ergibt, ist eine Funktion, die noch niemand
# geschrieben hat. Der Stopp kostet dabei mehr als nur Wartezeit: Er
# unterbricht die Vollautomatik mitten in der Kaskade, und der Mensch muss den
# Lauf von Hand fortsetzen.
#
# WAS SIE NICHT TUT: Sie quittiert NICHT auf Verdacht. Sie prüft genau das,
# was der Mensch geprüft hätte — plus den Punkt, an dem die Prüfliste selbst
# blind war (BL-135: Commit und grüner Baum unterscheiden eine HALB gebaute
# Stufe nicht von einer fertigen; sie fragen nicht nach der Existenz der
# Zusicherungen). Fällt auch nur eine Prüfung durch, gibt sie 1 zurück und der
# Aufrufer meldet unverändert an den Menschen. Der teure Fehler wäre, eine
# unfertige Stufe durchzuwinken — deshalb ist jede Prüfung ein UND, keine
# Mehrheit, und im Zweifel gilt "nicht bestanden".
#
# Rückgabe 0 = alle Prüfungen bestanden, der Aufrufer darf selbst quittieren.
#          1 = mindestens eine Prüfung offen (Grund steht auf stderr).
#
# Abschaltbar über TEAM_QUITTUNG_AUTO=0 (Default an). Aus bleibt die alte
# Prüflisten-Meldung, unverändert.
team_quittung_selbstpruefung() {
    local rolle="$1" stufe="$2"
    local test_ordner="${TEAM_TEST_ORDNER:-tests/}"
    local smoke="${TEAM_SMOKE_TEST:-}"
    # BL-301 (Befund 2): Der Aufrufer muss wissen, ob die Pruefung an
    # "nichts hinterlassen" scheiterte — sonst druckt er den Plan des
    # vierten Ausgangs samt `echo N+1`, also den Rat, eine nie gebaute Stufe
    # zu quittieren.
    TEAM_SELBSTPRUEFUNG_LEER=0

    if [ "${TEAM_QUITTUNG_AUTO:-1}" != "1" ]; then
        return 1
    fi

    echo "[$rolle] Selbstprüfung des vierten Ausgangs (Kit-BL-41) für Stufe $stufe:" >&2

    # (1) Hat die Sitzung überhaupt etwas hinterlassen? Ohne Arbeit gibt es
    #     nichts zu quittieren — dann ist es kein "fertig ohne Quittung",
    #     sondern eine Stufe, die nie angefangen hat.
    local uncommittet betreff hat_arbeit=0
    # BL-269: Laufzeitartefakte (das eigene Log dieser Stufe, .ralph-logs/)
    # sind keine Arbeit — ohne Filter galt eine Sitzung, die nichts gebaut
    # hatte, in jedem Projekt ohne die gitignore-Zeile als "Arbeit vorhanden".
    uncommittet="$(git status --porcelain 2>/dev/null | cut -c4- \
                   | grep -Ev "$TEAM_GUARD_LAUFZEIT" | grep -Ev "$TEAM_GUARD_IGNORIERT" || true)"
    betreff="$(git log -1 --pretty=%s 2>/dev/null)"
    [ -n "$uncommittet" ] && hat_arbeit=1
    case "$betreff" in *"stufe$stufe"*|*"Stufe $stufe"*) hat_arbeit=1 ;; esac
    if [ "$hat_arbeit" -eq 0 ]; then
        echo "    ✗ Kein Commit für Stufe $stufe und keine uncommitteten Änderungen." >&2
        echo "      Die Sitzung hat nichts hinterlassen — das ist NICHT der vierte Ausgang." >&2
        TEAM_SELBSTPRUEFUNG_LEER=1
        return 1
    fi
    echo "    ✓ Arbeit vorhanden (uncommittet und/oder Commit der Stufe)." >&2

    # (2) BL-135: Gibt es eine ZUSICHERUNG? Genau der Punkt, an dem die
    #     Prüfliste für den Menschen blind war. Eine Stufe, die Produktivcode
    #     baut und keine einzige Testdatei berührt, ist nach den
    #     Verifikationsregeln dieses Projekts nicht fertig — egal wie grün der
    #     Baum ist, denn der bestehende Bestand deckt das Neue nicht ab.
    local dateien
    if [ -n "$uncommittet" ]; then
        # Schon ohne Statusspalte (siehe oben) — ein zweites Abschneiden
        # machte aus `tests/` ein `ts/`, und jede Stufe galt als ungesichert.
        dateien="$uncommittet"
    else
        dateien="$(git show --name-only --pretty=format: HEAD 2>/dev/null)"
    fi
    if ! printf '%s\n' "$dateien" | grep -q "^\"\?${test_ordner}"; then
        echo "    ✗ Keine Datei unter ${test_ordner} berührt (Kit-BL-135)." >&2
        echo "      Die Stufe hat keine nachweisbare Zusicherung — grüner Baum beweist hier" >&2
        echo "      nichts, weil der Bestand das Neue nicht prüft. Das gehört an den Menschen." >&2
        return 1
    fi
    echo "    ✓ Zusicherung vorhanden — mindestens eine Datei unter ${test_ordner} berührt (Kit-BL-135)." >&2

    # (3) Ist der Baum grün? Der teuerste, aber unverzichtbare Schritt — er
    #     ist derselbe Befehl, den die Prüfliste dem Menschen nennt.
    if [ -z "$smoke" ]; then
        echo "    ✗ Kein TEAM_SMOKE_TEST konfiguriert — ohne Verifikationsbefehl wird nicht" >&2
        echo "      automatisch quittiert." >&2
        return 1
    fi
    # BL-232: Verifiziert wird mit dem STUFEN-Befehl (schnell, wenn
    # konfiguriert). Die Messung ist die ZWEITE desselben Stands — die Rolle
    # hat ihn selbst gefahren; im Feld waren das bei vier Stufen rund 32
    # Minuten reine Doppelmessung. Sie bleibt (die Rolle hat nicht quittiert,
    # ihr Ergebnis ist also nicht belegt), wird aber BENANNT und gemessen.
    local voll="$smoke"
    smoke="${TEAM_SMOKE_TEST_SCHNELL:-$smoke}"
    # BL-320: Kann dieser Befehl hier ueberhaupt laufen? Sonst ist der Baum
    # nicht rot, sondern ungeprueft — und die Meldung muss das sagen.
    if ! team_smoke_umgebung_pruefen "$smoke"; then
        echo "      Es wird NICHT automatisch quittiert: Der Baum ist nicht rot, er ist ungeprüft." >&2
        return 1
    fi
    # BL-207: Kein zweiter Lauf neben einen laufenden stellen. Zwei
    #     gleichzeitige Testlaeufe kollidieren, und das Ergebnis waere eine
    #     Eigenschaft der MASCHINE statt eine des Codes.
    # BL-315: ...aber auch nicht aufgeben. Der laufende ist meist der der
    #     Rolle, die ihn gestartet und nicht abgewartet hat (im Feld schob sie
    #     sogar die Warteschleife in den Hintergrund) — das Warten ist genau
    #     der Schritt, den sie nicht geschafft hat. Die Selbstpruefung
    #     uebernimmt ihn, bis zur Frist, und misst danach selbst.
    if team_smoke_parallel_lauf; then
        local frist t0w laeuft=1 vergangen gemeldet=0
        frist="$(team_selbstpruefung_wartefrist)"
        t0w=$(date +%s)
        if [ "$frist" -gt 0 ]; then
            echo "    … Es läuft noch ein Verifikationslauf — meist der der Rolle, die ihn gestartet und nicht abgewartet hat." >&2
            echo "      Gefunden: $TEAM_SMOKE_PARALLEL_ZEILE" >&2
            echo "      Die Selbstprüfung wartet bis zu ${frist} s auf sein Ende, statt einen zweiten danebenzustellen (Kit-BL-315) …" >&2
        fi
        while [ "$laeuft" -eq 1 ]; do
            vergangen=$(( $(date +%s) - t0w ))
            [ "$vergangen" -ge "$frist" ] && break
            if [ $((vergangen - gemeldet)) -ge 60 ]; then
                echo "      … läuft nach ${vergangen} s noch" >&2
                gemeldet=$vergangen
            fi
            sleep 2
            team_smoke_parallel_lauf || laeuft=0
        done
        if [ "$laeuft" -eq 1 ]; then
            echo "    ? Es läuft bereits ein Verifikationslauf — Ergebnis UNBEKANNT, nicht rot (Kit-BL-207)." >&2
            [ "$frist" -gt 0 ] && echo "      Er lief nach ${frist} s Wartezeit immer noch (Kit-BL-315)." >&2
            echo "      Gefunden: $TEAM_SMOKE_PARALLEL_ZEILE" >&2
            echo "      Ein zweiter Lauf daneben kollidiert (Datenbankdateien, Ports," >&2
            echo "      Nutzerverzeichnisse) und meldete ROT für einen Baum, der allein gefahren" >&2
            echo "      grün ist. Es wird deshalb NICHT automatisch quittiert und NICHTS behauptet." >&2
            echo "      Miss von Hand nach, wenn der laufende Test fertig ist: $voll" >&2
            return 1
        fi
        echo "    ✓ Der laufende Verifikationslauf ist beendet ($(( $(date +%s) - t0w )) s gewartet) — jetzt misst die Selbstprüfung selbst (Kit-BL-315)." >&2
    fi
    echo "    … Smoke-Test läuft ($smoke) — zweite Messung desselben Stands, die Rolle hat ihn schon gefahren (Kit-BL-232) …" >&2
    local t0 dauer
    t0=$(date +%s)
    if ! $smoke >/dev/null 2>&1; then
        dauer=$(( $(date +%s) - t0 ))
        # BL-232 (3): Flackern vom Regress trennen, BEVOR der Mensch geweckt
        # wird — genau diese Handbewegung loeste den Feldfall auf (16 rote
        # Faelle, allein gefahren gruen).
        echo "    … ROT nach ${dauer} s — ein zweiter Lauf trennt Flackern vom Regress (Kit-BL-232) …" >&2
        if $smoke >/dev/null 2>&1; then
            echo "    ? Der zweite Lauf ist GRÜN — das Rot war flackernd oder lastbedingt, nicht reproduzierbar (Kit-BL-232)." >&2
            echo "      Nicht automatisch quittiert: Ein flackernder Baum ist ein Befund für den Menschen, kein grüner." >&2
            return 1
        fi
        echo "    ✗ $smoke ist ROT. Auch der zweite Lauf war rot — kein Flackern." >&2
        echo "      Das gehört an den Menschen: Erst prüfen, WO — sind ausschließlich die von" >&2
        echo "      DIESER Stufe neu angelegten Testdateien rot, ist der Testaufbau der" >&2
        echo "      wahrscheinlichere Schuldige als der Produktivcode (Kit-BL-61)." >&2
        # BL-201: Der Befund kann eine Eigenschaft des LAUFS statt des Codes
        # sein. Ein Hintergrundlauf, den die Rolle angestossen und nie zu Ende
        # gefuehrt hat, hinterlaesst einen halben Zustand (halb geschriebene
        # Datenbankdateien, belegte Ports) — im Feld meldete die
        # Selbstpruefung daraufhin ROT, obwohl der Baum gruen war. Ein Befund,
        # der als sicher gelesen wird, obwohl er es nicht ist, schickt den
        # Menschen in einen Zweig, der eine fertige Stufe wegwirft.
        echo "      ABER: Dieser Befund ist nicht sicher. Wurde der Test vorher als" >&2
        echo "      Hintergrundlauf angestossen und nie zu Ende gefuehrt, misst du seinen" >&2
        echo "      halben Zustand statt deinen Code. Miss im VORDERGRUND nach, bevor du den" >&2
        echo "      Befund verwendest — und lies das Feld \`result\` im Lauf-Log (Kit-BL-201)." >&2
        return 1
    fi
    dauer=$(( $(date +%s) - t0 ))
    echo "    ✓ $smoke ist grün (${dauer} s)." >&2
    # BL-232 (4): Fruehwarnung statt Deckel. Im Feld blieben 107 s Puffer bei
    # einem Tageswachstum von 198 s — der Riss kam ohne Ankuendigung.
    local frist="${TEAM_SMOKE_TEST_TIMEOUT:-600}"
    if [ "$frist" -gt 0 ] 2>/dev/null && [ $((dauer * 100)) -ge $((frist * 75)) ]; then
        echo "    ⚠ Die Suite braucht ${dauer} s — mehr als 75 % von TEAM_SMOKE_TEST_TIMEOUT (${frist} s). Wächst sie weiter, reißt sie die Frist (Kit-BL-232). Jetzt planen: TEAM_SMOKE_TEST_SCHNELL für die Stufen oder die Frist anheben." >&2
    fi

    echo "[$rolle] Alle drei Prüfungen bestanden — Stufe $stufe wird automatisch quittiert." >&2
    return 0
}

# --- Rollen-Briefings (Stufe 90) ----------------------------------------------
# team_briefing <rolle>: gibt den Inhalt von team/prompts/rolle-<rolle>.md aus —
# ersetzt die frühere Prompt-Zeile "Rolle siehe CLAUDE.md — lies sie zuerst.",
# die jeden Rollenaufruf einen zusätzlichen Voll-Read von CLAUDE.md auslösen
# ließ. Fallback (Pflicht, Selbstbezugs-Risiko dieser Kaskade): fehlt die Datei
# oder ist sie leer, liefert der Helfer exakt die alte Zeile zurück — kein
# Abbruch, keine stderr-Fehlermeldung, damit ein Fehler hier nie einen Lauf
# lahmlegt.
team_briefing() {
    local datei="team/prompts/rolle-$1.md"
    # BL-283: Ralphs Briefing traegt den Satz zur Smoke-Test-Grenze, wie ihn
    # der Installer gerendert hat — in einem frischen Projekt also "noch KEIN
    # Smoke-Test … entfaellt". Baut Stufe 1 ihn, widerspraeche das Briefing
    # bis zum naechsten --update der Konfiguration im SELBEN Prompt. Deshalb
    # wird der Satz hier zur Laufzeit ersetzt, sobald einer bekannt ist.
    local fehlt="Fuer dieses Projekt ist noch KEIN Smoke-Test konfiguriert."
    if [ -s "$datei" ] && [ "$1" = ralph ] && [ -n "${TEAM_SMOKE_TEST:-}" ] \
       && grep -qF "$fehlt" "$datei"; then
        local zeile
        while IFS= read -r zeile || [ -n "$zeile" ]; do
            case "$zeile" in
                *"$fehlt"*)
                    printf '%s%s\n' "${zeile%%"$fehlt"*}" \
                        "Der Smoke-Test (\`${TEAM_SMOKE_TEST}\`) muss gruen sein, bevor die Stufe fertig ist." ;;
                *) printf '%s\n' "$zeile" ;;
            esac
        done < "$datei"
    elif [ -s "$datei" ]; then
        cat "$datei"
    else
        echo "Rolle siehe CLAUDE.md — lies sie zuerst."
    fi
}

# --- Read-Only-Guard (Linie 3 — deterministisch, CHIRURGISCH) -------------------
# team_guard_begin: merkt sich HEAD als Rollback-Punkt UND den Ausgangszustand
#   des Arbeitsbaums (BL-16).
# team_guard_verify <rolle> <whitelist-regex>:
#   Ermittelt geänderte Pfade (committet seit Start + Arbeitsverzeichnis), die
#   NICHT auf die Whitelist passen. Bei Verletzung wird NUR jeder einzelne
#   Verletzer-Pfad zurückgesetzt — niemals blanko `git reset --hard`/`clean -fd`.
#   (Lektion 2026-07-10: ein blindes reset+clean löschte einmal die gesamte
#   uncommittete Team-Infrastruktur. Nie wieder.)
#
# WARUM ES DEN SCHNAPPSCHUSS GIBT (BL-16, Feld K2 2026-08-01)
#   Der Guard hatte KEINEN Ausgangszustand: Er las nur "welche Pfade sind jetzt
#   schmutzig" und schrieb jeden davon der laufenden Rolle zu. Jeder fremde
#   Schreiber — eine parallele Sitzung, eine Handänderung, ein abgebrochenes
#   Werkzeug — wurde damit angelastet UND hart zurückgesetzt. Der Kommentar
#   "schützt parallele/legitime uncommittete Arbeit" galt nur gegenüber dem
#   blanko `reset --hard`, das dieser Guard ablöste; das chirurgische
#   `git checkout -- <pfad>` zerstört fremde Arbeit genauso, nur gezielter.
#   Real eingetreten: Axels korrekte Ermittlung zählte als Fehlschlag (dritte
#   Stagnation → Lauf gestoppt), und die zurückgerollten Pfade waren die
#   unbeteiligte Arbeit einer parallel laufenden Sitzung.
#   Der Schnappschuss hält BLOB-HASHES, nicht nur Pfade: Ein reiner Pfadabgleich
#   würde eine Rolle freisprechen, die eine ohnehin schon schmutzige Datei
#   zusätzlich verändert. Unverändert ⇒ fremd. Verändert ⇒ ihre Sache.
team_guard_schnappschuss() {
    # Je schmutzigem Pfad eine Zeile "<blob-hash> <pfad>". Was sich nicht als
    # Datei lesen lässt (Löschung, Umbenennung, untracked Verzeichnis) bekommt
    # "-" und gilt nur dann als fremd, wenn es das auch bleibt.
    local pfad
    git status --porcelain 2>/dev/null | cut -c4- | while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        if [ -f "$pfad" ]; then
            # BL-271 (2): `-w` legt den Blob in die Objektdatenbank — der
            # Rollback kann damit auf den Stand VOR der Rolle zurueck statt auf
            # den Start-Commit. `--no-filters`: die Bytes des Arbeitsbaums, wie
            # sie dastehen (unter autocrlf sonst die normalisierte Fassung).
            printf '%s %s\n' "$(git hash-object -w --no-filters -- "$pfad" 2>/dev/null || echo -)" "$pfad"
        else
            printf '%s %s\n' "-" "$pfad"
        fi
    done
}

# team_stufen_schnappschuss: nur der Blob-Schnappschuss, ohne Warnung und ohne
# Rohmaterial-Erfassung — fuer Ralph, der je STUFE festhaelt, was schon
# schmutzig war, damit sein Auffangpfad nur Eigenes staged (BL-274).
team_stufen_schnappschuss() {
    TEAM_GUARD_VORHER="$(team_guard_schnappschuss)"
}

team_guard_begin() {
    TEAM_GUARD_HASH="$(git rev-parse HEAD)"
    TEAM_GUARD_VORHER="$(team_guard_schnappschuss)"
    if [ -n "$TEAM_GUARD_VORHER" ]; then
        # Laut warnen, statt still weiterzulaufen: Der Lauf soll gar nicht erst
        # blind starten, und der Mensch am Terminal soll wissen, dass hier zwei
        # Schreiber unterwegs sein könnten.
        echo "[guard] WARNUNG: Der Arbeitsbaum ist beim Rollenstart NICHT sauber:" >&2
        printf '%s\n' "$TEAM_GUARD_VORHER" | sed 's/^[^ ]* /  /' >&2
        echo "[guard] Diese Pfade werden der Rolle nicht angelastet, solange sie unverändert bleiben." >&2
        echo "[guard] Zwei schreibende Instanzen auf einem Arbeitsbaum sind trotzdem unzulässig — bitte committen." >&2
    fi
    # BL-263: Git sieht die Rohmaterial-Zone nicht, also braucht sie ihren
    # eigenen Startstand. Hier statt in jedem Aufrufer: Wer den Guard beginnt,
    # hat damit auch die Zone erfasst.
    team_raw_begin
}

# Pfade aus dem Schnappschuss, die sich seit dem Rollenstart NICHT verändert
# haben. Sie gehören nicht dieser Rolle.
team_guard_fremdpfade() {
    local eintrag hash pfad jetzt
    [ -z "${TEAM_GUARD_VORHER:-}" ] && return 0
    printf '%s\n' "$TEAM_GUARD_VORHER" | while IFS= read -r eintrag; do
        [ -z "$eintrag" ] && continue
        hash="${eintrag%% *}"
        pfad="${eintrag#* }"
        if [ -f "$pfad" ]; then
            jetzt="$(git hash-object --no-filters -- "$pfad" 2>/dev/null || echo -)"
        else
            jetzt="-"
        fi
        if [ "$jetzt" = "$hash" ]; then
            printf '%s\n' "$pfad"
        fi
    done
    return 0
}

# Laufzeitartefakte, die die SHELL um den Rollenaufruf herum schreibt — nicht
# die Rolle. Sie stehen im gitignore-Fragment; fehlt es (Einzug in eine
# gewachsene Codebasis, in der der Anwender das Fragment abgelehnt hat),
# tauchen sie in `git status --porcelain` auf und sähen wie ein Übergriff aus.
#
# BL-24 macht diese Liste zur Pflicht statt zur Kosmetik: Seit der Rollback
# Verzeichnisse wirklich entfernen kann, würde er hier die Kostenlogs DES
# LAUFENDEN AUFRUFS löschen — ein selbstverschuldeter BL-4 (verlorene
# Kostenhistorie), ausgelöst ausgerechnet vom Wächter. Vorher scheiterte das
# `rm -f` an ihnen still; dass das gut ging, war Zufall, kein Entwurf.
#
# BL-269: Zwei Dateien fehlten hier, beide mit eigenem Schaden. Die Gate-Datei
# (BL-256) räumte Franks Rollback mit weg — danach meldete sich der Lauf als
# fertig, während das Gate aus war. `.ralph-uebersprungen` (BL-255) blockierte
# den ZWEITEN planmäßigen Übersprung an Ralphs eigenem Sauberkeits-Riegel. Die
# Gate-Datei ist konfigurierbar, also steht hier ihr Name, nicht der Default.
# Welche Datei hierher gehört, hält test_bl269_laufzeitartefakte_an_allen_stellen.py
# gegen das gitignore-Fragment und gegen die Namen, die der Code schreibt.
_team_gate_re="$(printf '%s' "$TEAM_GATE_DATEI" | sed 's/[][\\.*^$(){}?+|]/\\&/g')"
TEAM_GUARD_LAUFZEIT='^(\.team-logs/|\.ralph-logs/|\.team-protokolle/|\.team-loop\.lock$|\.team-loop\.lock\.d/|\.ralph-state$|\.harry-state$|\.marv-state$|\.vollautomatik-state$|\.ralph-uebersprungen$|\.frank-attempts$|\.team-focus-[a-z]+$|\.budget-ledger\.lock$|'"$_team_gate_re"'$)'

# Werkzeug-Ordner des Stakeholders, die das T.E.A.M. KOMPLETT ignoriert
# (BL-263): weder angelastet noch zurueckgesetzt, weder gelesen noch
# ueberwacht. Heute `.obsidian/` — Obsidian schreibt dort bei jedem Klick
# (workspace.json). Das gitignore-Fragment nimmt den Ordner aus Git; diese
# Ausnahme haelt, wenn die Zeile im Projekt fehlt (vor dem Update angelegt, von
# Hand entfernt). Ohne sie haette der Guard die Arbeitsflaeche des Menschen
# einer Rolle angelastet und zurueckgerollt. Angelegt wird der Ordner vom Kit
# nie — er taucht auf, sobald der Stakeholder das Projekt als Vault oeffnet.
TEAM_GUARD_IGNORIERT='^\.obsidian(/|$)'

# --- Rohmaterial-Zonen des Stakeholders (BL-263) ------------------------------
# TEAM_ROHMATERIAL_ORDNER ist der Eingang des Menschen — eine Leerliste von
# Ordnern (Default `raw/ Clippings/`), in die NUR er ablegt; jede Rolle liest
# dort nur. `raw/` legt der Installer an, `Clippings/` taucht auf, sobald der
# Stakeholder Web-Clippings ablegt. Beide stehen im gitignore-Fragment — Git
# und damit Guard und Rollback sehen sie nicht. Zwei Dinge sichern sie trotzdem:
#
#   * team_pfade_zuruecksetzen fasst keinen Pfad darunter an. Das deckt die
#     Wege, auf denen eine Zone doch in eine Pfadliste geraet: Eine Rolle hat
#     Material mit `git add -f` committet, oder das Fragment fehlt im Projekt.
#     Wie knapp das ist, zeigt BL-24: Dort ueberlebte ein manueller
#     Input-Ordner namens `raw/` nur, weil der Rollback an Verzeichnissen
#     scheiterte. Seit dem Fix haette er ihn geloescht.
#   * Ein Schnappschuss (Pfad, Groesse, Zeitstempel) beim Rollenstart und der
#     Abgleich danach machen jeden Schreibzugriff sichtbar. Gemeldet wird er
#     als Uebergriff; geloescht oder zurueckgesetzt wird NICHTS. Ob eine
#     Aenderung von der Rolle oder vom Stakeholder stammt, ist nicht zu
#     unterscheiden — und fremdes Material wegzuraeumen waere schlimmer als
#     jeder Rest (dieselbe Abwaegung wie in team_fremd_ausfiltern).
#
# Der Wert bleibt, wie die Konfiguration ihn gesetzt hat — normalisiert wird
# nur beim Gebrauch (team_raw_zonen). Die Bibliothek reicht
# Konfigurationswerte unveraendert durch; auf der pwsh-Bahn prueft BL-182 genau
# das, und beide Bahnen sollen hier dasselbe tun.
TEAM_ROHMATERIAL_ORDNER="${TEAM_ROHMATERIAL_ORDNER:-raw/ Clippings/}"

# team_raw_zonen — die Zonen einzeln, je Zeile eine, ohne abschliessenden
# Schraegstrich (so nennen Git-Pfade sie). Ordnernamen mit Leerzeichen werden
# nicht unterstuetzt — dieselbe Grenze wie bei TEAM_WEITERER_CODE.
team_raw_zonen() {
    local -a zonen=()
    local zone
    read -r -a zonen <<< "${TEAM_ROHMATERIAL_ORDNER:-}" || true
    for zone in "${zonen[@]+"${zonen[@]}"}"; do
        zone="${zone%/}"
        if [ -n "$zone" ]; then printf '%s\n' "$zone"; fi
    done
    return 0
}

# team_raw_pfad <pfad> — Exit 0, wenn <pfad> in einer Rohmaterial-Zone liegt;
# auch der Ordner selbst, wie `git status` ihn als EINEN Eintrag meldet.
team_raw_pfad() {
    local zone
    while IFS= read -r zone; do
        case "$1" in
            "$zone"|"$zone"/*) return 0 ;;
        esac
    done < <(team_raw_zonen)
    return 1
}

# team_raw_stand — je Eintrag unter den Zonen eine Zeile, sortiert:
#   "d<TAB><pfad>" fuer Ordner, "f<TAB><pfad><TAB><bytes><TAB><mtime>" sonst,
#   Pfade ab der Repo-Wurzel — wie Git und jede andere Guard-Meldung sie nennen.
# Eine Zone, die es (noch) nicht gibt, traegt nichts bei. Scheitert `find` an
# einem Eintrag, bleibt der Rest gueltig: Eine Pruefung darf den Rollenlauf
# nicht abbrechen.
team_raw_stand() {
    local zone
    while IFS= read -r zone; do
        [ -d "$zone" ] || continue
        find "$zone" -mindepth 1 \( -type d -printf 'd\t%p\n' \) \
            -o \( -printf 'f\t%p\t%s\t%T@\n' \) 2>/dev/null || true
    done < <(team_raw_zonen) | LC_ALL=C sort
    return 0
}

team_raw_begin() {
    TEAM_RAW_VORHER="$(team_raw_stand)"
    TEAM_RAW_ERFASST=1
}

# team_raw_pruefen <rolle>
#   Exit 0 = die Zonen sind unveraendert · 1 = Uebergriff, laut gemeldet.
#   Faengt nie etwas an: kein Loeschen, kein Zuruecksetzen, kein Commit.
team_raw_pruefen() {
    local rolle="$1" nachher abweichung
    if [ "${TEAM_RAW_ERFASST:-0}" != 1 ]; then
        echo "[$rolle] Rohmaterial-Zone (${TEAM_ROHMATERIAL_ORDNER}): kein Startstand erfasst — NICHT geprüft." >&2
        return 0
    fi
    nachher="$(team_raw_stand)"
    if [ "$nachher" = "$TEAM_RAW_VORHER" ]; then
        return 0
    fi
    abweichung="$( { awk -F'\t' '
        NR == FNR { if ($0 != "") vorher[$2] = $0; next }
        $0 != "" { jetzt[$2] = $0 }
        END {
            for (p in jetzt)
                if (!(p in vorher)) print "neu:       " p
                else if (vorher[p] != jetzt[p]) print "geändert:  " p
            for (p in vorher)
                if (!(p in jetzt)) print "entfernt:  " p
        }' <(printf '%s\n' "$TEAM_RAW_VORHER") <(printf '%s\n' "$nachher") || true; } \
        | LC_ALL=C sort -k2)"
    echo "[$rolle] ÜBERGRIFF in der Rohmaterial-Zone (${TEAM_ROHMATERIAL_ORDNER}) — sie gehört dem Stakeholder, jede Rolle liest dort nur:" >&2
    printf '%s\n' "$abweichung" | sed 's/^/  /' >&2
    echo "  Nichts davon wurde angefasst (Kit-BL-263). Stammt eine Änderung nicht vom Stakeholder, hat die Rolle die Zone verletzt — von Hand prüfen." >&2
    return 1
}

# team_fremd_ausfiltern <pfadliste>
#   Entfernt aus <pfadliste> alles, was team_guard_fremdpfade als fremd
#   ausweist — mit einer Feinheit, die beim Bau von BL-114 aufgefallen ist und
#   die auch den Guard betraf:
#
#   `git status --porcelain` meldet ein untracked VERZEICHNIS als EINEN
#   Eintrag mit Schrägstrich (`plans/`), nicht als Liste seiner Dateien —
#   dieselbe Eigenheit, an der BL-24 haengt. Der Startschnappschuss haelt
#   deshalb `plans/` fest. Committet eine Rolle eine fremde Datei aus so einem
#   Ordner versehentlich mit (`git add -A` ist bei bypassPermissions der
#   Normalfall), taucht sie danach als `plans/closeout.md` auf und passt auf
#   KEINEN Eintrag der Fremdliste mehr. Ein reiner Zeichenvergleich haette sie
#   geloescht — also genau die uncommittete Closeout-Ausgabe, wegen der
#   BL-114 geschrieben wurde. Deshalb gilt ein Pfad auch dann als fremd, wenn
#   er UNTER einem fremden Ordnereintrag liegt.
#
#   Bewusst in diese Richtung konservativ: Legt die Rolle eine eigene Datei in
#   einen bereits fremden Ordner, bleibt sie liegen. Ein Rest, der liegen
#   bleibt, ist sichtbar und behebbar; fremde Arbeit, die geloescht wurde, ist
#   weg.
team_fremd_ausfiltern() {
    local liste="$1" fremd pfad eintrag behalten
    [ -z "$liste" ] && return 0
    fremd="$(team_guard_fremdpfade)"
    if [ -z "$fremd" ]; then
        printf '%s\n' "$liste"
        return 0
    fi
    while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        behalten=1
        while IFS= read -r eintrag; do
            [ -z "$eintrag" ] && continue
            if [ "$pfad" = "$eintrag" ]; then
                behalten=0
            else
                case "$eintrag" in
                    */) [ "${pfad#"$eintrag"}" != "$pfad" ] && behalten=0 ;;
                esac
            fi
        done <<< "$fremd"
        [ "$behalten" -eq 1 ] && printf '%s\n' "$pfad"
    done <<< "$liste"
    return 0
}

# team_eigene_pfade <pathspec…>
#   Gibt die abweichenden Pfade unter <pathspec…> aus, die dieser Rolle
#   GEHOEREN — fremde sind ausgefiltert. Leere Ausgabe = nichts Eigenes.
#
#   WARUM ES SIE GIBT (BL-206, Feld B): Der Commit-Block des Red-Team-Sweeps
#   war die DRITTE Stelle mit derselben Zustaendigkeit und die einzige ohne
#   den Filter. team_guard_verify und team_rollback_rolle rufen beide
#   team_fremd_ausfiltern; der Sweep staged stattdessen `git add <testordner>`
#   blanko — und `git add` auf einen Ordner nimmt JEDE untracked Datei darin
#   mit, auch die fremde. Sie landet dann unter der Sweep-Botschaft, also
#   unter einer Urheberschaft, die nicht stimmt. Woertlich die Bauform von
#   BL-114 (dort war der `git clean` eingeschraenkt, das `git reset --hard`
#   daneben nicht): zwei Stellen nachgezogen, die dritte nicht.
#
#   WARUM --untracked-files=all: `git status --porcelain` meldet ein untracked
#   VERZEICHNIS als EINEN Eintrag mit Schraegstrich. Wer den blanko staged,
#   hat wieder den Ordner adressiert statt der Datei — der Fix waere keiner.
#   team_fremd_ausfiltern kennt die Ordner-Schreibweise auf der FREMD-Seite
#   und faengt eine Datei auch unter einem fremden Ordnereintrag ab; die
#   Aufloesung hier kostet also nichts und schliesst die Luecke.
team_eigene_pfade() {
    local roh eigene pfad
    roh="$(git status --porcelain --untracked-files=all -- "$@" 2>/dev/null | cut -c4- | grep -v '^$' || true)"
    [ -z "$roh" ] && return 0
    eigene="$(team_fremd_ausfiltern "$roh")"
    # Sichtbar machen statt still weglassen: Wer den Sweep-Commit liest, soll
    # wissen, dass hier fremde Arbeit lag — und dass sie unangetastet blieb.
    # Ein stilles Auslassen waere die Fehlerrichtung von BL-160.
    while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        if ! echo "$eigene" | grep -Fxq -- "$pfad"; then
            echo "[guard] Nicht angefasst, lag vor dem Rollenstart im Baum (Kit-BL-206): $pfad" >&2
        fi
    done <<< "$roh"
    echo "$eigene"
    return 0
}

# team_eigene_stagen <pathspec…>
#   Staged NAMENTLICH, was dieser Lauf unter <pathspec…> angefasst hat —
#   ohne fremde Pfade (team_eigene_pfade) und ohne Laufzeitartefakte.
#   Exit 0 = etwas gestaged, 1 = nichts Eigenes.
#
#   BL-274: Drei von vier Commit-Stellen umgingen den Fremdfilter, den das
#   Kit fuer genau diesen Zweck hat — Axel stagte den Plan-Ordner blanko (dort
#   liegt die uncommittete Closeout-Ausgabe des Architekten und der Entwurf
#   einer Kit-Meldung), Frank sein Beutebuch, Ralphs Auffangpfad `git add -A`.
#   Ein Mensch konnte waehrend eines Laufs keine Doku-Datei ablegen, ohne dass
#   sie unter einer fremden Botschaft im Commit landete.
team_eigene_stagen() {
    local eigene pfad
    local -a liste=()
    eigene="$(team_eigene_pfade "$@" | grep -Ev "$TEAM_GUARD_LAUFZEIT" \
              | grep -Ev "$TEAM_GUARD_IGNORIERT" || true)"
    while IFS= read -r pfad; do
        [ -n "$pfad" ] && liste+=("$pfad")
    done <<< "$eigene"
    [ "${#liste[@]}" -gt 0 ] || return 1
    git add -- "${liste[@]}" || return 1
    return 0
}

# team_pfade_zuruecksetzen <rolle> <hash> <pfadliste>
#   Setzt JEDEN uebergebenen Pfad EINZELN auf den Stand von <hash> zurueck:
#   beim Start getrackt → `git checkout <hash> -- <pfad>`, neu entstanden →
#   gezielt entfernen. Gibt auf STDOUT die Pfade aus, die danach WEITERHIN
#   abweichen (leer = vollzogen); Meldungen gehen nach stderr.
#
#   Herausgeloest aus team_guard_verify (BL-114). Der Grund ist nicht
#   Aufraeumen: Die Einstiegsskripte rollten bis dahin mit einem blanken
#   `git reset --hard` + `git clean -fd` zurueck — also mit genau dem, was der
#   Kopf dieses Abschnitts sich seit dem 2026-07-10 verbietet. Die Lehre war am
#   Guard angewandt und am Aufrufer nicht. Eine gemeinsame Funktion macht das
#   Auseinanderlaufen unmoeglich, statt es nur zu verbieten.
team_pfade_zuruecksetzen() {
    local rolle="$1" hash="$2" liste="$3" pfad rest=""
    [ -z "$liste" ] && return 0
    while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        if team_raw_pfad "$pfad"; then
            # BL-263: Die Rohmaterial-Zone gehoert dem Stakeholder — nie
            # zuruecksetzen, nie loeschen. Hoechstens aus dem INDEX nehmen, was
            # eine Rolle dort neu eingetragen hat (`git add -f`): Die Datei
            # bleibt liegen, der Ordner bleibt unversioniert.
            if ! git cat-file -e "$hash:$pfad" 2>/dev/null; then
                git rm -r --cached --quiet -- "$pfad" >/dev/null 2>&1 || true
            fi
            echo "[$rolle] Guard: '$pfad' liegt in der Rohmaterial-Zone — Stakeholder-Eigentum, NICHT angefasst (Kit-BL-263)." >&2
            continue
        fi
        # BL-271 (2), BL-206 (2): War der Pfad beim Rollenstart schon
        # geaendert (fremde, uncommittete Arbeit), gehoert der Stand VOR der
        # Rolle hierher — nicht der des Start-COMMITS. Bis hierher holte
        # `git checkout <start> -- <pfad>` den Commit zurueck, und die fremde
        # Arbeit an dieser Datei war weg, nicht wiederherstellbar.
        local blob
        blob="$(printf '%s\n' "${TEAM_GUARD_VORHER:-}" | awk -v p="$pfad" \
                '{ i = index($0, " "); if (i && substr($0, i + 1) == p) { print substr($0, 1, i - 1); exit } }')"
        if [ -n "$blob" ] && [ "$blob" != "-" ] && git cat-file -e "$blob" 2>/dev/null; then
            if git cat-file blob "$blob" > "$pfad" 2>/dev/null; then
                git reset -q -- "$pfad" >/dev/null 2>&1 || true
                echo "[$rolle] Guard: '$pfad' auf den Stand VOR der Rolle zurückgesetzt — er war beim Start schon geändert, diese Arbeit bleibt (Kit-BL-271)." >&2
                continue
            fi
        fi
        if git cat-file -e "$hash:$pfad" 2>/dev/null; then
            # War beim Start getrackt → auf Startstand zurückholen.
            git checkout "$hash" -- "$pfad" 2>/dev/null || true
        else
            # Neu entstanden (committet oder untracked) → gezielt entfernen.
            #
            # `-r` ist hier nötig (Verzeichnisse), und `-r` auf einem Pfad aus
            # `git status` ist genau die Zeile, die man einmal richtig schreibt
            # und nie wieder ansieht. Deshalb die Plausibilitätsprüfung davor:
            # Der Pfad kommt ausschließlich aus `git status --porcelain`
            # innerhalb des Repos, ist also relativ und ohne führenden
            # Schrägstrich. Alles andere wird NICHT entfernt, sondern gemeldet.
            case "$pfad" in
                /*|*..*|"")
                    echo "[$rolle] Guard: '$pfad' sieht nicht nach einem Repo-Pfad aus — NICHT entfernt." >&2
                    rest="$rest$pfad"$'\n'
                    continue ;;
            esac
            git rm -rf --cached -- "$pfad" >/dev/null 2>&1 || true
            rm -rf -- "$pfad"
        fi
        # Der Erfolg wird GEPRÜFT, nicht angenommen. Sonst wiederholt sich die
        # eigentliche Lehre dieses Fundes bei der nächsten Ursache.
        if [ -e "$pfad" ] && ! git diff --quiet "$hash" -- "$pfad" 2>/dev/null; then
            rest="$rest$pfad"$'\n'
        fi
    done <<< "$liste"
    printf '%s' "$rest"
}

# team_rollback_rolle <rolle> <start-hash>
#   Verwirft den GESAMTEN Beitrag eines Rollenlaufs — Commits, Aenderungen an
#   getrackten Dateien und neu angelegte Dateien —, aber NUR seinen.
#
#   BL-114: Hier stand in frank.sh, axel.sh und redteam.sh ein blankes
#   `git reset --hard "$START_HASH"` (in frank zusaetzlich `git clean -fd`
#   ohne Pfadeinschraenkung). Das trifft JEDE uncommittete Arbeit im
#   Zielprojekt, nicht nur die der Rolle: eine parallele Sitzung, eine
#   Handaenderung, eine noch nicht committete Closeout-Ausgabe des
#   Architekten. Der Guard nebenan arbeitet seit derselben Lehre chirurgisch
#   und kennt ueber team_guard_begin sogar den Ausgangszustand des
#   Arbeitsbaums (BL-16) — zwei Zeilen weiter warf der Aufrufer weg, was der
#   Guard gerade sorgfaeltig geschont hatte.
#
#   Drei Dinge bleiben ausdruecklich unangetastet:
#     * Pfade aus dem Startschnappschuss, die sich seither nicht veraendert
#       haben (team_guard_fremdpfade) — fremde Arbeit.
#     * Laufzeitartefakte (TEAM_GUARD_LAUFZEIT) — dort liegen die Kostenlogs
#       DIESES Aufrufs; sie zu loeschen waere ein selbstverschuldeter BL-4.
#     * Gestagte fremde Aenderungen: HEAD wandert mit `--soft` zurueck, der
#       Arbeitsbaum bleibt dabei unberuehrt.
#
#   `git clean -fd` deckte den Fall ab, dass Frank mit bypassPermissions auch
#   AUSSERHALB des Produktivordners Dateien anlegt (HM-29). Das leistet die
#   Pfadliste weiter: `git status --porcelain` meldet jede nicht ignorierte
#   neue Datei im ganzen Repo — nur eben namentlich statt pauschal.
team_rollback_rolle() {
    local rolle="$1" start="$2" eigen="${3:-}" pfade rest fremde="" c betreff
    # BL-236: Der Rollback setzte HEAD auf den beim Start gemerkten Commit
    # zurueck — und warf damit jeden Commit weg, den waehrenddessen ein Mensch
    # in einer zweiten Sitzung gemacht hatte. Im Feld verschwand so ein reiner
    # Doku-Commit (eine Fundliste) still aus der Historie; zurueckgeholt per
    # cherry-pick aus dem Reflog. Die dritte Angabe sagt, welche Commits
    # EIGEN sind: eine Kennung, die ihre Nachricht traegt (bei Frank die
    # Fundnummer, so verlangt es sein Auftrag), oder "-" fuer eine Rolle, die
    # nie committet (Axel, Red Team) — dann ist JEDER Commit fremd. Liegt ein
    # fremder vor, wird nichts zurueckgerollt; der Fall geht an den Menschen.
    # Ohne Angabe bleibt es beim alten Verhalten (alles gilt als eigen).
    while IFS= read -r c; do
        [ -z "$c" ] && continue
        [ -z "$eigen" ] && break
        betreff="$(git log -1 --format=%B "$c" 2>/dev/null)"
        if [ "$eigen" = "-" ] || [ "${betreff#*"$eigen"}" = "$betreff" ]; then
            fremde="$fremde  $(git log -1 --format='%h %s' "$c")"$'\n'
        fi
    done <<< "$(git rev-list "$start..HEAD" 2>/dev/null)"
    if [ -n "$fremde" ]; then
        echo "[$rolle] ROLLBACK ANGEHALTEN — seit dem Rollenstart liegen Commits auf dem Zweig, die nicht diesem Lauf gehören:" >&2
        printf '%s' "$fremde" >&2
        echo "  Ein Zurückrollen würfe sie mit weg (Kit-BL-236). NICHTS angefasst — von Hand prüfen: git log --oneline $start..HEAD" >&2
        return 1
    fi
    pfade="$( { git diff --name-only "$start" HEAD 2>/dev/null;
                git status --porcelain | cut -c4-; } | sort -u \
              | grep -Ev "$TEAM_GUARD_LAUFZEIT" \
              | grep -Ev "$TEAM_GUARD_IGNORIERT" || true)"
    pfade="$(team_fremd_ausfiltern "$pfade")"
    if [ "$(git rev-parse HEAD)" != "$start" ]; then
        git reset --soft "$start" >/dev/null 2>&1 || true
    fi
    rest="$(team_pfade_zuruecksetzen "$rolle" "$start" "$pfade")"
    if [ -n "$rest" ]; then
        echo "[$rolle] ROLLBACK UNVOLLSTÄNDIG — diese Pfade stehen weiterhin abweichend im Baum:" >&2
        printf '%s' "$rest" | sed 's/^/  /' >&2
        echo "  Von Hand prüfen und zurücknehmen." >&2
        return 1
    fi
    return 0
}

team_guard_verify() {
    local rolle="$1" whitelist="$2" roh nicht_angelastet verletzungen raw_rc=0
    # BL-287: WAS gefunden wurde, fuer team_guard_urteil. Der Rueckgabewert
    # allein trennte "Pfad zurueckgerollt" nicht von "nur die Rohmaterial-Zone
    # hat sich geaendert" — und das Urteil meldete fuer beides einen Rollback.
    TEAM_GUARD_BEFUND=""
    # BL-263: Die Rohmaterial-Zone prueft ihr eigener Schnappschuss — Git sieht
    # sie nicht. Ein Uebergriff dort zaehlt wie jeder andere, nur ohne Rollback.
    team_raw_pruefen "$rolle" || { raw_rc=1; TEAM_GUARD_BEFUND="rohmaterial"; }
    roh="$( { git diff --name-only "$TEAM_GUARD_HASH" HEAD 2>/dev/null;
              git status --porcelain | cut -c4-; } | sort -u \
            | grep -Ev "$whitelist" \
            | grep -Ev "$TEAM_GUARD_LAUFZEIT" \
            | grep -Ev "$TEAM_GUARD_IGNORIERT" || true)"
    [ -z "$roh" ] && return "$raw_rc"

    # BL-114: derselbe Filter wie im Rollback — er kennt auch den Fall, dass
    # eine fremde Datei aus einem untracked ORDNER mitcommittet wurde und
    # danach unter ihrem vollen Pfad auftaucht.
    verletzungen="$(team_fremd_ausfiltern "$roh")"
    if [ -n "$verletzungen" ]; then
        nicht_angelastet="$(printf '%s\n' "$roh" \
                            | grep -Fxvf <(printf '%s\n' "$verletzungen") || true)"
    else
        nicht_angelastet="$roh"
    fi

    if [ -z "$verletzungen" ]; then
        # Der Verdacht löst sich auf. Genau dieser Fall wurde im Feld einer
        # Rolle angelastet, die ihn nicht verursacht hatte.
        echo "[$rolle] Guard: Pfade außerhalb der Whitelist geändert, aber ALLE waren beim Rollenstart bereits geändert und sind es unverändert — nicht dieser Rolle zugeschrieben, kein Rollback:" >&2
        printf '%s\n' "$nicht_angelastet" | sed 's/^/  /' >&2
        return "$raw_rc"
    fi

    # Die Meldung trennt die beiden Fälle ausdrücklich sprachlich. Im Feld wurde
    # der Übergriff zunächst der falschen Rolle zugeschrieben, weil die Pfadliste
    # im Log neben ihrem Namen stand — belegt war das nirgends.
    #
    # BL-24: Die Vollzugsmeldung steht bewusst NICHT mehr vor dem Aufräumen.
    # `rm -f` (ohne -r) kann kein Verzeichnis entfernen, und `git status
    # --porcelain` meldet ein untracked Verzeichnis als EINEN Eintrag mit
    # Schrägstrich (`raw/`), nicht als Liste seiner Dateien. Der Rollback
    # scheiterte damit still, während elf Zeilen vorher schon "chirurgischer
    # Rollback" gedruckt war — der Guard behauptete einen Vollzug, den es
    # nicht gab. Im Feld an einem Harry-Sweep beobachtet; dort ein Glücksfall,
    # weil der Ordner erhalten bleiben sollte. Legt eine Rolle selbst ein
    # Verzeichnis an (Wegwerf-Skripte, `__pycache__` unter einem neuen Pfad),
    # bleibt es samt Inhalt liegen, während der Lauf Vollzug protokolliert.
    echo "[$rolle] GUARD-VERLETZUNG — DIESE ROLLE hat die folgenden Pfade geändert:" >&2
    printf '%s\n' "$verletzungen" >&2
    if [ -n "$nicht_angelastet" ]; then
        echo "[$rolle] NICHT angelastet (beim Rollenstart bereits geändert, seither unverändert):" >&2
        printf '%s\n' "$nicht_angelastet" | sed 's/^/  /' >&2
    fi
    local rest p raw_ausgenommen=0
    rest="$(team_pfade_zuruecksetzen "$rolle" "$TEAM_GUARD_HASH" "$verletzungen")"
    while IFS= read -r p; do
        if [ -n "$p" ] && team_raw_pfad "$p"; then raw_ausgenommen=1; fi
    done <<< "$verletzungen"
    if [ -n "$rest" ]; then
        echo "[$rolle] Guard: ROLLBACK UNVOLLSTÄNDIG — diese Pfade stehen weiterhin abweichend im Baum:" >&2
        printf '%s' "$rest" | sed 's/^/  /' >&2
        echo "  Von Hand prüfen und zurücknehmen; der Lauf gilt als Übergriff." >&2
    elif [ "$raw_ausgenommen" -eq 1 ]; then
        # BL-24-Lehre: Die Vollzugsmeldung darf nicht mehr behaupten, als
        # geschehen ist. Die Zone blieb bewusst stehen — das steht hier.
        echo "[$rolle] Guard: chirurgischer Rollback vollzogen — AUSGENOMMEN die Rohmaterial-Zone (siehe oben, von Hand prüfen)." >&2
    else
        echo "[$rolle] Guard: chirurgischer Rollback vollzogen." >&2
    fi
    TEAM_GUARD_BEFUND="rollback"
    return 1
}

# team_guard_urteil <rolle> <uebergriff 0|1> <ergebnis-liegt-vor 0|1>
#   Exit 0 = die Runde zählt · 1 = der Aufruf gilt als gescheitert.
#
# BL-16 Ebene 2 (Stakeholder-Entscheid 2026-08-02): Ein Guard-Übergriff
# kassiert den ÜBERGRIFF, nicht die Arbeit. Liegt das eigentliche Ergebnis der
# Rolle vor, ist die Leistung erbracht — der Grenzübertritt ist bereits
# chirurgisch zurückgerollt und laut gemeldet, und ein zusätzlicher Fehlschlag
# bestraft nur noch das Falsche: Er speist den Stagnationszähler und stoppt den
# Lauf. Genau so ging im Feld ein fertiger, korrekter Ermittlungsbericht als
# "Aufruf fehlgeschlagen" durch. Fehlt das Ergebnis, bleibt es beim Fehlschlag.
team_guard_urteil() {
    local rolle="$1" uebergriff="$2" ergebnis="$3"
    [ "$uebergriff" -eq 0 ] && return 0
    # BL-287: Hat sich NUR die Rohmaterial-Zone geaendert, wurde nichts
    # zurueckgerollt — und meistens war es der Stakeholder selbst, der dort
    # waehrend des Laufs ablegt, wie vorgesehen. Die Meldung sagt, was war,
    # und die Runde zaehlt: Die Notiz des Stakeholders darf nicht zur Haelfte
    # der Begruendung fuer einen gescheiterten Aufruf werden (Axel).
    if [ "${TEAM_GUARD_BEFUND:-}" = "rohmaterial" ]; then
        echo "[$rolle] Rohmaterial-Zone verändert (siehe oben), zurückgerollt wurde nichts. Stammt die Änderung vom Stakeholder, ist nichts zu tun." >&2
        return 0
    fi
    if [ "$ergebnis" -eq 1 ]; then
        echo "[$rolle] Guard-Übergriff kassiert, Ergebnis zählt — die Arbeit ist geleistet, zurückgerollt wurde nur der Grenzübertritt." >&2
        return 0
    fi
    echo "[$rolle] Guard-Übergriff UND kein vollständiges Ergebnis — Aufruf gilt als gescheitert." >&2
    return 1
}

# --- Substanz-Anker für Frank (HM-29) -----------------------------------------
# team_diff_beruehrt_fund <HM-Nr> <start-hash>
# Franks Dreisatz-Verifikation prüfte bislang nur FORM (Promise, Commit-
# Message-Muster, Beutebuch-Status), nie, ob der committete Diff überhaupt mit
# dem gemeldeten Fund zu tun hat — ein Fund konnte so fälschlich als "erledigt"
# verbucht werden, obwohl die eigentliche Fundstelle nie angefasst wurde
# (HM-29). Diese Funktion prüft LOSE, ob mindestens eine der im Beutebuch-Block
# per Backtick referenzierten Dateien (team/tools/beutebuch.py dateien) im Diff
# seit start-hash vorkommt. Nennt der Fund KEINE Datei, gilt die Prüfung als
# bestanden (kein falscher Blocker bei rein beschreibenden Funden).
team_diff_beruehrt_fund() {
    local hm="$1" start="$2" fund_dateien diff_dateien f d
    fund_dateien="$($TEAM_BEUTEBUCH_TOOL dateien "$hm" 2>/dev/null || true)"
    [ -z "$fund_dateien" ] && return 0
    diff_dateien="$(git diff --name-only "$start" HEAD)"
    while IFS= read -r f; do
        [ -z "$f" ] && continue
        while IFS= read -r d; do
            case "$d" in
                *"$f") return 0 ;;
            esac
        done <<< "$diff_dateien"
    done <<< "$fund_dateien"
    return 1
}

# team_reproducer_liegt_vor <HM-Nr>
# BL-28: Der Substanz-Anker oben besteht, sobald IRGENDEINE im Fundblock
# referenzierte Datei im Diff liegt — und das ist regelmäßig die
# Produktivdatei, die der Fix ohnehin anfasst. Im Feld reservierte `HM-30`
# einen Reproducer-Pfad, Franks Fix berührte CHANGELOG und Produktivdatei, die
# Testdatei entstand NIE, und der Anker war zufrieden. Damit ist die
# Absicherung genau dort wirkungslos, wo BL-15 sie einführen wollte.
#
# Diese Funktion prüft die EINE Datei, deren Zweck die Absicherung ist: den
# Pfad aus der `Reproducer-Test`-Zeile. Rückgabe 0, wenn er existiert ODER der
# Fund keine lesbare solche Zeile trägt (dafür ist `beutebuch.py lint` vor dem
# Lauf zuständig, BL-29 — nicht diese Prüfung nach dem Lauf).
# Rückgabe 1 nur im benannten Fall: Pfad reserviert, Datei nicht angelegt.
team_reproducer_liegt_vor() {
    local hm="$1" pfad
    pfad="$($TEAM_BEUTEBUCH_TOOL reproducer "$hm" 2>/dev/null || true)"
    [ -z "$pfad" ] && return 0
    [ -e "$pfad" ] && return 0
    return 1
}

# --- Lock (eine Pipeline zur Zeit) -----------------------------------------------
# Zwei Verfahren, EIN Versprechen. Der Normalfall ist `flock`; fehlt es, nimmt
# das Kit einen Sperrordner.
#
# BL-190: Vorher entschied EINE Bedingung (`if ! flock -n 9`) ueber beides —
# ein FEHLENDES PROGRAMM lieferte dort denselben Nicht-Null-Status wie eine
# BELEGTE SPERRE. Unter Git for Windows gibt es `flock` nicht (es gehoert nicht
# zum MSYS2-Kern, den Git mitliefert), und dort brach damit JEDE Rolle der
# bash-Bahn sofort ab — mit einer Meldung, die auf einen
# Nebenlaeufigkeitskonflikt zeigte, den es nicht gab. Wer ihr folgte, suchte
# einen zweiten Lauf, killte Prozesse oder loeschte die Lock-Datei; nichts
# davon half, weil die Datei nie das Problem war. Dieselbe
# Fehlerklassen-Verwechslung wie BL-173 (ein PATH-Problem als Auth-Fehler) und
# dieselbe Abhilfe: die Klasse TRENNEN, bevor man handelt.
#
# Warum ein ORDNER und nicht "laut ohne Sperre weiterlaufen": `mkdir` ist auf
# jedem POSIX-Dateisystem und unter MSYS atomar — Pruefen und Anlegen sind EIN
# Schritt, es gibt kein Fenster dazwischen. Damit bleibt die Zusicherung "eine
# Pipeline zur Zeit" ERHALTEN, statt gegen eine Meldung getauscht zu werden.
# Zwei Rollen gleichzeitig im selben Arbeitsbaum sind der Schaden, den BL-12
# teuer belegt hat.
#
# Der Ordner ist der ERSATZ, nicht der Normalfall: Wo `flock` da ist, bleibt
# es. Sonst laegen zwei Sperrmechaniken im Feld, und bei einem Vorfall wuesste
# niemand, welche gegriffen hat — genau deshalb sagt der Ersatzweg einmal
# ausdruecklich an, dass er laeuft.
TEAM_LOCK_DATEI=".team-loop.lock"
TEAM_LOCK_ORDNER=".team-loop.lock.d"

# team_flock_vorhanden: Ist `flock` aufloesbar? (0 = ja)
# Reine ABFRAGE, ohne zu melden — Bauart team_cli_vorhanden (BL-173).
team_flock_vorhanden() {
    command -v flock >/dev/null 2>&1
}

# team_flock_fehlt_melden <label>: sagt den Ersatzweg an, mit dem Werkzeug beim
# Namen.
#
# Das ist kein Fehler und keine Warnung, sondern eine Bestandsangabe: Bei einem
# Vorfall muss ohne Nachforschen feststehen, WELCHE der beiden Sperren gegriffen
# hat. Sie erscheint hoechstens einmal je Pipeline — die Kind-Skripte laufen
# unter TEAM_LOCK_HELD=1 und kommen hier nie an.
team_flock_fehlt_melden() {
    echo "[${1:-team}] Hinweis: 'flock' ist auf dieser Maschine nicht vorhanden." >&2
    echo "  Die Sperre läuft deshalb über den Ordner $TEAM_LOCK_ORDNER (gleichwertig, Kit-BL-190)." >&2
    echo "  Das ist KEIN Sperrkonflikt — es läuft keine zweite Pipeline." >&2
}

# team_lock_ordner_verwaist: Haelt den Sperrordner noch ein LEBENDER Prozess?
# (0 = verwaist, darf uebernommen werden)
#
# Die hinterlegte PID ist genau dafuer da. Ohne diesen Teil tauscht man einen
# Fehlalarm gegen einen DAUERHAFTEN: Ein Lauf, der abstuerzt, blockierte sonst
# jeden folgenden, und niemand koennte den Unterschied zu einem echten
# Doppellauf sehen.
#
# Uebernommen wird STILL. Ein toter Prozess haelt nichts — das ist kein Befund,
# und eine Meldung, die nach jedem regulaeren Lauf erscheint, waere nach BL-14
# keine.
team_lock_ordner_verwaist() {
    local pid
    pid="$(cat "$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)"
    # Keine lesbare PID: Der Ordner steht, aber niemand bekennt sich zu ihm —
    # der Lauf ist zwischen mkdir und dem Schreiben gestorben. Als "gehalten"
    # zu werten machte die Ablage dauerhaft unbrauchbar, und zwar durch genau
    # den Fehlalarm, den dieser Eintrag abstellt.
    [ -n "$pid" ] || return 0
    kill -0 "$pid" 2>/dev/null && return 1
    return 0
}

# team_lock_ordner_nehmen <label>: der Ersatzweg. 0 = Sperre gehoert uns.
team_lock_ordner_nehmen() {
    local label="$1" pid
    if ! mkdir "$TEAM_LOCK_ORDNER" 2>/dev/null; then
        if ! team_lock_ordner_verwaist; then
            pid="$(cat "$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)"
            echo "[$label] Eine andere T.E.A.M.-Pipeline läuft bereits ($TEAM_LOCK_ORDNER, PID ${pid:-?}) — Abbruch." >&2
            return 1
        fi
        rm -rf "$TEAM_LOCK_ORDNER"
        if ! mkdir "$TEAM_LOCK_ORDNER" 2>/dev/null; then
            # Zwischen Pruefung und Anlegen war ein anderer schneller. DAS ist
            # der Konfliktfall, und hier heisst die Meldung zu Recht so.
            echo "[$label] Eine andere T.E.A.M.-Pipeline läuft bereits ($TEAM_LOCK_ORDNER) — Abbruch." >&2
            return 1
        fi
    fi
    printf '%s\n' "$$" > "$TEAM_LOCK_ORDNER/pid"
    # BL-199: Zusaetzlich die WINDOWS-PID, wenn der Wirt eine hat. Sie ist das
    # einzige Lebendigkeitsmerkmal, das die pwsh-Bahn auswerten KANN — `$$` ist
    # eine MSYS-PID aus einem eigenen Prozessraum. Gemessen: Git-Bash meldete
    # `$$` = 15946, `Get-Process -Id 15946` fand zeitgleich nichts; ueber
    # /proc/<pid>/winpid dagegen findet PowerShell den Prozess (nachgemessen
    # am 2026-08-28, Hin- und Rueckweg). Unter Linux gibt es die Datei nicht;
    # dann bleibt es bei `pid`, und die pwsh-Seite meldet ehrlich "unbekannt"
    # statt zu raten.
    if [ -r "/proc/$$/winpid" ]; then
        cat "/proc/$$/winpid" > "$TEAM_LOCK_ORDNER/winpid" 2>/dev/null || true
    fi
    team_lock_aufraeumen_anmelden
    return 0
}

# team_lock_aufraeumen_anmelden: gibt den Sperrordner beim Prozessende frei.
#
# Beim flock-Weg macht das der Kernel — der Deskriptor faellt beim Exit weg.
# Ein Ordner faellt nicht weg. Die PID-Uebernahme oben fuehrt zwar auch ohne
# diesen Teil zum Ziel, hinterliesse aber nach JEDEM Lauf ein Verzeichnis in
# der Ablage des Anwenders (dieselbe Gattung wie BL-196).
#
# Gesetzt wird der Trap nur, wenn EXIT noch FREI ist: Ein `trap ... EXIT` aus
# einer Bibliothek ueberschreibt still, was das aufrufende Skript dort schon
# haengen hat — ein teurer Nebeneffekt fuer eine Aufraeumarbeit. Ist EXIT
# belegt, bleibt die PID-Uebernahme der Weg. Sie ist der Grund, warum dieser
# Teil eine Bequemlichkeit sein DARF und keine Zusicherung sein MUSS.
team_lock_aufraeumen_anmelden() {
    if [ -n "$(trap -p EXIT)" ]; then return 0; fi
    trap 'team_unlock' EXIT
}

# team_unlock: Gegenstueck zu team_lock, mit dem pwsh-Zweig gleichgezogen.
# Gibt NUR frei, was dieser Prozess selbst haelt — sonst raeumte ein Lauf die
# Sperre eines fremden weg und machte aus der Zusicherung das Gegenteil.
team_unlock() {
    if [ -d "$TEAM_LOCK_ORDNER" ] \
       && [ "$(cat "$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)" = "$$" ]; then
        rm -rf "$TEAM_LOCK_ORDNER"
    fi
    # Und der flock-Weg: Beim Prozessende faellt der Deskriptor ohnehin weg,
    # aber wer team_unlock RUFT, will die Sperre JETZT los — sonst gaebe die
    # Funktion auf dem einen Weg frei und auf dem anderen nur den Anschein.
    # Auf einem nie geoeffneten Deskriptor ist das folgenlos.
    exec 9>&- 2>/dev/null || true
    unset TEAM_LOCK_HELD
    return 0
}

# team_lock <label>: nimmt die Sperre (non-blocking). Läuft das Skript
# unterhalb der Vollautomatik (TEAM_LOCK_HELD=1), wird nicht erneut gelockt.
team_lock() {
    if [ "${TEAM_LOCK_HELD:-0}" = "1" ]; then return 0; fi
    if team_flock_vorhanden; then
        exec 9>"$TEAM_LOCK_DATEI"
        if ! flock -n 9; then
            echo "[$1] Eine andere T.E.A.M.-Pipeline läuft bereits ($TEAM_LOCK_DATEI) — Abbruch." >&2
            return 1
        fi
    else
        team_flock_fehlt_melden "$1"
        team_lock_ordner_nehmen "$1" || return 1
    fi
    export TEAM_LOCK_HELD=1
}

# team_pipeline_laeuft [wurzel]: Haelt gerade jemand die Sperre?
#   0 = ja   1 = nein   2 = UNKLAR (BL-199)
#
# Der dritte Zustand ist der Inhalt von BL-199 und keine Bequemlichkeit: Es
# gibt seit BL-190 ZWEI Sperrartefakte, und ihr Lebendigkeitsmerkmal ist nicht
# auf jeder Bahn auswertbar. Wer daraus ein Ja/Nein presst, luegt in eine von
# beiden Richtungen — und beide Luegen sind teuer: "idle" auf einen laufenden
# Lauf ist ein Bericht, dem man nicht mehr glauben darf; "laeuft" auf einen
# toten Rest ist der Dauer-Fehlalarm, den BL-190 gerade abgestellt hat.
# Der Aufrufer entscheidet, was Vorsicht bei IHM heisst: der BL-10-Schutz im
# Installer bricht bei 2 ab, der Statusbericht sagt "unbekannt".
#
# BL-190 ist eine GATTUNG, keine Stelle (BL-154): Die Frage "laeuft gerade eine
# Pipeline?" wird an DREI Orten gestellt — hier, in `team-status.sh` (Zeile
# "Pipeline: laeuft/idle") und in `install.sh` vor einem `--update`. Alle drei
# fragten `flock`, und alle drei gaben ohne `flock` die falsche Antwort:
#
#   * `install.sh` las `! flock -n … true` als "gehalten", weil ein fehlendes
#     Programm Nicht-Null liefert — ein `--update` brach also ab, sobald die
#     Datei ueberhaupt existierte. Derselbe Fehler wie in `team_lock`, an einer
#     zweiten Stelle.
#   * `team-status.sh` hatte `command -v flock` davor und meldete deshalb
#     "idle" — was ab jetzt falsch ist, weil der Ersatzweg eine Sperre haelt,
#     von der die Zeile nichts weiss. Ein Bericht, der eine laufende Pipeline
#     als idle ausweist, ist schlimmer als gar keiner.
#
# Beide Mechaniken werden gefragt, und der Ordner zuerst: Wo er liegt, ist er
# die gueltige Sperre.
team_pipeline_laeuft() {
    local wurzel="${1:-.}" pid
    if [ -d "$wurzel/$TEAM_LOCK_ORDNER" ]; then
        pid="$(cat "$wurzel/$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)"
        if [ -n "$pid" ]; then
            # Lesbares eigenes Merkmal: Es wird ausgewertet, und sein
            # Ergebnis gilt. Eine tote PID heisst verwaist — nicht unklar.
            kill -0 "$pid" 2>/dev/null && return 0
        elif [ -s "$wurzel/$TEAM_LOCK_ORDNER/winpid" ]; then
            # BL-199: Kein lesbares `pid`, aber ein `winpid` — der Ordner
            # stammt dann von einem Lauf, dessen Merkmal DIESE Bahn nicht
            # auswerten kann (eine Windows-PID liegt ausserhalb des
            # MSYS-Prozessraums, gemessen). "Verwaist" waere hier eine
            # Behauptung, "gehalten" ebenfalls.
            return 2
        fi
    fi
    if [ -e "$wurzel/$TEAM_LOCK_DATEI" ]; then
        # (a) Der eigene, kooperative Weg.
        if command -v flock >/dev/null 2>&1 \
           && ! flock -n "$wurzel/$TEAM_LOCK_DATEI" true 2>/dev/null; then
            return 0
        fi
        # (b) BL-199: Dieselbe Datei haelt die pwsh-Bahn mit FileShare::None —
        # eine Sperre, die das BETRIEBSSYSTEM durchsetzt und die `flock` nicht
        # sieht. Gemessen: Ein Schreib-Oeffnen scheitert dann mit "Device or
        # resource busy". Unter Linux setzt .NET FileShare nicht durch, dort
        # gelingt das Oeffnen immer — die Probe ist also genau dort still, wo
        # sie nichts zusichern koennte. In einer SUBSHELL, damit der Deskriptor
        # 9 des Aufrufers (team_lock!) unangetastet bleibt.
        if ! ( exec 9>>"$wurzel/$TEAM_LOCK_DATEI" ) 2>/dev/null; then
            return 0
        fi
    fi
    return 1
}

# --- Ergebnis-Prüfung --------------------------------------------------------
# team_result_is_error <json-datei>
# Rückgabe 0, wenn die JSON-Ausgabe von `claude -p` einen Fehler meldet
# (is_error) oder gar nicht lesbar ist — dann greift z. B. Ralphs API-Fallback.
team_result_is_error() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(0)
sys.exit(0 if data.get("is_error") else 1)
' "$1"
}

# team_bewerte_ergebnis <rolle> <out-datei> <cli-exit-code>
# HM-33: Der reine Prozess-Exit-Code der `claude`-CLI darf ein geschriebenes
# Erfolgs-JSON (is_error:false) nicht überstimmen — z. B. endet die CLI bei
# gesetztem ANTHROPIC_API_KEY mit einer reinen "connectors disabled"-Warnung
# und Exit≠0, obwohl das Ergebnis inhaltlich erfolgreich ist. Das geschriebene
# JSON ist die letzte Instanz: Rückgabe 1 (Fehler) NUR wenn team_result_is_error
# zutrifft (Datei nicht lesbar ODER is_error:true) — der CLI-Exit-Code fließt
# nur noch in die Warnzeile ein, nicht mehr in die Erfolgs-/Fehler-Entscheidung.
team_bewerte_ergebnis() {
    local rolle="$1" out="$2" cli_exit="$3"
    if team_result_is_error "$out"; then
        return 1
    fi
    if [ "$cli_exit" -ne 0 ]; then
        echo "[$rolle] CLI-Exit≠0 trotz gültigem Erfolgs-JSON — werte als Erfolg (vermutlich reine CLI-Warnung, siehe HM-33)." >&2
    fi
    return 0
}

# --- Session-Limit (429) -------------------------------------------------------
# Kaskade 9 / Stufe 29 (plans/ralph-kaskade-9-session-limit.md): reine
# Erkennungs-/Parse-Logik. Warten/Retry folgt in Stufe 30.

# team_result_is_429 <json-datei>
# Rückgabe 0, wenn die JSON-Ausgabe von `claude -p` ein Session-Limit (429)
# meldet — über zwei Signale: das starke Feld api_error_status == 429, oder
# (Fallback für CLI-Versionen ohne dieses Feld) das Feld "result" IST IN
# GÄNZE (nicht nur als Teilstring irgendwo enthalten, HM-21) exakt die CLI-
# Systemmeldung "You've hit your session limit · resets HH[:MM]pm[ (Zone)]" —
# die Minuten sind OPTIONAL (BL-32): die CLI schreibt bei vollen Stunden nur
# "resets 3pm" (ohne ":00"), belegt durch den echten Vorfall in
# .ralph-logs/archiv/stufe-49-20260712-134536.json — ohne diese Optionalität
# wurde ein Doppel-429 (Abo UND API) fälschlich als "echter Fehler" (Exit 1)
# statt als Session-Limit gewertet und die Auto-Warte-/Retry-Logik übersprungen.
# belegt durch den echten Vorfall in .team-logs/harry-20260711-184756.json
# ("You've hit your session limit · resets 6:50pm (Europe/Berlin)", ganzes
# result-Feld, num_turns 1: die CLI liefert diesen Satz unverändert und
# OHNE umgebenden Fließtext, weil dabei nie ein Modell-Turn stattfindet).
# HM-19 hatte den Anker bereits auf "hit your session limit" + wortgrenzen-
# geschütztes Reset-Muster verengt, blieb aber ein Teilstring-Suche — dadurch
# genügte weiterhin ein Claude-generierter Erklärtext, der das Beutebuch/den
# Kaskade-9-Plan wörtlich zitiert (HM-21: genau dieses Zitat steht jetzt
# dauerhaft im Repo). Ein bloßes Zitat mitten in längerem Fließtext hat immer
# zusätzliche Wörter davor/danach im result-Feld und besteht den vollständigen
# Abgleich (re.fullmatch auf den getrimmten String) deshalb NICHT mehr.
# Nicht lesbare Datei → kein 429 (Rückgabe 1), das bleibt Sache von
# team_result_is_error.
team_result_is_429() {
    "$TEAM_PYTHON" -c '
import json, re, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)
if data.get("api_error_status") == 429:
    sys.exit(0)
text = str(data.get("result") or "").strip()
# BL-32: Minuten optional (\d{1,2}(:\d{2})?) — die CLI schreibt bei vollen
# Stunden nur "resets 3pm" ohne ":00" (echter Vorfall stufe-49).
pattern = r"you.ve hit your session limit\s*[·\-–:]\s*resets\s+\d{1,2}(:\d{2})?\s*[ap]m(\s*\([^)]*\))?\.?"
if re.fullmatch(pattern, text, re.IGNORECASE):
    sys.exit(0)
sys.exit(1)
' "$1"
}

# team_429_reset_epoch <json-datei>
# Liest die Reset-Uhrzeit aus dem freien Ergebnistext ("resets HH:MMpm",
# 12h-Format, lokale Zeitzone) und gibt einen Unix-Epoch-Zeitpunkt in der
# Zukunft aus. Liegt die geparste Uhrzeit heute schon in der Vergangenheit,
# gilt sie für morgen (Reset über Mitternacht). Kein/unlesbares Datum → leere
# Ausgabe, Exit 1 — der Aufrufer behandelt das wie "Reset unbekannt".
# HM-22: durchsucht wie team_result_is_429 NUR das Feld "result" (nicht den
# kompletten JSON-Dump, der Zitate/andere Felder mit "resets HH:MMpm" enthalten
# kann) und verlangt Wortgrenzen um "resets ... [ap]m" — sonst kann ein Treffer
# aus falscher Fundstelle (z. B. einem Doku-Zitat) einen falschen Reset-
# Zeitpunkt liefern.
team_429_reset_epoch() {
    "$TEAM_PYTHON" -c '
import json, re, sys
from datetime import datetime, timedelta

try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)

text = str(data.get("result") or "")
# BL-32: Minuten-Gruppe optional; bei "resets 3pm" (volle Stunde ohne ":MM")
# ist die Minute 0. Ohne diese Optionalität lieferte die Funktion "Reset
# unbekannt", wodurch die Auto-Warte-/Retry-Logik (Strategie A) übersprungen
# und ein Doppel-429 fälschlich als harter Fehler (Exit 1) behandelt wurde.
m = re.search(r"\bresets\s+(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b", text, re.IGNORECASE)
if not m:
    sys.exit(1)

hour = int(m.group(1)) % 12
if m.group(3).lower() == "pm":
    hour += 12
minute = int(m.group(2)) if m.group(2) else 0
if minute > 59:
    sys.exit(1)

now = datetime.now()
reset = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
if reset <= now:
    reset += timedelta(days=1)

print(int(reset.timestamp()))
' "$1"
}

# --- Kosten ------------------------------------------------------------------
# team_summe_cost_usd <json-datei…>
# Summe von total_cost_usd über MEHRERE Logs — die Kosten EINES team_claude-
# Aufrufs inklusive aller gescheiterten Vorversuche (Abo-Versuch vor dem
# API-Fallback, 429-Zwischenversuche). Fehlende/kaputte Dateien zaehlen als 0.
# Hintergrund (BL-55, real erlebt 2026-08-01, Kaskade 22 Stufe 93): Der Abo-
# Versuch scheiterte NACH 1.6806 USD, der API-Fallback kostete 0.3984 — gemeldet
# und gegen den Pro-Stufe-Cap geprueft wurden nur die 0.3984, weil TEAM_LAST_COST
# allein aus dem FINALEN Log gelesen wurde. Damit war der Cap umgehbar: 4.9 USD
# Abo-Fehlversuch + 4.9 USD API meldeten 4.9 gegen einen 5-USD-Deckel.
team_summe_cost_usd() {
    "$TEAM_PYTHON" -c '
import json, sys
gesamt = 0.0
for pfad in sys.argv[1:]:
    try:
        gesamt += float(json.load(open(pfad)).get("total_cost_usd", 0) or 0)
    except Exception:
        pass
print(f"{gesamt:.10f}")
' "$@"
}

# team_extract_cost_usd <json-datei>
# Liest total_cost_usd aus der JSON-Ausgabe von `claude -p --output-format json`.
team_extract_cost_usd() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
    print(data.get("total_cost_usd", 0) or 0)
except Exception:
    print(0)
' "$1"
}

# --- Kosten-Summierung (zentral, dedupliziert vollautomatik.sh/team-status.sh) -
# Kapselt team/tools/kosten.py — vorher existierte dieselbe Python-Summierung
# doppelt/dreifach als Inline-Heredoc in vollautomatik.sh und team-status.sh.

# team_kosten_summe <dir…>: Gesamtsumme total_cost_usd über alle *.json in
# den angegebenen Log-Ordnern (Abo + API zusammen).
team_kosten_summe() {
    $TEAM_KOSTEN_TOOL summe "$@"
}

# team_kosten_seit <epoch> <dir…>: Summe total_cost_usd nur über *.json, deren
# mtime >= <epoch> ist — die Kosten EINES Laufs (seit dem gemerkten Startpunkt),
# nicht lebenslang. Grundlage der Pro-Lauf-Deckel-Durchsetzung in vollautomatik.sh
# (BL-18, Stakeholder-Entscheid: „Pro-Lauf-Deckel = operative Grenze,
# Gesamtrahmen nur dokumentiert" — CLAUDE.md/BL-13). Der lebenslange Kontostand
# bleibt team_kontostand_gesamt (Anzeige, nicht Durchsetzung).
team_kosten_seit() {
    local seit="$1"; shift
    $TEAM_KOSTEN_TOOL summe --since "$seit" "$@"
}

# team_kosten_split <dir…>: wie team_kosten_summe, aber getrennt nach
# Abo-Gegenwert (nicht abgerechnet) und real abgerechneter API — Ausgabe
# "abo<TAB>api" (Klassifizierung über den Dateinamen, siehe team_claude:
# API-Fallback-Logs enden auf "-api-fallback.json").
team_kosten_split() {
    $TEAM_KOSTEN_TOOL summe --split "$@"
}

# team_ledger_summe [pfad]: historische Basissumme aus der committeten
# .budget-ledger (append-only, Stufe 18 in
# plans/ralph-kaskade-6-budget-governance.md). Kommentarzeilen (#) und
# Leerzeilen werden ignoriert; fehlende Datei ergibt 0.
team_ledger_summe() {
    $TEAM_KOSTEN_TOOL ledger "${1:-.budget-ledger}"
}

# team_ledger_domaene <website|team> [pfad]: Ledger-Summe gefiltert auf eine
# Domaene (BL-29, Kaskade 13/Stufe 41/44). Altzeilen ohne Domaenenfeld (vor
# Kaskade 13) zaehlen hier NIE mit — sie bleiben "unzugeordnet" (Differenz aus
# team_ledger_summe minus website minus team).
team_ledger_domaene() {
    local domaene="$1" pfad="${2:-.budget-ledger}"
    $TEAM_KOSTEN_TOOL ledger "$pfad" --domaene "$domaene"
}

# team_ledger_split [pfad]: wie team_ledger_summe, aber die usd-Spalte nach
# auth-Bucket getrennt — Ausgabe "abo<TAB>api<TAB>gemischt" (BL-17-Restpunkt/
# BL-29-"1b", Kaskade 16/Stufe 53). "gemischt" sammelt alles, was NICHT exakt
# auth=="abo" oder auth=="api" ist (v. a. "abo/api", aber auch Altzeilen ohne
# auth-Wert) — ehrlich statt geraten, es gilt immer
# abo+api+gemischt == team_ledger_summe.
team_ledger_split() {
    $TEAM_KOSTEN_TOOL ledger "${1:-.budget-ledger}" --split
}

# team_akteur_abschluss <rolle> <auth:abo|api> <usd> <domaene:website|team>
# [notiz] [pfad] [repo]: rollen-agnostischer A1-Abschluss (BL-33, Kaskade 15/
# Stufe 51) — duenner Wrapper um `kosten.py akteur-abschluss` fuer JEDE
# interaktiv (ausserhalb team_claude) arbeitende Rolle (Architekt, Frank im
# Abomodus, …), analog den bestehenden team_ledger_*-Wrappern. Alle Werte
# gehen als eigene argv-Elemente an Python (kein `python -c` mit roher
# Interpolation — Lehre aus BL-23/HM-17). pfad/repo optional, Default wie
# kosten.py (".budget-ledger"/"."), damit Fixture-Tests isoliert gegen ein
# Test-Ledger pruefen koennen.
# BL-26: Alles ab Position 8 sind Schalter des WERKZEUGS (--kaskade,
# --addieren, --ersetzen) und werden unveraendert durchgereicht. Vorher
# endete der Wrapper bei Position 7 und liess alles Weitere kommentarlos
# fallen — im Feld buchte ein Aufruf mit `--kaskade vor-23` dadurch auf die
# Kaskade aus .ralph-plan und ersetzte dort eine abgeschlossene Zeile ueber
# 8,4678 USD. Ein Wrapper, der Schalter still verschluckt, ist bei JEDER
# Erweiterung des Werkzeugs eine neue Falle; unbekannte Schalter lehnt
# kosten.py selbst ab, laut statt leise.
team_akteur_abschluss() {
    local rolle="$1" auth="$2" usd="$3" domaene="$4" notiz="${5:-}"
    local pfad="${6:-.budget-ledger}" repo="${7:-.}"
    if [ "$#" -gt 7 ]; then shift 7; else set --; fi
    if [ -n "$notiz" ]; then
        $TEAM_KOSTEN_TOOL akteur-abschluss --usd "$usd" \
            --domaene "$domaene" --rolle "$rolle" --auth "$auth" \
            --notiz "$notiz" --pfad "$pfad" --repo "$repo" "$@"
    else
        $TEAM_KOSTEN_TOOL akteur-abschluss --usd "$usd" \
            --domaene "$domaene" --rolle "$rolle" --auth "$auth" \
            --pfad "$pfad" --repo "$repo" "$@"
    fi
}

# team_architekt_kaskade [plan-datei]: Nummer der AKTIVEN Kaskade, aus dem
# Namen der Plan-Datei gelesen ("plans/ralph-kaskade-13-…" -> "13"). Leer,
# wenn keine Nummer erkennbar ist (frisches Projekt, benannte Kaskade,
# fehlende .ralph-plan) — der Aufrufer entscheidet dann selbst, ob er ohne
# Kaskadenbezug weitermacht.
#
# BL-18: Herausgeloest aus team_architekt_stand, weil die ANZEIGE die Nummer
# braucht, ohne dass die Zwei-Felder-Schnittstelle "USD<TAB>status" um ein
# drittes Feld wachsen muss (die haengt an mehreren Tests und an
# team-status.sh gleichzeitig). Eine Quelle fuer das Muster statt zwei.
team_architekt_kaskade() {
    local plan_datei="${1:-$(team_plan_datei)}"
    # Ein Projekt OHNE erkennbare Kaskadennummer (benannte Kaskade, frisches
    # Projekt) darf den Aufrufer nicht wegreissen. `| head -1` allein leistet
    # das nur unter `set -e`: Unter `set -o pipefail` bestimmt der ERSTE
    # fehlschlagende Teil den Status der Pipeline, also der leere grep (rc 1)
    # — egal was head zurueckgibt. Gemessen (BL-111): `set -e` und `set -eu`
    # gaben rc=0, `set -euo pipefail` riss den Aufrufer weg. Alle bauenden und
    # pruefenden Rollen laufen mit voller Strenge; die Zusicherung muss also
    # dort gelten, wo sie gebraucht wird, nicht nur eine Stufe darunter.
    # BL-209/BL-202: BEIDE Praefixe. `ralph-kaskade-` nennt eine Rolle,
    # obwohl die Datei das ganze Team bindet; kuenftige Projekte bekommen
    # `team-kaskade-`. Bestandsprojekte behalten ihre Namen — beide Formen
    # muessen deshalb NEBENEINANDER erkannt werden. Ohne das schaltet eine
    # Umbenennung diese Ableitung STUMM ab: Sie gibt dann leer zurueck, und
    # leer ist hier ein gueltiger Wert (benannte Kaskade), kein Fehler.
    { printf '%s' "$plan_datei" \
        | grep -oE '(ralph|team)-kaskade-[0-9]+' | grep -oE '[0-9]+' | head -1; } || true
}

# team_bau_notiz [plan-datei]: Notiztext fuer die ralph-(Bau-)Ledgerzeile,
# ABGELEITET aus dem Namen der Plandatei statt vom Menschen abgeschrieben.
# "plans/ralph-kaskade-22-doku-konsolidierung.md" -> "K22 doku-konsolidierung".
# Leer, wenn kein Muster erkennbar ist — dann schreibt kosten.py seinen
# eigenen Vorspann, und niemand behauptet etwas Falsches.
#
# BL-34: --rollen-abschluss schreibt ZWEI Zeilen (roles + ralph) und trug
# bisher in beide DENSELBEN, von Hand getippten Text. Der Mensch denkt beim
# Abschluss an das Red Team, also stand ueber Ralphs vier Baustufen die Notiz
# "Harry/Marv-Sweeps + Frank HM-9/HM-10". Zweimal im Feld passiert, beide Male
# von jemandem, der die Regel kurz vorher gelesen bzw. zitiert hatte — die
# Disziplinloesung traegt hier nachweislich nicht. Diese Ableitung ist die
# Variante (2) der Fix-Skizze: Die Information liegt in .ralph-plan vor und
# ist fuer eine Bau-Zeile die richtige.
team_bau_notiz() {
    local plan_datei="${1:-$(team_plan_datei)}" name nummer thema
    name="$(basename -- "$plan_datei" 2>/dev/null)"
    name="${name%.md}"
    # BL-209/BL-202: beide Praefixe, siehe team_kaskaden_nummer daneben.
    case "$name" in
        ralph-kaskade-[0-9]*|team-kaskade-[0-9]*)
            nummer="$(printf '%s' "$name" | grep -oE '[0-9]+' | head -1)"
            thema="${name#*-kaskade-${nummer}}"
            thema="${thema#-}"
            [ -n "$thema" ] && printf 'K%s %s' "$nummer" "$thema" \
                            || printf 'K%s' "$nummer"
            ;;
        *) ;;
    esac
}

# team_architekt_stand [ledger-pfad] [plan-datei]: liefert "USD<TAB>status"
# fuer die Architekt-Kosten der AKTIVEN Kaskade — BL-28-Hybrid A2->A1
# (Kaskade 13/Stufe 44): Hat der Stakeholder fuer diese Kaskade bereits
# eine echte Architekt-Zeile per `architekt-abschluss` (Stufe 43)
# eingetragen, ist status "echt" und der Wert kommt aus der Ledger. Sonst
# status "geschaetzt" mit der A2-Live-Schaetzung (team_architekt_schaetzung).
# Beide Pfade optional (Default ".budget-ledger"/aktives .ralph-plan) —
# Fixture-Tests koennen so isoliert gegen ein Test-Ledger/-Plan pruefen.
# HM-46: Existenz einer echten Zeile wird ueber die TREFFERANZAHL
# (--anzahl) geprueft, nicht mehr ueber einen Wertevergleich der Summe
# gegen den String "0.0000" — eine echte Zeile mit usd=0.0000 (z. B. eine
# Kaskade, in der der Architekt nachweislich 0 USD kostete) ist am
# Summenwert allein nicht von "keine Zeile vorhanden" zu unterscheiden.
team_architekt_stand() {
    local ledger_pfad="${1:-.budget-ledger}" plan_datei="${2:-$(team_plan_datei)}"
    local kaskade anzahl echt
    kaskade="$(team_architekt_kaskade "$plan_datei")"
    if [ -n "$kaskade" ]; then
        anzahl="$($TEAM_KOSTEN_TOOL ledger "$ledger_pfad" --rolle architekt --kaskade "$kaskade" --anzahl 2>/dev/null)"
        if [ -n "$anzahl" ] && [ "$anzahl" -gt 0 ] 2>/dev/null; then
            echt="$($TEAM_KOSTEN_TOOL ledger "$ledger_pfad" --rolle architekt --kaskade "$kaskade" 2>/dev/null)"
            printf '%s\techt\n' "$echt"
            return 0
        fi
    fi
    # BL-141: NICHT mehr "geschätzt" — der Wert ist Zeilen-Churn mal
    # Eichfaktor, misst also die Groesse des Diffs und nicht die Arbeit.
    # Im Feld lag er 35 % zu niedrig, und die alte Beschriftung liess
    # offen, woraus geschaetzt wurde. Gemessen wird mit
    # `kosten.py sitzung-messen`.
    printf '%s\tChurn-Proxy\n' "$(team_architekt_schaetzung)"
}

# team_architekt_schaetzung: A2-Live-Schaetzung der Architekt-Kosten (BL-28,
# Kaskade 13/Stufe 42) — der Architekt laeuft interaktiv ausserhalb von
# team_claude und schreibt keine total_cost_usd-JSONs. Proxy: Zeilen-Churn
# (git diff --numstat) ueber plans/** + CLAUDE.md seit dem letzten
# .budget-ledger-Commit, mal Eichfaktor (siehe team/tools/kosten.py). Bewusst
# eine GROBE Groessenordnung — Stufe 43 ersetzt sie beim Kaskaden-Abschluss
# durch den echten Konsolenwert (A1). Ohne bisherigen Ledger-Commit (frisches
# Repo) ist die Ausgabe 0.0000 statt eines Abbruchs.
team_architekt_schaetzung() {
    local ref
    ref="$(git log -1 --format=%H -- .budget-ledger 2>/dev/null)"
    if [ -z "$ref" ]; then
        echo "0.0000"
        return 0
    fi
    $TEAM_KOSTEN_TOOL architekt-schaetzung --since "$ref" 2>/dev/null \
        || echo "0.0000"
}

# --- Deckel-Empfehlung (Governance, Stufe 19) --------------------------------
# Der Architekt hinterlegt im Kopf des aktiven Kaskaden-Plans eine Zeile
# `BUDGET_EMPFEHLUNG_USD=<zahl>` (siehe
# plans/ralph-kaskade-6-budget-governance.md). vollautomatik.sh/halbautomatik.sh lesen sie hier
# zentral, statt das grep-Muster mehrfach zu duplizieren.

# team_plan_datei: aktive Plan-Datei aus der Zeiger-Datei .ralph-plan (eine
# Zeile, Pfad — Stufe 20 in plans/ralph-kaskade-6-budget-governance.md). Fehlt
# die Zeiger-Datei, ist die Ausgabe leer — der Aufrufer fällt auf seinen
# Default zurück (kein Abbruch hier; ralph.sh selbst bricht beim Bau ab).
team_plan_datei() {
    # Starterkit-Fix: `|| true` — sonst reisst der RC!=0 einer fehlenden
    # Zeiger-Datei den Aufrufer unter `set -e` weg, obwohl die Doku oben
    # ausdruecklich "kein Abbruch hier" zusagt (frisches Projekt = Normalfall).
    { head -n1 .ralph-plan 2>/dev/null || true; } | tr -d '[:space:]'
}

# team_plankopf_wert <schluessel> <plan-datei>: liest eine `<SCHLUESSEL>=<wert>`-
# Zeile aus dem Kopf einer Plan-Datei. Gemeinsame Ableitung von team_ralph_cap
# und team_budget_empfehlung — zwei Kopien derselben Pipeline waren schon
# einmal der eigentliche Befund (BL-151).
#
# BL-150: DER PLANKOPF IST MARKDOWN, NICHT KONFIGURATION.
#
# Die Anker standen auf `^[[:space:]]*` und lasen den Rest bis Zeilenende. Der
# Architekt legte den Plankopf aber als `**RALPH_CAP=5**` an — und das ist
# nicht sein Fehler: Der uebrige Plankopf (`**Plan:**`, `**Stufen:**`,
# `**Typ:**`) ist durchgehend fett, und sein Briefing verlangte die Zeilen,
# ohne ein Wort ueber Blank-Pflicht zu sagen. Ein Architekt, der sich exakt an
# sein Briefing haelt und dem Stil des eigenen Dokuments folgt, blockierte
# damit den Bau: Ralph stieg mit Exit 1 aus, team-status.sh zeigte `Cap ?`,
# und die Deckel-Anhebung der Vollautomatik bekam nie einen Wert — ein
# fehlender Wert, den niemand vermisst, weil sein Fehlen wie ein bewusst
# niedriger Deckel aussieht.
#
# Gefunden im Feld (Feld D) beim ALLERERSTEN Vollautomatik-Start. Das
# Zeitfenster ist genau ein Plan pro Projekt: Danach wird die Schreibweise vom
# ersten Plan abgeschrieben und der Fehler ist fuer immer unsichtbar.
#
# Geduldet wird deshalb die Auszeichnung, nicht der Sonderfall: fuehrende
# Auszeichnungs- und Aufzaehlungszeichen vor dem Schluessel, nachlaufende
# hinter dem Wert. Die Werte sind Zahlen, also kann alles davon spurlos weg.
team_plankopf_wert() {
    local schluessel="$1" plan="$2"
    [ -n "$plan" ] && [ -f "$plan" ] || return 0
    # `|| true` aus demselben Grund wie in team_architekt_kaskade (BL-111):
    # Eine Plandatei OHNE die Zeile ist der dokumentierte Normalfall, unter
    # `set -o pipefail` machte der leere grep daraus einen Abbruch.
    { grep -E "^[[:space:]*_\`>#+-]*${schluessel}=" "$plan" \
        | head -1 | cut -d= -f2 | tr -d '[:space:]*_`'; } || true
}

# team_ralph_cap [plan-datei]: liest RALPH_CAP aus der angegebenen (oder sonst
# der aktiven) Plan-Datei — dasselbe Muster wie team_budget_empfehlung. Fehlt
# Datei/Zeile, ist die Ausgabe leer.
team_ralph_cap() {
    team_plankopf_wert RALPH_CAP "${1:-$(team_plan_datei)}"
}

# team_budget_empfehlung [plan-datei]: liest BUDGET_EMPFEHLUNG_USD aus der
# angegebenen (oder sonst der aktiven) Plan-Datei. Fehlt Datei/Zeile, ist die
# Ausgabe leer — der Aufrufer fällt dann auf seinen Default zurück (kein
# Abbruch, keine Rateraterei).
team_budget_empfehlung() {
    team_plankopf_wert BUDGET_EMPFEHLUNG_USD "${1:-$(team_plan_datei)}"
}

# team_kontostand_gesamt: kumulierter Kontostand wie `team-status.sh --budget`
# ("Gesamt"-Zeile) = historische .budget-ledger-Basis + aktuelle lokale Logs
# (.ralph-logs + .team-logs).
team_kontostand_gesamt() {
    local basis abo api
    basis="$(team_ledger_summe)"
    IFS=$'\t' read -r abo api <<<"$(team_kosten_split .ralph-logs .team-logs)"
    # kein rohes ${…}-Interpolieren — BL-23/HM-17/HM-34/HM-42: Werte als
    # eigene sys.argv-Elemente uebergeben statt in den Python-Quelltext.
    "$TEAM_PYTHON" -c "import sys; print(f'{float(sys.argv[1]) + float(sys.argv[2]) + float(sys.argv[3]):.4f}')" "$basis" "$abo" "$api"
}

# team_logs_archivieren <dir>: verschiebt die aktuell in <dir> liegenden
# *.json-Rohlogs nach <dir>/archiv/ (bleiben lokal erhalten, zaehlen aber
# wegen des nicht-rekursiven glob() in team/tools/kosten.py nicht mehr in
# team_kosten_summe/team_kontostand_gesamt mit). AUFRUFEN, direkt NACHDEM
# eine neue .budget-ledger-Zeile fuer eine abgeschlossene Kaskade angehaengt
# wurde — sonst zaehlt der Kontostand dieselben Kosten doppelt (Ledger-Zeile
# + Rohlog), siehe BL-17. Ohne diesen Schritt bleibt die Ledger-Zeile die
# einzige Quelle, die je nach Log-Rotation ueberlebt; das war die urspruengliche
# Absicherungsidee hinter der Ledger (siehe Stufe 18,
# plans/ralph-kaskade-6-budget-governance.md) — bislang fehlte nur der
# Vollzug.
#
# BL-4/2026-08-01: Der regulaere Weg laeuft NICHT mehr hierueber. Sowohl die
# .team-logs als auch die .ralph-logs werden vom jeweiligen kosten.py-Verb
# (rollen-abschluss / ralph-abschluss) INTERN archiviert — im selben Prozess
# und auf demselben Snapshot, mit dem gezaehlt wurde (HM-39/AX-4-Fix; ein
# Zwei-Schritt-Ablauf aus Zaehlen hier und Archivieren dort war genau der
# Race). Diese Funktion bleibt als manuelles Werkzeug fuer Sonderfaelle
# bestehen — wer sie aufruft, archiviert OHNE zu ledgern und muss die
# passende Ledger-Zeile selbst verantworten.
team_logs_archivieren() {
    local dir="$1" archiv
    [ -d "$dir" ] || return 0
    archiv="$dir/archiv"
    mkdir -p "$archiv"
    find "$dir" -maxdepth 1 -name '*.json' -exec mv -t "$archiv" {} + 2>/dev/null
    return 0
}

# team_redteam_auftrag <grundauftrag> <stackneutraler-default>
#
# BL-172: Fokus und Grundauftrag VERKETTEN statt gegeneinander ausspielen.
#
# Bis hierher lautete die Kette `${TEAM_REDTEAM_FOCUS:-${GRUNDAUFTRAG:-...}}`
# — ein gesetzter Fokus ERSETZTE den Grundauftrag. Das kollidiert mit einer
# normativen Aussage der Regeldatei: Der Fokus wird bei JEDER Kaskade gesetzt
# und hat kein Verfallsdatum. Wird er pflichtgemaess immer gesetzt, greift der
# Grundauftrag NIE — er wirkte allein in dem Lauf, den es laut Regel nicht
# geben soll. `TEAM_REDTEAM_AUFTRAG_*` war damit strukturell tot.
#
# Die beiden tragen verschiedene Zeitraeume, und genau darum brauchen beide
# Platz: Der Grundauftrag traegt, was sich NICHT pro Kaskade aendert (etwa,
# dass in diesem Projekt personenbezogene Daten Minderjaehriger in einer
# lokalen Datenbank liegen), der Fokus das, was DIESE Kaskade beruehrt. Beides
# zugleich zu brauchen ist der Normalfall, nicht die Ausnahme.
#
# NUR HIER, NICHT BEI SCOPE_LINE: `TEAM_REDTEAM_FOCUS` steuert zwei Dinge, die
# auseinanderfallen — WO geprueft wird (SCOPE_LINE; dort ist Ersetzen richtig,
# ein Fokus schneidet den Umfang bewusst zu) und WORAUF geachtet wird (hier;
# dort ist Ersetzen falsch). Der Fix gehoert an die zweite Stelle.
#
# Der Schaden war leise: Der Sweep laeuft, findet etwas, und niemand sieht,
# dass die dauerhafte Kenntnis der Angriffsflaeche in diesem Lauf gar nicht im
# Prompt stand.
team_redteam_auftrag() {
    local grund="${1:-}" standard="${2:-}" fokus="${TEAM_REDTEAM_FOCUS:-}"
    local basis="${grund:-$standard}"
    # BL-325: Belegt das Projekt sein Laufzeitverhalten ueber ein Log, ist
    # eine Behauptung ohne Beleg ein eigener Fund — gleich, was der Fokus sagt.
    if [ -n "${TEAM_LAUFZEIT_BELEG:-}" ]; then
        basis="${basis}

LAUFZEIT-BELEGE (Kit-BL-325): Dieses Projekt belegt sein Laufzeitverhalten über ${TEAM_LAUFZEIT_BELEG}. Eigene Fundklasse: Laufzeitverhalten, das der Code behauptet, ohne dass eine Logzeile es belegt oder eine Auswerteregel sie liest — und eine Auswerteregel, die nur gegen eine nachgeahmte Testdatei geprüft ist statt gegen eine Zeile im echten Format."
    fi
    if [ -n "$fokus" ]; then
        printf '%s\n\nSCHWERPUNKT DIESER KASKADE (zusaetzlich, nicht statt des Obigen): %s\n' \
               "$basis" "$fokus"
    else
        printf '%s\n' "$basis"
    fi
}

# team_resolve_budget_cap <aktueller-deckel> <user-hat-gesetzt:0|1> <empfehlung>
# Reine Rechenlogik der "nur anheben, nie senken"-Regel (Stakeholder-
# Entscheid 2, Stufe 19) — isoliert testbar ohne echten vollautomatik.sh-Lauf:
#   - hat der User TEAM_BUDGET_USD explizit gesetzt, gewinnt IMMER der
#     aktuelle Wert (auch wenn die Empfehlung höher läge);
#   - sonst gewinnt die Empfehlung, aber nur wenn sie größer als der aktuelle
#     (Default-)Deckel ist — eine niedrigere Empfehlung senkt nie.
# team_budget_cap_hinweis <gefahrener-deckel> <user-hat-gesetzt:0|1> <empfehlung>
#
# BL-185: Die GEGENRICHTUNG war stumm. Gemeldet wurde nur, wenn eine Empfehlung
# den Deckel ANHEBT — wird sie verworfen, stand die falsche Zahl nirgends.
#
# Im Feld: Der Plan empfahl 34, gefahren wurde mit 26 — dem Wert der
# VORKASKADE, der in derselben interaktiven Shell weiterlebte. Folgenlos blieb
# das nur, weil der Lauf mit 18,20 unter beiden Deckeln blieb; ein 8 USD zu
# tiefer Deckel bricht mitten in der Fixphase ab und rollt bezahlte Arbeit
# zurueck (BL-32-Muster).
#
# Der Mensch behaelt den Vorrang — er erfaehrt jetzt nur, dass er ihn ausuebt.
# Der Unterschied zwischen den beiden Werten ist ihre LEBENSDAUER:
# BUDGET_EMPFEHLUNG_USD haengt am Plan und altert mit ihm, TEAM_BUDGET_USD ist
# eine Umgebungsvariable ohne Verfallsdatum.
#
# Isoliert testbar, aus demselben Grund wie team_resolve_budget_cap: Ein
# Nachweis, der einen echten vollautomatik-Lauf braucht, wird nicht gefahren.
# Leere Ausgabe = nichts zu melden.
team_budget_cap_hinweis() {
    local gefahren="$1" user_gesetzt="$2" empfehlung="$3"
    [ -n "$empfehlung" ] || return 0
    [ "$empfehlung" != "$gefahren" ] || return 0
    echo "Deckel: Der Plan empfiehlt $empfehlung USD, gefahren wird mit $gefahren USD."
    if [ "$user_gesetzt" = "1" ]; then
        echo "  Grund: TEAM_BUDGET_USD ist gesetzt und hat Vorrang. Stammt der Wert noch aus einer frueheren Kaskade dieser Shell, jetzt korrigieren — die Empfehlung altert mit dem Plan, die Variable nicht."
    else
        echo "  Grund: Eine Empfehlung senkt den Deckel nie, sie hebt ihn nur an."
    fi
}

team_resolve_budget_cap() {
    local aktuell="$1" user_gesetzt="$2" empfehlung="$3"
    if [ "$user_gesetzt" = "1" ]; then
        echo "$aktuell"; return 0
    fi
    if [ -n "$empfehlung" ] \
       && "$TEAM_PYTHON" -c "import sys; sys.exit(0 if float(sys.argv[1]) > float(sys.argv[2]) else 1)" "$empfehlung" "$aktuell" 2>/dev/null; then
        echo "$empfehlung"; return 0
    fi
    echo "$aktuell"
}

# team_budget_check <kosten> <soft-limit> <label> [hard-limit]
#
# Zwei-Schwellen-Modell (Stakeholder-Entscheid 2026-07-12, HM-32).
# Rückgabe:
#   0 = ok (unter der Warnschwelle)
#   1 = Warnschwelle (80 % des Soft-Limits) erreicht — reiner Hinweis
#   2 = SOFT-Limit überschritten — deutlicher Hinweis; der Aufrufer entscheidet,
#       ob das ein weicher (weitermachen) oder harter (Abbruch) Fall ist:
#         * Frank/Axel behandeln 2 als WEICH (kein Rollback, Fix bleibt gültig),
#         * Ralph/Harry/Marv rufen OHNE hard-limit auf und behandeln 2 als HART.
#   3 = HARD-Limit überschritten — IMMER harter Abbruch (nur bei gesetztem
#       hard-limit > soft-limit möglich; die iterierenden Rollen Frank/Axel).
#
# Rückwärtskompatibel: Ohne <hard-limit> verhält sich die Funktion wie zuvor
# (0/1/2), 2 bleibt "Soft-Limit überschritten". Der neue Zustand 3 tritt nur
# auf, wenn ein sinnvolles hard-limit (> soft-limit) übergeben wird.
team_budget_check() {
    "$TEAM_PYTHON" -c '
import sys
cost = float(sys.argv[1])
soft = float(sys.argv[2])
label = sys.argv[3]
hard = float(sys.argv[4]) if len(sys.argv) > 4 and sys.argv[4] else None

if hard is not None and hard > soft and cost >= hard:
    print(f"HARD-CAP ÜBERSCHRITTEN ({label}): {cost:.2f} USD >= Hard-Cap {hard:.2f} USD — harter Abbruch.")
    sys.exit(3)
if cost >= soft:
    print(f"SOFT-CAP ÜBERSCHRITTEN ({label}): {cost:.2f} USD >= Soft-Cap {soft:.2f} USD.")
    sys.exit(2)
if cost >= 0.8 * soft:
    print(f"WARNSCHWELLE ({label}): {cost:.2f} USD >= 80 % von {soft:.2f} USD — Stakeholder informieren.")
    sys.exit(1)
sys.exit(0)
' "$1" "$2" "$3" "${4:-}"
}