@gtrabanco/pi-agentic-workflow 0.24.0 → 0.24.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "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.6.0
+version: 5.6.2
 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

@@ -96,7 +96,8 @@ verdict:
    that route). The check keys the lane-era/legacy split on evidence, not on an
    author-controlled artifact (fix/285; the lane-era pipeline structurally never
    writes `progress.md` or `ACCEPTANCE.md`, so demanding them made the gate
-   unsatisfiable for every lane-era unit — issue #285):
+   unsatisfiable for every lane-era unit; the post-feature 61 unit doc's `## Acceptance
+   criteria` is the canonical acceptance source — issue #285):
    - **Legacy path** — opened only when the unit's `progress.md` carries a
      `## Pre-execution review receipt v1 — plan` whose digest **re-derives**
      (`scripts/pre-execution-snapshot.mjs verify --stage plan` exits 0 over the
@@ -108,13 +109,15 @@ verdict:
      `structural.reasonCode`/`changedPaths` name the drifted dimension), and —
      for a feature unit — its named `— spec` parent re-derives the same way.
      The acceptance manifest binds when present (fix/285): a unit that carries
-     `ACCEPTANCE.md` still binds it in the snapshot. Bound artifacts
+     `ACCEPTANCE.md` still binds it in the snapshot; post-feature 61 units bind
+     the unit doc's `## Acceptance criteria` section instead. Bound artifacts
      are frozen: new implementation-phase files are allowed, edits to a bound
      artifact are not. A receipt that does not re-derive — stale, missing,
      wrong-stage **or impossible-timeline** — is never a pass: the check falls
      through to the lane-era path, so a planted or stale `progress.md` cannot
      buy a weaker gate (and a unit doc with no lane-era surface left is then
-     **BLOCKED**, `→ Next: /unit-lane <unit>`).
+     **BLOCKED**, `→ Next: /unit-lane <unit>`). Restoring the bound artifact or obtaining explicit user approval for a
+     SPEC amendment and replacement manifest, then write a fresh receipt.
    - **Lane-era path** (feature 61's single-doc contract) — the unit doc's
      Evidence section carries the `## Triaged steps` block whose `Steps:` /
      `Skipped:` / `Budget:` lines re-derive identically from the doc's own
@@ -154,5 +157,6 @@ verdict:
 A legacy unit with no ledgers is not exempt: the missing ledgers must be constructed
 and reviewed through the adoption route (the pre-execution gate in `execute-phase`'s
 preflight) before MERGE-READY. The audit never coerces old evidence into the new
-format, never edits `ACCEPTANCE.md`, and never accepts a hand-written table that the
+format, never edits `ACCEPTANCE.md` (legacy (pre-feature 61)) or the unit doc's acceptance
+section (post-feature 61), and never accepts a hand-written table that the
 plan snapshot does not bind.

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

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

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

@@ -55,7 +55,7 @@ task | implementation-owner | validator | required-evidence | status
 | `authority-source` | the SPEC/acceptance/criterion or ledger row that *requires* it — never the implementation |
 | `phase` / `task` | exactly one phase and one task; a row needing two phases means the phase cut is wrong |
 | `implementation-owner` | the skill/role that performs it (usually `execute-phase`) |
-| `validator` | the command or check that proves it, copied from `ACCEPTANCE.md` or the phase's done-when |
+| `validator` | the command or check that proves it, copied from the acceptance artifact (`ACCEPTANCE.md` for legacy (pre-feature 61) units; `sed -n '/^## Acceptance criteria/,/^## /p' <unit>/SPEC.md \| git hash-object --stdin` for post-feature 61) or the phase's done-when |
 | `required-evidence` | what must be recorded where (test name, receipt line, ledger row) |
 | `status` | `planned \| in-progress \| verified \| n/a \| deferred` |
 
@@ -147,7 +147,7 @@ progress | docs/features/<NN>-<slug>/SPEC.md · docs/fix/<issue>-<topic>/SPEC.md
 known-issues | docs/features/<NN>-<slug>/known-issues.md · docs/fix/<issue>-<topic>/known-issues.md | unit-lane:known-entries + execute-phase:blocker-entries-and-status | none | none | bun test scripts/ledger-ownership.test.mjs
 decisions | docs/features/<NN>-<slug>/decisions.md · docs/fix/<issue>-<topic>/decisions.md | unit-lane:decisions + execute-phase:phase-decisions + human-owner:ratified-verdicts | none | none | bun test scripts/ledger-ownership.test.mjs
 roadmap | docs/features/ROADMAP.md · docs/fix/README.md | unit-lane:row-registration + execute-phase:status-and-pr-link + audit-docs:low-risk-row-repair | none | none | bun test scripts/bounded-delivery-loops.test.mjs
-acceptance-manifest | docs/features/<NN>-<slug>/ACCEPTANCE.md · docs/fix/<issue>-<topic>/ACCEPTANCE.md | unit-lane:acceptance-freeze + human-owner:approved-amendment | none | none | git hash-object docs/features/<NN>-<slug>/ACCEPTANCE.md
+acceptance-manifest | docs/features/<NN>-<slug>/ACCEPTANCE.md · docs/fix/<issue>-<topic>/ACCEPTANCE.md | unit-lane:acceptance-freeze + human-owner:approved-amendment | none | none | git hash-object docs/features/<NN>-<slug>/ACCEPTANCE.md (legacy pre-feature 61) · sed -n '/^## Acceptance criteria/,/^## /p' <unit>/SPEC.md then git hash-object --stdin (unit doc era, post-feature 61)
 # no-script-writer: SPEC.md · PLAN.md · TASKS.md · CHECKLIST.md · testing.md · architecture-notes.md · planning-evidence.md · planning-obligations.md · delegated-evidence.md
 ```
 

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

@@ -63,7 +63,7 @@ in the unit's unbound `progress.md`:
 ## Wording-only determination v1 — <spec|plan>
 - Determination: <opaque id>
 - Artifact revision: <the rotated artifactRevisionId>
-- Acceptance fingerprint: <the ACCEPTANCE.md blob the batch left unmoved>
+- Acceptance fingerprint: <the acceptance artifact (ACCEPTANCE.md for legacy (pre-feature 61), unit doc ## Acceptance criteria for post-feature 61) blob the batch left unmoved>
 - Intent and authority unchanged: yes
 ```
 
@@ -149,7 +149,8 @@ One rule, same shape for every consumer:
 
 - **Construct, never coerce.** Add what the unit is missing — the planning-evidence
   and obligation ledgers, built from the artifacts as they stand today — and leave
-  `ACCEPTANCE.md`, `PLAN.md`, `TASKS.md`, the phase commits and any older receipt
+  `ACCEPTANCE.md` (legacy (pre-feature 61)), the unit doc's `## Acceptance criteria` (post-feature
+  61), `PLAN.md`, `TASKS.md`, the phase commits and any older receipt
   byte-identical. Rewriting an old verdict, its digest, or its date is forgery.
 - **Re-review, then resume.** The adopted unit re-runs the lane's `review` step like any other and
   `execute-phase` resumes **only** on that current verdict. A pre-lane unit

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

