Allegato H — Euristiche di qualità del codice e di usabilità

Stato: APPROVATO E IN PRODUZIONE. Non resta nessuna decisione aperta: la forma (D-043 e D-044), gli interruttori (D-045 e D-046), il cruscotto (D-047) e le severità iniziali con il peso dell'accessibilità (D-048, sezione 10) sono decise. Il documento è pubblicato nelle otto lingue del metodo e i suoi due prompt fanno parte dell'API dei prompt: da lì build/prompts.mjs esige il testo inglese identico byte per byte nelle otto, altrimenti la costruzione fallisce. Data: 2026-10-22.

Registro delle decisioni di questo allegato: docs/DECISIONES.md, da D-043 a D-048. Il cruscotto di conformità (sezione 12) è stato deciso con due cifre in D-047. Il lavoro di implementazione vive in PND-002.

1. Cosa manca oggi, e perché

Il gradino 9 misura già il codice, e lo fa con un cancello che non lascia passare: un solo formattatore, limiti di dimensione (trecento righe per file, quaranta per funzione), complessità per funzione, codice duplicato, codice morto, dipendenze dichiarate e usate, copertura con cricchetto e prove di mutazione dove ci sono utenti reali. Il numero resta scritto in docs/CODE_QUALITY.md. Questo è risolto.

Non è risolta l'altra metà del prodotto. Ho verificato il corpus dei gradini: non c'è una sola menzione di usabilità, di persone/profili né di raggruppamento funzionale. L'interfaccia oggi si regge su due cose: la cattura che il proprietario guarda dieci secondi e i casi di prova manuale. Sono entrambe buone ed entrambe umane, care e smemorate. Un sistema può superare il cancello di qualità con lode ed essere inusabile: tutto verde, e la persona non trova dove incassare.

E c'è un problema di secondo livello che è tecnico ma si nota nell'interfaccia: quando lo stesso prodotto lo usano più profili (amministrazione, operatività, consultazione, cliente), le funzionalità si abilitano in tre posti diversi — il database, il menu e la guardia della rotta — che si scrivono in momenti diversi e si disallineano da soli. Il sintomo è sempre lo stesso: qualcuno vede un pulsante che non gli spetta, o peggio, qualcuno che ha il permesso non trova la schermata.

Le due euristiche che seguono attaccano queste due cose con la stessa forma: un catalogo corto di enunciati verificabili, pochi strumenti che li misurano da soli, e una via di eccezione dichiarata per quando il progetto ha bisogno di uscire.

2. Il modello: tre strati, una sola forma della regola

La tentazione è fare un elenco di regole e legarlo allo stack del primo progetto. Invecchia male: la regola di React non vale in Angular, quella di Angular non vale in un server con template, e in due anni metà elenco è morto. La proposta separa tre strati.

Strato 1 — Nucleo agnostico (non si negozia). Enunciati su risultati, non su strumenti. "C'è un solo formattatore e nessuno discute con lui" vale uguale in TypeScript, PHP o Go. Il nucleo si enumera con identificatori stabili e non cambia da progetto a progetto.

Strato 2 — Adattatore per stack (configurabile). Per ogni regola del nucleo, ogni famiglia di frontend dichiara con cosa si misura e con quale soglia. Un progetto React con Vite, uno Next, uno Angular, uno con server e template, uno mobile e uno da riga di comando sono sei adattatori diversi dello stesso nucleo. Qui vive tutto quello che l'utente ha chiesto come "configurabile per frontend".

Strato 3 — Decisioni del progetto (dichiarate). Le soglie concrete e le esenzioni. Non si inventano: si chiedono al proprietario e restano scritte, come il dimensionamento nel gradino di architettura. Se una soglia non è dichiarata, vale quella dell'adattatore e resta registrata come tale.

Ogni regola si scrive sempre con la stessa scheda di sei campi:

L'eccezione si dichiara, mai si omette. Una regola si spegne con un registro di quattro campi: identificatore, motivo in una riga, chi la autorizza (il proprietario, non l'agente) e data di revisione. Una regola spenta senza registro è un guasto del cancello, non una decisione. È lo stesso criterio che il metodo già usa per non accettare un limite alzato "per passare".

3. I quattro strumenti

Nessuna euristica serve se la sua verifica è un'opinione. Sono quattro, e ogni regola dichiara a quale appartiene.

