update review-loop skill

Author: hiyuki

.agents/skills/review-loop/SKILL.md

@@ -11,10 +11,10 @@ Use this skill to run a two-phase workflow:
 1. Plan loop: `planner` writes or revises `plan.md`; `plan-reviewer` reviews it.
 2. Code loop: after user confirmation, `coder` implements the confirmed plan; `code-reviewer` reviews the resulting diff.
 
-The workflow requires real planner and coder subagents. If the current
-environment cannot create them, stop and tell the user that `review-loop`
-cannot run in this session. Codex and Claude Code reviewers run as standalone
-CLI processes instead of custom subagents.
+The workflow requires real planner, reviewer, and coder subagents. If the
+current environment cannot create fresh native subagents, stop and tell the
+user that `review-loop` cannot run in this session. Codex and Claude Code use
+host-native subagents for all four roles.
 
 ## Required Setup
 
@@ -33,19 +33,16 @@ Default `maxRounds` is `3`. If the user specifies a maximum loop count, pass it
 
 - Do not implement code until the plan loop has ended and the user explicitly confirms the plan.
 - Do not let reviewer roles modify repository files. Reviewers return one strict
-  JSON object; the orchestrator persists and validates it with
-  `scripts/persist-review-json.js`.
+  JSON object; the orchestrator persists and validates it through
+  `scripts/review-manager.js --finalize`.
 - Start every reviewer in a fresh context that does not inherit planner/coder conversation history.
-- On Codex or Claude Code, enter the reviewing phase, then run
-  `scripts/run-reviewer.js`. It starts a new read-only CLI process with
-  state-derived paths, binds every initial input to a SHA-256 digest, writes an
-  immutable `runtime/reviewer-runs/*` artifact, validates the strict JSON
-  result, and persists the canonical review. Code reviews also bind the
-  validated Git snapshot tree. Reviewing-phase advancement fails when any
-  bound input, snapshot, or run artifact changes. Confirmation gates check only
-  `plan.md` or the Git tree, so later task-workspace patch, scope, review, and
-  log edits do not block normal work by themselves. Do not invoke
-  `scripts/persist-review-json.js` directly on either platform.
+- On Codex or Claude Code, run `scripts/review-manager.js --prepare`, pass the
+  returned paths-only prompt to a fresh native reviewer subagent, save its one
+  JSON response to a temporary file outside the repository, then run
+  `scripts/review-manager.js --finalize --input <file> --agent-id <id>`. Prepare
+  binds every input and the Git tree; finalize rejects drift, writes the
+  immutable reviewer-run, and persists the canonical review. Do not invoke
+  `scripts/persist-review-json.js` directly.
 - Use `scripts/validate-review-json.js` for later read-only revalidation.
 - Use `scripts/snapshot-diff.js` after every code loop implementation round.
 - `coder-complete` reconstructs the current Git tree, path partitions, and
@@ -77,9 +74,8 @@ The four required roles are:
 - `code-reviewer`
 
 Use the templates under `templates/roles/` as role definitions. On Codex and
-Claude Code, only `planner` and `coder` are custom subagents;
-`plan-reviewer` and `code-reviewer` templates are consumed by
-`run-reviewer.js`. Do not create reviewer agent definitions.
+Claude Code all four roles are native subagents, and reviewer roles must start
+with no inherited planner/coder conversation.
 
 ## User Confirmation Gates
 

.agents/skills/review-loop/references/claude-code.md

@@ -1,109 +1,53 @@
 # Claude Code Integration
 
-Claude Code support uses real planner/coder subagents and standalone reviewer
-CLI processes. Do not run planner or coder as single-agent roleplay.
+Claude Code support uses real native subagents for `planner`, `plan-reviewer`,
+`coder`, and `code-reviewer`. Do not run any role as single-agent roleplay and
+do not start standalone `claude -p` reviewer processes.
 
 ## Role Discovery
 
-Check project agents first:
+Prepare all four roles with `scripts/prepare-agent-roles.js` either as temporary
+task roles or project agents:
 
 ```text
 .claude/agents/planner.md
+.claude/agents/plan-reviewer.md
 .claude/agents/coder.md
+.claude/agents/code-reviewer.md
 ```
 
-If both exist, reuse them. Reviewer instructions remain under
-`templates/roles/` and are consumed by `run-reviewer.js`; do not create Claude
-Code reviewer agents.
-
-If either planner/coder role is missing, ask the user to choose:
-
-- temporary roles under `.agent-workflows/review-loop/<task-id>/runtime/roles/`
-- persistent project agents under `.claude/agents/`
-
-Use `scripts/prepare-agent-roles.js` for either path. `auto` mode compares only
-the planner and coder project roles with their generated definitions.
-
-## Agent Format
-
-Claude Code custom agents are Markdown files with YAML frontmatter:
-
-```yaml
----
-name: planner
-description: Planner for review-loop workflows.
----
-```
-
-Planner and coder inherit the parent model, effort, tools, and permission mode.
-
-## Temporary Roles
-
-Temporary planner/coder roles are copied from `templates/roles/` to:
-
-```text
-.agent-workflows/review-loop/<task-id>/runtime/roles/
-```
-
-They are valid only for the current task. Claude Code automatically discovers
-named agents only from its configured agent locations. Use temporary
-definitions only when the host can register them for the current session.
-Otherwise choose project roles.
-
-## Persistent Roles
-
-Persistent planner/coder roles are copied to:
-
-```text
-.claude/agents/
-```
-
-This requires explicit user confirmation because it modifies project-level
-agent configuration. Reload manually created agent files with `/agents` or
-restart the session before invoking them.
+Temporary roles are valid only when the host can register them for the current
+session. Project roles require explicit user confirmation and a `/agents`
+reload or session restart.
 
 ## Starting Roles
 
-Start planner and coder as new named subagent invocations when required by the
-state machine. Reviewers are started only through:
-
-```bash
-node .agents/skills/review-loop/scripts/run-reviewer.js \
-  --task-id <task-id> \
-  --kind plan|code \
-  --round N
-```
-
-For plan review, the script starts a new `claude -p` process with a paths-only
-review prompt. For code review, it starts a new `claude -p` process whose user
-message invokes `/code-review high` against the cumulative round patch. The
-native skill may use its own internal reviewer agents; the workflow does not
-create or resume an outer reviewer subagent.
-
-Both commands pin `model = opus`, `effort = high`,
-`permission-mode = plan`, deny direct edit tools, omit `--fix`, and set
-`--no-session-persistence`. They request `--output-format json` with
-`--json-schema`; the runner extracts `structured_output`, validates it, writes
-the immutable reviewer-run artifact, and persists the canonical review. Every
-initial input is bound to a SHA-256 digest. Code reviews additionally bind and
-revalidate the snapshot tree and patches before launch, after completion, and
-during later state validation.
-
-The runner derives `model = opus`, `reasoningEffort = high`, read-only mode, and
-the plan/code-specific source from the command and overwrites
-`evidence.reviewerConfig`; reviewer self-reporting is not trusted.
-
-The fresh CLI process does not inherit the planner/coder conversation. It still
-loads repository-visible Claude Code configuration and can inspect files in the
-working tree. This is conversation isolation, not repository-read isolation.
-
-Do not invoke `persist-review-json.js` directly for Claude Code reviews.
+Start planner and coder as new named native subagents when required by the
+state machine. Start reviewers through Claude Code's native Agent/Task tool as
+new tasks with no resumed session or inherited planner/coder conversation.
+Restrict reviewer tools to read-only inspection when the host supports tool
+allow/deny configuration.
+
+For a reviewer round:
+
+1. Run `review-manager.js --task-id <id> --kind plan|code --round N --prepare`.
+2. Pass the returned prompt unchanged to the matching reviewer role.
+3. Require the reviewer to run its context-isolation preflight before reading
+   repository files and return exactly one JSON object with no repository writes.
+4. Save the response to a temporary file outside the repository.
+5. Run `review-manager.js ... --finalize --input <file> --agent-id <id>`.
+
+Prepare binds input digests and the current Git tree. Finalize reconstructs the
+request and rejects input, snapshot, or worktree drift before writing the
+immutable reviewer-run and canonical review. The orchestrator normalizes
+`reviewerConfig` to the host-native contract with source
+`claude-native-subagent`; it does not trust reviewer self-reporting.
+Finalize also rejects output that lacks the exact passed
+`context-isolation-preflight` evidence. This self-check supplements, but does
+not replace, starting a new native task without a resumed session.
 
 ## Failure
 
-If Claude Code cannot create real planner/coder subagents in the current
-session, stop the workflow and tell the user:
-
-```text
-review-loop requires real planner/coder subagent support. Current Claude Code session cannot create subagents, so the workflow cannot continue.
-```
+If Claude Code cannot create fresh native subagents, stop the workflow and
+report that review-loop requires native planner, reviewer, and coder subagent
+support.

.agents/skills/review-loop/references/codex.md

@@ -1,93 +1,53 @@
 # Codex Integration
 
-Codex support uses real planner/coder subagents and standalone ephemeral
-`codex exec review` processes with JSON Schema output. Do not run planner or
-coder as single-agent roleplay.
+Codex support uses real native subagents for `planner`, `plan-reviewer`,
+`coder`, and `code-reviewer`. Do not run any role as single-agent roleplay and
+do not start a nested `codex exec` process.
 
 ## Role Discovery
 
-Check project custom agents first:
+Prepare these project agents with `scripts/prepare-agent-roles.js --mode project`:
 
 ```text
 .codex/agents/planner.toml
+.codex/agents/plan-reviewer.toml
 .codex/agents/coder.toml
+.codex/agents/code-reviewer.toml
 ```
 
-If both exist, reuse them. Reviewer instructions remain under
-`templates/roles/` and are read by `run-reviewer.js`; do not create reviewer
-agent TOMLs.
-
-If any are missing or stale, ask the user for permission to create or refresh
-the project custom agents under `.codex/agents/`, then run
-`scripts/prepare-agent-roles.js --mode project`. Codex discovers custom agents
-only from its personal or project agent directories, so task-workspace
-temporary roles are not supported.
-
-## Persistent Agent Format
-
-Codex custom agents are TOML files. Each file must define:
-
-```toml
-name = "planner"
-description = "Planner for review-loop workflows."
-developer_instructions = """
-Read the review-loop workspace inputs and produce or revise plan.md.
-Do not implement code.
-"""
-```
+In `auto` mode the preparation script verifies all four definitions. Ask before
+creating or refreshing project agent files.
 
 ## Starting Roles
 
-Codex does not spawn subagents without an explicit request. After roles are
-prepared, the orchestrator must explicitly start planner and coder as the state
-machine requires. Reviewers are started only through `scripts/run-reviewer.js`.
-
-For each role, include:
-
-- role name
-- task id
-- workspace path
-- input files
-- required output path
-- instruction to return a concise summary to the orchestrator
-
-After `planner-complete` or `coder-complete`, run the state-derived reviewer:
-
-```bash
-node .agents/skills/review-loop/scripts/run-reviewer.js \
-  --task-id <task-id> \
-  --kind plan|code \
-  --round N
-```
-
-The script launches a new CLI process rather than resuming or forking the parent
-conversation. It passes only fixed instructions plus state-derived repository
-paths, records a SHA-256 digest for every initial input, explicitly selects a
-read-only sandbox, validates the returned strict JSON, and writes both the
-immutable run record and canonical review artifact. Code review runs also bind
-the validated snapshot tree and fail if the worktree or patches drift.
-Do not invoke `persist-review-json.js` directly for Codex reviews.
-
-This isolates conversation history, not repository visibility. The reviewer can
-read any file visible inside the repository's read-only sandbox.
-
-`run-reviewer.js` pins `model = "gpt-5.6"`, uses
-`--ephemeral --output-schema schemas/review.schema.json`,
-`model_reasoning_effort = "high"`, and `sandbox_mode = "read-only"` on the
-command line. Each review records those settings and
-`source = "codex-exec-review-command"` in `evidence.reviewerConfig`. The runner
-derives and overwrites this configuration from the actual command; reviewer
-self-reporting is not trusted as audit evidence.
-
-In `auto` mode, `prepare-agent-roles.js` compares the planner and coder project
-roles with their current templates. A mismatch returns `stale_roles`; refresh
-project roles explicitly before spawning planner or coder.
+Start planner and coder as named native subagents when required by the state
+machine. Start every reviewer with `spawn_agent` and `fork_turns: "none"` so it
+does not inherit planner, coder, or orchestrator conclusions.
+
+For a reviewer round:
+
+1. Run `review-manager.js --task-id <id> --kind plan|code --round N --prepare`.
+2. Pass the returned prompt unchanged to the matching reviewer role.
+3. Require the reviewer to run its context-isolation preflight before reading
+   repository files and return exactly one JSON object with no repository writes.
+4. Save the response to a temporary file outside the repository.
+5. Run `review-manager.js ... --finalize --input <file> --agent-id <id>`.
+
+Prepare binds the input digests and current Git tree. Finalize reconstructs the
+request and rejects any input, snapshot, or worktree drift before writing the
+immutable reviewer-run and canonical review.
+Finalize also rejects output that lacks the exact passed
+`context-isolation-preflight` evidence. This self-check supplements, but does
+not replace, `fork_turns: "none"`.
+
+Codex native subagents do not currently expose a per-agent sandbox override.
+The reviewer role is therefore a no-write contract backed by Git-tree drift
+validation, not a separately enforced OS sandbox. `reviewerConfig` records
+`model = host-selected`, `reasoningEffort = host-selected`,
+`sandboxMode = read-only`, and `source = codex-native-subagent`; these describe
+the host-native review contract and do not claim a pinned CLI model.
 
 ## Failure
 
-If Codex cannot create real planner/coder subagents in the current session,
-stop the workflow and tell the user:
-
-```text
-review-loop requires real planner/coder subagent support. Current Codex session cannot create subagents, so the workflow cannot continue.
-```
+If Codex cannot create fresh native subagents, stop the workflow and report
+that review-loop requires native planner, reviewer, and coder subagent support.