@antoneeo/kb-agentic-skill 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.6.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.5.1] - 2026-08-25
 
 ### Fixed

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/kb-agentic-skill",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
   "keywords": [
     "claude-code",

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

@@ -1,6 +1,6 @@
 ---
 name: kb-agentic
-version: 1.5.1
+version: 1.6.0
 description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs and knowledge management.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -120,7 +120,7 @@ Use this mode when `devpnt_*` tools are available and point at the current proje
 - Run spec elicitation round (`elicitation.md`) before drafting analysis.
 - Run taxonomy pass (`taxonomy.md`): verify whether topics, categories, or SOPs already exist in `ai_docs/`. Avoid duplication.
 - Create or update `ai_docs/solutions/ANALYSIS_[topic].md`.
-- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
+- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when no higher rung is usable — a permission-gated rung is asked about, never silently skipped (`review.md`). Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
 
 ### 4. Knowledge Processing & Distillation
 - **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.

package/skills/kb-agentic-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/kb-agentic-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/kb-agentic-skill/templates.md

@@ -448,7 +448,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
@@ -463,9 +463,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