Replace flowchart/ with a traceable specification in docs/

The two Mermaid diagrams under flowchart/ described the intended flow but
had drifted from the code and carried no link back to it. docs/ now holds
the specification instead: 15 Italian documents (flows, architecture, data
model, API, security, audit log, operations, decisions and limits, bug
history) with 472 numbered requirements, each pointing at the function
that implements it and the test that covers it. docs/processo-di-modifica.md
defines the ID convention and the spec -> code -> test change workflow, and
CLAUDE.md now names docs/ as authoritative.

Writing the spec from the code also corrected stale claims in CLAUDE.md
(B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control
scope, the error contract's bare-string exceptions) and in the operator
guides (payouts do retry, only `drawing` fails to resume, rounds do not
open without fee_address). The B-70 doc test now pins the prose in
docs/scommesse-e-prelievi.md instead of the deleted diagram.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/processo-di-modifica.md

@@ -0,0 +1,84 @@
+# Processo di modifica: dalla documentazione al codice
+
+La cartella `docs/` è la **specifica** di PLM Lottery. Descrive cosa il
+software fa e perché; il codice è l'implementazione di questa specifica.
+Ogni modifica di comportamento parte da qui.
+
+## Convenzione dei requisiti
+
+Ogni regola verificabile ha un **identificativo stabile**, nella forma
+`PREFISSO-NN`, scritto in grassetto all'inizio del punto che la descrive,
+seguito dai riferimenti all'implementazione e, dove esistono, ai test:
+
+```markdown
+- **[RND-11]** Alla scadenza il round passa subito a `closing`: da quel momento
+  nessuna scommessa è più accettata.
+  *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
+  *Test:* `tests/unit/test_scheduler.py`
+```
+
+Regole della convenzione:
+
+- **Un identificativo non si riusa mai.** Un requisito eliminato resta nel
+  documento come `~~[RND-11]~~ Rimosso: <motivo>`, così i riferimenti già
+  scritti (commenti, commit, test) non puntano a una regola diversa.
+- **I numeri non si rinumerano.** Un requisito nuovo prende il numero
+  successivo al più alto del suo prefisso, anche se finisce in mezzo al testo.
+- **I riferimenti al codice** sono `percorso:funzione` o `percorso:Classe.metodo`,
+  mai numeri di riga (cambiano a ogni modifica).
+- Il testo descrittivo che non contiene regole (introduzioni, spiegazioni,
+  esempi) non ha identificativo.
+
+### Prefissi
+
+| Prefisso | Documento | Ambito |
+|---|---|---|
+| `ARC` | [architettura.md](architettura.md) | Struttura del codice, processi, frontend, test |
+| `DAT` | [modello-dati.md](modello-dati.md) | Tabelle, campi, stati, vincoli |
+| `API` | [api.md](api.md) | Endpoint, formato delle risposte, codici di errore |
+| `SEC` | [sicurezza.md](sicurezza.md) | Chiavi, autenticazione, limiti, rischi accettati |
+| `REG` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Registrazione e account |
+| `DEP` | [registrazione-e-depositi.md](registrazione-e-depositi.md) | Depositi e saldo |
+| `BET` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Scommesse |
+| `WDR` | [scommesse-e-prelievi.md](scommesse-e-prelievi.md) | Prelievi |
+| `RND` | [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) | Round, estrazione, pagamento |
+| `TX` | [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md) | Ciclo di vita delle transazioni, RBF, riconciliazione |
+| `ELC` | [connessione-electrum.md](connessione-electrum.md) | Connessione alla rete |
+| `AUD` | [audit-log.md](audit-log.md) | Eventi del registro di audit |
+| `OPS` | [operativita.md](operativita.md) | Procedure operative |
+| `DEC` | [decisioni-e-limiti.md](decisioni-e-limiti.md) | Decisioni di progetto |
+| `LIM` | [decisioni-e-limiti.md](decisioni-e-limiti.md) | Limiti noti accettati |
+
+## Il ciclo di una modifica
+
+1. **Modificare la specifica.** Si cambia il testo del requisito in `docs/`
+   (o se ne aggiunge uno nuovo con il prossimo numero libero). Se la modifica
+   tocca una decisione (`DEC-*`) o un limite (`LIM-*`), si aggiorna anche
+   quello.
+2. **Individuare l'impatto.** I riferimenti *Codice* e *Test* del requisito
+   dicono dove intervenire. Si cercano anche le altre occorrenze
+   dell'identificativo nel repository (`git grep RND-11`) e i requisiti di
+   altri documenti che dipendono dallo stesso codice.
+3. **Implementare e testare.** Si modifica il codice e si aggiunge o aggiorna
+   un test che verifica il nuovo comportamento. Il test cita l'identificativo
+   nella sua docstring.
+4. **Allineare i riferimenti.** Se il codice si è spostato (funzione
+   rinominata, file diviso), si aggiornano i riferimenti *Codice* del
+   requisito.
+5. **Commit unico.** Specifica, codice e test entrano nello stesso commit,
+   con l'identificativo nel messaggio (ad esempio
+   `Close the round on its own deadline (RND-11)`).
+
+Una correzione di bug che non cambia la specifica (il codice non faceva ciò
+che il documento già diceva) segue la convenzione `B-nn` descritta in
+[storico-bug.md](storico-bug.md): numero successivo, commit dedicato, test di
+regressione. Se invece il bug rivela che la specifica era sbagliata o
+incompleta, si corregge prima la specifica, come per qualunque altra modifica.
+
+## Documenti della specifica
+
+Il punto d'ingresso è [come-funziona.md](come-funziona.md). Le guide
+operative ([setup.md](setup.md), [running-the-server.md](running-the-server.md),
+[guida-utente.md](guida-utente.md), [guida-admin.md](guida-admin.md)) non
+contengono requisiti: descrivono come usare il software, e si aggiornano
+quando la specifica cambia qualcosa di visibile.