/fold-findings

name: fold-findings
user-invocable: true
version: 1.5.1
argument-hint: [finding-id …]
author: "Gabriel Trabanco <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 — verify before ending the turn

✓ 1. Every finding taken up this turn produced its fixed per-finding output
     line (FOLDED <sha> | 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 ` + `.

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 `review-findings.md` under `docs/features/<NN>-<slug>/` or `docs/fix/<n>-<topic>/`; schema is owned by `review-change`/`audit-pr`:

   | id | file:line | axis | severity | class | route | folded |

After `VERDICT: BLOCKED`, append missing rows (`class: fix-now`, `folded: no`, next free `Fn`, dedupe `file:line`+axis), commit as `docs(<unit>): reconstruct fold ledger from audit-pr blockers`, then fold; never report “no findings”. 2. Queue `folded: no` rows; explicit IDs restrict it and leave other rows untouched. Group by root cause, verifier and rollback boundary. 3. The project's verification gate and forge CLI (use the declared forge). 4. Whether the branch has an open PR; this decides immediate push after commit.

Progressive loading — fold queue

The allowlist is exactly these two paths; read both, in order, before changing code or the ledger:

1. [frozen classification, definition of fixed, and forbidden actions](references/FOLD_POLICY.md) 2. [per-finding fold process](references/FOLD_PROCESS.md)

Both are normative and one hop from this file. Missing resource → stop; never infer a classification or fold procedure.

Report — return exactly this structure (fixed output contract)

Per finding, in processing order:

| <finding-id> | verdict: FOLDED <sha> | DISPUTED <reason → user decision> | BLOCKED <missing input> | REPLAN <proposed phase(s) → /execute-phase> |

Then exactly:

Folded: n/m · Disputed: k · Blocked: j · Replan: r

Omit `· Replan: r` when `r = 0` (preserves the existing three-field format).

Then print the REPAIR-RECEIPT as the ABSOLUTE-last output, together with the branching `→ Next:` block below. The receipt is immutable once printed; a later fold prints a new receipt (append-only output history — no ledger row, no schema field). Six fields, always present:

## REPAIR-RECEIPT
- Repaired: <F-ids with (VF-<n>) refs, joined ` + `, or `none`>
- Refuted/open: <F-ids joined ` + `, or `none`>
- Gate: <command> → exit <n> at head <40-hex sha> · n/a when nothing was folded
- Batch class: <all-repair-in-place | frozen (replan present) | none>
- Fold diff: <shortstat from a real `git diff` run> · none when nothing was folded
- Branch: <RE-REVIEW-REQUIRED (delta) | RE-REVIEW-OPTIONAL | RE-REVIEW-SKIPPED | REPLAN-ROUTE>

• The `Gate` line carries the actual exit codes observed at the head the gate

ran on — green or red. A **failed gate never silences the receipt**: the batch is reported with the observed exit codes and nothing folded (a red gate is not a silent gap).

• The `Fold diff` shortstat comes from a real `git diff` run over the batch's

commits.

• The `Batch class` derives from the taken queue's frozen rows only — the fold

never reclassifies (`all-repair-in-place`, `frozen (replan present)`, or `none` for an empty queue); the vocabulary comes from `review-implementation`'s closed class set.

**Freeze-batch (replan present).** When the taken queue contains any row whose frozen class is `replan-in-unit` or `decision-required`, nothing folds: no `folded: yes` flips, no commits. The receipt records the `REPLAN-ROUTE` branch and every retained (unfolded) row id, and the loop stops. The consumer is the conclusion the already-run router printed, never the invocation itself: on `route: replan` the planner it named — `/plan-fix <n>` for a fix unit or `/plan-feature <slug>` for a feature unit; on `route: decision` stop and surface the decision to the user, never a planner. `<unit>` is the bare folder number or the full slug (both resolve). The invocation `node scripts/unit-route.mjs <unit>` is the discovery step the fold already ran; it is never the recommendation.

Guardrails

Scope is the ledger (or explicit ID subset); unlisted discover