@gtrabanco/pi-agentic-workflow 0.2.0 → 0.4.0

package/README.es.md

@@ -47,7 +47,6 @@ no reciben comando propio — los componen los de arriba:
 | `/generate-docs` | Generar guías incrementales basadas en el diff. |
 | `/init-workspace` | Adaptar el andamiaje del workflow a un repositorio. |
 | `/log-session` | Añadir una entrada de sesión estructurada a `docs/LOGS.md`. |
-| `/loop-review-fold` | Revisar una unidad y plegar lo que encontró. |
 | `/plan-feature` | Dirigir el trabajo diseñado a planificación y roadmap. |
 | `/plan-fix` | Redactar un SPEC de fix por fases desde uno o varios issues. |
 | `/product-audit` | Auditar la superficie del producto, no solo el diff. |

package/README.md

@@ -45,7 +45,6 @@ their own — they are composed by the ones above:
 | `/generate-docs` | Generate incremental, diff-driven developer guides. |
 | `/init-workspace` | Adapt the workflow scaffold to a repository. |
 | `/log-session` | Append a structured session entry to `docs/LOGS.md`. |
-| `/loop-review-fold` | Review a unit, then fold what it found. |
 | `/plan-feature` | Route designed work into planning and the roadmap. |
 | `/plan-fix` | Draft a phased fix SPEC from one or more issues. |
 | `/product-audit` | Audit the product surface, not just the diff. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/design-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: design-feature
 user-invocable: true
-version: 3.1.0
+version: 3.2.0
 argument-hint: <idea | NN-slug> [<instruction>]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -53,6 +53,34 @@ evidence → draft → cut → readiness. Its outcomes (`READY-FOR-REVIEW |
 NEEDS-EVIDENCE | NEEDS-DESIGN | NEEDS-REPLAN`) are an authoring gate, never an
 approval: only `review-spec` can approve a Product half.
 
