Merge pull request #439 from Cai-Tang-www/fix/hook&verifier

feat: 实现 runtime 验收闭环与 verifier 双门控

Author: phantom5099

docs/compatibility-fallback-lifecycle.md

@@ -0,0 +1,21 @@
+# Compatibility Fallback Lifecycle
+
+## 为什么 fallback 只能短期存在
+- completion-only 旧路径会绕过 verifier gate，破坏双门控与单一裁决层。
+- 长期保留会形成双真源，增加状态不一致风险。
+
+## 触发条件
+- `runtime.verification.enabled=false` 时进入兼容路径。
+
+## 事件与日志要求
+- 兼容路径必须输出结构化 stop reason：`compatibility_fallback`。
+- acceptance 事件中保留内部摘要，标记这是 fallback 行为。
+
+## 移除条件
+- 验收与 verifier 在主链路稳定后，移除 `enabled=false` 作为常规运行路径。
+- 仅保留灰度发布窗口内的短期开关。
+
+## 禁止长期双轨原因
+- 终态语义会被分裂为“old completion-only”与“new dual-gate”两套规则。
+- TUI / runtime / persistence 难以保证统一解释，容易引发回归。
+

docs/runtime-finalization-flow.md

@@ -0,0 +1,26 @@
+# Runtime Finalization Flow
+
+## 旧流程
+- assistant final 且无 tool call 时，可直接进入完成路径。
+
+## 新流程
+- assistant final -> completion gate -> `beforeAcceptFinal` -> verifier engine -> acceptance decision -> decider stop reason -> runtime 终态。
+
+## beforeAcceptFinal 插入点
+- 在 runtime 主循环中，`len(tool_calls)==0` 的 final 候选分支。
+- 先发 `verification_started`，后执行 acceptance engine。
+
+## 分支行为
+- `accepted`: `verification_completed` -> `acceptance_decided` -> `agent_done`
+- `continue`: `verification_finished` -> 注入 runtime reminder -> 下一轮
+- `incomplete`: `acceptance_decided` + `stop_reason_decided` -> `agent_done`
+- `failed`: `verification_failed` + `acceptance_decided` + `stop_reason_decided` -> `agent_done`
+
+## completion_gate vs verification_gate
+- completion gate 只控制“能否尝试收尾”。
+- verification gate 才决定“是否允许最终完成”。
+
+## decider 位置与真源关系
+- decider 在 run 退出时统一发 `stop_reason_decided`。
+- acceptance 输出写入 runtime 终态快照，由 decider 统一编码原因。
+

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

@@ -0,0 +1,31 @@
+# Stop Reason And Decision Priority
+
+## StopReason 全集
+- `user_interrupt`
+- `fatal_error`
+- `budget_exceeded`
+- `max_turn_exceeded`
+- `retry_exhausted`
+- `verification_failed`
+- `accepted`
+- `todo_not_converged`
+- `todo_waiting_external`
+- `no_progress_after_final_intercept`
+- `max_turn_exceeded_with_unconverged_todos`
+- `max_turn_exceeded_with_failed_verification`
+- `verification_config_missing`
+- `verification_execution_denied`
+- `verification_execution_error`
+- `compatibility_fallback`
+
+## 优先级
+- `user_interrupt` > `fatal_error` > `budget_exceeded` > `max_turn_exceeded` > `retry_exhausted` > `verification_failed` > `accepted`
+
+## 决议互斥关系
+- decider 返回单一 stop reason。
+- acceptance/verifier 只提供输入，不直接终裁。
+
+## 与 ErrorClass 的关系
+- `ErrorClass` 只描述失败分类（compile/test/lint/type/timeout/permission 等）。
+- stop reason 描述终止归因；error class 描述失败类型，二者不重复表达。
+

docs/task-acceptance-design.md

@@ -0,0 +1,38 @@
+# Task Acceptance Design
+
+## 背景问题
+- 旧流程中，模型输出 final 且无 tool call 时，runtime 可能直接完成。
+- 这会导致“文本 final”与“任务真实完成”混淆。
+
+## 为什么模型 final 不能直接等于完成
+- final 仅代表模型主观结束意图，不代表 required todo、文件产物或验证命令已满足。
+- 真实完成必须由 runtime 验收层裁决。
+
+## completion / verification / acceptance 区分
+- `completion_gate`：判断当前回合是否可尝试收尾（必要非充分）。
+- `verification_gate`：由 verifier engine 判断任务是否满足验收条件。
+- `acceptance_decision`：聚合两者输出 `accepted/continue/incomplete/failed`。
+
+## 双门控模型
+- `completed = completion_gate.passed && verification_gate.passed`
+- 任一门未通过都不能直接 `agent_done`。
+
+## 状态机
+- provider final -> `beforeAcceptFinal` -> verification -> acceptance_decided
+- `accepted` -> `agent_done`
+- `continue` -> 注入系统提醒继续推理
+- `incomplete/failed` -> 结束 run 并输出 stop reason
+
+## StopReason 设计
+- stop reason 由 controlplane decider 统一输出。
+- 新增 `verification_failed`、`todo_not_converged`、`retry_exhausted` 等枚举。
+
+## 与 todo / subagent / runtime 的关系
+- todo 是 verifier 输入，不直接决定终态。
+- subagent 完成不等于主任务完成，仍需通过 verifier gate。
+- runtime 只消费 decider 输出，不再平行判定终态。
+
+## decider 单一裁决层
+- 终态只由 decider 输出。
+- events / TUI / persistence 统一消费 decider 决议。
+

