@antoneeo/agentic-sdlc-skill 1.25.0 → 1.26.1

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.26.1 / kb 1.4.7 / mkt 0.4.7] - 2026-08-06
+
+The late design review of F-034 (`review.md` row 1b, run after 1.26.0 had shipped because the
+gate had been skipped) returned FAIL with four blockers. Three were defects in the shipped
+doctrine and are fixed here; the fourth was a governance-record gap, fixed in `ai_docs/`.
+
+### Fixed
+- **`dispatch.md` contradicted the scoped re-review it delegates to `review.md` to define.**
+  It said "exactly three review touches per task, never a loop" and "not an extra review slot",
+  while `review.md` requires every review-driven correction to be re-reviewed — so an agent
+  executing a dispatched plan received two irreconcilable instructions. Reconciled: the scoped
+  re-review is a round **inside** slot 2 or 3, never a fourth slot; "never a loop" bounds the
+  slots, not the rounds within one. (Shared spine — the contradiction had shipped in all three
+  distributions; `dispatch.md` was missing from 1.26.0's impact map.)
+- **The claim-to-evidence rule had no enforcement point.** Its acceptance criterion promised a
+  completion claim without fresh proof would be "nameable by the closure review", but
+  `review.md` §Reviewing had no such finding class and the reviewer is never handed `SKILL.md`.
+  Added: an unproven or stale completion claim — including one resting on a narrower check than
+  the claim needs, or on a delegated agent's report rather than the diff — is now a finding.
+- **`SKILL.md`'s branch hygiene contradicted its own destructive guard.** One bullet ordered the
+  agent to "clean up the branch/worktree; never leave orphan branches"; the next reserved
+  destruction for the user's explicit request. The cleanup is now PROPOSED once the user has
+  chosen, with the anti-orphan duty kept as something to raise rather than to perform.
+- **Two gaps in the scoped re-review's own wording:** a PASS that carried findings is now
+  explicitly provisional until its corrections pass a round (the commonest real case, previously
+  unruled — the rule's trigger fired but its gate was already behind the fixes); and the single
+  REVIEW_LOG row now carries the round-1 verdict alongside the final one (`FAIL → PASS`) instead
+  of collapsing a first-round FAIL into a bare PASS, which erased the evidence the same file
+  says logging exists to preserve.
+
+- **`revise_rounds` had no defined meaning**, in the very document `SKILL.md` names as the owner
+  of the review log's schema and column meanings — and the historical rows already used it both
+  ways. Defined: it counts **review rounds**, not fix cycles (the first review is round 1, each
+  scoped re-review adds one), so a review whose findings were corrected always reads ≥ 2 and 3 is
+  the ceiling. The `verdict` column's format is defined alongside it (`FAIL → PASS` when the
+  round-1 and final verdicts differ), and the second example row — which taught a bare `PASS`
+  after two real findings closed in one round — now teaches both rules instead of contradicting
+  one. Raised at the review's round-3 cap and fixed before release rather than deferred.
+
+### Changed
+- `ai_docs/solutions/ANALYSIS_execution_integrity.md` gains what the design review found
+  missing: the **ceremony-cost disclosure** Non-Goal 3 requires (measured on the shipped diff)
+  with the owner's explicit acceptance recorded; the **rulings placement** run per mechanism
+  against the ledger's own criterion (the previous claim used a narrower "user-facing" test the
+  ledger does not define); the **lens-scoping decision** stated; and a named disposition for the
+  chronic `stale` debt. No shipped file changes from these.
+
+## [1.26.0 / kb 1.4.6 / mkt 0.4.6] - 2026-08-06
+
+### Added
+- **Execution Integrity — Tranche A (F-034).** Three observed/irreversible gaps close as
+  wording in existing owners, from a firsthand comparative study of Superpowers 6.2.0 (MIT;
+  concepts reimplemented, no text copied, no dependency) gated by the standing weight
+  criterion: (1) **claim-to-evidence** — every completion claim binds to a proof run AFTER
+  the final relevant edit; a narrower check never supports a broader claim; delegated work is
+  verified on the diff, never on the subagent's report; unavailable proof is reported, never
+  claimed (observed failure: a closure artifact claimed "check clean" while the gate was NOT
+  CLEAN — REVIEW_LOG F-033). (2) **Scoped re-review of review-driven corrections**
+  (`review.md`, shared spine — ACTIVE in kb/mkt too): a fix is unreviewed work; per-finding
+  verdicts ADDRESSED/NOT ADDRESSED/CONTESTED, correction-only scope, new breakage in the fix
+  joins the findings, two rounds are the norm inside the existing cap of 3, one logical
+  review = one REVIEW_LOG row. (3) **Destructive guards** — integration is the user's choice;
+  discard only on explicit request naming branch/commits/worktree; no unauthorized
+  force-push; no foreign-worktree cleanup; project guides own the specific commands.
+- **Enforcement-writing technique** on the touched rules: a triage rationalization table
+  (`Excuse | Reality`) in Rule Zero and red-flag stop-words in the verification rule — the
+  study's key finding was that Superpowers' asset is HOW it writes rules (pre-refuting the
+  escape thought), not any mechanism.
+- **Reviewer output honesty:** `CANNOT VERIFY` is a first-class reviewer output (a claim not
+  checkable from the provided inputs is reported, not silently passed); pre-judging findings
+  in a review request ("don't flag X") is forbidden. Companion change in the devPNT reviewer
+  agents ships in that repo.
+  Tranche B (tdd/debugging) rides the next admitted touch of those overlays; Tranche C
+  (dispatch ledger machinery) stays frozen until an observed failure reopens it. Rationale:
+  `ai_docs/architecture/ADR_2026-08-06_execution_integrity_tranche_a.md`.
+
 ## [1.25.0 / kb 1.4.5 / mkt 0.4.5] - 2026-08-06
 
 ### Added

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.25.0",
+  "version": "1.26.1",
   "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.25.0",
