@antoneeo/agentic-sdlc-skill 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.28.0] - 2026-08-26
+
+F-038 — the gated rung: truthful log vocabulary and a mandated ask, no grant memory.
+
+### Fixed
+- **A review rung that exists behind a permission policy is no longer logged as
+  "unavailable".** The ladder knew two states (the client supports the rung, or not)
+  and hard-coded rung 3's reason as "no subagent facility on this client" — so a gated
+  facility produced false log rows, and the ladder's own prohibition ("rung 3 is
+  illegitimate wherever rung 1 or 2 exists") was unsatisfiable on a gated client: the
+  agent could not obey it without asking, and no rule said to ask.
+
+### Added
+- **The gated-rung stop.** At a due review gate (design; closure), when the best rung is
+  permission-gated (a standing policy — an interactive per-call prompt is NOT this) and
+  no ungated rung works (a working one-shot CLI pre-empts the stop; a gated rung 2 joins
+  the question instead), the gate stops and asks ONE question in the five-bullet blocking
+  form: the gated rung(s) vs the fallback, each higher rung's status, the quoted policy,
+  the cost (~130-175k subagent tokens per deep review, measured 2026-08) AND what
+  independence last bought, and what stays blocked. **No grant memory**: the answer holds
+  while the conversation does; an agent that cannot recall a grant asks again. Unattended
+  runs never emit the question — rung 2 is still owed a try, then rung 3 with its reason.
+  (Successor to a design CANCELLED at the review cap after grant memory failed three
+  ways; rulings r18/r19.)
+- **The reason words.** A below-rung-1 row says why the rung(s) above did not run:
+  `absent` (the client has no such facility — a claim about the client, never a policy),
+  `gated, declined`, `gated, unattended`, `gated, pre-empted` (nothing asked — an
+  ungated lower rung ran the review). A rung-1 row owes nothing. For rung 3 this
+  re-words an existing duty; for rung 2 it is a new one-word duty, disclosed and
+  accepted with the rest.
+
+## [1.27.1 / kb 1.5.1 / mkt 0.5.1] - 2026-08-25
+
+### Fixed
+- **The three README front pages did not mention the hook wiring that 1.27.0 added.**
+  `init` now changes what every project gets, and the README *is* the npm page, so two
+  of the three said nothing about it and the third barely did. Each now describes the
+  wiring, the settings.json / settings.local.json split and why it exists, and the
+  broken-hook report. `GUIDE_release.md` step 2 already made this a release duty; it was
+  skipped in 1.27.0 and this is the catch-up.
+- **`publish_all.bat`'s verify block reported the previous version after a successful
+  publish — twice.** `--prefer-online` (added in kb 1.4.8) forces revalidation but cannot
+  outrun CDN propagation of the `latest` tag in the seconds after publishing, so the
+  1.27.0 run printed mkt `0.4.7` when `0.5.0` had in fact landed. The flag alone was the
+  wrong fix and the note claiming otherwise is corrected: the block now **polls** each
+  package until the registry agrees with the local version, and prints both when it does
+  not, so "did it publish?" is answerable from the run instead of a manual `npm view`.
+
 ## [1.27.0 / kb 1.5.0 / mkt 0.5.0] - 2026-08-25
 
 F-036 — the orientation hook installs itself.

package/README.md

