@antoneeo/agentic-sdlc-skill 1.21.1 → 1.22.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.22.0 / kb 1.4.2 / mkt 0.4.2] - 2026-08-05
+
+### Added
+- **Interaction Contract (F-032, code lens).** A conditional `## Interaction Contract`
+  section in the ANALYSIS, between the use cases and the Capability Ledger: per use
+  case, actor action on surface → system response → outcome, with view states,
+  existing interaction idioms reused by default and non-binding feasibility notes.
+  Fires when the change creates or modifies a surface an actor *acts on or perceives*
+  (trigger owned by the `templates.md` section comment; SKILL.md and review.md cite
+  it). Binds observable behavior only — after design approval a contracted path
+  changes only as a user-approved scope change. Hybrid sequence: D-UC → D-IC → P-TM →
+  E-ISP — the E-ISP inherits the interaction, it never generates it. Enforced by a
+  lens-keyed clause in the shared `review.md` (inert in kb/mkt, whose templates
+  define no such section) and a wiring invariant test in all three batteries.
+  Ceremony cost disclosed and owner-accepted (rulings r16; ADR 2026-08-04).
+
+### Fixed
+- **Registry recognition hard-coded to one entry point (all three lenses).** The
+  workstream-registry header is written with `entry_script()` but was recognized as
+  "already ours" only by the literal `sdlc_check.py`: a registry generated by
+  `mkt_check.py` was treated as legacy and re-checked for conversion blockers on
+  every run. Recognition now matches the generated marker for any family entry point.
+- **mkt battery isolation.** `test_merge_safety` built `ai_docs` fixtures while
+  inheriting whichever docs root the last imported module set — unittest discovery
+  imports every module (including the mkt overlay, which flips the default to
+  `mkt_docs`) before any test runs, so the marketing battery failed 13+1 under full
+  discovery and passed module-by-module. The battery now pins its docs root in
+  `setUpModule`, as `test_skill_invariants` already did. Full discovery green in all
+  three distributions.
+
 ## [1.21.1 / kb 1.4.1 / mkt 0.4.1] - 2026-08-03
 
 ### Added

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.21.1",
+  "version": "1.22.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.21.1",
+  "version": "1.22.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.21.1
+version: 1.22.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).
 
+**Interaction 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 `## Interaction Contract`: the observable behavior the actors get, per use case (actor action on surface → system response → outcome), 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 only — components 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.
 
 **Blast-radius enumeration is an authoring duty, not a review finding.** Before writing the Impact (the list of what changes), for every symbol whose signature you change, thread a new field through, or that has more than one caller: mechanically enumerate EVERY consumer with the best symbol-graph tool your toolchain offers — an LSP/IDE call hierarchy or a find-usages / call-graph capability — with `grep` only as a last-resort fallback, and list the full set in the Impact. Anchor to symbol identity, not line numbers (they rot). This is deterministic and cheap: doing it up-front collapses the review into one pass, instead of the reviewer returning "you missed a consumer" one round at a time. Leaving completeness to the closure review is the myopia failure this whole workflow exists to prevent.
@@ -225,7 +227,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, 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, Interaction 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.
 
@@ -234,6 +236,7 @@ Standalone L3:
 Hybrid L3:
 - Restore the Master Plan, Action Plan and linked documents.
 - Use devPNT for plans and governed artifacts.
+- The Interaction 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.
 - 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/elicitation.md

@@ -134,8 +134,11 @@ exists (this narrows the reply and speeds up the round). Cover:
    answer to "never lose the thread" — ask again until it is a benefit
    (`vision.md`: the Vision is the distilled benefit; solutions and preferences
    are what gets filtered out).
-2. **Actors** — who interacts with this: their role, primary goal, and what
-   "good UX" means to them. These become the Vision's `## Actors`; each
+2. **Actors** — who interacts with this: their role, primary goal, what
+   "good UX" means to them, and the surfaces they use today for this job
+   (the screens, commands or endpoints they operate — the Interaction
+   Contract's as-is starts here; skip the surface half when no actor-facing
+   surface is in scope). These become the Vision's `## Actors`; each
    use-case below attaches to one (actor = who they are, use-case = what
    they do). Skip only when an approved Vision already names them.
 3. **Scope boundaries** — what is explicitly included in this unit of work.

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

@@ -168,6 +168,20 @@ When you are the reviewer:
   mark ANALYZED, with no searches named**, is the finding that matters most on a
   project the methodology arrived in recently — an unread map reported as an empty
   one is how a duplicate of the existing codebase gets designed.
