Files

T

arcodangeandClaude Fable 5 96c594e0ce feat(fleet): scaffold the atom registry — classes, contract, worked example, AGENTS.md section

Closes erp#38 deliverables: fleet/ layout, atom.yaml schema documented
in fleet/README.md, 7 class skeletons per the PRD agent-catalog,
invoice-extract as the worked example (contract only — implementation
is erp#40), golden/ + profile/ stubs, AGENTS.md Fleet section with
freshness fixes (fleet/ no longer "not yet landed").

Co-Authored-By: Claude Fable 5 <[email protected]>

2026-07-15 18:38:08 +02:00

6.7 KiB

Raw Blame History

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/`	the AI-agent fleet — atom registry + `atom.yaml` schema (fleet/README.md), class skeletons (fleet/classes/), worked example `invoice-extract`; golden sets + fiscal profile are stubs (erp#39, erp#54)

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 — 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 — 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/ — the 7 prompt skeletons per the PRD agent catalog; 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 above + .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; promotion/demotion per the PRD qa-strategy 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.

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.

6.7 KiB Raw Blame History Unescape Escape