chore: Sync review-related skills with documents repo

Mirrors six upstream changes:

- Drop the PowerShell wrapper from build verification. format-build-verify
  now calls cmake directly: 'cmake --preset <preset> --fresh' for configure
  and 'cmake --build --preset <preset>' for build, both redirecting to
  {{tmp_dir}}/build.log. Compound commands and tee piping are forbidden.
  --fresh is mandatory to avoid stale CMakeCache.txt mismatches when
  switching presets or toolchains.
- Drop Bash(pwsh ./build.ps1:*) / Bash(powershell ./build.ps1:*) from the
  review-helper agent allow-list since the build path no longer goes
  through PowerShell; Bash(cmake:*) already covers the new flow.
- Tell the triage Sub explicitly that {{tmp_dir}} is pre-created by the
  leader and that paths are relative. The Sub must not run existence
  checks (Test-Path / ls), mkdir, or absolute-path conversions before
  writing triage.json.
- Inline the verification logic into review-resolve/templates/verify.md so
  the verify Sub has the comment.md / document.md discipline checks
  in-prompt rather than referencing SKILL.md. The duplicated section is
  removed from SKILL.md.
- Add comment-sensei agent (model: sonnet) for language-agnostic
  comment-discipline review against .claude/rules/comment.md and FIXME /
  TODO usage. Wired in as an optional reviewer in parallel-review
  scope-analysis and as an optional specialist in review-respond triage.

Author: hanatyan128

.claude/agents/comment-sensei.md

@@ -0,0 +1,36 @@
+---
+name: comment-sensei
+description: Code-comment specialist. Across all programming languages, detects violations against `.claude/rules/comment.md` and checks correct usage of FIXME / TODO and similar annotations. Specialist candidate (optional, not required) when reviews or fixes include comment additions or modifications.
+model: sonnet
+---
+
+You are **comment-sensei**, a specialist who evaluates code-comment quality across all programming languages.
+
+## Areas of expertise
+
+- Detecting violations against the comment discipline in `.claude/rules/comment.md`
+- Evaluating the use of FIXME / TODO / XXX / NOTE and similar annotations
+- Judging the balance between comments and code expressiveness (whether the intent should be expressed in code or supplemented by a comment)
+- Assessing the readability and misreading risk of comments for third-party readers
+
+## Your responsibilities
+
+- First, Read `.claude/rules/comment.md` to grasp the current discipline.
+- Review whether added or modified comments violate `.claude/rules/comment.md`. Typical violation patterns:
+  - Multi-paragraph justifications (long defenses of "why this is safe enough as-is")
+  - Restatements of the obvious "what" (descriptions that the naming and structure already convey)
+  - Writing dependent on chat context or porting history (e.g., "the original logic in a was modified in b as ...")
+  - Change-history-style writing (content that belongs in git log / PR description)
+- Verify whether FIXME / TODO and similar annotations meet the requirements:
+  - States the problem and the recommended fix direction in 1–2 lines
+  - Is not an exhaustive rationale explanation
+  - Is self-contained for third-party readers
+- On detection, present the recommended action (reduce the comment, fix the code, move change history to git log / PR description).
+
+## Behavior rules
+
+- Respond in the same language the user is using (Japanese or English).
+- Ignore the syntactic differences in comment markers (`//` / `#` / `/* */` / `--` / `<!-- -->`, etc.); evaluate only the meaning of the comment.
+- When "leaving a comment" and "fixing the code" can both work, prefer expressing the intent in code (per the policy in `.claude/rules/comment.md`).
+- User-facing documentation (README / API references, etc.) is out of scope for this agent (explicitly out of scope per `.claude/rules/comment.md`).
+- Domain-specific findings about code logic, implementation, performance, thread safety, etc. are out of scope. Defer to domain specialists such as cpp-sensei / qt-sensei / obs-sensei.

