@antoneeo/agentic-sdlc-skill 1.34.0 → 1.36.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.36.0] - 2026-09-25
+
+### Changed
+- **F-026 revised: a real doubt is asked when it emerges.** The question discipline
+  no longer sends doubts to the deliverable ("Default non-blocking" is gone). A real
+  doubt (a fact the search leaves open, or a choice whose pros and cons do not
+  settle it) is asked before the first write that would embed its answer, grouped,
+  with the pros and cons of each option. A choice that clearly wins the weighing is
+  taken without asking, and the weighing is written next to it — each rejected option
+  stated at its strongest; options that serve different needs, none good enough at
+  both, that nothing the user wrote ranks are a real doubt, however clear the
+  agent's own ranking. Reserved approvals
+  are always asked. A real doubt becomes a declared assumption only in unattended
+  or delegated work. `review.md` makes an unasked doubt a design-review finding; `dispatch.md`
+  tells a subagent to return its real doubts instead of deciding them.
+
+### Fixed
+- **`stale` no longer counts the audit plan against the area that holds it.**
+  Committing a hash mark of `ai_docs/` changed `ai_docs/audit/audit_plan.md` after
+  the recorded commit, so the area went stale again and every re-mark repeated the
+  loop. The plan's own edits are now excluded; any other change in the area still
+  counts.
+
+## [1.35.0] - 2026-09-19
+
+### Added
+- F-057: shared project memory in every lens, no sibling installation required.
+  `index` catalogs original documents; `recall QUERY` searches live metadata.
+  KB integrity is shared; domain ownership and marketing numerical checks remain.
+  Vendored validators now require entry point + sdlc_core.py + knowledge.py.
+
+
+### Fixed
+- **F-056: `stale` no longer reports an area fresh when it cannot evaluate it.** An
+  `audit_plan.md` row whose reference no longer resolves (the commit was amended,
+  rebased or squash-merged away, or the clone is shallow), whose reference is a git
+  hash where git is unusable, or whose reference is unparseable used to print a
+  warning, then `[ok]`, and exit 0. It now prints `[stale]` with the re-mark command
+  and exits 1, so `check` is NOT CLEAN. A reference that still resolves but is no
+  longer an ancestor of HEAD gets a warning before it dangles, and `mark` says to
+  commit its result as a new commit. **Teams that squash- or rebase-merge:** a
+  reference recorded on a feature branch never reaches the integration branch, so
+  re-mark those areas after the merge.
+
 ## [1.34.0] - 2026-09-14
 
 ### Changed

package/README.md

