# Bereich: Kanban-Engine (kartenbasierte Themenverarbeitung)
beschreibung: Verteilt einen Themen-Run als Kanban-Board über mehrere Stages und zieht Karten worker-gesteuert durch die Verarbeitung.

## Feature: Themen-Run starten und überwachen [kern]
beschreibung: Initialisiert pro Topic den Laufzeit-Zustand, fährt Worker pro Stage hoch und meldet den Live-Fortschritt der Karten im Fluss.

### Kann für ein Topic einen Lauf starten, Worker hochfahren und live registrieren
einheiten: backend/kanban.py::run_flow

### Kann den Laufzeit-Zustand pro Topic (aktive Worker, Producer, Wachsignal) führen
einheiten: backend/kanban.py::Flow

### Kann sekündlich die Gesamtzahl der Karten im Fluss als deutschen Statustext melden
einheiten: backend/kanban.py::_progress

## Feature: Board und Stages modellieren [kern]
beschreibung: Bildet die Spalten eines Kanban-Boards mit Verarbeitung und Verhaltens-Flags ab und verknüpft Vorgänger-Stages automatisch.

### Kann eine Kanban-Spalte mit zugeordneter Verarbeitung und Verhaltens-Flags (Serial, Drain, Barrier, Gate) beschreiben
einheiten: backend/kanban.py::Stage

### Kann Vorgänger-Spalten automatisch verketten, sodass Barrier-Worker ihre Quellen kennen
einheiten: backend/kanban.py::chain_stages

## Feature: Karten worker-gesteuert abarbeiten [kern]
beschreibung: Pullt Karten aus der Queue der eigenen Stage, hält mehrere Pakete gleichzeitig und wartet reaktiv auf neue Arbeit.

### Kann Karten pullen, mehrere Pakete gleichzeitig halten und beim Stopp alle laufenden Tasks sauber abbrechen
einheiten: backend/kanban.py::_worker

### Kann reaktiv auf neue Arbeit warten, statt dauerhaft zu pollen
einheiten: backend/kanban.py::_sleep_wake

### Kann Ruhe über aktive Worker und Queue-Bestand zuverlässig erkennen und zum Beenden auflösen
einheiten: backend/kanban.py::quiescent

## Feature: Fehler im Karten-Lauf behandeln [kern]
beschreibung: Wiederholt fehlgeschlagene Karten mit exponentiellem Backoff und verschiebt erschöpfte Karten in die Dead-Letter-Stage.

### Kann fehlgeschlagene Karten mit Backoff wiederholen oder als Dead-Letter ablegen, ohne bereits weitergerückte Karten zu bestrafen
einheiten: backend/kanban.py::_fail_package

# Bereich: Pipeline-Steuerung (Guide-Laufzeitverwaltung)
beschreibung: Orchestriert parallele Agent-Aufrufe für einen Guide, verwaltet Stornierung und Fortschritt und stellt Helfer für Prompt-Bau sowie Fehlerformatierung bereit.

## Feature: Guide-Abbruch handhaben [kern]
beschreibung: Markiert einen Guide als abgebrochen, beendet laufende Agent-Slots und gibt die Sperre für einen Neustart wieder frei.

### Kann einen laufenden Guide abbrechen, zugehörige Agent-Slots stoppen und den Datensatz als fehlgeschlagen markieren
einheiten: backend/pipeline.py::cancel_guide

### Kann den Stornierungsstatus eines Guides abfragen
einheiten: backend/pipeline.py::is_guide_cancelled

### Kann nach einem Abbruch die Sperre lösen, damit der Guide neu gestartet werden kann
einheiten: backend/pipeline.py::clear_guide_cancelled

## Feature: Live-Fortschritt und Statusmeldungen [kern]
beschreibung: Schreibt Fortschritt, Schrittnummer und Fehler persistiert und meldet nebenläufige Jobs mit Live-Zähler an einen Reporter.

### Kann Fortschritt, Schrittnummer und Fehlermeldung im Guide-Datensatz persistieren
einheiten: backend/pipeline.py::_set_progress, backend/pipeline.py::_set_step, backend/pipeline.py::_fail

### Kann nebenläufige Jobs mit Live-Zähler an einen Reporter melden und auch bei Ausnahmen weiterzählen
einheiten: backend/pipeline.py::_gather_progress

