@antoneeo/agentic-sdlc-skill 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,17 +1,52 @@
 # Changelog - Agentic SDLC Skill
 
-Tutte le modifiche significative a questa skill saranno documentate in questo file.
-
-## [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/README.md

@@ -1,86 +1,81 @@
-# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
-
-A "Documentation-First" SDLC protocol designed to manage the software development lifecycle rigorously. It natively supports **Claude Code** (skill auto-installed in `~/.claude/skills/`), **Gemini CLI** (extension), and **Codex AI** (skill auto-installed in `~/.codex/skills/`).
-
+# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
+
+`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Cursor/Windsurf-style project instructions, and optional devPNT governance.
+
 ## Key Features
-- **Documentation-First**: Requires documentation (`ai_docs/`) to be created or updated before writing code.
-- **Vision-Guided Governance**: Adds `ai_docs/vision/` and a Vision Gate so features stay aligned with goals, non-goals, and expected benefits.
-- **Automatic Audit**: Analyzes the existing architecture and features.
-- **Traceable Workflow**: Tracks feature status in `features_history.md`.
-- **Built-In Quality**: Native integration of analysis, development, and testing.
-
-## Installation
-
-### Via npm (recommended - installs for all detected CLIs)
-
-```bash
-npm install -g @antoneeo/agentic-sdlc-skill
-```
-
-The `postinstall` script automatically detects installed CLIs and configures each one:
-
-- **Claude Code**: copies the skill to `~/.claude/skills/agentic-sdlc/`. Restart Claude Code; invoke it through the `Skill` tool as `agentic-sdlc`, or let it trigger automatically from SDLC/audit prompts.
-- **Gemini CLI**: suggests `gemini extensions install` (see below).
-- **Codex AI**: copies the skill to `$CODEX_HOME/skills/agentic-sdlc/` or `~/.codex/skills/agentic-sdlc/`. Restart Codex to load it.
-
-`npm uninstall -g @antoneeo/agentic-sdlc-skill` also removes the skills from `~/.claude/skills/agentic-sdlc/` and `~/.codex/skills/agentic-sdlc/`.
-
-#### Troubleshooting — skill not visible in Claude Code after install
-
-If after `npm install -g` you do **not** see the line `--- Agentic SDLC Skill Discovery ---` in the npm output, and `~/.claude/skills/agentic-sdlc/` does not exist, the `postinstall` hook was skipped by npm. The most common cause is `ignore-scripts=true` in your npm config (set by some Node installers, corporate IT policies, or security tools).
-
-The package ships an explicit `agentic-sdlc-install-skill` command that does the same work but does **not** depend on the `postinstall` hook. After `npm install -g`, the bin shim is created regardless of `ignore-scripts`, so you can simply run:
-
-```bash
-npm install -g @antoneeo/agentic-sdlc-skill@latest
-agentic-sdlc-install-skill
-```
-
-You should see the `--- Agentic SDLC Skill Discovery ---` banner and `📦 Installed Claude Code skill at: ...`. Then restart Claude Code (or Codex) and the skill will be available.
-
-> **Note on `npx`**: because the package exposes two bin commands, the shorthand `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` does not work — npx cannot disambiguate. If you prefer npx, use the explicit `-p` form: `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill`.
-
-Alternatively, fix the npm config and reinstall (the `postinstall` hook will then run automatically):
-
-```bash
-npm config set ignore-scripts false
-npm uninstall -g @antoneeo/agentic-sdlc-skill
-npm install -g @antoneeo/agentic-sdlc-skill@latest
-```
-
-### Via Gemini CLI (local alternative)
-
-> **Tip:** Before installing, copy this folder from the USB drive to your computer's hard drive (for example, `C:\tools\agentic-sdlc-skill`). This keeps the skill available even after the USB drive is removed.
-
-To install this extension, open a terminal in the folder that contains this README and run:
-
-```bash
-gemini extensions install .
-```
-
-*Note: If you are in a different folder, replace `.` with the full path to the skill folder.*
-
-## Global Availability
-Once installation is complete, the skill is **globally available**. You can close this folder and move to **any other project** on your PC: Gemini CLI will automatically recognize the commands and workflow of the `agentic-sdlc` skill.
-
-## Getting Started
-
-After installation, start Gemini CLI and verify that the skill is available:
-
-1. **List available skills:**
-   ```bash
-   /skills list all
-   ```
-2. **Activate the skill:**
-   The skill activates automatically when it detects requests related to development, audits, or feature management. You can also invoke it explicitly:
-   > "Use the agentic-sdlc skill to analyze this project"
-
-## Project Structure
-- `skills/`: Contains the skill logic (`SKILL.md`).
-- `references/`: Markdown templates for Vision, architecture, analysis, and feature history.
-- `ai_docs/vision/`: Project and feature Vision documents created by the SDLC workflow.
-- `gemini-extension.json`: Extension manifest.
-
----
-Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo))
-(c) 2026 Antonio Pinto. All rights reserved.
+
+- **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work.
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star.
+- **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
+- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer.
+- **Installed support files**: Claude, Codex, and Gemini receive the full skill folder, including `templates.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`.
+- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
+
+## Installation
+
+### Via npm
+
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
+```
+
+The installer copies `skills/agentic-sdlc-skill/` recursively into native skill locations:
+
+- Claude Code: `~/.claude/skills/agentic-sdlc/`
+- Codex: `~/.codex/skills/agentic-sdlc/`
+- Gemini CLI: `~/.gemini/skills/agentic-sdlc/`
+
+Restart the relevant agent, or reload skills where the CLI supports it.
+
+The global package also exposes:
+
+```bash
+agentic-sdlc-init
+```
+
+Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+
+## Runtime Shape
+
+The actual runtime skill is the folder:
+
+```text
+skills/agentic-sdlc-skill/
+├── SKILL.md
+├── templates.md
+├── ENFORCEMENT.md
+└── scripts/
+    └── sdlc_check.py
+```
+
+`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
+
+## Standalone vs Hybrid
+
+Standalone:
+
+- `ai_docs/` is the source of truth.
+- Vision, analysis, audit, handoff, test strategy, and feature history are maintained locally.
+
+Hybrid/devPNT:
+
+- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
+- `ai_docs/` remains useful as readable context, fallback, handoff, or shadow copy.
+- Divergence between user request, local Vision, and devPNT `M-VISION` must be surfaced before implementation.
+
+## Gemini Extension Alternative
+
+You can still install this folder as a Gemini extension:
+
+```bash
+gemini extensions install .
+```
+
+For native Gemini Agent Skills, the npm installer now copies the skill folder into `~/.gemini/skills/agentic-sdlc/`.
+
+## Created By
+
+Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
+
+(c) 2026 Antonio Pinto. All rights reserved.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.4.0",
-  "description": "Protocollo SDLC Documentation-First per Gemini CLI.",
+  "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.4.0",
-  "description": "Protocollo SDLC Documentation-First per Claude Code, Gemini CLI e Codex. Auto-installa le skill native in ~/.claude/skills/ e ~/.codex/skills/. Gestisce audit, analisi, sviluppo e chiusura feature con documentazione sincronizzata.",
+  "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,7 +25,10 @@
     "preuninstall": "node scripts/preuninstall.js"
   },
   "files": [
-    "skills",
+    "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/analysis_template.md

@@ -1,25 +1,44 @@
-# Analisi della Feature: [Nome Feature]
-
+---
+id: F-XXX
+feature: [Nome Feature]
+stato: PLANNED
+livello: L3
+data_inizio: YYYY-MM-DD
+data_fine:
+---
+# Analisi della Feature: [Nome Feature]
+
 ## Obiettivo
 - Cosa si vuole ottenere?
-- Quali problemi risolve?
+- Quale problema risolve?
 
-## Allineamento alla Vision
-- Quale documento di Vision guida questa feature? (`ai_docs/vision/project_vision.md` o `ai_docs/vision/features/VISION_[nome_feature].md`)
-- Quale beneficio atteso realizza?
-- Quali non-obiettivi o vincoli di Vision devono essere rispettati?
-- Quali segnali di successo dimostreranno che la feature è coerente con la Vision?
+## Vision della Feature
+- Documento guida: `ai_docs/vision/project_vision.md` o `ai_docs/vision/features/VISION_[nome_feature].md`.
+- Stato della Vision guida: DRAFT oppure APPROVED.
+- Beneficio atteso.
+- Non-obiettivi / fuori scope.
+- Segnali di successo.
 
 ## Impatto
-- Modifiche ai file esistenti?
-- Impatti sulle performance?
-- Nuove dipendenze?
-
-## Piano d'Azione
-1. [ ] Sviluppo...
-2. [ ] Test...
-
-## Strategia di Test
-- Test unitari (AAA Pattern)
-- Test d'integrazione
-- Esempi di input e output attesi
+- File o moduli coinvolti.
+- API, contratti o formati dati impattati.
+- Performance, migrazioni o nuove dipendenze.
+
+## Sicurezza e Threat Model
+- Superfici toccate: input esterni, authN/authZ, crittografia, rete, dati personali, filesystem.
+- Minacce principali.
+- Mitigazioni.
+- Se non c'e' impatto di sicurezza, motivare perche.
+
+## Piano d'Azione
+- [ ] Sviluppo
+- [ ] Test
+- [ ] Chiusura documentale
+
+## Strategia di Test
+- Unit test AAA.
+- Test di integrazione o smoke check.
+- Verifica alternativa se i test automatici non sono eseguibili.
+
+## Diario / Stato Corrente
+- YYYY-MM-DD: Stato iniziale e prossimo passo.

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/references/feature_vision_template.md

@@ -1,5 +1,7 @@
 # Vision della Feature: [Nome Feature]
 
+Usare un file separato solo quando la feature attraversa piu ANALYSIS o piu milestone. Altrimenti tenere la Vision della Feature dentro `ANALYSIS_[feature].md`.
+
 ## Problema
 - Quale problema specifico risolve questa feature?
 

package/references/features_history_template.md

@@ -1,6 +1,5 @@
-# Storico delle Feature
-
-| ID | Nome Feature | Stato | Data Inizio | Data Fine | Doc. Analisi | Note |
-|:---|:-------------|:------|:------------|:----------|:-------------|:-----|
-| [ID] | Nome | [PLANNED] | YYYY-MM-DD | - | [ANALYSIS_nome.md] | In attesa |
-| [ID] | Altra | [COMPLETED] | YYYY-MM-DD | YYYY-MM-DD | [ANALYSIS_altra.md] | Conclusa |
+<!-- GENERATED by agentic-sdlc - update manually only if the project does not use sdlc_check.py index. -->
+# Feature History
+
+| ID | Feature Name | Level | Status | Start Date | End Date | Analysis Doc |
+|:---|:---|:---|:---|:---|:---|:---|

package/references/principles_template.md

@@ -1,6 +1,7 @@
 # Principi di Vision
+Stato: DRAFT
 
-I principi in questo file guidano trade-off, scope e decisioni tecniche quando più soluzioni sono possibili.
+I principi in questo file guidano trade-off, scope e decisioni tecniche quando piu soluzioni sono possibili.
 
 ## Principi
 - **[Principio]**: [Descrizione pratica del criterio decisionale].
@@ -9,4 +10,4 @@ I principi in questo file guidano trade-off, scope e decisioni tecniche quando p
 - Preferire [A] rispetto a [B] quando [condizione].
 
 ## Anti-Pattern Strategici
-- [Comportamento o direzione da evitare perché devia dalla Vision].
+- [Comportamento o direzione da evitare perche devia dalla Vision].

package/references/project_vision_template.md

@@ -1,13 +1,14 @@
 # Vision del Progetto
+Stato: DRAFT
 
 ## North Star
-- Qual è l'obiettivo finale che il progetto deve preservare nel tempo?
+- Qual e' l'obiettivo finale che il progetto deve preservare nel tempo?
 
 ## Problema Centrale
 - Quale problema reale risolve il progetto?
 
 ## Utenti Target
-- Chi sono gli utenti o stakeholder principali?
+- Chi sono utenti o stakeholder principali?
 
 ## Valore Atteso
 - Quale beneficio misurabile o osservabile deve produrre il progetto?
@@ -18,7 +19,7 @@
 
 ## Non-Obiettivi
 - [Cosa il progetto non vuole diventare]
-- [Cosa è esplicitamente fuori scope]
+- [Cosa e' esplicitamente fuori scope]
 
 ## Segnali di Successo
 - [Indicatore qualitativo o quantitativo]

package/references/roadmap_template.md

@@ -1,8 +1,9 @@
 # Roadmap della Vision
+Stato: DRAFT
 
-| Milestone | Beneficio Atteso | Priorità | Segnali di Successo | Stato |
+| Milestone | Beneficio Atteso | Priorita | Segnali di Successo | Stato |
 |:---|:---|:---|:---|:---|
 | M1 | [Beneficio] | Alta | [Segnale] | [PLANNED] |
 
 ## Note di Direzione
-- Decisioni strategiche o cambi di priorità rilevanti.
+- Decisioni strategiche o cambi di priorita rilevanti.

package/scripts/init.js

@@ -44,49 +44,65 @@ const files = {
 // 2. Operational Protocol (System Prompt)
 const protocolContent = `# "Agentic SDLC" Operational Protocol
 
