chore: Sync review-rounds / review-respond skills with documents repo

Mirrors four upstream changes:

- Specify build-invocation forms and accept Windows PowerShell in
  review-helper. Pin pwsh ./build.ps1 / powershell ./build.ps1 forms
  on Windows, mandate `>` redirection for log capture, and forbid
  `-Command` and `tee` / `Tee-Object`.
- Bundle the final-report compile prompt next to the sequencer .py
  (mirror of final-report-format.md), and exclude future-recommendation
  candidates whose same-location finding ended up Fixed in a later
  round.
- Pass previous-round doc paths to the triage sub-agent so findings
  matching prior-round Fixed / Won't Fix / Downgrade verdicts are
  treated as Won't Fix.
- Render future-recommendation findings as full-text subsections
  (one subsection per finding, full text quoted from the source review
  document) in place of the previous table.

Author: hanatyan128

.claude/agents/review-helper.md

@@ -2,7 +2,7 @@
 name: review-helper
 description: Helper agent for review-related skills (parallel-review / review-respond / review-resolve / review-rounds), responsible for aggregation, compilation, analysis, and format & build verification. Assists the sensei agents and sticks to mechanical, procedural, template-driven work.
 model: sonnet
-allowed-tools: Read, Write, Glob, Grep, Bash(grep:*), Bash(ls:*), Bash(find:*), Bash(mkdir:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git status:*), Bash(clang-format:*), Bash(cmake-format:*), Bash(cmake:*), Bash(make:*), Bash(pwsh ./build.ps1:*), Bash(.claude/scripts/rm-tmp.sh:*), Bash(python .claude/scripts/render-review.py:*)
+allowed-tools: Read, Write, Glob, Grep, Bash(grep:*), Bash(ls:*), Bash(find:*), Bash(mkdir:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git status:*), Bash(clang-format:*), Bash(cmake-format:*), Bash(cmake:*), Bash(make:*), Bash(pwsh ./build.ps1:*), Bash(powershell ./build.ps1:*), Bash(.claude/scripts/rm-tmp.sh:*), Bash(python .claude/scripts/render-review.py:*)
 ---
 
 You are **review-helper**, a helper agent that assists the specialist (sensei) agents (cpp-sensei / qt-sensei / obs-sensei, etc.) in the review-related skills.

.claude/sequencer/programs/review_rounds.py

@@ -93,6 +93,11 @@
     Path(__file__).resolve().parent / "review_rounds" / "final-report-format.md"
 ).as_posix()
 
