skill-staged-review

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に調整されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex にインストールされているスキル名を使用します。 現在の Codex シェルとサブエージェントツールを使用してください。現在のセッションで利用可能であることが確認されるまでは、プロバイダー、モデル、ホストのサブエージェントが利用可能だと主張しないでください。 ホストツールに相当するものについては、skills/blocks/codex-host-adapter.md を参照してください。

実行契約（必須 - 省略不可）

この生成された Codex スキルは、元のスキルから引き継いだ、適用必須のワークフロー契約を保持しています。

禁止事項：

• このスキルで実行が求められている場合、参照されているワークフローコマンドを要約、模擬実行、または省略しないでください。
• 実際のファイルまたはコマンド出力を確認せずに、プロバイダーの出力や検証成果物が存在すると主張しないでください。
• 必須のプロバイダー、コマンド、またはホスト機能を利用できない場合、何も伝えずに処理を続けないでください。利用できない依存関係を報告し、サポートされている代替手段を使用してください。

2 段階レビューのパイプライン

仕様への適合性（正しいものを構築したか）とコード品質 （正しく構築したか）を分離します。ステージ 1 に合格してからステージ 2 を実行してください。

ステージ 1：仕様への適合性

実装が意図契約に適合しているかを検証します。

ステップ 1：意図契約を読み込む

PLAN_STORAGE="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}/scripts/plan-storage.sh"
OCTO_PLAN_DIR="$("$PLAN_STORAGE" current "$PWD" 2>/dev/null || true)"
INTENT_FILE="${OCTO_PLAN_DIR:+${OCTO_PLAN_DIR}/session-intent.md}"
if [[ -f "$INTENT_FILE" ]]; then
  echo "Intent contract found: $INTENT_FILE"
  cat "$INTENT_FILE"
else
  echo "WARNING: No current resolved intent contract found for this workspace"
  echo "Skipping Stage 1 — proceeding to Stage 2 (code quality) only."
fi

意図契約が存在しない場合： ユーザーに警告し、ステージ 2 に進みます。成功基準を捏造してはいけません。契約は以前のワークフローで作成されている必要があります。

ステップ 2：成功基準を検証する

意図契約に記載された成功基準ごとに、次の手順を実施します。

1. ## Success Criteria セクションから基準を読み取る
2. コードベース内で、その基準が満たされていることを示す証拠を探す
3. ステータスを付ける：
   • [PASS] — 基準が満たされていることを証拠が確認している
   • [FAIL] — 基準が満たされていないことを証拠が示している
   • [PARTIAL] — 部分的に満たされており、不足箇所が特定されている

結果を提示します。

## Stage 1: Spec Compliance

### Success Criteria Check

#### Good Enough Criteria
- [PASS] Criterion 1: <how it was met>
- [FAIL] Criterion 2: <why not met, what's missing>

#### Exceptional Criteria
- [PARTIAL] Criterion 1: <what's done, what's remaining>

ステップ 3：境界を検証する

意図契約に記載された境界ごとに、次の手順を実施します。

1. ## Boundaries セクションから境界を読み取る
2. 実装に違反がないか確認する
3. ステータスを付ける：
   • [RESPECTED] — 違反が見つからない
   • [VIOLATED] — 実装が境界を越えている

### Boundary Check
- [RESPECTED] Boundary 1: <confirmation>
- [VIOLATED] Boundary 2: <what violated it>

ステップ 4：ステージ 1 の判定

結果	アクション
すべての基準が PASS ＋ すべての境界が RESPECTED	ステージ 2 に進む
基準に FAIL がある	失敗を報告する。ユーザーに今すぐ修正するか、それでも続行するかを確認する
境界に VIOLATED がある	違反を報告する。ユーザーに今すぐ修正するか、それでも続行するかを確認する

ユーザーが修正を選んだ場合： レビューを停止し、必要な修正を具体的に列挙します。 ユーザーが続行を選んだ場合： 例外を記録し、ステージ 2 に進みます。

ステージ 2：コード品質

スタブの検出と、コード品質の包括的なレビューを実施します。

ステップ 1：スタブの検出

変更されたすべてのファイルに対して 5 つのチェックを実行します。

