@gtrabanco/pi-agentic-workflow 0.20.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.20.0",
+  "version": "0.24.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: 5.1.0
+version: 6.0.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>"
@@ -34,6 +34,9 @@ Tick every box before ending the turn; an unchecked box means the turn is not
 done:
 
 ```
+✓ Required user inputs were answered concretely (not defaulted). Nothing here
+  is inferred: a gap runs `node scripts/needs-input.mjs <unit-dir>` and the
+  `open-questions@1` block is pasted, then the run stops.
 ✓ Triage verified — unit doc Evidence section header matches
   `bun scripts/unit-route.mjs --triage <slug>` output block (PREFLIGHT.md)
 ✓ Unit doc read and step selected (explicit P<k> or first unfinished)
@@ -54,6 +57,25 @@ done:
 - To execute all remaining steps: `<NN-slug>` with no step argument.
 - To repair a failed step: `<NN-slug> P<k>` (retry the same step).
 
+## Inputs — artifacts, never questions
+
+This skill **never interviews**. It reads its inputs — the unit doc's `Tasks`,
+`unit-route.mjs --triage`'s block, the route's tier — and a missing or ambiguous
+one is a **gap**, resolved in one fixed order and never by inference:
+**(0) provenance** (search the repo's own docs and record where) →
+**(1) research** (2–3 concrete options with trade-offs; asking for more research
+is a legitimate answer) → **(2) halt**: run `node scripts/needs-input.mjs
+<unit-dir>`, paste the `open-questions@1` block verbatim, stop. Interactive the
+block is the pause point, unattended it is a hard fail. Grammar and exit codes:
+`orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open questions.
+
+Bare `<NN-slug>` runs **all remaining steps** — the phase is not an input. File
+targets are the unit doc's nested `Relevant files:` metadata plus the
+path-protection checkpoint. `--max-attempts N` defaults to 3; `--force` skips the
+*stop* on the dependency and phase-lint gates (never the check — `PREFLIGHT.md`
+records the override in the Progress log) and has **no bypass** on the
+path-protection checkpoint.
+
 ## Step 0 — Discover the project
 
 Per the agent guide's **Workflow conventions** + **documentation map**, read the

package/skills/fold-findings/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: fold-findings
 user-invocable: true
-version: 1.7.0
+version: 1.9.0
 argument-hint: [finding-id …]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -102,9 +102,9 @@ no schema field). Six fields, always present:
 - Repaired: <F-ids with (VF-<n>) refs, joined ` + `, or `none`>
 - Refuted/open: <F-ids joined ` + `, or `none`>
 - Gate: <command> → exit <n> at head <40-hex sha> · n/a when nothing was folded
-- Batch class: <all-repair-in-place | frozen (replan present) | none>
+- Batch class: <all-repair-in-place | frozen (replan present) | frozen (product owner present) | none>
 - Fold diff: <shortstat from a real `git diff` run> · none when nothing was folded
