文档：按当前 V1 实现重校独立验证技术方案

基于 AgentRunner、TaskCoordinator、LocalAgentExecutor、ToolPolicy、文件存储与现有测试，重写 V1 当前实现基线和实际代码落点。

校正 Worker 未提交、Validator 重验证、Snapshot 生成、Goal 投影、并行异常隔离、capability 权限、legacy examples 适配等真实边界，并把未实现能力明确归入 V2/V3。

Agent框架任务规划与独立验证技术方案.md

@@ -1,13 +1,14 @@
 # Agent框架任务规划与独立验证技术方案
 
-> 文档定位：通用 Agent 框架演进方案，不属于任何具体业务项目的技术方案  
-> 适用范围：当前仓库 `agent/agent` 框架内核  
-> 分析日期：2026-07-18  
-> 写作原则：基于真实代码说明保留什么、修改什么、如何分阶段落地；不展开业务表结构和具体业务字段
+> 文档定位：通用 Agent 框架演进方案，不属于任何具体业务项目的技术方案
+> 适用范围：当前仓库 `agent/agent` 框架内核
+> 分析日期：2026-07-18
+> 实施状态：Framework V1 已在当前仓库 `cyber-agent 0.4.0` 版本基线落地，本文以当前代码和测试为准
+> 写作原则：说清 V1 已实现什么、还有哪些边界、V2/V3 如何演进；不展开业务表结构和具体业务字段
 
 ## 一、结论
 
-现有 Agent 框架可以直接演进为一套支持“主 Agent 统一规划、Worker 执行、Validator 独立评估、主 Agent 重新决策”的通用框架，不需要整体更换成其他编排框架。
+现有 Agent 框架已经落地一套支持“主 Agent 统一规划、Worker 执行、Validator 独立评估、主 Agent 重新决策”的 V1 通用闭环，没有更换 AgentRunner，也没有引入另一套业务 Workflow 引擎。
 
 需要保留的核心能力包括：
 
@@ -20,7 +21,7 @@
 - TraceStore、事件和可视化基础；
 - ToolRegistry、RunConfig 和 AgentPreset。
 
-真正缺少的不是 Agent 执行能力，而是下面四层语义没有分开：
+V1 已经把原来混在 Trace、Goal 和自由文本结果里的四层语义分开：
 
 ```text
 Task：一个业务无关的任务是否真正解决
@@ -29,7 +30,7 @@ Validation：Validator 对某次尝试的独立评估
 Decision：主 Agent 对评估结果做出的最终决定
 ```
 
-框架演进后的关键规则是：
+当前 `explicit_validation` 模式的关键规则是：
 
 > Worker 运行结束不等于 Task 完成；Validator 评估通过也不等于 Task 完成；只有主 Agent 明确接受以后，Task 才能完成。
 
@@ -51,7 +52,7 @@ Decision：主 Agent 对评估结果做出的最终决定
 - 控制 Planner、Worker、Validator 的工具权限；
 - 管理 Agent 会话生命周期和上下文隔离；
 - 保存 Task、Attempt、Validation、Decision 和 Trace；
-- 提供通用事件、API、SDK、恢复和观测能力。
+- V1 提供 Python 内核、规划工具、文件存储和通用事件；公开 Task HTTP API、跨进程恢复和分布式观测属于 V2/V3。
 
 ### 2.2 框架不负责什么
 
@@ -75,7 +76,7 @@ Decision：主 Agent 对评估结果做出的最终决定
 业务项目 B ─┼──> Agent Framework
 业务项目 C ─┘
 
