git:20260514.783f189 to git:20260916.cadb06c

---

name: execute

argument-hint: "<--session <uuid> | --plan <text|path> --title <title> | --review-only> [--stop-after <stage>] [--handsfree] [--accept-external-state]"

description: >

Run the execution + quality polish + delivery stages of review-loop

against one of three entry modes: resume an approved session

(`--session`), execute a user-supplied plan (`--plan`), or run a

pure-CR pass on the current working tree (`--review-only`). Supports

batched runs via `--stop-after <stage>`. Use when you already have a

plan, or only want CR on existing code.

---

# execute — Execution + Polish + Delivery Sub-Skill

Drive an approved / user-supplied / review-only plan through the

execution loop, quality polish (Step 3.5), docs consistency (3.6),

security preflight (3.7), and delivery (Step 4). Supports multi-batch

runs via `--stop-after <stage>` and the unsafe `--accept-external-state`

opt-in.

## Protocol Imports

The Orchestrator MUST Read each of these files at start. They are the

single source of truth for this skill's execution loop and output

schemas.

- `docs/protocol/session-file.md`

- `docs/protocol/execution.md`

- `docs/protocol/executor-output.md`

- `docs/protocol/reviewer-output.md`

Do not re-derive any rule that already lives in a protocol doc. When a

step below says "see `docs/protocol/<doc>.md` §Foo", follow that doc

verbatim.

The startup read set is complete only after all 4 docs above have been read

explicitly; the embedded executor/reviewer prompt bodies are not a substitute

for reading `executor-output.md` and `reviewer-output.md`.

## Orchestrator rules

- **Plugin agent-type sandbox bug**: every Executor / Reviewer / quality

agent invocation MUST use `subagent_type: general-purpose` with the

agent's full `.md` body inlined in the `prompt` parameter. Never use

`subagent_type: review-loop:<name>`. See `CLAUDE.md` §"Plugin agent

type sandbox bug".

- **Unsupported `--stop-after` values are rejected at parse time**,

before any lock is acquired or session field is written. The

Orchestrator must not modify the session file or create the lock

until flag parsing has succeeded.

- Only the Orchestrator writes to the session file. Sub-agents read.

- Live Reports after each round are not optional.

## Invocation — three mutually-exclusive entry modes

Exactly one of the three entry flags must be supplied. Supplying more

than one is a parse error; the Orchestrator exits without touching the

session file or the lock.

```

# Entry mode 1 — resume an approved session

run execute: --session <uuid> [--stop-after <stage>] [--handsfree] [--accept-external-state]

# Entry mode 2 — execute a user-supplied plan verbatim

run execute: --plan <text|path> --title <...> [--description <...>] [--stop-after <stage>] [--handsfree] [--accept-external-state]

# Entry mode 3 — pure code-review over the current working tree

run execute: --review-only [--description <what was done>] [--stop-after <stage>] [--handsfree] [--accept-external-state]

```

---

## Step 0 — Parse and validate flags

Before parsing flags or touching session state, Read the 4 Protocol Imports

docs listed above.

Execute before any lock or session write.

1. **Entry-mode mutual exclusion**: count how many of `--session`,

`--plan`, `--review-only` are present. If ≠ 1 → print usage and

exit with non-zero.

2. **`--stop-after <stage>`**: validate against the Claude Code full

supported set (per `docs/protocol/execution.md`

§Runtime-supported subsets):

- `exec-round`

- `before-polish`

- `before-docs`

- `before-security`

- `before-delivery`

- `delivery` (default when flag is absent)

Any other value → reject at parse time. Error message must list the

supported subset. Do **not** create the lock, do **not** touch the

session file.

3. **`--handsfree`**: enable handsfree mode for this invocation.

Handsfree alone does NOT auto-accept drift — see `--accept-external-state`.

4. **`--accept-external-state`**: **unsafe opt-in**. Auto-selects "(A)

accept" wherever `docs/protocol/session-file.md` instructs the

Orchestrator to pause-and-confirm (drift check step 4; backward-compat

missing-baseline fallback). Documented as unsafe: the user is opting

out of pausing on external tree drift. The flag has no effect outside

those two prompts — it does not bypass unmerged-conflict errors,

