メインコンテンツまでスキップ

river review plan CLI 仕様

river review plan は River Review が提供する CLI サブコマンドのうち、上流アーティファクトに対して レビュー計画（plan）を生成・実行する エントリポイントです。本ドキュメントは引数、入力アーティファクト、出力フォーマット、終了コード、severity 区分（fail / warn / advisory）、machine-readable 出力方針を定義します。

関連 Issue: #517（Task）/ #509（Capability）/ #507（Epic） 前提: 入力アーティファクトの契約は Artifact Input Contract に従う。

位置づけ​

  • river review plan は PlanGate v6 をはじめとする上流ワークフローが生成した artifact を入力とし、レビュー計画（実行対象 skill の選定・順序）と、その計画に基づく実行結果を Review Artifact スキーマで出力する。
  • 既存の river run がローカル開発者向けの汎用エントリであるのに対し、river review plan は CI / バッチ実行で安定した契約 を提供することを目的とする。
  • 安定性ラベルは Beta（参考: Stable Interfaces）。CLI オプションの追加は minor、削除/意味変更は major bump とする。

Usage​

river review plan [options]

最小例​

# 入力 artifact をカレントディレクトリから自動検出してレビュー計画を実行
river review plan

# 明示的に artifact を指定し、JSON 出力をファイルへ書き出す
river review plan \
  --artifact pbi-input=./artifacts/pbi-input.md \
  --artifact plan=./artifacts/plan.md \
  --artifact diff=./artifacts/diff.patch \
  --output json \
  --output-file ./artifacts/review-artifact.json

# 計画のみを生成（実行しない）
river review plan --plan-only --output json

引数​

artifact 指定​

オプション型必須説明
--artifact <id>=<path>反復可任意Artifact Input Contract で定義された artifact ID とファイルパスのペア。複数指定可。
--artifacts-dir <path>string任意artifact 既定ファイル名を探索するベースディレクトリ。未指定時はカレントディレクトリ。

artifact 解決の優先順位は Artifact Input Contract「指定方法（入力チャネル）」に従う（CLI 引数 → 設定ファイル → ディレクトリ自動検出）。

計画制御​

オプション型デフォルト説明
--phase <value>enummidstreamupstream / midstream / downstream。レビューフェーズ。
--planner <value>enumoffoff / order / prune。AI プランナーのモード。
--plan-onlyflagfalseレビュー計画のみを生成し、skill を実行しない。status は ok、findings は空配列となる。
--include-skill <id>反復可-計画で必ず含める skill ID。
--exclude-skill <id>反復可-計画から除外する skill ID。
--max-cost <usd>number-計画の見積もりコストが上限を超えた場合は実行せず終了コード 1 で終了する。

出力制御​

オプション型デフォルト説明
--output <format>enumjsonjson（既定・machine-readable）/ markdown（人間向け、#976 実装済み）。text は未実装。
--output-file <path>string-出力先ファイル。未指定時は標準出力。
--summary-file <path>string-人間向けサマリ（Markdown）を別ファイルへ書き出す。--output json と併用する想定。
--quietflagfalsestdout への進捗ログを抑制（エラーは stderr に出力）。CI 用。
--debugflagfalseデバッグ情報を Review Artifact の debug フィールドに含める。

備考（#802 Phase 3、2026-05-18）: --output <format> = 形式、--output-file <path> = 出力先という契約は plan/exec/verify で統一されており、グローバル --output <mode>（river run）と意味が一致します（PlanGate CLI 安定化ロードマップ の決定）。--format <format> は review 系の互換 alias として受理されますが canonical は --output です。--output と --format が両指定かつ不一致の場合は設定エラー（exit 3）。

実装現況（#976 更新）: 後方互換のため --output/--format 未指定時は JSON を出力します。json 明示・markdown 明示はともに受理（markdown は #976 で実装）、text の明示指定は未実装エラー（exit 3）、yaml は review 契約外のため exit 3。

失敗判定の閾値​

オプション型デフォルト説明
--fail-on <severity>enumcriticalcritical / major / minor / info。指定 severity 以上の finding が 1 件でもあれば fail と判定。
--warn-on <severity>enummajor--fail-on には届かないが warn と扱う閾値。
--advisory-onlyflagfalseseverity に関わらず常に成功扱い（exit 0）。発見事項は出力されるが CI を落とさない。

severity の語彙は schemas/output.schema.json と .claude/rules/review-core.md の severity マッピングに準ずる（critical / major / minor / info）。

入力アーティファクト​