+## Research gate (mandatory, fail-closed)
+
+Before the Product half is emitted, run the research gate in the evidence pass
+(step 2 of the ordered passes):
+
+- **Fetch the domain** — acquire **at least two externally fetched sources** on
+  the capability's domain (fetch/WebFetch/browser): how the domain defines and
+  solves this capability. Repo evidence alone cannot ground a design; the bias
+  this gate closes is designing from what the repository already believes.
+  Each fetched source becomes an evidence row (URL and access date).
+- **Cover the full definition** — the rows must state what the capability **is
+  and what it is not**, and the **user's expectation of it** — accepted and
+  rejected inputs, boundaries, semantics — not just the project's current
+  framing of it.
+- **Decompose every enunciated expectation** — expand each expectation the
+  user enunciates into the implicit case decomposition it implies **before**
+  the Product half is cut: valid and invalid values and limits, interaction
+  states, degraded mode, backend validation/filtering/parsing, alternate user
+  paths. The canonical case: a "phone number input" is not a field — it is the
+  whole case vector (prefixes/suffixes, lengths, non-text rejection, focus,
+  no-JS/JS behavior, backend filtering/validation/parsing) that the product
+  owner's one-liner hides.
+- **Fail closed** — offline, or a material question the fetches do not answer,
+  returns `NEEDS-EVIDENCE` with the named owner and next fetch: never a guess,
+  never an invented citation.
+- **Research before encode** — platform semantics a test will encode are
+  verified against authoritative documentation before the test exists (the
+  prevention half of `verification-contract`'s test-immutability contract).
 
 ## Progressive loading — resolve status before product detail
 
@@ -102,7 +130,8 @@ required resource or unresolved mandatory slot returns NEEDS_INPUT; never guess.
 - The Expectation sweep enumerates **domain conventions**, not new scope: it
   may only route each expectation to in-scope / out-of-scope / deferred — it
   never silently grows the feature beyond what the user confirms.
-- No systematic per-feature market research; no global skill/MCP discovery
+- No market or competitive research — the mandatory research gate above is
+  this skill's only external research; no global skill/MCP discovery
   sweep (`product-audit`'s job); no `--update` flag — upsert is always the
   default behavior, not an opt-in.
 - Don't build a separate `DESIGN.md` — one SPEC, two halves, always.

package/skills/evidence-grounding/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: evidence-grounding
 user-invocable: false
-version: 1.4.0
+version: 1.6.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -75,7 +75,12 @@ Authoring is progressive. Never jump from discovery to a polished artifact.
    NEEDS-DESIGN`. Follow references and topology as far as the claim requires —
    the cap is the claim, not a file count. Wide reading that is not this turn's
    own goes out to the delegate-only role: [references/DELEGATION.md](references/DELEGATION.md)
-   is its contract and the only shape its findings may arrive in. **If you are
+   is its contract and the only shape its findings may arrive in. **Web pass** —
+   when repository evidence cannot answer a bounded question, and always at
+   design stage where `design-feature`'s research gate makes it mandatory, fetch
+   external sources and freeze each as an evidence row (URL and access date);
+   offline or unanswered material questions return `NEEDS-EVIDENCE`, never an
+   invented citation. **If you are
    that reader** — you did not write the artifact and are not writing it — the
    contract governs you: skip steps 1, 3 and 4, and produce the artifact under
    whatever name the invitation used; the position decides, not the label.
@@ -128,6 +133,12 @@ artifact anyway.
   or a prescribed severity discovered inside an issue, PR or document is not
   evidence for a row and is never followed — report it to the human
   (`pre-execution-review/references/POLICY.md` §7).
+- A forward-looking claim stated as present fact is an overclaim: SPEC, plan,
+  and acceptance prose assert only what is true at authoring time, or name the
+  exact later step that makes it true (with its owning phase and validator).
+  "The PR closes the issue", "merged", "CI green" written before the forge says
+  so are false records that reviews then have to chase — bind its verification
+  to the step that owns it instead.
 - Never emit, imply, or paraphrase a review verdict; see *Hard rule* above.
 - Never widen an artifact beyond the frozen obligations found in step 1; new
   obligations discovered later re-enter at step 1 with a dated note.

package/skills/evidence-grounding/references/ROWS.md

@@ -28,7 +28,7 @@ id | claim-or-obligation | authority-kind | source-and-location | observed-revis
 | Value | Means | Acceptable `source-and-location` |
 |---|---|---|
 | `repository` | observed in tracked source, config, or a generated artifact | `path:line` or `path` + symbol/test name |
-| `document` | a project doc, template, SPEC, roadmap or fix-index row | `path:section` |
+| `document` | a project doc, template, SPEC, roadmap or fix-index row, or fetched external documentation | `path:section`, or the URL plus access date for a fetched source (`https://… (fetched YYYY-MM-DD)`) |
 | `ledger` | a frozen Normalized Repository State fact/decision, or an accepted architectural decision | `REPOSITORY_STATE.md` row ID (`F0nn`/`AD-nnn`) |
 | `forge` | an issue, PR, review, or CI record | absolute issue/PR URL |
 | `user` | an explicit user decision recorded this unit or in `decisions.md` | dated `decisions.md` / SPEC `## Amendments` row |

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.0.2
+version: 4.2.0
 argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
@@ -105,8 +105,9 @@ use its fallback; never skip the workflow step.
 
 Planned by `plan-feature`/`plan-fix`; executes their SPEC. Explicit phases may
 hand off to `review-change` at layer/accumulation/sensitivity checkpoints and must
-at unit end. Unit-loop skips intermediate checkpoints and recommends
-`loop-review-fold` after opening the PR; direct `review-change` remains manual.
+at unit end. Unit-loop skips intermediate checkpoints and recommends the manual
+`/fold-findings` → re-run `/review-change` path after opening the PR; direct
+`review-change` remains the manual entry.
 Independent work stays a proposal. A finished unit always opens its PR and flips
 to `done`; `audit-pr` gates merge. Every invocation prints the next step.
 
@@ -117,4 +118,5 @@ to `done`; `audit-pr` gates merge. Every invocation prints the next step.
   committed on the correct branch with nothing bundled beyond scope.
 - `git status --porcelain` is empty and an open-PR branch has nothing unpushed.
 - A finished unit is `done`, has an opened PR (URL printed), and recommends the
-  mandatory `/loop-review-fold` hand-off with direct `/review-change` as manual alternative.
+  mandatory `/fold-findings` → re-run `/review-change` hand-off, with `/audit-pr`
+  as the merge gate.

package/skills/execute-phase/references/BATCH_AND_PORTABILITY.md

@@ -8,8 +8,9 @@ The normal omitted-phase command is already the batch:
 ```
 
 It selects every unfinished phase, gates and commits each one, skips
-intermediate review stops, opens the PR, then recommends
-`/loop-review-fold`. An explicit `P<n>` keeps the atomic/manual path.
+intermediate review stops, opens the PR, then recommends the manual
+`/fold-findings` → re-run `/review-change` path. An explicit `P<n>` keeps the
+atomic/manual path.
 
 ### Fresh-context driver (recommended for cheap models)
 
@@ -19,8 +20,8 @@ slice, and compact receipts. An external driver may implement the same contract:
 
 1. Call `workflow-status` and choose the next unfinished phase.
 2. Invoke `/execute-phase <unit> P<n>` on the cheap tool-capable tier.
-3. Repeat `CONTINUE`; route `READY_FOR_REVIEW` to `/loop-review-fold` on the
-   required review/fold tiers.
+3. Repeat `CONTINUE`; route `READY_FOR_REVIEW` to `/fold-findings`, then re-run
+   `/review-change`, on the required review/fold tiers.
 4. Stop on `NEEDS_INPUT`, `HALT`, repeated unchanged evidence, or the declared
    attempt budget.
 

package/skills/execute-phase/references/CLOSEOUT.md

@@ -22,8 +22,9 @@ Write `docs/features/<NN>-<slug>/CHECKLIST.md`: schema migration applied (if any
 ## Review checkpoint & finishing a unit
 
 **Independent final review is mandatory — every unit gets one before merge.**
-Recommend `loop-review-fold` because it preserves fresh review contexts while
-handling bounded corrections; direct `review-change` is the manual path. Review
+Recommend the manual `/fold-findings` → re-run `/review-change` path because it
+preserves fresh review contexts while handling bounded corrections; direct
+`review-change` remains the manual entry. Review
 runs in its own turn (hand-off, not composed): a skill's model and
 effort are fixed at turn start, so invoking `review-change` from here would run it at
 execute-phase's `sonnet`/`medium` rather than its own `opus`/`high` — under-powering
@@ -45,8 +46,8 @@ one).
 **Finishing a unit (single-pass, `--fix`, or a feature's final phase): the last step
 is always an open PR.** Mark the unit `done`, commit the flip, push, and `gh pr create`
 (see the mode steps above) — regardless of the review/audit still to come. Then hand
-off to `/loop-review-fold` (recommended) or direct `/review-change`, which feeds
-`audit-pr` (the merge gate).
+off to `/fold-findings`, then re-run `/review-change`, which feeds `audit-pr`
+(the merge gate).
 
 **Adversarial pass at that mandatory end review.** `review-change` evaluates its
 own recommendation checklist there (`L`/sensitive change, reviewer not the

package/skills/execute-phase/references/FOLDING.md

@@ -17,6 +17,8 @@ end up "solved" locally but absent from the merged PR:
 ```
 ✓ Fixes implemented (scope: only the routed findings — nothing extra)
 ✓ Gate RUN and green (exit codes pasted)
+✓ Never edit an existing test's expectation to match behaviour — a setup
+  repair keeps assertions at least as strong and never touches expectations
 ✓ Per-phase / unit docs updated where the finding touched them
   (known-issues.md entry resolved? progress.md notes the fold)
 ✓ Each folded finding's row in the unit's `review-findings.md` ledger (if one
@@ -39,8 +41,7 @@ Final-phase / single-pass / fix hand-off:
 <unit> implemented, gate green, marked done.
 PR opened: <FULL PR URL — always printed here; not every agent shows open PRs>
 Roadmap/fix-index row: done · #<n> (linked and pushed)
-→ Next: /loop-review-fold <unit> (recommended review/fold router; unresolved findings go to triage/replan)
-  · manual path → /review-change
+→ Next: /fold-findings, then re-run /review-change (unresolved findings go to triage/replan)
   · clean    → /audit-pr (merge gate) → human merges
   · findings → fold fix-now into this PR; independent work remains a proposal until user triage; re-review
   · docs site declared (documentation map has a `Docs site` block) →

package/skills/execute-phase/references/UNIT_LOOP.md

@@ -82,7 +82,6 @@ UNIT LOOP — <unit> COMPLETE
 Phases: <n> · Commits: <sha list> · Acceptance: <blob> · Gate: PASS
 PR: <url>
 
-→ Next: /loop-review-fold <unit> — select the persisted review/fold route, then triage or replan unresolved findings
-  · manual path → /review-change, then /fold-findings and re-review as required
+→ Next: /fold-findings, then re-run /review-change on the changed HEAD — triage or replan unresolved findings
   · merge gate after REVIEW-PASS → /audit-pr
 ```

package/skills/fold-findings/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: fold-findings
 user-invocable: true
-version: 1.2.2
+version: 1.3.0
 argument-hint: [finding-id …]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/fold-findings/references/FOLD_POLICY.md

@@ -31,6 +31,8 @@ A finding is `FOLDED` only when **all** of these hold:
 ✗ Adding a known-issues.md / backlog entry instead of fixing the code
 ✗ A decisions.md tradeoff note that accepts the defect as-is
 ✗ Deleting, skipping (.skip, .only elsewhere), or loosening a test to make it pass
+✗ Editing an existing test's expectation to match behaviour — a setup repair
+  may only keep assertions at least as strong and never touch expectations
 ✗ eslint-disable / @ts-ignore / equivalent suppression AS the fix
 ✗ A TODO/FIXME stub left in place of the actual fix
 ✗ Ticking `folded: yes` without a reviewer-mappable diff behind it
@@ -41,3 +43,8 @@ A finding is `FOLDED` only when **all** of these hold:
 
 Something forbidden looks like the only option → stop, do not apply it, and
 mark the finding `DISPUTED` or `BLOCKED` with the reason instead.
+
+Never edit an existing test's expectation to match behaviour: a setup repair may
+only keep assertions at least as strong and never touch expectations; the
+test-immutability contract (`verification-contract`) owns the sole amendment
+path.

package/skills/log-session/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: log-session
 user-invocable: true
-version: 2.0.0
+version: 2.1.0
 argument-hint: "[note to prepend to the entry]"
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -86,6 +86,12 @@ the HEAD sha and start time at session open.
    - **Next:** the concrete next step(s) — the command to run, the unfinished
      thread, the open question. Write it so a cold reader knows exactly where to
      resume.
+   - **Status words are forge-verified.** `merged`, `closed`, `approved` — any
+     claim about a PR/issue state is checked with the forge in the same turn
+     (`gh pr view <N> --json state,mergedAt`) before it is written. A log that
+     records a state the forge contradicts is a false record that the next
+     review must chase (fix #157's F14). Write the actual state: "PR #N open,
+     awaiting the human merge".
 
 4. **Append the entry** to `docs/LOGS.md`, newest at the bottom (append-only,
    chronological). Use this format so the auto-hook entries and these stay

package/skills/plan-feature-scaffold/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-feature-scaffold
 user-invocable: false
-version: 2.1.0
+version: 2.2.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -56,6 +56,18 @@ The [verification contract](<../verification-contract/SKILL.md>) owns the
 `ACCEPTANCE.md` schema, validation ladder, and anti-weakening rules. Consume it
 after the engineering plan is complete and before registering `planned`.
 
+## Research and reference trace (plan stage)
+
+- **Conditional web research.** Plan-stage research runs only when a bounded
+  question (ROWS.md Q1–Q5) cannot be answered from repository evidence: run
+  exactly one web pass before the phases are emitted and freeze what it
+  returns as evidence rows (URL and access date). A question the repository
+  answers is never re-fetched.
+- **Mandatory reference trace.** Affected code is located by symbol/reference
+  search — LSP/serena when the environment offers it, grep otherwise — and the
+  blast radius is derived from that search, never from model memory: added or
+  changed code can break callers the plan must name.
+
 ## Guardrails
 
 - Docs only. No source edits, migrations, or dependencies.

package/skills/plan-fix/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-fix
 user-invocable: true
-version: 3.0.1
+version: 3.1.0
 argument-hint: <issue-number> [<issue-number> …]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -68,6 +68,18 @@ One or more GitHub issue numbers from this repo, space-separated.
 - One local commit with SPEC and `docs/fix/README.md` (`pending`, all merged issues).
 - **Stop: do not push/open PR.** Hand off to `review-plan`, then `execute-phase --fix`.
 
+## Research and reference trace (plan stage)
+
+- **Conditional web research.** Plan-stage research runs only when a bounded
+  question (ROWS.md Q1–Q5) cannot be answered from repository evidence: run
+  exactly one web pass before the phases are emitted and freeze what it
+  returns as evidence rows (URL and access date). A question the repository
+  answers is never re-fetched.
+- **Mandatory reference trace.** Affected code is located by symbol/reference
+  search — LSP/serena when the environment offers it, grep otherwise — and the
+  blast radius is derived from that search, never from model memory: added or
+  changed code can break callers the plan must name.
+
 ## Hard rules
 
 - Honor Workflow conventions: create `fix/<n>-<topic>` first, never `main`; gate,

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

@@ -1,7 +1,7 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 1.5.0
+version: 1.7.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >

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

@@ -135,7 +135,7 @@ and is out of scope; a copy or shell rewrite stays the reviewer's job.
 ```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:review-mark + audit-pr:audit-rows + triage-issue:triage-rows + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | node --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 + audit-pr:audit-rows + triage-issue:triage-rows + fold-findings:folded-flag | scripts/ledger-provenance.mjs | · fold <sha> + · ticked <sha> + · REOPENED | node --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 | node --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 | node --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 | node --test scripts/ledger-ownership.test.mjs
@@ -172,3 +172,25 @@ REVIEW-RAN | HEAD <40-hex sha> | n/a | n/a | review-mark | n/a | n/a
 other cells carry `n/a` because the row reports no finding — which keeps it out of
 the fix-now projection, `fold-findings`, and the annotator (its pattern matches
 `F<n>` ids only). A mark says a review ran, never that the candidate passed.
+
+### The durable finding mark
+
+A candidate finding that verifies — or refutes — before persistence gets a
+per-finding durable signature of its own, under `review-change:finding-mark`.
+This is the fix/161 extension of the feature-28 treatment: a verdict has a
+signature, so must the individual finding. The single writer of every finding mark is `review-change`; nothing else appends one.
+
+```text
+finding-mark@1
+id | file:line | axis | severity | class | route | folded
+VF-<n> | <file:line> · reviewer review-change · HEAD <40-hex sha> · recheck <method + reproducer> | <axis> | confirmed | finding-mark | n/a | n/a
+```
+
+`VF-` ids are deliberately outside the `F<n>` range the provenance annotator's
+row pattern matches, so a finding mark is invisible to the recount, to
+`--check`, to `--annotate`, and to the fix-now projection. A `confirmed`
+finding's row carries the mark; a `refuted` candidate carries its
+counter-evidence in the same report and **never becomes a row**, a fold task,
+or a re-review trigger. The mark's `confirmed | refuted` value and the
+`recheck` cell (the method the finding's axis demands) are what let a driver
+outside the repo consume the verification the review performed.

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

@@ -86,7 +86,7 @@ outside this policy and can never be translated into a PASS.
 - An automatic forge issue. No route in the pre-execution set — `evidence-grounding`
   readiness, `review-spec`, `review-plan`, `plan-feature-scaffold`, `plan-fix`,
   `execute-phase`, `workflow-status`, `ship-roadmap`, `review-change`,
-  `loop-review-fold`, `audit-pr` — creates one for a planning gap, and none defers
+  `audit-pr` — creates one for a planning gap, and none defers
   an obligation to a future issue: the row stays in the unit's ledger, open, until
   the **user** amends the governing SPEC. A blocker that says "file an issue" is a
   contract violation, not a workaround, and a `deferred` row without an amendment is

package/skills/review-a11y/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-a11y
 user-invocable: false
-version: 1.0.1
+version: 1.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -35,6 +35,15 @@ default branch. State the scope at the top of the returned table.
 ✓ Motion/animation respects reduced-motion preferences (n/a if no motion added)
 ✓ Error messages programmatically associated with their fields
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-brand/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-brand
 user-invocable: false
-version: 1.0.1
+version: 1.1.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -40,6 +40,15 @@ default branch. State the scope at the top of the returned table.
   labeled the same way everywhere)
 - ✓ Placeholder/lorem text absent from the diff
 
+## Materiality bar
+
+Report a row only when a competent user's outcome changes or a rule the project
+explicitly declares is violated — cite the rule it violates beside the evidence.
+Not findings: comment/punctuation typos, formatting-only drift, style preference
+with no cited rule, hypothetical robustness beyond the SPEC's named scenarios.
+An empty table with `Decision: PASS` is the expected result for a well-formed
+change — never pad the table.
+
 ## Return exactly
 
 ```

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 2.12.0
+version: 3.2.1
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -81,19 +81,19 @@ Every axis maps to a skill of the workflow's **own internal review pack**
 | API ergonomics / usage docs (inline pass) | if API | if API | flags/help | ✓✓ | ✓ |
 
 > `review-implementation` (the single classifier over the synthesized table —
-> process step 7) and `review-debt` (the debt transform over the classified
-> table — process step 8) are not axis finders: they run once per review, not
+> process step 8) and `review-debt` (the debt transform over the classified
+> table — process step 9) are not axis finders: they run once per review, not
 > per axis.
 
 ## Isolation rule (default — every pass, not only adversarial)
 
-Each applicable pass, the classifier (step 7), and debt transform (step 8) runs
+Each applicable pass, the verification pass (step 6), the classifier (step 8), and debt transform (step 9) runs
 **isolated/context-clean** and returns only its fixed findings table plus
 `PASS | FAIL`—never diff or prose. Spawn one fresh subagent/headless run per
 pass; without those, use a fresh conversation. Pass only scope, its checklist,
 and Step 0 docs; cap full non-diff reads at 10 (targeted ≤50-line reads/greps
 excluded). The orchestrator retains tables, not sources, and fuses them in step
-6. Inline fallback is sequential table reduction. A pass runs at its own tier or
+7. Inline fallback is sequential table reduction. A pass runs at its own tier or
 stronger, never weaker.
 
 
@@ -143,8 +143,11 @@ only for independent proposals (D3). It is Stage 4: checkpoint reviews are
 optional, the end review is mandatory and fresh. `fix-now` folds in-unit,
 `replan-in-unit` adds user-confirmed phases, and independent work becomes
 proposals. `audit-pr` consumes only the verified PR-comment receipt, never the
-chat report; `product-audit` is the periodic sweep;
-`loop-review-fold` may run this skill fresh and route FAIL to `fold-findings`.
+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
+user instruction, per `REVIEW_PROCESS.md`); a programmatic outer driver may run
+the same review→fold sequence.
 
 ## Done when
 

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

@@ -35,7 +35,9 @@ lost, and none becomes reviewer-created backlog (D3):
 - **ignore** → note the rationale in the report; no further action.
 
 The report's `Decision:` line is **three-state** (D10): `REVIEW-PASS` when the
-table is clean, `REVIEW-FAIL` while any fix-now finding is open, and
+table is clean (the ledger carries only `high`/`med` fix-now rows — `low`
+findings are report-only notes that never block), `REVIEW-FAIL` while any
+fix-now finding is open, and
 `NEEDS-DECISION` when a decision-required finding blocks. Only `REVIEW-PASS`
 **and only when the PR exists** posts the idempotent exact-SHA receipt (step 13
 of *Persist and decide*); `REVIEW-FAIL` leaves findings in the fold ledger and

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

@@ -12,19 +12,33 @@
 
    **Merged unit → no write** (a PR exists and its state is `MERGED` — check
    `gh pr view --json state` when a PR is open; otherwise the unit is unmerged
-   by definition). Otherwise, for each **fix-now** finding: append a row
-   (create the file with the header row if it doesn't exist yet), carrying the
-   verbatim `Sev` value into `severity`; `folded` always starts `no` —
+   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
+   (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`.
-   Re-runs **dedupe by `file:line` + axis** (the same rule the adversarial mode
-   uses to merge reviewer findings, above): a finding already on the ledger at
-   that `file:line`+axis is not re-appended; a genuinely new finding gets the
-   next `Fn` id. **Non-fix-now findings are never written here** — they keep
-   their destinations from step 10 (outcome routing): independent future
+   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**:
+   a row already on the ledger at that `file:line`+axis is not re-appended;
+   a re-report at a folded row's location is legitimate only as `regression of <id>`
+   (fix provably failed) or `DISPUTED`; else `Fn+1`.
+   **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;
+   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.
 12. **Close out the final-review receipt before reporting.** First derive the
-   `Decision` from step 6 and persist step 11. Then, before printing any line of
+   `Decision` from step 7 and persist step 11. Then, before printing any line of
    the fixed report block or the `→ Next:` block, complete the receipt action
    below. The receipt is a precondition of the report, not a follow-up.
 
@@ -75,19 +89,25 @@
    Architectural invariants: pass | finding (<ID>) | n/a: no project invariants declared
    Receipt: current at <head SHA> | n/a: no PR | none: REVIEW-FAIL/NEEDS-DECISION
 
-   <the synthesized decision table (step 6)>
+   <the synthesized decision table (step 7)>
 
    Manual verification (a human must check):
    - <item> …
 
-   Proposals (step 10): <n> — batched for the user, no issues created (D3)
+   Notes (low · report-only, never persisted):
+   - <finding + evidence, or none>
+
+   Refuted (verified false — reported with counter-evidence, never persisted):
+   - <candidate + counter-evidence, or none>
+
+   Proposals (step 11): <n> — batched for the user, no issues created (D3)
 
    Summary: <1-2 sentences>
    Decision: REVIEW-PASS | REVIEW-FAIL | NEEDS-DECISION   (D10: review says these three; only audit-pr says MERGE-READY)
    ```
 
 14. **Next step.** The `→ Next:` block is **never one static template** — branch
-   on the `Decision` value from step 6 and emit the matching block **verbatim,
+   on the `Decision` value from step 7 and emit the matching block **verbatim,
    as multiple literal lines**. Never join the `·` sub-bullets into one prose
    line — each sub-bullet is its own line, exactly as quoted below.
    For `REVIEW-FAIL` or `NEEDS-DECISION`, list every open finding ID in the
@@ -98,9 +118,9 @@
    passing receipt was posted** (step 12):
 
    ```
-   → Next: /loop-review-fold <unit> — repair all open fix-now findings: <F1> + <F2> + <F3>,
-     then re-review changed HEADs within the bounded correction budget
-     · manual path → /fold-findings, then re-run /review-change
+   → Next: /fold-findings — repair all open fix-now findings: <F1> + <F2> + <F3>,
+     then re-run /review-change on the changed HEAD (bounded at two cycles; a
+     third cycle never starts without an explicit user instruction)
      · /audit-pr → only after the table is clean (not yet — findings open)
       · any finding routed replan-in-unit? → confirm the proposed SPEC phase(s),
         then /execute-phase on this same branch (yes: list the finding ids; no: