@gtrabanco/pi-agentic-workflow 0.11.2 → 0.13.1

package/skills/plan-feature-scaffold/references/SCAFFOLD_PROCESS.md

@@ -28,6 +28,14 @@
    - Rotate `artifactRevisionId` for the unit's plan artifacts on this write and
      carry it in the hand-off. A later revert to these same bytes is a new
      authoring event and needs a new id.
+   - Declare the test set in the `path-protection-plan@1` block (feature 60),
+     placeholder tokens only, never a project glob: `freeze-after: <P<n>|none>`
+     plus one justified row per test decision
+     (`created | <repo-relative path or glob> | <one-line justification>`,
+     `not-created | <test name> | <one-line justification>`,
+     `ignored | <test name> | <one-line justification>`). Put it in `PLAN.md` for
+     M/L, or in the SPEC's `### Phases` for XS/S; the grammar is
+     `path-protection@1` in the turn contract.
 4. **Scale by size:**
 
    - **XS/S:** SPEC + `ACCEPTANCE.md`. Its `### Phases` has checkbox tasks and at least `P1`

package/skills/plan-fix/SKILL.md

@@ -3,7 +3,7 @@ name: plan-fix
 user-invocable: true
 version: 3.3.0
 argument-hint: <issue-number> [<issue-number> …]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Draft and locally commit a tightly scoped, phased fix SPEC from one or more

package/skills/planning-preflight/SKILL.md

@@ -2,7 +2,7 @@
 name: planning-preflight
 user-invocable: false
 version: 1.1.1
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal planning gate: consumes the normalized repository state and makes

package/skills/pre-execution-review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 2.2.1
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+version: 2.5.1
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal owner of the pre-execution review cycle and the planning ledgers:

package/skills/pre-execution-review/references/LEDGERS.md

@@ -90,7 +90,11 @@ status | resolution-evidence | resolving-artifact-revision
 
 - `stage` is `spec` or `plan`; `severity` and `class` use the receipt
   vocabularies (`info|low|medium|high|critical`,
-  `product|plan|source|environment|runtime`). `info` is the only immaterial one.
+  `product|plan|source|environment|runtime`). Material is `medium` and above; a
+  `low` row is a persisted **report-note** — visible, non-blocking, and resolved
+  by the stage author without a re-review — and `info` is immaterial.
+- Deflating a real defect below the `medium` minimum to unblock a pass is itself
+  a finding: the row is re-classified and blocks, never waved through.
 - `finding-id` is stable across cycles: a repeated finding keeps its id and gains
   a second resolution row, which is exactly what makes the no-progress and
   `CONVERGENCE-ANOMALY` rules computable.
@@ -104,9 +108,9 @@ status | resolution-evidence | resolving-artifact-revision
 - `resolving-artifact-revision` is the `artifactRevisionId` of the write that
   closed the row — the link that lets a re-review prove the snapshot actually
   changed.
-- A `PASS` may not coexist with an open material/unverified row in this table for
-  the bound snapshot. `audit-pr` reads it; the merge authority stays
-  `audit-pr`'s alone.
+- A `PASS` may coexist with open or unverified `low`/`info` report-note rows; it
+  is refused while any open or unverified `medium`+ row exists for the bound
+  snapshot. `audit-pr` reads it; the merge authority stays `audit-pr`'s alone.
 
 ## Durable ledger write ownership (the map)
 
@@ -114,7 +118,7 @@ The one-owner rule, stated once so every skill and template can cite it here:
 **a durable ledger has exactly one writer per column set, plus at most one
 declared mechanical annotator, which may append only the token its own row
 names.** Nobody else writes a row — not a reviewer, not a later phase, not a
-script. So `fold-findings` flips only the `folded:` flag `triage-issue` gives it,
+script. So `fold-findings` flips only the `folded:` flag per the map's `fold-findings:folded-flag` owner entry,
 and `scripts/ledger-provenance.mjs` appends only the marker it really emits:
 its `· fold <sha>` (or `· ticked <sha>` on a row that scores 1) plus the
 `· REOPENED — provenance unproven` note when a tick has no matching
