@gtrabanco/pi-agentic-workflow 0.21.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.21.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.8.0
+version: 1.9.0
 argument-hint: [finding-id …]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -144,8 +144,16 @@ table: [`FOLD_PROCESS.md`](references/FOLD_PROCESS.md) §Batch classification.
 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)

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/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