Gouvernance documentaire

Niveaux d’autorité

1. Le code de l’app et ses tests : la preuve de ce qui est livré (Source de vérité).
2. AGENTS.md et .claude/ de l’app : les règles des agents qui y travaillent, ce qui est vrai maintenant.
3. Les ADR de ce dépôt : le pourquoi des décisions structurantes, immuables une fois acceptées.
4. Les autres pages de ce dépôt : l’explication, l’architecture, les runbooks, les audits.
5. Le propriétaire : seul à trancher un prix, un contrat, une dépense ou un risque juridique.

Un README, un commentaire de code ou une page ne change pas seul une règle produit. Un ADR conserve l’histoire : quand une partie est remplacée, on écrit un nouvel ADR qui le dit, on ne réécrit pas l’ancien.

Une seule documentation, deux dépôts

• BoostEcom/docs.boostecom.app porte toute la prose d’ingénierie, en un seul exemplaire.
• BoostEcom/boostecom.app porte le code, ses gardes, content/ (servi à l’exécution), backlog/ (alimente le Dev Studio et le manifeste de la flotte) et les règles des agents.

Une page qui cite l’app le fait par chemin (src/...) ; scripts/audit-boostecom-claims.mjs vérifie ces chemins, les scripts pnpm, les crons, les variables et les identifiants de plan contre un clone de l’app.

Une seule série d’ADR

Les ADR vivent sous adr/, nommés NNNN-slug.mdx, numérotés de façon contiguë depuis 0001, chacun avec une section « Statut », tous indexés dans engineering/adr.mdx. Il n’y a pas de seconde série (pas de decisions/ ni de numérotation parallèle). Tenu par scripts/audit-docs.mjs.

Une seule page pour le travail restant

Ce qui reste à faire pour BoostEcom (actions du propriétaire, travail de l’app, décisions ouvertes) vit sur une seule page : Reste à faire. Les items restent dans backlog/ de l’app, un fichier par item ; la page en est le récit : ce qui bloque, dans quel ordre, ce que le propriétaire seul peut faire.

• un runbook décrit le comment et renvoie à cette page pour le quoi ;
• une PR qui termine une tâche la retire de la page et l’ajoute à « Fait récemment » ;
• une PR qui découvre un écart l’ajoute à la page au lieu de le cacher dans une autre.

Tenu par scripts/audit-docs.mjs : la page existe, reste protégée et lisible par founder, et aucune autre page ne porte de titre « à faire », « backlog » ou « décisions ouvertes », ni de ligne de statut destinée au propriétaire.

Anciens noms

Les surfaces opérateur retirées le 8 octobre 2026 et les anciens hôtes ne se nomment que dans adr/, audits/ et engineering/migration/, qui racontent l’histoire. Ailleurs, une ligne ne les nomme que si elle dit qu’ils sont retirés. La liste refusée est dans scripts/audit-docs.mjs.

Neutralité

La documentation ne nomme ni ne reproduit des contenus, prompts ou interfaces de concurrents. Les fournisseurs et SDK réellement intégrés (Shopify, Stripe, Vercel, Neon, Resend, AI Gateway…) se nomment quand c’est nécessaire pour décrire leur usage.

Revue périodique

À chaque étape de lancement, puis chaque trimestre :

• relancer les deux audits, avec un clone frais de l’app ;
• vérifier les pages publiques et leurs liens ;
• revalider fournisseurs, versions et plans ;
• archiver ou reclasser les pages obsolètes ;
• vérifier que Reste à faire reflète le backlog de l’app.