pi-gauntlet 5.16.2 → 5.17.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.17.0 - 2026-09-22
+
+- `finishing-a-development-branch` runs the plan header's `**Verification:**` set once at ship: Step 1 skips when that set passed in this session's verify phase and `git -C "$WORKTREE" diff --quiet <verified commit> HEAD -- . ':!<telemetry.dir>'` is clean, so the gated flow verifies once before a PR and twice before a squash (the post-squash run stays). The landing menu is renumbered - 1 Push + PR, 2 Push + draft PR (`gh pr create --draft`), 3 Squash-merge, 4 Keep, 5 Discard (detached HEAD: PR, draft PR, Keep, Discard); overrides files that pin finishing option numbers need updating. `writing-plans` defines the header set for multi-service repos as the affected services' commands. `scripts/ci.mjs` pins the three landing headings.
+
+## v5.16.3 - 2026-09-22
+
+- The amendment human batch card carries what the reviewer funnel already knows: the header names the step that raised the batch and the plan consequence of applying as recommended (`from <trigger>; applying as recommended reopens <ids>; <phase consequence>`), each item quotes the reviewer's verdict verbatim on a `Reviewer:` line (`not reviewed - <rule>` for prefiltered items, `reviewer unavailable: <reason>` on a failed dispatch), and `Impact:` states the approved-contract shift per spec section instead of listing plan tasks. The finish-gate disposition bullet mirrors `Reviewer:` and `Impact:`. Supersedes the card fields of `doc/specs/2026-09-19-readable-amendment-gates.md`.
+
 ## v5.16.2 - 2026-09-22
 
 - gatekeep-pr: `SKILL.md` is a flow-ordered body under 250 lines; the assessment phases, finding IDs and dispositions, consent table and courses, and the post-selection loop move to `skills/gatekeep-pr/reference/{assessment,findings,decision-menu,post-selection-loop}.md`, each rule owned once. The CI telemetry-salvage probe reads `reference/post-selection-loop.md`. (#43)

package/README.md

@@ -40,7 +40,7 @@ Concretely, one change through the gauntlet:
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor. Independent implementation, review, and council batches remain parallel, but their dispatches are foreground: the orchestrator waits for terminal results before accepting work or advancing a phase.
 4. **verify**: the parent first runs the plan's full verification command set; only a passing result permits whole-diff code review, then the **conformance gate**. A review fix invalidates that result, so the parent reruns full verification before the next review or conformance gate. The conformance subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Unauthorized rows - shipped surface no human input asked for, whether it crept in or was laundered through the spec - follow their recommendation like every other row: a contained removal auto-runs, anything another requirement leans on is deferred with a plain-language "I'd cut it / I'd keep it" recommendation. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
-5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it against its issue before merging. **Human gate 2** - the only other decision you make.
+5. **`finishing-a-development-branch`**: PR, draft PR, squash, keep, or discard. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it against its issue before merging. **Human gate 2** - the only other decision you make.
 6. *(Optional)* Once the merge lands, `/skill:check-delivery <ref>` can prove delivery - default-branch landing, delivery target, per-AC evidence - before the tracker status advances. Explicit invocation only, no auto-chain: deploys commonly lag merges by minutes to hours, so an auto-run would routinely check too early.
 
 Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive a branch-local one-shot nudge after an unexpected settled stop; it is fire-and-forget, does not bypass either human gate, and older Pi hosts without `agent_settled` retain existing behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.16.2",
+  "version": "5.17.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/amendment-surface.md

@@ -62,18 +62,19 @@ Expected reply - one line per item, nothing else:
 <handle>: auto-apply | escalate - <one-line reason> - probed: <check> - <result>
 ```
 
-Fail closed: a dispatch error, an async handle, a silence-kill, or a missing or malformed line -> that item (every item when the dispatch failed) is `escalate`, and the batch menu carries `reviewer unavailable: <reason>`.
+Fail closed: a dispatch error, an async handle, a silence-kill, or a missing or malformed line -> that item (every item when the dispatch failed) is `escalate`, its `Reviewer:` line `reviewer unavailable: <reason>`.
 
 ## 4. Human batch - one menu
 
-Render only escalated and prefiltered items. Nothing symbol-dense above the fold; each item's `old -> new` sits under `Details`, after the footer.
+Render only escalated and prefiltered items; `<N>` counts them. Nothing symbol-dense above the fold; each item's `old -> new` sits under `Details`, after the footer.
 
 ```
-Spec amendments: <N> need your call.
+Spec amendments: <N> need your call - from <trigger>; applying as recommended <reopens | adds | removes> <task ids | no tasks>; <phase consequence | no phase change>.
 
 * <handle> - <title>: <what>. <why>.
   Example: <before -> after>
-  Impact: <plan tasks/waves affected, or: no plan yet>
+  Reviewer: <one-line reason verbatim | not reviewed - <prefilter rule> | reviewer unavailable: <reason>>
+  Impact: <spec section>: <approved contract> -> <new contract>; ...
   Recommended: <accept | alt-n> (<one-clause why>).
   Alternatives: alt-1 <one line>; alt-2 <one line>
 
@@ -84,6 +85,10 @@ Details
 <handle>: <location> - old: <text> -> new: <text>
 ```
 
+`<trigger>` is the step the main loop is running when the batch forms: `the spec review`, `planning Task <n>`, `Task <n> BLOCKED`, `the verify-phase code review (FIX_FIRST <ids>)`, `the finish-gate council-edit revert`, else `the <phase> phase`; `your request` only for an amend the user raised in prose. The plan clause is the section 5 aftermath as `recommended` would land, over reviewer-cleared plus rendered items, read from the plan file and tracker state - call no `plan_tracker`/`phase_tracker` before the reply: any of `reopens <ids>`, `adds <n> task(s)`, `removes <ids>`, comma-joined (`reopens no tasks` when the plan is untouched), then `; restarts implement, then verify` when a reopen lands in `verify`/`ship`, else `; no phase change`.
+
+`Reviewer:` quotes the `<one-line reason>` of the section 3 reply verbatim; the `probed:` half stays in the commit body; a prefiltered item carries `not reviewed - <the rule that prefiltered it>`. `Impact:` restates the design-contract shift from `location` in the reader's words, never quoted spec text, one clause per touched decision, `;`-joined; `(none) -> <new>` for a contract added, `<old> -> (removed)` for a contract removed. `Details` keeps the verbatim `old -> new`.
+
 `Alternatives:` appears only when genuine ones exist; otherwise the item's choices are exactly `accept` and `custom(...)`. Reply grammar: `1` applies every recommendation; `2:` overrides the named handles, omitted handles keep theirs, a handle at most once; `custom(<effect>)` is free text and may redirect anywhere ("keep the spec, fix the parser"). A redirect away from the spec drops the item (still recorded in the batch commit body as `custom(<effect>)`) and returns the finding to its calling loop. Invalid handle or choice -> reprompt for that item only, keep every valid pick, never reopen the gate. Take no action before the reply.
 
 ## 5. Apply, aftermath, commit
@@ -110,7 +115,7 @@ Called from `finishing-a-development-branch` Step 3.5, before the carried-open m
 1. Draft an item (step 1) for each gap with `recommended: accept`, verdict `DRIFTED` or `PARTIAL`, not `UNAUTHORIZED`, whose `origin` is not an acceptance criterion - the `accept-into-spec` edit built from its `origin` + `evidence`. Every other gap skips the funnel and stays a menu row.
 2. Review (step 3), apply and commit (step 5).
 3. Re-audit against the amended spec; regenerate the inventory. Only concerns the re-audit closed drop out; sibling concerns keep their rows.
-4. Render the disposition menu for what remains - escalated items are ordinary rows there, never a second menu. Rows whose recommended disposition edits the spec carry the readable card fields (`what`, `why`, `Example:`) on the bullet, adapted to the disposition bullet grammar. A human-selected spec-changing disposition (`accept-into-spec`, `rescope-into-spec`, state-changing `custom`) is already approved: it applies at the protocol's execute-order step 2, bypasses steps 2-4 of this surface, and is recorded as today (`Gn - <title>: <disposition>`); an auto-applied item is recorded `Gn - <title>: accept-into-spec (auto-applied)`.
+4. Render the disposition menu for what remains - escalated items are ordinary rows there, never a second menu. Rows whose recommended disposition edits the spec carry the readable card fields (`what`, `why`, `Example:`, `Reviewer:`, `Impact:`) on the bullet, adapted to the disposition bullet grammar. A human-selected spec-changing disposition (`accept-into-spec`, `rescope-into-spec`, state-changing `custom`) is already approved: it applies at the protocol's execute-order step 2, bypasses steps 2-4 of this surface, and is recorded as today (`Gn - <title>: <disposition>`); an auto-applied item is recorded `Gn - <title>: accept-into-spec (auto-applied)`.
 
 ## Worked example
 
@@ -130,19 +135,22 @@ Eight synthetic items modelled on one real run. Items 1-5 and 8 reach the review
 The reviewer clears items 1-5; nothing is applied yet. The batch renders items 6-8 (items 1-5 apply together with the accepted ones after the reply):
 
 ```
-Spec amendments: 3 need your call.
+Spec amendments: 3 need your call - from Task 7 BLOCKED; applying as recommended reopens Tasks 4, 6; no phase change.
 
 * scope - ROP feed out of scope: adds an out-of-scope line for the ROP feed to Non-goals. Drops a deliverable you approved.
   Example: regulator feed = NERC filings + ROP announcements -> NERC filings only
-  Impact: Task 4, Wave 2
+  Reviewer: not reviewed - removes approved scope
+  Impact: Non-goals: the ROP feed ships this release -> (removed)
   Recommended: accept (the ROP source has no stable page this release).
 * count - Fewer announcements per fetch: the acceptance criterion drops from at least 3 to at least 1. Lowers the bar you set.
   Example: 3 items per fetch -> 1
-  Impact: Task 6
+  Reviewer: not reviewed - acceptance-criteria location
+  Impact: Acceptance criteria: a fetch yields three or more announcements -> one or more
   Recommended: accept (the captured fixture has one item; the criterion assumed three).
-* bytes - Fixture byte count: the verification line changes from 41,208 to 43,117 bytes. No measurement was cited, so the reviewer could not confirm it.
+* bytes - Fixture byte count: the verification line changes from 41,208 to 43,117 bytes. The verification line would assert a size nobody measured.
   Example: 41,208 bytes -> 43,117 bytes
-  Impact: no plan yet
+  Reviewer: rubric (a) fails - no measurement cited for the new byte count
+  Impact: Verification: the fixture measures 41,208 bytes -> 43,117 bytes
   Recommended: alt-1 (measure first; apply whatever `wc -c` reports).
   Alternatives: alt-1 replace the number with the `wc -c` result
 

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

@@ -32,9 +32,11 @@ Then call `phase_tracker({ action: "start", phase: "ship" })`.
 
 ### Step 1: Verify Tests
 
-**Hard verification gate.** Tests/format/lint must pass before presenting any options — including Discard. The user's stated intent to throw the branch away does not change whether the diff is in a verifiable state; verifying first surfaces accidental damage to unrelated code before the branch is gone forever. No exceptions.
+**Hard verification gate.** Tests/format/lint must pass before presenting any options — including Discard. The user's stated intent to throw the branch away does not change whether the diff is in a verifiable state; verifying first surfaces accidental damage to unrelated code before the branch is gone forever. The skip rule below is the only exception.
 
-Run the project's canonical verification target in the worktree: `(cd "$WORKTREE" && <verification command>)`. The exact command lives in the repo's `AGENTS.md` or service-level docs (look for "verification", "CI", or "test" sections). Typical patterns: `make ci`, `npm test`, `pytest`, `cargo test`, `bundle exec rspec`. Cross-cutting changes: run each affected service's target; don't skip any.
+Run the plan header's `**Verification:**` set in the worktree: `(cd "$WORKTREE" && <command>)`. With no plan in this session, run the verification command(s) of the affected services from the gauntlet overrides file or `AGENTS.md` (look for "verification", "CI", or "test" sections).
+
+**Skip rule.** Skip the run when this set passed in the verify phase of this session and the tree is unchanged since apart from the telemetry record: `git -C "$WORKTREE" diff --quiet <commit the run passed on> HEAD -- . ':!<telemetry.dir>'` (`<telemetry.dir>` defaults to `.pi/gauntlet/telemetry`) exits 0 and no edit or write landed outside `<telemetry.dir>` since. Otherwise run it once. Unsure means run.
 
 **Scoping caveat — pre-existing findings.** Some services carry lint findings unrelated to the diff. If verification fails on lines you didn't touch:
 
@@ -48,7 +50,7 @@ Tests failing (<N> failures). Must fix before completing:
 
 [Show failures]
 
-Cannot proceed with Options 1–3 until tests pass.
+Cannot proceed until tests pass.
 ```
 
 Stop. Don't proceed to Step 2.
@@ -59,7 +61,7 @@ No documentation prompt here: Documentation impact is decided at spec time (`/sk
 
 ### Step 2: Detect Environment
 
-Detached HEAD (`git -C "$WORKTREE" symbolic-ref -q HEAD` prints nothing) -> reduced 3-option menu (no merge), no cleanup. Otherwise the standard 4 options.
+Detached HEAD (`git -C "$WORKTREE" symbolic-ref -q HEAD` prints nothing) -> reduced 4-option menu (no merge), no cleanup. Otherwise the standard 5 options.
 
 ### Step 3: Determine Base Branch
 
@@ -144,38 +146,42 @@ Amendments auto-applied (N):
 
 Omit the block when N = 0.
 
-**Normal repo and named-branch worktree — present exactly these 4 options:**
+**Normal repo and named-branch worktree — present exactly these 5 options:**
 
 ```
 Implementation complete. What would you like to do?
 
-1. Squash-merge to <base-branch> (no PR, no surviving branch)
-2. Push and create a Pull Request
-3. Keep the branch as-is (I'll handle it later)
-4. Discard this work
+1. Push and create a Pull Request
+2. Push and create a draft Pull Request
+3. Squash-merge to <base-branch> (no PR, no surviving branch)
+4. Keep the branch as-is (I'll handle it later)
+5. Discard this work
 
 Which option?
 ```
 
-**Detached HEAD — present exactly these 3 options:**
+**Detached HEAD — present exactly these 4 options:**
 
 ```
 Implementation complete. You're on a detached HEAD (externally managed workspace).
 
 1. Push as new branch and create a Pull Request
-2. Keep as-is (I'll handle it later)
-3. Discard this work
+2. Push as new branch and create a draft Pull Request
+3. Keep as-is (I'll handle it later)
+4. Discard this work
 
 Which option?
 ```
 
+Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Discard block.
+
 **Don't add explanation** - keep options concise.
 
 ### Step 5: Execute Choice
 
-#### Strip the plan, keep the record (Options 1 and 2)
+#### Strip the plan, keep the record (Options 1-3)
 
-Run this on the feature branch before either landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
+Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
 
 ```bash
 # Plans are ephemeral - if one was committed on this branch, remove it before landing.
@@ -190,27 +196,7 @@ node <bin>/gauntlet-telemetry-salvage.mjs --worktree "$WORKTREE" --base <base-br
 
 The salvage prints one line per spec on the branch (`present`, `present <path> (marked shipped)`, `restored <path> from <sha>`, `restored <path> from <sha> (marked shipped)`, `no telemetry run`, `never written`, `restore failed <path>: <reason>`) and always exits 0. `(marked shipped)` means the record was still `in_progress` with no ship phase (the recorder lost its binding) and the salvage committed `status: shipped` + `shipped_at` as one `telemetry:` commit; it rides the squash or push like any branch commit. Print its stdout verbatim in the ship completion message. A `restore failed` line is reported, never retried, and never blocks the ship - the record stays recoverable from the branch ref.
 
-#### Option 1: Squash-merge to base
-
-Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
-
-```bash
-git -C "$PRIMARY" checkout <base-branch>
-git -C "$PRIMARY" pull
-git -C "$PRIMARY" merge --squash "$FEATURE"
-git -C "$PRIMARY" commit -m "<imperative summary> (ref <ticket-id>)"
-(cd "$PRIMARY" && <Step 1 command for the service(s) touched>)
-```
-
-The plan was already removed on the branch, so the staged squash tree carries the spec, the telemetry record, and the implementation - never the plan.
-
-The post-squash re-verify is not optional - `git merge --squash` can surface conflict-resolution mistakes the worktree-side run couldn't catch.
-
-Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMARY" branch -D "$FEATURE"`.
-
-**No push. No PR.** The squashed commit stays local on `<base-branch>` unless the user explicitly asks to push.
-
-#### Option 2: Push and Create PR
+#### Option 1: Push and Create PR
 
 Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
 
@@ -231,7 +217,7 @@ EOF
 )")
 ```
 
-When the spec's `## Acceptance criteria` has at least one `venue:` or `deferred:` row, append this block after `## Test Plan`, listing those rows verbatim with their disposition, so the reader knows what `/skill:check-delivery` verifies after deploy and what a follow-up owns. With no such rows the body ends at `## Test Plan`, byte-identical to today. Option 1's squash commit message is unchanged.
+When the spec's `## Acceptance criteria` has at least one `venue:` or `deferred:` row, append this block after `## Test Plan`, listing those rows verbatim with their disposition, so the reader knows what `/skill:check-delivery` verifies after deploy and what a follow-up owns. With no such rows the body ends at `## Test Plan`, byte-identical to today. Option 3's squash commit message is unchanged.
 
 ```markdown
 ## Acceptance criteria
@@ -241,13 +227,37 @@ When the spec's `## Acceptance criteria` has at least one `venue:` or `deferred:
 
 **Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
 
