@antoneeo/agentic-sdlc-skill 1.36.0 → 1.37.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.37.0] - 2026-10-02
+
+### Changed
+- F-061: start bug analysis from incident evidence; maintain hypotheses ranked jointly by likelihood and verification cost, deepen supported causal links with the five whys, and require clean Poka-Yoke correction with the owner's exact design check and collateral verification. Allow declared alternative evidence for intermittent incidents while retaining regression tests.
+- F-058: route course creation to `course-creator` and guard a fourth byte-identical shared core copy.
+- Document explicit `domain: course` and canonical `C-` course analysis identifiers.
+
 ## [1.36.0] - 2026-09-25
 
 ### Changed

package/README.md

@@ -1,204 +1,205 @@
-# Agentic SDLC Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
-
-## Shared project memory
-
-All three lenses include project memory by default; install the lens you need,
-not a second skill just for recall. `index` registers guides, decisions and plans
-in the docs root's `memory/INDEX.md`, linking originals without copying them.
-`recall "onboarding"` finds related metadata across domains; optional
-`topics: [onboarding]` links documents by subject. Read the originals for authority,
-status and evidence: discovery is not approval or proof of implementation.
-
-Registration happens at `index`/documentation closure, not through a background
-watcher. Existing projects acquire the catalog on their next `index`; `recall`
-also sees live metadata. The KB lens remains the specialist for ingestion and
-taxonomy. Marketing retains its numerical validators. See the skill's `memory.md`.
-Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.py`.
-
-
-`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, 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, 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".
-- **Architect pass — capabilities before files**: at L3, before listing what changes, the feature is stated as the *capabilities* it needs and each is ruled against the platform (EXISTS / INADEQUATE / MISSING); what is missing is designed as a component with its own contract, of which the feature is one consumer — never inlined into the feature's code path. A `## Component Map` in `strategic/architecture.md` is the durable inventory the pass reads, so the platform is not re-derived from source every session. On a codebase the methodology arrives in late, the map's silence is treated as **unread, not empty**: it can never ground a MISSING verdict.
-- **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 + 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`.
-- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
-- **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.
-- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, with independent fresh-context reviews of technical artifacts and diffs.
-- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
-- **Question discipline**: a real doubt is asked when it emerges, before its answer is written into any document — grouped, with the pros and cons of each option. A choice whose pros clearly win is taken without asking, and the weighing is written next to it; a fact is settled by evidence or asked, never weighed. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks — never a stream of "shall I proceed?".
-- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `hybrid.md`, `ENFORCEMENT.md`, `memory.md`, and the validator's three files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` + `scripts/knowledge.py` — plus the `LICENSE` and `NOTICE` it ships under.
-- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read — it always exits 0 and carries no verdict, because a measurement that can fail a build becomes a target.
-
-## Installation
-
-### Via npm
-
-```bash
-npm install -g @antoneeo/agentic-sdlc-skill@latest
-```
-
-That is enough — the package's `postinstall` runs the installer. If your npm blocks
-install scripts (`--ignore-scripts`, some CI/pnpm setups), run it by hand:
-
-```bash
-agentic-sdlc-install-skill
-```
-
-> The command is on your PATH only after a **global** (`-g`) install; after a local
-> `npm i`, invoke it as `npx 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/`
-- Google Antigravity: `~/.gemini/config/skills/agentic-sdlc/` (detected distinctly from Gemini CLI; override the home with `ANTIGRAVITY_HOME`)
-
-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` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
-
-It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
-the project is handed the reading guide, the generated manifest, the guide router and the
-last handoff before it does anything — instead of only when it remembers to look. That
-wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
-skipped, and a project could run fully governed with an agent that never met the process.
-
-The hook command names a validator, so where that validator lives decides which file gets
-it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
-(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
-`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
-duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
-with the correction rather than counted as installed.
-
-## Runtime Shape
-
-The actual runtime skill is the folder:
-
-```text
-skills/agentic-sdlc-skill/
-├── SKILL.md
-├── templates.md
-├── architect.md
-├── guides.md
-├── vision.md
-├── tdd.md
-├── debugging.md
-├── elicitation.md
-├── review.md
-├── dispatch.md
-├── routing.md
-├── hybrid.md
-├── memory.md
-├── ENFORCEMENT.md
-├── LICENSE
-├── NOTICE
-└── scripts/
-    ├── sdlc_check.py
-    ├── sdlc_core.py
-    └── knowledge.py
-```
-
-`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
-
-The validator is **three files**: `sdlc_check.py` selects the lens, `sdlc_core.py` owns structural checks, and `knowledge.py` adds shared memory and KB integrity. Copy all three; core alone is not equivalent.
-
-Installing or updating the npm package wires the session-orientation hook
-machine-wide (user-level Claude Code settings; removal is a standing opt-out
-that no update overrides -- ENFORCEMENT.md par.4).
-
-## The family: three lenses, one spine
-
-Same process, three fidelity disciplines — what the agent's assertions must be faithful to:
-
-| Package | Faithful to | Unit of work | Own doctrine |
-|---|---|---|---|
-| [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill) | this repository's code | feature | `architect.md`, `tdd.md`, `debugging.md` |
-| [`@antoneeo/kb-agentic-skill`](https://www.npmjs.com/package/@antoneeo/kb-agentic-skill) | the documents you supply | topic | `taxonomy.md`, `distillation.md`, `reconciliation.md` |
-| [`@antoneeo/mkt-agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/mkt-agentic-sdlc-skill) | market evidence | engagement | `frameworks.md`, `research.md` |
-
-The three lenses share the process spine and knowledge-integrity engine. Install only the one you need; when two live in the same project, `routing.md` decides which lens owns a given piece of work. Marketing additionally runs its numerical checks: code/KB do not certify marketing arithmetic.
-
-## 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)).
-
-## License
-
-Apache-2.0 — the full terms are in the `LICENSE` file, the attribution in `NOTICE`. Copyright 2026 Antonio Pinto.
-
-If you redistribute this skill, or a version you modified, keep `LICENSE` and `NOTICE` with it.
-
-Using the skill in your own project carries no obligation: the documents it creates or templates there are yours, and so is a copy of the validator and its tests placed in that project to check its own documents.
-
-Versions up to 1.33.0 were released under the MIT license and remain available under it.
-
-If you use the skill in commercial work, a mention on your product page or website is appreciated. It is a request, not a condition of the license. A ready-made badge:
-
-```markdown
-[![Made with agentic-sdlc](https://img.shields.io/badge/made%20with-agentic--sdlc-blue)](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill)
-```
-
-## Which model to run it on
-
-The skill names **capability tiers**, never providers — a model name in doctrine
-rots at the next release. The binding is yours to make, and the rule is one line:
-
-> **A session's floor is the highest floor among the roles it performs itself.**
-
-Authoring a governed artifact — the vision, the analysis, the use cases, the
-threat model — is a **deep-tier** role: its output is judgement, and nothing
-downstream scores it. So a session that will DESIGN wants your strongest model.
-A session that only executes an already-approved plan, or does small maintenance,
-can sit a tier lower. The cheapest tier is the wrong choice for the main session
-whatever the task, because the failure there is not a wrong answer — it is
-**silently not applying the process**: a triage never run, a router verdict
-declared without the lookup, a gate nobody noticed. That failure is invisible to
-every check in here.
-
-**The reviewer's tier is not automatically yours.** On some clients a subagent
-inherits the session's model; on others it takes one from its own definition, so
-a strong session can be reviewed by a weak one — and a weak session can buy a
-strong review. Set it deliberately; the
-`model` column in the review log is where the choice becomes visible.
-
-**Avoid one combination**: authoring below the floor AND reviewing below the floor
-on the same unit. One disclosed weakness is a disclosed weakness; two is an
-artifact nobody competent ever read. Where your client offers nothing better, the
-review still runs and both facts are recorded — a disclosed worst case beats
-skipping the review.
+# Agentic SDLC Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
+
+## Shared project memory
+
+All four lenses include project memory by default; install the lens you need,
+not a second skill just for recall. `index` registers guides, decisions and plans
+in the docs root's `memory/INDEX.md`, linking originals without copying them.
+`recall "onboarding"` finds related metadata across domains; optional
+`topics: [onboarding]` links documents by subject. Read the originals for authority,
+status and evidence: discovery is not approval or proof of implementation.
+
+Registration happens at `index`/documentation closure, not through a background
+watcher. Existing projects acquire the catalog on their next `index`; `recall`
+also sees live metadata. The KB lens remains the specialist for ingestion and
+taxonomy. Marketing retains its numerical validators. See the skill's `memory.md`.
+Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.py`.
+
+
+`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, 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, 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".
+- **Architect pass — capabilities before files**: at L3, before listing what changes, the feature is stated as the *capabilities* it needs and each is ruled against the platform (EXISTS / INADEQUATE / MISSING); what is missing is designed as a component with its own contract, of which the feature is one consumer — never inlined into the feature's code path. A `## Component Map` in `strategic/architecture.md` is the durable inventory the pass reads, so the platform is not re-derived from source every session. On a codebase the methodology arrives in late, the map's silence is treated as **unread, not empty**: it can never ground a MISSING verdict.
+- **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), evidence-first debugging with hypotheses ranked by likelihood and verification cost, supported causal questioning and clean Poka-Yoke correction with regression checks; an L3 spec-elicitation round and a single code-review definition wired into the workflow phases.
+- **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`.
+- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
+- **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.
+- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, with independent fresh-context reviews of technical artifacts and diffs.
+- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
+- **Question discipline**: a real doubt is asked when it emerges, before its answer is written into any document — grouped, with the pros and cons of each option. A choice whose pros clearly win is taken without asking, and the weighing is written next to it; a fact is settled by evidence or asked, never weighed. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks — never a stream of "shall I proceed?".
+- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `hybrid.md`, `ENFORCEMENT.md`, `memory.md`, and the validator's three files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` + `scripts/knowledge.py` — plus the `LICENSE` and `NOTICE` it ships under.
+- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`. `benefit` reports what the review gates have already caught, beside what the doctrine costs to read — it always exits 0 and carries no verdict, because a measurement that can fail a build becomes a target.
+
+## Installation
+
+### Via npm
+
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+```
+
+That is enough — the package's `postinstall` runs the installer. If your npm blocks
+install scripts (`--ignore-scripts`, some CI/pnpm setups), run it by hand:
+
+```bash
+agentic-sdlc-install-skill
+```
+
+> The command is on your PATH only after a **global** (`-g`) install; after a local
+> `npm i`, invoke it as `npx 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/`
+- Google Antigravity: `~/.gemini/config/skills/agentic-sdlc/` (detected distinctly from Gemini CLI; override the home with `ANTIGRAVITY_HOME`)
+
+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` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+
+It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
+the project is handed the reading guide, the generated manifest, the guide router and the
+last handoff before it does anything — instead of only when it remembers to look. That
+wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
+skipped, and a project could run fully governed with an agent that never met the process.
+
+The hook command names a validator, so where that validator lives decides which file gets
+it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
+(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
+`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
+duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
+with the correction rather than counted as installed.
+
+## Runtime Shape
+
+The actual runtime skill is the folder:
+
+```text
+skills/agentic-sdlc-skill/
+├── SKILL.md
+├── templates.md
+├── architect.md
+├── guides.md
+├── vision.md
+├── tdd.md
+├── debugging.md
+├── elicitation.md
+├── review.md
+├── dispatch.md
+├── routing.md
+├── hybrid.md
+├── memory.md
+├── ENFORCEMENT.md
+├── LICENSE
+├── NOTICE
+└── scripts/
+    ├── sdlc_check.py
+    ├── sdlc_core.py
+    └── knowledge.py
+```
+
+`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
+
+The validator is **three files**: `sdlc_check.py` selects the lens, `sdlc_core.py` owns structural checks, and `knowledge.py` adds shared memory and KB integrity. Copy all three; core alone is not equivalent.
+
+Installing or updating the npm package wires the session-orientation hook
+machine-wide (user-level Claude Code settings; removal is a standing opt-out
+that no update overrides -- ENFORCEMENT.md par.4).
+
+## The family: four lenses, one spine
+
+Same process, four fidelity disciplines — what the agent's assertions must be faithful to:
+
+| Package | Faithful to | Unit of work | Own doctrine |
+|---|---|---|---|
+| [`@antoneeo/agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill) | this repository's code | feature | `architect.md`, `tdd.md`, `debugging.md` |
+| [`@antoneeo/kb-agentic-skill`](https://www.npmjs.com/package/@antoneeo/kb-agentic-skill) | the documents you supply | topic | `taxonomy.md`, `distillation.md`, `reconciliation.md` |
+| [`@antoneeo/mkt-agentic-sdlc-skill`](https://www.npmjs.com/package/@antoneeo/mkt-agentic-sdlc-skill) | market evidence | engagement | `frameworks.md`, `research.md` |
+| [`@antoneeo/course-creator`](distributions/course-creator/README.md) | the learner's starting point and verified teaching sources | course | `learning_design.md`, `source_check.md`, `simulation.md`, `feedback.md` |
+
+The four lenses share the process spine and knowledge-integrity engine. Install only the one you need; when two live in the same project, `routing.md` decides which lens owns a given piece of work. Marketing runs numerical checks; course creator checks instructional structure. Neither structural check certifies factual truth or human learning.
+
+## 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)).
+
+## License
+
+Apache-2.0 — the full terms are in the `LICENSE` file, the attribution in `NOTICE`. Copyright 2026 Antonio Pinto.
+
+If you redistribute this skill, or a version you modified, keep `LICENSE` and `NOTICE` with it.
+
+Using the skill in your own project carries no obligation: the documents it creates or templates there are yours, and so is a copy of the validator and its tests placed in that project to check its own documents.
+
+Versions up to 1.33.0 were released under the MIT license and remain available under it.
+
+If you use the skill in commercial work, a mention on your product page or website is appreciated. It is a request, not a condition of the license. A ready-made badge:
+
+```markdown
+[![Made with agentic-sdlc](https://img.shields.io/badge/made%20with-agentic--sdlc-blue)](https://www.npmjs.com/package/@antoneeo/agentic-sdlc-skill)
+```
+
+## Which model to run it on
+
+The skill names **capability tiers**, never providers — a model name in doctrine
+rots at the next release. The binding is yours to make, and the rule is one line:
+
+> **A session's floor is the highest floor among the roles it performs itself.**
+
+Authoring a governed artifact — the vision, the analysis, the use cases, the
+threat model — is a **deep-tier** role: its output is judgement, and nothing
+downstream scores it. So a session that will DESIGN wants your strongest model.
+A session that only executes an already-approved plan, or does small maintenance,
+can sit a tier lower. The cheapest tier is the wrong choice for the main session
+whatever the task, because the failure there is not a wrong answer — it is
+**silently not applying the process**: a triage never run, a router verdict
+declared without the lookup, a gate nobody noticed. That failure is invisible to
+every check in here.
+
+**The reviewer's tier is not automatically yours.** On some clients a subagent
+inherits the session's model; on others it takes one from its own definition, so
+a strong session can be reviewed by a weak one — and a weak session can buy a
+strong review. Set it deliberately; the
+`model` column in the review log is where the choice becomes visible.
+
+**Avoid one combination**: authoring below the floor AND reviewing below the floor
+on the same unit. One disclosed weakness is a disclosed weakness; two is an
+artifact nobody competent ever read. Where your client offers nothing better, the
+review still runs and both facts are recorded — a disclosed worst case beats
+skipping the review.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.36.0",
+  "version": "1.37.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.36.0",
+  "version": "1.37.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/scripts/init.js

@@ -203,16 +203,16 @@ in the skill's \`routing.md\`: it decides which lens's method and validation rul
 that unit. L1 never reaches it. Never refer to a document whose meaning differs by lens
 ("threat model", "vision", \`principles.md\`, \`handoff.md\`) by its bare name.
 
-Select the owning lens by the unit's purpose, then apply only its risk scale.
-The project's always-on pointer stays intact: consult the selected skill rather than
-merging multiple mandatory ladders. All lenses already carry shared project memory
-(\`memory.md\`); another installation is not needed for cross-domain recall.
+Select the owning lens by the unit's purpose, then apply only its risk scale.
+The project's always-on pointer stays intact: consult the selected skill rather than
+merging multiple mandatory ladders. All lenses already carry shared project memory
+(\`memory.md\`); another installation is not needed for cross-domain recall.
 This file is NOT auto-loaded by any client: it is a note for you, deliberately additive.
-Delete this note once the routing pointer is integrated.
+Delete this note once the routing pointer is integrated.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
+    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
   }
 }
 

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

@@ -14,17 +14,17 @@ python "<skill_dir>/scripts/sdlc_check.py" check
 
 ## 2. Check in CI (recommended for teams)
 
-Copy all three validator files into the repository: `scripts/sdlc_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
+Copy all three validator files into the repository: `scripts/sdlc_check.py`, `scripts/sdlc_core.py`, and `scripts/knowledge.py`, keeping them side by side. Then add to the pipeline:
 
 ```
 python tools/sdlc_check.py validate --strict
 ```
 
-The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
+The validator ships as **three files**: the domain entry point, `sdlc_core.py` and `knowledge.py`. Keep all three together. The core alone still runs but omits shared-memory/KB checks and domain-specific overlays; it is not an equivalent CI gate. `check` includes the knowledge surface when present.
 
 Effect: an unregenerated index, invalid frontmatter, a missing security section or incoherent states **block the pipeline** instead of relying on the agent's memory. `--strict` also fails on warnings and on a missing `ai_docs/`, so a wrong working directory cannot produce a green pipeline. This works because documents travel in the same PR as the code (Phase 5 rule).
 
-Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill — all three files, together.
 
 **Projects whose docs root is not `ai_docs/`.** Pass `--docs-dir <name>` (e.g. `--docs-dir mkt_docs`) on any subcommand, or set `AGENTIC_SDLC_DOCS_DIR`. Without either, the validator walks up from the working directory and takes the nearest root it recognizes. If it finds two side by side — the shape of a half-finished migration — it refuses and names both rather than validating half a project and printing a verdict. `ai_docs/` remains the default and the recommended root: the parameter exists so a legacy tree can be read and migrated, not so a second one can be kept.
 
@@ -155,7 +155,7 @@ Gemini CLI — wire the same command into its startup-hook mechanism if present;
 **Usage notes:**
 - The hook assumes the working directory is the project root (standard Claude Code hook behavior); it also accepts `--root <path>`.
 - **Hybrid/devPNT projects**: add `--hybrid` — the hook then appends a one-line pointer to run `devpnt_mcp_get_bootstrap` for the Master Plan / Knowledge Layer and does not replicate them; the filesystem orientation (router + handoff + README) still emits.
-- Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep all three files current when you update the skill.
+- Like the CI gate (§2), if you copied the validator into the repo, the hook references that copy — keep all three files current when you update the skill.
 
 ### Per-turn reminder: `remind` (UserPromptSubmit -- wired by default)
 
@@ -215,7 +215,7 @@ It aggregates the test files (`test_plan.py` + `test_session_start.py` + `test_s
 
 **Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
 
-**T10 note:** if you copied the validator (all three files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
+**T10 note:** if you copied the validator (all three files) and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.
 
 ## `benefit` is a report, never a CI gate
 

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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.36.0
+version: 1.37.0
 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
@@ -59,10 +59,11 @@ Always classify the request before choosing the process. Declare the chosen leve
 | **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:
-- **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`kb-agentic`, `mkt-agentic-sdlc`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
+- **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`kb-agentic`, `mkt-agentic-sdlc`, `course-creator`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
 - 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.
+- For L2/L3 bugs, load `debugging.md` at the start of analysis, before proposing a cause or fix: incident evidence, ranked hypotheses and causal verification precede correction.
 - **A real doubt is asked when it emerges, before its answer is written — any phase, any level; a question is legal only after naming the search with its result and the decision it blocks.** `elicitation.md` §The question discipline owns the rule — what is a real doubt, the pros-and-cons weighing, the form — and is the only place it is stated: read it before you ask or assume, and do not work from a summary of it.
 - The full audit does not start for L1/L2 unless explicitly requested.
 
@@ -204,7 +205,7 @@ Hybrid L3:
 - 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** — the verdict already declared with the triage level (`## Operative Guides`). Re-run the lookup here only if the work has moved to a topic the first one did not cover, and say so if the verdict changes.
 - 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`.
+- For bugs (L2/L3), continue the investigation and design-verification method in `debugging.md`; implementation follows the `tdd.md` discipline above.
 - 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. `dispatch.md` also carries the family-wide **delegation boundary** (what may be delegated at all, and what never may) — that section is not gated by the opt-in trigger and applies at any level, dispatch or no dispatch.