arcodangeandClaude Fable 5
a482bb18c4
fleet/profile/ goes from stub to the machine-readable business-rules surface the fleet reads (PRD agent-catalog document surface + compliance ADC framework): - fiscal.yaml — entity, VAT position, 8 rules (regime reel simplifie until 2026-12-31 -> quarterly CA3 from 2027-01-01 per LF 2025 art. 38; KM export autoliquidation 259-1 CGI box E2; FR 20% deductible; intra-EU reverse charge; FX 766/666; SaaS expensed; CCA 455 lane). Every rule carries effective_from/effective_until AND decision: adc-NNN; every date cites its PRD anchor as an inline comment (verified against factory origin/main). - calendar.yaml — 15 entries: acomptes TVA (2026-07 month-window, 2026-12-15), last CA12 FY-2026 (2027-05-04), CA3 quarterly windows, CFE (December), AG comptes annuels (2027-06-30), e-invoicing milestones (2026-09-01 reception, 2027-09-01 emission/e-reporting), URSSAF echeancier with the in-file NOTE that a real direct debit exists since May 2026 (erp#57 revisit of the payroll-dormant assumption), KM deferred due dates + renewal stub. - JSON Schemas for both + scripts/validate.py (stdlib-only: strict YAML-subset parser, JSON-Schema-subset checker, rule->ADC resolution, calendar checks). - decisions/ — ADC register: template + adc-001..005 Accepted formalizations (autoliquidation KM, FX->766/666, SaaS expensed, reel simplifie until abolition, CCA personal-card lane) + adc-006/007 Proposed stubs (retainer currency -> erp#53; capital path -> erp#51). Agents draft, the operator Accepts — never the reverse; immutable once merged, supersede never edit. - Mutation policy in-file: PRs only (T12 proposes, human merges). - Same-change: profile README stub -> real doc; fleet/README.md layout line and AGENTS.md fleet row updated (profile no longer a stub). Validation: PASS — 8 rules, 15 entries, 7 ADCs, 0 errors, 7 warnings (the warnings list exactly what awaits operator verification). Human gate left open on purpose: operator sanity-read of the calendar + Acceptance of adc-001..005. 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 + validator (profile/README.md)
|
||
└── 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).
|