PlanGate

外部レビューア標準インターフェース（正本）

PlanGate の C-2 / V-3 外部レビューア接続の 正本。River Review（現行 repository: s977043/river-review）を 第一の参照実装とし、任意の外部レビューアを同一 IF で接続できる。 関連: #227 / TASK-0089 / .claude/rules/review-principles.md §7-bis / schemas/plangate-reviewers.schema.json / schemas/review-external.schema.json / River Review 側: s977043/river-review（旧 s977043/river-reviewer から移動）

1. 目的

PlanGate の C-2（plan ゲート外部レビュー）/ V-3（実装後外部モデルレビュー）は 「外部レビューアを呼ぶ」設計（PLANGATE_EXTERNAL_REVIEWER 環境変数 + bin/plangate review <TASK> --phase c2|v3）を持つ。本 IF は接続設定・データ フロー・出力マッピング・責務分担を正規化し、導入側が 「PlanGate だけ」 「river-reviewer だけ」「両方」 の 3 パターンを迷わず選べるようにする。

本 IF は review-principles.md §7-bis の C-2 レビュア責務契約（2 レーン）を 変更しない。5 レビュー観点・ Severity・判定基準（§2〜4）も不変。本 IF は 接続の機械的規約 のみ。

2. レビューア設定ファイル .plangate-reviewers.yaml

リポジトリルートに任意配置（無ければ従来どおり PLANGATE_EXTERNAL_REVIEWER の単一プロバイダ動作）。スキーマ: schemas/plangate-reviewers.schema.json。 最小構成例: .plangate-reviewers.example.yaml。

version: "1.0"
reviewers:
  c2:
    provider: river-reviewer
    command: "river run . --phase upstream --output-format json"
    output_mapping:
      severity: finding.severity
      evidence: finding.evidence
      location: "finding.file + ':' + finding.line"
  v3:
    provider: river-reviewer
    command: "river run . --phase midstream --output-format json"
    output_mapping:
      severity: finding.severity
      evidence: finding.evidence
      location: "finding.file + ':' + finding.line"

3. 出力フォーマット変換

3.0 現行 runtime と structured normalization の境界

現行 bin/plangate review / _review_parallel() は reviewer stdout を取得し、 provider / lane の表示情報を付けて review-external.md へ書く。legacy output_mapping は runtime では評価しない。この事実を「変換済み」と扱ってはならない。

provider 固有 JSON を機械利用する場合は、#1394 で追加した scripts/reviewer_normalize.py を単一の normalization boundary とする。

provider stdout
   ↓
named adapter
   ↓
normalized reviewer envelope

named adapter は構文・既知フィールドを決定論的に変換するだけで、semantic similarity、 approval 判定、finding からの stance 推測を行わない。

first-class な bin/plangate review 配線と Deliberation position sidecar 生成は #1354 で Human-owned HO 変更として接続する。#1394 単独では legacy Markdown 出力挙動を変更しない。

3.1 River Review JSON → normalized reviewer envelope

旧 repository 名 s977043/river-reviewer は現行 s977043/river-review へ移動している。現行の schemas/output.schema.json はトップレベル issues[] + summary を持つ。

river-review-v1 adapter の主要変換:

River Review normalized field 備考
issues[].id source_finding_ref run 内 finding ID をそのまま保持
issues[].severity severity 既存 PlanGate 4 段階へ正規化
issues[].title claim タイトルを短い claim として保持
issues[].message rationale_summary 本文を rationale summary として保持
criterionRefs[] / artifactRefs[] evidence_refs[] explicit ref のみ
file + optional line evidence_refs[] location ref として保持

River Review の issues[] は finding であって Deliberation position ではない。 そのため初期 adapter は必ず:

position_capability = unavailable
positions = []

とする。decision / gate / finding 有無 / severity から support|oppose|conditional を推測しない。zero findings も support を意味しない。

explicit position を提供する producer は plangate-normalized-v1 contract を使う。

3.2 Severity マッピング

river-reviewer と PlanGate の 4 段階は 現時点で語彙一致。明示的に固定:

river-reviewer PlanGate (review-principles §3) マージ影響
critical critical ブロッカー
major major 修正推奨
minor minor 任意
info info 無視可

将来どちらかが語彙を変えた場合、本表が 唯一の正規変換点。未知 severity は安全側で major に丸める（versioning-stability-policy.md §2.1 制約強化 = major のため、追加時は本表更新を破壊的変更として扱う）。

3.3 events 最小フィールド（後続実装の解釈固定）

review-principles §7-bis の案を 本 IF で正規化する（#230 gate-event-normalization と整合）:

{ "review_id": "R-NNN", "lane": "design|codebase",
  "severity": "critical|major|minor|info",
  "reflected_in": "<artifact path>", "status": "open|reflected|deferred" }

events 化（gate-event-normalization.md）時は この形を踏襲する。本 PBI は 参照定義まで（events 発火実装は別 PBI）。

4. 責務分担

フェーズ PlanGate の責務 外部レビューア（river-reviewer）の責務
C-1 セルフレビュー（内部実施） 不使用
C-2 レビュー結果の受け取り + ゲート判定（2 レーン責務契約 §7-bis 適用） upstream スキルで plan 品質検証を実行
V-1 受け入れ検査の判定（内部） 不使用
V-3 外部レビュー結果の受け取り + 判定 midstream スキルで diff レビューを実行

5. 3 つの導入パターン

