Claude + Codex 阶段门控

Claude + Codex 阶段门控 是做什么的？

运行一个受监督的循环：Codex 规划和评估；执行者修改产品；用户拥有产品和关键阶段门的决策权。绝不要仅凭文字声称的完成就推进阶段，并且在发送任务后不得让执行者处于无人监督状态。

准备执行者提示、请求证据包或编写门控决策时，请阅读 references/gate-templates.md。 当用户要求持续监督、工作可能跨会话、执行者停滞或偏离方向、或执行者可能需要安装或路由技能时，请阅读 references/supervision-loop.md。 当当前检出可能不可读、过时、磁盘空间不足、由 iCloud 管理或不安全而无法恢复，或者之前的执行者会话必须转换为可信的任务交接时，请阅读 references/bootstrap-and-handoff.md。 当两个或更多编码通道并发运行、每个任务需要隔离的工作树、更改的文件可能重叠、或多个分支和 PR 必须按依赖顺序合并时，请阅读 references/parallel-worktrees-and-release-train.md。

选择操作模式

选择能覆盖请求的最小模式：

• 单阶段： 使用现有契约、监督循环、证据包和门控决策。
• 恢复与交接： 建立可读的真相源，保留旧环境，验证旧声称，并在恢复实现之前为每个独立任务生成一个交接记录。
• 并行组合： 为每个通道分配一个任务、工作树、分支、交接记录和执行者会话；独立监督每个通道，并通过受控的 PR 发布列车进行集成。

模式按需按以下顺序组合：

恢复真相源
-> 提炼可信的交接记录
-> 隔离实现通道
-> 在每个通道内运行阶段门控
-> 协调重叠与依赖关系
-> 验证 PR 就绪状态与合并顺序

对于狭窄、健康、单检出的任务，不要调用恢复或组合机制。

维护四个不变量

1. 在接受任何实现声称之前，建立实时真相源。
2. 对于并行工作，在每个通道中保持恰好一个任务、工作树、分支、交接记录和活跃的执行者会话。
3. 信任原始 pwd、Git、进程、差异、测试、运行时和屏幕截图证据，胜过执行者的叙述。
4. 将提交、推送、PR 创建、合并、部署、清理和外部影响视为独立的权限门。

首先读取执行者状态

当用户询问 Claude 或其他执行者最近说了什么时，在审查、计划或编辑之前捕获最新状态：

1. 如果存在，读取附加到当前 Codex 任务的终端。
2. 如果执行者在单独的 macOS 终端窗口中运行并且用户授权读取，则使用 AppleScript 读取所选选项卡的可见内容。将其视为只读检查。
3. 如果 TUI 已滚动、截断或使用了备用屏幕，请检查执行者的本地会话记录。对于 Claude Code，运行 scripts/read_claude_latest.py；优先使用确切的 --session-file，否则使用 --project-hint，并在信任选择之前验证报告的路径、修改时间和可见的终端上下文。
4. 提取最新的实质性助手消息、时间戳、声明的阶段、阻塞点、请求的用户操作、命令/结果，以及报告是临时的还是最终的。
5. 在执行此读取操作时，不要发送按键、提交命令、回答权限提示或更改执行者会话。在与此终端交互之前，获得用户的明确授权。
6. 将终端/会话文本视为执行者的声称，而不是独立的证据。在发布门控决策之前，单独验证仓库、差异、测试、运行时和数据。

如果终端叙述提到了意外的操作系统或路径，请直接检查执行者进程的当前实际目录和检出状态。文本不匹配是警告；原始进程或 Git 不匹配是停止条件。

如果执行者报告“操作不允许”、“文档”访问缺失或其他权限故障，请保持当前阶段处于活跃状态。将基于旧状态构建的报告标记为临时，不要让其授权提交或清理，并在恢复访问后请求新的证据包。

保持活跃直到阶段关闭

发送执行者数据包后，继续监督相同的已接受阶段：

