@gtrabanco/pi-agentic-workflow 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.5.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/audit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: audit-pr
 user-invocable: true
-version: 5.0.3
+version: 5.1.0
 argument-hint: <pr-number> (optional — defaults to the current branch's PR)
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/audit-pr/references/02_CLOSURE_AND_SCOPE_GATES.md

@@ -95,7 +95,7 @@ verdict:
    `structural.reasonCode`/`changedPaths` name the drifted dimension), and — for a
    feature unit — its named `— spec` parent re-derives the same way. Bound artifacts
    are frozen: new implementation-phase files are allowed, edits to a bound artifact
-   are not. Stale, missing or wrong-stage lineage → **BLOCKED**,
+   are not. Stale, missing, wrong-stage **or impossible-timeline** lineage → **BLOCKED**,
    `→ Next: /review-plan <unit>` (or `/review-spec <unit>` when the parent is the
    broken link). A `SPEC-REVIEW-PASS` never satisfies the plan hop, and vice versa.
 2. **Obligations are closed.** Every row of the unit's obligation ledger is

package/skills/design-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: design-feature
 user-invocable: true
-version: 3.2.0
+version: 3.3.0
 argument-hint: <idea | NN-slug> [<instruction>]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/design-feature/references/REPAIR.md

@@ -65,6 +65,11 @@ further edit, then routes to that owner. More cycles stay allowed when
 correctness needs them; they never earn a PASS, and an exhausted cycle budget
 does not downgrade an open finding.
 
+A repair responding to a persisted verdict is **never** a loop defect (POLICY §4
+scopes every guard to blind re-reviews): a unit whose `progress.md` carries an open
+FAIL/NEEDS-DESIGN receipt is being repaired by definition, so no "already complete"
+answer exists for it and no cycle cap converts its verdict into a dead end.
+
 The spec-stage detail this skill adds: the owning stage of a Product-half miss is
 `product` unless the evidence proves the plan asked for something the SPEC never
 said — then it is `plan`, and it leaves this skill for `plan-feature`.

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.3.0
+version: 4.4.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>"

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

@@ -21,7 +21,7 @@ Actual:   <receipt state — what was read, and `structural.changedPaths` +
           `structural.reasonCode` from the verify run naming which bound file moved>
 
 → Next: /review-plan <NN>-<slug> — the plan needs a current independent review
-  · the review returned NEEDS-DESIGN / a Product-rooted finding → /design-feature <NN>-<slug>
+  · the review returned a Product-rooted finding → /design-feature <NN>-<slug>
   · a bound artifact is genuinely wrong → /plan-feature <NN>-<slug> (re-cut), then re-review
   · no bypass flag exists for this gate: --force has never covered it and does not now
 

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/plan-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-feature
 user-invocable: true
-version: 5.0.0
+version: 5.1.0
 argument-hint: <NN-slug | #N> | --from-issue N | --scaffold <slug> | --next
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/plan-feature/references/ROUTING.md

@@ -29,10 +29,15 @@ SPEC's `## Design status` marker is the SPEC-local record and the
    → Next: /execute-phase <NN> <next-phase> — this feature is already being
      implemented; resume the current phase, don't re-plan it.
    ```
-4. **Roadmap row status `done`** → **STOP**. Print exactly:
+4. **Roadmap row status `done`** → **STOP** (replanning stays forbidden — the
+   feature is fully built), and: `done` means built + PR open with the human merge
+   pending (a lifecycle label, never a gate verdict), so this is **not** "nothing
+   pending". Route to the merge gate instead. Print exactly:
 
    ```
