@gtrabanco/pi-agentic-workflow 0.7.1 → 0.8.0

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

@@ -5,7 +5,7 @@ digest**. One command produces it, so an author, a reviewer and a consumer canno
 drift apart while reading the same bytes.
 
 ```bash
-node scripts/pre-execution-snapshot.mjs build --stage <spec|plan> --unit <NN-slug|fix-N> \
+bun scripts/pre-execution-snapshot.mjs build --stage <spec|plan> --unit <NN-slug|fix-N> \
   [--dir <artifact-dir>] [--unit-kind <feature|fix>] [--artifact-revision <id>] \
   [--source-revision <sha>] [--parent <64-hex>] [--json <out-file>]
 ```
@@ -61,7 +61,7 @@ Rules the builder enforces and no caller may improvise around:
 ### Re-verifying a receipt (consumers)
 
 ```bash
-node scripts/pre-execution-snapshot.mjs verify --stage <spec|plan> --unit <NN-slug|fix-N> \
+bun scripts/pre-execution-snapshot.mjs verify --stage <spec|plan> --unit <NN-slug|fix-N> \
   [--dir <artifact-dir>] [--unit-kind <feature|fix>] [--receipt <receipt-id-or-digest>] \
   [--parent <64-hex>] [--policy <version>] [--source-revision <sha>] [--artifact-revision <id>]
 ```

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.4.0
+version: 3.5.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -37,6 +37,18 @@ For `REVIEW-FAIL` or `NEEDS-DECISION`, list every open finding ID in the closing
 recommendation, joined with ` + `; the review must never hand off only the first
 finding.
 
+## Review-end turn boundary
+
+On `REVIEW-FAIL` or `NEEDS-DECISION`, this skill **ends at the report**: it
+never invokes `/fold-findings`, `/execute-phase`, `/plan-feature`,
+`/design-feature` or `/triage-issue` — those are separate user-initiated invocations,
+run in a fresh turn (a programmatic outer driver may compose the same
+sequence in-turn, per `REVIEW_PROCESS.md`). The review's only mutations are the
+ledger commit (persist step 11) and, on `REVIEW-PASS` with a PR, the
+receipt comment (persist step 12); it never folds a finding, executes a phase,
+or edits code. A `REVIEW-FAIL`/`NEEDS-DECISION` turn closes when the report
+block is printed (report step 13).
+
 Consume the internal [verification contract](<../verification-contract/SKILL.md>);
 the reviewer checks the same frozen `ACCEPTANCE.md` blob as the executor before
 mapping candidate evidence.
@@ -140,7 +152,8 @@ Orchestrates internal finders (`review-code`, `review-security`, `review-verify`
 one `review-implementation` classifier and `review-debt` transform, isolated by
 default; installed platform packs are optional. `triage-issue` is user-invoked
 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,
+optional, the end review is mandatory and fresh. `fix-now` is routed to the
+unit's fold cycle — a separate `/fold-findings` invocation, never run by this review;
 `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. On `REVIEW-FAIL` the manual

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

@@ -21,10 +21,11 @@ Every finding gets a destination under the current-unit contract — none silent
 lost, and none becomes reviewer-created backlog (D3):
 
 - **fix-now** → persisted to the unit's `review-findings.md` fold ledger, then
-  folded into the current phase (unmerged work) — never a tracked issue, never
-  `plan-fix`. Classification honors `review-implementation`'s **current-unit
-  contract**: in-scope defects are always fix-now / replan-in-unit — never a
-  postpone/tradeoff/wontfix/new-issue escape.
+  routed to the current phase's fold cycle (`/fold-findings`, invoked after this review ends)
+  — never a tracked issue, never `plan-fix`. Classification honors
+  `review-implementation`'s **current-unit contract**: in-scope defects are
+  always fix-now / replan-in-unit — never a postpone/tradeoff/wontfix/new-issue
+  escape.
 - **fix-now / `replan-in-unit`** (too large to fold as-is) → keeps its fix-now
   class and ledger row; propose the new SPEC phase(s) to the user, then
   `execute-phase` on the same branch folds it.

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

@@ -37,6 +37,10 @@
    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.
+   This skill's only mutations are this ledger commit (step 11) and, on
+   `REVIEW-PASS` with a PR, the receipt comment (step 12) — it never runs a
+   fold, executes a phase, or edits source (see the review-end turn boundary in
+   the SKILL.md Turn contract).
 12. **Close out the final-review receipt before reporting.** First derive the
    `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
@@ -112,6 +116,10 @@
    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
    closing recommendation, joined with ` + `; never hand off only the first.
+   The `→ Next:` block is a **recommendation, not a to-do list**: it names what
+   the *next* user-initiated invocation should be, and this turn ends when the
+   report block (step 13) is printed — emit the block and end the run; do not
+   begin the recommended command.
 
    **`Decision: REVIEW-FAIL`** (any fix-now finding open) — the recommended line
    is the fold, never the merge gate. Findings were persisted in step 11; **no

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

@@ -148,8 +148,8 @@
    and a human must check — visual correctness, real-device/locale behavior, UX
    feel, perf under load, anything marked *verify*. Be explicit so the dev has zero
    doubt about what to eyeball.
-11. **Route the outcomes.** fix-now findings fold into the current unit (or gain
-    user-confirmed phases via replan-in-unit); decision-required stops for the
+11. **Route the outcomes.** fix-now findings are routed to the unit's fold cycle (a separate `/fold-findings` invocation, never run by this review), or gain
+    user-confirmed phases via replan-in-unit; decision-required stops for the
     user's decision; genuinely independent future capabilities become
     **non-blocking proposals** — batched in the report with a trigger, and
     **never** sent to `triage-issue` automatically (D3). `review-change` creates
@@ -176,4 +176,5 @@ A **third cycle never starts** unless the user explicitly instructs it — it is
 the user's escape, never a reviewer election. The residue routes to
 `triage-issue --prioritize-now` (or the programmatic outer driver), and a unit
 that needs a third cycle has a planning or root-cause defect, not a review
-deficit.
+deficit. Re-runs count **separate review invocations**, not in-session steps:
+`/review-change` is invoked by the user in a fresh turn each time.

package/skills/review-plan/SKILL.md

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

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

@@ -51,7 +51,7 @@ tables is a finding. Either way `review-plan` reads the **whole** table
 
 Then digest it with the recipe owner —
 `pre-execution-review`'s [`SKILL.md`](<../../pre-execution-review/SKILL.md>) →
-SNAPSHOT reference: `node scripts/pre-execution-snapshot.mjs build --stage plan
+SNAPSHOT reference: `bun scripts/pre-execution-snapshot.mjs build --stage plan
 --unit <unitId> --parent <Product snapshot digest>`
 (`verify` mode is what consumers run afterwards, and it shares the builder, so pass
 `--parent` there too on a feature unit; a **fix** unit omits it and binds `null`).

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

@@ -59,9 +59,9 @@ answer beside the verdict block before reporting. A feature plan run names `--pa
 
 ```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>
+bun 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
+bun 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,

package/skills/review-spec/SKILL.md

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

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

@@ -43,7 +43,7 @@ contract failures, not style.
 
 Then build the snapshot with the recipe owner —
 `pre-execution-review`'s [`SKILL.md`](<../../pre-execution-review/SKILL.md>) →
-SNAPSHOT reference: `node scripts/pre-execution-snapshot.mjs build --stage spec
+SNAPSHOT reference: `bun scripts/pre-execution-snapshot.mjs build --stage spec
 --unit <unitId>` (canonical serializer: sorted keys, context rows ordered by kind
 then identifier, UTF-8, lowercase SHA-256). The digest is stdout's first line, so
 this recipe writes no file; `--json` is in-repository only. Paste the digest it

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

@@ -47,7 +47,7 @@ receipt, run the recipe owner's re-verify for this stage and paste the sensor's
 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>
+bun 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,

package/skills/ship-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship-roadmap
 user-invocable: true
-version: 5.2.0
+version: 5.2.1
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--fullauto] | --continue [--fullauto]"
@@ -102,7 +102,7 @@ fallback only when a primitive is unavailable; keep stage order and safety floor
 
 | Relation | Skills/policy |
 |---|---|