.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(powershell ./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(.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/skills/parallel-review/templates/scope-analysis.md

@@ -18,6 +18,7 @@ Reviewer candidate mapping (kind / selection condition):
 - devops-sensei (optional): the diff contains changes to CMakeLists.txt / *.cmake / .github/workflows / build.ps1 / .clang-format / .cmake-format / Inno Setup / packaging settings
 - python-sensei (optional): the diff contains changes to .py files
 - lua-sensei (optional): the diff contains changes to .lua files
+- comment-sensei (optional): the diff contains additions or modifications that include comment markers (`//` / `#` / `/* */` / `<!-- -->` / `--`, etc.) or annotations such as FIXME / TODO
 
 For each reviewer's specialty area and perspective, see the agent definition (`.claude/agents/{name}.md`). This mapping only provides selection criteria.
 

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

@@ -129,46 +129,6 @@ Include `template_id` (Read from the template's frontmatter) in the return value
 
 Receive the return value from each verification agent (`{items: [{id, outcome}, ...], template_id}`). Verify that `template_id` matches `8a1f5c9b-2e73-4d64-9c1e-8b3d7f2a5e94`. If it does not match, relaunch that agent. **Do not place the verification body in context** (the return value contains only `items`).
 
-### Verification Logic
-
-Decision branches that the verification sub-agent applies based on the trailing field of the finding.
-
-#### Common additional checks (always perform immediately before the code-verification branch decision)
-
-Apply in each of the `Status: 🟢 Fixed` / `Triage: 🚫 Won't Fix` / `Estimate: 🔻 Downgrade` branches:
-
-- If comments were added or modified, check for `.claude/rules/comment.md` (auto-loaded) violations. If any violation exists, mark as Feedback.
-- If human-facing documentation (README, API references, etc.; AI-facing prompts under `.claude/` are out of scope) was added or modified, check for `.claude/rules/document.md` (auto-loaded) violations. If any violation exists, mark as Feedback.
-
-#### `Status: 🟢 Fixed` present
-
-1. Read the referenced file and lines to confirm that the described fix actually exists:
-   - Estimate ▶️ Maintain: the normal fix for the finding (including logic changes) is fully reflected.
-   - Estimate 🚧 Alternative: a `FIXME:` / `TODO:` comment is present at the relevant location, roughly aligned with the FIXME direction in the Estimate, and sufficient for the future fix (logic changes are not expected).
-2. Check for newly introduced issues (regressions / bugs / style violations / thread safety / resource leaks, etc.).
-3. Perform the common additional checks.
-4. Decision: Resolved (accurate, complete, no new issues) / Feedback (missing, incomplete, or new issues; describe the remaining work).
-
-#### `Triage: 🚫 Won't Fix` present
-
-1. Read the referenced file and evaluate whether the rationale for "not fixing" is still valid against the current code.
-2. Perform the common additional checks.
-3. Decision: Resolved (rationale is valid) / Feedback (rationale is flawed or the situation has changed; describe the reason).
-
-#### `Estimate: 🔻 Downgrade` present
-
-1. Read the referenced file and evaluate whether the downgrade rationale (diffusion signals / Cost / Future / reason) is valid against the current code.
-2. Confirm whether a separate-PR recommendation is present and appropriate (be especially careful for Critical / Major findings without a separate-PR recommendation).
-3. Perform the common additional checks.
-4. Decision: Resolved (rationale is valid) / Feedback (rationale is flawed or the situation has changed; describe the reason).
-
-#### Cases reported as Unresolved
-
-- `Estimate: 🚧 Alternative` present, no `Status` — FIXME not yet added.
-- `Estimate: ▶️ Maintain` present, no `Status` — fix not yet completed.
-- Only `Triage: 🔧 Will Fix` — estimate not yet completed.
-- No metadata between the markers — not yet triaged.
-
 ## Step 3 — Verification report and reflection (delegate to the aggregator sub-agent)
 
 The leader (you) does not place the verification body in context.

.claude/skills/review-resolve/templates/verify.md

@@ -8,10 +8,41 @@ Verify the assigned findings `{{ids}}` in batch. Read `.claude/rules/sub-agent.m
 
 Input: review document `{{document_path}}` (Read it to obtain each id's severity / location / description / trailing field).
 
-For each id:
+For each id, determine Resolved / Feedback / Unresolved using the logic below and Write the result to `{{tmp_dir}}/verifications/{id}.json`. The trailing field is the final value among triage / estimate / status / verification within the METADATA markers.
 
-1. Based on the trailing field (the final value among triage / estimate / status / verification), determine Resolved / Feedback / Unresolved per the rules defined in the "Step 2 § Verification Logic" section of `.claude/skills/review-resolve/SKILL.md`.
-2. Write to `{{tmp_dir}}/verifications/{id}.json`.
+Common additional checks (always perform immediately before the code-verification branch decision; apply in each of the `Status: 🟢 Fixed` / `Triage: 🚫 Won't Fix` / `Estimate: 🔻 Downgrade` branches):
+
+- If comments were added or modified, Read `.claude/rules/comment.md` and check for violations. If any violation exists, mark as Feedback.
+- If human-facing documentation (README, API references, etc.; AI-facing prompts under `.claude/` are out of scope) was added or modified, Read `.claude/rules/document.md` and check for violations. If any violation exists, mark as Feedback.
+
+`Status: 🟢 Fixed` present:
+
+1. Read the referenced file and lines to confirm the described fix actually exists:
+   - Estimate ▶️ Maintain: the normal fix for the finding (including logic changes) is fully reflected.
+   - Estimate 🚧 Alternative: a `FIXME:` / `TODO:` comment is present at the relevant location, roughly aligned with the FIXME direction in the Estimate, and sufficient for the future fix (logic changes are not expected).
+2. Check for newly introduced issues (regressions / bugs / style violations / thread safety / resource leaks, etc.).
+3. Perform the common additional checks.
+4. Decision: Resolved (accurate, complete, no new issues) / Feedback (missing, incomplete, or new issues; describe the remaining work).
+
+`Triage: 🚫 Won't Fix` present:
+
+1. Read the referenced file and evaluate whether the rationale for "not fixing" is still valid against the current code.
+2. Perform the common additional checks.
+3. Decision: Resolved (rationale is valid) / Feedback (rationale is flawed or the situation has changed; describe the reason).
+
+`Estimate: 🔻 Downgrade` present:
+
+1. Read the referenced file and evaluate whether the downgrade rationale (diffusion signals / Cost / Future / reason) is valid against the current code.
+2. Confirm whether a separate-PR recommendation is present and appropriate (be especially careful for Critical / Major findings without a separate-PR recommendation).
+3. Perform the common additional checks.
+4. Decision: Resolved (rationale is valid) / Feedback (rationale is flawed or the situation has changed; describe the reason).
+
+Cases reported as Unresolved:
+
+- `Estimate: 🚧 Alternative` present, no `Status` — FIXME not yet added.
+- `Estimate: ▶️ Maintain` present, no `Status` — fix not yet completed.
+- Only `Triage: 🔧 Will Fix` — estimate not yet completed.
+- No metadata between the markers — not yet triaged.
 
 Format of `{{tmp_dir}}/verifications/{id}.json`: `{id, severity, trailing_field, outcome (Resolved | Feedback | Unresolved), reason (1–3 sentences), memo_value, feedback_detail}`
 
@@ -25,4 +56,4 @@ memo_value:
 
 feedback_detail (include only when outcome == Feedback): `{description, current_state, issue, suggestion}`
 
-Return value: `{items: [{id, outcome}, ...], template_id}`. Include the `template_id` value Read from this template's frontmatter as-is.
+Return value: `{items: [{id, outcome}, ...], template_id}` (do not include reason / memo_value / feedback_detail or other body content in the return value; write them only to `verifications/{id}.json`). Include the `template_id` value Read from this template's frontmatter as-is.

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

@@ -15,13 +15,14 @@ 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 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.
+   - The CWD for command execution is assumed to be the project root. Do not specify absolute paths (use relative paths only).
+   - Configure: `cmake --preset <platform-preset> --fresh > {{tmp_dir}}/build.log 2>&1` (`--fresh` removes the existing CMakeCache.txt and CMakeFiles to avoid cache mismatches caused by preset switches or toolchain differences).
+   - Build: `cmake --build --preset <platform-preset> >> {{tmp_dir}}/build.log 2>&1` (`>>` appends).
+   - Select `<platform-preset>` from CMakePresets.json for the current platform (Windows: `windows-x64` / macOS: `macos` / Linux: `linux-x86_64`). When the project's preset names differ, Read CLAUDE.md or CMakePresets.json to confirm.
+   - Do not go through PowerShell scripts (build.ps1, etc.). Do not use pwsh / powershell (cmake direct invocation suffices).
+   - Do not use `tee` / `Tee-Object` via the `|` pipe.
+   - Do not use compound commands (`;`, `&&`). The Bash tool returns the exit code automatically, so `echo $?` is unnecessary.
+   - Treat the run as failed at the moment configure or build exits with a non-zero 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,11 @@ 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.
 
+Preconditions:
+
+- `{{tmp_dir}}` is created in advance by the leader via `mkdir -p`. The Sub must not perform existence checks (`Test-Path` / `ls`, etc.) or mkdir. The only filesystem write is triage.json.
+- The paths passed (`{{document_path}}` / `{{tmp_dir}}`) are relative. Do not convert them to absolute paths.
+
 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).
@@ -43,7 +48,7 @@ Won't Fix guideline (when any of the following applies):
 
 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.").
 
-Specialist assignment (Will Fix only): Choose the most suitable from cpp-sensei / qt-sensei / obs-sensei / network-sensei / av-sensei / devops-sensei / python-sensei / lua-sensei.
+Specialist assignment (Will Fix only): Choose the most suitable from cpp-sensei / qt-sensei / obs-sensei / network-sensei / av-sensei / devops-sensei / python-sensei / lua-sensei / comment-sensei. Assign comment-sensei when the finding is primarily about a comment-discipline violation or improper FIXME / TODO usage.
 
 `{{tmp_dir}}/triage.json` format: `{items: [{id, verdict, assignee (null for Won't Fix), reason, memo_value}], will_fix_count, wontfix_count, by_stage: {<stage>: <int>}}`