@gtrabanco/pi-agentic-workflow 0.24.2 → 0.26.0

package/package.json

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

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 6.0.0
+version: 6.1.0
 argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"

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

@@ -15,7 +15,12 @@ when every step below ran — fixing the code and stopping is the classic way
 findings end up "solved" locally but absent from the merged PR:
 
 ```
-✓ Fixes implemented (scope: only the routed findings — nothing extra)
+✓ Fixes implemented — the batch is the routed findings **plus everything that
+  depends on them**: callers of what changes, consumers of what it delivers, and
+  every mention that stops being true (a comment, a prose claim, a declared
+  validator, a manifest narration). Nothing beyond that
+✓ `bun scripts/promise-coherence.mjs` RUN → `verdict PASS` (the repaired claims
+  reproduce at the head; a skipped line is read, never assumed)
 ✓ Gate RUN and green (exit codes pasted)
 ✓ Never edit an existing test's expectation to match behaviour — a setup
   repair keeps assertions at least as strong and never touches expectations

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 4.0.2
+version: 4.0.3
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -152,9 +152,9 @@ loads exactly upgrade and skips bootstrap plus portability.
 
 The adaptive lane (feature 61) replaces the fixed pipeline with a single-unit-
 document model. Every NEW unit produces one `SPEC.md` under
-`docs/features/<NN>-<slug>/` with 14 sections: Objective, Why, User outcome, Impact,
-Acceptance criteria, Non-goals, Future cost, Applicable tests, Known pre-existing
-issues, Tasks, Evidence, Progress log, Next, References.
+`docs/features/<NN>-<slug>/` with 14 sections: Objective, Why, User outcome, Acceptance criteria, Impact,
+Non-goals, Future cost, Applicable tests, Known pre-existing issues, Tasks,
+Evidence, Progress log, Next, References.
 
 Conventions written into the project's AGENTS.md:
 

package/skills/orchestration-envelope/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: orchestration-envelope
 user-invocable: false
-version: 2.3.0
+version: 2.4.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >

package/skills/orchestration-envelope/references/TURN_CONTRACT.md

@@ -16,6 +16,14 @@
 ✓ 11. No reconstruction from memory — missing reference → STOP.
 ```
 
+**A box that runs a command discloses what the command needs.** When a box
+invokes a script with a placeholder (`node scripts/x.mjs <unit-dir>`), the same
+skill's text must name the artifact that placeholder requires — the script
+declares it (`PREREQUISITES` in `scripts/needs-input.mjs`) and
+`scripts/promise-coherence.mjs` checks the disclosure. A box that instructs a
+run the skill never equips reproduces the failure it was written to prevent
+(fix #258 F45/F53: `missing-unit-doc`).
+
 **Single owner:** orchestration-envelope/references/TURN_CONTRACT.md. All skills load this + skill-specific additions only. Duplication forbidden. Missing reference = STOP.
 
 **Push policy supplement:** Box 4 covers the end-of-unit push. Some consumers (e.g. `execute-phase/references/PREFLIGHT.md`) define additional push rules for mid-phase commits when a PR is already open — those per-consumer supplements extend this contract and must be loaded alongside it by the consumer skill.

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

@@ -1,7 +1,7 @@
 ---
 name: pre-execution-review
 user-invocable: false
-version: 2.7.1
+version: 2.8.0
 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 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 |
+| `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. When it is a backticked reader command, state the outcome it must produce — `` … matches <N> `` or `` … exits <N> `` — because `scripts/promise-coherence.mjs` re-runs it at the head and `verified` is only truthful while it reproduces. A validator with no stated outcome is a claim nobody can check |
 | `required-evidence` | what must be recorded where (test name, receipt line, ledger row) |
 | `status` | `planned \| in-progress \| verified \| n/a \| deferred` |
 
@@ -66,7 +66,9 @@ Status lifecycle and its hard edges:
   follow-up issue.
 - `verified` requires the named validator to have run and its evidence to be
   recorded where `required-evidence` says. An assertion of intent is not a
-  status change.
+  status change. A count or exit code in the validator cell is re-run by
+  `scripts/promise-coherence.mjs`; when the command stops producing it, the row
+  is stale even while it still reads `verified`.
 - `n/a` needs evidence in the row (a `path:line`, ledger row, or cited contract)
   and may never contradict the SPEC's scope section. `n/a` without evidence is
   an open obligation.

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 2.0.0
+version: 2.3.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

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

@@ -43,6 +43,12 @@ its work landed in the unit doc before continuing:
 - [ ] Each executor turn recorded its Evidence row and dated Progress entry
 - [ ] Diff guard run at the lane's resume (see step 4 in SKILL.md)
 - [ ] `git status --porcelain` is empty when the lane resumes
+- [ ] Each phase swept the change **plus everything that depends on it** —
+      callers of what changed, consumers of what it delivers, and every mention
+      that stops being true; a surviving mention is part of the same phase, not
+      a finding for the next review
+- [ ] `bun scripts/promise-coherence.mjs` RUN at the lane's resume → `verdict
+      PASS` (the unit doc's declared validators reproduce at the head)
 
 ## Allowed
 

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,7 +1,7 @@
 ---
 name: verification-contract
 user-invocable: false
-version: 1.4.2
+version: 1.4.3
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -17,6 +17,16 @@ description: >
 Single owner of the delivery finish line. Planning freezes it; executors may
 strengthen coverage but cannot move it; review checks the same bytes.
 
+## Executable claims
+
+An acceptance criterion or Evidence row that states a count, an exit code or a
+length is a promise, not a description: `scripts/promise-coherence.mjs` re-runs
+it. Write the outcome a command must produce (`` `cmd` matches <N> ``,
+`` `cmd` exits <N> ``) or, for a shape promise, name the file and the
+`## Section` the count is about (`` … a 3–5 line `## Inputs` in
+`skills/<name>/SKILL.md` ``) — a length with no named surface cannot be recounted
+and fails closed.
+
 ## Artifact
 
 Legacy (pre-feature 61) units (ACCEPTANCE.md present — binding if present):