gitnexus-review

GitNexus 审查

在不编辑源码、不提交、不推送、不发布或不解决讨论线程的前提下，审查所请求的变更范围。后续的明确请求可能会授权这些操作。使用 GitNexus 获取结构性证据，使用源码检查获取实证；两者不可相互替代。

解析目标

接受以下形式：

输入	审查范围
PR URL、owner/repo#42、#42 或纯数字	GitHub PR
base...head	合并基范围
base..head	精确的双点范围
分支、标签或提交	相对于仓库默认分支的 ref
local、staged、unstaged 或工作区相关表述	本地变更
无目标	当前分支的开放 PR；否则为本地变更；否则为当前分支

显式目标始终优先。仅当在 gh 认证可用的 GitHub 仓库中时，才将纯数字解释为 PR；否则请要求提供 ref 或 URL。如果隐式模式同时发现分支提交和本地变更，应将它们作为两个带标签的范围分别审查，而不是静默丢弃或混合其中任何一个。

记录解析出的目标类型、仓库根目录、默认分支、base SHA、head SHA、适用时的合并基，以及包含的本地状态。从远程元数据（refs/remotes/<remote>/HEAD 或 GitHub 仓库元数据）解析默认分支；仅在显式回退时使用 main 或 master，并说明何时这样做。

PR

使用 gh pr view/gh api 固定 PR 编号、仓库、标题、URL、base ref、base SHA、head ref 和 head SHA。在不切换用户分支的情况下获取这些确切的提交。计算 git merge-base <base> <head> 并将该 SHA 用作审查基线：GitHub PR diff 是合并基 diff，而 detect_changes(scope: "compare") 是双点比较。

使用本地 git diff <merge-base> <head> 作为完整 diff 的真相来源；使用 GitHub 元数据获取 PR 事实和审查状态。对于 fork PR，请获取 pull ref 或贡献者远程，而不是假设 head 分支存在于 origin 上。

分支、ref 或范围

在审查前将每个 ref 解析为提交。对于分支或 A...B，使用合并基作为比较基线。对于显式的 A..B，将 A 视为精确基线。当意图是合并基语义时，不要将特性分支直接与移动的默认分支顶端进行比较。

本地变更

检查 git status --short、已暂存的 diff、未暂存的 diff，以及每个未跟踪的文件。根据请求使用 detect_changes 并传入 staged、unstaged 或 all。未跟踪的文件不保证出现在 Git diff 或图映射中，因此请直接读取它们，并在审查溯源中列出它们。

对齐检出与索引

图谱与 diff 必须描述同一个 head。仅当现有 worktree 恰好位于目标 SHA 时，才复用它。否则为 PR/ref head 创建一个临时分离 worktree，在那里审查，之后只移除该临时 worktree。绝不切换或重置用户当前的 worktree。

在目标 worktree 中检查 GitNexus 状态。如果已过期，在信任图谱结果之前运行 node .gitnexus/run.cjs analyze --index-only（临时 worktree 从不携带被 gitignore 的 run.cjs —— 回退到已安装的 gitnexus CLI，然后 npx gitnexus），并且当 diff 有可能触及信任或数据流边界时，在同一次刷新中加上 --pdg，这样下面的污点分析就不必再付出第二次完整 analyze 的代价。污点与依赖证据需要那一层 PDG：当工作流的污点分析发现它缺失时，用 analyze --pdg --index-only 重建，并在 provenance 中记录此次重建。对于本地更改，刷新索引，使新增或修改的源码被纳入。 如果无法建立精确的目标检出/索引，说明该限制，并且不要声称完成了完整的图谱支撑审查。

审查工作流

1. 阅读完整差异和变更文件列表。区分生成文件、依赖项变动、测试和行为变更。
2. 针对确切范围运行 detect_changes：
   • PR/分支/...：scope: "compare"，base_ref: <merge-base SHA>。
   • 显式的 A..B：scope: "compare"，在位于 B 的工作树中使用 base_ref: <A SHA>。
   • 本地：scope: "staged"、"unstaged" 或 "all"。 如果 MCP 服务连接在其他位置，请传入 worktree。