-   → Next: nothing — <NN>-<slug> already shipped (roadmap status `done`).
+   → Next: /audit-pr <PR> — done means built + PR open, merge pending (a lifecycle label, never a gate verdict)
+     · the row's PR is merged → nothing pending, pick the next unit → /plan-feature --next
+     · no PR is open → the row is mislabeled or execution stopped → /execute-phase <NN> (never a replan)
    ```
 5. **Roadmap row status `idea`, or no row at all** → **STOP**. Print exactly:
 

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

@@ -1,7 +1,7 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 2.0.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/pre-execution-review/references/POLICY.md

@@ -76,6 +76,13 @@ 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.
+
 ### 5. What a cycle can never produce
 
 - A verdict from an author turn, a readiness preflight, a roadmap status, or a
@@ -93,6 +100,14 @@ outside this policy and can never be translated into a PASS.
   an open row with a new name.
 - Execution authority from a neighbouring stage: a `SPEC-REVIEW-PASS` never unlocks
   `execute-phase`, and a `PLAN-REVIEW-PASS` never certifies the Product half.
+- A gate answer from a roadmap row's status. Gates read receipts only;
+  roadmap rows are labels and never answer a gate. `done` means built + PR open
+  with the human merge pending (`docs/features/ROADMAP.md` § Status legend;
+  `docs/fix/README.md` § Status legend), so it never satisfies or suppresses a
+  pre-execution/verification gate, never retires the obligation to re-derive a
+  receipt, and never lets a reviewer or consumer report a unit closed while its
+  PR is unmerged. The complement of §5's "no verdict *from* a status" — and the
+  same rule read the other way: a status never **suppresses** a gate either.
 
 ### 6. Legacy adoption (units planned before this gate existed)
 
@@ -142,6 +157,19 @@ reports; a printed verdict whose mark is still "for next turn" is not finished.
   a gate rejection. The mark is what the ownership map designates for that truth
   class — receipt block, folded row, rejection trace — at the home and column set
   [`LEDGERS.md`](LEDGERS.md) names. This section opens no second home.
+- **The reviewer is consumer zero.** Write-then-report is mechanical, not prose: in
+  the same act as persisting the receipt, the reviewer runs the sensor's own
+  `verify --stage <spec|plan> --unit <id> [--dir …]` (the fix unit's recipe; a
+  feature plan adds `--parent`) and pastes the sensor's JSON answer beside the
+  verdict block *before* the report is printed. A digest-bound receipt requires
+  `structural.fresh: true` (and, for a PASS verdict, `current: true`); exit 3
+  (`missing-receipt-snapshot`) or a digest-bound `structural.fresh: false` means
+  the mark did not land — the reviewer fixes the write and re-runs, and the verdict
+  is not emit-able in that turn. A `Snapshot: refused` receipt's
+  `missing-receipt-snapshot` answer is its sanctioned form. A verdict block
+  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:

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

@@ -105,6 +105,12 @@ sensor exists to catch: they carry no bound digest, so they fail as
 `missing-receipt-snapshot` rather than being interpreted charitably. Nothing here
 grants a verdict — only a reviewer turn writes the block.
 
+**The reviewer is consumer zero.** This re-verify recipe, run by the reviewer itself
+in the same act as persisting the receipt (POLICY §8), is the self-check that makes
+write-then-report mechanical: the reviewer runs `verify --stage …` for its own stage
+before it prints the verdict and pastes the sensor's answer beside the block. The
+recipe owner stays this file; §8 owns the rule the recipe serves.
+
 ### Authoring side: rotating the revision
 
 The author's `artifactRevisionId` is the field that lets a reviewer prove its own

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.2.1
+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/PERSIST_AND_DECIDE.md

@@ -135,6 +135,12 @@
      · adversarial recommendation checklist fired AND this run was
        single-reviewer? → re-run the fold review as /review-change
        --adversarial N (N per the ladder below) instead of single-reviewer
+
+   The two-cycle cap scopes the **review→fold loop on source findings** only (a
+   finding already on the branch, repaired here). A planning repair routed by a
+   `class: plan`/`product` finding is a **verdict response** under
+   `pre-execution-review` POLICY §4 — it re-derives plan/Product authority, not
+   source — so it is never a loop-defect stop and never counts against this cap.
        (yes: <which box fired>; no: omit this line)
      · SPEC drift flagged here AND on a prior unit? → /product-audit (yes: the
        founding assumptions are probably stale — don't keep patching a

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>

package/skills/review-plan/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: review-plan
 user-invocable: true
-version: 1.5.0
+version: 1.6.0
 argument-hint: <NN-slug | fix-N | path/to/SPEC.md> [--adversarial N]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
   Independent read-only review of a frozen Engineering plan before execution, in a
   context that did not cut it: feature or fix snapshot, obligation ledger sweep,
-  phase and validator checks. Returns only PLAN-REVIEW-PASS, PLAN-REVIEW-FAIL, or
-  NEEDS-DESIGN with a snapshot-bound receipt. Never edits a plan artifact.
+  phase and validator checks. Returns only PLAN-REVIEW-PASS or PLAN-REVIEW-FAIL
+  with a snapshot-bound receipt (a product-intent gap is PLAN-REVIEW-FAIL with
+  `class: product`). Never edits a plan artifact.
   Triggers: "review-plan", "review the plan", "review the phases".
 ---
 
@@ -81,7 +82,7 @@ another `references/` path.
 |---|---|---|
 | Roadmap row read, unit kind known (feature or fix) | [checks](references/CHECKS.md) — snapshot construction, falsification, the L1–L6 ledger sweep | [eng-checks](references/ENG-CHECKS.md) and [output](references/OUTPUT.md) |
 | Snapshot bound and the ledgers swept clean enough to judge the plan | [eng-checks](references/ENG-CHECKS.md) — P1–P12, plus F1–F4 for a fix unit | [output](references/OUTPUT.md) until every check has a result |
-| Any check failed, the parent receipt is missing/stale, or a product choice is open | [output](references/OUTPUT.md) for the FAIL / `NEEDS-DESIGN` block and route | — |
+| Any check failed, the parent receipt is missing/stale, or a product choice is open | [output](references/OUTPUT.md) for the FAIL block (product-intent gaps get `class: product`) and route | — |
 | A prior Plan receipt exists for this unit | [output](references/OUTPUT.md) §Repeats for the no-progress / convergence gate before re-running anything | never blend rows from two snapshots |
 
 ## Guardrails
@@ -98,12 +99,13 @@ another `references/` path.
   candidate `ReviewReceipt` or a staged `VerificationReceipt` answers different
   questions and never stands in for a Plan review. A missing parent receipt is
   reported, not repaired by assumption.
-- **Three verdicts only.** Exactly `PLAN-REVIEW-PASS | PLAN-REVIEW-FAIL |
-  NEEDS-DESIGN`. No partial pass, no "approve with caveats", no SPEC verdict, no
-  generic "approved" verb (PD1).
+- **Two verdicts only.** Exactly `PLAN-REVIEW-PASS | PLAN-REVIEW-FAIL`.
+  No partial pass, no "approve with caveats", no SPEC verdict, no generic
+  "approved" verb (PD1). The design-verdict token is not a verdict at this stage — a gap
+  requiring invented product intent is `PLAN-REVIEW-FAIL` with `class: product`.
 - **No engineering decisions invented.** Where the right phase cut, validator, or
   migration depends on a product choice this review cannot make, return
-  `NEEDS-DESIGN` and route it to the human through `design-feature` — invalidating
+  `class: product` and route it to the human through `design-feature` — invalidating
   downstream Plan evidence is the point.
 - **No source fixes.** A plan defect that this turn could "just patch" is still a
   defect: report it and route it. Implementing while reviewing collapses the gate.

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

@@ -13,7 +13,7 @@ One `PreExecutionReviewReceipt v1`
 
 ```text
 ## Pre-execution review receipt v1 — plan