-#### Option 3: Keep As-Is
+#### Option 2: Push and Create Draft PR
+
+Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then Option 1's push and `gh pr create` commands with `--draft` added. The PR body is unchanged. Do not clean up the worktree.
+
+#### Option 3: Squash-merge to base
+
+Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
+
+```bash
+git -C "$PRIMARY" checkout <base-branch>
+git -C "$PRIMARY" pull
+git -C "$PRIMARY" merge --squash "$FEATURE"
+git -C "$PRIMARY" commit -m "<imperative summary> (ref <ticket-id>)"
+(cd "$PRIMARY" && <the Step 1 set>)
+```
+
+The plan was already removed on the branch, so the staged squash tree carries the spec, the telemetry record, and the implementation - never the plan.
+
+The post-squash re-verify is not optional - `git merge --squash` can surface conflict-resolution mistakes the worktree-side run couldn't catch.
+
+Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMARY" branch -D "$FEATURE"`.
+
+**No push. No PR.** The squashed commit stays local on `<base-branch>` unless the user explicitly asks to push.
+
+#### Option 4: Keep As-Is
 
 Report: "Keeping branch <name>. Worktree preserved at <path>."
 
 **Don't cleanup worktree.**
 
-#### Option 4: Discard
+#### Option 5: Discard
 
 **Confirm first:**
 ```
@@ -265,7 +275,7 @@ If confirmed: Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `
 
 ### Step 6: Cleanup Workspace
 