-Agent Framework 不 import、不读取、不假设任何业务项目的内部代码和数据结构
+Orchestration 内核不 import、不假设任何具体业务模块和数据结构
 ```
 
 业务项目通过配置和接口向框架注入：
@@ -88,209 +89,134 @@ Agent Framework 不 import、不读取、不假设任何业务项目的内部代
 - 业务侧的验收条件；
 - 人工审批和发布动作。
 
-旧的 `examples.{project_name}.run` 动态加载已从 `trace/run_api.py` 迁移到 Host 侧 legacy adapter；框架内核只依赖 `ProjectEnvironmentResolver` 端口。具体项目启动方式和旧内容评分器都由 Host 组装，框架内核不 import `examples` 或任何业务包。
+旧的 `examples.{project_name}.run` 动态加载已从 `trace/run_api.py` 迁移到 Host 侧 legacy adapter；Orchestration 内核只依赖 `ProjectEnvironmentResolver` 端口，不 import `examples` 或具体业务包。为保持旧入口兼容，源码中的可选 `trace/examples_api.py` 仍会在 Host 注册该路由时扫描 `examples/` 并读取项目 Prompt；这是 legacy 适配层边界，不属于新编排协议。
 
-## 三、当前框架真实能力
+## 三、V1 当前实现基线
 
-### 3.1 AgentRunner 可以继续作为统一执行引擎
+### 3.1 三种角色共用 AgentRunner
 
-`agent/agent/core/runner.py` 已经实现模型调用、工具调用、消息循环、Trace 写入、停止和恢复等能力。
+Planner、Worker 和 Validator 都通过 `agent/agent/core/runner.py` 中的同一套 AgentRunner 模型循环执行。角色不是调用方传入的自由字段，而是由 AgentPreset 决定。
 
-Planner、Worker 和 Validator 可以继续使用同一个 AgentRunner，但必须拥有不同的：
+`explicit_validation` 启动时，Runner 会：
 
-- 角色身份；
-- System Prompt；
-- 工具权限；
-- 上下文来源；
-- 最大运行轮次；
-- 结果协议；
-- 任务完成权限。
+- 要求已装配 TaskCoordinator，否则直接启动失败；
+- 根据 preset 解析 planner、worker 或 validator 角色；
+- 强制关闭并发 Tool Call；
+- 把不可覆盖的角色契约追加到 System Prompt；
+- 用同一份已解析权限同时过滤 Tool Schema 并校验真实执行。
 
-不需要为 Validator 再开发另一套 Agent 执行器。
+### 3.2 Trace 身份和保护上下文已落地
 
-### 3.2 Trace 已经支持父子 Agent 关系
+Trace 已增加 `agent_role`，旧 Trace 缺省读为 `legacy`。Worker Trace 保存 root trace、task、spec version 和 attempt 身份；Validator Trace 额外保存 snapshot 和 validation 身份。
 
-`agent/agent/trace/models.py` 中的 Trace 已经保存：
+Host 传入的 context 会先合并，但 role、task_id、attempt_id、validation_id 和 coordinator 等框架字段最后由 Runner 覆盖，业务不能伪造。
 
-- `agent_type`；
-- `parent_trace_id`；
-- `parent_goal_id`；
-- 运行状态；
-- 消息、工具调用、成本和耗时；
-- 可扩展的 context。
+### 3.3 Task Ledger 已成为唯一状态真相
 
-因此可以继续使用：
+`agent/agent/orchestration/models.py` 已定义 Task、TaskSpec、Attempt、ArtifactSnapshot、ValidationReport 和 PlannerDecision。`TaskCoordinator` 是唯一 Ledger 写入入口。
 
-```text
-主 Agent = 主 Trace
-Worker = Worker Sub-Trace
-Validator = Validator Sub-Trace
-```
-
-不需要另造会话系统，但需要在 Trace context 中增加稳定的任务身份和角色身份，用于权限校验和恢复。
-
-### 3.3 GoalTree 已经具备动态规划基础
-
-`agent/agent/trace/goal_models.py` 和 `goal_tool.py` 已支持：
-
-- 创建顶层 Goal；
-- 创建子 Goal；
-- 切换当前 Goal；
-- 完成或放弃 Goal；
-- 使用父子关系表达任务树。
-
-主 Agent 可以在执行期间重新规划和拆分任务，不需要预先生成一张固定流程图。
-
-### 3.4 Worker 已经支持新建和有限续用上下文
+GoalTree 仍保留任务树展示和焦点能力，但 explicit 模式不向 Planner 暴露旧 `goal` 写入工具。Coordinator 先更新 Ledger，再投影 Goal 状态；Ledger 仍是唯一状态真相，后续可用 `reconcile_goal_tree()` 修复不一致。V1 已隔离 Attempt 创建后的投影异常，但其他投影点失败仍可能表现为“Ledger 已提交、当前工具调用报错”；统一 best-effort 隔离属于后续加固项。
 
-`agent/agent/tools/builtin/subagent.py` 默认会为 Worker 创建新 Sub-Trace，也支持使用 `continue_from` 恢复已有 Trace。
+### 3.4 Worker 和 Validator 通过 LocalAgentExecutor 运行
 
-这可以继续承担：
+`agent/agent/orchestration/executor.py` 为两种角色创建本地 Sub-Trace：
 
-- 新 Attempt 默认使用新 Worker 上下文；
-- 同一个 Task、同一个版本的局部返修有限续用原 Worker；
-- 换人、改题、拆题时创建新 Worker。
+- 新 Worker Attempt 默认新 Trace；仅 repair 可经 Coordinator 校验后续用原 Worker Trace；
+- 每次 Validation 都创建新 Validator Trace；
+- Worker 必须以 `submit_attempt` 结束；
+- Validator 必须以 `submit_validation` 结束；
+- 两个提交工具都是 terminal tool，成功提交一次后立即结束当前 Agent Loop。
 
-### 3.5 框架已经支持多 Worker 并行
+V1 explicit 只支持本地 Sub-Trace，`remote_*` Worker 或 Validator 会被拒绝；远程 Agent 仍走 legacy 路径。
 
-当前 `agent()` 工具能够同时运行多个 Sub-Trace。
+### 3.5 独立 Task 批量调度已实现
 
-新框架继续允许没有依赖关系的 Task 并行，但不把“并行”理解成“所有 Task 都可以同时跑”。存在先后依赖的 Task 仍由主 Agent 和 Coordinator 顺序推进。
+`dispatch_tasks` 由 Coordinator 直接为每个 Task 保留独立 Attempt，再以 `asyncio.Semaphore` 限制并行度。每个分支都运行自己的 Worker→Validator 周期，按输入 task_ids 顺序返回 TaskCycleResult。
 
-不过，当前代码只具备“同时启动多个 Sub-Trace”的并发能力，还不具备可靠的并行任务调度语义：
+TaskConflict、单个 Task 预留异常和单个执行周期内的 Artifact/框架异常会按 Task 归一化，不会中断同批 sibling。但所有分支返回后，批次级幂等结果写入失败仍会使整次工具调用报错，持续 Store 故障也不保证能返回逐 Task 结果。V1 不生成“整批成功”的聚合业务状态。
 
-- 多 Worker 聚合采用“任一分支成功，整体就算完成”的规则；
-- Worker 并行开关没有与 RunConfig 的实际配置正确连接；
-- `_get_allowed_tools(single, ...)` 没有真正根据 single 区分权限，多任务只读约束没有生效；
-- 分支结果会继续回写同一个父 Goal，无法分别验证和决策。
+### 3.6 端口、默认适配器和兼容边界已明确
 
-新 Coordinator 必须把每个并行 Task 建成独立 Attempt 和 Validation，按依赖关系和聚合策略汇总。任何单个分支都不能直接完成父 Task，并行度也必须由 Coordinator 显式控制。
+V1 已定义 TaskStore、ArtifactStore、AgentExecutor、ToolPolicy 和 EventSink Protocol，并提供文件存储、本地执行、默认权限和 JSONL 事件实现。
 
-### 3.6 已有扩展接口可以继续演进
+`RunConfig.completion_policy` 默认仍是 `legacy_auto`。新闭环必须显式使用 planner preset、`explicit_validation` 并调用 `wire_orchestration()`。旧 `agent`、`evaluate`、`goal`、Trace 读取和 project_name 入口保持兼容。
 
-当前代码已经具备：
+## 四、V1 已解决的原始问题
 
-- `TraceStore Protocol`：允许替换存储实现；
-- `ToolRegistry`：允许业务注册自己的工具；
-- `RunConfig`：允许每次运行传入配置；
-- `AgentPreset`：允许定义不同 Agent 角色；
-- `ToolContext Protocol`：允许工具获得运行上下文。
+### 4.1 运行结束不再等于 Task 完成
 
-新能力应沿着这些扩展点增加，不应另建一套平行框架。
-
-## 四、当前代码必须解决的问题
-
-### 4.1 Worker 运行结束会直接完成 Goal
-
-当前 `subagent.py` 在 Worker 返回后，会把 Worker 的运行状态写入父 Goal。
-
-但 Worker 的 `completed` 只说明 Agent 循环正常结束，不说明输出满足 Task 要求。
-
-新模式必须改为：
+explicit 模式的成功提交路径已强制：
 
 ```text
 Worker Trace completed
-→ Attempt submitted
+→ Attempt 必须已 submit_attempt
 → Task awaiting_validation
