@gtrabanco/pi-agentic-workflow 0.24.0 → 0.24.4

package/package.json

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

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 2.0.0
+version: 2.2.0
 argument-hint: <NN-slug | "<idea>"> [--retriage] | --fix <issue-number> | --from-issue <issue-number>
 description: >
   One-shot lane conductor for a delivery unit: triage, implement, evidence, and
@@ -25,6 +25,12 @@ done:
   is inferred: a gap re-enters provenance → research, and a gap surviving both
   runs `node scripts/needs-input.mjs <unit-dir>` and stops with the
   `open-questions@1` block routed back to the owning stage.
+✓ Every claim the SPEC or the plan asserts (objective, why, ACs, tasks) cites
+  its source — `path:line`, a doc, or an owner answer in the unit folder's
+  `sources.md`. A claim with none is a question, never a default.
+✓ Every question asked is recorded with its resolution (owner answer, "Decide
+  for me" + reason, or the explicit `none — no questions` line) in
+  `decisions.md`; no question the user already answered is asked twice.
 ✓ Triage ran (bun scripts/unit-route.mjs --triage <slug>) and its block pasted
   verbatim into the unit doc's Evidence section as the authoritative step list
 ✓ Unit doc exists at docs/features/<NN>-<slug>/SPEC.md (created from template
@@ -135,7 +141,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/DESIGN.md

@@ -13,9 +13,10 @@ Cheap-to-change defaults are recorded as assumptions, never silent.
 
 ## Purpose
 
-Run the gap interview, induce acceptance criteria from user scenarios, and
-close entity, role, and expectation boundaries — distilled from the full design
-skill's closure.
+Run **investigate → orient → ask → decide**: every claim the SPEC makes is
+entered in a ledger that cites its source, and entity, role, and expectation
+boundaries close. The unit of progress is a **claim with a source** — a claim no
+source or owner answer supports is a defect, not a judgment call.
 
 ## Inputs
 
@@ -24,20 +25,63 @@ skill's closure.
   installed tooling — whatever they already answer is never asked again
 - Research findings from the research step
 
-## The gap interview (runs before acceptance criteria lock)
+## Stage 1 — investigate
 
-Collect every open decision the unit depends on and filter each one:
+Open with a provenance search, then journal every claim. **The first action of
+this stage is a search, not a sentence**: no design claim is written before the
+repository has been asked.
 
-| The gap… | The lane does |
+1. **Provenance search.** Run the greps and reads whose result would settle the
+   claim (`grep -rn "<term>" docs/ src/`, the documentation map, the architecture
+   doc, the roadmap, prior units' `decisions.md`), and record **where you
+   looked**: `path:line` hits and the greps run. A "not found" without that
+   receipt is the defect this stage exists to catch.
+2. **Journal** — append one row per claim to the unit folder's `sources.md`:
+
+| id | claim | source | certainty |
+|---|---|---|---|
+| INV-001 | <the claim, one line> | `<path:line>`, `<doc#anchor>`, `owner answer <Q-id>`, or `user request` | confirmed / inferred / unknown |
+
+   `confirmed` = verifiable by a command or documented; `inferred` = deduced,
+   not yet verified; `unknown` = no evidence found (→ the orient stage must ask).
+3. **Induce acceptance criteria** from user scenarios — each AC is a claim too,
+   and cites the scenario or owner answer it came from.
+4. **Close boundaries**: entities and their roles, actors, accepted and rejected
+   inputs (the expectation sweep), deferrals (→ `## Future`).
+
+Pass only if: ✓ the provenance search ran and its receipt is recorded ✓ every
+claim is a `sources.md` row ✓ every AC is induced from a user scenario.
+
+## Stage 2 — orient
+
+Filter each `INV-*` claim with three fixed tiers, in order — the lowest tier that
+settles the claim wins, and the repository always speaks first:
+
+| Tier | When it settles the claim | What this stage does |
+|---|---|---|
+| **0 · provenance** | A recorded `path:line`, doc, or prior decision answers it | Nothing to ask — point the row at the source |
+| **1 · research** | External and unresearched, in tier 0 or outside it | Research it into 2–3 options with trade-offs |
+| **2 · ask** | No evidence exists anywhere | Backlog it for the ask stage — never decided here |
+
+The tier-2 backlog is then filtered by cost of being wrong — expensive to undo
+= **scope** (personal / team / global), **stack**, **architecture pattern**,
+**data model**, **deployment target**, **security configuration**:
+
+| The claim… | The lane does |
 |---|---|
-| The request, the repo, or the installed tooling already answers it | Never asks |
 | Blocks now and is expensive to undo once code sits on top | Asks |
 | Blocks a later task that is already foreseeable | Asks now as a possibility; re-asks only if conditions change |
-| Cheap to change later | Takes a reasonable default and records it as an assumption — never silent |
+| Cheap to change later | Takes a reasonable default, records it as a dated assumption — never silent |
+
+Pass only if: ✓ every `INV-*` row carries a tier and a cost verdict ✓ every
+tier-0 row names the source that settled it ✓ no claim was researched or asked
+before the provenance tier ran.
 
-Expensive to undo = the choices that cost a lot to change once code exists on
-top: **scope** (personal / team / global), **stack**, **architecture pattern**,
-**data model**, **deployment target**, and **security configuration**.
+## Stage 3 — ask
+
+Batch the tier-2 claims from the orient stage. This stage reads the **orient
+output and the ask backlog** — never re-derives a claim the provenance tier
+settled, never re-asks an answer the user already gave.
 
 Mechanics — one batched form-turn, never one-question-per-turn:
 
@@ -49,52 +93,104 @@ Mechanics — one batched form-turn, never one-question-per-turn:
 - Every slot carries: the **recommended option with its why**, one
   alternative, **"Decide for me"**, and **"Explain the options"** — the user
   may always answer freely.
-- **"Decide for me"**: the lane chooses, then records the choice and its
-  reason as a dated row in the unit folder's `decisions.md` — explicit, never
-  guessed silently.
-- **"Explain the options"**: explain each alternative didactically, then
-  re-ask only that slot.
 - A tool the project lacks may be offered as one more option (with its
   recommendation and why); installing it always needs the user's explicit
   consent.
-- **Ready when:** no expensive-to-undo blocking gap remains unanswered — not
-  when no gaps remain. An answer the user already gave is never re-asked.
+- **Ready when:** no expensive-to-undo blocking claim remains unanswered — not
+  when no questions remain.
+
+The questions are the `open-questions@1` block of the unit folder's
+`decisions.md` — the grammar `scripts/needs-input.mjs` reads, published in the
+template agent guide's question protocol. Append the block (never a table of
+your own invention) and carry a search receipt on every question:
 
-Deferred ideas ("down the road I'd like…") are never implemented, never turned
-into spec or tasks by this unit: they go verbatim to the unit doc's
-`## Future` section, dated, so the architecture may accommodate them without
-building them.
+```text
+open-questions@1
+id | date | type | question | blocks | search-receipt | options | route
+Q1 | <YYYY-MM-DD> | open-question | <the decision being asked> | <why nothing proceeds without it> | <where the repository was searched: path:line, greps, prior units> | <option A — trade-off> \| <option B — trade-off> \| Decide for me \| Explain the options | design
+```
+
+## Stage 4 — decide
+
+Record every answer — the user's, and every "Decide for me" choice with its
+reason — as a `decision` row of the same block, newest last. Only the owner
+closes a question; the row carries where the answer is recorded (a chat paste, an
+issue comment) and what was discarded:
+
+```text
+D1 | <YYYY-MM-DD> | decision | Q1 | human-owner | <where the answer is recorded> | <what was chosen> | <what was discarded and why>
+```
+
+A cheap default taken in stage 2 goes to the file's `## Assumptions` as a dated
+row, correctable by the user. Then fill the unit doc's **Acceptance criteria**
+(induced from a concrete scenario, command-verified where possible, numbered).
 
 ## Fixed output contract
 
-Fill the unit doc's **Acceptance criteria** section. Each AC must be:
-- Induced from a concrete user scenario ("I do X and observe Y")
-- Command-verified where possible (not "feel correct")
-- Numbered (AC1, AC2, …)
+The step owns four panes of the unit folder and nothing else:
+
+<!-- sources:start -->
+`sources.md` — one row per claim, each with a source or an owner answer. A
+claim row with an empty, `—`, or `n/a` source is a **defect**: either find the
+source in the provenance tier or convert the claim into a question.
+<!-- sources:end -->
+
+<!-- questions:start -->
+The unit folder's `decisions.md` — the `open-questions@1` block the ask stage
+appended, plus the `decision` rows the decide stage appended (one per question
+closed). The step also refreshes `BRIEF.md`, the reviewer brief that restates
+them, so a reviewer never has to re-derive the step's questions.
+
+| Asked | Resolution |
+|---|---|
+| <question id + the decision being asked> | <what was chosen, by whom (owner answer / Decide for me), and why> |
+
+When the orient stage left an empty ask backlog, write exactly
+``none — no questions: every claim was settled by provenance or research``.
+An empty table is never that line — the form is a decision, the blank is a
+missing one.
+<!-- questions:end -->
+
+<!-- deferred:start -->
+`## Future` in the unit doc — deferred ideas ("down the road I'd like…"),
+verbatim and dated. They are never implemented, never turned into spec or tasks
+by this unit, and are reviewed at close, on resume, and when work returns to the
+area.
+<!-- deferred:end -->
+
+<!-- acceptance:start -->
+The unit doc's **Acceptance criteria** section, numbered and command-verified.
+<!-- acceptance:end -->
 
 ## Checklist (pass only if)
 
-- [ ] The gap interview ran before the ACs locked: one batched form-turn,
-      each gap filtered through the table above
-- [ ] No expensive-to-undo blocking gap remains unanswered
+- [ ] The provenance search ran first and its receipt is recorded (`path:line`, the greps, prior units)
+- [ ] Every claim (objective, why, every AC, non-goals) cites its source or an owner answer in `sources.md`, and none lacks one
+- [ ] Every claim carries a certainty (`confirmed` / `inferred` / `unknown`); an `unknown` claim became a question
+- [ ] Every acceptance criterion (AC1, AC2, …) is induced from a user scenario and cites what induced it
+- [ ] The orient tiers ran in order: provenance before research before ask
+- [ ] Every question asked was recorded with its resolution — or the questions pane says `none` explicitly
+- [ ] No expensive-to-undo blocking claim remains unanswered
 - [ ] Every "Decide for me" choice is recorded with its reason in `decisions.md`
-- [ ] Cheap defaults are recorded as assumptions, correctable by the user
-- [ ] Deferred user ideas landed in `## Future`, not in scope
-- [ ] Every AC is induced from a user scenario, not inferred from vague intent
-- [ ] Acceptance criteria are command-verified where possible
+- [ ] Cheap defaults are recorded as dated assumptions, correctable by the user
 - [ ] Entity closure: every entity mentioned has its role in the unit stated
 - [ ] Role closure: every actor/role that interacts with the unit is listed
 - [ ] Expectation sweep: user's accepted and rejected inputs are bounded
-- [ ] Vague items → ask the user with concrete options, never invent
+- [ ] Deferrals landed in `## Future`, not in scope
 
 ## Forbidden
 
+- Never infer a claim: one that is not in the repository and not derivable from
+  it is a question for the owner, never a default. A claim with no source and no
+  owner answer is the defect, not a judgment call
+- Do not write a design claim before the provenance search ran
 - Do not ask what the request, the repo, or the installed tooling already answers
 - Do not ask one question per turn when slots are independent
+- Do not invent a question table of your own: the ask stage writes the
+  `open-questions@1` block the dispatcher reads
+- Do not decide at the ask stage — asking and answering are different stages
 - Do not implement, spec, or task anything from `## Future`
 - Do not install a missing tool without explicit user consent
 - Do not build a separate DESIGN.md — one SPEC, all in the unit doc
-- Do not invent product scope the user did not confirm
 - Do not pre-fill engineering content (phases, tests, architecture)
 - Do not stamp "designed" with an incomplete closure row
-- An incomplete row silently un-does the skill's purpose

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/unit-lane/references/PLAN.md

@@ -2,16 +2,96 @@
 
 ## Purpose
 
-Cut tasks from acceptance criteria. Each task names its validator. Smallest
-first. No future-phase work.
+Run **investigate → orient → ask → decide** over the plan itself: cite every
+task, sweep every claim against what the repository already decided, ask only
+what no source answers, and record the answers. Each task names its validator;
+smallest first; no future-phase work.
 
 ## Inputs
 
-- The unit's Acceptance criteria (filled by the design step)
-- The unit's non-goals
+- The unit doc: acceptance criteria, non-goals, and the design step's four panes
+  (`sources.md`, `decisions.md`)
+- The unit's Impact section — the surface the executor must sweep
+
+## Stage 1 — investigate
+
+Open with the same provenance search the design step ran, aimed at the plan's own
+claims ("does a validator for this exist?", "is this module already covered?",
+"did a prior unit decide this?"). Journal each claim as a row of the unit
+folder's `sources.md`, with the id prefix `CLAIM-`:
+
+| id | claim | source | certainty |
+|---|---|---|---|
+| CLAIM-001 | <the plan claim, one line> | `<path:line>`, prior `decisions.md:line`, or `owner answer <Q-id>` | confirmed / inferred / unknown |
+
+Two claims never need a search: the unit's own acceptance criteria (the design
+step cited them) and its non-goals. Everything else does — a plan claim with no
+source and no owner answer is the defect this stage exists to catch.
+
+## Stage 2 — orient
+
+Re-run the provenance tier over the plan's claims, then sweep every one of them
+against what the repository has **already decided in writing** — a plan must not
+contradict a prior decision in architecture, engineering, product, or any other
+domain. A claim the provenance search explains is settled at tier 0: point the
+row at `path:line` and move on. **Record where you looked** for every row the
+search did not settle — the greps meant for it and the prior units of the same
+area. In the same pass, check that the acceptance criteria are the plan's
+*input*, not a claim it re-decides: a task that would change an AC belongs to the
+design step, not here.
+
+**Candidate sources** — deterministic keyword/FTS matching, no new index and no
+new tooling: `docs/features/<NN>-<slug>/decisions.md`,
+`docs/fix/<issue>-<topic>/decisions.md`, the project's architectural invariants,
+the Normalized Repository State (`discover-repository-state` /
+`resolve-repository-state`), `AGENTS.md`, and a unit SPEC's `## Design status`
+(legacy marker, units ≤ 60).
+
+**Advisory only — no new authority.** `contradicts` routes to
+`resolve-repository-state` only when the hit is against a frozen NRS fact (its
+only candidate source that carries a `<contradiction-id>` row after a
+`discover-repository-state` step); hits against `decisions.md` / `AGENTS.md` /
+architectural invariants / `## Design status` surface a `NEEDS-DECISION` for the
+user, per the existing rules. A plan with **no candidate match is clean and
+proceeds** — a miss never blocks it, a missed candidate can never void a plan,
+and the sweep issues no stage verdict and grants no gate of its own.
+
+Pass only if: ✓ the provenance search ran and where you looked is recorded ✓ every `CLAIM-*` row was swept ✓ every `contradicts` hit is either
+resolved from a frozen NRS fact or backlogged for the ask stage ✓ no task
+re-decides an acceptance criterion.
+
+## Stage 3 — ask
+
+Only `contradicts` hits and `unknown` claims that no source settles reach this
+stage — a plan asks after the repository has spoken, never before. Batch them
+into **one** form-turn (≤6 slots) using the design step's mechanics: recommended
+option with its why, one alternative, "Decide for me", "Explain the options".
+
+The questions are the same `open-questions@1` block the dispatcher reads — append
+the block to the unit folder's `decisions.md` (route `unit-lane`: these are
+plan-owned facts), never a table of your own:
+
+```text
+open-questions@1
+id | date | type | question | blocks | search-receipt | options | route
+Q2 | <YYYY-MM-DD> | open-question | <the decision being asked> | <why nothing proceeds without it> | <where the repository was searched: path:line, greps, prior units> | <option A — trade-off> \| <option B — trade-off> \| Decide for me \| Explain the options | unit-lane
+```
+
+A plan with an empty backlog writes the explicit `none` line instead — never a
+blank.
+
+## Stage 4 — decide
+
+Record every answer as a `decision` row of the same block (newest last), and a
+`Decide for me` choice with its reason — then cut the tasks:
+
+```text
+D2 | <YYYY-MM-DD> | decision | Q2 | human-owner | <where the answer is recorded> | <what was chosen> | <what was discarded and why>
+```
 
 ## Fixed output contract
 