パターン .plangate-reviewers.yaml 動作
PlanGate だけ ファイル自体を置かない 内蔵 C-1/V-1 + PLANGATE_EXTERNAL_REVIEWER（codex 既定）
river-reviewer だけ c2 と v3 を river-reviewer に設定 外部レビューに一本化（PlanGate は受け取り + ゲート判定）
両方 c2 を river-reviewer、v3 を別 provider 等 フェーズごとに最適な provider を選択

.plangate-reviewers.yaml を 置く場合は reviewers に c2 / v3 のうち最低 1 つが必須（schema minProperties:1）。レビューアを 一切使わない場合はファイル自体を置かない。

いずれもゲート判定（C-3/C-4）と承認境界は PlanGate 側が保持（外部レビューアは 判定材料を提供するのみ・responsibility-classes.md）。

6. 検証

7. 関連

8. v2.0: 並列マルチレビューア（Mode 連動自動スケール）

v2.0 拡張（TASK-0122 / #424）。v1.0 との後方互換を維持する additive 拡張。

8.1 フィールド説明

フィールド 型 必須 説明
lane "design" \| "codebase" \| "security" 任意 レビューレーン（review-principles §7-bis に対応）
mode_threshold enum（後述） 任意 このレビューアが起動する最低 Mode。タスクの Mode がこの値未満なら自動スキップ
command string または array of string 必須 v2.0 では文字列配列も許容（配列は空白結合して実行）

8.2 Mode スケール表

mode_threshold の値と起動条件:

mode_threshold 値 起動するタスク Mode
ultra-light ultra-light 以上（全 Mode）
light light 以上
standard standard 以上
high-risk high-risk 以上
critical critical のみ

タスクの Mode は docs/working/TASK-XXXX/current-state.md または plan.md の **Mode**: / **モード**: 行から自動取得する。取得不能な場合は mode_threshold フィルタを無効化して全レビューアを実行する。

8.3 v2.0 設定例

version: "2.0"
reviewers:
  c2:
    - provider: codex
      lane: design
      mode_threshold: standard
      command: "codex review --phase upstream --output-format json"
      output_mapping:
        severity: finding.severity
        evidence: finding.evidence
        location: "finding.file + ':' + finding.line"
    - provider: gemini
      lane: security
      mode_threshold: high-risk
      command: "gemini review --phase upstream --output-format json"
      output_mapping:
        severity: finding.severity
        evidence: finding.evidence
        location: "finding.file + ':' + finding.line"
  v3:
    provider: codex
    command: "codex review --phase midstream --output-format json"
    output_mapping:
      severity: finding.severity
      evidence: finding.evidence
      location: "finding.file + ':' + finding.line"

8.4 並列実行の動作

  1. .plangate-reviewers.yaml の当該フェーズが配列形式の場合、各レビューアを & で並列起動し wait で全完了を待つ
  2. 失敗したレビューアは warn 扱いでスキップ（他のレビューアには影響しない）
  3. 結果は provider 名アルファベット順にソートし R-001, R-002 … と連番を付けて review-external.md に集約
  4. 並列実行の記録は decision-log.jsonl に parallel_review イベントとして append される

8.5 後方互換

9. 専門 Reviewer Skill 一覧（TASK-0126〜 段階導入）

既存の 2 レーン設計（review-principles.md §7-bis）を 維持しながら、C-2 / V-3 に接続する専門 Skill を段階的に整備する。 導入順: ① plan-quality → ② security-risk → ③ test-strategy → ④ 残 4 本（high-risk+ 限定）

フェーズ Skill Lane Mode 閾値 状態
C-2 plan-quality-reviewer design-validity light+ ✅ 導入済み（TASK-0126）
C-2 / V-3 security-risk-reviewer security standard+ 🔜 予定
C-2 / V-3 test-strategy-reviewer test-strategy standard+ 🔜 予定
V-3 implementation-quality-reviewer code-quality high-risk+ 🔜 予定
V-4 release-readiness-reviewer release critical+ 🔜 予定
V-3 docs-handoff-reviewer docs high-risk+ 🔜 予定

9.1 plan-quality-reviewer（設計妥当性レーン）

version: "2.0"
reviewers:
  c2:
    - provider: plan-quality-reviewer
      lane: design-validity
      mode_threshold: light
      command: "/plan-quality-reviewer"
      output_mapping:
        severity: finding.severity
        evidence: finding.body
        location: "finding.id"

10. 外部レビュー実行不可時の記録規約（#463）

C-2 / V-3 の外部 AI レビューが実行不可（CLI 未導入・API 不達・quota 超過・ネットワーク遮断等）の場合、review-external.md に以下を必須記録する。これにより「指摘なし（実行したが finding ゼロ）」と「実行不可（実行できなかった）」を区別し、監査連続性を保つ。

必須記録項目（unavailable 時）

項目 説明
実行状態 executed / unavailable を明示
実行不可の理由 具体的事由（例: codex CLI 未導入 / Gemini quota 超過）
代替レビュー観点 セルフレビュー（C-1）で補った観点、または後追いレビューの予定
未充足リスク 外部レビュー欠如で残るリスク（severity 相当の見積り）

判定への影響

events 連携（#230 と additive）

将来 events 化する場合の最小フィールド:

{ "review_id": "R-NNN", "lane": "design|codebase|security",
  "review_status": "executed|unavailable",
  "unavailable_reason": "<string|null>",
  "alternative_perspective": "<string|null>",
  "residual_risk": "<string|null>" }

テンプレート: docs/working/templates/review-external.md の「外部レビュー実行可否（必須）」セクション。

This site is open source. Improve this page.