-You are a senior software engineer strictly following a "Documentation-First" and "Vision-Guided" process. NEVER implement code without completing the preceding documentation steps. Use your tools (file read/write, shell execution) to adhere to the following phases.
-
-## 1. Audit and Alignment Phase
-Before responding to any operational request:
-- Check for the existence of the \`ai_docs/\` and \`ai_docs/vision/\` folders.
-- If \`ai_docs/\` is missing or essential documents are absent, create them by analyzing the source code:
-    1. \`ai_docs/vision/project_vision.md\`: North Star, target users, goals, non-goals, success signals.
-    2. \`ai_docs/vision/roadmap.md\`: Milestones, expected benefits, priorities, success signals.
-    3. \`ai_docs/vision/principles.md\`: Stable decision principles and strategic anti-patterns.
-    4. \`ai_docs/strategic/architecture.md\`: Tech Stack, Directory Structure, Architecture Patterns.
-    5. \`ai_docs/strategic/existing_features.md\`: List of current features.
-    6. \`ai_docs/strategic/features_history.md\`: Feature history table (ID, Name, Status, Dates).
-    7. \`ai_docs/audit/audit_plan.md\`: Codebase analysis plan in batches.
+You are a senior software engineer following a Documentation-First and Vision-Guided process. The process is proportional to risk: do not apply heavyweight governance to trivial work, but never bypass Vision, security, or design gates for significant changes.
+
+## 0. Triage First
+Classify every operational request:
+- L1 Trivial: small local fix, no API/dependency/behavior expansion. Implement with relevant tests; no new docs.
+- L2 Small: clear root cause, up to 3 files, low risk. Provide mini-analysis in the response; test.
+- L3 Significant: public contract, user-visible behavior, security-sensitive area, new dependency, architectural impact, or more than 3 files. Use the full workflow below.
+- Spike: time-boxed exploration; document result in \`ai_docs/solutions/SPIKE_[topic].md\`; production work must be reclassified.
+
+Security-sensitive areas are never L1.
+
+## 1. Mode Selection
+- Standalone: if devPNT is unavailable, use \`ai_docs/\` as the complete source of truth.
+- Hybrid/devPNT: if devPNT is available and configured for this project, use it for governed state. The devPNT M-VISION is the milestone north star, Master Plan is strategic roadmap, Action Plan is tactical execution, and governed artifacts live in devPNT.
+- Do not create silent double truth. In Hybrid, \`ai_docs/\` is human-readable context, fallback, handoff, or shadow; devPNT governs plans and versioned artifacts.
+
+## 2. Audit and Alignment
+For L3 or explicit audit requests:
+- Check \`ai_docs/\`, \`ai_docs/vision/\`, \`ai_docs/strategic/\`, \`ai_docs/audit/\`, and \`ai_docs/solutions/\`.
+- If missing, create them by analyzing the codebase in batches.
 - Never treat architecture or feature history as a substitute for Vision.
 
-## 2. Vision Gate
-For every new feature request or significant behavior change:
-- Read \`ai_docs/vision/project_vision.md\`, \`ai_docs/vision/roadmap.md\`, and \`ai_docs/vision/principles.md\`.
-- If Vision documents are missing, empty, or ambiguous, create or update them before technical analysis.
-- For significant features, create \`ai_docs/vision/features/VISION_[feature_name].md\` covering Problem, Expected Benefit, Users/Stakeholders, Success Signals, Non-Goals, and linked principles.
-- If the request conflicts with Vision, stop and surface the conflict instead of implementing silently.
-
-## 3. Request Analysis Phase
-For every new feature request:
-- Create \`ai_docs/solutions/ANALYSIS_[feature_name].md\` (Objective, Vision Alignment, Impact, Action Plan, Test Strategy).
-- Add an entry in \`ai_docs/strategic/features_history.md\` with status \`[PLANNED]\`.
-
-## 4. Development and Testing Phase
-Only after Phases 2 and 3 are complete:
-1. Update feature status to \`[IN_PROGRESS]\` in \`ai_docs/strategic/features_history.md\`.
-2. Implement code surgically following the plan.
-3. **Mandatory:** Write automated tests following the **AAA (Arrange, Act, Assert)** pattern.
-4. Execute tests. If they fail, fix and re-run until Exit Code is 0.
-
-## 5. Closing Phase
-Upon feature completion:
-- Verify the delivered result against \`ai_docs/vision/project_vision.md\` and the feature Vision document, including non-goals.
-- Update \`ai_docs/strategic/architecture.md\` and \`ai_docs/strategic/existing_features.md\` if necessary.
-- Update \`ai_docs/vision/\` documents if goals, non-goals, roadmap, expected benefits, or success signals changed.
-- Update \`ai_docs/strategic/features_history.md\` setting status to \`[COMPLETED]\`.
+## 3. Vision Gate
+Standalone:
+- Read \`ai_docs/vision/project_vision.md\`, \`roadmap.md\`, and \`principles.md\`.
+- Vision documents start as \`Stato: DRAFT\`; DRAFT informs but does not block an explicit user request.
+- \`Stato: APPROVED\` is binding: surface conflicts before implementation.
+
+Hybrid/devPNT:
+- Read the active M-VISION before design or code.
+- Verify the request advances a stated benefit or success signal.
+- If request, local Vision, and M-VISION diverge, stop and surface the conflict.
+
+## 4. Request Analysis
+For L3 in Standalone:
+- Create or update \`ai_docs/solutions/ANALYSIS_[feature].md\`.
+- Include Objective, Feature Vision, Impact, Security and Threat Model, Action Plan, Test Strategy, and Diary/Current State.
+
+For L3 in Hybrid:
+- Restore Master Plan, Action Plan, and related devPNT artifacts.
+- Use devPNT for D-UC, P-TM, E-ISP, E-TDD, E-TP, ADR, and plan updates.
+- Use Markdown shadows only as readable mirrors, never as the authoritative source over devPNT.
+
+## 5. Development and Testing
+Only after the required gate for the triage level:
+1. Implement surgically following the plan.
+2. Write or update automated tests where possible, using AAA for unit tests.
+3. Run tests/lint/smoke checks. If the environment cannot run them, document the alternative verification.
+4. After 3 consecutive test runs without progress, stop and ask for guidance.
+
+## 6. Closing
+- Verify the result against local Vision or devPNT M-VISION.
+- Update only documents actually impacted.
+- In Hybrid, propose ADR/KL updates when architectural facts changed.
+- Keep docs and code in the same commit/PR.
 `;
 
 const projectVisionBoilerplate = `# Project Vision
+Stato: DRAFT
 
 ## North Star
 - TBD
@@ -105,6 +121,7 @@ const projectVisionBoilerplate = `# Project Vision
 `;
 
 const roadmapBoilerplate = `# Vision Roadmap
