sunrain520/spec-first/spec-code-review

Code Review

Reviews code changes against intent, tests, standards, and risk lenses. When reviewer dispatch is explicitly authorized and callable, it uses selected personas and merges structured findings; otherwise it performs an honest inline report-only review with degraded coverage.

Workflow Contract Summary

• 输入： 当前分支、显式 base、远端 branch/PR，及可选 plan/task-pack 上下文。
• 输出： 默认 report-only 的结构化 findings、actionable queue、coverage、验证限制与 run artifact；mode:agent 返回 JSON。
• 硬出口： scope/base 不可解析、task context 漂移或越界、错误 checkout、必需独立覆盖不可用时不得给出完整 merge-ready 声明。
• 权威： source/diff/test/log 提供事实，reviewers 判断语义；review、local mutation、commit 与 landing 是四个独立授权面。
• 消费者： 人工 reviewer、spec-work、caller-owned shipping/LFG 流程与后续 residual gate。

When to Use

• Before creating a PR
• After completing a task during iterative implementation
• When feedback is needed on any code changes
• Can be invoked standalone
• Can run inside larger workflows; use mode:agent when the caller needs JSON instead of markdown tables

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md. Overrides: high-risk

• foreign-residual-workspace -> blocked-action-required: stop before reviewer dispatch that depends on suspect local artifacts, checkout mutation, root-cause-like review claims, or PR-ready verdicts until the named cleanup/init action runs or the user explicitly accepts degraded evidence.
• optional external-tool evidence unavailable -> fallback-only: use bounded direct source, diff, test, log, and user-provided evidence; disclose missing reviewer/tool coverage and do not claim unconfirmed impact or full review coverage.
• non-git-build-workspace coverage gaps -> partial: review only the selected repo/inspected build surfaces and directly inspect uncovered modules before claiming they are unaffected.

Argument Parsing

Parse the invocation arguments supplied by the current host for optional tokens. Strip only recognized tokens while preserving quoted paths, Windows drive paths, URLs, and the order of the remainder before interpreting it as a PR number, GitHub URL, or branch name.

Grouping is presentation, not a mode. The grouping: tokens change how the finding set is organized for triage — never reviewer selection, merge logic, scope rules, or the Stage 5c apply decision.

Mode alias: mode:headless normalizes to mode:agent. mode:agent + mode:headless is not a conflict.

Path-valued tokens split only at their first : and may be host-quoted so paths with spaces remain one argument. Preserve the decoded path exactly; do not split it again on whitespace. Windows drive letters inside the value and POSIX paths are data, not extra tokens.

Conflicting arguments: Stop without dispatching reviewers when:

• Multiple incompatible scope selectors appear together (e.g. base: and a PR number/branch target — base: means "review the current checkout against this base")
• Multiple distinct mode: tokens other than the mode:agent/mode:headless alias pair
• Multiple distinct grouping: tokens (e.g. grouping:off and grouping:always)
• task-pack and task tokens must appear together, exactly once, with exactly one task-context: token
• any task token appears without mode:agent or without base:, or task context is combined with a PR number/URL/branch target

Deprecated mode:autofix is not a conflict — ignore the token and proceed with the normal flow (see below).

Emit a one-line failure reason. In mode:agent, return JSON: {"status":"failed","reason":"..."}.

Phase 0a: Freeze effective mode before any tool call

Normalize mode before interpreting intent or running any repository command. This is an exit gate, not a later presentation choice:

effective_mode: default | agent
source_mutation_gate: open | closed
artifact_write_gate: review-artifacts-only

When mode:agent or its mode:headless alias is present, set effective_mode: agent, mutation_policy: report-only, and source_mutation_gate: closed. In this mode, adjacent fix/apply wording is intent data, not mutation authority. Do not call project-writing tools, apply_patch, edit/write APIs, git apply, git restore, git checkout, formatters with write flags, or any command that can rewrite reviewed source. The only permitted writes are run-scoped review artifacts and deterministic evidence under the exact artifact roots owned below.

Generate the run ID and resolve REVIEW_ARTIFACT_DIR here, before scope inspection. Use the OS-native temporary-directory rules in Stage 4 and reuse the same canonical path for the entire run. Failure to create an artifact directory does not open the source mutation gate; mode:agent continues report-only with an in-band limitation.

Phase 0: Resolve mutation, commit, and dispatch policy

Before scope detection, derive three independent run-local facts from the current user request and any visible upstream handoff:

mutation_policy: report-only | apply-fixes
commit_authorization: authorized | missing
worker_dispatch_authorization: authorized | missing
capability_probe: not_applicable | attempted | unavailable
worker_dispatch_capability: available | missing | unknown
worker_context_isolation: isolated | inherited | unknown
worker_model_override: supported | unsupported | unknown
worker_bounded_parallelism: supported | unsupported | unknown

• Ordinary requests to "review", "check", "audit", or run spec-code-review use mutation_policy: report-only.
• Report-only means the reviewed files stay byte-identical. Under report-only, never "helpfully" fix, revert, restore, or normalize a defect you found — not even to undo an obviously bad change, and not even when the finding is P0. Finding a bug is evidence for the report; repairing it belongs to an explicitly authorized apply-fixes run (or the caller). git restore, git checkout <file>, git apply -R, edit/write tools on reviewed source, and formatter runs that rewrite it are all violations, regardless of the declared mutation_policy in the output JSON matching report-only.
• Use mutation_policy: apply-fixes only when the current user or upstream caller explicitly says review-and-fix, review and fix, apply fixes, or equivalent. mode:agent always forces report-only even when adjacent text asks to apply.
• apply-fixes authorizes only bounded local review-owned edits. It does not authorize commit, push, PR creation/update, tickets, or unrelated cleanup.
• Set commit_authorization: authorized only when commit creation is separately explicit. Without commit authorization, return a verified uncommitted review-fix set.
• Set worker_dispatch_authorization: authorized only when the current user/upstream explicitly requests subagents, personas, delegated reviewers, multi-agent review, or parallel review. A review invocation, task context, plan, available primitive, or permission setting is not dispatch authorization. Missing authorization forbids schema discovery and fixes capability_probe: not_applicable + worker_dispatch_capability: unknown. Only after authorization may the current-session registry/schema be consumed as provider_untrusted evidence; confirmed absence records subagent_capability_missing, while unavailable/incomplete/ambiguous discovery records worker_capability_unproven. Normalize every path as worker_dispatch_outcome; use only live facts for isolation, model override, parallelism, permission, capacity, output, and mutation claims.

If review repo scope is ambiguous in a parent multi-repo workspace, stop before local diff claims or apply and return a failure reason naming the required selected child repo/current checkout; do not open a blocking prompt. Read-only PR-remote scope may proceed from explicit PR metadata without choosing a sibling checkout. Generated runtime mirrors remain out of source-fix scope.

Operating principles

Same review pipeline for default and mode:agent: