pi-gauntlet 5.16.3 → 5.17.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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`.

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.3",
+  "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/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/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)