-**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
+**Only runs for the Squash-merge and Discard options (3 and 5).** The PR, draft PR, and Keep options always preserve the worktree.
 
 **If the worktree was created by a project-native script** (e.g. `script/worktree create`, `bin/worktree`): defer to its destroy command, run against the primary: `"$PRIMARY/script/worktree" destroy "${WORKTREE##*/}"`.
 
@@ -284,10 +294,11 @@ Removal precedes branch deletion in both options; `git branch -d`/`-D` fails whi
 
 | Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan strip + record salvage |
 |---|---|---|---|---|---|
-| 1. Squash-merge locally | yes (squash) | - | - | yes (after Step 6 removal) | yes (guarded, on the branch before squash) |
-| 2. Create PR | - | yes | yes | - | yes (guarded, on the branch before push) |
-| 3. Keep as-is | - | - | yes | - | - |
-| 4. Discard | - | - | - | yes (force, after Step 6 removal) | - |
+| 1. Create PR | - | yes | yes | - | yes (guarded, on the branch before push) |
+| 2. Create draft PR | - | yes | yes | - | yes (guarded, on the branch before push) |
+| 3. Squash-merge locally | yes (squash) | - | - | yes (after Step 6 removal) | yes (guarded, on the branch before squash) |
+| 4. Keep as-is | - | - | yes | - | - |
+| 5. Discard | - | - | - | yes (force, after Step 6 removal) | - |
 
 A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branch.
 
