@antoneeo/agentic-sdlc-skill 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,30 +1,52 @@
 # Changelog - Agentic SDLC Skill
 
-Tutte le modifiche significative a questa skill saranno documentate in questo file.
-
-## [1.5.0] - 2026-06-13
-### Added
-- Introdotta la Regola Zero di triage (`L1`, `L2`, `L3`, `Spike`) per rendere il processo proporzionale al rischio.
-- Aggiunta simbiosi esplicita con devPNT: in Hybrid la `M-VISION` guida la milestone, il Master Plan resta roadmap strategica e l'Action Plan governa l'esecuzione tattica.
-- Aggiunti support file dentro la skill runtime: `templates.md`, `ENFORCEMENT.md`, `scripts/sdlc_check.py`.
-- `agentic-sdlc-install-skill` ora installa la skill nativa anche in `~/.gemini/skills/agentic-sdlc/`.
-- Aggiunto validatore meccanico opzionale per frontmatter ANALYSIS, Vision state, indice feature e audit stale.
-
-### Changed
-- Il nome pubblico resta `agentic-sdlc`; la proposta v2 e' stata integrata come evoluzione, non come skill parallela.
-- Aggiornati `agentic-sdlc-init`, template, protocolli generati, README e metadata.
-- La modalita Standalone resta completa; devPNT e' un livello di governance superiore, non un prerequisito.
-
-## [1.4.0] - 2026-06-07
-### Added
-- Introdotta la governance della **Vision** con nuova struttura `ai_docs/vision/` (`project_vision.md`, `roadmap.md`, `principles.md`, `features/`).
-- Aggiunto il **Vision Gate** nel workflow operativo: ogni feature significativa deve essere verificata rispetto a obiettivi, non-obiettivi, benefici attesi e segnali di successo prima dell'analisi tecnica.
-- Aggiunti template Vision in `references/` e sezione `Allineamento alla Vision` nel template di analisi.
-- `agentic-sdlc-init` ora crea i documenti Vision boilerplate nei nuovi progetti.
-
-## [1.3.1] - 2026-05-14
-### Fixed
-- Correzione documentazione (README + CHANGELOG) della sintassi per invocare il bin `agentic-sdlc-install-skill`. La forma `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` documentata in 1.3.0 **non funziona** perché npx non riesce a disambiguare il bin quando il pacchetto ne espone più di uno (errore: `could not determine executable to run`). Sintassi corretta: lanciare `agentic-sdlc-install-skill` direttamente dopo `npm install -g`, oppure usare `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` con `-p` esplicito.
+Tutte le modifiche significative a questa skill saranno documentate in questo file.
+
+## [1.6.0] - 2026-06-15
+### Added
+- **Manifest generato dei documenti canonici** (`ai_docs/INDEX.md`): `sdlc_check.py index` ora produce, oltre a `features_history.md`, un indice completo di tutti i doc in `vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`, con descrizione e stato letti dall'header. Si rigenera, quindi non drifta.
+- **Lifecycle dei documenti canonici**: convenzione header `status: CURRENT|SUPERSEDED|DRAFT|DEPRECATED` + `supersedes:`. `validate` avvisa se `status` manca/è invalido o se un doc superseduto è ancora `CURRENT`. Stop ai grep che riportano a guide obsolete.
+- **Modello a due indici** documentato nella sezione "Documenti ai_docs" di `SKILL.md`: `README.md` curato (must-read, a mano) vs `INDEX.md` generato (completo, meccanico) — ruoli separati, prima confusi in un unico README che driftava.
+
+### Changed
+- §1 Audit: leggere `README.md` + `INDEX.md` all'avvio per sapere cosa esiste prima di esplorare il codice.
+- §3 Analisi: cercare con glob/grep un'ANALYSIS esistente prima di crearne una nuova (anti-duplicazione).
+- §5 Chiusura: gate "Indici allineati" — rigenerare `INDEX.md`, aggiornare il `README.md` curato per i must-read, marcare lo `status`; doc canonico non indicizzato o senza `status` = chiusura sporca.
+- `templates.md`: aggiunto il template dell'header dei documenti canonici.
+
+### Fixed
+- `sdlc_check.py` legge ora i file con `utf-8-sig`: un BOM iniziale (file autorati su Windows) non impedisce più il riconoscimento del frontmatter `---`.
+- L'estrattore dell'header riconosce sia il frontmatter `status:` sia la riga in corpo `**Status:**`/`Stato:`, e gli stati di tutte le convenzioni in uso (canonici `CURRENT/SUPERSEDED/DRAFT/DEPRECATED`, vision `DRAFT/APPROVED`, ADR `Accepted/Proposed/Rejected`) — niente più falsi avvisi "status non riconosciuto" su `APPROVED`/`Accepted`.
+- La descrizione del manifest salta righe di metadati (`Date`, `Created`, `Task ref`, ...) e i commenti HTML, così non finiscono come descrizione del documento.
+- `index` non genera più un `INDEX.md` vuoto su progetti senza documenti canonici (solo `solutions/`+`audit/`).
+
+### Migrazione (da 1.5.x)
+- Al primo `sdlc_check.py check`/`validate` dopo l'upgrade, un progetto con documenti canonici darà **un errore** `ai_docs/INDEX.md mancante`: è atteso — esegui **una volta** `sdlc_check.py index` per generarlo. Da lì in poi resta allineato.
+- I documenti canonici preesistenti senza `status:` produrranno **avvisi** (non errori): aggiungi l'header `description:`/`status:` per silenziarli. I nuovi progetti nascono già compatibili (template aggiornati).
+
+## [1.5.0] - 2026-06-13
+### Added
+- Introdotta la Regola Zero di triage (`L1`, `L2`, `L3`, `Spike`) per rendere il processo proporzionale al rischio.
+- Aggiunta simbiosi esplicita con devPNT: in Hybrid la `M-VISION` guida la milestone, il Master Plan resta roadmap strategica e l'Action Plan governa l'esecuzione tattica.
+- Aggiunti support file dentro la skill runtime: `templates.md`, `ENFORCEMENT.md`, `scripts/sdlc_check.py`.
+- `agentic-sdlc-install-skill` ora installa la skill nativa anche in `~/.gemini/skills/agentic-sdlc/`.
+- Aggiunto validatore meccanico opzionale per frontmatter ANALYSIS, Vision state, indice feature e audit stale.
+
+### Changed
+- Il nome pubblico resta `agentic-sdlc`; la proposta v2 e' stata integrata come evoluzione, non come skill parallela.
+- Aggiornati `agentic-sdlc-init`, template, protocolli generati, README e metadata.
+- La modalita Standalone resta completa; devPNT e' un livello di governance superiore, non un prerequisito.
+
+## [1.4.0] - 2026-06-07
+### Added
+- Introdotta la governance della **Vision** con nuova struttura `ai_docs/vision/` (`project_vision.md`, `roadmap.md`, `principles.md`, `features/`).
+- Aggiunto il **Vision Gate** nel workflow operativo: ogni feature significativa deve essere verificata rispetto a obiettivi, non-obiettivi, benefici attesi e segnali di successo prima dell'analisi tecnica.
+- Aggiunti template Vision in `references/` e sezione `Allineamento alla Vision` nel template di analisi.
+- `agentic-sdlc-init` ora crea i documenti Vision boilerplate nei nuovi progetti.
+
+## [1.3.1] - 2026-05-14
+### Fixed
+- Correzione documentazione (README + CHANGELOG) della sintassi per invocare il bin `agentic-sdlc-install-skill`. La forma `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` documentata in 1.3.0 **non funziona** perché npx non riesce a disambiguare il bin quando il pacchetto ne espone più di uno (errore: `could not determine executable to run`). Sintassi corretta: lanciare `agentic-sdlc-install-skill` direttamente dopo `npm install -g`, oppure usare `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` con `-p` esplicito.
 - Nessuna modifica al codice della skill: il bin di 1.3.0 funziona correttamente, era solo la doc a indicare la sintassi sbagliata.
 
 ## [1.3.0] - 2026-05-14

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.5.0",
-  "description": "Protocollo SDLC Documentation-First con triage, Vision governance e integrazione opzionale devPNT.",
+  "version": "1.6.0",
+  "description": "Protocollo SDLC Documentation-First con triage, Vision governance e integrazione opzionale devPNT.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.5.0",
-  "description": "Protocollo SDLC Documentation-First per Claude Code, Gemini CLI e Codex con triage, Vision governance, support file installati e integrazione opzionale devPNT.",
+  "version": "1.6.0",
+  "description": "Protocollo SDLC Documentation-First per Claude Code, Gemini CLI e Codex con triage, Vision governance, support file installati e integrazione opzionale devPNT.",
   "keywords": [
     "claude-code",
     "claude-skill",
@@ -25,10 +25,10 @@
     "preuninstall": "node scripts/preuninstall.js"
   },
   "files": [
-    "skills/agentic-sdlc-skill/SKILL.md",
-    "skills/agentic-sdlc-skill/templates.md",
-    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
-    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
+    "skills/agentic-sdlc-skill/SKILL.md",
+    "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
+    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
     "gemini-extension.json",
     "references",
     "README.md",

package/references/architecture_template.md

@@ -1,3 +1,7 @@
+---
+description: Stack, struttura directory e pattern architetturali del progetto.
+status: CURRENT
+---
 # Architettura del Progetto
 
 ## Stack Tecnologico
@@ -6,13 +10,13 @@
 - **Database:** [es. PostgreSQL]
 - **Strumenti di Test:** [es. Jest, Vitest]
 
-## Struttura delle Directory
-- `src/`: Codice sorgente.
-- `ai_docs/vision/`: Vision di progetto, roadmap, principi e mini-vision delle feature.
-- `ai_docs/strategic/`: Architettura, feature esistenti e storico feature.
-- `ai_docs/solutions/`: Analisi e piani delle singole feature.
-- `ai_docs/audit/`: Piano di audit e handoff di sessione.
-- `tests/`: Test automatici.
+## Struttura delle Directory
+- `src/`: Codice sorgente.
+- `ai_docs/vision/`: Vision di progetto, roadmap, principi e mini-vision delle feature.
+- `ai_docs/strategic/`: Architettura, feature esistenti e storico feature.
+- `ai_docs/solutions/`: Analisi e piani delle singole feature.
+- `ai_docs/audit/`: Piano di audit e handoff di sessione.
+- `tests/`: Test automatici.
 
 ## Pattern Architetturali
 - [es. MVC, Clean Architecture, Layered Architecture]

package/references/existing_features_template.md

@@ -1,3 +1,7 @@
+---
+description: Catalogo sintetico delle funzionalità esistenti del progetto.
+status: CURRENT
+---
 # Funzionalità Esistenti
 
 - [ID] **Nome Feature**: Descrizione sintetica della funzionalità.

package/skills/agentic-sdlc-skill/SKILL.md

@@ -83,6 +83,7 @@ Regole Hybrid:
 ### 1. Audit e Allineamento
 
 - Leggi `ai_docs/audit/handoff.md` se esiste; se ha Data/Branch non coerenti, trattalo come storico.
+- Leggi `ai_docs/README.md` (must-read curati) e `ai_docs/INDEX.md` (manifest generato di tutti i doc canonici) per sapere cosa esiste prima di esplorare il codice. `solutions/` e `audit/` non sono indicizzate per file: cercale con glob/grep.
 - Se `ai_docs/` manca o e' incompleta, crea struttura e documenti minimi analizzando il progetto a lotti.
 - In Standalone usa `ai_docs/audit/audit_plan.md` per mappatura e stato.
 - In Hybrid preferisci la mappatura devPNT/KL quando disponibile; non duplicare la governance dei piani.
@@ -104,6 +105,7 @@ Hybrid:
 ### 3. Analisi della Richiesta
 
 Standalone L3:
+- Prima di creare un nuovo `ANALYSIS_[feature].md`, cerca con glob/grep in `ai_docs/solutions/` un'analisi gia' esistente sullo stesso tema: se c'e', aggiornala invece di duplicarla.
 - Crea o aggiorna `ai_docs/solutions/ANALYSIS_[feature].md`.
 - Sezioni minime: Obiettivo, Vision della Feature o Allineamento alla Vision, Impatto, Sicurezza e Threat Model, Piano d'Azione, Strategia di Test, Diario/Stato Corrente.
 - Per feature che attraversano piu milestone o piu analisi, crea anche `ai_docs/vision/features/VISION_[feature].md`.
@@ -127,10 +129,39 @@ Hybrid L3:
 - Esegui test/lint/smoke check pertinenti.
 - Verifica allineamento con Vision locale o M-VISION devPNT.
 - Aggiorna solo i documenti effettivamente impattati.
+- **Indici allineati (Poka-Yoke)**: se hai creato, spostato o rimosso documenti canonici (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`):
+  - rigenera il manifest con `sdlc_check.py index` (scrive `ai_docs/INDEX.md`) — non scriverlo a mano;
+  - se il documento e' must-read, aggiungi/aggiorna la sua riga nel `README.md` curato;
+  - se il documento ne sostituisce un altro, marca il vecchio `status: SUPERSEDED` e dichiara `supersedes:` nel nuovo;
+  - se hai creato una nuova sottodirectory canonica, dalle uno scopo nel `README.md`.
+  Doc canonico non indicizzato o senza `status` = chiusura sporca (`sdlc_check.py check` fallisce/avvisa). Non dichiarare DONE finche' non e' pulito. Dettagli: sezione "Documenti ai_docs".
 - In Hybrid proponi ADR/KL quando ci sono decisioni architetturali.
 - In Standalone, se il progetto adotta `sdlc_check.py`, esegui `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` o la copia locale equivalente.
 - I documenti aggiornati devono viaggiare nello stesso commit/PR del codice che descrivono.
 
+## Documenti ai_docs: due indici + lifecycle
+
+I documenti in `ai_docs/` hanno due ruoli serviti da due indici distinti — non confonderli:
+
+- **`ai_docs/README.md` (curato, a mano):** la priorita' di lettura. Poche righe, solo must-read canonici, cambia di rado. Giudizio umano su "cosa leggere prima".
+- **`ai_docs/INDEX.md` (generato, `sdlc_check.py index`):** il manifest completo di ogni doc canonico (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`) con descrizione e stato. Mai a mano: si rigenera, cosi' non drifta.
+- **`strategic/features_history.md` (generato):** lo storico delle ANALYSIS, dai loro frontmatter.
+- `audit/` e `solutions/` sono discovery-by-grep: non entrano nel manifest.
+
+**Header dei documenti canonici (lifecycle).** Ogni doc in quelle directory dovrebbe aprirsi con un frontmatter minimo, cosi' il manifest si genera da solo e un agente sa subito se fidarsi:
+
+```markdown
+---
+description: Una riga — cos'e' e quando leggerlo.
+status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
+supersedes: vecchio_doc.md   # solo se rimpiazza un altro doc
+---
+```
+
+In fallback (nessun frontmatter) il manifest deduce il titolo dal primo `# H1` e la descrizione dalla prima riga di prosa o blockquote; ma senza `status` un doc non porta segnale di freschezza. `status` mancante, valore non valido, o doc superseduto ancora `CURRENT` = avviso in `validate`. Un doc `SUPERSEDED` resta sul filesystem come storico, ma il suo stato lo dichiara morto: niente piu' grep che riportano a guide obsolete.
+
+Senza Python/hook (ambienti minimali) gli indici e gli header restano una disciplina di prosa: aggiorna `README.md` e marca lo `status` a mano; il validatore e' solo il backstop dove e' adottato.
+
 ## Enforcement Meccanico
 
 Il prompt non e' enforcement. Quando il progetto richiede garanzie ripetibili:

package/skills/agentic-sdlc-skill/scripts/sdlc_check.py

@@ -5,7 +5,8 @@
 Comandi:
   check      gate unico di chiusura: validate + stale in un solo comando (exit 1 se uno dei due fallisce)
   validate   verifica la coerenza strutturale di ai_docs/ (exit 1 se errori)
-  index      rigenera ai_docs/strategic/features_history.md dai frontmatter delle ANALYSIS_*.md
+  index      rigenera gli indici generati: strategic/features_history.md (dai frontmatter
+             delle ANALYSIS_*.md) e ai_docs/INDEX.md (manifest dei documenti canonici)
   stale      elenca le aree modificate dopo l'ultima analisi registrata in audit_plan.md (exit 1 se presenti)
   mark       registra percorsi come ANALYZED con riferimento corrente (hash git, altrimenti timestamp UTC)
   gate       hook PreToolUse: blocca scritture su percorsi protetti senza ANALYSIS IN_PROGRESS (exit 2)
@@ -28,6 +29,16 @@ SKIP_DIRS = {".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "ven
              "dist", "build", ".idea", ".vs", "ai_docs"}
 INDEX_HEADER = ("<!-- GENERATO da sdlc_check.py index - non modificare a mano. "
                 "Fonte di verita': frontmatter dei file ANALYSIS_*.md -->")
+MANIFEST_HEADER = ("<!-- GENERATO da sdlc_check.py index - non modificare a mano. "
+                   "Fonte di verita': gli header dei documenti canonici in ai_docs/. -->")
+# Directory i cui .md sono documenti canonici durevoli: vengono manifestati in INDEX.md.
+# audit/ e solutions/ restano discovery-by-grep (sessione / process artifact), non manifestati.
+MANIFEST_DIRS = ("vision", "reference", "architecture", "functional", "strategic")
+# Stati riconosciuti: doc canonici (CURRENT/SUPERSEDED/...), vision (DRAFT/APPROVED),
+# ADR (Accepted/Proposed/Rejected). Unione, per non dare falsi avvisi su convenzioni gia' in uso.
+CANONICAL_STATES = {"CURRENT", "SUPERSEDED", "DRAFT", "DEPRECATED",
+                    "APPROVED", "ACCEPTED", "PROPOSED", "REJECTED"}
+GENERATED_DOCS = {"features_history.md", "INDEX.md"}  # generati: mai entrate del manifest
 MTIME_GRACE = timedelta(seconds=2)
 
 try:
@@ -52,7 +63,9 @@ def find_project_root(start=None):
 
 
 def read_text(path):
-    return path.read_text(encoding="utf-8", errors="replace")
+    # utf-8-sig: scarta un eventuale BOM iniziale (file autorati su Windows) cosi'
+    # il frontmatter '---' a riga 0 resta riconoscibile; legge utf-8 normale altrimenti.
+    return path.read_text(encoding="utf-8-sig", errors="replace")
 
 
 def parse_iso(value):
@@ -181,11 +194,122 @@ def build_index(root):
     return "\n".join(lines) + "\n"
 
 
+# riga "Status:"/"Stato:" nel corpo (con o senza ** **), prefisso che precede la descrizione
+_STATUS_LINE = re.compile(r"^\**\s*(?:status|stato)\s*\**\s*:\s*\**\s*([A-Za-z][\w-]*)", re.I)
+# righe puramente di metadati da saltare quando si sceglie la descrizione di fallback
+_META_LINE = re.compile(r"^\**\s*(date|data|task ref|version|versione|owner|autore|branch|agente|created|creato|updated|aggiornato)\b", re.I)
+
+
+def extract_doc_meta(path):
+    """(title, description, status, supersedes) di un doc canonico.
+
+    Riconosce DUE convenzioni di header: il frontmatter YAML-lite
+    (description/status/supersedes/title) e la riga in corpo `**Status:** X`
+    (usata da ADR e doc legacy). In fallback deduce il titolo dal primo '# H1'
+    e la descrizione dalla prima riga di prosa, saltando le righe di metadati.
+    """
+    text = read_text(path)
+    lines = text.splitlines()
+    meta = load_frontmatter(lines)
+    body = lines
+    if lines and lines[0].strip() == "---":
+        for i in range(1, min(len(lines), 60)):
+            if lines[i].strip() == "---":
+                body = lines[i + 1:]
+                break
+
+    title = meta.get("title", "")
+    if not title:
+        for line in body:
+            m = re.match(r"^#\s+(.*)$", line)
+            if m:
+                title = m.group(1).strip()
+                break
+    title = title or path.stem
+
+    status = meta.get("status", "").upper()
+    if not status:
+        for line in body[:25]:
+            m = _STATUS_LINE.match(line.strip())
+            if m:
+                status = m.group(1).upper()
+                break
+
+    desc = meta.get("description", "")
+    if not desc:
+        for line in body:
+            s = line.strip()
+            if not s or s.startswith("#") or s.startswith("<!--") or _META_LINE.match(s):
+                continue
+            if s.startswith(">"):
+                s = s.lstrip(">").strip()
+            m = _STATUS_LINE.match(s)
+            if m:
+                # "Status: X — descrizione": tieni la parte dopo lo status; se vuota, salta
+                rest = s[m.end():].strip(" *—–-:.")
+                if not rest:
+                    continue
+                s = rest
+            if s:
+                desc = s
+                break
+    desc = re.sub(r"\s+", " ", desc).strip()
+    if len(desc) > 160:
+        desc = desc[:157].rstrip() + "..."
+    return title, desc, status, meta.get("supersedes", "").strip()
+
+
+def list_canonical_docs(root):
+    """[(rel_to_ai_docs, path, (title, desc, status, supersedes))] per i doc canonici."""
+    ai = root / "ai_docs"
+    out = []
+    for d in MANIFEST_DIRS:
+        base = ai / d
+        if not base.is_dir():
+            continue
+        for p in sorted(base.rglob("*.md")):
+            if p.name in GENERATED_DOCS or p.name == "README.md":
+                continue
+            out.append((p.relative_to(ai).as_posix(), p, extract_doc_meta(p)))
+    return out
+
+
+def build_manifest(root):
+    docs = list_canonical_docs(root)
+    lines = [MANIFEST_HEADER,
+             "# Indice documenti `ai_docs/` (generato)",
+             "",
+             "Manifest completo dei documenti canonici. Per la priorita' di lettura (must-read)",
+             "vedi il `README.md` curato a mano. Lo storico delle ANALYSIS e' in",
+             "`strategic/features_history.md`. `audit/` e `solutions/` sono discovery-by-grep,",
+             "non manifestate qui."]
+    by_dir = {}
+    for rel, _, meta in docs:
+        by_dir.setdefault(rel.split("/", 1)[0], []).append((rel, meta))
+    for top in MANIFEST_DIRS:
+        rows = by_dir.get(top)
+        if not rows:
+            continue
+        lines += ["", f"## {top}/", "",
+                  "| Documento | Stato | Descrizione |", "|---|---|---|"]
+        for rel, (title, desc, status, _sup) in rows:
+            d = (desc or title).replace("|", "\\|")
+            lines.append(f"| `{rel}` | {status or '-'} | {d} |")
+    return "\n".join(lines).rstrip() + "\n"
+
+
 def cmd_index(root):
-    target = root / "ai_docs" / "strategic" / "features_history.md"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(build_index(root), encoding="utf-8")
-    print(f"[ok] indice rigenerato: {target}")
+    hist = root / "ai_docs" / "strategic" / "features_history.md"
+    hist.parent.mkdir(parents=True, exist_ok=True)
+    hist.write_text(build_index(root), encoding="utf-8")
+    print(f"[ok] indice ANALYSIS rigenerato: {hist}")
+    # INDEX.md solo se esistono doc canonici: niente manifest vuoto su progetti minimali
+    if list_canonical_docs(root):
+        manifest = root / "ai_docs" / "INDEX.md"
+        manifest.write_text(build_manifest(root), encoding="utf-8")
+        print(f"[ok] manifest documenti rigenerato: {manifest}")
+    else:
+        print("[info] nessun documento canonico: INDEX.md non generato")
     return 0
 
 
@@ -250,6 +374,29 @@ def cmd_validate(root):
         elif norm_text(read_text(hist)) != norm_text(build_index(root)):
             errors.append("strategic/features_history.md non allineato alle ANALYSIS: esegui 'sdlc_check.py index'")
 
+    # Manifest dei documenti canonici allineato (Poka-Yoke: file non indicizzato = chiusura sporca)
+    docs = list_canonical_docs(root)
+    manifest = ai / "INDEX.md"
+    if docs:
+        if not manifest.is_file():
+            errors.append("ai_docs/INDEX.md mancante: esegui 'sdlc_check.py index'")
+        elif norm_text(read_text(manifest)) != norm_text(build_manifest(root)):
+            errors.append("ai_docs/INDEX.md non allineato ai documenti canonici: esegui 'sdlc_check.py index'")
+
+    # Lifecycle dei documenti canonici: status dichiarato + coerenza supersedes
+    canon_status = {rel: meta[2] for rel, _, meta in docs}
+    for rel, _, (title, desc, status, supersedes) in docs:
+        if not status:
+            warnings.append(f"{rel}: manca 'status:' nell'header (CURRENT/SUPERSEDED/DRAFT/DEPRECATED)")
+        elif status not in CANONICAL_STATES:
+            warnings.append(f"{rel}: status '{status}' non riconosciuto ({'/'.join(sorted(CANONICAL_STATES))})")
+        if supersedes:
+            base = os.path.basename(supersedes)
+            for other, ost in canon_status.items():
+                if (other == supersedes or other.endswith("/" + supersedes)
+                        or os.path.basename(other) == base) and ost == "CURRENT":
+                    warnings.append(f"{other}: ancora CURRENT ma superseduto da {rel} (impostare status: SUPERSEDED)")
+
     # Handoff: intestazione e freschezza
     hand = ai / "audit" / "handoff.md"
     if hand.is_file():
@@ -443,7 +590,7 @@ def main(argv=None):
     sub = ap.add_subparsers(dest="cmd", required=True)
     sub.add_parser("check", parents=[common], help="gate di chiusura: validate + stale in un solo comando")
     sub.add_parser("validate", parents=[common], help="verifica coerenza di ai_docs/")
-    sub.add_parser("index", parents=[common], help="rigenera features_history.md")
+    sub.add_parser("index", parents=[common], help="rigenera features_history.md + ai_docs/INDEX.md")
     sub.add_parser("stale", parents=[common], help="aree modificate dopo l'ultima analisi")
     mp = sub.add_parser("mark", parents=[common], help="registra percorsi come ANALYZED")
     mp.add_argument("paths", nargs="+", help="percorsi relativi alla radice del progetto")

package/skills/agentic-sdlc-skill/templates.md

@@ -5,6 +5,21 @@ Regole generali:
 - La conformità al template non è l'obiettivo: se una sezione non ha contenuto reale, scrivi esplicitamente perché non si applica. Mai testo riempitivo.
 - Date sempre assolute, in UTC dove indicato.
 
+## Header dei documenti canonici (vision/ reference/ architecture/ functional/ strategic/)
+
+Ogni documento canonico durevole apre con questo frontmatter: alimenta il manifest generato `ai_docs/INDEX.md` e dà a un agente il segnale di freschezza prima che si fidi del contenuto.
+
+```markdown
+---
+description: Una riga — cos'è il documento e quando leggerlo.
+status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
+supersedes: vecchio_doc.md   # solo se rimpiazza un altro doc canonico
+---
+# Titolo del Documento
+```
+
+Quando un doc ne sostituisce un altro: il nuovo dichiara `supersedes:`, il vecchio passa a `status: SUPERSEDED` (resta come storico, non si cancella). `sdlc_check.py validate` avvisa se `status` manca o se un doc superseduto è ancora `CURRENT`.
+
 ## ai_docs/vision/project_vision.md
 
 ```markdown
@@ -152,9 +167,13 @@ Agente: Claude
 
 ## ai_docs/strategic/architecture.md e existing_features.md
 
-Invariati rispetto alla v1:
+Doc canonici: aprono con l'header (`description:`/`status:`) cosi' entrano puliti nel manifest `INDEX.md`.
 
 ```markdown
+---
+description: Stack, struttura directory e pattern architetturali del progetto.
+status: CURRENT
+---
 # Architettura del Progetto
 ## Stack Tecnologico
 ## Struttura delle Directory
@@ -162,8 +181,12 @@ Invariati rispetto alla v1:
 ```
 
 ```markdown
+---
+description: Catalogo sintetico delle funzionalità esistenti del progetto.
+status: CURRENT
+---
 # Funzionalità Esistenti
 - [ID] **Nome Feature**: Descrizione
 ```
 
-`ai_docs/strategic/features_history.md` NON ha template: è generato da `sdlc_check.py index`.
+`ai_docs/strategic/features_history.md` e `ai_docs/INDEX.md` NON hanno template: sono generati da `sdlc_check.py index`.