Restructure docs: docs-first, SSOT, one ADR per decision

- Add docs/README.md as the index of all documentation.
- Split the 52 DEC entries of decisioni-e-limiti.md into docs/adr/ADR-NN
  files (same numbers), add ADR-53 (audit log), TEMPLATE.md and an ADR index
  with a feature -> ADR table.
- Rename decisioni-e-limiti.md to limiti-noti.md (LIM only) and rewrite all
  DEC-nn references as links to the ADRs.
- Document the docs-first / SSOT / ADR rules in processo-di-modifica.md and
  map the docs in CLAUDE.md and README.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-10-14 12:05:57 +02:00
1 parent 7ba8e22bb4
commit b424f670c5
76 files changed
+2147 -1530

No files matched your search

+37 -4
View File
@@ -1,5 +1,35 @@
# Processo di modifica: dalla documentazione al codice
L'indice di tutta la documentazione è [README.md](README.md). Questo documento
ne fissa le regole di lavoro.
## Principi: docs-first, SSOT, ADR
- **Docs-first.** Si cambia prima la documentazione, poi il codice; spec,
codice e test stanno nello stesso commit.
- **SSOT.** Ogni informazione ha un solo proprietario e gli altri documenti
rimandano a lei per ID senza ripeterla:
| Informazione | Proprietario |
|---|---|
| Perché una scelta (contesto, alternative, conseguenze) | un ADR in [adr/](adr/README.md) |
| Che cosa deve fare il software (regola verificabile) | il requisito `PREFISSO-NN` del documento di dominio |
| Schema, stati, vincoli | `DAT` in [modello-dati.md](modello-dati.md) |
| Soglie e rischi di sicurezza | `SEC` in [sicurezza.md](sicurezza.md) |
| Eventi di audit | `AUD` in [audit-log.md](audit-log.md) |
| Come lo fa | il codice (riferimento `percorso:funzione`) |
| Limiti accettati | `LIM` in [limiti-noti.md](limiti-noti.md) |
| Difetti trovati e corretti | [storico-bug.md](storico-bug.md) |
- **Un ADR per ogni funzionalità.** Una funzionalità nuova, o un cambio di
scelta in una esistente, parte da un ADR scritto da [adr/TEMPLATE.md](adr/TEMPLATE.md):
prossimo numero libero, stato *Proposta* finché non è approvato, poi
*Accettata*. L'ADR elenca i requisiti che lo attuano; i requisiti citano
l'ADR. Un ADR non si riscrive: se la scelta cambia se ne scrive uno nuovo e
il vecchio passa a *Sostituita da ADR-MM*. Un nuovo ADR va aggiunto
all'indice per area e alla tabella funzionalità → ADR di
[adr/README.md](adr/README.md).
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.
@@ -82,15 +112,18 @@ fa il codice oggi:
| `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 |
| `ADR` | [adr/](adr/README.md) | Decisioni di progetto (un file per decisione) |
| `LIM` | [limiti-noti.md](limiti-noti.md) | Limiti noti accettati |
## Il ciclo di una modifica
0. **Scegliere.** Se la modifica è una funzionalità o una scelta nuova, si
scrive o aggiorna l'ADR (e si approva) prima di toccare i requisiti.
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.
tocca una decisione (`ADR-*`) o un limite (`LIM-*`), si aggiorna anche
quello; se introduce una funzionalità o una scelta nuova, si scrive prima
il relativo ADR (vedi sotto).
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