@antoneeo/agentic-sdlc-skill 1.23.0 → 1.25.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.25.0 / kb 1.4.5 / mkt 0.4.5] - 2026-08-06
+
+### Added
+- **Functional Spec — the readable WHAT (code lens, F-033).** A conditional `## Functional
+  Spec` ANALYSIS section between the Use Cases and the Interface Contract: the complete
+  observable behavior — rules, cases (normal/edge/error/state-dependent), acceptance
+  criteria — **component-free by construction**, the one object a person reads to answer
+  "is this what we want?" and the AI reads as the behavior contract the design and closure
+  review conform to. Authority split: Use Cases own WHY, the Functional Spec owns WHAT, the
+  Interface Contract owns THROUGH-WHAT (its authority line now cedes behavior semantics),
+  the Impact owns HOW. Fires on behavior change; internal refactor exempt with one line.
+  The shared `review.md` gains the enforcement clause (absence on behavior change,
+  Solution-leakage inside the spec, uncovered cases, acceptance criteria without tests,
+  UC↔FS↔IC coverage — inert in kb/mkt). Rationale + rejected alternatives:
+  `ai_docs/architecture/ADR_2026-08-06_functional_spec_layer.md`; admission: rulings r17.
+- **The strategic pass is ONE search with four open buffers.** SKILL.md §3 now states the
+  owner's model: find how the Actors (defined in the Vision) obtain from the components
+  what the Vision prescribes — risks mitigated in-loop, architecture and patterns
+  respected, quality/maintainability the objective, Poka-Yoke and DRY the selection
+  criteria between hypotheses. Use Cases / Functional Spec / Interface Contract / Threat
+  Model are open buffers — every thought is captured immediately where it belongs; the
+  order UC → FS → IC → TM binds only finalization and reading. Vision divergence halts
+  the pass.
+
+### Changed
+- **Hybrid section updated to post-M47 reality.** The Interface Contract is devPNT's
+  governed `D-IC` (the "lives in the E-ISP" line was stale); the strategy artifacts
+  (`D-UC`/`D-IC`/`P-TM`) are authored as one bundle pass and approved per-document
+  (devPNT doctrine §4.2 owns the procedure); the Functional Spec rides in the `E-ISP`
+  until a governed `D-FS` exists (devPNT-side work).
+
+## [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.25.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.25.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.25.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,7 +218,13 @@ 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).
 
-**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.
+**The strategic pass is ONE search with four open buffers (L3).** The task: find how the Actors (defined in the Vision) obtain from the components what the Vision prescribes — mitigating or eliminating risks along the way, respecting the existing architecture and its patterns, optimizing for quality and maintainability. Actors and Vision are fixed; components, interfaces and flows are the degrees of freedom — modified only as declared changes, never accidental redesign — and Poka-Yoke and DRY govern every choice: the engineering principles are the selection criteria BETWEEN hypotheses during the search, not a checklist after it. The loop is free — hypothesis → verification against the two anchors (the real system, the Vision) → decision → next hypothesis — and every thought is captured immediately in the section it belongs to: Use Cases, Functional Spec, Interface Contract and Security & Threat Model are four open buffers, not four phases (a risk is written into the threat model the moment it is thought; one later eliminated by a design choice disappears at finalization or stays as "eliminated by construction: [the choice]"). The order UC → FS → IC → TM governs only finalization and reading: at convergence, walk the four in dependency order for coherence — each behavior serves a need, each flow realizes a behavior, each threat targets a real surface. The loop is free WITHIN the Vision frame: a hypothesis adding an unauthorized capability or touching a Non-Goal halts the pass and goes to the user.
+
+**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.
+
+**Functional Spec before the Interface Contract (conditional).** When the change adds or alters observable behavior — the trigger's owning definition lives in the `templates.md` `## Functional Spec` section comment; cite it, never restate it — the ANALYSIS carries a `## Functional Spec`: the complete observable WHAT (rules, cases, acceptance criteria), component-free by construction, the one object a person reads to answer "is this what we want?" and the AI reads as the behavior contract the design and the closure review conform to. Without it the WHAT is validated implicitly across four documents — which is where review rounds go to argue about what was meant. Trigger not fired → one line in the section stating why.
+
+**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 interaction 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 the observable interaction **and the responsibility-level flow** (behavior semantics are the Functional Spec's) — 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.
 
@@ -227,7 +233,7 @@ For any L3, run the spec elicitation round in `elicitation.md` BEFORE drafting t
 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), Use Cases / User Needs, Interface Contract (conditional — the paragraph above), Capability Ledger, Impact, Security and Threat Model, Action Plan, Test Strategy, Diary/Current State. (`review.md` makes an uncovered use-case a finding, so an ANALYSIS without that section fails its own closure review.)
+- Minimum sections: Objective, Feature Vision (or Vision Alignment), Use Cases / User Needs, Functional Spec (conditional — behavior change, the paragraph above), Interface Contract (conditional — the paragraph above), Capability Ledger, Impact, Security and Threat Model, Action Plan, Test Strategy, Diary/Current State. (`review.md` makes an uncovered use-case a finding, so an ANALYSIS without that section fails its own closure review.)
 - 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 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.
 