river review plan が認識する artifact は Artifact Input Contract の「対象アーティファクト一覧」と完全に一致する。対象 ID の集合と既定ファイル名は同契約を SSoT とし、本仕様では再掲しない（現時点で 12 種類）。

  • artifact ID とファイル形式の追加・変更・削除は本仕様ではなく Artifact Input Contract 側で管理する。
  • diff artifact が未指定で git diff フォールバックも空の場合、status を no-changes とし、skill は実行されない（exit 0）。
  • 必須 artifact の解決に失敗した場合は exit 1（後述）。

出力フォーマット​

--output text（未実装）​

人間が読める plain text 要約を想定するフォーマットだが、review namespace では未実装（明示指定すると exit 3）。人間向け表示には --output markdown を使用する。review namespace の既定は --output json。

--output markdown（#976 実装済み）​

GitHub Actions のコメント投稿などで利用する人間可読 Markdown を出力する（status / phase / planner mode、Selected/Skipped skills、findings がある場合は ## Findings セクション）。--summary-file と同じレンダラ（formatReviewPlanSummaryMarkdown）を使用する。JSON は引き続き唯一の machine-readable 契約であり、Markdown は人間向けの派生表示。

--output json（machine-readable / 安定契約）​

schemas/review-artifact.schema.json に準拠した JSON を出力する。

  • スキーマバージョンは version フィールドで管理（現行 "1"）。
  • findings 配列の各要素は output.schema.json の issue 定義と互換。
  • --debug 指定時のみ debug セクションを含める。
  • --plan-only 指定時は findings を空配列、status を ok とし、plan.selectedSkills のみが意味を持つ。

JSON 出力は 唯一の安定 machine-readable 契約 とする。後続パイプライン（Riverbed Memory 取り込み、評価、CI gate）は本 JSON のみを参照することを推奨する。

Severity 区分（fail / warn / advisory）​

区分判定基準既定の振る舞い
failseverity が --fail-on 以上（既定 critical）の finding が 1 件以上exit 1 で終了。CI を落とす。
warn--fail-on 未満かつ --warn-on 以上（既定 major）の finding が 1 件以上exit 2 で終了。CI 設定で扱いを選択可能。
advisory上記いずれにも該当しないが finding が存在する（minor / info のみ、または --advisory-only 指定）exit 0 で終了。情報提供のみ。

severity の内部語彙（blocker / warning / nit）と JSON スキーマ語彙（critical / major / minor / info）の対応は .claude/rules/review-core.md を参照する。JSON スキーマ語彙のうち info は内部語彙に直接対応するトークンを持たず、severity が未指定の finding（.claude/rules/review-core.md の「(なし)」列）に割り当てられる補助レベルで、現時点では内部語彙からの変換には使用されない。不明な severity 値は fail-safe として major に分類される。

終了コード​

Exit意味
0成功。status が ok / no-changes / skipped-by-label で、かつ fail / warn 判定なし。
1失敗。--fail-on 閾値到達（--advisory-only 未指定時）、必須 artifact 欠損、計画/実行エラー、--max-cost 超過、いずれか。
2警告のみ。--warn-on 閾値に達したが --fail-on には届かない finding が存在する。
3設定エラー。引数バリデーション失敗、設定ファイル読み込み失敗など。

--advisory-only を指定した場合、fail / warn 判定は無効化され、内部エラー（artifact 欠損・実行エラー）以外は常に exit 0。

実装現況（#976）: gate 判定は opt-in で、--fail-on / --warn-on / --advisory-only のいずれかを明示したときのみ exit 1 / 2 を返す。いずれも未指定なら従来どおり成功時 exit 0（既存呼び出し・plangate-review workflow は非破壊）。フラグを与えたときの既定値は --fail-on critical / --warn-on major。判定は artifact の findings[].severity の最大値に基づく。

CI / 後続システムとの接続​

  • Review Artifact: --output json --output-file <path> を CI の artifact upload で永続化することを推奨する。
  • GitHub Action: runners/github-action/action.yml の inputs から本 CLI へのマッピングを提供する（未実装、別途対応予定）。
  • Riverbed Memory: 取り込み入力としては JSON 出力のみを正とする（参考: Riverbed Storage）。
  • PR コメント: idempotent 更新（<!-- river-review --> marker）の方針は Stable Interfaces を継承する。

互換性ポリシー​

  • --artifact で渡せる ID 集合は Artifact Input Contract に従い拡張される。
  • フラグ追加は minor、フラグの削除・意味変更・既定値変更は major bump とする。
  • exit code の意味（0 / 1 / 2 / 3）は Stable Contract として扱い、変更には major bump を要する。
  • JSON 出力スキーマの破壊的変更は Review Artifact のバージョニングに従う。

関連ドキュメント​