+Stato: DRAFT
 
 | Milestone | Expected Benefit | Priority | Success Signal | Status |
 |:---|:---|:---|:---|:---|
@@ -112,6 +129,7 @@ const roadmapBoilerplate = `# Vision Roadmap
 `;
 
 const principlesBoilerplate = `# Vision Principles
+Stato: DRAFT
 
 ## Principles
 - TBD
@@ -120,12 +138,12 @@ const principlesBoilerplate = `# Vision Principles
 - TBD
 `;
 
-const historyBoilerplate = `# Feature History
-
-| ID | Feature Name | Status | Start Date | End Date | Analysis Doc | Notes |
-|:---|:---|:---|:---|:---|:---|:---|
-| 000 | Project Init | [COMPLETED] | - | - | - | Automatic initialization |
-`;
+const historyBoilerplate = `<!-- GENERATED by agentic-sdlc - update manually only if the project does not use sdlc_check.py index. -->
+# Feature History
+
+| ID | Feature Name | Level | Status | Start Date | End Date | Analysis Doc |
+|:---|:---|:---|:---|:---|:---|:---|
+`;
 
 console.log('🚀 Initializing Agentic SDLC workflow (Discovery Mode)...');
 
@@ -155,7 +173,7 @@ writeIfNotExists(files.principles, principlesBoilerplate, 'Vision Principles Boi
 writeIfNotExists(files.architecture, '# Project Architecture\n\n- Stack:\n- Patterns:\n', 'Architecture Boilerplate');
 writeIfNotExists(files.existingFeatures, '# Existing Features\n\n- \n', 'Features Boilerplate');
 writeIfNotExists(files.featuresHistory, historyBoilerplate, 'History Table');
-writeIfNotExists(files.auditPlan, '# Audit Plan\n\n| Directory/File | Status | Notes |\n|:---|:---|:---|\n| / | [PENDING] | Initial analysis |\n', 'Audit Plan');
+writeIfNotExists(files.auditPlan, '# Audit Plan\n\nStates: PENDING | ANALYZED | SKIPPED.\n\n| Percorso | Stato | Riferimento | Note |\n|---|---|---|---|\n| / | PENDING | - | Initial analysis |\n', 'Audit Plan');
 
 // 5. Client Discovery and Configuration
 console.log('\n--- Environment Analysis ---');