@@ -138,7 +142,7 @@ must pass; the CI node-compat job enforces the fallback.
 ```text
 ledger-ownership@1
 truth-class | ledger | owner | annotator | annotator-token | validator
-review-findings | docs/features/<NN>-<slug>/review-findings.md · docs/fix/<issue>-<topic>/review-findings.md | review-change:finding-rows + review-change:finding-mark + review-change:review-mark + audit-pr:audit-rows + triage-issue:triage-rows + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | bun test scripts/ledger-provenance.test.mjs
+review-findings | docs/features/<NN>-<slug>/review-findings.md · docs/fix/<issue>-<topic>/review-findings.md | review-change:finding-rows + review-change:finding-mark + review-change:review-mark + review-change:review-gate-ran-marks + audit-pr:audit-rows + triage-issue:triage-rows + execute-phase:gate-ran-marks + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | bun test scripts/ledger-provenance.test.mjs
 planning-findings | docs/features/<NN>-<slug>/planning-findings.md · docs/fix/<issue>-<topic>/planning-findings.md | review-spec:spec-stage-rows + review-plan:plan-stage-rows + design-feature:product-class-resolutions + plan-feature:plan-class-resolutions + plan-fix:fix-plan-class-resolutions + fold-findings:source-class-resolutions | none | none | bun test scripts/pre-execution-quality.test.mjs
 progress | docs/features/<NN>-<slug>/progress.md · docs/fix/<issue>-<topic>/progress.md | plan-feature-scaffold:create + execute-phase:phase-entries + execute-phase:gate-rejection-traces + review-spec:product-receipt + review-plan:plan-receipt | none | none | bun test scripts/pre-execution-sensor.test.mjs
 known-issues | docs/features/<NN>-<slug>/known-issues.md · docs/fix/<issue>-<topic>/known-issues.md | plan-feature-scaffold:create + execute-phase:blocker-entries-and-status | none | none | bun test scripts/ledger-ownership.test.mjs
@@ -203,3 +207,36 @@ reproducer as its regression check — it never re-derives it; a `recheck` cell
 that cannot be materialized yields `BLOCKED <missing input>`. This consumption
 leaves the row shape, the `VF-` exclusions, and the `review-change`
 single-writer rule untouched.
+
+### The gate-run mark
+
+A gate run — green or red — leaves a durable mark in the unit's
+`review-findings.md` ledger (for features:
+`docs/features/<NN>-<slug>/review-findings.md`, for fixes:
+`docs/fix/<issue>-<topic>/review-findings.md`), owned by the `review-findings`
+truth-class row's owner cell extended with the two recorder column-sets:
+
+```text
+gate-ran@1
+id | file:line | cmds | exit | [additive-slots ...]
+GATE-RAN | HEAD <40-hex sha> | <cmds> | exit <code> | [reserved trailing slot: `manifest <sha>`]
+```
+
+- **Fixed format** (the one grammar; every consumer cites this block):
+  `GATE-RAN | HEAD <sha> | <cmds> | exit <code>` — every run records the SHA,
+  the commands run, and the exit code (green and red alike; `exit 0` is green).
+  `<cmds>` is the runnable command(s) the gate ran, joined by ` | ` when several.
+- **Additive slots**: fields after `HEAD` are additive; consumers ignore unknown
+  trailing fields (feature 35's `manifest <sha>` slot is reserved, not yet
+  consumed).
+- **Identical-head reuse**: any skill may consume a **green** run only at the
+  identical HEAD; a changed head ⇒ re-run the gate. A red mark is never
+  consumed as a pass.
+- **Recorder column-sets**: the `review-findings` truth-class row's owner cell
+  declares `execute-phase:gate-ran-marks` (executor phase gates) and
+  `review-change:review-gate-ran-marks` (reviewer gate runs), distinct column-set
+  names per the one-writer-per-column-set rule.
+- **Owner extension**: the identical owner cell is mirrored into both template
+  projections (`docs/features/_TEMPLATE/LEDGERS.md` and `docs/fix/_TEMPLATE/LEDGERS.md`).
+- **No new truth-class row**: the grammar admits no new row — the existing
+  `review-findings.md` ledger pattern is reused with extended owner cells.

package/skills/pre-execution-review/references/POLICY.md

@@ -38,15 +38,34 @@ what is specific to their artifact set.
 The first review emits one complete unioned findings set — never a drip of
 successive surprises. Its owner then classifies **every** finding by root cause
 (`product | plan | source | environment | runtime`) and applies **one**
-evidence-bounded repair batch to the owning artifact(s) before a single
-re-review of the resulting snapshot.
+evidence-bounded repair batch to the owning artifact(s). The batch rotates
+`artifactRevisionId`; by default it is followed by one re-review of the freshly
+rotated snapshot.
 
 | Class | What the batch may do | What it may not do |
 |---|---|---|
 | Common root cause | One edit that closes several findings | Split into per-finding micro-edits that leave the shared cause in place |
-| Wording-only | Skip a full replan when intent, obligation identity, phase topology, validators, and authority are all unchanged | Proceed without recording that determination in the evidence |
+| Wording-only | Skip the re-review when intent, obligation identity, phase topology, validators, and authority are all unchanged | Proceed without recording the determination, or without rotating `artifactRevisionId` |
 | Scope-changing | Re-cut the plan or the Product half | Ride through as a "wording fix" |
 
+A wording-only batch records its machine half and its judgment half as one block
+in the unit's unbound `progress.md`:
+
+```text
+## Wording-only determination v1 — <spec|plan>
+- Determination: <opaque id>
+- Artifact revision: <the rotated artifactRevisionId>
+- Acceptance fingerprint: <the ACCEPTANCE.md blob the batch left unmoved>
+- Intent and authority unchanged: yes
+```
+
+The revision rotation is **never** skippable: the freshness predicate refuses an
+unrecorded rotation (`stale-source-revision` — bound bytes moved and no matching
+determination was recorded), and a later material movement after an exempted one
+is refused because the recorded revision no longer matches.
+The determination is the exemption's record, never authorization to move bytes
+without one.
+
 Never repair by editing the reviewed claim into agreement with the reviewer: the
 repair supplies the missing evidence or routes the gap to its owner.
 
@@ -57,8 +76,8 @@ falsifiable question and a new evidence route**. Identical inputs plus an
 identical question stop as no-progress: report it and stop, do not re-issue the
 same verdict with more confidence.
 
-One repair/re-review cycle is the normal correction path. Entering a **second**
-cycle is allowed when correctness needs it and never grants PASS, but it is a
+One repair/re-review cycle is the normal correction path. A **second**
+consecutive unconverged repair/re-review cycle is not routine — it is a
 `CONVERGENCE-ANOMALY`: before any further edit, report
 
 ```text