-- Branch: <RE-REVIEW-REQUIRED (delta) | RE-REVIEW-OPTIONAL | RE-REVIEW-SKIPPED | REPLAN-ROUTE>
+- Branch: <RE-REVIEW-REQUIRED (delta) | RE-REVIEW-OPTIONAL | RE-REVIEW-SKIPPED | REPLAN-ROUTE | PRODUCT-ROUTE>
 ```
 
 - The `Gate` line carries the actual exit codes observed at the head the gate
@@ -114,9 +114,9 @@ no schema field). Six fields, always present:
 - The `Fold diff` shortstat comes from a real `git diff` run over the batch's
   commits.
 - The `Batch class` derives from the taken queue's frozen rows only — the fold
-  never reclassifies (`all-repair-in-place`, `frozen (replan present)`, or
-  `none` for an empty queue); the vocabulary comes from
-  `review-implementation`'s closed class set.
+  never reclassifies (`all-repair-in-place`, `frozen (replan present)`,
+  `frozen (product owner present)`, or `none` for an empty queue); the
+  vocabulary comes from `review-implementation`'s closed class set.
 
 **Freeze-batch (replan present).** When the taken queue contains any row whose
 frozen class is `replan-in-unit` or `decision-required`, nothing folds: no
@@ -129,13 +129,31 @@ and surface the decision to the user, never a planner. `<unit>` is the bare fold
 `node scripts/unit-route.mjs <unit>` is the discovery step the fold already
 ran; it is never the recommendation.
 
+**Freeze-batch (product owner present).** Any taken `fix-now` row whose `Route`
+cell begins `product owner`, `product-owned` or `owned by product` (head-anchored,
+identical to `scripts/unit-route.mjs`'s `PRODUCT_ROUTE` regex,
+per `#293`) freezes the batch too —
+nothing folds, no `folded: yes` flips, no commits: the fold loop repairs source,
+never authority (`pre-execution-review` POLICY §4, `#293`). The receipt records
+the `PRODUCT-ROUTE` branch and the retained row ids; the consumer is the
+router's printed `route: product` lane hand-off. Full condition and hand-off
+table: [`FOLD_PROCESS.md`](references/FOLD_PROCESS.md) §Batch classification.
+
 ## Guardrails
 
 Scope is the ledger (or explicit ID subset); unlisted discoveries are proposals
 for user triage. Batch only when one root-cause correction, validator set and
 rollback boundary own the rows: one commit/push, individual ticks/lines. Split
-otherwise. Do not widen beyond a finding's file/line/axis unless its root cause
-requires it; explain that in the commit. Artifact language follows user
+otherwise.
+
+**The fix covers the change and everything that depends on it.** When what a
+piece receives changes, find its callers; when what it delivers changes, find
+its consumers; when something is removed, check what still uses it and ask
+before breaking it. A surviving mention of what changed — a comment, a prose
+claim, a declared validator, a manifest narration, a sibling surface stating
+the same thing — is part of this same fold, never a finding for the next
+cycle. The fold ends when nothing still asserts what is no longer true; state
+in the commit which surfaces the correction swept. Artifact language follows user
 instruction > project docs language > English; conversation language never decides.
 
 ## Portability (agents other than Claude Code)
@@ -175,6 +193,7 @@ or touched outside the queue.
   · any BLOCKED (<F1> + <F2> + …) → supply the listed missing inputs, then re-run /fold-findings
   · any REPLAN (<F1> + <F2> + …) → /unit-lane <slug> or /unit-lane --fix <n> — the lane re-runs its plan step, appends the phases to the unit's SPEC; its review step gates before /execute-phase on this unit
   · any DECISION (<F1> + <F2> + …) → stop and surface the decision to the user — a `route: decision` conclusion names no planner, so the unit waits on the user before any plan or code change
