@antoneeo/agentic-sdlc-skill 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.9.0] - 2026-07-03 (M2 execution disciplines + Feature B unit 2 agent KB)
+### Added
+- `tdd.md`: TDD discipline (RED/GREEN/REFACTOR, increment rule, AAA test shape, documented exemptions) — the L2/L3 default for implementation work.
+- `debugging.md`: systematic debugging method (reproduce, isolate, root cause, fix, regression test, collateral check) with circuit-breaker integration.
+- `elicitation.md`: spec elicitation round (goal/benefit, scope boundaries, non-goals, constraints, acceptance signals) run before drafting the analysis in phase 3.
+- `review.md`: single definition of requesting, receiving, and performing code review, reused by the Hybrid review gates.
+- `SKILL.md` wiring: pointers to the four new files added at phase 3 (elicitation), phase 4 (TDD, debugging, circuit breaker), and phase 5 (review).
+- Agent-global KB (fixed root, project-wins precedence, `overrides:` with fail-closed confinement, collision warnings).
+
 ## [1.8.1] - 2026-07-02
 ### Fixed
 - **Guide freshness hash is now line-ending independent**: `sha256_file` in `sdlc_check.py` normalizes CRLF → LF before hashing. Previously the raw-byte hash made a fresh Windows checkout with `core.autocrlf=true` rewrite `.sources/` snapshots and flag every guide `[stale]` (false positive). Backward compatible: recorded hashes were computed on LF content, and normalization maps CRLF copies back to the same digest. (Edge case: a hash recorded pre-1.8.1 on a snapshot that genuinely contained CRLF bytes will flag `[stale]` once — regenerate the hash.)

package/README.md

@@ -8,7 +8,7 @@
 - **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star.
 - **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.
-- **Installed support files**: Claude, Codex, and Gemini receive the full skill folder, including `templates.md`, `guides.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`.
+- **Installed support files**: Claude, Codex, and Gemini receive the full skill folder, including `templates.md`, `guides.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`; an agent-global KB at `~/.agentic-sdlc` shares the same engine cross-project.
 - **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
 
 ## Installation
@@ -45,6 +45,10 @@ skills/agentic-sdlc-skill/
 ├── SKILL.md
 ├── templates.md
 ├── guides.md
+├── tdd.md
+├── debugging.md
+├── elicitation.md
+├── review.md
 ├── ENFORCEMENT.md
 └── scripts/
     └── sdlc_check.py

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.8.1",
+  "version": "1.9.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.8.1",
+  "version": "1.9.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",
@@ -28,6 +28,10 @@
     "skills/agentic-sdlc-skill/SKILL.md",
     "skills/agentic-sdlc-skill/templates.md",
     "skills/agentic-sdlc-skill/guides.md",
+    "skills/agentic-sdlc-skill/tdd.md",
+    "skills/agentic-sdlc-skill/debugging.md",
+    "skills/agentic-sdlc-skill/elicitation.md",
+    "skills/agentic-sdlc-skill/review.md",
     "skills/agentic-sdlc-skill/ENFORCEMENT.md",
     "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
     "gemini-extension.json",

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

@@ -176,6 +176,8 @@ Hybrid:
 
 ### 3. Request Analysis
 
+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).
+
 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`.
@@ -191,14 +193,16 @@ Hybrid L3:
 
 - Implement only after the documentation gate required by the level.
 - Modify surgically, consistently with the plan.
-- Write or update relevant automated tests; use AAA for unit tests when applicable.
+- Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).
 - If the environment does not allow automated tests, declare the alternative verification and the reason.
-- Circuit breaker: after 3 consecutive runs without progress on the tests, stop and ask for instructions.
+- For bugs (L2/L3), follow the systematic debugging method in `debugging.md`.
+- 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.
 - Update the ANALYSIS Diary or the Action Plan when you complete milestones, hit blockers or change decisions.
 
 ### 5. Closure
 
 - Run the relevant tests/lint/smoke checks.
+- For the review itself follow `review.md` (requesting and receiving findings) — the single definition, intended for reuse by the Hybrid review gates (devPNT-side wiring out of this unit's scope).
 - Verify alignment with the local Vision or the devPNT M-VISION.
 - Update only the documents actually impacted.
 - **Aligned indexes (Poka-Yoke)**: if you created, moved or removed canonical documents (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`):
