arcodange-org/erp
1
0
Fork 0
Code Issues 18 Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
f027ff3c345396b213af1aa9c60253ffd640a9f4
erp/AGENTS.md
T
arcodangeandClaude Fable 5 f2a60817e2 feat(fleet): multi-runtime harness — verifier tests + capped builder shell 
The harness layer (builder sessions, cold verifiers, evidence flow) gets a
committable home, per the PRD model-fleet § harness portability and erp#63:

- fleet/harness/verifier/: the two canonical verifier tests (locate-test,
  cold-reader backlog audit) with pinned inputs, verbatim prompts, ground
  truth and pass rules — judged context-free, never self-graded.
- fleet/harness/bin/run-verifier.sh: runs a test against any OpenAI-style
  local endpoint (Ornith/MLX) or vibe -p (Mistral); emits sha256-pinned
  JSON transcripts.
- fleet/harness/bin/vibe-builder.sh: the bounded shell for scoped builders
  and recurring tasks — refuses the trunk (linked-worktree guard), hard
  --max-turns/--max-price caps, full JSON journal per run.
- fleet/README.md layout + AGENTS.md Fleet section updated in the same
  change (same-change freshness rule).

Part of erp#63 (harness portability spike, D2).

Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh
2026-07-18 18:52:53 +02:00

46 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`; golden sets + fiscal profile are stubs ([erp#39](https://gitea.arcodange.lab/arcodange-org/erp/issues/39), [erp#54](https://gitea.arcodange.lab/arcodange-org/erp/issues/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](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).
- 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.
Reference in New Issue View Git Blame Copy Permalink