arcodange-org/factory
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(prd): AI back-office — agent fleet for daily admin & accounting

Browse Source 
New PRD tree vibe/PRD/ai-back-office/ (hub + 6 leaves + STATUS): task
inventory T01-T16 with mode operatoire, atom/contract architecture on
the ADR-0003 write gate, four-tier model fleet (Claude/Mistral/M4/Pi),
12 challenges with mitigations, POC plan with exit criteria, QA
strategy with autonomy promotion gates. Index row + bidirectional
backlinks (erp guidebook, safe-prod PRD).

Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
arcodange
2026-07-11 14:25:04 +02:00
co-authored by Claude Fable 5
parent 5a80ec32ae
commit 169c8debb4
11 changed files with 867 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vibe/PRD/ai-back-office/README.md
+163
View File
@@ -0,0 +1,163 @@
[vibe](../../README.md) > [PRD](../README.md) > **AI back-office**
# AI back-office — an agent fleet for daily admin & accounting
> **Status:** In design
> **Last Updated:** 2026-07-11
> **Foundations:** [ADR 0002 — per-application environments](../../ADR/0002-per-application-environments.md) · [ADR 0003 — sandbox state lifecycle](../../ADR/0003-sandbox-state-lifecycle.md)
> **Map:** [ERP guidebook](../../guidebooks/erp/README.md)
> **Adjacent:** [Safe, production-like environment](../safe-prod-like-environment/README.md) (same rehearse-before-prod philosophy)
## Problem
Arcodange is a one-person SAS (software consulting, incorporated January 2026). The same person is the engineer, the salesperson, and the entire back office. The recurring administrative and accounting work — pulling supplier invoices out of mailboxes, recording them in Dolibarr with the right VAT ventilation, issuing the monthly client invoice with its mandatory legal mentions, reconciling Qonto/Wise against the ERP, preparing TVA, watching fiscal deadlines — is manual, interrupt-driven, and competes directly with billable work. Volumes are small (tens of documents a month), so the pain is not throughput: it is **consistency, deadline safety, and cognitive load**. A missed acompte, a malformed invoice, or an unrecorded supplier bill carries fiscal and legal risk out of proportion with the five minutes it would have taken.
Most of the hard groundwork already exists: a read-only skill catalogue over the Dolibarr API (invoices, payments, TVA, thirdparties, templates, snapshots), bank-side reconciliation over the Qonto and Wise APIs, Zoho mailbox ingestion, an iso-prod ERP sandbox with a write-scoped agent and a human-gated promote flow ([ADR 0003](../../ADR/0003-sandbox-state-lifecycle.md)), daily off-site backups with tested restore, and a Telegram webhook gateway. But these bricks only run **when a human thinks to launch them**. There is no standing fleet, no scheduler, no policy that routes the right task to the right model, and no explicit autonomy contract saying which agent may do what unattended.
Meanwhile three dated regulatory obligations are about to *raise* the admin surface: **e-invoice reception becomes mandatory for every French company on 2026-09-01**; the **régime réel simplifié de TVA disappears on 2027-01-01** (the annual CA12 + acomptes give way to quarterly CA3 declarations); and **e-invoice emission plus e-reporting of international transactions becomes mandatory for PME on 2027-09-01** — which covers Arcodange's export invoices to its US client. Doing nothing means strictly more paperwork every quarter from 2027.
## Users & personas
A **single operator wearing three hats**, plus the fleet itself:
- **The operator** — wants mornings without paperwork: a Telegram digest, a handful of one-tap approvals, and the confidence that nothing fiscal is silently overdue.
- **The verifier** — the same person in accounting mode: wants every agent action traceable (journals, snapshots, manifests), every write rehearsed before prod, and evidence packs good enough to hand to an expert-comptable or an auditor.
- **The platform engineer** — maintains the fleet: wants atoms that are boring to operate, measurable, and cheap to retire. An atom that needs weekly babysitting is a failed atom.
- **The agents** — consumers of contracts: each atom needs typed inputs/outputs, explicit guardrails, and a defined escalation path, so that models of very different sizes can be swapped behind the same interface.
## Goals & non-goals
**Goals**
- **Enumerate every recurring admin/accounting task** with an explicit mode opératoire, guardrails, and a target autonomy level — the [task inventory](task-inventory.md) is the requirement backbone of this PRD.
- **Atomic excellence**: each capability is one narrow, contract-bound atom (extract, validate, record, reconcile, report) that does its one job measurably well. Formats are guaranteed by **deterministic validators, not by model goodwill** — the LLM proposes, code disposes.
- **The right model for each job** across four tiers — Claude (frontier reasoning), Mistral (EU cloud), local model on the M4 MacBook, SLM on the Raspberry Pi cluster — with graceful degradation when a tier is unavailable. See [model fleet](model-fleet.md).
- **Human-gated writes as an invariant**: every ERP mutation is rehearsed on the sandbox and promoted through the existing ADR-0003 gate; approvals and digests flow through Telegram. See [agent architecture](agent-architecture.md).
- **Efficiency**: routine admin costs the human ≤ 15 minutes/day (review + approvals), with hard deadlines never carried in a human head.
- **Resilience**: no single point of failure — a cloud outage degrades to local triage + queueing, every write is replayable from manifests, books are restorable (tested backups) and provable (content-hashed snapshots).
- **Prove feasibility with real POCs** — actual implementations against the real mailbox, real bank feeds, and the iso-prod sandbox. See the [POC plan](poc-plan.md).
**Non-goals**
- **No agent ever moves money.** Executing payments, transfers, or anything on a bank's write path is permanently out of scope. Agents *record* what happened and *prepare* what should happen; a human executes.
- **No transfer of legal responsibility.** Declarations (TVA, liasse fiscale, annual accounts) are prepared by agents and **signed/filed by the human**; this PRD does not replace an expert-comptable's advice.
- **No GPU purchases, no fine-tuning farm** in v1 — off-the-shelf models only, on hardware the lab already owns.
- **Not a multi-tenant product.** Atoms are written cleanly enough to generalize, but Arcodange is the only tenant.
- **No payroll/DSN automation** until Arcodange actually pays a salary (explicit trigger to revisit).
## The autonomy ladder
Every task in the inventory carries a target level. Promotion up the ladder is earned through measured evals (see [QA strategy](qa-strategy.md)), never assumed.
| Level | Name | Meaning |
| --- | --- | --- |
| **A0** | Manual | Human does the task; agents at most document it. |
| **A1** | Prepare | Agent produces the draft/computation; human executes the action. |
| **A2** | Rehearse + gate | Agent executes fully against sandbox/draft state; human approves; the gated apply hits prod. |
| **A3** | Autonomous + audit | Agent acts unattended; human audits via digest and sampling. Reserved for read-only or trivially reversible actions. |
## Architecture at a glance
```mermaid
%%{init: {'theme':'base'}}%%
flowchart TB
subgraph sources["Inbound sources"]
zoho["Zoho mail<br>books@ · bureaux@"]:::src
bank["Qonto + Wise APIs"]:::src
cal["Compliance calendar"]:::src
end
subgraph fleet["Agent fleet — atoms on four model tiers"]
pi["Pi tier (24/7 sentinel)<br>triage · reminders"]:::proc
m4["M4 tier (local)<br>sensitive extraction"]:::proc
mistral["Mistral tier (EU cloud)<br>2nd extractor · OCR"]:::proc
claude["Claude tier (frontier)<br>business validation · orchestration"]:::proc
end
validators["Deterministic validators<br>format + arithmetic + dedupe"]:::gate
sandbox["ERP sandbox<br>rehearsed writes (ADR-0003)"]:::store
tg["Telegram gateway<br>digest · approval cards"]:::gate
human["Human gate"]:::gate
prod["ERP prod (Dolibarr) + GED<br>snapshots · daily backups"]:::store
sources --> pi
pi --> m4
pi --> mistral
m4 --> validators
mistral --> validators
validators --> claude
claude --> sandbox
sandbox --> tg
tg --> human
human --> prod
classDef src fill:#2563eb,stroke:#1e40af,color:#fff
classDef proc fill:#059669,stroke:#047857,color:#fff
classDef store fill:#7c3aed,stroke:#6d28d9,color:#fff
classDef gate fill:#b45309,stroke:#92400e,color:#fff
```
1. **Inbound sources** — the Zoho mailboxes (`books@` for supplier invoices, `bureaux@` for administration), the Qonto/Wise bank APIs, and a machine-readable compliance calendar — feed the fleet.
2. The **Pi tier** watches 24/7: it classifies inbound items, fires deadline reminders, and routes work — its outputs are classifications and reminders, never actions or writes.
3. Extraction runs on the **M4 tier** (sensitive documents stay on-device) and/or the **Mistral tier** (EU cloud, second opinion, OCR); critical fields require cross-model agreement.
4. **Deterministic validators** — arithmetic, VAT rates, checksums, dedupe keys — are the format guarantors; anything that fails is quarantined, never guessed.
5. The **Claude tier** performs business-level validation against the fiscal profile, assembles write manifests, and orchestrates.
6. Writes are **rehearsed on the ERP sandbox**, surfaced as **Telegram approval cards**, and only the **human gate** promotes them to **prod**, where snapshots and daily backups close the evidence loop.
## Requirements
- **[Task inventory](task-inventory.md)** — the enumerated tasks (T01–T16 + backlog), each with trigger, mode opératoire, guardrails, current tooling, and target autonomy. *This is the functional requirement set.*
- **[Agent architecture](agent-architecture.md)** — atom contracts, pipeline shape, write safety, security model (least-privilege ephemeral ERP credentials), prompt-injection defenses, runtimes/scheduling, and the human channel.
- **[Model fleet](model-fleet.md)** — the four tiers, routing policy, structured-output enforcement, availability model, degraded modes, and cost envelope.
- **[Challenges](challenges.md)** — the twelve identified risks and their mitigation strategies (the technical "second temps" of this PRD).
- **[POC plan](poc-plan.md)** — feasibility proofs as real implementations, ordered, with exit criteria.
- **[QA strategy](qa-strategy.md)** — golden sets, eval harness, autonomy promotion gates, parity checks, and ops QA. Mandatory per PRD convention.
**Regulatory milestones the roadmap must respect:**
| Date | Obligation | Impact here |
| --- | --- | --- |
| **2026-09-01** | E-invoice **reception** mandatory for all companies | Inbound supplier pipeline gains a structured source: a PDP (*plateforme de dématérialisation partenaire* — accredited e-invoicing platform); PDP choice + Dolibarr wiring needed *before* this date. |
| **2026-12** | TVA acompte de décembre (réel simplifié) | Calendar + preparation atom (expected ≈ 0 € while in TVA credit — verify, don't assume). |
| **2027-01-01** | Régime réel simplifié **supprimé** → quarterly **CA3** | TVA preparation atom must produce quarterly CA3 sheets from 2027-Q1; last CA12 (FY 2026) filed ~May 2027. |
| **2027-09-01** | E-invoice **emission** (PME) + **e-reporting** of international transactions | Outbound invoices to the US client must flow through a PDP; emission pipeline + e-reporting atom. |
## Success criteria
- **Human time**: routine admin ≤ 15 min/day median (measured weekly from digest interactions), excluding exceptional events.
- **Supplier invoices**: 100 % recorded in Dolibarr with attached PDF within 48 h of arrival; extraction accuracy ≥ 98 % on critical fields (amounts, IBAN, refs, dates) over the golden set — overall field accuracy tracked alongside — before any atom reaches A2.
- **Bank**: weekly reconciliation with zero unexplained deltas older than 7 days.
- **TVA**: every declaration prepared ≥ 5 days before its deadline; dry-run figures match filed figures exactly (€-parity).
- **Write safety**: zero prod writes outside the manifest → gate → promote path; 100 % of writes replayable from journals.
- **Resilience**: triage and reminders keep running through a full cloud outage (Pi tier alone); monthly restore drill passes.
- **Cost**: cloud inference spend ≤ 30 €/month at current volumes (alert at 20 €).
## Phased roadmap
| Phase | Scope | Anchor |
| --- | --- | --- |
| **0 — Foundations** | Read skills, sandbox + promote gate, backups, snapshots, bank reco, email ingest, Telegram gateway MVP | ✅ shipped pre-PRD (see [STATUS](STATUS.md)) |
| **1 — Flagship pipeline** | POC-1 supplier-invoice end-to-end + POC-5 routing bench | proves A2 write loop |
| **2 — Urgent compliance** | E-invoicing reception readiness (PDP choice, ADR, Dolibarr wiring) | **hard deadline 2026-09-01** |
| **3 — Standing fleet** | POC-2 Pi sentinel, scheduler/queue, digest + approval cards | proves 24/7 + degraded modes |
| **4 — Money loops** | POC-3 reconciliation + payment recording, dunning drafts, cash report | closes the bank↔ERP loop |
| **5 — Fiscal autopilot** | POC-4 TVA dry-runs (acomptes, CA12 2026, CA3-2027 simulation), compliance calendar | proves €-parity before 2027 regime switch |
| **6 — Emission era** | E-invoice emission + e-reporting pipeline (PME deadline) | **hard deadline 2027-09-01** |
Phases are streams, not strict gates: **phase 2 starts immediately, in parallel with phase 1** — its 2026-09-01 deadline cannot wait for the flagship. Tasks not named in a phase ride the nearest infrastructure: T05 (and decision D3) lands with phase 4's money loops, T12/T15 with phase 5's fiscal autopilot, and T16 grows out of POC-1's GED attach.
## QA strategy
Golden datasets built from real history (mails, invoices, filed declarations), a per-atom eval harness with field-level scoring and injection fixtures, autonomy promotions earned only through measured gates (and revoked on incident), predicted-delta assertions around every write, €-parity dry-runs for fiscal outputs, and ops QA (heartbeats where silence itself alerts, monthly restore drills, quarterly degraded-mode game-days). Full detail: [qa-strategy.md](qa-strategy.md).
## Leaves
| Page | Summary | Status |
| --- | --- | --- |
| [Task inventory](task-inventory.md) | T01–T16 + backlog: trigger, mode opératoire, guardrails, current tooling, target autonomy per task. | 🟡 In design |
| [Agent architecture](agent-architecture.md) | Atom contracts, pipeline shape, write safety, security, injection defenses, runtimes, human channel. | 🟡 In design |
| [Model fleet](model-fleet.md) | Four tiers, routing policy, structured outputs, availability, degraded modes, cost. | 🟡 In design |
| [Challenges](challenges.md) | Twelve risks with mitigation strategies and residual ownership. | 🟡 In design |
| [POC plan](poc-plan.md) | Ordered feasibility proofs with exit criteria and challenge coverage. | 🟡 In design |
| [QA strategy](qa-strategy.md) | Golden sets, eval harness, promotion gates, parity checks, ops QA. | 🟡 In design |
| [STATUS](STATUS.md) | Foundation ledger (shipped PRs) + phase tracker. | 🟢 Current |