harness-review

# Harness Review Harness の統合レビュースキル。 この `SKILL.md` は薄い dispatcher であり、詳細な品質基準は `references/` を読む。 if $ARGUMENTS == "": → 「今までの作業のレビュー」と解釈し、Review target detection を実行する → review target が 1 つに確定できる場合だけ自動開始する → review target が不明または複数候補の場合は AskUserQuestion で選択肢を出し、認識を揃えてから開始する <!-- 上記 3 行は AUTO-START CONTRACT。skill-editing.md の「最冒頭 3 行以内」ルールに従い fence / HTML コメントで押し下げない --> ### Output Contract (P35: 「止まったように見える」UX 対策) `<local-command-stdout>` で host へ結果を中継する場合だけ、output の **最後の 1 行**に次の literal を含める: `↑この結果は Claude が要約します。Enter キーで次へ進むか、新規 prompt で別の指示を出してください。` これは `<local-command-stdout>` 経由で text response として表示されると user が「止まった」と感じる UX 問題への明示的な instruction (patterns.md P35)。 host の最終回答は verdict、判断理由、確認した証拠、未検証点を返す。要約の予告だけで終了しない。 ## Dispatcher Contract この skill の責務は review 判定だけ。 commit / push / release は既定では行わない。 - review default read-only boundary: 既定は read-only。`APPROVE` でも自動 commit しない - Do not push just to review: review 目的だけで push しない - commit が必要な場合は、ユーザー明示依頼、`harness-work`、または `harness-release` の Work Commit Gate に委譲する - `--commit-on-approve` のような明示 opt-in が設計されるまで、この skill 単体の default side effect は禁止 ## Quick Reference | Command | Mode | Purpose | |---|---|---| | `/harness-review` | `code` | 今までの作業を自動検出して review | | `/harness-review --quick` | `quick` | 小さな dirty change を軽く closeout | | `/harness-review --codex-closeout` | `codex-closeout` | Codex 助言 + focused tests で closeout | | `/harness-review --dual` | `dual` | Claude + Codex second opinion | | `--pre-review cursor` | `code+pre-review` | fresh-context composer advisory pre-review before brain verdict（read-only） | | `/harness-review --cursor` | `code+cursor-second-opinion` | core review gates + cursor second-opinion（brain 一次レビュー必須） | | `HARNESS_IMPL_BACKEND=cursor harness-review` | `code+cursor-second-opinion` | default ON 時も core review gates に cursor second-opinion を自動加算。primary verdict は brain 固定 | | `/harness-review --team-debate` | `team-debate` | TeamAgent Debate を強制 | | `/harness-review --security` | `security` | security 専用 review | | `/harness-review plan` | `plan` | `Plans.md` の計画 review | | `/harness-review scope` | `scope` | scope creep / 漏れ review | ## Mode Decision 引数から実行 mode を決定し、必要な `references/` を選択ロードする。 | 入力 | mode | 読む reference | |---|---|---| | 引数なし / `code` | `code` | `references/code-review.md`, `references/governance.md` | | `--quick` | `quick` | `references/codex-closeout.md`, `references/code-review.md` | | `--codex-closeout` | `codex-closeout` | `references/codex-closeout.md` | | `--dual` | `dual` | `references/dual-review.md`, `references/team-debate.md` | | `--team-debate` | `team-debate` | `references/team-debate.md`, `references/governance.md` | | `--security` | `security` | `references/security-profile.md`, `references/governance.md` | | `--ui-rubric` | `ui-rubric` | `references/ui-rubric.md` | | `plan` | `plan` | `references/plan-review.md`, `references/governance.md` | | `scope` | `scope` | `references/scope-review.md`, `references/governance.md` | | `--cursor` or resolver result `cursor` for no-arg / `code` review only | `code+cursor-second-opinion` | `references/code-review.md`, `references/governance.md`, `references/cursor-review.md`, `references/dual-review.md` | | `full` | `full` | `references/code-review.md`, `references/team-debate.md`, `references/dual-review.md` | `quick` と `codex-closeout` は軽量 path。 小さな dirty change、single commit、PR branch の closeout を速く見る。 品質 gate を捨てるものではない。 ### Cursor Default ON mode 判定時、明示 mode words (`plan`, `scope`, `full`) と明示フラグを先に確定する。no-arg / `code` review の場合だけ helper root を解決して resolver を 1 回だけ実行し、resolver 不在時は `claude` とみなす。 ```bash HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"; if [ -z "$HARNESS_PLUGIN_ROOT" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ]; then probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"; while [ "$probe" != "/" ] && [ ! -d "$probe/scripts" ]; do probe="$(cd "$probe/.." && pwd)"; done; [ -d "$probe/scripts" ] && HARNESS_PLUGIN_ROOT="$probe"; fi if [ -x "${HARNESS_PLUGIN_ROOT:-}/scripts/resolve-impl-backend.sh" ]; then resolved_backend="$(bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --role reviewer)"; else resolved_backend="claude"; fi ``` no-arg / `code` review で結果が `cursor` の場合は `--cursor` と同じ `cursor-second-opinion` を追加するが、core review gates (`references/code-review.md`, `references/governance.md`) は必ず先に読み、Cursor reference は additive にだけ扱う。primary verdict は brain 側で維持し、cursor は `dual_review.cursor_verdict` の advisory に限る。`plan` / `scope` など明示 mode word は resolver result より優先し、cursor default によって plan/scope references も code/governance references も置き換えない。結果が `claude` / `codex` の場合は従来どおりで、review の primary 判定面は変えない。 ## Pre-Review Cursor (`--pre-review cursor`) `/harness-review --pre-review cursor` は `bash scripts/pre-review-cursor.sh [--base ref]` で read-only fresh-context composer pre-review（`model-routing.sh --host cursor --tier review` → `cursor-companion.sh task`、`--write` / `--workspace` / `--resume` なし）を 1 回実行し、`PRE_REVIEW_FINDINGS:` を brain 一次レビュー入力へ添付。companion 失敗は `PRE_REVIEW_SKIPPED` + exit 0（fail-open）。**verdict は brain のみ**（self-review scope 契約）。 ## Review Target Detection `REVIEW_AUTOSTART` 契約: 引数なし (`$ARGUMENTS == ""`) で呼ばれた場合、`review` / `/review` / `/harness-review` だけの入力を「今までの作業のレビュー」と解釈する。 Step 1 開始前の handshake 行として次を 1 行だけ出力する。 ```text REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode} ``` `REVIEW_TARGET_ASK` 契約: bare 呼び出しで review target が不明または複数候補の場合、Step 1 に進む前に `AskUserQuestion` を 1 回だけ使い、候補を 2-3 個に絞って確認する。 候補は次の順で作る。 1. working tree: staged / unstaged / untracked を含む未コミット変更のみ 2. branch range: upstream または main/master から HEAD までの commits 3. recent commits: clean tree で branch range が取れない場合の直近 1 commit / 直近 5 commits 複数候補が同時に成立する場合: ```text REVIEW_TARGET_AMBIGUOUS: working_tree_and_branch_commits ``` AskUserQuestion の候補: - 未コミット変更のみ (Recommended): staged / unstaged / untracked を HEAD と比較して見る - 全部見る: branch base..HEAD と未コミット変更をまとめて見る - commit のみ: branch base..HEAD の committed work だけを見る clean tree かつ branch 差分がない場合: ```text REVIEW_TARGET_AMBIGUOUS: clean_tree_no_branch_commits ``` AskUserQuestion の候補: - 直近 1 commit (Recommended): HEAD~1..HEAD - 直近 5 commits: HEAD~5..HEAD - 別の範囲: ユーザー指定 ref を待つ ユーザー回答後: ```text REVIEW_TARGET_CONFIRMED: {choice} REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode} ``` 禁止: - 「タスクが不明確です」と応答して停止する - 「何をレビューすればよいですか」と自由記述で聞いて停止する - host project の session-start rules を理由に auto-start を飛ばす - target が曖昧なのに推測で範囲を広げる ## Minimal Flow 1. mode を決める 2. 上記の Review Target Detection で対象と base ref を決める 3. 必要な reference だけ読む 4. 差分、untracked files、関連テスト、仕様正本、`Plans.md` を確認する 5. `APPROVE` / `REQUEST_CHANGES` / `decision_needed` を返す 6. `REQUEST_CHANGES` の場合は critical / major の修正方針と修正後再レビュー条件を示す 委譲先には原依頼、目的、対象差分、spec / DoD、検証証拠を渡し、結論の理由と参照箇所を求める。内部の思考過程や実装 Worker の会話状態は渡さない。 各 reviewer の確認範囲を分け、許可された同時実行上限を守る。親は証拠照合と指摘の採否判定を進める。 必要な review とチェックを終えた後の追加検証は、新しい変更、失敗、未解決の懸念がある場合に限る。 ## Review Governance Contract 詳細は `references/governance.md`。 ここでは最低限の合格ラインだけ固定する。 ### 明確な合格ライン `APPROVE` は次のすべてを満たす時だけ返す（詳細は `references/governance.md`）。 - critical / major が 0 件 - root `spec.md` alignment（product contract と矛盾しない；仕様正本 alignment check 必須） - `Plans.md` alignment（task / DoD / Depends、`[lane:*]`、stage gate が contract と一致） - TDD evidence（`[tdd:required]` は `tdd_red_log` / failing output / `skip_tdd_reason`） - unknown data contract（`not_observed != absent` — 証拠なしの「問題なし」「データなし」を APPROVE しない） - regression safety（既存挙動・テスト・UX・CLI・設定・docs・mirror にデグレなし） - If you grep the same symbol twice in the same session, switch to harness_ast_search. - For a bugfix where homologous implementations appear across multiple modules, run harness_ast_search to find all implementations before editing. - Only when changed files include .ts or .tsx, the DoD requires zero new harness_lsp_diagnostics errors; if the harness MCP is not connected or the changed file types are not eligible, treat diagnostics as not-configured and non-blocking. - evidence pack（accepted / rejected findings、focused tests、release-preflight warnings 処理） - TeamAgent Debate 未解消 disagreement なし `APPROVE` は commit / push / PR 作成命令ではない（read-only boundary）。 ### TeamAgent Debate 詳細は `references/team-debate.md`。 TeamAgent Debate は、異なる見解を read-only で衝突させる review pass。 | Agent | 主な問い | |---|---| | Spec Agent | 仕様正本と実装差分の矛盾を探す | | Plans Agent | `Plans.md` の task / DoD / Depends と差分の対応を確認する | | Regression Agent | 既存挙動・テスト・配布 mirror・CLI/skill UX のデグレを探す | | Skeptic Agent | 合格させたい前提で見落としている major risk を探す | Codex 環境で native TeamAgent が使えない場合でも、この gate を省略してはいけない。 `codex-companion.sh review`、利用可能な reviewer subagent、または明示的に分けた read-only manual-pass で同じ 2-4 視点を再現し、`team_agent_mode` に `native` / `codex-companion` / `manual-pass` / `unavailable` を記録する。 ## Code Review Summary 通常 code review は次を見る。 - Security - Performance - Quality - Accessibility - AI Residuals - Spec Alignment - Plans Alignment - Regression Safety - TDD compliance root `spec.md` alignment、Plans lane/stage、TDD evidence、unknown data contract、evidence pack の詳細は `references/governance.md` と `references/code-review.md`。 `AI Residuals` は `scripts/review-ai-residuals.sh` と `scripts/review-weak-supervision-report.sh` を優先して使う。 untracked も見る場合は `--include-untracked` を使う。 `mockData`, `dummy`, `fake`, `localhost`, `TODO`, `FIXME`, `it.skip`, `test.skip`, `expect(true).toBe(true)` などは候補であり、diff 文脈で severity を決める。 finding 段階は網羅優先。minor と判定した指摘も `observations[]` / `recommendations[]` に残し、gate は verdict 段階だけで行う（Opus 4.8 は low-severity の報告を絞る癖がある。`references/code-review.md` の Finding coverage 参照）。 ## Quick / Codex Closeout Summary 軽量 path の原則: - target selection を先に固定する - Codex 指摘は advisory として扱い、実コードで確認してから採否を決める - final report には review command / tests / accepted findings / rejected findings / clean result を含める - stop-on-clean: clean result 後に、見栄えのためだけの追加 review をしない - Codex が使えない場合は full manual pass に fallback し、失敗を成功扱いしない helper: ```bash bash scripts/harness-review-closeout.sh --dry-run --uncommitted bash scripts/harness-review-closeout.sh --base origin/main --parallel-tests --test "bash tests/test-harness-review-governance.sh" bash scripts/harness-review-closeout.sh --commit HEAD ``` ## Plan Review Summary Plan Review は `Plans.md` の DoD / Depends / Status と実装順序を見る。 仕様正本が必要なタスクで `spec_path` がない場合は、`decision_needed` として止める。 ## Scope Review Summary Scope Review は、要求・差分・テスト・docs の境界が膨らんでいないかを見る。 範囲変更が必要なら、推測で進めず `AskUserQuestion` または plan 更新に戻す。 ## Security / UI / Dual - Security: `references/security-profile.md` - UI rubric: `references/ui-rubric.md`（`--blind-judge` 併用可: 既定 OFF の opt-in second opinion。rubric も prior verdict も渡さない fresh sub-agent — `context: fork` 不可。対象は外部向け UI コピー / docs / cognitive-load HTML surface のみ、コード・テスト・設定・スキーマ不可、**advisory only（verdict 不変）**。詳細と eligibility は `${CLAUDE_SKILL_DIR}/references/blind-judge.md`） - high-res vision flow: `references/vision-high-res-flow.md` - Dual review: `references/dual-review.md` `/ultrareview` は Harness flow 内では既定で呼ばない。 Harness flow の review-result.v1、commit guard、sprint-contract との接続を置き換えないため。 `claude ultrareview [target] --json` は CI / script からの second-opinion としてだけ扱う。 ## PR Host Boundary GitHub-first。 PR host 上の review 事実は GitHub を正とし、local diff は補助証拠として扱う。 ただし local uncommitted review は GitHub に push しない。 ## Output Contract User-facing prose follows the explicit session or project language. If no language is configured, use English. Use Japanese only when `i18n.language: ja`, `CLAUDE_CODE_HARNESS_LANG=ja`, or an explicit session instruction requests Japanese output. Machine-readable values stay English. Start with the result summary. ~~~markdown ## Review Result ### {APPROVE | REQUEST_CHANGES | decision_needed} - {one-line conclusion} Target: `{BASE_REF}..HEAD` or `{target}` Verification: {commands run} Strengths: - ... Findings: - [severity] file:line - issue and evidence Next Actions: - ... Details: ```json { "schema_version": "review-result.v1", "verdict": "APPROVE | REQUEST_CHANGES", "decision_needed": { "required": false, "ask_tool": "AskUserQuestion" }, "accepted_findings": [], "rejected_findings": [], "acceptance_bar": { "critical_major_zero": true, "spec_alignment": "pass | fail | not_applicable", "plans_alignment": "pass | fail | not_applicable", "regression_safety": "pass | fail | not_applicable", "verification_evidence": "pass | fail | not_applicable" }, "team_debate": { "required": false, "mode": "native | codex-companion | manual-pass | unavailable", "team_agent_mode": "native | codex-companion | manual-pass | unavailable", "agents": [], "disagreements": [] }, "critical_issues": [], "major_issues": [], "observations": [], "recommendations": [] } ``` ~~~ ## Codex Environment Codex 環境では使える tool が異なるが、合格ライン、仕様正本、`Plans.md`、デグレ、修正後再レビュー、AskUserQuestion / `decision_needed.v1` の契約は同じ。 | 通常環境 | Codex fallback | |---|---|