@antoneeo/agentic-sdlc-skill 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.11.0] - 2026-07-03 (M4: Consolidation & Proactive Activation — self-activating, self-consulting, self-testing skill)
+### Added
+- **SessionStart orientation hook** (`sdlc_check.py orient`): emits a bounded, repo-sourced orientation (README + INDEX + guide router + handoff + Rule-Zero triage) at session start. Zero-execution, **fail-OPEN** (a missing/empty `ai_docs/` never blocks the session), size-capped. Manual per-client wiring in `ENFORCEMENT.md` §4; `--hybrid` points at the devPNT bootstrap instead of duplicating plan/KL. `test_session_start.py` (9 cases).
+- **Guide-layer consumption** (closes the write-only gap — Layer D "point to them"): a **consult trigger** (before operative L2/L3 work, targeted router match, L1 exempt, never blanket) and a **proactive-creation trigger** (propose a guide after user-indication-governed reusable work; never silent, never from model knowledge). Mechanics in `guides.md` §0/§1; hooked from `SKILL.md` Operative Guides + Phase 4/5; reconciled with subagent dispatch in `dispatch.md`.
+- **Worktree/branch hygiene** in the closure discipline (`SKILL.md` Phase 4 isolate-on-branch / Phase 5 merge-decision + cleanup).
+- **Skill eval harness** (dev-only, not shipped): `test_skill_invariants.py` is the deterministic static release gate (`python -m unittest discover -s scripts -p "test_*.py"` — asserts the skill's own doctrine invariants: triggers/hook/worktree present and wired, indexes idempotent, support pointers resolve; zero LLM/network/subprocess). Opt-in behavioral corpus `evals/scenarios/` + `run_behavioral.py` (non-CI, never gates). `ENFORCEMENT.md` §5.
+
+### Process note
+- Full governance per unit: M-VISION v2.1 (revised — added the guide-consumption unit) → D-UC + P-TM → per-unit E-ISP (deep review) + E-TDD (light review) → implement → §4.6 code review. The independent-review gate caught real defects at design time (incomplete eval invariant set, the M3↔M4 dispatch interaction, a REPO path off-by-one, a P-TM overclaim of unbuilt guards). Battery 51/51 green. ADR `adr_2026-07-03_skill_eval_harness`; KL architecture v1.4 + principles v1.2.
+
 ## [1.10.0] - 2026-07-03 (M3: Subagent Execution / Feature A — opt-in executable plan)
 ### Added
 - **`dispatch.md`**: subagent-execution doctrine (opt-in for L3). The dispatch loop — validate the plan → per-task brief → economy-tier implementer → one-shot review → ledger — with client-relative model tiers (no provider names), one-shot review slots (no iterative loops), degradation to same-session where subagents do not exist, and guides injected by pointer (never pasted).

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.10.0",
+  "version": "1.11.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.10.0",
+  "version": "1.11.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",

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

@@ -54,3 +54,55 @@ Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the mess
 - `ai_docs/`, `tests/` and `test/` are always excluded from blocking.
 - The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
 - **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see the SKILL.md shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.
+
+## 4. SessionStart hook (orientation, optional)
+
+Emits the `ai_docs/` orientation — reading guide (`README.md`), manifest (`INDEX.md`), guide router (`reference/INDEX.md`) and last `handoff.md` — plus the Rule-Zero triage reminder to stdout at session start, so the agent begins already oriented instead of reading them only if it remembers to. It is **fail-open**: a missing, unreadable or oversized doc is skipped, the output is size-capped, and it always exits 0 — a broken or empty `ai_docs/` never blocks the session. It is **zero-execution** (it reads and prints, never runs anything) and opt-in.
+
+Wire it via each client's SessionStart mechanism — the same command everywhere (add `--hybrid` on devPNT/Hybrid projects):
+
+Claude Code — in the project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" orient"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex — in `.codex/hooks.json`, the same `SessionStart` → `{"type":"command","command":"… orient"}` shape (this replaces the legacy static-echo protocol some fixtures still carry).
+
+Gemini CLI — wire the same command into its startup-hook mechanism if present; otherwise the step simply degrades to the manual Phase-1 reads (no capability lost).
+
+**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 `sdlc_check.py` into the repo, the hook references that copy — keep it current when you update the skill.
+
+## 5. Skill eval battery (release gate)
+
+The skill self-tests its own doctrine invariants. Two layers over one scenario corpus:
+
+**Static battery — the deterministic release gate.** Run before any publish:
+
+```
+python -m unittest discover -s skills/agentic-sdlc-skill/scripts -p "test_*.py"
+```
+
+It aggregates the three test files (`test_plan.py` + `test_session_start.py` + `test_skill_invariants.py`) and asserts the skill's invariants: the M4 triggers/hook/worktree doctrine is present and wired, support-file pointers resolve, and the generated indexes are idempotent. A non-zero exit **blocks the release** — a failing eval is always a real regression, never flakiness: the battery is stdlib-only, makes no model/network/subprocess call (deterministic by construction). If `test_indexes_idempotent` fails, run `sdlc_check.py index` and re-run.
+
+**Behavioral corpus — opt-in, non-CI.** `evals/scenarios/*.md` (declarative, model-neutral) + `evals/run_behavioral.py` seed a fixture and print a prompt + pass criteria for a human/agent to run and self-assess. Because live adherence is nondeterministic, this layer **never gates** — it is the reproducible way to check that, e.g., the consult trigger actually fires on a seeded repo (the "demonstrably" artifact).
+
+**Optional CI** (same shape as §2, not mandatory): add a `run:` step invoking the `unittest discover` command above.
+
+**T10 note:** if you copied `sdlc_check.py` and the `test_*.py` battery into the repo for CI, that copy is authoritative — keep it current when you update the skill.

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

@@ -156,6 +156,7 @@ gate) instead of requiring an IN_PROGRESS ANALYSIS.
 
 - Read `ai_docs/audit/handoff.md` if it exists; if its Date/Branch are inconsistent, treat it as history.
 - Read `ai_docs/README.md` (curated must-reads) and `ai_docs/INDEX.md` (generated manifest of all canonical docs) to know what exists before exploring the code. `solutions/` and `audit/` are not indexed per file: search them with glob/grep.
