feat(knowledge): Context-Aware Delegation und Microtasking-Policy

AGENTS.md

@@ -7,7 +7,7 @@ Pi-Package (`pi-package`), das Firstmate bei Crew-Routing und Quota-Balance unte
 - Installierbare Extension: `package.json` → `"pi": { "extensions": ["./index.ts"] }`
 - Tools: `crew_route`, `crew_balance`, `crew_apply_dispatch`, `crew_suggest_primary`, `crew_discover`, `crew_evidence`, `crew_update_check`
 - Knowledge: Drei-Ebenen System
-  - Basis: `knowledge/*.json` (Task-Klassen, Provider, Profile)
+  - Basis: `knowledge/*.json` (siehe `knowledge/README.md`)
   - Hersteller: `knowledge/manufacturers/` (Official Docs, Manufacturer Claims)
   - Benchmarks: `knowledge/benchmarks/` (Artificial Analysis, HumanEval, etc.)
   - Lokale Evidenz: `knowledge/local/` (no-mistakes Outcomes, privacy-conscious)
@@ -16,6 +16,7 @@ Pi-Package (`pi-package`), das Firstmate bei Crew-Routing und Quota-Balance unte
   - `evidence.ts`: Lokale Evidenz-Sammlung aus no-mistakes
   - `knowledge-layers.ts`: Drei-Ebenen Knowledge System mit Conflict Resolution
   - `update.ts`: Compatibility Checks und Firstmate-Version-Awareness
+- Delegation/Microtasking (Policy, kein paralleles Routing): `knowledge/delegation.json`, `knowledge/context-pack.json`, `docs/` (siehe `docs/README.md`)
 
 ## Was es nicht ist
 

CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md

README.md

