@antoneeo/agentic-sdlc-skill 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.15.0] - 2026-07-19 (Write Triggers + Code-Comprehension Guides)
+### Added
+- **Code-comprehension guides (`source_kind: code`)** — a new guide kind the agent writes **autonomously** (a duty, no proposal) when it recognizes a high-complexity component / feature / abstraction layer with no CURRENT guide: a source-faithful map of how the thing works, so the next session starts with the model instead of re-deriving it and breaking the component from partial understanding. Reuses the ENTIRE guide machinery (snapshot + `source_hash` + `stale` + router + fidelity markers) — the source is verbatim CODE EXCERPTS in `.sources/` instead of a handed document; `sdlc_check.py` is unchanged. The skill-wide "propose, never a silent write" rule is relaxed for THIS kind only (additive, code-anchored, reversible); the anti-hallucination floor holds — every claim traces to a code excerpt. Triggered by concrete signals (high comprehension cost, high fan-in, non-obvious flow, prior / repeated-across-sessions breakage from partial understanding, non-local rationale) and by **chronic fragility** (a component breaking repeatedly across sessions → write the guide AND escalate a refactor as its own L3; stop patching). Touches `guides.md` §1–§6, `SKILL.md` (4th "Comprehend" moment + Write-Triggers `code` row + consult wording), `templates.md` (`source_kind` + comprehension repertoire), `debugging.md` (capture-the-model + chronic-fragility). Positioned under Vision **Layer A** (Documentation-First lifecycle applied to code understanding), distinct from Layer D's user-indication operative guides.
+- **`SKILL.md` §Write Triggers** — a mechanical document→trigger→phase table, symmetric to Rule Zero: triage decides IF documentation is due, this table decides WHICH document each event produces. One event, one destination; create-or-update, never duplicate. It is the authoritative write index; the workflow phases point to it.
+
+### Changed
+- **Bootstrap set made explicit (Phase 1)** — the named doc set (`README.md`, the three Vision docs as DRAFT, `strategic/architecture.md`, `strategic/existing_features.md`, Standalone `audit/audit_plan.md`, then regenerate `INDEX.md`) replaces the vague "minimal documents".
+- **`handoff.md` write trigger + session-end rule** — mandatory at every L3 closure, and when a session ends with an ANALYSIS still IN_PROGRESS; the Phase-4 Diary trigger now names "session ends with work unfinished". Mirrored in `templates.md`.
+- **`VISION_[feature].md` retroactive trigger** — fires when creating the SECOND `ANALYSIS_*` on the same theme (no foresight required).
+- **ADR trigger unified** across Standalone (`architecture/`) and Hybrid (devPNT DB); no decision, no ADR.
+- **`features_history.md` regime** pinned to `sdlc_check.py index` (prose discipline only without Python).
+- **"Understand before acting"** now names cross-session source-memory rot — re-read a component you think you remember; trust the code (and its comprehension guide), not memory.
+- **SKILL.md thesis line** — the skill's one-line "why": prevent *myopia* (acting from partial understanding).
+- **Blast-radius enumeration is an authoring duty (Phase 3)** — mechanically enumerate every consumer of a signature-changed / multi-caller symbol up front with the symbol-graph, not as a review finding; `debugging.md` root-cause traces callers the same way (not text search).
+
+### Process note
+Doc-only: no `sdlc_check.py` or packaging change; validator behavior untouched (the packaged file allowlist is unchanged). Standalone L3 (devPNT off this session — locked on another project). Governed by `ai_docs/solutions/ANALYSIS_comprehension_guides.md` (F-015), Vision decision **B** (comprehension homed under Layer A, Layer D's differentiator untouched). Validated by TWO independent blind comprehension tests (fresh agent, skill-only, no hints): the new trigger is discoverable + correct, and the adversarial (refuses a general-knowledge guide) and autonomy-boundary (the autonomy relaxation does not leak to refactors or operative guides) probes pass; 6 findings surfaced across the two rounds and all fixed. Eval battery 52/52 green; `validate` 0 errors.
+
 ## [1.14.0] - 2026-07-08 (M6: Vision Actors — a characterized cast in the Vision)
 ### Changed
 - **Vision defines Actors.** The Vision templates replace the flat `## Target Users` / `## Users or Stakeholders` with a first-class `## Actors` element: one light line per actor — **Role** — primary goal; good UX = what a good experience means to them. An Actor is defined ONCE in the Vision (project or feature) and REFERENCED by each use-case / `D-UC` (actor = who they are, use-case = what they do) — anti-DRY, and enough to design the intended UX for concrete roles instead of an implicit "user". A feature may declare its own feature-local cast for internal-tooling work.

package/README.md

@@ -4,10 +4,10 @@
 
 ## Key Features
 
-- **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work.
+- **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work, with a symmetric **Write Triggers** table mapping each event to the document it produces (one event, one destination).
 - **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. The Vision names its **Actors** — the cast a feature serves, one light line each — so UX is designed for concrete roles, not an implicit "user".
 - **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), systematic debugging, an L3 spec-elicitation round, and a single code-review definition wired into the workflow phases.
