/execute-phase

name: execute-phase
user-invocable: true
version: 4.10.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: >
  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

> **Runner commands** below are `bunx @gtrabanco/agentic-workflow@<pin> …` — read `<pin>` > from [references/RUNNER.md](../runner-contract/references/RUNNER.md). It is stamped at > release and never guessed: a hard-coded version re-opens the per-release sweep the > contract removes, and `latest` is not a legal pin.

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.

**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 step ID absent from the triage block in the unit doc.

Turn contract

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn; the contract's Push policy supplement governs mid-phase commits when a PR is already open. Skill-specific additions (the `→ Next:` box is canonical-owned and not restated here):

✓ Required user inputs were answered concretely (not defaulted). Nothing here
  is inferred: a gap runs `bunx @gtrabanco/agentic-workflow@<pin> needs-input <unit-dir>` (npx fallback
if bun is not installed) and the
  `open-questions@1` block is pasted, then the run stops.
✓ Tool choice re-made this turn — `bun` before `node` on manual invocation,
  `rg` before `grep` on search; availability checked once with
  `node scripts/setup-env.mjs --check` (node and grep stay the documented fallback)
✓ Triage verified — unit doc Evidence section header matches
  `bunx @gtrabanco/agentic-workflow@<pin> unit-route --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)
✓ Phase read set consumed — the phase read its `Relevant files:` targets
  (`bun scripts/relevant-files.mjs <unit-doc> --phase P<k>`) instead of
  surveying the repo, and discovered-file appends landed at phase close
✓ Test impact derived — the phase's test set came from the hint's block
  (TEST_IMPACT.md), and a prose-only phase recorded its `empty` verdict
✓ Evidence rows updated (command → exit/digest → output → verified-by)
  — each row carries the command, observed output (reproduced, not typed by
  hand), and the verifying-by credit. (S5 — claim-evidence loop: mandatory
  reproduction, loop-until-green inside the same turn)
✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
  phase id (what, commit, next)
✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
  or the mirror marked pending when the layer is degraded
✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
✓ Self-audit box (S9 d): every claim the persist introduces was re-derived
  with pasted output before the commit lands.

When to use

• 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).

Inputs — artifacts, never questions

This skill **never interviews**. It reads its inputs — the unit doc's `Tasks`, `unit-route.mjs --triage`'s block, the route's tier — and a missing or ambiguous one is a **gap**, resolved in one fixed order and never by inference: **(0) provenance** (search the repo's own docs and record where) → **(1) research** (2–3 concrete options with trade-offs; asking for more research is a legitimate answer) → **(2) halt**: run `bunx @gtrabanco/agentic-workflow@<pin> needs-input <unit-dir>` (npx fallback if bun is not installed), paste the `open-questions@1` block verbatim, stop. Interactive the block is the pause point, unattended it is a hard fail. Grammar and exit codes: `orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open questions.

Bare `<NN-slug>` runs **all remaining steps** — the phase is not an input. File targets are the unit doc's nested `Relevant files:` metadata plus the path-protection checkpoint. `--max-attempts N` defaults to 3; `--force` skips the *stop* on the dependency and phase-lint gates (never the check — `PREFLIGHT.md` records the override in the Progress log) and has **no bypass** on the path-protection checkpoint.

Step 0 — Discover the project

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) **and the receipt sections of the shape it is written in** (#308 accepts both): the legacy shape carries `## Evidence` + `## Progress log`, a re-cut unit doc carries `## Specs`, `## Findings` + `## Log` (its evidence and gate runs are `E`/`G` log lines, its progress is `P` lines). If neither pair is pr