execute-phase · diff
v4.8.0 to v5.0.0
191 added, 106 removed. Audit A to A.
---
name: execute-phase
user-invocable: true
- version: 4.8.0
- argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
+ version: 5.0.0
+ argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
author: "Gabriel Trabanco <1969593+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.
+ Step executor for units whose triage (unit-lane) decided which steps the unit
+ needs. Implements one triaged step (or all remaining steps), with frozen
+ acceptance, step-local gates, commits, red-gate repair, and diff-size guard.
+ BREAKING: replaced PLAN.md/TASKS.md/progress.md/ACCEPTANCE.md with the unit
+ doc's Tasks section, Evidence rows, and Progress log; ACCEPTANCE.md is gone —
+ acceptance criteria live in the unit doc and Evidence rows are the receipts.
---
# 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:
+ Step executor for units. The unit doc (created by `unit-lane`) owns `Tasks` P1…Pn,
+ `Evidence` rows, and a `Progress` log — these replace PLAN.md, TASKS.md,
+ progress.md, and ACCEPTANCE.md. Each step runs as an atomic gate/commit.
- | 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 |
+ **Argument resolution (first match):**
+ - `<NN-slug> P<k>` — exactly the step named by the triage order (P1, P2, …)
+ - `<NN-slug>` (no step) — all remaining steps, one commit each
+ - `P<k>` alone — the step by position in the current unit (last-known NN-slug)
- Never infer a phase ID absent from the invocation/ledger.
+ Never infer a step ID absent from the triage block in the unit doc.
## 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.
+ Tick every box before ending the turn; an unchecked box means the turn is not
+ done:
- ## Hard rules
+ ```
+ ✓ Triage verified — unit doc Evidence section header matches
+ `bun scripts/unit-route.mjs --triage <slug>` output block (PREFLIGHT.md)
+ ✓ Unit doc read and step selected (explicit P<k> or first unfinished)
+ ✓ Step executed and committed (one commit per step, conventional format)
+ ✓ Evidence rows updated (command → exit/digest → output → verified-by)
+ ✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry (what, commit, next)
+ ✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
+ ✓ → Next: block printed as the absolute last output
+ ```
- - 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.
+ ## When to use
- ## Context budget (hard rule — context is repaid every turn)
+ - A triaged unit from `unit-lane`: steps include `implement`/`tests`/`evidence`
+ → invoke with `<NN-slug>` or `<NN-slug> P<k>`.
+ - Docs-only units (triage returns only `[docs, evidence]`) do **not** load this
+ skill — they are executed in-place by the unit-lane conductor.
+ - To execute all remaining steps: `<NN-slug>` with no step argument.
+ - To repair a failed step: `<NN-slug> P<k>` (retry the same step).
- - **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.
+ ## Step 0 — Discover the project
- ## Progressive loading — mandatory route before acting
+ Per the agent guide's **Workflow conventions** + **documentation map**, read the
+ unit doc at `docs/features/<NN-slug>/SPEC.md`. Verify it carries `## Tasks` (P1…Pn),
+ `## Evidence`, and `## Progress` sections. If absent, the unit is not ready —
+ stop and suggest `unit-lane` triage first.
- This entrypoint carries the universal turn contract and handoff schema. Load only
- the listed one-hop route resource immediately before its step.
+ ## Process
- 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/FORGE_BODY.md)
- - creating an issue → [descope guard](references/DESCOPE.md) first
- - finding out-of-scope work → [opportunistic finding policy](references/OPPORTUNISTIC_FINDING.md)
- 4. Before `progress.md`, read [handoff schema](references/HANDOFF.md).
- 5. For implementation/finish, read [closeout](references/CLOSEOUT.md); for a
- folded finding also [folding](references/FOLDING.md).
- 6. Only for `/loop`, external drivers, manual batching, or missing vendor
- primitives, read [batch and portability](references/BATCH_AND_PORTABILITY.md).
+ ### 1. Verify triage currency
- Fixed blocks in selected resources are normative and copied exactly. Missing or
- unreadable required resource → STOP; never reconstruct from memory.
+ Run `bun scripts/unit-route.mjs --triage <slug>` and compare its block to the
+ Evidence section header in the unit doc. **Mismatch → STOP and re-triage first.**
+ This is the gate that ensures the executor and unit-lane agree on steps.
- ## Portability
+ ### 2. Select the step
- The contract is vendor-neutral. When slash commands, tiers or a loop primitive
- are absent, read [batch and portability](references/BATCH_AND_PORTABILITY.md) and
- use its fallback; never skip the workflow step.
+ If a step argument is given (e.g. `P2`), use that step. Otherwise, the **first
+ unfinished step** — the first P<k> in `Tasks` whose checkbox is unticked.
+ Never execute a step the triage skipped.
+ ### 3. Pre-step gates
+
+ Run gates in order; any fails → STOP (see [PREFLIGHT.md](references/PREFLIGHT.md)):
+
+ 1. **Path-protection checkpoint** — read the committed range against protected
+ paths (e.g. `tests/`, `fixtures/`). Exit 1 → STOP with the gate rejection
+ block. No `--force` bypass (no flag can override).
+ 2. **Phase-lint** — run `bun scripts/phase-lint.mjs <unit-doc>` **only** when the
+ step is `implement` and the unit has `Tasks` P1…Pn. Parse the `Tasks` section
+ (not PLAN.md/TASKS.md). Exit 1 → STOP. If the script is absent, apply the
+ eight `phase-contract` rules by hand, label weaker, and disclose.
+ 3. **Dependency/invariant checks** — per unit-lane's triage catalog rules:
+ ensure required dependencies are merged; architectural invariants preserved
+ or backed by an explicit recorded decision (block `violates`/`introduces`/
+ `changes` before edits).
+
+ ### 4. Execute the step
+
+ Follow the unit-lane reference for this step (`references/STEPS.md` catalog):
+ one line — read the step's reference file, perform its checklist, commit the
+ work. For `implement` steps: write tests-first where they pay (core/domain,
+ orchestration — record the failing red run's command, exit, and failing test
+ names before implementation), then green. UI/adapter glue may test after.
+
+ ### 5. Post-step
+
+ 1. **Diff guard** (implement steps only): run `bun scripts/diff-guard.mjs --base
+ <last-step-commit> --unit <unit>` — paste the block verbatim. **BREACH → STOP**
+ (re-triage or record exception). Anti-gaming: **NEVER shrink a diff by deleting
+ comments, blank lines, docs or tests.**
+ 2. **Evidence rows**: one row per AC satisfied — `| AC | command | exit/digest |
+ output (≤2 lines) | verified-by |`. Append to the Evidence section.
+ 3. **Progress log**: append a dated entry —
+ `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
+ 4. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
+ <step-summary>"` — run it, paste the SHA.
+
+ ### 6. Red gate (repair loop)
+
+ After each step: run the project's verification gate (type-check + tests + build).
+
+ - **Gate green** → proceed.
+ - **Gate red** → record exit code + failing test names in the Progress log, repair
+ the same step, retry. Default `--max-attempts 3` (user value overrides).
+ - **Exhausted** → STOP with:
+
+ ```text
+ UNIT LOOP — <unit> BLOCKED at <P<k>>
+ Reason: <NO-PROGRESS|ATTEMPT-BUDGET> · Attempts: <n>
+ Last validator: <command> → <exit/status + compact failure>
+ Preserved: no red commit; acceptance blob <sha> unchanged
+
+ → Next: inspect the named blocker, then re-run /execute-phase <unit> <P<k>>
+ · architecture/product decision required → resolve it before resuming
+ · continue atomically → /execute-phase <unit> <P<k>>
+ ```
+
+ ### 7. Whole-unit mode
+
+ When invoked as `<NN-slug>` with no step: loop all remaining steps, one commit
+ each. After each step: gates, execute, diff guard (if implement), evidence/
+ progress update, commit. Skip intermediate review checkpoints; the mandatory end
+ review covers the full accumulated diff. On gate red at any step: repair that
+ step (up to `--max-attempts`), then continue the loop. Terminal:
+
+ ```text
+ UNIT LOOP — <unit> COMPLETE
+ Steps: <n> · Commits: <sha list> · Gate: PASS
+ PR: <url>
+
+ → Next: /review-change on the changed HEAD — the mandatory end review
+ · findings (REVIEW-FAIL) → /fold-findings, then re-run /review-change
+ · merge gate after REVIEW-PASS → /audit-pr
+ ```
+
+ ### 8. Descope guard
+
+ Before creating **any** issue while executing: classify with the descope test.
+ A descope (moving an acceptance criterion or task out of scope) requires
+ **explicit user approval first**, then record in the unit doc's
+ `## References` section (not a follow-up issue) as:
+ `- <YYYY-MM-DD> — descoped: "<criterion>" — approved by user`.
+ An issue may never be the first record of a descope.
+
+ ## Required references
+
+ These files must be loaded when their topic is active:
+ - [PREFLIGHT.md](references/PREFLIGHT.md) — all gate blocks (dependency, status, pre-exec, evidence, lint, path-protection)
+ - [EXECUTION_CONTRACT.md](references/EXECUTION_CONTRACT.md) — step completion gate, architectural invariants
+ - [PRE_EXECUTION_GATE.md](references/PRE_EXECUTION_GATE.md) — pre-execution review gate, normalizer order
+ - [FOLDING.md](references/FOLDING.md) — review finding fold cycle
+ - [DESCOPE.md](references/DESCOPE.md) — descope test and amendment rule
+ - [FORGE_BODY.md](references/FORGE_BODY.md) — forge operations (gh body-file rule)
+
+ ## Guardrails
+
+ **Allowed:**
+ - Only the triaged steps listed by the unit doc's Evidence header
+ - Changes scoped to the acceptance criteria and step tasks
+ - Documentation updates in the unit doc (Evidence, Progress, References)
+ - Conventional commit messages per the project's Workflow conventions
+ - The step's own reference file (read one-hop from the unit doc catalog)
+
+ **Forbidden:**
+ - Never commit red (test failure) — fix within the step's scope, or record the
+ blocker and stop.
+ - Never weaken a validator (loosen assertions, reduce coverage) — a repair must
+ keep assertions at least as strong.
+ - Never execute a step the triage skipped — the catalog is authoritative.
+ - Never edit the unit doc's Acceptance criteria (that is re-triage with user consent).
+ - Never expand scope beyond what Non-goals define — findings discovered during
+ implementation never widen the unit.
+ - Never invent an acceptance criterion — ask the user with concrete options.
+
## Relationship to other skills
- Planned by `plan-feature`/`plan-fix`; executes their SPEC. Explicit phases may
- hand off to `review-change` at layer/accumulation/sensitivity checkpoints and must
- at unit end. Unit-loop skips intermediate checkpoints and recommends the manual
- `/review-change` → `/fold-findings` (only on `REVIEW-FAIL`) → re-run
- `/review-change` path after opening the PR; `review-change` remains the manual
- entry.
- Independent work stays a proposal. A finished unit always opens its PR and flips
- to `done`; `audit-pr` gates merge. Every invocation prints the next step.
+ `unit-lane` conducts (triage → steps → doc updates); this executes (one step at a
+ time or all remaining). `fold-findings` handles review finding repairs. The review
+ pack axes (`review-implementation`, `review-code`, `review-security`, `review-perf`,
+ `review-a11y`, `review-debt`) compose the review step; `workflow-status` routes
+ here. `triage-issue` feeds issues into the lane. This skill is the **step executor**
+ a turn invokes to perform one triaged step of a unit under the full gate machinery.
+ ## Portability (agents other than Claude Code)
+
+ - **No slash menu** — open this `SKILL.md` and follow it literally in a fresh
+ conversation. Where it says `run`, execute the shell command directly.
+ - **No model tiers** — triage and review use the strongest model; execution
+ steps may use cheaper. Never review with a weaker model than the author.
+ - **No `/loop`/subagents** — invoke `<NN-slug>` for all remaining steps (the
+ built-in loop), or `<NN-slug> P<k>` for individual steps.
+ - **No fresh workers** — execute inline and reduce state to the unit doc after
+ each commit; never re-read prior files.
+
## Done when
- - Requested scope is implemented (all remaining phases, one explicit phase, or
- legacy pass), gate is green, per-phase docs are updated, and the work is
- committed on the correct branch with nothing bundled beyond scope.
- - `git status --porcelain` is empty and an open-PR branch has nothing unpushed.
- - A finished unit is `done`, has an opened PR (URL printed), and recommends the
- mandatory `/review-change` end review, then `/fold-findings` (only on
- `REVIEW-FAIL`) and a re-run `/review-change`, with `/audit-pr`
- as the merge gate.
+ - Requested scope is implemented (all remaining steps, one explicit step), gate
+ is green, unit doc Evidence/Progress are current, and the work is committed.
+ - **The closing `→ Next:` block is printed.**
+ ## Closing recommendation
+
+ ```
+ → Next: /unit-lane <NN-slug> — the conductor continues with the next triaged step
+ · all steps done → /review-change — the mandatory end review
+ · findings (REVIEW-FAIL) → /fold-findings, then re-run /review-change
+ · merge gate after REVIEW-PASS → /audit-pr — the merge gate
+ ```