Bra1nZ/evidence-first-docs

Documentation fondée sur les preuves

La documentation n'est pas une histoire sur le système. C'est un registre d'affirmations : chaque énoncé matériel doit être traçable jusqu'à un mécanisme et une preuve, avec les limites énoncées au même endroit que l'affirmation.

Une phrase confiante est bon marché. Le but est de permettre au lecteur de distinguer ce qui a été prouvé, ce qui a été testé, ce qui a seulement été relu, et ce qui reste ouvert.

La règle fondamentale

Chaque affirmation matérielle comporte quatre éléments :

1. Mécanisme — ce qui, dans le système, est censé rendre l'affirmation vraie.
2. Preuve — l'artefact de preuve : preuve formelle, modèle, test, rapport d'analyse, trace, benchmark ou compte-rendu de relecture.
3. Périmètre — où l'affirmation s'applique et ce qui se trouve en dehors de la frontière de confiance.
4. Statut — l'étiquette honnête la plus forte que la preuve supporte.

Si l'un des quatre manque, l'affirmation n'est pas prête. Reformulez-la comme une intention de conception, un plan ou une question ouverte — ne la présentez pas comme un résultat.

Registre d'affirmations

Maintenez un tableau, dans le document ou dans un fichier de preuves lié :

ID	Affirmation	Mécanisme	Preuve	Périmètre / TCB	Statut	Limitations	Dernière vérification
C-01	Seul le rôle X peut écrire la table T	Vérification d'autorisation + politique de base de données	Tests négatifs T-04..T-11	PostgreSQL 14–17 ; rôle Y, session sans rôle	testé	Superutilisateur et DBA sont hors du modèle de menace	2026-11-02

Règles :

• Une ligne par affirmation, pas une ligne par document.
• Les affirmations doivent être falsifiables. « Le système est sécurisé » n'est pas une affirmation ; « le rôle Y ne peut pas écrire T via un point d'entrée supporté » en est une.
• Liez l'artefact, pas seulement le nom de l'outil. « SARIF » est un format ; le chemin du rapport et l'ensemble des règles relues sont la preuve.
• Mettez à jour Dernière vérification lorsque l'artefact est réexécuté ; une preuve obsolète est une constatation, pas une formalité.
• Conservez les résultats négatifs. « Nous avons essayé de le casser et avons échoué à cause de X » est une preuve ; les cacher produit une fausse sensation de couverture.

Échelle de statut

Utilisez l'étiquette la plus forte que la preuve supporte, jamais une plus forte :

Statut	Signification
prouvé	Preuve formelle mécanisée de la propriété énoncée, avec hypothèses et TCB déclarés
model-checked	Exploration exhaustive ou bornée d'un modèle ; précisez la borne et l'écart modèle-code
testé	Tests exécutés qui tentent la violation, avec environnement et résultat enregistrés
static-refinement	Analyse statique ou vérification de raffinement ; précisez l'outil, les règles et les conclusions non résolues
relu	Relecture humaine uniquement ; aucune preuve exécutable ou formelle
ouvert	L'affirmation existe mais la preuve non ; c'est un risque, pas un résultat

Un statut inférieur n'est pas un échec. Un statut gonflé en est un.

N'écrivez pas vérifié, prouvé, correct, sécurisé, sûr, complet, garanti, certifié ou conforme sans un statut et un périmètre adjacents. Si le mot survivrait sans la preuve, supprimez le mot.

Force de la preuve

Privilégiez la preuve qui peut échouer pour la bonne raison :

1. Preuve formelle de la propriété énoncée sous des hypothèses explicites.
2. Model checking exhaustif dans une borne énoncée.
3. Tests basés sur les propriétés ou fuzz testing avec un corpus et un oracle enregistrés.
4. Tests négatifs ciblés qui échouent lorsque le mécanisme est supprimé.
5. Analyse statique avec un ensemble de règles relues et des conclusions triées.
6. Relecture de code avec des relecteurs nommés et une liste de points.
7. Affirmation ou anecdote.

La hiérarchie n'est pas absolue : un test ciblé peut être plus fort qu'une preuve mal appliquée. Faites correspondre la preuve à l'affirmation. Une preuve d'un modèle qui ne raffine pas le code ne prouve pas le code. Un test qui réussit parce que la plateforme a refusé en premier ne prouve pas votre garde.

Périmètre et frontière de confiance

Énoncez la frontière à côté de l'affirmation, pas dans une annexe éloignée :

• Versions et plateformes couvertes.
• Acteurs privilégiés exclus : superutilisateur, DBA, administrateur de déploiement, gestionnaire de secrets, système de construction, opérateur.
• Hypothèses : primitives cryptographiques, horloge, réseau, stockage, isolation des locataires, configuration.
• Ce qui est modélisé symboliquement et ce qui est exécuté réellement.
• Ce qui est hors périmètre et pourquoi.