@@ -76,12 +95,18 @@ on a Product- or Plan-rooted finding is invalid even when the candidate changed:
 the loop repairs source, not authority. Runtime retry and budget mechanics stay
 outside this policy and can never be translated into a PASS.
 
-The guards above gate **blind re-reviews** — an identical snapshot with the
-identical question — and never a repair performed in response to a persisted
-verdict: a repair turn whose input is a FAIL/NEEDS-DESIGN receipt produces a new
-snapshot by design, so no cycle cap or anomaly rule may block or end it. The
-anomaly is printed and routed, never a stop, and no cap converts a verdict into a
-dead end.
+A **third cycle never** starts without explicit user instruction: after two
+consecutive unconverged cycles the orchestrator's `stop-review-loop-cap` refusal
+stops a further `review-spec`/`review-plan` invocation, names `design-feature` as
+the human route, and a PASS resets the count. An unconverged loop ends in the
+`needs-design` verdict where the verdict vocabulary sanctions it (the spec stage)
+and in the refusal plus `design-feature` routing at the plan stage. The guards
+above gate **blind re-reviews** — an identical snapshot with the identical
+question — and never a repair performed in response to a persisted verdict: a
+repair turn whose input is a FAIL/NEEDS-DESIGN receipt produces a new snapshot by
+design, so the count is over review invocations, never over repairs. The cap
+stops the loop and routes a human decision; it never establishes correctness from
+a count and never waives a finding.
 
 ### 5. What a cycle can never produce
 