+  · any PRODUCT (<F1> + <F2> + …) → /unit-lane <slug> or /unit-lane --fix <n> — the lane repairs the half, its review step re-judges it
 ```
 
 Every `· ` sub-bullet is exactly one physical line — never hard-wrapped across
@@ -187,12 +206,13 @@ carry `<slug>` or `<n>` into a live hand-off.
 
 ## Closing-block decision branch (choose one, at emission)
 
-The closing block picks exactly one of four outcomes. The **no-decision →
+The closing block picks exactly one of five outcomes. The **no-decision →
 re-review default** holds whenever the turn carries no recorded prior consumer
 decision to skip.
 
 | Batch state | Branch | `→ Next:` (consumer) |
 |---|---|---|
+| freeze-batch (≥ 1 product-owned row) | `PRODUCT-ROUTE` | `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) when the router concludes `product` — the lane repairs the half through its `design` step, its `review` step re-judges it; the conclusion printed by `node scripts/unit-route.mjs <unit>` (discovery step the fold already ran) |
 | freeze-batch (≥ 1 replan-class row) | `REPLAN-ROUTE` | `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) when the router concludes `replan` — user confirms, the lane's `plan` step appends the phases and its `review` step gates, then `/execute-phase` on this unit; on `route: decision` stop and surface the decision to the user — the conclusion printed by `node scripts/unit-route.mjs <unit>` (discovery step the fold already ran) |
 | `all-repair-in-place` + docs-only + no folded row severity `high` + prior consumer skip decision | `RE-REVIEW-SKIPPED` | skip — consumer has explicitly decided to skip the re-review |
 | `all-repair-in-place` + docs-only + no folded row severity `high` | `RE-REVIEW-OPTIONAL` | `/review-change` (default, delta mode) — or the consumer's recorded skip decision |

package/skills/fold-findings/references/FOLD_PROCESS.md

@@ -44,6 +44,7 @@
    | Condition over the taken batch | Batch class | Fold behavior |
    |---|---|---|
    | ≥ 1 row with frozen class `replan-in-unit` or `decision-required` | `frozen (replan present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the REPLAN-ROUTE and every retained (unfolded) row id; the loop stops; the consumer is the conclusion printed by `node scripts/unit-route.mjs <unit>` (discovery step the fold already ran), where `<unit>` is the bare folder number or the full slug (both resolve): on `route: replan` the planner command the router printed — `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) — the lane appends the phases and its `review` step gates, then `/execute-phase` on this unit; on `route: decision` stop and surface the decision to the user, never a planner |
+   | ≥ 1 row with frozen class `fix-now` whose `Route` cell begins `product owner`, `product-owned` or `owned by product` (head-anchored, identical to `scripts/unit-route.mjs`'s `PRODUCT_ROUTE` regex: `/^(?:product[- ]owner\|product[- ]owned\|owned by product)\b/i`, per `#293`) | `frozen (product owner present)` | **freeze-batch** — nothing folds, no `folded: yes` flips, no commits; the receipt records the PRODUCT-ROUTE and every retained (unfolded) row id; the loop stops; the consumer is the conclusion printed by `node scripts/unit-route.mjs <unit>`: `route: product` and the lane hand-off — `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix) — the lane repairs the half, its `review` step re-judges it, then `/execute-phase` on this unit |
    | all taken rows foldable, none replan-class | `all-repair-in-place` | fold as today (group → fix → gate → commit → flip) |
    | empty queue (zero findings taken) | `none` | receipt only |
 
@@ -51,8 +52,9 @@
    class set (`CLASSIFY.md`); the receipt invents no parallel vocabulary.
 
    The emitted branch follows the closing-block decision inputs in the skill:
-   a freeze-batch always selects `REPLAN-ROUTE`; otherwise the docs-only
-   file-set test (E-D3) and the frozen-severity-`high` override (E-D2) select
+   a freeze-batch selects `REPLAN-ROUTE` for a `frozen (replan present)` batch
+   and `PRODUCT-ROUTE` for a `frozen (product owner present)` batch; otherwise
+   the docs-only file-set test (E-D3) and the frozen-severity-`high` override (E-D2) select
    `RE-REVIEW-OPTIONAL` vs `RE-REVIEW-REQUIRED (delta)`.
 8. **Disputes.** Non-reproducible/already-fixed/wrong findings become
    `DISPUTED <evidence → user decision>`; never edit classification or create an
@@ -82,7 +84,7 @@ present:
 - Repaired: <F-ids with (VF-<n>) refs, joined ` + `, or `none`>
 - Refuted/open: <F-ids joined ` + `, or `none`>
 - Gate: <command> → exit <n> at head <40-hex sha> · n/a when nothing was folded
-- Batch class: <all-repair-in-place | frozen (replan present) | none>
+- Batch class: <all-repair-in-place | frozen (replan present) | frozen (product owner present) | none>
 - Fold diff: <shortstat from a real `git diff` run> · none when nothing was folded
-- Branch: <RE-REVIEW-REQUIRED (delta) | RE-REVIEW-OPTIONAL | RE-REVIEW-SKIPPED | REPLAN-ROUTE>
+- Branch: <RE-REVIEW-REQUIRED (delta) | RE-REVIEW-OPTIONAL | RE-REVIEW-SKIPPED | REPLAN-ROUTE | PRODUCT-ROUTE>
 ```

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 3.3.0
+version: 4.0.2
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -21,6 +21,10 @@ raw placeholders.
 ## Turn contract — verify before ending the turn
 
 ```
+✓ Required user inputs were answered concretely (not defaulted). Consent for
+  every install, hook, and overwrite is explicit; a consent gap runs the
+  three-tier dispatch and stops with the dispatcher's `open-questions@1` block
+  — against a scratch unit folder when no unit exists yet (§Consent).
 ✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
 ✓ Nothing was installed or overwritten without an explicit yes
 ✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
@@ -38,6 +42,21 @@ first on purpose).
 - Prefer this over a static `npx degit gtrabanco/agentic-workflow/template` when you
   want the gate commands, architecture, and doc domains filled in by interview.
 
+## Consent — mandatory, never defaulted
+
+Installing a tool, wiring a hook, or overwriting an existing file each need an
+explicit yes; context never supplies one, and an ambiguous repository state
+(partially scaffolding) is not a route to guess. A consent gap is an open
+question: **(0) provenance** (search the repo's own docs and record where) →
+**(1) research** (concrete options) → **(2) halt**: run `node
+scripts/needs-input.mjs <unit-dir>`, paste the `open-questions@1` block verbatim,
+stop with the questions carried in it. The dispatcher needs a unit folder, and
+consent gaps usually precede any unit — so the run first writes a scratch one
+(`SPEC.md` + `decisions.md` in a `mktemp` directory, deleted after the paste)
+and runs the dispatcher against that. Grammar and exit codes:
+`orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open questions.
+`[target-dir]` is optional — absent means the current directory, recorded.
+
 ## Step 0 — Discover the project (always first)
 
 Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
@@ -133,7 +152,7 @@ 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 13 sections: Objective, Why, User outcome,
+`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.
 

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -22,7 +22,7 @@
    that the scaffold failed. If retained, add its documentation-map row and
    name the project's explicit architectural-decision authority.
 7. **Propagate the unit doc template.** Ensure
-   `docs/features/_TEMPLATE/SPEC.md` exists with all 13 mandatory sections.
+   `docs/features/_TEMPLATE/SPEC.md` exists with all 14 sections sections.
    This is the template used when creating new unit documents.
 8. **Provision the Serena project config.** Load
    [SERENA](SERENA.md), ask consent, then: (a) append the `.gitignore`

package/skills/init-workspace/references/UPGRADE.md

@@ -36,11 +36,11 @@ lacks**. Nine ordered steps:
 4. **Propose the adaptive lane conventions (feature 61 P11).** For pre-lane
    installs (before the fixed pipeline was retired), propose these missing
    blocks additively — **never clobber existing content**:
-   - The **unit document conventions** section in AGENTS.md (the 13-section
+   - The **unit document conventions** section in AGENTS.md (the 14-section
      SPEC.md, triage-driven step selection, diff-size guard, evidence rows,
      dated progress log, closed commit format `type(scope): description`).
    - The **unit doc template** under `docs/features/_TEMPLATE/SPEC.md` if
-     absent — the same 13-section template used by new units.
+     absent — the same 14-section template used by new units.
    - The **lane workflow doc** under `docs/workflow/` if absent: `FEATURE_WORKFLOW.md`
      (unit doc → triage → catalog steps → evidence → review → release),
      `ISSUE_WORKFLOW.md` (issues route through triage to the lane).

package/skills/orchestration-envelope/SKILL.md

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

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

@@ -85,6 +85,50 @@ next | suggested
 next | continuation
 ```
 
+## Open questions (the needs-input halt)
+
+An input a step cannot resolve is never inferred: the step stops and hands the
+questions back. The block below is that hand-off — printed by
+`scripts/needs-input.mjs`, never hand-authored — so a weaker model copies it
+instead of paraphrasing the questions away. Interactive, the block is the pause
+point and the run waits for a user decision; unattended, it is a hard fail
+carrying the same block.
+
+```text
+open-questions@1
+# produced-by: scripts/needs-input.mjs <unit-dir> [--json]
+# input:       <unit-dir>/SPEC.md + <unit-dir>/decisions.md (the ledger's own grammar is
+#              published by the template agent guide, template/AGENTS.md)
+# machine:     continuation-refusal-type (schema-export:CONTINUATION_REFUSALS)
+# exit:        0 well-formed artifact (pending questions or none) | 1 fail-closed | 2 usage error
+header:      open-questions@1
+fields:      Unit: <unit-folder-name>
+             Open questions: <count>
+             - <question-id> · <route> · <the question>
+               Blocks: <why nothing proceeds without it>
+               Searched: <where the repository was searched: path:line, greps, prior units>
+               Options:
+                 - <one researched option with its trade-off>
+             Pending: none                    (only when the count is 0)
+             Route back: <design | unit-lane> · … | none
+             Continuation: no-decision-available | none
+             Decision: open | none
+fail-block:  NEEDS-INPUT FAIL — needs-input@1
+             Unit: <unit-folder-name>
+             Reason: <missing-unit-doc | malformed-ledger-header | malformed-entry |
+                      missing-search-receipt | missing-options | unknown-route |
+                      unknown-question | invalid-authority | duplicate-id>
+             Where: <path[:line]>
+             Continuation: no-decision-available
+route:       design | unit-lane
+```
+
+`route` is the stage that owns the fact and therefore receives it back —
+`design` for scope/architecture questions, `unit-lane` for plan-owned facts.
+Execution never interviews: it halts with the questions. `Continuation` reuses
+the schema's existing `no-decision-available` (`decisionAvailable === false`),
+so the halt needs no new envelope field.
+
 ## Path-protection checkpoint (feature 60)
 
 The Tier 1 path gate is versioned so the checkpoint invocation, the closed

package/skills/review-change/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-change
 user-invocable: true
-version: 3.11.0
+version: 3.12.0
 argument-hint: <path-or-glob> [--adversarial N] [--synthesize]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

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

@@ -138,9 +138,10 @@ exact command tokens.
         fix); the lane re-runs its plan step on this branch, its review step
         gates, then `/execute-phase <unit>` (yes: list the finding ids; no: omit
         this line)
-      · any finding owned by product? → /unit-lane <unit> — the lane's design
-        step repairs the half, its review step re-judges it (yes: list the ids;
-        no: omit this line)
+      · any finding owned by product? → `node scripts/unit-route.mjs <unit>` prints
+        `route: product` + the lane hand-off — `/unit-lane <unit>` for a feature,
+        `/unit-lane --fix <n>` for a fix: the lane repairs the half, its review
+        step re-judges it (yes: list the ids; no: omit this line)
       · independent proposals → present to the user; only the user routes them
         to /triage-issue
      · adversarial recommendation checklist fired AND this run was

package/skills/review-implementation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-implementation
 user-invocable: false
-version: 1.10.0
+version: 1.11.0
 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

@@ -175,7 +175,7 @@ finding in its `Route` cell.
 |---|---|---|
 | `source` | fold locally: `/fold-findings`, then re-run `/review-change` on the changed HEAD | — |
 | `plan` | run `node scripts/unit-route.mjs <unit>` → `route: replan`; the planning author re-cuts the artifact (SPEC `## Phases`, an obligation row, an acceptance mapping, a ledger) on the same branch with the user's confirmation, then the lane's **`review` step** precedes `execute-phase` | fold it in code and leave the plan describing the old build |
-| `product` | `/unit-lane <unit>` repairs the half through its `design` step, its `review` step re-judges it | patch the product claim into agreement in code |
+| `product` | run `node scripts/unit-route.mjs <unit>` → `route: product` → `/unit-lane <slug>` (feature) or `/unit-lane --fix <n>` (fix): the lane repairs the half through its `design` step, its `review` step re-judges it | patch the product claim into agreement in code |
 | `environment` / `runtime` | the existing retry/`BLOCKED` paths | translate into a PASS, or an issue |
 
 - `fix-now` with a `plan` or `product` owner keeps its severity but is **not**

package/skills/triage-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: triage-issue
 user-invocable: true
-version: 2.10.0
+version: 2.11.0
 argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/triage-issue/references/REVIEW_FINDING_PROCESS.md

@@ -24,6 +24,13 @@ after `/fold-findings` leaves rows unresolved.
      `decision-required`. Ask the user; do not guess or weaken the finish line.
    - A finding disproved by current evidence is `disputed`. Preserve the row
      and show the evidence; do not mark it folded or silently delete it.
+   - A `fix-now` finding whose owning stage is `product` — the finding is
+     against the product half, not the code — is `product-repair` (#293). Run
+     `node scripts/unit-route.mjs <unit>`; its `route: product` line prints the
+     lane hand-off (`/unit-lane <unit>` for a feature, `/unit-lane --fix <n>`
+     for a fix): the lane repairs the half, its review step re-judges it. Never
+     fold it into the current unit — the fold loop repairs source, not
+     authority (`pre-execution-review` POLICY §4).
 
 4. Never implement the new phases in this triage turn. After a replan, ask the
    user to continue manually with `/execute-phase <unit> P<n>` (or the fix
@@ -34,7 +41,7 @@ Return exactly one block per finding:
 ```text
 REVIEW FINDING <F-k> — <short title>
 Checked: <commands and evidence>
-VERDICT: fix-now | replan-in-unit | decision-required | disputed
+VERDICT: fix-now | replan-in-unit | decision-required | product-repair | disputed
 Action taken: <current-unit fold/phase | unit-lane | user decision>
 ```
 

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 1.5.0
+version: 2.0.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
@@ -21,6 +21,10 @@ Tick every box before ending the turn; an unchecked box means the turn is not
 done:
 
 ```
+✓ Required user inputs were answered concretely (not defaulted). Nothing here
+  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.
 ✓ 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
@@ -44,6 +48,26 @@ Both `--fix <n>` and `--from-issue <n>` are the exact forms
 `scripts/unit-route.mjs` prints for a tracked issue with no unit folder
 (`route: plan-from-issue`) — never invent a different spelling.
 
+## Inputs — never inferred, never defaulted
+
+The unit identifier, a mode's issue number, the unit kind, and the
+objective/why/user-outcome the SPEC carries are **never inferred**: no silent
+`feature` default, no acceptance criterion invented from a vague request. A gap
+is resolved in one fixed order — **(0) provenance** (search the repo's own docs
+and append an `open-question` row to the unit's `decisions.md` recording where)
+→ **(1) research** (2–3 concrete options with trade-offs; asking for more
+research is a legitimate answer) → **(2) halt**: run `node
+scripts/needs-input.mjs <unit-dir>`, paste the `open-questions@1` block verbatim,
+stop. The block routes each question back to the stage that owns the fact —
+`design` for scope/architecture, `unit-lane` for plan-owned facts. Grammar and
+exit codes: `orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open
+questions.
+
+The conversation lives in the unit folder's `decisions.md` (append-only
+`open-questions@1`; its two entry types are published in the template agent
+guide's question protocol). A resumed session re-reads the pending rows and
+continues from the first one still open — never re-asks them.
+
 ## Step 0 — Discover the project
 
 Per the agent guide's **Workflow conventions** + **documentation map**, then read

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

@@ -1,5 +1,16 @@
 # Design step
 
+## Needs-input guard
+
+A blank or vague scope or acceptance-criteria input is a gap, not a licence to
+infer. The order is fixed: search the repository's own docs first and append an
+`open-question` row to the unit folder's `decisions.md` recording where; research
+an external gap into 2–3 concrete options. A gap surviving both runs
+`node scripts/needs-input.mjs <unit-dir>`, pastes the `open-questions@1` block
+and stops — route `design` for scope/architecture questions. "Decide for me" is
+a legitimate answer: the lane chooses and records the choice with its reason.
+Cheap-to-change defaults are recorded as assumptions, never silent.
+
 ## Purpose
 
 Run the gap interview, induce acceptance criteria from user scenarios, and

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

@@ -1,5 +1,16 @@
 # Research step
 
+## Needs-input guard
+
+**Unit objective and scope** are the input to this step, and the lane authors
+them, not the user. A blank or missing objective/scope is therefore a **document
+defect**: stop and repair the SPEC (`/unit-lane <unit>` — its §1 writes the
+objective/why/user-outcome) or re-triage. Never infer unit scope, and never
+turn a doc defect into a question the user cannot answer. A gap that survives
+the repair runs `node scripts/needs-input.mjs <unit-dir>`, pastes the
+`open-questions@1` block and stops, routed to `design` or `unit-lane` by the
+owning stage.
+
 ## Purpose
 
 Establish what is known and what is uncertain about the unit's domain before