@@ -295,15 +306,15 @@ A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branc
 
 **Skipping test verification**
 - **Problem:** Merge broken code, create failing PR
-- **Fix:** Always verify tests before offering options
+- **Fix:** Verify, or apply the Step 1 skip rule, before offering options
 
 **Open-ended questions**
 - **Problem:** "What should I do next?" is ambiguous
-- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
+- **Fix:** Present exactly 5 structured options (or 4 for detached HEAD)
 
-**Cleaning up worktree for Option 2**
+**Cleaning up worktree for a PR option (1 or 2)**
 - **Problem:** Remove worktree user needs for PR iteration
-- **Fix:** Only cleanup for Options 1 and 4
+- **Fix:** Only cleanup for the Squash-merge and Discard options (3 and 5)
 
 **Deleting branch before removing worktree**
 - **Problem:** `git branch -d` fails because worktree still references the branch
@@ -321,7 +332,7 @@ A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branc
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
 
-**Skipping the strip-and-salvage block in Options 1 and 2 (any path that lands on base)**
+**Skipping the strip-and-salvage block in Options 1-3 (any path that lands on base)**
 - **Problem:** Plan docs are ephemeral and shouldn't land on `<base-branch>`; the telemetry record is a deliverable and must. Skipping the block ships the plan, or drops the record the spec index reads.
 - **Fix:** Run the block on `$WORKTREE` before the squash or the push. The plan stays in the branch's git history (`git -C "$PRIMARY" log --all -- doc/plans/...`). Spec and telemetry record stay on `<base-branch>`; plan does not.
 