-- **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `ai_docs/reference/GUIDE_*.md` — consulted before operative work, proposed after reusable work — shared cross-project via `~/.agentic-sdlc`.
+- **Operative + comprehension guides + agent-global KB**: distil user-provided indications into source-faithful operative `GUIDE_*.md` (`source_kind: document`), and let the agent autonomously author **code-comprehension guides** (`source_kind: code`) for complex components — a source-faithful mental-model map that survives across sessions, so the next session doesn't re-derive and break the component from partial understanding. Consulted before work; shared cross-project via `~/.agentic-sdlc`.
 - **Opt-in subagent execution**: an approved design projects into a validated executable plan an orchestrator can drive through subagents.
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "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.14.0",
+  "version": "1.15.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",

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

@@ -7,6 +7,8 @@ copyright: (c) 2026 Antonio Pinto
 
 # Agentic SDLC
 
+**Why this skill exists:** to prevent *myopia* — acting from partial understanding, where a change breaks what it did not account for and hard-won knowledge evaporates between sessions. Triage, the Vision Gate, the documentation lifecycle and comprehension guides are all one defense against that.
+
 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:
@@ -19,7 +21,7 @@ Read these files only when needed. `SKILL.md` is the operating contract; the sup
 
 ## Technical Values
 
-- **Understand before acting:** do not modify code without understanding root cause, constraints and current shape.
+- **Understand before acting:** do not modify code without understanding root cause, constraints and current shape — including re-reading a component you think you remember, because your model of it rots between sessions; trust the code (and its comprehension guide), not memory.
 - **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.
@@ -36,7 +38,7 @@ Always classify the request before choosing the process. Declare the chosen leve
 | 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. |
+| **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 on the same topic, or the handoff (see Write Triggers). |
 | **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. |
 
@@ -46,6 +48,24 @@ Cross-cutting rules:
 - When in doubt, pick the higher level.
 - The full audit does not start for L1/L2 unless explicitly requested.
 
+## Write Triggers
+
+Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it. This table is the authoritative write index — the workflow phases carry the surrounding procedure and point here for the trigger.
+
+| Document | Write trigger | Phase |
+|---|---|---|
+| `solutions/ANALYSIS_[feature].md` | Every L3, after elicitation and before any code. On topic match with an existing analysis, update that one instead of a new file. | 3 |
+| `solutions/SPIKE_[topic].md` | Closing any Spike — including a failed one (a negative outcome is still an outcome). | — |
+| `vision/features/VISION_[feature].md` | Feature known multi-milestone at analysis time, OR the retroactive trigger: you are about to create the SECOND `ANALYSIS_*` on the same theme — extract the shared feature vision first, then let both analyses reference it. | 3 |
+| `audit/handoff.md` | Mandatory at every L3 closure, and at session end when an ANALYSIS is still IN_PROGRESS (even without closure); discretionary after an L2 when useful. Refresh Date / Branch / active features / next step; ≤ 20 lines. | 5 / session end |
+| `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark` records the reference — git hash, else UTC timestamp). | 1 |
+| `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. Propose, never a silent write, never from model knowledge. | 4 / 5 |
+| `reference/GUIDE_[topic].md` (`source_kind: code`) | Recognized high-complexity component/feature/layer with no CURRENT guide — including one that breaks repeatedly across sessions → **duty to write autonomously** (no proposal; additive, code-anchored, reversible). Fidelity floor: every claim traces to a code excerpt. Signals + guard-rails: `guides.md` §1. | any |
+| ADR — `architecture/` (Standalone) or devPNT DB (Hybrid) | An architectural decision was taken (new pattern, layer or contract change, structural dependency): record it at closure, before DONE. No decision, no ADR. | 5 |
+| `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the stack or the feature catalog actually changed. | 1 / 5 |
+| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap, as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
+| `INDEX.md`, `reference/INDEX.md`, `strategic/features_history.md` | Never by hand: regenerated by `sdlc_check.py index` at closure when canonical docs or guides changed (prose discipline where the validator is not adopted). | 5 |
+
 ## Operating Modes
 
 ### Full Standalone
