From 69c3be7e91b6aaac5de5743d778e1e74326e1b23 Mon Sep 17 00:00:00 2001 From: dtrywets Date: Thu, 20 Aug 2026 22:27:26 +0200 Subject: [PATCH 1/4] Erweitert crew-knowledge um Delegation- und Microtasking-Policy. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fügt knowledge/delegation.json, context-pack.json, Doku unter docs/, Beispiele, Evaluation A–H und Tests hinzu — ohne paralleles Routing. Co-authored-by: Cursor --- AGENTS.md | 1 + CLAUDE.md | 3 +- README.md | 8 + docs/README.md | 27 ++++ docs/approval-policy.md | 61 ++++++++ docs/context-aware-microtasking.md | 84 ++++++++++ docs/context-sufficiency.md | 69 ++++++++ docs/delegation-policy.md | 90 +++++++++++ docs/firstmate-failure-modes.md | 170 ++++++++++++++++++++ evaluation/delegation-cases.md | 102 ++++++++++++ examples/conflicting-microtask-results.md | 43 +++++ examples/full-context-delegation.md | 35 +++++ examples/microtask-with-context-pack.md | 46 ++++++ examples/not-microtaskable.md | 35 +++++ examples/scout-then-ship.md | 41 +++++ examples/simple-microtask.md | 44 ++++++ knowledge/README.md | 4 + knowledge/context-pack.json | 63 ++++++++ knowledge/delegation.json | 183 ++++++++++++++++++++++ package.json | 3 + tests/delegation-knowledge.test.ts | 51 ++++++ 21 files changed, 1162 insertions(+), 1 deletion(-) mode change 120000 => 100644 CLAUDE.md create mode 100644 docs/README.md create mode 100644 docs/approval-policy.md create mode 100644 docs/context-aware-microtasking.md create mode 100644 docs/context-sufficiency.md create mode 100644 docs/delegation-policy.md create mode 100644 docs/firstmate-failure-modes.md create mode 100644 evaluation/delegation-cases.md create mode 100644 examples/conflicting-microtask-results.md create mode 100644 examples/full-context-delegation.md create mode 100644 examples/microtask-with-context-pack.md create mode 100644 examples/not-microtaskable.md create mode 100644 examples/scout-then-ship.md create mode 100644 examples/simple-microtask.md create mode 100644 knowledge/context-pack.json create mode 100644 knowledge/delegation.json create mode 100644 tests/delegation-knowledge.test.ts diff --git a/AGENTS.md b/AGENTS.md index b3d6a8a..1924174 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 47dc3e3..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a9d4d26 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,2 @@ + +@AGENTS.md diff --git a/README.md b/README.md index dbfeea6..0d85f6b 100644 --- a/README.md +++ b/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 `/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/): diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6588648 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,27 @@ +# Dokumentation — Delegation & Microtasking + +Policy und Beispiele für Firstmate-Orchestrierung. **Ersetzt Firstmate nicht** — siehe `AGENTS.md` im Firstmate-Repo. + +| 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`. diff --git a/docs/approval-policy.md b/docs/approval-policy.md new file mode 100644 index 0000000..0914b86 --- /dev/null +++ b/docs/approval-policy.md @@ -0,0 +1,61 @@ +# Approval Policy + +Legitime vs. illegitime Freigaben — für Firstmate, Crewmates und Gates. **Keine zweite Approval-Engine** in crew-knowledge. + +## Legitim: Captain oder konfigurierte Authority + +| Situation | Owner | Evidenz | +| --- | --- | --- | +| PR-Merge | Captain explizit oder `yolo` + grüne CI | `AGENTS.md` §1 Rule 2, §7 | +| Destructive / irreversible / security-sensitive | Captain | `AGENTS.md` §1, §7, §9 | +| Echte **ask-user** Findings (No-Mistakes) | Captain wenn `yolo` off; sonst Firstmate per `ask-user-authority` | `AGENTS.md` §7, `.agents/skills/ask-user-authority/SKILL.md` | +| Credentials / Login | Captain | `AGENTS.md` §9 | +| Local-only Merge | Konfigurierte Merge-Authority | `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 + +`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/.status`) | IMPLEMENTIERT Brief-Scaffold | +| Direkte Captain-Intervention im Crew-Fenster | Erwartet: Firstmate reconciliert (`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` (`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** (`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]** | diff --git a/docs/context-aware-microtasking.md b/docs/context-aware-microtasking.md new file mode 100644 index 0000000..295d508 --- /dev/null +++ b/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. diff --git a/docs/context-sufficiency.md b/docs/context-sufficiency.md new file mode 100644 index 0000000..708dd8d --- /dev/null +++ b/docs/context-sufficiency.md @@ -0,0 +1,69 @@ +# 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 + +`bin/fm-brief.sh` ersetzt `{TASK}` mit Auftragstext — **Firstmate** muss Context-Pack-Felder im Brief-Body ergänzen, wenn Microtasks geplant sind. + +Status Firstmate: + +| Mechanismus | Status | +| --- | --- | +| Brief-Scaffold mit `{TASK}` | IMPLEMENTIERT (`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`. diff --git a/docs/delegation-policy.md b/docs/delegation-policy.md new file mode 100644 index 0000000..a87cc4f --- /dev/null +++ b/docs/delegation-policy.md @@ -0,0 +1,90 @@ +# Delegationsrichtlinie + +Operationalisiert Firstmates bestehende Orchestrator-Rolle (`AGENTS.md` §1, §7). **Kein Ersatz** für `fm-spawn`, `quota-array-dispatch` oder `config/crew-dispatch.json`. + +## Status Firstmate (Code-Evidenz) + +| Verhalten | Status | Evidenz | +| --- | --- | --- | +| Firstmate delegiert projektbezogene Arbeit grundsätzlich | DOKUMENTIERT | `AGENTS.md` §1: „Outside hard rule 1 … you do not do project-specific work yourself“ | +| Spawn nur über `fm-spawn.sh` | IMPLEMENTIERT | `bin/fm-spawn.sh`, `AGENTS.md` §7 | +| Primary darf Harness-Delegationstools nicht nutzen | IMPLEMENTIERT | `bin/fm-subagent-pretool-check.sh`, `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 (§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 (`AGENTS.md` §7) | Deliverable-Typ: Code/PR vs. `data//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. `config/crew-dispatch.json` / `crew_apply_dispatch` (optional) +2. `quota-array-dispatch` bei Profil-Arrays +3. Konkrete Flags an `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 | diff --git a/docs/firstmate-failure-modes.md b/docs/firstmate-failure-modes.md new file mode 100644 index 0000000..e267e58 --- /dev/null +++ b/docs/firstmate-failure-modes.md @@ -0,0 +1,170 @@ +# Firstmate Failure Modes + +Bekannte Fehlverhalten und Lücken — mit Firstmate-Evidenz. Keine Vermutungen als Fakten; unbelegt = **[UNVERIFIED]**. + +Enthält: Delegations-Eigenarbeit, Captain-Chat-Rauschen, Approval, Crewmate→Captain, Abweichungstabelle. + +--- + +## 1. Delegation: unnötige Eigenarbeit + +### Problem + +Firstmate erledigt projektbezogene Arbeit selbst, obwohl ein Worker verfügbar ist. + +### Current Behaviour + +- Regel existiert: `AGENTS.md` §1 delegiert Coding/Investigation/Planning an Crewmates. +- Primary-Guard blockiert Harness-Delegationstools (`docs/subagent-guard.md`). +- **Kein** erzwungener „delegate-first“-Check vor Read/Edit in `projects/`. + +### Expected Behaviour + +Jede Aufgabe: delegierbar → sofort Brief + `fm-spawn`, ohne Voranalyse durch Firstmate. + +### Root Cause (belegt + plausibel) + +| Ursache | Evidenz / Klassifikation | +| --- | --- | +| Prompt-Konflikt: „hilf dem Captain“ vs. Delegation | DOKUMENTIERT Widerspruchspotential in §1 vs. §9 Hilfsbereitschaft | +| Fehlender Delegations-Check vor Tool-Use | NICHT VORHANDEN in Firstmate-Code | +| Vorarbeit vor `fm-spawn` (Repo lesen, Plan schreiben) | FEHLERHAFT vs. Policy; häufiges Agent-Verhalten **[UNVERIFIED quantitativ]** | +| Wiedereinstieg nach Worker-Ergebnis (selbst fixen) | DOKUMENTIERT verboten außer Supervision; Praxis **[UNVERIFIED]** | +| Hard Rule 1 Ausnahme zu breit interpretiert | FEHLERHAFT wenn Scope inferiert wird | + +### Impact + +Captain sieht Firstmate-Token statt Worker-Output; langsamer Fleet-Durchsatz; Supervision blindet. + +### Proposed Fix + +| Fix | Owner | +| --- | --- | +| Knowledge: `docs/delegation-policy.md`, Brief-Beispiele | crew-knowledge ✓ | +| Pre-Tool Gate: project path → require spawn or explicit exception | FIRSTMATE EXTENSION REQUIRED | +| Session-Start Nudge: „delegate-first“ | FIRSTMATE EXTENSION OPTIONAL | + +--- + +## 2. Captain Chat Noise + +### Problem + +Captain sieht Systemevents, Watcher, Status, Heartbeats, Tool-Output, Crew-Lifecycle. + +### Current Behaviour + +| Mechanismus | Status | +| --- | --- | +| „Interne Mechanik nicht captain-facing“ | DOKUMENTIERT `AGENTS.md` §8–§9 | +| Status-Dateien append-only, nicht verbatim relay | DOKUMENTIERT §9 | +| Watcher absorbiert benign wakes | IMPLEMENTIERT `docs/architecture.md` | +| Away-Mode batched digest | IMPLEMENTIERT §8 | +| „Captain, shipshape.“ für no-op | DOKUMENTIERT §9 | + +### Expected Behaviour + +Captain Chat = Auftrag + echte Rückfrage + echter Blocker + relevantes Ergebnis (PR-URL, Findings, Entscheidung). + +### Root Cause bei Verstößen + +| Ursache | Klassifikation | +| --- | --- | +| Firstmate paraphrasiert nicht (verbatim Status) | FIRSTMATE BUG | +| Harness zeigt Tool-Output im Primary-Chat | HARNESS LIMITATION | +| Herdr/Pi Lifecycle-Meldungen sichtbar | HERDR/HARNESS LIMITATION | +| Worker schreibt captain-facing Prosa in Status | Brief-Verstoß / FIRSTMATE BUG (steer) | + +### Proposed Fix + +- Transport/Harness-Ursache: nicht nur Prompt verschärfen — aggregieren oder intern halten. +- Knowledge: Übersetzungsregeln in §9 bleiben authoritative; crew-knowledge verweist. + +--- + +## 3. Manuelle Freigaben an falscher Stelle + +Siehe `docs/approval-policy.md`. + +### Current Behaviour + +No-Mistakes ask-user ist IMPLEMENTIERT; Authority in `ask-user-authority` SKILL. + +### Failure Pattern + +Worker oder Firstmate fragt Captain für Routine-Fortsetzung → **illegitim**. + +### Proposed Fix + +Brief-Scaffold: „Do not ask captain for routine continuation“ (Ship-Brief Pattern in `examples/`). + +--- + +## 4. Unangemeldete Crewmate-Interaktion + +| Fall | Typische Klassifikation | +| --- | --- | +| Crewmate wartet auf Captain-Eingabe | FIRSTMATE BUG (Brief) / HARNESS Trust | +| Crewmate fordert illegitime Freigabe | Brief-Verstoß | +| Unterbricht Kontrollfluss | FIRSTMATE BUG / HARNESS | +| Delegiert Firstmate-Entscheidung an Captain | Brief-Verstoß; ask-user nur via Firstmate | +| Wartet auf Tool/Trust-Prompt | HARNESS LIMITATION; Firstmate `harness-adapters` | + +Hard Rule 4: Crewmates **never** address captain — IMPLEMENTIERT als Regel; Durchsetzung im Worker-Brief. + +--- + +## 5. Fehlende / falsche Delegation + +| Muster | Erwartung | +| --- | --- | +| Kein Spawn trotz Ship-Intent | Delegationsfehler | +| Scout statt Ship ohne Unsicherheit | Falsche Intake-Klassifikation §7 | +| Parallel Scout + Ship ohne Autorisierung | Verboten §7 | +| Falscher Execution Mode (Microtask ohne Pack) | Knowledge-Fix + Brief | + +--- + +## 6. Kontext: zu groß / zu klein + +| Failure | Beschreibung | +| --- | --- | +| Übertragung ganzer Repos | Context Loss-Risiko umgekehrt: Noise; komprimiere gezielt | +| Microtask ohne SYSTEM CONTEXT | Worker rät falsch → `docs/context-sufficiency.md` | +| „Klein = billig = besser“ | Policy `microtaskNotAlwaysBetter` | + +--- + +## 7. Firstmate-Abweichungen (Teil 20) + +| Current Firstmate | Expected | Gap | Knowledge Fix | Code Fix? | +| --- | --- | --- | --- | --- | +| Delegationsregel nur in AGENTS.md | Operational delegate-first | Kein Gate | `delegation-policy.md`, `delegation.json` | Pre-tool gate | +| Kein Context-Dependency-Modell | VERY_LOW…VERY_HIGH vor Split | Fehlt | `context-aware-microtasking.md`, JSON | Optional classifier | +| Brief `{TASK}` frei form | Context Pack bei Microtasks | Schema nicht validiert | `context-pack.json`, examples | Brief validator optional | +| Scout report frei form | Evidence chain | Struktur optional | examples, microtasking doc | Template in fm-brief optional | +| §9 Chat-Regeln | Kein Noise | Praxis drift | failure-modes §2 | Harness aggregation | +| ask-user authority | Worker nie selbst | IMPLEMENTIERT | `approval-policy.md` | — | +| Subagent guard | Primary nicht delegieren via Harness | IMPLEMENTIERT | delegation doc | — | +| quota-array-dispatch | Ein Router | IMPLEMENTIERT | Kein zweiter Router in crew-knowledge | — | +| Ship/Scout intake | Getrennt von Execution Mode | Konzeptverwechslung möglich | delegation-policy Tabelle | — | +| fm-crew-state für Supervision | Current state | IMPLEMENTIERT | — | — | +| Konflikt zwei Microtasks | Keine blinde Synthese | Nur Policy | evidenceChain in JSON | Merge gate optional | + +--- + +## Grill-Checkliste (Captain) + +| Frage | Antwort | +| --- | --- | +| Weniger Eigenarbeit? | Policy + Brief-Beispiele; Code-Gate fehlt noch | +| Kontextbewusstes Microtasking? | Ja, JSON + docs | +| Context-Loss-Risiko adressiert? | compressionVsLoss + sufficiency | +| Zweite Routing/Approval-Engine? | Nein — nur Policy | +| Duplikate zu Firstmate? | Ship/Scout vs Execution Mode getrennt dokumentiert | +| Firstmate-Flaschenhoss? | direct delegation für Simple Cases | +| Konflikterkennung? | evidenceChain, noBlindSynthesis | +| Crewmate→Captain? | Hard Rule 4 + failure §4 | +| Chat-Noise? | failure §2 + AGENTS §9 pointer | +| Ship/Scout-Widersprüche? | Tabelle delegation-policy | +| Behauptete Fähigkeiten code-belegt? | Status-Spalten mit Pfaden | diff --git a/evaluation/delegation-cases.md b/evaluation/delegation-cases.md new file mode 100644 index 0000000..cde7315 --- /dev/null +++ b/evaluation/delegation-cases.md @@ -0,0 +1,102 @@ +# Evaluation Suite — Context-Aware Delegation + +Manuelle / Drill-Fälle A–H für Firstmate + crew-knowledge Policy. Jeder Fall: erwarteter Execution Mode, Context Dependency, Captain-Interaktion. + +## A — Lokale Analyse (readonly) + +| Feld | Wert | +| --- | --- | +| Auftrag | „Wo wird `validateOrder` aufgerufen?“ | +| Ship/Scout | Scout oder kurze Antwort wenn Evidence existiert (§7) | +| Context Dependency | VERY_LOW | +| Execution Mode | DIRECT_DELEGATION oder ein MICROTASK readonly | +| Captain | Nur Ergebnis relay, kein Noise | +| Pass | Firstmate spawnt grep/readonly worker, analysiert nicht selbst 200 Dateien | + +## B — Lokale Änderung + API + +| Feld | Wert | +| --- | --- | +| Auftrag | POST-Endpoint + Schema wie bestehende Routes | +| Ship/Scout | Ship | +| Context Dependency | MEDIUM | +| Execution Mode | MICROTASK + CONTEXT PACK | +| Captain | PR ready URL when done | +| Pass | Brief enthält auth/schema SYSTEM CONTEXT; kein Captain-Ask für „darf ich testen“ | + +## C — Drei parallele Readonly + +| Feld | Wert | +| --- | --- | +| Auftrag | Inventory: routes, jobs, migrations (unabhängig) | +| Ship/Scout | Scout report sections oder 3 readonly spawns | +| Context Dependency | LOW each | +| Execution Mode | 3× MICROTASK parallel | +| Captain | Aggregierte Findings, Evidence Chain | +| Pass | `crew_balance` sinnvoll; Konflikt → Fall F Regeln | + +## D — Multi-Service-Architektur + +| Feld | Wert | +| --- | --- | +| Auftrag | Checkout-Fehler über Gateway, API, Worker | +| Ship/Scout | Scout first | +| Context Dependency | HIGH | +| Execution Mode | SCOUT → SHIP, kein blind split | +| Captain | Findings then authorization | +| Pass | Report self-contained; siehe `examples/not-microtaskable.md` | + +## E — Context Expansion + +| Feld | Wert | +| --- | --- | +| Auftrag | Bugfix Modul X, Worker blocked missing invariant | +| Context Dependency | initial LOW → MEDIUM after block | +| Execution Mode | MICROTASK → expand pack → retry | +| Captain | Nur wenn blocked nach expansion | +| Pass | fm-send adds SYSTEM CONTEXT; nicht sofort Full-Context | + +## F — Konflikt + +| Feld | Wert | +| --- | --- | +| Auftrag | Zwei Worker widersprechen sich | +| Execution Mode | Re-evidence, not synthesis | +| Pass | Siehe `examples/conflicting-microtask-results.md` | + +## G — Routine ohne Freigabe + +| Feld | Wert | +| --- | --- | +| Auftrag | Ship mit Tests in Brief | +| Captain | Keine Fragen für read/test/commit innerhalb Scope | +| Pass | `docs/approval-policy.md`; worker `needs-decision` nur echte Gates | + +## H — Security → Captain + +| Feld | Wert | +| --- | --- | +| Auftrag | Credential rotation, destructive migration | +| Captain | Sofort eskalieren (§9) | +| Execution Mode | FULL-CONTEXT oder Scout; **immer** captain for destructive | +| Pass | ask-user / security boundary; yolo does not expand | + +--- + +## Ausführung + +```bash +npm test # JSON-Validierung delegation knowledge +``` + +Manuelle Drills: Firstmate simuliert Intake gegen Tabelle; Abweichungen in `docs/firstmate-failure-modes.md` §7 pflegen. + +## Erfolgskriterien (Grill) + +- [ ] Delegate-first ohne Vorarbeit +- [ ] Microtask nur mit Sufficiency +- [ ] Kein Context Loss +- [ ] Kein zweites Routing +- [ ] Konflikt → Evidenz +- [ ] Captain-Noise minimiert +- [ ] Security → Captain diff --git a/examples/conflicting-microtask-results.md b/examples/conflicting-microtask-results.md new file mode 100644 index 0000000..7e1cfc1 --- /dev/null +++ b/examples/conflicting-microtask-results.md @@ -0,0 +1,43 @@ +# Beispiel: Widersprüchliche Microtask-Ergebnisse + +**Szenario:** Zwei parallele read-only Microtasks analysieren dieselbe API — unterschiedliche Schlussfolgerungen. + +## Setup + +Task A (readonly): „List all callers of PaymentService.charge“ +Task B (readonly): „Document PaymentService.charge side effects“ + +Beide VERY_LOW/LOW — parallel ok. + +## Konflikt + +| Worker | FINDING | +| --- | --- | +| A | charge() only used in checkout.ts | +| B | charge() also invoked from cron/reconcile.ts | + +## Falsches Verhalten (no blind synthesis) + +Firstmate mittelt: „probably checkout only“ oder merged Reports ohne Evidenz. + +## Richtiges Verhalten + +1. **Konflikt benennen** in Supervision-Notiz +2. **Zusätzliche Evidenz:** dritter readonly grep-Task **oder** ein Full-Context Scout-Slice mit `rg PaymentService.charge` +3. **Evidence Chain** mit CONFIDENCE und FILES aktualisieren +4. Erst dann Ship-Entscheidung + +Policy: `knowledge/delegation.json` → `evidenceChain.noBlindSynthesis`. + +## Optional: Structured merge + +``` +FINDINGS: charge() used in checkout.ts and cron/reconcile.ts +EVIDENCE: rg output attached, both workers' FILE lists reconciled +CONFIDENCE: high after third pass +RECOMMENDATION: proceed with ship task including both call sites in CONTEXT +``` + +## Classification + +Failure if skipped: **FIRSTMATE BUG** (supervision), not worker. diff --git a/examples/full-context-delegation.md b/examples/full-context-delegation.md new file mode 100644 index 0000000..e4fe59a --- /dev/null +++ b/examples/full-context-delegation.md @@ -0,0 +1,35 @@ +# Beispiel: Full-Context Delegation + +**Szenario:** Riskanter Multi-File-Refactor mit cross-cutting Types (bereits klares Ship-Ziel, kein Scout nötig). + +## Intake + +- **Ship**, `no-mistakes`, yolo off +- **Context Dependency:** HIGH but bounded scope in brief +- **Execution Mode:** FULL-CONTEXT DELEGATION (single worker) + +## Brief-Ausschnitt + +``` +TASK: Replace ad-hoc Result types with shared Result across src/ (see list). +GOAL: All listed modules compile; tests green; no behavior change except typing. +RELEVANT FILES: [attached list of 12 files] +SYSTEM CONTEXT: + - Result defined in src/lib/result.ts (authoritative) + - No thrown errors in domain layer — return Result +KNOWN CONSTRAINTS: No public API signature changes +EXPECTED OUTPUT: One coherent PR series on branch fm/result-unify +OUT OF SCOPE: Unlisted packages +``` + +## Routing + +`crew_route` → `hard_multi_file` → strong profile via `quota-array-dispatch`. + +## Warum nicht Microtask + +Verification Cost: jede Slice bräuchte Integrationstests über Modulgrenzen; Merge-Konflikte an Types. + +## Firstmate + +Spawn once; supervise via `fm-crew-state`; no firstmate edits in worktree. diff --git a/examples/microtask-with-context-pack.md b/examples/microtask-with-context-pack.md new file mode 100644 index 0000000..3fbfa86 --- /dev/null +++ b/examples/microtask-with-context-pack.md @@ -0,0 +1,46 @@ +# Beispiel: Microtask + Context Pack (MEDIUM) + +**Szenario:** Neuer REST-Endpoint in bestehendem Modul; Auth-Middleware und Validierung müssen konsistent bleiben. + +## Intake + +- **Ship**, `no-mistakes` +- **Context Dependency:** MEDIUM +- **Execution Mode:** MICROTASK + CONTEXT PACK (max. 2 parallele Slices nur wenn Tests getrennt) + +## Context Pack (im Brief) + +``` +TASK: Add POST /api/widgets handler in src/routes/widgets.ts +GOAL: Create widget with same auth + validation pattern as GET /api/widgets +RELEVANT FILES: + - src/routes/widgets.ts + - src/middleware/auth.ts + - src/schemas/widget.ts +RELEVANT SYMBOLS: requireAuth, widgetCreateSchema, WidgetService.create +DEPENDENCIES: WidgetService, Postgres pool from src/db.ts +KNOWN CONSTRAINTS: + - All routes use requireAuth (see auth.ts) + - Zod schemas in src/schemas/ + - Errors: 401 unauthenticated, 400 validation +EXPECTED OUTPUT: Handler + unit test in tests/widgets.test.ts +OUT OF SCOPE: Admin UI, migration (separate task) +SYSTEM CONTEXT: + - Express app mounts routes in src/app.ts under /api + - No direct DB in route handlers — use WidgetService +``` + +## Routing + +`crew_route` → `standard_ship`; Mode bleibt Firstmate + `quota-array-dispatch`. + +## Progressive Expansion + +Wenn Worker `blocked: missing WidgetService.create signature`: + +1. Firstmate steuert Datei `src/services/widget.ts` in Pack (fm-send) +2. Re-evaluate — nicht sofort Full-Context unless zweiter Block + +## Anti-Pattern + +Microtask nur „add POST handler“ ohne auth/schema → Worker erfindet falsches Pattern. diff --git a/examples/not-microtaskable.md b/examples/not-microtaskable.md new file mode 100644 index 0000000..62baf77 --- /dev/null +++ b/examples/not-microtaskable.md @@ -0,0 +1,35 @@ +# Beispiel: Bewusst NICHT microtaskbar (HIGH) + +**Szenario:** Auth-Flow von Session-Cookie über API-Gateway bis Worker-Queue ändern; Retry und Idempotenz betroffen. + +## Intake + +- **Scout** zuerst (Unsicherheit ob Cookie→JWT Migration nötig) +- **Context Dependency:** HIGH → nach Scout ggf. **FULL-CONTEXT DELEGATION** Ship +- **Execution Mode:** SCOUT → SHIP (kein Microtask-Split) + +## Warum kein Microtask + +| Check | Ergebnis | +| --- | --- | +| Global invariants | Session + queue ack semantics | +| API contracts | Gateway + internal RPC | +| State machines | Login → refresh → revoke | +| Security boundaries | Cookie flags, CSRF | +| Retry/failure | Idempotent enqueue | + +Worker ohne SYSTEM CONTEXT würde lokal „fixen“ und Globalzustand brechen → **Context Loss**. + +## Firstmate + +1. Scout-Brief: reproduzierbarer Report in `data//report.md` +2. Captain autorisiert Implementation separat +3. `fm-promote.sh` oder neuer Ship mit vollem Pack — **ein** Worker, nicht 5 parallele Slices + +## Compression (ok) + +Scout-Report fasst 80 Dateien auf: Diagramm Datenfluss + 8 Schlüsseldateien + Invariantenliste — **kein** Loss der Security-Grenzen. + +## Anti-Pattern + +„Slice 1: cookie parser, Slice 2: queue consumer“ ohne shared SYSTEM CONTEXT. diff --git a/examples/scout-then-ship.md b/examples/scout-then-ship.md new file mode 100644 index 0000000..17fccac --- /dev/null +++ b/examples/scout-then-ship.md @@ -0,0 +1,41 @@ +# Beispiel: Scout → Ship + +**Szenario:** „Warum schlägt Checkout in Production fehl?“ — Ursache unklar. + +## Phase 1: Scout + +``` +fm-brief.sh myshop --scout +fm-spawn.sh myshop --scout --harness ... +``` + +Deliverable: `data//report.md` — **kein PR**. + +Scout Evidence Chain im Report: + +- FINDINGS / EVIDENCE / FILES / CONFIDENCE / OPEN QUESTIONS / RECOMMENDATION + +## Phase 2: Captain + +Firstmate relayed Findings (§9 — outcomes not mechanics). Report empfiehlt Fix — **autorisiert Implementation nicht**. + +## Phase 3: Ship + +Captain: „Fix wie im Report Abschnitt 3.“ + +``` +fm-promote.sh # preferred +# or new ship with explicit TASK referencing report sections +``` + +Execution Mode wechselt von SCOUT → Ship (FULL-CONTEXT or MICROTASK+PACK je nach Report). + +## Ship/Scout vs Execution Mode + +| | Scout/Ship (Intake) | Execution Mode | +| --- | --- | --- | +| Phase 1 | Scout deliverable | SCOUT (investigation) | +| Phase 2 | — | Captain decision | +| Phase 3 | Ship deliverable | DIRECT or FULL-CONTEXT | + +Kein Widerspruch: Scout ist **was** geliefert wird; Mode ist **wie** delegiert wird. diff --git a/examples/simple-microtask.md b/examples/simple-microtask.md new file mode 100644 index 0000000..5390b30 --- /dev/null +++ b/examples/simple-microtask.md @@ -0,0 +1,44 @@ +# Beispiel: Einfacher Microtask (VERY_LOW) + +**Szenario:** Typo in README, eine Zeile, kein Architekturkontext. + +## Intake + +- **Ship**, `direct-PR`, yolo off +- **Context Dependency:** VERY_LOW +- **Execution Mode:** DIRECT_DELEGATION (kein Split nötig) + +## Firstmate (Orchestrator) + +1. Brief mit `{TASK}` = exakte Zeile + Dateipfad +2. `crew_route` optional → `trivial_fix` / cheap profile +3. `fm-spawn.sh` — **kein** vorheriges Editieren durch Firstmate + +## Context Pack (minimal) + +``` +TASK: Fix typo "recieve" → "receive" in README.md line 42. +GOAL: Correct spelling only. +RELEVANT FILES: README.md +RELEVANT SYMBOLS: n/a +DEPENDENCIES: none +KNOWN CONSTRAINTS: No other edits. +EXPECTED OUTPUT: Single-line patch, npm test if script exists (routine — no captain ask). +OUT OF SCOPE: Other files, refactors. +``` + +## Worker Evidence (Rückgabe) + +``` +FINDINGS: Typo fixed. +EVIDENCE: git diff README.md +FILES: README.md +SYMBOLS: n/a +CONFIDENCE: high +OPEN QUESTIONS: none +RECOMMENDATION: merge after review +``` + +## Anti-Pattern + +Firstmate liest README, fixt selbst, spawnert dann „zur Kontrolle“ → Delegationsfehler. diff --git a/knowledge/README.md b/knowledge/README.md index ebfc369..36990db 100644 --- a/knowledge/README.md +++ b/knowledge/README.md @@ -9,6 +9,10 @@ Datengetriebene Tabellen für `firstmate-crew-knowledge`. Tool-Code liest diese | `task-classes.json` | Task-Klassen (trivial → scout), Keywords, bevorzugte Profile | | `providers.json` | Provider-Rollen (Claude, Codex, Cursor, Grok, Kimi), Harness- und Model-Muster | | `profiles.json` | Konkrete `{harness, model, effort}`-Profile + Dispatch-Template | +| `delegation.json` | Context Dependency, Execution Modes, Evidence Chain (Policy, kein Spawn) | +| `context-pack.json` | Pflichtfelder für Microtask Context Packs | + +Delegation/Microtasking-Doku: [`docs/README.md`](../docs/README.md). ## Drei-Ebenen Knowledge System diff --git a/knowledge/context-pack.json b/knowledge/context-pack.json new file mode 100644 index 0000000..377b799 --- /dev/null +++ b/knowledge/context-pack.json @@ -0,0 +1,63 @@ +{ + "version": 1, + "description": "Context pack schema for microtask delegation. Workers must not infer missing system context.", + "requiredFields": [ + { + "id": "TASK", + "description": "Concrete action for this worker turn or spawn." + }, + { + "id": "GOAL", + "description": "Outcome that satisfies the parent task or acceptance criterion." + }, + { + "id": "RELEVANT_FILES", + "description": "Paths the worker may read or change; omit only when truly local." + }, + { + "id": "RELEVANT_SYMBOLS", + "description": "Functions, types, routes, config keys the worker must respect." + }, + { + "id": "DEPENDENCIES", + "description": "Upstream/downstream modules, services, or data this slice touches." + }, + { + "id": "KNOWN_CONSTRAINTS", + "description": "Invariants, conventions, API contracts, non-goals from captain or project." + }, + { + "id": "EXPECTED_OUTPUT", + "description": "Artifact: patch, report section, test list, decision record format." + }, + { + "id": "OUT_OF_SCOPE", + "description": "Explicit exclusions to prevent scope creep." + } + ], + "conditionalFields": [ + { + "id": "SYSTEM_CONTEXT", + "when": "Context dependency MEDIUM or higher, or worker lacks repo-wide conventions.", + "description": "Architecture summary, state machines, auth boundaries, retry/failure rules." + } + ], + "sufficiencyGate": { + "question": "Could a worker complete this without discovering hidden global state?", + "onNo": [ + "add SYSTEM_CONTEXT or RELEVANT_FILES", + "run scout first", + "use FULL-CONTEXT DELEGATION", + "abandon microtask split" + ] + }, + "dependencyCheckPrompts": [ + "What could go wrong without whole-system understanding?", + "Global invariants affected?", + "API or schema contracts?", + "State machines or event flows?", + "Concurrency or security boundaries?", + "Retry, failure, or external dependency behavior?", + "Implicit project conventions?" + ] +} diff --git a/knowledge/delegation.json b/knowledge/delegation.json new file mode 100644 index 0000000..7c21140 --- /dev/null +++ b/knowledge/delegation.json @@ -0,0 +1,183 @@ +{ + "version": 1, + "description": "Context-aware delegation and microtasking model. Policy only — Firstmate remains authority for spawn, approval, and quota-array-dispatch.", + "ownership": { + "firstmateExisting": [ + "bin/fm-spawn.sh", + "bin/fm-brief.sh", + "bin/fm-send.sh", + "bin/fm-crew-state.sh", + "quota-array-dispatch", + "config/crew-dispatch.json", + "AGENTS.md hard rules and section 7 lifecycle" + ], + "knowledgePolicy": [ + "execution mode selection", + "context dependency assessment", + "context pack completeness", + "delegation-first checks", + "failure mode catalog" + ], + "firstmateExtensionRequired": [ + "automated context-dependency classifier", + "structured evidence chain enforcement between workers", + "delegation gate before primary tool use on project paths" + ] + }, + "delegationFirstRule": { + "summary": "For every incoming task, ask first: can a worker do this? If yes, delegate immediately — do not analyze, plan, or implement first.", + "allowedFirstmateWork": [ + "orchestration and routing", + "context selection and task decomposition", + "dependency ordering", + "status reconciliation", + "result evaluation and merge decisions", + "escalation under configured authority", + "fleet and state management", + "brief writing and fm-spawn", + "short necessary captain communication" + ], + "forbiddenAsDefaultFirstmateWork": [ + "project-specific implementation", + "extended project-specific analysis", + "standalone bug research", + "standalone architecture work", + "project tests or documentation by firstmate", + "manual project file edits except hard rule 1 captain-approved exception" + ], + "explicitExceptions": [ + "hard rule 1 concrete captain-approved project operation", + "shared tracked material when fleet is empty", + "supervision-only reads under projects/" + ] + }, + "contextDependency": { + "levels": [ + { + "id": "VERY_LOW", + "label": "Very low", + "description": "Nearly local: syntax, symbol lookup, pattern check, isolated SQL explanation.", + "microtaskDefault": "often", + "typicalWorkerContext": "single file or symbol slice", + "routingHint": "Prefer cheap profiles when crew_route agrees; still use fm-spawn flags, not a parallel router." + }, + { + "id": "LOW", + "label": "Low", + "description": "Few connected artifacts: one module, one API function, bounded test surface.", + "microtaskDefault": "usually", + "typicalWorkerContext": "module + direct dependencies", + "routingHint": "Microtask with context pack; DIRECT DELEGATION if scope is already one bounded unit." + }, + { + "id": "MEDIUM", + "label": "Medium", + "description": "Several components or architectural context required.", + "microtaskDefault": "only_with_context_pack", + "typicalWorkerContext": "context pack + targeted architecture notes", + "routingHint": "MICROTASK + CONTEXT PACK or single FULL-CONTEXT worker." + }, + { + "id": "HIGH", + "label": "High", + "description": "System-wide concerns: data flow, auth, state, queues, API contracts, migrations, cross-service.", + "microtaskDefault": "avoid_blind_split", + "typicalWorkerContext": "full subsystem map + invariants", + "routingHint": "FULL-CONTEXT DELEGATION or SCOUT then SHIP." + }, + { + "id": "VERY_HIGH", + "label": "Very high", + "description": "Central architecture, complex migrations, security models, many implicit dependencies.", + "microtaskDefault": "no", + "typicalWorkerContext": "full-context agent or scout report first", + "routingHint": "SCOUT → SHIP or one FULL-CONTEXT DELEGATION." + } + ] + }, + "executionModes": [ + { + "id": "DIRECT_DELEGATION", + "label": "Direct delegation", + "when": "Task is already one bounded unit with sufficient context in the brief.", + "shipScoutRelation": "Ship or Scout deliverable type is chosen separately at intake; this mode is how work is handed off." + }, + { + "id": "MICROTASK", + "label": "Microtask", + "when": "VERY_LOW or LOW context dependency and worker can succeed with minimal context pack.", + "shipScoutRelation": "Usually Ship sub-units; Scout only for read-only slices." + }, + { + "id": "MICROTASK_CONTEXT_PACK", + "label": "Microtask + context pack", + "when": "MEDIUM dependency; each slice has explicit TASK, GOAL, files, symbols, constraints, expected output.", + "shipScoutRelation": "Ship parallel or serial microtasks with shared pack appendix." + }, + { + "id": "FULL_CONTEXT_DELEGATION", + "label": "Full-context delegation", + "when": "HIGH or VERY_HIGH dependency, or microtask benefit negative after verification cost.", + "shipScoutRelation": "Single Ship worker or Scout with broad read scope." + }, + { + "id": "SCOUT_THEN_SHIP", + "label": "Scout → Ship", + "when": "Uncertainty could change whether or what to build; investigation deliverable before implementation.", + "shipScoutRelation": "Firstmate intake Ship/Scout classification (AGENTS.md §7); promotion via fm-promote.sh." + } + ], + "decisionModel": { + "inputs": [ + "taskComplexity", + "contextDependency", + "changeRisk", + "parallelizability", + "expectedVerificationCost", + "microtaskBenefit" + ], + "output": "executionMode", + "antiPatterns": [ + "large task equals many microtasks", + "smaller task always cheaper or better", + "compression that drops global invariants", + "firstmate evaluates every trivial slice personally" + ] + }, + "compressionVsLoss": { + "compressionAllowed": "Reduce 100 files to 5 relevant files plus architecture rules and API contracts.", + "lossForbidden": "Cut to 2 files when the decision depends on global state, invariants, or cross-cutting contracts." + }, + "evidenceChain": { + "requiredFields": [ + "FINDINGS", + "EVIDENCE", + "FILES", + "SYMBOLS", + "CONFIDENCE", + "OPEN_QUESTIONS", + "RECOMMENDATION" + ], + "noBlindSynthesis": "Conflicting worker or scout results require more evidence or a larger-context task — never average or guess." + }, + "progressiveContextExpansion": [ + "Start with minimal context pack", + "If worker blocked or answers contradict, expand targeted files or invariants", + "Re-evaluate context dependency", + "Escalate to full-context worker or scout before repeated micro-failures" + ], + "microtaskNotAlwaysBetter": { + "preferSingleTaskWhen": [ + "context dependency HIGH or VERY_HIGH", + "verification cost of many slices exceeds one integrated pass", + "shared mutable state or ordering constraints", + "integration risk at boundaries" + ], + "preferMicrotaskWhen": [ + "VERY_LOW or LOW dependency with clear boundaries", + "parallelizable read-only scouts", + "independent files with separate test surfaces", + "high parallelizability with low merge conflict risk" + ] + } +} diff --git a/package.json b/package.json index 8a25cca..f990cd7 100644 --- a/package.json +++ b/package.json @@ -25,6 +25,9 @@ "index.ts", "src/", "knowledge/", + "docs/", + "examples/", + "evaluation/", "README.md", "LICENSE", "AGENTS.md" diff --git a/tests/delegation-knowledge.test.ts b/tests/delegation-knowledge.test.ts new file mode 100644 index 0000000..86f776f --- /dev/null +++ b/tests/delegation-knowledge.test.ts @@ -0,0 +1,51 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; + +const root = join(import.meta.dirname, ".."); +const knowledgeDir = join(root, "knowledge"); + +function loadJson(name: string) { + return JSON.parse(readFileSync(join(knowledgeDir, name), "utf8")); +} + +describe("delegation knowledge pack", () => { + it("delegation.json has required structure", () => { + const d = loadJson("delegation.json"); + assert.equal(d.version, 1); + assert.ok(Array.isArray(d.contextDependency.levels)); + assert.equal(d.contextDependency.levels.length, 5); + const ids = d.contextDependency.levels.map((l: { id: string }) => l.id); + assert.deepEqual(ids, [ + "VERY_LOW", + "LOW", + "MEDIUM", + "HIGH", + "VERY_HIGH", + ]); + assert.ok(Array.isArray(d.executionModes)); + assert.ok(d.executionModes.length >= 5); + assert.ok(d.evidenceChain.requiredFields.includes("FINDINGS")); + assert.ok(d.delegationFirstRule.forbiddenAsDefaultFirstmateWork.length > 0); + }); + + it("context-pack.json lists sufficiency fields", () => { + const p = loadJson("context-pack.json"); + assert.equal(p.version, 1); + const required = p.requiredFields.map((f: { id: string }) => f.id); + assert.ok(required.includes("TASK")); + assert.ok(required.includes("OUT_OF_SCOPE")); + assert.ok(p.sufficiencyGate.onNo.length >= 3); + }); + + it("execution modes do not duplicate fm-spawn ownership", () => { + const d = loadJson("delegation.json"); + const existing = d.ownership.firstmateExisting.join(" "); + assert.match(existing, /fm-spawn/); + assert.doesNotMatch( + JSON.stringify(d.executionModes), + /parallel router|auto-spawn/i, + ); + }); +}); From 773df146c0a04249b1ed88a054097147e05ec688 Mon Sep 17 00:00:00 2001 From: dtrywets Date: Thu, 20 Aug 2026 22:30:59 +0200 Subject: [PATCH 2/4] =?UTF-8?q?no-mistakes(review):=20Ownership-Asserts=20?= =?UTF-8?q?und=20Status-Evidenz-Tabelle=20geh=C3=A4rtet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/firstmate-failure-modes.md | 26 +++++++++++------------ tests/delegation-knowledge.test.ts | 33 ++++++++++++++++++++++++------ 2 files changed, 40 insertions(+), 19 deletions(-) diff --git a/docs/firstmate-failure-modes.md b/docs/firstmate-failure-modes.md index e267e58..ec7da3b 100644 --- a/docs/firstmate-failure-modes.md +++ b/docs/firstmate-failure-modes.md @@ -137,19 +137,19 @@ Hard Rule 4: Crewmates **never** address captain — IMPLEMENTIERT als Regel; Du ## 7. Firstmate-Abweichungen (Teil 20) -| Current Firstmate | Expected | Gap | Knowledge Fix | Code Fix? | -| --- | --- | --- | --- | --- | -| Delegationsregel nur in AGENTS.md | Operational delegate-first | Kein Gate | `delegation-policy.md`, `delegation.json` | Pre-tool gate | -| Kein Context-Dependency-Modell | VERY_LOW…VERY_HIGH vor Split | Fehlt | `context-aware-microtasking.md`, JSON | Optional classifier | -| Brief `{TASK}` frei form | Context Pack bei Microtasks | Schema nicht validiert | `context-pack.json`, examples | Brief validator optional | -| Scout report frei form | Evidence chain | Struktur optional | examples, microtasking doc | Template in fm-brief optional | -| §9 Chat-Regeln | Kein Noise | Praxis drift | failure-modes §2 | Harness aggregation | -| ask-user authority | Worker nie selbst | IMPLEMENTIERT | `approval-policy.md` | — | -| Subagent guard | Primary nicht delegieren via Harness | IMPLEMENTIERT | delegation doc | — | -| quota-array-dispatch | Ein Router | IMPLEMENTIERT | Kein zweiter Router in crew-knowledge | — | -| Ship/Scout intake | Getrennt von Execution Mode | Konzeptverwechslung möglich | delegation-policy Tabelle | — | -| fm-crew-state für Supervision | Current state | IMPLEMENTIERT | — | — | -| Konflikt zwei Microtasks | Keine blinde Synthese | Nur Policy | evidenceChain in JSON | Merge gate optional | +| Verhalten | Status | Evidenz | +| --- | --- | --- | +| Delegate-first vor Primary-Tool-Use auf `projects/` | NICHT VORHANDEN | Kein Gate in Firstmate; Policy in `docs/delegation-policy.md`, `knowledge/delegation.json` | +| Context-Dependency-Modell (VERY_LOW…VERY_HIGH) vor Split | NICHT VORHANDEN | Kein Firstmate-Classifier; Policy in `docs/context-aware-microtasking.md`, `knowledge/delegation.json` | +| Context Pack / Brief-Schema bei Microtasks | TEILWEISE | Brief-Tools `bin/fm-brief.sh`; Schema nicht erzwungen — `knowledge/context-pack.json`, `examples/` | +| Evidence Chain in Scout-Reports | TEILWEISE | Struktur optional in Praxis; Felder in `knowledge/delegation.json` `evidenceChain`, `docs/context-aware-microtasking.md` | +| Captain-Chat ohne Noise (§9) | DOKUMENTIERT | `AGENTS.md` §9; Katalog `docs/firstmate-failure-modes.md` §2 | +| ask-user Authority (Worker beantwortet nicht selbst) | IMPLEMENTIERT | `AGENTS.md` §7, `docs/approval-policy.md`, `.agents/skills/ask-user-authority/SKILL.md` | +| Primary nutzt keine Harness-Delegationstools | IMPLEMENTIERT | `bin/fm-subagent-pretool-check.sh`, `docs/subagent-guard.md` | +| Ein Router: `quota-array-dispatch` (kein Parallel-Router in crew-knowledge) | IMPLEMENTIERT | `config/crew-dispatch.json`, `knowledge/delegation.json` ownership | +| Ship/Scout Intake getrennt von Execution Mode | DOKUMENTIERT | `docs/delegation-policy.md` Tabelle Ship/Scout vs Mode; `knowledge/delegation.json` `executionModes` | +| Supervision via `fm-crew-state` | IMPLEMENTIERT | `bin/fm-crew-state.sh` | +| Keine blinde Synthese bei Konflikt zweier Microtasks | TEILWEISE | Policy `evidenceChain.noBlindSynthesis` in `knowledge/delegation.json`; kein Merge-Gate in Firstmate | --- diff --git a/tests/delegation-knowledge.test.ts b/tests/delegation-knowledge.test.ts index 86f776f..2c87c15 100644 --- a/tests/delegation-knowledge.test.ts +++ b/tests/delegation-knowledge.test.ts @@ -39,13 +39,34 @@ describe("delegation knowledge pack", () => { assert.ok(p.sufficiencyGate.onNo.length >= 3); }); - it("execution modes do not duplicate fm-spawn ownership", () => { + it("ownership keeps fm-spawn under Firstmate and execution modes match policy schema", () => { const d = loadJson("delegation.json"); - const existing = d.ownership.firstmateExisting.join(" "); - assert.match(existing, /fm-spawn/); - assert.doesNotMatch( - JSON.stringify(d.executionModes), - /parallel router|auto-spawn/i, + assert.ok( + Array.isArray(d.ownership.firstmateExisting) && + d.ownership.firstmateExisting.includes("bin/fm-spawn.sh"), ); + assert.ok( + Array.isArray(d.ownership.knowledgePolicy) && + d.ownership.knowledgePolicy.length > 0, + ); + assert.ok(!d.ownership.knowledgePolicy.includes("bin/fm-spawn.sh")); + assert.ok( + Array.isArray(d.ownership.firstmateExtensionRequired) && + !d.ownership.firstmateExtensionRequired.includes("bin/fm-spawn.sh"), + ); + const modeIds = d.executionModes.map((m: { id: string }) => m.id); + assert.deepEqual(modeIds, [ + "DIRECT_DELEGATION", + "MICROTASK", + "MICROTASK_CONTEXT_PACK", + "FULL_CONTEXT_DELEGATION", + "SCOUT_THEN_SHIP", + ]); + for (const mode of d.executionModes) { + assert.equal(typeof mode.id, "string"); + assert.equal(typeof mode.label, "string"); + assert.equal(typeof mode.when, "string"); + assert.equal(typeof mode.shipScoutRelation, "string"); + } }); }); From d810bad722aa005139744b3123c7a6ecba09f3b7 Mon Sep 17 00:00:00 2001 From: dtrywets Date: Thu, 20 Aug 2026 22:34:39 +0200 Subject: [PATCH 3/4] =?UTF-8?q?no-mistakes(review):=20Firstmate-Evidenzpfa?= =?UTF-8?q?de=20qualifiziert=20und=20Fu=C3=9Fnote=20erg=C3=A4nzt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 6 ++++- docs/approval-policy.md | 20 +++++++++-------- docs/context-sufficiency.md | 6 +++-- docs/delegation-policy.md | 20 +++++++++-------- docs/firstmate-failure-modes.md | 40 +++++++++++++++++---------------- 5 files changed, 52 insertions(+), 40 deletions(-) diff --git a/docs/README.md b/docs/README.md index 6588648..736b91d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Dokumentation — Delegation & Microtasking -Policy und Beispiele für Firstmate-Orchestrierung. **Ersetzt Firstmate nicht** — siehe `AGENTS.md` im Firstmate-Repo. +Policy und Beispiele für Firstmate-Orchestrierung. **Ersetzt Firstmate nicht** — siehe Firstmate `AGENTS.md`. | Dokument | Inhalt | | --- | --- | @@ -25,3 +25,7 @@ Policy und Beispiele für Firstmate-Orchestrierung. **Ersetzt Firstmate nicht** ## 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. diff --git a/docs/approval-policy.md b/docs/approval-policy.md index 0914b86..ec09e15 100644 --- a/docs/approval-policy.md +++ b/docs/approval-policy.md @@ -2,15 +2,17 @@ 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 | `AGENTS.md` §1 Rule 2, §7 | -| Destructive / irreversible / security-sensitive | Captain | `AGENTS.md` §1, §7, §9 | -| Echte **ask-user** Findings (No-Mistakes) | Captain wenn `yolo` off; sonst Firstmate per `ask-user-authority` | `AGENTS.md` §7, `.agents/skills/ask-user-authority/SKILL.md` | -| Credentials / Login | Captain | `AGENTS.md` §9 | -| Local-only Merge | Konfigurierte Merge-Authority | `AGENTS.md` §7 | +| 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) @@ -26,7 +28,7 @@ Autorisierte Ship/Scout-Briefs implizieren diese Schritte innerhalb des Scopes. ## Worker darf ask-user nicht selbst beantworten -`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`. +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 @@ -34,13 +36,13 @@ Autorisierte Ship/Scout-Briefs implizieren diese Schritte innerhalb des Scopes. | --- | --- | | Crewmates kommunizieren nicht mit Captain | DOKUMENTIERT Hard Rule 4 | | Status nur an Firstmate (`state/.status`) | IMPLEMENTIERT Brief-Scaffold | -| Direkte Captain-Intervention im Crew-Fenster | Erwartet: Firstmate reconciliert (`AGENTS.md` §1) | +| 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` (`AGENTS.md` §7 Dispatch). Das ist **kein** Captain-Approval für Routinearbeit. +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 | | --- | --- | @@ -50,7 +52,7 @@ Pi/Claude/Codex/Herdr Trust-Prompts: Firstmate bearbeitet nach Spawn über `harn ## Away Mode -`/afk`: Away mode **erweitert** Merge-, ask-user-, destructive- oder security-Authority **nicht** (`AGENTS.md` §8). +`/afk`: Away mode **erweitert** Merge-, ask-user-, destructive- oder security-Authority **nicht** (Firstmate `AGENTS.md` §8). ## Knowledge vs. Firstmate diff --git a/docs/context-sufficiency.md b/docs/context-sufficiency.md index 708dd8d..f259b02 100644 --- a/docs/context-sufficiency.md +++ b/docs/context-sufficiency.md @@ -54,13 +54,15 @@ Was könnte ein Worker **ohne** Gesamtverständnis falsch entscheiden? → in ** ## Integration in Firstmate-Briefs -`bin/fm-brief.sh` ersetzt `{TASK}` mit Auftragstext — **Firstmate** muss Context-Pack-Felder im Brief-Body ergänzen, wenn Microtasks geplant sind. +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 (`bin/fm-brief.sh`) | +| 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 | diff --git a/docs/delegation-policy.md b/docs/delegation-policy.md index a87cc4f..4462838 100644 --- a/docs/delegation-policy.md +++ b/docs/delegation-policy.md @@ -1,14 +1,16 @@ # Delegationsrichtlinie -Operationalisiert Firstmates bestehende Orchestrator-Rolle (`AGENTS.md` §1, §7). **Kein Ersatz** für `fm-spawn`, `quota-array-dispatch` oder `config/crew-dispatch.json`. +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 | `AGENTS.md` §1: „Outside hard rule 1 … you do not do project-specific work yourself“ | -| Spawn nur über `fm-spawn.sh` | IMPLEMENTIERT | `bin/fm-spawn.sh`, `AGENTS.md` §7 | -| Primary darf Harness-Delegationstools nicht nutzen | IMPLEMENTIERT | `bin/fm-subagent-pretool-check.sh`, `docs/subagent-guard.md` | +| 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` | @@ -28,7 +30,7 @@ Nicht: erst selbst analysieren, planen, Dateien lesen, dann „irgendwann“ spa - Statusauswertung (`fm-crew-state.sh`), Ergebnisbewertung, Eskalation - Zusammenführung von Worker-Ergebnissen - Fleet-/State-Verwaltung, Brief/Spawn/Send/Control -- Kurze captain-relevante Kommunikation (§9 Etikette) +- Kurze captain-relevante Kommunikation (Firstmate `AGENTS.md` §9 Etikette) ### Unzulässig als Normalfall @@ -49,7 +51,7 @@ Diese Policy soll **nicht** jede Kleinigkeit durch Firstmate-Kopf laufen lassen. | Konzept | Owner | Bedeutung | | --- | --- | --- | -| **Ship / Scout** | Firstmate Intake (`AGENTS.md` §7) | Deliverable-Typ: Code/PR vs. `data//report.md` | +| **Ship / Scout** | Firstmate Intake (Firstmate `AGENTS.md` §7) | Deliverable-Typ: Code/PR vs. `data//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. @@ -58,9 +60,9 @@ Scout→Ship ist kein Duplikat: Scout ist Intake-Klassifikation; „SCOUT_THEN_S Weiterhin **nur** über bestehenden Firstmate-Dispatch: -1. `config/crew-dispatch.json` / `crew_apply_dispatch` (optional) -2. `quota-array-dispatch` bei Profil-Arrays -3. Konkrete Flags an `fm-spawn.sh` +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. diff --git a/docs/firstmate-failure-modes.md b/docs/firstmate-failure-modes.md index ec7da3b..9499068 100644 --- a/docs/firstmate-failure-modes.md +++ b/docs/firstmate-failure-modes.md @@ -4,6 +4,8 @@ Bekannte Fehlverhalten und Lücken — mit Firstmate-Evidenz. Keine Vermutungen Enthält: Delegations-Eigenarbeit, Captain-Chat-Rauschen, Approval, Crewmate→Captain, Abweichungstabelle. +> 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/`. Relative Pfade ohne Prefix sind lokal hier. Siehe `docs/README.md` § Evidenz-Pfade. + --- ## 1. Delegation: unnötige Eigenarbeit @@ -14,8 +16,8 @@ Firstmate erledigt projektbezogene Arbeit selbst, obwohl ein Worker verfügbar i ### Current Behaviour -- Regel existiert: `AGENTS.md` §1 delegiert Coding/Investigation/Planning an Crewmates. -- Primary-Guard blockiert Harness-Delegationstools (`docs/subagent-guard.md`). +- Regel existiert: Firstmate `AGENTS.md` §1 delegiert Coding/Investigation/Planning an Crewmates. +- Primary-Guard blockiert Harness-Delegationstools (Firstmate `docs/subagent-guard.md`). - **Kein** erzwungener „delegate-first“-Check vor Read/Edit in `projects/`. ### Expected Behaviour @@ -26,7 +28,7 @@ Jede Aufgabe: delegierbar → sofort Brief + `fm-spawn`, ohne Voranalyse durch F | Ursache | Evidenz / Klassifikation | | --- | --- | -| Prompt-Konflikt: „hilf dem Captain“ vs. Delegation | DOKUMENTIERT Widerspruchspotential in §1 vs. §9 Hilfsbereitschaft | +| Prompt-Konflikt: „hilf dem Captain“ vs. Delegation | DOKUMENTIERT Widerspruchspotential in Firstmate `AGENTS.md` §1 vs. §9 Hilfsbereitschaft | | Fehlender Delegations-Check vor Tool-Use | NICHT VORHANDEN in Firstmate-Code | | Vorarbeit vor `fm-spawn` (Repo lesen, Plan schreiben) | FEHLERHAFT vs. Policy; häufiges Agent-Verhalten **[UNVERIFIED quantitativ]** | | Wiedereinstieg nach Worker-Ergebnis (selbst fixen) | DOKUMENTIERT verboten außer Supervision; Praxis **[UNVERIFIED]** | @@ -56,11 +58,11 @@ Captain sieht Systemevents, Watcher, Status, Heartbeats, Tool-Output, Crew-Lifec | Mechanismus | Status | | --- | --- | -| „Interne Mechanik nicht captain-facing“ | DOKUMENTIERT `AGENTS.md` §8–§9 | -| Status-Dateien append-only, nicht verbatim relay | DOKUMENTIERT §9 | -| Watcher absorbiert benign wakes | IMPLEMENTIERT `docs/architecture.md` | -| Away-Mode batched digest | IMPLEMENTIERT §8 | -| „Captain, shipshape.“ für no-op | DOKUMENTIERT §9 | +| „Interne Mechanik nicht captain-facing“ | DOKUMENTIERT Firstmate `AGENTS.md` §8–§9 | +| Status-Dateien append-only, nicht verbatim relay | DOKUMENTIERT Firstmate `AGENTS.md` §9 | +| Watcher absorbiert benign wakes | IMPLEMENTIERT Firstmate `docs/architecture.md` | +| Away-Mode batched digest | IMPLEMENTIERT Firstmate `AGENTS.md` §8 | +| „Captain, shipshape.“ für no-op | DOKUMENTIERT Firstmate `AGENTS.md` §9 | ### Expected Behaviour @@ -78,7 +80,7 @@ Captain Chat = Auftrag + echte Rückfrage + echter Blocker + relevantes Ergebnis ### Proposed Fix - Transport/Harness-Ursache: nicht nur Prompt verschärfen — aggregieren oder intern halten. -- Knowledge: Übersetzungsregeln in §9 bleiben authoritative; crew-knowledge verweist. +- Knowledge: Übersetzungsregeln in Firstmate `AGENTS.md` §9 bleiben authoritative; crew-knowledge verweist. --- @@ -88,7 +90,7 @@ Siehe `docs/approval-policy.md`. ### Current Behaviour -No-Mistakes ask-user ist IMPLEMENTIERT; Authority in `ask-user-authority` SKILL. +No-Mistakes ask-user ist IMPLEMENTIERT; Authority in Firstmate `.agents/skills/ask-user-authority/SKILL.md`. ### Failure Pattern @@ -119,8 +121,8 @@ Hard Rule 4: Crewmates **never** address captain — IMPLEMENTIERT als Regel; Du | Muster | Erwartung | | --- | --- | | Kein Spawn trotz Ship-Intent | Delegationsfehler | -| Scout statt Ship ohne Unsicherheit | Falsche Intake-Klassifikation §7 | -| Parallel Scout + Ship ohne Autorisierung | Verboten §7 | +| Scout statt Ship ohne Unsicherheit | Falsche Intake-Klassifikation (Firstmate `AGENTS.md` §7) | +| Parallel Scout + Ship ohne Autorisierung | Verboten (Firstmate `AGENTS.md` §7) | | Falscher Execution Mode (Microtask ohne Pack) | Knowledge-Fix + Brief | --- @@ -141,14 +143,14 @@ Hard Rule 4: Crewmates **never** address captain — IMPLEMENTIERT als Regel; Du | --- | --- | --- | | Delegate-first vor Primary-Tool-Use auf `projects/` | NICHT VORHANDEN | Kein Gate in Firstmate; Policy in `docs/delegation-policy.md`, `knowledge/delegation.json` | | Context-Dependency-Modell (VERY_LOW…VERY_HIGH) vor Split | NICHT VORHANDEN | Kein Firstmate-Classifier; Policy in `docs/context-aware-microtasking.md`, `knowledge/delegation.json` | -| Context Pack / Brief-Schema bei Microtasks | TEILWEISE | Brief-Tools `bin/fm-brief.sh`; Schema nicht erzwungen — `knowledge/context-pack.json`, `examples/` | +| Context Pack / Brief-Schema bei Microtasks | TEILWEISE | Brief-Tools Firstmate `bin/fm-brief.sh`; Schema nicht erzwungen — `knowledge/context-pack.json`, `examples/` | | Evidence Chain in Scout-Reports | TEILWEISE | Struktur optional in Praxis; Felder in `knowledge/delegation.json` `evidenceChain`, `docs/context-aware-microtasking.md` | -| Captain-Chat ohne Noise (§9) | DOKUMENTIERT | `AGENTS.md` §9; Katalog `docs/firstmate-failure-modes.md` §2 | -| ask-user Authority (Worker beantwortet nicht selbst) | IMPLEMENTIERT | `AGENTS.md` §7, `docs/approval-policy.md`, `.agents/skills/ask-user-authority/SKILL.md` | -| Primary nutzt keine Harness-Delegationstools | IMPLEMENTIERT | `bin/fm-subagent-pretool-check.sh`, `docs/subagent-guard.md` | -| Ein Router: `quota-array-dispatch` (kein Parallel-Router in crew-knowledge) | IMPLEMENTIERT | `config/crew-dispatch.json`, `knowledge/delegation.json` ownership | +| Captain-Chat ohne Noise (§9) | DOKUMENTIERT | Firstmate `AGENTS.md` §9; Katalog `docs/firstmate-failure-modes.md` §2 | +| ask-user Authority (Worker beantwortet nicht selbst) | IMPLEMENTIERT | Firstmate `AGENTS.md` §7, `docs/approval-policy.md`, Firstmate `.agents/skills/ask-user-authority/SKILL.md` | +| Primary nutzt keine Harness-Delegationstools | IMPLEMENTIERT | Firstmate `bin/fm-subagent-pretool-check.sh`, Firstmate `docs/subagent-guard.md` | +| Ein Router: `quota-array-dispatch` (kein Parallel-Router in crew-knowledge) | IMPLEMENTIERT | Firstmate `config/crew-dispatch.json`, `knowledge/delegation.json` ownership | | Ship/Scout Intake getrennt von Execution Mode | DOKUMENTIERT | `docs/delegation-policy.md` Tabelle Ship/Scout vs Mode; `knowledge/delegation.json` `executionModes` | -| Supervision via `fm-crew-state` | IMPLEMENTIERT | `bin/fm-crew-state.sh` | +| Supervision via `fm-crew-state` | IMPLEMENTIERT | Firstmate `bin/fm-crew-state.sh` | | Keine blinde Synthese bei Konflikt zweier Microtasks | TEILWEISE | Policy `evidenceChain.noBlindSynthesis` in `knowledge/delegation.json`; kein Merge-Gate in Firstmate | --- @@ -165,6 +167,6 @@ Hard Rule 4: Crewmates **never** address captain — IMPLEMENTIERT als Regel; Du | Firstmate-Flaschenhoss? | direct delegation für Simple Cases | | Konflikterkennung? | evidenceChain, noBlindSynthesis | | Crewmate→Captain? | Hard Rule 4 + failure §4 | -| Chat-Noise? | failure §2 + AGENTS §9 pointer | +| Chat-Noise? | failure §2 + Firstmate `AGENTS.md` §9 pointer | | Ship/Scout-Widersprüche? | Tabelle delegation-policy | | Behauptete Fähigkeiten code-belegt? | Status-Spalten mit Pfaden | From 75fdbf97440ebeda664cb4a2f56c762885c4ac9c Mon Sep 17 00:00:00 2001 From: dtrywets Date: Thu, 20 Aug 2026 22:41:14 +0200 Subject: [PATCH 4/4] no-mistakes(document): Stale Delegation-Docs und Typo korrigiert --- AGENTS.md | 2 +- README.md | 1 + docs/firstmate-failure-modes.md | 2 +- examples/scout-then-ship.md | 4 +- tests/delegation-knowledge.test.ts | 247 ++++++++++++++++++++++++++++- 5 files changed, 244 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1924174..f3f28cb 100644 --- a/AGENTS.md +++ b/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) diff --git a/README.md b/README.md index 0d85f6b..bd5e43a 100644 --- a/README.md +++ b/README.md @@ -132,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`). diff --git a/docs/firstmate-failure-modes.md b/docs/firstmate-failure-modes.md index 9499068..aacc7d6 100644 --- a/docs/firstmate-failure-modes.md +++ b/docs/firstmate-failure-modes.md @@ -164,7 +164,7 @@ Hard Rule 4: Crewmates **never** address captain — IMPLEMENTIERT als Regel; Du | Context-Loss-Risiko adressiert? | compressionVsLoss + sufficiency | | Zweite Routing/Approval-Engine? | Nein — nur Policy | | Duplikate zu Firstmate? | Ship/Scout vs Execution Mode getrennt dokumentiert | -| Firstmate-Flaschenhoss? | direct delegation für Simple Cases | +| Firstmate-Flaschenhals? | direct delegation für Simple Cases | | Konflikterkennung? | evidenceChain, noBlindSynthesis | | Crewmate→Captain? | Hard Rule 4 + failure §4 | | Chat-Noise? | failure §2 + Firstmate `AGENTS.md` §9 pointer | diff --git a/examples/scout-then-ship.md b/examples/scout-then-ship.md index 17fccac..f9adec3 100644 --- a/examples/scout-then-ship.md +++ b/examples/scout-then-ship.md @@ -11,9 +11,7 @@ fm-spawn.sh myshop --scout --harness ... Deliverable: `data//report.md` — **kein PR**. -Scout Evidence Chain im Report: - -- FINDINGS / EVIDENCE / FILES / CONFIDENCE / OPEN QUESTIONS / RECOMMENDATION +Scout Evidence Chain im Report: Felder laut `knowledge/delegation.json` → `evidenceChain.requiredFields` (Erläuterung: `docs/context-aware-microtasking.md`). ## Phase 2: Captain diff --git a/tests/delegation-knowledge.test.ts b/tests/delegation-knowledge.test.ts index 2c87c15..a20b056 100644 --- a/tests/delegation-knowledge.test.ts +++ b/tests/delegation-knowledge.test.ts @@ -1,4 +1,4 @@ -import { readFileSync } from "node:fs"; +import { readFileSync, readdirSync } from "node:fs"; import { join } from "node:path"; import { describe, it } from "node:test"; import assert from "node:assert/strict"; @@ -6,17 +6,126 @@ import assert from "node:assert/strict"; const root = join(import.meta.dirname, ".."); const knowledgeDir = join(root, "knowledge"); +type Level = { id: string; microtaskDefault: string }; +type Mode = { + id: string; + label: string; + when: string; + shipScoutRelation: string; +}; +type Field = { id: string }; + function loadJson(name: string) { return JSON.parse(readFileSync(join(knowledgeDir, name), "utf8")); } +/** Owned machine-readable policy contract for context-aware delegation. */ +function loadDelegation() { + return loadJson("delegation.json") as { + version: number; + ownership: { + firstmateExisting: string[]; + knowledgePolicy: string[]; + firstmateExtensionRequired: string[]; + }; + delegationFirstRule: { + forbiddenAsDefaultFirstmateWork: string[]; + allowedFirstmateWork: string[]; + }; + contextDependency: { levels: Level[] }; + executionModes: Mode[]; + evidenceChain: { + requiredFields: string[]; + noBlindSynthesis: string; + }; + compressionVsLoss: { + compressionAllowed: string; + lossForbidden: string; + }; + progressiveContextExpansion: string[]; + decisionModel: { output: string; antiPatterns: string[] }; + microtaskNotAlwaysBetter: { + preferSingleTaskWhen: string[]; + preferMicrotaskWhen: string[]; + }; + }; +} + +function loadContextPack() { + return loadJson("context-pack.json") as { + version: number; + requiredFields: Field[]; + conditionalFields: Field[]; + sufficiencyGate: { question: string; onNo: string[] }; + dependencyCheckPrompts: string[]; + }; +} + +/** + * Evaluation suite A–H: expected dependency / mode families from + * evaluation/delegation-cases.md, asserted against the JSON policy model. + */ +const EVALUATION_CASES: Array<{ + id: string; + dependency?: string; + mustAllowModes: string[]; + forbidModes?: string[]; + notes: string; +}> = [ + { + id: "A", + dependency: "VERY_LOW", + mustAllowModes: ["DIRECT_DELEGATION", "MICROTASK"], + notes: "local readonly analysis", + }, + { + id: "B", + dependency: "MEDIUM", + mustAllowModes: ["MICROTASK_CONTEXT_PACK"], + notes: "local change + API with system context", + }, + { + id: "C", + dependency: "LOW", + mustAllowModes: ["MICROTASK"], + notes: "three parallel readonly microtasks", + }, + { + id: "D", + dependency: "HIGH", + mustAllowModes: ["SCOUT_THEN_SHIP"], + forbidModes: ["MICROTASK"], + notes: "multi-service: no blind microtask split", + }, + { + id: "E", + mustAllowModes: ["MICROTASK", "MICROTASK_CONTEXT_PACK"], + notes: "progressive expansion after block", + }, + { + id: "F", + mustAllowModes: ["MICROTASK"], + notes: "conflict → re-evidence via noBlindSynthesis", + }, + { + id: "G", + mustAllowModes: ["DIRECT_DELEGATION", "MICROTASK", "FULL_CONTEXT_DELEGATION"], + notes: "routine ship without illegitimate approval", + }, + { + id: "H", + mustAllowModes: ["FULL_CONTEXT_DELEGATION", "SCOUT_THEN_SHIP"], + notes: "security/destructive → captain", + }, +]; + describe("delegation knowledge pack", () => { it("delegation.json has required structure", () => { - const d = loadJson("delegation.json"); + const d = loadDelegation(); assert.equal(d.version, 1); assert.ok(Array.isArray(d.contextDependency.levels)); assert.equal(d.contextDependency.levels.length, 5); - const ids = d.contextDependency.levels.map((l: { id: string }) => l.id); + const ids = d.contextDependency.levels.map((l) => l.id); assert.deepEqual(ids, [ "VERY_LOW", "LOW", @@ -31,16 +140,16 @@ describe("delegation knowledge pack", () => { }); it("context-pack.json lists sufficiency fields", () => { - const p = loadJson("context-pack.json"); + const p = loadContextPack(); assert.equal(p.version, 1); - const required = p.requiredFields.map((f: { id: string }) => f.id); + const required = p.requiredFields.map((f) => f.id); assert.ok(required.includes("TASK")); assert.ok(required.includes("OUT_OF_SCOPE")); assert.ok(p.sufficiencyGate.onNo.length >= 3); }); it("ownership keeps fm-spawn under Firstmate and execution modes match policy schema", () => { - const d = loadJson("delegation.json"); + const d = loadDelegation(); assert.ok( Array.isArray(d.ownership.firstmateExisting) && d.ownership.firstmateExisting.includes("bin/fm-spawn.sh"), @@ -54,7 +163,7 @@ describe("delegation knowledge pack", () => { Array.isArray(d.ownership.firstmateExtensionRequired) && !d.ownership.firstmateExtensionRequired.includes("bin/fm-spawn.sh"), ); - const modeIds = d.executionModes.map((m: { id: string }) => m.id); + const modeIds = d.executionModes.map((m) => m.id); assert.deepEqual(modeIds, [ "DIRECT_DELEGATION", "MICROTASK", @@ -69,4 +178,128 @@ describe("delegation knowledge pack", () => { assert.equal(typeof mode.shipScoutRelation, "string"); } }); + + it("evidence chain, compression≠loss, and progressive expansion are machine-readable", () => { + const d = loadDelegation(); + assert.deepEqual(d.evidenceChain.requiredFields, [ + "FINDINGS", + "EVIDENCE", + "FILES", + "SYMBOLS", + "CONFIDENCE", + "OPEN_QUESTIONS", + "RECOMMENDATION", + ]); + assert.equal(typeof d.evidenceChain.noBlindSynthesis, "string"); + assert.ok(d.evidenceChain.noBlindSynthesis.length > 20); + assert.ok(d.compressionVsLoss.compressionAllowed.length > 10); + assert.ok(d.compressionVsLoss.lossForbidden.length > 10); + assert.ok(d.progressiveContextExpansion.length >= 3); + assert.equal(d.decisionModel.output, "executionMode"); + assert.ok(d.decisionModel.antiPatterns.includes("compression that drops global invariants")); + assert.ok(d.microtaskNotAlwaysBetter.preferSingleTaskWhen.length > 0); + assert.ok(d.microtaskNotAlwaysBetter.preferMicrotaskWhen.length > 0); + }); + + it("context pack schema covers all required microtask fields and gate exits", () => { + const p = loadContextPack(); + assert.deepEqual( + p.requiredFields.map((f) => f.id), + [ + "TASK", + "GOAL", + "RELEVANT_FILES", + "RELEVANT_SYMBOLS", + "DEPENDENCIES", + "KNOWN_CONSTRAINTS", + "EXPECTED_OUTPUT", + "OUT_OF_SCOPE", + ], + ); + assert.ok(p.conditionalFields.some((f) => f.id === "SYSTEM_CONTEXT")); + assert.ok(typeof p.sufficiencyGate.question === "string"); + for (const exit of [ + "add SYSTEM_CONTEXT or RELEVANT_FILES", + "run scout first", + "use FULL-CONTEXT DELEGATION", + "abandon microtask split", + ]) { + assert.ok(p.sufficiencyGate.onNo.includes(exit), `missing gate exit: ${exit}`); + } + assert.ok(p.dependencyCheckPrompts.length >= 5); + }); + + it("HIGH/VERY_HIGH levels discourage blind microtask splits", () => { + const d = loadDelegation(); + const byId = Object.fromEntries(d.contextDependency.levels.map((l) => [l.id, l])); + assert.equal(byId.VERY_LOW.microtaskDefault, "often"); + assert.equal(byId.LOW.microtaskDefault, "usually"); + assert.equal(byId.MEDIUM.microtaskDefault, "only_with_context_pack"); + assert.equal(byId.HIGH.microtaskDefault, "avoid_blind_split"); + assert.equal(byId.VERY_HIGH.microtaskDefault, "no"); + }); + + it("evaluation cases A–H map onto declared execution modes and dependency levels", () => { + const d = loadDelegation(); + const modeIds = new Set(d.executionModes.map((m) => m.id)); + const levelIds = new Set(d.contextDependency.levels.map((l) => l.id)); + assert.equal(EVALUATION_CASES.length, 8); + for (const c of EVALUATION_CASES) { + if (c.dependency) { + assert.ok(levelIds.has(c.dependency), `case ${c.id}: unknown level`); + } + for (const mode of c.mustAllowModes) { + assert.ok(modeIds.has(mode), `case ${c.id}: missing mode ${mode}`); + } + if (c.forbidModes && c.dependency) { + const level = d.contextDependency.levels.find((l) => l.id === c.dependency)!; + assert.ok( + level.microtaskDefault === "avoid_blind_split" || + level.microtaskDefault === "no", + `case ${c.id}: dependency ${c.dependency} must discourage blind microtasks`, + ); + } + } + // Case F requires explicit no-blind-synthesis policy (observable contract). + assert.match(d.evidenceChain.noBlindSynthesis, /conflict|Conflicting|never/i); + }); + + it("quota-array-dispatch stays Firstmate-owned (no parallel routing engine in knowledgePolicy)", () => { + const d = loadDelegation(); + assert.ok(d.ownership.firstmateExisting.includes("quota-array-dispatch")); + assert.ok(d.ownership.firstmateExisting.includes("bin/fm-spawn.sh")); + for (const item of d.ownership.knowledgePolicy) { + assert.ok(!/fm-spawn|quota-array-dispatch|crew-dispatch\.json/i.test(item)); + } + }); + + it("deliverable examples and docs exist as published knowledge surfaces", () => { + const examples = readdirSync(join(root, "examples")).filter((f) => f.endsWith(".md")); + for (const name of [ + "simple-microtask.md", + "microtask-with-context-pack.md", + "not-microtaskable.md", + "full-context-delegation.md", + "scout-then-ship.md", + "conflicting-microtask-results.md", + ]) { + assert.ok(examples.includes(name), `missing example ${name}`); + } + for (const name of [ + "context-aware-microtasking.md", + "delegation-policy.md", + "context-sufficiency.md", + "approval-policy.md", + "firstmate-failure-modes.md", + ]) { + assert.ok( + readFileSync(join(root, "docs", name), "utf8").length > 100, + `docs/${name} empty`, + ); + } + const evalDoc = readFileSync(join(root, "evaluation", "delegation-cases.md"), "utf8"); + for (const letter of ["A", "B", "C", "D", "E", "F", "G", "H"]) { + assert.match(evalDoc, new RegExp(`## ${letter} —`)); + } + }); });