skill-staged-review

Host：Codex CLI — 此技能最初为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而非 /octo:* 斜杠命令。 使用当前启用的 Codex shell 和子 Agent 工具。除非当前会话已提供相应能力，否则不要声称某个提供商、模型或 Host 子 Agent 可用。 有关 Host 工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

执行约定（强制 — 不可跳过）

此生成的 Codex 技能保留了源技能中强制执行的工作流约定。

禁止：

• 此技能要求执行所引用的工作流命令时，不得总结、模拟或跳过该命令。
• 未检查实际文件或命令输出前，不得声称提供商输出或验证产物已存在。
• 所需的提供商、命令或 Host 能力不可用时，不得默不作声地继续；应报告不可用的依赖项，并使用受支持的备用方案。

两阶段审核流程

将规范符合性（是否构建了正确的内容？）与代码质量 （是否以正确的方式构建？）分开。阶段 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 独立调用时先询问用户