@@ -170,9 +195,9 @@ reports; a printed verdict whose mark is still "for next turn" is not finished.
   printed without the pasted self-check output is a contract defect, and every
   consumer reads a chat-only verdict as `missing-receipt-snapshot` — it does not
   exist to the sensor.
-- **A gate rejection is typed**, from a closed set of four: `dependency`, `status`,
-  `phase-lint`, `stale-or-missing-receipt`. Each fixed gate block carries its type
-  and names what it read and where the turn goes:
+- **A gate rejection is typed**, from a closed set of five: `dependency`, `status`,
+  `phase-lint`, `path-protection`, `stale-or-missing-receipt`. Each fixed gate
+  block carries its type and names what it read and where the turn goes:
 
   ```text
   GATE REJECTION — <type>
@@ -191,6 +216,7 @@ reports; a printed verdict whose mark is still "for next turn" is not finished.
   dependency | PREFLIGHT.md
   status | PREFLIGHT.md
   phase-lint | PREFLIGHT.md
+  path-protection | PREFLIGHT.md
   stale-or-missing-receipt | PRE_EXECUTION_GATE.md
   ```
 

package/skills/product-audit/SKILL.md

@@ -2,11 +2,11 @@
 name: product-audit
 user-invocable: true
 disable-model-invocation: true
-version: 3.1.0
+version: 3.2.0
 metadata:
   opencode/autoinvoke: false
 argument-hint: <path-or-area> (optional — defaults to the whole product)
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Audit the whole product across code, quality, process, docs, roadmap, and
@@ -97,12 +97,12 @@ Verdict: <one-line honest health verdict>
   Installed tooling ....... ✓ | ⚠ | ✗ | n-a
 
 ## Findings (severity-ranked, one F-sequence for the whole audit)
-  F1 [SEV] <dimension> — <finding> — evidence: <file:line | metric | doc> — class: <fix-now|postpone|tradeoff>
+  F1 [SEV] <dimension> — <finding> — evidence: <file:line | metric | doc> — class: <fix-now|replan-in-unit|decision-required|proposal|ignore>
   F2 [SEV] ...
   [example — scope-export recurrence] F<k> [med] Workflow discipline — <N>
     consecutive units exported scope via `## Amendments`/descope issues —
     features are being cut too big for real capacity — evidence: <unit list +
-    amendments/issues> — class: postpone — route: #64 (atomicity/split rules)
+    amendments/issues> — class: proposal — route: #64 (atomicity/split rules)
 
 ## Delta vs audit <prior-id>
   New: F<k>

package/skills/product-audit/references/AUDIT_DIMENSIONS.md

@@ -12,7 +12,7 @@
 | **Brand / voice** | User-facing copy vs. the brand guide | surfaces with copy |
 | **Tech debt** | Accumulated shortcuts, TODO/FIXME, stale abstractions | all |
 | **Process & docs** | Incomplete phases, aging open issues, **solvable known-issues**, doc completeness, missing/optimizable workflow docs, capability-inventory freshness (`docs/CAPABILITIES.md` ↔ code drift) | all |