+- Optional: a SessionStart hook (`ENFORCEMENT.md` §4) can emit this orientation automatically at session start (README + INDEX + guide router + handoff + triage reminder); when it is not wired, do these reads manually as above. The hook is a convenience, never a requirement — it introduces no Python dependency for the process itself and fails open (a missing/empty `ai_docs/` never blocks the session).
 - If `ai_docs/` is missing or incomplete, create the structure and minimal documents by analyzing the project in batches.
 - In Standalone use `ai_docs/audit/audit_plan.md` for mapping and state.
 - In Hybrid prefer the devPNT/KL mapping when available; do not duplicate plan governance.
@@ -192,8 +193,10 @@ Hybrid L3:
 ### 4. Development and Testing
 
 - Implement only after the documentation gate required by the level.
+- Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree.
 - Modify surgically, consistently with the plan.
 - Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).
+- Before implementing (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first — the consult trigger (`guides.md` §0, summarized under `## Operative Guides`). A targeted description match, not a blanket read.
 - If the environment does not allow automated tests, declare the alternative verification and the reason.
 - 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.
@@ -205,6 +208,7 @@ Hybrid L3:
 - 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.
+- If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
 - Update only the documents actually impacted.
 - **Aligned indexes (Poka-Yoke)**: if you created, moved or removed canonical documents (`vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`):
   - regenerate the manifest with `sdlc_check.py index` (writes `ai_docs/INDEX.md`) — never write it by hand;
@@ -216,6 +220,7 @@ Hybrid L3:
 - In Hybrid propose ADR/KL updates when there were architectural decisions.
 - In Standalone, if the project adopts `sdlc_check.py`, run `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` or the equivalent local copy.
 - Updated documents must travel in the same commit/PR as the code they describe.
+- **Branch/worktree hygiene**: an L3 ran on its own branch (Phase 4) — close it with an explicit merge decision (merge, keep open, or discard) and clean up the branch/worktree; never leave orphan branches. In Hybrid, the running devPNT server locks `.devpnt/*.db`, so the merge is done from a separate git worktree or via a ref-only push, never an in-place branch switch in the primary worktree.
 
 ## ai_docs documents: two indexes + lifecycle
 
@@ -244,6 +249,11 @@ Legacy note: the validator also accepts the deprecated Italian frontmatter keys
 
 ## Operative Guides
 
+Guides are **consulted, created, and proposed** — three moments; the mechanics live once in `guides.md`:
+- **Consult (before acting):** before operative L2/L3 work (L1 exempt), check the guide router for a guide covering the task and read the match first — a targeted description match, never a blanket read. → `guides.md` §0.
+- **Create (from user indications):** the origin+purpose test below.
+- **Propose proactively (after success):** after reusable, user-indication-governed work, PROPOSE distilling a guide — a proposal, never a silent write, never from model knowledge. → `guides.md` §1.
+
 Trigger test: the user hands over indications to follow (origin = user, not model
 knowledge) meant to govern how the agent operates (purpose = operative), not just
 inform an answer. Both hold → distill into `ai_docs/reference/GUIDE_[topic].md`.
@@ -265,6 +275,7 @@ regenerate with `sdlc_check.py index`.
 The prompt is not enforcement. When the project needs repeatable guarantees:
 - read `ENFORCEMENT.md`;
 - use `scripts/sdlc_check.py validate --strict` in CI;
-- use `scripts/sdlc_check.py gate` only for security-critical directories, not for the whole repository.
+- use `scripts/sdlc_check.py gate` only for security-critical directories, not for the whole repository;
+- (skill development) the self-eval battery `python -m unittest discover -s scripts -p "test_*.py"` guards the skill's own doctrine invariants and is the deterministic release gate — see `ENFORCEMENT.md` §5.
 
 The validator is a support, not a universal prerequisite: the skill must stay usable in environments without Python or hooks, declaring what it cannot verify automatically.

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

@@ -33,6 +33,14 @@ without an E-ISP.
    - Write `{status, verify_result, timestamp}` back to the ledger. The
      validator never writes the ledger — single-writer, orchestrator-owned.
 
+**Guide consumption under dispatch.** Selecting each task's `guides` field IS the
+consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrator
+runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
+router) when populating `guides`. A dispatched context-free subagent does **NOT**
+run its own router consult — it reads the guide pointers handed to it in the
+brief. (Proactive guide-creation stays at closure — the same broad final pass
+below — so it needs no separate dispatch hook.)
+
 ## Model tiers (client-relative, no provider names)
 
 - Default dispatch: **economy** implementer tier.

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

