diff --git a/AGENTS.md b/AGENTS.md index cce80b0..b2a76ab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,17 @@ ## Code Review Rules -- 优先识别会造成错误放行、错误阻断、权限扩大、secret 暴露、供应链漂移或发布/回滚证据失真的具体问题,并核对新增公共 MUST 是否确实跨项目通用。 -- 审计器变更必须同时具有能复现旧缺口的失败 fixture 和保持合法项目通过的正例;只增加字符串匹配而不能证明约束时应指出误报或漏报路径。 -- 修改 Action 或公共规则时,核对模板、审计器已知映射、契约和 fixture 是否同步;不重复报告 lint、格式化或纯风格问题,不要求与当前风险无关的重构。官方 Review 当前不是 required check,且 GitHub 对有写权限者推送新提交不保证自动关闭 Auto-merge;v1 暂不允许对单个 PR 开启 Auto-merge,只在 Review 当前 HEAD、全部 review thread 已解决后人工合并。 +### 阻塞边界 + +- 只提交 P0/P1 finding:问题必须由当前 PR 引入、存在当前可达的触发路径,并会造成明确的正确性、安全、权限、数据、兼容性或发布后果;评论必须说明触发条件、实际影响和最小安全路径,证据不足则不报告。 +- P2/P3、纯防御性加固、需要未来维护者同时修改规则与测试才成立的假设、测试还可增加更多 fixture、lint/格式/措辞/命名或无当前影响的重构默认不报告,也不得仅因建议有价值就阻塞合并。 + +### 本仓重点 + +- 重点检查会造成审计错误放行或错误阻断、权限扩大、secret 暴露、供应链漂移、发布/回滚证据失真,或把单项目细节误升格为公共 MUST 的改动;机械一致性继续交给确定性 CI。 + +### Few-shot + +正例:缺少 `dev` Environment 时审计仍返回 `PASS`,使发布 secret 绕过审批;这是当前可达的权限后果,应提交 P1。 + +反例:还可以增加嵌套列表、另一种措辞或更多 fixture,让测试覆盖更全面;这属于 P2/P3 加固,不提交 finding。 diff --git a/MAINTENANCE.md b/MAINTENANCE.md index 157d5a7..d725e49 100644 --- a/MAINTENANCE.md +++ b/MAINTENANCE.md @@ -23,7 +23,7 @@ ## 新项目接入 1. 在独立 worktree 中复制 `templates/AGENTS.md`,替换占位符并补齐项目内部规则;项目规则不得降低公共 MUST,根文件必须保留精确 `## Code Review Rules` 标题。 -2. 在官方 GitHub/Codex 设置中启用 Code Review 与 `Automatic reviews`,并用真实 PR 验证自动审查;未触发或需要重审时使用 `@codex review`。 +2. 在官方 GitHub/Codex 设置中启用 Code Review 与 `Automatic reviews`,并用真实 PR 验证自动审查;未触发时先排查设置和事件,确认没有结果或在途信号后才使用 `@codex review`。 3. 保持 Auto-merge 关闭;官方 Review 尚非 required check 时不得为单个 PR 开启 Auto-merge。只有仓库仅使用临时 PR head 分支,或所有长期 head 分支受保护时,才启用合并后自动删除远端分支。 4. 复制并按项目实际情况改造 `templates/` 下的 PR、release workflow、`release-safety.yml` 与 `release-safety-contract.sh`;把后两者分别安装为 `.github/release-safety.yml` 与 `.github/scripts/release-safety-contract.sh`,保持 wrapper 的 Git mode 为 `100755`,并映射项目真实 job/step 拓扑。 5. 通过真实 PR 证明 `PR container validation` 成功,随后原子迁移 master required check。 @@ -54,16 +54,22 @@ prepare 存在时,publish、migration 与 deploy 必须使用 `needs. ## 官方 Codex Code Review 维护 - 只采用官方 Codex Code Review,不自建 Reviewer、GitHub Action、Bot、Webhook 服务、模型调用或平行评论协议。 -- 自动触发依赖官方 `Automatic reviews`;`AGENTS.md` 只定义审查规则,不能代替设置。自动审查未出现或需要重审时使用 `@codex review`。 -- v1 保持观察模式,不把官方 Review 增加为 required check,不修改现有 branch protection,也不要求官方输出自定义批准口令或严重级别。 -- 官方设置和审查行为通过真实 PR 验收;中央审计只检查根 `AGENTS.md` 是普通文件,且固定 `markdown-it-py==3.0.0` CommonMark parser 产生源码行精确等于 `## Code Review Rules` 的真实 h2。不得恢复手写 Markdown 状态机,也不抓取页面或调用私有接口。 +- 自动触发依赖官方 `Automatic reviews`;`AGENTS.md` 只定义审查规则,不能代替设置。自动审查未出现时先按官方说明排查仓库开关、Codex cloud 和触发事件,确认没有结果或在途信号后才使用 `@codex review`。 +- 非平凡 PR 先保持 Draft,完成实现、测试、内部交叉审查和范围冻结后再进入官方 Review;多个独立架构边界必须拆分,跨仓变更先冻结共享协议,最终集成 PR 才使用 `Closes #xx`。 +- `## Code Review Rules` 保持两到三条简洁、项目特有的高后果规则,并提供安全路径或正反 few-shot;机械一致性、lint 和格式交给确定性 CI。 +- 只提交 P0/P1 finding:必须证明问题由当前 PR 引入、存在当前可达路径并造成明确正确性、安全、权限、数据、兼容性或发布后果。若产品仍输出 P2/P3,则默认不阻塞;只有维护者给出可复现证据并明确升级后才按阻塞项处理。 +- 等一轮 findings 返回后统一分类。阻塞项按根因批量修复;非阻塞项回复处置依据后解决 thread,不修改代码、不自动建 Issue,也无需重新 Review。 +- 只有阻塞修复显著改变原风险面时才做一次定向 Review;定向 Review 再出现非阻塞建议时直接记录处置并停止,再出现新的阻塞 P0/P1 时先拆分、收窄或重新设计 PR。 +- 官方 Reviewer 给出未发现重大问题的文字结论,或全部 finding 完成阻塞分类与处置,即视为闭环;不追求 emoji、reaction、固定口令或零评论。 +- v1 保持建议模式,不把官方 Review 增加为 required check,不修改现有 branch protection;required checks 仍是确定性门禁。 +- 官方设置和审查行为通过真实 PR 验收;中央审计只检查根 `AGENTS.md` 是普通文件,且固定 `markdown-it-py==3.0.0` CommonMark parser 产生源码行精确等于 `## Code Review Rules` 的真实 h2。不得恢复手写 Markdown 状态机,也不抓取页面、调用私有接口或伪称验证同一 HEAD 请求次数、在途 Review 和审查预算。 - 官方功能演进时先更新接入说明和精简规则;若官方补齐缺口,优先删除临时流程,不维护平行实现。 ## Auto-merge 维护 - GitHub 只保证无写权限者推送新提交时关闭 Auto-merge;有写权限者推送后不保证自动关闭。官方 Review 当前不是 required check,因此 v1 暂不允许仓库或单个 PR 开启 Auto-merge。 - 不建立 HEAD 监听器、自动合并 Bot、Action 或定时任务来补这个能力缺口;未来等官方 Review 可成为当前 HEAD required gate,或 GitHub 保证任意新提交都会撤销 Auto-merge 后再评估。 -- 人工合并前确认官方 Review 当前 HEAD、全部 review thread 已解决、required checks 成功且风险已分类;新提交必须重新 Review。 +- 人工合并前确认 required checks 成功、阻塞 finding 已修复或有明确风险接受、全部 review thread 已完成处置且依赖与发布风险已分类;非阻塞项不要求修改代码或重复审查。 - Dependabot PR 不能只凭 CI 绿灯自动合并;运行时依赖、跨大版本和会触发生产发布的仓库必须另做兼容性与发布授权判断。 - 分支自动删除不是公共强制项。只有仓库仅使用临时 PR head 分支,或所有长期 head 分支受保护时,才启用 GitHub 的合并后自动删除;存在未保护且需要复用的长期 head 分支时必须关闭。 - 本地 worktree/分支只在已合并、干净、没有独有提交且相关发布验收完成后删除。 diff --git a/README.md b/README.md index ede14f0..9324391 100644 --- a/README.md +++ b/README.md @@ -24,15 +24,21 @@ ## 官方 Codex Code Review -基线只接入和治理官方 Codex Code Review,不自建 Reviewer、GitHub Action、Bot、Webhook 服务、模型调用或评论协议。自动唤醒使用官方 `Automatic reviews`;没有自动触发或需要重审时,在 PR 评论使用 `@codex review`。 +基线只接入和治理官方 Codex Code Review,不自建 Reviewer、GitHub Action、Bot、Webhook 服务、模型调用或评论协议。自动唤醒使用官方 `Automatic reviews`;未触发时先按官方说明排查设置和事件,确认没有结果或在途信号后才使用 `@codex review` 人工兜底。 -根 `AGENTS.md` 的 `## Code Review Rules` 只告诉官方 Reviewer 应优先检查哪些项目风险,不能开启 Automatic reviews,也不能证明自动审查已经触发。v1 保持观察模式,不增加 required check,不改变现有 branch protection;官方设置通过真实 PR 验收,中央审计只验证仓库内可稳定读取的规则文件。完整边界见 [官方治理契约](contracts/codex-code-review.md)。 +根 `AGENTS.md` 的 `## Code Review Rules` 只告诉官方 Reviewer 应检查哪些高后果项目风险,不能开启 Automatic reviews,也不能证明自动审查已经触发。按照[官方建议](https://learn.chatgpt.com/docs/third-party/github#customize-what-codex-reviews),规则保持两到三条简洁约束,提供安全路径与正反 few-shot,把 lint、格式和机械一致性留给 CI。v1 保持建议模式,不增加 required check,不改变现有 branch protection;完整边界见[官方治理契约](contracts/codex-code-review.md)。 + +阻塞边界以影响证据为准:只提交由当前 PR 引入、存在当前可达路径并会造成明确正确性、安全、权限、数据、兼容性或发布后果的 P0/P1。若产品仍输出 P2/P3,则默认不阻塞;测试还能增加 fixture、理论加固、未来同时修改规则与测试、lint/措辞/命名或纯重构无需修改,也无需重新 Review。 + +非平凡 PR 在 Draft 阶段完成实现、测试、内部交叉审查与范围冻结,再让官方 Review 检查稳定变更。一轮 findings 返回后统一分类:阻塞项按根因批量修复;非阻塞项回复处置依据后解决 thread,不修改代码、不自动建 Issue,也不触发新 Review。只有阻塞修复显著改变原风险面时才进行一次定向 Review;若再次出现新的阻塞 P0/P1,先拆分或收窄 PR,而不是自动循环。 + +官方 Reviewer 给出未发现重大问题的明确文字结论,或全部 finding 已完成阻塞分类与处置,即视为闭环;不追求 emoji、reaction、固定批准口令或零评论。包含多个独立架构边界的大型需求应拆成阶段 PR,跨仓变更先冻结共享协议,只有最终集成 PR 使用 `Closes #xx`。 ## Auto-merge 与分支清理 GitHub 只保证无写权限者推送新提交时关闭 Auto-merge;有写权限者推送后不保证自动关闭。由于官方 Review 当前不是 required check,纳管产品仓库在 v1 暂不允许开启 Auto-merge,也不为单个 PR 启用它。 -人工合并前必须确认官方 Review 当前 HEAD、全部 review thread 已解决且 required checks 成功;新提交必须重新 Review。Dependabot PR 不会自动合并;尤其是运行时依赖、跨大版本升级、构建行为变化,以及合并即触发生产发布的仓库,仍需兼容性判断和明确发布授权。 +人工合并前必须确认 required checks 成功、阻塞 finding 已修复或有明确风险接受、全部 review thread 已完成处置,且依赖或发布风险已分类;非阻塞项不要求代码修改或重复审查。Dependabot PR 不会自动合并;尤其是运行时依赖、跨大版本升级、构建行为变化,以及合并即触发生产发布的仓库,仍需兼容性判断和明确发布授权。 分支自动删除不是公共强制项。只有仓库仅使用临时 PR head 分支,或所有长期 head 分支受保护时,才启用 GitHub 的合并后自动删除;存在未保护且需要复用的 `dev`、`release` 等长期 head 分支时必须关闭。本地 worktree 和分支始终只在确认已合并、工作区干净且没有独有提交后清理。 @@ -75,7 +81,7 @@ GitHub 只保证无写权限者推送新提交时关闭 Auto-merge;有写权 - `master` branch protection 和 required check。 - 纳管产品仓库关闭 Auto-merge;分支自动删除按项目真实分支模型配置,不由公共审计强制。人工合并前的 Review/thread/风险分类仍由真实 PR 验收。 -中央审计明确不解释任意 shell 的控制流,也不尝试从注释、`echo`、here-doc、字符串或脚本名证明 ref/内容 ID 比对、容器内 smoke、回滚命令及实际 `DEPLOY_TARGET_SHA`。它也不抓取官方页面或私有接口来判断 Automatic reviews 设置和模型审查质量;这些事实分别由项目可执行契约测试、真实发布验收和真实 PR Review 负责。模板只是一种可复制 profile,`.github/release-safety.yml` 才是每个项目拓扑的声明式适配层。 +中央审计明确不解释任意 shell 的控制流,也不尝试从注释、`echo`、here-doc、字符串或脚本名证明 ref/内容 ID 比对、容器内 smoke、回滚命令及实际 `DEPLOY_TARGET_SHA`。它也不抓取官方页面或私有接口来判断 Automatic reviews 设置、模型审查质量、同一 HEAD 请求次数、在途 Review 或审查轮次预算;这些事实分别由项目可执行契约测试、真实发布验收和真实 PR 时间线负责。模板只是一种可复制 profile,`.github/release-safety.yml` 才是每个项目拓扑的声明式适配层。 本地 fixture 自测: diff --git a/contracts/codex-code-review.md b/contracts/codex-code-review.md index e7c63ea..3cf6642 100644 --- a/contracts/codex-code-review.md +++ b/contracts/codex-code-review.md @@ -11,39 +11,66 @@ ## 2. 触发与规则分离 - MUST:在官方 GitHub/Codex 设置中启用 Code Review 与 `Automatic reviews`,由官方集成自动触发新 PR 审查。 -- MUST:自动审查未触发或需要重新审查时,使用官方评论命令 `@codex review` 作为人工兜底。 +- MUST:Automatic Review 未出现时,先按官方排障说明检查仓库开关、Codex cloud 配置、触发事件与 PR 时间线;确认没有结果或在途信号后,才使用官方评论命令 `@codex review` 人工兜底,不用空提交制造触发。 +- MUST:同一 HEAD 不得并发或重复请求;Review 正在运行,或已经产生有效结果时,不得再次触发,也不得为了 emoji、reaction、批准口令或重复确认追加请求。 - MUST:每个仓库根目录维护普通文件 `AGENTS.md`,并包含独占一行的精确标题 `## Code Review Rules`。 -- MUST:`AGENTS.md` 只声明官方 Reviewer 的审查重点,不能被描述为 Automatic reviews 的开启方式或触发证据。 +- MUST:`AGENTS.md` 只声明官方 Reviewer 的高后果审查重点,不能被描述为 Automatic reviews 的开启方式、触发证据或 required check。 - 项目扩展点:项目可以在根规则或更近目录的 `AGENTS.md` 中补充架构、协议、数据和真实验收约束,但不得降低根级公共审查原则。 ## 3. 审查内容 -- MUST:规则优先要求寻找有可触发场景和实际影响的问题,包括但不限于正确性、性能、回归、安全、隐私、权限、可维护性、数据/API 兼容、跨仓协议与 CI/CD 基线风险。 -- MUST:PR 描述、实现者解释和已有测试都视为待验证声明;审查应对照改动、相关调用方和测试证据独立判断。 -- MUST:避免重复 lint、格式化和类型检查已能稳定发现的问题,避免纯风格偏好、无实际影响的猜测和与当前风险无关的大范围重构建议。 -- MUST:不要求官方 Reviewer 使用自定义严重级别、批准口令或评论格式,以免把基线绑定到官方当前输出实现。 +- MUST:遵循[官方 Code Review 定位](https://learn.chatgpt.com/docs/third-party/github):标准 GitHub Review 只提交高优先级 P0/P1;规则只保留两到三条简洁、项目特有且结果导向的约束,并给出安全路径或正反 few-shot。 +- MUST:finding 只有同时满足以下条件才是阻塞项:由当前 PR 引入、存在当前可达的触发路径、违反明确验收标准,并会造成具体的正确性、安全、权限、数据、兼容性或发布后果;标签本身不能替代影响证据。 +- MUST:P0/P1 在满足上述证据时默认阻塞。若产品仍输出 P2/P3,则默认不阻塞也不要求修改;只有维护者给出可复现证据并明确升级后,才进入当前 PR 的阻塞集合。 +- MUST:纯防御性加固、需要未来维护者同时修改规则与测试才成立的假设、测试还可增加更多 fixture、lint/格式/措辞/命名、纯重构或没有当前影响的建议默认不报告;出现时记录“不阻塞”的处置依据即可,无需重新 Review。 +- MUST:PR 描述、实现者解释和已有测试都视为待验证声明;审查应对照改动、相关调用方和测试证据独立判断,但机械一致性继续由确定性 CI 负责。 - 项目扩展点:各项目补充高风险模块、跨仓消费者、迁移兼容、前端状态协议和真实用户路径。 -## 4. v1 合并边界 +## 4. Finding 处置与收敛 + +本节用于防止 review churn:官方 Review 是高信号风险探测器,不是穷举式调试器,也不是独立于 CI 和维护者判断的平行状态机。 + +“稳定变更”指当前范围已冻结、没有已知待提交代码、项目测试已通过,且跨仓共享协议已经对齐;只有该状态才进入官方 Review。 + +### 4.1 Draft 与范围冻结 + +- MUST:非平凡 PR 先保持 Draft,在实现、项目测试、CI 契约和内部交叉审查完成后冻结范围,再进入官方 Review;不得把官方 Review 当作逐提交调试器。 +- MUST:包含多个可独立验证的架构边界时拆分为阶段 PR,例如数据/API、后台任务/索引和部署验收;跨仓变更先冻结共享协议,再分别进入最终 Review。 +- MUST:阶段 PR 说明其依赖与验收边界;只有真正完成 Issue 整体交付的最终集成 PR 使用 `Closes #xx`,避免阶段合并提前关闭需求。 +- 项目扩展点:项目可以按风险定义大型 PR 提醒阈值,但文件数或代码行数只能作为拆分信号,不能替代架构边界判断。 + +### 4.2 一轮收齐与批量修复 + +- MUST:等待一轮 Review 完整结束并收齐 findings,再按“阻塞、非阻塞、重复/outdated、既有问题或范围外”统一分类;不得一条 finding 对应一次 push 和一次完整 Review。 +- MUST:阻塞 finding 按根因批量修复,在本地完成针对性回归后推送一个完整批次;只有修复显著改变原风险面时,才请求一次聚焦该阻塞项的定向 Review。 +- MUST:非阻塞 finding 回复影响判断与处置依据后解决 thread;不修改代码、不创建跟踪 Issue,也不触发新 Review,除非维护者另行决定其确有独立价值。 +- MUST:Review 后新增与 finding 无关的业务范围时,PR 退回 Draft、重新冻结范围并重新审查;仅修复已分类 finding 时,以修复证据、确定性测试和 required CI 完成闭环。 + +### 4.3 通过与停止条件 + +- MUST:官方 Reviewer 给出未发现重大问题的明确文字结论,或所有 finding 均已完成阻塞分类与处置,即视为本轮 Review 闭环;不要求 emoji、reaction、固定措辞或零评论。 +- MUST:P2/P3、加固建议和已解释的非阻塞 thread 不得成为继续修改与复审的理由;若定向 Review 又提出新的非阻塞建议,直接记录处置并停止。 +- MUST:定向 Review 再发现新的阻塞 P0/P1,说明范围或设计仍不稳定;维护者必须先决定拆分 PR、收窄范围或重新设计,不得自动进入无界循环。 + +## 5. v1 合并边界 - MUST:v1 采用观察模式,官方 Review 不新增为 required status check,也不改变现有 `master` branch protection。 - MUST:没有官方稳定状态接口和真实仓库验证前,不假设 Review 能映射为 GitHub required check、approval 或固定 check 名称。 -- MUST:Review 发现的问题按现有 PR 对话处理;是否阻塞合并由现有门禁和维护者判断,不增加平行状态机。 +- MUST:Review 发现的问题按现有 PR 对话处理;是否阻塞合并由本契约的影响证据、现有门禁和维护者判断,不增加平行状态机。 - MUST:[GitHub 官方文档](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request)只保证无写权限者向已开启 Auto-merge 的 PR 推送时自动关闭;有写权限者推送新提交后不保证自动关闭,Auto-merge 可能继续保持开启。官方 Review 当前又不是 required check,因此 v1 暂不允许仓库或单个 PR 开启 Auto-merge。 - MUST:不创建自研合并 Bot、Action、HEAD 监听器或平行状态机来补 GitHub/Codex 当前能力缺口。 - MUST:合并后自动删除远端分支不是所有项目的公共强制项。只有仓库仅使用临时 PR head 分支,或所有长期 head 分支受保护时,才允许启用该设置;否则必须关闭,避免 GitHub 删除仍需复用的长期分支。 -- MUST:人工合并前必须确认官方 Review 当前 HEAD、全部 review thread 已解决、required checks 成功,且依赖或发布风险已分类。 -- MUST:PR 出现新提交后,旧 Review 不再作为当前 HEAD 的证据;必须重新 Review 并再次确认全部 review thread 已解决,才能人工合并。 +- MUST:人工合并前必须确认 required checks 成功、阻塞 finding 已修复或有明确风险接受、全部 review thread 已完成处置,且依赖或发布风险已分类;非阻塞 finding 无需修改代码或重新 Review。 - MUST:Dependabot PR 不因 CI 通过而自动合并;运行时依赖、跨大版本升级、构建工具行为变化及会随合并触发生产发布的仓库,都必须先完成兼容性与发布授权判断。 - 项目扩展点:未来只有在官方 Review 能成为与当前 HEAD 绑定的 required gate,或 GitHub 保证任意新提交都会撤销 Auto-merge 后,才重新评估启用原生 Auto-merge。 -## 5. 审计与验收 +## 6. 审计与验收 - MUST:中央只读审计检查根 `AGENTS.md` 是 Git tree 中的普通文件,并在 fenced code、HTML comment 与 raw HTML block 之外包含精确 `## Code Review Rules` 标题;缺失、symlink、非普通文件或缺少真实标题统一报告 `[CODE_REVIEW_RULES]`。 - MUST:审计使用固定 `markdown-it-py==3.0.0` 的 CommonMark parser,只接受真实 `h2` token,且 token 对应源码行必须精确等于 `## Code Review Rules`;不得维护平行的手写 Markdown 状态机。 - MUST:直接依赖 `markdown-it-py==3.0.0` 与传递依赖 `mdurl==0.1.2` 在本地入口和两条基线 workflow 中显式校验或固定安装,不得依赖运行环境碰巧预装的版本。 -- MUST:中央审计不抓取 GitHub/Codex 页面、不调用私有接口,也不声称验证 Automatic reviews 设置或模型审查质量。 -- MUST:中央审计验证纳管产品仓库关闭 Auto-merge;分支自动删除取决于项目真实分支模型,不由公共审计强制。人工合并前是否完成当前 HEAD Review、解决 thread 与风险分类,由真实 PR 验收,不伪装成静态仓库审计结论。 +- MUST:中央审计不抓取 GitHub/Codex 页面、不调用私有接口,也不声称验证 Automatic reviews 设置、模型审查质量、同一 HEAD 请求次数或在途 Review;这些运行态事实由真实 PR 时间线验收。 +- MUST:中央审计验证纳管产品仓库关闭 Auto-merge;分支自动删除取决于项目真实分支模型,不由公共审计强制。人工合并前是否完成 finding 分类、thread 处置与风险判断,由真实 PR 验收,不伪装成静态仓库审计结论。 - MUST:官方设置通过真实 PR 验收:Automatic reviews 能产生审查;必要时 `@codex review` 能触发人工兜底;Reviewer 能遵循仓库规则。 - MUST:接入不得新增 review 专用 secret、GitHub App、workflow、runner 或发布权限。 - 项目扩展点:保存测试 PR、Review 链接和观察期结论的方式。 diff --git a/templates/AGENTS.md b/templates/AGENTS.md index 71c6105..85c5b3a 100644 --- a/templates/AGENTS.md +++ b/templates/AGENTS.md @@ -25,9 +25,20 @@ ## Code Review Rules -- 只报告可证实且会造成实际影响的问题;尤其关注正确性、性能、回归、安全、隐私、权限、可维护性等风险。 -- 检查数据/API 与跨仓协议兼容、CI/CD 权限边界、失败/回滚路径及测试能否证明这些高风险行为。 -- 把 PR 说明和已有测试视为待验证声明,不重复 lint、格式化或纯风格意见,不要求与当前风险无关的工作;官方 Review 当前不是 required check,且 GitHub 对有写权限者推送新提交不保证自动关闭 Auto-merge;v1 暂不允许对单个 PR 开启 Auto-merge,只在 Review 当前 HEAD、全部 review thread 已解决后人工合并;项目重点:PROJECT_REPLACE_REVIEW_RULES +### 阻塞边界 + +- 只提交 P0/P1 finding:问题必须由当前 PR 引入、存在当前可达的触发路径,并会造成明确的正确性、安全、权限、数据、兼容性或发布后果;评论必须说明触发条件、实际影响和最小安全路径,证据不足则不报告。 +- P2/P3、纯防御性加固、需要未来维护者同时修改规则与测试才成立的假设、测试还可增加更多 fixture、lint/格式/措辞/命名或无当前影响的重构默认不报告,也不得仅因建议有价值就阻塞合并。 + +### 项目重点 + +- 检查数据/API 与跨仓协议兼容、CI/CD 权限边界、失败/回滚路径及测试能否证明这些高风险行为;机械一致性继续交给确定性 CI;项目重点:PROJECT_REPLACE_REVIEW_RULES + +### Few-shot + +正例:新增接口绕过现有授权校验,使普通用户能够读取他人数据;这是当前可达的安全后果,应提交 P1。 + +反例:还可以增加另一种输入形式的 fixture 或重命名 helper 以提升可维护性,但当前支持路径没有错误;这属于 P2/P3 加固,不提交 finding。 ## CI/CD 公共门禁 @@ -42,7 +53,7 @@ - 发布、手动部署、self-hosted、`dev` Environment 和发布 secret 能力只存在于唯一受控 release workflow;按真实拓扑维护 `.github/release-safety.yml`,不要把模板 job/step ID 当成公共事实。 - 项目可执行契约测试负责证明 ref/内容 ID、容器内 smoke、回滚命令和实际目标 SHA;固定 `100755` wrapper 内部调用项目测试,`PR container validation` job 名称必须唯一、无依赖且无条件执行,workflow/job/targeted step 不得自定义 shell 或工作目录,targeted step 只以精确单行 `run` 执行 manifest 声明路径。中央审计只验证 manifest 与结构化 YAML 高层约束,不解释任意 shell 控制流。 - `master` 要求 GitHub Actions 产生的 `PR container validation`,启用 strict、管理员保护和对话解决,禁止 force push 与删除。 -- 官方 Review 尚非当前 HEAD 的 required check 时,仓库保持 `allow_auto_merge=false`;只在 Review 当前 HEAD、全部 review thread 已解决且 required checks 成功后人工合并。只有仓库仅使用临时 PR head 分支,或所有长期 head 分支受保护时,才设置 `delete_branch_on_merge=true`。 +- 官方 Review 不是 required check 时,仓库保持 `allow_auto_merge=false`;只在 required checks 成功、阻塞 finding 已解决或有明确风险处置且 review thread 已完成处置后人工合并。只有仓库仅使用临时 PR head 分支,或所有长期 head 分支受保护时,才设置 `delete_branch_on_merge=true`。 ## 项目命令 diff --git a/tests/test-audit.sh b/tests/test-audit.sh index 417a000..b033591 100755 --- a/tests/test-audit.sh +++ b/tests/test-audit.sh @@ -162,15 +162,23 @@ maintenance = (root / "MAINTENANCE.md").read_text() audit_entrypoint = (root / "scripts" / "audit-github-baseline.sh").read_text() audit_source = (root / "scripts" / "audit_github_baseline.py").read_text() -def section_bullets(document, heading): +def section_content(document, heading): lines = document.splitlines() start = lines.index(heading) + 1 section = [] for line in lines[start:]: if line.startswith("## "): break - section.append(line) - return [line for line in section if line.startswith("- ")] + section.append(line.rstrip()) + return "\n".join(section).strip() + + +def section_bullets(document, heading): + return [ + line + for line in section_content(document, heading).splitlines() + if line.startswith("- ") + ] for marker in ( "PROJECT_REPLACE", @@ -189,8 +197,17 @@ assert "不得降低" in contract for document in (template, root_agents): assert "## Code Review Rules" in document assert len(section_bullets(document, "## Code Review Rules")) == 3 -assert "性能" in section_bullets(template, "## Code Review Rules")[0] -assert "可维护性等风险" in section_bullets(template, "## Code Review Rules")[0] + review_rules = section_content(document, "## Code Review Rules") + for marker in ( + "只提交 P0/P1", + "当前可达", + "P2/P3", + "默认不报告", + "正例:", + "反例:", + ): + assert marker in review_rules, (marker, document[:40]) + assert "## 官方 Review 收敛" not in document for document in (review_contract, readme, maintenance): for marker in ( "官方 Codex Code Review", @@ -199,10 +216,8 @@ for document in (review_contract, readme, maintenance): "不自建", ): assert marker in document, (marker, document[:40]) -for document in (root_agents, template, review_contract, readme, maintenance): +for document in (review_contract, readme, maintenance): for marker in ( - "Review 当前 HEAD", - "全部 review thread 已解决", "单个 PR", "Auto-merge", "暂不允许", @@ -210,13 +225,25 @@ for document in (root_agents, template, review_contract, readme, maintenance): assert marker in document, (marker, document[:40]) for document in (review_contract, readme, maintenance): for marker in ( - "新提交", "有写权限", "不保证自动关闭", "不是 required check", "Dependabot", + "P0/P1", + "P2/P3", + "默认不阻塞", + "无需重新 Review", + "当前可达", ): assert marker in document, (marker, document[:40]) +for document in (root_agents, template, review_contract, readme, maintenance): + for forbidden in ( + "Review 当前 HEAD", + "最终复审", + "至少等待 15 分钟", + "最多两轮完整", + ): + assert forbidden not in document, (forbidden, document[:40]) for marker in ("markdown-it-py==3.0.0", "mdurl==0.1.2"): assert marker in audit_entrypoint, marker assert 'MarkdownIt("commonmark")' in audit_source