-- Review: <receipt-id> · Snapshot: <64-hex|refused> · Verdict: <plan-review-pass|plan-review-fail|needs-design>
+- Review: <receipt-id> · Snapshot: <64-hex|refused> · Verdict: <plan-review-pass|plan-review-fail>
 - Unit: <unitId> · Stage: plan · Unit kind: <feature|fix>
 - Parent SPEC snapshot: <64-hex> · Parent Product receipt: <receipt-id of the current SPEC-REVIEW-PASS>
 - Source revision: <40-hex> · Artifact revision: <artifactRevisionId>
@@ -52,6 +52,26 @@ verdict, and file one finding row per refused artifact carrying its code verbati
 checks bind to a snapshot, so with no snapshot none of them ran. `SNAPSHOT.md` owns why
 a refusal prints no digest and what a consumer then reads this receipt as.
 
+**Self-check (`verify --stage plan …`, POLICY §8).** In the same act as appending the
+receipt, run the recipe owner's re-verify for this stage and paste the sensor's JSON
+answer beside the verdict block before reporting. A feature plan run names `--parent`
+(the Product digest this plan descended from); a fix unit omits it (it binds none):
+
+```bash
+# feature plan — binds the Product snapshot it descends from
+node scripts/pre-execution-snapshot.mjs verify --stage plan --unit <NN-slug> --dir docs/features/<NN>-<slug> --unit-kind feature --parent <64-hex>
+# fix unit — no Product half exists (D6)
+node scripts/pre-execution-snapshot.mjs verify --stage plan --unit fix-<N> --dir docs/fix/<N> --unit-kind fix
+```
+
+A digest-bound receipt requires `structural.fresh: true` (and, for a PASS verdict,
+`current: true`); `exit 3` (`missing-receipt-snapshot`) or a digest-bound
+`structural.fresh: false` means the mark did not land — fix the write and re-run, the
+verdict is not emit-able in this turn. A `Snapshot: refused` receipt's
+`missing-receipt-snapshot` answer is its sanctioned form. A verdict block printed
+without the pasted self-check output is a contract defect — chat-only is
+`missing-receipt-snapshot` to every consumer.
+
 ### Verdict blocks — return exactly one
 
 ```text
@@ -72,20 +92,11 @@ PLAN-REVIEW-FAIL — <NN-slug|fix-N> BLOCKED
 - Parent state: <current | stale-parent → review-spec first | missing → review-spec first>
 ```
 
