Code Review

代码评审 (code-review)

能力边界

• 能做: 功能正确性对照（实现 vs AC/契约）、代码质量审查、命名/风格规范检查、安全漏洞检测、架构合规验证、测试质量审查、项目级腐化指标扫描（重复/死码/复杂度）
• 不做: 修改代码(仅报告问题)、需求评审；任务依赖图由 task-dep-analysis 负责

输入规范

• 代码文件或目录(DEV产出)
• arch#§7开发约定(命名/风格/Git约定)
• arch#§5非功能架构(安全/错误处理)

输出规范

• 任务粒度审查: CODE-REVIEW-{task_id}-r{N}.md（问题列表 + 严重等级: CRITICAL/HIGH/MEDIUM/LOW）
• 项目级扫描: CODE-SCAN-{YYYYMMDD}-r{N}.md（腐化指标聚合 + 严重等级）
• 审查结论: approved/approved_with_notes/needs_revision

操作指令: 任务粒度评审 (review)

Step 1: Layer 1 — Lint脚本自动检查

前置判断: 读取当前平台 Hook 配置（Claude: .claude/settings.json；Cursor: .cursor/hooks.json），检查是否存在 matcher 为 Edit|Write（Cursor 可为 Write/StrReplace）且 command 包含 lint_format.py 的条目:

• 已配置 lint hook → 编码阶段已通过 hook 以 --fix 模式实时修复格式/lint问题，跳过 Layer 1，直接进入 Step 2 Layer 2，并在审查报告标题下标注 Layer 1 delegated to hook
• 未配置 lint hook → 执行: cataforge skill run code-review -- review {file_or_dir}

调用约定: 入口与返回码语义按 COMMON-RULES §Layer 1 调用协议。本 skill 增量：exit 1 时可追加 --fix 自动修复后重新检查——--fix 就地改写被审文件，执行权属仅限 implementer（continuation）/ tdd-engine / lint hook 语境，reviewer 角色（禁改被审对象）禁用，遇 convention 类 finding 记入报告由 implementer continuation 修复；未知参数与非法 --focus 值为用法错误（exit 2）；两个模式均支持 --format json 输出结构化 finding（Layer 2 与报告聚合的机读输入）。

工具适配与检查清单见 §Layer 1 检查项；工具不存在时自动跳过并 WARN，不阻断检查流程。

Step 2: Layer 2 — AI语义审查