docs/todo-schema-migration.md

@@ -0,0 +1,20 @@
+# Todo Schema Migration
+
+## 新增字段
+- `required`：是否参与 final 收口拦截，默认 `true`。
+- `blocked_reason`：`internal_dependency / permission_wait / user_input_wait / external_resource_wait / unknown`。
+
+## 兼容策略
+- 旧数据缺失 `required` 时，按 `true` 处理。
+- 旧数据缺失 `blocked_reason` 时，按 `unknown` 处理。
+- 旧 blocked todo 不会因新字段缺失导致反序列化失败。
+
+## 默认值语义
+- `required=nil` 视为 required=true（兼容旧 session）。
+- `blocked_reason=""` 规整为 `unknown`。
+
+## 持久化迁移注意事项
+- `CurrentTodoVersion` 升级到 `5`。
+- 归一化流程在加载与写入两侧都应用缺省值规则。
+- 工具层 schema 与 patch 同步支持新字段，避免 runtime/工具协议漂移。
+

docs/verifier-configuration-and-policy.md

@@ -0,0 +1,28 @@
+# Verifier Configuration And Policy
+
+## 配置来源
+- 全局：`~/.neocode/config.yaml` 的 `runtime.verification`。
+- 仓库级扩展预留：`.neocode/verification.yaml`（本阶段先保留接口与策略位）。
+
+## 优先级
+- 仓库级 > 全局级 > 内建默认值（策略已按该优先级设计）。
+
+## 命令来源
+- 所有命令型 verifier 从 `runtime.verification.verifiers.<name>.command` 读取。
+- verifier 内禁止硬编码项目命令。
+
+## 启停规则
+- verifier 支持独立 `enabled/required`。
+- 未配置 command 时：
+  - required=true -> 返回显式 soft_block/fail
+  - required=false -> skip（显式结果，不 silent pass）
+
+## required / optional 行为
+- required verifier 失败会阻断 final。
+- optional verifier 缺省可跳过，但仍有事件与结果记录。
+
+## non-interactive policy
+- verifier 命令走独立 `execution_policy`，不走普通 ask 权限链路。
+- 默认白名单命令（go/git/test/lint/typecheck 等）。
+- 明确拒绝高风险命令（如 `rm`、`sudo`）。
+

docs/verifier-engine-design.md

@@ -0,0 +1,28 @@
+# Verifier Engine Design
+
+## Verifier 接口
+- `FinalVerifier{Name, VerifyFinal}`
+- 输入为 `FinalVerifyInput`（session/run/task/workdir/messages/todos/runtime state/config）。
+- 输出为 `VerificationResult`（status/reason/error_class/evidence）。
+
+## Verifier 分类
+- P0：`todo_convergence`
+- P1：`file_exists`、`content_match`、`command_success`、`git_diff`
+- P1 代码任务：`build/test/lint/typecheck`（命令驱动）
+
+## Orchestrator 流程
+- 按策略解析 verifier 列表并顺序执行。
+- 汇总 `VerificationGateDecision{Passed, Reason, Results}`。
+
+## 聚合规则
+- 任一 `fail` -> `verification_failed`
+- 否则任一 `hard_block` -> `todo_waiting_external` 或 `todo_not_converged`
+- 否则任一 `soft_block` -> `todo_not_converged`
+- 全部 `pass` -> `accepted`
+
+## Task policy 映射
+- `unknown`: todo_convergence
+- `create_file/docs`: todo_convergence + file_exists + content_match
+- `config`: todo_convergence + file_exists + content_match + command_success
+- `edit_code/fix_bug/refactor`: todo_convergence + git_diff + build/test/lint/typecheck(按策略启停)
+

internal/config/runtime.go

@@ -18,6 +18,7 @@ type RuntimeConfig struct {
 	MaxNoProgressStreak  int                 `yaml:"max_no_progress_streak,omitempty"`
 	MaxRepeatCycleStreak int                 `yaml:"max_repeat_cycle_streak,omitempty"`
 	MaxTurns             int                 `yaml:"max_turns,omitempty"`
+	Verification         VerificationConfig  `yaml:"verification,omitempty"`
 	Assets               RuntimeAssetsConfig `yaml:"assets,omitempty"`
 }
 