@@ -14,7 +14,7 @@
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **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, with independent fresh-context reviews of technical artifacts and diffs.
-- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when the first two are unavailable), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
+- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
 - **Question discipline**: a question to the user is legal only when the agent searched first and names the search with its result, and names the decision the answer unblocks. Otherwise it proceeds on a declared assumption — same evidence duty, batched, never a stream of "shall I proceed?".
 - **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `ENFORCEMENT.md`, and the validator's two files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py`.
 - **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`.
@@ -54,6 +54,19 @@ agentic-sdlc-init
 
 Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
 
+It also **wires the SessionStart orientation hook** into `.claude/`, so an agent opening
+the project is handed the reading guide, the generated manifest, the guide router and the
+last handoff before it does anything — instead of only when it remembers to look. That
+wiring used to be a manual step documented in `ENFORCEMENT.md`; being manual, it was
+skipped, and a project could run fully governed with an agent that never met the process.
+
+The hook command names a validator, so where that validator lives decides which file gets
+it: a repo that vendors it gets a repo-relative command in the shared `.claude/settings.json`
+(portable — commit it); otherwise the path is machine-specific and goes to the git-ignored
+`.claude/settings.local.json`, and each teammate runs `init` once. Re-running `init` never
+duplicates the hook, and a hook whose validator no longer resolves is reported as **broken**
+with the correction rather than counted as installed.
+
 ## Runtime Shape
 
 The actual runtime skill is the folder:

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.27.0",
+  "version": "1.28.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.27.0",
+  "version": "1.28.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",

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

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.27.0
+version: 1.28.0
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto

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

@@ -1,96 +1,98 @@
-# 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. The router verdict (Rule Zero) is therefore declared ONCE, by the
-orchestrator, when it authors the plan; a dispatched subagent does not declare
-one. (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.
-
-**The scoped re-review is a round INSIDE slot 2 or 3, never a fourth slot.**
-`review.md` §Receiving requires every review-driven correction to be
-re-reviewed against the correction alone — that round belongs to the slot whose
-findings caused it, and is bounded by the same cap of 3 rounds. "Never a loop"
-bounds the SLOTS (no unbounded re-reviewing of a task), not the rounds inside
-one slot: a fix nobody looked at is the defect the round exists to catch. Slot 1
-is the implementer's own pass, not an independent review, so its fixes carry no
-re-review round. The ledger records the round on the task's fail path as usual.
-
-## 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.
+# 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. The router verdict (Rule Zero) is therefore declared ONCE, by the
+orchestrator, when it authors the plan; a dispatched subagent does not declare
+one. (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.
+
+**The scoped re-review is a round INSIDE slot 2 or 3, never a fourth slot.**
+`review.md` §Receiving requires every review-driven correction to be
+re-reviewed against the correction alone — that round belongs to the slot whose
+findings caused it, and is bounded by the same cap of 3 rounds. "Never a loop"
+bounds the SLOTS (no unbounded re-reviewing of a task), not the rounds inside
+one slot: a fix nobody looked at is the defect the round exists to catch. Slot 1
+is the implementer's own pass, not an independent review, so its fixes carry no
+re-review round. The ledger records the round on the task's fail path as usual.
+
+## 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 — absent, or permission-gated with no grant
+in context (`review.md`'s gated-rung stop owns the asking; task dispatch never
+asks; the broad final pass IS `review.md` moment 2 and asks there) → 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/review.md

@@ -12,7 +12,7 @@ Two moments, and they review different things:
 |---|---|---|---|
 | **1. Design review** | End of Phase 3 — **before any implementation** | the ANALYSIS (Standalone) / the `E-ISP`+`E-TDD` (Hybrid) | L3 |
 | **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
-| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 row is optional |
+| **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 closure review is optional; every review that runs logs its row |
 
 **Why the design review is its own moment, and not a nicety.** The closure review
 can only tell you the code matches the design; it cannot tell you the design was
@@ -30,17 +30,56 @@ blind to it, which is why independence, not effort, is what this gate buys.
    a SELF-CONTAINED prompt — the reviewer session has no other context, which is
    exactly what makes it independent.
 3. **A declared self-pass** — a separate, explicitly adversarial pass by you,
-   against the same checklist. **Rung 3 is illegitimate wherever rung 1 or 2
-   exists**: on a client with a subagent facility or a one-shot CLI, descending to
-   it is choosing zero independence, which is the one thing this gate buys. When
-   you do use it, the log row must carry *why* — `self-pass (declared; no subagent
-   facility on this client)` — not merely that you did. A rung named without its
+   against the same checklist. **Rung 3 is illegitimate wherever a higher rung
+   is usable**: on a client with a working subagent facility or one-shot CLI,
+   descending to it is choosing zero independence, which is the one thing this
+   gate buys. A gated rung the user DECLINED is not usable — see *The gated
+   rung* below; a gated rung nobody asked about is not declined (unattended is
+   its own case below). When
+   you do use it, the log row must carry *why*, in the reason words below —
+   `self-pass (declared; absent — the client has no such facility)` — not merely
+   that you did. A rung named without its
    reason is indistinguishable from a rung chosen for convenience.
 
 Rung 3 stays in the ladder deliberately: it is what keeps the methodology
 completable with no network, no account and no subagent facility. It is a floor,
 never a default.
 
+**The gated rung — present is not absent (F-038).** A rung that exists behind a
+standing policy or instruction forbidding its use absent a user request is
+**permission-gated**, not unavailable. An interactive per-call approval prompt is
+NOT this: answering the prompt IS the grant. With an ungated rung usable — rung 1
+free, or a one-shot CLI that works (try it, or show it failed) — the prohibition
+above is already satisfiable and no stop fires (the row still carries
+`gated, pre-empted` when a gated rung sat above the one that ran); a gated
+rung 2 is not "usable" for this clause, it joins the question instead. When the best rung is gated and no
+ungated rung works, the gate STOPS and asks: descending to rung 3 on silence is
+illegal while a user is reachable. The stop is doctrine-mandated (legal by mandate,
+`elicitation.md` §Blocking is reserved) and carries that file's five-bullet
+blocking form — its closed-list exemption covers this file's round-cap hand-over
+only, not this stop. The question offers the gated rung(s) against the fallback, with what each
+buys; states each higher rung's status (tried / unusable / gated) with the
+standing instruction quoted and "no grant visible in my current context"; says
+why no assumption survives (assuming either way writes a false log row); says
+why it is the USER'S call — their tokens (~130-175k per deep review, measured
+2026-08) against a benefit only they can price, stated with what independence
+last bought; and names what stays blocked — which reviewer runs, nothing else.
+**No grant memory exists**: the answer holds while the conversation does, and an
+agent that cannot recall a grant asks again — one question per gate per intact
+context; re-asking is a smaller defect than a false row. Unattended
+(`elicitation.md`'s Unattended path — the user is not reachable), no question is
+emitted: rung 2 is still owed a try, then rung 3 runs with its reason logged.
+
+**The reason words.** A below-rung-1 row carries why the rung(s) above did not
+run; a rung-1 row owes nothing. `absent` — the client has no such facility (a
+claim about the client, never about a policy); `gated, declined` — usable only
+with the user's assent at this gate, and the user withheld it (a standing policy
+answered no, or a per-call prompt denied); `gated, unattended` — a standing policy
+gates it and no user is reachable to ask; `gated, pre-empted` — gated, nothing
+asked: an ungated lower rung ran the review instead. `gated` always appears with
+its outcome. The trigger term "permission-gated" scopes the STOP; the row word
+`gated` additionally covers a denied per-call prompt, which never triggers one.
+
 Use a different model from the author's where the client allows it.
 
 **Rounds are capped at 3.** FAIL → revise → re-review. If findings still stand

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

@@ -508,7 +508,7 @@ adds values to the existing columns rather than a second table.
 | date | doc_key | tier | reviewer | findings_raised | findings_real | verdict | revise_rounds |
 |---|---|---|---|---|---|---|---|
 | 2026-06-11 | ANALYSIS_login_sso.md | design | subagent (opus, fresh ctx) | 4 | 3 | FAIL → PASS | 2 |
-| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; no subagent facility) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
+| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; absent) | 2 | 2 | PASS with findings → corrections re-reviewed, PASS | 2 |
 
 ## Notes
 <!-- One short paragraph per review that found something worth remembering: what
@@ -523,9 +523,17 @@ and `closure` (Standalone); `deep`, `light`, `code`, `guide`, `vision` (devPNT g
 and the Vision blind check). The validator reads this column by its header name, so
 extra or reordered columns are fine — but the header must say `tier`. `reviewer`
 records the realization actually used — fresh subagent, one-shot client run, or a
-**declared** self-pass. Writing `self-pass` where independence was unavailable is
-honest; writing nothing, or implying independence you did not have, is the failure
-this column exists to prevent. `findings_real` is how many raised findings survived
+**declared** self-pass — and, for any rung below rung 1, WHY the rung(s) above did
+not run, in the ladder's reason words (`review.md`): `absent` — the client has no
+such facility (a claim about the client, never about a policy); `gated, declined` —
+usable only with the user's assent at this gate, withheld (a standing policy
+answered no, or a per-call prompt denied); `gated, unattended` — a standing policy
+gates it, no user reachable; `gated, pre-empted` — gated, nothing asked, an ungated
+lower rung ran the review. A rung-1 row owes nothing. `gated` here is the ROW
+word — it also covers a denied per-call prompt, which never triggers `review.md`'s
+stop. Writing `self-pass` with its
+true reason is honest; writing nothing, or implying independence you did not have,
+is the failure this column exists to prevent. `findings_real` is how many raised findings survived
 triage: over time it is the only evidence of whether the gate earns its cost.
 `revise_rounds` counts **review rounds**, not fix cycles: the first review is round 1
 and every scoped re-review adds one. A review that produced findings which were then