+- **Interaction Contract (same reviews; fires only in the lens whose template
+  defines the section — the code lens today).** When the change creates or
+  modifies an actor-facing surface (the trigger's owning definition is the code
+  lens's `templates.md` section comment — cite it, never restate it), **an
+  artifact carrying NO `## Interaction Contract` is itself a finding** — "the
+  artifact does not have one" is what a skipped contract looks like, not a reason
+  to skip the check. When the contract is there, four findings live here: a
+  use-case with no named interaction path realizing it; a design or diff element
+  that alters a contracted observable behavior with no explicit renegotiation
+  note (after design approval that is a scope change owed to the user, not a
+  design detail); a contracted path the `## Test Strategy` does not cover; and a
+  new interaction idiom introduced where the contract's own as-is names an
+  existing one, with no declared reason. A lens whose template defines no such
+  section (knowledge, marketing) never fires this clause.
 
 ## Anti-patterns
 

package/skills/agentic-sdlc-skill/scripts/sdlc_check.py

@@ -56,8 +56,8 @@ sdlc_core.set_profile(
         "triage", "write_triggers", "workstream_registry", "vision_gate",
         "design_review_gate", "guide_router", "worktree_hygiene",
         # code overlay
-        "architect_pass", "comprehension_guides", "tdd", "subagent_dispatch",
-        "legacy_narrative_handoff", "question_discipline",
+        "architect_pass", "interaction_contract", "comprehension_guides", "tdd",
+        "subagent_dispatch", "legacy_narrative_handoff", "question_discipline",
     ),
     design_gate_between=("### 3. Request Analysis", "### 4. Development and Testing"),
 )

package/skills/agentic-sdlc-skill/scripts/sdlc_core.py

@@ -245,6 +245,7 @@ REQUIRED_CAPABILITIES = frozenset({
 # Listed here so "this distribution does not claim it" is a visible decision.
 OPTIONAL_CAPABILITIES = frozenset({
     "architect_pass",         # does the component already exist? (code overlay)
+    "interaction_contract",   # actor-facing surface spec between use cases and solution (code overlay)
     "taxonomy_pass",          # do the categories/topics already exist? (knowledge overlay)
     "comprehension_guides",   # source_kind: code maps of complex components
     "tdd",                    # test-first discipline
@@ -841,8 +842,11 @@ def registry_conversion_blockers(root):
     if not hand.is_file():
         return []
     text = read_text(hand)
-    if "GENERATED by sdlc_check.py index" in text:
-        return []                                   # already ours
+    # "Already ours" = written by ANY family entry point: the header is WRITTEN
+    # with entry_script(), so recognition must not hard-code one distribution's
+    # script name (a registry generated by mkt_check.py is just as generated).
+    if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
+        return []
     blockers = []
     known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
     orphans = [r for r in parse_registry_rows(text) if r not in known]

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

@@ -250,6 +250,37 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
      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. -->
 
+## Interaction Contract
+<!-- [conditional] Fires when the change creates or modifies a surface through
+     which an actor **acts on or perceives** the system — GUI view, CLI
+     command/flags, API endpoint, user-edited config, notification or
+     user-facing message. The verb pair is the test; the list is illustrative.
+     IN: an error dialog's wording and states (the actor perceives it and
+     decides on it). OUT: an internal log format, a private module API
+     (operated by code, not by an actor). Not fired → one line stating why.
+     This comment is the OWNING definition of the trigger; SKILL.md and
+     review.md cite it, never restate it.
+     Content, in this order:
+     1. As-is — the touched surfaces as they exist, AND the interaction
+        patterns/idioms already in use relevant to these use cases (how the
+        product already does selection, confirmation, errors, navigation).
+     2. Per use case, the interaction path (table below): actor action on
+        surface → system response → outcome. 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.
+     3. States for each new/changed view: empty, loading, error, denied.
+     4. Feasibility notes, NON-binding: "path X presupposes reuse of Y",
+        "alternative Z discarded: disproportionate cost" — hypotheses the
+        Impact confirms or refutes (early architect-pass probes).
+     The contract binds OBSERVABLE behavior only — no components, no files
+     (that is the Impact's vocabulary). After design approval, changing a
+     contracted path is a scope change the USER approves: the solution may
+     propose it, never enact it silently. Every contracted path is covered
+     by ## Test Strategy. -->
+
+| Use case | Surface | Actor action | System response | Outcome |
+|---|---|---|---|---|
+
 ## Capability Ledger
 <!-- the architect pass (`architect.md`), run BEFORE the Impact below. One row per
      capability the feature requires the system to be able to DO — a verb over a