+→ Validator submit_validation
+→ Task awaiting_decision
+→ Planner accept passed Validation
+→ Task completed
 ```
 
-Worker 不再拥有完成 Task 或 Goal 的权限。
+仅返回自由文本的 Worker 会被记为 Attempt failed；Worker 运行异常、停止或过期时，Task 直接进入 needs_replan，不会启动 Validator。未提交结构化报告的 Validator 会被记为 Validation error。
 
-### 4.2 旧 evaluate 不能直接承担正式 Validator
+### 4.2 正式 Validator 与旧 evaluate 已分开
 
-当前 evaluate 主要返回自由文本，且存在以下问题：
+V1 已增加 validator preset、独立 Validator Trace、固定 Snapshot 输入和 `submit_validation` 结构化协议。运行状态 error/stopped/expired 与评审结论 failed/inconclusive 分开保存。
 
-- 不能稳定解析通过、不通过和无法判断；
-- 评估运行结束可能错误完成当前 Goal；
-- 指定其他 Goal 时可能把状态更新到当前 Goal；
-- 没有绑定 Task 版本和 Attempt 快照；
-- 无法区分“产物不通过”和“Validator 自己运行异常”。
+旧 `evaluate()` 仅在 `legacy_auto` 中保留原语义，不参与 explicit 闭环。
 
-建议保留旧 evaluate 兼容历史调用，新增正式的 `validator` 能力，不在原接口上强行改变全部旧语义。
+### 4.3 权限已从工具名黑名单升级为 capability 边界
 
-### 4.3 Preset 还不是可靠的权限边界
+ToolRegistry 已支持 `read`、`write`、`agent_spawn`、`external_send`、`task_control`、`attempt_submit`、`validation_submit` 标签。explicit 模式下，未标注工具 fail-closed，超出角色 capability 上限的工具同时从 Schema 和执行层拒绝。
 
-当前 Runner 获取工具时会把 tool groups 和显式 tools 取并集。结果是角色本来只应该得到少量工具，却可能同时得到默认 core 工具。
+legacy 模式仍保留原 tools/tool_groups 并集行为，避免旧业务立即失效。
 
-新规则必须是：
+### 4.4 父任务自动完成已关闭
 
-```text
-Preset 定义角色最大权限
-RunConfig 只能在最大权限内缩小
-denied_tools 永远扣除
-执行工具时再次校验当前角色
-```
-
-权限控制不能只体现在模型看到的 Tool Schema 中，还要在工具真正执行前进行第二次校验。
-
-### 4.4 父 Goal 会自动级联完成
-
-当前 GoalTree 和 FileSystemTraceStore 都有“子 Goal 全部完成后自动完成父 Goal”的逻辑。
-
-显式验证模式下必须关闭这种行为。子 Task 全部完成后，父 Task只能进入“等待主 Agent 决策”，由主 Agent重新判断父问题是否真的解决。
-
-### 4.5 运行状态和业务状态混在一起
-
-当前 Trace、Goal 和 Agent 结果都可能使用 `completed`，但它们表达的是不同含义。
+GoalTree 的旧级联行为保留为 legacy 默认。Coordinator 投影 Goal 时始终传入 `cascade_completion=False`。子 Task 全部 completed 后，父 Task 只从 `waiting_children` 进入 `needs_replan`，不会自动 completed。
 
-必须明确：
+### 4.5 repair 续用已进行身份校验
 
-```text
-Trace completed：某个 Agent 停止运行
-Attempt submitted：Worker 交付了一次输出
-Validation Run Status=completed 且 Verdict=passed：Validator 正常完成并建议接受
-Task completed：主 Agent 已明确接受
-```
-
-### 4.6 continue_from 缺少身份校验
-
-当前续用主要检查 Trace 是否存在，没有严格确认：
+Coordinator 会校验 root trace、task、spec version、Worker role、最新 Decision=repair、返修次数、Trace 终态、保护 context 和消息可恢复性。调用方不能直接传入任意 Trace ID。
 
-- 是否属于同一个主 Trace；
-- 是否属于同一个 Task；
-- Task 版本是否一致；
-- 原 Trace 是否是 Worker；
-- 是否仍允许继续返修；
-- 是否已经超过上下文或次数限制。
+V1 默认每个 TaskSpec 最多一次 repair 续用。“是否属于局部小修”仍由 Planner 判断；上下文长度和总成本硬限制属于 V2。
 
-新框架必须在 Coordinator 中统一校验，不允许调用方绕过。
+### 4.6 Ledger 真相与观测投影边界
 
-### 4.7 当前缺少针对核心语义的系统测试
+Ledger commit 成功后不会因观测失败而回滚，因此 Ledger 始终是真相。EventSink 异常和 Attempt 创建后的 Goal 投影异常已被捕获为警告；其他 Goal 投影调用点还没有统一隔离，可能让已成功的 Ledger commit 对外表现为当前工具调用失败。Attempt 异常处理使用明确 attempt_id，不会按“最新 Attempt”猜测并误伤其他正在运行的 Attempt。
 
-当前仓库没有完整覆盖 Goal、Subagent、Preset、Validator、状态转换的测试体系。
+### 4.7 核心回归测试已建立
 
-这次框架升级必须同步建立测试，否则很容易出现“模型正文说未通过，但 Goal 状态已经完成”一类问题。
+当前 `agent/tests` 共有 45 个测试用例，覆盖状态机、Ledger/Snapshot、terminal tool、角色权限、Worker→Validator→Decision 闭环、repair/retry/revise/split/revalidate、并行异常隔离、Goal 投影、legacy 真实执行和 Host 解耦。
 
 ## 五、目标架构
 
 ```mermaid
 flowchart TD
-    Host[业务项目] --> SDK[Framework API / SDK]
-    SDK --> Coordinator[Task Coordinator]
-
-    Coordinator --> Planner[Main Agent / Planner]
-    Planner --> GoalTree[Dynamic GoalTree]
-    Planner --> Ledger[Task Ledger]
-
-    Ledger --> Attempt[Task Attempt]
-    Attempt --> Worker[Worker AgentRunner]
-    Worker --> Output[Attempt Output Snapshot]
-
-    Output --> Checks[Deterministic Checks]
-    Checks --> Validator[Validator AgentRunner]
-    Validator --> Report[Validation Report]
-
-    Report --> Planner
-    Planner --> Decision[Planner Decision]
+    Host[Host Application] --> Runner[Main AgentRunner / Planner]
+    Runner --> PlannerTools[Planner Tools]
+    PlannerTools --> Coordinator[TaskCoordinator]
+    Coordinator --> Ledger[TaskLedger]
+    Coordinator --> Projection[Goal Projection]
+    Projection --> GoalTree[GoalTree]
+
+    Coordinator --> Executor[LocalAgentExecutor]
+    Executor --> Worker[Worker Sub-Trace]
+    Worker --> Submission[submit_attempt]
+    Submission --> Snapshot[ArtifactSnapshot Manifest]
+    Snapshot --> Validator[Validator Sub-Trace]
+    Validator --> Report[ValidationReport]
+
+    Report --> Runner
+    Runner --> Decision[PlannerDecision]
     Decision --> Ledger
-    Decision --> GoalTree
 
     Coordinator --> TraceStore[TraceStore]
-    Coordinator --> EventBus[Framework Events]
+    Coordinator --> EventSink[TraceEventSink]
 
     Host -.注入.-> Tools[Business Tools]