3. 对每个行为发生变化的符号运行上游 impact，并设置 includeTests: true。优先检查公共契约、共享类型、控制流、持久化、安全边界和错误处理；跳过机械性或生成内容的变更。
4. 检查所有不在差异中的直接（d=1）依赖项。不在差异中的依赖项只是线索，并不自动意味着存在漏洞——请在源代码中核实变更后的契约和调用方行为。
5. 对关键或含义不明确的符号使用 context，并检查受影响的执行流。阅读引用位置周围的实现和测试。
6. 污点与依赖关系检查。 对信任或数据流边界上的变更代码——外部输入、持久化、进程执行、网络、身份验证——对变更的文件或符号运行 explain，并结合差异判断其源→汇污点分析结果：由变更引入的数据流，或由变更移除的净化器/防护措施，才算发现；已有的数据流只是背景信息，不属于此次变更的缺陷。如果变更声称会防护或净化某些内容，请使用 pdg_query 验证：是什么控制了变更的语句，其值又流向何处。这需要 --pdg 索引；如果无法构建，请说明跳过了污点检查，不要暗示已完成覆盖。
7. 检查测试是否覆盖了变更行为、边界条件和受影响的数据流。在可行时运行只读的定向验证。如果差异更新了已提交的基线、指纹或黄金文件，请针对最新提交重新运行确切的 CI 检查命令，而不要盲目信任已提交的值——过期的构件在差异中不可见，只会在 CI 中失败。
8. 将图分析证据与原始差异核对。新增文件、动态分派、配置、反射和未跟踪内容可能需要直接审查，即使图分析结果为空。版本和失效常量也属于审查范围：当差异改变了发出或持久化的内容时，请确认所有控制缓存、增量写回和指纹基线的架构/版本常量都已递增或重新生成——例如，在 GitNexus 中，图 DDL 无需手动递增版本，因为 SCHEMA_FINGERPRINT（gitnexus/src/core/lbug/schema.ts）由 NODE_SCHEMA_QUERIES + REL_SCHEMA_QUERIES 派生，会自行变化；需要检查的是差异是否更改了这些数组中的字符串，以及是否将新增的 DDL 数组纳入指纹计算。解析器兼容性也会自动处理：请审查 gitnexus/src/core/parse-cache-identity.ts 中的 base/PDG 归属边界、导入/资源覆盖审计，以及真实的冷启动 → 热启动回放测试。超出这些边界的新解析器依赖需要明确覆盖；贡献者无需分配语义计数器。重新建立基线前，仍需审慎审查两组基准指纹：自动失效机制无法保证语义正确性。其他未改动 DDL 的语义变更，则依赖索引元数据中的分析器运行器身份回执。

专家视角

深度来自让审查者与实际变更相匹配，而不是来自一次通才式的审阅。在工作流第 2 步之后，按图已经知道的职能领域对变更的文件和符号进行分组——即索引的聚类列表；context 会给出每个符号所属的聚类——并为每个被触及的领域分配一个专家视角：一位负责该领域契约、不变量和失败模式的审查者，在评判 diff 之前先以仓库自身的材料（架构文档、agent 规则、该领域的测试）为依据。视角是去验证，而不只是阅读：当变更的代码是从仓库自身工具链可达的纯函数——解析器、提取器、捕获发射器、格式化器——就在候选的失败形态上执行它（一个临时探针，事后删除），并引用观察到的输出。在证据层级中，经验性探针优先于源码阅读；角色互换、死分支和依赖错误恢复的行为会反复通过阅读检查，却在十行探针下失败。编号工作流只运行一次；在第 6 步之后派发各视角的审阅，把已经收集到的证据交给每个视角，而不是让各视角重复执行 impact、context 或 taint 调用。例如在 GitNexus 本身中：共享摄取流水线的变更得到一位摄取专家，外加每种变更语言提取器各一位语言专家；嵌入变更得到一位嵌入专家；LadybugDB/存储变更得到一位 Ladybug 专家。

有四个跨领域视角无论领域如何都会运行：

• 架构契合度——变更落在架构所规定该关注点所在的位置，复用现有的接缝，并且不添加平行结构。
• 语言合规性——按仓库自身配置的类型/lint/测试契约（tsconfig 严格性、lint 规则、测试约定）；例如在一个严格 TypeScript 仓库中：严格性完好，没有 any/as any 逃逸，模块边界有类型标注。按仓库的契约评判，绝不用通用的风格标尺。
• 完成的定义——变更的行为有测试，因变更而过时的文档得到更新，并且同步/漂移防护（随附副本、清单、变更日志）仍然成立。
• 简洁性——YAGNI 与清晰代码检查：标记投机性抽象、未使用的开关和过度工程；符合完成的定义的最小 diff 才是标准。