+# Adjacent bundle: prompt template for the final report aggregator sub-agent.
+_FINAL_REPORT_COMPILE_PATH = (
+    Path(__file__).resolve().parent / "review_rounds" / "final-report-compile.md"
+).as_posix()
+
 _SEVERITY_COUNTS_SCHEMA = {
     "type": "object",
     "properties": {
@@ -262,7 +267,12 @@
     {commit_clause}
 
     Additional constraints:
-    - Do not reference the previous round's review document (bias avoidance)
+    - When launching the triage sub-agent, pass the following as the
+      previous_round_doc_paths variable (`(none)` in Round 1; in Round N, the
+      doc_paths of Round 1..N-1). For decision behavior, see the Won't Fix
+      guideline in templates/triage.md:
+{previous_round_doc_paths_block}
+    - Do not pass the previous round's review document to the estimate sub-agent (bias avoidance)
     - Confirm Will Fix count via the triage sub-agent's return value (state explicitly even if 0)
     - When judging diffusion signal e (Will Fix originating from FIXME), confirm
       whether the target finding originates from FIXME: / TODO: in the review body
@@ -317,6 +327,10 @@
         Run {respond_skill} Step 1 (triage).
         Append to triage prompt: prioritize triage of findings whose stage is "feedback"
         (Feedback details are in current_meta.verification).
+        When launching triage, pass the following as the previous_round_doc_paths
+        variable (for decision behavior, see the Won't Fix guideline in
+        templates/triage.md):
+{previous_round_doc_paths_block}
 
     Step 2.4.{attempt}.2 Feedback estimate
         Run {respond_skill} Step 2 (parallel estimate).
@@ -375,7 +389,7 @@
     the leader). The launch prompt is as follows:
 
     ```
-    As your first action, you MUST Read `.claude/skills/review-rounds/templates/final-report-compile.md`. Do not perform any other judgment, action, or tool call before the Read completes. After reading, follow its instructions.
+    As your first action, you MUST Read `{compile_path}`. Do not perform any other judgment, action, or tool call before the Read completes. After reading, follow its instructions.
 
     Variables (substitute into the template's {{{{...}}}} placeholders):
     - round_doc_paths: |
@@ -533,6 +547,8 @@ def run(ctx):
             break
 
         # ----- Step 2.2: review-respond -----
+        # round_records has not yet been appended for the current round, so
+        # its contents at this point form the "list of past-round documents".
         respond_result = yield Instruction(
             text=_TPL_RESPOND.format(
                 round_num=round_num,
@@ -541,6 +557,9 @@ def run(ctx):
                 doc_path=doc_path,
                 confirm_clause=confirm_clause,
                 commit_clause=commit_clause,
+                previous_round_doc_paths_block=_format_round_docs_block(
+                    round_records
+                ),
             ),
             expect_schema=_RESPOND_SCHEMA,
             timeout_minutes=180,
@@ -603,6 +622,9 @@ def run(ctx):
                         doc_path=doc_path,
                         respond_skill=_REVIEW_RESPOND_SKILL,
                         resolve_skill=_REVIEW_RESOLVE_SKILL,
+                        previous_round_doc_paths_block=_format_round_docs_block(
+                            round_records
+                        ),
                     ),
                     expect_schema=_FEEDBACK_SCHEMA,
                     timeout_minutes=120,
@@ -657,6 +679,7 @@ def run(ctx):
                 branch_dir=branch_dir,
                 termination_reason=termination_reason,
                 format_path=_FINAL_REPORT_FORMAT_PATH,
+                compile_path=_FINAL_REPORT_COMPILE_PATH,
                 round_docs_block=_format_round_docs_block(round_records),
                 per_round_stats_block=_format_per_round_stats_block(round_records),
             ),

.claude/sequencer/programs/review_rounds/final-report-compile.md

@@ -0,0 +1,31 @@
+---
+name: final-report-compile
+description: Prompt for the final report aggregator sub-agent that generates the final report from all rounds' review documents in review-rounds Step 3
+template_id: 4f8a2d1c-9b35-4e67-a2c1-8b5d3f9e7a16
+---
+
+<!--
+This file is kept in sync with .claude/skills/review-rounds/templates/final-report-compile.md.
+-->
+
+Generate the final report from all rounds' review documents. Read `.claude/rules/sub-agent.md` and observe the common prohibitions.
+
+Input:
+
+- Each round's review document: `{{round_doc_paths}}` (e.g., `Round 1 → {round1_doc_path}, Round 2 → {round2_doc_path}, ...`)
+- Each round's statistics (reference information): `{{round_stats}}` (e.g., `Round 1: findings=N, will_fix=N, maintain=N, alternative=N, downgrade=N, fixed=N, wontfix=N, feedback_attempts=N, unresolved=N, code_changed=<bool>, ...`)
+- Report template: `{{template_path}}`
+- Output path: `{{report_path}}`
+- Language: `{{language}}`
+
+What to do:
+
+1. Read the template markdown to grasp the structure (`<...>` placeholders, table structure, sample subsections under future recommendations).
+2. From each round's md `<!-- METADATA(id) --> ... <!-- /METADATA(id) -->`, extract Triage / Estimate / Status / Verification values to obtain per-finding details (severity / location / summary / response / whether a separate-PR recommendation is attached, etc.).
+3. Fill the template's statistics summary, full findings list, future recommendations, and review document list, and Write to `{{report_path}}`.
+   - Aggregation rules for the "Recommended future actions" section:
+     - Candidates: findings with Triage: 🚫 Won't Fix / Estimate: 🔻 Downgrade / Estimate: 🚧 Alternative whose reason field explicitly states a separate-PR recommendation.
+     - Exclusion: among the candidates, do not include findings at the same location with the same content that were resolved in a later round as Status: 🟢 Fixed (already fixed, so no need to keep on the roadmap). Identity is determined by matching `file:line` and finding gist. When the determination is difficult, do not exclude — instead append a note in the recommendation reason field stating that the determination is deferred.
+     - Format: produce one subsection per finding, following the template example. Heading format: `### R{source round number}-{source ID} — `file:line`` (always prefix with the round number to avoid ID collisions across multiple rounds). Within the subsection, list severity / source round / source ID / source reviewer / decision as bullets, then **transcribe the entire body** of the finding from the source review document (the range from immediately below `### {id} — ...` up to just before `---`, excluding the `<!-- METADATA(id) --> ... <!-- /METADATA(id) -->` block) after a `**Finding:**` label, **without omission**. Separate subsections with `---`.
+
+Return value: `{report_path, template_id}`. Include `template_id` exactly as Read from this template's frontmatter.

.claude/sequencer/programs/review_rounds/final-report-format.md

@@ -54,19 +54,59 @@ List findings with `Triage: 🚫 Won't Fix` and `Estimate: 🔻 Downgrade` that
 
 ## Recommended future actions
 
-Aggregate the following (findings expected to be addressed later in a separate PR):
+List findings expected to be addressed later in a separate PR, in full text using the same section format as the review document.
 
-- `Triage: 🚫 Won't Fix` items where a separate-PR recommendation is explicitly stated in the reason field
-- `Estimate: 🔻 Downgrade` items where a separate-PR recommendation is explicitly stated in the reason field
-- `Estimate: 🚧 Alternative` (FIXME already attached) items where a separate-PR recommendation is explicitly stated in the reason field
+Aggregation targets (any of the following with a separate-PR recommendation explicitly stated in the reason field):
+
+- `Triage: 🚫 Won't Fix`
+- `Estimate: 🔻 Downgrade`
+- `Estimate: 🚧 Alternative` (FIXME already attached)
+
+Exclusion rule: among the candidates above, exclude from this section any finding at the same location with the same content that was resolved as `Status: 🟢 Fixed` in a later round (already fixed, so there is no need to keep it on the roadmap). Identity is determined by matching `file:line` and finding gist.
 
 This is mutually exclusive with the "Judged not to require action" section. Alternative FIXME attachments are also listed in the "Resolved" section, but when accompanied by a separate-PR recommendation, they are additionally listed in this section (for roadmap purposes).
 
-| # | Severity | Location | Summary | Recommendation reason |
-|---|----------|----------|---------|------------------------|
-| 1 | Minor | `file:line` | Summary | Triage: 🚫 Won't Fix — bug in existing code. Recommended to fix in a separate PR. |
-| 2 | Major | `file:line` | Summary | Estimate: 🔻 Downgrade — Cost L, Signals a,b,c. This response is recommended to be performed in a separate PR. |
-| 3 | Major | `file:line` | Summary | Estimate: 🚧 Alternative — FIXME already attached (`output.cpp:200`). Full response recommended in a separate PR. |
+### R1-C-1 — `file.cpp:42`
+
+- **Severity:** Critical
+- **Source round:** Round 1
+- **Source ID:** C-1
+- **Source reviewers:** cpp-sensei, obs-sensei
+- **Decision:** Triage: 🚫 Won't Fix — bug in existing code. Recommended to fix in a separate PR.
+
+**Finding:**
+
+{Transcribe the entire body of the finding from the source review document (do not include METADATA markers)}
+
+---
+
+### R2-M-3 — `output.cpp:200`
+
+- **Severity:** Major
+- **Source round:** Round 2
+- **Source ID:** M-3
+- **Source reviewers:** cpp-sensei
+- **Decision:** Estimate: 🔻 Downgrade — Cost: L, Future: M, Signals: a,b,c — This response is recommended to be performed in a separate PR
+
+**Finding:**
+
+{Transcribe the entire body of the finding from the source review document}
+
+---
+
+### R1-M-2 — `output.cpp:300`
+
+- **Severity:** Major
+- **Source round:** Round 1
+- **Source ID:** M-2
+- **Source reviewers:** qt-sensei
+- **Decision:** Estimate: 🚧 Alternative — Cost: M, Future: S, Signals: b,d — FIXME already attached (`output.cpp:200`). Full response recommended in a separate PR.
+
+**Finding:**
+
+{Transcribe the entire body of the finding from the source review document}
+
+---
 
 ## Review document list
 

.claude/skills/review-respond/SKILL.md

@@ -138,6 +138,7 @@ As your first action, you MUST Read `.claude/skills/review-respond/templates/tri
 Variables (substitute into the template's {{...}} placeholders):
 - document_path: {document_path}
 - tmp_dir: {tmp_dir}
+- previous_round_doc_paths: {previous_round_doc_paths} (in the standard flow, "(none)". Non-empty only when an upper flow such as review-rounds passes a list of past-round doc_paths.)
 
 Round-specific overrides (apply after following the template's instructions):
 - (none)

.claude/skills/review-respond/templates/format-build-verify.md

@@ -15,8 +15,13 @@ What to do:
    - Verification commands: `clang-format -style=file -fallback-style=none --dry-run -Werror <file>`; on violation, auto-fix with `clang-format -i -style=file -fallback-style=none <file>`. CMake is the same.
 
 2. Build verification:
-   - Choose the command for the current platform from build.ps1 / Makefile / build script, or from the CMake presets listed in CLAUDE.md.
-   - Run the build, save stdout/stderr to `{{tmp_dir}}/build.log`. Determine success/failure by exit code.
+   - Choose one of the following for the current platform:
+     - Windows: `pwsh ./build.ps1` / `powershell ./build.ps1` (positional script-argument form).
+     - Linux / macOS: a direct command such as `cmake --preset <preset>` or `make` (use the preset listed in CLAUDE.md).
+   - Capture output with the `>` redirection only: `<command> > {{tmp_dir}}/build.log 2>&1`.
+   - Do not use PowerShell's `-Command` flag (limit invocation to positional or `-File` form to avoid arbitrary-expression execution).
+   - Do not pipe through `tee` / `Tee-Object` (avoids shrinking the permission boundary and unintended external-command invocation).
+   - Determine success/failure by the exit code.
 
 3. Specialist identification on failure:
    - Read build.log and the error-source files to analyze the cause and concisely organize the fix direction (fix_guidance).

.claude/skills/review-respond/templates/triage.md

@@ -6,6 +6,8 @@ template_id: 1e9c4f7a-5b82-4d63-a1c8-3f7d2e9b4a15
 
 As the initial-triage owner of the review document, Read `{{document_path}}`, perform stage classification and the triage decision for each finding, and Write the result to `{{tmp_dir}}/triage.json`. Read `.claude/rules/sub-agent.md` and observe the common prohibitions.
 
+If `{{previous_round_doc_paths}}` is provided (empty in the standard flow that runs in Round 1), Read each file to extract past-round decision information (id / location / description / METADATA's triage / estimate / status / verification) and reference it during triage. No reference is needed when the value is empty or `(none)`.
+
 Extraction targets: Critical / Major / Minor sections (skip Info). For each finding, obtain id (C-1, M-1, mi-1, etc.) / severity / location / description (the body up to the marker) / current_meta (the current values of triage / estimate / status / verification; when the same field appears multiple times, use the last value).
 
 Stage classification (based on current_meta):
@@ -34,6 +36,10 @@ Won't Fix guideline (when any of the following applies):
 4. Inferable as acceptable from the project's purpose, use case, or assumed users.
 5. Preference-based refactoring (no rationale grounded in correctness, safety, performance, or maintainability).
 6. Reproducibility unclear; e2e verification needed.
+7. A finding at the same location with the same content was already processed in a past round (only judgable when `{{previous_round_doc_paths}}` is provided). Identity is determined by matching `file:line` and finding gist. Applicable patterns:
+   - Already `status: 🟢 Fixed` in a past round (an edge case that does not happen in the normal flow; since it has been rediscovered, explicitly state in the reason field "Already Fixed in a previous round").
+   - `triage: 🚫 Won't Fix` in a past round (state in the reason field "Same finding as previous-round Won't Fix" and concisely transcribe the past decision's reason as well).
+   - `estimate: 🔻 Downgrade` in a past round (state in the reason field "Same finding as previous-round Downgrade" and concisely transcribe the past decision's reason as well).
 
 High-severity exception: For Critical / Major Won't Fix, explicitly state "recommend separate PR" in the reason field (e.g. "Won't Fix — Existing-code bug. Recommend fixing in a separate PR.").
 

.claude/skills/review-rounds/SKILL.md

@@ -142,10 +142,12 @@ Round-specific overrides (apply after following the template's instructions):
   - At triage start: `## Round {N} — Step 2: Triage`
   - At estimate start: `## Round {N} — Step 2.5: Estimate`
   - At fix / verify / update / commit start: `## Round {N} — Step 3: Review Respond (Fix & Verify)`
-- Additional constraints for the triage / estimate sub-agents:
-  - Do not reference the previous round's review document.
+- Additional constraints for the triage sub-agent:
+  - At launch, pass the full list of past-round doc_paths as the `previous_round_doc_paths` variable (`(none)` in Round 1, the doc_paths of Round 1..N-1 in Round N). For decision behavior, see the Won't Fix guideline in `.claude/skills/review-respond/templates/triage.md`.
   - State the Will Fix count explicitly in the triage report (also state explicitly when 0).
-  - When determining the diffusion signal e (Will Fix originating from FIXME) during estimate, verify whether the finding originates from a `FIXME:` / `TODO:` in the review body or target file.
+- Additional constraints for the estimate sub-agent:
+  - Do not reference the previous round's review document (bias avoidance).
+  - When determining the diffusion signal e (Will Fix originating from FIXME), verify whether the finding originates from a `FIXME:` / `TODO:` in the review body or target file.
 - Round loop control after triage:
   - Will Fix == 0: skip Steps 2.3–2.4 and proceed to Step 2.5 (round end).
   - Will Fix >= 1: proceed to the estimate phase.

.claude/skills/review-rounds/templates/final-report-compile.md

@@ -16,8 +16,12 @@ Input:
 
 What to do:
 
-1. Read the template markdown to grasp the structure (`<...>` placeholders, table structure).
+1. Read the template markdown to grasp the structure (`<...>` placeholders, table structure, sample subsections under future recommendations).
 2. From each round's md `<!-- METADATA(id) --> ... <!-- /METADATA(id) -->`, extract Triage / Estimate / Status / Verification values to obtain per-finding details (severity / location / summary / response / whether a separate-PR recommendation is attached, etc.).
 3. Fill the template's statistics summary, full findings list, future recommendations, and review document list, and Write to `{{report_path}}`.
+   - Aggregation rules for the "Recommended future actions" section:
+     - Candidates: findings with Triage: 🚫 Won't Fix / Estimate: 🔻 Downgrade / Estimate: 🚧 Alternative whose reason field explicitly states a separate-PR recommendation.
+     - Exclusion: among the candidates, do not include findings at the same location with the same content that were resolved in a later round as Status: 🟢 Fixed (already fixed, so no need to keep on the roadmap). Identity is determined by matching `file:line` and finding gist. When the determination is difficult, do not exclude — instead append a note in the recommendation reason field stating that the determination is deferred.
+     - Format: produce one subsection per finding, following the template example. Heading format: `### R{source round number}-{source ID} — `file:line`` (always prefix with the round number to avoid ID collisions across multiple rounds). Within the subsection, list severity / source round / source ID / source reviewer / decision as bullets, then **transcribe the entire body** of the finding from the source review document (the range from immediately below `### {id} — ...` up to just before `---`, excluding the `<!-- METADATA(id) --> ... <!-- /METADATA(id) -->` block) after a `**Finding:**` label, **without omission**. Separate subsections with `---`.
 
 Return value: `{report_path, template_id}`. Include `template_id` exactly as Read from this template's frontmatter.