-    Host -.注入.-> ArtifactPort[Artifact Port]
-    Host -.V2 注入.-> EvidencePort[V2 Evidence Port]
+    Host -.注入.-> ArtifactStore[ArtifactStore]
+    Tools -.read capability.-> Validator
 ```
 
 这套架构中：
@@ -299,7 +225,7 @@ flowchart TD
 - Task Ledger 表达每个任务当前运行到哪一步；
 - Trace 记录某个 Agent 实际做过什么；
 - Coordinator 用确定性程序推进状态；
-- Validator 只产生报告；
+- Validator 是完整的单 Agent 运行时，但只产生评估报告；
 - 主 Agent 的 Decision 才能完成、修订或拆分 Task；
 - 业务能力通过工具和接口注入。
 
@@ -326,7 +252,7 @@ GoalTree 已经能够表达任务拓扑，不需要重写。
 - 关联的 Validation；
 - 最近一次 Planner Decision；
 - 是否等待子任务；
-- 是否被新版本替代；
+- TaskSpec 版本历史，以及是否被新 Task 替代；
 - 当前输出引用和证据引用。
 
 Task Ledger 不是第二棵任务树，而是 GoalTree 的运行台账。
@@ -337,13 +263,13 @@ Task Ledger 不是第二棵任务树，而是 GoalTree 的运行台账。
 
 GoalTree 只负责保存任务拓扑、焦点和展示所需摘要。现有 `Goal.status` 仅作为旧界面和旧接口的兼容投影，不允许被 Worker、Validator 或 Goal 工具独立写入。
 
-所有 `goal(done)`、Worker 回写、Validator 回写和父节点完成动作，都必须转换为 Coordinator Command。Coordinator 先原子更新 Task Ledger，再更新 Goal 的兼容投影。
+explicit 模式不向 Planner、Worker 或 Validator 暴露旧 `goal(done)` 写入入口。新规划工具统一调用 Coordinator：Coordinator 先原子更新 Task Ledger，再更新 Goal 兼容投影。`legacy_auto` 仍保留旧 Goal 回写语义。
 
 如果两者出现不一致：
 
 - Task Ledger 的状态用于调度、恢复和权限判断；
 - Goal.status 不能反向覆盖 Task Ledger；
-- Reconciliation 根据 Task Ledger 修复 Goal 投影并记录异常事件。
+- `reconcile_goal_tree()` 根据 Task Ledger 修复 Goal 投影并返回修复数量；专用异常事件属于 V2 观测增强。
 
 详细状态一律从 Task Ledger 读取，避免 Task 与 Goal 双写后各自成为“真相”。
 
@@ -363,7 +289,7 @@ Host Application 是使用框架的业务项目。
 - 决定是否需要人工审批；
 - 消费框架事件并构建自己的产品界面。
 
-框架不读取 Host Application 的内部模块。
+Orchestration 内核只接收 Host 注入的配置、工具和端口，不主动读取 Host Application 的内部模块。legacy 可选路由的 `examples/` Prompt 扫描是前述兼容例外。
 
 ### 7.2 Task Coordinator
 
@@ -377,7 +303,7 @@ Coordinator 不是 Agent，而是一层确定性程序。
 - 绑定 Task 版本和固定输出快照；
 - 在 Worker、Validator 和主 Agent 之间传递正确上下文；
 - 防止重复请求产生重复执行；
-- 管理超时、停止、恢复和错误状态；
+- V1 归一化 executor 返回的 failed、error、stopped 和 expired 状态；主动超时、后台 stop/resume 和进程重启恢复属于 V2；
 - 保证只有主 Agent Decision 能完成 Task。
 
 Agent 负责判断，Coordinator 负责守规则。
@@ -423,6 +349,8 @@ Worker 负责执行一次 Task Attempt。
 
 Validator 使用独立 Trace 和独立上下文进行评估。
 
+代码上它与主 Agent 共用完整 AgentRunner，因此可以在一次 Validation 内自主安排核验步骤、多轮推理并多次调用已授权只读工具。但它不是业务 Planner，不能规划任务树、派发 Worker/Validator、创建 SubAgent 或作出 Task Decision。
+
 它可以拥有和主 Agent 同等级的推理能力，也可以调用文件、数据库、API、网页和测试工具，但这些工具必须是只读或安全检查型工具。
 
 它负责：
@@ -443,6 +371,8 @@ Validator 使用独立 Trace 和独立上下文进行评估。
 - 发布输出；
 - 完成 Task。
 
+每次 Validation 都使用新 Trace，一轮内只能成功调用一次 `submit_validation`，提交后立即结束本轮 Agent Loop。Validator 不能自己发起第二轮验证。
+
 ## 八、核心对象
 
 ### 8.1 Task
@@ -471,7 +401,7 @@ Attempt 表示一个 Worker 对某个 Task 版本做过的一次执行。
 - 使用不同模型重做；
 - 使用不同工具组合重做。
 
-每个 Attempt 都绑定自己的 Worker Trace 和输出快照。
+每个 Attempt 都绑定自己的 Worker Trace。只有成功调用 `submit_attempt` 的 Attempt 才会绑定新提交清单快照；failed、stopped 或 expired Attempt 只保留状态、错误和 Trace，不生成 Snapshot。V1 ArtifactSnapshot 冻结的是 summary、artifact_refs 和 evidence_refs 的规范化 manifest 及 SHA-256，不复制外部产物字节。
 
 ### 8.3 Validation
 
@@ -496,7 +426,7 @@ Decision 表示主 Agent 在读取评估后做出的明确决定。
 
 框架不能假设输出是文本、图片、代码、知识条目还是其他内容。
 
-框架只保存通用引用，例如：
+框架只保存通用引用，且 `ArtifactRef` 必须提供不可变 version 或 digest，例如：
 
 - 输出标识；
 - 输出版本；
@@ -505,11 +435,11 @@ Decision 表示主 Agent 在读取评估后做出的明确决定。
 - 内容哈希；
 - 业务自定义 metadata。
 
-具体内容由 Host Application 的 Artifact Port 保存和读取。
+具体内容由 Host Application 的业务存储保存和读取；V1 FileSystemArtifactStore 仅保存提交清单快照。
 
 ### 8.6 Evidence Reference
 
-框架只记录 Validator 使用过哪些证据引用，不理解证据的业务结构。
+V1 不定义独立 EvidenceRef 类，evidence_refs 复用 ArtifactRef 结构。框架只记录 Validator 使用过哪些证据引用，不理解证据的业务结构。
 
 证据可能来自：
 
@@ -584,7 +514,7 @@ inconclusive   无法判断或证据不足
 4. Validation Run Status=completed 后，无论 Verdict 是什么，都进入 awaiting_decision；
 5. 普通 accept 只允许绑定当前 Task Version、当前 Attempt Snapshot，以及 Run Status=completed 且 Verdict=passed 的 Validation；
 6. 只有主 Agent 的有效 accept Decision 能把 Task 写成 completed；
-7. 子 Task 全部完成后，父 Task 只能进入 awaiting_decision 或 needs_replan；
+7. 子 Task 全部 completed 后，父 Task 从 waiting_children 进入 needs_replan，绝不自动 completed；
 8. 旧 Task 版本的 Validation 不能用于新版本；
 9. 执行失败和评估异常不能伪装成业务不通过；
 10. 重复请求不能重复创建 Attempt 或重复接受输出。
@@ -609,7 +539,7 @@ Validation error / stopped / expired
 
 `awaiting_decision` 专指“已有有效评审结论，等待主 Agent 决策”。
 
-`needs_replan` 专指“执行或评审链路没有形成有效结论，需要主 Agent决定重新执行、重新验证、修改任务或阻塞”。
+`needs_replan` 专指“当前 Task 需要主 Agent 基于执行、评审或子任务结果决定下一步”；下一步可以是重新执行、重新验证、修改或拆分任务、或暂时阻塞。
 
 普通 accept 不能推翻 failed 或 inconclusive。V1 不提供任何 override 通道；需要例外审批的业务必须把人工复核建模为新 Task 或由 Host 在框架之外处理，不得把 failed/inconclusive 标记为已通过。
 
@@ -640,15 +570,11 @@ sequenceDiagram
 
 ## 十一、Validator 设计
 
-### 11.1 先做确定性检查，再做 Agent 判断
-
-验证建议分三层：
+### 11.1 V1 的验证方式与后续分层
 
-1. 确定性检查：格式、必填、文件存在、哈希、接口状态、测试结果等；
-2. Validator 判断：需要推理、比较、归因和综合判断的标准；
-3. 高风险复核：由第二模型、人工或业务侧审批完成。
+V1 每次都运行完整 Validator Agent。Validator 可通过 Host 注入的 read capability 工具执行格式、文件、哈希、接口和测试结果检查；Coordinator 只校验结构化报告是否覆盖验收条件，以及总体 passed 是否与硬性条件冲突。
 
-能够由程序确定的内容，不应全部交给模型猜测。
+独立 DeterministicCheck 引擎、按风险选择轻量检查/完整 Validator、第二模型和人工复核策略属于 V2/V3，不是 V1 已实现组件。
 
 ### 11.2 Validator 必须评估固定快照
 
@@ -666,14 +592,14 @@ Validator 启动时必须绑定：
 
 Validator 可以使用高能力模型和丰富查询工具，但不能获得写权限。
 
-只读不能只靠 Prompt 保证，应通过：
+只读不能只靠 Prompt 保证。框架 V1 已实现：
 
-- 只读工具组；
-- 只读数据库账号；
-- 只读 API；
+- validator preset 白名单与 `read` capability 上限；
 - ToolRegistry 执行前角色校验；
 - 禁止 Agent、Goal 写入、文件写入和发布工具；
-- 独立运行环境或沙箱。
+- 未标注 capability 的 Host 工具默认拒绝。
+
+只读数据库账号、只读 API 凭证和独立沙箱仍需 Host/部署环境提供，不能只靠框架 capability 替代。
 
 ### 11.4 报告必须结构化
 
@@ -682,33 +608,35 @@ Validator 报告至少要能让程序稳定识别：
 - 总体结论：passed、failed、inconclusive；
 - 每条验收条件的结论；
 - 对应证据引用；
-- 未验证事实；
-- 失败位置；
-- 风险等级；
+- 未验证事实列表；
+- 风险列表；
 - 给主 Agent 的处理建议。
 
-Validator 可以附带自然语言分析，但不能只返回一段无法解析的自由文本。
+Validator 可以在 `criterion_results.reason` 和 `summary` 里说明失败位置，但 V1 没有独立 `failure_location` 或 `risk_level` 字段。它不能只返回一段无法解析的自由文本。
 
 ## 十二、主 Agent重新规划
 
-框架需要向主 Agent提供以下通用 Decision：
+框架 V1 已向主 Agent 提供以下通用 Decision：
 
 | Decision | 框架动作 |
 |---|---|
 | accept | 在有效 passed Validation 基础上接受本次输出，Task 完成 |
 | repair | 同 Task、同版本创建新 Attempt，可有限续用原 Worker Trace 上下文 |
 | retry | 创建新 Attempt，并创建新 Worker Trace |
-| revalidate | 对当前未变化的 Attempt Snapshot 创建新 Validation |
 | revise | 同一个 task_id 下创建新的不可变 spec_version，旧版本失效但 Task 不进入 superseded |
 | split | 创建子 Task，父 Task 进入 waiting_children |
-| request_evidence | 创建补证据 Task 或补充验证步骤 |
 | block | 等待用户、权限、资源或外部系统 |
+| unblock | 解除阻塞并回到 needs_replan |
 | cancel | 停止当前 Task 后续执行 |
 | supersede | 创建新的 task_id 替代旧 Task，旧 Task 进入 superseded |
 
 Coordinator 必须检查 Decision 是否适用于当前状态。例如已经 superseded 的 Task 不能再次 accept，已经修改验收条件的 Task 不能继续使用旧 Validation。
 
-`repair` 和 `retry` 都必须创建新 Attempt 和新 Output Snapshot。区别仅在于：repair 可以在满足上下文校验时通过 `continue_from` 续用上一 Worker Trace；retry 使用全新的 Worker Trace。旧 Attempt、旧 Snapshot 和旧 Validation 永远不修改。
+`revalidate` 不通过 `task_decide` 执行，而是 Planner 调用独立 `validate_attempt` 工具。它只允许在上一次 Validator 为 error、stopped 或 expired，且 Task 处于 needs_replan 时，对未变化 Snapshot 创建新 Validator Trace。failed/inconclusive 是有效评审结论，不能使用 revalidate 绕过主 Agent 重规划。
+
+“补证据”不是 V1 的独立 DecisionAction。主 Agent 应通过 `task_plan` 创建补证据 Task，或使用 split、revise、block 组合表达。
+
+`repair` 和 `retry` 都必须创建新 Attempt，该 Attempt 成功提交后才产生新 Output Snapshot。区别仅在于：repair 可以在满足上下文校验时通过 `continue_from` 续用上一 Worker Trace；retry 使用全新的 Worker Trace。旧 Attempt、旧 Snapshot 和旧 Validation 永远不修改。
 
 Validation 必须始终绑定 `task_id + spec_version + attempt_id + snapshot`。revise 只产生同一 Task 的新 spec_version；supersede 才会产生新的 task_id。
 
@@ -758,13 +686,14 @@ New Attempt → New Worker Sub-Trace
 - 同一个 Task Version；
 - 原 Trace 的角色是 Worker；
 - Decision 是 repair；
-- 修改范围明确且局部；
 - 未超过连续返修次数；
-- 未超过上下文长度和成本限制。
+- 原 Trace 处于可恢复终态，保护 context 身份一致，且消息仍可恢复。
+
+“是否只是局部小修”由 Planner 根据 ValidationReport 判断。V1 Coordinator 不能从自然语言自动证明修改范围，也尚未实现总 Token/总成本上限；这些属于 V2 策略。
 
 改题、拆题、换路线或换 Worker 时必须新建 Trace。
 
-即使 repair 续用了原 Worker Trace，它仍然是一笔新的 Attempt，并生成新的 Output Snapshot。续用的是会话上下文，不是修改旧 Attempt。
+即使 repair 续用了原 Worker Trace，它仍然是一笔新的 Attempt，并在成功提交后生成新的 Output Snapshot。续用的是会话上下文，不是修改旧 Attempt。
 
 ### 13.4 Validator 默认每次新建上下文
 
@@ -790,18 +719,22 @@ V1 中 Planner 只拥有编排写权限和业务只读权限，不允许直接
 
 Worker 可以使用当前 Attempt 明确允许的业务工具。
 
+Worker 角色 capability 上限为 read、write、external_send 和 attempt_submit；默认 worker preset 只配置文件读写、bash 和 `submit_attempt`。Host 如需外发能力，必须在自定义 Worker preset 中显式授权并正确标注 capability。
+
 框架默认禁止 Worker 使用：
 
 - `agent`；
 - `validator`；
 - Task/Goal 写入；
 - Planner Decision；
-- 发布和接受工具。
+- `agent_spawn`、`task_control` 和 `validation_submit` capability。
 
 ### 14.3 Validator 权限
 
 Validator 可以使用只读查询和安全检查工具。
 
+默认 validator preset 只包含文件/图像读取、glob、grep 和 `submit_validation`。DB、API 和网页查询不是开箱即有：Host 必须把工具标注为 `read`，并加入自定义 validator preset 白名单。
+
 框架默认禁止 Validator 使用：
 
 - 文件写入；
@@ -819,16 +752,20 @@ Validator 可以使用只读查询和安全检查工具。
 有效工具采用：
 
 ```text