1. Cancello automatico. Corre a ogni push e alla chiusura del blocco. Restituisce verde o rosso. È economico, è ripetibile e non discute. Misura tutto quello che si può contare.
2. Interrogazione della matrice. La matrice delle funzionalità per profilo (vedi B2) è un artefatto dichiarativo; il menu, il routing e i permessi derivano da lei. Verificare la matrice è verificare l'interfaccia. È il pezzo che trasforma una parte dell'usabilità in qualcosa verificabile dalla macchina.
3. Prova end-to-end per profilo. Per ogni profilo dichiarato, uno script che entra come quel profilo e confronta l'insieme delle funzionalità raggiungibili con la riga della matrice: né meno né più. È la prova che cattura i due disallineamenti tipici (il pulsante che avanza e la schermata che manca).
4. Caso manuale. Ciò che nessuna macchina giudica: se il raggruppamento si capisce, se l'attività si completa senza aiuto, se il testo è nella lingua dell'utente. Si esegue con persone e si registra, come già ordina il gradino 10.

4. Parte A — Qualità del codice

Il nucleo estende il gradino 9: non lo sostituisce né lo contraddice, dà nome, severità e adattatore a ogni cosa che già si misura, e aggiunge quello che oggi manca, cioè l'interfaccia vista come codice.

Le regole da CQ-12 a CQ-18 sono quelle che fanno significare qualcosa a "qualità del codice" sul fronte. Senza di loro, il progetto può avere mutazione al novanta per cento e una schermata che calcola il totale con la propria aritmetica in un componente: il peggio dei due mondi, perché il calcolo duplicato passa tutte le prove del backend.

Severità iniziali (D-048). Bloccano dal primo giorno le quattordici regole che hanno un verificatore e che non dipendono da una soglia da discutere: da CQ-01 a CQ-06, CQ-08 e da CQ-11 a CQ-17. CQ-09 blocca dove ci sono utenti reali, che è dove si misura. Avvisano tre, e solo tre: CQ-07 (tipi), CQ-10 (dipendenze) e CQ-18 (accessibilità), perché sono quelle che hanno bisogno che il progetto prima calibri. Il formattatore, il linter, la dimensione e la complessità non si allentano: il gradino 9 già li blocca oggi, e questo lo estende, non lo sostituisce; il debito ereditato si risolve con un'eccezione dichiarata o con la linea base del cricchetto, mai abbassando la severità. E CQ-12 e CQ-14 sono le due uniche regole di questa tabella che bloccano con rosso umano e non di macchina: si verificano alla chiusura della pendenza e con il caso manuale davanti, come UX-22 e UX-27, non a ogni commit. Se il progetto non può sostenere quella chiusura, la regola scende ad AVVISA per decisione registrata, non per dimenticanza.

Adattatore per famiglia di frontend. Un esempio di come si istanzia lo strato 2 (i nomi sono illustrativi; il progetto sceglie e lo scrive):

Quello che cambia fra le colonne è lo strumento e la soglia. Quello che non cambia è l'enunciato. È questo che rende l'euristica agnostica senza farla diventare decorativa.

5. Parte B — Usabilità

Cinque famiglie. La prima e la seconda sono quelle che il proprietario ha chiesto esplicitamente; le altre tre esistono perché senza di loro il raggruppamento e i profili si degradano uguale, più lentamente.

B1 — Raggruppamento per convergenza funzionale

La regola madre: una funzionalità si raggruppa per quello che la persona è venuta a fare, non per il modulo da cui è uscita. Il codice si organizza per entità ("Fattura", "Cliente", "Pagamento"); le persone no. Nessuno entra nel sistema per "gestire entità": entra per incassare, per spedire, per chiudere il mese. Se il menu mostra le entità, la persona fa da traduttrice. Il menu è il lavoro.

B2 — Profili e funzionalità abilitate per profilo

Qui c'è il pezzo che rende di più, e la ragione è di ingegneria, non di disegno: l'abilitazione si dichiara una volta, in una matrice, e tutto il resto deriva da lei. Oggi l'errore classico è scrivere il permesso tre volte (nel menu, nella guardia della rotta e nel filtro dei dati) e che le tre si separino. Con la matrice come unico produttore, il menu, il routing, i permessi del server e gli script di prova sono consumatori, e la simmetria produttore/consumatore che il metodo già esige diventa verificabile da sola.

