RFC Proposal: Runtime 任务完成判定闭环与 Hook 扩展层（确定性验证 + ReAct 内循环）

[pionxe]

1. Summary

• 当前系统已具备 ReAct 主链路、Tool Facts、Todo、SubAgent 与 RunState phase，但“任务完成”仍缺少 runtime 级确定性闭环。
• 本提案将完成判定升级为“双环模型”：内环由 ReAct 自驱执行，外环由 Runtime 强制验证流水线（lint/build/test/typecheck）兜底。
• 同时引入 Runtime Hook 扩展层，借鉴 Claude Code Hook 思路，但采用强类型、可测试、可控失败策略的 Go 内部机制。
• 目标是让系统从“会调用工具”升级为“对代码任务结果负责到底”。

2. Background and Problems

2.1 Observed Facts

• completion gate 已存在，但当前阻断条件仅覆盖 pending todo / unverified write / post-execute closure。
  关联文件：internal/runtime/controlplane/completion.go
• RunState 已有 plan/execute/verify，但 verify 目前未绑定 runtime 强制验证流水线。
  关联文件：internal/runtime/controlplane/phase.go, internal/runtime/run.go
• ToolExecutionFacts 已支持 WorkspaceWrite 与 VerificationPerformed/Passed/Scope，但主要依赖工具返回事实，不是 runtime 硬判定。
  关联文件：internal/tools/types.go, internal/tools/bash/tool.go, internal/runtime/turn_control.go
• StopReason 当前缺少“验证失败/重试耗尽/闭环熔断”语义。
  关联文件：internal/runtime/controlplane/stop_reason.go, internal/runtime/controlplane/decider.go
• Todo 领域已具备 RetryCount/RetryLimit/FailureReason 等字段，但 runtime 尚未形成统一“验证失败 -> 回退重做 -> 熔断阻塞”的调度闭环。
  关联文件：internal/session/todo.go
• Runtime 已存在 ExecuteSystemTool 执行通道，可用于外循环确定性验证。
  关联文件：internal/runtime/system_tool.go
• 当前工具执行含权限审批链路，若直接走普通 bash 自动验证，可能进入 ask 交互阻塞。
  关联文件：internal/runtime/permission.go

2.2 Inference

• 仅依赖 Prompt 约束和模型自我修复，无法稳定保证“完成判定可信、失败策略一致、token 消耗可收敛”。
• 必须把“是否完成”的最终控制权收归 Runtime。

2.3 Assumption

• 不同仓库的验证命令差异大，需要配置化命令集合与启停策略。
• 自动化验证默认不应触发人工审批弹窗，否则闭环被中断。

3. Goals

• 建立 Runtime 强控的任务完成闭环：写入后必须经过验证流水线才可 DONE。
• 建立结构化失败归因：验证失败可被机器读取并驱动下一轮修复。
• 建立统一重试与熔断策略：失败可重试，重试耗尽后进入 BLOCKED 并停止自动消耗。
• 建立可扩展 Hook 机制：不改主循环即可插入治理策略、观测与审计能力。
• 保持模块边界：不把策略泄漏到 TUI，不把工具执行散落到 runtime/tui 之外。

4. Non-Goals

• 不在本 RFC 中引入新的模型厂商适配逻辑。
• 不在本 RFC 中实现完整 CI 平台替代。
• 不以“兼容旧路径”为目标保留多套完成判定逻辑。
• 不把 Hook 设计成任意外部脚本执行平台（避免不可控副作用）。

5. Design

5.1 Main Structure / System Prompt

• 采用“双环架构”：
• 内环：现有 ReAct（plan/execute）负责产出修改与工具调用。
• 外环：Runtime 在 verify 阶段强制执行验证流水线并给出硬结果。
• 完成判定收敛为：
• completion gate 通过（无 pending todo、无未验证写入、无 post-execute closure）
• 且 verification gate 通过（对本轮写入范围完成验证）
• Prompt 仅保留行为约束，不承担最终裁决：
• 可增加 submit_for_review 作为模型显式提交信号。
• 即使模型未显式提交，Runtime 在检测到未验证写入时仍会强制触发外循环验证。

5.2 Sub-agent Design

• SubAgent 继续用于执行类子任务，不拥有最终完成判定权。
• SubAgent 返回结果只作为内环输入，不可直接将 Todo 标记为最终完成。
• Runtime 对 SubAgent 产物执行同一套验证与重试规则，避免主/子代理行为分裂。

5.3 Tool Strategy

• 新增 Runtime 验证编排器（建议走 ExecuteSystemTool 通道），执行配置化命令：
• lint
• typecheck
• build
• test
• 统一输出结构化结果：
• stage
• command
• exit_code
• error_class
• file
• line
• summary
• raw_excerpt
• 工具事实约束：
• 模型工具返回的 VerificationPerformed/Passed 作为参考信号。
• 最终 verification gate 以 Runtime 验证编排器结论为准。
• 禁止通过伪造工具事实绕过完成门禁。

5.4 Behavior Constraints

• 新增 StopReason（建议）：
• STOP_VERIFICATION_FAILED
• STOP_RETRY_EXHAUSTED
• STOP_REACT_STEP_EXHAUSTED
• Todo 闭环规则：
• 验证失败：RetryCount++，写入 FailureReason，状态回退到可继续执行态。
• 达到 RetryLimit：状态转 blocked，Run 终止并等待人工介入。
• 验证通过：清除未验证写入标记，允许进入完成判定。
• 熔断规则：
• 内环超过步数上限触发 STOP_REACT_STEP_EXHAUSTED。
• 外环重试耗尽触发 STOP_RETRY_EXHAUSTED。

5.5 Hook Mechanism (Claude Hook 思路的本地化落地)

• 引入 Runtime 内部 Hook Registry（强类型接口 + 固定生命周期点）：
• BeforeToolExecute
• AfterToolExecute
• BeforeVerification
• AfterVerification
• BeforeCompletionDecision
• BeforeStopReasonDecide
• Hook 分级：
• Blocking Hook：失败即阻断（质量门禁、安全策略）。
• Non-blocking Hook：失败仅记录（埋点、通知、观测）。
• 每个 Hook 必须声明：
• name
• priority
• timeout
• failure_policy（fail-open / fail-closed）
• 与 Claude Code Hook 的关系：
• 借鉴事件拦截思想。
• 不采用松散脚本化回调，改为 runtime 内部可测试机制，避免不可控副作用。

6. Acceptance Criteria

• 代码写入后，任务无法直接 DONE，必须通过 runtime 外循环验证。
• 验证失败时，系统能输出结构化失败归因并驱动下一轮修复提示。
• 连续失败达到重试上限后，任务进入 blocked，并输出明确 stop reason。
• stop_reason_decided 事件能区分“验证失败”“重试耗尽”“普通完成”等终止类型。
• Hook 可以在不改 ReAct 主循环代码的情况下启停，且行为可被测试覆盖。
• 关键路径测试覆盖：
• completion gate
• stop reason 决议
• todo 重试流转
• 验证编排器成功/失败分支
• hook fail-open/fail-closed 语义

7. Dependencies and Impact

• 配置层：新增 runtime verification 配置项与校验逻辑。
  关联文件：internal/config/runtime.go, internal/config/config.go
• Runtime 控制面：扩展 stop reason、验证门禁、重试熔断与事件载荷。
  关联文件：internal/runtime/controlplane/decider.go, internal/runtime/events.go, internal/runtime/run_lifecycle.go
• Runtime 执行面：在 run.go 与 turn_control.go 接入验证编排与回退逻辑。
  关联文件：internal/runtime/run.go, internal/runtime/turn_control.go
• Session/Todo：消费既有重试字段并补齐流转校验测试。
  关联文件：internal/session/todo.go
• 文档：同步更新 runtime 流程、todo 设计、tools 与 TUI 事件说明。
  关联文件：docs/runtime-provider-event-flow.md, docs/session-todo-design.md, docs/tools-and-tui-integration.md

8. Implementation Changes

• 在 internal/runtime 新增验证编排模块与结构化失败分类模块（建议新目录 verification）。
• 在 internal/runtime 新增 Hook 抽象与注册中心（建议新目录 hooks）。
• 扩展 internal/runtime/controlplane/stop_reason.go 与 decider.go 的停止语义。
• 扩展 internal/runtime/events.go 新增验证相关事件载荷（开始、完成、失败归因）。
• 在 internal/runtime/run.go 引入“写入后强制验证 -> 失败回退 -> 成功放行”的闭环。
• 在 internal/config/runtime.go 增加 verification 配置字段及默认值/校验。
• 补齐单元测试与回归测试：
• 验证流水线通过/失败/超时
• 重试计数与阻塞
• Hook 顺序、超时、失败策略
• stop reason 唯一决议一致性

9. Alternatives

• 仅做 Prompt 强化 + 工具约束，不做 Runtime 外循环。
• 优点：实现快。
• 缺点：完成判定稳定性依赖模型，难以工程化兜底。
• 纯状态机硬编码，不引入 Hook。
• 优点：简单直接。
• 缺点：后续新增治理策略时会持续侵入主循环。

10. Risks and Rollback

• 风险：验证命令配置不当导致误阻塞。
• 对策：提供按仓库可配命令集和可观测失败摘要。
• 风险：Hook 滥用导致隐式副作用。
• 对策：限制 Hook 生命周期点、超时、失败策略与读写边界。
• 回滚：关闭 verification gate 与 Hook registry 开关后，退回现有 completion gate 行为。

[Cai-Tang-www]

@xgopilot 这份提案怎么样，给个评分满分10分

[fennoai]

评分结论

8.7 / 10。

关键理由

1. 问题定义准确：把“任务完成判定”从 Prompt 约束上升到 Runtime 强约束，方向正确。
2. 方案完整度高：双环（ReAct 内环 + Runtime 验证外环）、StopReason、重试熔断、结构化失败归因、Hook 生命周期都覆盖到了。
3. 边界意识好：强调不让厂商差异泄漏、不跨层执行工具，符合当前架构。
4. 可落地性较强：给了明确改动点与验收标准，测试面也比较全面。

扣分点

1. 配置与迁移策略还不够细：verification 命令来源、默认策略、仓库级覆盖优先级需要再写清。
2. Hook 治理边界还可再收紧：需要明确可见上下文、可变更范围与幂等约束，避免隐式副作用。
3. 失败分类字典建议先标准化：error_class 的枚举和映射规则若不先定，会影响后续自动修复质量。

如果你愿意，我可以下一步直接给一版“可执行的最小落地拆解清单”（按 PR 粒度）。

View job run

[Cai-Tang-www]

你是 neo-code 项目的 Go 架构实现者。请基于现有仓库，完整实现“任务验收与完成判定闭环”。

一、目标

将当前 runtime 从“模型发出 final 就结束”升级为：

1. 模型发出 final 只是“申请结束”
2. runtime 在真正接受 final 之前，必须进入 beforeAcceptFinal() hook
3. beforeAcceptFinal() 通过统一的 verifier engine 运行一组验收器
4. runtime 根据 verifier 结果决定：
   • accept final
   • intercept final and continue
   • stop as incomplete
   • stop as failed
5. 所有决定都必须有结构化 stop reason、事件和日志
6. 第一阶段先以 Todo 收敛为最小验收条件，再支持文件存在、命令成功、git diff、build/test/lint 等验证器
7. 保持现有 runtime / todo / subagent / security 边界，不推翻现有架构

---

二、核心原则

1. 模型文本 final 不是系统完成条件
2. 真正完成必须由 runtime 验收层决定
3. Hook 负责拦 final，Verifier 负责判断能否 final
4. Todo completed 不是唯一终态，terminal state 包括：
   • completed
   • failed
   • canceled
5. blocked 要区分：
   • agent 可继续推进的 blocked -> continue
   • 需要外部输入/审批的 blocked -> incomplete / waiting
6. 必须避免死循环，支持：
   • max-turn
   • no-progress breaker
   • final intercepted repeatedly
7. 先做单会话单任务稳定闭环，不做 DAG / 多 subagent 并发扩展

---

三、目标主链路

把 runtime 主循环升级为：

