@antoneeo/agentic-sdlc-skill 1.6.0 → 1.8.0

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

@@ -1,172 +1,263 @@
----
-name: agentic-sdlc
-description: Protocollo SDLC Documentation-First con triage proporzionale, Vision come guida, modalita Standalone completa e simbiosi opzionale con devPNT. Usare per feature, bug significativi, refactor, audit e manutenzione documentata.
-author: Antonio Pinto (https://github.com/Antoneeo)
-copyright: (c) 2026 Antonio Pinto
----
-
-# Agentic SDLC
-
-Questa skill guida lo sviluppo software con un processo Documentation-First proporzionale al rischio. Deve funzionare pienamente anche senza devPNT. Quando devPNT e' disponibile e configurato per il progetto corrente, la skill lavora in simbiosi con la sua governance: M-VISION, Master Plan, Action Plan e artefatti versionati diventano il quadro autorevole per milestone e implementazione.
-
-File di supporto nella directory della skill:
-- `templates.md`: template per Vision, ANALYSIS, Spike, audit plan e handoff.
-- `scripts/sdlc_check.py`: validatore meccanico per `ai_docs/` (`check`, `validate`, `index`, `stale`, `mark`, `gate`).
-- `ENFORCEMENT.md`: setup opzionale per CI e hook.
-
-Leggi questi file solo quando servono. `SKILL.md` e' il contratto operativo; i support file sono risorse progressive.
-
-## Valori Tecnici
-
-- **Comprendi prima di agire:** non modificare codice senza capire root cause, vincoli e forma attuale.
-- **Mantieni coerenza architetturale:** rispetta layer, responsabilita, naming, pattern e convenzioni esistenti.
-- **Applica DRY e semplicita:** non duplicare logica o conoscenza; astrai solo se riduce complessita reale.
-- **Preserva qualita:** ogni modifica deve mantenere o migliorare stabilita, testabilita e manutenibilita.
-- **Verifica tecnicamente:** chiudi lavoro implementativo con test, lint, smoke check o motivo esplicito.
-- **Mantieni memoria utile:** documenta decisioni e stato operativo rilevanti, non testo riempitivo.
-- **Proteggi la Vision:** ogni decisione deve restare allineata a benefici attesi, utenti, non-obiettivi e segnali di successo.
-
-Se una patch sembra facile ma non capisci perche il codice attuale e' fatto cosi, indaga prima.
-
-## Regola Zero: Triage
-
-Classifica sempre la richiesta prima di scegliere il processo. Dichiara il livello scelto all'utente quando inizi il lavoro operativo.
-
-| Livello | Criteri | Processo richiesto |
-|---|---|---|
-| **L1 - Triviale** | Circa 10 righe in 1-2 file; nessun cambio API, dipendenza o comportamento nuovo; refusi o fix che ripristinano comportamento gia atteso | Implementa. Esegui test pertinenti se esistono. Nessun nuovo documento. |
-| **L2 - Piccolo** | Root cause chiara; massimo 3 file; nessuna nuova dipendenza o API pubblica; rischio basso | Mini-analisi nel messaggio: obiettivo, impatto, sicurezza, test. Test obbligatori. Nessun nuovo documento salvo aggiornare analisi/handoff esistenti se utile. |
-| **L3 - Significativo** | Oltre 3 file, API/contratti, nuova dipendenza, comportamento visibile, area security-sensitive, cambio architetturale o design non ovvio | Workflow completo: Vision Gate, analisi, piano, implementazione, test, chiusura. |
-| **Spike** | Esplorazione time-boxed per ridurre incertezza | Codice non mergiabile in main. Esito in `ai_docs/solutions/SPIKE_[tema].md`. Per produzione riclassifica come L2 o L3. |
-
-Regole trasversali:
-- Parsing input esterni, authN/authZ, crittografia, rete, dati personali e filesystem sono security-sensitive: mai L1.
-- Se durante L1/L2 emerge impatto maggiore, fermati, riclassifica e dichiaralo.
-- Nel dubbio scegli il livello piu alto.
-- L'audit completo non parte per L1/L2 salvo richiesta esplicita.
-
-## Modalita Operative
-
-### Standalone completa
-
-Usa questa modalita quando devPNT non e' disponibile, non e' configurato per il progetto corrente o l'utente chiede esplicitamente un workflow solo filesystem.
-
-Fonte di verita:
-- Vision: `ai_docs/vision/project_vision.md`, `roadmap.md`, `principles.md`.
-- Feature/analisi: `ai_docs/solutions/ANALYSIS_[feature].md`.
-- Audit/handoff: `ai_docs/audit/`.
-- Storico feature: `ai_docs/strategic/features_history.md` manuale o generato dal validatore, in base alla struttura adottata dal progetto.
-
-La modalita Standalone non e' ridotta: deve poter gestire audit, feature, bug significativi, test, handoff e chiusura senza devPNT.
-
-### Hybrid in simbiosi con devPNT
-
-Usa questa modalita quando i tool `devpnt_*` sono disponibili e puntano al progetto corrente.
-
-Gerarchia autorevole:
-1. **M-VISION devPNT**: faro strategico della milestone. Prima di design o codice, leggila e verifica benefici, success signals, scope-in e non-goals.
-2. **Master Plan devPNT**: roadmap strategica e milestone.
-3. **Action Plan devPNT**: lavoro tattico corrente per il goal attivo.
-4. **Artefatti governati devPNT**: `D-UC`, `P-TM`, `E-ISP`, `E-TDD`, `E-TP`, ADR.
-5. **`ai_docs/` locale**: contesto leggibile, fallback Standalone, handoff locale o shadow/mirror quando utile.
-
-Regole Hybrid:
-- devPNT e' la fonte governata per piani e artefatti; non creare una seconda verita in `ai_docs/`.
-- La skill resta autonoma: se devPNT non c'e', passa a Standalone senza perdere capacita.
-- Se richiesta utente, Vision locale e M-VISION divergono, fermati e rendi esplicito il conflitto.
-- Non creare o modificare milestone senza rispettare la M-VISION.
-- Non accettare automaticamente proposte devPNT: presenta la preview e attendi conferma esplicita.
-- Se il protocollo devPNT locale impone bootstrap, piani o gate piu severi, seguili.
-
-## Workflow L3
-
-### 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.
-- Per template dettagliati usa `templates.md`.
-
-### 2. Vision Gate
-
-Standalone:
-- Leggi `project_vision.md`, `roadmap.md`, `principles.md`.
-- Se un documento dichiara `Stato: DRAFT`, trattalo come ipotesi: segnala conflitti, ma non bloccare una richiesta esplicita dell'utente.
-- Se dichiara `Stato: APPROVED`, e la richiesta confligge, fermati e chiedi scelta: aggiornare Vision o modificare/rifiutare la richiesta.
-- Non promuovere mai una Vision a `APPROVED` senza conferma dell'utente.
-
-Hybrid:
-- Leggi la M-VISION della milestone o chiedi/crea il passaggio richiesto dal protocollo devPNT.
-- Verifica che la richiesta serva un beneficio o success signal della M-VISION.
-- Se la richiesta aggiunge scope non autorizzato, trattala come divergenza di Vision.
-
-### 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`.
-
-Hybrid L3:
-- Ripristina Master Plan, Action Plan e documenti collegati.
-- Usa devPNT per piani e artefatti governati.
-- Usa `ai_docs/solutions/SHADOW_[doc_key]_vX.Y.md` solo come shadow leggibile quando serve; in divergenza vince devPNT.
-
-### 4. Sviluppo e Test
-
-- Implementa solo dopo il gate documentale richiesto dal livello.
-- Modifica in modo chirurgico, coerente con il piano.
-- Scrivi o aggiorna test automatici pertinenti; usa AAA per unit test quando applicabile.
-- Se l'ambiente non permette test automatici, dichiara verifica alternativa e motivo.
-- Circuit breaker: dopo 3 esecuzioni consecutive senza progresso sui test, fermati e chiedi istruzioni.
-- Aggiorna il Diario dell'ANALYSIS o l'Action Plan quando completi milestone, incontri blocchi o cambi decisione.
-
-### 5. Chiusura
-
-- 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:
-- leggi `ENFORCEMENT.md`;
-- usa `scripts/sdlc_check.py validate` in CI;
-- usa `scripts/sdlc_check.py gate` solo per directory security-critical, non per tutto il repository.
-
-Il validatore e' un supporto, non un prerequisito universale: la skill deve restare usabile anche in ambienti senza Python o senza hook, dichiarando cosa non puo' verificare automaticamente.
+---
+name: agentic-sdlc
+description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: (c) 2026 Antonio Pinto
+---
+
+# Agentic SDLC
+
+This skill guides software development with a Documentation-First process proportional to risk. It must work fully even without devPNT. When devPNT is available and configured for the current project, the skill works in symbiosis with its governance: M-VISION, Master Plan, Action Plan and versioned artifacts become the authoritative frame for milestones and implementation.
+
+Support files in the skill directory:
+- `templates.md`: templates for Vision, ANALYSIS, Spike, audit plan and handoff.
+- `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
+- `scripts/sdlc_check.py`: mechanical validator for `ai_docs/` (`check`, `validate`, `index`, `stale`, `mark`, `gate`).
+- `ENFORCEMENT.md`: optional setup for CI and hooks.
+
+Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
+
+## Technical Values
+
+- **Understand before acting:** do not modify code without understanding root cause, constraints and current shape.
+- **Preserve architectural coherence:** respect existing layers, responsibilities, naming, patterns and conventions.
+- **Apply DRY and simplicity:** do not duplicate logic or knowledge; abstract only when it reduces real complexity.
+- **Preserve quality:** every change must maintain or improve stability, testability and maintainability.
+- **Verify technically:** close implementation work with tests, lint, smoke checks or an explicit reason.
+- **Keep useful memory:** document relevant decisions and operational state, not filler text.
+- **Protect the Vision:** every decision must stay aligned with expected benefits, users, non-goals and success signals.
+
+If a patch looks easy but you do not understand why the current code is shaped the way it is, investigate first.
+
+## Rule Zero: Triage
+
+Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
+
+| Level | Criteria | Required process |
+|---|---|---|
+| **L1 - Trivial** | About 10 lines in 1-2 files; no API, dependency or new-behavior change; typos or fixes restoring already-expected behavior | Implement. Run relevant existing tests. No new documents. |
+| **L2 - Small** | Clear root cause; at most 3 files; no new dependency or public API; low risk | Mini-analysis in the message: objective, impact, security, tests. Tests mandatory. No new document, except updating an existing analysis/handoff if useful. |
+| **L3 - Significant** | More than 3 files, APIs/contracts, new dependency, user-visible behavior, security-sensitive area, architectural change or non-obvious design | Full workflow: Vision Gate, analysis, plan, implementation, tests, closure. |
+| **Spike** | Time-boxed exploration to reduce uncertainty | Code not mergeable into main. Outcome in `ai_docs/solutions/SPIKE_[topic].md`. For production, reclassify as L2 or L3. |
+
+Cross-cutting rules:
+- Parsing of external input, authN/authZ, cryptography, networking, personal data and filesystem access are security-sensitive: never L1.
+- If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
+- When in doubt, pick the higher level.
+- The full audit does not start for L1/L2 unless explicitly requested.
+
+## Operating Modes
+
+### Full Standalone
+
+Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
+
+Source of truth:
+- Vision: `ai_docs/vision/project_vision.md`, `roadmap.md`, `principles.md`.
+- Features/analyses: `ai_docs/solutions/ANALYSIS_[feature].md`.
+- Audit/handoff: `ai_docs/audit/`.
+- Feature history: `ai_docs/strategic/features_history.md`, manual or generated by the validator, depending on the structure the project adopts.
+
+Standalone mode is not reduced: it must handle audits, features, significant bugs, tests, handoffs and closure without devPNT.
+
+### Hybrid in symbiosis with devPNT
+
+Use this mode when the `devpnt_*` tools are available and point at the current project.
+
+Authoritative hierarchy:
+1. **devPNT M-VISION**: strategic beacon of the milestone. Before design or code, read it and verify benefits, success signals, scope-in and non-goals.
+2. **devPNT Master Plan**: strategic roadmap and milestones.
+3. **devPNT Action Plan**: current tactical work for the active goal.
+4. **devPNT governed artifacts**: `D-UC`, `P-TM`, `E-ISP`, `E-TDD`, `E-TP`, ADR.
+5. **Local `ai_docs/`**: readable context, Standalone fallback, local handoff or shadow/mirror when useful.
+
+Hybrid rules:
+- devPNT is the governed source for plans and artifacts; do not create a second truth in `ai_docs/`.
+- The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
+- If the user request, the local Vision and the M-VISION diverge, stop and make the conflict explicit.
+- Do not create or modify milestones without respecting the M-VISION.
+- Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
+- If the local devPNT protocol imposes stricter bootstrap, plans or gates, follow them.
+
+## Coexistence with devPNT (the Hybrid seam)
+
+This section is the single authoritative answer to "who owns what" when both the
+skill and devPNT are active. The skill owns the **process** (triage, phases, Vision
+Gate, lifecycle); devPNT owns the **machinery** (governed storage, versioned
+proposals, semantic analysis, independent reviewers). devPNT strengthens the
+process; it never replaces it.
+
+### Ownership matrix
+
+| Artifact | Standalone master | Hybrid master | Mirror rule |
+|---|---|---|---|
+| Product vision | `vision/project_vision.md` | `vision/project_vision.md` (product scope) | devPNT KL vision is regenerated from it, never edited independently |
+| Milestone vision | `vision/roadmap.md` milestones | devPNT M-VISION | `roadmap.md` may reference the M-VISION key; it never restates its content |
+| Feature design | `solutions/ANALYSIS_[feature].md` | devPNT E-ISP/E-TDD (+ D-UC/P-TM) | shadow exported from the ACCEPTED DB version as `SHADOW_[doc_key]_vX.Y.md`; on divergence the DB wins and the shadow is regenerated |
+| Plans | `## Action Plan` inside the ANALYSIS | devPNT Master/Action Plan | none |
+| Feature state | ANALYSIS frontmatter `status` | Action Plan node status | mapping table below; at closure both must move together |
+| ADR | `architecture/` (canonical dir) | devPNT DB (`adr_YYYY-MM-DD_slug`) | optional filesystem shadow `SHADOW_adr_*` exported at closure for grep-ability |
+| Audit / freshness | `audit/audit_plan.md` + `stale`/`mark` | devPNT KL coverage + summary status | run `check --hybrid` (skips audit-plan staleness) |
+| Operative guides | `ai_docs/reference/` | `ai_docs/reference/` — **filesystem-first even in Hybrid** | devPNT bootstrap may point at their index; it never copies their content |
+| Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
+
+### Triage equivalence (one threshold, two vocabularies)
+
+devPNT's "significance threshold" and the skill's triage are the SAME test. Do not
+run two classifications:
+
+| Skill triage | devPNT equivalent | Governed artifacts |
+|---|---|---|
+| L1 Trivial | trivial exempt | none |
+| L2 Small | localized obvious edit | none — but see escalation |
+| L3 Significant | governed unit of change | D-UC/P-TM/E-ISP/E-TDD per the devPNT trigger policy |
+| Spike | exempt (non-mergeable) | `SPIKE_[topic].md` only |
+
+Escalation triggers (any one of these makes it L3, in BOTH vocabularies): touches
+more than one module, changes a public API/contract/message format, changes a data
+model or state machine, has a security surface, risks duplicating existing logic,
+or the design choice is non-obvious. An L2 that trips one of these is not an L2.
+
+### Feature state mapping
+
+| ANALYSIS frontmatter | devPNT plan node |
+|---|---|
+| PLANNED | READY (or BLOCKED / ON_HOLD while waiting) |
+| IN_PROGRESS | PROGRESS |
+| COMPLETED | DONE |
+| CANCELLED | CANCELLED |
+
+Closure discipline: never mark the node DONE while the shadow/ANALYSIS still says
+IN_PROGRESS, or vice versa. They move in the same closure step.
+
+### Shadow discipline (Hybrid)
+
+- Shadow filename: `SHADOW_[doc_key]_vX.Y.md`, first line
+  `<!-- SHADOW generated from devPNT (doc_key vX.Y) - do not edit by hand -->`.
+  Never save a shadow under an `ANALYSIS_*` name: that name means "authoritative
+  Standalone document" and the validator treats it as such.
+- **Export the approved E-TDD shadow BEFORE implementation** (not only at closure).
+  It gives context-free subagents their design input, unlocks `gate --hybrid`, and
+  guarantees the filesystem fallback if devPNT becomes unavailable mid-feature.
+- At closure, refresh all shadows from the accepted DB versions.
+
+### Validator in Hybrid
+
+Pass `--hybrid` explicitly (never auto-detected — an explicit flag beats a guessed
+mode): `check --hybrid` and `stale --hybrid` skip audit-plan staleness (mapping is
+delegated to devPNT/KL) — guide-drift checking still runs (`ai_docs/reference/`
+is filesystem-first even in Hybrid, see the ownership matrix above); `gate --hybrid`
+also unlocks on the presence of an E-TDD shadow in `solutions/` (the Hybrid design
+gate) instead of requiring an IN_PROGRESS ANALYSIS.
+
+## L3 Workflow
+
+### 1. Audit and Alignment
+
+- Read `ai_docs/audit/handoff.md` if it exists; if its Date/Branch are inconsistent, treat it as history.
+- Read `ai_docs/README.md` (curated must-reads) and `ai_docs/INDEX.md` (generated manifest of all canonical docs) to know what exists before exploring the code. `solutions/` and `audit/` are not indexed per file: search them with glob/grep.
+- If `ai_docs/` is missing or incomplete, create the structure and minimal documents by analyzing the project in batches.
+- In Standalone use `ai_docs/audit/audit_plan.md` for mapping and state.
+- In Hybrid prefer the devPNT/KL mapping when available; do not duplicate plan governance.
+- For detailed templates use `templates.md`.
+
+### 2. Vision Gate
+
+Standalone:
+- Read `project_vision.md`, `roadmap.md`, `principles.md`.
+- If a document declares `Status: DRAFT`, treat it as a hypothesis: flag conflicts, but do not block an explicit user request.
+- If it declares `Status: APPROVED` and the request conflicts, stop and ask for a choice: update the Vision or modify/reject the request.
+- Never promote a Vision to `APPROVED` without the user's confirmation.
+
+Hybrid:
+- Read the milestone's M-VISION, or ask for/create the step required by the devPNT protocol.
+- Verify that the request serves a benefit or success signal of the M-VISION.
+- If the request adds unauthorized scope, treat it as a Vision divergence.
+
+### 3. Request Analysis
+
+Standalone L3:
+- Before creating a new `ANALYSIS_[feature].md`, search `ai_docs/solutions/` with glob/grep for an existing analysis on the same topic: if there is one, update it instead of duplicating it.
+- Create or update `ai_docs/solutions/ANALYSIS_[feature].md`.
+- Minimum sections: Objective, Feature Vision (or Vision Alignment), Impact, Security and Threat Model, Action Plan, Test Strategy, Diary/Current State.
+- For features spanning multiple milestones or multiple analyses, also create `ai_docs/vision/features/VISION_[feature].md`.
+
+Hybrid L3:
+- Restore the Master Plan, Action Plan and linked documents.
+- Use devPNT for plans and governed artifacts.
+- Use `ai_docs/solutions/SHADOW_[doc_key]_vX.Y.md` only as a readable shadow when needed; on divergence devPNT wins.
+
+### 4. Development and Testing
+
+- Implement only after the documentation gate required by the level.
+- Modify surgically, consistently with the plan.
+- Write or update relevant automated tests; use AAA for unit tests when applicable.
+- If the environment does not allow automated tests, declare the alternative verification and the reason.
+- Circuit breaker: after 3 consecutive runs without progress on the tests, stop and ask for instructions.
+- Update the ANALYSIS Diary or the Action Plan when you complete milestones, hit blockers or change decisions.
+
+### 5. Closure
+
+- Run the relevant tests/lint/smoke checks.
+- Verify alignment with the local Vision or the devPNT M-VISION.
+- Update only the documents actually impacted.
+- **Aligned indexes (Poka-Yoke)**: if you created, moved or removed canonical documents (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`):
+  - regenerate the manifest with `sdlc_check.py index` (writes `ai_docs/INDEX.md`) — never write it by hand;
+  - if the document is a must-read, add/update its line in the curated `README.md`;
+  - if the document replaces another, mark the old one `status: SUPERSEDED` and declare `supersedes:` in the new one;
+  - if you created a new canonical subdirectory, give it a purpose in `README.md`.
+  A canonical doc that is unindexed or lacks `status` = dirty closure (`sdlc_check.py check` fails/warns). Do not declare DONE until it is clean. Details: section "ai_docs documents".
+  - guides created or changed: `sdlc_check.py index` regenerates BOTH manifests (`ai_docs/INDEX.md` and the guide router `ai_docs/reference/INDEX.md`) in one run.
+- In Hybrid propose ADR/KL updates when there were architectural decisions.
+- In Standalone, if the project adopts `sdlc_check.py`, run `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` or the equivalent local copy.
+- Updated documents must travel in the same commit/PR as the code they describe.
+
+## ai_docs documents: two indexes + lifecycle
+
+Documents in `ai_docs/` play two roles served by two distinct indexes — do not confuse them:
+
+- **`ai_docs/README.md` (curated, by hand):** the reading priority. Few lines, only canonical must-reads, changes rarely. Human judgement on "what to read first".
+- **`ai_docs/INDEX.md` (generated, `sdlc_check.py index`):** the complete manifest of every canonical doc (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`) with description and status. Never by hand: it is regenerated, so it does not drift.
+- **`strategic/features_history.md` (generated):** the ANALYSIS history, from their frontmatter.
+- `audit/` and `solutions/` are discovery-by-grep: they do not enter the manifest.
+
+**Canonical document header (lifecycle).** Every doc in those directories should open with a minimal frontmatter, so the manifest generates itself and an agent knows immediately whether to trust it:
+
+```markdown
+---
+description: One line — what it is and when to read it.
+status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
+supersedes: old_doc.md       # only if it replaces another doc
+---
+```
+
+As a fallback (no frontmatter) the manifest derives the title from the first `# H1` and the description from the first prose line or blockquote; but without `status` a doc carries no freshness signal. A missing `status`, an invalid value, or a superseded doc still marked `CURRENT` = warning in `validate`. A `SUPERSEDED` doc stays on the filesystem as history, but its state declares it dead: no more greps leading back to obsolete guidance.
+
+Without Python/hooks (minimal environments) the indexes and headers remain a prose discipline: update `README.md` and mark the `status` by hand; the validator is only the backstop where it is adopted.
+
+Legacy note: the validator also accepts the deprecated Italian frontmatter keys (`stato`, `livello`, `data_inizio`, `data_fine`) and Italian section headings in existing projects. New documents must use the English forms.
+
+## Operative Guides
+
+Trigger test: the user hands over indications to follow (origin = user, not model
+knowledge) meant to govern how the agent operates (purpose = operative), not just
+inform an answer. Both hold → distill into `ai_docs/reference/GUIDE_[topic].md`.
+
+A guide TRAINS the agent, two levels: the guide is the **synthesis** a trained
+agent carries (compact — read whole before acting); the verbatim snapshot in
+`.sources/` is the **book**, reached on demand via the section markers. Fidelity
+constraint: only what the source supports; gaps marked `[not covered by source]`,
+never filled from general knowledge; selection and compression expected, addition
+forbidden. Full pipeline, DRY rule, snapshotting and maintenance: `guides.md`.
+
+`ai_docs/reference/INDEX.md` is generated (the guide router) — never edit by hand,
+regenerate with `sdlc_check.py index`.
+
+## Mechanical Enforcement
+
+The prompt is not enforcement. When the project needs repeatable guarantees:
+- read `ENFORCEMENT.md`;
+- use `scripts/sdlc_check.py validate --strict` in CI;
+- use `scripts/sdlc_check.py gate` only for security-critical directories, not for the whole repository.
+
+The validator is a support, not a universal prerequisite: the skill must stay usable in environments without Python or hooks, declaring what it cannot verify automatically.

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

@@ -0,0 +1,153 @@
+# Operative Guides — pipeline
+
+Support file for `ai_docs/reference/GUIDE_[topic].md`. Read this only when the
+trigger below fires; the template lives in `templates.md`.
+
+**The training model (what a guide IS).** A guide TRAINS the agent on a topic
+the user cares about, the way training works for a person: you study the
+material once, you carry a SYNTHESIS in your head, and you go back to the book
+when a task needs detail. Two levels, both produced by this pipeline:
+- **The guide = the synthesis** — compact and dense: core principles, decision
+  rules, the map of what exists, where people go wrong. Small enough that a
+  reader takes it in WHOLE before acting (that is the "preparation").
+- **The snapshot = the book** (`.sources/`, verbatim) — the details live here,
+  reachable on demand.
+- **The fidelity markers are the bridge**: `[source: <snapshot>#anchor]` both
+  proves provenance AND tells the reader where in the book the full detail is.
+A guide that restates the source at length is as wrong as a fragmented one:
+completeness is guaranteed by the book level, economy by the synthesis level.
+
+## 1. When to trigger
+
+Trigger test is origin + purpose, not content taxonomy (no "is this technical
+enough" judgement call):
+- **Origin**: the user hands you indications to follow — a document to adhere
+  to, a pasted policy, "do it this way", a style guide, a runbook.
+- **Purpose**: the material is meant to GOVERN how the agent operates, not
+  just inform a one-off answer.
+
+Both hold → this is guide material. Either is missing (e.g. the user pastes
+background context with no operative intent, or asks a one-off question) →
+this is not a guide; answer normally, do not create a file.
+
+Never manufacture a guide from model knowledge. If the user asks for "a guide
+on X" without handing over source material, ask for the source first — a
+guide with no `distilled_from` is not this pipeline's output.
+
+## 2. Pipeline
+
+0. **Search before creating (DRY — one CURRENT guide per topic).** Before
+   proposing anything, read `ai_docs/reference/INDEX.md` and grep
+   `reference/GUIDE_*.md` for topic overlap with the new material. Never end
+   up with two CURRENT guides on the same topic. On overlap, pick by
+   provenance:
+   - **Same source, evolved** → UPDATE the existing guide in place: new
+     snapshot, new `source_hash`, same file (history lives in git).
+   - **Different source replacing the old one** → NEW guide + mark the old
+     one `status: SUPERSEDED` (its provenance chain must stay honest — do not
+     graft a new source onto a guide distilled from another).
+   - **Different source, partial overlap** → flag it to the user explicitly:
+     the current frontmatter binds ONE source per guide (`distilled_from`/
+     `source_hash` are singular), so a clean multi-source merge is not yet
+     supported — regenerate from the prevailing source and mark what the
+     merge drops, or keep the topics separate if they truly are.
+   Semantic overlap is NOT mechanically detectable: this step is agent
+   discipline plus the human reviewing the router — say what you found.
+   **Also verify the handed SOURCE itself is current**: check its lifecycle
+   (status/supersedes headers) and search the project for a newer version of
+   the same document before snapshotting. A user may hand you a path that a
+   migrated copy has since superseded — distilling from it produces a guide
+   that is born stale. If you find a newer version, surface it and distill
+   from that one. (Learned the hard way on first field use, 2026-07-02.)
+1. **Decompose into PREPARATION units — and weigh the fragmentation risk.**
+   A guide's goal is to PREPARE an agent for a situation: everything that
+   situation needs must arrive in ONE guide. The risk is asymmetric — extra
+   context injected costs tokens (cheap, recoverable); missing context makes
+   the agent invent or fail (the exact failure this pipeline exists to
+   prevent). Every split is a bet that no future task will cross the cut.
+   Therefore:
+   - **Default = one guide per source/domain.** Split ONLY when the resulting
+     guides would be consulted in DISJOINT situations — no plausible task
+     needs two of them at once.
+   - **Run the split test per proposed fragment and DECLARE it** in the
+     proposal: "which tasks consult this fragment, and would any of those
+     tasks also need another fragment?" Any overlap → merge, do not split.
+   - Heterogeneous sources (unrelated policies handed over together) are the
+     legitimate split case; a single coherent document about one subsystem
+     almost never is.
+2. **User confirms** the topic decomposition — including the declared
+   fragmentation-risk assessment — before any file is written.
+3. **Snapshot each source verbatim** into
+   `ai_docs/reference/.sources/<slug>-<hash8>.md`:
+   - `slug` derives from the topic (lowercase, hyphenated).
+   - `hash8` = first 8 hex chars of the snapshot file's own SHA-256 (compute
+     the snapshot first, hash it, then name it — the hash is of the file you
+     just wrote, not of the original source).
+   - The snapshot is verbatim: no paraphrasing, no reformatting beyond what is
+     needed to save it as markdown.
+4. **Source-anchored SYNTHESIS (not restatement).** Select and compress what
+   the source says into the operative essence — decision rules, invariants,
+   the "where people go wrong" list — and POINT INTO the snapshot for the
+   detail (`[source: <snapshot>#anchor]` doubles as the detail-lookup
+   pointer: "full checklist → snapshot §7"). Every claim must still trace to
+   a specific point in the snapshot; do not extract from memory of the
+   conversation — re-read the snapshot while writing each section. Selection
+   and compression are allowed and expected; ADDITION is not (that stays
+   summarize-and-expand, forbidden). A guide approaching the source's own
+   length is a paraphrase, not a synthesis — wrong output.
+5. **Render per template** (`templates.md` → `## ai_docs/reference/GUIDE_[topic].md`):
+   frontmatter with `source`, `distilled_from`, `source_hash` (the snapshot's
+   SHA-256, matching what you just computed), optional `source_version`; body
+   sections chosen from the repertoire, each with a fidelity marker.
+   **Write for the two-level read**: the guide (synthesis) is small enough to
+   be read WHOLE before acting; the snapshot (book) is where size lives and
+   where readers grep/partial-read on demand, following the section markers.
+   Use the repertoire's stable, self-describing headings, keep one concern per
+   `##` section, and make the frontmatter `description` the "should I open
+   this file at all" answer. This is why one synthesis + one book beats
+   several fragments: the synthesis guarantees the whole picture, the book
+   guarantees the details, the markers connect them.
+6. **Run `sdlc_check.py index`** so both `ai_docs/INDEX.md` and
+   `ai_docs/reference/INDEX.md` (the guide router) regenerate.
+
+## 3. Fidelity rules (mandatory, the D5 constraint)
+
+- Only what the source supports goes in the guide. If the source is silent on
+  something a reader might expect, mark the section `[not covered by source]`
+  — never fill the gap from general knowledge.
+- Every `##` section body carries exactly one kind of marker: `[source:
+  <snapshot>#<anchor-or-line>]` for content traceable to the snapshot, or the
+  literal `[not covered by source]` for an acknowledged gap. A section with
+  neither is a validator warning.
+- `summarize-and-expand` is forbidden: do not take a short source note and
+  "helpfully" expand it into a longer procedure using inferred steps. If the
+  source says one sentence, the guide section says that one sentence
+  (source-anchored), not an elaborated version of it.
+- When in doubt about whether something is "supported" by the source, treat it
+  as not covered rather than stretching the marker to fit.
+
+## 4. Ingestion bound (T9)
+
+If a source document exceeds roughly 2000 lines, do not silently truncate or
+skim it. Stop and ask the user to either split it into smaller documents or
+select the specific sections relevant to the guide being built. Silent
+truncation produces a guide that looks complete but is missing unreviewed
+material — worse than asking.
+
+## 5. Review
+
+Before the guide is used operatively for the first time, recommend an
+independent guide-vs-source review (a fresh pass comparing the rendered guide
+against the snapshot, checking every marker) — process control per the
+threat model (P-TM). This is a recommendation to the user, not a hard gate:
+state it explicitly when handing off a newly created guide.
+
+## 6. Maintenance
+
+- **Source changed**: create a new snapshot (new hash), regenerate the guide
+  from it (new `source_hash`), and if the guide is replacing a prior guide
+  rather than updating in place, mark the old one `status: SUPERSEDED`.
+- **`stale` flags hash drift**: `sdlc_check.py stale` (also under `--hybrid`)
+  compares each guide's recorded `source_hash` against the live snapshot file
+  and reports `[stale]` when they diverge — that is the signal to regenerate,
+  not a manual freshness check.