erp/AGENTS.md

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.

Where the work comes from — the backlog

The AI back-office PRD 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 (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 (owner arcodange, not arcodange-org) and factory#22 (ADR tracking).
• Full phase tracker + backlog map: the PRD 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/	atom registry, class skeletons, golden sets — not yet landed, tracked by erp#38

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.
• 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 + agent-architecture.
• 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 > 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 (verify → flip STATUS → truth-pass docs → deprecation grep → fresh-reader smoke test) before the milestone closes.

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.