Task Completion Loop

把已有 plan / spec / 半成品收敛为同一份最终代码快照上的可验证终态。

本 Skill 是薄编排：依赖 skill 拥有内部协议；本 Skill 只管理任务账本、调用顺序、证据新鲜度、授权边界和停止条件。

入口与授权

同时具备才启动：

1. Git 仓库，以及命名 plan/spec 或可从当前代码确定的明确范围。
2. 明确的完整闭环实现请求。只要 Goal、只要 review-fix-re-review、只要架构加固、普通实现、纯讨论、纯 review 或只读诊断 → 不是本 Loop。

先从文档与代码解析范围。仍无法安全确定时，只问一个范围问题并停止。禁止默认全仓库。

实现请求授权修改冻结范围内的 working tree；除非用户明确要求只读或禁止编辑。它不授权：

• git add、commit、push、merge、rebase、branch/worktree 创建；
• PR、issue、评论、消息、任务、API 数据、部署、生产写；
• 排除路径或冻结范围外修改。

agentic-review-handoff 所需的 .review-handoff/** 与幂等 $GIT_COMMON_DIR/info/exclude 条目是本闭环的本地协议产物，不是交付动作；预检时披露，完成报告中记录。用户明确禁止 .git/** 写时，在源码修改前返回 HUMAN_GATE。

能力预检

始终要求：

仅在用户显式要求 grill-with-docs，或预检发现仍有用户拥有的产品/领域决策时，要求并调用 grill-with-docs（其 frontmatter 默认 disable-model-invocation: true；文件可读即按父会话路径加载）。

在讨论、Goal、源码修改前：

1. 解析每个 skill 及其传递硬依赖（特别是 architecture-hardening-loop 的 scanner、codebase-design、只读 delegation、非宿主 Reviewer 的真实 adapter）。invocation policy 与父会话执行路径沿用 architecture-hardening-loop「硬依赖与 runtime 能力」的规则：用户点名本 Loop 即授权硬依赖按用途嵌套调用；文件可读即可由父会话执行；未安装/不可读、合同不兼容或 worker/工具无法执行才算缺失。细则见 decision-and-terminal-gates.md 的 Preflight policy。
2. 选定 Peer A、Peer B（见下文「Peer 选择」），对每个 Peer 用 agentic-review-handoff 的 review-loop consult --repo <root> --peer <product> [--fallback <未用的产品>] --question-file <md> 完成一次真实往返（用户点名账号如 codex002 / cc002 / grok002 时加 --peer-command=<名字>），并用 review-loop sessions --repo <root> --product=<product> 取回可恢复句柄；Phase 1 A 的首条成功往返即可充当此证据，不单独占一轮。每个 Peer 都须能以 adapter 的只读控制启动；盲审用的 Claude 同样。只有名字、catalog 条目或 CLI 文件存在不算可用。
3. 确认 review 协议产物可写，且不与用户的 .git/** 限制冲突。

Peer 选择：Peer A、Peer B 是两个和宿主不同的产品，按 agentic-review-handoff 保存的 Reviewer 偏好顺序（review-loop prefs，默认 claude,codex,grok）去掉宿主后取前两个：三方收敛要三个不同产品，所以这里总是跳过宿主，偏好里的 skipHost 不影响。例如默认偏好下 Claude 宿主 → Codex + Grok；Codex 宿主 → Claude + Grok；Grok 宿主 → Claude + Codex。用户点名的产品或账号优先。consult 可直接传 --host=<宿主> --skip-host，由脚本按偏好选。某个 Peer 超时，脚本按 --fallback 换到两个 Peer 和宿主都没用到的已安装产品（结果里的 fallbacks）；没有这样的产品就不换人，按下文超时规则处理。不拿另一位 Peer 的产品顶替，否则两份立场就不独立了。

缺少始终要求的能力，或缺少本轮实际需要的条件能力：

Task Completion Result
- Result: MISSING_DEPENDENCIES
- Missing: <exact skill, dependency chain, or runtime capability>
- Stop point: before discussion, Goal activation, and source changes
- Substitution/install: none; no generic agent impersonation, copied skill logic, or automatic install
- Work started: no

禁止用通用 subagent 冒充 Peer 或盲审的 Claude、伪造会话或复制缺失 skill 逻辑：三方收敛的价值来自真正独立的模型立场，冒充会让交叉质疑退化为自我评论。代装依赖属于外部写，见「入口与授权」。

状态机

预检与任务账本
  -> 三方交叉质疑
  -> 条件式 grill-with-docs（用户决策）
  -> Goal Gate
  -> 实现全部 PENDING + 验证
  -> agentic-review-handoff
  -> architecture-hardening-loop = NO_ACTIONABLE_FINDINGS
  -> 全新只读 Claude 盲审
       -> Fix：修、验、重跑下游门禁、再盲审
       -> 仅 Backlog / Reject：完成 Goal
  -> COMPLETED

任意阶段的出口：
  缺能力 -> MISSING_DEPENDENCIES
  用户决策 / 权限 / 范围扩张 -> HUMAN_GATE
  证据缺失、过期或外部会话超时 -> UNVERIFIED

Phase 0：任务账本与证据

1. 读取仓库指令、plan/spec、直接关联决策、当前代码与测试。
2. 记录仓库根、分支、HEAD、working tree；保留既有改动，不 reset / clean 无关内容。
3. 给原始计划的每项工作标记：

冻结范围包含本轮全部 PENDING 及必要测试/文档。可按依赖顺序拆成内聚批次，但不得只完成第一个容易批次就声称 plan 已完成。

原始 PENDING 不能被 reviewer 建议偷换成 Backlog：Backlog 是 reviewer 对新发现的分类，plan 承诺项的归属只属于用户或有效决策。它只能完成、被有效决策取代、明确排除或进入 HUMAN_DECISION。

可逆、范围内、不改变已决定行为的实现细节与测试选择仍属于对应 PENDING，不是 HUMAN_DECISION。按权威文档、当前代码、仓库惯例、最小改动和验证质量自行决定；agent 意见不一致本身不构成门禁。

正式 evidence id 采用 agentic-review-handoff 返回的 evidence 对象，相等性只比较 baseSha + pathFilter + digest。优先复用依赖 skill 的冻结证据，但每道门禁前后必须用同一 base/filter 执行 review-loop evidence 重算；相同 HEAD 或相同 git status 不等于相同快照。任何范围内代码或测试修改都会使旧快照的下游 test/review/audit 结论过期。

Phase 1：三方收敛与用户决策

A. 独立立场

宿主、真实 Peer A、真实 Peer B 分别读取同一组文档、代码和任务账本。每方写清范围、归属、假设、风险、排除项和可证伪验证。用 review-loop sessions 记录两个 Peer 的可恢复句柄；本步首条成功往返同时完成预检第 2 项。

预算与并行

• A 的三方立场互不依赖：宿主写自己的立场时，并行发起 Peer A 与 Peer B。
• B 的两次交叉质疑互不依赖，并行发起。B 至多两轮；第二轮后仍存分歧，属技术默认值由宿主依证据裁定，属用户决策转入 C。
• 每次外部调用设 deadline（默认与 agentic-review-handoff 的 Reviewer timeout 一致，20 分钟；宿主可缩短并记录）。以后台进程发起并按下一条等待，避免宿主前台工具超时截断真实会话。进程存活时不杀、不重发；超时先由 --fallback 换人（见「Peer 选择」），没有可换的才按 DELIVERY_UNKNOWN 处理：仅当本地证据证明未提交才同参数重试一次，否则本阶段记 UNVERIFIED，保留句柄与已得立场，下一轮从缺失的一方继续。
• 等后台外部调用结束：优先等发起时记下的 PID（如 review-loop consult ... > out 2>&1 & echo $! > pid，再 while kill -0 "$(cat pid)" 2>/dev/null; do sleep 15; done），或用宿主自带的后台任务完成通知。不用 pgrep -f / ps | grep 按等待命令自身也含的字符串轮询：它会匹配到等待脚本自己，循环永不结束；非用模式不可时写成 [r]eview-loop 这类方括号形式，让它匹配不到自身。
• 快路径：账本无 HUMAN_DECISION、范围由 plan/代码唯一确定、A 三方在范围/归属/验证上无实质分歧时，B 只跑一轮，无新分歧即收敛。快路径不减少参与方，不省略 B。

B. 交叉质疑

• 把宿主 + Peer B 立场交给 Peer A；把宿主 + Peer A 立场交给 Peer B。
• 双方攻击对方最强论点，并允许依据证据改口。
• 宿主独立打开引用路径、核对当前行为，再综合证据。

三份平行评论不算收敛：只有被对方攻击过仍成立的论点才是证据。

C. 用户决策

• 权威文档和代码已经给出答案，或只剩普通技术默认值：自行收敛，不重新提问。
• 真正的 HUMAN_DECISION：用户说“不要问”也不扩大产品决策或外部写授权（见「入口与授权」）；Agent 一致不能代替用户。
• 出现真实用户决策或显式 grill-with-docs 时，先读 decision-and-terminal-gates.md 的 Human decision convergence，再决定是否返回 HUMAN_GATE。按 grilling 的 frontier round 提问：同轮可含全部互不依赖的问题，每个问题都附推荐答案，让用户只做取舍而不重新调研。

记录：

Three-party Convergence
- Decision:
- Why:
- Work ledger:
- Frozen scope / exclusions:
- Ownership and dependency direction:
- Verification:
- Peer A (product) session:
- Peer B (product) session:
- Fallbacks: none | <from → to, reason>
- Remaining decisions: none | <list>

Phase 2：Goal Gate

收敛后调用 goal-gate，严格服从其 Decision / Next：

• wait for user /goal、ask approval 或 defer：返回 HUMAN_GATE 并停止。生成 prompt 不代表 Goal 已激活。
• suggest + adopt goal and continue：按 transcript contract 继续本 Loop，报告 Goal: not-created；suggest + provide prompt / route elsewhere：返回 HUMAN_GATE。
• 已有 Goal：从 native 工具、产品状态或调用方传入的可核对 parent contract 比较 objective、冻结范围、Done condition 与 completion owner；native getter 不是唯一证据源。ownership 关系与完成权见 decision-and-terminal-gates.md 的 Goal ownership；冲突或证据不足才 defer。
• 可激活或采用时，Goal 覆盖任务账本、冻结范围、验证、三道门禁、协议写和外部写边界。

Done condition 要求：账本无 PENDING / HUMAN_DECISION；验证和三道门禁覆盖同一最终 evidence id。只有 created-by-loop / exact-same-goal 由本 Skill 完成；broader-compatible 即使本 Loop 已完成，也保持父 Goal active，并报告 Goal: active-checkpoint。

Phase 3：实现与验证

按依赖顺序处理全部 PENDING：

1. 转成可观察成功标准；行为变更可行时先展示失败复现。
2. 做最小内聚改动，不顺手做相邻 backlog 或投机抽象。
3. 先跑定向检查，再跑相关包/仓检查。
4. 对外可见行为使用浏览器、CLI、日志、渲染或请求/响应等真实 runtime 信号。
5. 证据通过后才标记 VERIFIED_DONE，并同步 plan / 现状文档。

未运行、失败或已过期的必需证据记 UNVERIFIED，不能算通过。

Phase 4：三道门禁

开始或恢复本阶段前，读 decision-and-terminal-gates.md 的三份 terminal contract；依赖拥有内部状态机，本 Skill 只核对终态、evidence id 和父 Goal ownership。

1. agentic-review-handoff：默认 completion=pass；只在最终 PASS / NO_FINDINGS 覆盖当前 evidence id 时继续。BLOCKED、concerns_require_fix、review-only 与异常路径见 reference。
2. architecture-hardening-loop：同范围运行，只接受 NO_ACTIONABLE_FINDINGS；其 HUMAN_GATE / MISSING_DEPENDENCIES / UNVERIFIED 原样透传为本 Loop 的同名 Result。它修改文件会使旧 evidence id 失效；其内部 review 覆盖最终 evidence id 时可复用，不必重跑直接 review。Fix 与 ownership 路径见 reference。
3. 全新 Claude 盲审：使用新的可验证只读会话审最终 evidence id。范围内 Fix 触发最小修复和全部下游门禁重跑；最多 2 轮。

无人值守续跑

仅用于无人值守 / 自主运行；有人在场回答的 human-in-the-loop 会话不套用。

• 纯文本结束的回合是进度报告，不是完成证据。任务账本就是 checklist，每回合更新；回合结束时仍有 PENDING 且未写明 blocker，就继续，或由宿主 / 父会话发一条点名未完成项的短消息。同一任务自动续跑最多 2–3 次，之后停下交审（按下文预算规则返回 UNVERIFIED），让真正卡住的运行结束。
• 本 Loop 启动的后台命令、subagent 或 Peer / Claude 会话仍在运行时，等它结束并取回输出，不把任务当作完成。
• 不应出现的提前停止：(1) 长总结只宣布下一步、没有工具调用；(2) 提出“除非你另有安排，否则我继续”并等回复；(3) 列出待用户决策项，但按自己判断没有一项阻塞剩余工作；(4) 因回合太长或某个里程碑完成而停下汇报。状态说明与建议放在下一次工具调用的同一消息里。应当停止：没有用户就无法推进（HUMAN_GATE），或阻塞点是被刻意保护的对象。本节不替代高风险 / 破坏性动作的确认，也不扩大「入口与授权」。

终态与报告

Phase 1 的 deadline、B 轮数与 Phase 4 的 2 轮盲审是本 Skill 的全部预算。预算见底既不是完成理由，也不是用户决策：它不改变代码是否正确，用户也无实质取舍可做。宿主可续跑时继续；必须交还控制时返回 UNVERIFIED、保持 Goal active，并从未完成证据继续，不要求用户重复授权。

跨任务经验

经验目录：${AGENT_LESSONS_DIR:-$HOME/.local/state/agent-lessons}/task-completion-loop/，每条一个 <slug>.md。它在 skill 目录外，更新 skill 不会覆盖，也不会进仓库。

• Phase 0 读仓库指令后，列出该目录，只读 cue 与本任务形态相符的条目。经验只是提示；与当前代码、证据或用户决策冲突时，以后者为准。
• 终态报告前，最多写一条新经验，三项缺一不写：
  • cue：遇到什么形态的情况适用。写情况的形状，不写本仓库的文件名、函数名或业务事实。
  • lesson：这次学到什么做法或坑。
  • evidence：哪个 evidence id、门禁或盲审结论证明它，以及对比的是哪两种做法。
• 只因结果 COMPLETED 不构成经验；没有可对照的证据就不写。与已有条目重复时更新那条，不新增。
• 经验文件不得写入评审打分、凭证或用户私有数据。

Task Completion Result
- Scope / exclusions:
- Work ledger:
- Three-party decision:
- Goal: <completed | active-checkpoint | not-created | deferred-conflict>
- Final evidence id:
- Implemented:
- Verification:
- Agentic review: <packet/session + evidence id>
- Architecture hardening: <result + evidence id>
- Final Claude audit: <fresh session + evidence id>
- Fixed / Backlog / Rejected:
- Protocol, Git, and external actions:
- Lessons: <读取的条目 | 新写或更新的条目 + evidence | none（理由）>
- Result: COMPLETED | HUMAN_GATE | MISSING_DEPENDENCIES | UNVERIFIED