pi-gauntlet 7.24.0 → 7.25.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v7.25.0 - 2026-10-21
+
+### Changed
+
+- **Decision menus render 1-N after a numbered list.** A numbered option menu placed directly below an ordered list, separated only by a blank line, rendered as `4.`-`6.` because CommonMark merged the two lists; a human replying `5` was then read against a three-option menu. One shared reference, `skills/brainstorming/reference/menu-layout.md`, owns the three permitted layouts (a prose line, a `---` rule, or bullets above the menu) and the reply mapping: a bare reply above the option count resolves to `R - L` when it lands in range, the agent echoes the resolved option in one sentence (`Taking 5 as option 2 - merge`) before acting, and any other out-of-range reply gets a clarifying question. Every menu site in shape-ticket, chase-bug, gatekeep-pr, check-delivery, finishing-a-development-branch, and gauntlet-resume cites it with one line; no site restates the rule. (#73)
+- **check-delivery's confirmation gate is a two-option menu** (`1. approve the write` / `2. decline`); a typed `yes` still approves. (#73)
+
+### Added
+
+- Eval target `check-delivery` and a `menu-after-numbered-findings` sample in six targets; `shape-ticket`, `gatekeep-pr`, and `check-delivery` load the shared reference through `target.json`. (#73)
+
 ## v7.24.0 - 2026-10-21
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.24.0",
+  "version": "7.25.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/reference/menu-layout.md

@@ -0,0 +1,37 @@
+## Exposure
+A numbered option list directly after an ordered list with only a blank line merges under CommonMark, displaying `N+1.`-`N+k.` after `N` preceding items. This control renders the options as `4.`-`6.`:
+```markdown
+1. Finding A
+2. Finding B
+3. Finding C
+
+1. Keep
+2. Merge
+3. Stop
+```
+
+## Permitted layouts
+Separate numbered options from preceding ordered content. Default to a prose line (`Pick one:` or `Verdict:`); alternatively insert a `---` rule or write preceding content as bullets:
+```markdown
+1. Finding
+
+Pick one:
+1. Merge
+```
+```markdown
+1. Finding
+
+---
+
+1. Merge
+```
+```markdown
+- Finding
+
+1. Merge
+```
+
+## Reply mapping
+Apply only to bare numeric replies to numbered option menus. Leave #63 compound replies such as `1: cache=A` and its bare-`1` shortcut to [disposition-protocol.md](../../finishing-a-development-branch/reference/disposition-protocol.md).
+Count `N` options and let `L` count every preceding item in the entire contiguous ordered run adjoining the options through blank lines alone. Stop at prose, a rule, or bullets; earlier separated lists contribute nothing. Set `L = 0` after a separator.
+Take replies `1`-`N` unchanged, without echo, even when they also equal `L + k`. Only map `R > N` with `1 <= R - L <= N` to option `R - L`; echo the resolution before acting: `Taking 5 as option 2 - merge`. For every other out-of-range reply, ask a clarifying question naming the valid range `1`-`N`.

package/skills/chase-bug/SKILL.md

@@ -167,6 +167,8 @@ change request, not a menu row.
 **Real bug** - four actions (all rendered unless noted), exactly one tagged
 `[recommended]`. Untracked origin:
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 1. [ ] File a ticket - /skill:shape-ticket, seeded with this evidence.
 2. [ ] Brainstorm now - /skill:brainstorming with this evidence as the seed.
@@ -176,6 +178,8 @@ change request, not a menu row.
 
 Tracker/GitHub origin (ticket row omitted as today, renumbered):
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 1. [ ] Brainstorm now - /skill:brainstorming with this evidence as the seed.
 2. [ ] Implement hotfix now - follow hotfix.md; add "as a PR" for a PR.
@@ -241,6 +245,8 @@ A verdict without its named citation is a red flag (see Red Flags - STOP).
 For a negative verdict, render the verdict with its citation, then a short
 numbered menu:
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 Verdict: <verdict name> - <citation>
 
@@ -254,6 +260,8 @@ way; for `cannot-replicate`, renumber the discovery-ticket row to 2.
 
 For `cannot-replicate` only, add a third row offering a discovery ticket:
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 3. [ ] File a discovery ticket - /skill:shape-ticket, seeded with what's missing.
 ```
@@ -379,6 +387,8 @@ rendered is out of skill scope - the skill has ended.
 
 **Real-bug example:**
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 Fault story: user pastes a URL with a trailing slash -> the router's path
 matcher does an exact string compare instead of normalizing -> the route

package/skills/check-delivery/SKILL.md

@@ -260,7 +260,18 @@ explicit yes-gate as the success path. Never posted unprompted.
 All-clear path -> **one confirmation gate**: present the shipped SHA,
 deliverable set, stage results (including any skip), the per-AC verdict
 table with evidence, the reviewer script, and the exact write about to
-happen. On approval, one batched write. The numbered steps below are the
+happen.
+
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
+```text
+1. approve the write
+2. decline
+```
+
+Treat option `1` or typed `yes` as explicit approval; option `2` or any
+unrecognized/non-approval reply means no write. On approval, one batched
+write. The numbered steps below are the
 ordinary-run shape; when a ratified descope strike is in play, the
 body-edit half precedes step 1 - see the `descope edits` paragraph below
 for its mechanics, not repeated here:

package/skills/finishing-a-development-branch/SKILL.md

@@ -180,6 +180,8 @@ Omit the block when N = 0.
 
 **Normal repo and named-branch worktree — present exactly these 5 options:**
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 Implementation complete. What would you like to do?
 
@@ -194,6 +196,8 @@ Which option?
 
 **Detached HEAD — present exactly these 4 options:**
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 Implementation complete. You're on a detached HEAD (externally managed workspace).
 

package/skills/gatekeep-pr/reference/decision-menu.md

@@ -8,6 +8,8 @@ Read from SKILL.md step 6. Input: the report's verdict and the PR state. Output:
 
 Render fix consequences with the applicable lifetime from `post-selection-loop.md` `### Continuation record`. For named fixes, state that authority retains only the selected stable IDs for later independent reassessments, with the same lifetime as broad fixes; link active pre-push retries to `fix-wave.md` `## Review before push`. For clarification-only fixes, state one-shot authority for the exactly selected payload; keep nit consequences one-shot.
 
+Read and apply [menu-layout](../../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 Rows are `<n>. <verb> - <consequence>`; every row, `stop` included, carries its consequence clause. `stop` is always last, before the compose hint. `show evidence` is always offered and never `[recommended]`. A row the actor cannot execute - by `## Availability` below, or because the forge would refuse it (branch protection, a withhold) - is omitted and named in the compose line's `Not offered:` sentence; it is never `[recommended]`. Exactly one row is `[recommended]`. A **terminal overlay** is `own merge`, `merge queued` (once its read returns `MERGED` it re-renders as `own merge`), `approved`, or `merged or closed PR`; every other menu is an ordinary open-PR menu. **Landed** means the PR's `state` is `MERGED`; under `approved` and under a closed-unmerged PR nothing has landed.
 
 - `accept contract change` - invoke the concrete proposal's owning amendment process through `post-selection-loop.md` `### Contract decision`; settle the baseline only after completion

package/skills/gatekeep-pr/reference/post-selection-loop.md

@@ -93,6 +93,8 @@ Apply per `fix-wave.md`: the local conflict check, one fresh implementer helper
 
 After `gh pr merge` returns, read `gh pr view <N> --json state,mergeCommit`. `state: MERGED` -> write the returned `state` into `pr.state` and `mergeCommit.oid` into `pr.merge_commit` (the same two writes when a queued merge's `wait` re-read returns `MERGED`), render the `AC coverage` block once and re-render the menu under the `own merge` overlay (`decision-menu.md`); any other state (a merge queue) -> one `PR comments` line `The merge is queued, so coverage posts wait. (<state>)` and the menu `wait` (re-run the read) / `show evidence` / `stop`. The block, `<sha>` = `mergeCommit.oid`, one row per `scope.rows` entry in row order with its outcome (`covered`, `deferred per spec to <ref>`, `deviates per spec: <why>`, `elsewhere per spec: <repo>`, `venue: <env> - <observation>, checked before prod deploy`); with no rows (`source: pr`, or an empty `scope.rows`) the block has no row lines and `post coverage to ticket` is not offered. With `source: pr` the header line drops `, spec <path>`. An `in-scope` row whose observation half is `not judged here` renders `covered; observable half checked after merge`.
 
+Read and apply [menu-layout](../../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```markdown
 ## AC coverage
 Informational - the ticket's rows are unchanged. PR <url>, merged <sha>, spec <path>

package/skills/gatekeep-pr/reference/report.md

@@ -8,6 +8,8 @@ Render bottom-up for a terminal: least important first, verdict and menu last. E
 
 Section order is fixed:
 
+Read and apply [menu-layout](../../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 ```
 Delivers: <one sentence: what the PR does. With source: spec, a second sentence built from these clauses in
           order, each present only when it applies, joined with semicolons: covered rows ("ACs 1, 2, 4";

package/skills/gauntlet-resume/SKILL.md

@@ -39,6 +39,8 @@ optional pasted text after the command line. Count tokens first; then first matc
 Spec dirs resolve per `reference/reconstruction.md` "Candidates" (`flowGuards.specDirs`
 precedence).
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 | Input | Route |
 |---|---|
 | no tokens, no pasted text | discovery: `<tmpdir>` via `node -p "require('os').tmpdir()"`; candidates are the regular files directly under `<tmpdir>/pi-handoff/` ending `.md` (non-recursive) whose line 1 starts `# Handoff:`; sorted by mtime, newest first; displayed one per line as `<n>. <title line> - <worktree: field value> - <mtime ISO-8601>` with `worktree: unavailable` when the field is absent; the human picks `<n>` (a single candidate is still confirmed); none -> STOP "no handoff briefs found under <tmpdir>/pi-handoff" |

package/skills/shape-ticket/SKILL.md

@@ -118,6 +118,8 @@ Present, per proposed issue:
 - Proposed comment and supported relations, verbatim, if any - one approval covers the exact title + body + metadata + comment + relation payload.
 - For overlap, show mutually exclusive supported enrichment/create-anyway/no-write alternatives and coverage under the gathered reference; show failing alternatives unavailable. Selecting an option approves that displayed payload without another authorization prompt.
 
+Read and apply [menu-layout](../brainstorming/reference/menu-layout.md) before presenting these options and before acting on a numeric reply.
+
 Number the options. A split offers per-issue subset selection, e.g. "approve 1,3; decline 2". **No affirmative answer on the exact presented diff = no write.**
 
 ### 9 - Write