@antoneeo/agentic-sdlc-skill 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [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.
+- `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`, `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
@@ -45,6 +45,11 @@ skills/agentic-sdlc-skill/
 ├── SKILL.md
 ├── templates.md
 ├── guides.md
+├── tdd.md
+├── 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.8.1",
+  "version": "1.10.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.10.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,11 @@
     "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/dispatch.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,17 @@ 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.
+- **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.
 - 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 +258,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/dispatch.md

@@ -0,0 +1,77 @@
+# 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.
+
+## 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/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,13 @@ 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"
+# 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",
@@ -102,6 +109,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.
@@ -387,6 +413,33 @@ 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
+            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})")
+        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)",
@@ -536,15 +589,10 @@ 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"
     if guides:
@@ -769,6 +817,179 @@ 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
+
+
 # --------------------------------------------------------------------- main
 
 def main(argv=None):
@@ -799,6 +1020,15 @@ 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\")")
 
+    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)
@@ -814,6 +1044,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/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]
 
@@ -188,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`.