@gtrabanco/pi-agentic-workflow 0.10.5 → 0.10.7

package/package.json

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

package/skills/design-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: design-feature
 user-invocable: true
-version: 3.3.0
+version: 3.4.0
 argument-hint: <idea | NN-slug> [<instruction>]
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -89,15 +89,18 @@ another `references/` path; in the DEFER column, bare names live in the same
 directory as the links.
 
 **Hard stop for an incomplete raw-idea interview:** LOAD exactly
-`references/INTERVIEW.md` and no other reference. Ask its one next
-question, return `NEEDS_INPUT`, and end the turn. `WRITE_AND_UPSERT.md` is
+`references/INTERVIEW.md` and no other reference. Present its ONE compact
+form-turn — the ≤ 6 fixed rubric slots plus the identity rows, each carrying a
+recommended default the user can accept with one word — then return
+`NEEDS_INPUT` and end the turn when slots remain unresolved; genuine ambiguity
+gets at most **2 follow-up turns**, never a third ask. `WRITE_AND_UPSERT.md` is
 forbidden until every mandatory interview slot is resolved; that resource then
 owns closure rows and writing.
 
 | Condition now | LOAD now | DEFER / SKIP now |
 |---|---|---|
 | Bare existing slug, no instruction | [interview](references/INTERVIEW.md) through its interaction rule; report status and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` |
-| Brand-new idea with any mandatory interview slot unresolved | [interview](references/INTERVIEW.md) only; ask exactly its next question and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` |
+| Brand-new idea with any mandatory interview slot unresolved | [interview](references/INTERVIEW.md) only; present exactly one form-turn (≤ 6 slots + identity, each with a default) and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` |
 | New idea after every mandatory interview slot resolves | [interview](references/INTERVIEW.md), then [closure, write, and upsert](references/WRITE_AND_UPSERT.md) | `UPSERT_EXAMPLE.md` unless shape is ambiguous; `REPAIR.md`, `PORTABILITY.md` |
 | Existing slug plus instruction | interview, then closure/write/upsert | [upsert example](references/UPSERT_EXAMPLE.md) unless shape is ambiguous; `REPAIR.md`, `PORTABILITY.md` |
 | Existing slug whose `progress.md` carries `SPEC-REVIEW-FAIL` or `NEEDS-DESIGN` | [interview](references/INTERVIEW.md), then [review repair](references/REPAIR.md) | `UPSERT_EXAMPLE.md`, `PORTABILITY.md` |

package/skills/design-feature/references/INTERVIEW.md

@@ -16,10 +16,13 @@
 3. **Raw-idea interview (folded in, only when starting from zero or the
    instruction leaves genuine gaps).** Fixed protocol — structural, not
    judgement:
-   - **One question per turn, never batched.** Each question carries a
-     recommended default the user can accept with one word. Ask nothing the
-     docs or the instruction already answer.
-   - **Vagueness rubric (fixed slots — the question list IS this list).**
+   - **One form-turn, then at most 2 follow-up turns.** The first interview
+     turn is ONE compact form covering every rubric slot below plus the
+     identity slots, each row carrying a recommended default the user accepts
+     with one word (or edits in place). Ask nothing the docs or the instruction
+     already answer. Genuine ambiguity the form cannot resolve gets at most
+     **2 follow-up turns** — never a third ask.
+   - **Vagueness rubric (fixed slots — the form rows ARE this list).**
      Probe each slot until it is filled or explicitly `n/a: <reason>`:
      1. **Affected users/roles** — who uses it; who must not.
      2. **Error & edge states** — what happens on failure / empty / invalid.
@@ -40,11 +43,13 @@
    - **Escalation (structural).** If, after the interview, **≥ 3 rubric slots
      remain empty** (neither filled nor `n/a`), do not guess: end the turn
      `NEEDS_INPUT`, listing the empty slots verbatim as the pending
-     questions — the feature is not designable yet.
-   - The identity questions ride the same one-per-turn protocol: problem &
-     goal, business goals, size estimate (`XS/S/M/L` — XS/S stays SPEC-only,
-     M/L gets the full artifact set), non-goals / future work, traceability
-     (offer a tracking issue; if created, the eventual PR will `Closes #n`).
+     questions — the feature is not designable yet. Ambiguity that survives the
+     follow-up budget escalates the same way (`interview:ambiguity-cap`): the
+     2-turn cap never licenses a third ask.
+   - The identity questions ride the same form-turn: problem & goal, business
+     goals, size estimate (`XS/S/M/L` — XS/S stays SPEC-only, M/L gets the
+     full artifact set), non-goals / future work, traceability (offer a
+     tracking issue; if created, the eventual PR will `Closes #n`).
 4. **Proportional research.** Capability closure (step 5) is cheap and comes
    first. Reach for external or domain research **only** when the feature
    touches a domain genuinely new to the project (a regulation, an unfamiliar

package/skills/orchestration-envelope/SKILL.md

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

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

@@ -20,6 +20,37 @@
 
 **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.
 
+## Machine-check profile (boxes 1–5)
+
+Boxes 1–5 are mechanical. Demonstrate them by running the verifier — the
+scaffold shim `template/.agentic-workflow/hooks/turn-contract.sh` (bash + git +
+gh; presence-only box2 — the conditional phase-lint clause is engine-only, so
+a shim receipt leaves that clause unverified, ED-52-3) or the producer-crate
+engine `packages/agentic-workflow/bin/turn-contract.mjs` — and pasting its
+one-line receipt beside the git/gh evidence. When the receipt is pasted,
+reciting boxes 1–5 in prose is **not** required. Verifier unavailable (no bash,
+or no shim/engine in the project)? Recite boxes 1–5 exactly as before — the
+profile never weakens a box, and a turn with neither receipt nor recitation is
+unverified. Boxes 6–11 are unchanged: they stay agent-attested judgment calls
+no script may speak for. The closing `→ Next:` block may be echoed from the
+`workflow-status` envelope instead of hand-authored: `next.recommended`
+supplies the recommended line and `next.alternatives` the `·` sub-bullets,
+preserving the fixed block shape.
+
+```text
+turn-contract-receipt@1
+ok-line:    TURN-CONTRACT ok
+fail-line:  TURN-CONTRACT fail box<N>: <code>
+codes:      branch-default | not-a-repo | no-commits | acceptance-missing |
+            phase-lint-failed | pr-not-open | pr-head-mismatch |
+            pr-unreachable | dirty-tree | ahead-of-remote
+exit:       0 ok | 1 contract fail | 2 usage error
+order:      boxes 1→5, first failure wins; within box5, dirty-tree precedes
+            ahead-of-remote
+stdout:     exactly one line; diagnostics never (git/gh evidence stays in the
+            agent's transcript)
+```
+
 ## Hand-off grammar (versioned — read by `scripts/normative-drift.test.mjs`)
 
 Box 9's closing hand-off and box 10's machine result are ordered here, so the
@@ -51,5 +82,6 @@ next | recommended
 next | alternatives
 next | tier
 next | suggested
+next | continuation
 ```
 

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

@@ -1,5 +1,9 @@
 ## Persist and decide
 
+When the unit's review receipt is missing or stale, the re-entry command is the
+**emitted** `next.continuation` (`rendering` for display) — quote it, never author
+exact command tokens.
+
 11. **Persist fix-now findings to the fold ledger.** The unit's **fix-now fold
    ledger** is `review-findings.md`, located beside its other docs
    (`docs/features/<NN>-<slug>/review-findings.md` for a feature,

package/skills/review-plan/references/OUTPUT.md

@@ -6,7 +6,10 @@ Append the receipt to `docs/features/<NN>-<slug>/progress.md` (fix units:
 `docs/fix/<N>/progress.md`), then append every finding row to
 `planning-findings.md` (ledger contract: `pre-execution-review/references/LEDGERS.md`).
 Any later write to a reviewed plan artifact rotates `artifactRevisionId` and makes
-this receipt stale — that is the contract working, not a mistake.
+this receipt stale — that is the contract working, not a mistake. When a missing or
+stale receipt is the reason for re-entry, the re-entry command is the **emitted**
+`next.continuation` (`rendering` for display): quote it, never author exact command
+tokens.
 
 One `PreExecutionReviewReceipt v1`
 (`agentic-workflow/pre-execution-review-receipt@1`) per review:

package/skills/review-spec/references/OUTPUT.md

@@ -8,7 +8,9 @@ each finding row to the unit's `planning-findings.md`** with
 create the file from that contract when the unit has none. A findings ledger the
 reviewer cannot write is not a ledger. Any later write to a reviewed artifact
 rotates `artifactRevisionId` and makes this receipt stale — that is the contract
-working, not a mistake.
+working, not a mistake. When a missing or stale receipt is the reason for re-entry,
+the re-entry command is the **emitted** `next.continuation` (`rendering` for display):
+quote it, never author exact command tokens.
 
 One `PreExecutionReviewReceipt v1`
 (`agentic-workflow/pre-execution-review-receipt@1`) per review, in a fenced block:

package/skills/ship-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship-roadmap
 user-invocable: true
-version: 5.2.1
+version: 5.2.2
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--fullauto] | --continue [--fullauto]"

package/skills/ship-roadmap/references/RECOVERY_AND_SELECTION.md

@@ -85,7 +85,7 @@ turns:
          stages (`plan-fix` → REVIEW-PLAN → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
          budget caps, floors, and merge policy as features.
    6. Nothing startable → `SHIP: BLOCKED` with the **unblock map** ("merging
-      #12 unblocks 05 and 07") and the resume command.
+      issue `#<n>` unblocks features `05` and `07`") and the resume command.
 
    `execute-phase`'s own dependency gate stays active inside every subagent —
    it's the belt to this braces. **The autopilot never passes `--force`:** a

package/skills/workflow-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.6.0
+version: 3.7.0
 author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>]"