### Kann Info-Meldungen mit Topic-Präfix einheitlich loggen
einheiten: backend/pipeline.py::_log

## Feature: Parallele Agent-Slots orchestrieren [kern]
beschreibung: Startet mehrere Agent-Slots parallel, sammelt bis zum Quorum gültige Ergebnisse und reagiert auf Stornierung und Infrastrukturfehler.

### Kann mehrere Agent-Slots parallel starten und auf eine konfigurierbare Quorum-Anzahl gültiger Ergebnisse warten, mit Hedging, Grace-Periode und Infrastruktur-Retries
einheiten: backend/pipeline.py::_race

### Kann Pipeline-Parameter einmal bündeln und durch alle Pipeline-Glieder reichen
einheiten: backend/pipeline.py::GenContext

## Feature: Fehler klassifizieren und formatieren [rand]
beschreibung: Erkennt Infrastruktur- von inhaltlichen Fehlern und baut kompakte Fehlertexte für Anzeige und Vergleich.

### Kann Infrastruktur- von inhaltlichen Fehlern anhand einer Markerliste unterscheiden
einheiten: backend/pipeline.py::_is_infra

### Kann Agent-Fehler aus Returncode und Ausgaben zu einer kompakten Meldung formatieren
einheiten: backend/pipeline.py::_claude_error

### Kann aus einer Liste von Slot-Ergebnissen den ersten verwertbaren Fehler auswählen und melden
einheiten: backend/pipeline.py::_gather_error

## Feature: Prompt-Bau und Schemavalidierung [rand]
beschreibung: Stellt Helfer bereit, um Prompts aus Vorlagen aufzubauen, Timeouts zu berechnen und Agent-Antworten zu validieren.

### Kann Prompt-Vorlagen aus dem Templates-Verzeichnis laden und mit Argumenten ausfüllen
einheiten: backend/pipeline.py::_prompt

### Kann zusätzliche Nutzeranweisungen als klar markierten Block an einen Prompt anhängen
einheiten: backend/pipeline.py::_extra

### Kann die Timeout-Dauer eines Schritts als Basis plus skalierten Zuschlag pro Eintrag berechnen
einheiten: backend/pipeline.py::_timeout

### Kann die Probleme-Liste einer Agent-Antwort bereinigen oder leer zurückgeben
einheiten: backend/pipeline.py::_problems_schema

# Bereich: Provider-Konfiguration
beschreibung: Lädt Umgebung und Provider-Defaults, wählt pro Rolle den effektiven Provider samt Modell und überschreibt Tuning-Werte zur Startzeit.

## Feature: Umgebung und Defaults laden [kern]
beschreibung: Lädt eine .env-Datei und stellt den Default-Provider als Pflicht-Voraussetzung für den Start sicher.

### Kann eine .env-Datei laden und damit Umgebungsvariablen setzen, auch über bereits gesetzte Werte hinweg
einheiten: backend/config.py::_load_env

### Kann das System ohne konfigurierten Default-Provider gar nicht starten
einheiten: backend/config.py::DEFAULT_PROVIDER

## Feature: Provider-Stacks und Rollen-Routing [kern]
beschreibung: Stellt mehrere unabhängige Provider-Stacks bereit und routet Agent-Rollen optional auf alternative Provider um.

### Kann mehrere unabhängige Provider-Stacks (Cloud-Auth, API-Key, lokal) mit Modellen und Authentifizierung bereitstellen
einheiten: backend/config.py::PROVIDERS

### Kann die vier Agent-Rollen prozessweit auf alternative Provider umleiten
einheiten: backend/config.py::ROLE_ROUTING

### Kann für eine Rolle das effektive (Provider, Modell)-Paar unter Berücksichtigung von Overrides und "provider:model"-Syntax liefern
einheiten: backend/config.py::resolve_role

## Feature: Schritt-Timeouts und Tuning-Overrides [rand]
beschreibung: Definiert pro Agent-Schritt eine Timeout-Paarung und erlaubt numerische Tuning-Overrides per JSON zur Startzeit.

### Kann pro Agent-Schritt ein Timeout-Paar (Basis, Pro-Eintrag) zentral definieren
einheiten: backend/config.py::TIMEOUTS

### Kann numerische Tuning-Konstanten aus einer JSON-Umgebungsvariablen zur Startzeit überschreiben
einheiten: backend/config.py::_apply_param_overrides
