docs: explain resumable Improve acceptance

docs/116/codex-improve.md

@@ -4,7 +4,7 @@
 
 ## 适用场景
 
-当你希望先弄清问题和方案，再让 Codex 修改代码时使用 Improve。它把工作分成 advisor 审查与规划、隔离 executor 实现、主会话验收，以及按风险触发的独立复核。调用 `$improve` 不会改变当前 Codex 会话使用的模型或 reasoning effort。
+当你希望先弄清问题和方案，再让 Codex 修改代码时使用 Improve。它把工作分成 advisor 审查与规划、隔离 executor 实现、主会话实现审查、按风险触发的独立复核，以及必要时交给用户或外部系统完成的实际验收。调用 `$improve` 不会改变当前 Codex 会话使用的模型或 reasoning effort。
 
 进入目标仓库并启动 Codex：
 
@@ -51,15 +51,21 @@ advisor 不会把第一版草稿直接交给 executor。`plan` 和 `review-plan`
 - 目标行为、约束、依赖、验证、回滚、停止条件和验收标准；
 - Engineering contract（仓库已有的 build、test、lint、CI、policy、classifier、兼容性、发布和部署等工程约束）及其影响。
 
+每项检查还会被明确分为三类：
+
+- implementation gate：Codex 可以通过测试、构建、浏览器、截图、日志、指标或模拟器验证的检查，必须在实现获批前完成；
+- deferred acceptance：当前环境确实无法完成的实体机、人工判断或外部系统验收；
+- observation：合并后的长期观察项，除非计划写明失败阈值和状态变化，否则不阻塞当前改动。
+
 这些内容必须足以让没有历史对话的新 executor 执行。发生上下文压缩、会话恢复或中断后，计划和仓库证据才是任务语义来源，聊天摘要只用于定位。
 
 如果实现需要改变仓库既有的 CI、测试政策、门控规则、发布策略或兼容边界，advisor 必须解释影响并以 `BLOCKED` 等待批准，不能把这类变化作为附带修改自动纳入范围。
 
 ## 隔离执行
 
-`$improve execute <计划文件>` 会从当前 Git `HEAD` 创建临时 branch 和 worktree。worktree 是同一个 Git 仓库的独立工作目录，executor 只能在其中修改计划允许的路径。
+`$improve execute <计划文件>` 会从当前 Git `HEAD` 创建独立 branch 和 worktree。worktree 是同一个 Git 仓库的独立工作目录，executor 只能在其中修改计划允许的路径。
 
-主目录中尚未提交的修改不会自动进入 worktree，因此执行前应确认 executor 需要的基础改动已经提交。executor 会运行计划规定的检查并留下未提交 diff，但不会自行提交、合并、推送或创建 PR。临时 worktree 会保留给当前 Codex 会话检查和继续修改。
+主目录中尚未提交的修改不会自动进入 worktree，因此执行前应确认 executor 需要的基础改动已经提交。executor 会运行计划规定的检查并留下未提交 diff，但不会自行提交、合并、推送或创建 PR。worktree 保存在 `$XDG_STATE_HOME/codex-improve/worktrees`，未设置该变量时使用 `~/.local/state/codex-improve/worktrees`；会话中断或机器重启后仍可从输出的路径继续。
 
 ## 外部实践与独立复核
 
@@ -70,9 +76,21 @@ executor 完成后，当前会话先检查完整 diff、验证结果和 Engineer
 - 行为重要或存在歧义时，correctness reviewer 检查正确性、安全、回归、测试以及计划是否落实。
 - 引入抽象、模块、公开接口、依赖、兼容层、跨所有者边界、复杂生命周期、并发或安全逻辑时，elegance reviewer 检查复用、抽象必要性、模块边界、locality、speculative flexibility 和可删除代码。
 
