# erp — Dolibarr ERP & the AI back-office fleet

This repo runs Arcodange's **Dolibarr 22.0.4 ERP** (the company's book of record) and hosts the tooling + AI-agent skills that operate its daily admin & accounting. Deployed by the factory ArgoCD app-of-apps: **prod** at `erp.arcodange.lab`, **iso-prod sandbox** at `erp-sandbox.arcodange.lab`. Ecosystem front door: [factory AGENTS.md](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/AGENTS.md).

## Where the work comes from — the backlog

The [AI back-office PRD](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md) is decomposed into **self-contained issues** on dated milestones. Each issue body carries its context, deliverables, acceptance criteria, dependencies and PRD links — no conversation history needed.

- **Resume protocol: pick the top unblocked issue of the earliest open [milestone](https://gitea.arcodange.lab/arcodange-org/erp/milestones)** (P1 flagship → P2 e-invoicing *hard 2026-09-01* → P3 standing fleet → ledger compliance → P4 money loops → P5 fiscal).
- From a session: `ToolSearch select:mcp__gitea__list_issues,mcp__gitea__issue_read`, then owner `arcodange-org`, repo `erp`. Related backlogs: [telegram-gateway issues](https://gitea.arcodange.lab/arcodange/telegram-gateway/issues) (owner `arcodange`, **not** arcodange-org) and [factory#22](https://gitea.arcodange.lab/arcodange-org/factory/issues/22) (ADR tracking).
- Full phase tracker + backlog map: the PRD [STATUS.md](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/STATUS.md).

## Map

| Path | What |
| --- | --- |
| `chart/` | Helm chart (prod + sandbox overlay), backup CronJob, before-start SQL |
| `ops/` | `sandbox/sandbox-lifecycle.sh` (iso-prod refresh), `backup/` (offsite db+docs, restore) |
| `bin/arcodange` | operational CLI — read prod (invoices, payments, TVA, bank, templates, snapshot), sandbox writes, gated promote |
| `.claude/skills/` | the skill catalog; each `SKILL.md` frontmatter carries its **Use when… / SKIP for…** triggers — read them before reinventing |
| `test/` | Playwright provisioning POCs (sandbox write agent `ai_agent_sandbox`, rights in `provisionSandbox.ts` WRITE_IDS) |
| `fleet/` | the AI-agent fleet — atom registry + `atom.yaml` schema ([fleet/README.md](fleet/README.md)), class skeletons ([fleet/classes/](fleet/classes/)), worked example `invoice-extract`; fiscal profile + compliance calendar + ADC register ([fleet/profile/](fleet/profile/README.md)); golden sets are stubs ([erp#39](https://gitea.arcodange.lab/arcodange-org/erp/issues/39)) |

## Operating rules for agents

- **Trunk is reserved for the user.** Work in a worktree under `.claude/worktrees/<slug>/` on an `arcodange/<slug>` branch. This forge is **Gitea** — use the `mcp__gitea__*` tools for PRs/issues; `gh` fails silently.
- **Prod is read-only for agents** (`ai_agent` key from `.claude/skills/dolibarr/.env`, mode 600). Beware the `voir_tous` ACL trap: a missing permission returns empty lists, not errors.
- **Writes rehearse on the sandbox first** (`ai_agent_sandbox`, host-guarded — structurally cannot reach prod), then reach prod only through the human-gated promote flow (`arcodange promote plan|apply`, prod key ENV-only + explicit confirm) — [ADR-0003](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/ADR/0003-sandbox-state-lifecycle.md).
- **Production is an append-only ledger**: create → validate → pay → avoir; never mutate or delete a validated document, never fabricate a ref Dolibarr owns. Full grammar + anti-hallucination write contract (provenance anchors, fresh-feed corroboration, refuse-never-repair): PRD [compliance](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/compliance.md) + [agent-architecture](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md).
- **Choose the accounting instrument before writing, and read the existing state to check the choice.** *Who does the company owe?* A real supplier → supplier invoice; URSSAF or the tax office → social charge; **the associé himself → various payment on `CCA1`, with no thirdparty at all**. Neither URSSAF nor the gérant is a supplier: giving either a supplier record pollutes the auxiliary ledger, the aged balances and the payables reports, and is far costlier to undo than to avoid. The check that catches it is free — **an entry whose model contradicts the entries already in the ledger is almost always wrong**. This also decides the technical path: `/chargesociales` and `/variouspayments` have **no REST API**, so the gated promote cannot carry them (UI scripts keep the sandbox rehearsal and prod opt-in, but have no judge and no gate artefact). [RUNBOOK_quel_instrument.md](.claude/skills/dolibarr-sandbox-write/RUNBOOK_quel_instrument.md), `adc-010`.
- Sandbox state is disposable: `bin/arcodange sandbox checkpoint {status|refresh|provision|relink-env}` (refresh re-seeds iso-prod and wipes the write agent → re-provision, human login). Anything irreversible-by-design is trialed on a checkpoint first.
- Bank feeds (Qonto/Wise) and the Zoho mailbox are **read-only by construction**; no agent ever moves money.
- **Doc freshness.** Docs describe intent; the PRD STATUS + git describe reality. Before acting on any versionable claim (a path exists, a flag's value, a status emoji), verify in trust order: **live system > code/git log > [PRD STATUS](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/STATUS.md) > PRD leaves > memories**. A PR that makes a documented claim false updates that doc **in the same PR**; whoever closes a milestone follows the QA-gated [closure protocol](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/STATUS.md) — the QA gate is held by an **independent context-free subagent prompted to refute** (the closer never self-certifies) → flip STATUS → truth-pass docs → deprecation grep → fresh-reader smoke test — before the milestone closes.

## Fleet

- **Atom registry**: [`fleet/README.md`](fleet/README.md) — what an atom is, the `atom.yaml` contract schema field by field, the `fleet/` layout. An atom absent from the registry does not run.
- **Class skeletons**: [`fleet/classes/`](fleet/classes/) — the 7 prompt skeletons per the PRD [agent catalog](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-catalog.md#agent-classes); every atom's `prompt.md` extends exactly one, and prompts carry **no business rules** (those live in `fleet/profile/` + validators).
- **Environment rules**: the [operating rules](#operating-rules-for-agents) above + [`.claude/skills/dolibarr-sandbox-write/SKILL.md`](.claude/skills/dolibarr-sandbox-write/SKILL.md) (the host-guarded sandbox write path and its promote gate).
- **Autonomy ladder**: levels A0–A3 in the PRD [hub](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md#the-autonomy-ladder); promotion/demotion per the PRD [qa-strategy gates](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/qa-strategy.md#autonomy-promotion-gates).
- **Graduation**: an atom earns autonomy through its golden-set evals and unedited-approval streaks — the earned level + eval evidence live in its `atom.yaml` `autonomy` field, and a promotion is a PR changing that field with the evidence linked.
- **Harness**: [`fleet/harness/`](fleet/harness/README.md) — the multi-runtime execution layer around the atoms: canonical verifier tests (locate-test, backlog audit), `run-verifier.sh` for any OpenAI-style local endpoint or `vibe -p` (Mistral), and `vibe-builder.sh` (the capped, worktree-guarded shell for scoped builders and recurring tasks). Runtimes are admitted per role by evidence ([erp#63](https://gitea.arcodange.lab/arcodange-org/erp/issues/63)); Claude is the escalation tier, not a prerequisite, per the PRD [harness portability](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/model-fleet.md#harness-portability).

## Before building anything

Read the PRD hub (5 min) — problem, autonomy ladder A0–A3, architecture, agent catalog. Then your issue. Then the SKILL.md of anything you touch. A change that leaves its `SKILL.md` stale is an incomplete change.