-```text
-NEEDS-DESIGN — <NN-slug|fix-N>
-- Snapshot: <digest> · Blocking rows: <Lnn / Pnn / obligation-id>
-- Missing choice (product authority only): <one bounded question>
-- Recommended default: <the smallest coherent answer>
-- Downstream: this Plan receipt and every execution decision bound to the parent
-  Product half are invalid until the answer lands and the Product half is re-reviewed
-```
-
-`NEEDS-DESIGN` when the answer requires inventing product intent, scope, role,
-authority, or user outcome; `PLAN-REVIEW-FAIL` when the plan is decidable but
-incomplete, contradictory, unowned, or unsupported. Never blend them; never emit
-a fourth verdict, a generic "approved", or a `SPEC-REVIEW-*` verdict from this
-stage.
+`PLAN-REVIEW-FAIL` when the plan is decidable but incomplete, contradictory,
+unowned, or unsupported. A gap that requires **inventing product intent is
+`PLAN-REVIEW-FAIL` with `class: product`** — the design-verdict token is not a
+verdict at this stage: only `review-spec` may emit it. Never emit a generic
+"approved" or a `SPEC-REVIEW-*` verdict from this stage.
 
 ### Routes
 
@@ -104,7 +115,6 @@ not authority.
 | `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: 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 |
-| `NEEDS-DESIGN` | the human, through `design-feature` | dated amendment → new Product revision → `review-spec` → `plan-feature` replan → `/review-plan` again |
 
 Repeating this review follows the no-progress and convergence rules in
 `pre-execution-review/references/POLICY.md` §4 — a repeat needs
@@ -121,6 +131,10 @@ into `review-change → fold-findings`, which repairs source, not plan authority
 ✓ L1–L6 resolved, and every applicable P/F check resolved to pass / finding / n/a
 ✓ Obligation ledger swept row by row: none blank, deferred, duplicated, unvalidated
 ✓ One verdict block returned verbatim from the closed set
+✓ RUN `verify --stage plan` for this stage in-turn (feature plan names `--parent`;
+  fix omits it), JSON pasted beside the block; `structural.fresh: true` (+ `current: true` on PASS) —
+  `exit 3`/`structural.fresh: false` means the mark did not land, fix and re-run;
+  `exit 4`/`current: false` means a verdict persisted but not a PASS — the verdict itself is the emit result, route per verdict
 ✓ Receipt appended to progress.md and findings appended to planning-findings.md
 ✓ `git status --porcelain` shows no change to any reviewed plan artifact
 ✓ Closing `→ Next:` printed as the absolute last output
@@ -136,7 +150,7 @@ On PASS:
   · Product half moved after this receipt → the parent went stale: /review-spec <NN>
 ```
 