+  "version": "1.26.1",
   "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.25.0
+version: 1.26.1
 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
@@ -56,6 +56,16 @@ Cross-cutting rules:
 - **Before asking the user anything — any phase, any level — the question must pass the legality test: search first and name the search with its result; name the decision or fact blocked without the answer.** Blocking the work is the exception, not the default. `elicitation.md` §The question discipline owns the rule and is the only place it is stated — read it before you ask, and do not work from a summary of it.
 - The full audit does not start for L1/L2 unless explicitly requested.
 
+Triage rationalizations — the thought on the left is the signal to STOP and re-triage:
+
+| Excuse | Reality |
+|---|---|
+| "Too simple to need the process" | Simple is where unexamined assumptions bite; L1's process IS proportionally simple — use it, don't skip it |
+| "It's just a fix" | A "fix" that delivers a new capability or client is a new feature wearing a fix label — the framing does not set the level, the criteria do |
+| "It's small, so L2" | Size is one criterion of several: one touched contract, security surface or non-obvious design makes it L3 at any size |
+| "I'll reclassify later if it grows" | Later is after the unscoped edits exist; reclassify the moment the bigger impact emerges, not at closure |
+| "The doubt itself is small" | When in doubt, pick the higher level — that rule exists precisely for this thought |
+
 ## Write Triggers
 
 Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it. This table is the authoritative write index — the workflow phases carry the surrounding procedure and point here for the trigger.
@@ -262,6 +272,7 @@ Hybrid L3:
 ### 5. Closure
 
 - Run the relevant tests/lint/smoke checks.
+- **Claim-to-evidence (fires at EVERY completion claim, any phase, any level).** Before stating or implying that anything passes, works, is fixed, is clean or is complete: name the claim, run the proof that establishes *that* claim **after the final relevant edit**, read the full result, and report the actual status with the evidence. Freshness: a check run before a later relevant change proves nothing about the current tree. Breadth: a narrower check never supports a broader claim — targeted tests ≠ full suite; lint ≠ build; "tests pass" ≠ "requirements complete" (that claim maps to the Functional Spec acceptance criteria where the artifact carries them; "gate clean" maps to a fresh gate run reporting clean). **Delegated work is verified on the diff/files, never on the agent's report** — "the subagent said success" is a claim, not evidence. If the environment cannot run the proof, say so and give the alternative evidence — never claim the unavailable result. Red flags that mean STOP and run the proof: "should", "probably", "seems to", "still passes", "just this once", any satisfaction expressed before verification.
 - For the review itself follow `review.md` (requesting and receiving findings) — the single definition, intended for reuse by the Hybrid review gates (devPNT-side wiring out of this unit's scope).
 - Verify alignment with the local Vision or the devPNT M-VISION.
 - If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
@@ -278,7 +289,8 @@ Hybrid L3:
 - If an architectural decision was taken (new pattern, layer or contract change, structural dependency), record an ADR before DONE — Standalone in `architecture/`, Hybrid propose the ADR/KL update in the devPNT DB. No decision, no ADR (Write Triggers).
 - In Standalone, if the project adopts `sdlc_check.py`, run `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` or the equivalent local copy.
 - Updated documents must travel in the same commit/PR as the code they describe.
-- **Branch/worktree hygiene**: an L3 ran on its own branch (Phase 4) — close it with an explicit merge decision (merge, keep open, or discard) and clean up the branch/worktree; never leave orphan branches. In Hybrid, the running devPNT server locks `.devpnt/*.db`, so the merge is done from a separate git worktree or via a ref-only push, never an in-place branch switch in the primary worktree.
+- **Branch/worktree hygiene**: an L3 ran on its own branch (Phase 4) — close it with an explicit merge decision (merge, keep open, or discard), and once the user has chosen, PROPOSE the branch/worktree cleanup their choice implies; an orphan branch left behind with nothing said is the failure this bullet prevents — the cleanup itself is theirs to authorize (next bullet). In Hybrid, the running devPNT server locks `.devpnt/*.db`, so the merge is done from a separate git worktree or via a ref-only push, never an in-place branch switch in the primary worktree.
+- **Destructive guards (integration is the user's; destruction is explicit).** The integration choice — merge, push/PR, keep — belongs to the user. Discard happens ONLY on the user's explicit request, and the confirmation names exactly what dies: the branch, its commits, the worktree path. Never force-push without explicit authorization; a rejected push means the remote moved — investigate, don't force. Never clean up a worktree this workflow did not create — the host or another workflow owns it. Repository-specific release/finish commands are the project guide layer's (the router in `## Operative Guides`): the skill owns this discipline, the matched `GUIDE_*.md` owns the commands — cite it, never restate it.
 
 ## ai_docs documents: two indexes + lifecycle
 

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

@@ -65,6 +65,15 @@ Exactly three review touches per task, never a loop:
 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

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

@@ -507,8 +507,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
@@ -527,6 +527,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).