@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/routines/executing-plans/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: executing-plans
+description: The checkpoint coordinator for /feature. Routed to by /feature once a writing-plans plan exists. Groups tasks into batches, delegates each batch to subagent-driven-development (fresh author agent per task, full review chain, fresh verification), then stops for a human checkpoint before the next batch. The checkpointed counterpart to /sprint's autonomous run.
+disable-model-invocation: true
+---
+
+# executing-plans
+
+Coordinate the plan in small, user-acknowledged batches. Routed to by `/feature` after
+`writing-plans` has produced a plan. Each batch is executed by `subagent-driven-development` — fresh
+author agent per task, spec-compliance review, quality review, fresh verification — and the user
+checkpoints between batches. The orchestrator never implements; it schedules and checkpoints.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a path, a command, or a task boundary:
+
+- `<project-root>/.codearbiter/plans/<slug>.md` — the approved plan. The ordered task list and each task's verification command are the contract. No plan, no execution.
+- `<project-root>/.codearbiter/specs/<slug>.md` — the spec the plan implements.
+- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
+- `<project-root>/.codearbiter/tech-stack.md` — the exact verification, test, and build invocations.
+
+## Phase 1 — Batch plan · gate: BLOCK
+
+Group the plan's tasks into small batches. Keep batches tight — three to five tasks is a ceiling, not
+a target. Respect the plan's ordering and dependencies: a task never lands before the task it depends on.
+
+**Resume is the normal re-entry.** A task already `ACCEPTED` in the plan's status column was verified
+before an earlier interruption — exclude it from batching and say so ("resuming: T-01–T-03 already
+ACCEPTED"). Batch only the non-`ACCEPTED` tasks, starting at the first. Never re-execute an `ACCEPTED`
+task, and never restart the pipeline at brainstorming because the session died mid-plan.
+
+For each task, confirm the plan names its exact target paths and its verification command. A task
+missing either is underspecified — return it to `writing-plans`, do not improvise the gap.
+
+Present the batch breakdown to the user as information, not a question: which tasks land in batch 1,
+and what follows. Do NOT stop for a separate acknowledgment — the user approved the plan in
+`writing-plans`, and the first Phase 3 checkpoint arrives after batch 1; a breakdown objection
+surfaces there (or the user interrupts). Each unresolved unknown is a `[CONFIRM-NN]` in
+`open-questions.md` — surface it, do not guess past it.
+
+Gate: a batch sequence exists and every task has a target path and a verification command. A
+`[CONFIRM-NN]` that blocks batch 1 is the only reason to stop here.
+
+## Phase 2 — Execute batch · gate: BLOCK
+
+Invoke `subagent-driven-development` (`<plugin-root>/routines/subagent-driven-development/SKILL.md`) with `scope = [current batch task IDs]`. Pass the plan slug and
+spec slug so it can read its own pre-flight files. Do not implement anything here — the author agents,
+review chain, and verification all run inside that skill.
+
+`subagent-driven-development` returns when every task in the scope is `ACCEPTED` (Phase 3–5 green,
+verification passed on a fresh run). A `tdd` BLOCK, a security CRITICAL finding, or an unresolved
+`[CONFIRM-NN]` surfaced inside that skill halts the loop — surface it to the user and do not proceed.
+
+Gate: `subagent-driven-development` signals batch complete with all scoped tasks `ACCEPTED`. Any
+unresolved halt from inside the skill is a gate failure here.
+
+## Phase 3 — Checkpoint · gate: STOP
+
+Every task in the batch is done and verified. STOP and checkpoint with the user before any further
+work:
+
+- **Landed** — the tasks completed this batch, each verified by `subagent-driven-development` Phase 5.
+- **Next** — the tasks in the upcoming batch.
+- **Open** — any `[NEEDS-TRIAGE]` marker raised inside the batch, any `[CONFIRM-NN]` still blocking.
+
+Do not begin the next batch until the user acknowledges. This gate is the point of `/feature` — the
+human checkpoint that separates it from `/sprint`'s autonomous run.
+
+Gate: the user has acknowledged the checkpoint. On acknowledgement, loop to Phase 2 for the next
+batch. When the final batch is acknowledged and the plan is fully verified, route to `commit-gate` —
+do not commit from here.
+
+## Hard rules
+
+- MUST NOT execute tasks inline — delegate every batch to `subagent-driven-development` with an explicit `scope`.
+- MUST NOT advance past a checkpoint the user has not acknowledged.
+- MUST NOT call `commit-gate` until all batches are acknowledged and every plan task is `ACCEPTED`.
+- MUST surface any halt from `subagent-driven-development` (tdd BLOCK, CRITICAL, CONFIRM-NN) to the user — do not swallow it or re-dispatch around it.
+- MUST NOT absorb scope the plan does not name — mark it `[NEEDS-TRIAGE]`.
+- MUST NOT commit; route to `commit-gate` when the plan is fully verified.
+- MUST return an underspecified task (missing path or verification command) to `writing-plans` — do not improvise the gap.
+- MUST surface a plan-versus-code conflict via `/conflict`, never silently reconcile it.

package/plugins/ca-pi/routines/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: finishing-a-development-branch
+description: The terminal step of /feature and /sprint. Routed to once commit-gate has cleared, to decide the branch's fate — merge via PR, open a PR, or discard. Direct merge to the default branch is forbidden; every change lands through a PR. Under /sprint the skill auto-selects "open PR" and surfaces the merge decision to the user.
+---
+
+# finishing-a-development-branch
+
+The work is committed and green. Now decide where it goes. Routed to by `/feature` and `/sprint`
+after `commit-gate` clears — never before.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess the branch name or the default branch:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — the default-branch name and project context.
+- `<project-root>/.codearbiter/plans/<slug>.md` — the plan this branch executed, when `/feature` or `/sprint` produced one. The yardstick for "is the work complete."
+- `<project-root>/.codearbiter/last-checkpoint` — the most recent gate results; confirms `commit-gate` cleared on this branch.
+
+`commit-gate` MUST have cleared on the current HEAD. If it has not, this skill does not run — return to it.
+
+## Phase 1 — State assembly · gate: BLOCK
+
+Assemble the facts the decision needs. Nothing is presented until all are in hand:
+
+- **Branch** — the current branch name and its base. Confirm it is NOT the default branch; if HEAD is the default branch, STOP — there is nothing to finish and merge-to-default is forbidden.
+- **Diff summary** — files changed, insertions/deletions, and the commit list since the base. Read it, do not paraphrase from memory.
+- **Gate results** — `commit-gate` outcome and the `last-checkpoint` record. Surface any open `[NEEDS-TRIAGE]` markers left in the diff as out-of-scope findings.
+- **Plan delta** — when a plan exists, state which plan items the branch satisfied and which remain open. Open items are surfaced, not hidden.
+
+Gate: branch confirmed non-default, diff summary read, gate results and plan delta in hand.
+
+## Phase 2 — Present terminal options · gate: STOP
+
+Present exactly three terminal options with the Phase 1 state attached, then STOP for the choice:
+
+1. **Open a PR** — push the branch and open a pull request against the default branch, then stop. The PR stays open; the merge happens later, by the user or reviewers.
+2. **Merge via PR** — push the branch, open the PR, and once its checks are green, merge it **through the PR** so the work lands on the default branch now. Distinct from option 1: this one completes the merge. Still PR-only — no direct push to the default branch, no force-push.
+3. **Discard** — abandon the branch.
+
+Under `/feature`: STOP and let the user pick.
+
+Under `/sprint`: auto-select **option 1 (open PR)** and surface the merge decision to the user — `/sprint`
+autonomy ends at the PR boundary. It MUST NOT merge (option 2) and MUST NOT discard.
+
+Gate: a single terminal option is chosen — by the user under `/feature`, or auto-selected as "open PR" under `/sprint`.
+
+## Phase 3 — Execute the choice · gate: BLOCK
+
+Carry out the chosen option, and only that one:
+
+- **Open a PR** — push the branch and open the PR against the default branch. The reviewer path-matrix, the anti-slop PR-body composition (description citing the plan items satisfied, the gate results, the §2 conflict level of any non-obvious tradeoff), and the babysitter attach are the steps documented in the `/ca-pr` command flow (`<plugin-root>/skills/ca-pr/SKILL.md`) — **execute those steps here; do not re-invoke `/ca-pr`** (under `/sprint` this skill is reached via `commit-gate`, without the `/pr` command ever running, so a route back would loop). Leave the PR open; the merge is not yours to take.
+- **Merge via PR** — open the PR as above, confirm its checks are green, then merge it through the PR (squash or merge per project convention) so the work lands. Never push to the default branch directly, never force-push.
+- **Discard** — requires explicit user confirmation naming the branch. Before discarding, verify the branch is fully pushed; if any commit is un-pushed, STOP and report exactly what would be lost — never delete un-pushed work silently. Discard proceeds only after the user confirms with that loss in view.
+
+Gate: the chosen option completed — for open-PR a PR exists against the default branch; for merge the work landed through that PR; for discard the user confirmed against a stated loss summary.
+
+## Phase 4 — Receipt · gate: BLOCK
+
+The loop has been a chain of gates the user watched clear. End it on its most rewarding beat, not in
+silence. Emit a tight **Receipt** — a win summary that reflects the prevention back, drawn ONLY from
+the state Phase 1 already assembled plus `<project-root>/.codearbiter/last-checkpoint`. This is
+**not a fresh audit-trail crawl** — no new log scan, no `git` archaeology. If a field has no data in
+hand, omit the line rather than go digging.
+
+Report only what the assembled state supports:
+
+- **Obligations covered** — the count of `tdd` obligations that reached `COVERED` on this branch.
+- **Gates that fired and what each caught** — the gates that BLOCKed and then cleared, named with the
+  specific thing caught (an untested seam, a scope-creep file set aside), not a bare gate name.
+- **SMARTS decisions the user made** — the architectural forks the user resolved, one line each.
+- **Secrets / regressions prevented** — credential findings and behavioral-proof mismatches the gates
+  stopped before they shipped.
+- **Suite time** — the wall-clock of the verifying run, from the gate results in hand.
+
+Close with **exactly one** warm, synthesizing sentence (per the orchestrator register) that reflects
+the run back — synthesized for this branch, not the register's canned example. One sentence, earned,
+never on a no-op close.
+
+Gate: the Receipt is emitted from in-hand state (no fresh crawl), and the close carries at most one
+warm sentence.
+
+## Hard rules
+
+- MUST NOT merge directly to the default branch or force-push — every change lands through a PR.
+- MUST NOT auto-merge under `/sprint`; auto-select "open PR" and surface the merge decision to the user.
+- MUST NOT discard a branch without explicit user confirmation that names the branch.
+- MUST NOT delete un-pushed commits silently — STOP and report the loss before any discard.
+- MUST NOT run before `commit-gate` has cleared on the current HEAD.
+- MUST NOT guess the branch or default-branch name — read `CONTEXT.md` or STOP.
+- MUST draw the Receipt only from Phase 1 state + `last-checkpoint` — never a fresh audit-trail crawl — and never build a rolling cross-branch "saves" tally.
+- MUST keep the close to at most one warm sentence; never on a no-op close.

package/plugins/ca-pi/routines/post-merge-cleanup/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: post-merge-cleanup
+description: Finish an already-merged branch. Proves the branch is contained in the fetched default, classifies leftover artifacts as unique / redundant / superseded, returns to a clean --ff-only default checkout, and deletes the merged local branch — every discard confirmed per item. Routed to by /ca-cleanup.
+---
+
+# post-merge-cleanup
+
+The walk back from a merged PR. Routed to by `/ca-cleanup`.
+
+The work has landed on the default branch. What is left is local: the branch you
+are standing on, and whatever the run left in the tree. This skill returns you to
+a clean, fast-forwarded default checkout without losing anything you have not
+explicitly agreed to lose.
+
+**It is ordinary lifecycle work and never needs `/ca-override`.** When it
+cannot proceed, it names the gate that stopped it. Issue #308 recorded the
+alternative: with no owner for this transition, the routing loop reached for
+`/ca-chore`, then for `/ca-override` — a bypass manufactured to cover a
+coverage hole.
+
+## Pre-flight
+
+Read this, or STOP and surface the gap — never guess the default-branch name:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — the default-branch name.
+
+If HEAD is already the default branch, there is no transition to make. Report the
+dirty state read-only and exit; branch pruning across *other* branches belongs to
+`/ca-standup`.
+
+## Phase 1 — Prove the merge · gate: BLOCK
+
+A branch that looks merged is not merged. Establish it against the network, not
+against a stale local ref. This repo squash-merges by default, so SHA-ancestry
+alone is the wrong instrument for most landings: it holds for a fast-forward or
+a merge-commit landing, but a squash merge writes a new commit with no SHA
+lineage back to the branch, and `--is-ancestor` will report non-zero for a
+branch that landed cleanly. The gate is **content-containment**, proven by
+whichever instrument fits the landing, always reported as a fact:
+
+1. `git fetch` the remote holding the default branch. A fetch that fails STOPs —
+   an unfetched comparison proves nothing.
+2. Prove containment with two primary instruments plus a fallback, tried in
+   order:
+   1. **Ancestry** — `git merge-base --is-ancestor HEAD origin/<default>`. Holds
+      for a fast-forward or merge-commit landing. If it holds, that is the
+      proof: report it and move on.
+   2. **Squash-merge proof via the PR record** — if ancestry fails, run
+      `gh pr list --head "$(git branch --show-current)" --state merged --json number,state,headRefOid,mergeCommit`.
+      A `MERGED` PR whose `headRefOid` equals local `git rev-parse HEAD` proves
+      every commit on this branch rode that PR's squash into the default
+      branch. Report the PR number, that `headRefOid == HEAD`, the merge
+      commit (`mergeCommit.oid` in that JSON), **and** the ancestry check's
+      negative result — all as facts, not as a failure. Corroborate with
+      `git diff --quiet origin/<default> HEAD` when it happens to hold; a
+      **non-empty** diff alongside a valid PR proof is normal (the default
+      branch advanced since the merge landed) and is reported as a fact, never
+      treated as a failure. The PR-record identity — `MERGED` plus
+      `headRefOid == HEAD` — is the load-bearing proof; the diff is
+      corroboration only when it happens to be fresh, never a requirement.
+   3. **Fallback when `gh` is unavailable or no PR record exists** —
+      `git diff --quiet origin/<default> HEAD` (the tree is byte-identical to
+      the fetched default) is an acceptable fallback proof. Report it as such.
+3. Report whichever instrument held as a fact — the default branch, the fetched
+   SHA, and which of the three proofs established containment.
+
+If none of the three hold, STOP exactly as today. Name the un-landed commits
+and route to `/ca-pr`; nothing is deleted here.
+
+> Deliberate deviation from issue #586's suggested contract: that suggestion
+> required the squash-merge proof's diff to be empty. That requirement
+> re-breaks this gate the moment any later PR merges to the default branch —
+> the common state, not an edge case. The PR-record identity is what proves
+> containment; the diff is corroboration, demoted from requirement to fact.
+
+Gate: the remote is fetched and HEAD is proven contained in the fetched default
+branch — by ancestry, by the PR-record squash proof, or by the byte-identical
+fallback — or the skill has stopped.
+
+## Phase 2 — Classify the residue · gate: BLOCK
+
+List every dirty tracked change, every untracked file, and every stash reachable
+from this branch. Classify each into exactly one of three, and say *why* for each:
+
+- **Redundant** — byte-identical to content already on the default branch, or a
+  regenerated build artifact whose generator is committed and rerunnable. Safe to
+  remove because removing it loses no information.
+- **Superseded** — an earlier form of something the merged PR already landed in a
+  better shape. Name what supersedes it.
+- **Unique** — anything else. This is the default: an artifact that cannot be
+  proven redundant or superseded IS unique. Uncertainty classifies as unique, not
+  as redundant.
+
+Present the classification before touching anything. A file whose class you
+cannot establish is reported as unique with the reason you could not classify it.
+
+Gate: every dirty, untracked, and stashed artifact carries a class and a stated
+reason, with unclassifiable items counted as unique.
+
+## Phase 3 — Resolve the residue · gate: STOP
+
+Per item, in the order Phase 2 listed them. Never batch:
+
+- **Unique** — offer to keep it: `/ca-commit` it on this branch before the
+  transition, move it aside, or leave it in place and stop the cleanup. It is
+  discarded only if the user explicitly confirms *that item by name*, with the
+  Phase 2 reasoning in view.
+- **Redundant / superseded** — offer removal, one confirmation each, stating what
+  it is and why it is safe. Declining leaves it exactly where it is.
+
+A stash is never dropped here. Stashes are reported with `git stash show` as the
+suggested next step, the same report-and-route contract `/ca-standup` holds.
+
+If anything the user chose to keep would block the checkout, STOP and say so
+rather than removing it anyway — but distinguish the two causes before naming
+the artifact as the blocker:
+
+- **The kept artifact genuinely conflicts** — its content collides with what
+  checking out the default branch would need to change or remove. This is the
+  user's to resolve, as today.
+- **The local default ref lags the fetched one** — git refuses a checkout when
+  a locally-modified tracked file differs between HEAD and the target ref, and
+  a stale local `<default>` makes that difference larger than reality: content
+  the kept artifact never actually touches can still collide with what a
+  *current* default branch would carry. That gap is not the user's problem and
+  not the kept artifact's fault. It is resolved by Phase 4's fast-forward-first
+  step, not by discarding anything here. Issue #586 recorded the observed
+  failure mode: a stale local `main` — 513 lines behind on
+  `.codearbiter/gate-events.log` alone — made this STOP name a correctly-kept
+  38-line artifact as the blocker, which invites exactly the silent discard
+  this phase exists to prevent.
+
+Gate: every item is resolved by an explicit per-item decision, and the working
+tree is clean enough to check out the default branch — or the skill has stopped
+with the blocker named, correctly attributed to a genuine conflict or a stale
+local ref.
+
+## Phase 4 — Transition · gate: BLOCK
+
+Only after Phase 3 leaves the tree safe:
+
+1. **Fast-forward the local default ref BEFORE checking it out:**
+   `git fetch origin <default>:<default>`. Git refuses a non-fast-forward
+   update of a ref that is not currently checked out, so the `--ff-only`
+   guarantee is preserved by the instrument itself — this cannot silently
+   rewrite the local default ref, only advance it or refuse. This is what
+   keeps a stale local default from blocking (or worse, misattributing) the
+   checkout below. This step can itself be refused for the same reason a
+   checkout can be — `<default>` checked out in another worktree — in which
+   case report that as the (correctly attributed) blocker, per Phase 3, and
+   stop; do not treat the refusal as license to skip ahead.
+2. Check out the default branch, then **verify the checkout actually happened**
+   (`git branch --show-current`). A checkout silently fails when another worktree
+   holds the branch, and every step after this one would otherwise run against
+   the wrong branch.
+3. Fast-forward with `--ff-only` (belt over the braces of step 1 — a no-op when
+   the pre-checkout fetch already brought the local ref current). A divergence
+   means the default branch moved in a way this skill will not reconcile:
+   report it and stop. Never a merge commit, never a rebase, never a reset.
+
+Gate: the local default ref was fast-forwarded before the checkout — or the
+fast-forward's refusal was itself reported as a fact and the skill stopped —
+HEAD is confirmed on the default branch by re-read, and the belt-and-braces
+`--ff-only` pull either succeeded (typically a no-op) or was reported as a
+refused divergence.
+
+## Phase 5 — Delete the merged local branch · gate: STOP
+
+Offer deletion of the now-merged local branch, with the Phase 1 containment
+proof restated. One confirmation, naming the branch.
+
+- `git branch -d` first, always. Never reach for `-D` on the assumption that a
+  refusal means `-d` can't handle a squash merge — it often can. `git branch
+  -d`'s safety check accepts a branch merged into its **upstream**, not only
+  into HEAD: with an upstream still configured and equal to the tip, `-d`
+  succeeds (with a warning) even for a squash merge that `--is-ancestor` alone
+  would call unmerged. Do not conclude a refusal here means `-D` is required —
+  check the reason first.
+- **The sanctioned `-D` path.** `-d` typically refuses once the remote branch
+  has been auto-deleted and pruned, because there is then no upstream left for
+  `-d` to test reachability against. When that happens, `git branch -D` is
+  permitted, but ONLY when both hold:
+  1. Phase 1's proof, established this run, was the PR-record squash proof
+     (`MERGED` and `headRefOid == HEAD`) — not a bare ancestry pass, not a
+     stale or assumed proof.
+  2. The confirmation restates that Phase-1 proof and explicitly names the
+     branch.
+  Frame this precisely: `-d`'s safety check tests SHA-reachability, and the
+  squash proof has already shown that instrument is the wrong one for this
+  repo's merge mode. The PR-record proof plus a named confirmation **replaces**
+  the check that `-d` can no longer run — it does not bypass it. Everywhere
+  else, `-D` stays forbidden exactly as before: if `-d` refuses and Phase 1's
+  proof was anything other than the PR-record squash proof, report both and
+  stop.
+- The **remote** branch is never touched. If the user wants it gone, that is
+  theirs to do or the platform's auto-delete-on-merge to do.
+
+Declining leaves the branch in place. That is a normal outcome, not a failure.
+
+Gate: the branch is deleted only after an explicit confirmation naming it, via
+`-d`, or via `-D` restricted to the sanctioned path above with the proof
+restated, with the remote untouched.
+
+## Phase 6 — Receipt
+
+One short summary: what landed, what was removed, what was kept, and where HEAD
+is now. State declines as declines — a cleanup the user stopped halfway is a
+correct outcome reported plainly, not an error.
+
+## Hard rules
+
+- MUST fetch and prove `HEAD` is **contained** in the fetched default branch
+  before any deletion — via ancestry, via the PR-record squash proof (`MERGED`
+  and `headRefOid == HEAD`), or, without `gh`, via a byte-identical tree diff.
+  MUST NOT infer merge state from a `: gone]` upstream alone.
+- MUST classify every artifact, and MUST treat anything not provably redundant or
+  superseded as unique.
+- MUST NOT discard a unique or unclassifiable artifact without an explicit
+  confirmation naming that item.
+- MUST confirm every removal and the branch deletion individually — no batched or
+  implied yes.
+- MUST fast-forward the local default ref (`git fetch origin <default>:<default>`)
+  before checking it out, or report the fast-forward's own refusal (e.g.
+  `<default>` checked out in another worktree) as the blocker and stop. MUST
+  re-read the current branch after checkout before acting on it.
+- MUST use `--ff-only`, and MUST NOT merge, rebase, or reset to reach the default
+  branch.
+- MUST use `git branch -d`, and MAY use `-D` ONLY when the Phase-1 squash-merge
+  proof held this run and `-d` refused, with that proof restated and the branch
+  named in the confirmation. Everywhere else `-D` is forbidden. MUST NOT delete a
+  remote branch, force-push, or write to the default branch.
+- MUST NOT drop a stash — report and route, as `/ca-standup` does.
+- MUST NOT route to `/ca-override` when blocked. Name the gate instead.

package/plugins/ca-pi/routines/refactor/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: refactor
+description: The behavior-preserving restructure gate. Routed to by /refactor for a rename, extract, inline, move, dedup, or internal-implementation swap. Six gated phases prove behavioral parity through unmodified pre-existing tests; any diff that classifies as `feat` is not a refactor and is routed to tdd. A modified pre-existing test is rejected as evidence — it is a behavior change in disguise.
+---
+
+# refactor
+
+Restructure, do not rewrite. Externally observable behavior before equals after — proven by mechanism, not inspection. Routed to by `/refactor`.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a command or a threshold:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
+- `<project-root>/.codearbiter/tech-stack.md` — the test, coverage, lint, and type-check invocations; file layout.
+- `<project-root>/.codearbiter/coding-standards.md` — style, structure, naming. Required for Phase 4.
+
+The working tree MUST be clean over the named surface before Phase 1. A dirty surface conflates the refactor diff with unrelated edits and breaks parity verification — STOP and surface it.
+
+## Phase 1 — Surface identification · gate: BLOCK
+
+Enumerate the exact blast radius before any other work. Restate the planned refactor in one sentence and confirm it back to the user, then record a surface table:
+
+- Files (repo-relative paths).
+- Top-level symbols touched — function, class, and exported member names.
+- Public method signatures within those symbols.
+- External consumers — call sites in other modules.
+
+Reject vague surfaces. "the auth module", "the user service", "some helpers in utils" are categories, not surfaces. A surface is acceptable only when a reader could grep the repo for the listed symbols and arrive at the same file set. The table is the parity contract for Phases 2–6.
+
+Gate: a precise, complete surface table, user-signed-off. A vague or category-level surface does not pass — "the functions `signToken`, `verifyToken`, and `rotateKey` in `src/auth/tokens.ts`" passes; "the auth module" does not.
+
+## Phase 2 — Behavioral parity coverage proof · gate: BLOCK
+
+Prove pre-existing tests already exercise the named surface well enough to detect a behavior change, before any production code is touched. Locate every test that exercises a symbol in the surface table. Run the coverage command from `tech-stack.md` scoped to the surface files; record line, branch, and per-symbol coverage.
+
+Coverage scales with the maturity value (`stage:` in `CONTEXT.md`) — the same knob as `tdd` Phase 5,
+using the shared threshold table `<plugin-root>/includes/maturity-coverage.md`.
+
+Every public method in the surface table MUST have at least one direct test — transitive coverage through a higher-level integration test does not count. A public method with zero direct tests is uncovered for this gate.
+
+**Lines and branches must both clear the threshold** (issue #507); a surface satisfying one and not
+the other is not proven. Where the surface has no coverage tooling, take the no-tooling exemption in
+`<plugin-root>/includes/maturity-coverage.md` — it requires QUOTING the `tech-stack.md` Coverage
+section that omits a command for this surface — and the per-symbol direct-test proof stands alone.
+Without that citation the phase STOPs rather than passing on an unverifiable claim.
+
+If surface coverage is below the maturity threshold on either metric, OR any public method has zero direct tests, halt and route to the `tdd` skill (`<plugin-root>/routines/tdd/SKILL.md`) Phase 1 to backfill obligations and red tests for the uncovered surface. Resume Phase 2 only after the backfill is green.
+
+Gate: surface coverage at or above the maturity threshold on BOTH lines and branches AND every public method backed by a direct test. Otherwise backfill via `tdd` Phase 1 before retrying.
+
+## Phase 3 — Red parity tests (conditional) · gate: BLOCK
+
+Pin any new test seam the refactor exposes before implementation. A new seam is one of: a newly exported symbol that did not exist; a new public method signature on an existing class; a previously private function promoted to module-public.
+
+If the refactor exposes no new seam, record "No new seams" and skip to Phase 4. Otherwise, for each seam write one or more tests that pin its contract. These tests MUST be red before implementation, and every pre-existing test MUST stay green. A seam test is scoped strictly to the restructure — it MUST NOT require behavior beyond what the original code already produced. A seam test that needs new behavior to pass means the work is a feature: route it to `tdd` and abort.
+
+Gate: either "No new seams", or failing seam tests with all pre-existing tests still green. BLOCK if a proposed seam test requires new behavior, or if any pre-existing test breaks as a side effect of writing the seam tests.
+
+## Phase 4 — Implementation · gate: BLOCK
+
+Apply the restructure with zero behavior change, to the conventions in `coding-standards.md`. Confine every edit to the surface table. Acceptable edits: rename symbols (with consumer updates); extract or inline functions and methods; move symbols between files; replace an internal implementation with an equivalent one; collapse or split modules where the public interface is preserved.
+
+Unacceptable inside a refactor: adding a behavior, branch, error path, or side effect; changing the value any public method returns for any pre-existing input; adding a public method beyond a Phase 3 seam; changing observable order of operations (event emission, logging, IO). Classify the resulting staged diff against `commit-gate` classification criteria — a diff that classifies as `feat` is not a refactor; halt and route to `tdd`.
+
+Gate: the refactor confined to the surface table, with any Phase 3 seam tests now green. BLOCK if the diff classifies as `feat`, or if any edit falls outside the Phase 1 surface table without an explicit user-approved amendment.
+
+## Phase 5 — Parity verification · gate: BLOCK
+
+Run the full project test suite from `tech-stack.md`. Every pre-existing test from Phase 2 MUST pass with NO modification to its source — inspect the diff and confirm zero edits to any pre-existing test file. A modified pre-existing test is, by definition, evidence the surface's observable behavior changed: revert it. If it cannot pass after revert, the refactor introduced a behavior change and is routed to `tdd` as a feature or fix. Phase 3 seam tests (if any) MUST pass. Record the pass/fail tally and any modified-test detection.
+
+Gate: full suite green with zero pre-existing tests modified. BLOCK if any pre-existing test was modified to pass, or if any test fails.
+
+## Phase 6 — Lint and coverage · gate: BLOCK
+
+Run lint, the type-check if the project is statically typed, and coverage, all from `tech-stack.md`. Resolve every lint and type error. Confirm surface coverage remains at or above the maturity threshold on both lines and branches — a refactor MUST NOT reduce coverage of the surface it touched on either metric.
+
+Where the surface has no coverage tooling, the same clause as Phase 2 applies — the no-tooling exemption in `<plugin-root>/includes/maturity-coverage.md`, citation included — and parity is verified through Phase 5's unmodified pre-existing tests alone. Phase 2 and Phase 6 MUST NOT give different answers about the same surface, which is why both defer to the one shared clause rather than restating its conditions.
+
+Gate: clean lint and type-check, zero errors, and no coverage regression on the named surface. "Mostly passes" is not passing — this is what clears the path to `commit-gate`.
+
+## Hard rules
+
+- MUST NOT begin Phase 2 without a precise, user-signed-off surface table.
+- MUST NOT proceed past Phase 2 if surface coverage is below the maturity threshold or any public method has zero direct tests — route to `tdd` Phase 1 to backfill.
+- MUST NOT introduce new behavior in Phase 4. A diff that classifies as `feat` under `commit-gate` is not a refactor.
+- MUST NOT modify any pre-existing test to make it pass. A modified test is a behavior change.
+- MUST NOT reduce coverage of the named surface during the refactor.
+- MUST NOT extend the surface mid-flight without an explicit user-approved amendment to the Phase 1 table.
+- MUST NOT inline-suppress a lint rule to clear Phase 6, and never to bypass a security-relevant rule.
+- MUST NOT guess the test, coverage, lint, or type-check command — read `tech-stack.md` or STOP.