@@ -236,7 +242,8 @@ Standalone L3:
 Hybrid L3:
 - Restore the Master Plan, Action Plan and linked documents.
 - Use devPNT for plans and governed artifacts.
-- The Interface Contract lives in the `E-ISP`, above its Impacted Components map (like the Capability Ledger — never a second copy in `ai_docs/`); a dedicated governed artifact for it is devPNT-side work, not this skill's. Its place in the governed sequence is between `D-UC` and `P-TM`: the use cases say what the person needs, the contract says through which surface, the threat model then assesses those surfaces — the `E-ISP` inherits the interaction, it never generates it.
+- The Interface Contract is devPNT's governed `D-IC`, between `D-UC` and `P-TM`: the use cases say what the person needs, the contract says through which surface, the threat model then assesses those surfaces — the `E-ISP` inherits the interaction, it never generates it. The strategy artifacts (`D-UC`/`D-IC`/`P-TM`) are authored as ONE bundle pass and approved per-document in one sitting (one reasoning act, three projections — devPNT doctrine §4.2 owns the procedure).
+- The Functional Spec has no governed artifact yet: it rides in the `E-ISP`, above its Impacted Components map (like the Capability Ledger — never a second copy in `ai_docs/`); a dedicated `D-FS` is devPNT-side work, not this skill's.
 - Use `ai_docs/solutions/SHADOW_[doc_key]_vX.Y.md` only as a readable shadow when needed; on divergence devPNT wins.
 
 ### 4. Development and Testing

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

@@ -146,6 +146,34 @@ 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.
+- **Functional Spec (same reviews; fires only in the lens whose template defines
+  the section — the code lens today).** When the change adds or alters observable
+  behavior (the trigger's owning definition is the code lens's `templates.md`
+  `## Functional Spec` section comment — cite it, never restate it), **an L3
+  artifact carrying NO `## Functional Spec` is itself a finding** — absence is
+  what a skipped spec looks like, not a reason to skip the check. When the spec
+  is there, these findings live here: **a component, file or mechanism named
+  inside it** — the spec is component-free by construction; that is
+  Solution-leakage (component names belong to the Interface Contract, mechanism
+  to the Impact); a behavior whose edge, error or state-dependent cases are
+  absent with no stated reason; an acceptance criterion no `## Test Strategy`
+  item covers; a behavior serving no use case, or a use case whose behavior the
+  spec leaves unstated; and an Interface Contract flow realizing a behavior the
+  spec does not state. A lens whose template defines no such section (knowledge,
+  marketing) 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,49 @@ 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). -->
+
+## Functional Spec
+<!-- [conditional] Fires when the change ADDS or ALTERS observable behavior —
+     what the system does, decides or shows. Not fired (pure internal refactor,
+     no behavior change) → one line stating why. This comment is the OWNING
+     definition of the section; SKILL.md and review.md cite it, never restate it.
+     THE validation object: the complete observable WHAT, readable by a person
+     ("is this what we want?") and by the AI (the contract the design and the
+     closure review conform to). Component-free by construction: it names NO
+     components, files or mechanisms — behavior only, in the actor's and the
+     domain's vocabulary. (Product names obey the Use Cases grounding buckets:
+     EXISTS with the product's own term / NEW declared / METAPHOR never an
+     interface element.)
+     Content, per use case whose behavior the change touches (a question, not a form):
+     1. Behavior — the rules and decisions, stated as observable outcomes
+        ("a request with an expired token is rejected and the actor is told the
+        session expired; no partial state persists").
+     2. Cases — normal, edge, error and state-dependent behavior: empty, invalid,
+        concurrent, limits, repeated. Each case states what the actor observes.
+     3. Acceptance criteria — the "done when": checkable statements
+        (given/when/then form welcome), each covered by ## Test Strategy.
+     Authority split: Use Cases own WHY (the need), this section owns WHAT
+     (behavior semantics), the Interface Contract owns THROUGH-WHAT (surfaces,
+     flows, feedback), the Impact owns HOW. A component or mechanism named here
+     is Solution-leakage — move it to the Interface Contract (component names)
+     or the Impact (mechanism). -->
 
 ## Interface Contract
 <!-- [conditional] Fires when the change creates or modifies a surface through
@@ -281,9 +323,11 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
         feed the threat model (## Security) and the Impact.
      Reuse the as-is idioms by default; a NEW idiom where an existing one covers
      the job is a declared decision with its reason — never an unmarked invention.
-     Authority split: the contract binds observable behavior AND the
-     responsibility-level flow — it NAMES the components in the flow, never their
-     mechanism or file-level design (that is the Impact's vocabulary). After
+     Authority split: behavior semantics (rules, cases, outcomes) are
+     ## Functional Spec's — this contract binds the observable interaction AND
+     the responsibility-level flow that deliver them; it NAMES the components in
+     the flow, never their mechanism or file-level design (that is the Impact's
+     vocabulary). After
      design approval, changing a contracted surface, flow or feedback is a scope
      change the USER approves: the solution may propose it, never enact it
      silently. Every contracted flow is covered by ## Test Strategy. -->