# Taskboard — Aufgaben statt Delay-Schleifen > **Bauplan zu einem gebauten System.** Dateiformat, Wahrheitsaufteilung Datei/DB, > Scanner-Verhalten und Invarianten. Umgesetzt; der Stand steht in der > [Roadmap](Roadmap.md) 3.2. Die Abschnitte im Präsens beschreiben teils den Zustand > *vor* der Umsetzung — sie begründen den Entwurf. Setzt A1 aus der [Roadmap](Roadmap.md) um. Das Taskboard ist das Fundament, auf dem Audit (A3), Staging (A2), Marktkalender (C1) und das Ergebnisregister (C7/C8) aufsetzen. Es löst zugleich sechs Altpunkte auf einmal (F-A5 Queue, F-A4 Run-Historie, B8 Rekursion, B6 `Task.Delay`-Überlauf, B7 Cron in Lokalzeit, T7 `RunAsync` vs. `ChatAsync`). Aufbau analog zum [Memory-Konzept](Memory-Konzept.md): erst warum die vorhandenen Mechanismen nicht reichen, dann Dateiformat, Wahrheitsaufteilung, Scanner-Verhalten, Invarianten, Migration. ## Das Problem Heute gibt es zwei getrennte, je für sich unzureichende Wege, einen Agenten Arbeit tun zu lassen: - **Der Cron-Scheduler** (`AgentScheduler`, `ToolJobScheduler` — beide inzwischen gelöscht, siehe unten) hing starr am Agenten: eine Cron-Zeile je Agent, ausgeführt über ein `Task.Delay` bis zum nächsten Termin. Ein jährlicher Termin bedeutet ein `Task.Delay` über Monate (B6). Cron läuft in Lokalzeit ohne explizite Zone (B7). Ob mit oder ohne Kontext gelaufen wird, entscheidet ein implizites Flag (`UseChatContext`, T7). - **Die `coordination/*.md`-Dateien** im SharedWorkspace sind die improvisierte Antwort der Agenten darauf, dass es kein Aufgabenmodell gibt: `task_*`-, `status_*`- und `broadcast`-Dateien, per Konvention beschrieben, ohne Schema, ohne Claiming, ohne Zustandsübergänge. Zwei Agenten, die dieselbe Datei „übernehmen", tun das ohne jede Absicherung. Delegation läuft heute über rekursives `send_message`/`spawn` — ein Agent ruft synchron einen anderen, der wieder einen dritten (B8: Zyklengefahr, deshalb ein `LoopGuard` als Notbremse). Es gibt keine Run-Historie am Auftrag und keine Queue. ## Warum ein neues Subsystem, nicht der vorhandene State-Store Dieselbe Überlegung wie beim Gedächtnis: `IStateStore` ist eine Schlüssel-Wert-Tabelle für kleine Marker. Ein Aufgabenmodell mit Status, Zuweisung, Abhängigkeiten und Terminen darin abzulegen hieße, JSON in eine `Value`-Spalte zu schreiben — nicht filterbar, nicht atomar claimbar, nicht auswertbar. Der Kern ist eine **atomare Anspruchsnahme** (Claim). Genau das kann ein Dateisystem nicht verlässlich und der Schlüssel-Wert-Store nicht ausdrücken, eine SQL-Zeile mit einem bedingten `UPDATE` aber sehr wohl. Deshalb eine eigene Tabelle auf dem vorhandenen [`SqliteStorage`](../src/ClawdDotNet.Core/Storage/SqliteStorage.cs) (WAL, `busy_timeout`, prozessweite Schreib-Warteschlange) — dieselbe Grundlage, die schon Gedächtnis, Zustand und Verbrauch teilen. ## Wahrheitsaufteilung — Datei ist Definition, DB ist Koordination Die eine Entscheidung, an der alles hängt: | Ebene | Wahrheit über | Wer schreibt | |---|---|---| | **Markdown-Datei** (Frontmatter + Rumpf) | die *Definition* der Aufgabe: Titel, Priorität, Assignee, Termin, Abnahme, Abhängigkeiten. Menschen- und agentenlesbar. | Mensch (Editor), Agent (`task_*`-Tool) | | **SQLite-Tabelle `Tasks`** | den *Ausführungszustand*: Status, Claim, Lease, Last-Fired-Marker je Termin, Blocker-Auflösung. | ausschließlich das Taskboard selbst (Importer, Scanner, Tool) | **Regel:** Für die Definition ist die Datei die Wahrheit. Für jede Ausführungsentscheidung ist die DB die Wahrheit. Weichen beide ab (Absturz zwischen DB-Claim und Datei-Schreiben), gewinnt die DB, und die Datei wird bei der Reconciliation nachgezogen. Warum nicht alles nur in die DB und die Datei als reine Projektion? Weil die Datei der Bedienpunkt ist: Ein Mensch soll eine Aufgabe im Editor anlegen und ändern können, ein Agent über sein Tool, und beides soll im SharedWorkspace sichtbar und versionierbar bleiben. Warum nicht alles nur in Dateien? Weil das Claiming dort nicht atomar geht — siehe oben. Die Aufteilung nimmt von beidem das Belastbare. Der **Importer** ist die Brücke: Er liest die Frontmatter-Definition und spiegelt sie idempotent in die DB-Zeile (`UPSERT` auf `task_id`). Er läuft beim Start (alle Dateien), nach jeder `task_*`-Änderung (die betroffene Datei) und optional per `FileSystemWatcher` mit Debounce (~500 ms, wie bei A4), damit von Hand editierte Dateien zeitnah einfließen. ## Dateiformat Aufgaben liegen als eine Datei je Aufgabe unter `SharedWorkspace/tasks/`. Der Dateiname ist beschreibend (`recherche-nvda-earnings.md`); die stabile Identität ist die `id` im Frontmatter, nicht der Name — so überlebt eine Aufgabe das Umbenennen. ```markdown --- id: t-8f3a2c # stabil, beim Anlegen vergeben; Wahrheit der Identität title: NVDA Earnings recherchieren status: todo # backlog | todo | in_progress | in_review | done | canceled | blocked type: work # work | approval | human_input priority: 3 # 1 (niedrig) .. 5 (hoch) assignee: "@crawler" # @new | @ | @human when: # optional; fehlt = einmalige Aufgabe, sofort fällig kind: cron # at | every | cron value: "0 7 * * 1-5" tz: Europe/Berlin # PFLICHT, wenn when gesetzt ist — kein Termin ohne Zone require_approval: false # true = gilt erst nach Review (in_review) als done acceptance: | # Abnahmekriterien, gegen die das Ergebnis geprüft wird Aktuelle Zahlen mit Datum und Quelle, in SharedWorkspace/data/nvda.json abgelegt. blocked_by: [t-4b1e] # diese Aufgabe startet erst, wenn alle Blocker done sind onlyWhenMarketOpen: false # C1: Termin nur auslösen, wenn der Markt offen ist --- Freitext-Rumpf: Auftragsbeschreibung, Kontext, Verweise. Geht als Aufgabenstellung an den Agenten. Kommentare (Ergebnisse, Kritik, Reopen) werden unten angehängt. ``` Feldregeln: - **`when.kind`**: `at` (einmaliger Zeitpunkt, ISO 8601), `every` (Intervall, z. B. `30m`), `cron` (5-Felder-Ausdruck wie bisher). `tz` ist bei allen dreien Pflicht — das ist die Antwort auf B7. Die vorhandene [`CronExpression`](../src/ClawdDotNet.Core/Scheduling/CronExpression.cs) rechnet heute zonen-blind in `DateTime.Now`; sie wird in einen zonen-bewussten Aufruf gekapselt (nächsten Termin in `tz` bestimmen, dann in UTC vergleichen). Das verzahnt sich mit R2 (`TimeProvider`) aus der [Teststrategie](Teststrategie.md). - **`assignee`** ersetzt das `UseChatContext`-Flag durch eine explizite Angabe (T7): - `@new` bzw. `@new:` → frischer Lauf ohne Historie (`AgentEngine.RunAsync`). Bloßes `@new` ist nur eindeutig, wenn die Instanz genau **einen** Agenten hat; sonst benennt `@new:` den Ziel-Agenten. Ist er nicht auflösbar, scheitert der Dispatch mit klarer Meldung, statt einen falschen Agenten zu raten. - `@` → bestehender Agent mit seinem Kontext (`AgentEngine.ChatAsync`) - `@human` → wartet auf einen Menschen; kein Modell-Lauf - **`type`**: `work` (Standard), `approval` und `human_input`. Bei den letzten beiden ist ein Mensch der Assignee; seine Antwort **ist** das Ergebnis und Input für Folgeaufgaben. Kein Sonderpfad — nur ein Assignee, der kein Modell ist. ## Scanner-Verhalten Ein einziger Takt (~60 s) statt vieler langer `Task.Delay`. Damit kennt das System keine Monats-Delays mehr (B6), und ein verpasster Takt ist ein verpasster Termin, kein Zeitbombe. Je Takt: 1. **Fällige Termine bestimmen.** Aus jeder aktiven Task-Zeile den nächsten Termin in ihrer `tz` berechnen und gegen „jetzt" prüfen. Ein Termin ist durch einen **Occurrence-Key** eindeutig: `task_id` + geplante Feuerzeit (bei `at`/`cron`/`every`). 2. **Claim vor Lauf (at-most-once).** Bevor gelaufen wird, wird der Occurrence-Key atomar beansprucht: ```sql UPDATE Tasks SET claim_token = @token, claimed_at = @now, last_occurrence = @occ, status = 'in_progress' WHERE id = @id AND status IN ('todo','backlog') AND (last_occurrence IS NULL OR last_occurrence < @occ) AND (claim_token IS NULL OR claimed_at < @leaseCutoff); ``` Genau eine Zeile betroffen = Anspruch gewonnen. Ein zweiter, gleichzeitiger Takt findet die Bedingung nicht mehr erfüllt (Rowcount 0) und läuft **nicht** — so wird ein doppelter Tick zu einem Lauf. 3. **Dispatch nach Assignee.** `@new` → `RunAsync`; `@` → `ChatAsync`; `@human` → kein Lauf, Status bleibt/wird `in_review` bzw. `todo`, die UI zeigt die Aufgabe als wartend. Der Rumpf (+ Abnahmekriterien) ist die Nachricht an den Agenten. 4. **Abschluss verbuchen.** Last-Fired-Marker setzen (`last_occurrence = @occ`), Status fortschreiben, Claim lösen. Bei `require_approval` → `in_review` statt `done`. Der Lauf wird am Task verknüpft (Grundlage für A3-Receipts und die Run-Historie F-A4). **Kein Retry-Sturm.** Der Marker wird auch bei einem **fehlgeschlagenen** Lauf gesetzt: ein fehlgeschlagener Lauf bleibt der einzige Versuch für diesen Termin. Wiederholung ist eine bewusste Entscheidung (neuer Termin oder Reopen), kein Automatismus. Das schützt vor einem Agenten, der bei jedem Takt erneut in denselben Fehler läuft und Budget verbrennt. **Serialisierung mit den Chat-Läufen (B2).** Der Scanner ruft die Engine über dieselben Einstiegspunkte wie WebView, ToolJob und AgentComm. `ChatAsync` ist bereits je Agent über ein `SemaphoreSlim`-Gate serialisiert ([`AgentEngine`](../src/ClawdDotNet.Core/Engine/AgentEngine.cs)) — der Scanner fügt sich dort ein, statt einen zweiten, konkurrierenden Pfad in den geteilten Konversationskontext aufzumachen. Der Claim ist eine **DB**-Grenze (welcher Termin wird behandelt), das Agent-Gate eine **Kontext**-Grenze (kein verschränkter Nachrichtenstrom). Beide werden gebraucht; keine ersetzt die andere. ### Startup-Reconciliation Beim Start wird Soll (Frontmatter) gegen Ist (DB-Marker/Claims) abgeglichen, statt verpasste Läufe still zu überspringen: - Alle Task-Dateien importieren (UPSERT), gelöschte Dateien in der DB als `archived` markieren. - **Stale Claims freigeben:** Ein Claim, dessen `claimed_at` älter ist als die Lease-Dauer (ein während des Laufs abgestürzter Prozess), wird verworfen — die Bedingung `claimed_at < @leaseCutoff` im Claim-`UPDATE` erledigt das ohnehin, die Reconciliation stellt den Status zusätzlich von `in_progress` auf `todo` zurück. - **Verpasste Termine erkennen:** Liegt der letzte planmäßige Termin nach dem Last-Fired-Marker, ist ein Lauf ausgefallen. Er wird als solcher gemeldet (Log, später A5), nicht heimlich verschluckt. Ob nachgeholt wird, ist Politik — Standard: einmal nachholen, sonst würde ein über Nacht ausgeschalteter Rechner beim Start eine Welle auslösen. ## Die drei Invarianten Der Scanner-Kern ist in der Roadmap als der heikle Teil markiert (die Fehlerklasse, die hier schon einmal schiefging). Er wird strikt gegen diese Invarianten gebaut und mit Property-Tests (FsCheck, siehe Teststrategie) abgesichert: 1. **Nie zwei Claims auf einen Task-Termin.** Garantiert durch das bedingte `UPDATE`: Rowcount ≤ 1 pro Occurrence-Key. Test: N parallele Claims auf denselben Key → genau einer gewinnt. 2. **Kein Dispatch bei offenem Blocker.** Eine Aufgabe mit unerfüllten `blocked_by` ist nicht `todo`, sondern `blocked`, und die Claim-Bedingung (`status IN ('todo','backlog')`) greift nicht. Test: Blocker offen → kein Lauf; letzter Blocker `done` → genau ein Auto-Dispatch. 3. **Doppelter Tick = ein Lauf.** Zwei Takte im selben Fenster konkurrieren um denselben Occurrence-Key; der Claim lässt nur einen durch. Test: zwei gleichzeitige `ScanOnce` → ein Lauf, ein Marker. Diese drei sind keine Kür, sondern die Bedingung dafür, dass der Kern mit einem schwächeren Modell umgesetzt werden darf. ## Abhängigkeiten und Eskalation - **`blocked_by` mit Auto-Dispatch:** Wird eine Aufgabe `done`, sucht das Board alle Aufgaben, deren `blocked_by` sie enthält. Sind für eine davon **alle** Blocker `done`, wechselt sie `blocked → todo` und der Scanner nimmt sie beim nächsten Takt auf. - **Blocker-Eskalation:** Meldet ein Agent einen Blocker (`task_update status=blocked` mit Begründung), fällt die Aufgabe und der Zuständige (Lead/Benutzer) wird benachrichtigt. Bis A5 (Matrix) steht, geht das über den vorhandenen Log-/UI-Weg. ## Zusammenspiel mit Staging (A2) und Reopen - **`require_approval` / `in_review`:** Eine Aufgabe mit `require_approval: true` gilt nach dem Lauf nicht als `done`, sondern als `in_review`. Das ist der natürliche Andockpunkt für A2: Die Freigabe erzeugt einen Folge-Task, der den Agenten mit dem eingefrorenen Aufruf weckt (so bleibt der Lauf regulär beendet, kein pausierter In-Memory-Zustand — genau die Architektur-Vorgabe aus der Roadmap-Einstufung für A2). - **Reopen/Feedback:** Ergebnis + Kritik gehen per `task_comment` an **denselben** Agenten zurück (`ChatAsync` in dessen Kontext), statt eine neue Aufgabe von vorn zu beginnen. Die Aufgabe kehrt nach `todo`/`in_progress` zurück, der Verlauf am Task bleibt erhalten. ## Agenten-Tool Ein Tool `Taskboard` im Muster von `MemoryTool` (eine Aktion je Aufruf), das über einen neuen `ITaskRepository` auf dem `AgentToolContext` arbeitet (analog `IMemoryRepository? Memory`): | Aktion | Zweck | |---|---| | `task_create` | Aufgabe anlegen — schreibt Datei **und** DB-Zeile (über den Importer). Vergibt die `id`. | | `task_list` | Aufgaben filtern (Status, Assignee, Betreff). Gekappte, kontextschonende Ausgabe wie bei Memory. | | `task_update` | Status/Felder ändern; `blocked` melden; Ergebnis eintragen. | | `task_comment` | Kommentar/Kritik anhängen; mit Reopen den Zuständigen erneut wecken. | Agent-zu-Agent-Delegation läuft künftig hierüber: Statt rekursivem `send_message` legt ein Agent eine Aufgabe mit `assignee: @` an. Das ist strukturell zyklenfrei (B8) — eine Aufgabe ist ein Datensatz, kein synchroner Aufruf-Stack. **Sicherheit:** Ein Task-Rumpf ist Prompt-Input für den Assignee. Fremdbestimmte Inhalte (Ergebnisse anderer Tools, die in einen Task fließen) werden als Daten gerahmt, nicht als Anweisung — dieselbe Linie wie K2. Irreversibles, das ein Task auslöst, läuft über A2. ## Migration Die `coordination/*.md`-Dateien gehen im Taskboard auf. Die Altdateien haben kein Schema (freies Markdown wie `# Task: …`, `## Status: ASSIGNED`), deshalb bewusst konservativ (`CoordinationMigration`, beim Start ausgeführt): - **`task_*`-Dateien** → einmalig als `backlog`-Aufgaben übernommen: Titel aus der `# Task:`-Überschrift (sonst erste Überschrift, sonst Dateiname), das ganze Markdown als Rumpf, `assignee: @human` als sicherer Default, bis ein Mensch sie zuordnet. `backlog` (nicht `todo`), damit der Scanner nichts unbesehen ausführt. - **`status_*`, `broadcast`, Incident-Berichte, `*.json`-Artefakte** → keine Aufgaben; bleiben unangetastet (später nach A5/Matrix bzw. verfallen als Altbestand). Idempotent durch **Verschieben statt Löschen**: eine übernommene `task_*`-Datei wandert nach `coordination/migrated/` — die Historie bleibt, ein zweiter Start findet sie nicht mehr. Vor der Migration greift die übliche Regel: frisches Backup. ## Ein Takt für alles — Ablösung der Alt-Scheduler Der Scanner ist der **einzige** periodische Treiber. Die früheren `AgentScheduler` und `ToolJobScheduler` (zwei `Task.Delay`-Schleifen mit B6/B7, ungetestet) sind **gelöscht** — alles Periodische ist jetzt ein Task: - **Geplanter Agent-Lauf** (früher `scheduler`-Config) → ein normaler Task mit `when: cron` und Assignee `@new:`. - **Tool-Job-Poll** (früher `toolJobs`-Config, z. B. `telegram_poll`) → ein Task vom Typ **`tool_job`** mit `tool_name`/`job_type`. Beim fälligen Termin tickt der Dispatcher den `IToolJobProvider` und weckt den Zielagenten (Assignee) nur, wenn der Tick etwas meldet — mit oder ohne Kontext, je nach `ToolJobResult`. Zwei Feinheiten, die dabei geradegezogen wurden: - **Wiederkehrende Tasks** (`cron`/`every`/`tool_job`) kehren nach dem Feuern auf `todo` zurück statt auf `done` — sonst liefe ein Cron-Task nur ein einziges Mal. Der Last-Fired-Marker verhindert weiterhin, dass **derselbe** Termin doppelt feuert. - **`backlog` ist ein Halte-Status**: Der Scanner claimt nur `todo`. Eine Aufgabe in `backlog` (frisch importiert, migriert, oder ein deaktivierter Poll) ruht, bis ein Mensch sie auf `todo` setzt. Die Alt-Konfiguration (`scheduler`, `toolJobs`) wird beim Start einmalig und nicht-destruktiv in Tasks migriert (`SchedulerTaskMigration`, stabile Ids `sched-` / `tj--`). Ein manuelles „Jetzt ausführen" im Host läuft über `TaskScanner.RunTaskNowAsync`. ## Verzahnung - **C1 Marktkalender:** `onlyWhenMarketOpen` gehört ins Frontmatter, nicht in einen eigenen Mechanismus — der Scanner überspringt einen Termin, wenn der Markt zu ist. - **A3 Audit/Receipts:** Jeder Lauf wird am Task verknüpft; der Abschluss-Beleg (Schritte, Tokens, Kosten) fällt daraus ab und macht C7 weitgehend zum Abfallprodukt. - **F-A5/F-A4:** Das Board **ist** die Queue; die verknüpften Läufe **sind** die Historie. ## Umsetzungsreihenfolge Bewusst so geschnitten, dass der heikle Kern zuletzt und gegen grüne Invarianten kommt: 1. **Modelle + `ITaskRepository` + Schema + Frontmatter-Parser.** Reine, testbare Bausteine. Der Parser wird eng gebaut (die Frontmatter ist ein kleiner, flacher Satz aus Skalaren und kurzen Listen) — keine YAML-Bibliothek, passend zum dependency-armen Stil des Projekts. 4.6-tauglich. 2. **`Taskboard`-Tool + Importer.** Datei ↔ DB, `task_*`-Aktionen. 4.6-tauglich. 3. **Scanner-Kern** (Claim, Dispatch, Reconciliation, Auto-Dispatch) — strikt gegen die drei Invarianten, mit Property-Tests. Der in der Roadmap für Opus 5/Fable markierte Teil; mit Opus 4.8 nur streng nach diesem Dokument und mit den Invarianten-Tests als Netz. 4. **Migration** der `coordination/*.md`. Neue Subsysteme kommen mit Tests nach der [Teststrategie](Teststrategie.md); die Invarianten-Tests sind bei Punkt 3 die Absicherung, kein Nice-to-have. ## Offen - **Nachhol-Politik verpasster Termine** — umgesetzt als „höchstens einmal nachholen": der Scanner nimmt den jüngsten verpassten Termin, nicht jeden einzelnen. Eine frische Aufgabe holt zudem keinen Termin von **vor** ihrer Anlage nach. Ob das je Task abschaltbar sein soll (`catchUp: true|false`), ist offen. - **Marktkalender (C1)** — der Scanner fragt eine `IMarketCalendar` (derzeit Platzhalter „immer offen"). C1 liefert später den echten Kalender; die Verzahnung steht. - **DST-Randfall** — eine bei der Zeitumstellung nicht existierende Ortszeit (Frühjahr, „02:30") wird derzeit übersprungen statt verschoben. Für die geplanten Termine unkritisch; die Härtung gehört zur Scheduler-Nacharbeit (Teststrategie R4/R5). - **Priorität als Reihenfolge** — bei mehreren fälligen Aufgaben desselben Agenten bestimmt `priority` die Reihenfolge; ob strikt oder gewichtet, ist noch offen. - **Aufräumen** — `done`/`canceled`-Aufgaben nach einer Frist archivieren, damit `tasks/` nicht zuwächst (dieselbe Überlegung wie „Verfall" beim Gedächtnis).