-reviewer 接收一份不依赖聊天记录的完整 evidence dossier（证据包），并输出结构化 verdict。Elegance review 会把 Ponytail 的复杂度检查作为一个内部视角，但其建议只是待验证假设；不能为了减少代码而破坏正确性、用户决定、仓库规则或必要测试。
+reviewer 接收一份不依赖聊天记录的完整 evidence dossier（证据包），并输出结构化 verdict。当前主会话只运行一次 Ponytail 复杂度检查，并把原始建议及采纳或拒绝理由放入证据包；elegance reviewer 复核这些证据，不会再次调用 Ponytail。Ponytail 建议只是待验证假设，不能为了减少代码而破坏正确性、用户决定、仓库规则或必要测试。
+
+review 有分阶段收敛规则和最终运行保护，但具体 token 与时间阈值仍在观察，不是稳定的用户承诺。reviewer 不会自动重试；无法形成可靠结论时返回 `INCONCLUSIVE`，需要用户批准后才能重试或改变计划。事件日志、结构化结果和诊断文件保存在 `$XDG_STATE_HOME/codex-improve/reviews`，未设置该变量时使用 `~/.local/state/codex-improve/reviews`。
+
+## 实现审查与实际验收
+
+Improve 分开记录三件事，避免把“代码已经正确实现”和“用户已经在真实环境确认”混成同一个结论：
+
+- Implementation review：实现仍待审查、已经批准、需要修改或被阻断；
+- Checkpoint：当前改动还没有恢复点、已有可恢复目标，或已经集成；
+- External acceptance：不需要外部验收、等待验收、已经通过或已经失败。
+
+独立 reviewer 只判断实现和 agent 可获得的证据。需要观察实体机 UI、操作真实硬件或等待外部系统时，尚未执行的验收不会让一个正确实现被判为 `BLOCK`。主会话会先完成所有 implementation gates，再准备一个精确 checkpoint，例如持久 worktree 与 diff、commit、branch、PR 或 deployment ID。涉及 commit、push、部署或合并时，仍会先按仓库规则请求批准。
 
-review 有分阶段收敛规则和最终运行保护，但具体 token 与时间阈值仍在观察，不是稳定的用户承诺。reviewer 不会自动重试；无法形成可靠结论时返回 `INCONCLUSIVE`，需要用户批准后才能重试或改变计划。
+只有实现已批准、checkpoint 可以恢复，而且验收已经可以针对该目标执行时，计划才进入 `ACCEPTANCE PENDING`。此时可以退出终端、切换机器或稍后再回复；下一次对话会从计划和 checkpoint 恢复，而不是依赖聊天记忆。验收失败若证明实现有缺陷，任务回到实现阶段；如果只是代理、网络或其他无关环境故障，则保留待验收状态并记录证据。
 
 ## 完整流程
 
@@ -84,8 +102,10 @@ review 有分阶段收敛规则和最终运行保护，但具体 token 与时间
   -> executor 在独立 worktree 中修改和验证
   -> 当前会话核对完整 diff 与 Engineering contract
   -> 按风险触发 correctness / elegance 独立复核
-  -> 当前会话验证 reviewer 结论并给出验收结果
-  -> 你决定接受、要求修改或放弃
+  -> 当前会话验证 reviewer 结论并给出实现审查结果
+  -> 若无需外部验收，你决定是否集成
+  -> 若需要实体机、人工或外部验收，先准备可恢复 checkpoint
+  -> 你针对该 checkpoint 验收并反馈，记录结果并在集成后进入 DONE
 ```
 
 ## 预定义 agents
@@ -94,7 +114,7 @@ review 有分阶段收敛规则和最终运行保护，但具体 token 与时间
 
 | Agent / profile | 模型与 effort | 权限 | 负责什么 |
 | --- | --- | --- | --- |
-| 当前 Codex 会话（advisor） | 沿用当前会话设置 | 审查和规划阶段不修改源代码；只写计划 artifact（通常是 Markdown 计划文件） | 理解仓库、筛选问题、与用户确认方向、收敛计划，并在执行后承担最终验收。 |
+| 当前 Codex 会话（advisor） | 沿用当前会话设置 | 审查和规划阶段不修改源代码；只写计划 artifact（通常是 Markdown 计划文件） | 理解仓库、筛选问题、与用户确认方向、收敛计划，并在执行后负责实现审查与外部验收交接。 |
 | `improve-scout` | `gpt-5.6-luna` + `high` | 只读 | 在大型审查中分区寻找候选问题；必要时围绕明确的外部实践问题收集一手社区证据。它只提供线索，不修改代码或作最终裁决。 |
 | `improve-executor` | `gpt-5.6-sol` + `medium` | 仅可写独立 worktree | 默认执行器；按照 `READY` 计划修改代码、运行检查并留下未提交 diff。 |
 | `improve-executor-deep` | `gpt-5.6-sol` + `xhigh` | 仅可写独立 worktree | 处理技术不确定性高、跨模块或需要更深入推理的计划；更慢且 token 消耗更高，不作为默认选择。 |
@@ -105,7 +125,7 @@ review 有分阶段收敛规则和最终运行保护，但具体 token 与时间
 
 Improve 会在内部使用两个命令：
 
-- `codex-improve-exec` 创建临时 branch/worktree，并启动普通或 deep executor。
+- `codex-improve-exec` 创建持久 branch/worktree，并启动普通或 deep executor。
 - `codex-improve-review` 用对应的只读 profile 运行 correctness 或 elegance review，保存结构化结果和诊断信息。
 
 普通用户通常不需要直接调用它们，只需在 Codex 对话中使用 `$improve ...`。