Execute

---
name: execute
description: "Codex Stage 1 execute skill. 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 — Codex Stage 1 Execution 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.

## Stage 1 Scope

- Codex Stage 1 follows the same broad `exec -> polish -> docs -> security -> delivery` lifecycle.
- Codex Stage 1 assumes a single orchestrator-owned workspace for the session.
- Included: execution loop, Quality Polish (Step 3.5), Documentation
  Consistency (3.6), Security Preflight (3.7), Delivery (Step 4),
  shared `.review-loop/config.md`, shared `.review-loop/sessions/*.md`,
  Claude CLI default reviewer, optional local Codex reviewer, shared
  reviewer schema, Stage 1 hallucination guards.
- Excluded: planning-phase orchestration — that lives in
  `.agents/skills/plan/SKILL.md`.

## 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; embedded executor/reviewer prompt bodies are
not a substitute for reading `executor-output.md` and
`reviewer-output.md`.

## Runtime Identity

- Codex is the orchestrator. Do not do the planning or coding in the main thread.
- The orchestrator is the only writer of `.review-loop/sessions/{uuid}.md`.
- `review_loop_executor` never writes the session file directly.
- `review_loop_reviewer` never writes the session file directly.
- Do not create or switch to another git worktree or repository checkout.
- The Executor must stay in the orchestrator-owned workspace for the session. Executor-created hidden worktrees are forbidden in Codex Stage 1.
- When invoking Codex subagents, use a fresh self-contained prompt that embeds
  the required task context directly. Do not rely on inherited or forked parent
  thread context.
- Reject malformed Executor or Reviewer output instead of guessing.

## Completed Agent Cleanup

- Track every Codex subagent id spawned for `review_loop_executor` and
  `review_loop_reviewer` during this execute session.
- Before every new `spawn_agent` call, call `close_agent` on any completed Codex subagent id from earlier execution rounds, polish substeps, or local-reviewer rounds unless the orchestrator explicitly intends to reuse that exact id.
- Do not close a subagent until its output has been captured, validated or
  rejected, and any information needed for the session-file update,
  retry decision, or user-facing failure report has been copied into
  orchestrator-owned state.
- After each execution round, polish substep, or local Codex reviewer
  retry finishes, close the completed Executor and local Reviewer
  subagents for that round before spawning the next agent or moving to
  the next stage.
- The Claude CLI reviewer path is a child process, not a Codex subagent, so
  completed-agent cleanup does not apply to it. Continue deleting its
  temporary prompt file immediately after the command returns.

## 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
review-loop:execute --session <uuid> [--stop-after <stage>] [--handsfree] [--accept-external-state]

# Entry mode 2 — execute a user-supplied plan verbatim
review-loop:execute --plan <text|path> --title <...> [--description <...>] [--stop-after <stage>] [--handsfree] [--accept-external-state]

# Entry mode 3 — pure code-review over the current working tree
review-loop: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 Codex Stage 1
   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)

   Codex Stage 1 accepts every value listed above for `--stop-after`;
   `before-polish`, `before-docs`, and `before-security` are the most
   common request points and are highlighted here for that reason.
   `exec-round` and `before-delivery` are also accepted. `delivery` is
   the default no-early-stop value (run through delivery), not a stop
   point.

   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). 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 Stage 1 defaults documented in
   `.agents/skills/review-loop/SKILL.md` §Config Loading.
6. **Reviewer backend resolution**: default Stage 1 keeps review on the
   outside-sandbox Claude CLI reviewer path. If
   `codex_reviewer_backend: codex` is set, use the local Codex reviewer
   directly. Do not auto-fall back from the Claude path to the local
   Codex reviewer.

## 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.

## 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.

- `.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." plus 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 steps 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
sequence: update context → spawn `review_loop_executor` (skipped on
`--review-only` round 1) → update context → optional context-persist
sub-step → reviewer dispatch → parse → Live Report → loop control →
close completed Codex subagents per §Completed Agent Cleanup.

### 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: reviewer-approved` → strict plan-conformance block.
- `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`
   can be added without the Executor running before the first review-only
   gate.
3. REQUEST_CHANGES → round 2+ follows the standard CR → fix loop
   (Executor runs, then Reviewer, alternating).

### Executor dispatch (Codex Stage 1)

Spawn `review_loop_executor` with a fresh self-contained prompt that
includes the approved plan, relevant session content, unresolved review
issues, and the required execution schema from
`docs/protocol/executor-output.md` §Execution round schema. Do not rely
on inherited or forked parent thread context.

Concrete dispatch anchor: `codex_execution_executor_dispatch`. The
Codex execution-phase Executor remains a `judgment`-tier local agent.

Validate the Executor output against the shared schema. If invalid,
retry once with explicit correction instructions. If still invalid,
stop and surface the failure. Then
release the single-writer lock per docs/protocol/session-file.md §Lock file lifecycle before exiting.

### Reviewer dispatch (Codex Stage 1)

Default Claude CLI path. Render the full reviewer prompt to
`.review-loop/tmp/{session_id}-reviewer-prompt.txt`, then run:

```bash
claude -p --no-session-persistence --output-format stream-json --include-partial-messages --model {reviewer_model if set; else judgment_model if set; else claude-sonnet-4-6} < .review-loop/tmp/{session_id}-reviewer-prompt.txt
```

- Run the Claude call outside the sandbox.
- Read stdout line by line. Find `type == "result"` and use its
  `result` field as the reviewer output. Intermediate events are
  heartbeat signals; do not treat them as output. If no `type ==
  "result"` line appears before exit, treat that as a command execution
  failure.
- Validate the `result` field against the shared reviewer schema in
  `docs/protocol/reviewer-output.md`.
- Delete `.review-loop/tmp/{session_id}-reviewer-prompt.txt` immediately
  after the command returns.
- If the Claude call fails or validation fails, do not guess and do not
  retry Claude for that round. Record a short failure reason summary in
  `## Review History` (command execution / JSON parsing / missing
  `result` / reviewer schema validation). If
  `codex_reviewer_backend: codex` is not set, surface the Claude-path
  failure to the user instead of auto-falling back. Then
  release the single-writer lock per docs/protocol/session-file.md §Lock file lifecycle before exiting.

Optional local Codex reviewer path: spawn `review_loop_reviewer` only
if `codex_reviewer_backend: codex` is set, or if the user has otherwise
explicitly opted in. Use a fresh self-contained prompt with the same
review content and the same reviewer schema rules. If invalid, retry
once with explicit correction instructions. If still invalid, stop and
surface the failure. Then
release the single-writer lock per docs/protocol/session-file.md §Lock file lifecycle before exiting.

#### Parallel Reviewer Fan-Out (N>1)

When the orchestrator decides to dispatch N>1 independent reviewer rounds in
the same wall-clock window (for example a polish-stage parallel sweep),
shell out once to the conflict-aware parallel scheduler in
`scripts/review_verification.py` instead of looping the single-shot path
serially. N=1 dispatch keeps the single-shot invocation above
byte-identical — argv, stdin handoff, model resolution, and temp-file
lifecycle are unchanged.

Build `<jobs.json>` as a JSON list of objects with one entry per reviewer
round, matching the schema accepted by `_load_jobs` in
`scripts/review_verification.py`:

- `session_id` (required) — current session uuid
- `job_id` (required) — orchestrator-stable identifier unique within the
  round; used as the per-job prompt-file discriminator
- `runtime` (optional, default `"codex"`) — leave at `"codex"` for the
  Codex Stage 1 `claude -p` shell-out path
- `prompt_text` (required for non-empty dispatch) — the full reviewer
  prompt body, identical to what would be rendered into
  `.review-loop/tmp/{session_id}-reviewer-prompt.txt` in the single-shot
  path
- `reviewer_model` — resolved via the same shared model-tier rule used by
  the single-shot path: `reviewer_model if set; else judgment_model if
  set; else claude-sonnet-4-6` (per `docs/protocol/planning.md` §Shared
  model-tier contract)
- `timeout_secs` (optional, default `300.0`)
- `conflict_keys`, `capacity_keys`, `extra_argv`, `worktree` (optional;
  omit unless overriding scheduler defaults)

Inline `prompt_text` directly in the JSON object — do not write per-job
prompt files yourself; the scheduler renders each job's `prompt_text` to
`.review-loop/tmp/{session_id}-reviewer-prompt.{job_id}.txt` internally
and hands the FD to the spawned `claude -p` via stdin redirection (per
`scripts/review_verification.py:457-459` Scheduler docstring and
`:648-651` `_run_one`). For `runtime: "codex"` jobs (the Codex Stage 1
fan-out path documented in this section), per-job stdout is captured by
the scheduler via `subprocess.PIPE` and surfaced through each
`<results.json>` entry's `stdout` field — there is no per-job output
file. For `runtime: "claude_code"` jobs (the Claude-Code orchestrator's
`codex exec -o` fan-out, not used here), per-job stdout is written to
`.review-loop/tmp/{session_id}-reviewer-output.{job_id}.txt`.

Invoke the scheduler outside the sandbox:

`python3 scripts/review_verification.py --jobs .review-loop/tmp/{session_id}-jobs.json --output .review-loop/tmp/{session_id}-results.json`

`<results.json>` is a JSON list of objects, one per job, each carrying
`job_id`, `returncode`, `stdout`, `stderr`, `timed_out`, `parsed_verdict`,
`parsed_issues`, and `error`. For every entry:

- If the entry's `error` field is non-null, or `timed_out` is true, or
  `returncode` is non-zero, classify as a **command-execution failure**
  for the round's failure-mode taxonomy and record `error`, the last
  4 KB of `stderr`, `timed_out`, and `returncode` in `## Review History`.
  Do not attempt to parse `stdout` for that entry — the per-entry
  diagnostic fields take precedence over stream-json parse outcome.
- Treat the per-entry `stdout` field as the same stream-json byte stream
  the single-shot path reads from `claude -p`. Find the line where
  `type == "result"` and use its `result` field as the reviewer output.
- Validate that `result` against the shared reviewer schema in
  `docs/protocol/reviewer-output.md`. The orchestrator remains the single
  authority for verdict extraction and schema validation; the scheduler's
  own `parsed_verdict` / `parsed_issues` are best-effort metadata only
  per `scripts/review_verification.py:12-17` and must not be substituted
  for orchestrator-side validation.
- Apply the same per-round failure-mode taxonomy as the single-shot path
  (command execution / JSON parsing / missing `result` / reviewer schema
  validation) when recording `## Review History`.

After the round completes (success or failure), delete every per-job
prompt file `.review-loop/tmp/{session_id}-reviewer-prompt.{job_id}.txt`,
every `runtime: "claude_code"` per-job output file
`.review-loop/tmp/{session_id}-reviewer-output.{job_id}.txt` (absent for
the `runtime: "codex"` path used in this section), and the
`.review-loop/tmp/{session_id}-jobs.json` /
`.review-loop/tmp/{session_id}-results.json` artifacts, matching the
single-shot prompt-cleanup discipline.

Per-job prompt files are scheduler-owned and may already be unlinked
when the orchestrator's cleanup runs (the scheduler unlinks them in its
own `finally:` per `scripts/review_verification.py:646`); treat ENOENT
as success and do not surface it. The `<jobs.json>` / `<results.json>`
artifacts are orchestrator-owned — a non-ENOENT failure to delete them
should be logged as a warning in `## Review History` but must not block
the round verdict.

### Code Review Content

Code review content must include:

- the shared session file path
- the current execution-phase context from the session file
- the latest Executor execution output
- the actual post-Executor changed file list, including deleted tracked
  files
- the delta attributable to the current round, derived from the relevant
  pre-round and post-round state for files touched in that round
- the orchestrator-owned current workspace as the authoritative review
  scope
- prior `Review History` context when present
- the exact shared reviewer schema
- a review-only instruction
- explicit direction to enforce correctness and tests; plan-conformance enforcement follows the §Provenance-aware reviewer prompts block selected by `plan_source` (strict for `reviewer-approved`, advisory/MINOR for `user-supplied`, omitted entirely for `review-only`)
- if implementation appears to exist only in a different git worktree or
  repository path than the current workspace, return REQUEST_CHANGES
  with a [CRITICAL] workspace divergence issue
- an explicit instruction to ignore unrelated startup or prompt-hook
  injections (for example HANDOFF pickup banners, LEARNINGS sync text,
  or other user-level `additionalContext`) that do not pertain to the
  provided session file and review task

### 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
  `--stop-after before-polish`.
- `REQUEST_CHANGES` → feed feedback to the next Executor round.
- Soft-limit prompt: when `soft_limit_exec` is reached and blocking
  issues remain, surface the situation to the user instead of silently
  continuing or silently stopping. Respect the configured execution
  soft limit, but do not bypass review validation.
- `--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.

- Record the pre-Executor changed file set before each execution round.
  Use it for file-presence validation and to help derive the
  current-round delta, but unchanged path sets alone do not prove a
  no-op.
- After the Executor returns, collect the actual post-Executor changed
  file set.
- Compare the Executor's claimed file changes against the current-round
  delta attributable to that round, using pre-round and post-round
  state. Same path sets alone are not enough.
- A valid no-op execution round must encode that explicitly in the
  execution schema: `### Changes Made` states that no code changes were
  required, `### Files Modified / Created / Deleted` is `None`, and
  `### Notes for Reviewer` identifies the round as a no-op.
- For a no-op or unchanged run, do not invent new file changes in
  `## Files Changed`. Reject the result if the Executor claims changes
  that cannot be tied to a meaningful current-round delta.
- 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.

### Stage minting

When an execution round reaches reviewer `APPROVE`, run Step 3.4 before
Step 3.5 if the terminal gate has not yet run in this execution convergence.
Step 3.4 is single-pass per execution convergence. Withhold `exec` until the
gate returns APPROVE or controlled SKIP, or until gate-requested repairs later
receive a normal Step 3 reviewer APPROVE. Then mint `exec` into
`completed_stages` in `## Session Metadata` per the shared session-file
lifecycle. This applies to both edit rounds and reviewed no-op rounds. If Step
3.4 returns REQUEST_CHANGES, do not mint `exec`; feed the gate findings to
ordinary Step 3 Executor/Reviewer repair rounds, and do not run Step 3.4 again
while repairing those findings. Do not represent execution completion with
custom metadata keys such as `completed_at`; the shared protocol completion
state is carried by `completed_stages` and related baseline metadata.

## 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.

```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=<...>]`.
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.

**Run the adversarial gate invocation outside the sandbox.** The Python
invoker writes tempfiles (`tempfile.mkstemp` for config snapshot,
`tempfile.NamedTemporaryFile` for the rendered fallback prompt), which
the Codex read-only sandbox blocks. Mirrors the existing reviewer-call
and scheduler-call sandbox boundary.

The invoker shells out via Bash, not `spawn_agent` — completed-agent
cleanup 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` is set in config, the orchestrator skips the Step 3.5 substeps; in that case `skip_quality_polish: true` mints `polish` as a no-op completion and still continues through docs and security.

- Any substep that writes code clears `completed_stages` and the
  Orchestrator replays from `exec` per
  `docs/protocol/session-file.md` §`completed_stages` lifecycle. Each
  replay iteration that writes files clears the set and restarts from
  `exec`. Termination is guaranteed by the per-stage caps.
- Narrow `reviewer-only fast-replay` exception: eligible Step 3.5.4
  prose/comment/metadata-only writes that do not touch lint-pinned needles
  or change the `bash scripts/run-skill-lint` baseline may preserve the
  current `completed_stages` per
  `docs/protocol/session-file.md` §`completed_stages` lifecycle.
- Step 3.5.4 reviewer-only fast-replay `APPROVE` does not mint `polish`.
  Step 3.5.6 mints `polish` only after the full Step 3.5 invocation finishes
  cleanly with either no writes, or only eligible writes already approved by
  reviewer-only fast-replay.
- 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.

## Step 3.6 — Documentation Consistency

Per `docs/protocol/execution.md` §Step 3.6. Single pass. Update project
docs + fix stale code comments. Writes → clear `completed_stages`,
replay from `exec`, except for the narrow `reviewer-only fast-replay`
exception above when the write is eligible prose/comment/metadata-only work
that does not touch lint-pinned needles or change the
`bash scripts/run-skill-lint` baseline. No-write or approved reviewer-only
fast-replay → mint `docs`. After minting `docs`, proceed to Step 3.7 — a
no-op docs stage is not a terminal state.

- 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
coverage. Writes to `.gitignore` or `git rm --cached` → clear
`completed_stages`, replay from `exec`. No-write → mint `security`.

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: 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.

---

## Codex Hallucination Guard

For full guard rules see `.agents/skills/review-loop/SKILL.md`
§Codex Hallucination Guard. Briefly: reject Executor output that lacks
the required schema sections, claims file changes without concrete
paths, claims implementation changes not reflected in the current-round
delta attributable to that round, or implies work performed in a
different git worktree or repository checkout than the
orchestrator-owned current workspace. Reject reviewer output missing
`### VERDICT` / `### Strengths`, using any severity outside
`[CRITICAL]` / `[MINOR]`, or contains semantic inconsistencies
(`APPROVE` with `[CRITICAL]`, `REQUEST_CHANGES` with only `[MINOR]`).
Reject reviewer output that fails to flag workspace divergence when
implementation appears to exist only in a different git worktree or
repository path than the current workspace.

The post-Executor set is the source of truth. The pre-Executor set is
useful for file-presence validation and current-round delta derivation,
but unchanged path sets alone do not prove a no-op. Treat a run as
no-op only when the Executor explicitly reports it and there is no
meaningful delta attributable to the current round.

## 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
discipline (applies equally to execution).