ff

2026-10-26 00:25:18 +01:00
parent 1df884da84
commit 1bc033c329
46 changed files with 2958 additions and 0 deletions
@@ -0,0 +1,14 @@
+# CHANGELOG
+
+Formato: [Keep a Changelog](https://keepachangelog.com/it/1.1.0/) · Versionamento semantico.
+
+Le voci descrivono ciò che cambia **per chi usa il prodotto**. Le decisioni tecniche stanno in
+[`DECISIONS.md`](DECISIONS.md), il diario di lavoro in [`DEVELOPMENT_LOG.md`](DEVELOPMENT_LOG.md).
+
+---
+
+## [Non rilasciato] — 0.1.0
+
+### Aggiunto
+
+- Documentazione di progetto con metodo spec-driven ({{DATA}}).
@@ -0,0 +1,83 @@
+# DECISIONS — Registro delle decisioni architetturali (ADR)
+
+Ultimo aggiornamento: **{{DATA}}** · Progetto: **{{PROGETTO}}**
+
+Ogni decisione strutturale del progetto è registrata qui con un identificativo `D-xxx` immutabile.
+Le decisioni si **superano**, non si cancellano: una decisione sbagliata resta a registro con stato
+*Superata da D-yyy*, così la storia del progetto resta leggibile.
+
+**Stati:** `Proposta` · `Accettata` · `Superata da D-xxx` · `Respinta`
+
+**Formato:** Contesto → Decisione → Alternative valutate → Conseguenze.
+
+---
+
+## Indice
+
+| ID | Titolo | Stato | Data |
+|---|---|---|---|
+| [D-001](#d-001--stack-tecnologico) | Stack tecnologico | Proposta | {{DATA}} |
+| [D-002](#d-002--sviluppo-spec-driven-vincolante) | Sviluppo spec-driven vincolante | Accettata | {{DATA}} |
+| [D-003](#d-003--la-documentazione-vive-nel-repository) | La documentazione vive nel repository | Accettata | {{DATA}} |
+
+---
+
+## D-001 — Stack tecnologico
+
+**Stato:** Proposta · {{DATA}}
+
+### Contesto
+<!-- DA COMPILARE: vincoli del committente, competenze, sistemi esistenti con cui integrarsi. -->
+
+### Decisione
+<!-- DA COMPILARE: linguaggi, framework, database, code, storage, deploy. -->
+
+### Alternative valutate
+- <!-- DA COMPILARE: alternativa — perché scartata. -->
+
+### Conseguenze
+- <!-- DA COMPILARE -->
+
+---
+
+## D-002 — Sviluppo spec-driven vincolante
+
+**Stato:** Accettata · {{DATA}}
+
+### Contesto
+Le regole di business scritte solo nel codice emergono dal debugging invece che dalla
+specifica, e si scoprono quando un difetto le rivela.
+
+### Decisione
+Nessuna implementazione senza una `SPEC-xxx` in stato *Approvata*. Ogni spec contiene: contesto,
+requisiti coperti (`REQ-xxx`), contratto API, modello dati, regole, casi di errore, criteri di
+accettazione, task derivati (`T-xxx`). `07-quality/TRACEABILITY.md` mantiene la matrice
+REQ → SPEC → T → test e non deve avere righe vuote. Il contratto API (`04-api/openapi.yaml`) è
+la fonte di verità e si scrive prima del codice.
+
+### Alternative valutate
+- **Documentazione a valle del codice.** Produce documenti veri ma tardivi; le regole restano
+  scoperte finché un bug non le rivela.
+
+### Conseguenze
+- La fase di documentazione precede quella di codice; il codice inizia più tardi e procede più dritto.
+- Una spec approvata si modifica solo con una nuova `D-xxx` o una revisione tracciata.
+
+---
+
+## D-003 — La documentazione vive nel repository
+
+**Stato:** Accettata · {{DATA}}
+
+### Contesto
+Documentazione e codice divergono quando vivono in luoghi diversi.
+
+### Decisione
+`docs/` sta nel repository del codice e si aggiorna **nella stessa modifica** del codice che la
+riguarda.
+
+### Alternative valutate
+- **Wiki esterno.** Più comodo da modificare, ma non versionato con il codice.
+
+### Conseguenze
+- Una revisione del codice è anche revisione della documentazione.
@@ -0,0 +1,14 @@
+# DEVELOPMENT LOG — Diario tecnico
+
+Diario in ordine cronologico inverso. Registra **cosa si è scoperto e perché si è deciso così**,
+non l'elenco delle modifiche (quello è in [`CHANGELOG.md`](CHANGELOG.md)). Le voci non si
+cancellano: si annotano.
+
+Formato del titolo: `## AAAA-MM-GG (n) · titolo che dice cosa si è capito`
+
+---
+
+## {{DATA}} · Nasce la documentazione
+
+Creato lo scheletro della documentazione spec-driven. Decisioni iniziali: `D-001` (stack,
+proposta), `D-002` (metodo spec-driven), `D-003` (documentazione nel repository).
@@ -0,0 +1,43 @@
+# PROJECT MEMORY — Memoria permanente
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Da leggere **all'inizio di ogni sessione di lavoro** sul progetto. Contiene ciò che non è
+deducibile dal codice e che, se dimenticato, fa ripetere errori già commessi. Non è un
+riassunto della documentazione: ogni voce qui deve avere un perché.
+
+---
+
+## 1. In una frase
+
+<!-- DA COMPILARE -->
+
+---
+
+## 2. Le cose da non dimenticare mai
+
+<!-- Una sottosezione per vincolo. Ogni vincolo dice: la regola, perché esiste (meglio se con
+un fatto osservato e la data), la decisione D-xxx che la fissa. -->
+
+### 2.1 <!-- vincolo -->
+
+---
+
+## 3. Azioni pendenti fuori sequenza
+
+<!-- DA COMPILARE o «nessuna». Es. credenziali da ruotare. -->
+
+---
+
+## 4. Metodo
+
+Spec-driven **vincolante** (D-002): `REQ → SPEC → T → codice + test → TRACEABILITY`.
+Si implementa solo da una spec *Approvata*.
+
+---
+
+## 5. Come riprendere il lavoro
+
+1. Leggere questo file e [`../00-INDEX.md`](../00-INDEX.md) (riquadri delle novità in testa).
+2. Aprire [`TODO.md`](TODO.md): fuori sequenza, poi la fase corrente.
+3. Per il task scelto: la sua spec, i `REQ` e le `D-xxx` citate.
@@ -0,0 +1,45 @@
+# ROADMAP
+
+Ultimo aggiornamento: **{{DATA}}**
+
+---
+
+## 0. Fuori sequenza — da fare subito
+
+| # | Azione | Perché ora |
+|:-:|---|---|
+| <!-- DA COMPILARE o «nessuna» --> | | |
+
+## 1. Fasi
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│ FASE 0 · Documentazione                                            │
+│   visione · requisiti · architettura · spec · contratto · dati     │
+│   ▸ criterio di uscita: spec della fase 1 approvate                │
+└────────────────────────────────────────────────────────────────────┘
+                              ▼
+┌────────────────────────────────────────────────────────────────────┐
+│ FASE 1 · Fondamenta                                                │
+│   <!-- DA COMPILARE -->                                            │
+│   ▸ criterio di uscita: <!-- DA COMPILARE -->                      │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. Dettaglio
+
+### Fase 1 · Fondamenta
+
+| Spec | Task | Criterio di uscita |
+|---|---|---|
+| <!-- SPEC-001 --> | <!-- T-010…019 --> | |
+
+## 3. Dipendenze critiche
+
+<!-- DA COMPILARE -->
+
+## 4. Rischi
+
+| Rischio | Fase | Contromisura |
+|---|---|---|
+| <!-- DA COMPILARE --> | | |
@@ -0,0 +1,39 @@
+# TODO — Backlog
+
+Ultimo aggiornamento: **{{DATA}}**
+
+Stato: ⬜ da fare · 🟡 in corso · ✅ fatto · ⏸ sospeso
+
+**Regola:** un task entra in lavorazione solo se la sua specifica è approvata (D-002). Al termine
+si aggiorna [`TRACEABILITY.md`](../07-quality/TRACEABILITY.md) — quando il test passa, non quando
+il codice è scritto.
+
+**Numerazione:** i task di `SPEC-nnn` usano il blocco `T-nnn0…T-nnn9` (la spec 4 usa i task da
+40 a 49); oltre il nono si aggiunge un suffisso (`b`, `c`). I task fuori sequenza usano i numeri
+da 1 a 9.
+
+---
+
+## 🔴 Fuori sequenza — prima di tutto
+
+| ID | Task | Stato |
+|---|---|:-:|
+| <!-- T-001 --> | | ⬜ |
+
+---
+
+## Fase 0 · Documentazione
+
+| ID | Task | Spec | Stato |
+|---|---|---|:-:|
+| — | Visione, glossario, casi d'uso, requisiti | — | 🟡 |
+| — | Architettura, modello dati, sicurezza | — | ⬜ |
+| — | Specifiche della fase 1 approvate | — | ⬜ |
+
+---
+
+## Fase 1 · Fondamenta
+
+| ID | Task | Spec | Stato |
+|---|---|---|:-:|
+| <!-- T-010 --> | | <!-- SPEC-001 --> | ⬜ |