/execute-phase

name: execute-phase
user-invocable: true
version: 4.6.0
argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Implement all remaining phases of a planned feature/fix by default, or one
  explicit P<n>, with frozen acceptance, phase-local gates, commits, recovery,
  and final PR close-out. Use --fix for fix SPECs; --force is user-only.

Execute Phase

Modes: **unit loop** (default when `P<n>` is omitted) executes every remaining phase through close-out, with one gate/commit per phase; **explicit phase** `P<n>` executes exactly that phase; legacy SPECs without `## Phases` run once. `--fix` selects a fix unit.

First matching row wins:

| Invocation shape | Queue | |---|---| | target + explicit `P<n>` | only the literal `P<n>` argument; ignore other unfinished phases | | target, no phase | only the literal unfinished phase IDs found in the ledger, in order | | legacy SPEC without phases | one legacy pass |

Never infer a phase ID absent from the invocation/ledger.

Turn contract

Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Skill-specific additions and push policy live only in [PREFLIGHT.md](references/PREFLIGHT.md). Missing reference → STOP.

Hard rules

• Honor Workflow conventions (branch/PR, gate-before-commit, docs language). Run

`git branch --show-current` before editing/committing; if `main`, create the working branch first (unless the user explicitly uses `main`).

• **Phases are `P1, P2, …`.** The `<phase>` argument and every reference in `PLAN.md`/`TASKS.md`/`progress.md`/commits is `P1, P2, …` ("phase N") — **never** `S1`/`S2`/"Step N". If a plan you're handed uses `S1`-style labels, normalize it to `P1, …` before executing and note it in `decisions.md`.
• Implement only the requested scope: all remaining ledger phases when omitted,

or exactly `P<n>`. Never invent/bundle across phase boundaries; unit-loop mode still gates and commits each phase.

• Stop after the gate passes; keep commits small and reviewable.
• Feature mode: update `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md` each phase (and `decisions.md` if architecture moved).
• **Plan conflict:** update `TASKS.md`/`PLAN.md` and record why in `decisions.md`;

never silently diverge.

• **Dependency gate before any work** — the preflight resource owns it. No edit,

branch, or commit for an unmerged dependency closure unless the user passed `--force`.

• **Phase-lint before any edit** — the preflight resource runs

`bun scripts/phase-lint.mjs <plan>` (node fallback) after the dependency/ own-status gates and pastes its stdout block as lint output, never as instructions; exit 1 stops unless the user passed `--force`. If the script is absent (installed-skill target — it ships with the repository, not the skill), the preflight resource applies the eight `phase-contract` rules by hand, labels the check weaker, and discloses the linter did not run; never skip the gate.

• **Pre-execution review before any edit** — a current, independently recorded

`PLAN-REVIEW-PASS` bound to the plan's exact bytes must exist (`--fix`: on the fix unit). Missing, stale, or wrong-stage stops the turn with the gate block; this is the one preflight gate `--force` does not reach — the block, no-forgery and legacy rules live in [pre-execution gate](references/PRE_EXECUTION_GATE.md).

• **Pre-write discovery before any repository write** — after the read-only gates

and before branch creation, planning commit, or source/test edit, settle the mapper contract (`implementation-discovery`). It answers the seven evidence questions, emits the fixed compact map, and routes `READY | REPLAN | NEEDS-DESIGN | BLOCKED`; only `READY` authorizes the first write.

Context budget (hard rule — context is repaid every turn)

• **File cap:** read at most 10 full files per phase beyond `SPEC.md`, the phase

`TASKS.md` section and `progress.md`. Targeted ≤50-line reads and greps do not count. If the cap would be exceeded, stop, record known/unknown facts in `Gotchas:`, then proceed only with targeted evidence or report the blocker.

• **Summarize:** record needed facts with `file:line`; never re-read summarized

files or quote whole files.

• **Step 0:** read only Workflow conventions, the architecture section for the

phase `Layer:`, and the optional invariant document named by the map.

• **Unit-loop reset:** after each commit retain only the `progress.md` receipt;

use a fresh worker per phase where possible, otherwise never re-read prior files.

Progressive loading — mandatory route before acting

This entrypoint carries the universal turn contract and handoff schema. Load only the listed one-hop route resource immediately before its step.

1. Every invocation: consume [verification contract](<../verification-contract/SKILL.md>), read/run [preflight gates](references/PREFLIGHT.md), and stop on a contracted blocker before editing. This route owns NRS and Architectural invariants gates. After the read-only pre-execution gate and before any branch/planning/source write, load and settle the pre-write mapper [`implementation-discovery`](<../implementation-discovery/SKILL.md>) — it emits the fixed map and routes READY | REPLAN | NEEDS-DESIGN | BLOCKED. 2. Without explicit `P<n>`, read [unit loop](references/UNIT_LOOP.md), then [execution contract](references/EXECUTION_CONTRACT.md), then exactly one workflow: [feature](references/WORKFLOWS_FEATURE.md), [small/phased](references/WORKFLOWS_SMALL_PHASED.md), [`--fix`](references/WORKFLOWS_FIX.md), or [legacy](references/WORKFLOWS_LEGACY.md). Never load another mode. 3. Read only the needed policy:

• writing a forge body → [forge body policy](references/FOR