@antoneeo/agentic-sdlc-skill 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.8.1] - 2026-07-02
+### Fixed
+- **Guide freshness hash is now line-ending independent**: `sha256_file` in `sdlc_check.py` normalizes CRLF → LF before hashing. Previously the raw-byte hash made a fresh Windows checkout with `core.autocrlf=true` rewrite `.sources/` snapshots and flag every guide `[stale]` (false positive). Backward compatible: recorded hashes were computed on LF content, and normalization maps CRLF copies back to the same digest. (Edge case: a hash recorded pre-1.8.1 on a snapshot that genuinely contained CRLF bytes will flag `[stale]` once — regenerate the hash.)
+- `guides.md` step 3 now states the hash is computed over LF-normalized content and recommends the `ai_docs/reference/.sources/** -text` `.gitattributes` rule to consumer projects (defense in depth: keeps snapshots byte-verbatim).
+
+### Test battery addition
+- Scenario 10 (extends the unit-1 battery): snapshot checked out with CRLF endings + guide recording the LF-normalized hash → `stale` must NOT flag it; a genuine content edit must still flag `[stale]`.
+
+## [1.8.0] - 2026-07-02 (Feature B unit 1: operative guides, project scope)
+### Added
+- **Operative guides** (`ai_docs/reference/GUIDE_[topic].md`): a durable, source-faithful layer distilled from USER-PROVIDED indications — the capability neither agentic-sdlc nor superpowers had. New support file `guides.md` (pipeline: topic decomposition → user confirmation → verbatim snapshot in `reference/.sources/` with SHA-256 → source-anchored extraction → per-section fidelity markers `[source: …]` / `[not covered by source]`); guide template with provenance frontmatter (`source`, `source_version`, `distilled_from`, `source_hash`) in `templates.md`; short "Operative Guides" section in `SKILL.md`.
+- **Generated guide router** `ai_docs/reference/INDEX.md` (emitted by `sdlc_check.py index`, alignment-checked by `validate`): path, status, when-to-consult line and provenance summary per guide — the pointer target for the devPNT Hybrid bridge.
+- **Mechanical fidelity controls** in `sdlc_check.py`: provenance-key and per-section marker checks (warn; fails CI under `--strict`); `distilled_from` path confinement — absolute paths, `..` and symlink escapes rejected, fail-closed (ERROR); guide freshness in `stale` — recorded `source_hash` vs current snapshot, flagged in EVERY mode including `--hybrid` (guides are filesystem-first even in Hybrid).
+
+### Changed
+- `stale --hybrid` no longer returns unconditionally 0: it still skips audit-plan staleness (delegated to devPNT/KL) but now checks guide-source drift.
+- `list_canonical_docs` skips dot-subdirectories of canonical dirs (e.g. `reference/.sources/`): snapshot files are no longer swept into the manifest. Projects that kept `.md` files under dot-subdirs of canonical dirs will see them leave `INDEX.md` (more correct).
+
+### Process note
+- First live run of **model-per-dispatch**: implementation dispatched to an economy-tier subagent working from the accepted E-TDD shadow as a self-contained brief; independent deep code review passed first round with zero blocking findings. Governance: M-VISION → D-UC → P-TM → E-ISP → E-TDD, all through independent review gates (devPNT Hybrid).
+
 ## [1.7.0] - 2026-07-02 (Phases 0-1 of the evolution roadmap)
 ### Changed (breaking-soft)
 - **English is now the canonical language of the skill**: `SKILL.md`, `templates.md`, `ENFORCEMENT.md`, validator messages, generated indexes and the project protocol are in English. New ANALYSIS documents use English frontmatter keys (`status`, `level`, `start_date`, `end_date`) and English section headings. **Existing projects keep working**: the validator silently accepts the deprecated Italian keys (`stato`, `livello`, `data_inizio`, `data_fine`) and Italian headings.

package/README.md