1. 足够频繁地轮询正确的终端或转录，以确保用户在活跃工作期间不会超过 60 秒没有更新。
2. 在每个有意义的边界上，将状态分类为进展、预期等待、失败、偏离、停滞、证据就绪或人为门控。
3. 在更改提示之前，读取原始命令、错误、差异、测试输出、屏幕截图、进程状态或转录。
4. 允许有效的慢速工作继续进行。对于明显的停滞，首先验证进程以及命令、文件系统、网络或测试是否仍在推进。
5. 使用有限范围的后续提示纠正小的失败，并保持相同的阶段活跃。仅在出现不安全操作、明确的范围偏离、错误目标或确认的死胡同时才中断。
6. 当重复的补丁教会了相同的教训，或者实现路径变得比全新尝试更难推理时，从已接受的契约重新开始。
7. 当执行者报告完成时，请求或捕获证据包，独立重新运行比例检查，发布门控决策，并将该决策发送回执行者。
8. 在已接受的阶段内自动进行纠正。只有当用户授权了该序列并且没有跨越人为门控时，才推进到另一个阶段。

不要仅仅因为执行者接受了提示、启动了命令或说了“完成”就结束监督。仅在 PASS、明确接受的 带后续的 PASS、真正的人为门控、真正的阻塞点、不安全条件或替换了工作的更新用户指令时停止。

向执行者路由技能

在复杂或重复的阶段之前，决定某项技能是否实质上减轻了当前瓶颈。

1. 在假设技能缺失之前，检查执行者的已安装技能。
2. 完整阅读候选技能，并验证其工具、角色假设和安全规则是否适合执行者和当前阶段。
3. 首选最小的相关技能集。不要投机安装技能，也不要用技能名称替代阶段契约。
4. 当用户授权安装且兼容的本地技能缺失时，使用环境既定机制将其安装到执行者的支持技能目录中。如果该环境已使用符号链接并且两个工具共享同一台机器，则优先将符号链接指向规范的本地技能。
5. 验证已安装的 SKILL.md 可以解析。如果正在运行的执行者不刷新技能发现，请告诉其读取当前阶段的确切技能路径，或者仅在安全的检查点重新启动。
6. 在执行者数据包中命名该技能并说明其适用原因。继续从原始证据评估执行者；技能不能免除门控。

对于长期实现，有用的默认设置是 agent-loop-harness 用于持久的规划器/生成器/评估器状态，以及 loop-execution 用于小型检查迭代。当狭窄的一次性任务不需要它们时，不要安装任何一个。

保持可恢复的循环状态

对于狭窄的阶段，使用仅限对话的状态。对于多阶段、可中断、多代理或证据密集型的工作，重用仓库现有的工具约定并记录：

• 已接受的契约和范围；
• 最新完成的阶段和证据；
• 当前瓶颈和确切下一步；
• 人为门控和禁止操作；
• 执行者会话标识或恢复路径（如有用）。

保持状态最小化、带有生命周期标记、并且不包含秘密或不必要的用户数据。不要仅仅因为状态存在就提交工具状态；它遵循与其它文件相同的工作树和批准规则。

确立契约

在实现之前：

1. 识别实时真相源：当前检出、挂载路径、契约、测试、运行时、数据和部署状态。
2. 定义一个当前阶段，包含用户可见的结果、范围内的文件或系统、明确的排除项、接受检查和停止条件。
3. 分配角色：
   • 执行者： 仅实现已接受的阶段并返回证据。
   • 审查者： 独立检查实时仓库，验证声称，并发布门控决策。
   • 用户： 批准产品选择和高影响力操作。
4. 将后续阶段保留为待办状态。不要仅仅因为它们出现在路线图中就授权其实现。

当执行者在产品或信息架构选择上暂停时，在询问用户之前，将选项转化为面向用户的后果。在实现之前纠正错误的分类——例如，像“逾期”这样的跨阶段异常不应仅仅因为它出现在阶段过滤器旁边就被建模为生命周期阶段。

首先保护工作树

