@antoneeo/agentic-sdlc-skill 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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).
+- **`sdlc_check.py plan` subcommand**: `plan validate` (schema check of the executable plan, fail-closed path/guide confinement, sidecar-ledger cross-check — "no valid plan, no dispatch") and `plan brief --task <id>` (emits, to stdout, the task + prior-task interfaces + guide pointers). The validator is **zero-execution**: a task's `verify` command is emitted as text, never run.
+- **Executable-plan template** (`ai_docs/solutions/PLAN_[feature].md`) in `templates.md`: Markdown frontmatter (`status`, `derived-from`) + a fenced `json` task array + the sidecar `PLAN_[feature].ledger.json` shape (`task_id -> {status, verify_result, timestamp}`, git-tracked, survives compaction).
+- **`SKILL.md` §4** opt-in subagent-execution hook + the Hybrid `derived-from` seam (the plan is derived from the accepted E-TDD, never independently authored).
+- `test_plan.py`: stdlib-`unittest` battery for the `plan` subcommand (32 cases: schema, confinement, ledger, fail-fast JSON, zero-execution poka-yoke).
+
+### Changed
+- **`confine_under(base, rel)` extracted** in `sdlc_check.py`: the fail-closed path-confinement pattern (absolute/`..`/resolve-escape → reject), previously inlined twice (the `overrides:` and `distilled_from` checks), is now a single helper reused by both plus the new plan-path / guide-pointer confinement. Behavior-preserving (catches `(ValueError, OSError)`).
+
+### Process note
+- 4th live **model-per-dispatch** run (economy implementer from the E-TDD shadow, battery 32/32, deep code review PASS zero BLOCK). Governance: M-VISION → D-UC → P-TM → E-ISP → E-TDD, all through the independent review gate — which killed 3 real BLOCKs at design time (T1 subprocess-invariant misstatement, a missing impacted file, a `confine_under` OSError-crash regression). ADR `adr_2026-07-03_executable_plan_json_in_md`.
+
 ## [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.

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`, `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.
+- **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`, `dispatch.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
@@ -49,6 +49,7 @@ skills/agentic-sdlc-skill/
 ├── debugging.md
 ├── elicitation.md
 ├── review.md
+├── dispatch.md
 ├── ENFORCEMENT.md
 └── scripts/
     └── sdlc_check.py

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.9.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.9.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",
@@ -32,6 +32,7 @@
     "skills/agentic-sdlc-skill/debugging.md",
     "skills/agentic-sdlc-skill/elicitation.md",
     "skills/agentic-sdlc-skill/review.md",
+    "skills/agentic-sdlc-skill/dispatch.md",
     "skills/agentic-sdlc-skill/ENFORCEMENT.md",
     "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
     "gemini-extension.json",

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,18 +193,22 @@ 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.
 - Update the ANALYSIS Diary or the Action Plan when you complete milestones, hit blockers or change decisions.
+- **Opt-in subagent execution**: for an L3 with an approved design, the orchestrator MAY execute the work via subagents per `dispatch.md`, gated by `sdlc_check.py plan validate` ("no valid plan, no dispatch"); default stays same-session. Hybrid: the executable `PLAN_[feature].md` is `derived-from` the accepted E-TDD, never independently authored.
 
 ### 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.
+- 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;
@@ -215,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
 
