@antoneeo/agentic-sdlc-skill 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.24.0 / kb 1.4.4 / mkt 0.4.4] - 2026-08-05
+
+### Added
+- **Use-case grounding gate (code lens).** The use-cases / `D-UC` now pass a tight two-check gate
+  before anything builds on them — the top-of-funnel twin of the blast-radius duty: (1) every
+  product name resolves to EXISTS (the product's own term for a real thing) / NEW (declared) /
+  METAPHOR (never an interface element); a name in no bucket invents system reality the project
+  does not have. (2) every use-case traces to a Vision / M-VISION benefit; one that traces to
+  nothing is drift. The gate reads the use-case TEXT and is verified by the **independent design
+  review (moment 1), which precedes and never replaces the owner's own review** — so an ungrounded
+  name or an untraced use-case is caught before the Interface Contract binds it, the threat model
+  assesses it and the Impact maps it. Owning definition: `templates.md` `## Use Cases / User
+  Needs`; enforced by the shared `review.md` use-case-grounding clause (inert in kb/mkt, which
+  define no `## Use Cases` section); `SKILL.md` §3 cites it. The user-need judgement (right need?
+  right actor? good UX?) stays the owner's. Rationale + rejected alternatives:
+  `ai_docs/architecture/ADR_2026-08-05_use_case_grounding_gate.md`. Companion devPNT change
+  (§4.5 D-UC grounding review) ships in that repo's doctrine.
+
 ## [1.23.0 / kb 1.4.3 / mkt 0.4.3] - 2026-08-05
 
 ### Changed

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.23.0",
+  "version": "1.24.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.23.0",
+  "version": "1.24.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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.23.0
+version: 1.24.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
@@ -218,6 +218,8 @@ 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).
 
+**Use cases are grounded before anything builds on them (two checks, nothing else).** The use-cases the elicitation produces pass a tight gate whose owning definition is the `templates.md` `## Use Cases / User Needs` comment — cite it, never restate it: every product name they use resolves to EXISTS (the product's own term for a real thing) / NEW (declared) / METAPHOR (never an interface element), and every use-case traces to a Vision benefit. A name in no bucket invents system reality the project does not have; a use-case tracing to no benefit is drift. It is the top-of-funnel twin of the blast-radius duty below — ground the reasoning artifact in what the system IS and the vision WANTS before the contract, the Ledger and the Impact all inherit it. The author self-applies at drafting; then the independent design review (`review.md` moment 1) verifies the two checks before the owner's own review — it precedes it, never replaces it.
+
 **Interface Contract before the Impact (conditional).** When the change creates or modifies an actor-facing surface — the trigger's owning definition lives in the `templates.md` section comment; cite it, never restate it — the ANALYSIS carries a `## Interface Contract`: the observable behavior the actors get, per use case — the responsibility-level flow each action triggers, naming the components it traverses, and the universal feedback that returns — built by first reading the surfaces and interaction idioms already in place and reusing them by default (a new idiom is a declared decision, never an unmarked invention). It binds observable behavior **and the responsibility-level flow** — it names the components in the flow, never their mechanism; **mechanism and files stay the Impact's vocabulary**. Drafting interleaves with the architect pass below (the contract's feasibility notes are early capability probes), but finalization is ordered: contract and Ledger are both complete before the Impact is drafted. After design approval, a contracted path changes only as a user-approved scope change — the solution proposes, never silently enacts. Trigger not fired → one line in the section stating why. Why it exists: without it the interaction is invented at implementation time, UX is emergent instead of designed, and the review's "actor UX fit" check has no object.
 
 **Architect before you list files.** Once the spec is known and BEFORE drafting the Impact, run the architect pass in `architect.md`: state what the feature requires the system to be able to DO (capabilities — verbs over domain nouns, no files), rule each one against the platform — **EXISTS** (name the component and where it lives) / **INADEQUATE** (name the gap) / **MISSING** (say what you searched) — and design what is missing as a component with **its own contract, in its own vocabulary**, of which this feature is one consumer. The output goes where that mode keeps designs — Standalone: the ANALYSIS `## Capability Ledger`; Hybrid: the `E-ISP`, above its Impacted Components map (`architect.md`; never a second copy in `ai_docs/`) — and it feeds the Impact. Note the coverage asymmetry: the validator backstop reads Standalone ANALYSIS files only, so in Hybrid the sole check that the pass ran is `review.md`'s ledger clause — which is why that clause fires on a MISSING ledger and not only on the rows of one that is present. Why it is its own step: a feature is not a unit of construction, and an agent that skips it builds the missing capability inside the feature's code path, where no component owns it and the next feature rebuilds it differently. The pass is a question, not a form — when every capability plainly exists, one line answers it.

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

@@ -146,6 +146,19 @@ When you are the reviewer:
   which one is current. The rule bites hardest across domains, where the same slot
   ("threat model", "vision", "handoff") carries a different meaning under each lens and
   a copy looks like an independent second source.
+- **Use-case grounding (same reviews; the two-check gate whose owning definition
+  is the code lens's `templates.md` `## Use Cases / User Needs` comment — cite it,
+  never restate it).** On an L3 impact/solution analysis (Standalone) or `D-UC`
+  (Hybrid), two findings live here and nowhere else: **a product name in no
+  bucket** — the use-cases name a thing that neither EXISTS in the product (called
+  by the term the product itself uses; a renamed existing thing is a phantom), nor
+  is declared NEW in this change, nor is a pure METAPHOR kept out of the interface;
+  it invents system reality that is not there. And **a use-case that traces to no
+  Vision / M-VISION benefit** — a need the vision does not want, which is drift.
+  This gate checks the use-cases are GROUNDED and runs BEFORE the owner's own
+  review, never replacing it; coverage of each use-case by the Impact, and the
+  Actor it serves, stay the conformance-statement clause above. A lens whose
+  template defines no `## Use Cases` section never fires this clause.
 - **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
   that carries NO Capability Ledger is itself a finding** — the lens's capability
   pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left

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

@@ -248,7 +248,23 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
      (the Standalone home for what Hybrid keeps in D-UC). Each use-case NAMES the
      Actor it serves (defined in the Vision's ## Actors) — actor = who they are,
      use-case = what they do. Derived from the elicitation round; the Impact below
-     must cover each, and the closure review checks coverage + actor UX fit. -->
+     must cover each, and the closure review checks coverage + actor UX fit.
+     GROUNDING GATE (two checks, nothing else — this comment is the OWNING
+     definition of the gate; review.md and SKILL.md cite it, never restate it):
+     1. Every product name the use-cases use resolves to exactly ONE bucket:
+        EXISTS — real in the product, called by the term the product itself uses
+        (a renamed existing thing is a phantom, not a citation); NEW — introduced
+        by this change and explicitly declared new; METAPHOR — illustrative only,
+        never named as an interface element an actor acts on. A name in no bucket
+        invents system reality that is not there.
+     2. Every use-case traces to a benefit named in the Vision (Standalone) /
+        M-VISION (Hybrid). A use-case serving no stated benefit is drift, not a need.
+     Both read the use-case TEXT — the author self-applies at drafting, then an
+     independent design review (review.md, moment 1) verifies them BEFORE, and
+     without replacing, the owner's own review. They keep the top of the funnel
+     from proposing what the vision does not want or the project does not have;
+     drafting is grounded in BOTH anchors first — the Vision (benefit + actors)
+     and the real system (summaries / existing features / source). -->
 
 ## Interface Contract
 <!-- [conditional] Fires when the change creates or modifies a surface through