docs(prd): agent catalog — task→(prompt+model+orchestrator) matrix + agent-facing file syntax

New agent-catalog.md leaf answering three operator directions: (1) the document surface agents read is now specified — AGENTS.md orientation maps, SKILL.md with trigger-carrying descriptions (Use-when/SKIP-for), atom.yaml registry contracts, thin prompt.md files (no business rules in prompts — rules live in profile files and validators), schema'd fiscal.yaml/calendar.yaml with effective_from dates, [AGENT]/[HUMAN] runbooks, env-var-indirected .mcp.json; same-change freshness rule extended to the fleet. (2) hermes's telegram-gateway confirmed as THE human channel when available (cluster-served cards, email fallback; D1 operator-endorsed). (3) the categorization to prove: seven agent classes (incl. the LLM-free deterministic controller) and a T01-T17 assignment matrix with per-row proof gates and statuses (proven / to-prove / not-built), re-scored monthly from run journals (fallback rate >20% = wrong cell). New D8 (fleet code home, leaning erp fleet/). Co-Authored-By: Claude Fable 5 <[email protected]>
2026-07-11 15:09:28 +02:00
parent 5430e5f3ac
commit 8e4186dbeb
4 changed files with 82 additions and 4 deletions
@@ -31,7 +31,7 @@ Every atom is registered in a versioned YAML registry (git) with:
 | `model_policy` | Preferred tier, fallbacks, escalation rule ([model fleet](model-fleet.md)). |
 | `eval_ref` | Golden set + scoring script for this atom. |

-The registry is the source of truth for what the fleet may do; an atom absent from the registry does not run.
+The registry is the source of truth for what the fleet may do; an atom absent from the registry does not run. File layout, prompt syntax, and the full agent-facing document surface (`AGENTS.md`, `SKILL.md`, `atom.yaml`, `prompt.md`, profile files) are specified in the [agent catalog](agent-catalog.md#the-document-surface-agents-read).

 ## The pipeline shape

@@ -149,6 +149,8 @@ Inbound documents are adversarial by default — an invoice PDF or a mail body c

 ## Human channel

+The channel is **hermes's telegram-gateway whenever it is available** (operator direction, 2026-07): the gateway runs on the cluster, so digests and approval cards are served 24/7 without depending on the laptop being awake — the M4-side hermes runtime consumes the same gateway for its own jobs. When the gateway is down, the fleet keeps queueing, the digest falls back to plain email, and the [degraded-modes table](model-fleet.md#degraded-modes) applies.
+
 - **One daily digest** (Telegram, morning): items awaiting approval, quarantined items, aging unresolved work, heartbeat summary, upcoming deadlines (D-30/D-7/D-1). An empty day still sends "all green" — silence must be distinguishable from failure.
 - **Approval cards**: one decision per card (approve / edit / reject-with-reason); rejection reasons are first-class data feeding golden sets.
 - **Escape hatch**: every automated lane has a documented manual runbook fallback (the fleet augments the operator; it never becomes the only way to run the company).
@@ -170,12 +172,13 @@ To be settled by POC evidence, each closing with a short ADR:

 | # | Decision | Options (leaning) |
 | --- | --- | --- |
-| D1 | Work queue | telegram-gateway's planned Postgres durable queue (**leaning** — already roadmapped, transactional, one less system) vs. flat files in git vs. Redis |
+| D1 | Work queue | telegram-gateway's planned Postgres durable queue (**leaning, operator-endorsed 2026-07** — already roadmapped, transactional, one less system) vs. flat files in git vs. Redis |
 | D2 | Orchestration runtime | Claude Agent SDK headless for cluster-triggered jobs + **hermes** for M4-side lanes (**leaning** — hermes already runs skills + cron there) vs. bespoke TS orchestrator (erp `test/` Deno codebase) vs. pure CronJobs + scripts |
 | D3 | KM monthly invoice firing | enable Dolibarr template auto-fire (`frequency>0`) vs. agent-fired via sandbox+promote (**leaning** — keeps the gate + mention audit in-line) |
 | D4 | PA — e-invoicing platform (*plateforme agréée*, ex-PDP) | **Leaning: Qonto** (operator direction, 2026-07 — the capital-deposit bank, DGFiP-registered PA, e-invoicing included in every plan, and the fleet's richest existing API integration); POC-6 validates reception + API pull before the ADR — **must close before 2026-09-01** ([C12](challenges.md#c12--e-invoicing-reform-unknowns)) |
 | D5 | OCR provider for scanned docs | Mistral OCR (EU cloud) vs. local vision model on M4 vs. Tesseract baseline |
 | D6 | Pi inference serving | llama.cpp server vs. Ollama on arm64, resource limits, node pinning ([C5](challenges.md#c5--slm-capability-ceiling-on-pi-hardware)) |
 | D7 | Cluster↔vault access | git clone/pull of the SecondBrain remote (**leaning** — the Gitea remote exists, offline-friendly, reviewable) vs. tunneled Obsidian REST API (M4-only today) vs. keeping vault access M4-exclusive |
+| D8 | Fleet code home | erp repo `fleet/` next to the skills (**leaning** — the atoms are ERP-domain today; revisit into a dedicated repo when a second domain joins) vs. dedicated fleet repo vs. scattered per existing repo |

-D4–D6 close with their mapped POCs ([POC-6](poc-plan.md#poc-6--e-invoicing-readiness-spike), [POC-5](poc-plan.md#poc-5--model-routing-bench), [POC-2](poc-plan.md#poc-2--pi-sentinel)); D1–D2 are settled while building phase 3's standing fleet (the queue and scheduler *are* its skeleton); D3 lands with phase 4's money loops; D7 closes when the first cluster-side atom needs vault context (phase 3 at the earliest).
+D4–D6 close with their mapped POCs ([POC-6](poc-plan.md#poc-6--e-invoicing-readiness-spike), [POC-5](poc-plan.md#poc-5--model-routing-bench), [POC-2](poc-plan.md#poc-2--pi-sentinel)); D1–D2 are settled while building phase 3's standing fleet (the queue and scheduler *are* its skeleton); D3 lands with phase 4's money loops; D7 closes when the first cluster-side atom needs vault context (phase 3 at the earliest); D8 rides POC-1 — the first atoms need their home on day one.