+candidates
+= RunConfig.tools（显式提供时）
+  否则 RunConfig.tool_groups 匹配工具
+  否则全部已注册工具
+
 effective_tools
-= preset.allowed_tools
-∩ run_config.requested_tools
-∩ host_policy.allowed_tools
+= candidates
+∩ preset.allowed_tools（如定义）
 − preset.denied_tools
-− host_policy.denied_tools
-∩ role.allowed_capabilities
+− RunConfig.exclude_tools
+再保留 capability 全部属于 role.allowed_capabilities 的工具
 ```
 
-当某层没有显式 requested tools 时，表示“不进一步缩小”，不是“允许全部”。Schema 过滤和执行前授权使用同一份 capability 结果。
+explicit 模式下未标注 capability 的工具默认拒绝。Host 当前通过自定义 preset、capability 标签或替换 ToolPolicy 端口扩展，V1 没有独立 HostPolicy 对象。替换 ToolPolicy 属于受信任 composition root 的安全责任；默认 DefaultToolPolicy 中，Schema 过滤和执行前授权使用同一份解析结果。
 
 ## 十五、通用扩展接口
 
@@ -836,21 +773,21 @@ effective_tools
 
 保存 Task、Attempt、Validation 和 Decision。
 
-框架可以提供文件系统默认实现，业务可以替换为关系数据库、文档数据库或其他共享存储。
+V1 已提供 TaskStore Protocol 和 FileSystemTaskStore。V2 可替换为关系数据库、文档数据库或其他共享存储。
 
-### 15.2 Artifact Port
+### 15.2 Artifact Store
 
-负责保存和读取 Attempt Output Snapshot。
+负责冻结和读取 AttemptSubmission 的不可变 manifest Snapshot。
 
 框架只认识 Artifact Reference，不认识具体内容结构。
 
 ### 15.3 Evidence Port（V2 扩展）
 
-负责向 Validator 提供业务证据查询能力。V1 不定义独立证据读取端口；证据使用 ArtifactRef/EvidenceRef 和经 capability 授权的只读工具提供。
+负责向 Validator 提供业务证据查询能力。V1 不定义独立证据读取端口；证据使用 `evidence_refs` 字段中的 ArtifactRef 和经 capability 授权的只读工具提供。
 
 实际实现可以是 ToolRegistry 中注册的只读工具，也可以是业务提供的适配器。
 
-### 15.4 Validation Policy
+### 15.4 Validation Policy（V2 扩展）
 
 用于定义：
 
@@ -860,31 +797,36 @@ effective_tools
 - 哪些 Task 需要人工复核；
 - 最大验证次数和成本。
 
-框架提供机制，业务通过配置选择策略。
+V1 没有 ValidationPolicy 类或策略引擎，每次都启动完整 Validator。以上风险分层属于 V2/V3。
 
 ### 15.5 Tool Policy
 
 Tool Policy 负责角色到工具权限的映射，并在工具执行前进行二次授权。
 
-业务可以注册工具，但不能绕过框架的角色上限。
+在 DefaultToolPolicy 下，业务可以注册工具，但不能绕过框架的角色上限；Host 若替换该端口，必须自行承担等价的权限隔离责任。
 
 ### 15.6 Event Sink
 
-框架输出通用事件，例如：
+当前 TraceEventSink 输出的主要事件包括：
 
 ```text
