@xenonbyte/req-2-plan 0.6.0 → 0.7.0

package/README.md

@@ -6,12 +6,16 @@ English | [简体中文](README.zh-CN.md)
 [![node](https://img.shields.io/node/v/%40xenonbyte%2Freq-2-plan.svg)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-> Turn a raw requirement into an approved, executor-neutral implementation PLAN across Claude Code, Codex, Gemini, and opencode.
+> Turn a raw requirement into an approved, executor-neutral implementation PLAN - then execute that PLAN in place - across Claude Code, Codex, Gemini, and opencode.
 
-`req-2-plan` installs the `r2p` workflow for AI coding agents. It takes a rough
-requirement through a staged, gated process - **requirement brief**, **risk
-discovery**, **DESIGN**, **SPEC**, and **PLAN** - so the final plan is grounded,
-reviewed, and ready for another agent or engineer to execute.
+`req-2-plan` installs the `r2p` workflow for AI coding agents, and it works in
+two phases. **Plan:** it takes a rough requirement through a staged, gated
+process - **requirement brief**, **risk discovery**, **DESIGN**, **SPEC**, and
+**PLAN** - so the final plan is grounded, reviewed, and ready to execute.
+**Execute:** `r2p-execute` then drives that approved PLAN through an in-place,
+subagent-orchestrated implementation loop on your current branch - one
+implementer per task, a reviewer after each, a whole-branch final review, then
+auto-archive - so the same tool that planned the change can also land it.
 
 The npm package is the lifecycle installer. It currently supports four agent
 platforms - **Claude Code**, **Codex**, **Gemini**, and **opencode**. From one
@@ -19,7 +23,7 @@ shared source it generates platform-specific agent surfaces, installs the shared
 `r2p-*` wrappers, and keeps an owned manifest so uninstall only removes files
 managed by `r2p`.
 
-**Contents:** [Why r2p](#why-r2p) · [Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Workflow commands](#workflow-commands) · [Development](#development)
+**Contents:** [Why r2p](#why-r2p) · [Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Workflow commands](#workflow-commands) · [Executing a PLAN](#executing-a-plan) · [Development](#development)
 
 ## Why r2p
 
@@ -31,7 +35,7 @@ planning phase explicit:
 - risks and unknowns are surfaced before implementation planning;
 - DESIGN, SPEC, and PLAN each pass structural quality gates;
 - human decisions are recorded instead of guessed;
-- execution can start from a PLAN without re-deciding scope.
+- execution runs straight from the PLAN - by hand or via `r2p-execute` - without re-deciding scope.
 
 Use it when the requirement is more than a one-line edit, when a change touches
 important behavior, or when you want a durable handoff between agents.
@@ -43,9 +47,9 @@ important behavior, or when you want a durable handoff between agents.
 - **Four supported platforms**: installs matching surfaces for Claude Code (`claude`), Codex (`codex`), Gemini (`gemini`), and opencode (`opencode`).
 - **One lifecycle CLI**: `r2p install`, `r2p uninstall`, `r2p status`, `r2p version`, and `r2p help`.
 - **Manifest-backed install safety**: pre-existing files are backed up, and uninstall removes only managed paths.
-- **Project Context Pack**: `--repo-path` captures real repository facts for tiering and PLAN checks.
+- **Project Context Pack**: real repository facts (the current directory by default, or `--repo-path <dir>`) ground tiering and PLAN checks.
 - **Repair paths**: reopen closed runs, route upstream gaps, and resolve repaired decisions.
-- **Execution handoff**: `r2p-execute` can drive an approved PLAN through an in-place implementation loop.
+- **In-place PLAN execution**: `r2p-execute` runs the approved PLAN on your current branch through a subagent-driven SDD loop - a fresh implementer per task, a task-reviewer and fix loop after each, then a whole-branch final review that re-runs the full verification suite before the run auto-archives. Subagent dispatch is required, and it never pushes or opens pull requests.
 
 ## Supported platforms
 
@@ -109,20 +113,19 @@ r2p install --platform claude,codex,gemini,opencode
 Install the platform skills, then start a workflow from your agent:
 
 ```text
-/r2p-start --repo-path . "Add rate limiting"
+/r2p-start "Add rate limiting"
 /r2p-continue
 ```
 
 Start from a requirement file instead of inline text:
 
 ```text
-/r2p-start --repo-path . --file change-req.md
+/r2p-start --file change-req.md
 ```
 
-For repositories used as requirement context, pass `--repo-path`. Use `.` for the
-current repository or a path to the target repository for cross-project work.
-This builds the Project Context Pack used by tier estimation and PLAN reference
-checks.
+Tier estimation and the Project Context Pack are grounded in the current
+directory by default. Pass `--repo-path <dir>` to ground them in a different
+repository instead - for example, a target repository for cross-project work.
 
 The workflow stops whenever it needs a human or agent action: tier lock,
 artifact content, quality-gate repair, checkpoint approval, subagent review, or
@@ -139,20 +142,43 @@ gap resolution. Run the printed `next:` command exactly, then resume with
 ## Workflow commands
 
 After installation, the agent-facing commands call shared wrappers under
-`~/.req-to-plan/bin`.
-
-| Command | Purpose |
-|---|---|
-| `r2p-start` | Start a new run from inline requirement text or `--file <path>`. |
-| `r2p-continue` | Advance the active run to the next stop or completed state. |
-| `r2p-status` | Inspect the active run, or all runs with `--all`, without changing state. |
-| `r2p-switch` | Select a different active `--work-id`. |
-| `r2p-tier-lock` | Lock the tier with `--base light\|standard` and optional modifiers. |
-| `r2p-reopen` | Reopen a closed or executing run from a specific stage and select the reopened run. |
-| `r2p-gap-open` | Route an upstream gap on an open run back to the owner stage. |
-| `r2p-gap-resolve` | Close a repaired upstream-gap route. |
-| `r2p-archive` | Move a closed run under `.req-to-plan/archive/` and untrack its active path. |
-| `r2p-execute` | Execute a closed PLAN in place on the current branch, then archive the run. |
+`~/.req-to-plan/bin`. Each command, its purpose, and its parameters - optional
+parameters show their default; `—` means you must supply the value:
+
+| Command | Purpose | Parameter | Required / optional | Default |
+|---|---|---|---|---|
+| `r2p-start` | Start a new run and propose a tier from a repo scan. | `<requirement>` or `--file <path>` | one required | — |
+| | | `--repo-path <dir>` | optional | current directory |
+| | | `--separate` | optional | off |
+| `r2p-continue` | Advance the active run and print the exact `next:` action. | *(none)* | — | — |
+| `r2p-status` | Inspect runs without changing state. | `--all` | optional | off |
+| `r2p-switch` | Point the active-run marker at another run. | `--work-id <id>` | required | — |
+| `r2p-tier-lock` | Lock the active run's complexity tier. | `--work-id <id>` | required | — |
+| | | `--base light\|standard` | required | — |
+| | | `--confirm` | required | — |
+| | | `--modifiers <a,b,…>` | optional | none |
+| | | `--override-floor` | optional | off |
+| `r2p-reopen` | Reopen a closed or executing run to repair an upstream artifact. | `--from <work-id>` | required | — |
+| | | `--stage <stage>` | required | — |
+| | | `--reason <text>` | required | — |
+| `r2p-gap-open` | Route an upstream decision gap on an open run back to its owner stage. | `--work-id <id>` | required | — |
+| | | `--owner-stage <stage>` | required | — |
+| | | `--required-action "<text>"` | required | — |
+| `r2p-gap-resolve` | Close a repaired upstream-gap route. | `--work-id <id>` | required | — |
+| | | `--route-id <id>` | required | — |
+| `r2p-archive` | Archive a closed run out of the active workspace. | `--work-id <id>` | optional | active run |
+| | | `--force` | optional | off |
+| `r2p-execute` | Execute a closed PLAN in place, run a whole-branch review, then archive. | `--work-id <id>` | optional | active run |
+
+Notes: `--modifiers` takes a comma-separated subset of `migration`,
+`cross_project`, `safety`, `dependency`, `scope_expanding`. `--stage` and
+`--owner-stage` take a pipeline stage (`raw_requirement` … `plan`); a gap's
+`--owner-stage` must be strictly upstream of the current stage, and
+`--required-action` must be a single line. `--confirm` is what makes the tier
+lock take effect, and `--override-floor` allows locking below the computed
+floor. `--separate` starts a parallel run while another is still open. `--force`
+lets `r2p-archive` archive an executing run whose PLAN-TASKs are not all checked
+off.
 
 Most runs only need `r2p-start` and repeated `r2p-continue`. Use the specialized
 commands when the workflow prints them or when you intentionally need to switch,
@@ -212,6 +238,32 @@ present. If a later stage discovers an upstream decision gap, use
 `r2p-gap-open`, repair the owner stage, then close the route with
 `r2p-gap-resolve`.
 
+## Executing a PLAN
+
+`r2p` does not stop at the PLAN. Once a run is closed at the PLAN checkpoint,
+`r2p-execute` implements it in place on your current branch - no new branch, no
+worktree, no push. It assumes the host agent can dispatch subagents and fails
+explicitly if it cannot.
+
+The loop is Spec-Driven Development (SDD):
+
+- **Pre-flight**: read the PLAN once and batch any contradiction or defect to you
+  before work starts; an upstream defect routes back to a stage reopen, never a
+  patch in execution.
+- **Per task**: a fresh implementer subagent builds exactly one PLAN-TASK under
+  TDD, commits only its own files, and reports back; a task-reviewer checks it
+  against the SPEC and the task's verification criteria, and a fix loop clears
+  Critical and Important findings before the task's checkbox flips.
+- **Whole-branch review**: once every task is done, a final reviewer on the most
+  capable model re-runs the full verification suite over the entire execution
+  range and walks the PLAN as a checklist. This review is the merge gate.
+- **Auto-archive**: a clean `Verdict: Approved` final review lets `r2p-execute`
+  archive the run. Commits stay on your current branch; `push` and pull requests
+  remain a separate, explicit request.
+
+Progress is tracked durably in `execution/progress.md`, so an interrupted run
+resumes from the first unchecked task instead of restarting.
+
 ## Development
 
 Install development dependencies:

package/README.zh-CN.md

@@ -6,17 +6,20 @@
 [![node](https://img.shields.io/node/v/%40xenonbyte%2Freq-2-plan.svg)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-> 把原始需求变成一份获批、执行器中立的实现 PLAN，并在 Claude Code、Codex、Gemini、opencode 上一致运行。
+> 把原始需求变成一份获批、执行器中立的实现 PLAN，再在原地把这份 PLAN 执行落地，并在 Claude Code、Codex、Gemini、opencode 上一致运行。
 
-`req-2-plan` 为 AI coding agent 安装 `r2p` 工作流。它把粗略需求推进到一条分阶段、
-门控的流程中：**requirement brief**、**risk discovery**、**DESIGN**、**SPEC**、
-**PLAN**。最终得到的计划有上下文、有审查记录，也能直接交给另一个 agent 或工程师执行。
+`req-2-plan` 为 AI coding agent 安装 `r2p` 工作流，分两个阶段工作。**规划（Plan）：**
+把粗略需求推进到一条分阶段、门控的流程中——**requirement brief**、**risk discovery**、
+**DESIGN**、**SPEC**、**PLAN**——让最终计划有上下文、有审查记录、可直接执行。
+**执行（Execute）：** 随后 `r2p-execute` 把这份获批 PLAN 接入当前分支上、由 subagent
+编排的原地实现循环——每个任务一个 implementer、每个任务后一次 review、最后一次整分支
+评审，然后自动归档——让规划这次改动的工具也能把它落地。
 
 这个 npm 包是生命周期安装器。目前它支持 4 个 agent 平台：**Claude Code**、**Codex**、
 **Gemini**、**opencode**。它从一份共享源生成各平台的 agent 入口，安装共享的
 `r2p-*` wrapper，并维护 owned manifest，确保卸载时只移除 `r2p` 自己管理的文件。
 
-**Contents:** [Why r2p](#why-r2p) · [Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Workflow commands](#workflow-commands) · [Development](#development)
+**Contents:** [Why r2p](#why-r2p) · [Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Workflow commands](#workflow-commands) · [Executing a PLAN](#executing-a-plan) · [Development](#development)
 
 ## Why r2p
 
@@ -27,7 +30,7 @@ AI agent 执行很快，但模糊需求容易变成含糊计划、隐藏范围
 - 风险和未知点会在实现计划前暴露；
 - DESIGN、SPEC、PLAN 都要通过结构化 quality gate；
 - 必须由人选择的决定会被记录，而不是由 agent 猜；
-- 执行可以从 PLAN 开始，不需要重新决定范围。
+- 执行可以直接从 PLAN 开始——手动执行，或用 `r2p-execute`——不需要重新决定范围。
 
 当需求不只是单行修改、会影响重要行为，或需要在多个 agent 之间做稳定交接时，适合使用它。
 
@@ -38,9 +41,9 @@ AI agent 执行很快，但模糊需求容易变成含糊计划、隐藏范围
 - **支持 4 个平台**：为 Claude Code（`claude`）、Codex（`codex`）、Gemini（`gemini`）、opencode（`opencode`）安装匹配入口。
 - **单一生命周期 CLI**：`r2p install`、`r2p uninstall`、`r2p status`、`r2p version`、`r2p help`。
 - **Manifest-backed 安装安全**：覆盖前备份已存在文件，卸载只删除受管路径。
-- **Project Context Pack**：`--repo-path` 捕获真实仓库事实，用于 tier 估算和 PLAN 校验。
+- **Project Context Pack**：以真实仓库事实（默认当前目录，或用 `--repo-path <dir>`）支撑 tier 估算和 PLAN 校验。
 - **修复路径**：可重开 closed run、路由上游缺口，并关闭已修复的决策路线。
-- **执行交接**：`r2p-execute` 可以把获批 PLAN 接入当前分支上的实现循环。
+- **原地执行 PLAN**：`r2p-execute` 在当前分支上通过 subagent 驱动的 SDD 循环执行获批 PLAN——每个任务一个全新 implementer、每个任务后接 task-reviewer 与 fix 循环，最后一次整分支评审会重跑完整验证套件，通过后 run 自动归档。它要求宿主能派发 subagent，且从不 push 或开 PR。
 
 ## Supported platforms
 
@@ -101,18 +104,18 @@ r2p install --platform claude,codex,gemini,opencode
 安装平台 skill 后，在 agent 里启动一次工作流：
 
 ```text
-/r2p-start --repo-path . "Add rate limiting"
+/r2p-start "Add rate limiting"
 /r2p-continue
 ```
 
 也可以从需求文件启动，而不是传内联文本：
 
 ```text
-/r2p-start --repo-path . --file change-req.md
+/r2p-start --file change-req.md
 ```
 
-只要需求以代码仓库为上下文，就传 `--repo-path`。当前仓库传 `.`，跨项目需求传目标仓库路径。
-这会构建 Project Context Pack，供 tier 估算和 PLAN 引用校验使用。
+tier 估算和 Project Context Pack 默认以当前目录为基准。传 `--repo-path <dir>`
+可改为以另一个仓库为基准——例如跨项目需求里的目标仓库。
 
 工作流会在需要人或 agent 动作时停下：锁定 tier、填写 artifact、修复 quality gate、
 批准 checkpoint、执行 subagent review，或解决 gap。按输出里的 `next:` 命令执行，
@@ -127,20 +130,40 @@ r2p install --platform claude,codex,gemini,opencode
 
 ## Workflow commands
 
-安装后，面向 agent 的命令会调用 `~/.req-to-plan/bin` 下的共享 wrapper。
-
-| Command | Purpose |
-|---|---|
-| `r2p-start` | 从内联需求文本或 `--file <path>` 启动新 run。 |
-| `r2p-continue` | 把活动 run 推进到下一个停点或完成状态。 |
-| `r2p-status` | 只读查看活动 run；加 `--all` 可查看全部 run。 |
-| `r2p-switch` | 切换活动的 `--work-id`。 |
-| `r2p-tier-lock` | 用 `--base light\|standard` 和可选 modifier 锁定 tier。 |
-| `r2p-reopen` | 从指定阶段重开一个 closed 或 executing run，并选择新重开的 run。 |
-| `r2p-gap-open` | 把 open run 的上游缺口路由回 owner stage。 |
-| `r2p-gap-resolve` | 关闭一个已修复的上游缺口 route。 |
-| `r2p-archive` | 把 closed run 移到 `.req-to-plan/archive/`，并取消活动路径跟踪。 |
-| `r2p-execute` | 在当前分支原地执行 closed PLAN，然后归档该 run。 |
+安装后，面向 agent 的命令会调用 `~/.req-to-plan/bin` 下的共享 wrapper。各命令的用途与
+参数如下——可选参数标注默认值，`—` 表示必须自行提供：
+
+| Command | Purpose | Parameter | 必填 / 可选 | 默认值 |
+|---|---|---|---|---|
+| `r2p-start` | 启动新 run，并基于仓库扫描给出 tier 建议。 | `<requirement>` 或 `--file <path>` | 二选一必填 | — |
+| | | `--repo-path <dir>` | 可选 | 当前目录 |
+| | | `--separate` | 可选 | 关 |
+| `r2p-continue` | 把活动 run 推进到下一个停点，并打印精确的 `next:` 动作。 | *(无)* | — | — |
+| `r2p-status` | 只读查看 run，不改状态。 | `--all` | 可选 | 关 |
+| `r2p-switch` | 把活动 run 标记指向另一个 run。 | `--work-id <id>` | 必填 | — |
+| `r2p-tier-lock` | 锁定活动 run 的复杂度 tier。 | `--work-id <id>` | 必填 | — |
+| | | `--base light\|standard` | 必填 | — |
+| | | `--confirm` | 必填 | — |
+| | | `--modifiers <a,b,…>` | 可选 | 无 |
+| | | `--override-floor` | 可选 | 关 |
+| `r2p-reopen` | 重开一个 closed 或 executing run 以修复上游 artifact。 | `--from <work-id>` | 必填 | — |
+| | | `--stage <stage>` | 必填 | — |
+| | | `--reason <text>` | 必填 | — |
+| `r2p-gap-open` | 在 open run 上把上游决策缺口路由回 owner stage。 | `--work-id <id>` | 必填 | — |
+| | | `--owner-stage <stage>` | 必填 | — |
+| | | `--required-action "<text>"` | 必填 | — |
+| `r2p-gap-resolve` | 关闭已修复的上游缺口 route。 | `--work-id <id>` | 必填 | — |
+| | | `--route-id <id>` | 必填 | — |
+| `r2p-archive` | 把 closed run 归档出活动工作区。 | `--work-id <id>` | 可选 | 活动 run |
+| | | `--force` | 可选 | 关 |
+| `r2p-execute` | 原地执行 closed PLAN，做整分支评审，然后归档。 | `--work-id <id>` | 可选 | 活动 run |
+
+说明：`--modifiers` 接受 `migration`、`cross_project`、`safety`、`dependency`、
+`scope_expanding` 的逗号分隔子集。`--stage` 与 `--owner-stage` 取流水线阶段
+（`raw_requirement` … `plan`）；gap 的 `--owner-stage` 须严格位于当前阶段上游，
+`--required-action` 须为单行。`--confirm` 才会让 tier 锁定真正生效，`--override-floor`
+允许锁到计算下限以下。`--separate` 可在已有 run 仍打开时另起一个并行 run。`--force`
+让 `r2p-archive` 能归档 PLAN-TASK 未全部勾选的 executing run。
 
 大多数 run 只需要 `r2p-start`，然后反复 `r2p-continue`。当工作流输出这些命令，
 或你明确需要切换、修复、重开、执行、归档时，再使用对应的专用命令。
@@ -195,6 +218,27 @@ Standard tier 的 DESIGN/SPEC/PLAN 阶段可能要求 subagent review，尤其
 `migration`、`safety`、`cross_project` 等 tier modifier 时。如果后续阶段发现上游决策缺口，
 用 `r2p-gap-open` 路由回 owner stage，修复后再用 `r2p-gap-resolve` 关闭 route。
 
+## Executing a PLAN
+
+`r2p` 不止步于 PLAN。run 在 PLAN checkpoint 关闭后，`r2p-execute` 会在当前分支上原地
+实现它——不开新分支、不建 worktree、不 push。它假设宿主 agent 能派发 subagent，否则
+显式失败。
+
+这个循环采用 Spec-Driven Development（SDD）：
+
+- **Pre-flight**：先通读一遍 PLAN，在动工前把任何矛盾或缺陷一次性抛给你；上游缺陷会
+  路由回某个阶段重开，而不是在执行里打补丁。
+- **逐任务**：一个全新 implementer subagent 在 TDD 下只实现一个 PLAN-TASK，只提交自己
+  改动的文件并回报；随后 task-reviewer 对照 SPEC 与该任务的验证标准检查，fix 循环清掉
+  Critical 与 Important 发现后才勾选该任务。
+- **整分支评审**：全部任务完成后，由最强模型上的 final reviewer 在整个执行区间上重跑
+  完整验证套件，并把 PLAN 当作清单逐条核对。这次评审就是合并门槛。
+- **自动归档**：final review 干净地给出 `Verdict: Approved`，`r2p-execute` 才会归档该
+  run。commit 留在当前分支；`push` 和 pull request 仍需你单独显式请求。
+
+进度持久记录在 `execution/progress.md`，因此被打断的 run 会从第一个未勾选的任务继续，
+而不是从头再来。
+
 ## Development
 
 安装开发依赖：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/req-2-plan",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Requirement-to-PLAN workflow CLI and agent integration installer.",
   "bin": {
     "r2p": "bin/r2p.js"

package/tools/r2p-task-brief

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+export PYTHONPATH="$REPO_ROOT${PYTHONPATH:+:$PYTHONPATH}"
+if command -v python3 >/dev/null 2>&1; then
+    exec python3 -m tools.workflow_cli.agent_shortcuts task-brief "$@"
+else
+    exec python -m tools.workflow_cli.agent_shortcuts task-brief "$@"
+fi

package/tools/workflow_cli/agent_shortcuts.py

@@ -968,6 +968,21 @@ def _cmd_execute(ns: argparse.Namespace, base_path: Path) -> None:
     sys.exit(EXIT_CONFLICT)
 
 
+def _cmd_task_brief(ns: argparse.Namespace, base_path: Path) -> None:
+    work_id = ns.work_id
+    if not work_id:
+        pointer = read_active_pointer(base_path)
+        if not pointer:
+            print("no_selected_run: true\nnext: r2p-task-brief --work-id <id> --task <N>\n")
+            sys.exit(1)
+        work_id = pointer["selected_work_id"]
+    work_id = _validate_work_id(work_id)
+    sys.exit(_run_cli(
+        ["plan-task-brief", "--work-id", work_id, "--task", str(ns.task)],
+        base_path,
+    ))
+
+
 def _cmd_gap_open(ns: argparse.Namespace, base_path: Path) -> None:
     work_id = _validate_work_id(ns.work_id)
     args = [
@@ -1065,6 +1080,10 @@ def _build_parser() -> argparse.ArgumentParser:
     p_tier_lock.add_argument("--override-floor", action="store_true")
     p_tier_lock.add_argument("--confirm", action="store_true")
 
+    p_task_brief = sub.add_parser("task-brief")
+    p_task_brief.add_argument("--work-id", dest="work_id", default=None)
+    p_task_brief.add_argument("--task", type=int, required=True)
+
     p_gap_open = sub.add_parser("gap-open")
     p_gap_open.add_argument("--work-id", dest="work_id", required=True)
     p_gap_open.add_argument("--owner-stage", dest="owner_stage", required=True)
@@ -1104,6 +1123,7 @@ def main(args: list[str] | None = None, base_path: Path | None = None) -> None:
         "gap-open": _cmd_gap_open,
         "gap-resolve": _cmd_gap_resolve,
         "execute": _cmd_execute,
+        "task-brief": _cmd_task_brief,
     }
     handlers[ns.subcommand](ns, bp)
     sys.exit(0)

package/tools/workflow_cli/agent_templates/claude/commands/r2p-execute.md

@@ -38,26 +38,97 @@ Use the least powerful model that can handle each role:
 - **Integration / judgment / debugging** (multi-file coordination, pattern matching): standard model.
 - **Architecture / design AND the final whole-branch review**: most capable model.
 - Always specify the model explicitly when dispatching; an omitted model inherits the session model.
+- Read the task brief on demand when sizing the implementer model; do not paste or retain a rewritten copy of it.
 - **Turn count beats token price**: use a mid-tier floor for reviewers and for implementers working from prose descriptions; drop to cheapest only for complete-code/single-file mechanical tasks.
 
+## Controller Narration Discipline
+
+Between tool calls, the controller narrates at most one short line. Use the prefix `Narration:` for these inter-call notes (e.g. `Narration: implementer returned DONE, writing diff`). Never paste a subagent's returned text — report body, diff content, or review findings — into a later dispatch; reviewer findings move through `review_report_path`, not pasted text. What the controller restates into its own context is bounded to `status`, `report_path` or diff path, `review_report_path`, `commit_range`, `test_summary`, and `concerns`.
+
+## Authoritative Context Set
+
+Each subagent (implementer, reviewer, fix) receives these run-dir paths and reads them directly — bodies are never pasted:
+
+| Path | Domain |
+|---|---|
+| `02-project-context.md` | planning-time repository baseline |
+| `03-requirement-brief.md` | goal / scope / non-goals / acceptance |
+| `04-risk-discovery.md` | cross-task risks and mitigations |
+| `05-design.md` | chosen design and rejected alternatives |
+| `06-spec.md` | full behavior / interface / data / error / test contracts |
+| `execution/progress.md` | execution ledger (task ID + title list), read-only to subagents |
+
+`07-plan.md`, `00-raw-requirement.md`, and `01-intake-brief.md` are **not** in the set. No generated `task-N-context.md` bundle, `context-manifest.json`, sha256/content-hash, or drift gate is introduced.
+
+### Authority Responsibility Matrix
+
+Each authority owns exactly its domain — this is a matrix, not a priority order:
+
+| Authority | Owns |
+|---|---|
+| Task brief | Current task execution scope / files / steps / verification |
+| `03-requirement-brief.md` | Goal / scope / non-goals / acceptance |
+| `04-risk-discovery.md` | Risk constraints and mitigations |
+| `05-design.md` | Chosen architecture and rejected alternatives |
+| `06-spec.md` | Behavior / interface / data / error / test contracts |
+| `## Global Constraints` | Plan-wide execution constraints |
+| `02-project-context.md` | Planning-time repository baseline |
+| Current working tree / HEAD | Operational truth about code that exists now |
+| `00-raw-requirement.md` / `01-intake-brief.md` | Provenance only — never an execution authority |
+
+**`02` baseline-vs-working-tree rule**: a predecessor task's legitimate repo change makes the working tree the operational truth; an unexplained or conflicting difference → `BLOCKED`.
+
+**Ledger read-only rule**: only the controller flips checkboxes or appends `Resolved:`/`Gap:`/`Unresolved:`/`Minor:` records to `execution/progress.md`; subagents read but do not write to the ledger.
+
+### Conflict Rule
+
+No artifact silently overrides another outside its domain. If a task cannot satisfy all applicable authorities simultaneously, the subagent returns `BLOCKED`, names the conflicting files/IDs, and asks the human to **reopen** the owning stage — no guessing, no picking a winner, no patching around an upstream defect.
+
+### Required Consumption
+
+Each implementer, reviewer, and fix subagent must **read the full Authoritative Context Set before acting** — availability is not consumption. Subagents may skip the embedded `(read-only)` Upstream Summary / Project Context blocks within those files. On-demand depth applies only to the current codebase, git history, and prior task reports/reviews — never to whether to read an approved artifact. This rule is orthogonal to Model Selection: a cheap model on a mechanical task still reads the set.
+
+### Ledger Ownership and Sibling Escalation
+
+Default position/ownership derives from the ledger's `PLAN-TASK-NNN <title>` list (stay within the brief's Files/Steps; treat every other listed task ID as owned elsewhere). The full `07-plan.md` is not handed to subagents; whole-plan reasoning stays with the controller's Pre-flight read. An unclear sibling boundary → the subagent returns `NEEDS_CONTEXT` / `BLOCKED`; the controller resolves it or hands a specific `r2p-task-brief --task <M>` single-task brief and re-dispatches — never a whole-plan read or a guess from the title.
+
+### Path Delivery and Fail-Closed Preflight
+
+The controller derives `run_dir = parent(plan)` from the execute output and hands absolute paths by default, or repository-root-relative paths paired with an explicit `repo_root`. Each subagent runs a preflight before acting:
+1. Input paths must already exist and be readable. For each role, inputs include the Authoritative Context Set paths, the task brief path, the ledger path, and any handed report/review/diff path the subagent is meant to consume.
+2. Output paths do not need to exist at preflight. For each role, treat generated output paths as destination paths: implementer `execution/task-N-report.md`, task-reviewer `execution/task-N-review.md`, and final reviewer `execution/final-review-report.md`. Their parent directories must resolve under the same `run_dir` / `work_id` and be writable before the subagent writes.
+3. Every handed path resolves under the same `run_dir` / `work_id`.
+4. Any repo-root-relative path was resolved against the handed `repo_root`, not the process cwd.
+5. If any input path is missing or unreadable, any output parent is missing or unwritable, or any path is unresolved or wired to a different run → `BLOCKED` — no silent continue on a partial/mixed set.
+
 ## Per-Task Loop
 
 For each PLAN-TASK (in order):
 
-### 1. Extract task inline
+### 1. Run `r2p-task-brief` and obtain the task-brief path
 
-Read the task text directly from `07-plan.md`. Note the task's `Skeleton`, `Steps`, `Spec References`, and `Verification` criteria.
+Run `{{R2P_BIN_DIR}}/r2p-task-brief --work-id <work-id> --task <N>` (where `<N>` is the task's integer, e.g. `2` for `PLAN-TASK-002`) for the current task. This installed wrapper delegates to the internal `plan-task-brief` CLI command. The command returns a `brief_path` pointing to a scoped brief file that contains the task's `Skeleton`, `Steps`, `Spec References`, and `Verification` criteria. Pass the `brief_path` as the handoff pointer to both the implementer and the reviewer — not pasted task text from `07-plan.md`. The controller uses the returned `brief_path` without eager-reading the full task body into its own context; the implementer and reviewer read the task-brief on demand.
 
 ### 2. Dispatch a fresh implementer subagent
 
 Record BASE (`git rev-parse HEAD`) BEFORE dispatching the implementer — **never use `HEAD~1`** as BASE (it drops all but the last commit of a multi-commit task). For Task 1, this BASE is also `<execution-base-commit>` for the final whole-branch review. Persist the Task 1 BASE immediately in tracked execution state by adding `Execution BASE: <execution-base-commit>` to `execution/progress.md`.
 
 Provide the subagent with:
-- The task text (from `07-plan.md`)
-- Scene-setting context (project, dependencies, architectural constraints)
+- The `brief_path` returned by `r2p-task-brief` (not pasted task text from `07-plan.md`)
+- **Read the Authoritative Context Set before acting**: the `02-project-context.md` entry supplies the project/dependency/architecture baseline deterministically
+- Global Constraints from the PLAN (`## Global Constraints`), copied verbatim when present — the brief carries only the task body, so the implementer does not otherwise see plan-level constraints
 - TDD instructions: follow `Skeleton`/`Steps`; prove `Verification` with evidence
 - A report file path (`execution/task-N-report.md`)
 
+The implementer return contract is minimal and inline:
+- `status`: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+- `report_path`: the report file path
+- `commit_range`: `<base7>..<head7>` for committed task work, or `none` if no commit was created
+- `test_summary`: one-line test summary, or `not run: <reason>`
+- `concerns`: `none` or a concise list of decision-relevant concerns, missing context, or blockers
+
+The controller uses these fields to decide whether to continue without opening the full report. The controller does not ask the implementer to restate the task.
+
 The implementer must:
 1. Implement exactly what the task specifies, following TDD
 2. Satisfy the task's `Verification` criteria and attach evidence (test output, assertions)
@@ -81,20 +152,37 @@ The fresh implementer subagent verifies-then-removes ambiguity by evidence and T
 After the implementer reports DONE:
 1. `mkdir -p .req-to-plan/<work-id>/logs` then `git diff -U10 <base-commit> HEAD > .req-to-plan/<work-id>/logs/task-N-diff.md`. Keep diff scratch under `logs/` (gitignored), never under `execution/`.
 2. Dispatch a task-reviewer subagent with:
-   - The task text and `Spec References` from `07-plan.md`
-   - The implementer's report
+   - **Read the Authoritative Context Set before acting**: the reviewer checks `Spec References` IDs against the full `06-spec.md` text, not the IDs alone
+   - The `brief_path` returned by `r2p-task-brief` (not pasted task text). The reviewer reads `Spec References` from the task brief. Do not pass separate `Spec References`.
+   - The implementer report file path (`execution/task-N-report.md`)
    - The diff file path (`.req-to-plan/<work-id>/logs/task-N-diff.md`)
+   - A review report file path (`execution/task-N-review.md`)
    - Global constraints from the plan (copy verbatim from `## Global Constraints`); never pre-judge a finding's severity; never paste prior-task summaries into a later dispatch
 
-The task-reviewer returns two verdicts:
-- **Spec compliance**: checked against `Spec References` + `Verification`
+The task-reviewer writes detailed findings, if any, to `execution/task-N-review.md` and returns only this inline summary:
+- `status`: APPROVED / CHANGES_REQUESTED / NEEDS_CONTEXT / BLOCKED
+- `review_report_path`: the review report file path
+- `test_summary`: one-line test summary, or `not run: <reason>`
+- `concerns`: `none` or a concise list of decision-relevant concerns, missing context, or blockers
+
+Surface in `concerns` every ⚠️ "cannot verify from diff" item and every unfixed Minor finding — do not leave them only in the report. This is how the controller learns there is something to adjudicate (§6) without opening the report on a clean task.
+
+The review report records:
+- **Spec compliance**: checked against the task brief's `Spec References` and `Verification`
 - **Code quality**: clean, tested, maintainable
+- **⚠️ DEFER items**: explicit `cannot verify from diff` warnings for requirements satisfied by unchanged code, by sibling task work, or by evidence outside the task diff
 
 ### 6. Fix loop
 
-- Dispatch fix subagents for Critical and Important findings
-- Re-dispatch the task-reviewer after each fix wave
-- Only when the task-reviewer is clean (both spec ✅ and quality Approved, and `Verification` satisfied), update the matching `execution/progress.md` checkbox from `- [ ] PLAN-TASK-NNN ...` to `- [x] PLAN-TASK-NNN ...` and append one line:
+- Dispatch fix subagents for Critical and Important findings. Pass the `review_report_path` to the fix subagent with the instruction: Fix all Critical and Important findings in the review report. Do not paste the finding bodies into the dispatch. Also hand: **Read the Authoritative Context Set before acting**, the task brief path (`brief_path`), and the current task diff path (`logs/task-N-diff.md`).
+- After each fix wave: the fix subagent commits only its intentionally-changed files (staging only files changed for this task, exactly as the §2 implementer does); then the loop regenerates `logs/task-N-diff.md` from the task's BASE to `HEAD` (`git diff -U10 <base-commit> HEAD > .req-to-plan/<work-id>/logs/task-N-diff.md`) — commit-then-diff — before re-dispatching the task-reviewer. The re-review must not run against an uncommitted working tree.
+- Re-dispatch the task-reviewer after each fix wave with the refreshed diff path
+- Before flipping the checkbox, adjudicate each reviewer "cannot verify from diff" warning. When `concerns` lists ⚠️ items, open `review_report_path` to adjudicate each; a `none`/empty `concerns` means no ⚠️ remains to adjudicate. Record one line per finding in `execution/progress.md`:
+  - `Resolved: <finding>` — clears the warning; a `Resolved:` claim about unchanged code must cite implementation and test evidence
+  - `Gap: <finding>` — blocks the flip and cannot be overridden on the controller's own judgment
+  - `Unresolved: <finding>` — blocks the flip and cannot be overridden on the controller's own judgment
+- Minor findings not fixed within a task: record each as `Minor: <finding>` in `execution/progress.md` and carry them into the final whole-branch review input rather than dropping them per task.
+- Only when the task-reviewer is clean (both spec ✅ and quality Approved, and `Verification` satisfied, and no open `Gap:` or `Unresolved:` entries), update the matching `execution/progress.md` checkbox from `- [ ] PLAN-TASK-NNN ...` to `- [x] PLAN-TASK-NNN ...` and append one line:
   `Task N: complete (commits <base7>..<head7>, review clean)`
 
 **Continuous execution**: execute all PLAN-TASKs without pausing to ask "should I continue?" between tasks. Stop only on: unresolvable `BLOCKED`, upstream defect requiring repair, dirty-tree block, or all tasks complete. `Verification` requires fresh command output; "should pass" / "looks correct" is not evidence; do not report `DONE` without it.
@@ -105,9 +193,10 @@ After all tasks complete, dispatch a final whole-branch review subagent on the *
 - First create the whole-branch diff: `mkdir -p .req-to-plan/<work-id>/logs` then `git diff -U10 <execution-base-commit> HEAD > .req-to-plan/<work-id>/logs/final-diff.md`
 - Scope: review the complete execution range `git diff -U10 <execution-base-commit> HEAD`, where `<execution-base-commit>` is the Task 1 BASE captured before dispatching the first implementer
 - Include the diff file path (`.req-to-plan/<work-id>/logs/final-diff.md`) in the reviewer dispatch; do not ask the reviewer to infer the changed range
+- Provide a final review report path (`execution/final-review-report.md`) and require detailed findings there
 - **re-run the full verification suite** on the final HEAD and attach the fresh output (per-task greens do not catch cross-task regressions)
 - Walk the PLAN task-by-task as a line-by-line requirements checklist; report any gap
-- Dispatch ONE fix subagent carrying the complete findings list (not one fixer per finding)
+- Dispatch ONE fix subagent carrying the complete findings list by passing `execution/final-review-report.md`, not pasted findings (not one fixer per finding)
 - This whole-branch review is the merge gate
 
 After the review settles, write `execution/final-review.md` recording the reviewed range, a one-line summary, and the verdict:

package/tools/workflow_cli/agent_templates/codex/skills/r2p-execute/SKILL.md

@@ -39,26 +39,97 @@ Use the least powerful model that can handle each role:
 - **Integration / judgment / debugging** (multi-file coordination, pattern matching): standard model.
 - **Architecture / design AND the final whole-branch review**: most capable model.
 - Always specify the model explicitly when dispatching; an omitted model inherits the session model.
+- Read the task brief on demand when sizing the implementer model; do not paste or retain a rewritten copy of it.
 - **Turn count beats token price**: use a mid-tier floor for reviewers and for implementers working from prose descriptions; drop to cheapest only for complete-code/single-file mechanical tasks.
 
+## Controller Narration Discipline
+
+Between tool calls, the controller narrates at most one short line. Use the prefix `Narration:` for these inter-call notes (e.g. `Narration: implementer returned DONE, writing diff`). Never paste a subagent's returned text — report body, diff content, or review findings — into a later dispatch; reviewer findings move through `review_report_path`, not pasted text. What the controller restates into its own context is bounded to `status`, `report_path` or diff path, `review_report_path`, `commit_range`, `test_summary`, and `concerns`.
+
+## Authoritative Context Set
+
+Each subagent (implementer, reviewer, fix) receives these run-dir paths and reads them directly — bodies are never pasted:
+
+| Path | Domain |
+|---|---|
+| `02-project-context.md` | planning-time repository baseline |
+| `03-requirement-brief.md` | goal / scope / non-goals / acceptance |
+| `04-risk-discovery.md` | cross-task risks and mitigations |
+| `05-design.md` | chosen design and rejected alternatives |
+| `06-spec.md` | full behavior / interface / data / error / test contracts |
+| `execution/progress.md` | execution ledger (task ID + title list), read-only to subagents |
+
+`07-plan.md`, `00-raw-requirement.md`, and `01-intake-brief.md` are **not** in the set. No generated `task-N-context.md` bundle, `context-manifest.json`, sha256/content-hash, or drift gate is introduced.
+
+### Authority Responsibility Matrix
+
+Each authority owns exactly its domain — this is a matrix, not a priority order:
+
+| Authority | Owns |
+|---|---|
+| Task brief | Current task execution scope / files / steps / verification |
+| `03-requirement-brief.md` | Goal / scope / non-goals / acceptance |
+| `04-risk-discovery.md` | Risk constraints and mitigations |
+| `05-design.md` | Chosen architecture and rejected alternatives |
+| `06-spec.md` | Behavior / interface / data / error / test contracts |
+| `## Global Constraints` | Plan-wide execution constraints |
+| `02-project-context.md` | Planning-time repository baseline |
+| Current working tree / HEAD | Operational truth about code that exists now |
+| `00-raw-requirement.md` / `01-intake-brief.md` | Provenance only — never an execution authority |
+
+**`02` baseline-vs-working-tree rule**: a predecessor task's legitimate repo change makes the working tree the operational truth; an unexplained or conflicting difference → `BLOCKED`.
+
+**Ledger read-only rule**: only the controller flips checkboxes or appends `Resolved:`/`Gap:`/`Unresolved:`/`Minor:` records to `execution/progress.md`; subagents read but do not write to the ledger.
+
+### Conflict Rule
+
+No artifact silently overrides another outside its domain. If a task cannot satisfy all applicable authorities simultaneously, the subagent returns `BLOCKED`, names the conflicting files/IDs, and asks the human to **reopen** the owning stage — no guessing, no picking a winner, no patching around an upstream defect.
+
+### Required Consumption
+
+Each implementer, reviewer, and fix subagent must **read the full Authoritative Context Set before acting** — availability is not consumption. Subagents may skip the embedded `(read-only)` Upstream Summary / Project Context blocks within those files. On-demand depth applies only to the current codebase, git history, and prior task reports/reviews — never to whether to read an approved artifact. This rule is orthogonal to Model Selection: a cheap model on a mechanical task still reads the set.
+
+### Ledger Ownership and Sibling Escalation
+
+Default position/ownership derives from the ledger's `PLAN-TASK-NNN <title>` list (stay within the brief's Files/Steps; treat every other listed task ID as owned elsewhere). The full `07-plan.md` is not handed to subagents; whole-plan reasoning stays with the controller's Pre-flight read. An unclear sibling boundary → the subagent returns `NEEDS_CONTEXT` / `BLOCKED`; the controller resolves it or hands a specific `r2p-task-brief --task <M>` single-task brief and re-dispatches — never a whole-plan read or a guess from the title.
+
+### Path Delivery and Fail-Closed Preflight
+
+The controller derives `run_dir = parent(plan)` from the execute output and hands absolute paths by default, or repository-root-relative paths paired with an explicit `repo_root`. Each subagent runs a preflight before acting:
+1. Input paths must already exist and be readable. For each role, inputs include the Authoritative Context Set paths, the task brief path, the ledger path, and any handed report/review/diff path the subagent is meant to consume.
+2. Output paths do not need to exist at preflight. For each role, treat generated output paths as destination paths: implementer `execution/task-N-report.md`, task-reviewer `execution/task-N-review.md`, and final reviewer `execution/final-review-report.md`. Their parent directories must resolve under the same `run_dir` / `work_id` and be writable before the subagent writes.
+3. Every handed path resolves under the same `run_dir` / `work_id`.
+4. Any repo-root-relative path was resolved against the handed `repo_root`, not the process cwd.
+5. If any input path is missing or unreadable, any output parent is missing or unwritable, or any path is unresolved or wired to a different run → `BLOCKED` — no silent continue on a partial/mixed set.
+
 ## Per-Task Loop
 
 For each PLAN-TASK (in order):
 
-### 1. Extract task inline
+### 1. Run `r2p-task-brief` and obtain the task-brief path
 
-Read the task text directly from `07-plan.md`. Note the task's `Skeleton`, `Steps`, `Spec References`, and `Verification` criteria.
+Run `{{R2P_BIN_DIR}}/r2p-task-brief --work-id <work-id> --task <N>` (where `<N>` is the task's integer, e.g. `2` for `PLAN-TASK-002`) for the current task. This installed wrapper delegates to the internal `plan-task-brief` CLI command. The command returns a `brief_path` pointing to a scoped brief file that contains the task's `Skeleton`, `Steps`, `Spec References`, and `Verification` criteria. Pass the `brief_path` as the handoff pointer to both the implementer and the reviewer — not pasted task text from `07-plan.md`. The controller uses the returned `brief_path` without eager-reading the full task body into its own context; the implementer and reviewer read the task-brief on demand.
 
 ### 2. Dispatch a fresh implementer subagent
 
 Record BASE (`git rev-parse HEAD`) BEFORE dispatching the implementer — **never use `HEAD~1`** as BASE (it drops all but the last commit of a multi-commit task). For Task 1, this BASE is also `<execution-base-commit>` for the final whole-branch review. Persist the Task 1 BASE immediately in tracked execution state by adding `Execution BASE: <execution-base-commit>` to `execution/progress.md`.
 
 Provide the subagent with:
-- The task text (from `07-plan.md`)
-- Scene-setting context (project, dependencies, architectural constraints)
+- The `brief_path` returned by `r2p-task-brief` (not pasted task text from `07-plan.md`)
+- **Read the Authoritative Context Set before acting**: the `02-project-context.md` entry supplies the project/dependency/architecture baseline deterministically
+- Global Constraints from the PLAN (`## Global Constraints`), copied verbatim when present — the brief carries only the task body, so the implementer does not otherwise see plan-level constraints
 - TDD instructions: follow `Skeleton`/`Steps`; prove `Verification` with evidence
 - A report file path (`execution/task-N-report.md`)
 
+The implementer return contract is minimal and inline:
+- `status`: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+- `report_path`: the report file path
+- `commit_range`: `<base7>..<head7>` for committed task work, or `none` if no commit was created
+- `test_summary`: one-line test summary, or `not run: <reason>`
+- `concerns`: `none` or a concise list of decision-relevant concerns, missing context, or blockers
+
+The controller uses these fields to decide whether to continue without opening the full report. The controller does not ask the implementer to restate the task.
+
 The implementer must:
 1. Implement exactly what the task specifies, following TDD
 2. Satisfy the task's `Verification` criteria and attach evidence (test output, assertions)
@@ -82,20 +153,37 @@ The fresh implementer subagent verifies-then-removes ambiguity by evidence and T
 After the implementer reports DONE:
 1. `mkdir -p .req-to-plan/<work-id>/logs` then `git diff -U10 <base-commit> HEAD > .req-to-plan/<work-id>/logs/task-N-diff.md`. Keep diff scratch under `logs/` (gitignored), never under `execution/`.
 2. Dispatch a task-reviewer subagent with:
-   - The task text and `Spec References` from `07-plan.md`
-   - The implementer's report
+   - **Read the Authoritative Context Set before acting**: the reviewer checks `Spec References` IDs against the full `06-spec.md` text, not the IDs alone
+   - The `brief_path` returned by `r2p-task-brief` (not pasted task text). The reviewer reads `Spec References` from the task brief. Do not pass separate `Spec References`.
+   - The implementer report file path (`execution/task-N-report.md`)
    - The diff file path (`.req-to-plan/<work-id>/logs/task-N-diff.md`)
+   - A review report file path (`execution/task-N-review.md`)
    - Global constraints from the plan (copy verbatim from `## Global Constraints`); never pre-judge a finding's severity; never paste prior-task summaries into a later dispatch
 
-The task-reviewer returns two verdicts:
-- **Spec compliance**: checked against `Spec References` + `Verification`
+The task-reviewer writes detailed findings, if any, to `execution/task-N-review.md` and returns only this inline summary:
+- `status`: APPROVED / CHANGES_REQUESTED / NEEDS_CONTEXT / BLOCKED
+- `review_report_path`: the review report file path
+- `test_summary`: one-line test summary, or `not run: <reason>`
+- `concerns`: `none` or a concise list of decision-relevant concerns, missing context, or blockers
+
+Surface in `concerns` every ⚠️ "cannot verify from diff" item and every unfixed Minor finding — do not leave them only in the report. This is how the controller learns there is something to adjudicate (§6) without opening the report on a clean task.
+
+The review report records:
+- **Spec compliance**: checked against the task brief's `Spec References` and `Verification`
 - **Code quality**: clean, tested, maintainable
+- **⚠️ DEFER items**: explicit `cannot verify from diff` warnings for requirements satisfied by unchanged code, by sibling task work, or by evidence outside the task diff
 
 ### 6. Fix loop
 
-- Dispatch fix subagents for Critical and Important findings
-- Re-dispatch the task-reviewer after each fix wave
-- Only when the task-reviewer is clean (both spec ✅ and quality Approved, and `Verification` satisfied), update the matching `execution/progress.md` checkbox from `- [ ] PLAN-TASK-NNN ...` to `- [x] PLAN-TASK-NNN ...` and append one line:
+- Dispatch fix subagents for Critical and Important findings. Pass the `review_report_path` to the fix subagent with the instruction: Fix all Critical and Important findings in the review report. Do not paste the finding bodies into the dispatch. Also hand: **Read the Authoritative Context Set before acting**, the task brief path (`brief_path`), and the current task diff path (`logs/task-N-diff.md`).
+- After each fix wave: the fix subagent commits only its intentionally-changed files (staging only files changed for this task, exactly as the §2 implementer does); then the loop regenerates `logs/task-N-diff.md` from the task's BASE to `HEAD` (`git diff -U10 <base-commit> HEAD > .req-to-plan/<work-id>/logs/task-N-diff.md`) — commit-then-diff — before re-dispatching the task-reviewer. The re-review must not run against an uncommitted working tree.
+- Re-dispatch the task-reviewer after each fix wave with the refreshed diff path
+- Before flipping the checkbox, adjudicate each reviewer "cannot verify from diff" warning. When `concerns` lists ⚠️ items, open `review_report_path` to adjudicate each; a `none`/empty `concerns` means no ⚠️ remains to adjudicate. Record one line per finding in `execution/progress.md`:
+  - `Resolved: <finding>` — clears the warning; a `Resolved:` claim about unchanged code must cite implementation and test evidence
+  - `Gap: <finding>` — blocks the flip and cannot be overridden on the controller's own judgment
+  - `Unresolved: <finding>` — blocks the flip and cannot be overridden on the controller's own judgment
+- Minor findings not fixed within a task: record each as `Minor: <finding>` in `execution/progress.md` and carry them into the final whole-branch review input rather than dropping them per task.
+- Only when the task-reviewer is clean (both spec ✅ and quality Approved, and `Verification` satisfied, and no open `Gap:` or `Unresolved:` entries), update the matching `execution/progress.md` checkbox from `- [ ] PLAN-TASK-NNN ...` to `- [x] PLAN-TASK-NNN ...` and append one line:
   `Task N: complete (commits <base7>..<head7>, review clean)`
 
 **Continuous execution**: execute all PLAN-TASKs without pausing to ask "should I continue?" between tasks. Stop only on: unresolvable `BLOCKED`, upstream defect requiring repair, dirty-tree block, or all tasks complete. `Verification` requires fresh command output; "should pass" / "looks correct" is not evidence; do not report `DONE` without it.
@@ -106,9 +194,10 @@ After all tasks complete, dispatch a final whole-branch review subagent on the *
 - First create the whole-branch diff: `mkdir -p .req-to-plan/<work-id>/logs` then `git diff -U10 <execution-base-commit> HEAD > .req-to-plan/<work-id>/logs/final-diff.md`
 - Scope: review the complete execution range `git diff -U10 <execution-base-commit> HEAD`, where `<execution-base-commit>` is the Task 1 BASE captured before dispatching the first implementer
 - Include the diff file path (`.req-to-plan/<work-id>/logs/final-diff.md`) in the reviewer dispatch; do not ask the reviewer to infer the changed range
+- Provide a final review report path (`execution/final-review-report.md`) and require detailed findings there
 - **re-run the full verification suite** on the final HEAD and attach the fresh output (per-task greens do not catch cross-task regressions)
 - Walk the PLAN task-by-task as a line-by-line requirements checklist; report any gap
-- Dispatch ONE fix subagent carrying the complete findings list (not one fixer per finding)
+- Dispatch ONE fix subagent carrying the complete findings list by passing `execution/final-review-report.md`, not pasted findings (not one fixer per finding)
 - This whole-branch review is the merge gate
 
 After the review settles, write `execution/final-review.md` recording the reviewed range, a one-line summary, and the verdict:

package/tools/workflow_cli/cli.py

@@ -68,7 +68,12 @@ from tools.workflow_cli.output import (
 from tools.workflow_cli.tier import estimate_tier, scan_keywords
 from tools.workflow_cli.workspace import ensure_workspace_gitignore, commit_requirement_dir
 from tools.workflow_cli.atomic import atomic_write_text
-from tools.workflow_cli.markdown import plan_task_anchors, strip_readonly_sections
+from tools.workflow_cli.markdown import (
+    PLAN_TASK_ANCHOR_RE,
+    heading_bounded_bodies,
+    plan_task_anchors,
+    strip_readonly_sections,
+)
 
 
 # ---------------------------------------------------------------------------
@@ -936,9 +941,9 @@ def _cmd_gap_open(args):
         )
         mgr.save(record)
     except Exception as e:
-        run_md_path.write_text(run_md_before, encoding="utf-8")
+        atomic_write_text(run_md_path, run_md_before)
         for _d, _aa, _artifact_file, artifact_path, artifact_before in reversed(affected):
-            artifact_path.write_text(artifact_before, encoding="utf-8")
+            atomic_write_text(artifact_path, artifact_before)
         print_and_exit(
             format_error(
                 f"Cannot gap-open: failed to mark downstream stale atomically ({e})",
@@ -1624,6 +1629,76 @@ def _cmd_stage_ready(args):
     )
 
 
+# ---------------------------------------------------------------------------
+# plan-task-brief
+# ---------------------------------------------------------------------------
+
+
+def _positive_int(raw: str) -> int:
+    """argparse type: positive integer (>= 1); raises ArgumentTypeError → exit 2."""
+    try:
+        n = int(raw)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"expected a positive integer, got {raw!r}")
+    if n < 1:
+        raise argparse.ArgumentTypeError(f"task number must be >= 1, got {n}")
+    return n
+
+
+def _cmd_plan_task_brief(args):
+    """Write a read-only task brief for one PLAN-TASK-NNN to logs/task-N-brief.md."""
+    record, mgr, run_dir = _load_run(args.work_id, args.base_path)
+    if record.status != RunStatus.EXECUTING:
+        print_and_exit(
+            format_error(
+                "plan-task-brief requires an EXECUTING run",
+                exit_code=EXIT_CONFLICT,
+            ),
+            EXIT_CONFLICT,
+        )
+    try:
+        plan_text = read_artifact(run_dir, Stage.PLAN)
+    except FileNotFoundError:
+        print_and_exit(
+            format_error("PLAN artifact not found", exit_code=EXIT_NOT_FOUND),
+            EXIT_NOT_FOUND,
+        )
+    stripped = strip_readonly_sections(plan_text)
+    anchors = plan_task_anchors(stripped)
+    bodies = list(heading_bounded_bodies(stripped, PLAN_TASK_ANCHOR_RE.match))
+    target_idx = None
+    for i, (tid, _title) in enumerate(anchors):
+        m = re.match(r"PLAN-TASK-(\d+)", tid)
+        if m and int(m.group(1)) == args.task:
+            target_idx = i
+            break
+    if target_idx is None:
+        print_and_exit(
+            format_error(f"task {args.task} not found in PLAN", exit_code=EXIT_NOT_FOUND),
+            EXIT_NOT_FOUND,
+        )
+    task_id = anchors[target_idx][0]
+    body = bodies[target_idx]
+    logs_dir = run_dir / "logs"
+    _reject_symlink_or_exit(logs_dir, "logs dir is a symlink")
+    brief_path = logs_dir / f"task-{args.task}-brief.md"
+    _reject_symlink_or_exit(brief_path, "brief target is a symlink")
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(brief_path, body)
+    rel = brief_path.relative_to(run_dir.parent.parent)
+    print_and_exit(
+        format_success(
+            {
+                "work_id": args.work_id,
+                "task_id": task_id,
+                "brief_path": rel.as_posix(),
+            },
+            message="task brief written",
+        ),
+        EXIT_OK,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Subparser registration
 # ---------------------------------------------------------------------------
@@ -1684,6 +1759,20 @@ def _register_run_commands(subparsers):
     p.add_argument("--work-id", required=True)
     p.set_defaults(func=_cmd_run_execute_start)
 
+    # plan-task-brief
+    p = subparsers.add_parser(
+        "plan-task-brief",
+        help="Write a read-only brief for one PLAN task to logs/task-N-brief.md",
+    )
+    p.add_argument("--work-id", required=True, help="Workflow run ID")
+    p.add_argument(
+        "--task",
+        required=True,
+        type=_positive_int,
+        help="Task number to extract (positive integer, e.g. 2 for PLAN-TASK-002)",
+    )
+    p.set_defaults(func=_cmd_plan_task_brief)
+
 
 def _register_tier_commands(subparsers):
     # tier-estimate

package/tools/workflow_cli/install.py

@@ -18,6 +18,7 @@ from pathlib import Path
 from typing import Any
 
 from tools.workflow_cli.version import R2P_VERSION
+from tools.workflow_cli.atomic import atomic_write_text
 
 
 # ---------------------------------------------------------------------------
@@ -1120,6 +1121,6 @@ def _safe_write(
         backup = _backup_path(backup_dir, dest)
         shutil.copy2(str(dest), str(backup))
         backups.append({"target": str(dest), "backup": str(backup)})
-    dest.write_text(content, encoding="utf-8")
+    atomic_write_text(dest, content)
     installed_paths.append(str(dest))
     written.append(dest)

package/tools/workflow_cli/version.py

@@ -1 +1 @@
-R2P_VERSION = "0.6.0"
+R2P_VERSION = "0.6.1"