-On FAIL or NEEDS-DESIGN, name every finding id once, in order, joined with ` + `:
+On FAIL, name every finding id once, in order, joined with ` + `:
 
 ```
 → Next: /plan-feature <NN-slug> "<instruction>" (or /plan-fix <N> "<instruction>") —

package/skills/review-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-spec
 user-invocable: true
-version: 1.6.0
+version: 1.7.0
 argument-hint: <NN-slug | path/to/SPEC.md>
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT

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

@@ -42,6 +42,22 @@ verdict, and file one finding row per refused artifact carrying its code verbati
 checks bind to a snapshot, so with no snapshot none of them ran. `SNAPSHOT.md` owns why
 a refusal prints no digest and what a consumer then reads this receipt as.
 
+**Self-check (`verify --stage spec …`, POLICY §8).** In the same act as appending the
+receipt, run the recipe owner's re-verify for this stage and paste the sensor's JSON
+answer beside the verdict block before reporting:
+
+```bash
+node scripts/pre-execution-snapshot.mjs verify --stage spec --unit <NN-slug> --dir docs/features/<NN>-<slug> --unit-kind <feature|fix>
+```
+
+A digest-bound receipt requires `structural.fresh: true` (and, for a PASS verdict,
+`current: true`); `exit 3` (`missing-receipt-snapshot`) or a digest-bound
+`structural.fresh: false` means the mark did not land — fix the write and re-run, the
+verdict is not emit-able in this turn. A `Snapshot: refused` receipt's
+`missing-receipt-snapshot` answer is its sanctioned form. A verdict block printed
+without the pasted self-check output is a contract defect — chat-only is
+`missing-receipt-snapshot` to every consumer.
+
 ### Verdict blocks — return exactly one
 
 ```text
@@ -110,7 +126,10 @@ is ever lost between cycles.
 ✓ Snapshot digest computed from one revision and pasted; no mixed-revision bytes
 ✓ All 14 Product checks resolved to pass / finding / n/a with a reason
 ✓ One verdict block returned verbatim from the closed set