User Input
-> Plan / Todo update
-> Execute Tools / SubAgent
-> Model proposes final
-> beforeAcceptFinal()
-> run verifier engine
-> acceptance decision
-> accept / continue / incomplete / failed
-> emit final runtime event

其中：

• 模型提出 final 后，不可直接 agent_done
• 只有 acceptance decision = accepted 才允许真正结束

---

四、要新增的核心模块

请新增以下目录与文件：

internal/runtime/acceptance/
types.go
hook.go
engine.go
policy.go
stop_reason.go

internal/runtime/verify/
verifier.go
types.go
todo_convergence.go
file_exists.go
content_match.go
command_success.go
git_diff.go
build.go
test.go
lint.go

docs/
task-acceptance-design.md
verifier-engine-design.md
runtime-finalization-flow.md

---

五、核心设计

5.1 beforeAcceptFinal Hook

新增 runtime hook：

func (s *Service) beforeAcceptFinal(ctx context.Context, input FinalAcceptanceInput) (AcceptanceDecision, error)

职责：

1. 收集当前 run 的最终验收上下文
2. 调用 acceptance engine
3. 返回决策：
   • accepted
   • continue
   • incomplete
   • failed

该 hook 是唯一允许 runtime 接受模型 final 的入口。

任何 provider / model 的 final signal 都必须先经过此 hook。

---

5.2 AcceptanceDecision

定义统一决策类型：

type AcceptanceStatus string

const (
AcceptanceAccepted AcceptanceStatus = "accepted"
AcceptanceContinue AcceptanceStatus = "continue"
AcceptanceIncomplete AcceptanceStatus = "incomplete"
AcceptanceFailed AcceptanceStatus = "failed"
)

type AcceptanceDecision struct {
Status AcceptanceStatus
StopReason string
UserVisibleSummary string
InternalSummary string
ContinueHint string
VerifierResults []VerificationResult
HasProgress bool
Retryable bool
WaitingExternal bool
}

语义要求：

• accepted:
  当前 run 允许真正结束
• continue:
  拦截模型 final，继续下一轮推理
• incomplete:
  当前 run 不应继续推理，但不能算完成，应以未完成结束
• failed:
  当前 run 已明确失败，应以失败结束

---

5.3 VerificationResult

定义统一验证输出：

type VerificationStatus string

const (
VerificationPass VerificationStatus = "pass"
VerificationSoftBlock VerificationStatus = "soft_block"
VerificationHardBlock VerificationStatus = "hard_block"
VerificationFail VerificationStatus = "fail"
)

type VerificationResult struct {
Name string
Status VerificationStatus
Summary string
Reason string
Retryable bool
WaitingExternal bool
Evidence map[string]any
}

说明：

• pass:
  该 verifier 通过
• soft_block:
  当前不能 accept final，但 agent 仍可继续推进
• hard_block:
  当前不能 accept final，而且继续推进意义不大，需要 incomplete / waiting
• fail:
  明确失败，应结束为 failed

---

5.4 Verifier 接口

定义统一接口：

type FinalVerifier interface {
Name() string
VerifyFinal(ctx context.Context, input FinalVerifyInput) (VerificationResult, error)
}

type FinalVerifyInput struct {
SessionID string
RunID string
TaskID string
Workdir string
Messages []MessageLike
Todos []TodoSnapshot
LastAssistantFinal string
ToolResults []ToolResultLike
RuntimeState RuntimeStateSnapshot
Metadata map[string]any
}

注意：

• verifier 不直接改状态
• verifier 只输出证据和判断
• runtime 根据多个 verifier 的结果做最终 acceptance decision

---

六、第一阶段必须实现的 verifier

6.1 TodoConvergenceVerifier（P0，必须先做）

目标：
在模型尝试 final 时，检查当前 required todos 是否都已进入 terminal state。

terminal state:

• completed
• failed
• canceled

非 terminal state:

• pending
• in_progress
• blocked

实现要求：

1. 仅检查“当前 run 负责收口的 required todos”
2. 不要把所有历史 todo 一起算进去
3. blocked 要分两类：
   • 可继续推进 -> soft_block
   • 等待外部输入/审批 -> hard_block
4. 所有 required todos terminal 时 -> pass
5. 有 pending / in_progress -> soft_block
6. 有 blocked 且 waiting external -> hard_block

建议返回 evidence：

evidence:

• total_required_todos
• terminal_count
• pending_ids
• in_progress_ids
• blocked_ids
• waiting_external_ids

---

6.2 FileExistsVerifier（P1）

适用：

• create_file
• docs
• config
• scaffold

能力：

• 路径是否存在
• 是否为文件
• 是否非空
• 可选：是否命中预期路径

返回：

• pass / fail / hard_block

---

6.3 ContentMatchVerifier（P1）

适用：

• create_file
• docs
• config

能力：

• 文件内容是否非空
• 是否包含 required strings / sections
• 可选：语法可解析（JSON/YAML/Go）

返回：

• pass / fail

---

6.4 CommandSuccessVerifier（P1）

适用：

• build
• test
• lint
• typecheck
• migration
• generate

能力：

• 检查命令退出码
• 记录 stdout/stderr 摘要
• 抽取 error marker

返回：

• pass / fail / soft_block

---

6.5 GitDiffVerifier（P1）

适用：

• edit_code
• fix_bug
• refactor

能力：

• 检查是否真的有改动
• changed files 是否存在
• 是否命中目标路径
• diff 不是空
• 可选：改动量是否超阈值

返回：

• pass / fail

---

6.6 BuildVerifier / TestVerifier / LintVerifier（P1）

适用：

• 代码任务

能力：

• 绑定对应命令验证结果
• 若没有执行过对应命令，可返回 soft_block，要求继续执行验证
• 若执行失败，返回 fail 或 soft_block（按配置）

---

七、Acceptance Engine 聚合规则

请实现：

type Engine struct {
verifiers []FinalVerifier
policy AcceptancePolicy
}

func (e *Engine) EvaluateFinal(ctx context.Context, input FinalVerifyInput) (AcceptanceDecision, error)

聚合规则如下：

1. 如果任一 verifier 返回 fail
   -> AcceptanceFailed

2. 否则如果任一 verifier 返回 hard_block
   -> AcceptanceIncomplete

3. 否则如果任一 verifier 返回 soft_block
   -> AcceptanceContinue

4. 否则全部 pass
   -> AcceptanceAccepted

补充规则：

• 若连续多次被 AcceptanceContinue 且没有 todo/tool 状态变化，则触发 no-progress -> AcceptanceIncomplete
• 若达到 max-turn，则不再 continue，直接 AcceptanceIncomplete 或 AcceptanceFailed（按 stop reason）

---

八、TaskType 到 Verifier 的映射策略

请实现 task policy：

type TaskType string

const (
TaskTypeUnknown TaskType = "unknown"
TaskTypeCreateFile TaskType = "create_file"
TaskTypeEditCode TaskType = "edit_code"
TaskTypeFixBug TaskType = "fix_bug"
TaskTypeRefactor TaskType = "refactor"
TaskTypeDocs TaskType = "docs"
TaskTypeConfig TaskType = "config"
)

type AcceptancePolicy interface {
ResolveVerifiers(input FinalVerifyInput) []FinalVerifier
}

第一版映射如下：

1. unknown

   • TodoConvergenceVerifier

2. create_file

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier

3. docs

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier

4. config

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier
   • CommandSuccessVerifier（若存在 parse/check 命令）

5. edit_code

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • BuildVerifier（若配置）
   • TestVerifier（若配置）

6. fix_bug

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • TestVerifier
   • BuildVerifier

7. refactor

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • BuildVerifier
   • TestVerifier
   • LintVerifier（可选）

---

九、Runtime 主循环改造要求

在 runtime 主循环中，找到模型发出 final 或 assistant_done 的位置，改造成：

1. provider 返回 assistant final content
2. runtime 暂存该 final content
3. 不直接 emit agent_done
4. 调用 beforeAcceptFinal()
5. 根据 AcceptanceDecision 执行：

accepted

• emit verification_finished
• emit acceptance_decided(status=accepted)
• emit stop_reason_decided(reason=accepted)
• append assistant message
• persist session
• emit agent_done
• end run

continue

• emit verification_finished
• emit acceptance_decided(status=continue)
• 注入一条 system reminder / runtime reminder：
  "There are unfinished required todos or unmet acceptance checks. Continue execution. Do not finalize yet."
• 继续下一轮推理
• 若本轮无新增进展，记录 no-progress counter

incomplete

• emit verification_finished
• emit acceptance_decided(status=incomplete)
• emit stop_reason_decided(reason=...)
• append final assistant summary（应告知未完成原因）
• persist session
• emit agent_done
• end run

failed

• emit verification_finished
• emit acceptance_decided(status=failed)
• emit stop_reason_decided(reason=...)
• append final assistant summary（失败原因）
• persist session
• emit agent_done
• end run

---

十、No Progress 与 Max Turn

请补齐并统一如下逻辑：

no-progress

连续 N 轮（默认 2 或 3）满足以下全部条件：

• final 被拦截
• todo 状态无变化
• tool result 无新增
• verifier 结果无改善

则不再 continue，转为 incomplete

stop_reason:

• no_progress_after_final_intercept

max-turn

达到 max-turn 后：

• 不再允许 continue
• 即使 todo 未收敛，也必须结束
• stop_reason:
  • max_turn_exceeded_with_unconverged_todos
  • max_turn_exceeded_with_failed_verification

---

十一、Todo 的 required / optional / terminal 规则

请完善 Todo 模型支持以下语义：

1. required: bool

   • 默认 true
   • optional todo 不拦 final

2. terminal states:

   • completed
   • failed
   • canceled

3. non-terminal:

   • pending
   • in_progress
   • blocked

4. blocked_reason

   • internal_dependency
   • permission_wait
   • user_input_wait
   • external_resource_wait
   • unknown

规则：

• blocked_reason = permission_wait / user_input_wait / external_resource_wait
  -> waiting external
• 其它 blocked 先按 soft_block 处理

---

十二、SubAgent 契约收口要求

必须保证：

1. subagent completed 不是 task accepted
2. subagent 的输出必须回灌到 todo / tool result / verifier context
3. subagent 如果执行完，但其 todo 未 terminal，不允许最终 accept
4. subagent 相关 todo 进入 required todo 集合后，必须参与 TodoConvergenceVerifier

请补齐：

• subagent result contract
• subagent writeback to todo
• subagent failure / cancel / blocked handling

---

十三、事件协议要求

请在现有 runtime event 基础上新增：

• verification_started
• verification_finished
• acceptance_decided

并扩展 stop_reason_decided 的 reason 枚举，至少包含：

• accepted
• todo_not_converged
• todo_waiting_external
• verification_failed
• no_progress_after_final_intercept
• max_turn_exceeded_with_unconverged_todos
• max_turn_exceeded_with_failed_verification

payload 要求：

• payload_version 与现有机制兼容
• 包含 session_id / run_id / task_id
• 包含 verifier_results 摘要
• 包含 acceptance_status

---

十四、文档要求

新增并补齐：

docs/task-acceptance-design.md

必须包含：

• 背景问题
• 为什么模型 final 不能直接等于完成
• acceptance / verification / completion 的区别
• 状态机
• stop reason 设计
• 与 todo / subagent / runtime 的关系

docs/verifier-engine-design.md

必须包含：

• verifier 接口
• verifier 分类
• 聚合规则
• task policy 映射

docs/runtime-finalization-flow.md

必须包含：

• 原有流程
• 新流程
• beforeAcceptFinal 的插入点
• continue / incomplete / failed / accepted 的分支图

---

十五、测试要求

必须补齐测试，不允许只写实现。

至少包括：

15.1 TodoConvergenceVerifier

• all terminal -> pass
• pending exists -> soft_block
• in_progress exists -> soft_block
• blocked internal dependency -> soft_block
• blocked permission wait -> hard_block
• optional todos ignored

15.2 Acceptance Engine

• any fail -> failed
• any hard_block and no fail -> incomplete
• any soft_block and no fail/hard_block -> continue
• all pass -> accepted

15.3 Runtime Hook