La matrice ha quattro colonne e una riga per funzionalità: funzionalità, casa (il gruppo di B1), profili che la hanno, rotta d'ingresso. Nient'altro.

B3 — Stati, e cosa vede la persona quando qualcosa manca

La maggior parte dei reclami di "non funziona" sono schermate che non hanno saputo dire "non c'è niente", "sta caricando" o "è fallito". Quattro stati, sempre, in ogni elenco e in ogni schermata di dettaglio.

B4 — Azioni ed errori

B5 — Linguaggio e accessibilità

6. Dove si aggancia, e quali artefatti produce

L'allegato non inventa gradini nuovi: si appende a quelli che esistono. Questo evita di duplicare cancelli ed evita il destino abituale degli elenchi di usabilità, che è essere letti una volta.

Dove va (D-043). È trasversale ai quattro tratti, con il peso principale nel Ciclo di Costruzione (gradini da 5 a 12), che è dove si decide e si costruisce. Non è un gradino proprio: un gradino numerato obbligherebbe a rinumerare la scala, altererebbe il conteggio dei passi e sottoporrebbe l'allegato alla traduzione obbligatoria dei contratti nelle otto lingue prima che la costruzione possa passare in verde, senza aggiungere nessun cancello che il ciclo non abbia già.

Come si aggancia (D-044). Una fonte canonica, cinque ancore e due ingressi precedenti. Il testo delle regole vive solo qui e i prompt lo citano; non lo copiano mai. Ripetere le quarantacinque regole dentro gli otto prompt del ciclo le diluisce (competono con il lavoro proprio di ogni gradino e l'agente le obbedisce diversamente ogni volta), le deriva (due copie dello stesso testo si disallineano da sole, che è l'antipattern che persegue il gradino 11) e non le rende più trasversali: quello che rende trasversale una regola è che ogni blocco passi per lo stesso cancello, non che la regola sia scritta dappertutto.

Stato (D-049). Le cinque ancore sono agganciate: il prompt iniziale dei gradini 5, 8, 9, 10 e 12 cita questa appendice nelle otto lingue, con un'unica formulazione inglese identica in tutte e la sua traduzione locale accanto. Il documento è pubblicato sul sito con il resto del metodo nelle otto lingue, e i suoi due prompt sono entrati in docs/html/api/prompts.json come contratto anexo-h: da lì build/prompts.mjs li confronta byte per byte nelle otto, altrimenti la costruzione fallisce.