-| **Workflow discipline** | The workflow's own rules held: branch/PR discipline, `done · #<pr>` links, phase naming (`P1…`), per-phase docs, commit format, dependency closures, artifact language — **run `audit-docs` checks 1–13 mechanically** (compose it); never assume a rule held because it "should". **Scope-export recurrence:** across the most recent units (merged or in-flight), each with a non-empty `## Amendments` descope log or a descope-classified born issue (`audit-pr`'s scope-bleed gate) counts as one scope-exporting unit — **≥ 2 consecutive** such units is a planning-quality finding ("features cut too big for real capacity"), routed to the atomicity/split rules (**#64**), not re-litigated as a per-unit defect | all |
+| **Workflow discipline** | The workflow's own rules held: branch/PR discipline, `done · #<pr>` links, phase naming (`P1…`), per-phase docs, commit format, dependency closures, artifact language — **run `audit-docs` checks mechanically** (cite the count from `audit-docs`; never restated in the dimension table); never assume a rule held because it "should". **Scope-export recurrence:** across the most recent units (merged or in-flight), each with a non-empty `## Amendments` descope log or a descope-classified born issue (`audit-pr`'s scope-bleed gate) counts as one scope-exporting unit — **≥ 2 consecutive** such units is a planning-quality finding ("features cut too big for real capacity"), routed to the atomicity/split rules (**#64**), not re-litigated as a per-unit defect | all |
 | **Roadmap coherence** | Stale/obsolete/superseded features, missing dependencies, gaps & opportunities | all |
 | **Installed tooling** | Installed skills + connected MCP servers vs. the project's applicable axes and roadmap features — unregistered-but-useful items, and tooling that would change a feature's scope | all |
 

package/skills/product-audit/references/AUDIT_PROCESS.md

@@ -4,7 +4,7 @@
 2. **Sweep code & axes** — run the applicable axes across the codebase: compose
    `review-implementation` plus the internal review pack's applicable passes
    (each returns its fixed-format table + PASS|FAIL), and any optional installed
-   extras. Classify findings (severity + fix-now / postpone / tradeoff).
+   extras. Classify findings (severity + closed class set from review-implementation/CLASSIFY.md).
 
 **Evidence-provenance gate (fixed):** applies during every evidence-collecting sweep
 step (2–5). Each item ends with exactly one fallback; never pick another one mid-audit.

package/skills/replan-findings/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: replan-findings
 user-invocable: false
-version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+version: 1.1.1
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal contract: the conditional replan entry. Loaded only when
@@ -67,8 +67,8 @@ fingerprint: <sha256 over the inputs the answer used>
 - `read-set` is the bounded intake below: at most 12 paths, then an explicit
   `… and N more` line — never a silent truncation.
 - `open-rows`/`rows:` come from the ledger's open rows only (`folded` not
-  `yes`/`—`/`-`/`n/a`/empty), and the id shapes `VF-<n>` and `REVIEW-RAN` are
-  marks, never findings.
+  `yes`/`—`/`-`/`n/a`/empty), and the id shapes `VF-<n>`, `REVIEW-RAN` and
+  `GATE-RAN` are marks, never findings.
 
 Exit codes are part of the contract: a route prints and exits **0**; an unknown
 unit, or any argument count other than one, exits **1**; an ambiguous token (a

package/skills/review-a11y/SKILL.md

@@ -2,7 +2,7 @@
 name: review-a11y
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal accessibility review pass of the agentic-workflow review pack —

package/skills/review-brand/SKILL.md

@@ -2,7 +2,7 @@
 name: review-brand
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal brand & copy review pass of the agentic-workflow review pack — composed

package/skills/review-change/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.6.0
+version: 3.7.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Review a change with only applicable internal axes, classify every finding,
@@ -152,12 +152,14 @@ sequential/headless fallbacks; never collapse independent adversarial passes.
 Orchestrates internal finders (`review-code`, `review-security`, `review-verify`,
 `review-design`, `review-a11y`, `review-brand`, `review-perf`, `review-seo`), then
 one `review-implementation` classifier and `review-debt` transform, isolated by
-default; installed platform packs are optional. `triage-issue` is user-invoked
-only for independent proposals (D3). It is Stage 4: checkpoint reviews are
+default; installed platform packs are optional. `triage-issue` is user-invoked,
+never auto-run (D3), for independent proposals, audit findings, and
+`--prioritize-now` runs. It is Stage 4: checkpoint reviews are
 optional, the end review is mandatory and fresh. `fix-now` is routed to the
 unit's fold cycle — a separate `/fold-findings` invocation, never run by this review;
 `replan-in-unit` adds user-confirmed phases, and independent work becomes
-proposals. `audit-pr` consumes only the verified PR-comment receipt, never the
+proposals. `audit-pr` consumes
+only the verified PR-comment receipt, never the
 chat report; `product-audit` is the periodic sweep. On `REVIEW-FAIL` the manual
 correction path is `/fold-findings`, then re-run `/review-change` on the changed
 HEAD (bounded at two cycles — a third cycle never starts without an explicit

package/skills/review-change/references/OUTPUT_AND_GUARDRAILS.md

@@ -35,7 +35,8 @@ lost, and none becomes reviewer-created backlog (D3):
 - **fix-now / `decision-required`** → stop and surface the decision to the user;
   the unit blocks until decided. No issue is created.
 - **proposal** (independent future capability) → batched in the report with a
-  trigger; only the **user** routes it to `triage-issue`.
+  trigger; only the **user** routes it to `triage-issue` (independent
+  proposals, audit findings, or `--prioritize-now` runs).
 - **ignore** → note the rationale in the report; no further action.
 
 The report's `Decision:` line is **three-state** (D10): `REVIEW-PASS` when the

package/skills/review-change/references/PERSIST_AND_DECIDE.md

@@ -18,14 +18,17 @@ exact command tokens.
    `gh pr view --json state` when a PR is open; otherwise the unit is unmerged
    by definition). Otherwise, for each **fix-now** finding of severity `high`
    or `med` (only ledger severities; finder scale
-   `critical`→`high`, `major`→`med`, `minor`→`low`): append a row
+   converts through the canonical table in
+   `CLASSIFY.md`):
+   append a row
    (create the file with the header row when missing), carrying the
    verbatim `Sev` value into `severity`; `folded` always starts `no` — that
    row comes from a **confirmed** candidate only and carries its
    `finding-mark@1` signature on a **separate `VF-` row** (reviewer, head SHA,
    recheck + reproducer), as modeled in `LEDGERS.md` (§finding-mark@1) and the
    fixture.