@@ -68,6 +68,14 @@ Schema der Dispatch-Datei entspricht Firstmate `docs/examples/crew-dispatch.json
 
 Ohne aufgelöstes Home (`FM_HOME` oder Fallback `FM_ROOT_OVERRIDE`) nur Dry-Run/Anzeige — **keine** Writes. Writes gehen ausschließlich nach `<Home>/config/…` (explizites Tool mit `dryRun=false`).
 
+## Delegation & Microtasking (Policy)
+
+Context-aware Delegation und Microtasking sind **Knowledge/Policy** — Firstmate bleibt Authority für Spawn, Approval und `quota-array-dispatch`.
+
+- Doku: [`docs/README.md`](docs/README.md)
+- Tabellen: `knowledge/delegation.json`, `knowledge/context-pack.json`
+- Beispiele: [`examples/`](examples/), Evaluation: [`evaluation/delegation-cases.md`](evaluation/delegation-cases.md)
+
 ## Knowledge-Pack
 
 Datengetrieben unter [`knowledge/`](knowledge/):
@@ -124,6 +132,7 @@ Tests laufen ohne Netzwerk gegen Fixture-JSON unter `tests/fixtures/`.
 - **Phase 3 (Update)**: `tests/update.test.ts` – Compatibility Checks, Version Detection
 - **Phase 4 (Compatibility)**: Alle Tests prüfen Dispatch-Schema, Harness-Verfügbarkeit, Effort-Werte
 - **Phase 5 (Evidence)**: `tests/evidence.test.ts` – Privacy-conscious Metric Collection, Aggregation
+- **Delegation Knowledge**: `tests/delegation-knowledge.test.ts` – JSON-Struktur für Delegation/Context-Pack, Ownership, Evaluation A–H
 
 Alle Tests müssen grün sein (`npm test`).
 

docs/README.md

@@ -0,0 +1,31 @@
+# Dokumentation — Delegation & Microtasking
+
+Policy und Beispiele für Firstmate-Orchestrierung. **Ersetzt Firstmate nicht** — siehe Firstmate `AGENTS.md`.
+
+| Dokument | Inhalt |
+| --- | --- |
+| [delegation-policy.md](delegation-policy.md) | Delegate-first, erlaubte Eigenarbeit, Entscheidungsmodus |
+| [context-aware-microtasking.md](context-aware-microtasking.md) | Context Dependency, wann (nicht) splitten |
+| [context-sufficiency.md](context-sufficiency.md) | Context Pack, Sufficiency Gate |
+| [approval-policy.md](approval-policy.md) | Legitime Freigaben, Crewmate→Captain |
+| [firstmate-failure-modes.md](firstmate-failure-modes.md) | Failure-Katalog, Abweichungstabelle, Grill-Checkliste |
+
+## Knowledge JSON
+
+| Datei | Inhalt |
+| --- | --- |
+| `../knowledge/delegation.json` | Execution modes, dependency levels, evidence chain |
+| `../knowledge/context-pack.json` | Pflichtfelder Context Pack |
+
+## Beispiele & Evaluation
+
+- [`../examples/`](../examples/) — sechs Szenarien
+- [`../evaluation/delegation-cases.md`](../evaluation/delegation-cases.md) — Fälle A–H
+
+## Tools (unverändert)
+
+`crew_route`, `crew_balance`, `fm-spawn` — Routing bleibt Firstmate + `quota-array-dispatch`.
+
+## Evidenz-Pfade
+
+Status- und Evidence-Spalten mit Prefix **Firstmate** verweisen auf Dateien im [kunchenguid/firstmate](https://github.com/kunchenguid/firstmate)-Checkout (bzw. `$FM_HOME`), nicht auf dieses crew-knowledge-Paket. Relative Pfade ohne Prefix (`docs/…`, `knowledge/…`, `examples/`) sind lokal hier.

docs/approval-policy.md

@@ -0,0 +1,63 @@
+# Approval Policy
+
+Legitime vs. illegitime Freigaben — für Firstmate, Crewmates und Gates. **Keine zweite Approval-Engine** in crew-knowledge.
+
+> Evidenz mit Prefix **Firstmate** bezieht sich auf den [kunchenguid/firstmate](https://github.com/kunchenguid/firstmate)-Checkout (`$FM_HOME`), nicht auf lokales crew-knowledge. Siehe `docs/README.md` § Evidenz-Pfade.
+
+## Legitim: Captain oder konfigurierte Authority
+
+| Situation | Owner | Evidenz |
+| --- | --- | --- |
+| PR-Merge | Captain explizit oder `yolo` + grüne CI | Firstmate `AGENTS.md` §1 Rule 2, §7 |
+| Destructive / irreversible / security-sensitive | Captain | Firstmate `AGENTS.md` §1, §7, §9 |
+| Echte **ask-user** Findings (No-Mistakes) | Captain wenn `yolo` off; sonst Firstmate per `ask-user-authority` | Firstmate `AGENTS.md` §7, Firstmate `.agents/skills/ask-user-authority/SKILL.md` |
+| Credentials / Login | Captain | Firstmate `AGENTS.md` §9 |
+| Local-only Merge | Konfigurierte Merge-Authority | Firstmate `AGENTS.md` §7 |
+
+## Nicht legitim (Routine)
+
+Worker oder Firstmate sollen **nicht** stoppen und fragen:
+
+- „Darf ich weiterlesen?“
+- „Nächster Schritt ok?“
+- „Datei X lesen?“
+- „Tests ausführen?“
+- „Autorisierten Auftrag fortsetzen?“
+
+Autorisierte Ship/Scout-Briefs implizieren diese Schritte innerhalb des Scopes.
+
+## Worker darf ask-user nicht selbst beantworten
+
+Firstmate `AGENTS.md` §7: Implementation worker stoppt bei ask-user, Firstmate entscheidet oder eskaliert. Crewmate antwortet via `no-mistakes axi respond` **nur** nach Firstmate-Entscheidung mit `--resolve-key`.
+
+## Crewmate → Captain
+
+| Regel | Status |
+| --- | --- |
+| Crewmates kommunizieren nicht mit Captain | DOKUMENTIERT Hard Rule 4 |
+| Status nur an Firstmate (`state/<id>.status`) | IMPLEMENTIERT Brief-Scaffold |
+| Direkte Captain-Intervention im Crew-Fenster | Erwartet: Firstmate reconciliert (Firstmate `AGENTS.md` §1) |
+
+Klassifikation bei Verstößen: siehe `docs/firstmate-failure-modes.md` § Unangemeldete Crewmate-Interaktion.
+
+## Trust Dialogs (Harness)
+
+Pi/Claude/Codex/Herdr Trust-Prompts: Firstmate bearbeitet nach Spawn über `harness-adapters` (Firstmate `AGENTS.md` §7 Dispatch). Das ist **kein** Captain-Approval für Routinearbeit.
+
+| Ursache | Typ |
+| --- | --- |
+| Harness blockiert Tool bis Trust | HARNESS LIMITATION / EXPECTED (Firstmate handled) |
+| Worker fragt Captain statt Firstmate | FIRSTMATE BUG / Brief-Verstoß |
+| No-Mistakes ask-user Gate | NO-MISTAKES REQUIREMENT |
+
+## Away Mode
+
+`/afk`: Away mode **erweitert** Merge-, ask-user-, destructive- oder security-Authority **nicht** (Firstmate `AGENTS.md` §8).
+
+## Knowledge vs. Firstmate
+
+| | |
+| --- | --- |
+| Approval-Entscheidung | FIRSTMATE EXISTING |
+| Diese Policy (was fragen, was nicht) | KNOWLEDGE / POLICY |
+| Automatische Unterdrückung falscher Trust-UI | FIRSTMATE EXTENSION REQUIRED **[UNVERIFIED]** |

docs/context-aware-microtasking.md

@@ -0,0 +1,84 @@
+# Context-aware Microtasking
+
+Microtasking ist eine **Optimierungsoption**, keine Standardstrategie. Große Aufgabe ≠ viele kleine Aufgaben.
+
+## Grundsatz
+
+Vor jeder Zerlegung:
+
+> Ist diese Teilaufgabe mit **begrenztem, aber ausreichendem** Kontext zuverlässig lösbar?
+
+Wenn nein: kein Microtask — mehr Kontext, Scout, Full-Context-Worker, oder ein größerer Task.
+
+## Context Dependency
+
+| Stufe | Typische Arbeit | Microtasking |
+| --- | --- | --- |
+| **VERY_LOW** | Syntax, Symbolsuche, Muster-Check | Oft sinnvoll; kurzer Kontext |
+| **LOW** | Ein Modul, eine API, begrenzte Tests | Normalerweise sinnvoll |
+| **MEDIUM** | Mehrere Komponenten, Architekturkontext | Nur mit gezieltem Context Pack |
+| **HIGH** | Datenfluss, Auth, Queues, Migrationen, Cross-Service | Nicht blind zerlegen |
+| **VERY_HIGH** | Zentrale Architektur, Security-Modelle, implizite Abhängigkeiten | Full-Context oder Scout→Ship |
+
+Definitionen: `knowledge/delegation.json` → `contextDependency.levels`.
+
+## Wann Microtasking **nicht** besser ist
+
+Prefer **ein Task**, wenn:
+
+- Context Dependency HIGH oder VERY_HIGH
+- Verifikationskosten vieler Slices > ein integrierter Durchlauf
+- Gemeinsamer mutable State oder strikte Reihenfolge
+- Integrationsrisiko an Schnittstellen
+
+Prefer **Microtasks**, wenn:
+
+- VERY_LOW/LOW und klare Grenzen
+- Parallele read-only Scouts
+- Unabhängige Dateien mit getrennten Tests
+- Hohe Parallelisierbarkeit, geringes Merge-Konfliktrisiko
+
+## Compression ≠ Loss
+
+| Zulässig (Compression) | Unzulässig (Loss) |
+| --- | --- |
+| 100 Dateien → 5 relevante + Architekturregeln + API-Verträge | Auf 2 Dateien kürzen, obwohl Entscheidung vom Globalzustand abhängt |
+| Explizite OUT_OF_SCOPE im Brief | Worker soll „Rest des Repos“ selbst erraten |
+
+## Progressive Context Expansion
+
+1. Minimaler Context Pack im Brief
+2. Worker `blocked` oder widersprüchliche Evidenz → gezielte Erweiterung (Dateien, Invarianten)
+3. Erneut Context Dependency prüfen
+4. Erst dann Full-Context-Worker oder Scout
+
+Nicht sofort Full-Context, wenn ein kleiner Pack reichen könnte — aber auch nicht Microtasks ohne Pack.
+
+## Evidence Chain (Worker → Firstmate)
+
+Strukturierte Übergabe zwischen Agenten:
+
+- **FINDINGS** — was gilt
+- **EVIDENCE** — wie belegt (Tests, Logs, Code-Stellen)
+- **FILES** / **SYMBOLS**
+- **CONFIDENCE** — high / medium / low
+- **OPEN_QUESTIONS**
+- **RECOMMENDATION**
+
+Keine unbelegten Behauptungen. Bei Widerspruch: **keine blinde Synthese** — Konflikt benennen, mehr Evidenz oder größerer Kontext-Task.
+
+Firstmate erzwingt dieses Format heute **nicht** strukturell (NICHT VORHANDEN); Brief-Vorlage in `examples/` und Policy hier.
+
+## Modell-/Harness-Wahl
+
+Nach Modus und Dependency Brief schärfen, dann bestehenden Dispatch nutzen (`crew_route`, `quota-array-dispatch`, `fm-spawn`). Context Dependency VERY_LOW rechtfertigt günstigere Profile **nur** wenn Qualitätsboden (`task-classes.json` `qualityFloor`) passt.
+
+## Bezug zu crew-knowledge Tools
+
+| Tool | Rolle bei Microtasking |
+| --- | --- |
+| `crew_route` | Harness/Model/Effort pro Task-Klasse — **nicht** Zerlegung |
+| `crew_balance` | Quota bei parallelen Microtasks |
+| `crew_apply_dispatch` | Optional NL-Regeln in `crew-dispatch.json` |
+
+Kein neues Routing in diesem Paket.

docs/context-sufficiency.md

@@ -0,0 +1,71 @@
+# Context Sufficiency
+
+Ein Microtask darf erst delegiert werden, wenn der **Context Pack** ausreicht. Worker dürfen nicht „irgendwie herausfinden“ müssen.
+
+Schema: `knowledge/context-pack.json`.
+
+## Pflichtfelder
+
+| Feld | Inhalt |
+| --- | --- |
+| **TASK** | Konkrete Aktion für diesen Worker |
+| **GOAL** | Akzeptiertes Ergebnis |
+| **RELEVANT FILES** | Lesen/Ändern — leer nur bei VERY_LOW lokal |
+| **RELEVANT SYMBOLS** | APIs, Typen, Routen, Config-Keys |
+| **DEPENDENCIES** | Upstream/Downstream, Services, Daten |
+| **KNOWN CONSTRAINTS** | Invarianten, Konventionen, Verträge |
+| **EXPECTED OUTPUT** | Patch, Report-Abschnitt, Testliste, … |
+| **OUT OF SCOPE** | Explizite Ausschlüsse |
+
+## Bedingt: SYSTEM CONTEXT
+
+Wenn Context Dependency **MEDIUM+** oder implizite Konventionen relevant:
+
+- Architektur-Zusammenfassung
+- State Machines, Event-Flüsse
+- Auth-/Security-Grenzen
+- Retry/Failure-Verhalten
+- Externe Abhängigkeiten
+
+## Sufficiency Gate
+
+Frage vor Spawn:
+
+> Könnte ein Worker das ohne versteckten Globalzustand erledigen?
+
+| Antwort | Aktion |
+| --- | --- |
+| Ja | Microtask oder Direct Delegation |
+| Nein | Pack erweitern, Scout, Full-Context, oder Zerlegung verwerfen |
+
+## Context Dependency Check (vor Zerlegung)
+
+Prüfliste (aus `context-pack.json`):
+
+1. Globale Invarianten
+2. API-/Datenmodell-Verträge
+3. State Machines / Events
+4. Nebenläufigkeit
+5. Security Boundaries
+6. Retry / Failure / externe Deps
+7. Implizite Projektkonventionen
+
+Was könnte ein Worker **ohne** Gesamtverständnis falsch entscheiden? → in **KNOWN CONSTRAINTS** oder **SYSTEM CONTEXT** aufnehmen.
+
+## Integration in Firstmate-Briefs
+
+Firstmate `bin/fm-brief.sh` ersetzt `{TASK}` mit Auftragstext — **Firstmate** muss Context-Pack-Felder im Brief-Body ergänzen, wenn Microtasks geplant sind.
+
+> Evidenz mit Prefix **Firstmate** bezieht sich auf den [kunchenguid/firstmate](https://github.com/kunchenguid/firstmate)-Checkout (`$FM_HOME`). Siehe `docs/README.md` § Evidenz-Pfade.
+
+Status Firstmate:
+
+| Mechanismus | Status |
+| --- | --- |
+| Brief-Scaffold mit `{TASK}` | IMPLEMENTIERT (Firstmate `bin/fm-brief.sh`) |
+| Validiertes Context-Pack-Schema | NICHT VORHANDEN (Policy in crew-knowledge) |
+| Automatische Pack-Generierung | NICHT VORHANDEN |
+
+## Beispiele
+
+Siehe `examples/microtask-with-context-pack.md` und `examples/not-microtaskable.md`.

docs/delegation-policy.md

@@ -0,0 +1,92 @@
+# Delegationsrichtlinie
+
+Operationalisiert Firstmates bestehende Orchestrator-Rolle (Firstmate `AGENTS.md` §1, §7). **Kein Ersatz** für Firstmate `fm-spawn`, `quota-array-dispatch` oder `config/crew-dispatch.json`.
+
+> Evidenz mit Prefix **Firstmate** bezieht sich auf den [kunchenguid/firstmate](https://github.com/kunchenguid/firstmate)-Checkout (`$FM_HOME`), nicht auf lokales crew-knowledge `AGENTS.md`/`docs/`. Siehe `docs/README.md` § Evidenz-Pfade.
+
+## Status Firstmate (Code-Evidenz)
+
+| Verhalten | Status | Evidenz |
+| --- | --- | --- |
+| Firstmate delegiert projektbezogene Arbeit grundsätzlich | DOKUMENTIERT | Firstmate `AGENTS.md` §1: „Outside hard rule 1 … you do not do project-specific work yourself“ |
+| Spawn nur über `fm-spawn.sh` | IMPLEMENTIERT | Firstmate `bin/fm-spawn.sh`, Firstmate `AGENTS.md` §7 |
+| Primary darf Harness-Delegationstools nicht nutzen | IMPLEMENTIERT | Firstmate `bin/fm-subagent-pretool-check.sh`, Firstmate `docs/subagent-guard.md` |
+| Automatischer Delegations-Check vor jeder Primary-Aktion | NICHT VORHANDEN | Kein Gate in Firstmate vor Tool-Use auf `projects/` **[UNVERIFIED: nur negativ durch Codeabsence]** |
+| Kontext-Dependency-Klassifikation | NICHT VORHANDEN | Kein Firstmate-Modul; Policy in `knowledge/delegation.json` |
+
+## Harte Delegationsregel
+
+Für **jede** eingehende Aufgabe zuerst:
+
+> Kann ein Worker das zuverlässig erledigen?  
+> **Ja → sofort delegieren** (Brief, `crew_route` optional, `fm-spawn`).  
+> **Nein →** Ausnahme benennen und dokumentieren.
+
+Nicht: erst selbst analysieren, planen, Dateien lesen, dann „irgendwann“ spawnen.
+
+### Zulässige Firstmate-Eigenarbeit
+
+- Routing, Kontextauswahl, Zerlegung, Abhängigkeiten
+- Statusauswertung (`fm-crew-state.sh`), Ergebnisbewertung, Eskalation
+- Zusammenführung von Worker-Ergebnissen
+- Fleet-/State-Verwaltung, Brief/Spawn/Send/Control
+- Kurze captain-relevante Kommunikation (Firstmate `AGENTS.md` §9 Etikette)
+
+### Unzulässig als Normalfall
+
+- Projektspezifische Implementierung, ausführliche Analyse, Bug-Recherche, Architekturarbeit, Tests/Doku im Projekt
+- Das ist ein **Delegationsfehler**, nicht Effizienz
+
+Ausnahmen (Firstmate bestehend): Hard Rule 1 captain-approved project operation; leere Fleet + shared tracked material; reine Supervision-Reads.
+
+## Kein Firstmate-Flaschenhals
+
+Diese Policy soll **nicht** jede Kleinigkeit durch Firstmate-Kopf laufen lassen.
+
+- Einfache, klar begrenzte Aufgaben: **direkt delegieren**, ohne Microtask-Zerlegung
+- Microtasking nur bei plausibem Vorteil (Parallelität, isolierte Verifikation)
+- `crew_route` / `crew_balance` sind **optional** vor Spawn, kein Pflicht-Audit pro Slice
+
+## Ship vs. Scout vs. Ausführungsmodus
+
+| Konzept | Owner | Bedeutung |
+| --- | --- | --- |
+| **Ship / Scout** | Firstmate Intake (Firstmate `AGENTS.md` §7) | Deliverable-Typ: Code/PR vs. `data/<id>/report.md` |
+| **Execution Mode** | `knowledge/delegation.json` | **Wie** delegiert wird: direct, microtask, context pack, full-context, scout→ship |
+
+Scout→Ship ist kein Duplikat: Scout ist Intake-Klassifikation; „SCOUT_THEN_SHIP“ ist ein Ausführungsmodus bei hoher Unsicherheit.
+
+## Modellwahl
+
+Weiterhin **nur** über bestehenden Firstmate-Dispatch:
+
+1. Firstmate `config/crew-dispatch.json` / `crew_apply_dispatch` (optional)
+2. Firstmate `quota-array-dispatch` bei Profil-Arrays
+3. Konkrete Flags an Firstmate `bin/fm-spawn.sh`
+
+Zusätzliche **Knowledge-Faktoren** (kein paralleles Routing): Context Dependency, Task Complexity, Change Risk, Required Reasoning, Repository Knowledge, Output Requirements. Sie informieren Brief-Inhalt und Moduswahl, nicht einen zweiten Router.
+
+## Entscheidungsmodell
+
+```
+INPUT
+  → Task Complexity
+  → Context Dependency (VERY_LOW … VERY_HIGH)
+  → Change Risk
+  → Parallelizability
+  → Expected Verification Cost
+  → Microtask Benefit
+  → EXECUTION MODE
+```
+
+Modi: `DIRECT_DELEGATION` | `MICROTASK` | `MICROTASK + CONTEXT PACK` | `FULL-CONTEXT DELEGATION` | `SCOUT → SHIP`
+
+Maschinenlesbar: `knowledge/delegation.json`.
+
+## Ownership-Markierung
+
+| Bereich | Markierung |
+| --- | --- |
+| Spawn, Send, Control, Quota, Merge | FIRSTMATE EXISTING |
+| Context Pack, Dependency Check, Failure-Katalog | KNOWLEDGE / POLICY |
+| Automatischer Delegations-Gate, Evidence-Enforcement | FIRSTMATE EXTENSION REQUIRED |