@@ -253,6 +257,8 @@ forbidden. Full pipeline, DRY rule, snapshotting and maintenance: `guides.md`.
 `ai_docs/reference/INDEX.md` is generated (the guide router) — never edit by hand,
 regenerate with `sdlc_check.py index`.
 
+**Agent-global KB.** A second, cross-project guide root lives at the fixed path `~/.agentic-sdlc/` (same `ai_docs/` structure, same validator/router/freshness engine via `sdlc_check.py --root ~/.agentic-sdlc`). Project guides win on topic collision; a project guide that overrides a KB guide MUST declare `overrides: GUIDE_<topic>.md` — the validator warns on undeclared collisions (error under `--strict`) and fail-closes on an `overrides:` value that escapes the KB. Discovery is this paragraph: agents and subagents reach KB guides by path, exactly like project guides.
+
 ## Mechanical Enforcement
 
 The prompt is not enforcement. When the project needs repeatable guarantees:

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

@@ -0,0 +1,50 @@
+# Systematic Debugging
+
+Applies to bugs classified L2 or L3. Entered either from phase 4
+(Development and Testing) when a defect surfaces during implementation, or
+from the circuit breaker in `SKILL.md` §4 after repeated no-progress runs.
+
+## Method
+
+Work the steps in order; do not skip ahead to a fix before step 3 names the
+mechanism.
+
+1. **Reproduce deterministically.** Find the smallest input or scenario that
+   triggers the bug every time. A bug you cannot reliably reproduce cannot be
+   verified as fixed.
+2. **Isolate.** Narrow the failing case to its minimal form — strip
+   unrelated setup, unrelated data, unrelated code paths. Bisect (recent
+   commits, code paths, input ranges) when the boundary is unclear.
+3. **Root cause — name the mechanism.** State in one sentence why the
+   observed behavior happens, tracing the actual execution path. **MUST NOT
+   patch a symptom without naming the mechanism; why: symptom patches recur
+   and stack** — the same underlying defect resurfaces elsewhere, and each
+   unexplained patch makes the next investigation harder, not easier.
+4. **Fix at the cause**, not at the symptom identified in step 1.
+5. **Write a regression test that FAILS on the old code** (verify this
+   before applying the fix, or by temporarily reverting it) and passes after.
+   A regression test that was never confirmed to fail proves nothing.
+6. **Run the relevant suite for collateral.** A root-cause fix can change
+   behavior other callers depend on; check them before closing.
+
+## Circuit breaker integration
+
+After 3 consecutive runs without progress: STOP. Do not attempt a 4th
+variation of the same guess. Audit your assumptions from step 1 — is the
+reproduction actually deterministic, is the isolated case actually minimal,
+is the "root cause" from step 3 actually confirmed or just plausible? Then
+restart from step 1 with the corrected assumption.
+
+If still stuck after the restart, ask the user for instructions, and hand
+over the evidence gathered so far: the minimal reproduction, what was ruled
+out, and the current best hypothesis.
+
+## Anti-patterns
+
+- **Shotgun debugging**: changing several things at once hoping one fixes it
+  — when it "works," you do not know which change mattered or why.
+- **Stacking speculative fixes**: adding a second guess on top of an
+  unverified first one instead of confirming or discarding it first.
+- **"Fixed but can't say why"**: closing the bug without a step-3 mechanism
+  statement. If you cannot name the mechanism, the fix is not confirmed —
+  it may just be masking the trigger.

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