@@ -1,81 +1,82 @@
-# 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
-
-- **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.
+# 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
+
+- **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`, `guides.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
+├── guides.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.7.0",
+  "version": "1.8.1",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",
@@ -27,6 +27,7 @@
   "files": [
     "skills/agentic-sdlc-skill/SKILL.md",
     "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/guides.md",
     "skills/agentic-sdlc-skill/ENFORCEMENT.md",
     "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
     "gemini-extension.json",

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

@@ -11,6 +11,7 @@ This skill guides software development with a Documentation-First process propor
 
 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.
 
@@ -144,9 +145,10 @@ IN_PROGRESS, or vice versa. They move in the same closure step.
 
 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); `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.
+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
 
@@ -205,6 +207,7 @@ Hybrid L3:
   - 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.
@@ -234,6 +237,22 @@ Without Python/hooks (minimal environments) the indexes and headers remain a pro
 
 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:

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

@@ -0,0 +1,160 @@
+# 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 hash is computed over LF-normalized content (CRLF → LF), exactly as
+     `sdlc_check.py` does in `sha256_file` — so recorded hashes survive
+     checkouts that rewrite line endings (e.g. Windows `core.autocrlf=true`).
+   - Recommended for consumer projects: add
+     `ai_docs/reference/.sources/** -text` to `.gitattributes` so git never
+     rewrites snapshot bytes at all (keeps snapshots byte-verbatim; the
+     normalized hash stays stable either way).
+   - 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.

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

@@ -23,6 +23,7 @@ but are deprecated: new documents should use the English forms.
 Standard library only (Python >= 3.8). Windows and POSIX compatible.
 """
 import argparse
+import hashlib
 import json
 import os
 import re
@@ -49,6 +50,11 @@ CANONICAL_STATES = {"CURRENT", "SUPERSEDED", "DRAFT", "DEPRECATED",
                     "APPROVED", "ACCEPTED", "PROPOSED", "REJECTED"}
 GENERATED_DOCS = {"features_history.md", "INDEX.md"}  # generated: never manifest entries
 MTIME_GRACE = timedelta(seconds=2)
+GUIDE_INDEX_HEADER = ("<!-- GENERATED by sdlc_check.py index - do not edit by hand. "
+                      "Source of truth: the headers of the GUIDE_*.md files in ai_docs/reference/. -->")
+GUIDE_PROVENANCE_KEYS = ("source", "distilled_from", "source_hash")  # source_version optional
+# a guide section is "covered" when it carries a source marker or an explicit gap marker
+GUIDE_MARKER_RE = re.compile(r"\[(?:source:[^\]]+|not covered by source)\]")
 
 # Deprecated Italian frontmatter keys, mapped to the canonical English ones.
 LEGACY_KEYS = {"stato": "status", "livello": "level",
@@ -102,6 +108,16 @@ def read_text(path):
     return path.read_text(encoding="utf-8-sig", errors="replace")
 
 
+def sha256_file(path):
+    # CRLF->LF before hashing: a Windows checkout with core.autocrlf=true
+    # rewrites snapshot files, and a raw-byte hash would flag every guide
+    # [stale] on a fresh clone. Recorded hashes are LF-based, so normalizing
+    # maps CRLF copies back to the same digest.
+    h = hashlib.sha256()
+    h.update(path.read_bytes().replace(b"\r\n", b"\n"))
+    return h.hexdigest()
+
+
 def parse_iso(value):
     if not value:
         return None
@@ -325,6 +341,9 @@ def list_canonical_docs(root):
         if not base.is_dir():
             continue
         for p in sorted(base.rglob("*.md")):
+            rel_parts = p.relative_to(base).parts
+            if any(part.startswith(".") for part in rel_parts[:-1]):
+                continue  # dot-subdirs (e.g. reference/.sources/) are never canonical
             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)))
@@ -355,6 +374,37 @@ def build_manifest(root):
     return "\n".join(lines).rstrip() + "\n"
 
 
+def list_guides(root):
+    """[(rel_to_ai_docs, path, meta, text)] for ai_docs/reference/GUIDE_*.md."""
+    ref = root / "ai_docs" / "reference"
+    out = []
+    if not ref.is_dir():
+        return out
+    for p in sorted(ref.glob("GUIDE_*.md")):
+        text = read_text(p)
+        out.append((p.relative_to(root / "ai_docs").as_posix(), p,
+                    load_frontmatter(text.splitlines()), text))
+    return out
+
+
+def build_guide_index(root):
+    lines = [GUIDE_INDEX_HEADER,
+             "# Operative guides (generated router)",
+             "",
+             "One row per guide. `description` is the when-to-consult line; provenance",
+             "shows what the guide was distilled from. Freshness: run `sdlc_check.py stale`.",
+             "",
+             "| Guide | Status | When to consult | Source | Source version |",
+             "|---|---|---|---|---|"]
+    for rel, p, meta, _ in list_guides(root):
+        lines.append("| `{}` | {} | {} | {} | {} |".format(
+            p.name, meta.get("status", "-") or "-",
+            (meta.get("description", "") or "-").replace("|", "\\|"),
+            (meta.get("source", "") or "-").replace("|", "\\|"),
+            meta.get("source_version", "") or "-"))
+    return "\n".join(lines) + "\n"
+
+
 def cmd_index(root):
     if not require_ai_docs(root, "index"):
         return 1
@@ -369,6 +419,13 @@ def cmd_index(root):
         print(f"[ok] document manifest regenerated: {manifest}")
     else:
         print("[info] no canonical documents: INDEX.md not generated")
+    guides = list_guides(root)
+    gidx = root / "ai_docs" / "reference" / "INDEX.md"
+    if guides:
+        gidx.write_text(build_guide_index(root), encoding="utf-8")
+        print(f"[ok] guide router regenerated: {gidx}")
+    elif gidx.is_file():
+        print(f"[warn]  {gidx} exists but no GUIDE_*.md found: stale router, remove or add guides")
     return 0
 
 
@@ -464,6 +521,38 @@ def cmd_validate(root, strict=False):
                         or os.path.basename(other) == base) and ost == "CURRENT":
                     warnings.append(f"{other}: still CURRENT but superseded by {rel} (set status: SUPERSEDED)")
 
+    # Guide checks (ai_docs/reference/GUIDE_*.md): structure only — freshness is stale's job
+    guides = list_guides(root)
+    for rel, p, meta, text in guides:
+        missing = [k for k in GUIDE_PROVENANCE_KEYS if not meta.get(k)]
+        if missing:
+            warnings.append(f"{rel}: guide missing provenance key(s): {', '.join(missing)}")
+        # (b) per-section fidelity markers: every '## ' section body must carry a marker
+        body = text.split("---", 2)[-1]
+        sections = re.split(r"^##\s+", body, flags=re.M)[1:]
+        unmarked = [s.splitlines()[0].strip() for s in sections if not GUIDE_MARKER_RE.search(s)]
+        if unmarked:
+            warnings.append(f"{rel}: section(s) without [source: ...] / [not covered by source] marker: "
+                            + "; ".join(unmarked[:5]))
+        # (c) distilled_from confinement — fail closed (P-TM T6, distilled_from vector)
+        df = meta.get("distilled_from", "")
+        if df:
+            if Path(df).is_absolute() or ".." in Path(df).parts:
+                errors.append(f"{rel}: distilled_from '{df}' is absolute or escapes the project (..): rejected")
+            else:
+                target = (root / df).resolve()
+                try:
+                    target.relative_to(root.resolve())
+                except ValueError:
+                    errors.append(f"{rel}: distilled_from '{df}' resolves outside the project root: rejected")
+    # guide-router alignment (mirror of the root-manifest check)
+    gidx = root / "ai_docs" / "reference" / "INDEX.md"
+    if guides:
+        if not gidx.is_file():
+            errors.append("ai_docs/reference/INDEX.md missing: run 'sdlc_check.py index'")
+        elif norm_text(read_text(gidx)) != norm_text(build_guide_index(root)):
+            errors.append("ai_docs/reference/INDEX.md not aligned with the guides: run 'sdlc_check.py index'")
+
     # Handoff: header and freshness
     hand = ai / "audit" / "handoff.md"
     if hand.is_file():
@@ -515,14 +604,33 @@ def parse_audit_plan(root):
 
 
 def cmd_stale(root, hybrid=False):
+    rc = 0
+    # --- guide freshness (source_hash vs snapshot) — runs in EVERY mode
+    drifted = []
+    for rel, p, meta, _ in list_guides(root):
+        df, rec = meta.get("distilled_from", ""), meta.get("source_hash", "")
+        if not df or not rec:
+            continue  # structure problems are validate's job
+        src = root / df
+        if not src.is_file():
+            print(f"[warn]  {rel}: distilled_from '{df}' not found — snapshot missing")
+            rc = 1
+            continue
+        if sha256_file(src) != rec:
+            drifted.append((rel, df))
+    for rel, df in drifted:
+        print(f"[stale] {rel}: source snapshot '{df}' changed since distillation — regenerate the guide")
+    if drifted:
+        rc = 1
+    # --- audit-plan staleness — delegated to devPNT/KL in hybrid
     if hybrid:
         print("[info] hybrid mode: audit-plan staleness is delegated to devPNT/KL, skipping.")
-        return 0
+        return rc                                  # was: implicit skip-all; guide rc survives
     f, _, rows = parse_audit_plan(root)
     if not rows:
         print(f"[info] no rows in {f}: nothing to check "
               "(audit not initialized, or Hybrid mode where mapping is delegated to devPNT).")
-        return 0
+        return rc                                  # was: return 0 — MUST carry guide rc
     use_git = git_available(root)
     stale = []
     for row in rows:
@@ -554,7 +662,7 @@ def cmd_stale(root, hybrid=False):
 
     if not stale:
         print("[ok] no analyzed area was modified after its last recorded analysis.")
-        return 0
+        return rc                                  # was: return 0 — MUST carry guide rc
     print("Areas modified after the last recorded analysis:")
     for rel, changed in stale:
         print(f"  {rel}  ({len(changed)} files)")
@@ -563,7 +671,7 @@ def cmd_stale(root, hybrid=False):
         if len(changed) > 10:
             print(f"    ... and {len(changed) - 10} more")
     print("\nAfter re-analyzing, record it with: sdlc_check.py mark <path>")
-    return 1
+    return 1                                       # stale areas dominate: rc already implied
 
 
 def cmd_mark(root, paths):

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

@@ -20,6 +20,44 @@ supersedes: old_doc.md       # only if it replaces another canonical doc
 
 When a doc replaces another: the new one declares `supersedes:`, the old one switches to `status: SUPERSEDED` (it stays as history, do not delete it). `sdlc_check.py validate` warns if `status` is missing or if a superseded doc is still `CURRENT`.
 
+## ai_docs/reference/GUIDE_[topic].md
+
+Operative guide distilled from USER-PROVIDED indications (never from model knowledge).
+The guide is a SYNTHESIS — the compact training a reader takes in whole before acting;
+the verbatim snapshot in `ai_docs/reference/.sources/<slug>-<hash8>.md` is the book,
+reached on demand. `source_hash` is the snapshot's SHA-256. Every `##` section carries
+a fidelity marker: `[source: <snapshot-file>#<anchor-or-line>]` for covered content
+(doubling as the detail-lookup pointer into the book), or a literal
+`[not covered by source]` for gaps. Sections are CHOSEN from the repertoire below —
+only those the source actually supports; never force empty ones. A guide approaching
+the source's own length is a paraphrase, not a synthesis.
+
+```markdown
+---
+description: One line, ≤160 chars — when to consult this guide.
+status: CURRENT
+source: Human-readable name of what the user provided.
+source_version: v1.2          # optional — only when the origin is versioned
+distilled_from: ai_docs/reference/.sources/topic-a1b2c3d4.md
+source_hash: <sha256 of the snapshot file>
+---
+# Guide: [Topic]
+
+## How to do [X]
+[source: topic-a1b2c3d4.md#setup]
+<!-- operative steps, imperative voice -->
+
+## How to verify it is done right
+[source: topic-a1b2c3d4.md#checks]
+
+## What NOT to do
+[not covered by source]
+<!-- the user's material does not address this: do not invent. -->
+```
+
+Section repertoire (pick what the source supports): How to do X / How to verify /
+What NOT to do / What to watch out for / Core principles / When this applies.
+
 ## ai_docs/README.md
 
 Curated must-read index, by hand (it is NOT the generated manifest). Created at init, updated rarely, only for real must-reads.