@@ -17,6 +17,26 @@ when a task needs detail. Two levels, both produced by this pipeline:
 A guide that restates the source at length is as wrong as a fragmented one:
 completeness is guaranteed by the book level, economy by the synthesis level.
 
+## 0. Consuming a guide (consult before acting)
+
+Guides only pay off if they reach the work they govern. **Before operative work,
+proportional to triage** — L1 is exempt; engaged for L2/L3 — ask: *does a guide
+already cover how to do this well?*
+
+- **Scan the router, not the guides.** Read the when-to-consult descriptions in
+  the guide router `ai_docs/reference/INDEX.md` **and** the agent-KB router
+  `~/.agentic-sdlc/ai_docs/reference/INDEX.md` (if present). Match by topic.
+- **On a match, read that guide's synthesis whole** before acting (the snapshot
+  stays on demand via the section markers). No match → proceed normally.
+- **Targeted match, never blanket.** Open only the guide whose description fits
+  the task — never load every guide, which would reintroduce the exact token
+  cost the "point to them" model exists to avoid. The two-level model (compact
+  synthesis / verbatim snapshot) already bounds a single guide's cost.
+- **Under subagent dispatch** the consult happens at plan-authoring time (the
+  orchestrator populates each task's `guides` field); a context-free subagent
+  reads the pointers it was handed and does not run its own router lookup. See
+  `dispatch.md`.
+
 ## 1. When to trigger
 
 Trigger test is origin + purpose, not content taxonomy (no "is this technical
@@ -34,6 +54,20 @@ Never manufacture a guide from model knowledge. If the user asks for "a guide
 on X" without handing over source material, ask for the source first — a
 guide with no `distilled_from` is not this pipeline's output.
 
+### Proactive trigger (after reusable success)
+
+The trigger above is reactive (the user hands material over). It has a proactive
+twin: **after completing work that was governed by user-provided indications and
+is plausibly reusable** — it would prepare a future task — **PROPOSE** distilling
+a guide.
+
+- It is a **proposal to the user**, routed into this same pipeline (§2 onward):
+  the user confirms topic/scope before any file is written.
+- **Never a silent write, never from model knowledge.** If the work was not
+  governed by user-provided material there is nothing to distill — do not invent
+  a guide from general knowledge (the `distilled_from` fidelity constraint, §3,
+  is absolute). This adds a moment to PROPOSE, not a new writer.
+
 ## 2. Pipeline
 
 0. **Search before creating (DRY — one CURRENT guide per topic).** Before

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

@@ -85,6 +85,20 @@ except Exception:
     pass
 
 
+# --- orient (SessionStart hook) ---
+# Fixed, hard-coded doc set (label, path-relative-to-root). No content- or
+# user-derived paths -> no traversal input (P-TM T3); confine_under is
+# defense-in-depth. Emitted at session start by the orient subcommand.
+ORIENT_DOCS = [
+    ("Reading guide (README)", "ai_docs/README.md"),
+    ("Canonical manifest (INDEX)", "ai_docs/INDEX.md"),
+    ("Guide router (when-to-consult)", "ai_docs/reference/INDEX.md"),
+    ("Last session handoff", "ai_docs/audit/handoff.md"),
+]
+ORIENT_PER_DOC_CHARS = 6000     # per-doc truncation
+ORIENT_MAX_TOTAL_CHARS = 16000  # total ingestion cap (P-TM T2); tunable
+
+
 # ----------------------------------------------------------------- utilities
 
 def utc_now_iso():
@@ -990,6 +1004,53 @@ def cmd_plan(root, args):
     return 0
 
 
+def cmd_orient(args):
+    """SessionStart hook: emit a bounded, repo-sourced ai_docs/ orientation to
+    stdout and ALWAYS return 0 (fail-open, P-TM T8) -- a session hook must never
+    block the session or surface a traceback. Zero-execution (P-TM T1): reads a
+    fixed hard-coded doc set, confine_under each (P-TM T3), size-caps the total
+    (P-TM T2). No subprocess/eval anywhere in this call graph."""
+    try:
+        root = Path(args.root).resolve() if getattr(args, "root", None) else find_project_root()
+        chunks = []
+        total = 0
+        truncated = False
+        for label, rel in ORIENT_DOCS:
+            target = confine_under(root, rel)
+            if target is None or not target.is_file():
+                continue
+            try:
+                text = read_text(target)
+            except OSError:
+                continue
+            remaining = ORIENT_MAX_TOTAL_CHARS - total
+            if remaining <= 0:
+                truncated = True
+                break
+            text = text[:ORIENT_PER_DOC_CHARS]
+            if len(text) > remaining:
+                text = text[:remaining]
+                truncated = True
+            chunks.append((label, text))
+            total += len(text)
+        if not chunks:
+            return 0
+        out = ["=== Agentic SDLC -- session orientation (repo-sourced context, not authored instructions) ==="]
+        for label, text in chunks:
+            out.append(f"\n## {label}\n{text}")
+        if truncated:
+            out.append("\n[orientation truncated to the size cap -- open the files directly for full content]")
+        out.append("\nTriage every request (Rule Zero): L1 trivial - L2 small - L3 significant - Spike. "
+                   "When in doubt, pick the higher level.")
+        if getattr(args, "hybrid", False):
+            out.append("\n[devPNT active] Run devpnt_mcp_get_bootstrap for the Master Plan / Knowledge Layer -- "
+                       "the orientation above is the filesystem layer, not a bootstrap duplicate.")
+        print("\n".join(out))
+        return 0
+    except Exception:
+        return 0
+
+
 # --------------------------------------------------------------------- main
 
 def main(argv=None):
@@ -1020,6 +1081,9 @@ def main(argv=None):
     gp.add_argument("--file", help="file path to evaluate (alternative to --hook)")
     gp.add_argument("--protected", default="", help="protected prefixes separated by ';' (e.g. \"src/auth;src/crypto\")")
 
+    sub.add_parser("orient", parents=[common, hybrid_opt],
+                   help="SessionStart hook: emit ai_docs/ orientation to stdout (fail-open, zero-execution)")
+
     pp = sub.add_parser("plan", parents=[common],
                         help="Subagent Execution: validate/brief a PLAN_[feature].md (zero-execution)")
     pp_sub = pp.add_subparsers(dest="plan_cmd", required=True)
@@ -1032,6 +1096,8 @@ def main(argv=None):
     args = ap.parse_args(argv)
     if args.cmd == "gate":
         return cmd_gate(args)
+    if args.cmd == "orient":
+        return cmd_orient(args)
 
     root = Path(args.root).resolve() if args.root else find_project_root()
     if args.cmd == "check":