语言细则: 进入语义审查前，根据 framework.json project.languages，按需载入本 skill references/lang-<lang>.md（仅 active 语言，逐个 Read），作为该语言的评审细则（坏味道、安全陷阱、缺陷模式、性能反模式、评审 checklist）。这是散文评审参考，与 §Plugin-style rules 的 rules/*.yaml（Layer 1 机检 wiring）互补、不重复。

Layer 2 短路条件（降低轻量任务的审查开销，类比 doc-review §Layer 2 短路）:

满足以下任一条件且 Layer 1 exit 0 时跳过 Layer 2 直接判定为 approved:

1. 任务卡 task_kind ∈ CODE_REVIEW_L2_SKIP_TASK_KINDS（默认 [chore, config, docs]）
2. 任务卡 tdd_mode: light + AC 数 ≤ CODE_REVIEW_L2_SKIP_LIGHT_MAX_AC + Layer 1 输出无 security/error-handling 类 finding
3. 调度方声明 layer1-only 降级（由 ORCHESTRATOR-META-PROTOCOLS §Adaptive Review 反向降级触发；这是 Layer 2 编排参数，不传入 Layer 1 CLI——CLI 只认 review|scan 子命令与 --fix/--focus/--format，未知参数报 exit 2）

短路豁免（即使命中上述条件也强制跑 Layer 2）:

• 任务卡 security_sensitive: true
• 任务卡 user_facing_critical_path: true（页面/路由/UI 可达性 — 形式契约对但 handler 留白会被全档 light 短路放过；详见 §integration-wiring）
• 任务卡 consumer_components 字段非空（声明了下游 wiring 消费点 → 隐式 user-facing critical path）
• Layer 1 输出含任一 finding 涉及 security / error-handling / 注入 / 鉴权 / 加密 / 输入校验

命中短路时仍需按 Step 3/4 产出 CODE-REVIEW-{task_id}-r{N}.md 报告，front matter status: approved，并在报告标题下标注 Layer 2 skipped (short-circuit: <触发条件>)。降级场景（Layer 1 异常 / FAIL）不适用短路。

通过context加载 arch#§7开发约定 和 arch#§5非功能架构，按以下维度审查（括号内为对应的 category 枚举值；排序即注意力优先级——实质缺陷在前；Layer 1 lint 已机检的形式面不复报）:

• 功能正确性(correctness): 实现语义与任务卡 AC / arch 契约逐条对照——每条 AC 的 Then 由实现路径真实兑现，不以测试绿等价（弱断言可让缺陷带绿通过）；算法与边界（空集合/极值/差一/非法状态转换）；数据完整性（静默吞错、部分写入、丢失更新）。与 test-quality 分工：test-quality 审测试本身，correctness 直接审实现
• 安全漏洞(security): OWASP Top 10 检查(注入/XSS/认证/敏感数据暴露等)
• 集成连线(integration-wiring): 接线对象在生产路径有真实调用点、不是空 stub / 占位返回 / 仅满足类型契约的形式。仅 tests/ 内构造调用不算落地。各语言反例与正则候选见 wiring-checks.md；CHECKS_MANIFEST wiring_empty_handler 与 plugin-style YAML (wiring-{lang}.yaml) 承载具体识别规则。下游声明 wiring_placeholder: true + 关联 backlog ID 则豁免
• 错误处理(error-handling): 是否符合arch§5.3错误处理策略
• 接口一致性(consistency): 实现是否与arch接口契约匹配
• 代码结构(structure): 模块组织、职责划分是否合理。项目声明 arch 层模型时以 Layer 1 arch_guard 报告为输入，聚焦无 import 信号的语义越层（职责错置、接口层内嵌业务规则），不复查已机械判定的 import 方向违规
• 性能(performance): 热路径上的循环内 I/O、重复计算、明显劣化的复杂度量级；细则见各语言 references/lang-<lang>.md 性能反模式段。仅报可指认触发场景的问题，不做投机性微优化建议
• 视觉保真(visual-fidelity, 仅 user_facing_critical_path: true 且含样式/标记的 UI 任务): Layer 1 ui_fidelity 已机械抓死 token / 未加载字体 / 幽灵类；此处补静态抓不到的渲染缺陷——内容/图标是否被渲染成字面文本、激活与状态视觉是否真出现、计算样式（computed-style）是否等于设计值。收口须有渲染证据（截图或运行期计算样式读数），不以绿单测代替。无头 / 沙盒环境取不到渲染证据时不以 [ENV-LIMITATION] / [ASSUMPTION] 豁免，按 COMMON-RULES §verdict_blocking_semantics 出 conditional_release + 非空 blocking_conditions（条件=补一次真实渲染核验）驱动闭环
• 模拟器证据资格(simulator-evidence, 仅当审查证据引用外部系统模拟器/mock 结论时): 按保真度契约核对（external-truth-first.md），placeholder / 未声明者按证据不存在处理
• 测试质量(test-quality, 仅当审查范围包含 tests/ 目录时; AC 覆盖完整度由 sprint-review 负责，此处不重复):
  • 断言有效性: 每个测试是否包含对被测系统返回值/状态/副作用的有效断言
  • 断言强度: 断言必须绑定真实可观测属性（契约定义的返回值字段 / 状态变化 / 外部副作用）。仅校验 mock/spy 调用计数 / 对象存在性 / 常量真值的"弱断言"视为测试 bug；若 mock 中诡异条件让弱断言 PASS（永远返回常量 / 永远 raise / 强行短路真实路径），视为 implementation bug 假阳性而非测试问题。与 implementer §Assertion Strength Guard 同源
  • 测试逻辑: 断言的期望值是否与接口契约一致，测试是否验证了声称的行为
  • 边界覆盖: 是否覆盖关键边界条件（空值、异常输入等）
• 命名规范(convention): 文件/变量/接口命名是否符合arch约定；Layer 1 lint 机检面不复报，仅报机检抓不到的语义命名问题（名实不符、误导性命名）

维度收敛: 调用方可传 --focus <category[,...]>（值取自 COMMON-RULES §统一问题分类体系，另含 Layer 1 专属维度 integration-wiring / visual-fidelity / arch），仅审查指定维度。不传时跑全维度。例如：cataforge skill run code-review -- review {path} --focus security,error-handling。review 模式下 Layer 1 同步收敛：只执行 category 命中的检查（无命中维度的 Layer 1 检查跳过），Layer 2 按同一 focus 收敛散文维度。

增量审查模式（revision re-review）:

当同 task_id 已存在上一轮 CODE-REVIEW 报告（-r{N-1}）时——以报告文件存在为触发事实，不依赖调用方传入 revision 语境——审查范围收窄为：

• 仅审查 git diff 涉及的文件和函数（与上次审查的 commit baseline 比较）。Layer 1 调用无需增量参数——把收窄后的文件/目录作为 review <path> 目标即可；complexity_gate 本就只对 git diff 涉及的函数施门禁
• 上轮报告中无 CRITICAL/HIGH 的维度标注 [previously-approved]，不重复审查
• 上轮报告中 CRITICAL/HIGH 涉及的维度 + diff 新增代码的全维度 → 正常审查
• 上轮报告未闭环的 MEDIUM/LOW 逐条标注 still-open / resolved；still-open 项参与本轮聚类升级计数，并按本轮 finding 参与三态判定（COMMON-RULES §三态判定逻辑）
• report 中每个 [previously-approved] 维度附注上轮 report 编号供追溯

Step 3: 审查报告编号

报告编号按 .cataforge/references/review-report-spec.md §报告编号规则，前缀 CODE-REVIEW-{task_id}，目录 docs/reviews/code/。

Step 4: 产出审查报告

产出 CODE-REVIEW-{task_id}-r{N}.md，首行必须为 YAML front matter，字段按 .cataforge/references/review-report-spec.md §报告 Front Matter 约定（本模式 delta：id: "code-review-{task_id}-r{N}"、deps: ["{task_id}"]）；缺失会导致 cataforge context index 跳过该文件并被 cataforge doctor 计为 orphan。

front matter 之后按 .cataforge/references/review-report-spec.md §问题格式 列出问题，COMMON-RULES §归因分类 / §统一问题分类体系 提供 root_cause / category 枚举。

Step 5: 判定结论

三态判定按 COMMON-RULES §三态判定逻辑。判定后把本审查报告 front matter 的 status 由 draft 改为 approved（无论 verdict 类型）。

操作指令: 项目级健康度扫描 (scan)

适用于：用户提出"扫一下整个 src/"、"看下这个项目代码腐化情况"、定期巡检等不与具体 task_id 绑定的需求。默认按需触发（用户手动 / cataforge doctor --deep 可选附带），不进入 TDD 主循环。

签名: cataforge skill run code-review -- scan <path> [--focus <category[,...]>] [--format text|json] [--verbose]（--format json 输出结构化 finding 供 Layer 2 消费，读 stdout；日志走 stderr。--verbose 展开被截断的 info 尾）

Step 1: Layer 1 — Lint + 腐化指标

执行: cataforge skill run code-review -- scan {path} [--focus duplication,dead-code,complexity]

脚本内部按以下顺序执行:

1. 门禁检查恒跑（lint / wiring / ui-fidelity，同 review 模式；scan 的 --focus 不筛门禁检查）
2. 按 --focus 指定的腐化维度：duplication 由内置行块 floor 保底 + jscpd 增强承载（见 §Layer 1 检查项），test-quality 由内置 test_hygiene 承载（无标签慢测候选 / 每测重建昂贵 setup 候选，pattern 集 test-hygiene-{lang}.yaml），其余维度调对应 informational probe（vulture / ts-prune / radon / gocyclo 等）
3. vendored / 生成文件（*.min.* / *.map / *-lock.json 等，及项目级 .cataforge/skills/code-review/ignore 声明的 glob）不参与 lint 与探针；工具不存在 → WARN 跳过，不 FAIL

返回码语义按 §Layer 1 调用协议；scan 默认不因腐化 finding 而 FAIL（仅 lint error 时 FAIL），rot 信号视作 informational，由 Layer 2 做严重度判定。

Step 2: Layer 2 — AI 模式聚合

读取 Step 1 的 finding 列表，按 category 聚合并打严重等级:

• 同一文件的重复块跨阈值 → MEDIUM/HIGH（按重复行数判定）
• vulture 报死码 + 该文件未被任何引用 → HIGH
• 复杂度严重等级委托项目级 complexity.yaml 阈值（complexity_gate finding 已按 warn/fail 标注：超 fail → HIGH，超 warn → MEDIUM），不在此处另设数值
• ts-prune 未引用导出 → LOW（可能是公共 API）
• config 死键（config_dead_key）→ MEDIUM；结合业务判断是否由部署基础设施等外部消费（是则建议声明文件加豁免）
• API 导出移除（api_surface）→ HIGH（潜在破坏性变更）；新增导出 → LOW（面扩张提示）
• 豁免盘点（pragma_inventory）：unknown-pragma 残留 / 缺 reason → MEDIUM；高龄豁免（长期未清理）→ LOW 并列入重构建议
• 测试套件卫生（test_hygiene）：无标签慢测候选 → LOW，单文件密集命中（≥3 处）→ MEDIUM；每测重建昂贵 setup 候选 → MEDIUM（改进方向按 .cataforge/references/test-suite-performance.md）；慢测标记豁免为文件级粒度（文件内任一处命中标记 pattern 即豁免全文件）

Step 3: 产出扫描报告

报告路径: docs/reviews/code/CODE-SCAN-{YYYYMMDD}-r{N}.md（编号规则：当日同前缀已存在 r1 则递增到 r2）。Front matter 字段按 .cataforge/references/review-report-spec.md §报告 Front Matter 约定（本模式 delta：id: "code-scan-{YYYYMMDD}-r{N}"、deps: []）。

问题列表按 .cataforge/references/review-report-spec.md §问题格式；可用 category: structure / duplication / dead-code / complexity / coupling / performance / error-handling / security / consistency / convention / arch。

Step 4: 判定结论

三态判定按 COMMON-RULES §三态判定逻辑。scan 模式默认不阻塞流程（不进 needs_revision 自动重试），仅产出报告供后续重构决策。

Layer 1 检查项

权威清单见 cataforge.runtime.skill.builtins.code_review.CHECKS_MANIFEST（framework-review 自动对账）。每项检查的 id / 严重度 / 适用模式 / 豁免语法以 manifest 条目自述为准，本段不逐条复述。

• linter / formatter 工具适配（review + scan 门禁，按文件类型自动选择）：ESLint + Prettier (.js/.ts/.jsx/.tsx)、Ruff (.py)、dotnet format (.cs)、golangci-lint (.go)、cargo clippy (.rs)；工具未安装时跳过并 WARN，不阻断
• 声明式检查的语义细则按维度分文档承载：wiring 空 handler 见 wiring-checks.md；架构分层守护（arch_guard，项目声明 arch.yaml 方向矩阵即激活）见 arch-checks.md；复杂度门禁与棘轮基线（complexity_gate）见 complexity-checks.md
• duplication 维度（informational）：内置行块 floor（零依赖、语言通用，与 complexity_gate 同构保证维度不静默）保底 + jscpd token 级增强（多语言，出报告时用其精确信号）/ pmd-cpd（Java）
• scan 腐化 probe（informational，按 --focus 选择性执行）：dead-code（vulture / ts-prune / knip / cargo-machete / config 死键 xref）、complexity（radon / gocyclo / eslint，探针阈值统一取项目级 complexity.yaml）、consistency（API 面快照 diff）、convention（豁免盘点）、test-quality（test_hygiene 内置测试套件卫生扫描）；probe 工具缺失 WARN 跳过，scan 不因此 FAIL
• vendored / 生成文件排除（EXCLUDE_FILE_GLOBS：*.min.* / *.map / *-lock.json / *.d.ts 等）+ 项目级 .cataforge/skills/code-review/ignore：lint 遍历与探针 ignore 共享单一源，压缩第三方包不产生假阳性

豁免统一语法 cataforge: allow(<check-id>, reason="...")（reason 必填，缺失时豁免生效但记 WARN；文件级/行级生效范围随消费方）见 pragma-grammar.md。

Plugin-style rules (per-language extension)

Layer 1 的声明式规则全部走 rules YAML（schema v2：schema_version: 2 + rule_type + scope: language|project；scope: language 必填 language/extensions，scope: project 供语言无关的项目级模型且不写这两键；未知顶层键报错，防拼写失效）：

• 默认（cataforge package）：cataforge.runtime.skill.builtins.code_review.rules/*.yaml
• 项目 override（opt-in）：<project>/.cataforge/skills/code-review/rules/*.yaml，整文件替换、改完即生效；framework-review B3-β 自动校验；全注释 YAML 视为未声明（发运模板语义）

rule_type 一览：wiring（空 handler pattern）、arch（项目级 arch.yaml 方向矩阵 + arch-{lang}.yaml import pattern）、complexity（项目级 complexity.yaml 四指标阈值 + complexity-{lang}.yaml 代理度量 pattern）、config_keys（声明 × 消费 pattern）、api_surface（导出面 pattern + 项目级 gating 开关）、test_hygiene（慢测 / 标签 / 昂贵 setup pattern）。

Anti-Patterns

• 禁止: 把 user-facing critical path 任务（页面/路由/UI 可达性、consumer_components 非空）走 Layer 2 短路 —— 形式契约对但 wiring 留白只能由 §integration-wiring 维度抓出，短路会放走 false-positive
• 禁止: 让 reviewer 直接下场写补丁 —— code-review 仅产出审查报告（problem list + 严重等级），任何修改必须由 implementer / debug skill 在独立调度中完成
• 禁止: scan 模式因为腐化 finding 直接判 needs_revision —— scan 默认不阻塞流程；rot 信号转化为重构决策的输入，是 informational 而非 gating
• 禁止: 手写或复制 CHECKS_MANIFEST 条目到本文档 —— manifest 由 register_check() 注册表派生，新增检查在 checks/ 注册即自动进入 manifest 与 framework-review 对账面；散文复述必然漂移
• 禁止: 在 review 路径写 .cataforge/baselines/ —— 基线（复杂度棘轮 / API 面快照）只能由 scan 刷新，review 只读判定；孤立的基线变更会被 framework-review B3-γ 判 FAIL
• 避免: 报告写入 docs/reviews/doc/ 或其它非 docs/reviews/code/ 目录 —— 与 doc-review / framework-review 报告混淆会污染 sprint-review 聚合

效率策略

• Hook去重: 已配置 PostToolUse lint hook 时跳过 Layer 1，避免与编码阶段的实时 lint 重复检查
• Layer 1兜底: 未配置 hook 的项目仍执行 Layer 1 作为质量门禁
• Layer 2聚焦语义: AI审查专注于lint无法覆盖的逻辑/安全/架构问题
• Layer 2 短路: light 模式小任务 / chore / Adaptive Review 反向降级时跳过 Layer 2，由 sprint-review 兜底（见 §Step 2 短路条件）
• scan 模式按需触发: 不在 TDD 主循环内自动执行，避免每次任务评审都跑 jscpd/vulture
• 按严重等级排序问题