@@ -33,6 +34,7 @@ func defaultRuntimeConfig() RuntimeConfig {
 		MaxNoProgressStreak:  DefaultMaxNoProgressStreak,
 		MaxRepeatCycleStreak: DefaultMaxRepeatCycleStreak,
 		MaxTurns:             DefaultMaxTurns,
+		Verification:         defaultVerificationConfig(),
 		Assets:               defaultRuntimeAssetsConfig(),
 	}
 }
@@ -51,6 +53,7 @@ func (c RuntimeConfig) Clone() RuntimeConfig {
 		MaxNoProgressStreak:  c.MaxNoProgressStreak,
 		MaxRepeatCycleStreak: c.MaxRepeatCycleStreak,
 		MaxTurns:             c.MaxTurns,
+		Verification:         c.Verification.Clone(),
 		Assets:               c.Assets.Clone(),
 	}
 }
@@ -69,6 +72,7 @@ func (c *RuntimeConfig) ApplyDefaults(defaults RuntimeConfig) {
 	if c.MaxTurns <= 0 {
 		c.MaxTurns = defaults.MaxTurns
 	}
+	c.Verification.ApplyDefaults(defaults.Verification)
 	c.Assets.ApplyDefaults(defaults.Assets)
 }
 
@@ -83,6 +87,11 @@ func (c RuntimeConfig) Validate() error {
 	if c.MaxTurns < 0 {
 		return errors.New("max_turns must be greater than or equal to 0")
 	}
+	verification := c.Verification.Clone()
+	verification.ApplyDefaults(defaultVerificationConfig())
+	if err := verification.Validate(); err != nil {
+		return err
+	}
 	if err := c.Assets.Validate(); err != nil {
 		return err
 	}

internal/config/runtime_test.go

@@ -144,6 +144,27 @@ func TestRuntimeConfigValidate(t *testing.T) {
 	}).Validate(); err == nil {
 		t.Fatal("expected validation error for assets.max_session_assets_total_bytes=-1")
 	}
+
+	if err := (RuntimeConfig{
+		MaxNoProgressStreak:  1,
+		MaxRepeatCycleStreak: 1,
+		MaxTurns:             1,
+		Verification: VerificationConfig{
+			DefaultTaskPolicy: "unknown",
+			MaxNoProgress:     1,
+			MaxRetries:        0,
+			Verifiers: map[string]VerifierConfig{
+				"todo_convergence": {FailOpen: true, FailClosed: true},
+			},
+			ExecutionPolicy: VerificationExecutionPolicyConfig{
+				Mode:             "non_interactive",
+				DefaultTimeout:   1,
+				DefaultOutputCap: 1,
+			},
+		},
+	}).Validate(); err == nil {
+		t.Fatal("expected validation error for invalid verification config")
+	}
 }
 
 func TestRuntimeAssetsConfigZeroValuesResolveToDefaults(t *testing.T) {
@@ -171,3 +192,47 @@ func TestRuntimeAssetsConfigZeroValuesResolveToDefaults(t *testing.T) {
 		)
 	}
 }
+
+func TestRuntimeConfigVerificationDefaultsApplied(t *testing.T) {
+	t.Parallel()
+
+	defaults := defaultRuntimeConfig()
+	cfg := RuntimeConfig{}
+	cfg.ApplyDefaults(defaults)
+	if !cfg.Verification.EnabledValue() {
+		t.Fatalf("expected verification enabled by default")
+	}
+	if !cfg.Verification.FinalInterceptValue() {
+		t.Fatalf("expected verification final intercept enabled by default")
+	}
+	if cfg.Verification.MaxNoProgress <= 0 {
+		t.Fatalf("expected max_no_progress > 0, got %d", cfg.Verification.MaxNoProgress)
+	}
+	if len(cfg.Verification.Verifiers) == 0 {
+		t.Fatal("expected default verifiers to be populated")
+	}
+}
+
+func TestRuntimeConfigVerificationExplicitFalsePreserved(t *testing.T) {
+	t.Parallel()
+
+	defaults := defaultRuntimeConfig()
+	cfg := RuntimeConfig{
+		Verification: VerificationConfig{
+			Enabled:        boolPtrTest(false),
+			FinalIntercept: boolPtrTest(false),
+		},
+	}
+	cfg.ApplyDefaults(defaults)
+	if cfg.Verification.EnabledValue() {
+		t.Fatalf("expected explicit verification.enabled=false to be preserved")
+	}
+	if cfg.Verification.FinalInterceptValue() {
+		t.Fatalf("expected explicit verification.final_intercept=false to be preserved")
+	}
+}
+
+func boolPtrTest(value bool) *bool {
+	v := value
+	return &v
+}