@gtrabanco/pi-agentic-workflow 0.6.0 → 0.7.0

package/package.json

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

package/skills/fold-findings/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: fold-findings
 user-invocable: true
-version: 1.3.0
+version: 1.4.0
 argument-hint: [finding-id …]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -92,6 +92,37 @@ 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 to route to planning.
+
 ## Guardrails
 
 Scope is the ledger (or explicit ID subset); unlisted discoveries are proposals
@@ -139,3 +170,30 @@ or touched outside the queue.
 
 Replace placeholders with every actual affected finding ID before printing; never
 print `<F2>`, `…`, or a single representative ID in a live hand-off.
+
+## Closing-block decision branch (choose one, at emission)
+
+The closing block picks exactly one of four outcomes. The **no-decision →
+re-review default** holds whenever the turn carries no recorded prior consumer
+decision to skip.
+
+| Batch state | Branch | `→ Next:` (consumer) |
+|---|---|---|
+| freeze-batch (≥ 1 replan-class row) | `REPLAN-ROUTE` | plan-fix/execute-phase on this unit after the user confirms the replan |
+| `all-repair-in-place` + docs-only + no folded row severity `high` + prior consumer skip decision | `RE-REVIEW-SKIPPED` | skip — consumer has explicitly decided to skip the re-review |
+| `all-repair-in-place` + docs-only + no folded row severity `high` | `RE-REVIEW-OPTIONAL` | `/review-change` (default, delta mode) — or the consumer's recorded skip decision |
+| empty batch (class `none`) | `RE-REVIEW-OPTIONAL` | `/review-change` by default — safe: the head is unchanged |
+| anything else (behavioral surface or any folded row `high`) | `RE-REVIEW-REQUIRED (delta)` | `/review-change` — delta mode mandatory default |
+
+**Branch-selection decision inputs.**
+
+- **Docs-only test (E-D3).** ``RE-REVIEW-OPTIONAL`` requires every fold-diff
+  file to be a Markdown/documentation file; otherwise the batch is behavioral
+  (→ `RE-REVIEW-REQUIRED (delta)`).
+- **Frozen-severity-`high` override.** A folded row whose frozen severity is
+  `high` forces `RE-REVIEW-REQUIRED (delta)` even on a docs-only diff. Frozen
+  fields are never edited to reach a branch.
+- **SKIPPED requires prior consumer decision (E-D2).** `RE-REVIEW-SKIPPED`
+  is printed only by a turn carrying an explicit prior consumer decision to
+  skip. A turn with no recorded prior consumer decision prints
+  `RE-REVIEW-OPTIONAL` + the re-review default, **never** `RE-REVIEW-SKIPPED`.

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

@@ -48,3 +48,16 @@ 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.
+
+## Reproducer handoff (materialize, never re-derive)
+
+Before repairing a **behavioral** finding, read the row's `finding-mark@1`
+`recheck` cell (method + reproducer, written by `review-change` at verification
+time) and materialize it as the regression check — the method as written (red
+test first, reproducible command output, or direct read). The fold runner
+**never invents or re-derives** the reproducer; it consumes the cell as the
+allowed materialization.
+
+- A `recheck` cell that cannot be materialized as a runnable check yields
+  `BLOCKED <missing input>` and names the missing input.
+- Never substitute a weaker re-derived check for the recorded reproducer.

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

@@ -2,7 +2,9 @@
 
 1. **Build the queue.** Take every `folded: no` fix-now row, or the explicit ID
    subset, in severity/id order. `replan-in-unit` rows emit `REPLAN`; they stay
-   on the same SPEC/branch/PR and never become issues.
+   on the same SPEC/branch/PR and never become issues. **Empty batch:** an
+   empty queue (zero findings taken) prints a REPAIR-RECEIPT with batch class `none`
+   and nothing folded — a receipt only, no flips, no commits.
 2. **Form the fewest atomic correction groups.** Findings may share one group
    only when all boxes pass:
 
@@ -33,9 +35,44 @@
    member so no finding disappears inside the batch.
 6. **Continue groups.** A blocked/disputed group does not prevent independent
    groups from folding. Leave its rows `no` and emit individual outcomes.