# Get changed files
if git diff --cached --name-only 2>/dev/null | head -1 > /dev/null; then
  changed_files=$(git diff --cached --name-only)
elif git diff --name-only HEAD~1..HEAD 2>/dev/null | head -1 > /dev/null; then
  changed_files=$(git diff --name-only HEAD~1..HEAD)
else
  changed_files=$(git diff --name-only)
fi

# Filter source files
source_files=$(echo "$changed_files" | grep -E "\.(ts|tsx|js|jsx|py|go|rs|sh)$" || true)

STUB_ISSUES=0

for file in $source_files; do
  [[ -f "$file" ]] || continue

  # Check 1: TODO/FIXME/PLACEHOLDER markers
  todo_count=$(grep -cE "(TODO|FIXME|PLACEHOLDER|XXX)" "$file" 2>/dev/null || echo "0")
  if [[ "$todo_count" -gt 0 ]]; then
    echo "WARNING: $file has $todo_count TODO/FIXME markers"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 2: Empty function bodies
  empty_fn=$(grep -cE "function.*\{\s*\}|=>\s*\{\s*\}" "$file" 2>/dev/null || echo "0")
  if [[ "$empty_fn" -gt 0 ]]; then
    echo "ERROR: $file has $empty_fn empty functions"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 3: Suspicious null/undefined returns
  null_ret=$(grep -cE "return (null|undefined);" "$file" 2>/dev/null || echo "0")
  if [[ "$null_ret" -gt 0 ]]; then
    echo "WARNING: $file has $null_ret null/undefined returns — verify intentional"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 4: Substantive line count
  subst_lines=$(grep -cvE "^\s*(//|/\*|\*|#|import|export|$)" "$file" 2>/dev/null || echo "0")
  if [[ "$subst_lines" -lt 5 ]]; then
    echo "WARNING: $file has only $subst_lines substantive lines"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 5: Mock/test data in production code
  mock_count=$(grep -cE "const.*(mock|test|dummy|fake).*=" "$file" 2>/dev/null || echo "0")
  if [[ "$mock_count" -gt 0 ]]; then
    echo "WARNING: $file has $mock_count mock/test data references"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi
done

echo "Stub detection complete: $STUB_ISSUES issues found"

ステップ 2：複数の LLM による品質レビュー（推奨）

スタブを検出した後、複数のプロバイダーにコードを送信し、並行して品質レビューを実施します。 Claude だけのレビューパイプラインでは、外部モデルが検出する問題を見逃します。Codex はロジックエラーや正確性の確認に優れており、Antigravity は独立したセキュリティ分析とエッジケース分析を提供します。両方を利用することで、より信頼性の高い検出結果が得られます。

プロバイダーの利用可否を確認し、並行して送信します：

# Get the diff for review
DIFF_CONTENT=$(git diff --cached 2>/dev/null || git diff HEAD~1..HEAD 2>/dev/null || git diff)

外部プロバイダーが利用可能な場合は、Octopus ルーティングを通じて対象を絞ったレビューを送信します：

providers=()
command -v codex >/dev/null 2>&1 && providers+=(codex)
command -v agy >/dev/null 2>&1 && providers+=(agy)

for provider in "${providers[@]}"; do
  safe_provider=$(printf '%s' "$provider" | tr -c '[:alnum:]_-' '_')
  "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" spawn "$provider" \
    "Review this code diff for LOGIC, CORRECTNESS, and SECURITY issues. Focus on:
1. Logic bugs and off-by-one errors
2. Unhandled error paths
3. Race conditions or concurrency issues
4. Incorrect type handling or implicit coercions
5. Security issues at trust boundaries

Report ONLY high-confidence issues. Do NOT flag style preferences.

DIFF:
${DIFF_CONTENT}" > "/tmp/octopus-review-${safe_provider}.md" 2>/dev/null &
done

外部レビューの完了を待ち、Claude と利用可能な外部プロバイダーのすべての検出結果を統合して、包括的な品質評価を作成します。 外部プロバイダーが利用できない場合は、以下の Claude のみのレビューに切り替えます。

Claude（あなた）は、いずれの場合も品質レビューを全面的に実施します：