@@ -243,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`.
@@ -264,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

@@ -0,0 +1,85 @@
+# Subagent Execution Discipline
+
+Opt-in orchestration for L3 work with an approved design: the orchestrator
+drives a `PLAN_[feature].md` through subagents instead of implementing every
+task in the same session. Default stays same-session; this is an escalation,
+never a requirement.
+
+## Trigger
+
+Only for L3 (an approved E-TDD in Hybrid, or an ANALYSIS Action Plan in
+Standalone). Never for L1/L2 — the plan/ledger machinery is overhead a small
+change does not need. The plan is always `derived-from` the accepted design:
+it is never independently authored, exactly like an E-TDD is never authored
+without an E-ISP.
+
+## The loop
+
+1. `sdlc_check.py plan validate PLAN_[feature].md` — zero-execution schema +
+   confinement + ledger cross-check. Non-zero exit = **no dispatch**. This is
+   the hard gate: "no valid plan, no dispatch."
+2. For each task, in plan order:
+   - Read the task's status from the sidecar ledger
+     (`PLAN_[feature].ledger.json`). `status: done` (exact sentinel) → skip,
+     never re-dispatch. Anything else (pending, failed, missing, or a
+     corrupt-but-parseable entry) → treat as pending and dispatch.
+   - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
+     task block, the `produces` of prior-order tasks (interfaces), and
+     `guides` pointers (paths, never pasted content) to stdout.
+   - Spawn the subagent with that brief as its entire context window.
+   - Run `task.verify` out of band (the orchestrator executes it — the
+     validator only ever prints it, never runs it) plus the one-shot review
+     below.
+   - 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.
+- After **two** consecutive `verify_result: fail` on the same task: escalate
+  to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
+  first failure — a single fail is often a brief or environment issue, not a
+  capability gap.
+
+## Review slots — one-shot, not iterative
+
+Exactly three review touches per task, never a loop:
+
+1. Inline self-review by the implementer subagent before it reports done
+   (the standard critical-review pass, not a separate call).
+2. One reviewer pass per task (Hybrid: reuse the devPNT code-review gate;
+   Standalone: the `review.md` discipline).
+3. One broad final pass over the whole plan at closure, after all tasks are
+   DONE — catches cross-task drift a per-task review cannot see.
+
+If a review FAILs, fix and re-run `verify` — that is a normal loop iteration
+via the ledger's fail path, not an extra review slot.
+
+## Ledger protocol summary
+
+Read → skip-if-done → dispatch-if-pending → write. The ledger is the only
+memory the loop needs across sessions or context compaction: a resumed
+orchestrator re-reads it and picks up exactly where it left off, never
+re-running a DONE task.
+
+## Degradation
+
+No subagent-spawning tool available → the orchestrator runs each task in the
+same session, against the same plan and ledger, with the same one-shot review
+slots. No capability is lost, only the parallelism/isolation subagents would
+have added.
+
+## Hybrid note
+
+The plan's `derived-from` points at the accepted E-TDD document key. Per-task
+review reuses the devPNT independent reviewers (§4.6 code review gate) rather
+than restating review doctrine — see `review.md` for the single definition
+both modes share.

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

@@ -59,6 +59,9 @@ GUIDE_MARKER_RE = re.compile(r"\[(?:source:[^\]]+|not covered by source)\]")
 # 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"
+# Subagent Execution (Feature A): a PLAN_[feature].md task must carry these keys,
+# plus at least one of paths/produces (checked separately in cmd_plan).
+PLAN_TASK_REQUIRED = ("id", "title", "verify")
 
 # Deprecated Italian frontmatter keys, mapped to the canonical English ones.
 LEGACY_KEYS = {"stato": "status", "livello": "level",
@@ -82,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():
@@ -106,6 +123,25 @@ def require_ai_docs(root, command):
     return True
 
 
+def confine_under(base, rel):
+    """Fail-closed path confinement: resolve `rel` under `base` and require the
+    result to stay inside `base`. Returns None (reject) if `rel` is absolute,
+    contains a '..' part, or resolves outside `base` (including an OSError
+    during resolution, e.g. an unresolvable/reparse-point path on Windows).
+    Single source for path confinement (T2/T3): reused by check_kb_collisions'
+    `overrides:` check and cmd_validate's `distilled_from` check, and by the
+    new `plan` command's paths/consumes/produces/guides confinement."""
+    p = Path(rel)
+    if p.is_absolute() or ".." in p.parts:
+        return None
+    try:
+        t = (base / rel).resolve()
+        t.relative_to(base.resolve())
+        return t
+    except (ValueError, OSError):
+        return None
+
+
 def read_text(path):
     # utf-8-sig: strips a leading BOM (files authored on Windows) so the
     # frontmatter '---' on line 0 stays recognizable; reads plain utf-8 otherwise.
@@ -407,15 +443,10 @@ def check_kb_collisions(root, project_guides, errors, warnings):
         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)")
+            target = confine_under(kb_ref, ov)
+            if target is None:
+                errors.append(f"{rel}: overrides '{ov}' is absolute, contains '..', or 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})")
@@ -572,15 +603,9 @@ def cmd_validate(root, strict=False):
                             + "; ".join(unmarked[:5]))
         # (c) distilled_from confinement — fail closed (P-TM T6, distilled_from vector)
         df = meta.get("distilled_from", "")
-        if df:
-            if Path(df).is_absolute() or ".." in Path(df).parts:
-                errors.append(f"{rel}: distilled_from '{df}' is absolute or escapes the project (..): rejected")
-            else:
-                target = (root / df).resolve()
-                try:
-                    target.relative_to(root.resolve())
-                except ValueError:
-                    errors.append(f"{rel}: distilled_from '{df}' resolves outside the project root: rejected")
+        if df and confine_under(root, df) is None:
+            errors.append(f"{rel}: distilled_from '{df}' is absolute, contains '..', or 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"
@@ -806,6 +831,226 @@ def cmd_gate(args):
     return 2
 
 
+# --------------------------------------------------------------------- plan
+# Subagent Execution (Feature A). Zero-execution surface: this section and
+# everything it calls MUST NOT spawn a process (no subprocess/os.system/eval/
+# exec, no git_* helper). It validates a PLAN_[feature].md and prints a task
+# brief as text; the orchestrator (dispatch.md) is the sole executor.
+
+_PLAN_JSON_RE = re.compile(r"```json\s*\n(.*?)```", re.DOTALL)
+
+
+def extract_plan_json(text):
+    """Extract the first fenced ```json block from a PLAN_[feature].md body.
+    Returns (data, "") on success, or (None, reason) on any failure. Never
+    raises: a malformed or missing block is a validation failure, not a crash."""
+    m = _PLAN_JSON_RE.search(text or "")
+    if not m:
+        return None, "no fenced ```json block found in the plan file"
+    try:
+        data = json.loads(m.group(1))
+    except (ValueError, TypeError) as e:
+        return None, f"malformed JSON in the plan block: {e}"
+    if not isinstance(data, dict):
+        return None, "plan JSON block must be a JSON object"
+    return data, ""
+
+
+def load_ledger(path):
+    """Read the sidecar ledger {"<task_id>": {"status", "verify_result",
+    "timestamp"}}. Absent file -> ({}, ""). Malformed/unreadable -> ({}, reason).
+    Never raises, never hangs: the ledger is untrusted state read on every call."""
+    if not path.is_file():
+        return {}, ""
+    try:
+        raw = read_text(path)
+        data = json.loads(raw)
+    except (ValueError, TypeError, OSError) as e:
+        return {}, f"ledger '{path}' unreadable/malformed, treating as empty: {e}"
+    if not isinstance(data, dict):
+        return {}, f"ledger '{path}' is not a JSON object, treating as empty"
+    return data, ""
+
+
+def _confine_or_reject(base, rel, label, rel_label, errors):
+    t = confine_under(base, rel)
+    if t is None:
+        errors.append(f"{rel_label}: {label} '{rel}' is absolute, contains '..', or escapes "
+                      f"'{base}' — rejected (fail closed)")
+    return t
+
+
+def _validate_plan_tasks(root, data, rel_label, errors, warnings):
+    """Shared core of `plan validate`/`plan brief`: schema + confinement checks.
+    Returns the task list (possibly empty) on success; errors/warnings are
+    appended in place. Callers decide the exit code."""
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list) or not tasks:
+        errors.append(f"{rel_label}: 'tasks' must be a non-empty JSON array")
+        return []
+    ref_dir = root / "ai_docs" / "reference"
+    kb_ref = DEFAULT_KB_ROOT / "ai_docs" / "reference"
+    seen_ids = set()
+    for i, task in enumerate(tasks):
+        loc = f"{rel_label}: task[{i}]"
+        if not isinstance(task, dict):
+            errors.append(f"{loc}: not a JSON object")
+            continue
+        missing = [k for k in PLAN_TASK_REQUIRED if not task.get(k)]
+        if missing:
+            errors.append(f"{loc}: missing required field(s): {', '.join(missing)}")
+        if not task.get("paths") and not task.get("produces"):
+            errors.append(f"{loc}: must declare at least one of 'paths'/'produces'")
+        tid = task.get("id")
+        if tid:
+            if tid in seen_ids:
+                errors.append(f"{loc}: duplicate task id '{tid}'")
+            seen_ids.add(tid)
+        for key in ("paths", "consumes", "produces"):
+            for p in (task.get(key) or []):
+                _confine_or_reject(root, p, key, loc, errors)
+        for g in (task.get("guides") or []):
+            in_project = confine_under(ref_dir, g)
+            in_kb = confine_under(kb_ref, g)
+            if in_project is None and in_kb is None:
+                errors.append(f"{loc}: guide '{g}' is not confined under the project reference "
+                              f"dir ({ref_dir}) or the agent KB reference dir ({kb_ref}) — rejected")
+    return tasks
+
+
+def cmd_plan(root, args):
+    """Zero-execution: validates/briefs a PLAN_[feature].md. Never spawns a
+    process, never calls a git_* helper, never runs the opaque `verify` text —
+    it is printed, not executed."""
+    plan_path = Path(args.file)
+    if not plan_path.is_absolute():
+        plan_path = root / plan_path
+    if not plan_path.is_file():
+        sys.stderr.write(f"[plan] plan file not found: {plan_path}\n")
+        return 2
+    rel_label = str(plan_path)
+    data, reason = extract_plan_json(read_text(plan_path))
+    if data is None:
+        sys.stderr.write(f"[plan] {rel_label}: {reason}\n")
+        return 2
+
+    errors, warnings = [], []
+    tasks = _validate_plan_tasks(root, data, rel_label, errors, warnings)
+
+    ledger_path = plan_path.with_name(plan_path.stem + ".ledger.json")
+    ledger, ledger_reason = load_ledger(ledger_path)
+    if ledger_reason:
+        warnings.append(ledger_reason)
+    if not errors:
+        task_ids = {t.get("id") for t in tasks if isinstance(t, dict)}
+        for lid in ledger:
+            if lid not in task_ids:
+                warnings.append(f"ledger id '{lid}' not found in {rel_label}: orphaned entry (not fatal)")
+
+    for w in warnings:
+        sys.stderr.write(f"[warn] {w}\n")
+    for e in errors:
+        sys.stderr.write(f"[ERROR] {e}\n")
+
+    if args.plan_cmd == "validate":
+        if errors:
+            sys.stderr.write(f"\n[plan] validate: {len(errors)} errors, {len(warnings)} warnings.\n")
+            return 2
+        print(f"[ok] {rel_label}: plan valid ({len(tasks)} task(s), {len(warnings)} warning(s)).")
+        return 0
+
+    # brief
+    if errors:
+        sys.stderr.write(f"\n[plan] brief: plan is invalid, refusing to brief ({len(errors)} errors).\n")
+        return 2
+    target = None
+    for t in tasks:
+        if isinstance(t, dict) and t.get("id") == args.task:
+            target = t
+            break
+    if target is None:
+        sys.stderr.write(f"[plan] brief: task id '{args.task}' not found in {rel_label}\n")
+        return 2
+
+    print(f"# Task: {target.get('id')} — {target.get('title', '')}")
+    print()
+    print("## Task block")
+    print(json.dumps(target, indent=2))
+    print()
+    print("## Produces of prior-order tasks (interfaces)")
+    prior_produces = []
+    for t in tasks:
+        if not isinstance(t, dict):
+            continue
+        if t.get("id") == target.get("id"):
+            break
+        prior_produces.extend(t.get("produces") or [])
+    if prior_produces:
+        for p in prior_produces:
+            print(f"- {p}")
+    else:
+        print("(none)")
+    print()
+    print("## Guide pointers (paths, not content)")
+    guides = target.get("guides") or []
+    if guides:
+        for g in guides:
+            print(f"- {g}")
+    else:
+        print("(none)")
+    print()
+    print("## Verify (opaque text — orchestrator runs this out of band, NOT executed here)")
+    print(target.get("verify", ""))
+    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):
@@ -836,9 +1081,23 @@ 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)
+    pv = pp_sub.add_parser("validate", help="schema + confinement + ledger cross-check (exit 2 on error)")
+    pv.add_argument("file", help="path to the PLAN_[feature].md file")
+    pb = pp_sub.add_parser("brief", help="print a task's brief to stdout (verify text is NOT executed)")
+    pb.add_argument("file", help="path to the PLAN_[feature].md file")
+    pb.add_argument("--task", required=True, help="task id to brief")
+
     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":
@@ -851,6 +1110,8 @@ def main(argv=None):
         return cmd_stale(root, hybrid=args.hybrid)
     if args.cmd == "mark":
         return cmd_mark(root, args.paths)
+    if args.cmd == "plan":
+        return cmd_plan(root, args)
     return 0
 
 

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

@@ -189,6 +189,54 @@ Allowed frontmatter states: `PLANNED` | `IN_PROGRESS` | `COMPLETED` | `CANCELLED
 <!-- max 1 page. Spike code is NOT mergeable: for production reclassify L2/L3. -->
 ```
 
+## ai_docs/solutions/PLAN_[feature].md
+
+Opt-in, L3 only (see `dispatch.md`): the executable task list an orchestrator
+drives through subagents. It is `derived-from` the accepted E-TDD (Hybrid) or
+the ANALYSIS Action Plan (Standalone) — never independently authored. The
+validator gate is `sdlc_check.py plan validate PLAN_[feature].md` ("no valid
+plan, no dispatch").
+
+````markdown
+---
+status: DRAFT
+derived-from: e_tdd_[feature] vX.Y
+---
+# Plan: [Feature]
+
+```json
+{
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Add the confine_under helper",
+      "paths": ["skills/agentic-sdlc-skill/scripts/sdlc_check.py"],
+      "consumes": [],
+      "produces": ["skills/agentic-sdlc-skill/scripts/sdlc_check.py#confine_under"],
+      "verify": "python skills/agentic-sdlc-skill/scripts/test_plan.py",
+      "guides": ["GUIDE_python_style.md"]
+    }
+  ]
+}
+```
+````
+
+Task fields: `id`/`title`/`verify` are required; at least one of `paths`/
+`produces` is required. `paths` are files the task touches; `consumes`/
+`produces` declare interfaces between tasks (what an earlier task hands to a
+later one); `guides` are pointers (paths, not pasted content) into
+`ai_docs/reference/` or the agent-global KB. All path-shaped fields are
+confined fail-closed under the project root (or the reference/KB root for
+`guides`) — an absolute path or a `..` escape is rejected. `verify` is opaque
+text: the validator only prints it (`plan brief`), never runs it — the
+orchestrator executes it out of band.
+
+Sidecar ledger `ai_docs/solutions/PLAN_[feature].ledger.json` (orchestrator-
+owned, validator-read-only): `{ "<task_id>": {"status": "done", "verify_result":
+"pass", "timestamp": "2026-07-03T00:00:00Z"} }`. Only the exact `status: done`
+sentinel skips re-dispatch; any other value (or a missing `status`) is treated
+as pending. A ledger id absent from the plan is a non-fatal orphan warning.
+
 ## ai_docs/audit/audit_plan.md (Standalone mode only)
 
 The `Reference` field (git hash or ISO UTC timestamp) is managed by `sdlc_check.py mark` — do not fill it by hand. Freshness is verified with `sdlc_check.py stale`.