@@ -61,7 +61,8 @@ Rules the builder enforces and no caller may improvise around:
   `Depends on:` line plus the closure roadmap rows); the unit's artifacts and the
   authorities above stay bound.
 - **A snapshot digest is not a git blob id.** `git hash-object` stays the convention
-  for the frozen `ACCEPTANCE.md` manifest receipt only; comparing it to a snapshot
+  for the frozen `ACCEPTANCE.md` manifest receipt only (legacy pre-feature 61) or the post-feature
+  61 unit doc acceptance section; comparing it to a snapshot
   digest proves nothing and a sensor that does so is wrong, not cheap.
 
 ### Re-verifying a receipt (consumers)

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.12.0
+version: 3.12.1
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -59,7 +59,8 @@ 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
+the reviewer checks the same frozen acceptance artifact (legacy (pre-feature 61) `ACCEPTANCE.md`
+or post-feature-61 unit doc `## Acceptance criteria`) as the executor before
 mapping candidate evidence.
 
 ## When to use

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

@@ -31,8 +31,8 @@
    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;
+      acceptance-manifest (step-2 artifact) 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;
@@ -52,13 +52,14 @@
      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
-   `workflow` fix-now finding and no passing receipt may be posted. Legacy units
-   use the verification contract's committed SPEC-blob fallback. Then build a
-   **per-criterion coverage table** from the manifest — one row per acceptance
-   criterion, no free-form comparison:
+2. **Frozen acceptance + SPEC drift check (structural).** Locate the acceptance
+   artifact — legacy (pre-feature 61) `ACCEPTANCE.md` or the unit doc's
+   `## Acceptance criteria` section (post-feature 61) — recompute its blob,
+   and require an exact match with the execution receipt before assessing the
+   candidate. Missing/mismatch is a `workflow` fix-now finding and no passing
+   receipt may be posted. Legacy units use the verification contract's
+   committed SPEC-blob fallback. Then build a **per-criterion coverage table**
+   from the manifest — one row per acceptance criterion, no free-form comparison:
 
    ```
    | criterion | evidence (file:line or command run) | met | unmet | untouched |

package/skills/review-implementation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-implementation
 user-invocable: false
-version: 1.11.0
+version: 1.11.1
 argument-hint: <path-or-glob>
 allowed-tools: Read, Grep, Glob, Bash, WebFetch
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"

package/skills/review-implementation/references/CLASSIFY.md

@@ -42,7 +42,7 @@ A finding **blocks** only when the reviewer cites which single-owner source
 fails — blocking is a table lookup over cited sources, never a severity
 opinion. The four citation categories are:
 
-1. **ACCEPTANCE criterion** unverified or failed.
+1. **ACCEPTANCE criterion** (legacy `ACCEPTANCE.md` or post-feature 61 unit doc `## Acceptance criteria`) unverified or failed.
 2. **Obligation row** in the unit's ledger is not `verified` or `n-a`.
 3. **Gate is red** at the reviewed head (the project gate exited non-zero at
    the exact head under review).