-7. **Disputes.** Non-reproducible/already-fixed/wrong findings become
+   **Failed gate:** if the group's gate is red, do not fold the group — the
+   receipt records the observed gate exit codes and nothing is folded for it;
+   never silence the receipt and never commit red.
+7. **Batch classification.** The batch class derives from the taken queue's
+   frozen rows only, and the fold never reclassifies:
+
+   | Condition over the taken batch | Batch class | Fold behavior |
+   |---|---|---|
+   | ≥ 1 row with frozen class `replan-in-unit` or `decision-required` | `frozen (replan present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the REPLAN-ROUTE and every retained (unfolded) row id; the loop stops and routes to planning |
+   | all taken rows foldable, none replan-class | `all-repair-in-place` | fold as today (group → fix → gate → commit → flip) |
+   | empty queue (zero findings taken) | `none` | receipt only |
+
+   The batch-class vocabulary references only `review-implementation`'s closed
+   class set (`CLASSIFY.md`); the receipt invents no parallel vocabulary.
+
+   The emitted branch follows the closing-block decision inputs in the skill:
+   a freeze-batch always selects `REPLAN-ROUTE`; otherwise the docs-only
+   file-set test (E-D3) and the frozen-severity-`high` override (E-D2) select
+   `RE-REVIEW-OPTIONAL` vs `RE-REVIEW-REQUIRED (delta)`.
+8. **Disputes.** Non-reproducible/already-fixed/wrong findings become
    `DISPUTED <evidence → user decision>`; never edit classification or create an
    issue.
-8. **Replan.** If the smallest correct group exceeds a reviewable correction,
+9. **Replan.** If the smallest correct group exceeds a reviewable correction,
    emit `REPLAN` with proposed phases appended to the same unit. After user
    confirmation, `/execute-phase <unit>` completes them and ticks the rows.
+
+## REPAIR-RECEIPT — fixed printed block (verbatim copy)
+
+Printed after the per-finding table and tally, as part of the ABSOLUTE-last
+output together with the branching `→ Next:` block. Six fields, always
+present:
+
+```text
+## 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>
+```

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

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

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

@@ -194,3 +194,9 @@ 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.
+
+`fold-findings` reads the `recheck` cell to **materialize** the finding's
+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.

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.3.0
+version: 3.4.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

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

@@ -21,6 +21,37 @@
    same location. A cycle ≥ 2 that produces any new fix-now row appends the
    `CONVERGENCE-ANOMALY` block (`pre-execution-review/references/POLICY.md` §4)
    to the report.
+
+   **Delta mode (default on a post-fold re-review).** When the preceding fold
+   receipt's branch is `RE-REVIEW-REQUIRED (delta)` — or `RE-REVIEW-OPTIONAL`
+   acted on with the re-review decision — the review runs **delta mode**:
+
+   1. Re-verify every `folded: yes` row at the `file:line` cited in its
+      `review-findings.md` row (the existing cycle-≥2 rule above);
+   2. Review the **fold diff only** (`git diff <pre-batch HEAD>..<batch HEAD>`
+      over the commits this turn's batch produced);
+   3. Require the **gate green at the reviewed head** and the sibling
+      `ACCEPTANCE.md` blob recomputed to an **exact match** — the step-2
+      structural precondition, unchanged and still mandatory;
+   4. Append the normal `review-mark@1` `REVIEW-RAN` mark — delta cycles count
+      toward the two-cycle cap from the unchanged source (marks + forge
+      receipts), never a fresh reset;
+   5. Admit a candidate only when **genuinely new**: a same-`file:line`+axis
+      re-report inside the delta scope is admitted only as
+      `regression of <id>` or `DISPUTED`, never a plain new row (extending the
+      cycle-2 rule to the whole delta scope);
+   6. A clean delta pass posts the normal SHA-bound `REVIEW-PASS`.
+
+   **Escalation to a full pass.** Either trigger escalates a delta review to a
+   full pass, and the escalation **states which trigger fired and the observed
+   numbers**:
+
+   - **Width** — any changed file outside the union of the batch's cited files
+     (the folded rows' `file:line`), or any changed line in a cited file more
+     than **50 lines** from every cited line in that file (changed-line starts
+     read from `git diff --unified=0` hunk headers);
+   - **Size** — added+deleted changed lines **> 200**, or changed files
+     **> 15** (`git diff --numstat`).
 2. **Frozen acceptance + SPEC drift check (structural).** Locate sibling
    `ACCEPTANCE.md`, recompute its blob, and require an exact match with the
    execution receipt before assessing the candidate. Missing/mismatch is a
@@ -129,8 +160,10 @@
 
 The review→fold loop runs at most **two** review→fold cycles per unit, counted
 unit-level and family-agnostic from the ledger's `REVIEW-RAN` marks and forge
-receipts — new finding families do not reset the count. After two cycles without
-convergence, the review prints
+receipts — new finding families do not reset the count. **Delta cycles count
+from the same unchanged source** (the `review-mark@1` marks + forge receipts), so
+a delta-scoped re-review does not escape or reset the two-cycle bound. After two
+cycles without convergence, the review prints
 
 ```text
 LOOP CAP REACHED — <unit>