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,42 @@
+# Modello — Brief di implementazione (STS Lab Srl)
+
+Da presentare all'utente **prima** di scrivere codice. Ogni affermazione porta il riferimento
+`file:riga` o l'ID da cui viene. Togli le sezioni vuote, mai *Criteri* e *Incoerenze*.
+
+```markdown
+## Brief · <T-xxx / SPEC-xxx> — <titolo breve>
+*STS Lab Srl · Spec-Driven Reader*
+
+**Obiettivo** — una frase: cosa cambia per chi usa il prodotto.
+
+**Cancello**
+| Verifica | Esito |
+|---|---|
+| Spec | SPEC-xxx · Stato: Approvata v1.0 (03-specs/SPEC-xxx.md:3) |
+| Task | T-xxx · ⬜ · dipende da T-yyy ✅, T-zzz 🟡 |
+| Decisioni vincolanti | D-0nn (sintesi in una riga) |
+| Parità | REQ-ABC-01 è **P**: comportamento da riprodurre identico |
+
+**Requisiti coperti** — REQ-… con il testo essenziale e il tipo (P/C/N).
+
+**Regole normative** — punti elenco presi dalla spec, con i «non» in evidenza.
+
+**Contratto**
+- API: `METODO /percorso` → ingresso, uscita, esiti/codici (openapi.yaml:riga)
+- Dati: tabelle/colonne/vincoli toccati (DATABASE.md §n)
+- Stati: transizioni ammesse (DOMAIN_WORKFLOW.md §n)
+
+**Criteri di accettazione → test**
+| Criterio | Test previsto | Stato attuale (TRACEABILITY) |
+|---|---|---|
+| D1 | … | ✅ / 🟡 / ⬜ |
+
+**Piano** — passi in ordine, file di codice probabilmente toccati.
+
+**Incoerenze trovate** — documento A dice X, documento B dice Y; fonte di verità scelta e perché.
+Se nessuna: «nessuna rilevata».
+
+**Domande per l'utente** — solo quelle che bloccano.
+```
+
+<sub>STS Lab Srl · Spec-Driven Reader</sub>
@@ -0,0 +1,48 @@
+# Chiusura del ciclo — STS Lab Srl
+
+Checklist da seguire a lavoro finito, **nella stessa modifica del codice**. Ogni voce è
+condizionale: aggiorna solo ciò che il lavoro ha davvero toccato.
+
+## 1. Verifica prima di scrivere «fatto»
+
+- [ ] I test dei criteri di accettazione del task esistono e sono stati **eseguiti**.
+- [ ] Annotato il conteggio reale della suite (es. «backend 614 (+3), tutti passanti»).
+- [ ] Se una verifica è stata fatta solo con test e non contro il sistema reale, scriverlo.
+- [ ] Se qualcosa non è verificabile ora (cluster, casella reale, fornitore esterno), aprire
+      un task `T-xxx` per la verifica mancante invece di dichiarare ✅.
+
+## 2. Documenti di tracciamento
+
+- [ ] **TODO** — stato del task; nuovi task con l'ID successivo libero, la spec e lo stato.
+      Data «Ultimo aggiornamento» (e «precedente», se il file la usa).
+- [ ] **TRACEABILITY** — righe REQ interessate: criteri coperti e stato. ✅ solo con test passanti.
+      Aggiornare anche la riga di copertura dell'area.
+- [ ] **Spec** — se la regola è cambiata o estesa: nuova sezione `§n.bis`, nuovi criteri
+      (lettera della spec + numero successivo), nuovi task nella tabella *Task*.
+- [ ] **REQUIREMENTS** — nuovo `REQ-<AREA>-<nn>` se nasce un comportamento nuovo; tipo N
+      con la `D-xxx` d'origine; nuovo `DIF-nn` se è emerso un difetto.
+
+## 3. Decisioni e memoria
+
+- [ ] **DECISIONS** — una `D-xxx` nuova per ogni scelta strutturale, deviazione da una spec o
+      cambio di un requisito di parità. Formato: Contesto → Decisione → Alternative valutate →
+      Conseguenze. Aggiungerla anche alla tabella indice. Se sostituisce una decisione,
+      marcare la vecchia «Superata da D-xxx» senza cancellarne il testo.
+- [ ] **DEVELOPMENT_LOG** — voce in testa (ordine cronologico inverso): `## AAAA-MM-GG (n) · titolo`.
+      Cosa si è scoperto, cosa è stato tentato e respinto e **perché**, misure reali.
+- [ ] **PROJECT_MEMORY** — solo se è emerso un vincolo che, dimenticato, farebbe ripetere un errore.
+
+## 4. Comunicazione
+
+- [ ] **CHANGELOG** — sezione *[Non rilasciato]*; linguaggio per l'utente del prodotto
+      (Aggiunto / Modificato / Corretto), non dettagli interni.
+- [ ] **00-INDEX** — riquadro in testa `> **Titolo (AAAA-MM-GG):** …` con gli ID coinvolti
+      (`REQ-…`, `D-…`, `T-…`) e il conteggio dei test; aggiornare la data dell'indice e la
+      riga della spec nella mappa se ne cambia lo stato o il numero di criteri.
+
+## 5. Coerenza finale
+
+- [ ] Rieseguire `spec_index.py overview <docs>`: nessun nuovo ID «citato ma mai definito».
+- [ ] Nessun segreto, password o chiave nei documenti aggiornati.
+
+<sub>STS Lab Srl · Spec-Driven Reader</sub>
@@ -0,0 +1,91 @@
+# Layout della documentazione — STS Lab Srl
+
+Due forme ricorrenti nei progetti STS Lab Srl. La skill deve funzionare con entrambe e con
+varianti intermedie. Per un progetto nuovo l'utente sceglie quale creare: i modelli sono in
+`templates/strutturato/` e `templates/piatto/` (vedi [scrittura.md](scrittura.md)).
+
+---
+
+## A. Layout strutturato (es. `KadeonCad_v2/docs`)
+
+```
+docs/
+├── 00-INDEX.md            mappa, stato degli step, novità recenti in riquadri datati
+├── 01-product/            COSA e PER CHI
+│   ├── VISION.md            perché esiste, perimetro, non-obiettivi
+│   ├── GLOSSARY.md          lessico condiviso (usare gli stessi termini nel codice)
+│   ├── PERSONAS_CASI_USO.md attori e casi d'uso end-to-end
+│   └── REQUIREMENTS.md      REQ-<AREA>-<nn> + DIF-<nn> (difetti noti)
+├── 02-architecture/       COME È FATTO
+│   ├── ARCHITECTURE.md · C4_MODEL.md · DOMAIN_WORKFLOW.md (macchina a stati, invarianti)
+│   ├── DATA_MODEL.md (entità, relazioni, invarianti) · SECURITY.md · STORAGE.md
+│   └── <componente>.md      (AI_GATEWAY, MESH_ENGINE, …)
+├── 03-specs/              CONTRATTO PER L'IMPLEMENTAZIONE
+│   └── SPEC-<nnn>-<slug>.md
+├── 04-api/                CONTRATTO ESTERNO
+│   ├── openapi.yaml         FONTE DI VERITÀ dell'API
+│   └── API.md · WEBHOOKS.md · INTEGRATION_*.md
+├── 05-data/               DATABASE.md (schema fisico) · MIGRATION_*.md · SEED_BOOTSTRAP.md
+├── 06-devops/             INFRASTRUCTURE · KUBERNETES · CI_CD · ENVIRONMENTS · OBSERVABILITY · RUNBOOK · BACKUP_DR
+├── 07-quality/            TEST_STRATEGY · ACCEPTANCE_CRITERIA · TRACEABILITY · liste di parità
+└── 08-project/            DECISIONS · ROADMAP · TODO · CHANGELOG · DEVELOPMENT_LOG · PROJECT_MEMORY
+```
+
+**Dove cercare cosa**
+
+| Domanda | Documento |
+|---|---|
+| Cosa deve fare il prodotto? | `01-product/REQUIREMENTS.md` |
+| Come deve farlo questa funzione? | `03-specs/SPEC-xxx` |
+| Che forma ha la rotta? | `04-api/openapi.yaml` (poi API.md per le convenzioni) |
+| Che colonne/vincoli ha la tabella? | `05-data/DATABASE.md`; entità logiche in `02-architecture/DATA_MODEL.md` |
+| Transizioni di stato ammesse? | `02-architecture/DOMAIN_WORKFLOW.md` |
+| Perché è così? | `08-project/DECISIONS.md` (`## D-xxx`), poi `DEVELOPMENT_LOG.md` |
+| È fatto? È verificato? | `08-project/TODO.md`, `07-quality/TRACEABILITY.md` |
+| Come si rilascia / variabili d'ambiente? | `06-devops/ENVIRONMENTS.md`, `KUBERNETES.md` |
+
+**Legenda stati usata:** ⬜ da scrivere/fare · 🟡 in corso/parziale · ✅ completo/verificato ·
+🔒 congelato (modifica solo con nuova D-xxx) · ⏸ sospeso.
+
+---
+
+## B. Layout piatto (es. `Kadeon/kadeon/src/docs`)
+
+```
+docs/
+├── PROJECT_MEMORY.md     «leggere sempre prima di scrivere codice»; sintesi architettura,
+│                         decisioni, componenti già creati, sessioni
+├── ARCHITECTURE.md · API.md · DATABASE.md · AI_GATEWAY.md · OUTPUT_SCHEMA.md
+├── <MODULO>.md           proposta/specifica di un modulo (es. CAD_MODULE.md)
+├── <area>/DESIGN.md      proposte con opzioni e «domande ancora aperte» (es. whatsapp/)
+├── <area>/openapi.yaml   contratto del modulo
+├── DECISIONS.md          D-xxx con Stato · Contesto · Opzioni · Scelta · Motivazione
+├── TODO.md               T-<lettera><nn> raggruppati per tema, con Prio (P0–P3) e Stato
+├── CHANGELOG.md · DEVELOPMENT_LOG.md
+```
+
+Differenze da tenere presenti:
+
+- Non ci sono `REQ-`/`SPEC-`: il ruolo della spec lo svolge il **documento di modulo** o la
+  sezione di PROJECT_MEMORY/ARCHITECTURE; il cancello §3 si applica a quello.
+- Gli ID dei task hanno un prefisso tematico (`T-S01` sicurezza, `T-Q5`, `T-H01`…).
+- Stati in inglese: `pending` · `in_progress` · `done` · `blocked`; decisioni `accepted` ·
+  `proposed` · `superseded`.
+- Un `DESIGN.md` con «Domande ancora aperte» **non è approvato**: chiarire con l'utente.
+- PROJECT_MEMORY può essere lungo e datato: confronta la sua data con quelle di TODO e
+  DECISIONS.
+
+---
+
+## C. Formati degli ID
+
+| ID | Forma | Dove nasce | Note |
+|---|---|---|---|
+| Requisito | `REQ-<AREA>-<nn>` (AREA 2–5 lettere) | REQUIREMENTS | Tipo **P/C/N**; mai rinumerato |
+| Difetto | `DIF-<nn>` | REQUIREMENTS (sezione difetti) | ogni DIF ha un REQ di tipo C e un test |
+| Specifica | `SPEC-<nnn>` | file `03-specs/SPEC-nnn-slug.md` | riga `Stato:` in testa |
+| Task | `T-<nnn>` o `T-<lettera><nn>`, suffissi `b`, `c` | sezione *Task* della spec e TODO | barrato se chiuso senza lavoro |
+| Decisione | `D-<nnn>` | DECISIONS | *superata*, mai cancellata |
+| Criterio | lettera + numero (`D1`, `P12`, `M18`) | sezione *Criteri* della spec | ⚠ `D1` criterio ≠ `D-001` decisione |
+
+<sub>STS Lab Srl · Spec-Driven Reader</sub>
@@ -0,0 +1,181 @@
+# Scrivere la documentazione spec-driven — STS Lab Srl
+
+Guida per creare la documentazione quando il progetto non ce l'ha, completarla quando è solo
+uno scheletro, o aggiungere una spec a un progetto che già la usa.
+
+`S` = `python ~/.claude/skills/sts-spec-driven/scripts/spec_index.py`
+(da PowerShell: `python $HOME\.claude\skills\sts-spec-driven\scripts\spec_index.py`)
+
+---
+
+## 0. Scegliere il layout — lo decide l'utente
+
+Chiedi sempre con `AskUserQuestion`, prima di creare file. Proponi come primo, con
+«(Consigliato)», il layout che si adatta al progetto:
+
+| Layout | Quando consigliarlo | Cosa crea |
+|---|---|---|
+| **Strutturato** | più moduli o servizi, integrazioni con altri sistemi, riscrittura di un sistema esistente, più persone al lavoro, committente esterno, requisiti contrattuali | `00-INDEX` + `01-product … 08-project`, 29 documenti, spec in `03-specs/SPEC-nnn-*.md` |
+| **Piatto** | progetto piccolo o prototipo, un solo modulo, un solo sviluppatore, tempi brevi | 8 documenti nella stessa cartella, una spec per modulo `<NOME>_MODULE.md` |
+
+Chiedi nella stessa domanda (o subito dopo) **dove** creare la cartella: default `docs/` nella
+radice del repository (decisione D-003 dei modelli). Se esiste già una cartella con documenti
+sparsi, non sovrascriverla: proponi di crearci dentro lo scheletro e di spostare i contenuti
+esistenti nei documenti giusti.
+
+---
+
+## 1. Creare lo scheletro
+
+```bash
+S scaffold <repo>/docs --layout strutturato --progetto "Nome Progetto"
+S scaffold <repo>/docs --layout piatto      --progetto "Nome Progetto"
+```
+
+Lo script **non sovrascrive mai** un file esistente (li elenca come «già esistenti»). I
+documenti nascono con segnaposto `<!-- DA COMPILARE: … -->` che spiegano cosa scrivere, e con
+le decisioni iniziali già pronte: `D-001` stack (Proposta), `D-002` metodo spec-driven,
+`D-003` documentazione nel repository.
+
+---
+
+## 2. Raccogliere le informazioni
+
+### 2.1 Prima guarda, poi chiedi
+
+Prima di fare domande leggi ciò che esiste: `README`, `CLAUDE.md`, manifest delle dipendenze
+(`package.json`, `pyproject.toml`, `composer.json`, …), `docker-compose`, cartelle di codice,
+documenti del committente forniti dall'utente. Non chiedere ciò che puoi ricavare.
+
+### 2.2 Intervista — al massimo 4 domande per giro, solo ciò che manca
+
+| Tema | Domande |
+|---|---|
+| Problema | Chi usa il prodotto? Cosa fa oggi senza? Quanto costa il problema (tempo, errori)? |
+| Perimetro | Cosa deve esserci nel primo rilascio? Cosa è esplicitamente fuori? |
+| Vincoli | Stack imposto? Sistemi esistenti da integrare o da sostituire? Scadenze? |
+| Utenti | Quali ruoli? Chi può fare cosa? Multi-azienda (tenant)? |
+| Dati | Quali dati personali o sensibili? Per quanto si conservano? |
+| Esercizio | Dove gira (cloud, on-premise, Kubernetes)? Quali ambienti? |
+| Successo | Come si misura che il progetto ha funzionato? |
+
+Le risposte vanno nei documenti, non solo nella conversazione.
+
+### 2.3 Progetto con codice ma senza documentazione
+
+Ricostruisci dal codice, come è stato fatto in KadeonCad_v2:
+
+- ogni comportamento osservato diventa un `REQ` di tipo **P** (parità) con *Origine*
+  `file:funzione`; il codice è la fonte di verità, non i commenti;
+- ogni difetto visto leggendo diventa un `DIF-nn` + un `REQ` di tipo **C**;
+- ogni scelta tecnica già fatta diventa una `D-xxx` *Accettata* con la data di oggi e
+  «ricostruita dal codice» nel contesto;
+- le spec delle parti già scritte nascono comunque *da approvare*: l'utente conferma che il
+  comportamento attuale è quello voluto.
+
+---
+
+## 3. Ordine di scrittura
+
+Ogni step termina con un **riepilogo all'utente** e la sua conferma prima del successivo.
+A fine step aggiorna lo stato nella tabella degli step di `00-INDEX` (⬜ → 🟡 → ✅).
+
+### Layout strutturato
+
+| Step | Documenti | Esce quando |
+|:-:|---|---|
+| 0 | `00-INDEX` (cos'è, obiettivi, struttura del repo), `D-001` stack, `PROJECT_MEMORY` §1 | l'utente conferma obiettivi e stack |
+| 1 | `VISION` → `GLOSSARY` → `PERSONAS_CASI_USO` → `REQUIREMENTS` → `ARCHITECTURE`, `C4_MODEL`, `DOMAIN_WORKFLOW`, `DATA_MODEL`, `SECURITY` | requisiti rivisti dall'utente |
+| 2 | una `SPEC` per capability (`S new-spec`) | ogni REQ è coperto da almeno una spec |
+| 3 | `openapi.yaml` + `API.md`, `DATABASE.md`, `SEED_BOOTSTRAP.md` | ogni rotta delle spec è nel contratto |
+| 4 | `06-devops/*` | ambienti e pipeline descritti |
+| 5 | `TEST_STRATEGY`, `ACCEPTANCE_CRITERIA`, `TRACEABILITY`, `ROADMAP`, `TODO` | `S check` senza ID orfani né requisiti scoperti |
+
+Per un progetto piccolo in layout strutturato gli step 4 e parte del 5 possono restare
+⬜ con una riga «rimandato a …» nell'indice: meglio dichiarato vuoto che riempito di generico.
+
+### Layout piatto
+
+1. `PROJECT_MEMORY` §1–2 e `ARCHITECTURE`.
+2. `DECISIONS` (`D-001` stack).
+3. Primo documento di modulo: `S new-spec <docs> --titolo "…" --prefisso X`.
+4. `API.md`, `DATABASE.md` per ciò che il modulo tocca.
+5. `TODO` con la lettera del modulo e i suoi task.
+
+---
+
+## 4. Regole di qualità
+
+### Requisiti
+- Un comportamento per riga, osservabile e verificabile; «il sistema …».
+- Numeri espliciti al posto di aggettivi («entro 5 s», «≥ 200 pezzi», non «veloce», «grande»).
+- Niente soluzioni tecniche nel requisito (quelle vanno nella spec o in una `D-xxx`).
+- Ogni requisito ha Tipo (P/C/N) e Origine. Aree di 2–5 lettere maiuscole (`AUT`, `ING`, `NFR`).
+
+### Specifiche
+- Forma **normativa**: «il sistema rifiuta…», «non ricalcola…». I «non» in grassetto.
+- Algoritmi in pseudocodice; combinazioni di casi in tabella.
+- Contratto API con la **tabella degli esiti** e i codici HTTP; poi subito in `openapi.yaml`.
+- Criteri di accettazione binari, nella forma «Dato …, quando …, allora …»; ogni requisito
+  coperto ha almeno un criterio; i casi limite (valore 199/200, assente, altro tenant) sono
+  criteri a sé.
+- Task piccoli (indicativamente ≤ 1 giorno), con dipendenze; l'ultimo è sempre «Test di
+  accettazione <lettera>1–<lettera>n».
+- Numerazione: `SPEC-nnn` → task `T-nnn0…T-nnn9`, criteri con la lettera della spec
+  (SPEC-001 → A, SPEC-002 → B, …). Usa `S next-id` per non sbagliare.
+- Documento di modulo (layout piatto): la sezione «Domande ancora aperte» deve essere vuota o
+  «nessuna» prima dell'approvazione.
+
+### Decisioni
+- Alternative **reali** valutate, con il motivo dello scarto.
+- Conseguenze comprese quelle negative (costi, limiti accettati).
+
+### Sempre
+- **Non inventare.** Ciò che non sai resta `DA COMPILARE` o diventa una domanda all'utente;
+  mai numeri, nomi di sistemi o vincoli plausibili ma non confermati.
+- **Mai approvare da solo.** Le spec nascono «da approvare»; diventano «Approvata» solo dopo
+  un sì esplicito dell'utente (§5).
+- Italiano, frasi brevi, niente linguaggio promozionale. Gli stessi termini del `GLOSSARY`.
+- Nessun segreto nei documenti: solo il nome della variabile che lo contiene.
+
+---
+
+## 5. Approvare una spec (solo su richiesta dell'utente)
+
+1. Riga di stato: `Stato: **Approvata** · Versione 1.0 · AAAA-MM-GG`.
+2. `00-INDEX` §03: riga della spec con numero di criteri, blocco di task, stato ✅.
+3. `TODO`: i task della spec nella fase giusta, stato ⬜.
+4. `TRACEABILITY`: una riga per requisito coperto (REQ → SPEC §n → T → criteri → ⬜).
+5. `DEVELOPMENT_LOG`: voce breve con cosa è stato deciso approvando.
+6. `S check <docs>`.
+
+Una spec approvata si modifica solo con una nuova `D-xxx` o con una revisione tracciata
+(versione 1.1, sezione `§n.bis`).
+
+---
+
+## 6. Aggiungere una spec a un progetto che già esiste
+
+```bash
+S next-id <docs> SPEC                       # numero libero
+S new-spec <docs> --titolo "Portale cliente" # crea SPEC-nnn-portale-cliente.md, da approvare
+S next-id <docs> REQ --area POR              # se servono requisiti nuovi
+S next-id <docs> D                           # se la spec nasce da una decisione
+```
+
+Poi: requisiti nuovi in `REQUIREMENTS` (tipo N, origine `D-xxx`), riga nella mappa di
+`00-INDEX`, riquadro «novità» in testa all'indice, e la procedura del §5 quando l'utente approva.
+
+---
+
+## 7. Verifica finale
+
+```bash
+S check <docs>
+```
+
+Prima di consegnare: nessun ID orfano, nessun requisito scoperto, nessun task delle spec
+assente dal TODO. I segnaposto «DA COMPILARE» rimasti devono corrispondere solo a parti
+dichiarate rimandate. Riporta all'utente l'esito del controllo, non solo «fatto».
+
+<sub>STS Lab Srl · Spec-Driven Reader</sub>