package/skills/unit-lane/SKILL.md

@@ -135,7 +135,10 @@ execution work hands off one phase per turn:
 ```
 
 `<k>` is the first unfinished phase (the unit doc's Progress log records the
-phases done so far; `bun scripts/unit-route.mjs <NN-slug>` prints it) and
+phases done so far; `bun scripts/unit-route.mjs <NN-slug>` prints it — when every
+phase is recorded but the index still reads `in-progress`, the router refuses with
+`UNIT ROUTE — error … settle the index or roadmap status` and exits 1: settle the
+status, then continue the ladder) and
 `<tier>` is the `implement` entry of the triage block's `Tiers:` line. Never
 print the bare whole-unit `/execute-phase <NN-slug>` — whole-unit loop mode
 survives only as an explicit operator choice. When the last phase's turn

package/skills/unit-lane/references/IMPLEMENT.md

@@ -22,8 +22,10 @@ At each execution boundary, print exactly one phase hand-off and end the turn:
 ```
 
 `<k>` = first unfinished phase (lowest `P<n>` bullet the Progress log does not
-record; `bun scripts/unit-route.mjs <NN-slug>` prints it). `<tier>` = the
-`implement` entry of the triage block's `Tiers:` line. Never the bare
+record; `bun scripts/unit-route.mjs <NN-slug>` prints it — if every phase is
+recorded while the index still reads `in-progress`, the router refuses with
+`UNIT ROUTE — error … settle the index or roadmap status` and exits 1). `<tier>` =
+the `implement` entry of the triage block's `Tiers:` line. Never the bare
 whole-unit command.
 
 When the last phase's turn closes, `execute-phase` resumes the lane. Verify

package/skills/verification-contract/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: verification-contract
 user-invocable: false
-version: 1.3.0
+version: 1.4.2
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
-  Internal contract: one compact frozen ACCEPTANCE.md per delivery unit, its
-  validation ladder, anti-weakening rules, and blob-bound execution receipt.
-  Consumed by planners, execute-phase, and review-change.
+  Internal contract: the acceptance artifact per delivery unit — legacy (pre-
+  feature 61) units may carry a frozen `ACCEPTANCE.md` (binding if present);
+  post-feature 61 units use the unit doc's `## Acceptance criteria` section as
+  the canonical acceptance source; the unit doc's `## Evidence` table serves as
+  the execution receipt. Consumed by planners, execute-phase, and review-change.
 ---
 
 # Verification Contract (internal)
@@ -17,12 +19,18 @@ strengthen coverage but cannot move it; review checks the same bytes.
 
 ## Artifact
 
