tiered-audit

分层审计

适用场景

• 审计代码库的质量、模式或问题
• 合并前审查分支上的变更
• 调查不稳定或频繁变动的区域
• PR 前质量评估

不适用场景

• 审查特定文件（使用 pensive:code-reviewer）
• 仅审查架构（使用 pensive:architecture-review）
• 审查单次提交（使用 imbue:diff-analysis）

第 1 层：Git 历史审计

始终首先运行。 分析 git log、diff 统计和 blame，在不读取任何源文件的情况下识别值得关注的区域。

第 1 层分析内容

针对目标提交范围运行第 1 层脚本（默认为： 当前分支与主干的比较）：

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/tiered_audit.py" --base {base}
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/tiered_audit.py" --base {base} --json

该脚本会运行四条 git 查询（文件变动频率、连续修复提交的主题、 每次提交的 diff 大小、新增文件），应用 pensive.skills.tiered_audit 中的阈值（一个模块中有 3 个或更多文件发生变动，且其中一个文件的变动次数超过 2 次；单次提交中变更 200 行或更多；一个模块中新建 5 个或更多文件），并在每项标记旁打印生成该标记的 [E{n}] Command:，以便 findings 文件逐字引用证据。--json 会添加 escalation_targets 和一个用于第 2 层的 escalate 判定。

验证： 如果你知道某个分支变动频繁，但报告却为空，说明提交范围有误。请先通过 git merge-base {base} HEAD 检查 {base} 能否正确解析，再相信空结果。

第 1 层输出格式

将 findings 写入 .coordination/agents/tier1-audit.findings.md：

---
agent: tier1-audit
tier: 1
evidence_count: {N}
---

## Summary

{1-2 sentence overview of what the git history reveals}

## Churn Hotspots

{top 10 most-changed files with change counts}

For each flagged file, include:
- Location: path/to/file.py:line (most-changed function or block)
- Anchor: `verbatim source text at that line`

[E1] Command: git log --format="" --name-only ...
     Output: {relevant output}

## Fix-on-Fix Patterns

{commits that fix previous commits in the same area}

[E2] Command: git log --oneline ... | grep -iE ...
     Output: {relevant output}

## New File Clusters

{modules with 5+ new files}

## Large Diffs

{commits with 200+ line changes}

## Escalation Recommendation

{list of areas flagged for Tier 2, or "no escalation needed"}

升级判定

第 1 层完成后，根据 modules/escalation-criteria.md 中的升级标准检查 findings。

如果没有满足任何标准：审计完成。报告 findings。

如果满足了标准：列出被标记的区域，并依次对每个区域进行第 2 层审计。

第 2 层：定向区域审计

仅针对第 1 层标记的区域运行。 每次审计一个被标记的区域，不要并行执行。

第 2 层分析内容

针对每个被标记的区域：

1. 阅读该区域中的源文件
2. 检查模式、反模式和 Bug
3. 验证是否存在测试覆盖
4. 检查文档是否为最新
5. 评估架构适配性

第 2 层输出格式

每个区域对应一个 findings 文件： .coordination/agents/tier2-{area-name}.findings.md

每个文件都遵循审计输出契约 （参见 imbue:proof-of-work/modules/output-contracts）。

第 3 层：完整代码库审计

需要用户明确批准。 有关关卡协议，请参阅 modules/escalation-criteria.md。

第 3 层应使用专用会话（每个区域一个）， 通过文件进行协调，而不是使用并行子 Agent。

输出契约

所有层级都使用以下契约：

output_contract:
  required_sections:
    - summary
    - evidence
  min_evidence_count: 3    # Tier 1
  # min_evidence_count: 8  # Tier 2
  expected_artifacts: []
  retry_budget: 1
  strictness: normal

第 2 层将最低证据数量提高到 8，因为 它会读取源文件，因此应提供更深入的分析。

验证： 每层完成后，在进入下一层或报告结果之前，验证 findings 文件是否存在且至少包含规定数量的证据 （[E1]、[E2] 等）。

验证 Findings 是否有依据（tiered-audit:findings-verified）

将 findings 写入 .review/findings.json，运行引用验证器 （Skill(imbue:review-core) 第 5 步），并删除验证器拒绝的 findings，或将其标记为 UNVERIFIED。

退出标准

• 第 1 层 findings 文件存在于 .coordination/agents/tier1-audit.findings.md，且至少包含 3 条证据记录（[E1]–[E3]）。
• 仅在第 1 层升级标准明确标记的区域启动第 2 层。
• 每条报告的 finding 都包含 Location 和逐字引用的 Anchor，并经 citation_verifier.py 确认（退出码为 0）；或者，未验证的 findings 已被删除或标记为 UNVERIFIED。