unknown-git-state errors, or per-stage hard-stops.

5. **Config load**: read `.review-loop/config.md` if present; otherwise

use defaults from `skills/review-loop/SKILL.md` §Configuration.

6. **Reviewer backend availability**: same probe as `plan` skill

(`which codex` for `reviewer: codex`).

## Step 0.5 — Resolve target UUID (no writes yet)

Compute the session UUID so the lock path is known; **do not read or

write the session file yet** — the single-writer lock must come first

per `docs/protocol/session-file.md` §Lock file lifecycle.

- `--session <uuid>`: adopt the UUID the user supplied. Confirm the

path is well-formed (`.review-loop/sessions/{uuid}.md`). Do not Read

the file content yet.

- `--plan <text|path>`: generate a fresh lowercase UUID.

- `--review-only`: generate a fresh lowercase UUID.

Flag parsing (Step 0) and `--stop-after` validation have already

completed; those steps are intentionally pre-lock per the `--stop-after`

design-spec requirement and `docs/protocol/execution.md`

§Parse-time validation.

## Step 1 — Acquire the single-writer lock

Per `docs/protocol/session-file.md` §Lock file lifecycle. **Every

subsequent read and write of the session file (creation, resume-time

re-baselining, round updates) must happen under this lock.** Summary:

- `.review-loop/sessions/{uuid}.lock` — PID, ISO-8601 `started_at`,

`entry_point`, `stop_after`.

- No lock → proceed. Lock present + PID alive → refuse. Lock present +

PID dead → prompt-to-recover.

- Release on every clean exit path (delivery, `--stop-after` stop,

signal abort trap, unrecoverable error trap).

## Step 1.5 — Initialize or resume the session (under the lock)

Per the entry-mode initialization table in

`docs/protocol/session-file.md` §Entry-mode initialization table. All

reads and writes below happen **after** Step 1 acquired the lock.

`entry_point` is set once on session creation per

`docs/protocol/session-file.md` §Session Metadata schema; `--session`

resumes preserve the original value.

### Mode: `--session <uuid>`

1. Read `.review-loop/sessions/{uuid}.md`. If the file is missing →

release the lock and exit with an error.

2. Preserve all existing canonical content.

3. Respect backward-compat fallback: if any baseline quintet field is

missing, pause-and-prompt per

`docs/protocol/session-file.md` §Backward-compat fallback.

`--accept-external-state` auto-picks (A). Handsfree alone blocks.

The `entry_point` backfill rule for legacy sessions also lives in

`docs/protocol/session-file.md` §Session Metadata schema; this

skill defers to the protocol doc rather than re-stating it here.

### Mode: `--plan <text|path>`

1. Create `.review-loop/sessions/{uuid}.md` with the `--plan` column of

the init table:

- `## Approved Plan` → `- Source: user-supplied` followed by the

user's free-form plan text injected verbatim. If `--plan` was a

path, read the file and inject its contents; if it was inline

text, inject directly.

- `## Current Phase: execution`.

- `## Context` = `"User-supplied plan; no planning-phase context

captured."` + any `--description`.

- `## Acceptance Criteria` = `"Implementation matches the

user-supplied plan in ## Approved Plan."`.

2. Write `## Session Metadata`:

- `entry_point: execute-from-plan`

- `plan_source: user-supplied`

- Fresh baseline quintet (`base_head`, `base_dirty`, etc.) from

current repo state.

3. This mode drives **provenance-aware reviewer behavior**: during

execution rounds the reviewer's plan-conformance deviations are

advisory / MINOR per `docs/protocol/execution.md` §Provenance-aware

reviewer prompts, `plan_source: user-supplied` block. Correctness +

intent-alignment are still enforced strictly.

### Mode: `--review-only`

1. Create `.review-loop/sessions/{uuid}.md` with the `--review-only`

column of the init table:

- `## Approved Plan` → `- Source: review-only` followed by the

**two-line canonical sentinel** exactly as documented in

`docs/protocol/session-file.md` §Canonical sentinel for

`review-only`:

```

(none — review-only mode)

Scope: see `## Review Target` section below.

```

No other text goes into the body.

- `## Review Target` (non-canonical supplemental section) is

populated from the user's `--description` / scope arguments.

- `## Current Phase: execution`.

- `## Files Changed` — populated from the actual post-open dirty set

(read-only snapshot).

2. Write `## Session Metadata`:

- `entry_point: review-only`

- `plan_source: review-only`

- Fresh baseline quintet from current repo state.

3. The execution loop **skips the first Executor round** per

`docs/protocol/execution.md` §`--review-only` first-round skip.

## Step 2 — Drift check

Per `docs/protocol/session-file.md` §Drift-check decision tree (5

steps). For `--plan` and `--review-only` fresh sessions, the freshly

written baseline equals current state so step 2 + 3 pass cleanly. For

`--session` resumes, run the full decision tree.

On detected drift:

```

(A) Accept drift and reset baseline to current state

(clears completed_stages entirely, including exec)

(B) Abort

```

- `--accept-external-state` auto-picks (A). Unsafe.

- Handsfree still blocks on drift (external fact, not a design

decision).

- On (A): set `base_head ← current_head`, `base_dirty ←

current_dirty`, `last_verified_head ← current_head`,

`last_verified_dirty ← current_dirty`, clear `completed_stages`

entirely, continue.

- On (B): release the lock, exit.

### Resume from non-null `delivery_blocked_by`

Per `docs/protocol/session-file.md` §Resume from non-null

`delivery_blocked_by`. When the existing session has a non-null

`delivery_blocked_by`: prompt continue-or-abort with the previous block

reason; on continue, clear `delivery_blocked_by ← null` and then run

the standard drift check.

## Step 3 — Execution round loop

Per `docs/protocol/execution.md` §Step 3 — Execution round loop. Round

### Provenance-aware reviewer prompts

The Orchestrator picks the reviewer-prompt block that matches the

active `## Session Metadata.plan_source`, per

`docs/protocol/execution.md` §Provenance-aware reviewer prompts:

- `plan_source: user-supplied` → plan-conformance deviations become

`[MINOR]`/advisory unless they change user-visible behavior or

violate acceptance criteria; correctness + intent still enforced.

The orchestrator MUST emit the literal sentinel

`(plan_source: user-supplied — plan conformance is advisory/MINOR)`

verbatim inside the reviewer prompt so tests and audits can confirm

this block was selected.

- `plan_source: review-only` → pure CR mode. No plan-conformance

language. Reviewer is explicitly told the Approved Plan body is the

canonical sentinel from

`docs/protocol/session-file.md` §Canonical sentinel for `review-only`

and `## Review Target` carries the scope.

### `--review-only` first-round skip

Per `docs/protocol/execution.md` §`--review-only` first-round skip:

1. Round 1 — jump straight to the Reviewer. No Executor output. The

review content targets the existing diff + `## Review Target` scope.

The Orchestrator writes the round-1 Review History entry with the

literal marker `- Executor backend: skipped (review-only first round)`

so tests and audits can assert the skip unambiguously.

2. APPROVE → enter the normal post-APPROVE transition: run Step 3.4

before Step 3.5, and mint `exec` only after Step 3.4 APPROVE/controlled

SKIP, or after Step 3.4 REQUEST_CHANGES is repaired and a later normal

Step 3 Reviewer returns APPROVE. This remains the only path where `exec`

3. REQUEST_CHANGES → round 2+ follows the standard CR → fix loop

(Executor runs, then Reviewer, alternating).

### Executor / Reviewer dispatch (Claude Code)

Executor: see `docs/protocol/planning.md` §Executor dispatch, Claude

Code block — same template, with the execution-mode task body per

`docs/protocol/execution.md` §Round steps step 2.

Dispatch anchor: `execute_executor_dispatch_skill`. The execution-phase

Executor remains a `judgment`-tier dispatch and resolves `model` as

`executor_model` if set and not `inherit`, else `judgment_model` if set,

else omit.

Reviewer: see `docs/protocol/planning.md` §Reviewer dispatch, Claude

Code block, with the execution-mode review content template per

`docs/protocol/execution.md` §Round steps step 5. `review_style` and

`review_focus` apply to all rounds, not only round 2+.

**Never use `subagent_type: review-loop:<name>`** — plugin agent-type

sandbox bug. Always `general-purpose` with body inlined.

### Loop control

- `APPROVE` → exit the execution loop. If Step 3.4 has not yet run in this

execution convergence, run Step 3.4 before Step 3.5 and do not mint `exec`

yet. Step 3.4 is single-pass per execution convergence. Step 3.4 APPROVE or

controlled SKIP mints `exec` into `completed_stages` for the current

tree+index state, then proceeds to Step 3.5 unless `--stop-after

before-polish`. Step 3.4 REQUEST_CHANGES withholds `exec` and feeds the gate

findings to ordinary Step 3 Executor/Reviewer repair rounds; do not run Step

3.4 again while repairing those findings. A later normal Step 3 reviewer

APPROVE after those repairs mints `exec` and proceeds to Step 3.5 unless

- `REQUEST_CHANGES` → feed feedback to the next Executor round.

- Soft limit + stuck detection per `docs/protocol/execution.md`

§Per-stage max-round caps (`soft_limit_exec`, default 3).

- `--stop-after exec-round` → clean exit after the current round

finishes (even on `REQUEST_CHANGES`). Perform step 5 of the drift

tree (update `last_verified_*`, append to `session_commits`).

### No-op round validation

Per `docs/protocol/execution.md` §No-op execution round validation. The

Orchestrator compares the Executor's claimed file list against the

current-round delta (pre-round vs post-round). Same path sets alone do

not prove a no-op.

- If git diff --name-only HEAD itself fails (non-zero exit, missing repo, etc.) when computing the pre-Executor or post-Executor changed set, stop and surface the failure to the user.

Then release the single-writer lock per docs/protocol/session-file.md §Lock file lifecycle before exiting. Do not proceed with a partial or invented changed-set.

## Step 3.4 — Terminal Adversarial Gate

Per `docs/protocol/execution.md` §Step 3.4 — Terminal Adversarial Gate.

Single-entry-point Python invoker; single-pass per execution convergence

between Step 3 APPROVE and Step 3.5 polish entry. Gate APPROVE/SKIP mints

`exec`; gate REQUEST_CHANGES returns to ordinary Step 3 repair rounds without

minting `exec`, and the gate does not run again while repairing those findings.

All concerns (plugin-path preference,

snapshot/restore, drain threads, signal cleanup) live inside the invoker.

```bash

# Terminal Adversarial Gate — single-entry-point Python invoker.

python3 scripts/adversarial_gate_invoke.py --focus-file "$focus_text_file"

adversarial_exit=$?

# 0 → APPROVE; 1 → REQUEST_CHANGES; SKIP reasons land on stderr.

```

SKIP banner format: `adversarial-gate: SKIP reason=<reason>[ detail=<...>]`

(5 reasons per the protocol-doc SKIP-reason table). Verdict table:

adapter exit 0 → APPROVE; exit 1 → REQUEST_CHANGES; exit 2 → REQUEST_CHANGES

because produced-but-malformed adversarial output is blocking, not SKIP.

APPROVE mints `exec`; REQUEST_CHANGES does not mint `exec` and feeds findings

to ordinary Step 3 repair rounds without another Step 3.4 pass in that repair

path.

Fallback cleanup failure is a blocking REQUEST_CHANGES, not SKIP: if

`.review-loop/config.md` cannot be proven restored/deleted after fallback

execution, or an unexpected existing or create-from-empty config change must be

preserved for inspection, do not mint `exec`; feed the synthetic `[CRITICAL]`

cleanup issue to ordinary Step 3 repair rounds without another Step 3.4 pass

in that repair path.

No Agent dispatch involved — invoker is a Bash shell-out to Python, so

the plugin-agent-sandbox bug does not apply.

The `adversarial_gate_skip_paths` config key (default

`["**/SKILL.md", "docs/protocol/**", "tests/skills/contracts/**"]`)

lets the orchestrator skip the gate entirely when every Step 3 changed

file matches one of the patterns.

## Step 3.5 — Quality Polish

Per `docs/protocol/execution.md` §Step 3.5. Runs language-specific

static analysis, code-quality review-fix loop, simplify, test

consolidation. `quality_focus` applies only when Step 3.5 Quality Polish

actually runs. If `skip_quality_polish: true` in config, mint `polish`

as a no-op completion and continue to Step 3.6.

`docs/protocol/session-file.md` §`completed_stages` lifecycle.

- Hallucination guard: for every quality agent returning `tool_uses:

0`, discard and retry once; if retry is also 0, skip and report.

- `--stop-after before-polish` → exit after Step 3.4 APPROVE/SKIP and

before Step 3.5 starts.

`--stop-after before-docs` → exit after Step 3.5 and before Step 3.6.

All Step 3.5 invocations use `subagent_type: general-purpose` with the

agent body inlined, per `docs/protocol/execution.md` §3.5.2 /

§3.5.3 / §3.5.4 / §3.5.5.

## Step 3.6 — Documentation Consistency

Per `docs/protocol/execution.md` §Step 3.6. Single pass. Update project

- Hallucination guard: for every documentation-stage agent returning `tool_uses: 0`, discard and retry once; if retry is also 0, skip and report.

`--stop-after before-security` → exit after Step 3.6 and before Step 3.7.

## Step 3.7 — Security Preflight

Per `docs/protocol/execution.md` §Step 3.7. Single scan. Check for

tracked/staged sensitive files; audit `.gitignore` for missing

Step 3.7 runs **unconditionally** after Step 3.6, regardless of

whether any prior stage wrote files. A no-op session (zero code

changes, zero doc updates) still runs this scan — it is a security

gate, not a content-dependent step. The only exits before 3.7 are

`--stop-after before-security` / `before-docs` / `before-polish` /

`exec-round`.

- Hallucination guard: for every security-stage agent returning `tool_uses: 0`, discard and retry once; if retry is also 0, skip and report.

`--stop-after before-delivery` → exit after Step 3.7 and before Step 4.

## Step 4 — Delivery

Per `docs/protocol/execution.md` §Step 4 — Delivery, gated by the

delivery gate in §Delivery gate: `runtime_supported_set ⊆

`{exec, polish, docs, security}`; for Codex Stage 1 it is

`{exec, polish, docs, security}`. Codex Stage 1: `{exec, polish, docs, security} ⊆ completed_stages`.

On gate failure, hard-stop per §Delivery gate: set

`delivery_blocked_by ← <first missing stage>`, release the single-writer lock per docs/protocol/session-file.md §Lock file lifecycle, and exit without delivering.

The stuck summary is printed from `docs/protocol/execution.md`

§Per-stage max-round caps.

On gate pass:

1. If `auto_commit: true`: stage only the files the Executor reported

(never `git add -A`/`git add .`), commit with

`{commit_message_prefix}: {title}`, append sha to `session_commits`.

2. Print the Delivery Summary (format in

`docs/protocol/execution.md` §Step 4 — Delivery — this skill reuses

the same format). Render the Delivery Summary in 中文 (Simplified

Chinese) per `docs/protocol/execution.md` §Step 4: section

headings, prose, and prose-style field values use 中文; ASCII

tokens stay in original form.

3. Append to `docs_file` if set.

4. Cleanup round temp files; preserve the session file.

5. Clear `delivery_blocked_by ← null`. Release the lock.

## `--stop-after` replay / invalidation interaction

- Clean `--stop-after` exit at any stage clears `delivery_blocked_by`

per `docs/protocol/session-file.md` §`delivery_blocked_by`

lifecycle, even if the session was previously blocked (the user

already acknowledged on resume).

- Stage invalidation rules (see

`docs/protocol/session-file.md` §`completed_stages` lifecycle) apply

during replay. Each writing substep clears the set; replay restarts

from `exec`. Per-stage caps bound iteration.

## Hard-stop and `delivery_blocked_by` lifecycle

Per `docs/protocol/session-file.md` §`delivery_blocked_by` lifecycle.

- Set by: per-stage hard-stop (`<stage>`) or signal abort

(`"user-abort"`).

- Cleared by: delivery success, clean `--stop-after` exit, user's

resume-continue choice.

- Unrecoverable errors preserve `last_verified_*` and

`delivery_blocked_by` unchanged so the user can audit.

---

## Context Management

The Orchestrator keeps minimal state between rounds (session path,

latest Reviewer feedback, round number, current stage). All durable

state is on disk. See `docs/protocol/planning.md` §Context management