pre-pr-greptile

PR 前 Greptile 审查

PR 前的审查关卡。Greptile 会在自己的云端审查已提交分支的差异（约消耗 0 个 Claude 令牌，每次审查约 $1，月度免费额度用完后），此技能会对结果进行分流并推进 PR。这是一个关卡，不是盲目自动化：审查输出会经过验证，有风险的发现会先提交建议，而不会自动应用。

它复刻了 Greptile 官方的 cli-review 技能（优先使用 whoami → --json，回退到 --agent，并按严重程度排列发现），并将其 greploop 持续迭代直至干净的理念适配到本地 CLI（greploop 本身通过 gh 驱动 PR 机器人，而非本地审查）。

前置条件

• 预检（复刻 Greptile 官方的 cli-review）： git rev-parse --show-toplevel （确认你在仓库中）→ command -v greptile（确认 CLI 已就绪）→ greptile whoami （验证身份）。Greptile 没有 --fix/apply 命令——它只会生成发现；由 Agent 应用修复（与官方的 greploop 技能完全相同，该技能会自行编辑文件）。
• 身份验证（不要在 Agent/包装式 shell 中运行 greptile login）。 使用非交互式 greptile whoami 进行检查。如果未通过身份验证，则停止并告知用户在原生终端中运行 greptile login（在包装式/非交互式 shell 中，浏览器 OAuth 回调不可靠，会因 redirect_uri 格式错误而失败）。无头环境下的备用方案：export GREPTILE_API_KEY=… 或 echo "$GREPTILE_API_KEY" | greptile login --api-key（切勿将密钥作为 CLI 参数传递——它会留在 shell 历史记录/进程列表中）。
• 已安装 greptile（command -v greptile）。如果缺失、不可用或触发速率限制 → 停止 并告知用户；绝不等待，也绝不静默创建 PR（参见 Fail-open）。

流程

1. 确保当前位于功能分支，且工作已提交。 如果当前位于主干／基础分支 （testing、main、develop），请先创建 feature|bugfix|hotfix/<ticket>-slug。 Greptile 会审查分支与其基础分支之间的差异，因此必须先提交工作。确保每次提交都使用 SSH 签名（绝不使用 --no-gpg-sign，绝不使用 --no-verify）。
2. 明确解析基础分支，绝不假设是 main。 在此组织中，PR 的目标分支是 testing（主干）；请按仓库确认。greptile review 默认使用仓库的默认分支，该分支可能不正确——传入 -b <base>，以匹配预期的 PR 基础分支。
3. 运行审查： greptile review -b <base> --json（首选；使用 jq 'keys' 检查结构， JSON 架构尚未记录，切勿硬编码字段名）。 如果 JSON 失败，则回退到 greptile review -b <base> --agent（纯文本）。
4. 在信任任何审查发现之前，务必确认审查对应的是当前分支。 将审查中提及的文件与 git diff <base>...HEAD --name-only（三点语法 = merge-base，即 PR 差异）进行比较。 审查提及的文件必须是分支差异中文件的子集。如果两者没有重叠，或者审查在约 10 秒内返回（命中缓存），则这是过期／来自其他仓库的审查——丢弃它，再重新运行一次；如果仍不匹配，则停止并报告。绝不要应用未经验证的审查意见。（设置此保护措施，是因为曾观察到首次调用 greptile review 时返回了来自完全不同仓库的缓存审查结果。）
5. 对发现进行分类（仅限已验证的审查）： 按严重程度排序。对每项发现分级：
   • 机械性／低风险（未使用的导入、拼写错误、缺少 null 检查、文档／测试缺口）： 可直接安全修复。
   • 高风险（身份验证、加密、注入、数据丢失、并发，或任何逻辑／行为变更）： 不要自动应用——先提出差异，并获得用户明确批准。
   • 误报／与预期冲突： 不要应用；记录理由（用于 PR 正文／稍后的讨论串回复）。切勿为了消除小问题而削弱正确性或安全性。
6. 应用修复时，注意 SDD gate。 编辑生产源代码（.py/.ts/.vue/…）会触发全局 sdd_gate PreToolUse 钩子；如果仓库是 OpenSpec 项目且没有进行中的变更，该钩子会阻止操作——这在 PR 阶段是常见状态（所有任务均为 - [x]）。如果生产源代码修复被阻止：请报告情况，由用户决定（保留未完成任务、重新打开变更，或手动应用）。不要自动设置 SDD_HOOKS_DISABLED=1——这会破坏用户优先编写规范的纪律。docs/、测试、.claude/ 和 openspec/ 下的修复不受限制，可直接应用。
7. 重新提交修复（使用签名；优先采用 --fixup + 自动压缩，或创建一个小型的专注提交，以保持 PR 历史整洁），然后重新运行一次全新的 greptile review，并重新执行第 4 步的差异匹配。--resume 仅用于继续因崩溃／中断而未完成的审查——它不会重新审查新提交，因此应用修复后绝不要使用它。
8. 循环直至收敛，最多进行 3 次审查。 如果只剩小问题／误报，或某项发现再次出现（说明修复未能解决问题，需要人工判断），则提前停止。统计计费审查次数（初次审查 + 每次重新运行 + 任何过期审查的重跑）——免费额度用尽后，每次约需 1 美元，因此不要无故重跑。如果 3 次后仍未通过，则停止，不要创建 PR，并报告剩余发现。
9. 确认 gh 账号正确，然后推送并创建 PR。 运行 gh auth status；如果账号发生变化，运行 gh auth switch --user <correct-account>（账号错误会导致推送／gh pr create 返回 404 “Repository not found”）。使用签名通过 git push 推送分支，然后运行 gh pr create --base <base>——不得添加 Claude/Anthropic 联合作者署名，不得添加 “Generated with Claude Code” 页脚，绝不要使用 --no-verify。绝不要将基础分支合并到功能分支。

“干净”的定义

没有任何你认可的未解决发现项。小问题、建议和已记录的误报都不会阻止通过。保存跳过发现项的理由，避免循环反复争论同一个误报，并让门禁可以在记录豁免项后通过。

失败时开放／安全

门禁既不能死锁，也不能悄悄绕过。如果 greptile 缺失、未通过身份验证（在当前 shell 中）、出错或受到速率限制：停止并将决定交给用户——绝不挂起，也绝不悄悄打开 PR。如果用户明确要求跳过审查，请照做，并在 PR 正文中注明已跳过 greptile 预检。

防护措施

• 绝不对未通过差异匹配检查（步骤 4）的审查采取行动。不到 10 秒就返回的结果＝可疑。
• 绝不自动应用涉及安全性／行为变更的发现项——应先提请批准。
• 绝不绕过 SDD 门禁或提交签名来推动循环继续。
• 修复应保持精简且切题；不要为了满足无关的小问题而扩大分支范围。
• 可选的 PR 后续摘要评论不得公开暴露你选择不修复的安全问题相关推理——仅说明已解决的事项，或删去敏感细节。
• 每次自动修复编辑都会触发此环境中配置的 PostToolUse 钩子和 Stop test_gate——请为此预留时间，并将这些测试纳入“干净”的判定标准。

命令

greptile whoami                      # auth check (never `greptile login` from a wrapped shell)
greptile review -b testing --json    # primary: machine-readable, explicit base
greptile review -b testing --agent   # fallback: plain text for agents
git diff testing...HEAD --name-only  # the diff the review MUST match (step 4)
greptile review show <id>            # reopen a past review
gh auth switch --user <account>      # fix account drift before push / gh pr create