-| Compose (same/lower tier) | `init-workspace`; JIT `design-feature` + `plan-feature-scaffold`; `plan-feature`; the review→fold manual path (`/fold-findings` → re-run `/review-change`); verdict-only `audit-pr`; `audit-docs`. |
+| Compose (same/lower tier) | `init-workspace`; JIT `design-feature` + `plan-feature-scaffold`; `plan-feature`; the review→fold manual path (`/review-change` → `/fold-findings` on `REVIEW-FAIL` → re-run `/review-change`); verdict-only `audit-pr`; `audit-docs`. |
 | Cheap workers | `execute-phase` (fresh context/phase), mechanical folds, audit-blocker fixes; use the validated worker model. |
 | Human hand-off | Default merges, `product-audit` (higher effort), and report issue batches via `triage-issue`. |
 | Sibling | `workflow-status` supplies the strict sensor result; worker skills use the package-owned output profiles, while the conductor keeps its native `SHIP:` turn contract. |

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

@@ -70,9 +70,7 @@
      when the PR opens; any flips left at run end ride the report commit).
      Stop before the literal final `Hardening & PR` phase: PR owns that explicit
      phase so close-out has one owner. Never bundle phases into one worker.
-   - **REVIEW** — compose the manual review→fold path in-turn (equal tier) once,
-     `/fold-findings`, then re-run `/review-change`, over the complete PR
-     candidate. It reuses a current exact-SHA receipt or runs `review-change`
+   - **REVIEW** — compose the review→fold path (equal tier) once: `/review-change`, then `/fold-findings` (on `REVIEW-FAIL`), then re-run `/review-change`. It reuses a current exact-SHA receipt or runs `review-change`
      context-clean, batches compatible fixes through `fold-findings`, and
      re-reviews only changed HEADs. Default correction budget is two; unchanged
      evidence stops NO-PROGRESS. L/sensitive features

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

@@ -9,7 +9,7 @@
 | Product review (REVIEW-SPEC) | opus/high | `review-spec` in a **clean context** (fresh subagent or outside headless call) — never the turn that wrote the product half; tier equals or exceeds the author's, so the ≥ rule holds |
 | Plan review (REVIEW-PLAN) | opus/high | `review-plan` in a **clean context**, same rule; it judges the plan the previous stage froze |
 | Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
-| Final review/correction loop | opus/high | compose the manual path `/fold-findings`, then re-run `/review-change`; it reuses a current exact-SHA receipt or reviews context-clean, and routes unresolved findings to `triage-issue --prioritize-now` |
+| Final review/correction loop | opus/high | compose the manual path `/review-change`, then `/fold-findings` (only on `REVIEW-FAIL`), then re-run `/review-change`; it reuses a current exact-SHA receipt or reviews context-clean, and routes unresolved findings to `triage-issue --prioritize-now` |
 | Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |
 | Forge/git mechanics | — | Bash tool calls; no model judgment involved |
 | Final-report evidence gathering | haiku (optional) | fan-out subagents for grep-shaped per-feature log collection when ultracode is on; synthesis stays opus |

package/skills/workflow-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.2.0
+version: 3.2.1
 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

@@ -12,7 +12,7 @@ For every unit whose resolved status is `defined`, `planned` or `in-progress`:
    unit's `progress.md` (no `progress.md`, or no block for that stage → `missing`).
 2. The `snapshot` line — the `sha256:` digest the receipt binds — and each bound
    artifact's current bytes: re-derive the digest with the recipe owner's verify
-   mode — `node scripts/pre-execution-snapshot.mjs verify --stage <spec|plan> --unit
+   mode — `bun scripts/pre-execution-snapshot.mjs verify --stage <spec|plan> --unit
    <id> [--parent <64-hex>]` (`pre-execution-review` owns the recipe; a feature plan
    check needs the Product digest it descended from, a fix check binds no parent).
    Read `structural.reasonCode` and `structural.changedPaths` out of the JSON — they

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

@@ -71,7 +71,7 @@ live evidence against a frozen ledger remains a contradiction candidate.
    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
+   verify mode (`bun 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`/