# 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>