@@ -56,7 +76,7 @@ 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.
+- Feature history: `ai_docs/strategic/features_history.md` — generated by `sdlc_check.py index` (kept by hand as a prose discipline only in environments without Python).
 
 Standalone mode is not reduced: it must handle audits, features, significant bugs, tests, handoffs and closure without devPNT.
 
@@ -157,7 +177,7 @@ gate) instead of requiring an IN_PROGRESS ANALYSIS.
 - 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.
 - Optional: a SessionStart hook (`ENFORCEMENT.md` §4) can emit this orientation automatically at session start (README + INDEX + guide router + handoff + triage reminder); when it is not wired, do these reads manually as above. The hook is a convenience, never a requirement — it introduces no Python dependency for the process itself and fails open (a missing/empty `ai_docs/` never blocks the session).
-- If `ai_docs/` is missing or incomplete, create the structure and minimal documents by analyzing the project in batches.
+- If `ai_docs/` is missing or incomplete, create the structure and the **bootstrap set** by analyzing the project in batches: `README.md`, the three `vision/` docs (`Status: DRAFT`), `strategic/architecture.md`, `strategic/existing_features.md` and — Standalone — `audit/audit_plan.md`; then regenerate `INDEX.md`. Nothing else is mandatory at bootstrap (per-document triggers: Write Triggers).
 - 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`.
@@ -179,12 +199,14 @@ Hybrid:
 
 For any L3, run the spec elicitation round in `elicitation.md` BEFORE drafting the analysis (skip path inside — one-line note when the spec is already complete).
 
+**Blast-radius enumeration is an authoring duty, not a review finding.** Before writing the Impact (the list of what changes), for every symbol whose signature you change, thread a new field through, or that has more than one caller: mechanically enumerate EVERY consumer with the best symbol-graph tool your toolchain offers — an LSP/IDE call hierarchy or a find-usages / call-graph capability — with `grep` only as a last-resort fallback, and list the full set in the Impact. Anchor to symbol identity, not line numbers (they rot). This is deterministic and cheap: doing it up-front collapses the review into one pass, instead of the reviewer returning "you missed a consumer" one round at a time. Leaving completeness to the closure review is the myopia failure this whole workflow exists to prevent.
+
 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.
 - Build the Impact/solution **on** the Vision, the use-cases/user-needs and the Security & Threat Model — read and trace to them first, and state the trace (which actor / use-case / threat / benefit each part serves) so the closure review (`review.md`) can verify conformance. Do not draft the Impact in isolation.
-- For features spanning multiple milestones or multiple analyses, also create `ai_docs/vision/features/VISION_[feature].md`.
+- For a feature known to span multiple milestones, also create `ai_docs/vision/features/VISION_[feature].md`; the retroactive case (extract it when the SECOND `ANALYSIS_*` on a theme appears) is in Write Triggers.
 
 Hybrid L3:
 - Restore the Master Plan, Action Plan and linked documents.
@@ -197,11 +219,11 @@ Hybrid L3:
 - Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree.
 - Modify surgically, consistently with the plan.
 - Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).
-- Before implementing (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first — the consult trigger (`guides.md` §0, summarized under `## Operative Guides`). A targeted description match, not a blanket read.
+- Before implementing (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task — operative, or a comprehension map of the component you are about to touch — and read it first (the consult trigger, `guides.md` §0, summarized under `## Operative Guides`). A targeted description match, not a blanket read.
 - If the environment does not allow automated tests, declare the alternative verification and the reason.
 - For bugs (L2/L3), follow the systematic debugging method in `debugging.md`.
-- Circuit breaker: after 3 consecutive runs without progress on the tests, stop, switch to the systematic method in `debugging.md`, and ask for instructions if still stuck.
-- Update the ANALYSIS Diary or the Action Plan when you complete milestones, hit blockers or change decisions.
+- Circuit breaker: after 3 consecutive runs without progress on the tests, stop, switch to the systematic method in `debugging.md`, and ask for instructions if still stuck. `debugging.md` also covers **chronic fragility** — a component that breaks repeatedly across sessions is a comprehension + complexity signal (write the `source_kind: code` guide AND escalate a refactor), not a fourth patch.
+- Update the ANALYSIS Diary or the Action Plan when you complete milestones, hit blockers, change decisions, or a session ends with work unfinished.
 - **Opt-in subagent execution**: for an L3 with an approved design, the orchestrator MAY execute the work via subagents per `dispatch.md`, gated by `sdlc_check.py plan validate` ("no valid plan, no dispatch"); default stays same-session. Hybrid: the executable `PLAN_[feature].md` is `derived-from` the accepted E-TDD, never independently authored.
 
 ### 5. Closure
@@ -211,6 +233,7 @@ Hybrid L3:
 - Verify alignment with the local Vision or the devPNT M-VISION.
 - If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
 - Update only the documents actually impacted.
+- **Update `audit/handoff.md`** — mandatory at every L3 closure (Date, Branch, active features, next step; ≤ 20 lines). The session-end rule and the L2 case: Write Triggers.
 - **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`;
@@ -218,7 +241,7 @@ Hybrid L3:
   - 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.
+- If an architectural decision was taken (new pattern, layer or contract change, structural dependency), record an ADR before DONE — Standalone in `architecture/`, Hybrid propose the ADR/KL update in the devPNT DB. No decision, no ADR (Write Triggers).
 - 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.
 - **Branch/worktree hygiene**: an L3 ran on its own branch (Phase 4) — close it with an explicit merge decision (merge, keep open, or discard) and clean up the branch/worktree; never leave orphan branches. In Hybrid, the running devPNT server locks `.devpnt/*.db`, so the merge is done from a separate git worktree or via a ref-only push, never an in-place branch switch in the primary worktree.
@@ -250,10 +273,11 @@ Legacy note: the validator also accepts the deprecated Italian frontmatter keys
 
 ## Operative Guides
 
-Guides are **consulted, created, and proposed** — three moments; the mechanics live once in `guides.md`:
+Guides are **consulted, created, proposed, and (for code) authored for comprehension** — four moments; the mechanics live once in `guides.md`. Two source kinds: `document` (user indications, operative) and `code` (a comprehension map of a complex component):
 - **Consult (before acting):** before operative L2/L3 work (L1 exempt), check the guide router for a guide covering the task and read the match first — a targeted description match, never a blanket read. → `guides.md` §0.
-- **Create (from user indications):** the origin+purpose test below.
+- **Create (from user indications):** the origin+purpose test below (`source_kind: document`).
 - **Propose proactively (after success):** after reusable, user-indication-governed work, PROPOSE distilling a guide — a proposal, never a silent write, never from model knowledge. → `guides.md` §1.
+- **Comprehend (code, autonomous):** when a component/feature/layer is high-complexity and no CURRENT guide covers it, it is your DUTY to WRITE a `source_kind: code` comprehension guide autonomously — no proposal (additive, code-anchored, reversible); every claim traces to a code excerpt. Signals + guard-rails: `guides.md` §1.
 
 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

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

@@ -16,7 +16,11 @@ mechanism.
    unrelated setup, unrelated data, unrelated code paths. Bisect (recent
    commits, code paths, input ranges) when the boundary is unclear.
 3. **Root cause — name the mechanism.** State in one sentence why the
-   observed behavior happens, tracing the actual execution path. **MUST NOT
+   observed behavior happens, tracing the actual execution path. Trace it by
+   enumerating the real callers/consumers of each suspect symbol with the best
+   symbol-graph tool your toolchain offers — an IDE/LSP call hierarchy or a
+   find-usages / call-graph capability — not text search; `grep`
+   under-enumerates and hides the very consumer that breaks. **MUST NOT
    patch a symptom without naming the mechanism; why: symptom patches recur
    and stack** — the same underlying defect resurfaces elsewhere, and each
    unexplained patch makes the next investigation harder, not easier.
@@ -25,7 +29,24 @@ mechanism.
    before applying the fix, or by temporarily reverting it) and passes after.
    A regression test that was never confirmed to fail proves nothing.
 6. **Run the relevant suite for collateral.** A root-cause fix can change
-   behavior other callers depend on; check them before closing.
+   behavior other callers depend on; enumerate those callers with the
+   symbol-graph (step 3), not from memory, and check them before closing.
+
+**Capture the model you had to rebuild.** If naming the mechanism (step 3) forced
+you to reconstruct the mental model of a complex component that no guide documents —
+tracing it across files because it was written down nowhere — that is the
+comprehension trigger (`guides.md` §1): it is your duty to write the `source_kind:
+code` guide, so the next debugger starts with the map you just paid to build.
+
+**Chronic fragility is a signal, not a task to grind.** If a component breaks
+*repeatedly across sessions* and its complexity is no longer under control, stop
+treating each break as an isolated bug — that pattern has two duties, not one:
+1. **Understand** — write the `source_kind: code` comprehension guide (above) so the
+   understanding stops evaporating between sessions.
+2. **Escalate the complexity itself** — STOP stacking patches on a component nobody
+   fully understands. Flag the fragility as tech debt and propose a dedicated
+   **refactor as its own L3** (Vision-gated), instead of a fourth fix. Continuing to
+   patch a component you keep breaking is the anti-pattern, not the fix.
 
 ## Circuit breaker integration
 

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

@@ -17,6 +17,14 @@ when a task needs detail. Two levels, both produced by this pipeline:
 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.
 
+**Two source kinds.** A guide's `source_kind` is either `document` (the default —
+distilled from USER-PROVIDED indications; operative, "how to act") or `code`
+(distilled from the project's own code; a comprehension map of a complex component,
+"how it works"). Both are **source-faithful and snapshot-anchored** — the machinery
+below (snapshot, `source_hash`, fidelity markers, router, `stale`) is identical; only
+what is gathered into `.sources/` differs (a handed document vs verbatim code
+excerpts). Where a rule applies to only one kind, it says so.
+
 ## 0. Consuming a guide (consult before acting)
 
 Guides only pay off if they reach the work they govern. **Before operative work,
@@ -68,6 +76,34 @@ a guide.
   a guide from general knowledge (the `distilled_from` fidelity constraint, §3,
   is absolute). This adds a moment to PROPOSE, not a new writer.
 
+### Comprehension trigger (code source, autonomous — a duty, not a proposal)
+
+The two triggers above are for `source_kind: document` (the user hands material
+over). There is a third, for `source_kind: code`: while doing L2/L3 work, when you
+recognize that a component / feature / abstraction layer is **high-complexity** and
+no CURRENT guide already covers it, it is your **duty to WRITE a comprehension
+guide** — autonomously, no proposal, no human gate. The next session (or another
+agent) must not have to re-derive the model you just paid to build, and then break
+the component from partial understanding.
+
+- **Why autonomous is allowed here** (it is NOT for `document` guides): a
+  comprehension guide is **additive, code-anchored and reversible** (git). It changes
+  no code, plan or governed artifact — so the skill-wide "propose, never a silent
+  write" rule is relaxed for THIS kind only. The anti-hallucination floor still holds:
+  §3 fidelity is absolute — every claim traces to a verbatim code excerpt in the
+  snapshot, never to your assumption about what the code does.
+- **Recognize "high-complexity" by concrete signals** (any strong combination, not a
+  vibe): you had to trace one behavior across several files/modules (summaries were
+  not enough); high fan-in / large blast radius (many consumers); non-obvious control
+  or data flow (state machine, async/eventing, DI/plugin indirection, metaprogramming,
+  cross-cutting invariants); the area was already broken once — or **repeatedly
+  across sessions** — from partial understanding (handoff / diary / git shows it);
+  the "why" is not reconstructable from a single file.
+- **Guard-rails (autonomous is not unconstrained).** Search first (§2.0 — one CURRENT
+  guide per topic, both routers). Honor the fidelity floor (§3). RECOMMEND the
+  independent guide-vs-source review (§5) — it matters more here, since no human gated
+  creation. Announce the autonomous write in the closure / handoff so it is visible.
+
 ## 2. Pipeline
 
 0. **Search before creating (DRY — one CURRENT guide per topic).** Before
@@ -118,7 +154,10 @@ a guide.
      scope is a LOCATION decision by the user, never a content taxonomy; KB
      created lazily with `.sources/` on the first agent-scope guide).
 2. **User confirms** the topic decomposition — including the fragmentation-risk
-   assessment and scope decision — before any file is written.
+   assessment and scope decision — before any file is written. **`source_kind: code`
+   skips this gate**: the comprehension guide is written autonomously (§1
+   comprehension trigger). Still run the fragmentation/scope judgement yourself — just
+   do not block on confirmation.
 3. **Snapshot each source verbatim** into
    `ai_docs/reference/.sources/<slug>-<hash8>.md`:
    - `slug` derives from the topic (lowercase, hyphenated).
@@ -134,6 +173,13 @@ a guide.
      normalized hash stays stable either way).
    - The snapshot is verbatim: no paraphrasing, no reformatting beyond what is
      needed to save it as markdown.
+   - **For `source_kind: code`** the snapshot is the verbatim CODE EXCERPTS the guide
+     explains — the specific functions / classes / regions of the real files, each
+     labelled with its `path:symbol` (or `path:startLine-endLine`) — assembled into
+     the one `.sources/<slug>-<hash8>.md` and hashed identically. Copy the code
+     verbatim (no paraphrase); include ONLY the regions the guide covers, not whole
+     files, so `stale` tracks the code that matters. `distilled_from` records those
+     code paths.
 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
@@ -145,9 +191,11 @@ a guide.
    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.
+   frontmatter with `source_kind` (`document` | `code`), `source`, `distilled_from`,
+   `source_hash` (the snapshot's SHA-256, matching what you just computed), optional
+   `source_version`; body sections chosen from the repertoire (a `code` guide uses the
+   comprehension repertoire — how it works / control & data flow / invariants / where
+   it breaks), 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.
@@ -161,6 +209,11 @@ a guide.
 
 ## 3. Fidelity rules (mandatory, the D5 constraint)
 
+"The source" below means the SNAPSHOT — a handed document for `source_kind: document`,
+verbatim code excerpts for `source_kind: code`. The constraint is identical for both:
+never from UNVERIFIED knowledge. A code guide's every claim traces to the actual code
+in the snapshot, never to your assumption about what the code does.
+
 - 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.
@@ -200,5 +253,10 @@ state it explicitly when handing off a newly created guide.
   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.
+- **`source_kind: code` freshness**: `stale` works unchanged (the code-excerpt
+  snapshot drifts when the code changes → regenerate). ADDITIONALLY, when you modify
+  the code a comprehension guide describes, refresh that guide in the SAME closure
+  (docs travel with the code) — do not wait for `stale` to catch it. A stale
+  comprehension guide is a confident-wrong map, worse than none.
 - **Agent-global KB guides** use the same pipeline and validator via
   `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.

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

@@ -22,7 +22,10 @@ When a doc replaces another: the new one declares `supersedes:`, the old one swi
 
 ## ai_docs/reference/GUIDE_[topic].md
 
-Operative guide distilled from USER-PROVIDED indications (never from model knowledge).
+A guide is either OPERATIVE (`source_kind: document` — distilled from USER-PROVIDED
+indications, "how to act") or a COMPREHENSION map (`source_kind: code` — distilled from
+the project's own code, "how a complex component works"). Never from model knowledge:
+every claim traces to the snapshot (a handed document, or verbatim code excerpts).
 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
@@ -36,7 +39,8 @@ the source's own length is a paraphrase, not a synthesis.
 ---
 description: One line, ≤160 chars — when to consult this guide.
 status: CURRENT
-source: Human-readable name of what the user provided.
+source_kind: document         # document (user indications, operative) | code (comprehension map)
+source: Human-readable name of what the user provided (or the component, for source_kind: code).
 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>
@@ -56,8 +60,12 @@ overrides: GUIDE_topic.md   # optional — only for a project guide overriding a
 <!-- 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.
+Section repertoire (pick what the source supports):
+- **`document` (operative):** How to do X / How to verify / What NOT to do / What to
+  watch out for / Core principles / When this applies.
+- **`code` (comprehension):** How it works / Control & data flow / Key invariants /
+  Extension points / Where it breaks (failure modes) / Why it is shaped this way.
+  Every marker points into the code-excerpt snapshot: `[source: <slug>-<hash8>.md#path:symbol]`.
 
 ## ai_docs/README.md
 
@@ -273,6 +281,8 @@ States: PENDING (to analyze) | ANALYZED (analyzed, with reference) | SKIPPED (wi
 
 Just a pointer, ≤ 20 lines. The detail lives in the Diary of each ANALYSIS.
 
+Written at every L3 closure AND at session end with work still IN_PROGRESS (see SKILL.md, Write Triggers).
+
 ```markdown
 # Handoff
 Date: 2026-06-11 (UTC)