• final accepted path
• final intercepted -> continue path
• final intercepted -> no progress -> incomplete
• final intercepted -> max turn -> incomplete

15.4 File / Command / Git Verifier

• file exists / missing
• command success / failure
• git diff exists / empty

15.5 Session / Event

• verification_started emitted
• verification_finished emitted
• acceptance_decided emitted
• stop_reason_decided reason correct

---

十六、验收标准（必须达成）

实现完成后，以下场景必须通过：

场景 A：创建文件任务

用户要求创建文件。
当模型发出 final 时：

• 文件不存在 -> 不允许 final
• 文件存在但空 -> 不允许 final
• 文件存在且内容满足要求 -> 允许 final

场景 B：代码修改任务

用户要求修改代码。
当模型发出 final 时：

• 无 git diff -> 不允许 final
• 有 diff 但测试未跑 -> 根据策略继续
• 有 diff 且测试/构建通过 -> 允许 final

场景 C：Todo 未完成

存在 required todo 为 pending / in_progress。
模型发出 final。
runtime 必须拦截 final 并继续，而不是直接 agent_done。

场景 D：Todo 等待外部输入

存在 blocked todo，reason=user_input_wait。
模型发出 final。
runtime 不应盲目 continue，应以 incomplete/waiting 结束，并告诉用户还缺什么。

场景 E：连续无进展

模型连续发 final，todo 一直未收敛且无新工具结果。
runtime 必须熔断，不能无限循环。

场景 F：SubAgent 执行结束但 todo 未收敛

subagent 输出 completed，但其 required todo 未 terminal。
runtime 不允许直接 accept final。

---

十七、实现风格要求

1. 保持 Go 风格，接口清晰
2. 不在 hook 里硬编码所有规则，规则要下沉到 verifier
3. Hook 只负责触发和收口
4. Verifier 只负责判断，不负责直接改状态
5. 所有新增 stop reason、event、status 都要有注释
6. 代码改动尽量小步、局部、可测试
7. 不做 DAG 并发扩展，不做异步审批扩展
8. 当前只实现单会话、单主链路稳定闭环

---

十八、交付要求

请输出：

1. 修改后的代码
2. 新增文件列表
3. 关键设计说明
4. 测试说明
5. 哪些地方保留为后续扩展点

@xgopilot 我的这份实现方案和这个issue相性怎么样，如果要给两个的实现方案打分，分别是多少分满分10分

[fennoai]

相性结论

你这版实现方案与 Issue #435 高度一致，属于“同方向、同边界、同闭环目标”的关系。

基于当前仓库实现现状（completion gate、stop_reason、run.go 终止路径、todo 结构、ExecuteSystemTool/权限链路）做对照后，结论是：

• 目标一致性：高
• 架构边界一致性：高
• 可落地性：中高（主要风险在配置与权限交互）

两个方案打分（满分 10）

1. Issue RFC Proposal: Runtime 任务完成判定闭环与 Hook 扩展层（确定性验证 + ReAct 内循环） #435 RFC 正文方案：8.9 / 10
2. 你这条评论里的实现方案（扩展版）：9.3 / 10

为什么你的实现版更高

1. 把 beforeAcceptFinal() 作为唯一收口入口，语义更硬，更容易避免“模型 final 直接结束”的漏判。
2. 把 accept/continue/incomplete/failed 决策面显式化，且给了 VerificationResult 结构，工程可测性更好。
3. 对 no-progress/max-turn/final repeated intercept 给了更完整熔断语义，和现有 progress 控制面能自然衔接。
4. 对 Todo terminal/non-terminal、blocked 外部等待、SubAgent 收口契约定义更具体，可直接映射测试用例。

当前仓库下的主要扣分点

1. 配置落地细则还不够明确：各 verifier 命令来源、启停优先级、默认策略（仓库级/全局级）需要先定。
2. 权限链路冲突要先约束：自动验证若走普通审批流会被 ask 阻塞，需为 verification engine 设计“非交互执行策略”。
3. StopReason 与事件枚举需要一次性收敛：避免后续出现多套 reason/status 同义分裂。
4. Todo 字段扩展有迁移成本：required、blocked_reason 进入持久化后，需要兼容旧会话数据与校验逻辑。

建议

先按 P0 做最小闭环：TodoConvergenceVerifier + beforeAcceptFinal + acceptance_decided/verification_* 事件 + stop_reason 扩展，稳定后再接入 file/command/git/build/test/lint verifier。

View job run

[phantom5099]

@xgopilot 先从开发角度和用户角度评估收益

[fennoai]

收益评估结论

这份 RFC 的核心收益是把“模型说完成”升级为“Runtime 验证后才完成”，方向正确且对工程化价值很高。

开发角度收益

1. 完成判定可确定化：completion gate + verification gate 把终态裁决收归 runtime，减少 prompt 漂移导致的误完成。
2. 失败归因可编排：结构化验证结果（stage/exit_code/error_class/file/line）可直接驱动下一轮修复，降低人工排障成本。
3. 控制面更可维护：新增 stop reason（验证失败/重试耗尽/步数耗尽）后，状态机语义完整，回归测试更好写。
4. 扩展成本下降：Hook registry 允许在固定生命周期点增减治理逻辑，避免反复侵入主循环。
5. 资源消耗可收敛：重试上限 + 熔断能防止无限 ReAct 循环，避免 token 和工具执行失控。
6. 主/子代理行为统一：SubAgent 产物同样走外循环验证，减少“主代理严格、子代理宽松”的一致性问题。

用户角度收益

1. 结果可信度提升：用户拿到的是“通过验收的结果”，不是“模型主观完成”。
2. 失败反馈更可用：失败会有结构化原因与定位线索，用户知道下一步该补什么。
3. 交互预期更稳定：达到重试上限会明确进入 blocked/incomplete/failed，不会长时间无效自旋。
4. 任务状态更透明：事件层可区分普通完成、验证失败、重试耗尽，便于 UI 做清晰状态展示。
5. 跨仓库体验更一致：验证命令配置化后，不同项目都能复用同一完成闭环范式。

前置条件与风险点

1. 验证命令必须可配置且默认安全（避免审批阻塞、避免误拦截）。
2. error_class 需要先标准化字典，否则自动修复质量会不稳定。
3. Hook 必须限制超时、失败策略和副作用边界，避免变成隐式脚本平台。

建议

优先按 P0 TodoConvergence -> P1 验证流水线 -> Hook 扩展 三步推进；先保证“能判定、能熔断、能解释”，再做策略扩展。

本次完成情况

• 已完成：基于 Issue、历史评论和仓库规范的收益评估（开发角度 + 用户角度）。
• 未执行：代码实现、测试、文档改动（本次触发评论仅要求评估）。

View job run

[wynxing]

@xgopilot 请按专业审查的角度，对这个issue进行分析解读，如果你有相关的技能，请调用相关技能进行这个issue的审查

[fennoai]

审查结论

这是一个正确方向的 RFC，但按当前仓库实现对照，仍有几个会影响落地稳定性的缺口。以下按优先级给出问题与修正建议。

关键问题（按严重度）

1. P0: verification gate 仍未形成“runtime 硬判定”闭环。当前完成判定核心仍是 completion gate（internal/runtime/controlplane/completion.go:24），run 中在无 tool call 且 gate 通过时直接 agent_done 返回（internal/runtime/run.go:235-239）。这会让“模型 final=完成”在某些路径仍成立。
2. P0: 停止语义不完整，且优先级未扩展。当前 StopReason 只有 FATAL/MAX_TURNS/BUDGET/COMPLETED/USER_INTERRUPT（internal/runtime/controlplane/stop_reason.go:6-17），决议逻辑也未覆盖“验证失败/重试耗尽/ReAct步耗尽”（internal/runtime/controlplane/decider.go:20-44）。
3. P0: 外循环验证若走普通工具权限链路，存在 ask 阻塞风险。ExecuteSystemTool 仍走 executeToolCallWithPermission（internal/runtime/system_tool.go:76-83），而该链路会进入等待审批态（internal/runtime/permission.go:130-143）。RFC 里“自动验证默认不弹审批”需要落到执行策略，否则闭环中断。
4. P1: Todo 重试字段已存在但 runtime 未形成调度闭环。TodoItem 已有 RetryCount/RetryLimit/FailureReason（internal/session/todo.go:60-63），但当前 runtime 主循环未消费这组字段做“失败回退 -> 重试 -> blocked 熔断”。
5. P1: verify phase 目前只是生命周期标签，不是验证流水线。RunStateVerify 已定义（internal/runtime/controlplane/phase.go），但 run.go 仅在执行后切相位（internal/runtime/run.go:289-291），没有强制 lint/typecheck/build/test 编排。
6. P1: 事件协议缺少验证闭环事件。现有事件没有 verification_started/completed/failed 等结构化载荷（internal/runtime/events.go），会导致 TUI 与可观测链路无法区分“普通完成”和“验证失败后终止”。
7. P2: 配置面尚无 verification/hook 配置位。RuntimeConfig 当前仅有 max_no_progress_streak/max_repeat_cycle_streak/max_turns/assets（internal/config/runtime.go:17-22），RFC 依赖的命令集、启停开关、失败策略与超时尚无承载位置。

落地修正建议

1. 先定义“唯一完成条件”并写入 controlplane：completed = completion_gate && verification_gate，且 verification gate 只能由 runtime verifier engine 置为通过。
2. 扩展 stop reason 与决议优先级表（明确互斥顺序）：USER_INTERRUPT > FATAL_ERROR > BUDGET_EXCEEDED > MAX_TURNS > RETRY_EXHAUSTED > VERIFICATION_FAILED > COMPLETED（可按你们策略微调，但必须固定并测试）。
3. 给外循环验证加“免审批执行模式”：仅允许受控命令白名单、受控 workdir、固定 timeout/output cap，禁止进入 ask。
4. 为验证失败定义稳定的 error_class 枚举，避免后续自动修复提示漂移。建议最小集：compile_error/test_failure/lint_failure/type_error/timeout/permission_denied/env_missing/command_not_found/unknown。
5. Hook 先做最小强类型内置机制，不开放任意脚本；每个 hook 必须声明 timeout + failure_policy + priority，并约束可读写边界。
6. 补充事件协议：至少新增 verification_started、verification_stage_finished、verification_completed、verification_failed，并在 stop_reason_decided 中保持最终唯一归因。

建议补充到验收标准

1. 验证命令执行期间不得触发人工审批事件（否则判定配置错误或执行策略错误）。
2. 同一输入在无代码变更前提下，多次运行 stop reason 必须一致（确定性）。
3. retry_exhausted 时 Todo 必须进入 blocked 且写入失败摘要，不允许继续自动消耗。
4. 子代理产出必须经过同一 verifier engine；不得绕过主 runtime 的 completion/verification gate。

建议的最小执行顺序（避免大爆炸改造）

1. StopReason + decider 扩展。
2. Runtime verification config（命令集/开关/超时/策略）与校验。
3. verifier orchestrator（先接 test/lint/build/typecheck 最小命令集）。
4. run 主循环接入“写后强制验证 + 失败回退重试 + 熔断”。
5. hook registry（先接 BeforeVerification/AfterVerification/BeforeCompletionDecision）。
6. 事件与文档、测试补齐。

说明

本次为 Issue 审查解读，仅做分析，不涉及代码改动。

View job run

[phantom5099]

@xgopilot 检查该issue与comment中的提案，有没有试图兼容或兜底旧代码的情况，有没有碎片化设计，有没有过度设计

[fennoai]

审查结论

有，需要收敛。按你提的三项给结论如下。

1) 是否存在“兼容/兜底旧代码”倾向

存在，主要有 2 处：

1. Issue 的 10. Risks and Rollback 明确写了“关闭 verification gate 与 Hook registry 后退回现有 completion gate 行为”。这本质是旧路径兜底。
2. 当前提案同时保留 completion gate 与新增 verification/acceptance 语义，如果不定义唯一裁决入口，容易形成新旧并行判定。

建议：把“回滚开关”限定为短期发布开关（带移除时间点），并在控制面定义单一终态公式，避免长期双轨。

2) 是否有碎片化设计

有明显风险，集中在“判定语义分散”：

