pi-gauntlet 8.4.9 → 8.4.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v8.4.11 - 2026-11-12
+
+- Loop interrupted returns recover unconditionally as one failed attempt under either approval option: job identity checks fence signals, not reset or repair. Pending companion and resumed returns share the same recovery; only a dirty tree with no pending dispatch asks for discard. Git recovery failures consume the existing allowance rather than opening a new stop.
+- Spec approval authorizes every named paid or external action for the whole flow without count-based stops or spend accounting. Workers reuse action output for local rechecks; missing prerequisites and unnamed actions still report `unreachable:`. Option 5 also continues rows reopened during verify within their remaining allowance, without a second authorization; option 4 keeps its authorize-or-stop ask.
+- pi-cohort peer floor raised to 8.0.0.
+
+## v8.4.10 - 2026-11-12
+
+- Draft-PR handoff cleanup checks live remote equality before removing owned trees and conditionally deleting local branches at the pinned commit. Guarded wrappers can delete branches; host-owned, mismatched and failed cleanups report the state read back.
+- Coordinated brainstorms record portable script/native creation and destruction commands without inventing a `home:` path. Keyed and built-in creators retain `home:`, pre-existing host-owned trees retain ownership, and companion lookup uses the recorded branch with checkout identity validation.
+- pi-cohort peer floor raised to 7.7.5.
+
 ## v8.4.9 - 2026-11-11
 
 - Gatekeep-pr uses action, final and post menus with the judged recommendation on row 1. Its plain-language report describes the change and scope, explains standing and problems, then recommends a choice; detailed evidence stays behind `show evidence`.
@@ -52,7 +64,7 @@
 
 ## v8.3.0 - 2026-11-06
 
-- Loop execution uses the ledger allowance for interrupted child and seed recovery, exit-verification repairs and grant-funded conformance rounds. Recovery requires checkout ownership and confirmed job exit; stagnation supplies a row-local hint rather than stopping early. Unreachable target failures become audited scope cuts under amend permission, while exhausted named-action bounds still stop. Loop workers bound blocking calls and track longer jobs in isolated POSIX sessions; design approval authorizes named paid or external actions only within their flow-wide bounds.
+- Loop execution uses the ledger allowance for interrupted child and seed recovery, exit-verification repairs and grant-funded conformance rounds. Recovery requires checkout ownership and confirmed job exit; stagnation supplies a row-local hint rather than stopping early. Unreachable target failures become audited scope cuts under amend permission, while exhausted named-action bounds still stop. Loop workers bound blocking calls and track longer jobs in isolated POSIX sessions; design approval authorizes named paid or external actions only within their flow-wide bounds. The Unreleased changes remove this recovery proof and these named-action bounds.
 
 ## v8.2.1 - 2026-11-06
 

package/README.md

@@ -36,10 +36,28 @@ pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a r
 Concretely, one change through the gauntlet:
 
 0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create one tracker issue or repair a comma/whitespace list of issue refs - shaping each into a Context/Problem/Idea/Acceptance Criteria ticket, grounded by a repository audit, an AC integrity check, and a cheap council roast. Repair finishes preparation for all tickets before presenting exact-diff confirmations sequentially in ref order; each approval writes that ticket before the next gate, and may include one optional gated comment for a Reporter note or overlap evidence. The audit checks factual claims, Idea fit, AC mechanisms against cited repo guidance, and already-stated observable legs in configured sibling checkouts. It reports in-motion work and attempts a best-effort scenario through authorized current-system reads, without promising reproduction or a fix; missing access or nothing to observe is reported, not a new approval gate. Implementer detail moves into the gated Reporter note; brainstorming reads that note with the ticket so the spec retains the detail. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. The agent may start it on its own when the ask is "file a ticket" or another skill routes there; the write still waits for your yes on the presented diff. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket, brainstorming, or a bounded hotfix - before any spec exists.
