/fold-findings

name: fold-findings
user-invocable: true
version: 4.10.0
argument-hint: [finding-id …]
author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Repair persisted fix-now findings in compatible atomic batches: root-cause
  fixes, green gate, commit/push, and per-row `folded: yes` updates. Never
  reclassify or substitute backlog notes. Triggers: "fold-findings", "fix the
  review findings", "repair audit blockers".

Fold Findings

Repair persisted fix-now findings. `review-change` and `audit-pr` classify; this skill fixes each root cause, never relabeling, deferring, or weakening its check.

Turn contract

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn; box 1 of that contract (branch) and box 2 note the folded batches' gate runs. Skill-specific additions:

✓ 1. Every finding taken up this turn produced its fixed per-finding output
     line (FOLDED <sha> | NIMIO <note-path> | DISPUTED <reason> | BLOCKED <missing input> |
     REPLAN <proposed phase(s)>) — no finding silently skipped.
✓ 2. For each FOLDED batch: the gate was RUN (not assumed) and green, one
     atomic commit was RUN with its sha pasted, and (if the branch has an open PR)
     `git push` was RUN immediately after that commit.
✓ 3. The ledger row for each FOLDED finding was flipped `folded: no → yes`
     in the same commit — never a bare code fix with the ledger left stale.
✓ 4. No finding was reclassified: no severity downgrade, no fix-now →
     non-fix-now, no "actually this is fine" — a genuine objection produced
     `DISPUTED` with evidence for a user decision, never a silent drop/issue.
✓ 5. The closing `Folded: n/m · Disputed: k · Blocked: j[ · Replan: r]` tally
     and outcome-branched `→ Next:` block are printed as the ABSOLUTE last output.
     Every affected finding ID is named in that block, joined with ` + `.
✓ 6. Claim-evidence loop ran: before committing, every claim the repair
     introduces was reproduced with the command and observed output pasted
     into the claim table (`claim | command | output | status`). Loop ran until
     green inside the same turn. (S5)
✓ 7. Class escalation checked: ≥ 2 folded rows sharing mechanism+axis
     were escalated to one class-level fix-now finding. (S1)
✓ 8. Evidence-bound check: every finding citation was verified — the cited
     file:line exists and the snippet matches the working tree verbatim. (S10)
✓ 9. Reviewer anti-invention check: new findings are grounded in
     provably-changed bytes (git-computed) or a mis-run cited check. (S10)
✓ 10. Net narration diff ≤ 0 per fold: lines deleted, not moved. (S10)
✓ 11. Closure status printed: `closure: complete | open(n)`. (S4)

Missing reference → STOP. Any unchecked box means the turn is not done.

When to use

After `/review-change` reports `REVIEW-FAIL` with fix-now rows, or `/audit-pr` reports `VERDICT: BLOCKED` (every blocker is fix-now). If the ledger is absent or incomplete, reconstruct rows from the verdict in Step 0. Never process postpone/wontfix/promote/documented-tradeoff rows; those belong to `/triage-issue`.

Step 0 — Discover the project (always first)

Per Workflow conventions, read:

1. The unit's findings carrier: a migrated unit (issue #308) keeps its OPEN rows in its own `SPEC.md` under `## Findings`, with folded history and marks as `## Log` lines; a legacy unit keeps `review-findings.md` under `docs/features/<NN>-<slug>/` or `docs/fix/<n>-<topic>/`. Probe the doc first and fall back to the file — a unit with the section never reads both. Each carrier has **its own** schema, owned by `review-change`/`audit-pr` and stated for both shapes in `pre-execution-review/references/LEDGERS.md`:

• legacy (7 cols): `\| id \| file:line \| axis \| severity \| class \| route \| folded \|`

— closing a row flips `folded: no → yes`, and this skill is that flip's sole writer

• migrated (7 cols, `findings-table@1`): `\| id \| S# / file:line \| axis \| severity \|

impact \| class \| route \|` — every row it holds is OPEN; closing one **deletes the row** and appends a `## Log` `F` line naming the fold commit. There is no `folded` column to flip, and `class` here is the repairing owner (`product`/`plan`/`source`/ `environment`/`runtime`), not a disposition.

Never write one carrier's row into the other's grammar. After `VERDICT: BLOCKED`, append missing rows in the carrier's own schema (next free `Fn`, dedupe `file:line`+axis; legacy `class: fix-now`, `folded: no`), commit as `docs(<unit>): reconstruct fold ledger from audit-pr blockers`, then fold; never report “no findings”. 2. Queue the carrier's open rows — a legacy `folded: no` row, a migrated row of `## Findings` (all of them are open); explicit IDs restrict the queue and leave other rows untouched. Group by root cause, verifier and rollback boundary. 3. **Class escalation (S1).** After grouping: ≥ 2 folded rows sharing mechanism+axis ⇒ one class-level fix-now finding whose repair targets the *mechanism*, not a repeated instance. The two-cycle cap then means what it was built to mean: a class the loop refuses to repair is a planning defect, not more folds. Document the escalation as `F<next> (class: <mechanism>, replaces F<a> + F<b> + …)` in the ledger. 4. **Evidence-bound check (S10, from #218).** Before processing, verify every finding's citation: the cited `file:line` exists and the snippet matches the working tree verbatim. Wrong-citation and position-drift findings are discarded mechanically — `refuted` with evidence, no cycle consumed. 5. **Reviewer anti-invention check (S10, from #205).** Any new finding surfaced during fold must be grounded in **provably-changed bytes** (git-computed) or a **mis-run cited check** (the cited validator's own output contradicts it). A finding without changed-