+<!-- tasks:start -->
 Fill the unit doc's **Tasks** section:
 
 ```
@@ -30,39 +110,27 @@ backticked command **and** an expected outcome, e.g. `exits 0`), and the nested
 `Relevant files:` line is **metadata, never a task** — it is that phase's read
 set, written from the planner's own discovery, and a file that is missing from
 it is never out of scope for the executor.
+<!-- tasks:end -->
 
-## Prior-decisions contradiction sweep
-
-Before the plan is accepted, sweep its claims against what the repository has
-**already decided in writing** — a plan must not contradict a prior decision in
-architecture, engineering, product, or any other domain.
-
-**Candidate sources** — deterministic keyword/FTS matching, no new index and no
-new tooling: `docs/features/<NN>-<slug>/decisions.md`,
-`docs/fix/<issue>-<topic>/decisions.md`, the project's architectural invariants,
-the Normalized Repository State (`discover-repository-state` /
-`resolve-repository-state`), `AGENTS.md`, and a unit SPEC's `## Design status`
-(legacy marker, units ≤ 60).
-
-**Fixed evidence shape** — one row per candidate hit, the decision quoted from
-its source:
+<!-- sources:start -->
+`sources.md` — every `CLAIM-*` row with a source or an owner answer. A claim row
+whose source is empty, `—`, or `n/a` is a **defect**: find the source in the
+provenance tier or convert the claim into a question.
+<!-- sources:end -->
 