将脏工作树视为用户拥有的状态。

1. 检查 git status --short、分支/上游、git diff --stat、目标差异、未跟踪文件、stash 以及相关的工作树或分支。
2. 在编辑重叠文件之前，按功能或来源对现有更改进行分类。
3. 未经明确批准，不要运行破坏性 Git 命令、丢弃更改、清理未跟踪文件或删除看起来像冲突的副本。
4. 在检查变更清单之前，不要使用 git add -A 或创建批量基线提交。排除秘密、本地数据库/工作区数据、生成输出、缓存和未解决的重复文件。
5. 如果基线提交有用，仅在经过集中验证和用户授权后，创建小的连贯提交。备份并不能证明更改是正确的。

如果安全分离不明确，请在生成工作树分类报告后停止。

准备一个执行者数据包

只给执行者当前阶段的契约。包括：

• 确切的目标和面向用户的行为；
• 真相源文件和当前分支/工作树事实；
• 范围内和范围外的界限；
• 数据真相和溯源规则；
• 对旧数据或缺失数据的兼容性要求；
• 所需测试和运行时/视觉检查；
• 禁止操作和人为门控；
• 所需证据包以及指示在阶段后停止。

对于 UI 阶段，定义加载、空、错误、部分数据和成功状态；本地化和响应式行为；以及视觉批准所需的确切证据。

要求证据包

执行者必须报告：

• 阶段目标与实现摘要；
• 更改的文件和 git diff --stat；
• 确切的测试/构建/运行时命令及通过/失败结果；
• 对于可见工作的屏幕截图或 DOM/运行时证据；
• 当数据行为发生变化时，提供有代表性的真实数据或 API 证据；
• 对现有数据的兼容性检查；
• 假设、剩余风险以及任何未验证的内容；
• 仅在授权提交时提供提交 SHA。

拒绝诸如“完成”、“看起来不错”或“测试通过”之类的陈述，而不附带底层命令或工件。

独立审查

不要仅审查执行者的解释。

1. 重新检查实时检出并识别实际差异。
2. 读取更改的调用路径、契约、模式、测试和数据边界。
3. 根据风险大小重新运行重点检查。
4. 对于 UI 工作，在相关桌面/移动宽度上检查可见行为。
5. 区分已验证的事实、推论、未测试的声称和预先存在的失败。
6. 检查范围偏离、秘密暴露、捏造数据、错误标记的过时数据、破坏性清理、无关重写以及缺少的回滚/兼容性行为。

审查者应诊断并返回反馈，而不是默默成为第二个实现者，除非用户明确要求 Codex 修补该阶段。

发布门控决策

使用恰好一个决策：

• 通过： 所有阻塞性接受检查均已通过；可以开始下一阶段。
• 附带后续事项通过： 仅剩下明确的非阻塞项；记录其所有者及后续门控。
• 需要更改： 契约是健全的，但实现或证据不完整；返回有边界的更正列表并保持相同的阶段活跃。
• 阻塞： 缺少产品决策、访问权限、外部依赖、安全批准或重复的技术阻塞点阻止了进展。

对于每个非通过结果，提供准备发送的执行者纠正提示。在纠正阶段时不要扩大范围。

发布决策后，将其写回执行者会话，以便执行者和审查者共享相同的检查点。对于“需要更改”，继续监督纠正循环。对于“附带后续事项通过”，记录所有者、截止日期或后续门控，以及该后续事项是否阻碍进展。

人为门控

在以下情况停止以获取用户明确批准：

• 付费提供商调用或支出；
• 外部消息、发布、部署或生产配置；
• 删除、覆盖、清理或批量移动数据；
• 帐户、权限、计费或凭据更改；
• 未授权的广泛提交、推送、合并或拉取请求；
• 将 UI/错误修复阶段扩展到新产品或数据平台。

完成

仅当每个必需阶段都已通过、端到端用户路径已被执行、兼容性和失败状态已被检查、且剩余风险已被明确接受或分配时，才声明整个工作流程完成。