@@ -331,7 +342,7 @@ A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branc
 
 ## Completion
 
-Once the chosen option (Options 1, 2, or 3 — not Discard) is executed successfully, mark the ship phase complete:
+Once the chosen option (Options 1-4 — not Discard) is executed successfully, mark the ship phase complete:
 
 ```
 phase_tracker({ action: "complete", phase: "ship" })
@@ -350,16 +361,16 @@ Once the merge (and any deploy) has landed, `/skill:check-delivery <ticket-ref>`
 - Clean up worktrees you didn't create (provenance check)
 - Run any step without the `<worktree-path>` argument
 - Auto-proceed past an undispositioned carried-open gap
-- Skip the strip-and-salvage block before the Option 1 squash or the Option 2 push
+- Skip the strip-and-salvage block before the Option 3 squash or the Option 1/2 push
 - Delete the telemetry record (`.pi/gauntlet/telemetry/**` or the configured `telemetry.dir`) on any path
 
 **Always:**
-- Verify tests before offering options
+- Verify, or apply the Step 1 skip rule, before offering options
 - Print the `gauntlet-telemetry-salvage.mjs` output verbatim in the ship completion message
 - Derive `$PRIMARY` and `$FEATURE` from `<worktree-path>` before presenting the menu
-- Present exactly 4 options (or 3 for detached HEAD)
-- Get typed confirmation for Option 4
-- Clean up worktree for Options 1 & 4 only
+- Present exactly 5 options (or 4 for detached HEAD)
+- Get typed confirmation for Option 5 (Discard)
+- Clean up worktree for Options 3 & 5 (Squash-merge, Discard) only
 - Target `$PRIMARY` with `git -C` for merge, worktree removal, and branch deletion
 - Run `git -C "$PRIMARY" worktree prune` after removal
 - Surface the closure / conformance verdict as its own section before the options menu

package/skills/finishing-a-development-branch/reference/disposition-protocol.md

@@ -11,7 +11,7 @@ Each bullet:
 - `<handle>` leads the bullet and is a short unique human word derived from the title (`Cache coverage` -> `cache`); on collision append a digit. It is the token option 2 targets. When a gap split and no clean word fits, use the bare `Gn/Cn`; a single-concern gap uses its gap ID `Gn`.
 - The shared options line sits below the bullets: `Other options per item: fix-now / accept / rescope / follow-up / custom`, listing the options **generally available across items**. When a specific item's availability deviates - an option unavailable for it, or an `UNAUTHORIZED` item whose `rescope` is unavailable and whose `fix-now` means removal - note that deviation as a short parenthetical on **that item's bullet** (one clause, not a block), e.g. `(rescope N/A: scope creep)`. The shared line appears **only in the carried-open render**, never in the zero-gap path. Full per-option effects only on request, or when option 2 targets an unclear choice.
 - Group items under one recommended line only when they share a disposition and rationale; each grouped handle repeats its title.
-- A bullet whose recommendation edits the spec (`accept-into-spec`, `rescope-into-spec`, or an item the pre-menu funnel escalated) carries, indented under it, `what` and `why` as one sentence each and `Example: <before -> after>` - the readable card from `../../brainstorming/reference/amendment-surface.md`, adapted to this bullet. Escalated items are ordinary rows here; no second amendment menu renders.
+- A bullet whose recommendation edits the spec (`accept-into-spec`, `rescope-into-spec`, or an item the pre-menu funnel escalated) carries, indented under it, `what` and `why` as one sentence each, `Example: <before -> after>`, `Reviewer: <one-line reason verbatim | not reviewed - <the Conformance entry step 1 exclusion that kept it out> | reviewer unavailable: <reason>>`, and `Impact: <spec section>: <approved contract> -> <new contract>; ...` - the readable card from `../../brainstorming/reference/amendment-surface.md`, adapted to this bullet. Escalated items are ordinary rows here; no second amendment menu renders.
 - Availability per concern comes from the reference's single availability table - apply it against current context (worktree state, `maxFixRounds`, ownership, resource accessibility), do not restate it. `UNAUTHORIZED` bullets ask the reference's question verbatim (`Should this unrequested behavior become part of the current workflow?`); `rescope-into-spec` is shown **unavailable** (not dropped) and `fix-now` means **removal** of the unrequested code.
 - `revert conformance fix Gn`, when the gap has an auto-applied fix, renders on the shared options line as a **separate one-off action** - never inside a bullet's recommendation and never in the option-2 list. Name the parent gap and warn that revert undoes the entire gap-level commit (see "Revert semantics").
 

package/skills/subagent-driven-development/SKILL.md

@@ -224,7 +224,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 2. **Whole-diff code review.** Only after passing full verification, dispatch one foreground whole-diff `code-reviewer` per `/skill:requesting-code-review` against that committed HEAD, with `SCOPED_TEST_COMMANDS: none`; the reviewer does not repeat the full suite. Address Critical and Moderate findings. Before dispatching a review repair, reopen (`in_progress`) every existing plan-task index whose `Files:` ownership includes its touched files; leave unowned cross-cutting repair work in the review report. Mark each reopened index `complete` only once the repair is re-verified and the re-review accepts it — this is the same completion point step 1's reopened indices wait for, not an extra gate, and the gate order stays full verification -> whole-diff CR -> conformance. Any repair invalidates prior full verification, so rerun the full set successfully before the next gate.
 3. **Close the loop — conformance check.** The review in step 2 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-2 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop reuses durable `Gn` gap indices as defined in conformance-check.md; it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; on escalation, do not complete verify, stop and report.
 4. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the two-line sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.
-5. **Proceed to finishing — no confirmation prompt.** Once verify is complete per step 3's criterion, invoke `/skill:finishing-a-development-branch <abs worktree path>` immediately - the same absolute path every dispatch in this flow carried as `cwd`; finishing stops without it. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Carried-open concerns are resolved there per concern via the `## Closure / conformance` block from step 4. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
+5. **Proceed to finishing — no confirmation prompt.** Once verify is complete per step 3's criterion, invoke `/skill:finishing-a-development-branch <abs worktree path>` immediately - the same absolute path every dispatch in this flow carried as `cwd`; finishing stops without it. Its Step 4 menu (PR / draft PR / squash / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Carried-open concerns are resolved there per concern via the `## Closure / conformance` block from step 4. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
 
 ## Red Flags — STOP
 

package/skills/writing-plans/SKILL.md

@@ -154,7 +154,7 @@ Each step is **one action, 2-5 minutes**:
 
 **Spec:** `<project>/doc/specs/<same-filename-as-this-plan>.md`
 
-**Verification:** `<full verification command set — tests + style + format; a single bundling entrypoint, or the listed individual commands; from the recon report / project overrides>`
+**Verification:** `<full verification command set — tests + style + format; a single bundling entrypoint, or the listed individual commands; from the recon report / project overrides>` - in a repo with per-service verification commands, list the command of every service the change affects (its own files or code it depends on; a repo-wide shared path such as root config, a lockfile, or a shared library affects every dependent service), taking the per-service commands from the overrides file or AGENTS.md when recon reports a single entrypoint
 
 **Ticket:** `<ticket-id>` (omit if none)