-task_created
-attempt_started
+ledger_created
+tasks_created
+task_focused
+attempt_created
 attempt_submitted
 validation_started
-validation_completed
-planner_decision_recorded
-task_completed
-task_replanned
-task_blocked
+validation_submitted
+validation_restarted
+planner_decision
+worker_failed
+validation_error
+task_cycle_failed
+dispatch_completed
+goal_projection_linked
 ```
 
-业务系统可以订阅事件构建自己的页面、通知和监控。
+`planner_decision` 的 action/payload 表达 accept、block、split 等具体动作，V1 不为每个动作另造事件名。当前实现为本地 `events.jsonl`；稳定的对外订阅协议属于 V2。
 
 ## 十六、存储、恢复和可观测性
 
@@ -899,14 +841,23 @@ task_blocked
 - Output Snapshot 引用；
 - Validation Report 和证据引用；
 - Planner Decision；
-- 角色、模型、工具策略和成本；
+- Trace 中的角色、模型运行记录和成本；
 - 状态变更事件。
 
-### 16.2 V1 可以继续使用文件存储
+V1 Ledger 不保存完整 resolved tool policy 快照；可审计的策略快照属于 V2。
+
+### 16.2 V1 已实现文件存储
 
-第一版可以在现有 FileSystemTraceStore 基础上增加 Task Ledger 文件存储，先验证状态语义和运行闭环。
+V1 已定义 TaskStore/ArtifactStore/EventSink 端口，并提供 FileSystemTaskStore、FileSystemArtifactStore 和 TraceEventSink。默认目录为：
+
+```text
+.trace/{root_trace_id}/orchestration/
+├── ledger.json
+├── artifacts/{snapshot_id}.json
+└── events.jsonl
+```
 
-但新的 Task Store 应先定义 Protocol，避免业务直接依赖文件目录结构。
+`ledger.json` 使用临时文件加 `os.replace`、每 root trace 的 `asyncio.Lock` 和 revision 乐观锁。这些保证仅针对单进程 V1。
 
 ### 16.3 生产化使用共享存储
 
@@ -943,9 +894,9 @@ Task
 Worker → Validator → Planner Decision
 ```
 
-第一版可以继续使用现有 `await` 模式，不需要立即引入分布式队列。
+V1 当前使用 `await` 模式跑完工具内的同步闭环，没有引入分布式队列。
 
-多个互不依赖的 Task 可以继续使用现有并行 Sub-Trace 能力。批量预约 Attempt 和执行周期都必须逐 Task 隔离异常：单个 Task 冲突、Store 或 Artifact 异常只返回该分支错误，其他 Task 继续执行，返回顺序与输入一致。
+多个互不依赖的 Task 由 Coordinator 使用 Semaphore 并发调用 LocalAgentExecutor，不复用 legacy `agent()` 的多分支聚合语义。Task 预留和执行周期中的分支异常会逐 Task 隔离，其他 Task 继续执行，成功返回时顺序与输入一致。批次级 `dispatch_completed` 幂等写入不在分支 catch 内；该写入失败或持续 Store 故障仍可使整次工具调用报错。
 
 ### 17.2 后续增加后台任务接口
 