-| claim | prior decision | source path | relation |
-|---|---|---|---|
-| <the plan claim> | <the recorded decision> | <path:line> | `contradicts` \| `compatible` |
+<!-- questions:start -->
+The unit folder's `decisions.md` — the `open-questions@1` block the ask stage
+appended, plus the `decision` rows the decide stage appended, one per question
+closed. The step also refreshes `BRIEF.md`, the reviewer brief that restates
+them, so a reviewer never has to re-derive the step's questions:
 
-The cell value is exactly one of two values: `contradicts` or `compatible` —
-a row relation, not a stage verdict.
+| Asked | Resolution |
+|---|---|
+| <question id + the decision being asked> | <what was chosen, by whom (owner answer / Decide for me), and why> |
 
-**Advisory only — no new authority.** `contradicts` routes to
-`resolve-repository-state` only when the hit is against a frozen NRS fact
-(its only candidate source that carries a `<contradiction-id>` row after a
-`discover-repository-state` step); hits against
-`decisions.md` / `AGENTS.md` / architectural invariants / `## Design status`
-surface a `NEEDS-DECISION` for the user, per the existing rules. A plan with **no
-candidate match is clean and proceeds** — a miss never blocks it, a missed
-candidate can never void a plan, and the sweep issues no stage verdict and grants no
-gate of its own.
+When the sweep and the provenance tier left an empty backlog, write exactly
+``none — no questions: every claim was settled by provenance or research``.
+<!-- questions:end -->
 
 ## Planning ledgers (same step)
 