-1. Opt in with `/skill:brainstorming` and describe the change. The command is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. An ordinary implementation request or an agent recommendation is not consent. A leading run of GitHub references (`#N`, `owner/repo#N`, or a `/pull/N` or `/issues/N` URL), separated by whitespace or commas, resolves each reference as a PR first: related open, same-repository, non-fork PRs on one base form one rework subject, including drafts. Admission runs in listed order and relatedness is checked before provisioning; the first retained PR is home, whose existing branch rebases onto the fetched PR base by default, then member commits replay onto it in listed order. The first intent word `merge-forward` opts out and keeps the merge path. An unresolved conflict after its scoped helper aborts that step and continues to the spec with the repair as Task 1. A single non-PR reference follows the ticket path. The first non-reference token starts intent text; mid-sentence references and other ticket/free-text subjects keep their existing paths. The combined code, PR-carried specs, claims, and review threads are the brainstorm input, with each PR's provenance retained; only home's bound ticket supplies acceptance criteria, while member tickets supply context. A single PR retains the same rework path without member replays or a close offer. The combined state is judged against constraints from the fetched current base HEAD, not the fork point or the PRs' proposed policy edits; see the [PR-subject contract](skills/brainstorming/reference/pr-subject.md) and [PR-head worktree owner](skills/using-git-worktrees/reference/pr-head.md). **`brainstorming`** sets up an isolated worktree (on the existing branch for PR rework), explores the codebase, and turns the subject into a written spec - when its recon finds a cited case that the ask is the wrong change (misdiagnosed, wrong-sized, already solved, a band-aid, or cutting across a sound pattern - including a repo convention that is itself debt) and can name the alternative, question one is a framing question (`as framed`, `pivot: <alternative>`, or `smaller or none`); otherwise it opens with one sentence naming what it checked, and every approach it proposes ends with a `Pattern:` line naming what it follows or cuts across; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`, `elsewhere:` for a row another repo's part delivers), scope cuts come only from your answer to a cut question and are listed at the gate, the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows before the prod deploy. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; candidates come from brainstorming's scout recon, never a mechanical sweep). **You read and approve the spec - human gate 1.** Options 1/2/4/5 approve and pick an engine; option 6 approves the content only: it writes `**Engine:** deferred` under `**Amend-grant:** none`, pushes the branch, opens a draft PR carrying just the spec, prints the URL, and ends the flow - no plan, no loop, no handoff brief. For a coordinated spec, it first pushes every companion branch to origin, then opens one home draft PR; it creates no companion PRs. A later `brainstorming #N` reconstructs the recorded companions from their origin branches before re-presenting the implementation gate; the [publication and re-gate owner](skills/brainstorming/reference/spec-pr.md) defines all-member preflight, recovery, and cleanup. The branch stays; a gauntlet-owned worktree is removed, a host-owned checkout is reported and left. Option 6 is withheld on a PR subject (`Withheld: draft PR - #N already exists`) and when the branch's diff against the default branch is not spec-only. A later `brainstorming #N` on that PR classifies it from the diff alone: one added spec carrying the marker plus banner-only predecessor edits re-presents the gate with 1/2/4/5 (3 only when the spec commit carries a council audit) and skips gather, questionary, council, and scout; a spec-only diff without the marker prints `spec-only PR without the gate marker - running lint and council` and takes the normal brainstorm path with the carried spec as the draft; any other diff takes the rework path. Approval at that re-gate writes `**Engine:**`, `**Amend-grant:**`, and `**PR:** <owner/repo#N>` as a new commit on the PR branch and chains into planning or the loop as usual. Before approval, PR rework's sole write/run exception outside the spec directories permits only the base sync (rebase or merge), each member replay or merge, their conflict helpers' edits to the conflicted files, and their scoped conflict tests; other subjects have no implementation code yet.
-2. By default, **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files. Experimental approval options 4/5 instead select **`loop-implementation`**: the plan phase is skipped and a stamped acceptance-criteria ledger replaces the task plan. Option 4 retains amendment review; option 5 auto-applies amends, including unreachable-row cuts, and funds conformance rounds up to the allowance when the cap blocks. Redraws, exhausted bounds and unproven recovery still stop. See [Loop engine operations](doc/configuration.md#loop-engine-operations).
+1. Opt in with `/skill:brainstorming` and describe the change. The command is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. An ordinary implementation request or an agent recommendation is not consent. A leading run of GitHub references (`#N`, `owner/repo#N`, or a `/pull/N` or `/issues/N` URL), separated by whitespace or commas, resolves each reference as a PR first: related open, same-repository, non-fork PRs on one base form one rework subject, including drafts. Admission runs in listed order and relatedness is checked before provisioning; the first retained PR is home, whose existing branch rebases onto the fetched PR base by default, then member commits replay onto it in listed order. The first intent word `merge-forward` opts out and keeps the merge path. An unresolved conflict after its scoped helper aborts that step and continues to the spec with the repair as Task 1. A single non-PR reference follows the ticket path. The first non-reference token starts intent text; mid-sentence references and other ticket/free-text subjects keep their existing paths. The combined code, PR-carried specs, claims, and review threads are the brainstorm input, with each PR's provenance retained; only home's bound ticket supplies acceptance criteria, while member tickets supply context. A single PR retains the same rework path without member replays or a close offer. The combined state is judged against constraints from the fetched current base HEAD, not the fork point or the PRs' proposed policy edits; see the [PR-subject contract](skills/brainstorming/reference/pr-subject.md) and [PR-head worktree owner](skills/using-git-worktrees/reference/pr-head.md). **`brainstorming`** sets up an isolated worktree (on the existing branch for PR rework), explores the codebase, and turns the subject into a written spec - when its recon finds a cited case that the ask is the wrong change (misdiagnosed, wrong-sized, already solved, a band-aid, or cutting across a sound pattern - including a repo convention that is itself debt) and can name the alternative, question one is a framing question (`as framed`, `pivot: <alternative>`, or `smaller or none`); otherwise it opens with one sentence naming what it checked, and every approach it proposes ends with a `Pattern:` line naming what it follows or cuts across; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`, `elsewhere:` for a row another repo's part delivers), scope cuts come only from your answer to a cut question and are listed at the gate, the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows before the prod deploy. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; candidates come from brainstorming's scout recon, never a mechanical sweep). **You read and approve the spec - human gate 1.** Options 1/2/4/5 approve and pick an engine; option 6 approves the content only: it writes `**Engine:** deferred` under `**Amend-grant:** none`, pushes the branch, opens a draft PR carrying just the spec, prints the URL, and ends the flow - no plan, no loop, no handoff brief. For a coordinated spec, it first pushes every companion branch to origin, then opens one home draft PR; it creates no companion PRs. A later `brainstorming #N` reconstructs the recorded companions from their origin branches before re-presenting the implementation gate; the [publication and re-gate owner](skills/brainstorming/reference/spec-pr.md) defines all-member preflight, recovery, and cleanup. After confirming the live remote and local branch match the worktree commit, cleanup removes an owned tree and conditionally deletes the local branch at that pinned commit. A host-owned checkout or failed remote check keeps tree and branch, with a per-repo reason. Option 6 is withheld on a PR subject (`Withheld: draft PR - #N already exists`) and when the branch's diff against the default branch is not spec-only. A later `brainstorming #N` on that PR classifies it from the diff alone: one added spec carrying the marker plus banner-only predecessor edits re-presents the gate with 1/2/4/5 (3 only when the spec commit carries a council audit) and skips gather, questionary, council, and scout; a spec-only diff without the marker prints `spec-only PR without the gate marker - running lint and council` and takes the normal brainstorm path with the carried spec as the draft; any other diff takes the rework path. Approval at that re-gate writes `**Engine:**`, `**Amend-grant:**`, and `**PR:** <owner/repo#N>` as a new commit on the PR branch and chains into planning or the loop as usual. Before approval, PR rework's sole write/run exception outside the spec directories permits only the base sync (rebase or merge), each member replay or merge, their conflict helpers' edits to the conflicted files, and their scoped conflict tests; other subjects have no implementation code yet.
+2. By default, **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files. Experimental approval options 4/5 instead select **`loop-implementation`**: the plan phase is skipped and a stamped acceptance-criteria ledger replaces the task plan. Option 4 retains amendment review; option 5 auto-applies amends, including unreachable-row cuts, and funds conformance rounds up to the allowance when the cap blocks. Redraws and exhausted attempt or repair allowances still stop; an interrupted return recovers without a human turn under either option. See [Loop engine operations](doc/configuration.md#loop-engine-operations).
 3. **`subagent-driven-development`** executes the plan in waves, with task implementers followed by one integrated `wave-reviewer` after the scoped test gate passes. The reviewer checks anchored spec clauses and code quality together; repairs stay on the current tree and pass the same gate before re-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.
-The loop alternative to step 3 runs one fresh `loop-implementer` per seed or row iteration, without implement-phase reviewers. Each row starts with the shared allowance (default 4); approval replies such as `4; allowance 6` override it for one run. Under either loop approval option, attempt `escalateAfter + 1` (default 4), clamped to the last allowed attempt, escalates once per row on `escalationLoop.implModel` (the main-loop model when unset); later attempts use the ordinary worker model. The allowance also bounds seed and exit-verification repair counts; verification repairs use the same escalation model and count home repair commits plus an unmatched `pending: verify` reservation. Stagnation supplies a row-local hint, not an early stop. Interrupted returns spend attempts after ownership-fenced recovery: the driver confirms owned jobs exited before resetting the checkout; unknown ownership or failed cleanup requires a human decision. An admitted `unreachable:` target failure becomes an audited scope cut under amend permission, never a passing row. At a row stop, `retry <n> | <hint>` adds one attempt to that row, while `rows +N` raises every row's allowance. Attempts never reset and there is no total iteration cap. Ledger refresh completes implement when every row is closed; verify step 1 runs the gate set: deduplicated (owning checkout, command) pairs from done rows' recorded checks, with ownership from the ledger. Gate output goes to logs; the driver keeps exit codes and paths, not test output. CI on push owns the full run.
+The loop alternative to step 3 runs one fresh `loop-implementer` per seed or row iteration, without implement-phase reviewers. Each row starts with the shared allowance (default 4); approval replies such as `4; allowance 6` override it for one run. Under either loop approval option, attempt `escalateAfter + 1` (default 4), clamped to the last allowed attempt, escalates once per row on `escalationLoop.implModel` (the main-loop model when unset); later attempts use the ordinary worker model. The allowance also bounds seed and exit-verification repair counts; verification repairs use the same escalation model and count home repair commits plus an unmatched `pending: verify` reservation. Stagnation supplies a row-local hint, not an early stop. An interrupted return is one failed attempt: recovery is unconditional under either option, before checking allowance. The driver signals only identity-matching jobs, skips absent or mismatched jobs, deletes the jobs file, resets to the saved pre-dispatch HEAD and runs `clean -fd`, then restores the saved ledger and commits the failed attempt. Continue recovery even with a surviving job or remaining dirt. Wrong HEAD or an unwritten repair repeats reset and repair, counting each pass against the same allowance until the repair lands on the saved HEAD or the existing exhaustion stop fires. With no pending dispatch, a dirty entry or restored tree instead lists paths and asks for typed `discard` or Stop only; discard resets to HEAD, cleans and resumes the suspended entry or restore sequence before dispatch or verification. An admitted `unreachable:` target failure becomes an audited scope cut under amend permission, never a passing row. At a row stop, `retry <n> | <hint>` adds one attempt to that row, while `rows +N` raises every row's allowance. Attempts never reset and there is no total iteration cap. Ledger refresh completes implement when every row is closed; verify step 1 runs the gate set: deduplicated (owning checkout, command) pairs from done rows' recorded checks, with ownership from the ledger. Gate output goes to logs; the driver keeps exit codes and paths, not test output. CI on push owns the full run.
+
+Approval authorizes every paid or external action named in an AC or Design, with its runner and inputs, for the whole flow. A count or wording deferring it to later approval does not withhold authorization. The worker runs it whenever an attempt needs it without asking and reuses its output for local rechecks; evidence commands name local replay or fixtures. Missing prerequisites and unnamed actions still fail as `unreachable:`.
+
+These are the loop stops this recovery and authorization contract keeps or touches, not the driver's whole stop set. Missing capabilities or references, malformed grants, unresolved verification entrypoints, repeated-evidence amendment handling and failed refresh guards retain their own text. The driver renders only stops named in its skill and references; another failed dispatch consumes an attempt, not an invented menu or approval.
+
+| Stop | Option 4 | Option 5 |
+|---|---|---|
+| Row attempts reach effective allowance; seed repairs reach allowance; escalation model unavailable for a row's escalated round | Retry, `rows +N`, amend, stop | Same |
+| Verification repairs reach allowance; escalation model unavailable for a verification repair | Amend, stop | Same |
+| Conformance fix-round cap | Stops at cap | Funds up to allowance, then stops |
+| Spec amendment, including an `unreachable:` cut | Reviewer applies evidence-backed factual corrections; other amendments stop for review | Applies with no human turn |
+| Row reopened by an applied amendment during verify | Authorize the row's return, or stop | Runs within remaining row allowance, with verify active, then reruns step 1 |
+| A redraw | Stops | Stops |
+| Run cannot start: missing `checks:`, neither `allowance:` nor legacy `cap:`, unavailable settings tool, or seed `plan_check` findings | Stops | Stops |
+| Dirty tree with no dispatch pending; on resume, admission question or missing-history stops (unrecoverable pre-dispatch ledger/tuple, or unreadable child attribution with no tuple) | Stops | Stops |
+| Dispatch returns an async handle despite `async: false` | Stops | Stops |
+
+A budget reply does not supply a missing escalation model. A reopened row already at allowance takes the row stop under either option; option 5 keeps verify active without a phase reset. Resume's admission question lists commits and dirt and explains that answering `interrupted` discards them through reset to the pre-dispatch HEAD and `clean -fd`. See [loop stop boundaries](doc/configuration.md#loop-stop-boundaries) for the reply and continuation details.
 
 4. **verify**: the parent first runs the plan's full verification command set for waves, or the ledger gate set for loop; only a passing result permits whole-diff code review, then the **conformance gate**. A review fix invalidates that result, so the parent reruns the same set before the next review or conformance gate. Loop conformance repairs and finish also use the gate set, never the ledger's full `verification:` command. When the overrides file declares a happy path for the touched paths (see [Project-specific overrides](#project-specific-overrides)), the parent runs it once here, between code review and the conformance gate, and the reviewer reads its transcript as runtime evidence - a hang or a failed request shows up in the audit with the transcript quoted - as a gap when an origin clause ties to it, otherwise as a `happy-path: failed - unattributable` line - never as a silent green. 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 numbered decision brief - one item per decision, the problem in plain words first, lettered options each with a one-line consequence, and `Recommended: <letter> - <reason>` or `No recommendation - pick one`. Reply with one line per item (`1. B`), or bare `1` to take every recommendation (no-recommendation items are re-asked by number); a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
 5. **`finishing-a-development-branch`**: PR, draft PR, squash, keep, or discard; PR rework's row 1 offers a lease push of the rebased home branch to the existing PR (`Base:` records in `merge:` form push non-force). A spec whose header carries `**PR:**` (approved at a spec-PR re-gate) and no `## Rework record` replaces the two create rows with `Push to PR #N and mark it ready for review` and `Push to PR #N, keep it a draft` (`Push to PR #N (already ready for review)` when the PR is already ready): both push without force after strip-and-seal, the first then runs `gh pr ready`, neither rewrites the PR body, and both are withheld when origin's branch head is no longer an ancestor of local HEAD. For coordinated specs, these [header-linked rows 1/2](skills/finishing-a-development-branch/reference/spec-pr.md#push-rows-12) deliver companions in recorded order before one home seal carrying every companion PR URL, then push home and apply its readiness choice. Row 1 makes companion drafts ready too; row 2 creates drafts but never converts an already-ready PR back to draft. Companion URLs appear in the shipped summary, companions first and home last, not in the unchanged home PR body; keep that summary for cross-repo review because successful home delivery removes receipts. A spec still carrying `**Engine:** deferred` stops finishing (and `gauntlet-resume`) with `spec approved for handoff only - run brainstorming #N` before any phase change, verification, or push. The PR-rework push appends a `## Rework` block naming absorbed PRs while retaining the original description bytes; the header-linked `**PR:**` push leaves the body untouched. Only after a successful rework push and home-description edit does one gated confirmation show the exact close comments and eligible member targets, linking home; declining or any other finish option leaves members open. Closing never deletes member branches, and finish posts no review-thread replies. Its `Before:` handle includes the full portable pre-rework SHA and the local `refs/gauntlet/pre-rework/pr-<N>` ref in the rework checkout. The [finishing owner](skills/finishing-a-development-branch/SKILL.md#pr-subject-row-1-push-to-the-pr-branch) defines the landing and body-update contract. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it before merging - it judges the diff against the spec at the PR's head (the acceptance-criteria dispositions and Design you approved; the PR description when no spec applies) - rows the spec defers or deviates are settled, every other row needs its mechanism (code, tests, docs) - and against the rubric; whatever can be seen only after merge is left to step 6. **Human gate 2** - the only other decision you make.
@@ -71,17 +89,17 @@ In create mode, `shape-ticket` runs one bounded overlap check after clarificatio
 
 Use `/skill:shape-ticket --skip-overlap <ask>` to bypass discovery explicitly. Repair mode never discovers candidates. Bypass still retains source reads, known conflicts, integrity checks, roast, approval, and source revalidation. Incomplete search coverage is disclosed, not treated as proof of no overlap; independent sessions can still race, so this is not a uniqueness guarantee.
 
-Between gate 1 and gate 2, both engines take named authorized recommendations under the spec's amend grant and run one bounded escalated execution round before eligible stops; budgets, cap, stagnation, boundary failures and redraws still stop, and budget-only grants supply no amend permission. Planning takes concrete baseline `narrow` or `amend` recommendations under that permission; `fix-first` enters ticket shaping's own gate. An implementer-evidenced text correction to a drafted AC is an amendment, not a redraw; ticket rows, row add/remove and problem or component boundary changes still require redraw approval. See [execution continuation](doc/implement-engines.md#stops-models-and-telemetry). Once gate 1 picks an engine, task breakdown, implementation and reviews proceed within those limits; option 6 parks the approved spec in a draft PR and planning starts only when someone runs `brainstorming #N` on it and approves at the re-gate. Changing an approved spec later goes through brainstorming's `Amending an approved spec`: a fresh-context reviewer clears evidence-backed factual corrections on its own, escalations reach you as one readable batch, and only a redraw is a full stop - not a third numbered gate. That's the mechanism. What follows is the machinery behind it.
+Between gate 1 and gate 2, both engines take named authorized recommendations under the spec's amend grant and run one bounded escalated execution round before eligible stops; exhausted allowances, cap and admission failures, waves stagnation and redraws still stop, and budget-only grants supply no amend permission. Planning takes concrete baseline `narrow` or `amend` recommendations under that permission; `fix-first` enters ticket shaping's own gate. An implementer-evidenced text correction to a drafted AC is an amendment, not a redraw; ticket rows, row add/remove and problem or component boundary changes still require redraw approval. See [execution continuation](doc/implement-engines.md#stops-models-and-telemetry). Once gate 1 picks an engine, task breakdown, implementation and reviews proceed within those limits; option 6 parks the approved spec in a draft PR and planning starts only when someone runs `brainstorming #N` on it and approves at the re-gate. Changing an approved spec later goes through brainstorming's `Amending an approved spec`: a fresh-context reviewer clears evidence-backed factual corrections on its own, escalations reach you as one readable batch, and only a redraw is a full stop - not a third numbered gate. That's the mechanism. What follows is the machinery behind it.
 
 ### Multi-repo runs
 
-A run has one home repository and one leg per selected repository. The home's `## shape-ticket` `- sibling:` declarations define eligible companions, not automatic membership: the ask must select a declared companion by repo identifier, the declared clone URL's `NAME`, or the URL itself, or the ticket must select it through a matching repo-group heading. Unselected siblings are not resolved. Members are ordered home first, then selected siblings in declaration order. Every member gets its own worktree with the same full branch and derived worktree name.
+A run has one home repository and one leg per selected repository. The home's `## shape-ticket` `- sibling:` declarations define eligible companions, not automatic membership: the ask must select a declared companion by repo identifier, the declared clone URL's `NAME`, or the URL itself, or the ticket must select it through a matching repo-group heading. Unselected siblings are not resolved. Members are ordered home first, then selected siblings in declaration order. Every member gets its own worktree with the same full branch and shared creation NAME (branch with `/` replaced by `-`); a script or native tool can choose a different folder name.
 
-The approved home spec records `## Legs`, including each leg's scope, rules and resolved `contract:`. Each companion commits a leg file with the same filename in its own spec directory, carrying the home pointer, Problem, binding decisions and its own leg block. Plan and ledger stay home-owned; task `Leg:` selects the checkout for implementation and review. Committed artifacts use portable repo identifiers, not machine-local paths. See the [membership and artifact contract](skills/brainstorming/reference/legs.md).
+The approved home spec records `## Legs`, including each leg's scope, rules and resolved `contract:`. Keyed and built-in creators retain `home:`; flow-created script/native trees record portable `create:` and `destroy:` without `home:`, and a pre-existing host-owned tree without a keyed contract records neither `home:` nor `destroy:`. Script creation passes the shared NAME and explicit branch, while destruction uses the located folder's basename. Companion lookup selects the unique linked tree on the recorded branch and validates its checkout identity, rather than computing its location from `home:`. Each companion commits a leg file with the same filename in its own spec directory, carrying the home pointer, Problem, binding decisions and its own leg block. Plan and ledger stay home-owned; task `Leg:` selects the checkout for implementation and review. Committed artifacts use portable repo identifiers, not machine-local paths. See the [membership and artifact contract](skills/brainstorming/reference/legs.md).
 
 Home overrides and settings govern flow policy. Each leg's own overrides and settings govern checkout operations, directories and verification; absent configuration uses defaults. Recorded `contract:` lines are authoritative for every spec with `## Legs`, including one-member runs: amend the home block and affected companion file before using a changed contract. Finish does not replace them by rereading overrides. Legacy specs without `## Legs` are home-only and retain the finish-time reread.
 
-Option 6's draft-PR handle is one home draft PR plus companion branches on origin, with no brief, companion PRs or receipts. `brainstorming #N` preflights every recorded companion before provisioning them from origin and re-gating under the [publication and re-gate contract](skills/brainstorming/reference/spec-pr.md). This extends the [spec-only draft-PR design](doc/specs/2026-10-28-spec-only-draft-pr.md) without superseding it; PR lists still take the rework path. The separate `gauntlet-handoff` / `gauntlet-resume` route carries every member in the brief's `legs:` block. Resume starts only from the home primary, validates companion repository, branch and home pointer, and announces per-leg HEAD and dirty drift. On that route a missing companion worktree requires a live-validated completion receipt; draft-PR re-entry instead uses the published origin branch. The [brief contract](skills/gauntlet-resume/reference/brief-contract.md#coordinated-brief-grammar) owns the brief grammar and admission rules.
+Option 6's draft-PR handle is one home draft PR plus companion branches on origin, with no brief, companion PRs or receipts. `brainstorming #N` preflights every recorded companion before provisioning them from origin and re-gating under the [publication and re-gate contract](skills/brainstorming/reference/spec-pr.md). Cleanup runs companions first, then home, removing owned trees and deleting local branches only after a live remote equality check and confirmed removal; each leg reports its read-back state even when another cleanup fails. This supersedes the kept-local-branch cleanup in the [spec-only draft-PR design](doc/specs/2026-10-28-spec-only-draft-pr.md); a remote branch deleted after handoff now needs restoration from a clone that still has it, not the cleaned-up machine. PR lists still take the rework path. The separate `gauntlet-handoff` / `gauntlet-resume` route carries every member in the brief's `legs:` block. Resume starts only from the home primary, validates companion repository, branch and home pointer, and announces per-leg HEAD and dirty drift. On that route a missing companion worktree requires a live-validated completion receipt; draft-PR re-entry instead uses the published origin branch. The [brief contract](skills/gauntlet-resume/reference/brief-contract.md#coordinated-brief-grammar) owns the brief grammar and admission rules.
 
 One finish choice spans all legs. PR, draft PR and squash deliver companions in declaration order, then seal and deliver home; keep preserves all legs, and discard lists all legs before one confirmation. Verification and conformance run per leg; home's passing tests do not credit companions. Delivery failure stops without rollback and reports shipped and unshipped legs. A retry from the brief validates home-owned receipts and skips only proven deliveries; stale PR heads are updated, and failed post-squash verification reruns without another squash. See the [delivery and recovery contract](skills/finishing-a-development-branch/reference/legs.md).
 
@@ -148,7 +166,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) >= 1.5.0 - supports model-only tracker exposure and sequential tracker execution, so updates persist as transcript tool results rather than nested calls.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.7.4 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 8.0.0 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both. At each pi-gauntlet release, set the pi-cohort peer minimum and README floor together to the newest released pi-cohort version; `/skill:release` checks the registry before proceeding.
 

package/agents/loop-implementer.md

@@ -17,7 +17,7 @@ Append one decision line per changed row to the ledger's `## Decisions` section
 
 `row <n> <done|failed> | <one sentence: what was done> | <one sentence: reusable artifacts for done, retry guidance for failed>`
 
-For `done`, name what later rows can build on (a file, helper, interface or fixture) and how to reuse it; write `nothing new to build on` when the row added no reusable artifact, including an extra closed by a check without further edits. For `failed`, state what the next iteration should not redo or should try differently. Limit each sentence to 200 characters. Put action accounting inside the first sentence, not in a third slot. Use the seed contract below for `target: seed`.
+For `done`, name what later rows can build on (a file, helper, interface or fixture) and how to reuse it; write `nothing new to build on` when the row added no reusable artifact, including an extra closed by a check without further edits. For `failed`, state what the next iteration should not redo or should try differently. Limit each sentence to 200 characters. Use the seed contract below for `target: seed`.
 
 ## Inputs
 
@@ -31,13 +31,12 @@ Read additive inputs `Leg:`, `Rules:`, mapped original AC and, for companions, e
 2. Close the `target` row first. Read every `row <n> ...` line for the target row from `## Decisions`, oldest first, before choosing an approach. Treat them as ordered guidance: avoid what a `failed` line's third slot says not to redo, follow what it says to try differently, and never repeat an approach a prior line of this row rules out. Exclude other rows' lines from guidance for this target. Read `retry` and `escalated` lines in the same pass: use the retry hint as guidance; treat the escalation marker as historical evidence that escalation is spent, and never infer the current attempt's model from it. Keep `previous decision` as the latest admitted target line and the tie-break for most recent. Use `previous decision` and `hint` to avoid repeating work and to try a different approach; keep the target unchanged.
 3. Run `git diff --stat <base>`. Open full diff hunks only for files the row being worked on touches, using `git diff <base> -- <row files>`; read the relevant code before editing it.
 4. Implement the target row using Three-scenario TDD and Test economy below. Apply step 5's action authorization before running a check. Treat empty evidence on an unreached row as a normal state after partial seeding, not a seed failure; create its first check before implementing it, then close or fail the row with command-first evidence under step 5. Run only its targeted check under Evidence command, never the owning checkout's full verification command or the full suite.
-5. Before replacing an evidence cell, repeat each carried `ran <action> (<k> of <bound>)` and `bound spent: <action> ...` record verbatim in that row's own decision sentence before any new spend, including records from a successful seed; retain their ordinals and count copies only once. Treat a dropped record as a validation miss even when the replacement check passes. Update the target row's mutable cells: set `status` to `done` on a passing check or `failed` on a failing check, increment `attempts` by 1, and set `evidence` to one physical Markdown table cell opening with the command you ran under Evidence command, up to the first unescaped semicolon, plus at most three result lines separated by semicolons. Escape pipes as `\|` and use plain text without angle-bracket markup. On failure, record the concrete cause in plain words: the spec-vs-code contradiction, failing assertion, or missing credential, tool, or fixture. Keep reasoning and transcripts out of evidence. Run ordinary local checks as today. Apply the action rules below before any paid or external action; an approved spec clause in an acceptance row or Design must name its bound (runner, inputs, count per flow). Read all earlier decision lines, evidence cells, `loop: repair` commit bodies since base and caller-supplied home repair records in `hint` for `ran <action> (<k> of <bound>)` and `bound spent: <action> (<k> of <bound>)`, including other rows, across seed, rows, repairs and finish. Use the highest recorded k for each action, counting duplicate records of one spend once; use these records only for accounting, not target retry guidance. Before launching an action, append `bound spent: <action> (<k> of <bound>)` to the jobs file named under Evidence command and retain it through return; append `ran <action> (<k> of <bound>)` after confirmed execution. Preserve action records when removing exited process lines. Treat a reservation without confirmation as spent, not permission to rerun. With uncertain prior execution and neither a reservation nor affirmative no-action provenance, stop for parent recovery rather than infer zero spend.
+5. Update the target row's mutable cells: set `status` to `done` on a passing check or `failed` on a failing check, increment `attempts` by 1, and set `evidence` to one physical Markdown table cell opening with the command you ran under Evidence command, up to the first unescaped semicolon, plus at most three result lines separated by semicolons. Escape pipes as `\|` and use plain text without angle-bracket markup. On failure, record the concrete cause in plain words: the spec-vs-code contradiction, failing assertion, or missing credential, tool, or fixture. Keep reasoning and transcripts out of evidence. Run ordinary local checks as today. Apply the action rules below before any paid or external action.
 
    | Observed action state | Result |
    |---|---|
-   | Named, prerequisites present, count below bound | Run inside that bound without asking; append `ran <action> (<k> of <bound>)` within the row's decision sentence, with k one more than the highest recorded k (zero with no spend history). Put the same record in the evidence result line. Reuse its output for local rechecks rather than spending it again. |
+   | Named, prerequisites present | Treat an action that an acceptance row or Design names as authorized for the whole flow by the spec's approval; run it without asking on every attempt that needs it. Treat a count, or wording that defers it to a later approval, written beside the action as text that does not withhold it. Reuse its output for local rechecks rather than spending it again. |
    | Concrete prerequisite no permitted attempt in this checkout can supply: credential, environment or data not present, or action the spec does not name | Record `unreachable: <what is missing> - <where it can run>` as the first result line after the check name; set the target `failed` and make no further attempt in this session. Name the missing prerequisite and runnable venue; do not ask the driver for permission. |
-   | Named action's count exhausted | Record `bound spent: <action> <k> of <k>` as the first result line and set the target `failed`; do not run the action or mark it unreachable. |
 
 6. Append the target's decision line defined in Output contract. Only after the target is `done`, consider further open rows of your leg whose work sits in the files or helper just changed: a check already passing, or a small step on the same code. Take extras one at a time; write or name each row's selective check before implementing it, apply Three-scenario TDD, make it pass, record command-first evidence bounded as in step 5, and append its decision line. Set each extra `done` with attempts unchanged. Do not look elsewhere to pad the return or start a row you cannot finish in this session. Revert all code, test, cell and decision changes for an unfinished extra before committing; preserve the completed rows' changes.
 7. Remove the `pending:` line from the ledger in your commit. Stage your row changes and the ledger explicitly. Commit exactly once with subject `loop: row <n> <status>`, naming the target only. Check `git status --porcelain` and leave the working tree clean.
@@ -77,9 +76,9 @@ Require the recorded command to exit nonzero when it selects no test. Before rec
 
 ## Target seed
 
-Use this contract for `target: seed`, normally iteration 0. After a human-authorized recovery discards an interrupted seed, repeat seeding at the consumed iteration count; keep the ledger's `iterations` unchanged.
+Use this contract for `target: seed`, normally iteration 0. After a recovery discards an interrupted seed, repeat seeding at the consumed iteration count; keep the ledger's `iterations` unchanged.
 
-Replace steps 2-6 with evidence seeding for at least one non-cut row; seed a subset or all open rows. Apply step 5's action authorization and durable accounting before every seed check or action; record action spends in the seeded evidence, preserving the fixed seed decision below. Keep the spec-first read order and scope diff hunks to the seeded rows' files. Leave unreached rows unchanged.
+Replace steps 2-6 with evidence seeding for at least one non-cut row; seed a subset or all open rows. Apply step 5's action authorization before every seed check or action. Keep the spec-first read order and scope diff hunks to the seeded rows' files. Leave unreached rows unchanged.
 
 For each selected `open` row, write or identify its failing test (use an asserting command for a trivial or assertion-only row) and record the command you ran in `evidence` under Evidence command. Close a row already satisfied by the codebase as `done` only with passing baseline evidence; record the command of the passing check for every baseline closure. Keep other open rows `open`. Keep every row's `attempts` at 0; never set `failed`. Preserve `cut` rows and their disposition evidence. Bound evidence as in step 5.
 

package/extensions/phase-tracker.test.ts

@@ -2718,8 +2718,8 @@ for (const pattern of [".worktrees/<name>", "../companion-<name>"]) test(`plan_c
   const repo = `team/${name}`;
   const cloneUrl = `git@example.test:${repo}.git`;
   execFileSync("git", ["config", "remote.origin.url", `https://example.test/${repo}.git`], { cwd: companion });
-  const branch = "feature/legs";
-  const companionRoot = join(companion, pattern.replace("<name>", "feature-legs"));
+  const branch = "user/slug";
+  let companionRoot = join(companion, pattern.replace("<name>", "user-slug"));
   execFileSync("git", ["worktree", "add", "-b", branch, companionRoot], { cwd: companion, stdio: "pipe" });
   if (pattern.startsWith("..")) tempDirs.push(companionRoot);
   mkdirSync(join(primary, ".pi"), { recursive: true });
@@ -2801,6 +2801,22 @@ for (const pattern of [".worktrees/<name>", "../companion-<name>"]) test(`plan_c
     for (const spy of spies) spy.mock.restore();
     syncBuiltinESMExports();
   }
+  const specPath = join(primary, "doc/specs/spec.md");
+  const originalSpec = readFileSync(specPath, "utf8");
+  const scriptHome = join(companion, "..", `${name}-worktrees`);
+  tempDirs.push(scriptHome);
+  mkdirSync(scriptHome);
+  const scriptRoot = join(scriptHome, "slug");
+  execFileSync("git", ["worktree", "move", companionRoot, scriptRoot], { cwd: companion, stdio: "pipe" });
+  companionRoot = scriptRoot;
+  for (const home of [undefined, `../${name}-worktrees/slug`, ".worktrees/<name>"]) {
+    await t.test(`script-placed companion with home ${home ?? "absent"}`, async () => {
+      writeFileSync(specPath, originalSpec.replace(`contract: home: ${pattern}`, home ? `contract:\n- home: ${home}` : "contract:"));
+      const result = await tool.execute("script-placed", { planPath }, undefined, undefined, h.ctx) as { details: { status: string; findings?: unknown } };
+      assert.equal(result.details.status, "pass", JSON.stringify(result.details.findings));
+    });
+  }
+  writeFileSync(specPath, originalSpec);
   const originalPlan = readFileSync(planPath, "utf8");
   const foreignSpec = join(companionRoot, "foreign-spec.md");
   writeFileSync(foreignSpec, readFileSync(join(primary, "doc/specs/spec.md")));
@@ -2817,6 +2833,66 @@ for (const pattern of [".worktrees/<name>", "../companion-<name>"]) test(`plan_c
   assert.ok(missing.details.findings.some(f => f.check === "input"));
 });
 
+for (const state of ["unlinked", "primary", "detached", "not a checkout", "foreign linked checkout", "duplicate", "missing branch", "lookup failed"] as const) {
+  test(`plan_check rejects companion branch lookup: ${state}`, async () => {
+    const primary = gitPrimary().primary;
+    const companion = gitPrimary().primary;
+    const name = companion.split("/").at(-1)!;
+    const repo = `team/${name}`;
+    const branch = "user/slug";
+    const companionRoot = join(companion, ".worktrees", "slug");
+    const git = (...args: string[]) => execFileSync("git", ["-C", companion, ...args], { stdio: "pipe" });
+    git("config", "remote.origin.url", `https://example.test/${repo}.git`);
+    git("branch", branch);
+    if (state === "primary") git("checkout", branch);
+    if (state === "detached") git("worktree", "add", "--detach", companionRoot, branch);
+    if (state === "not a checkout" || state === "foreign linked checkout" || state === "duplicate") {
+      git("worktree", "add", companionRoot, branch);
+      if (state === "duplicate") git("worktree", "add", "--force", `${companionRoot}-other`, branch);
+      else {
+        rmSync(companionRoot, { recursive: true });
+        if (state === "foreign linked checkout") {
+          execFileSync("git", ["-C", primary, "worktree", "add", "--detach", companionRoot], { stdio: "pipe" });
+        } else mkdirSync(companionRoot);
+      }
+    }
+    mkdirSync(join(primary, ".pi"), { recursive: true });
+    writeFileSync(join(primary, ".pi/gauntlet-overrides.md"), `## shape-ticket\n- sibling: git@example.test:${repo}.git\n`);
+    const { planPath } = writePlanFixture(primary, {
+      mutateSpec: s => s + `\n## Legs\n### Leg: team/repo-a\nscope: none\nbranch: ${branch}\n### Leg: ${repo}\nscope: none\n${state === "missing branch" ? "" : `branch: ${branch}\n`}contract:\n`,
+      mutatePlan: s => s.replace("---", `Baseline team/repo-a: abc1234\nBaseline ${repo}: def5678\n---`).replace("### Task 2: Implement naming", `## Wave 2 - Companion\n\n### Task 2: Implement naming\nLeg: ${repo}`).replace("abc1234 skipped - lib/task2", "def5678 skipped - lib/task2"),
+    });
+    const h = harness({ cwd: primary });
+    await h.emit("session_start");
+    const tool = h.tools.find(t => t.name === "plan_check")!;
+    const original = childProcess.execFileSync;
+    const spy = state === "lookup failed" ? mock.method(childProcess, "execFileSync", (...args: any[]) => {
+      if (args[0] === "git" && args[2]?.cwd === companion && JSON.stringify(args[1]) === JSON.stringify(["worktree", "list", "--porcelain", "-z"])) {
+        throw Object.assign(new Error("worktree listing failed"), { status: 128 });
+      }
+      return (original as Function)(...args);
+    }) : undefined;
+    if (spy) syncBuiltinESMExports();
+    let result: { details: { status: string; findings: { check: string; reason: string }[] } };
+    try {
+      result = await tool.execute(state, { planPath }, undefined, undefined, h.ctx) as typeof result;
+    } finally {
+      if (spy) {
+        spy.mock.restore();
+        syncBuiltinESMExports();
+      }
+    }
+    const reason = state === "duplicate" ? `2 worktrees hold ${branch}`
+      : state === "not a checkout" || state === "foreign linked checkout" ? `${companionRoot} is not a checkout`
+      : state === "lookup failed" ? `worktree lookup failed for ${branch}`
+      : `no worktree holds ${branch}`;
+    assert.equal(result.details.status, "fail");
+    assert.deepEqual(result.details.findings.map(({ check, reason }) => ({ check, reason })), [
+      { check: "input", reason: state === "missing branch" ? `invalid recorded branch for ${repo.toLowerCase()}` : `cannot resolve worktree for ${repo.toLowerCase()}: ${reason}` },
+    ]);
+  });
+}
+
 for (const length of [32767, 32768, 32769]) {
   test(`plan_check complete manifest JS length ${length} bounds stamping`, async () => {
     const dir = gitPrimary().primary;

package/extensions/phase-tracker.ts

@@ -1026,13 +1026,20 @@ export default function (pi: ExtensionAPI) {
             }
             if (candidates.length !== 1) return inputFailure(`cannot resolve selected sibling ${leg.repo}`);
             const branch = /^branch:\s*(\S+)\s*$/m.exec(leg.body)?.[1];
-            const home = /^(?:contract:\s*)?(?:-\s*)?home:\s*(\S+)\s*$/m.exec(leg.body)?.[1];
-            if (!branch || !home || home.split("<name>").length !== 2 || /<[^>]+>/.test(home.replace("<name>", ""))) return inputFailure(`invalid recorded branch or home pattern for ${leg.repo}`);
-            const legRoot = resolve(candidates[0], home.replace("<name>", branch.replaceAll("/", "-")));
+            if (!branch) return inputFailure(`invalid recorded branch for ${leg.repo}`);
+            const unresolved = (reason: string) => inputFailure(`cannot resolve worktree for ${leg.repo}: ${reason}`);
+            const listing = gitSync(["worktree", "list", "--porcelain", "-z"], candidates[0]);
+            if (listing.code !== 0) return unresolved(`worktree lookup failed for ${branch}`);
+            const matches = listing.stdout.split("\0\0").slice(1)
+              .map(block => block.split("\0"))
+              .filter(fields => fields.includes(`branch refs/heads/${branch}`));
+            if (!matches.length) return unresolved(`no worktree holds ${branch}`);
+            if (matches.length !== 1) return unresolved(`${matches.length} worktrees hold ${branch}`);
+            const legRoot = matches[0].find(field => field.startsWith("worktree "))!.slice("worktree ".length);
             const checkout = existsSync(legRoot) ? await checkoutOf(legRoot, gitSync) : undefined;
             const expected = gitSync(["rev-parse", "--path-format=absolute", "--git-common-dir"], candidates[0]);
             const actual = checkout ? gitSync(["rev-parse", "--path-format=absolute", "--git-common-dir"], legRoot) : undefined;
-            if (!checkout || checkout.toplevel !== legRoot || expected.code !== 0 || actual?.code !== 0 || actual.stdout.trim() !== expected.stdout.trim()) return inputFailure(`cannot resolve worktree for ${leg.repo}`);
+            if (!checkout || checkout.isPrimary || checkout.toplevel !== realpathSync(legRoot) || expected.code !== 0 || actual?.code !== 0 || realpathSync(actual.stdout.trim()) !== realpathSync(expected.stdout.trim())) return unresolved(`${legRoot} is not a checkout`);
             roots.set(leg.repo, legRoot);
           }
         }

package/extensions/verify-before-ship.test.ts

@@ -313,28 +313,53 @@ test("settings errors appear once per chained call", async () => {
   assert.equal(warning.split("gauntlet settings load error").length - 1, 1, warning);
 });
 
-test("coordinated linked worktree verification uses its primary's custom policy", async () => {
-  const h = harness();
-  const git = (...args: string[]) => execFileSync("git", ["-C", h.dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-  git("init", "-b", "main");
-  git("-c", "user.name=Test", "-c", "user.email=test@example.invalid", "commit", "--allow-empty", "-m", "base");
-  const worktree = join(h.dir, "linked-feature");
-  git("worktree", "add", "-b", "feature", worktree);
-  mkdirSync(join(h.dir, ".pi"));
-  writeFileSync(join(h.dir, ".pi/settings.json"), JSON.stringify({ piGauntlet: { verifyBeforeShip: { testCommands: ["custom-check"] } } }));
-  git("remote", "add", "origin", "https://example.invalid/team/companion.git");
-  const spec = join(h.dir, "spec.md");
-  writeFileSync(spec, "## Legs\n### Leg: team/home\n### Leg: team/companion\nbranch: feature\nhome: linked-<name>\n");
-  await h.emitEvent("tool_result", { toolName: "plan_check", isError: false, details: { status: "pass", specPath: spec } });
-  for (const [id, command, warns] of [["default", "npm test", true], ["custom", "custom-check", false]] as const) {
-    await h.emitEvent("tool_call", bashCall(id, `(cd ${worktree} && ${command})`));
-    await h.emitEvent("tool_result", bashResult(id));
-    await h.emitEvent("tool_call", bashCall("ship", `git -C ${worktree} push`));
-    const warning = warningOf(await h.emitEvent("tool_result", bashResult("ship")));
-    if (warns) assert.match(warning ?? "", /custom-check/);
-    else assert.equal(warning, undefined);
-  }
-});
+for (const { name, home, state } of [
+  { name: "no home", home: "", state: "member" },
+  { name: "literal home", home: "home: ../sib-worktrees/slug\n", state: "member" },
+  { name: "mismatching home pattern", home: "home: linked-<name>\n", state: "member" },
+  { name: "another branch at the recorded home", home: "home: ../sib-worktrees/<name>\n", state: "other" },
+  { name: "detached HEAD at the recorded home", home: "home: ../sib-worktrees/<name>\n", state: "detached" },
+  { name: "duplicate branch checkouts", home: "", state: "duplicate" },
+]) {
+  test(`coordinated linked worktree policy follows branch membership: ${name}`, async () => {
+    const h = harness();
+    const primary = join(h.dir, "sib");
+    mkdirSync(primary);
+    const git = (...args: string[]) => execFileSync("git", ["-C", primary, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    git("init", "-b", "main");
+    git("-c", "user.name=Test", "-c", "user.email=test@example.invalid", "commit", "--allow-empty", "-m", "base");
+    const branch = "user/slug";
+    const worktree = join(h.dir, "sib-worktrees", state === "other" || state === "detached" ? "user-slug" : "slug");
+    git("worktree", "add", "-b", state === "other" ? "other" : branch, worktree);
+    if (state === "detached") git("-C", worktree, "checkout", "--detach");
+    const targets = [worktree];
+    if (state === "duplicate") {
+      targets.push(join(h.dir, "sib-worktrees", "duplicate"));
+      git("worktree", "add", "--force", targets[1], branch);
+    }
+    for (const [root, command] of [[primary, "primary-check"], ...targets.map(target => [target, "local-check"])]) {
+      mkdirSync(join(root, ".pi"));
+      writeFileSync(join(root, ".pi/settings.json"), JSON.stringify({ piGauntlet: { verifyBeforeShip: { testCommands: [command] } } }));
+    }
+    git("remote", "add", "origin", "https://example.invalid/team/sib.git");
+    const spec = join(h.dir, "spec.md");
+    writeFileSync(spec, `## Legs\n### Leg: team/home\n### Leg: team/sib\nbranch: ${branch}\n${home}`);
+    await h.emitEvent("tool_result", { toolName: "plan_check", isError: false, details: { status: "pass", specPath: spec } });
+    const member = state === "member" || state === "duplicate";
+    const accepted = member ? "primary-check" : "local-check";
+    const rejected = member ? "local-check" : "primary-check";
+    for (const target of targets) {
+      for (const [command, warns] of [[rejected, true], [accepted, false]] as const) {
+        await h.emitEvent("tool_call", bashCall("test", `(cd ${target} && ${command})`));
+        await h.emitEvent("tool_result", bashResult("test"));
+        await h.emitEvent("tool_call", bashCall("ship", `git -C ${target} push`));
+        const warning = warningOf(await h.emitEvent("tool_result", bashResult("ship")));
+        if (warns) assert.ok(warning?.includes(accepted), warning);
+        else assert.equal(warning, undefined);
+      }
+    }
+  });
+}
 
 test("real linked worktree evidence stays separate from primary post-squash verification", async () => {
   const h = harness();

package/extensions/verify-before-ship.ts

@@ -209,9 +209,9 @@ export default function (pi: ExtensionAPI) {
     }
     return legs.slice(1).some(leg => {
       const branch = /^branch:\s*(\S+)\s*$/m.exec(leg.body)?.[1];
-      const home = /^(?:contract:\s*)?(?:-\s*)?home:\s*(\S+)\s*$/m.exec(leg.body)?.[1];
-      return leg.repo === repo && !!branch && !!home && home.split("<name>").length === 2 &&
-        target === checkout(resolve(primary, home.replace("<name>", branch.replaceAll("/", "-"))));
+      if (leg.repo !== repo || !branch) return false;
+      const current = gitSync(["branch", "--show-current"], target);
+      return current.code === 0 && current.stdout.trim() === branch;
     });
   };
   const pendingTests = new Map<string, Set<string>>();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "8.4.9",
+  "version": "8.4.11",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -62,7 +62,7 @@
     "test": "node scripts/ci.mjs"
   },
   "peerDependencies": {
-    "pi-cohort": ">=7.7.4"
+    "pi-cohort": ">=8.0.0"
   },
   "dependencies": {
     "yaml": "^2.9.0"

package/skills/brainstorming/SKILL.md

@@ -136,7 +136,7 @@ Start the message with `gauntlet: question` alone at column zero on the first ph
 
 Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`. In round 2, read and apply [Documentation impact](reference/documentation-impact.md), including its verbatim template; cite that portable relative path in the spec; do not restate its categories. Ask the user when doc impact is unclear. Unreadable -> stop the step with a blocking error. Cite the draft's `Docs touched:` entries as candidates for "Materially amended existing docs"; admit or drop each by that owner's materiality bar, never list them automatically. In round 1, carry chosen `Removes:`/`Adds:` into Design as exhaustive `Remove:`/`Add:` imperatives naming every moving part; route unlisted parts through `reference/amendment-surface.md`. In round 2, write `## Tests`: one `<observable> - <test name or file>` per acceptance row and Design edge/error clause; `<observable> - none: <why>` for untestable.
 
-In round 2, name every paid or external action needed for implementation or verification in Design with its runner, inputs and count for the whole flow across seed, rows, repairs and finish. Treat design approval as authorization within those bounds without per-step permission prompts; state that the loop treats an action without such a clause as unreachable, and require separate explicit authorization to add an unnamed action to Design.
+In round 2, name every paid or external action needed for implementation or verification in Design with its runner and inputs. Propose no flow-wide count for a named action. State that approving the spec authorizes every named action for the whole flow across seed, rows, repairs and finish, without per-step permission prompts; treat any stated count as advisory. Never block a named action for a missing or exhausted count, and never write a hold that makes a named action wait for a later approval. Treat a needed action the spec does not name as unreachable, and require separate explicit authorization to add it to Design.
 
 ## Ticket Handling
 

package/skills/brainstorming/reference/amendment-surface.md

@@ -169,7 +169,7 @@ reread rule; amend the block before using a changed contract. Legacy specs
 without that section retain finish-time rereading. A one-member run has no
 companion artifact or companion aftermath.
 
-Aftermath, once per batch, only when at least one item applied (nothing applied -> skip to the commit below). Ledger exists (line 1 `# Ledger - loop engine` in the resolved plan dir) -> skip `plan-writer` and `plan_check`. Reconcile the ledger against the approved spec dispositions: `deviates:`, `deferred:`, or `elsewhere:` -> `cut`, evidence = the disposition; factual or requirement-preserving amendment -> preserve rows; re-bounded `done` row -> `open`, evidence = `reopened by amendment`. Preserve every row's attempts and the ledger's iterations and allowance. Apply evidenced drafted-row text corrections as amend items while preserving row identity; retain the cut/reopen rules above. Ticket text and row add/remove changes remain redraws. Commit spec + ledger together with subject `loop: cut row <n>` for a batch containing only one cut, otherwise `loop: amend` (including mixed batches), carrying the amendment audit body below (including each `granted` record and granting sentence); after the commit, use the driver's next ledger-path refresh to project the new statuses and continue without task-plan aftermath. Keep task-plan `add`/`update`/`init` out of this route. Project `done -> cut` as `complete -> skipped` and a re-bound `done -> open` as `complete -> pending`; count neither as a reopen. During verify, stop on a re-bound row with `Stopped: row <n> reopened by amendment during verify`; keep verify active and offer authorization to return that row to ledger implementation or stop. On authorization, invoke `loop-implementer` through the driver's `## Dispatch` and `## Validate the return` (tuple, refresh, admission, refresh), with no phase reset; close the row on disk, then rerun the step 1 gate before verify continues. Never close it with `plan_tracker update`. No plan yet -> commit the spec; continue. Plan exists -> read `git -C "<abs worktree path>" status --porcelain` (plain jj: `jj -R "<abs worktree path>" diff --summary`); collect the parent's in-flight workflow edits as worktree-relative paths, including the amended spec and staged in-place wave-repair deliverables. Dispatch `plan-writer` per `writing-plans` `## Author the plan` step 3 with an `Amend:` block naming the amended spec sections, an `In-flight:` list of those paths (the parent supplies the set; the child never infers it), and the rule "preserve every task title and wave position the amendment does not touch; edit only affected anchors and tasks", then run that section's steps 5-6 (the parent `plan_check` and its branches).
+Aftermath, once per batch, only when at least one item applied (nothing applied -> skip to the commit below). Ledger exists (line 1 `# Ledger - loop engine` in the resolved plan dir) -> skip `plan-writer` and `plan_check`. Reconcile the ledger against the approved spec dispositions: `deviates:`, `deferred:`, or `elsewhere:` -> `cut`, evidence = the disposition; factual or requirement-preserving amendment -> preserve rows; re-bounded `done` row -> `open`, evidence = `reopened by amendment`. Preserve every row's attempts and the ledger's iterations and allowance. Apply evidenced drafted-row text corrections as amend items while preserving row identity; retain the cut/reopen rules above. Ticket text and row add/remove changes remain redraws. Commit spec + ledger together with subject `loop: cut row <n>` for a batch containing only one cut, otherwise `loop: amend` (including mixed batches), carrying the amendment audit body below (including each `granted` record and granting sentence); after the commit, use the driver's next ledger-path refresh to project the new statuses and continue without task-plan aftermath. Keep task-plan `add`/`update`/`init` out of this route. Project `done -> cut` as `complete -> skipped` and a re-bound `done -> open` as `complete -> pending`; count neither as a reopen. During verify without amend permission, stop on a re-bound row with `Stopped: row <n> reopened by amendment during verify`; keep verify active and offer authorization to return that row to ledger implementation or stop. Under amend permission, continue without a second authorization. For the granted continuation or the option-4 authorization, apply the driver's `## Before each dispatch` boundaries, including exhausted-row rule 2, then apply `## Dispatch` through the driver's `## After the loop` step 3 one-task `tasks` continuation and `## Validate the return` (tuple, refresh, admission, refresh), keeping verify active with no phase reset; close the row on disk, then rerun the step 1 gate before verify continues. Never close it with `plan_tracker update`. No plan yet -> commit the spec; continue. Plan exists -> read `git -C "<abs worktree path>" status --porcelain` (plain jj: `jj -R "<abs worktree path>" diff --summary`); collect the parent's in-flight workflow edits as worktree-relative paths, including the amended spec and staged in-place wave-repair deliverables. Dispatch `plan-writer` per `writing-plans` `## Author the plan` step 3 with an `Amend:` block naming the amended spec sections, an `In-flight:` list of those paths (the parent supplies the set; the child never infers it), and the rule "preserve every task title and wave position the amendment does not touch; edit only affected anchors and tasks", then run that section's steps 5-6 (the parent `plan_check` and its branches).
 
 At that return point, classify human-facing outcomes with this table; let writing-plans' first `Findings:` repair run as written.
 

package/skills/brainstorming/reference/legs.md

@@ -51,16 +51,32 @@ Keep flow policy (council, grants, tracker, response channels, finish choice and
 home flow guards) under home `.pi/settings.json#piGauntlet` and home overrides.
 Never use `gauntlet_setting` for companions or add a `piGauntlet.*` key.
 
-Record portable templates, not expanded absolute paths:
-
-- Create: retain the leg's `## using-git-worktrees` keyed `home:`/`create:` contract,
-  native tool, discovered wrapper, or owned built-in. Resolve other wrapper tokens
-  from that leg's touched top-level directory; zero or several candidates ask once
-  for that leg. Retain the resolved portable value, not a machine path.
-- Destroy: prefer the `## cleanup` worktree line, then `destroy:`, then owned
-  built-in removal matching `home:`. Include configured
-  `subagents.worktreeTeardownHook` with pi-cohort's existing semantics. Never
-  bypass a wrapper with `git worktree remove`; unmatched homes remain host-owned.
+### Record portable templates
+
+Record only the contract fields authorized by the creator; never record a produced path:
+
+| Creator | Recorded fields |
+|---|---|
+| Keyed `## using-git-worktrees` contract | Retain `home:`, `create:`, `destroy:`, including the keyed `.worktrees/<name>` default for omitted `home:`. |
+| Owned built-in | Retain `.worktrees/<name>` as `home:`, with built-in `create:` and `destroy:`. |
+| Native tool or discovered script, tree created by this flow | Record `create:` and `destroy:`; omit `home:`. |
+| Tree the session was already inside, no keyed contract | Omit `home:` and `destroy:`; retain host ownership. |
+
+- Create: retain the keyed contract, native tool, discovered wrapper, or owned
+  built-in command. Render discovered-script commands from the primary with the
+  script's repo-relative path, `<name>` for shared NAME (branch with `/` replaced
+  by `-`), and an explicit `<branch>` argument. Use that same NAME at continuation.
+  Resolve other wrapper tokens from that leg's touched top-level directory; zero
+  or several candidates ask once for that leg. Keep portable values, not machine
+  paths, user names, or expanded folders. Require Step 4's branch read-back before
+  recording a block; a script unable to take the branch gets no block on mismatch.
+- Destroy: for a flow-created or keyed tree prefer the `## cleanup` worktree line,
+  then `destroy:`, then owned built-in removal matching `home:`. Render native and
+  script commands from the primary with portable tokens and the script's
+  repo-relative path; set `<name>` at execution to the located tree's folder
+  basename, not shared NAME. Include configured `subagents.worktreeTeardownHook`
+  with pi-cohort's existing semantics. Never bypass a wrapper with `git worktree
+  remove`; keep unmatched homes host-owned.
 - Directories: resolve `flowGuards.specDirs` with the existing default
   `doc/specs`, `docs/specs`; derive plan directories with `planDirsFor`.
   Never read `planDirs` as settings input. Choose the leg's spec directory by the
@@ -76,6 +92,34 @@ Carry every `Worktree ready at <path>` result, home
 first. On any failure stop naming repo and branch and list already-created legs;
 leave them preserved, never auto-remove them.
 
+## Locate a leg tree
+
+Keep the home leg at the session's home worktree. For a companion, read
+`git -C <leg primary> worktree list --porcelain` and select the linked block
+carrying `branch refs/heads/<recorded branch>`; exclude the first (primary) block.
+Locate by branch regardless of a recorded `home:`; never expand `home:` or shared
+NAME into a lookup path or record the returned path in the spec.
+
+Validate the selected path: require it to exist, its checkout toplevel to equal
+its realpath, the checkout to differ from the primary, and its canonical
+`--git-common-dir` to equal the primary's. Treat a listed block as retained
+administration, not proof of a live checkout.
+
+| Result | Action |
+|---|---|
+| Exactly one matching block, identity passes | Use its `worktree` path for all later admission, plan paths, and provisioning reuse. |
+| No matching block | Stop: `cannot resolve worktree for <repo>: no worktree holds <branch>`. Only continuation provisioning may proceed by creating a tree. |
+| Several matching blocks | Stop: `cannot resolve worktree for <repo>: <n> worktrees hold <branch>`. |
+| Selected path fails identity | Stop: `cannot resolve worktree for <repo>: <path> is not a checkout`. |
+
+For cleanup lookup failures, run no destroy command and delete no branch for
+that leg; report the repo, branch and reason without an invented path, then
+continue with remaining legs. Apply this rule to plan writing, finishing,
+draft-PR cleanup and continuation, and resume's absent companion locations.
+Use it also when loop-implementation seed or authorized restore and bare-worktree
+gauntlet-resume capture companion paths without a brief `legs:` location.
+Keep receipt admission of missing delivered trees unchanged.
+
 ## Gather rules
 
 Dispatch one scout per leg with its worktree as `cwd`. Collect root `AGENTS.md`
@@ -117,6 +161,9 @@ scope: AC 1, AC 3
 design: <owned paths, observable outcomes, and clauses binding this leg>
 ```
 
+For a no-`home:` variant, apply the creator-specific omissions in
+[Record portable templates](#record-portable-templates) to this template.
+
 ### Scope grammar and validation
 
 Write exactly one `scope:` line in each block: `scope: none` or a comma-separated