@@ -973,88 +924,73 @@ explicit_validation
 使用 Task、Attempt、Validation、Decision 的显式完成协议
 ```
 
-新项目默认使用 `explicit_validation`。
+框架 `RunConfig` 默认仍使用 `legacy_auto`。采用 V1 的新 Host 必须显式选择 planner preset 和 `explicit_validation`，并先调用 `wire_orchestration()`；缺少 Coordinator 时启动失败，不会静默退回 legacy。
 
 旧 evaluate 暂时保留，新 Validator 使用独立工具名、独立 Trace 类型和独立结构化结果。等旧调用完成迁移后，再决定是否废弃 evaluate。
 
-## 十九、代码改造范围
+## 十九、V1 实际代码落点
 
-### 19.1 保留不动或少动
+### 19.1 编排内核
 
-- `agent/agent/core/runner.py` 的核心模型循环；
-- Trace 和 Message 主体结构；
-- ToolRegistry 注册和调用框架；
-- GoalTree 的父子拓扑能力；
-- Sub-Trace 创建机制；
-- `continue_from` 的消息恢复基础；
-- WebSocket 和 Trace 可视化基础。
+```text
+agent/agent/orchestration/
+├── models.py          # Task/Attempt/Validation/Decision/Ledger
+├── protocols.py       # TaskStore/ArtifactStore/AgentExecutor/ToolPolicy/EventSink
+├── config.py          # 并行度、repair 次数和默认 preset
+├── state_machine.py   # 法定 Task 状态转换
+├── store.py           # 文件 Store 和 JSONL EventSink
+├── policy.py          # capability 权限解析
+├── executor.py        # 本地 Worker/Validator Sub-Trace
+├── coordinator.py     # 唯一 Ledger 状态写入入口
+└── wiring.py          # 框架组装
+```
 
-### 19.2 修改现有模块
+### 19.2 Runner、Trace 和工具集成
 
-| 模块 | 改造内容 |
+| 模块 | V1 实际落点 |
 |---|---|
-| `tools/builtin/subagent.py` | Worker 完成改为 Attempt 提交；禁止 Worker 创建孙 Agent；增加续用身份校验入口 |
-| `trace/goal_models.py` | 增加完成策略；显式验证模式关闭父 Goal 自动完成 |
-| `trace/goal_tool.py` | Goal 完成动作改为经过 Coordinator 校验 |
-| `trace/store.py` | 保存新事件；显式验证模式关闭级联；避免非法状态 |
-| `core/presets.py` | 增加 Planner、Worker、Validator 角色策略 |
-| `core/runner.py` | 正确应用 Preset、轮次和工具权限；执行工具前进行角色校验 |
-| `trace/models.py` | Trace context 增加通用角色和 Task 身份 |
-| `trace/run_api.py` | 把动态加载 examples 的历史入口迁移到 Host bootstrap/legacy adapter；V2 再增加通用 API |
-| `tools/builtin/__init__.py` | 注册 Validator 和 Planner Decision 工具 |
-
-### 19.3 新增通用模块
+| `core/runner.py` | completion policy、角色解析、terminal tool、保护 context、Schema/执行双层授权 |
+| `core/presets.py` | planner、worker、validator 预设和角色上限 |
+| `core/prompts/orchestration.py` | 不可覆盖的角色契约 |
+| `tools/builtin/orchestration.py` | `task_plan`、`dispatch_tasks`、`task_decide`、`validate_attempt`、`submit_attempt`、`submit_validation` |
+| `tools/models.py` / `tools/registry.py` | ToolCapability 声明和查询 |
+| `trace/models.py` | `agent_role` 和 `result_summary` |
+| `trace/goal_models.py` / `trace/store.py` | legacy 默认级联，explicit 可关闭级联 |
+| `trace/project_environment.py` | 只保留业务无关 Resolver Protocol |
 
-建议增加：
-
-```text
-agent/agent/orchestration/
-├── models.py
-├── protocols.py
-├── coordinator.py
-├── store.py
-├── policies.py
-└── events.py
-
-agent/agent/tools/builtin/
-├── validator.py
-└── task_planning.py
-```
+### 19.3 Host 兼容适配层
 
-具体业务适配器不放在这些模块里。
+`agent/examples/legacy_adapters.py` 承载旧 project_name 动态加载和旧内容评分器注入，由根 `api_server.py` 组装。可安装 `agent` 包不 import `examples` 或具体业务包。
 
 ## 二十、三个框架版本
 
 ### 20.1 Framework V1：任务执行与独立验证闭环
 
-目标：把最核心的语义和权限做正确。
+状态：已实现并在当前仓库 `cyber-agent 0.4.0` 版本基线中落地。
 
 包括：
 
 - 主 Agent是唯一 Planner；
 - Worker 不能创建孙 Agent；
 - Task、Attempt、Validation、Decision 分离；
-- Worker 结束后进入 awaiting_validation；
+- Worker 成功调用 `submit_attempt` 后进入 awaiting_validation；未提交、异常、停止或过期则进入 needs_replan；
 - 独立 Validator Trace；
 - 结构化 Validation Report；
-- 主 Agent支持 accept、repair、retry、revise、split、block；
+- `task_decide` 支持 accept、repair、retry、revise、split、block、unblock、cancel、supersede；
+- `validate_attempt` 支持 Validator error/stopped/expired 后对未变 Snapshot 重新评估；
 - 父 Task 不自动完成；
 - Worker 默认新 Trace；
 - Validator 默认新 Trace；
 - Planner、Worker、Validator 工具权限隔离；
 - 定义最小 TaskStore Protocol，并提供文件系统默认实现；
 - 定义最小 ArtifactStore、AgentExecutor、ToolPolicy 和 EventSink 协议及默认实现；
-- 使用不可变 Output Snapshot；
+- 使用不可变 AttemptSubmission manifest Snapshot，外部产物通过 version/digest 保证不可变；
 - 提供单进程幂等键，防止同一请求重复创建 Attempt、Validation 或 Decision；
 - orchestration 内核不再动态 import examples 或业务包；
 - `legacy_auto` 与 `explicit_validation` 双模式；
-- 建立核心状态测试。
-
-以下改动量是基于当前代码和测试缺口的粗估，不是排期承诺：
-
-- 修改现有文件 8～12 个；
-- 新增文件 5～8 个；
-- 业务无关的框架代码和测试合计约 1,600～2,800 行。
+- 建立 45 个当前回归用例，orchestration 覆盖率 90.07%；
+- 批量 Task 在预留和执行周期内按分支隔离异常，正常返回时顺序与输入一致；批次幂等写入失败的恢复仍属 V2；
+- 明确 V1 限制：仅本地 Sub-Trace、同步工具调用、单进程文件存储、无新 Task HTTP API。
 
 ### 20.2 Framework V2：通用扩展接口与可靠恢复
 
@@ -1065,18 +1001,13 @@ agent/agent/tools/builtin/
 - TaskStore、Artifact、Evidence 和 ToolPolicy 的生产级可插拔实现与业务适配器；
 - Validation Policy；
 - 通用 API 和 Python SDK；
-- 通用事件协议；
+- 把 V1 本地 EventSink/JSONL 升级为稳定对外事件协议；
 - 跨进程、可持久化的幂等和防重复执行；
 - 超时和重试限制；
 - 进程重启后的状态恢复；
 - start、poll、event、stop、resume；
 - 统一成本、耗时、模型和失败原因统计。
 
-以下改动量是基于当前范围的粗估，不是排期承诺：
-
-- 修改和新增文件 10～15 个；
-- 框架代码和测试约 1,500～3,000 行。
-
 ### 20.3 Framework V3：分布式生产治理
 
 目标：支持多业务、多实例和长时间运行。
@@ -1096,16 +1027,11 @@ agent/agent/tools/builtin/
 - 人工复核扩展点；
 - 完整监控和告警。
 
-预计在 V2 基础上新增：
-
-- 修改和新增文件 15～25 个；
-- 框架代码和测试约 2,000～4,000 行。
-
 ## 二十一、V1 验收用例
 
 ### 21.1 完成语义
 
-- Worker 正常结束后，Task 必须是 awaiting_validation，不能 completed；
+- Worker 成功调用 `submit_attempt` 后，Task 必须是 awaiting_validation，不能 completed；只正常结束但未提交时，Task 必须是 needs_replan；
 - Validator Run Status=completed 且 Verdict=failed 时，Task 不能完成；
 - Validator Run Status=completed 且 Verdict=passed 时，Task 必须进入 awaiting_decision；
 - 只有主 Agent accept 后，Task 才能 completed；
@@ -1124,14 +1050,14 @@ agent/agent/tools/builtin/
 ### 21.3 上下文隔离
 
 - 不同 Task 默认不能复用 Worker Trace；
-- 同 Task、同版本的局部 repair 可以续用 Worker Trace，但必须创建新 Attempt 和 Snapshot；
+- 同 Task、同版本的局部 repair 可以续用 Worker Trace，但必须创建新 Attempt，且只有成功提交才创建新 Snapshot；
 - revise、split 和 retry 默认创建新 Trace；
 - 改题后继续旧 Trace 必须被拒绝；
 - Validator 每次使用干净 Trace。
 
 ### 21.4 权限
 
-- Worker 不能调用 agent、validator 和 Planner Decision；
+- Worker 不能调用 `agent`、`evaluate`、Planner 工具和 `submit_validation`；
 - Validator 可以读取允许的证据；
 - Validator 不能修改文件、业务数据、GoalTree 和 Task；
 - 仅隐藏 Tool Schema 不足以绕过执行层权限检查；
@@ -1144,19 +1070,19 @@ agent/agent/tools/builtin/
 - 证据不足记录为 inconclusive；
 - 重复请求不会创建重复 Attempt；
 - 输出变化后旧 Validation 自动失效；
-- 达到次数、成本或上下文上限后进入 block 或 needs_replan。
+- 同一 TaskSpec 的第二次 repair 被拒绝；总 Attempt、Validation、Token 和成本上限留到 V2。
 
 ### 21.6 并行任务
 
-- 每个并行 Task 都有独立 Attempt 和 Validation；
+- 每个成功预留的并行 Task 都有独立 Attempt；只有 submitted Attempt 才创建独立 Validation，失败分支不伪造 Validation；
 - 单个分支成功不能直接完成整体或父 Task；
 - 并行度由 Coordinator 配置，而不是读取不存在的 Runner 配置；
-- 聚合策略必须明确区分全部成功、部分成功和全部失败；
+- `dispatch_tasks` 返回按输入排序的逐 Task 结果，不生成“任一成功则整体成功”的聚合状态；
 - 并行 Worker 仍受各自 Tool Policy 约束。
 
 ### 21.7 解耦检查
 
-- 框架内核不引用任何业务项目模块；
+- Orchestration 内核不引用任何具体业务项目模块；legacy `examples_api` 的可选 Prompt 扫描明确属于 Host 兼容边界；
 - 框架模型中不出现具体业务对象；
 - 测试使用通用任务和通用输出；
 - 业务工具通过 ToolRegistry 注册；
@@ -1171,11 +1097,11 @@ agent/agent/tools/builtin/
 
 ### 22.2 Validator 与 Worker 可能有共同偏差
 
-控制方式：先做确定性检查；高风险任务支持第二模型和人工复核；框架记录评估历史，供业务统计漏检和误拒。
+当前控制：Validator 使用独立 Trace、固定 Snapshot 和只读工具，框架保留评估历史。独立确定性检查引擎、第二模型和人工复核策略属于 V2/V3。
 
 ### 22.3 Validator 增加成本和延迟
 
-控制方式：使用 Validation Policy 按风险选择规则检查、完整 Validator 或高级复核，而不是所有 Task 使用同一成本配置。
+当前控制：Host 可通过 validator preset 选择模型、轮次和工具。按风险自动选择规则检查、完整 Validator 或高级复核的 ValidationPolicy 属于 V2。
 
 ### 22.4 主 Agent上下文越来越长
 
@@ -1183,11 +1109,11 @@ agent/agent/tools/builtin/
 
 ### 22.5 无限失败循环
 
-控制方式：限制同一 Task Version 的 Attempt 数、连续 repair 次数、拆分深度、Validation 次数、总 Token 和总成本。
+当前控制：V1 只硬性限制同一 TaskSpec 默认最多一次 repair 续用。Attempt 总数、拆分深度、Validation 次数、总 Token 和总成本限制属于 V2。
 
 ### 22.6 Prompt 不能保证权限
 
-控制方式：Preset 最大权限、RunConfig 缩小权限、Host Policy、工具执行层校验和基础设施只读账号共同生效。
+当前控制：preset 白/黑名单、RunConfig 候选集、role capability 上限、未分类 fail-closed 和工具执行层校验共同生效。Host 还应提供只读账号/凭证；V1 没有独立 HostPolicy 对象。
 
 ### 22.7 兼容旧调用可能拖累新语义
 
@@ -1222,7 +1148,7 @@ Central Main Planner
 - 把任何具体业务的 Workflow、数据结构或 Prompt 放进框架内核；
 - 在 V1 阶段整体更换框架或直接引入分布式调度。
 
-建议先完成 Framework V1，验证以下最小闭环：
+Framework V1 的最小闭环已实现并通过测试：
 
 ```text
 Main Agent Planning
@@ -1232,4 +1158,4 @@ Main Agent Planning
 → Replan or Complete
 ```
 
-框架只负责保证这个协议正确、可恢复、可扩展。业务项目负责告诉框架“做什么、用什么工具、如何验收、输出保存在哪里”。
+下一阶段不是重做 V1，而是二选一或并行推进：Host 业务接入这个协议，或进入 V2 的公开 API、共享存储、恢复和策略化验证。框架只负责保证通用协议正确；业务项目负责告诉框架“做什么、用什么工具、如何验收、输出保存在哪里”。