feat: implement 5-phase architecture with discovery, knowledge layers, and evidence collection

AGENTS.md

@@ -5,9 +5,17 @@ Pi-Package (`pi-package`), das Firstmate bei Crew-Routing und Quota-Balance unte
 ## Was dieses Repo ist
 
 - Installierbare Extension: `package.json` → `"pi": { "extensions": ["./index.ts"] }`
-- Tools: `crew_route`, `crew_balance`, `crew_apply_dispatch`, `crew_suggest_primary`
-- Knowledge: `knowledge/*.json` (Task-Klassen, Provider, Profile)
-- Logik in `src/`
+- 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)
+  - Hersteller: `knowledge/manufacturers/` (Official Docs, Manufacturer Claims)
+  - Benchmarks: `knowledge/benchmarks/` (Artificial Analysis, HumanEval, etc.)
+  - Lokale Evidenz: `knowledge/local/` (no-mistakes Outcomes, privacy-conscious)
+- Logik in `src/`:
+  - `discovery.ts`: Live Model Discovery (Pi, Claude, Codex, Grok, Kimi)
+  - `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
 
 ## Was es nicht ist
 
@@ -23,12 +31,25 @@ Autoritative Firstmate-Doku liegt im Firstmate-Home (nicht hier kopieren):
 - Spawn-Flags → `bin/fm-spawn.sh --harness/--model/--effort`
 - Quota-Daten → `quota-axi --json` (Skill `quota-axi`)
 
+## Architektur-Prinzipien
+
+- **Firstmate bleibt Authority**: crew-knowledge liefert nur Empfehlungen
+- **Kein Competing Dispatch Engine**: Nutzt Firstmate's `quota-array-dispatch`
+- **Respektiert config/crew-dispatch.json**: Natural Language Rules bleiben authoritative
+- **Provider ≠ Model ≠ Harness**: Klare Trennung, kein Inferieren von Provider aus Model-Namen
+- **Herdr ist Infrastructure**: Backend-Wahl (tmux, Herdr, etc.) beeinflusst nicht Model-Qualität
+- **Discovery Cache**: 15min TTL, force-refresh möglich
+- **Privacy-First Evidence**: Nur Metriken, KEINE Code-Inhalte, KEINE Prompts
+
 ## Lokale Konventionen
 
 - User-facing Docs: Deutsch; kurze English-Section in README ok
 - Commits/PR: Deutsch, ohne AI-Co-Author-Meta
 - Writes nur unter dem aufgelösten Home/config (siehe README) und nur bei explizitem Tool-Call (`dryRun=false`)
 - Tests: `npm test` (Node built-in test runner, Fixtures, kein Netz)
+- Evidence Collection: Automatisch aus no-mistakes, manuell via `recordEvidence()` oder `recordFromNoMistakesOutcome()`
+- Discovery Cache: `~/.cache/firstmate-crew-knowledge/discovery.json`
+- Local Evidence: `knowledge/local/evidence.json` und `knowledge/local/aggregated.json`
 
 ## Maintaining this file
 

README.md

@@ -1,9 +1,17 @@
 # firstmate-crew-knowledge
 
-Pi-Extension für [Firstmate](https://github.com/thelad-dev): empfiehlt pro Task-Klasse konkrete `{harness, model, effort}`-Profile und balanciert die Nutzung über die Captain-Subscriptions **Cursor**, **Claude**, **ChatGPT/Codex** und **Grok (xAI)**.
+Pi-Extension für [Firstmate](https://github.com/thelad-dev): empfiehlt pro Task-Klasse konkrete `{harness, model, effort}`-Profile und balanciert die Nutzung über die Captain-Subscriptions **Cursor**, **Claude**, **ChatGPT/Codex**, **Grok (xAI)** und **Kimi**.
 
 > **Wichtig:** Dieses Paket **ersetzt weder Firstmate-Urteil noch `fm-spawn`**. Firstmate bleibt Owner von Intake, `quota-array-dispatch` und dem finalen Spawn. Die Tools liefern nur Empfehlungen, Spawn-Flags und optional eine `crew-dispatch.json`.
 
+## Features
+
+- **Live Model Discovery**: Automatische Erkennung verfügbarer Modelle von Pi, Claude, Codex, Grok, Kimi mit Caching
+- **Drei-Ebenen Knowledge System**: Hersteller-Fakten, externe Benchmarks, lokale Crew-Evidenz
+- **Lokale Evidenz-Sammlung**: Automatisches Tracking von no-mistakes Outcomes (Privacy-conscious: keine Code-Inhalte, keine Prompts)
+- **Selbstaktualisierung**: Kompatibilitätsprüfung mit Firstmate-Updates
+- **Quota-Balance**: Live-Quota-Ranking über alle Subscriptions
+
 ## Install
 
 ```bash