@@ -1,186 +1,204 @@
-# Agentic SDLC Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
-
-`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 question to the user is legal only when the agent searched first and names the search with its result, and names the decision the answer unblocks. Otherwise it proceeds on a declared assumption — same evidence duty, batched, 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`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.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
-├── ENFORCEMENT.md
-├── LICENSE
-├── NOTICE
-└── scripts/
-    ├── sdlc_check.py
-    └── sdlc_core.py
-```
-
-`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
-
-The validator is **two files**: `sdlc_core.py` is the family's shared spine, `sdlc_check.py` is this lens's entry point. Copy both, or neither — the entry point is useless alone.
-
-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` |
-
-Triage, the Vision Gate, the review gates, the guide router, question discipline and the validator spine are byte-identical across the three. Install only the one you need; when two live in the same project, `routing.md` decides which lens owns a given piece of work and any of the three validators gives the same verdict on the same tree.
-
-## 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 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.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.34.0",
+  "version": "1.36.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.34.0",
+  "version": "1.36.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",
@@ -40,6 +40,8 @@
     "skills/agentic-sdlc-skill/ENFORCEMENT.md",
     "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
     "skills/agentic-sdlc-skill/scripts/sdlc_core.py",
+    "skills/agentic-sdlc-skill/scripts/knowledge.py",
+    "skills/agentic-sdlc-skill/memory.md",
     "skills/agentic-sdlc-skill/LICENSE",
     "skills/agentic-sdlc-skill/NOTICE",
     "gemini-extension.json",

package/scripts/init.js

@@ -203,27 +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.
 
-${protocolPreexisting ? `**Merge step owed.** The always-on protocol pointer of this project (\`CLAUDE.md\` /
-\`GEMINI.md\` / \`AGENTS.md\` / \`.cursorrules\`) was written by another lens's init and
-carries ITS triage ladder. This init did not overwrite it. Add the code lens's ladder
-to that file by hand — the pointer below — so both are always loaded.
-
-## Rule Zero — Triage every request (code lens)
-- L1 Trivial: ~10 lines, 1-2 files, no API/dependency/behavior change.
-- L2 Small: clear root cause, at most 3 files, low risk. Tests mandatory.
-- L3 Significant: >3 files, APIs/contracts, new dependency, user-visible behavior,
-  security-sensitive area, or architectural change. Full workflow via the skill.
-- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`.
-` : `The always-on protocol pointer for the code lens was created by this init. When you
-install another lens over this project, its init will leave its own ladder here for you
-to merge.
-`}
+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 it once the merge is done.
+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(`       Merge the ${SELF_LENS}-lens ladder from AGENTIC_MULTI_LENS.md into it by hand.`);
+    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 **both** validator files into the repository — `scripts/sdlc_check.py` (the entry point) **and** `scripts/sdlc_core.py` (the shared core it imports) — keeping them side by side, e.g. `tools/sdlc_check.py` + `tools/sdlc_core.py`. 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 two files: the core carries the behaviour and is identical in every distribution of the family, the entry point names the domain. Copying only `sdlc_check.py` fails immediately with a message saying so — loudly, never as a silently green pipeline. (Copying `sdlc_core.py` alone also works: `python tools/sdlc_core.py validate --strict` behaves identically, defaulting to the code domain.)
+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 — both 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 both 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 (both 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.34.0
+version: 1.36.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
@@ -20,7 +20,7 @@ Support files in the skill directory:
 - `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check run before promoting one to APPROVED.
 - `hybrid.md`: the devPNT seam — the authoritative hierarchy, the ownership matrix (who owns what when both authorities are live), the triage equivalence, the feature-state mapping and the shadow discipline. Read it when the `devpnt_*` tools point at this project; a Standalone session never needs it.
 - `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
-- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`). Two files: the core is the family's shared spine, the entry point names this domain. Copy both, or neither.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`).  Keep the entry point, `scripts/sdlc_core.py` and `scripts/knowledge.py` together; the last supplies common memory and KB integrity.
 - `ENFORCEMENT.md`: optional setup for CI and hooks.
 
 Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
@@ -37,6 +37,14 @@ Read these files only when needed. `SKILL.md` is the operating contract; the sup
 
 If a patch looks easy but you do not understand why the current code is shaped the way it is, investigate first.
 
+## Shared project memory
+
+Project memory is available by default, independently of installed sibling lenses.
+Read `memory.md` for the common consult/capture contract during orientation and
+closure. Use `recall` for cross-domain discovery; `index` registers original guides,
+plans and decisions without copying them. One owner still governs each unit.
+The validator now ships as three files: entry point, `sdlc_core.py`, `knowledge.py`.
+
 ## Rule Zero: Triage
 
 Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
@@ -55,7 +63,7 @@ Cross-cutting rules:
 - Parsing of external input, authN/authZ, cryptography, networking, personal data and filesystem access are security-sensitive: never L1.
 - If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
 - When in doubt, pick the higher level.
-- **Before asking the user anything — any phase, any level — the question must pass the legality test: search first and name the search with its result; name the decision or fact blocked without the answer.** Blocking the work is the exception, not the default. `elicitation.md` §The question discipline owns the rule and is the only place it is stated — read it before you ask, and do not work from a summary of it.
+- **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.
 
 Triage rationalizations — the thought on the left is the signal to STOP and re-triage: