@xenonbyte/req-2-plan 0.5.2 → 0.6.1

package/README.md

@@ -43,7 +43,7 @@ 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.
 
@@ -109,20 +109,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

package/README.zh-CN.md

@@ -38,7 +38,7 @@ 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 接入当前分支上的实现循环。
 
@@ -101,18 +101,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:` 命令执行，

package/package.json

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

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

@@ -31,6 +31,15 @@ Before dispatching Task 1, read `07-plan.md` once and scan for:
 Batch all findings into one question to the human **before** execution begins. If the scan is clean, proceed without comment.
 If a finding requires PLAN, SPEC, or DESIGN repair, stop and ask the human to reopen from the affected stage rather than patching over it in execution.
 
+## Model Selection
+
+Use the least powerful model that can handle each role:
+- **Mechanical implementation** (isolated, clear spec, complete `Skeleton`, 1–2 files): fast/cheap model.
+- **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.
+- **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.
+
 ## Per-Task Loop
 
 For each PLAN-TASK (in order):
@@ -41,6 +50,8 @@ Read the task text directly from `07-plan.md`. Note the task's `Skeleton`, `Step
 
 ### 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)
@@ -68,12 +79,12 @@ The fresh implementer subagent verifies-then-removes ambiguity by evidence and T
 ### 5. Write diff and dispatch task-reviewer
 
 After the implementer reports DONE:
-1. Record the diff inline: `git diff -U10 <base-commit> HEAD` (no external script needed)
+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
-   - The diff
-   - Global constraints from the plan
+   - The diff file path (`.req-to-plan/<work-id>/logs/task-N-diff.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`
@@ -86,14 +97,27 @@ The task-reviewer returns two verdicts:
 - 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:
   `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.
+
 ## Final Whole-Branch Review
 
-After all tasks complete, dispatch a final whole-branch review subagent:
-- Scope: all commits since the branch started (or since `closed_at_plan_checkpoint`)
-- Include the diff (`git diff -U10 <merge-base> HEAD`)
-- Dispatch fix subagents for any Critical/Important findings before marking done
+After all tasks complete, dispatch a final whole-branch review subagent on the **most capable model**:
+- 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
+- **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)
 - 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:
+- `Verdict: Approved` when the review is clean
+- `Verdict: Changes Requested` while findings remain
+- After any final-review fix wave, regenerate `.req-to-plan/<work-id>/logs/final-diff.md` from the same `<execution-base-commit>` to current `HEAD`, re-run the full verification suite, and re-dispatch the final whole-branch reviewer with the refreshed diff and output
+- Repeat until the post-fix reviewer is clean; only then append `Verdict: Approved` as the final unfenced verdict (the gate reads the last one)
+
+Note: `r2p-archive` refuses to archive an executing run unless this file's current verdict is `Verdict: Approved`.
+
 ## Auto-Archive on Completion
 
 When all tasks are done and the final whole-branch review is clean, call:
@@ -109,6 +133,7 @@ Commits are already on the **current branch**. `push` and PR creation still requ
 ## Durable Progress
 
 Track progress in `execution/progress.md` (not only in todos). On resume, read the ledger and skip tasks already marked complete.
+On resume, read `execution/progress.md` before the final review and reuse its `Execution BASE:` line as `<execution-base-commit>`. Do not recalculate it from `HEAD` or from the latest task range. If the line is missing, stop and ask the human for the original Task 1 BASE instead of inferring a range.
 
 ## Error Reference
 

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

@@ -9,4 +9,4 @@ To start from a requirement document, pass `--file <path>` instead of inline tex
 
 Use `--separate` to create an independent run when another open run exists.
 
-Optionally pass `--repo-path <dir>` to ground tier estimation and the Project Context Pack in real repo facts.
+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.

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

@@ -32,6 +32,15 @@ Before dispatching Task 1, read `07-plan.md` once and scan for:
 Batch all findings into one question to the human **before** execution begins — one interrupt, not one per discovery. If the scan is clean, proceed without comment. The task-reviewer loop catches conflicts that only emerge from implementation.
 If a finding requires PLAN, SPEC, or DESIGN repair, stop and ask the human to reopen from the affected stage rather than patching over it in execution.
 
+## Model Selection
+
+Use the least powerful model that can handle each role:
+- **Mechanical implementation** (isolated, clear spec, complete `Skeleton`, 1–2 files): fast/cheap model.
+- **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.
+- **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.
+
 ## Per-Task Loop
 
 For each PLAN-TASK (in order):
@@ -42,6 +51,8 @@ Read the task text directly from `07-plan.md`. Note the task's `Skeleton`, `Step
 
 ### 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)
@@ -69,12 +80,12 @@ The fresh implementer subagent verifies-then-removes ambiguity by evidence and T
 ### 5. Write diff and dispatch task-reviewer
 
 After the implementer reports DONE:
-1. Record the diff inline: `git diff -U10 <base-commit> HEAD`
+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
-   - The diff
-   - Global constraints from the plan
+   - The diff file path (`.req-to-plan/<work-id>/logs/task-N-diff.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`
@@ -87,13 +98,26 @@ The task-reviewer returns two verdicts:
 - 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:
   `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.
+
 ## Final Whole-Branch Review
 
-After all tasks complete, dispatch a final whole-branch review subagent:
-- Scope: all commits since the branch started (or since `closed_at_plan_checkpoint`)
-- Include the diff (`git diff -U10 <merge-base> HEAD`)
+After all tasks complete, dispatch a final whole-branch review subagent on the **most capable model**:
+- 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
+- **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)
 - This whole-branch review is the merge gate
-- Dispatch fix subagents for any Critical/Important findings before marking done
+
+After the review settles, write `execution/final-review.md` recording the reviewed range, a one-line summary, and the verdict:
+- `Verdict: Approved` when the review is clean
+- `Verdict: Changes Requested` while findings remain
+- After any final-review fix wave, regenerate `.req-to-plan/<work-id>/logs/final-diff.md` from the same `<execution-base-commit>` to current `HEAD`, re-run the full verification suite, and re-dispatch the final whole-branch reviewer with the refreshed diff and output
+- Repeat until the post-fix reviewer is clean; only then append `Verdict: Approved` as the final unfenced verdict (the gate reads the last one)
+
+Note: `r2p-archive` refuses to archive an executing run unless this file's current verdict is `Verdict: Approved`.
 
 ## Auto-Archive on Completion
 
@@ -110,6 +134,7 @@ Commits are already on the **current branch**. `push` and PR creation still requ
 ## Durable Progress
 
 Track progress in `execution/progress.md` (not only in todos). On resume, read the ledger and skip tasks already marked complete.
+On resume, read `execution/progress.md` before the final review and reuse its `Execution BASE:` line as `<execution-base-commit>`. Do not recalculate it from `HEAD` or from the latest task range. If the line is missing, stop and ask the human for the original Task 1 BASE instead of inferring a range.
 
 ## Error Reference
 

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

@@ -13,4 +13,4 @@ To start from a requirement document, pass `--file <path>` instead of inline tex
 
 Use `--separate` to create an independent run when another open run exists.
 
-Optionally pass `--repo-path <dir>` to ground tier estimation and the Project Context Pack in real repo facts.
+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.

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-start.toml

@@ -1,4 +1,4 @@
 name = "r2p-start"
-description = "Start a new requirement-to-PLAN workflow run. Optionally pass --repo-path <dir> to ground tier estimation and the Project Context Pack in real repo facts."
+description = "Start a new requirement-to-PLAN workflow run. 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."
 command = "{{R2P_BIN_DIR}}/r2p-start"
 version = "{{R2P_VERSION}}"

package/tools/workflow_cli/cli.py

@@ -47,6 +47,7 @@ from tools.workflow_cli.gates import (
     check_quality_gate,
     check_forced_subagent_review,
     check_execution_complete,
+    check_final_review_recorded,
 )
 from tools.workflow_cli.output import (
     COMPACT_DETAIL_LIMIT,
@@ -284,7 +285,16 @@ def _cmd_run_start(args):
             format_error("Requirement must not be blank", exit_code=EXIT_CLI_ERR),
             EXIT_CLI_ERR,
         )
-    repo_path = _validate_repo_path(args.repo_path) if args.repo_path else None
+    if args.repo_path:
+        repo_path = _validate_repo_path(args.repo_path)
+    else:
+        # --repo-path is optional: default to the workspace root (--base-path,
+        # which itself defaults to the current directory) so tier estimation and
+        # the Project Context Pack are grounded in real repo facts without an
+        # explicit flag. A standard-tier PLAN later requires a usable Context Pack
+        # (R11), so grounding by default avoids a silent gate failure. Using
+        # base_path (not literal Path.cwd()) preserves --base-path test isolation.
+        repo_path = args.base_path or Path.cwd()
     run_dir = _reject_symlinked_run_paths(work_id, args.base_path)
     mgr = RunStateManager(run_dir)
 
@@ -613,7 +623,13 @@ def _cmd_run_reopen(args):
             last_operation="reopen_from_execution",
             next_operation=f"continue_reopened_run:{new_work_id}",
         )
-        source_mgr.save(source_record)
+        try:
+            source_mgr.save(source_record)
+        except Exception:
+            # Roll back the just-created new run so no orphan is left and the
+            # source stays consistently EXECUTING.
+            shutil.rmtree(new_run_dir, ignore_errors=True)
+            raise
 
     print_and_exit(
         format_success(
@@ -656,6 +672,17 @@ def _cmd_run_archive(args):
                 ),
                 gate.exit_code,
             )
+        # 0b. Final-review gate: the whole-branch review verdict must be recorded.
+        # --force bypasses (abandoned/superseded run already skips this block).
+        review_gate = check_final_review_recorded(run_dir)
+        if not review_gate.passed:
+            print_and_exit(
+                format_error(
+                    " ".join(review_gate.issues),
+                    exit_code=review_gate.exit_code,
+                ),
+                review_gate.exit_code,
+            )
     # 1. Refuse to clobber an existing archived copy before mutating state.
     archive_dir = base / ".req-to-plan" / "archive" / str(record.work_id)
     if archive_dir.exists():
@@ -909,9 +936,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})",
@@ -1614,7 +1641,11 @@ def _register_run_commands(subparsers):
         default=None,
         help="Path to a file whose contents are the raw requirement",
     )
-    p.add_argument("--repo-path", default=None, help="Path to repository for baseline scan")
+    p.add_argument(
+        "--repo-path",
+        default=None,
+        help="Path to repository for baseline scan (default: current directory / --base-path)",
+    )
     p.add_argument("--overwrite", action="store_true", help="Overwrite an existing run")
     p.set_defaults(func=_cmd_run_start)
 

package/tools/workflow_cli/context_pack.py

@@ -11,6 +11,7 @@ try:
 except ImportError:  # pragma: no cover - older interpreters: pyproject parsing degrades to a no-op
     tomllib = None
 
+from tools.workflow_cli.atomic import atomic_write_text
 from tools.workflow_cli.repo_baseline import SKIP_DIRS, scan_repo_baseline
 
 _CONFIG_NAMES = {
@@ -167,6 +168,9 @@ def to_markdown(pack: ProjectContextPack) -> str:
 def write_context_pack(pack: ProjectContextPack, run_dir: Path) -> tuple[Path, Path]:
     json_path = run_dir / "02-project-context.json"
     md_path = run_dir / "02-project-context.md"
-    json_path.write_text(to_json(pack), encoding="utf-8")
-    md_path.write_text(to_markdown(pack), encoding="utf-8")
+    for target in (json_path, md_path):
+        if target.is_symlink():
+            raise ValueError(f"refusing to write through symlink: {target}")
+    atomic_write_text(json_path, to_json(pack))
+    atomic_write_text(md_path, to_markdown(pack))
     return md_path, json_path

package/tools/workflow_cli/gates.py

@@ -1110,6 +1110,90 @@ def check_forced_subagent_review(
     )
 
 
+# ---------------------------------------------------------------------------
+# Final Review Presence Gate
+# ---------------------------------------------------------------------------
+
+_FINAL_REVIEW_DISCLAIMER = (
+    "Presence check on the review audit trail — not a correctness guarantee."
+)
+_SUPPORTED_VERDICTS = {"approved", "changes requested"}
+
+_CANONICAL_NOT_APPROVED_MSG = (
+    "Final whole-branch review not approved: execution/final-review.md is missing, "
+    "or its current (last unfenced) 'Verdict:' line is not 'Approved'. "
+    + _FINAL_REVIEW_DISCLAIMER
+    + " Record 'Verdict: Approved', or re-run with --force to archive an abandoned run."
+)
+
+
+def _fail_gate(msg: str) -> GateResult:
+    return GateResult(passed=False, issues=[msg], exit_code=EXIT_GATE_FAIL)
+
+
+def _current_verdict(text: str) -> str | None:
+    """Return the last unfenced 'Verdict:' value (stripped, lowercased), or None."""
+    value = None
+    for line, _, _ in unfenced_markdown_lines(text):
+        s = line.strip()
+        if s[:8].lower() == "verdict:":
+            value = s[8:].strip().lower()  # last one wins
+    return value
+
+
+def _has_verdict(text: str) -> bool:
+    return _current_verdict(text) is not None
+
+
+def check_final_review_recorded(run_dir: Path) -> GateResult:
+    """Archive precondition: the final whole-branch review verdict is recorded.
+
+    Presence/audit only — never runs code or tests, never asserts the verdict is
+    true. Same trust level as the PLAN-TASK checkbox gate.
+    """
+    marker = run_dir / "execution" / "final-review.md"
+    text, err = _read_regular_text_no_symlink(marker)
+
+    if err == "missing":
+        return _fail_gate(_CANONICAL_NOT_APPROVED_MSG)
+
+    if err == "symlink":
+        return _fail_gate(
+            "execution/final-review.md is a symlink; refusing to read "
+            "outside the run directory. " + _FINAL_REVIEW_DISCLAIMER
+        )
+
+    if err == "not_regular":
+        return _fail_gate(
+            "execution/final-review.md is not a regular file. "
+            + _FINAL_REVIEW_DISCLAIMER
+        )
+
+    assert text is not None
+
+    if not _has_verdict(text):
+        # Case d: regular file, zero unfenced Verdict: lines
+        return _fail_gate(_CANONICAL_NOT_APPROVED_MSG)
+
+    current = _current_verdict(text)  # last unfenced 'Verdict:' value, lowercased
+    assert current is not None  # guarded by _has_verdict above
+
+    if current not in _SUPPORTED_VERDICTS:
+        return _fail_gate(
+            "execution/final-review.md current 'Verdict:' value is unsupported. "
+            + _FINAL_REVIEW_DISCLAIMER
+        )
+
+    if current == "changes requested":
+        return _fail_gate(
+            "Final whole-branch review not approved: current 'Verdict:' is "
+            "'Changes Requested'. " + _FINAL_REVIEW_DISCLAIMER
+        )
+
+    # current == "approved"
+    return GateResult(passed=True, issues=[], exit_code=0)
+
+
 # ---------------------------------------------------------------------------
 # Execution Completion Gate
 # ---------------------------------------------------------------------------

package/tools/workflow_cli/install.py

@@ -6,6 +6,7 @@ Supports: claude, codex, gemini, opencode
 from __future__ import annotations
 
 import os
+import secrets
 import json
 import hashlib
 import shutil
@@ -17,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
 
 
 # ---------------------------------------------------------------------------
@@ -204,15 +206,7 @@ class InstallService:
                 "r2p_version": R2P_VERSION,
                 "schema_version": SCHEMA_VERSION,
             }
-            self._validate_install_path(manifest_path, field="manifest")
-            manifest_path.parent.mkdir(parents=True, exist_ok=True)
-            tmp = manifest_path.with_name(manifest_path.name + ".tmp")
-            # The temp sibling shares the (validated) parent, but its own path is
-            # untrusted: reject a planted symlink so the atomic write cannot be
-            # redirected outside the manifest dir.
-            self._validate_install_path(tmp, field="manifest")
-            tmp.write_text(_dump_manifest(manifest), encoding="utf-8")
-            tmp.replace(manifest_path)
+            self._write_manifest_atomic(manifest_path, _dump_manifest(manifest))
             manifest_written = True
 
             # Remove obsolete managed shared wrappers (e.g. a 0.1.2 r2p-adapt) that
@@ -671,7 +665,14 @@ class InstallService:
             for mpath in sorted(install_dir.glob("*.yaml")):
                 if self._load_manifest_for_cleanup(mpath) is None:
                     continue
-                self._strip_path_from_manifest(mpath, path_str)
+                try:
+                    self._strip_path_from_manifest(mpath, path_str)
+                except ValueError:
+                    # Best-effort cleanup: _write_manifest_atomic rejects writes
+                    # that would follow an untrusted symlink. A symlinked or
+                    # otherwise unsafe manifest is left in place for operator
+                    # repair rather than aborting the in-progress install.
+                    continue
             # Delete the obsolete managed wrapper only when there was no user
             # original to restore in its place.
             if not restored and path_str not in preserve_paths:
@@ -772,7 +773,7 @@ class InstallService:
             changed = True
 
         if changed:
-            manifest_path.write_text(_dump_manifest(manifest), encoding="utf-8")
+            self._write_manifest_atomic(manifest_path, _dump_manifest(manifest))
 
     def _load_manifest_for_cleanup(self, manifest_path: Path) -> dict[str, Any] | None:
         """Load a manifest during best-effort shared-wrapper cleanup.
@@ -829,8 +830,44 @@ class InstallService:
                 file_snapshot.path.chmod(file_snapshot.mode)
             except OSError:
                 pass
-        snapshot.manifest_path.parent.mkdir(parents=True, exist_ok=True)
-        snapshot.manifest_path.write_text(snapshot.manifest_text, encoding="utf-8")
+        self._write_manifest_atomic(snapshot.manifest_path, snapshot.manifest_text)
+
+    def _write_manifest_atomic(self, manifest_path: Path, data: str) -> None:
+        """Write manifest data via a unique temp sibling, then atomically replace.
+
+        Closes the fixed-name temp collision + check-then-write TOCTOU window.
+        _validate_install_path is called on both the manifest path and each
+        candidate temp path (preserving the existing symlink-rejection rules).
+        """
+        self._validate_install_path(manifest_path, field="manifest")
+        manifest_path.parent.mkdir(parents=True, exist_ok=True)
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
+        last_err: Exception | None = None
+        for _ in range(100):
+            tmp = manifest_path.with_name(
+                f".{manifest_path.name}.{os.getpid()}.{secrets.token_hex(8)}.tmp"
+            )
+            self._validate_install_path(tmp, field="manifest")
+            try:
+                fd = os.open(tmp, flags, 0o666)
+            except FileExistsError as exc:
+                last_err = exc
+                continue
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                    fh.write(data)
+                os.replace(tmp, manifest_path)
+                return
+            except BaseException:
+                try:
+                    tmp.unlink()
+                except FileNotFoundError:
+                    pass
+                raise
+        raise FileExistsError(
+            f"could not create unique manifest temp for {manifest_path}"
+        ) from last_err
 
     def _validate_install_path(self, path: Path, *, field: str) -> None:
         """Reject install writes that would follow untrusted symlinks."""
@@ -1084,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.5.2"
+R2P_VERSION = "0.6.1"