-   `execute-phase`'s fold cycle is the only step that ever flips it to `yes`.
+   `ledger-ownership@1` / `fold-findings:folded-flag` is the sole writer of
+   the `folded: no → yes` flip.
    A `low` finding is **never persisted to the fold ledger** — report-only
    note (step 13), never blocking (finders' materiality floor). Re-runs
    **dedupe by `file:line` + axis**:
@@ -35,16 +38,19 @@ exact command tokens.
    **Non-fix-now findings are never written here** — they keep
    their destinations from step 11 (outcome routing): independent future
    capabilities batch as proposals; only the user routes them to `triage-issue`
-   (D3).
-   **Commit the ledger append** — rows + `REVIEW-RAN` mark, one commit
-   (`docs(<unit>): persist review findings F<n>–F<m>`), pushed when a PR is open;
+   (independent proposals, audit findings, or `--prioritize-now` runs) (D3).
+   **Commit the ledger append** — rows + `REVIEW-RAN` + `GATE-RAN` marks,
+   one commit (a reviewer records a `GATE-RAN` mark for the gate run the review
+   performed and consumes an identical-head green mark instead of re-running,
+   see `LEDGERS.md` §gate-ran@1; `docs(<unit>): persist review findings`);
+   pushed when a PR is open;
    an uncommitted append hands the next review a dirty-tree stop. On
-   `REVIEW-PASS` with an open PR no ledger write happens (the SHA-bound
-   receipt is the durable record): head and posted receipt stay identical.
-   This skill's only mutations are this ledger commit (step 11) and, on
-   `REVIEW-PASS` with a PR, the receipt comment (step 12) — it never runs a
-   fold, executes a phase, or edits source (see the review-end turn boundary in
-   the SKILL.md Turn contract).
+   `REVIEW-PASS` with an open PR the SHA-bound receipt is the durable record:
+   head and posted receipt stay identical.
+   This skill's only mutations are the rows + `REVIEW-RAN` + `GATE-RAN` marks
+   (all in the step 11 commit), and, on `REVIEW-PASS` with a PR, the receipt
+   comment (step 12) — it never runs a fold, executes a phase, or edits source
+   (see the review-end turn boundary in the SKILL.md Turn contract).
 12. **Close out the final-review receipt before reporting.** Derive the
    `Decision` from step 7 and persist step 11 first. Then — **only on
    `Decision: REVIEW-PASS` and when the PR exists** — run the receipt emitter,

package/skills/review-code/SKILL.md

@@ -2,7 +2,7 @@
 name: review-code
 user-invocable: false
 version: 1.2.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal correctness + simplification review pass of the agentic-workflow

package/skills/review-debt/SKILL.md

@@ -2,7 +2,7 @@
 name: review-debt
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal tech-debt transform pass of the agentic-workflow review pack —

package/skills/review-design/SKILL.md

@@ -2,7 +2,7 @@
 name: review-design
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal UI/UX design review pass of the agentic-workflow review pack —

package/skills/review-implementation/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: review-implementation
 user-invocable: false
-version: 1.8.0
+version: 1.9.0
 argument-hint: <path-or-glob>
 allowed-tools: Read, Grep, Glob, Bash, WebFetch
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal scope/classification engine composed by review-change (and reused by

package/skills/review-implementation/references/CLASSIFY.md

@@ -5,6 +5,61 @@ the **synthesized** findings table (D5). Classify each finding into exactly one
 class, in this order. Never reopen source files to classify; the table's
 evidence is authoritative.
 
+### Severity conversion (canonical table)
+
+The single-owner table below maps every severity scale the review pack emits
+onto the classification scale (`high | med | low`). Only this section may
+convert — a consumer facing an unknown scale **fails closed** (no ad-hoc
+conversion). The table replaces the ad-hoc mapping that lived at
+`PERSIST_AND_DECIDE.md`.
+
+The sensor's own `SEVERITY_VOCABULARY` map (`scripts/workflow-status.mjs:718-721`)
+is a direct projection of this table onto the envelope schema's `high|med|low`
+enum, not a competing converter; it always produces a value listed here.
+
+| Producer scale | → `high` | → `med` | → `low` |
+|---|---|---|---|
+| Ledger (`CLASSIFY.md` itself): `high` | self | — | — |
+| Ledger: `med` | — | self | — |
+| Ledger: `low` | — | — | self |
+| Finder (nine review passes): `critical` → `high` | ✓ | — | — |
+| Finder: `major` → `med` | — | ✓ | — |
+| Finder: `minor` → `low` | — | — | ✓ |
+| Planning: `critical` → `high` | ✓ | — | — |
+| Planning: `high` → `high` | ✓ | — | — |
+| Planning: `medium` → `med` | — | ✓ | — |
+| Planning: `low` → `low` | — | — | ✓ |
+| Planning: `info` → `low` | — | — | ✓ |
+| `audit-docs`: `high` → `high` | ✓ | — | — |
+| `audit-docs`: `low` → `low` | — | — | ✓ |
+
+**Unknown scale → fail closed.** A scale not listed above is an error; the
+consuming skill must not guess.
+
+### Derived blocking gate
+
+A finding **blocks** only when the reviewer cites which single-owner source
+fails — blocking is a table lookup over cited sources, never a severity
+opinion. The four citation categories are:
+
+1. **ACCEPTANCE criterion** unverified or failed.
+2. **Obligation row** in the unit's ledger is not `verified` or `n-a`.
+3. **Gate is red** at the reviewed head (the project gate exited non-zero at
+   the exact head under review).
+4. **Open confirmed `fix-now` row** on the fold ledger (a finding already
+   persisted as `fix-now` with `folded: no`).
+
+No citation among these four categories → the finding is a **report-note** or
+**proposal**, never blocking. D10's verdict rule (the three-way `REVIEW-PASS |
+REVIEW-FAIL | NEEDS-DECISION` verdict) remains **unchanged** — the derived gate
+operates inside the `REVIEW-FAIL` branch as the evidence that determines whether
+a finding truly blocks.
+
+**`report-note` definition owner.** The `report-note` classification is owned by
+`LEDGERS.md` §3 (`:91-96`): material is `medium`+, a `low` row is a persisted
+report-note. Classifying surfaces cite this owner instead of restating the
+materiality bar.
+
 ### Step 1 — `ignore` first (the claim, not a class choice)
 
 `ignore` claims **"this is not a real defect"** — a false positive or a

package/skills/review-perf/SKILL.md

@@ -2,7 +2,7 @@
 name: review-perf
 user-invocable: false
 version: 1.2.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal performance review pass of the agentic-workflow review pack — composed

package/skills/review-plan/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: review-plan
 user-invocable: true
-version: 1.6.1
+version: 1.7.0
 argument-hint: <NN-slug | fix-N | path/to/SPEC.md> [--adversarial N]
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Independent read-only review of a frozen Engineering plan before execution, in a

package/skills/review-plan/references/CHECKS.md

@@ -102,7 +102,10 @@ One row per finding in the receipt's `findings` array: stable `id`, `severity`
 (`info | low | medium | high | critical`), `class` (`product | plan | source |
 environment | runtime`), `claim` with its section/row pointer, `evidenceRefs`
 (≥ 1 — a finding without evidence is a hunch and gets dropped), `verification`,
-`resolution: open` on emission. Material = anything above `info`; a PASS may not
-carry an open or unverified material row. A Product-rooted finding found here
+`resolution: open` on emission. Material = `medium` and above; a `low` row is a
+persisted report-note the stage author resolves without a re-review, and `info`
+is immaterial. Deflating a real defect below the `medium` minimum to unblock a
+pass is itself a finding; a PASS may not carry an open or unverified material
+row. A Product-rooted finding found here
 keeps `class: product`: the class routes the repair, it is not a record of who
 noticed what.

package/skills/review-plan/references/OUTPUT.md

@@ -115,16 +115,17 @@ not authority.
 | Verdict / class | Who acts | What happens next |
 |---|---|---|
 | `PLAN-REVIEW-PASS` | nobody | `/execute-phase <NN>` binds this receipt + exact snapshot digest |
-| `PLAN-REVIEW-FAIL`, `class: plan` | `plan-feature` / `plan-fix` (the author) | one root-caused repair batch → new `artifactRevisionId` → re-review of the new snapshot |
+| `PLAN-REVIEW-FAIL`, `class: plan` | `plan-feature` / `plan-fix` (the author) | one root-caused repair batch → new `artifactRevisionId` → next cycle (default re-review; a recorded wording-only batch skips it) |
 | `PLAN-REVIEW-FAIL`, `class: product` | `design-feature` | repair the Product half → `review-spec` → the Plan receipt is re-derived (`stale-parent`) |
 | `PLAN-REVIEW-FAIL`, `class: source\|environment\|runtime` | its owner, later | record the row, keep it `open`, route it. Do not edit the plan to hide it and do not start `execute-phase` on a plan carrying an open material row |
 
 Repeating this review follows the no-progress and convergence rules in
 `pre-execution-review/references/POLICY.md` §4 — a repeat needs
 a changed snapshot or a named falsifiable question plus a new evidence route, and
-entering a second repair/re-review cycle prints the `CONVERGENCE-ANOMALY` block
-before any further edit. A second cycle never grants PASS and never gets folded
-into `review-change → fold-findings`, which repairs source, not plan authority.
+a second consecutive repair/re-review cycle prints the `CONVERGENCE-ANOMALY`
+block before any further edit; the orchestrator's `stop-review-loop-cap` refuses
+a third and names `design-feature` (a PASS resets the count). A second cycle
+never grants PASS and never folds into `review-change → fold-findings`.
 
 ### Skill-specific turn-contract boxes
 
@@ -157,10 +158,9 @@ On FAIL, name every finding id once, in order, joined with ` + `:
 
 ```
 → Next: /plan-feature <NN-slug> "<instruction>" (or /plan-fix <N> "<instruction>") —
-    one repair batch for F1 + P9 + L4, then /review-plan <NN-slug> re-reviews the new
+    one repair batch for F1 + P9 + L4, then /review-plan <NN-slug> judges the new
     artifact revision
   · class: product → /design-feature <NN-slug> then /review-spec <NN-slug>; the plan
     re-derives afterwards
   · a missing product choice → answer it yourself in the instruction; nothing here chooses
-  · a second cycle about to start → print CONVERGENCE-ANOMALY first, then route to the owner
 ```

package/skills/review-security/SKILL.md

@@ -2,7 +2,7 @@
 name: review-security
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal security review pass of the agentic-workflow review pack — composed

package/skills/review-seo/SKILL.md

@@ -2,7 +2,7 @@
 name: review-seo
 user-invocable: false
 version: 1.1.0
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Internal SEO review pass of the agentic-workflow review pack — composed

package/skills/review-spec/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: review-spec
 user-invocable: true
-version: 1.7.1
+version: 1.8.0
 argument-hint: <NN-slug | path/to/SPEC.md>
-author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Independent read-only review of a frozen Product half before engineering