Source de vérité
Qui fait foi entre l’application, ses gardes, cette documentation et le backlog, et où vit chaque concept.
Principe
L’application fait foi pour ce qui est livré. Une page de cette documentation décrit, explique et donne le pourquoi ; quand elle affirme un fait (une route, un plan, un cron, une variable, un outil, une limite), elle cite le fichier de BoostEcom/boostecom.app qui le prouve, et scripts/audit-boostecom-claims.mjs vérifie que ce fichier existe encore. Si la page et le code divergent, le code dit ce qui tourne ; la page est corrigée, ou l’écart devient une tâche sur Reste à faire.
Hiérarchie
| Domaine | Fait foi |
|---|---|
| Comportement livré | le code de l’app et les tests qui le prouvent (src/**, src/test/**) |
| Règles des agents qui travaillent dans l’app | AGENTS.md de l’app (et ses liens CLAUDE.md), les CLAUDE.md / AGENTS.md locaux, .claude/ |
| Pourquoi d’une décision structurante | les ADR de ce dépôt (adr/, série unique, immuables une fois acceptés) |
| Items de travail | backlog/ de l’app, un fichier par item ; Reste à faire en est le récit |
| Décisions de prix, contrat, dépense, risque juridique | le propriétaire seul (items type: decision) ; aucun agent ne les tranche |
| Explication, architecture, runbooks, audits | ce dépôt |
| Documentation produit pour les marchands | content/docs/ de l’app, servi sur https://www.boostecom.app/docs jusqu’à sa migration dans ce dépôt |
Les tags // SOT:
Dans l’app, chaque fichier canonique porte en première ligne // SOT: <concepts>. Avant de documenter un concept, trouver son fichier :
grep -rn "^// SOT:" src # la carte complète, une ligne par fichier
grep -rln "^// SOT:.*plans" src # le fichier d'un concept
src/test/sot-tags.test.ts tient cette carte : un nouveau registre canonique, c’est un tag et une ligne dans ce test.
Où vit chaque concept
Carte relevée sur l’app (25 fichiers tagués) :
| Concept(s) | Fichier |
|---|---|
| agents, identité des agents | src/features/ai/agents/identity-registry.ts |
| spécialistes (prompts, outils) | src/features/ai/agents/agents/specialists.ts |
| niveaux d’autonomie | src/features/ai/agents/autonomy.ts |
| plans, prix, crédits, limites de plan | src/types/billing-plans.ts |
| modèles d’IA | src/config/ai-models.ts |
| outils MCP | src/app/api/mcp/[storeId]/register-tools.ts |
| scopes MCP | src/lib/security/mcp-scopes.ts |
| permissions, RBAC | src/lib/security/permissions.ts |
| authentification API, session | src/lib/security/session-auth.ts |
| authentification des API d’administration | src/lib/security/with-admin-route.ts |
| limites de débit | src/lib/security/rate-limit.ts |
| variables d’environnement | src/env/server.ts |
| version de l’API Shopify | src/features/shopify/sdk/version.ts |
| fournisseurs, plafonds, FinOps | src/config/provider-ledger.ts |
| routes d’administration | src/config/admin-routes.ts |
| fonctionnalités marketing | src/config/marketing-ia.ts |
| systèmes | src/features/systems/registry.ts |
| locales, routes localisées | src/i18n/locale-path.ts |
| journalisation | src/lib/monitoring/index.ts |
| consentement cookies | src/components/shared/cookie-consent/consent.ts |
| contrat d’expériences | src/lib/experiments-contract.ts |
| signaux de pilier, hôtes référents IA | src/lib/pillar-signals.ts |
| vérification des tâches | src/lib/pillar-signals-verification.ts |
| piliers de boutique, sources de tâches | src/services/store-activity/hub-contract.ts |
| style du sélecteur d’éléments | src/features/ai/preview/annotations/selector-style.ts |
Autres sources fixes : le schéma de données est prisma/schema.prisma (pas de dossier de migrations : prisma db push et une garde de schéma générée) ; les crons sont ceux de vercel.json ; les scripts sont ceux de package.json ; les domaines sont dans src/config/domains.ts.
Les gardes de l’app
Une règle qu’un test peut tenir devient un test dans src/test/. Avant de pousser, l’app lance un crochet pre-push (déclaré dans package.json) qui enchaîne les gardes rapides, parmi lesquelles pnpm docs:claims, pnpm docs:links, pnpm backlog:ids et pnpm fleet:boundaries ; lint, typecheck et test tournent en CI. Plusieurs tests de l’app lisent encore de la prose (le dossier docs/ de l’app, en cours de migration ici) : ils seront portés dans scripts/audit-boostecom-claims.mjs, dont le registre liste les contrôles à porter (node scripts/audit-boostecom-claims.mjs --list).
Contrat de mise à jour
Un changement de fait met à jour, dans le même cycle :
- le code et ses tests, dans l’app ;
- la page de ce dépôt qui l’explique, avec son chemin ;
- un ADR si la décision est structurante ;
- Reste à faire si une tâche se ferme ou s’ouvre.
Aucune couche ne dérive silencieusement.