Annexe H - Heuristiques de qualité de code et d'utilisabilité

État : APPROUVE ET EN PRODUCTION. Aucune décision ne reste ouverte : la forme (D-043 et D-044), les interrupteurs (D-045 et D-046), le tableau (D-047) et les sévérités initiales avec le poids de l'accessibilité (D-048, section 10) sont décidées. Le document est publié dans les huit langues de la méthode et ses deux prompts font partie de l'API de prompts : à partir de là, build/prompts.mjs exige le texte anglais identique octet par octet dans les huit, sinon la construction échoue. Date : 2026-10-22.

Registre des décisions de cette annexe : docs/DECISIONES.md, D-043 à D-048. Le tableau de conformité (section 12) a été décidé avec deux chiffres dans D-047. Le travail d'implémentation vit dans PND-002 ; la traduction et l'indexation, dans PND-003.

1. Ce qui manque aujourd'hui, et pourquoi

L'étape 9 mesure déjà le code, et elle le fait avec une barrière qui ne laisse rien passer : un formateur unique, des limites de taille (trois cents lignes par fichier, quarante par fonction), la complexité par fonction, le code dupliqué, le code mort, les dépendances déclarées et utilisées, la couverture avec cliquet et les tests de mutation là où il y a de vrais utilisateurs. Le chiffre est écrit dans docs/CODE_QUALITY.md. C'est résolu.

Ce qui n'est pas résolu, c'est l'autre moitié du produit. J'ai révisé le corpus des étapes : il n'y a pas une seule mention de l'utilisabilité, des profils/personnes ni du regroupement fonctionnel. L'interface tient aujourd'hui sur deux choses : la capture que le propriétaire regarde pendant dix secondes et les cas de test manuels. Les deux sont bons et les deux sont humains, coûteux et oublieux. Un système peut passer la barrière de qualité avec les honneurs et être inutilisable : tout vert, et la personne ne trouve pas où encaisser.

Et il y a un problème de second niveau, technique mais qui se voit dans l'interface : quand le même produit est utilisé par plusieurs profils (administration, opérations, consultation, client), les fonctionnalités sont activées à trois endroits différents - la base, le menu et le garde de route - qui s'écrivent à des moments différents et se désynchronisent tout seuls. Le symptôme est toujours le même : quelqu'un voit un bouton qui n'est pas le sien, ou pire, quelqu'un qui a bien la permission ne trouve pas l'écran.

Les deux heuristiques qui suivent attaquent ces deux choses avec la même forme : un catalogue court d'affirmations vérifiables, quelques instruments qui les mesurent tout seuls, et un chemin d'exception déclarée pour quand le projet doit sortir du cadre.

2. Le modèle : trois couches, une seule forme de règle

La tentation est de faire une liste de règles et de l'attacher à la pile du premier projet. Cela vieillit mal : la règle React ne s'applique pas en Angular, celle d'Angular ne s'applique pas dans un serveur avec des gabarits, et dans deux ans la moitié de la liste est morte. La proposition sépare trois couches.

Couche 1 - Noyau agnostique (non négociable). Des affirmations sur des résultats, pas sur des outils. "Il y a un seul formateur et personne ne discute avec lui" s'applique de la même façon en TypeScript, en PHP ou en Go. Le noyau s'énumère avec des identifiants stables et ne change pas d'un projet à l'autre.

Couche 2 - Adaptateur par pile (configurable). Pour chaque règle du noyau, chaque famille de frontend déclare avec quoi on la mesure et avec quel seuil. Un projet React avec Vite, un Next, un Angular, un serveur avec gabarits, un mobile et un en ligne de commande sont six adaptateurs différents du même noyau. Tout ce que l'utilisateur a demandé comme "configurable par frontend" vit ici.