Une affirmation non qualifiée est une affirmation sur tout, ce qui est presque toujours faux. « Sécurisé contre le rôle Y sur PostgreSQL 14–17 avec la configuration documentée ; le DBA est en dehors du modèle » est honnête et utile.

Flux de travail

1. Inventorier les affirmations. Lisez le texte et marquez chaque phrase qui affirme une propriété, un résultat, une garantie ou un état de conformité.
2. Classer chaque affirmation. Est-ce une intention de conception, une exigence, un fait implémenté, un résultat de test, un résultat formel ou une revendication de version ?
3. Attribuer un ID et un statut. Ajoutez mécanisme, preuve, périmètre, limitations et Dernière vérification.
4. Tester l'affirmation contre l'artefact. Ouvrez le rapport, relancez la commande ou demandez l'artefact manquant. N'acceptez pas un nom de fichier comme preuve.
5. Reformuler les affirmations non étayées. Convertissez-les en « intention de conception », « planifié », « pas encore vérifié » ou question ouverte. Préservez l'ambition ; supprimez la fausse certitude.
6. Vérifier les négatifs. Pour chaque affirmation de sécurité ou de correction, nommez le test ou l'analyse qui a essayé de la violer. S'il n'y en a pas, marquez l'affirmation ouvert.
7. Revoir le langage. Supprimez les mots interdits, les quantificateurs vagues et les absolus non qualifiés. Voir references/banned-words.md.
8. Geler la preuve. Enregistrez la commande, le commit, l'environnement, la date et le chemin de l'artefact pour qu'un relecteur puisse reproduire le résultat.
9. Filtrer la version. Une note de version ne peut revendiquer que ce que le registre supporte. Listez explicitement le risque résiduel et les affirmations ouvertes.

Liste de relecture

• Chaque affirmation matérielle a un ID, un mécanisme, une preuve, un périmètre, un statut et des limitations.
• Chaque affirmation testé nomme un test qui peut échouer lorsque le mécanisme est supprimé.
• Chaque affirmation model-checked énonce la borne et l'écart modèle-code.
• Chaque affirmation prouvé énonce les hypothèses et la TCB.
• Les résultats négatifs et les échecs connus sont présents, pas filtrés.
• Les dates et versions sont à jour ; la preuve obsolète est marquée comme obsolète.
• Les acteurs privilégiés et les chemins hors périmètre sont nommés.
• Aucun mot interdit n'apparaît sans preuve et périmètre adjacents.
• Le README, la documentation architecturale, le contrat API et la note de version ne se contredisent pas.
• Un lecteur peut reproduire la preuve à partir du seul document.

Anti-patrons

1. Présent aspirationnel. « Le système applique... » quand c'est un plan.
2. Preuve par nom de fichier. « Voir rapport.pdf » sans résultat, périmètre ni date.
3. Nom d'outil comme preuve. « Vérifié avec analyse statique » sans règles, conclusions ni triage.
4. Blanchiment de périmètre. Un résultat de test étroit présenté comme une garantie à l'échelle du produit.
5. Absolutisme de suite verte. « Tous les tests passent » sans dire quels tests, sur quelles plateformes et ce qu'ils ont essayé de violer.
6. Cosplay de conformité. Le nom d'une norme utilisé comme un certificat ; une cartographie n'est pas un audit.
7. Limitations enterrées. L'avertissement existe mais est loin de l'affirmation.
8. Certitude obsolète. Un résultat d'un ancien commit présenté comme actuel.
9. Aucune preuve négative. Seuls les succès sont documentés ; les échecs et refus disparaissent.

Format de sortie

Lorsqu'on vous demande d'écrire ou de relire un document technique, produisez :

1. Un court résumé des affirmations avec des comptes par statut.
2. Le registre des affirmations (intégré ou lié).
3. Les affirmations ouvertes et risque résiduel, explicitement séparés des résultats.
4. Le périmètre et les hypothèses, à côté des affirmations qu'ils contraignent.
5. Un index des preuves avec chemins, commandes, dates et versions.

Utilisez references/evidence-template.md pour le registre et le format de la note de version. Utilisez references/banned-words.md avant la publication. Si le dépôt inclut une cartographie des normes, elle se trouve dans references/standards-map.md ; la compétence elle-même ne dépend d'aucune norme.

Adaptez la sortie au document. Une courte note de version a besoin d'un tableau d'affirmations compact et d'une courte section de risque résiduel, pas d'un pack d'audit complet. Un fichier de preuves pour certification nécessite le registre complet, l'index des preuves et le périmètre. Ne confondez pas exhaustivité avec longueur ; chaque ligne doit contenir une information dont le lecteur a besoin.