让投入与涉及面相称：涉及少量文件的单领域变更只需一次合并的审阅，覆盖其领域视角加上四项跨领域检查；多领域变更则为每个被触及的领域分配一个视角——在 harness 支持时作为并行子 agent 运行，每个都限定在自己的文件加上共享的图证据范围内，否则作为顺序审阅运行。绝不要为 diff 未触及的领域生成视角。合并基于相同材料的视角——两个视角阅读相同文件会为一次阅读的覆盖范围付双倍代价，所以把两项职责交给同一位审查者。在 harness 提供模型或投入层级时，把机械性视角（重命名清扫、文档一致性检查）放在更便宜的层级上运行，并把最强的引擎留给对抗性判断。每个视角都通过下面的 Finding 标准报告；在给出裁决之前进行合并与去重，丢弃任何没有具体失败场景的内容。

Swarm 通道

本技能在 ci-personas/ 中内置了六条可调度的通道定义 —— 只读审查员，仅限文件读取以及安全的图工具。其中五条是查找类通道：ci-correctness-lens、ci-security-lens、ci-blast-radius-lens、ci-coverage-lens 和 ci-adversarial-lens（后者假定改动是坏的，并构造出模式检查遗漏的可达失败场景）。它们将编号工作流的验证维度覆盖到每一个被触及的领域；领域分组以及上述四项横切检查仍由编排器负责。第六条 ci-critic-lens 是门禁而非查找器 —— 它审计已完成的草稿。

当 harness 支持子 Agent 且这些通道已注册为 Agent 时（CI 审查工作流会从其受信控制检出中安装它们；本地 harness 可通过将 ci-personas/*.md 复制到 ~/.claude/agents/ 或项目的 .claude/agents/ 来注册它们），按如下方式运行专家视角环节。首先建立你自己的图证据 —— 在调度任何通道之前，自己至少对某个已变更符号发起一次实质性上下文调用，因为通道调用永远无法满足本技能或其运行器所要求的证据。然后在单条消息中并行调度全部五条查找类通道。向每条通道提供 diff、变更文件清单、确切的 base 和 head 标识符、检出路径，以及与其职责匹配的那部分变更文件。

将每一份通道报告都视为未经证实的声明：在每条发现进入审查之前，将其重新锚定到 diff、源码或你自己的图查询上；跨通道去重；丢弃任何没有具体失败场景的发现。通道的工具调用永远不能替代本技能或其运行器要求编排会话本身提供的证据。

在撰写完整草稿审查后，将完整草稿正文连同相同的上下文调度给 ci-critic-lens。若返回 DEFECTS，修复草稿并重新调度 critic 一次；若第二轮后仍有缺陷，修复你认可的部分，在覆盖率章节中记录未解决的 critic 异议，然后继续 —— critic 会强化审查；它从不阻塞审查。这种故障开放是有意为之：critic 被限制为两轮，因此它无法使运行死锁或卡住，而审查仍受运行器自身的证据和 schema 检查约束。（这与单独的 gitnexus-pr-swarm-review 技能不同，后者的交互式名单将其 critic 视为必须在输出前通过的硬门禁；而本 CI 通道必须始终输出审查或一次干净的失败。）若子 Agent 调度不可用或任一通道失败，则以内联方式运行该通道的职责 —— 通道只是组织工作；它们从不设置门禁。

发现标准

仅当被审查的改动引入了具体缺陷、回归、安全问题、兼容性破坏、实质性覆盖缺口，或具有具体承载场景的可维护性成本（死旋钮、重复契约、易漂移的副本）时，才报告发现。每条发现必须包含：

• 严重级别以及精确的 path:line 锚点；
• 失败场景或契约；
• 适用时的 GitNexus 证据（依赖符号/流程）；
• 为什么现有代码或测试无法缓解它；
• 简明的修复方案或缺失的测试。

不要将风格偏好、既有问题、原始风险计数或推测报告为缺陷。不要因零图命中就推断为安全。根据后果、可达性、可逆性和测试证据来校准整体风险，而不是仅凭变更符号的数量。

输出

以严重级别顺序列出发现。若没有发现，则明确说明。然后提供：

## Review: <target>

### Findings

- [HIGH|MEDIUM|LOW] `path:line` — <problem, evidence, impact, remediation>

### Change and blast-radius summary

- Target/base/head/merge-base and local states reviewed
- Changed symbols and affected execution flows

### Coverage and residual risk

- Tests present, tests missing, graph/diff limitations

### Verdict

APPROVE | REQUEST CHANGES | NEEDS DISCUSSION

对于分支或本地审查，使用 READY、NOT READY 或 NEEDS DISCUSSION 代替 PR 批准动作。包含确切的目标 SHA，以便后续运行能判断证据是否已过期。