@antoneeo/kb-agentic-skill 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 Every significant change to this skill is recorded here.
 
+## [1.4.7] - 2026-08-06
+
+### Fixed
+- **Shared-spine sync: the scoped re-review contradicted `dispatch.md` (ACTIVE in this lens).**
+  `dispatch.md` said "exactly three review touches per task, never a loop" while `review.md`
+  required every review-driven correction to be re-reviewed. Reconciled: the scoped re-review is
+  a round inside slot 2 or 3, never a fourth slot. Also in the shared `review.md`: an unproven or
+  stale completion claim is now a reviewer finding; a PASS carrying findings is provisional until
+  its corrections pass a round; the single log row keeps the round-1 verdict (`FAIL → PASS`).
+  Found by the code lens's late design review of F-034.
+
+## [1.4.6] - 2026-08-06
+
+### Changed
+- **Shared-spine sync: review-driven corrections + reviewer honesty (ACTIVE in this lens).**
+  The shared `review.md` gains the scoped re-review discipline — a fix made in response to a
+  finding is unreviewed work and gets a correction-scoped re-review with per-finding verdicts
+  before PASS — plus the `CANNOT VERIFY` reporting duty and the no-pre-judging rule. Unlike
+  prior spine syncs these are NOT inert here: reviews of knowledge artifacts inherit the
+  correction discipline directly.
+
 ## [1.4.5] - 2026-08-06
 
 ### Changed

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "kb-agentic-skill",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "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.4.5",
+  "version": "1.4.7",
   "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.4.5
+version: 1.4.7
 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

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

@@ -1,87 +1,96 @@
-# 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.
-
-## 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 → 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

@@ -99,6 +99,12 @@ 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.
 
+Never pre-judge findings for the reviewer: do not instruct them to ignore or
+not flag a specific issue ("don't treat X as a defect", "at most minor"). If
+you believe a finding would be a false positive, let the reviewer raise it and
+resolve it with evidence in §Receiving — pre-judging is usually the requester
+sparing themselves a round.
+
 ## Receiving
 
 **MUST answer findings one by one — fix, or justify with evidence; why:
@@ -111,6 +117,28 @@ 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.
 
+### Review-driven corrections (scoped re-review)
+
+A fix made in response to a finding is new, unreviewed work — stopping after
+"I fixed it" ships the one version nobody reviewed. Every review-driven change
+therefore gets a **scoped re-review** before the review can PASS: hand the
+re-reviewer the original findings and ONLY the correction (the fix diff/range
+for code, the amended sections for a document), and require a per-finding
+verdict — `ADDRESSED`, `NOT ADDRESSED`, or `CONTESTED` with evidence. **A PASS
+that carried findings is provisional until its corrections pass that round** —
+the commonest real case is a PASS with non-blocking findings the author then
+fixes, and stopping there ships precisely the unreviewed version this rule
+exists to catch. The re-review also checks the correction itself for new
+blocker-level breakage — and nothing else: out-of-scope observations become separately
+recorded findings, never an extension of the loop. Expect two rounds as the
+norm, not the exception — round 1 finds, round 2 verifies the fixes — inside
+the same cap of 3 (§When a review is due). One logical review stays ONE
+REVIEW_LOG row — a scoped re-review is a round, not a new review — with the
+rounds narrated in the row's notes and **the verdict column carrying the
+round-1 verdict and the final one (`FAIL → PASS`), never the final one alone**:
+a first-round FAIL is the highest-value evidence the gate produces (§When a
+review is due), and collapsing it into a bare `PASS` erases exactly that.
+
 ## Reviewing
 
 When you are the reviewer:
@@ -123,6 +151,21 @@ When you are the reviewer:
   (see `## Requesting`).
 - Cite evidence as `file:line` for every finding — a finding without a
   location is not actionable.
+- **An unproven completion claim is a finding** (closure reviews, on the diff).
+  When the work under review states or implies that something passes, is fixed,
+  is clean or is complete, the evidence must be present and must post-date the
+  final relevant change; a claim resting on a stale run, on a narrower check
+  than the claim needs, or on a delegated agent's own report rather than the
+  diff, is a finding — name the claim and what would prove it. This is the
+  enforcement point of the author-side rule in `SKILL.md` §5 Closure, and the
+  reason a requester hands it over is that the reviewer cannot cite a rule it
+  was never given.
+- **Say what you could NOT verify.** When a claim in the artifact cannot be
+  verified from the inputs you were given (it lives in unchanged code, another
+  document, or an environment you cannot reach), report it as a
+  `CANNOT VERIFY` item instead of silently passing it — the requester holds
+  the context to resolve it, and must do so before closing. A PASS that
+  silently skipped unverifiable claims is review theater.
 - 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

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

@@ -447,8 +447,8 @@ 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 | PASS | 2 |
-| 2026-06-12 | diff feature/sso-login | closure | self-pass (declared; no subagent facility) | 2 | 2 | PASS | 1 |
+| 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 |
 
 ## Notes
 <!-- One short paragraph per review that found something worth remembering: what
@@ -467,6 +467,13 @@ records the realization actually used — fresh subagent, one-shot client run, o
 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
+corrected therefore always reads ≥ 2 — the corrections are unreviewed work until a
+round verifies them (`review.md` §Receiving) — and 3 is the ceiling, past which the
+residue goes to the user rather than into a fourth round. `verdict` carries the
+round-1 verdict and the final one when they differ (`FAIL → PASS`): collapsing a
+first-round FAIL into a bare `PASS` erases the evidence this log exists to keep.
 Concurrent reviews: `init` writes a `.gitattributes` stanza giving this file
 `merge=union` — a **built-in** driver (no per-clone `git config`, unlike
 `merge=ours`, which silently does nothing until every clone configures it).