I gradini 6, 7 e 11 ricevono al massimo una riga: il 6 già registra soglie ed eccezioni come decisioni (è il posto naturale dell'eccezione dichiarata), e l'11 è dove entra a colpi il caso della matrice scritta in quattro posti. Non si aggiunge loro testo proprio per non diluirli.

Tre artefatti, tutti in docs/: CODE_QUALITY.md (esteso), USABILITY.md (nuovo, con il risultato per regola e le eccezioni dichiarate) e PROFILE_MATRIX.md (la matrice, che è insieme documento e fonte del menu).

7. Configurazione

Un solo file per progetto dichiara strato 2 e strato 3. Esempio con la forma proposta, non con valori definitivi:

{
  "version": 1,
  "frontend": "react-vite",
  "misurato_da": {
    "formato": "prettier",
    "lint": "eslint",
    "tipi": "tsc",
    "complessita": "eslint-complexity",
    "duplicazione": "jscpd",
    "morti": "knip",
    "copertura": "vitest-coverage",
    "mutazione": "stryker",
    "accessibilita": "axe-core"
  },
  "soglie": {
    "righe_per_file": 300,
    "righe_per_funzione": 40,
    "percorsi_per_funzione": 10,
    "copertura_minima": 0,
    "obiettivo_mutazione": 0
  },
  "eccezioni": [
    {
      "regola": "CQ-17",
      "motivo": "report stampabile ereditato, senza token",
      "autorizza": "proprietario",
      "rivedere": "2027-01-31"
    }
  ]
}

Gli due zeri sono deliberati e sono la parte che conta: la copertura minima la fissa il cricchetto con il misurato, e l'obiettivo di mutazione lo fissa il proprietario quando il progetto ha utenti. Se stanno a zero e nessuno li ha dichiarati, il cancello lo riporta come soglia non dichiarata invece di inventarla.

8. I due pezzi, nella forma che usa il metodo

Qualità del codice.

Usabilità.

9. Cosa questa proposta non fa

• Non aggiunge un gradino. Sono quarantacinque regole trasversali (18 di qualità e 27 di usabilità), non una tappa nuova. Si appendono ai gradini che già esistono.
• Non inventa un punteggio. Un numero di "usabilità 78" non dice cosa aggiustare e si ottimizza nella direzione sbagliata. Si riporta per regola. La sezione 12 propone due cifre derivate, ma sono un conteggio di regole con la sua motivazione — non un voto di qualità né di usabilità — e non autorizzano a chiudere niente.
• Non sostituisce il proprietario. La prova del primo clic, la cattura e la prova di attività restano umane: sono l'unico strumento che distingue "funziona" da "serve".
• Non porta soglie di fabbrica. Quelle dell'adattatore sono un punto di partenza dichiarato; il progetto che non dichiara le sue eredita quelle e resta registrato come tale.
• Non promette che il cancello rilevi il raggruppamento sbagliato. Una macchina può verificare che non ci sia duplicazione né orfane; se il gruppo si chiama "Gestione", lo deve vedere una persona.

10. Le decisioni: cosa è rimasto risolto e cosa manca

Risolte

Chiuso in D-048, e le due correzioni che porta con sé

Le due domande che bloccavano la scrittura dei prompt hanno già risposta: la 1 nella riga 5 e la 2 nella riga 6. Ma la raccomandazione approvata aveva due errori di fatto, e restano scritti qui perché non tornino:

1. Il difetto del conteggio. Dove questo allegato diceva "ventisette regole" il numero corretto è quarantacinque: 18 di qualità (da CQ-01 a CQ-18) e 27 di usabilità (da UX-01 a UX-27). La cifra vecchia veniva da una bozza che ne contava solo metà. Corretto nelle sezioni 6 e 9 e annotato in D-048; il testo di D-044 si conserva come è stato scritto, perché una decisione è un registro e non si riscrive.
2. Il formattatore, il linter, la dimensione e la complessità non si allentano. Una versione precedente di questa raccomandazione li mandava ad "avvisa" per non bloccare progetti con debito ereditato. Non può essere: il gradino 9 già li blocca oggi, e questa estensione lo estende, non lo sostituisce. Il debito ereditato si risolve con un'eccezione dichiarata — con motivo e data di revisione — o con la linea base del cricchetto, non abbassando la severità della regola.

E una limitazione dichiarata, perché è l'unica della sua classe: CQ-12 e CQ-14 bloccano con rosso umano. Nessuno strumento prova che una schermata non decida regole di business. Si verificano alla chiusura della pendenza, con il caso manuale davanti e lo stesso criterio di UX-22 e UX-27; se il progetto non può sostenere quella chiusura, scendono ad AVVISA per decisione registrata. Una regola che blocca e che nessuno verifica è peggio di una regola che avvisa.

Pendente di calendario, non di decisione

La traduzione. Fatta: l'appendice esiste nelle otto lingue e i suoi due prompt fanno parte dell'API dei prompt, con il testo inglese identico byte per byte nelle otto versioni (lo esige D-043 e lo verifica build/prompts.mjs a ogni costruzione). Il castigliano resta il canonico: se mai una traduzione e il castigliano discordano, vince il castigliano e la traduzione si corregge nello stesso cambiamento.

11. Come si verifica che il cancello vigili

Un'euristica che non cambia niente quando la si accende o la si spegne non è un cancello, è decorazione. La prova di accettazione dell'implementazione (PND-002) è un progetto fixture con violazioni deliberate di ogni famiglia:

Quello che si guarda non è solo il colore: si guarda che le due righe di spegnimento esistano nel resoconto. Un risultato verde senza quella riga è l'unico guasto che questa prova non può rilevare da sola per colore, e per questo si verifica leggendo l'uscita.

12. Il cruscotto di conformità (DECISO: due cifre, D-047)

Stato. Deciso il 2026-10-22 in D-047: il cruscotto va con due cifre, con l'impronta del regolamento, con cricchetto, con l'umano fuori dalla percentuale e con la motivazione obbligatoria. Non autorizza a chiudere blocchi. Quello che segue è la specifica che l'implementazione (PND-002) deve rispettare.

Cos'è. Un derivato deterministico del risultato per regola che il cancello ha già emesso. Non misura niente di nuovo né giudica niente di nuovo: conta. Se il cruscotto potesse cambiare il verdetto di una regola ci sarebbero due fonti di verità per la stessa cosa, che è esattamente quello che l'allegato combatte in UX-10 (la navigazione deriva dalla matrice) e in CQ-14 (un solo posto per lo stato).

Cosa non è. Non è un criterio di accettazione. Nessuna cifra autorizza a chiudere un blocco: il verde o il rosso lo decide ogni regola che blocca, una per una. Il cruscotto descrive la tendenza e segnala cosa guardare. Se si comincia a usarlo come soglia di chiusura, ha smesso di servire, perché la via più corta per alzare un numero è spegnere regole.

Due cifre, mai una.

La ragione per cui sono due: spegnere una regola alza la conformità e abbassa la copertura. Con una sola cifra spegnere è gratis e il cruscotto premia la cecità. Con due cifre che si muovono in direzioni opposte, la scorciatoia sparisce: per mostrare un cruscotto migliore bisogna aggiustare codice, non spegnere regole. E la copertura non si può alzare senza misurare.

L'impronta del regolamento. Ogni registrazione conserva con quale metro è stata calcolata: versione del catalogo, regole attive e spente, adattatore di frontend e versioni degli strumenti. Senza questo, un 82 di ieri e un 91 di oggi non sono la stessa misura anche se si scrivono uguale: sono due regolamenti diversi e la serie è falsa. Due cifre senza impronta producono un'illusione di progresso, che è peggio di non avere cruscotto. Se l'impronta cambia, la registrazione si marca come non confrontabile o lo storico si ricalcola con il metro vigente; mai si grafica accanto senza dirlo.

Cricchetto. La conformità non scende da un blocco al successivo senza una decisione registrata che lo spieghi. È lo stesso meccanismo che la copertura delle prove ha già in CQ-08: il numero di oggi è il pavimento di domani. Scendere non è proibito; scendere senza registro, sì.

Cosa non entra nel conto. Quello che solo una persona può giudicare — la prova del primo clic (UX-07), la prova di attività (UX-06), la cattura (UX-27) e tutti i casi manuali — si registra come passato o fallito, per blocco, con nome e data, e si riporta a parte come copertura di verifica umana. Non entra nella percentuale di conformità. Se si mescolano, il risultato è un numero che è sessanta per cento misurazione e quaranta per cento opinione, e nessuno può dire quale sia quale. Per questo la sezione 9 vale ancora: il cruscotto non inventa un voto di usabilità, conta regole.

Come si falsifica. Amplia la prova di accettazione della sezione 11:

Dove appare. Nel resoconto onesto del gradino 12 (ancora 5), e in questo ordine: prima il verdetto binario del cancello, poi le due cifre, poi cosa è spento e fino a quando, poi il movimento contro il blocco precedente con la sua causa nominata. Sempre con la motivazione: è scesa di quattro punti: CQ-15, tre stringhe fuori dal catalogo nella schermata di incasso. Una cifra senza motivazione è rumore; la motivazione è quello che la rende azionabile per un proprietario che non legge codice.

Rischio dichiarato. Il cruscotto lo leggerà il proprietario, che non legge codice, e per questo vorrà che salga. Il numero diventa l'obiettivo, e l'obiettivo sposta lo scopo. Le difese sono quelle sopra, e sono cinque: due cifre che si contraddicono quando si spegne, l'impronta che impedisce di confrontare metri diversi, il cricchetto che non lascia scendere senza registro, l'umano fuori dalla percentuale e la motivazione obbligatoria, con il cancello che non si negozia per media. Se una delle cinque cade, il cruscotto si spegne: un cruscotto usato male fa più danno che non averlo.

13. Registro

Ogni decisione di questo allegato resta in docs/DECISIONES.md con data, autore, citazione testuale e file di impatto: D-043 (forma), D-044 (meccanismo), D-045 (interruttori), D-046 (disciplina dell'interruttore), D-047 (il cruscotto con due cifre). L'implementazione e i suoi criteri di accettazione vivono in PND-002.

Non resta nessuna decisione aperta: la forma (D-043 e D-044), gli interruttori (D-045 e D-046), il cruscotto (D-047) e le severità iniziali con il peso dell'accessibilità (D-048) sono decise. Il testo viaggia nelle otto lingue e fa parte dell'API dei prompt, il che chiude l'unico punto che restava in calendario.