@@ -0,0 +1,45 @@
+# Spec Elicitation
+
+Applies when an L3 request enters phase 3 (Request Analysis), BEFORE
+drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP (Hybrid).
+
+Skip path: if the spec is already complete — an approved Vision or explicit
+user requirements already answer goal, scope, and constraints — skip the
+round and add a one-line note in the analysis stating why it was skipped.
+Do not run the round as a formality when the answers are already on record.
+
+## The round
+
+Ask ONE structured set of questions, not a drip of follow-ups. Keep each
+question short and numbered; offer concrete options where a real choice
+exists (this narrows the reply and speeds up the round). Cover:
+
+1. **Goal / benefit** — what problem this closes, for whom, and why now.
+2. **Scope boundaries** — what is explicitly included in this unit of work.
+3. **Non-goals** — what is explicitly excluded, so scope does not silently
+   creep in later.
+4. **Constraints** — technical, compatibility, and security constraints that
+   bound the solution space.
+5. **Acceptance signals** — how you and the user will both recognize the
+   work is done and correct.
+
+## Reflect
+
+Fold the answers into the ANALYSIS `## Objective` / `## Vision-Alignment`
+sections (Standalone) or into the D-UC/E-ISP (Hybrid) — do not leave them
+sitting only in the chat transcript. The written document, not the
+conversation, is what the next session and the next reviewer will read.
+
+Run a second round only when an answer opens a real fork in the design (a
+genuinely new question the first round could not have anticipated). Do not
+run a second round to double-check answers that were already clear.
+
+## Anti-patterns
+
+- **Interrogation**: an endless list of questions, or drip-feeding one
+  question at a time across many turns instead of one structured round.
+- **Asking what the approved vision already answers**: re-asking goal or
+  non-goals that a `Status: APPROVED` Vision or M-VISION already states.
+- **Collecting answers without folding them in**: getting replies in chat
+  and proceeding to design without writing them into the analysis document —
+  the next reader has no record of why the scope is what it is.

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

@@ -39,8 +39,11 @@ guide with no `distilled_from` is not this pipeline's output.
 0. **Search before creating (DRY — one CURRENT guide per topic).** Before
    proposing anything, read `ai_docs/reference/INDEX.md` and grep
    `reference/GUIDE_*.md` for topic overlap with the new material. Never end
-   up with two CURRENT guides on the same topic. On overlap, pick by
-   provenance:
+   up with two CURRENT guides on the same topic. Search BOTH routers: project
+   `ai_docs/reference/INDEX.md` AND the agent KB router
+   `~/.agentic-sdlc/ai_docs/reference/INDEX.md` (if present) — one CURRENT
+   guide per topic PER SCOPE; a project guide on a KB topic requires the
+   explicit `overrides:` declaration. On overlap, pick by provenance:
    - **Same source, evolved** → UPDATE the existing guide in place: new
      snapshot, new `source_hash`, same file (history lives in git).
    - **Different source replacing the old one** → NEW guide + mark the old
@@ -75,8 +78,13 @@ guide with no `distilled_from` is not this pipeline's output.
    - Heterogeneous sources (unrelated policies handed over together) are the
      legitimate split case; a single coherent document about one subsystem
      almost never is.
-2. **User confirms** the topic decomposition — including the declared
-   fragmentation-risk assessment — before any file is written.
+   - **Also decide SCOPE per proposed guide**: project-scope
+     (`ai_docs/reference/`) or agent-scope (`~/.agentic-sdlc/ai_docs/reference/`,
+     governs the agent across ALL projects; origin+purpose test unchanged,
+     scope is a LOCATION decision by the user, never a content taxonomy; KB
+     created lazily with `.sources/` on the first agent-scope guide).
+2. **User confirms** the topic decomposition — including the fragmentation-risk
+   assessment and scope decision — before any file is written.
 3. **Snapshot each source verbatim** into
    `ai_docs/reference/.sources/<slug>-<hash8>.md`:
    - `slug` derives from the topic (lowercase, hyphenated).
@@ -158,3 +166,5 @@ state it explicitly when handing off a newly created guide.
   compares each guide's recorded `source_hash` against the live snapshot file
   and reports `[stale]` when they diverge — that is the signal to regenerate,
   not a manual freshness check.