@@ -31,6 +39,9 @@ Installable Pi package (`pi-package`) that classifies crew work, recommends `--h
 | Tool `crew_balance` | Live-Quota sortiert (Headroom/Runway), degraded wenn `quota-axi` fehlt |
 | Tool `crew_apply_dispatch` | Erzeugt Firstmate-`crew-dispatch.json` (Default: **dry-run**; `merge` hängt fehlende `when`-Regeln an und verweigert unlesbare/ungültige Bestandsdateien) |
 | Tool `crew_suggest_primary` | Listet/sucht authentifizierte Pi-Session-Modelle (`modelRegistry` / `scopedModels`) und empfiehlt ein Primary-Switch-Ziel nur darunter (kein Model-Switch, keine Crew-Panes) |
+| Tool `crew_discover` | Live-Modell-Discovery von Pi, Claude, Codex, Grok, Kimi mit 15min Cache |
+| Tool `crew_evidence` | Lokale Crew-Evidenz aus no-mistakes Outcomes anzeigen (aggregiert nach Task-Klasse/Modell) |
+| Tool `crew_update_check` | Kompatibilitätsprüfung mit aktueller Firstmate-Version |
 | Command `/crew-route …` | Slash-Einstieg: vollständige `crew_route`-Ausgabe via Widget/Notify/Status (ohne Truncation, ohne Editor) |
 
 ### Empfohlener Ablauf im Primary
@@ -61,10 +72,35 @@ Ohne aufgelöstes Home (`FM_HOME` oder Fallback `FM_ROOT_OVERRIDE`) nur Dry-Run/
 
 Datengetrieben unter [`knowledge/`](knowledge/):
 
+### Basis-Knowledge (Ebene 0)
 - `task-classes.json` — trivial_fix, standard_ship, hard_multi_file, research_web_live, scout_audit
-- `providers.json` — Rollen/Stärken Claude · Codex · Cursor · Grok, Pi-Model-Muster (`provider/model`)
+- `providers.json` — Rollen/Stärken Claude · Codex · Cursor · Grok · Kimi, Pi-Model-Muster (`provider/model`)
 - `profiles.json` — konkrete Profile + Dispatch-Template
 
+### Drei-Ebenen Knowledge System
+
+#### A. Hersteller-Fakten (`knowledge/manufacturers/`)
+- Offizielle Dokumentation von Anthropic, OpenAI, xAI, Moonshot AI
+- Source: `official-docs` | `manufacturer-claim`
+- Confidence: `high` (official-docs) | `low` (manufacturer-claim)
+
+#### B. Externe Benchmarks (`knowledge/benchmarks/`)
+- Artificial Analysis, HumanEval, MBPP, Coding-Benchmarks
+- Source: `external-benchmark`
+- Confidence: `medium`
+
+#### C. Lokale Crew-Evidenz (`knowledge/local/`)
+- Automatisch gesammelt aus no-mistakes Outcomes
+- Source: `local`
+- Confidence: `measured`
+- **Privacy:** Nur Metriken (Task-Klasse, Harness, Provider, Modell, Effort, Duration, Success, Tests, CI, Rework) – keine Code-Inhalte, keine Prompts
+
+### Source-Konflikt-Hierarchie
+
+- **"Was ist verfügbar?"**: Live Discovery > Auth State > Manufacturer Website
+- **"Was kann es?"**: Official Docs > Website > Discovery
+- **"Wie gut?"**: Local Evidence > External Benchmarks > Manufacturer Claims
+
 Tabellen aktualisieren, ohne Scorer-Code anzufassen.
 
 ## Fail-closed / Degraded
@@ -81,6 +117,24 @@ npm test
 
 Tests laufen ohne Netzwerk gegen Fixture-JSON unter `tests/fixtures/`.
 
+### Test Coverage
+
+- **Phase 1 (Discovery)**: `tests/discovery.test.ts` – Live Model Discovery, Caching, Staleness
+- **Phase 2 (Knowledge Layers)**: `tests/knowledge-layers.test.ts` – Drei-Ebenen System, Conflict Resolution
+- **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
+
+Alle Tests müssen grün sein (`npm test`).
+
+## Architektur-Prinzipien
+
+- **Firstmate bleibt Authority**: crew-knowledge liefert nur Empfehlungen
+- **Kein Competing Dispatch Engine**: Nutzt Firstmate's `quota-array-dispatch`
+- **Respektiert config/crew-dispatch.json**: Natural Language Rules bleiben authoritative
+- **Provider ≠ Model ≠ Harness**: Klare Trennung, kein Inferieren
+- **Herdr ist Infrastructure**: Backend-Wahl beeinflusst nicht Model-Qualität
+
 ## Lizenz
 
 MIT