Couche 3 - Décisions du projet (déclarées). Les seuils concrets et les exceptions. Ils ne s'inventent pas : ils se demandent au propriétaire et restent écrits, comme le dimensionnement de l'étape d'architecture. Si un seuil n'est pas déclaré, celui de l'adaptateur s'applique et il est enregistré comme tel.

Toute règle s'écrit toujours avec la même fiche de six champs :

L'exception se déclare, elle ne s'omet jamais. Une règle s'éteint avec une fiche de quatre champs : identifiant, motif en une ligne, qui l'autorise (le propriétaire, pas l'agent) et date de révision. Une règle éteinte sans fiche est un échec de la barrière, pas une décision. C'est le même critère que la méthode utilise déjà pour refuser une limite relevée "pour passer".

3. Les quatre instruments

Aucune heuristique ne vaut rien si sa vérification est une opinion. Il y en a quatre, et chaque règle déclare à laquelle elle appartient.

1. Barrière automatique. Elle tourne à chaque envoi et à la fermeture du bloc. Elle rend vert ou rouge. Elle est bon marche, répétable et ne discute pas. Elle mesure tout ce qui peut être compté.
2. Requête à la matrice. La matrice fonctionnalité-par-profil (voir B2) est un artefact déclaratif ; le menu, le routage et les permissions en dérivent. Vérifier la matrice, c'est vérifier l'interface. C'est la pièce qui convertit une partie de l'utilisabilité en quelque chose qu'une machine peut vérifier.
3. Test de bout en bout par profil. Pour chaque profil déclaré, un script qui entre comme ce profil et compare l'ensemble des fonctionnalités accessibles à la ligne de la matrice : ni moins ni plus. C'est le test qui attrape les deux désynchronisations typiques (le bouton qui reste et l'écran qui manque).
4. Cas manuel. Ce qu'aucune machine ne juge : si le regroupement se comprend, si la tâche se termine sans aide, si le texte est dans la langue de l'utilisateur. Il se déroule avec des personnes et il est enregistré, comme l'étape 10 le prescrit déjà.

4. Partie A - Qualité de code

Le noyau étend l'étape 9 : il ne la remplace pas et ne la contredit pas, il donne un nom, une sévérité et un adaptateur à chaque chose qui se mesure déjà, et il ajoute ce qui manque aujourd'hui, c'est-à-dire l'interface vue comme du code.

Les règles CQ-12 à CQ-18 sont celles qui font que "qualité de code" veut dire quelque chose sur le front. Sans elles, le projet peut avoir quatre-vingt-dix pour cent de mutation et un écran qui calcule le total avec sa propre arithmétique dans un composant : le pire des deux mondes, parce que le calcul dupliqué passe tous les tests du serveur.

Sévérités initiales (D-048). Des le premier jour bloquent les quatorze règles qui ont un vérificateur et qui ne dépendent pas d'un seuil discutable : CQ-01 à CQ-06, CQ-08 et CQ-11 à CQ-17. CQ-09 bloque là où il y a de vrais utilisateurs, c'est-à-dire là où elle se mesure. Trois avertissent, et seulement trois : CQ-07 (types), CQ-10 (dépendances) et CQ-18 (accessibilité), parce que ce sont celles qui ont besoin que le projet se calibre d'abord. Le formateur, le linter, la taille et la complexité ne se relachent pas : l'étape 9 les bloque déjà aujourd'hui, et cette extension l'étend, elle ne la remplace pas ; la dette héritée se résout par une exception déclarée ou par la ligne de base du cliquet, jamais en baissant la sévérité. Et CQ-12 et CQ-14 sont les deux seules règles de ce tableau qui bloquent avec un rouge humain et non machine : elles se vérifient à la fermeture de l'élément en attente et avec le cas manuel devant, comme UX-22 et UX-27, pas à chaque envoi. Si le projet ne peut pas tenir cette fermeture, la règle descend à AVERTIT par décision enregistrée, pas par négligence.

Adaptateur par famille de frontend. Exemple de la façon dont la couche 2 s'instancie (les noms sont illustratifs ; le projet choisit et écrit les siens) :

Ce qui change entre les colonnes, c'est l'outil et le seuil. Ce qui ne change pas, c'est l'énoncé. C'est cela qui rend l'heuristique agnostique sans la rendre décorative.

5. Partie B - Utilisabilité

Cinq familles. La première et la deuxième sont celles que le propriétaire a explicitement demandées ; les trois autres existent parce que sans elles le regroupement et les profils se degradent de la même façon, plus lentement.

B1 - Regroupement par convergence fonctionnelle

La règle mère : une fonctionnalité se regroupe par ce que la personne est venue faire, pas par le module dont elle est issue. Le code s'organise par entités ("Facture", "Client", "Paiement") ; les personnes non. Personne n'entre dans le système pour "gérer des entités" : on entre pour encaisser, pour expédier, pour clôturer le mois. Si le menu montre les entités, la personne fait la traduction. Le menu est le travail.

B2 - Profils et fonctionnalités activées par profil

Ici se trouve la pièce qui rapporte le plus, et la raison est d'ingénierie, pas de dessin : l'activation se déclare une fois, dans une matrice, et tout le reste en dérive. Aujourd'hui l'erreur classique est d'écrire la permission trois fois (dans le menu, dans le garde de route et dans le filtre de données) et de les avoir désynchronisées. Avec la matrice comme producteur unique, le menu, le routage, les permissions du serveur et les scripts de test sont des consommateurs, et la symétrie producteur/consommateur que la méthode exige déjà devient vérifiable toute seule.

La matrice a quatre colonnes et une ligne par fonctionnalité : fonctionnalité, maison (le groupe de B1), profils qui l'ont, route d'entrée. Rien de plus.

B3 - États, et ce que la personne voit quand quelque chose n'est pas là

La majorité des plaintes "ça ne marche pas" sont des écrans qui n'ont pas su dire "il n'y a rien", "ça charge" ou "ça a échoué". Quatre états, toujours, dans chaque liste et chaque écran de détail.

B4 - Actions et erreurs

B5 - Langue et accessibilité

6. Ou cela s'accroche, et quels artefacts cela produit

L'annexe n'invente pas d'étapes nouvelles : elle s'accroche à celles qui existent. Cela évite de dupliquer les barrières et évite le destin habituel des listes d'utilisabilité, qui est d'être lues une fois.

Ou elle va (D-043). Elle est transversale aux quatre troncons, avec le poids principal sur la Boucle de Construction (étapes 5 à 12), qui est là où l'on décide et l'on construit. Ce n'est pas une étape propre : une étape numérotée obligerait à renuméroter l'échelle, altérerait le compte des étapes et soumettrait l'annexe à la traduction obligatoire des contrats dans les huit langues avant que la construction puisse passer au vert, sans ajouter aucune barrière que la boucle n'ait déjà.

Comment elle s'accroche (D-044). Une source canonique, cinq ancres et deux entrées préalables. Le texte des règles vit seulement ici et les prompts le citent ; ils ne le copient jamais. Répéter les quarante-cinq règles dans les huit prompts de la boucle les dilue (elles rivalisent avec le travail de chaque étape et l'agent les obéit différemment chaque fois), les désaligne (deux copies du même texte se désynchronisent toutes seules, ce qui est l'antipattern que l'étape 11 poursuit) et ne les rend pas plus transversales : ce qui rend une règle transversale, c'est que chaque bloc passe par la même barrière, pas que la règle soit écrite partout.

État (D-049). Les cinq ancrages sont en place : le prompt initial des peldans 5, 8, 9, 10 et 12 cite cette annexe dans les huit langues, avec une seule rédaction anglaise identique dans toutes et sa traduction locale à côté. Le document est publié sur le site avec le reste de la méthode dans les huit langues, et ses deux prompts sont entrés dans docs/html/api/prompts.json comme contrat anexo-h : à partir de la build/prompts.mjs les compare octet par octet dans les huit, sinon la construction échoue.

Les étapes 6, 7 et 11 reçoivent au plus une ligne : la 6 enregistre déjà les seuils et les exceptions comme décisions (c'est l'endroit naturel de l'exception déclarée), et la 11 est là où entre à coups le cas de la matrice écrite à quatre endroits. On ne leur ajoute pas de texte propre pour ne pas les diluer.

Trois artefacts, tous dans docs/ : CODE_QUALITY.md (étendu), USABILITY.md (nouveau, avec le résultat par règle et les exceptions déclarées) et PROFILE_MATRIX.md (la matrice, qui est à la fois document et source du menu).

7. Configuration

Un seul fichier par projet déclare la couche 2 et la couche 3. Exemple avec la forme proposée, pas avec des valeurs definitives :

{
  "version": 1,
  "frontend": "react-vite",
  "measured_by": {
    "format": "prettier",
    "lint": "eslint",
    "types": "tsc",
    "complexity": "eslint-complexity",
    "duplication": "jscpd",
    "dead": "knip",
    "coverage": "vitest-coverage",
    "mutation": "stryker",
    "accessibility": "axe-core"
  },
  "thresholds": {
    "lines_per_file": 300,
    "lines_per_function": 40,
    "paths_per_function": 10,
    "minimum_coverage": 0,
    "mutation_target": 0
  },
  "exceptions": [
    {
      "rule": "CQ-17",
      "reason": "rapport imprimable herite, sans tokens",
      "authorised_by": "proprietaire",
      "review": "2027-01-31"
    }
  ]
}

Les deux zéros sont délibérés et c'est la partie qui compte : la couverture minimale est fixée par le cliquet avec ce qui a été mesuré, et l'objectif de mutation est fixé par le propriétaire quand le projet a des utilisateurs. S'ils sont à zéro et que personne ne les a déclarés, la barrière le signale comme seuil non déclaré au lieu de l'inventer.

8. Les deux pièces, dans la forme que la méthode utilise

Qualité de code.

Utilisabilité.

9. Ce que cette proposition ne fait pas

• Elle n'ajoute pas une étape. Ce sont quarante-cinq règles transversales (18 de qualité et 27 d'utilisabilité), pas une nouvelle étape. Elles s'accrochent aux étapes qui existent.
• Elle n'invente pas de score. Un chiffre d'« utilisabilité 78 » ne dit pas quoi corriger et s'optimise dans la mauvaise direction. On rend compte par règle. La section 12 propose deux chiffres dérivés, mais ils sont un compte de règles avec son bordereau - pas une note de qualité ni d'utilisabilité - et ils n'autorisent à fermer quoi que ce soit.
• Elle ne remplace pas le propriétaire. Le test du premier clic, la capture et le test de tâche restent humains : c'est le seul instrument qui distingue « ça marche » de « ça sert ».
• Elle n'apporte pas de seuils d'usine. Ceux de l'adaptateur sont un point de départ déclaré ; le projet qui ne déclare pas les siens les hérite et cela est enregistré comme tel.
• Elle ne promet pas que la barrière détecte le mauvais regroupement. Une machine peut vérifier qu'il n'y a ni duplication ni orphelines ; si le groupe s'appelle « Gestion », il faut une personne pour le voir.

10. Les décisions : ce qui est règle et ce qui manque

Réglées

Ferme dans D-048, et les deux corrections qu'elle porte

Les deux questions qui bloquaient l'écriture des prompts sont déjà répondues : la première est devenue la ligne 5 et la seconde la ligne 6. Mais la recommandation approuvée avait deux erreurs de fait, et elles sont écrites ici pour qu'elles ne reviennent pas :

1. Le défaut de comptage. Là où cette annexe disait « vingt-sept règles », le nombre correct est quarante-cinq : 18 de qualité (CQ-01 à CQ-18) et 27 d'utilisabilité (UX-01 à UX-27). L'ancien chiffre venait d'un brouillon qui n'en comptait que la moitié. Corrige dans les sections 6 et 9 et note dans D-048 ; le texte de D-044 est conservé tel qu'il a été écrit, parce qu'une décision est un registre et ne se réécrit pas.
2. Le formateur, le linter, la taille et la complexité ne se relachent pas. Une version antérieure de cette recommandation les envoyait à « avertit » pour ne pas bloquer les projets avec de la dette héritée. Ce n'est pas possible : l'étape 9 les bloque déjà aujourd'hui, et cette extension l'étend, elle ne la remplace pas. La dette héritée se résout par une exception déclarée - avec motif et date de révision - ou par la ligne de base du cliquet, pas en baissant la sévérité de la règle.

Et une limitation déclarée, parce que c'est la seule de son espèce : CQ-12 et CQ-14 bloquent avec un rouge humain. Aucun outil ne prouve qu'un écran ne décide pas de règles métier. Elles se vérifient à la fermeture de l'élément en attente, avec le cas manuel devant et le même critère que UX-22 et UX-27 ; si le projet ne peut pas tenir cette fermeture, elles descendent à AVERTIT par décision enregistrée. Une règle qui bloque et que personne ne vérifie est pire qu'une règle qui avertit.

Calendrier, pas décision

La traduction. Faite : l'annexe existe dans les huit langues et ses deux prompts font partie de l'API de prompts, identiques en anglais dans les huit versions (D-043 l'exige et build/prompts.mjs le fait respecter). Le texte espagnol reste le canonique : si jamais une traduction et l'espagnol se contredisent, l'espagnol gagne et la traduction se corrige dans la même modification.

11. Comment on vérifie que la barrière surveille

Une heuristique qui ne change rien quand on l'allume ou l'éteint n'est pas une barrière, c'est de la décoration. L'épreuve d'acceptation de l'implémentation (PND-002) est un projet fixture avec des violations délibérées de chaque famille :

Ce que l'on regarde n'est pas seulement la couleur : on regarde que les deux lignes d'extinction existent dans le rapport. Un résultat vert sans cette ligne est le seul échec que cette épreuve ne peut pas détecter seule par la couleur, et c'est pourquoi on le vérifie en lisant la sortie.

12. Le tableau de conformité (DÉCIDE : deux chiffres, D-047)

État. Décide le 2026-10-22 dans D-047 : le tableau va avec deux chiffres, avec l'empreinte du règlement, avec cliquet, avec l'humain hors du pourcentage et avec le bordereau obligatoire. Il n'autorise pas à fermer des blocs. Ce qui suit est la spécification que l'implémentation (PND-002) doit respecter.

Ce qu'il est. Un dérivé déterministe du résultat par règle que la barrière a déjà émis. Il ne mesure rien de nouveau et ne juge rien de nouveau : il compte. Si le tableau pouvait changer le verdict d'une règle, il y aurait deux sources de vérité pour la même chose, ce qui est exactement ce que l'annexe combat en UX-10 (la navigation dérive de la matrice) et en CQ-14 (un seul endroit pour l'état).

Ce qu'il n'est pas. Ce n'est pas un critère d'acceptation. Aucun chiffre n'autorise à fermer un bloc : le vert ou le rouge est décidé par chaque règle qui bloque, une par une. Le tableau décrit la tendance et montre quoi regarder. S'il commence à servir de seuil de fermeture, il cesse de servir, parce que le chemin le plus court pour faire monter un chiffre est d'éteindre des règles.

Deux chiffres, jamais un.

La raison pour laquelle il y en a deux : éteindre une règle fait monter la conformité et fait baisser la couverture. Avec un seul chiffre, éteindre est gratuit et le tableau recompense l'aveuglement. Avec deux chiffres qui bougent en sens opposé, le raccourci disparait : pour montrer un meilleur tableau il faut corriger du code, pas éteindre des règles. Et la couverture ne peut pas monter sans mesurer.

L'empreinte du règlement. Chaque enregistrement garde avec quelle mesure il a été calculé : version du catalogue, règles actives et éteintes, adaptateur de frontend et versions des outils. Sans cela, un 82 d'hier et un 91 d'aujourd'hui ne sont pas la même mesure même s'ils s'écrivent pareil : ce sont deux règlements différents et la série est fausse. Deux chiffres sans empreinte produisent une illusion de progrès, ce qui est pire que de ne pas avoir de tableau. Si l'empreinte change, l'enregistrement est marqué comme non comparable où l'historique est recalculé avec la mesure en vigueur ; on ne les trace jamais ensemble sans le dire.

Cliquet. La conformité ne baisse pas d'un bloc au suivant sans une décision enregistrée qui l'explique. C'est le même mécanisme que la couverture de tests a déjà en CQ-08 : le chiffre d'aujourd'hui est le plancher de demain. Baisser n'est pas interdit ; baisser sans enregistrement, si.

Ce qui n'entre pas dans le compte. Ce qu'une personne seule peut juger - le test du premier clic (UX-07), le test de tâche (UX-06), la capture (UX-27) et tous les cas manuels - s'enregistre comme passe ou échoue, par bloc, avec nom et date, et se rapporte à part comme couverture de vérification humaine. Il n'entre pas dans le pourcentage de conformité. Si on les melange, le résultat est un chiffre qui est soixante pour cent mesure et quarante pour cent opinion, et personne ne peut dire lequel est lequel. C'est pourquoi la section 9 tient toujours : le tableau n'invente pas une note d'utilisabilité, il compte des règles.

Comment on le falsifie. Il étend l'épreuve d'acceptation de la section 11 :

Ou il apparait. Dans le rapport honnête de l'étape 12 (ancre 5), et dans cet ordre : d'abord le verdict binaire de la barrière, ensuite les deux chiffres, ensuite ce qui est éteint et jusqu'a quand, ensuite le mouvement par rapport au bloc précédent avec sa cause nommée. Toujours avec le bordereau : a baissé de quatre points : CQ-15, trois chaînes hors du catalogue sur l'écran d'encaissement. Un chiffre sans bordereau est du bruit ; le bordereau est ce qui le rend actionnable pour un propriétaire qui ne lit pas de code.

Risque déclaré. Le tableau va être lu par le propriétaire, qui ne lit pas de code, et c'est pourquoi il voudra qu'il monte. Le chiffre devient l'objectif, et l'objectif déplace le but. Les défenses sont celles du dessus, et il y en a cinq : deux chiffres qui se contredisent quand on éteint, l'empreinte qui empêche de comparer des mesures différentes, le cliquet qui ne laisse pas baisser sans enregistrement, l'humain hors du pourcentage et le bordereau obligatoire, avec la barrière qui ne se négocie pas à la moyenne. Si l'une des cinq tombe, le tableau s'éteint : un tableau mal utilisé fait plus de dégâts que de ne pas en avoir.

13. Registre

Chaque décision de cette annexe reste dans docs/DECISIONES.md avec date, auteur, citation textuelle et fichiers d'impact : D-043 (forme), D-044 (mécanisme), D-045 (interrupteurs), D-046 (discipline de l'interrupteur), D-047 (le tableau a deux chiffres) et D-048 (sévérités initiales et le poids de l'accessibilité). L'implémentation et ses critères d'acceptation vivent dans PND-002 ; la traduction et l'indexation, dans PND-003.

Aucune décision ne reste ouverte : la forme (D-043 et D-044), les interrupteurs (D-045 et D-046), le tableau (D-047) et les sévérités initiales avec le poids de l'accessibilité (D-048) sont décidées. Le texte voyage dans les huit langues et fait partie de l'API de prompts, ce qui ferme le seul point qui restait au calendrier.