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

docs(prd): sandbox-vs-prod posture + certified-accounting-grade operations

Browse Source 
New compliance.md leaf: French bookkeeping obligations mapped to fleet
mechanisms — inaltérabilité (L.123-22) via an append-only production
ledger grammar (create/validate/pay/avoir, never mutate a validated
document) enforced by a promote-plan compliance linter; FEC (L.47 A
LPF) with quarterly export + Test Compta Demat validation (accounting-
module binding flagged as unverified gap); piste d'audit fiable (289
VII CGI) framed as a by-product of journals + tx-id reco + monthly
packs; retention, numbering, copie fiable; loi anti-fraude scoped out
(B2B-only) with BlockedLog as sandbox-first belt-and-braces.

New Environments section in agent-architecture: prod = the ledger
(grammar-bound), sandbox = disposable iso-prod rehearsal (exempt, never
wired to production third parties); side_effect_class -> environment/
credential mapping; POCs write on sandbox only; evals target fresh
checkpoints; irreversible-by-design features trial on checkpoints.

Woven through hub (goal, requirement, success criteria, leaves table),
T03/T05/T15 guardrails, QA (linter suite, pure-append snapshots, FEC
cadence, PAF evidence framing), C2, POC-1 exit criteria.

Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
arcodange
2026-07-11 14:48:20 +02:00
co-authored by Claude Fable 5
parent 8920547a98
commit a00f5cb065
7 changed files with 98 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vibe/PRD/ai-back-office/agent-architecture.md
+25 -1
View File
@@ -91,7 +91,31 @@ flowchart TB
- **Gated promote**: `promote-plan` (human-readable review) → `promote-apply --target prod` requiring the prod write key from ENV only (never stored) + an explicit confirm variable.
- **Iso-prod checkpoints**: the sandbox is re-seedable from prod at will, so rehearsals run against *today's* real state.
This PRD adds around it: idempotency keys on every write atom, predicted-delta assertions (rehearse → re-read → compare *before* asking for approval), pre/post snapshots ([T13](task-inventory.md#t13--erp-snapshot--drift-detection)), and approval cards as the human interface to the gate.
This PRD adds around it: idempotency keys on every write atom, predicted-delta assertions (rehearse → re-read → compare *before* asking for approval), pre/post snapshots ([T13](task-inventory.md#t13--erp-snapshot--drift-detection)), a **compliance linter** in `promote-plan` (a manifest with any operation outside the [ledger grammar](compliance.md#the-ledger-grammar-production) never reaches the approval card), and approval cards as the human interface to the gate.
## Environments — sandbox vs production
The environment split is not an implementation detail — it is both the **safety** device (ADR-0003) and the **compliance** device ([compliance](compliance.md)): the sandbox may host any experiment because its state is disposable; production is held to append-only ledger discipline because it *is* the books.
| | **Production** (`erp.arcodange.lab`) | **Sandbox** (`erp-sandbox.arcodange.lab`) |
| --- | --- | --- |
| Role | the ledger — book of record | rehearsal, POCs, evals, drills |
| State | permanent, append-shaped only | disposable; re-seeded **iso-prod** on demand (`arcodange sandbox checkpoint refresh`) |
| Credentials | read-only `ai_agent`; prod write key human-held, ENV-only at promote time | write-scoped `ai_agent_sandbox`, host-guarded (structurally cannot reach prod) |
| Ledger grammar | **enforced** (linter + locking + snapshot detection) | exempt — but manifests destined for prod are linted *before* rehearsal |
| Third parties | real (Qonto/PA, Zoho, Telegram) | **never wired to production externals**: no PA emission, no outbound mail — side channels are stubbed or blackholed |
Every atom's `side_effect_class` maps to an environment posture:
| `side_effect_class` | Runs against | Credential |
| --- | --- | --- |
| `read` | prod (and sandbox for evals) | read-only `ai_agent` |
| `draft` | no ERP at all | none |
| `write-sandbox` | sandbox only | `ai_agent_sandbox` (host-guarded) |
| `write-prod` | prod, **only** through the promote gate | human-held key + explicit confirm |
| `outbound` | production channels | allowlisted recipients, human-gated |
Standing rules: **every POC's write legs run on the sandbox** and enter prod only through the gate with a real approval; ERP-dependent **eval runs target a fresh checkpoint** (iso-prod refresh = a reproducible fixture); restore drills and game-days land on the sandbox by construction ([T14](task-inventory.md#t14--backup--restore-verification), [QA strategy](qa-strategy.md#ops-qa)); anything designed to be irreversible in prod (e.g. Dolibarr's BlockedLog module) is trialed on a checkpoint first, because the sandbox provides exactly the reversibility production denies.
## Security model