@@ -117,6 +117,9 @@ the JSON contract.
 - The human summary (unless `--json-only`) and the envelope are printed, envelope
   last.
 - Nothing was modified anywhere.
+- When the envelope carries `next.continuation`, the next-command echo **quotes the
+  emitted `next.continuation`** (`rendering` for display), never author exact command
+  tokens; the human-facing prose `→ Next:` block below stays.
 
 → Next: the envelope's `next.recommended` command — it is computed from the
   actual state, so it IS the recommendation

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

@@ -41,7 +41,7 @@ sensor reports a missing gate, never a verdict that no review ever happened.
 |---|---|---|
 | `current` | stage PASS verdict **and** recomputed digest = bound digest | spec: `/plan-feature <slug>` · plan: `/execute-phase <NN>` |
 | `missing` | no receipt block for the stage | `defined` → `/review-spec <slug>` · planned/in-progress → `/review-plan <NN>` |
-| `stale` | bound digest differs, or a bound context row moved | re-run **that stage's** review |
+| `stale` | bound digest differs, or a bound context row moved | re-run **that stage's** review — quote the emitted planning-gate re-run continuation (`next.continuation`, `rendering` for display), never author exact tokens |
 | `wrong-stage` | the only PASS belongs to the other stage | the stage that is missing — never the stage that passed |
 | `substitute` | prose verdict, legacy block, or internal attestation stands where a receipt should be | that stage's review, and report the substitute as a blocker detail |
 | `self-approved` | the author of the artifact recorded the PASS | that stage's review in a clean context |
@@ -50,9 +50,11 @@ sensor reports a missing gate, never a verdict that no review ever happened.
 | `impossible-timeline` | `structural.fresh: false`, `structural.reasonCode: impossible-timeline` — digest and revision match by construction; a receipt's own recorded timeline is physically impossible (finish predating source revision's commit date beyond the published skew); a legacy receipt with no parsable Started/finished: line, or a source revision git cannot resolve, stays unflagged (fail-open) | that stage's review — the timeline is self-refuting, not a stale source |
 
 A stale receipt re-runs the **review**, not the authoring skill: the artifacts may be
-exactly right and simply need re-judging in a clean context. A missing verdict block,
-or a verdict outside the stage's fixed set, is `missing` with the reason recorded —
-never a guess in the recommended direction.
+exactly right and simply need re-judging in a clean context. The command to re-run is
+the **emitted** `next.continuation` (`rendering` for display) — quoted as-is, never
+authored as fresh command prose. A missing verdict block, or a verdict outside the
+stage's fixed set, is `missing` with the reason recorded — never a guess in the
+recommended direction.
 
 ### Envelope projection