+- **Agent-global KB guides** use the same pipeline and validator via
+  `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.

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

@@ -0,0 +1,57 @@
+# Code Review Discipline
+
+Applies at closure of L2/L3 work, and to any independent review slot in this
+skill or in a connected governance layer — devPNT's §4.5/§4.6 review gates,
+and any future review step added to the workflow. This is the single
+definition of how to request, receive, and perform a review; other places
+that need review behavior point here instead of restating it (DRY).
+
+## Requesting
+
+When you hand work to a reviewer (human or agent), give them:
+
+- **Scope**: what changed and why, in one or two lines.
+- **The authoritative design artifact**: the ANALYSIS, E-TDD, or equivalent
+  the change was built against — not a paraphrase of it.
+- **The actual diff**: the real changed files, not a description of them.
+
+Never ask a reviewer to "review my session" or "review what I just did"
+without the artifacts above — that forces them to reconstruct scope from
+conversation instead of reviewing the change itself. Say which finding
+classes you want covered (correctness, security, conformance to the design,
+test coverage) if the default scope is not obvious.
+
+## Receiving
+
+**MUST answer findings one by one — fix, or justify with evidence; why:
+silent drops turn review into theater** — a review whose findings are not
+tracked to a resolution gives the appearance of quality control without its
+substance.
+
+If you disagree with a finding, say so explicitly with your reasoning; never
+resolve a disagreement by rewording the finding until it goes away. When the
+project keeps a `REVIEW_LOG` (or equivalent), log the outcome of each
+finding there.
+
+## Reviewing
+
+When you are the reviewer:
+
+- Verify claims against the real source, not against the diff's own
+  description of itself.
+- Cite evidence as `file:line` for every finding — a finding without a
+  location is not actionable.
+- Keep severity honest: do not inflate a style preference to a blocker, and
+  do not soften a real correctness or security issue to a nit.
+- No praise padding. A review reports problems and their fixes, not a
+  summary of what looks fine.
+
+## Anti-patterns
+
+- **Batch-dismissal**: closing out a whole findings list with one blanket
+  reply instead of addressing each finding individually.
+- **Rewording instead of addressing**: editing the finding's text to look
+  resolved without changing the code or providing evidence it is a
+  non-issue.
+- **Scope-creep findings**: raising issues unrelated to the change under
+  review instead of filing them separately.

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

@@ -55,6 +55,10 @@ GUIDE_INDEX_HEADER = ("<!-- GENERATED by sdlc_check.py index - do not edit by ha
 GUIDE_PROVENANCE_KEYS = ("source", "distilled_from", "source_hash")  # source_version optional
 # a guide section is "covered" when it carries a source marker or an explicit gap marker
 GUIDE_MARKER_RE = re.compile(r"\[(?:source:[^\]]+|not covered by source)\]")
+# Agent-global KB (Feature B unit 2): ONE client-agnostic root under home.
+# AGENTIC_SDLC_KB_ROOT env var is a TEST/CI seam only (scenario battery must
+# not touch the real user KB); the documented product path is fixed.
+DEFAULT_KB_ROOT = Path(os.environ.get("AGENTIC_SDLC_KB_ROOT", "")) if os.environ.get("AGENTIC_SDLC_KB_ROOT") else Path.home() / ".agentic-sdlc"
 
 # Deprecated Italian frontmatter keys, mapped to the canonical English ones.
 LEGACY_KEYS = {"stato": "status", "livello": "level",
@@ -387,6 +391,38 @@ def list_guides(root):
     return out
 
 
+def check_kb_collisions(root, project_guides, errors, warnings):
+    """Cross-root awareness (unit 2): project-wins precedence, declared via 'overrides:'."""
+    kb_root = DEFAULT_KB_ROOT
+    kb_ref = (kb_root / "ai_docs" / "reference")
+    try:
+        if root.resolve() == kb_root.resolve():
+            return  # validating the KB itself: no self-comparison
+    except OSError:
+        return
+    if not kb_ref.is_dir():
+        return  # no KB on this machine: zero behavior change
+    kb_names = {p.name for _, p, _, _ in list_guides(kb_root)}
+    for rel, p, meta, _ in project_guides:
+        ov = (meta.get("overrides") or "").strip()
+        if ov:
+            # T6: untrusted cross-root pointer — distilled_from parity, fail closed
+            ovp = Path(ov)
+            if ovp.is_absolute() or ".." in ovp.parts:
+                errors.append(f"{rel}: overrides '{ov}' is absolute or contains '..' — rejected (fail closed)")
+                continue
+            try:
+                target = (kb_ref / ov).resolve()
+                target.relative_to(kb_ref.resolve())
+            except (ValueError, OSError):
+                errors.append(f"{rel}: overrides '{ov}' escapes the KB reference dir — rejected (fail closed)")
+                continue
+            if not target.is_file():
+                warnings.append(f"{rel}: overrides target '{ov}' not found in KB ({kb_ref})")
+        if p.name in kb_names and ov != p.name:
+            warnings.append(f"{rel}: undeclared collision with KB guide '{p.name}' (project wins) — declare overrides: {p.name}")
+
+
 def build_guide_index(root):
     lines = [GUIDE_INDEX_HEADER,
              "# Operative guides (generated router)",
@@ -545,6 +581,7 @@ def cmd_validate(root, strict=False):
                     target.relative_to(root.resolve())
                 except ValueError:
                     errors.append(f"{rel}: distilled_from '{df}' resolves outside the project root: rejected")
+    check_kb_collisions(root, guides, errors, warnings)
     # guide-router alignment (mirror of the root-manifest check)
     gidx = root / "ai_docs" / "reference" / "INDEX.md"
     if guides:

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

@@ -0,0 +1,59 @@
+# TDD Discipline
+
+Applies to L2/L3 implementation work. L1, doc-only changes, and Spikes are
+exempt (a Spike records its outcome note only, per `SPIKE_[topic].md`).
+
+## The loop
+
+RED, GREEN, REFACTOR, in that order, every time.
+
+- **RED**: write ONE failing test first, run it, and watch it fail. **MUST:
+  no implementation code before the failing test exists; why: a test written
+  after the code passes vacuously and proves nothing** — it cannot
+  distinguish a correct implementation from a broken one, because it was
+  shaped to match whatever the code already does.
+- **GREEN**: write the minimum code needed to make that test pass. Resist
+  adding behavior the test does not require yet — that belongs to the next
+  loop.
+- **REFACTOR**: clean up implementation and test code while the suite stays
+  green. Re-run the tests after every refactor step, not just at the end.
+
+## Increment rule
+
+One behavior per loop. If you notice the failing test actually covers two
+behaviors, split it before writing implementation code — a test that asserts
+two unrelated things fails ambiguously and slows down the next RED step.
+
+## Test shape
+
+Unit tests follow AAA — arrange, act, assert:
+
+- **Arrange**: set up inputs, fixtures, and collaborators.
+- **Act**: invoke the one behavior under test.
+- **Assert**: check the outcome, and only that outcome.
+
+Keep the three parts visually separable (blank line or comment) so a reader
+can tell what is setup, what is the trigger, and what is being checked
+without tracing the whole test body. This is the single home of the AAA
+guidance — do not restate it elsewhere in the skill.
+
+## When TDD does not apply
+
+Legitimate exemptions: no test harness exists for the target environment,
+the change is pure documentation, or the work is a time-boxed Spike.
+
+**MUST record the explicit reason in the ANALYSIS Diary or Action Plan node;
+why: an unrecorded exemption is indistinguishable from forgetting** — a
+reviewer (or a future you) cannot tell "skipped on purpose, here is why" from
+"skipped by accident" unless the reason is written down at the time.
+
+## Anti-patterns
+
+- **Tests-after as the unexplained default**: writing implementation first
+  and tests afterward without an entry under "When TDD does not apply" above.
+- **Testing implementation details**: asserting on private state or call
+  internals instead of observable behavior — the test breaks on refactors
+  that change nothing externally.
+- **One giant test covering everything**: a single test that exercises
+  multiple behaviors is slow to diagnose when it fails and violates the
+  Increment rule above.

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

@@ -40,6 +40,7 @@ source: Human-readable name of what the user provided.
 source_version: v1.2          # optional — only when the origin is versioned
 distilled_from: ai_docs/reference/.sources/topic-a1b2c3d4.md
 source_hash: <sha256 of the snapshot file>
+overrides: GUIDE_topic.md   # optional — only for a project guide overriding an agent-KB guide
 ---
 # Guide: [Topic]