-✓ Receipt appended to the unit's progress.md before the report was printed
+✓ RUN `verify --stage spec` for this stage in-turn, JSON pasted beside the block;
+  `structural.fresh: true` (+ `current: true` on PASS) — `exit 3`/`structural.fresh: false` means
+  the mark did not land, fix and re-run, verdict not emit-able; `exit 4`/`current: false` means
+  a verdict persisted but not a PASS — the verdict itself is the emit result, route per verdict
 ✓ `git status --porcelain` shows no change to any reviewed artifact
 ✓ Closing `→ Next:` printed as the absolute last output
 ```

package/skills/ship-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship-roadmap
 user-invocable: true
-version: 5.1.0
+version: 5.2.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--fullauto] | --continue [--fullauto]"

package/skills/ship-roadmap/references/ADVANCE.md

@@ -42,9 +42,9 @@
    - **REVIEW-PLAN** (only between PLAN and EXECUTE) — compose `review-plan` in a
      clean context at the routed tier over the plan the previous stage just froze.
      `PLAN-REVIEW-PASS` releases EXECUTE. A FAIL routes by root cause: plan-local
-     (bad phase cut, blank validator, ledger drift) → one root-caused re-cut by the
-     planning author and a fresh review; product-rooted or an assumption this record
-     cannot settle → `NEEDS-DESIGN` → park as in REVIEW-SPEC. A second local cycle
+     (bad phase cut, blank validator, ledger drift) → root-caused re-cut by the
+     planning author and a review; product-rooted or an assumption this record
+     cannot settle → PLAN-REVIEW-FAIL with class: product → design-feature. A second local cycle
      that changes nothing stops editing and reports `CONVERGENCE-ANOMALY` instead of
      burning a third budget. **No stage between PLAN and EXECUTE may create a forge
      issue or defer an obligation to one** — an unmet obligation fails this stage, it

package/skills/workflow-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.1.0
+version: 3.2.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>]"

package/skills/workflow-status/references/PRE_EXECUTION.md

@@ -47,6 +47,7 @@ sensor reports a missing gate, never a verdict that no review ever happened.
 | `self-approved` | the author of the artifact recorded the PASS | that stage's review in a clean context |
 | `author-readiness` | an authoring readiness result sits where a verdict should be | that stage's review — readiness never licenses execution |
 | `legacy` | `planned`/`in-progress` unit with no ledgers and no receipt (predates feature 28) | the adoption route below |
+| `impossible-timeline` | `structural.fresh: false`, `structural.reasonCode: impossible-timeline` — digest and revision match by construction; a receipt's own recorded timeline is physically impossible (finish predating source revision's commit date beyond the published skew); a legacy receipt with no parsable Started/finished: line, or a source revision git cannot resolve, stays unflagged (fail-open) | that stage's review — the timeline is self-refuting, not a stale source |
 
 A stale receipt re-runs the **review**, not the authoring skill: the artifacts may be
 exactly right and simply need re-judging in a clean context. A missing verdict block,

package/skills/workflow-status/references/SENSOR_CORE.md

@@ -64,14 +64,18 @@ live evidence against a frozen ledger remains a contradiction candidate.
      command matched to the exact status: `defined` → `/plan-feature <slug>`,
      `planned` → `/execute-phase <NN>`.
    - deps unmet (any status ≥ `defined`) → `blocked_units` (unchanged).
-6a. **Sense the pre-execution receipts** for every unit at `defined`, `planned` or
-   `in-progress` ([pre-execution evidence](PRE_EXECUTION.md)): read the stage's
+6a. **Sense the pre-execution receipts** for every unit at `defined`, `planned`,
+   `in-progress`, **or `done` with a linked PR that is still open (unmerged — merge
+   state lives in the forge)** ([pre-execution evidence](PRE_EXECUTION.md)). A
+   done-but-unmerged row is a lifecycle label, never merge-ready, so a stale or
+   missing receipt there surfaces as a gate blocker; merged units stay excluded
+   (the merge itself closes their gates). Read the stage's
    newest receipt block, re-derive the bound digest with the recipe owner's
    verify mode (`node scripts/pre-execution-snapshot.mjs verify --stage
    <spec|plan> --unit <id> [--parent <64-hex>]` — a snapshot digest is a canonical SHA-256, never a
    git blob id; `structural.reasonCode` names the dimension that drifted), and
    label the stage `current`/`missing`/`stale`/`wrong-stage`/`substitute`/
-   `self-approved`/`author-readiness`/`legacy`. The label **overrides step 6's
+   `self-approved`/`author-readiness`/`legacy`/`impossible-timeline` (unresolvable revision or unparsable timeline: fail-open → unflagged). The label **overrides step 6's
    status-only command**: a unit without a current PASS for the stage it is about to
    enter is demoted out of `startable_now` into a `gate` blocker naming the missing
    review, and `detail.pre_execution[]` records the row. A roadmap row is never