1. completion gate、verification gate、acceptance decision、stop reason、todo state 同时存在，若无严格主从关系会出现同义分裂。
2. comment 里的模块拆分（acceptance/* + verify/* + hook + policy + event 扩展）较多，且与现有 controlplane/decider/run lifecycle 有边界重叠风险。
3. 事件面新增较多（verification_*、acceptance_decided、stop_reason_decided 扩展），若不做统一 payload/枚举治理，TUI 与 runtime 会被迫维护多套解释逻辑。

建议：先定义“唯一裁决层”（例如 decider），其余层只提供输入，不直接决定终态。

3) 是否过度设计

Issue 本体：轻度过度（可控）。
comment 扩展版：中度过度（首期范围偏大）。

主要体现在：

1. 首期同时引入大量 verifier（todo/file/content/command/git/build/test/lint）+ 多文档 + 完整 hook 体系，超出“先闭环再扩展”的最小落地。
2. 状态枚举和事件维度一次性扩得很宽，测试与迁移成本陡增。
3. SubAgent 契约收口、Todo 语义扩展、权限链路改造、验证编排并行推进，耦合面太大。

建议的收敛顺序（避免大爆炸）：

1. P0 只做 beforeAcceptFinal + TodoConvergenceVerifier + acceptance_decided + stop_reason 最小扩展。
2. P1 再接 git diff + test/build/lint（命令配置化、非交互执行）。
3. P2 再启用 Hook 分级（fail-open/fail-closed/priority/timeout）。

结论一句话

这组提案方向正确，但确实包含“旧路径兜底”和“首期范围过宽”问题；先收敛为单一裁决入口和 P0 最小闭环，才能避免碎片化与过度设计。

View job run

[phantom5099]

你是 neo-code 项目的 Go 架构实现者。请基于现有仓库，完整实现“任务验收与完成判定闭环”。

一、目标

将当前 runtime 从“模型发出 final 就结束”升级为：

1. 模型发出 final 只是“申请结束”

2. runtime 在真正接受 final 之前，必须进入 beforeAcceptFinal() hook

3. beforeAcceptFinal() 通过统一的 verifier engine 运行一组验收器

4. runtime 根据 verifier 结果决定：

   • accept final
   • intercept final and continue
   • stop as incomplete
   • stop as failed

5. 所有决定都必须有结构化 stop reason、事件和日志

6. 第一阶段先以 Todo 收敛为最小验收条件，再支持文件存在、命令成功、git diff、build/test/lint 等验证器

7. 保持现有 runtime / todo / subagent / security 边界，不推翻现有架构

二、核心原则

1. 模型文本 final 不是系统完成条件

2. 真正完成必须由 runtime 验收层决定

3. Hook 负责拦 final，Verifier 负责判断能否 final

4. Todo completed 不是唯一终态，terminal state 包括：

   • completed
   • failed
   • canceled

5. blocked 要区分：

   • agent 可继续推进的 blocked -> continue
   • 需要外部输入/审批的 blocked -> incomplete / waiting

6. 必须避免死循环，支持：

   • max-turn
   • no-progress breaker
   • final intercepted repeatedly

7. 先做单会话单任务稳定闭环，不做 DAG / 多 subagent 并发扩展

三、目标主链路

把 runtime 主循环升级为：

User Input -> Plan / Todo update -> Execute Tools / SubAgent -> Model proposes final -> beforeAcceptFinal() -> run verifier engine -> acceptance decision -> accept / continue / incomplete / failed -> emit final runtime event

其中：

• 模型提出 final 后，不可直接 agent_done
• 只有 acceptance decision = accepted 才允许真正结束

四、要新增的核心模块

请新增以下目录与文件：

internal/runtime/acceptance/ types.go hook.go engine.go policy.go stop_reason.go

internal/runtime/verify/ verifier.go types.go todo_convergence.go file_exists.go content_match.go command_success.go git_diff.go build.go test.go lint.go

docs/ task-acceptance-design.md verifier-engine-design.md runtime-finalization-flow.md

五、核心设计

5.1 beforeAcceptFinal Hook

新增 runtime hook：

func (s *Service) beforeAcceptFinal(ctx context.Context, input FinalAcceptanceInput) (AcceptanceDecision, error)

职责：

1. 收集当前 run 的最终验收上下文

2. 调用 acceptance engine

3. 返回决策：

   • accepted
   • continue
   • incomplete
   • failed

该 hook 是唯一允许 runtime 接受模型 final 的入口。

任何 provider / model 的 final signal 都必须先经过此 hook。

5.2 AcceptanceDecision

定义统一决策类型：

type AcceptanceStatus string

const ( AcceptanceAccepted AcceptanceStatus = "accepted" AcceptanceContinue AcceptanceStatus = "continue" AcceptanceIncomplete AcceptanceStatus = "incomplete" AcceptanceFailed AcceptanceStatus = "failed" )

type AcceptanceDecision struct { Status AcceptanceStatus StopReason string UserVisibleSummary string InternalSummary string ContinueHint string VerifierResults []VerificationResult HasProgress bool Retryable bool WaitingExternal bool }

语义要求：

• accepted:
  当前 run 允许真正结束
• continue:
  拦截模型 final，继续下一轮推理
• incomplete:
  当前 run 不应继续推理，但不能算完成，应以未完成结束
• failed:
  当前 run 已明确失败，应以失败结束

5.3 VerificationResult

定义统一验证输出：

type VerificationStatus string

const ( VerificationPass VerificationStatus = "pass" VerificationSoftBlock VerificationStatus = "soft_block" VerificationHardBlock VerificationStatus = "hard_block" VerificationFail VerificationStatus = "fail" )

type VerificationResult struct { Name string Status VerificationStatus Summary string Reason string Retryable bool WaitingExternal bool Evidence map[string]any }

说明：

• pass:
  该 verifier 通过
• soft_block:
  当前不能 accept final，但 agent 仍可继续推进
• hard_block:
  当前不能 accept final，而且继续推进意义不大，需要 incomplete / waiting
• fail:
  明确失败，应结束为 failed

5.4 Verifier 接口

定义统一接口：

type FinalVerifier interface { Name() string VerifyFinal(ctx context.Context, input FinalVerifyInput) (VerificationResult, error) }

type FinalVerifyInput struct { SessionID string RunID string TaskID string Workdir string Messages []MessageLike Todos []TodoSnapshot LastAssistantFinal string ToolResults []ToolResultLike RuntimeState RuntimeStateSnapshot Metadata map[string]any }

注意：

• verifier 不直接改状态
• verifier 只输出证据和判断
• runtime 根据多个 verifier 的结果做最终 acceptance decision

六、第一阶段必须实现的 verifier

6.1 TodoConvergenceVerifier（P0，必须先做）

目标： 在模型尝试 final 时，检查当前 required todos 是否都已进入 terminal state。

terminal state:

• completed
• failed
• canceled

非 terminal state:

• pending
• in_progress
• blocked

实现要求：

1. 仅检查“当前 run 负责收口的 required todos”

2. 不要把所有历史 todo 一起算进去

3. blocked 要分两类：

   • 可继续推进 -> soft_block
   • 等待外部输入/审批 -> hard_block

4. 所有 required todos terminal 时 -> pass

5. 有 pending / in_progress -> soft_block

6. 有 blocked 且 waiting external -> hard_block

建议返回 evidence：

evidence:

• total_required_todos
• terminal_count
• pending_ids
• in_progress_ids
• blocked_ids
• waiting_external_ids

6.2 FileExistsVerifier（P1）

适用：

• create_file
• docs
• config
• scaffold

能力：

• 路径是否存在
• 是否为文件
• 是否非空
• 可选：是否命中预期路径

返回：

• pass / fail / hard_block

6.3 ContentMatchVerifier（P1）

适用：

• create_file
• docs
• config

能力：

• 文件内容是否非空
• 是否包含 required strings / sections
• 可选：语法可解析（JSON/YAML/Go）

返回：

• pass / fail

6.4 CommandSuccessVerifier（P1）

适用：

• build
• test
• lint
• typecheck
• migration
• generate

能力：

• 检查命令退出码
• 记录 stdout/stderr 摘要
• 抽取 error marker

返回：

• pass / fail / soft_block

6.5 GitDiffVerifier（P1）

适用：

• edit_code
• fix_bug
• refactor

能力：

• 检查是否真的有改动
• changed files 是否存在
• 是否命中目标路径
• diff 不是空
• 可选：改动量是否超阈值

返回：

• pass / fail

6.6 BuildVerifier / TestVerifier / LintVerifier（P1）

适用：

• 代码任务

能力：

• 绑定对应命令验证结果
• 若没有执行过对应命令，可返回 soft_block，要求继续执行验证
• 若执行失败，返回 fail 或 soft_block（按配置）

七、Acceptance Engine 聚合规则

请实现：

type Engine struct { verifiers []FinalVerifier policy AcceptancePolicy }

func (e *Engine) EvaluateFinal(ctx context.Context, input FinalVerifyInput) (AcceptanceDecision, error)

聚合规则如下：

1. 如果任一 verifier 返回 fail
   -> AcceptanceFailed
2. 否则如果任一 verifier 返回 hard_block
   -> AcceptanceIncomplete
3. 否则如果任一 verifier 返回 soft_block
   -> AcceptanceContinue
4. 否则全部 pass
   -> AcceptanceAccepted

补充规则：

• 若连续多次被 AcceptanceContinue 且没有 todo/tool 状态变化，则触发 no-progress -> AcceptanceIncomplete
• 若达到 max-turn，则不再 continue，直接 AcceptanceIncomplete 或 AcceptanceFailed（按 stop reason）

八、TaskType 到 Verifier 的映射策略

请实现 task policy：

type TaskType string

const ( TaskTypeUnknown TaskType = "unknown" TaskTypeCreateFile TaskType = "create_file" TaskTypeEditCode TaskType = "edit_code" TaskTypeFixBug TaskType = "fix_bug" TaskTypeRefactor TaskType = "refactor" TaskTypeDocs TaskType = "docs" TaskTypeConfig TaskType = "config" )

type AcceptancePolicy interface { ResolveVerifiers(input FinalVerifyInput) []FinalVerifier }

第一版映射如下：

1. unknown

   • TodoConvergenceVerifier

2. create_file

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier

3. docs

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier

4. config

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier
   • CommandSuccessVerifier（若存在 parse/check 命令）

5. edit_code

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • BuildVerifier（若配置）
   • TestVerifier（若配置）

6. fix_bug

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • TestVerifier
   • BuildVerifier

7. refactor

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • BuildVerifier
   • TestVerifier
   • LintVerifier（可选）

九、Runtime 主循环改造要求

在 runtime 主循环中，找到模型发出 final 或 assistant_done 的位置，改造成：

1. provider 返回 assistant final content
2. runtime 暂存该 final content
3. 不直接 emit agent_done
4. 调用 beforeAcceptFinal()
5. 根据 AcceptanceDecision 执行：

accepted

• emit verification_finished
• emit acceptance_decided(status=accepted)
• emit stop_reason_decided(reason=accepted)
• append assistant message
• persist session
• emit agent_done
• end run

continue

• emit verification_finished
• emit acceptance_decided(status=continue)
• 注入一条 system reminder / runtime reminder：
  "There are unfinished required todos or unmet acceptance checks. Continue execution. Do not finalize yet."
• 继续下一轮推理
• 若本轮无新增进展，记录 no-progress counter

incomplete

• emit verification_finished
• emit acceptance_decided(status=incomplete)
• emit stop_reason_decided(reason=...)
• append final assistant summary（应告知未完成原因）
• persist session
• emit agent_done
• end run

failed

• emit verification_finished
• emit acceptance_decided(status=failed)
• emit stop_reason_decided(reason=...)
• append final assistant summary（失败原因）
• persist session
• emit agent_done
• end run

十、No Progress 与 Max Turn

请补齐并统一如下逻辑：

no-progress

连续 N 轮（默认 2 或 3）满足以下全部条件：

• final 被拦截
• todo 状态无变化
• tool result 无新增
• verifier 结果无改善

则不再 continue，转为 incomplete

stop_reason:

• no_progress_after_final_intercept

max-turn

达到 max-turn 后：

• 不再允许 continue

• 即使 todo 未收敛，也必须结束

• stop_reason:

  • max_turn_exceeded_with_unconverged_todos
  • max_turn_exceeded_with_failed_verification

十一、Todo 的 required / optional / terminal 规则

请完善 Todo 模型支持以下语义：

1. required: bool

   • 默认 true
   • optional todo 不拦 final

2. terminal states:

   • completed
   • failed
   • canceled

3. non-terminal:

   • pending
   • in_progress
   • blocked

4. blocked_reason

   • internal_dependency
   • permission_wait
   • user_input_wait
   • external_resource_wait
   • unknown

规则：

• blocked_reason = permission_wait / user_input_wait / external_resource_wait
  -> waiting external
• 其它 blocked 先按 soft_block 处理

十二、SubAgent 契约收口要求

必须保证：

1. subagent completed 不是 task accepted
2. subagent 的输出必须回灌到 todo / tool result / verifier context
3. subagent 如果执行完，但其 todo 未 terminal，不允许最终 accept
4. subagent 相关 todo 进入 required todo 集合后，必须参与 TodoConvergenceVerifier

请补齐：

• subagent result contract
• subagent writeback to todo
• subagent failure / cancel / blocked handling

十三、事件协议要求

请在现有 runtime event 基础上新增：

• verification_started
• verification_finished
• acceptance_decided

并扩展 stop_reason_decided 的 reason 枚举，至少包含：

• accepted
• todo_not_converged
• todo_waiting_external
• verification_failed
• no_progress_after_final_intercept
• max_turn_exceeded_with_unconverged_todos
• max_turn_exceeded_with_failed_verification

payload 要求：

• payload_version 与现有机制兼容
• 包含 session_id / run_id / task_id
• 包含 verifier_results 摘要
• 包含 acceptance_status

十四、文档要求

新增并补齐：

docs/task-acceptance-design.md

必须包含：

• 背景问题
• 为什么模型 final 不能直接等于完成
• acceptance / verification / completion 的区别
• 状态机
• stop reason 设计
• 与 todo / subagent / runtime 的关系

docs/verifier-engine-design.md

必须包含：

• verifier 接口
• verifier 分类
• 聚合规则
• task policy 映射

docs/runtime-finalization-flow.md

必须包含：

• 原有流程
• 新流程
• beforeAcceptFinal 的插入点
• continue / incomplete / failed / accepted 的分支图

十五、测试要求

必须补齐测试，不允许只写实现。

至少包括：

15.1 TodoConvergenceVerifier

• all terminal -> pass
• pending exists -> soft_block
• in_progress exists -> soft_block
• blocked internal dependency -> soft_block
• blocked permission wait -> hard_block
• optional todos ignored

15.2 Acceptance Engine

• any fail -> failed
• any hard_block and no fail -> incomplete
• any soft_block and no fail/hard_block -> continue
• all pass -> accepted

15.3 Runtime Hook

• final accepted path
• final intercepted -> continue path
• final intercepted -> no progress -> incomplete
• final intercepted -> max turn -> incomplete

15.4 File / Command / Git Verifier

• file exists / missing
• command success / failure
• git diff exists / empty

15.5 Session / Event

• verification_started emitted
• verification_finished emitted
• acceptance_decided emitted
• stop_reason_decided reason correct

十六、验收标准（必须达成）

实现完成后，以下场景必须通过：

场景 A：创建文件任务

用户要求创建文件。 当模型发出 final 时：

• 文件不存在 -> 不允许 final
• 文件存在但空 -> 不允许 final
• 文件存在且内容满足要求 -> 允许 final

场景 B：代码修改任务

用户要求修改代码。 当模型发出 final 时：

• 无 git diff -> 不允许 final
• 有 diff 但测试未跑 -> 根据策略继续
• 有 diff 且测试/构建通过 -> 允许 final

场景 C：Todo 未完成

存在 required todo 为 pending / in_progress。 模型发出 final。 runtime 必须拦截 final 并继续，而不是直接 agent_done。

场景 D：Todo 等待外部输入

存在 blocked todo，reason=user_input_wait。 模型发出 final。 runtime 不应盲目 continue，应以 incomplete/waiting 结束，并告诉用户还缺什么。

场景 E：连续无进展

模型连续发 final，todo 一直未收敛且无新工具结果。 runtime 必须熔断，不能无限循环。

场景 F：SubAgent 执行结束但 todo 未收敛

subagent 输出 completed，但其 required todo 未 terminal。 runtime 不允许直接 accept final。

十七、实现风格要求

1. 保持 Go 风格，接口清晰
2. 不在 hook 里硬编码所有规则，规则要下沉到 verifier
3. Hook 只负责触发和收口
4. Verifier 只负责判断，不负责直接改状态
5. 所有新增 stop reason、event、status 都要有注释
6. 代码改动尽量小步、局部、可测试
7. 不做 DAG 并发扩展，不做异步审批扩展
8. 当前只实现单会话、单主链路稳定闭环

十八、交付要求

请输出：

1. 修改后的代码
2. 新增文件列表
3. 关键设计说明
4. 测试说明
5. 哪些地方保留为后续扩展点

@xgopilot 解析提案中的主链路，同时分析这套方案有没有和仓库中PR或是issue冲突的地方

[fennoai]

解析结果

基于当前仓库实现，这份提案的目标主链路可落成以下闭环（并与现状一一映射）：

1. User Input -> Plan/Todo update -> Execute Tools/SubAgent
   • 现状已具备：internal/runtime/run.go 主循环 + turn_control.go 工具结果回灌 + subagent_* 执行链路。
2. Model proposes final（模型给出无 tool_call 的 assistant 文本）
   • 现状行为：在 run.go 中若无 tool call 且 completion gate 通过，会直接 emit agent_done 并结束。
3. beforeAcceptFinal()（新增唯一收口钩子）
   • 应插入到“无 tool call 分支、agent_done 前”，替代“直接完成”。
4. Verifier Engine（Todo 收敛 + 文件/命令/diff 等）
   • 现状仅有 completion gate 与工具 facts，不是 runtime 强制验收。
5. Acceptance Decision（accepted / continue / incomplete / failed）
   • 决议后统一映射到 stop reason、事件和终止动作。
6. Emit final runtime events
   • 现有 stop_reason_decided 在 run_lifecycle.go 统一发出；需扩展事件协议承载 acceptance/verifier 结果摘要。

结论：该提案方向与当前架构边界一致（runtime 负责决策，tui 只消费事件），但需要把“final=完成”从主循环中彻底替换为“final=申请验收”。

冲突分析（与现有 PR/Issue）

1. Issue #436（Run Ledger + Resume Checkpoint）: 高冲突/高耦合

• 两者都改 runtime 终止语义与阶段事实。
• 若 RFC Proposal: Runtime 任务完成判定闭环与 Hook 扩展层（确定性验证 + ReAct 内循环） #435 先做但不落 ledger/checkpoint，后续 为 Runtime 引入 Run Ledger + Resume Checkpoint #436 会二次改 run.go/run_lifecycle.go/持久化边界。
• 建议：至少预留 acceptance 决议快照结构，避免后续重复拆改。

2. Issue #384（Runtime 重规划）: 中冲突（语义字典不一致）

• NeoCode Runtime 重规划提案 #384 的 stop reason 体系（如 STOP_NO_PROGRESS）与 RFC Proposal: Runtime 任务完成判定闭环与 Hook 扩展层（确定性验证 + ReAct 内循环） #435 提案中的 reason 命名不同（如 todo_not_converged、verification_failed 等）。
• 若不先统一枚举词典，会导致 TUI/Gateway/测试断言分叉。

3. PR #430（runtime->context repository 注入）: 中冲突（代码落点重叠）

• 直接重叠文件：internal/runtime/run.go、internal/runtime/events.go。
• 语义不冲突，但极易产生合并冲突与事件字段漂移。

4. PR #434（ModelScope 配置/TUI）: 低冲突（协议消费侧）

• 若新增 stop reason/event 类型，TUI 侧 internal/tui/services/runtime_contract.go 与 internal/tui/core/app/update.go 需同步扩展；否则落到 unknown 分支。

5. PR #423（Gateway 文档与协议）: 低到中冲突（文档/协议一致性）

• runtime 新事件（verification_started/finished, acceptance_decided）需同步 gateway 对外文档，避免“实现已变、文档未变”。

关键风险点（提案内部与仓库现状）

1. 当前 TodoItem 尚无 required、blocked_reason 字段；提案依赖这两个字段做判定，属于模型层变更，需先定义兼容迁移策略。
2. stop_reason_decided 目前是 controlplane.StopReason 强类型枚举；若改成更细粒度 reason，需统一 runtime/tui/tests 常量，不建议多套字符串并存。
3. 自动验证若走 bash 普通通道可能触发 ask 审批阻塞；必须用可控的系统验证执行策略（避免闭环被人工审批打断）。

建议落地顺序（避免与现有事项冲撞）

1. P0：只落 beforeAcceptFinal + TodoConvergenceVerifier + acceptance_decided事件 + stop reason最小扩展。
2. P1：补 required/blocked_reason 与 Todo waiting-external 判定，再接 File/Git/Command verifiers。
3. P2：再扩 Hook registry（fail-open/fail-closed/timeout/priority），并与 为 Runtime 引入 Run Ledger + Resume Checkpoint #436 的 ledger/checkpoint 结构对齐。

本次范围说明

本次按你的要求仅做方案主链路解析与冲突分析，未进行代码修改、未执行测试。

View job run

[fennoai]

进度

已完成规则与现状盘点，开始进入实现阶段。

Todo

• 读取并遵循仓库规范（CLAUDE.md、AGENTS.md）
• 解析触发评论需求，拆分为可执行子任务
• 盘点现有 runtime/completion/decider/phase/todo/config/event 代码现状
• 设计并实现 acceptance + verify 双门控闭环（最小可用版本）
• 收敛 stop reason / acceptance / verification / error_class 枚举与 decider 单一真源
• 接入 beforeAcceptFinal 与 runtime 主循环拦截 final
• 接入 Todo 收敛验证与 retry exhausted 闭环
• 增加 verification non-interactive execution policy
• 扩展配置与旧数据兼容（todo required / blocked_reason）
• 补充关键测试与文档
• 本地运行格式化与测试
• 提交代码、推送分支并创建 PR
• 回复方案评分（方案相性/Issue 相性/仓库相性）

View job run

[Cai-Tang-www]

@xgopilot 看看我的这版提示词方案怎么样，打个分，和仓库，和这个issue相性如何，有无漏洞
你是 neo-code 项目的 Go 架构实现者。请基于现有仓库，完整实现“任务验收与完成判定闭环”。

一、目标

将当前 runtime 从“模型发出 final 就结束”升级为严格的“双门控完成机制”：

1. 模型发出 final 只是“申请结束”

2. runtime 在真正接受 final 之前，必须进入 beforeAcceptFinal() hook

3. 最终完成条件必须唯一且硬性定义为：

   completed = completion_gate && verification_gate

4. completion_gate 只能表示当前 ReAct/tool 回合已经自然收敛，不能单独决定完成

5. verification_gate 只能由 runtime verifier engine 置为通过，任何 provider/model final signal 都不能绕过它直接 agent_done

6. runtime 根据 verifier 结果决定：

   • accept final
   • intercept final and continue
   • stop as incomplete
   • stop as failed

7. 所有决定都必须有结构化 stop reason、事件和日志

8. 第一阶段先以 Todo 收敛为最小验收条件，再支持文件存在、命令成功、git diff、build/test/lint/typecheck 等验证器

9. 保持现有 runtime / todo / subagent / security 边界，不推翻现有架构

10. verifier 的配置来源、默认策略、启停优先级、权限执行策略、事件枚举、stop reason 枚举、todo 字段迁移兼容必须一次性设计清楚，避免后续返工

11. 必须把当前 controlplane 的 completion/stop/phase 机制统一收敛，不允许形成“旧 completion gate + 新 verifier gate”双真源并存

12. 必须显式限制兼容/回滚路径：允许短期发布灰度开关，但不得长期保留“回退到旧 completion-only 行为”的架构分支

13. 必须定义唯一终态裁决层（decider），其余模块只提供输入，不得直接决定 run 的最终终态

---

二、核心原则

1. 模型文本 final 不是系统完成条件
2. 真正完成必须由 runtime 验收层决定
3. Hook 负责拦 final，Verifier 负责判断能否 final
4. Todo completed 不是唯一终态，terminal state 包括：
   • completed
   • failed
   • canceled
5. blocked 要区分：
   • agent 可继续推进的 blocked -> continue
   • 需要外部输入/审批的 blocked -> incomplete / waiting
6. 必须避免死循环，支持：
   • max-turn
   • no-progress breaker
   • final intercepted repeatedly
   • retry exhausted
7. 先做单会话单任务稳定闭环，不做 DAG / 多 subagent 并发扩展
8. verifier 的运行不能被普通 ask 权限流阻塞，自动验证必须有“非交互执行策略”
9. StopReason、AcceptanceStatus、VerificationStatus、RuntimeEvent、ErrorClass 枚举必须一次性收敛，禁止后续再出现语义重复的新枚举
10. Todo 字段扩展必须兼容旧会话持久化数据，不能因为新增字段导致旧 session 无法加载
11. retry 不是模型层约定，而必须进入 runtime/todo 调度闭环
12. verify phase 不能只是生命周期标签，必须成为强制验证流水线
13. decider 是唯一终态裁决层（single source of truth for terminal decision）
14. completion gate、verification gate、acceptance decision、todo state、stop reason 之间必须有严格主从关系，禁止平行判定
15. runtime events、TUI、session persistence 都必须消费 decider 的统一输出，不得各自解释终态

---

三、唯一裁决层与主从关系（新增，必须严格遵守）

这是本方案的核心约束，必须实现为单一真源，防止碎片化设计。

3.1 唯一裁决层

decider 是唯一终态裁决层。

只有 decider 可以输出最终终态之一：

• completed
• continue
• incomplete
• failed

除 decider 外，任何模块不得直接决定终态。

3.2 其余层的职责严格限定如下

completion gate

只提供“当前回合是否可尝试收尾”的输入信号。

• 不能单独决定 completed
• 不能直接触发 agent_done

verifier engine

只提供验证结果输入。

• 输出 verifier results / verification gate decision
• 不能直接决定 run 终态

acceptance decision

是 decider 输出的结构化表达，不是平行判定层。

• 不得绕过 decider 独立决定 completed / failed / incomplete / continue

todo state

只提供任务收敛输入。

• 可以影响 verification gate
• 不能直接决定 run 终态

stop reason

是 decider 最终决议的编码结果。

• 不是独立判定层
• 不得由其它模块各自生成不同版本的 stop reason 真源

3.3 统一消费要求

runtime lifecycle、events、TUI、session persistence、日志都必须消费 decider 的统一输出。
不允许：

• runtime 自己判一套 completed
• TUI 自己再解释一套 completed
• persistence 落盘另一套 reason/status
• verifier engine 私自输出终态

3.4 防碎片化约束

所有 verification_、acceptance_、stop_reason_* 事件必须共享统一 payload 结构与统一枚举映射。
禁止出现：

• 多套 status
• 多套 reason
• 多套 error 分类
• 多套终态解释逻辑

---

四、兼容/回滚路径约束（新增，必须严格遵守）

4.1 允许短期发布灰度开关，但不得长期双轨

允许为了灰度发布引入短期开关，使系统可暂时 fallback 到旧 completion-only 行为。
但该开关只能是临时发布保护开关，不得成为长期架构分支。

4.2 任何 fallback 到旧路径都必须满足以下要求

1. 显式打日志
2. 显式发事件
3. 标记这是 compatibility fallback
4. 带 TODO/移除说明
5. 标注移除条件与预计移除阶段

4.3 禁止长期双真源

runtime/controlplane 内部只能存在一个最终完成判定真源。
旧 completion-only 路径不得作为长期逻辑保留。

---

五、目标主链路

把 runtime 主循环升级为：

User Input
-> Plan / Todo update
-> Execute Tools / SubAgent
-> completion gate evaluated
-> if model proposes final:
beforeAcceptFinal()
-> run verifier engine
-> verification gate decided
-> decider produces terminal decision
-> acceptance decision
-> accept / continue / incomplete / failed
-> emit final runtime event

其中：

• 模型提出 final 后，不可直接 agent_done
• 只有 completion_gate=true 且 verification_gate=true 时才允许真正结束
• completion gate 只能是必要不充分条件
• verification gate 是 runtime 最终完成的强判定真源
• decider 是唯一终态输出层

---

六、必须先收敛的现状问题（这是本任务必须修正的缺陷）

请显式修正以下问题，不允许只做表面补丁：

P0-1 completion gate 仍可能单独决定完成

当前系统中“无 tool call 且 completion gate 通过时直接 agent_done”的路径必须被替换。
要求：

• completion gate 不能再单独触发 completed
• 任何 completed 都必须经过 verification gate
• agent_done 只能在 decider 输出 acceptance decision = accepted 后发出

P0-2 StopReason 与决议优先级不完整

当前 stop reason 集合与 decider 逻辑不完整。
要求：

• 扩展并固定 stop reason 集合
• 扩展 decider 的互斥优先级表
• 所有 stop decision 必须通过统一 decider 得出

P0-3 外循环验证若走普通工具权限链路会 ask 阻塞

要求：

• verification engine 不能复用普通 ask 权限流
• 自动验证必须走 non-interactive execution policy
• 若验证命令不被允许，直接给出结构化拒绝，不得卡死等待审批

P1-4 Todo 重试字段已存在但 runtime 未形成闭环

若现有 TodoItem 已有 RetryCount / RetryLimit / FailureReason 等字段，必须：

• 接入 runtime 调度闭环
• 实现失败回退 -> 重试 -> 重试耗尽 -> blocked 熔断
• 映射到统一 stop reason 和事件

P1-5 verify phase 不能只是 phase tag

若已有 verify phase/run state，必须将其升级为强制验证流水线节点，而不是仅切换状态标签。

P1-6 事件协议缺少验证闭环事件

必须新增完整 verification 事件流，使 TUI/日志可区分：

• 普通完成
• 验证通过后完成
• 验证失败后终止
• 验证中断
• 验证阶段失败

P2-7 配置面缺少 verification/hook 配置位

必须扩展 runtime/config 结构，承载：

• verifier 命令集
• 启停开关
• fail-open/fail-closed
• timeout
• output cap
• 非交互执行策略
• hook 启停与优先级

P2-8 存在兼容旧路径长期保留的风险

要求：

• compatibility fallback 只能短期存在
• 必须有移除条件
• 不得长期并存新旧终态公式

P2-9 判定语义存在碎片化风险

要求：

• decider 成为唯一裁决层
• completion gate / verifier engine / acceptance decision / todo state / stop reason 只作为输入或输出编码，不得平行拍板

---

七、要新增或改造的核心模块

请新增或改造以下目录与文件：

internal/runtime/acceptance/
types.go
hook.go
engine.go
policy.go
stop_reason.go
decider.go
config.go
error_class.go

internal/runtime/verify/
verifier.go
types.go
orchestrator.go
todo_convergence.go
file_exists.go
content_match.go
command_success.go
git_diff.go
build.go
test.go
lint.go
typecheck.go
execution_policy.go

internal/runtime/controlplane/
completion.go # 修改：completion gate 不再单独决定完成
stop_reason.go # 修改：统一 stop reason
decider.go # 修改：扩展优先级与决议逻辑，并成为唯一裁决层
phase.go # 修改：verify phase 升级为流水线阶段

internal/config/
runtime.go # 扩展 verification/hook 配置
verification.go # 新增可选，若更利于结构化

docs/
task-acceptance-design.md
verifier-engine-design.md
runtime-finalization-flow.md
verifier-configuration-and-policy.md
todo-schema-migration.md
stop-reason-and-decision-priority.md
compatibility-fallback-lifecycle.md

---

八、核心设计

8.1 beforeAcceptFinal Hook

新增 runtime hook：

func (s *Service) beforeAcceptFinal(ctx context.Context, input FinalAcceptanceInput) (AcceptanceDecision, error)

职责：

1. 收集当前 run 的最终验收上下文
2. 调用 acceptance engine
3. 返回决策：
   • accepted
   • continue
   • incomplete
   • failed

该 hook 是唯一允许 runtime 接受 final 的入口。

任何 provider / model 的 final signal 都必须先经过此 hook。

---

8.2 双门控完成模型

请显式定义：

type CompletionGateDecision struct {
Passed bool
Reason string
}

type VerificationGateDecision struct {
Passed bool
Reason StopReason
Results []VerificationResult
}

completed 的唯一判定：

• completed = completion_gate.passed && verification_gate.passed

要求：

1. completion_gate 只判断当前回合是否达到了“可以尝试收尾”的状态
2. verification_gate 判断任务是否真正完成
3. runtime 只能在两者同时通过时 emit agent_done
4. 任何旧逻辑中直接以 completion gate passed 结束的路径都必须删掉或重构

---

8.3 AcceptanceDecision

定义统一决策类型：

type AcceptanceStatus string

const (
AcceptanceAccepted AcceptanceStatus = "accepted"
AcceptanceContinue AcceptanceStatus = "continue"
AcceptanceIncomplete AcceptanceStatus = "incomplete"
AcceptanceFailed AcceptanceStatus = "failed"
)

type AcceptanceDecision struct {
Status AcceptanceStatus
StopReason StopReason
ErrorClass ErrorClass
UserVisibleSummary string
InternalSummary string
ContinueHint string
VerifierResults []VerificationResult
HasProgress bool
Retryable bool
WaitingExternal bool
}

要求：

• StopReason 不再是裸 string，必须使用统一枚举类型
• 所有 acceptance 决策必须落到统一 stop reason 集合中
• ErrorClass 用于验证失败分类与后续自动修复提示
• AcceptanceDecision 是 decider 的结构化输出，不得作为平行判定层

---

8.4 StopReason（必须一次性收敛）

新增：

type StopReason string

const (
StopReasonUserInterrupt StopReason = "user_interrupt"
StopReasonFatalError StopReason = "fatal_error"
StopReasonBudgetExceeded StopReason = "budget_exceeded"
StopReasonMaxTurnExceeded StopReason = "max_turn_exceeded"
StopReasonRetryExhausted StopReason = "retry_exhausted"
StopReasonVerificationFailed StopReason = "verification_failed"
StopReasonAccepted StopReason = "accepted"
StopReasonTodoNotConverged StopReason = "todo_not_converged"
StopReasonTodoWaitingExternal StopReason = "todo_waiting_external"
StopReasonNoProgressAfterFinalIntercept StopReason = "no_progress_after_final_intercept"
StopReasonMaxTurnExceededWithUnconvergedTodos StopReason = "max_turn_exceeded_with_unconverged_todos"
StopReasonMaxTurnExceededWithFailedVerification StopReason = "max_turn_exceeded_with_failed_verification"
StopReasonVerificationConfigMissing StopReason = "verification_config_missing"
StopReasonVerificationExecutionDenied StopReason = "verification_execution_denied"
StopReasonVerificationExecutionError StopReason = "verification_execution_error"
StopReasonCompatibilityFallback StopReason = "compatibility_fallback"
)

要求：

1. runtime 内部一律使用该枚举
2. 事件 payload、日志、session 持久化、TUI 展示都复用该枚举值
3. 禁止再引入等价但不同名的 stop reason

---

8.5 StopReason 决议优先级（必须固定并测试）

定义固定优先级：

USER_INTERRUPT

FATAL_ERROR
BUDGET_EXCEEDED
MAX_TURNS
RETRY_EXHAUSTED
VERIFICATION_FAILED
COMPLETED

允许你根据现有架构做轻微映射，但必须满足：

1. 优先级固定
2. 互斥顺序固定
3. 有单元测试覆盖
4. TUI / logs / events / persisted session 使用同一套结果

若更细粒度 reason 出现，应先映射到该优先级框架，再做最终展示。

---

8.6 ErrorClass（新增，必须实现）

为验证失败定义稳定错误分类：

type ErrorClass string

const (
ErrorClassCompileError ErrorClass = "compile_error"
ErrorClassTestFailure ErrorClass = "test_failure"
ErrorClassLintFailure ErrorClass = "lint_failure"
ErrorClassTypeError ErrorClass = "type_error"
ErrorClassTimeout ErrorClass = "timeout"
ErrorClassPermissionDenied ErrorClass = "permission_denied"
ErrorClassEnvMissing ErrorClass = "env_missing"
ErrorClassCommandNotFound ErrorClass = "command_not_found"
ErrorClassUnknown ErrorClass = "unknown"
)

要求：

• verification failure 必须尽量映射到该集合
• 不允许直接暴露任意文本作为最终错误分类真源
• 后续自动修复提示与统计基于该枚举

---

8.7 VerificationResult

定义统一验证输出：

type VerificationStatus string

const (
VerificationPass VerificationStatus = "pass"
VerificationSoftBlock VerificationStatus = "soft_block"
VerificationHardBlock VerificationStatus = "hard_block"
VerificationFail VerificationStatus = "fail"
)

type VerificationResult struct {
Name string
Status VerificationStatus
Summary string
Reason string
ErrorClass ErrorClass
Retryable bool
WaitingExternal bool
Evidence map[string]any
}

说明：

• pass: 该 verifier 通过
• soft_block: 当前不能 accept final，但 agent 仍可继续推进
• hard_block: 当前不能 accept final，而且继续推进意义不大，需要 incomplete / waiting
• fail: 明确失败，应结束为 failed

---

8.8 Verifier 接口

定义统一接口：

type FinalVerifier interface {
Name() string
VerifyFinal(ctx context.Context, input FinalVerifyInput) (VerificationResult, error)
}

type FinalVerifyInput struct {
SessionID string
RunID string
TaskID string
Workdir string
Messages []MessageLike
Todos []TodoSnapshot
LastAssistantFinal string
ToolResults []ToolResultLike
RuntimeState RuntimeStateSnapshot
Metadata map[string]any
VerificationConfig VerificationConfig
}

注意：

• verifier 不直接改状态
• verifier 只输出证据和判断
• runtime 根据多个 verifier 的结果做最终 acceptance decision
• verifier 所需执行策略、命令、启停状态、作用域配置都从 VerificationConfig 读取，禁止散落硬编码

---

九、Verifier 配置与默认策略（必须实现）

9.1 配置目标

需要明确：

1. 各 verifier 的命令来源
2. 启停优先级
3. 默认策略
4. 配置作用域
5. 缺省行为

9.2 配置作用域与优先级

支持两级配置：

1. 全局级：~/.neocode/config.yaml
2. 仓库级：<repo>/.neocode/verification.yaml 或等效仓库内配置文件

优先级：

• 仓库级 > 全局级 > 内建默认值

9.3 RuntimeConfig / VerificationConfig 结构

必须扩展 runtime 配置承载 verification / hook 配置位。

例如：

type VerificationConfig struct {
Enabled bool
DefaultTaskPolicy string
FinalIntercept bool
MaxNoProgress int
MaxRetries int
Verifiers map[string]VerifierConfig
ExecutionPolicy VerificationExecutionPolicy
Hooks HookConfig
}

type VerifierConfig struct {
Enabled bool
Required bool
Command string
TimeoutSec int
OutputCapBytes int
Scope string
FailOpen bool
FailClosed bool
}

type HookConfig struct {
BeforeVerification HookSpec
AfterVerification HookSpec
BeforeCompletionDecision HookSpec
}

type HookSpec struct {
Enabled bool
TimeoutSec int
FailurePolicy string
Priority int
}

要求：

• verifier 可单独启停
• verifier 命令来源必须可配置
• 每个 verifier 的默认启用状态必须明确
• command 为空时的行为必须明确（soft_block / fail / skip）
• FailOpen 与 FailClosed 只允许二选一，默认策略必须写清楚
• hook 先实现强类型内置机制，不开放任意脚本执行
• 每个 hook 必须声明 timeout + failure_policy + priority

9.4 默认策略要求

第一版默认策略建议：

• TodoConvergenceVerifier: enabled=true, required=true
• FileExistsVerifier: enabled=true for create_file/docs/config
• ContentMatchVerifier: enabled=true for create_file/docs/config
• GitDiffVerifier: enabled=true for edit_code/fix_bug/refactor
• BuildVerifier/TestVerifier/LintVerifier/TypecheckVerifier: 默认 enabled=false，只有配置存在 command 时启用
• 未配置 command 的 verifier 不能 silent pass，必须走明确策略：
  • 若 required=true -> soft_block 或 fail（按 task policy）
  • 若 required=false -> skip，但要记录事件/日志

---

十、Verification Engine 的非交互权限策略（必须实现）

10.1 问题

如果 verifier 执行 build/test/lint/git 等命令仍然走普通 ask 权限流，会导致：

• final 前验收被 ask 阻塞
• verification engine 无法自动完成
• runtime 在 final 阶段卡死

10.2 解决方案

新增独立的 verification execution policy：

type VerificationExecutionPolicy struct {
Mode string
AllowNonInteractive bool
AllowReadOnlyGit bool
AllowBuildCommands bool
AllowTestCommands bool
AllowLintCommands bool
AllowTypecheckCommands bool
DenyDangerousCommands bool
AllowedCommands []string
RestrictedWorkdir string
TimeoutSec int
OutputCapBytes int
}

第一版要求：

• verification engine 执行必须走“非交互执行策略”
• 不允许 verification command 触发普通 ask
• verification engine 只允许执行低风险、白名单、可审计命令
• 默认只允许：
  • git 只读类
  • build
  • test
  • lint
  • typecheck
  • parse/check
• 明确禁止：
  • rm
  • sudo
  • 写系统目录
  • 网络副作用命令
  • 任何非白名单写命令

10.3 与普通权限流关系

要求：

1. 普通 agent tool 调用仍走原权限链路
2. verifier 命令执行不复用普通 ask，而是走 verification execution policy
3. verifier 执行必须在日志中标记为 verification_non_interactive=true
4. verifier command 若不被白名单允许，直接返回 verification_execution_denied
5. 验证命令执行期间不得触发人工审批事件；若发生，视为执行策略错误或配置错误

---

十一、第一阶段必须实现的 verifier

11.1 TodoConvergenceVerifier（P0，必须先做）

目标：
在模型尝试 final 时，检查当前 required todos 是否都已进入 terminal state。

terminal state:

• completed
• failed
• canceled

非 terminal state:

• pending
• in_progress
• blocked

实现要求：

1. 仅检查“当前 run 负责收口的 required todos”
2. 不要把所有历史 todo 一起算进去
3. blocked 要分两类：
   • 可继续推进 -> soft_block
   • 等待外部输入/审批 -> hard_block
4. 所有 required todos terminal 时 -> pass
5. 有 pending / in_progress -> soft_block
6. 有 blocked 且 waiting external -> hard_block

建议返回 evidence：

• total_required_todos
• terminal_count
• pending_ids
• in_progress_ids
• blocked_ids
• waiting_external_ids

---

11.2 FileExistsVerifier（P1）

适用：

• create_file
• docs
• config
• scaffold

能力：

• 路径是否存在
• 是否为文件
• 是否非空
• 可选：是否命中预期路径

返回：

• pass / fail / hard_block

---

11.3 ContentMatchVerifier（P1）

适用：

• create_file
• docs
• config

能力：

• 文件内容是否非空
• 是否包含 required strings / sections
• 可选：语法可解析（JSON/YAML/Go）

返回：

• pass / fail

---

11.4 CommandSuccessVerifier（P1）

适用：

• build
• test
• lint
• typecheck
• migration
• generate

能力：

• 检查命令退出码
• 记录 stdout/stderr 摘要
• 抽取 error marker

返回：

• pass / fail / soft_block

实现要求：

• 命令来源必须来自 VerificationConfig
• 不允许在 verifier 内硬编码仓库命令

---

11.5 GitDiffVerifier（P1）

适用：

• edit_code
• fix_bug
• refactor

能力：

• 检查是否真的有改动
• changed files 是否存在
• 是否命中目标路径
• diff 不是空
• 可选：改动量是否超阈值

返回：

• pass / fail

---

11.6 BuildVerifier / TestVerifier / LintVerifier / TypecheckVerifier（P1）

适用：

• 代码任务

能力：

• 绑定对应命令验证结果
• 若没有执行过对应命令，可返回 soft_block，要求继续执行验证
• 若执行失败，返回 fail 或 soft_block（按配置）

实现要求：

• 命令、超时、启停全部来自配置
• 若 required=true 且 command 未配置，必须给出明确结果，不能 silent skip

---

十二、Acceptance Engine 聚合规则

请实现：

type Engine struct {
policy AcceptancePolicy
}

func (e *Engine) EvaluateFinal(ctx context.Context, input FinalVerifyInput) (AcceptanceDecision, error)

聚合规则如下：

1. 如果任一 verifier 返回 fail
   -> AcceptanceFailed

2. 否则如果任一 verifier 返回 hard_block
   -> AcceptanceIncomplete

3. 否则如果任一 verifier 返回 soft_block
   -> AcceptanceContinue

4. 否则全部 pass
   -> AcceptanceAccepted

补充规则：

• 若连续多次被 AcceptanceContinue 且没有 todo/tool 状态变化，则触发 no-progress -> AcceptanceIncomplete
• 若达到 max-turn，则不再 continue，直接 AcceptanceIncomplete 或 AcceptanceFailed（按 stop reason）
• retry exhausted 应优先于 verification failed 进入 decider

注意：

• Engine 不应持有硬编码 verifier 列表
• verifier 选择由 AcceptancePolicy.ResolveVerifiers() 决定
• 所有聚合结果必须映射到统一 StopReason

---

十三、TaskType 到 Verifier 的映射策略

请实现 task policy：

type TaskType string

const (
TaskTypeUnknown TaskType = "unknown"
TaskTypeCreateFile TaskType = "create_file"
TaskTypeEditCode TaskType = "edit_code"
TaskTypeFixBug TaskType = "fix_bug"
TaskTypeRefactor TaskType = "refactor"
TaskTypeDocs TaskType = "docs"
TaskTypeConfig TaskType = "config"
)

type AcceptancePolicy interface {
ResolveVerifiers(input FinalVerifyInput) []FinalVerifier
}

第一版映射如下：

1. unknown

   • TodoConvergenceVerifier

2. create_file

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier

3. docs

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier

4. config

   • TodoConvergenceVerifier
   • FileExistsVerifier
   • ContentMatchVerifier
   • CommandSuccessVerifier（若存在 parse/check 命令）

5. edit_code

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • BuildVerifier（若配置）
   • TestVerifier（若配置）
   • TypecheckVerifier（若配置）

6. fix_bug

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • TestVerifier
   • BuildVerifier
   • TypecheckVerifier（若配置）

7. refactor

   • TodoConvergenceVerifier
   • GitDiffVerifier
   • BuildVerifier
   • TestVerifier
   • LintVerifier（可选）
   • TypecheckVerifier（可选）

---

十四、Todo 重试闭环（必须接入 runtime）

如果现有 TodoItem 已有：

• RetryCount
• RetryLimit
• FailureReason

则必须让 runtime 消费它们，形成闭环：

1. tool/subagent/verification 失败时，可写入 todo failure summary
2. 若 RetryCount < RetryLimit：
   • 按策略回退到 pending 或保留 blocked 再重试
   • RetryCount +1
3. 若 RetryCount >= RetryLimit：
   • todo 必须进入 blocked
   • 写入 FailureReason
   • 不允许继续自动消耗

新增或收敛 stop reason：

• retry_exhausted

要求：

• retry exhausted 必须进入 decider
• retry_exhausted 时 Todo 必须进入 blocked 且写入失败摘要
• 不允许继续自动消耗

---

十五、Runtime 主循环改造要求

在 runtime 主循环中，找到模型发出 final 或 assistant_done 的位置，改造成：

1. provider 返回 assistant final content
2. runtime 暂存该 final content
3. 不直接 emit agent_done
4. 先评估 completion_gate
5. emit verification_started
6. 调用 beforeAcceptFinal()
7. 由 decider 生成唯一终态输出
8. 根据 AcceptanceDecision 执行：

accepted

• emit verification_finished
• emit verification_completed
• emit acceptance_decided(status=accepted)
• emit stop_reason_decided(reason=accepted)
• append assistant message
• persist session
• emit agent_done
• end run

continue

• emit verification_finished
• emit acceptance_decided(status=continue)
• 注入一条 system reminder / runtime reminder：
  "There are unfinished required todos or unmet acceptance checks. Continue execution. Do not finalize yet."
• 继续下一轮推理
• 若本轮无新增进展，记录 no-progress counter

incomplete

• emit verification_finished
• emit acceptance_decided(status=incomplete)
• emit stop_reason_decided(reason=...)
• append final assistant summary（应告知未完成原因）
• persist session
• emit agent_done
• end run

failed

• emit verification_finished
• emit verification_failed
• emit acceptance_decided(status=failed)
• emit stop_reason_decided(reason=...)
• append final assistant summary（失败原因）
• persist session
• emit agent_done
• end run

---

十六、Verify Phase 不是标签，必须是流水线

若已有 RunStateVerify / verify phase，必须将其升级为真正流水线，而不是只做 phase 切换。

要求：

1. verification_started 进入 verify phase
2. verifier orchestrator 依次编排最小命令集：
   • test
   • lint
   • build
   • typecheck
     顺序可调，但必须固定并测试
3. 每个 stage 产生 stage result
4. stage failure 如何中断后续 stage 必须明确
5. verification_stage_finished 事件必须可观测

---

十七、No Progress 与 Max Turn

请补齐并统一如下逻辑：

no-progress

连续 N 轮（默认 2 或 3）满足以下全部条件：

• final 被拦截
• todo 状态无变化
• tool result 无新增
• verifier 结果无改善

则不再 continue，转为 incomplete

stop_reason:

• no_progress_after_final_intercept

max-turn

达到 max-turn 后：

• 不再允许 continue
• 即使 todo 未收敛，也必须结束
• stop_reason:
  • max_turn_exceeded_with_unconverged_todos
  • max_turn_exceeded_with_failed_verification

附加要求：

• 同一输入在无代码变更前提下，多次运行 stop reason 必须一致（确定性）

---

十八、Todo 字段扩展与迁移兼容（必须实现）

18.1 新增字段

请为 Todo 模型扩展：

1. required: bool

   • 默认 true
   • optional todo 不拦 final

2. blocked_reason

   • internal_dependency
   • permission_wait
   • user_input_wait
   • external_resource_wait
   • unknown

18.2 兼容要求

现有持久化 session / todo 数据可能没有这些字段。必须保证：

1. 旧 session 仍可正常反序列化
2. 缺失 required 时默认视为 true
3. 缺失 blocked_reason 时默认视为 unknown
4. 旧的 blocked todo 仍然可被现有逻辑识别，不得因为新增字段导致加载失败
5. 所有校验逻辑必须兼容“旧数据字段为空”的情况

18.3 迁移要求

请补齐：

• 反序列化默认值处理
• 单元测试
• 文档说明
• 如有 sqlite / json store，需要补兼容测试

---

十九、SubAgent 契约收口要求

必须保证：

1. subagent completed 不是 task accepted
2. subagent 的输出必须回灌到 todo / tool result / verifier context
3. subagent 如果执行完，但其 todo 未 terminal，不允许最终 accept
4. subagent 相关 todo 进入 required todo 集合后，必须参与 TodoConvergenceVerifier
5. 子代理产出必须经过同一 verifier engine；不得绕过主 runtime 的 completion/verification gate

请补齐：

• subagent result contract
• subagent writeback to todo
• subagent failure / cancel / blocked handling

---

二十、事件协议要求（必须一次性收敛）

请在现有 runtime event 基础上新增：

• verification_started
• verification_stage_finished
• verification_finished
• verification_completed
• verification_failed
• acceptance_decided

并扩展 stop_reason_decided 的 reason 枚举。

要求：

1. 所有 event type 使用统一命名风格
2. payload_version 与现有机制兼容
3. 不允许再新增语义重复的事件
4. acceptance 相关状态只允许通过：
   • AcceptanceStatus
   • VerificationStatus
   • StopReason
   • ErrorClass
     四套枚举表达
5. 不允许出现额外平行 status/reason/error 集合
6. stop_reason_decided 必须保持最终唯一归因
7. 所有事件必须以 decider 的统一输出为最终解释真源

payload 要求：

• 包含 session_id / run_id / task_id
• 包含 verifier_results 摘要
• 包含 acceptance_status
• 包含 stop_reason（如已决策）
• 包含 error_class（如有）

---

二十一、文档要求

新增并补齐：

docs/task-acceptance-design.md

必须包含：

• 背景问题
• 为什么模型 final 不能直接等于完成
• acceptance / verification / completion 的区别
• 双门控完成模型
• 状态机
• stop reason 设计
• 与 todo / subagent / runtime 的关系
• decider 作为唯一裁决层的说明

docs/verifier-engine-design.md

必须包含：

• verifier 接口
• verifier 分类
• orchestrator 流程
• 聚合规则
• task policy 映射

docs/runtime-finalization-flow.md

必须包含：

• 原有流程
• 新流程
• beforeAcceptFinal 的插入点
• continue / incomplete / failed / accepted 的分支图
• completion_gate vs verification_gate
• decider 的位置与输出真源关系

docs/verifier-configuration-and-policy.md

必须包含：

• 配置来源
• 仓库级 / 全局级优先级
• verifier 命令来源
• 启停规则
• required / optional verifier 行为
• non-interactive verification policy

docs/todo-schema-migration.md

必须包含：

• required / blocked_reason 新字段
• 旧数据兼容策略
• 默认值语义
• 持久化迁移注意事项

docs/stop-reason-and-decision-priority.md

必须包含：

• StopReason 全集
• 优先级表
• 决议互斥关系
• 与 ErrorClass 的关系

docs/compatibility-fallback-lifecycle.md

必须包含：

• 为什么 fallback 只能短期存在
• fallback 的触发条件
• fallback 事件与日志要求
• fallback 的移除条件
• 禁止长期双轨的原因

---

二十二、测试要求

必须补齐测试，不允许只写实现。

至少包括：

22.1 Completion vs Verification Gate

• completion gate passed but verification gate failed -> not completed
• completion gate passed and verification gate passed -> completed
• provider/model final never directly emits agent_done without verification gate

22.2 Decider as Single Source of Truth

• only decider can produce terminal outcome
• runtime / events / persistence consume same decision output
• no parallel terminal decision path remains

22.3 TodoConvergenceVerifier

• all terminal -> pass
• pending exists -> soft_block
• in_progress exists -> soft_block
• blocked internal dependency -> soft_block
• blocked permission wait -> hard_block
• optional todos ignored
• missing required field in legacy data defaults to true
• missing blocked_reason in legacy data defaults to unknown

22.4 Acceptance Engine

• any fail -> failed
• any hard_block and no fail -> incomplete
• any soft_block and no fail/hard_block -> continue
• all pass -> accepted

22.5 StopReason Decider

• priority order fixed
• retry_exhausted outranks verification_failed when both present
• completed only chosen when all higher-priority reasons absent

22.6 Runtime Hook

• final accepted path
• final intercepted -> continue path
• final intercepted -> no progress -> incomplete
• final intercepted -> max turn -> incomplete

22.7 File / Command / Git / Build/Test/Lint/Typecheck Verifier

• file exists / missing
• command success / failure
• git diff exists / empty
• required verifier missing config command -> explicit result
• disabled verifier skipped according to policy

22.8 Verification Execution Policy

• allowed build/test/lint/typecheck command runs non-interactively
• disallowed command rejected
• verification command never triggers ask flow
• verification_execution_denied stop reason emitted when needed

22.9 Verify Phase Pipeline

• verify phase is entered
• stages emit verification_stage_finished
• stage ordering deterministic
• failure path deterministic

22.10 Todo Retry Runtime Loop

• failure increments retry count
• retry before limit
• retry_exhausted -> todo blocked + summary written
• no further auto-consumption after retry exhausted

22.11 Session / Event

• verification_started emitted
• verification_finished emitted
• verification_completed emitted
• verification_failed emitted
• acceptance_decided emitted
• stop_reason_decided reason correct
• event payload uses unified enums

22.12 Todo Persistence Compatibility

• old todo json/session loads without new fields
• old blocked todo still works
• default values applied correctly

22.13 Compatibility Fallback

• fallback path emits explicit event and log
• fallback path marks compatibility mode
• fallback path is disabled by default or clearly scoped to short-term release mode

---

二十三、验收标准（必须达成）

实现完成后，以下场景必须通过：

场景 A：创建文件任务

用户要求创建文件。
当模型发出 final 时：

• 文件不存在 -> 不允许 final
• 文件存在但空 -> 不允许 final
• 文件存在且内容满足要求 -> 允许 final

场景 B：代码修改任务

用户要求修改代码。
当模型发出 final 时：

• 无 git diff -> 不允许 final
• 有 diff 但测试未跑 -> 根据策略继续
• 有 diff 且测试/构建通过 -> 允许 final

场景 C：Todo 未完成

存在 required todo 为 pending / in_progress。
模型发出 final。
runtime 必须拦截 final 并继续，而不是直接 agent_done。

场景 D：Todo 等待外部输入

存在 blocked todo，reason=user_input_wait。
模型发出 final。
runtime 不应盲目 continue，应以 incomplete/waiting 结束，并告诉用户还缺什么。

场景 E：连续无进展

模型连续发 final，todo 一直未收敛且无新工具结果。
runtime 必须熔断，不能无限循环。

场景 F：SubAgent 执行结束但 todo 未收敛

subagent 输出 completed，但其 required todo 未terminal。
runtime 不允许直接 accept final。

场景 G：验证命令未配置

任务策略要求 build/test/typecheck verifier，但 command 未配置。
系统必须给出明确可追踪结果，不能 silent pass。

场景 H：验证命令权限冲突

verifier 运行 build/test/lint/typecheck/git 等自动验证时，不应进入 ask 权限流。
若命令不在 verification 白名单内，应返回明确的 verification_execution_denied。

场景 I：旧会话兼容

加载旧 session / todo 数据时，不因新增 required / blocked_reason 字段失败。
默认值必须正确生效。

场景 J：确定性

同一输入在无代码变更前提下，多次运行 stop reason 必须一致。

场景 K：retry exhausted

retry_exhausted 时 Todo 必须进入 blocked 且写入失败摘要，不允许继续自动消耗。

场景 L：唯一裁决层

同一轮 run 中不得出现多个模块分别判定终态的情况。
最终 completed / continue / incomplete / failed 必须只来自 decider。

场景 M：兼容路径受限

若启用 compatibility fallback，必须：

• 发事件
• 记日志
• 标注 compatibility mode
• 不得默认长期启用

---

二十四、实现风格要求

1. 保持 Go 风格，接口清晰
2. 不在 hook 里硬编码所有规则，规则要下沉到 verifier / decider / policy
3. Hook 只负责触发和收口
4. Verifier 只负责判断，不负责直接改状态
5. 所有新增 stop reason、event、status、error_class 都要有注释
6. 代码改动尽量小步、局部、可测试
7. 不做 DAG 并发扩展，不做异步审批扩展
8. 当前只实现单会话、单主链路稳定闭环
9. verifier 配置、权限执行策略、事件枚举、迁移兼容、retry runtime 闭环必须一并落地，不允许留成隐含约定
10. decider 必须成为单一真源，不允许平行终态逻辑残留
11. compatibility fallback 只能短期存在，必须有移除路径

---

二十五、交付要求

请输出：

1. 修改后的代码
2. 新增文件列表
3. 关键设计说明
4. 测试说明
5. verifier 配置与默认策略说明
6. verification execution policy 说明
7. stop reason / event enum 收敛说明
8. todo 迁移兼容说明
9. retry runtime 闭环说明
10. decider 作为唯一裁决层的说明
11. compatibility fallback 的存在范围、移除条件与后续扩展点