@@ -89,25 +157,31 @@ name those files instead.
 
 ## Checklist (pass only if)
 
-- [ ] Every AC maps to at least one task
+- [ ] The provenance search ran first and its receipt is recorded for every plan claim
+- [ ] Every claim (CLAIM-001, …) cites its source or an owner answer in `sources.md`, including every acceptance criterion it rests on — none is blank, `—`, or `n/a`
+- [ ] Every claim was swept against the candidate sources; each `contradicts` hit is resolved or asked
+- [ ] Every question asked was recorded in `decisions.md` with its resolution (or the questions pane says `none`)
+- [ ] Every AC maps to at least one task, and no task re-decides an AC
 - [ ] Tasks are ordered smallest first
 - [ ] Each task names its validator (a backticked command plus its expected outcome)
 - [ ] Final task is verification (proves the whole unit works)
 - [ ] No task reaches into a future-phase concern (docs, release, migrations)
 - [ ] Phases labeled P1, P2, … (never S1, Step 1)
-- [ ] Every plan claim touching architecture, engineering or product intent was
-      swept against the candidate sources above
-- [ ] Each candidate hit is one fixed-shape row, with the prior decision cited
-      at `path:line` and one of the two relations
 - [ ] Both planning ledgers are cut (planning evidence + obligations), in the
       sizing rule's home, with stable ids
 
 ## Forbidden
 
+- Never infer a plan claim: one the repository does not answer and no owner
+  settled is a question, never a default
+- Do not cut a task before the claim it rests on cites a source or an owner answer
+- Do not invent a question table of your own: the ask stage writes the
+  `open-questions@1` block the dispatcher reads
+- Do not decide at the ask stage, and do not re-ask an answered question
 - Do not bundle across phase boundaries — one phase = one commit
 - Do not plan work beyond the unit's acceptance criteria
 - Do not include docs/release tasks here — those are separate catalog steps
 - Do not invent tasks that the ACs do not demand
 - Do not turn the sweep into a gate, stage verdict or blocking check — it routes,
   it never blocks a miss, and it adds no authority
-- Do not record a `prior decision` that no source `path:line` cites
+- Do not record a `prior decision` that no source `path:line` cites

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`).