1. アーキテクチャとの整合性 — コードはプロジェクトのパターンに従っていますか？
2. エラー処理 — エラーを適切に捕捉して処理していますか？
3. セキュリティ — OWASP Top 10 に関する問題はありませんか？
4. パフォーマンス — 明らかなボトルネックや N+1 クエリはありませんか？
5. 可読性 — 命名は明確で、複雑さは妥当ですか？
6. テストカバレッジ — 新しい動作はテストされていますか？

外部の検出結果を統合します： 外部プロバイダーから結果が返された場合は、その検出結果をあなたの検出結果と統合します。プロバイダー間で重要度の判断が異なる場合は、その相違を記載します。複数のプロバイダーが同じ問題を指摘した場合は、信頼度が高いものとして示します。

ステップ 3：ステージ 2 の結果を提示する

## Stage 2: Code Quality

### Stub Detection
- Files scanned: N
- Issues found: N
- [Details of each issue]

### Quality Review
- Architecture: [PASS/WARN/FAIL]
- Error Handling: [PASS/WARN/FAIL]
- Security: [PASS/WARN/FAIL]
- Performance: [PASS/WARN/FAIL]
- Readability: [PASS/WARN/FAIL]
- Test Coverage: [PASS/WARN/FAIL]

### Blocking Issues
[List any issues that must be fixed before merge]

### Recommendations
[Non-blocking suggestions for improvement]

統合レポート

両方のステージが完了したら、統合レポートを提示します：

## Staged Review — Complete

### Stage 1: Spec Compliance
- Success Criteria: N/N passed
- Boundaries: N/N respected
- Verdict: [PASS/FAIL]

### Stage 2: Code Quality
- Stub Detection: N issues
- Quality Score: [HIGH/MEDIUM/LOW]
- Blocking Issues: N
- Verdict: [PASS/FAIL]

### Overall Verdict: [PASS/FAIL]

[If FAIL: list specific items that must be addressed]
[If PASS: ready for merge/ship]

各レビュータイプの使い分け

レビュータイプ	使用する場面	確認内容
skill-code-review	簡易的な PR レビュー	コード品質のみ
skill-staged-review	大規模な機能の完成時	仕様への準拠＋コード品質
skill-verification-gate	完了を報告する前	成功したことの証拠

エラー処理

エラー	解決方法
インテント契約がない	ステージ 1 を省略してユーザーに警告し、ステージ 2 のみ実行
変更されたファイルがない	レビュー対象がないことを報告
Git を利用できない	git diff の代わりにファイル一覧を使用
ステージ 1 の失敗	修正するか、上書きするかをユーザーに確認
ステージ 2 のブロッキング問題	マージ前に必ず修正

要点

Staged Review = Spec Compliance (Stage 1) + Code Quality (Stage 2)
Stage 1 gates Stage 2. Both must pass for overall PASS.

正しいものを作り、その後で正しく作り上げます。

PR への結果の投稿（v8.44.0）

統合レポートの生成後、オープン中の PR があるか確認し、検出結果を投稿します。

# Detect open PR on current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
PR_NUM=""

if [[ -n "$CURRENT_BRANCH" && "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then
    if command -v gh &>/dev/null; then
        PR_NUM=$(gh pr list --head "$CURRENT_BRANCH" --json number --jq '.[0].number' 2>/dev/null || echo "")
    fi
fi

if [[ -n "$PR_NUM" ]]; then
    # Post combined report through the outbound credential gate.
    REPO_SLUG=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
    COMMENT_BODY="## Staged Review — Claude Octopus

${COMBINED_REPORT}

*Staged review by Claude Octopus (/octo:staged-review)*"
    if ! "${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}/scripts/safe-gh-comment.sh" \
            --repo "$REPO_SLUG" pr-comment "$PR_NUM" - <<< "$COMMENT_BODY"; then
        echo "GitHub write state is unknown; check for the staged review comment before retrying:" >&2
        gh pr view "$PR_NUM" --repo "$REPO_SLUG" --comments || true
        return 1 2>/dev/null || exit 1
    fi

    echo "Staged review posted to PR #${PR_NUM}"
fi

動作：

• /octo:deliver または /octo:embrace ワークフロー内で実行する場合は、自動的に投稿します
• 単独で /octo:staged-review を実行した場合は、まずユーザーに確認します