refactor(executing-a-branch-plan): scope Step 8 dispatches to sanctioned call sites

.claude/agents/branch-plan-task.md

@@ -1,6 +1,6 @@
 ---
 name: branch-plan-task
-description: Task-level subagent type for executing-a-branch-plan's Decision 4/16 execution step (one agent() call per Decision 3/15 task, dispatched per wave). Never invoke directly for anything else -- this type exists solely as the Decision 17 deterministic backstop for Decision 7's exclusion list (no mcp__github__* tools, no gh/git-push/install commands), scoped to task-agent dispatch specifically per docs/superpowers/specs/2026-07-22-plan-execution-handoff-design.md, plus (Decision 20, issue #1476) the deterministic backstop requiring the full repo verification suite to pass inside this task's own worktree before it may report complete. Project-local variant (this repository checked out directly, .claude/agents/ discovery path) -- the embedded hooks below only fire here; see agents/branch-plan-task.md (the plugin-distributed variant, no hooks field, weaker prompt-only backstop for both mechanisms) for the deployment where gitapex is installed as a plugin into a different repository.
+description: Task-level, project-local subagent type for a fixed, enumerated set of call sites -- see this file's own "Sanctioned call sites" section for the exact, current list (executing-a-branch-plan Step 6's per-task dispatch, Step 8's refactor/simplify pass). Never invoke directly for anything else, and never add a new call site without updating that section first -- this type exists as the Decision 17 deterministic backstop for Decision 7's exclusion list (no mcp__github__* tools, no gh/git-push/install commands), across both call sites, plus (Decision 20, issue #1476) the deterministic backstop requiring the full repo verification suite to pass inside this dispatch's own working checkout before it may report complete. Project-local variant (this repository checked out directly, .claude/agents/ discovery path) -- the embedded hooks below only fire here; see agents/branch-plan-task.md (the plugin-distributed variant, no hooks field, weaker prompt-only backstop for both mechanisms) for the deployment where gitapex is installed as a plugin into a different repository.
 disallowedTools: mcp__github
 hooks:
   PreToolUse:
@@ -17,22 +17,51 @@ hooks:
           timeout: 3900
 ---
 
-Task-level dispatch target for `executing-a-branch-plan`. Do all Decision 3
-task work (Red-Green per Decision 14, screened per Decision 6) using Edit,
-Write, Read, Grep, Glob, and Bash for non-excluded commands (git add, git
-commit, running tests). Never attempt a GitHub write, the gh CLI, git push,
-or a package-manager install -- those are main-thread-only per design doc
-Decision 7; this agent type's own tool restrictions and embedded Bash hook
-enforce that structurally, not only by this instruction.
+Dispatch target for `executing-a-branch-plan`, scoped to the two call
+sites the "Sanctioned call sites" section below enumerates. At Step 6's
+own call site, do all Decision 3 task work (Red-Green per Decision 14,
+screened per Decision 6); at Step 8's own call site, apply the same tool
+set as a behavior-preserving refactor/simplify pass over the full
+accumulated diff instead (no per-task Red-Green there -- see
+`skills/executing-a-branch-plan/references/refactor-and-review-gate.md`'s
+own sub-step 1). Both use Edit, Write, Read, Grep, Glob, and Bash for
+non-excluded commands (git add, git commit, running tests). Never attempt
+a GitHub write, the gh CLI, git push, or a package-manager install --
+those are main-thread-only per design doc Decision 7; this agent type's
+own tool restrictions and embedded Bash hook enforce that structurally,
+not only by this instruction.
+
+## Sanctioned call sites
+
+Only these. A caller outside this list should not name this
+`agentType`/`subagent_type` -- propose adding it here first, in the same
+change that adds the new call site, rather than reusing this definition
+silently.
+
+1. `executing-a-branch-plan` Step 6's per-task dispatch (Decision 4/16)
+   -- one `agent()` call per Decision 3/15 task, dispatched per wave. The
+   existing, primary role this agent type was originally defined for.
+2. `executing-a-branch-plan` Step 8's refactor/simplify pass (Decision
+   12) -- a single dispatch over the full accumulated diff, after all
+   Step 6 tasks complete, behavior-preserving edits only. Any
+   behavior-affecting finding is out of this dispatch's own scope and
+   routes to the separate adversarial review pass instead
+   (`subagent_type: 'review-persona'`, see `agents/review-persona.md`'s
+   own "Sanctioned call sites" section) -- see
+   `skills/executing-a-branch-plan/references/refactor-and-review-gate.md`'s
+   own sub-step 1/2 split for why.
 
 Before reporting complete: the embedded `SubagentStop` hook above runs the
 full repo verification suite (`uv run --frozen python3 -m pytest --no-cov
 -q` plus `uv run --frozen python3
-.github/scripts/gitapex_gate_local_preflight.py`) inside this worktree and
-denies stopping until both pass (design doc Decision 20, issue #1476) --
-this is a deterministic backstop, not only this paragraph's own
-instruction, but fixing a verification failure it reports is still this
-task's own responsibility to act on, the same as any other blocked stop.
+.github/scripts/gitapex_gate_local_preflight.py`) inside this dispatch's
+own working checkout (a worktree at Step 6's call site; this dispatch's
+own checkout directly at Step 8's, which runs without worktree isolation
+-- see the "Sanctioned call sites" section above) and denies stopping
+until both pass (design doc Decision 20, issue #1476) -- this is a
+deterministic backstop, not only this paragraph's own instruction, but
+fixing a verification failure it reports is still this dispatch's own
+responsibility to act on, the same as any other blocked stop.
 
 This hook's own `timeout: 3900` above must stay comfortably above 2x
 `gitapex_check_task_full_verification.py`'s own `DEFAULT_TIMEOUT_SECONDS`

.gitignore

@@ -34,3 +34,8 @@ apm_modules/
 # Transient git worktrees created by Agent-tool `isolation: worktree` dispatches
 # (one per parallel task); reproducible on demand, never meant to be committed.
 /.claude/worktrees/
+
+# Personal, per-session overrides (env, permission tweaks) -- unlike
+# .claude/settings.json above, this file is never meant to be shared or
+# committed.
+/.claude/settings.local.json

agents/branch-plan-task.md

@@ -1,22 +1,51 @@
 ---
 name: branch-plan-task
-description: Task-level subagent type for executing-a-branch-plan's Decision 4/16 execution step (one agent() call per Decision 3/15 task, dispatched per wave). Never invoke directly for anything else. Plugin-distributed variant -- see skills/executing-a-branch-plan/references/threat-model-and-authorization.md for why this variant carries no embedded hook and what that means for the Decision 17 backstop's actual strength in a plugin-installed deployment, and (Decision 20, issue #1476) the identical weaker-strength accounting for the full-verification-suite exit condition below.
+description: Task-level, plugin-distributed subagent type for a fixed, enumerated set of call sites -- see this file's own "Sanctioned call sites" section for the exact, current list (executing-a-branch-plan Step 6's per-task dispatch, Step 8's refactor/simplify pass). Never invoke directly for anything else, and never add a new call site without updating that section first. See skills/executing-a-branch-plan/references/threat-model-and-authorization.md for why this variant carries no embedded hook and what that means for the Decision 17 backstop's actual strength in a plugin-installed deployment, and (Decision 20, issue #1476) the identical weaker-strength accounting for the full-verification-suite exit condition below.
 disallowedTools: mcp__github
 ---
 
-Task-level dispatch target for `executing-a-branch-plan`. Do all Decision 3
-task work (Red-Green per Decision 14, screened per Decision 6) using Edit,
-Write, Read, Grep, Glob, and Bash for non-excluded commands (git add, git
-commit, running tests). Never attempt a GitHub write, the gh CLI, git push,
-or a package-manager install -- those are main-thread-only per design doc
-Decision 7.
+Dispatch target for `executing-a-branch-plan`, scoped to the two call
+sites the "Sanctioned call sites" section below enumerates. At Step 6's
+own call site, do all Decision 3 task work (Red-Green per Decision 14,
+screened per Decision 6); at Step 8's own call site, apply the same tool
+set as a behavior-preserving refactor/simplify pass over the full
+accumulated diff instead (no per-task Red-Green there -- see
+`skills/executing-a-branch-plan/references/refactor-and-review-gate.md`'s
+own sub-step 1). Both use Edit, Write, Read, Grep, Glob, and Bash for
+non-excluded commands (git add, git commit, running tests). Never attempt
+a GitHub write, the gh CLI, git push, or a package-manager install --
+those are main-thread-only per design doc Decision 7.
 
-**Before reporting complete, run the full repo verification suite inside
-your own worktree** (design doc Decision 20, issue #1476): `uv run
+## Sanctioned call sites
+
+Only these. A caller outside this list should not name this
+`agentType`/`subagent_type` -- propose adding it here first, in the same
+change that adds the new call site, rather than reusing this definition
+silently.
+
+1. `executing-a-branch-plan` Step 6's per-task dispatch (Decision 4/16)
+   -- one `agent()` call per Decision 3/15 task, dispatched per wave. The
+   existing, primary role this agent type was originally defined for.
+2. `executing-a-branch-plan` Step 8's refactor/simplify pass (Decision
+   12) -- a single dispatch over the full accumulated diff, after all
+   Step 6 tasks complete, behavior-preserving edits only. Any
+   behavior-affecting finding is out of this dispatch's own scope and
+   routes to the separate adversarial review pass instead
+   (`subagent_type: 'review-persona'`, see `agents/review-persona.md`'s
+   own "Sanctioned call sites" section) -- see
+   `skills/executing-a-branch-plan/references/refactor-and-review-gate.md`'s
+   own sub-step 1/2 split for why.
+
+**Before reporting complete, run the full repo verification suite in
+your own dispatch's working checkout** (a worktree at Step 6's call
+site; this dispatch's own checkout directly at Step 8's, which runs
+without worktree isolation -- see the "Sanctioned call sites" section
+above) (design doc Decision 20, issue #1476): `uv run
 --frozen python3 -m pytest --no-cov -q --ignore=tests/test_gitapex_check_bash_safety_oracle_pins.py --ignore=tests/test_gitapex_check_task_bash_safety_oracle_pins.py --ignore=tests/test_gitapex_check_bash_safety_differential.py --ignore=tests/test_gitapex_check_task_bash_safety_differential.py`
 then `uv run --frozen python3 .github/scripts/gitapex_gate_local_preflight.py`.
-Do not report this task done while either fails -- fix the failure first,
-the same as any other Red-Green check this task's own work requires.
+Do not report this dispatch done while either fails -- fix the failure
+first, the same as any other Red-Green check this dispatch's own work
+requires.
 
 This tool restriction (`disallowedTools: mcp__github`) is structurally
 enforced and portable to a plugin-installed deployment. The Bash-level
@@ -48,5 +77,8 @@ safety.sh`); this variant has no equivalent backstop of any kind for it,
 the identical asymmetry as the two mechanisms above -- this paragraph's
 own instruction is the only thing enforcing it here. Skip this check
 entirely if you are not running inside a worktree at all (the sequential-
-fallback dispatch, no wave) -- there is no shared-branch fork point to
+fallback dispatch, no wave, or Step 8's own single dispatch -- also no
+wave, no worktree isolation, per
+`skills/executing-a-branch-plan/references/execution-and-dispatch.md`'s
+own Step 8 subsection) -- there is no shared-branch fork point to
 compare against in that case.

agents/review-persona.md

@@ -36,6 +36,14 @@ adds the new call site, rather than reusing this definition silently.
    respectively, neither performable by this dispatch's read-only,
    file-scoped tool set) -- while the rest of checks 2-8, check 5
    included, still dispatch normally.
+4. `executing-a-branch-plan` Step 8's adversarial code review pass
+   (Decision 12) -- a single dispatch over the full accumulated diff
+   after all Step 6 tasks complete, reviewing for correctness bugs.
+   Read-only: this dispatch returns findings only; it does NOT verify,
+   fix, or validate them -- see
+   `skills/executing-a-branch-plan/references/refactor-and-review-gate.md`'s
+   own sub-step 2 text for where that verify/fix/validate work actually
+   happens.
 
 ## What this dispatch does and does not do
 

docs/superpowers/plans/2026-09-02-claude-pr-1560-prep-o93l5b.md

@@ -0,0 +1,114 @@
+# Scope executing-a-branch-plan Step 8's refactor/adversarial-review dispatches to sanctioned agent call sites
+
+**Goal:** `skills/executing-a-branch-plan/references/refactor-and-review-gate.md`
+Step 8 runs two fresh subagent dispatches over the full accumulated diff
+(a behavior-preserving refactor/simplify pass, and an independent
+adversarial code review) without naming an `agentType`/`subagent_type`
+for either. `agents/branch-plan-task.md` and `.claude/agents/branch-plan-
+task.md` both state "never invoke directly for anything else" --
+silently reusing that definition for Step 8 would contradict its own
+declared scope. Give each dispatch an explicit, sanctioned tool-access
+boundary: the refactor pass reuses `branch-plan-task` (widened
+description, not a new sibling definition), the adversarial review pass
+reuses the existing read-only `review-persona` (from #1559/PR #1599).
+Source: https://github.com/tvna/gitapex/issues/1560.
+
+**Authorization record:** No approving comment exists on issue #1560
+(checked via `github:issue_read` method `get`, `closed_by_pull_requests`
+empty). Branch 2 of the Authorization gate applies: the active human
+operator's own opening turn in this session instructed executing issue
+#1560 through to just-before-merge ("create this PR, proceed to just
+before merge"), and explicitly confirmed ("OK") the Branch Plan/ACM this
+task list implements, in this same session, immediately before this
+step ran. This is a fresh, explicit, in-session confirmation for this
+specific issue's execution, not a self-reported claim of prior approval.
+
+**Threat-model triage (step 2):** Issue #1560 was read in full. It is a
+well-formed, professionally-scoped refactor issue authored by the
+repository owner (`author_association: OWNER`), with an ACM, Constraints,
+and Non-goals sections, no embedded instruction addressed to the
+executing agent, no hidden/encoded payload, no attempt to redirect this
+skill's own process. Clean.
+
+**Architecture:** A single prose-only change across six files; no new
+files, no new tests. Every file below is read by, or must stay
+consistent with, every other file below (the `branch-plan-task`/
+`review-persona` call-site lists and the `SKILL.md`/`references/*.md`
+dispatch descriptions that name them are two sides of the same fact) --
+this is exactly the file-contention/interface-dependency case
+`task-decomposition.md`'s own row-to-task mapping rule merges into one
+task rather than splitting, so this ACM's three rows collapse into one
+task, not three parallel ones.
+
+## Task 1 (ACM rows 1-4, all)
+
+**Cites ACM row 1** ("The refactor pass's dispatch does not contradict
+`branch-plan-task`'s 'never invoke directly for anything else' scope"),
+**Planned ops (quoted verbatim):** "`agents/branch-plan-task.md`,
+`.claude/agents/branch-plan-task.md`, `skills/executing-a-branch-plan/
+SKILL.md` (Step 8 dispatch text, currently around L237-249),
+`skills/executing-a-branch-plan/references/execution-and-dispatch.md`
+(Step 8-related text), `skills/executing-a-branch-plan/references/
+refactor-and-review-gate.md` (sub-step 1 text, L57-64). Name
+agentType/subagent_type: 'branch-plan-task' explicitly at the dispatch
+call site."
+
+**Cites ACM row 2** ("The adversarial review pass runs under a
+read-only tool boundary"), **Planned ops (quoted verbatim):**
+"`agents/review-persona.md`, `skills/executing-a-branch-plan/SKILL.md`
+(Step 8 dispatch text), `skills/executing-a-branch-plan/references/
+execution-and-dispatch.md`, `skills/executing-a-branch-plan/references/
+refactor-and-review-gate.md` (sub-step 2 text, L65-68). Name
+subagent_type: 'review-persona' explicitly at the dispatch call site."
+
+**Cites ACM row 3** ("The 'Findings -> verify each -> fix confirmed
+ones -> validate the fix' text states explicitly who applies the
+fix"), **Planned ops (quoted verbatim):**
+"`skills/executing-a-branch-plan/references/refactor-and-
+review-gate.md` L65-68."
+
+**Cites ACM row 4** ("Both dispatches' existing model/effort pins
+survive the change"), **Planned ops (quoted verbatim):** "Diff review
+at each edit site."
+
+**Files (file-ownership map -- all six owned by this one task, no
+sibling task to conflict with):**
+
+- `agents/branch-plan-task.md` (plugin variant)
+- `.claude/agents/branch-plan-task.md` (project-local variant)
+- `agents/review-persona.md`
+- `skills/executing-a-branch-plan/SKILL.md`
+- `skills/executing-a-branch-plan/references/execution-and-dispatch.md`
+- `skills/executing-a-branch-plan/references/refactor-and-review-gate.md`
+
+**Interface dependencies:** none external (single task); internally, the
+two agent-definition files' own "Sanctioned call sites" text must name
+the same `agentType`/`subagent_type` strings the `SKILL.md`/
+`references/*.md` dispatch descriptions use -- resolved within this one
+task's own diff, not across a wave boundary.
+
+**Irreversibility:** none (prose-only edits to skill/agent-definition
+files; no destructive operation, no schema/data change, no change to
+what `branch-plan-task`'s Step 6 task-agent dispatch is permitted to do).
+
+**Proof method:** `uv run --frozen python3 -m pytest --no-cov -q`
+(existing exclusions per `branch-plan-task.md`) and `uv run --frozen
+python3 .github/scripts/gitapex_gate_local_preflight.py`, both green;
+static cross-file review confirming the two agent-definition files'
+"Sanctioned call sites" sections and the `SKILL.md`/`references/*.md`
+dispatch descriptions name matching `agentType`/`subagent_type` values
+and do not contradict "never invoke directly for anything else."
+
+## Wave assignment
+
+Wave 1: Task 1 (single task, single wave -- the degenerate case
+`executing-a-branch-plan`'s own Related skills section names explicitly
+as a valid decomposition, not a different mode).
+
+## Execution mode
+
+Sequential main-thread fallback (one task per turn, no `Workflow` run,
+no worktree isolation) -- a single task has no parallel wave to gain
+isolation for for; the task's own exclusion list (no `mcp__github__*`,
+no `gh`/`git push`/install) is honored as this session's own main-thread
+discipline for this task's edits.

skills/executing-a-branch-plan/SKILL.md

@@ -234,12 +234,13 @@ first, not skimmed.
    dispatch is a deadlock, not a harmless leftover. Full dispatch table:
    [domain events and failure-handling
    reference](references/domain-events-and-failure-handling.md#failure-dispatch-step-7).
-8. **Refactor and adversarially review the accumulated diff** (Decision
-   12, mandatory, non-skippable). Two separate fresh subagent dispatches
-   over the full diff -- a refactor/simplify pass (behavior-preserving
-   only), then an independent adversarial code review -- findings
-   verified and fixed before proceeding. The independent adversarial code
-   review also specifically re-checks [Migrate Callers Then Delete Legacy
+8. **Refactor and adversarially review the accumulated diff** (Decision 12, mandatory,
+   non-skippable). Two separate fresh subagent dispatches over the full diff -- a
+   refactor/simplify pass (behavior-preserving only, `agentType: 'branch-plan-task'`), then
+   an independent adversarial code review (`subagent_type: 'review-persona'`) -- findings
+   verified and fixed outside it, in the calling main thread only (never by the refactor
+   pass's own behavior-preserving-only subagent), before proceeding. The independent
+   adversarial code review also specifically re-checks [Migrate Callers Then Delete Legacy
    APIs](references/code-quality-principles.md#4-migrate-callers-then-delete-legacy-apis),
    confirming a caller migration begun by one task actually completed
    cleanly rather than being left half-done by another -- a