arcodangeandClaude Fable 5
f2a60817e2
The harness layer (builder sessions, cold verifiers, evidence flow) gets a committable home, per the PRD model-fleet § harness portability and erp#63: - fleet/harness/verifier/: the two canonical verifier tests (locate-test, cold-reader backlog audit) with pinned inputs, verbatim prompts, ground truth and pass rules — judged context-free, never self-graded. - fleet/harness/bin/run-verifier.sh: runs a test against any OpenAI-style local endpoint (Ornith/MLX) or vibe -p (Mistral); emits sha256-pinned JSON transcripts. - fleet/harness/bin/vibe-builder.sh: the bounded shell for scoped builders and recurring tasks — refuses the trunk (linked-worktree guard), hard --max-turns/--max-price caps, full JSON journal per run. - fleet/README.md layout + AGENTS.md Fleet section updated in the same change (same-change freshness rule). Part of erp#63 (harness portability spike, D2). Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh
100 lines
6.4 KiB
Markdown
100 lines
6.4 KiB
Markdown
# fleet/ — the atom registry
|
||
|
||
The fleet is Arcodange's AI back-office: narrow agents ("atoms") that operate the
|
||
Dolibarr ERP's daily admin & accounting under the
|
||
[AI back-office PRD](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md).
|
||
This directory is the **registry** — the versioned source of truth for what the
|
||
fleet may do. **An atom absent from the registry does not run.** Contract semantics
|
||
come from the PRD [atom contract](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md#atom-contract);
|
||
file syntax from the PRD [document surface](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-catalog.md#the-document-surface-agents-read).
|
||
|
||
## What an atom is
|
||
|
||
One narrow capability (classify, extract, validate, record, reconcile, report,
|
||
remind) with a **strict I/O contract** and **deterministic validators around it**.
|
||
The LLM proposes, code disposes: formats, arithmetic, checksums, dedupe and
|
||
referential integrity are enforced by validators, and a model output that fails
|
||
validation is **quarantined, never auto-corrected**. Workflows are compositions of
|
||
atoms with explicit gates — never one prompt that "does the accounting".
|
||
|
||
Each atom lives in `fleet/atoms/<atom>/`:
|
||
|
||
| File | Role |
|
||
| --- | --- |
|
||
| `atom.yaml` | the registry entry — the contract (schema below) |
|
||
| `prompt.md` | thin runtime prompt, ≤ ~40 lines, extends exactly one class skeleton; **no business rules** (rules live in `fleet/profile/` and in validators) |
|
||
| `scripts/` | the deterministic implementation: runners, validators, scoring hooks |
|
||
|
||
Folder name = atom name = registry `name` — the house `<app>` join-key discipline
|
||
applied to atoms.
|
||
|
||
## Layout
|
||
|
||
```
|
||
fleet/
|
||
├── README.md # this file: registry doc + atom.yaml schema
|
||
├── classes/ # the 7 prompt skeletons (PRD agent catalog)
|
||
│ ├── sentinel.md
|
||
│ ├── extractor.md
|
||
│ ├── erp-scribe.md
|
||
│ ├── deterministic-controller.md # no-LLM by design
|
||
│ ├── analyst-writer.md
|
||
│ ├── researcher.md
|
||
│ └── knowledge-archivist.md
|
||
├── atoms/
|
||
│ └── invoice-extract/ # T02 — the worked example (contract only; implementation = erp#40)
|
||
│ ├── atom.yaml
|
||
│ ├── prompt.md
|
||
│ └── scripts/
|
||
├── golden/ # per-atom golden sets — land with erp#39
|
||
├── profile/ # fiscal.yaml + calendar.yaml + ADC register — land with erp#54
|
||
└── harness/ # multi-runtime harness layer: verifier tests + builder bench (harness/README.md)
|
||
```
|
||
|
||
## `atom.yaml` — the contract, field by field
|
||
|
||
Per the PRD [atom contract](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md#atom-contract):
|
||
|
||
| Field | Meaning |
|
||
| --- | --- |
|
||
| `name`, `version` | Identity. Folder name = `name`. `version` bumps on **any** behavioral change (prompt, model, validator) — a bump re-triggers the atom's golden-set evals. |
|
||
| `input_schema` / `output_schema` | JSON Schema for the atom's I/O; enforced at runtime (constrained decoding where the model tier supports it). |
|
||
| `invariants` | Deterministic post-conditions checked by code after every run (e.g. `HT + TVA == TTC ± 0.01`). A failed invariant quarantines the output — refuse, never repair. |
|
||
| `side_effect_class` | `read` · `draft` · `write-sandbox` · `write-prod` · `outbound` — drives which gates and credentials apply, per the PRD [environment posture table](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md#environments--sandbox-vs-production). |
|
||
| `idempotency_key` | How a replay is recognized (e.g. supplier + `ref_supplier` + TTC) — a second run with the same key must be a no-op. |
|
||
| `autonomy` | The **earned** level (A0–A3 on the [autonomy ladder](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md#the-autonomy-ladder)) + a pointer to the eval evidence that justifies it. |
|
||
| `model_policy` | Preferred tier, fallbacks, escalation rule, per the PRD [model fleet](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/model-fleet.md); closed per-atom by routing-bench evidence (erp#45 for the first atoms). |
|
||
| `eval_ref` | Where the golden set + scoring script live (`fleet/golden/<atom>/`). |
|
||
|
||
Two registry conveniences beyond the PRD contract fields bind the entry to the rest
|
||
of the surface: `class` (which `fleet/classes/<class>.md` skeleton the prompt
|
||
extends) and `task` (the PRD [task-inventory](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/task-inventory.md)
|
||
id the atom serves).
|
||
|
||
The worked example is [`atoms/invoice-extract/atom.yaml`](atoms/invoice-extract/atom.yaml)
|
||
(T02) — contract only; its implementation is
|
||
[erp#40](https://gitea.arcodange.lab/arcodange-org/erp/issues/40).
|
||
|
||
## How an atom graduates
|
||
|
||
Autonomy is **earned per atom, never assumed**. The levels (A0 manual → A1 prepare
|
||
→ A2 rehearse + gate → A3 autonomous + audit) are defined on the PRD
|
||
[autonomy ladder](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md#the-autonomy-ladder);
|
||
promotion and demotion are mechanical, per the PRD
|
||
[autonomy promotion gates](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/qa-strategy.md#autonomy-promotion-gates)
|
||
(golden-set evals, unedited-approval streaks, incident demotion — the bars live
|
||
there, not here). The earned level and its evidence are recorded in the atom's
|
||
`autonomy` field: a promotion is a PR that changes that field with the evidence
|
||
linked, verified per the QA strategy's independent-verification rule.
|
||
|
||
## Conventions
|
||
|
||
- **English** for all agent-facing files (house language policy).
|
||
- **Same-change freshness**: a change to an atom that leaves its
|
||
`atom.yaml` / `prompt.md` stale is an incomplete change.
|
||
- **One capability per file**; YAML/frontmatter over prose for anything a machine
|
||
parses.
|
||
- Environment rules (trunk hygiene, read-only prod, sandbox-first writes, promote
|
||
gate) are the repo-wide ones: [`AGENTS.md`](../AGENTS.md) operating rules +
|
||
[`dolibarr-sandbox-write` SKILL.md](../.claude/skills/dolibarr-sandbox-write/SKILL.md).
|