-Every new feature/fix carries `ACCEPTANCE.md` beside its SPEC. Copy the matching
-repository template. Required parts: `Status: frozen`; one stable ID per SPEC
-criterion; `Required outcome`; named `Validator`; literal quality floor; project
-commands. Prefer commands, otherwise use `read-verified: <evidence>` or
-`manual: <exact observation>`. Unlabelled prose is invalid. A planned test may
-name its future project runner; it cannot substitute a narrower runner later.
+Legacy (pre-feature 61) units (ACCEPTANCE.md present — binding if present):
+the frozen `ACCEPTANCE.md` beside the SPEC; required parts: `Status: frozen`;
+one stable ID per SPEC criterion; `Required outcome`; named `Validator`; literal
+quality floor; project commands. Prefer commands, otherwise use
+`read-verified: <evidence>` or `manual: <exact observation>`. Unlabelled prose
+is invalid. A planned test may name its future project runner; it cannot
+substitute a narrower runner later.
+
+Lane-era units (post-feature 61): the unit doc's `## Acceptance criteria` section is the
+canonical acceptance source. Criteria are numbered, each induced from a concrete
+user scenario, and command-verified where possible (label `read-verified` for
+prose-only checks). Unlabelled prose is invalid.
 
 **Validator stability.** A validator must never gate on a surface other workflow
 actors mutate — the branch diff as a whole, the session log, progress entries,
@@ -33,31 +41,36 @@ diff-based validator enumerates the unit's paths or excludes the
 workflow-mutated surfaces explicitly (docs/LOGS.md, the unit's own docs
 directory, harness/toolstate).
 
-## Freeze and receipt
+**Validator determinism.** A frozen validator must be deterministic — pin network,
+clock, randomness, and unordered-concurrency dependencies (fixed version,
+frozen fixture, recorded input) or downgrade the row to `read-verified:`/
+`manual:`.
 
-At first execution run `git hash-object <unit>/ACCEPTANCE.md` and append to the
-unit progress file:
+**Property / fuzz validators.** A planner may emit a property or fuzz validator as
+a bounded `commands` row — deterministic, bounded runtime within the project's
+per-command timeout budgets. No new validator kind in `VerificationPlan
+v1` is needed: property/fuzz rides the existing `commands` class.
 
-```text
-## Acceptance receipt v1
-- Manifest: <path> · Blob: <sha> · Status: frozen · Verified: <date>
-```
+## Freeze and receipt
 
-Before every phase and final review, recompute it. Exact match continues;
-missing/mismatched evidence stops before edits:
+The unit doc's `## Evidence` table is the execution receipt: each Evidence row
+records a validator command, its exit code or blob digest, output excerpt, and
+who verified it. A frozen criterion's receipt is the Evidence row for that
+criterion — exact match continues; missing/mismatched evidence stops before
+edits:
 
 ```text
 ACCEPTANCE GATE — <unit> BLOCKED
-Expected blob: <sha|missing> · Actual: <sha|missing>
-Reason: the frozen finish line is missing or changed.
+Expected Evidence row for AC<N>: present with blob <sha> · Actual: missing/changed
+Reason: the frozen finish line evidence is missing or changed.
 
 → Next: restore the frozen manifest, or obtain explicit user approval for a
-  SPEC amendment and replacement manifest; then write a fresh receipt
+  SPEC amendment and replacement manifest; then record a fresh Evidence row
   · never edit tests, commands, or acceptance to make the current candidate pass
 ```
 
 A legitimate change requires, in order: explicit user approval; dated SPEC
-`## Amendments` row; replacement manifest; committed fresh receipt. The
+`## Amendments` row; replacement manifest; committed fresh Evidence row. The
 executor never self-authorizes it.
 
 Legacy unit with no manifest mention: fingerprint committed `SPEC.md` and record
@@ -99,5 +112,4 @@ semantics are verified against authoritative documentation **before a test encod
 
 ## Done when
 
-Frozen manifest + current blob receipt + named validators + literal quality
-floor; executor and reviewer evaluate identical bytes.
+Execution receipt (unit doc `## Evidence` table for post-feature 61 units; legacy `ACCEPTANCE.md` manifest binding-if-present) + named validators + literal quality floor; executor and reviewer evaluate identical evidence.

package/skills/workflow-status/SKILL.md

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

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

@@ -24,7 +24,8 @@ For every unit whose resolved status is `defined`, `planned` or `in-progress`:
    name the dimension that stopped being true, which is what the sensor labels
    `stale`. A snapshot digest is a canonical
    SHA-256 over the snapshot object, so `git hash-object` is never a substitute: it
-   stays correct only for the frozen `ACCEPTANCE.md` manifest blob.
+   stays correct only for the frozen acceptance artifact: `ACCEPTANCE.md` (legacy (pre-feature 61)) or the
+   unit doc's `## Acceptance criteria` section (post-feature 61).
 3. The verdict, the reviewed `unit`, the stage, and the author fields
    (`reviewer` and `authorId` — the receipt's `Reviewer:` / `Author:` lines — and
    `authorExclusion`).