@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/docs/architecture/dag-execution.md

@@ -1,140 +1,140 @@
-# Agent DAG 执行架构
-
-本页说明 Agent DAG 的主调用链、rank 调度、executor、run-owned skill snapshot、decision gate 与 pause/completed 生命周期。命令面与 `test/cli-contract.test.ts` 一致；符号归属以 `src/` 为准。完整 import 边界与 governance hook 见 `runtime-boundaries.md`。
-
-## 主调用链
-
-### 生成 + 校验 + 执行（`dag run-task`）
-
-```text
-src/commands/dag-run-task.ts  runDagRunTask
-  → src/application/dag/generate-task-dag.ts  generateTaskDagUseCase
-      └─ src/workflows/dag/init-hybrid.ts  initHybridDagFromTask     （生成 DagSpec）
-      └─ src/application/dag/validate-dag.ts  validateDagUseCase      （候选 + 最终校验）
-      └─ assertSafeForExecution                               （执行前安全检查）
-      └─ src/application/dag/run-dag.ts  runDagUseCase              （执行）
-```
-
-`generateTaskDagUseCase` 内部先 `initHybridDagFromTask` 生成 `DagSpec`，再调用 `validateDagUseCase` 做候选与最终两次校验，随后 `assertSafeForExecution` 确认 DAG 可安全执行，最后委托 `runDagUseCase` 执行。`runDagRunTask` 还 `export` 了 `assertSafeForExecution` 供命令层复用。
-
-### 直接执行既有 DAG（`run-dag`）
-
-```text
-src/commands/run-dag.ts
-  → src/application/dag/run-dag.ts  runDagUseCase
-      → src/workflows/dag/runner.ts  runDag
-```
-
-`run-dag` 是 top-level 命令，**不**在 `dag` 子树下（与 `dag run-task` 区分）。`runDagUseCase` 是 application 层 typed use-case，`runDag` 是 workflow runtime 核心。
-
-### 校验
-
-```text
-src/commands/dag-validate.ts  runDagValidate
-  → src/application/dag/validate-dag.ts  validateDagUseCase
-```
-
-### runtime contract preflight 与 repair writer 解析
-
-- `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
-- `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
-- `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
-
-## rank 调度
-
-拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：
-
-| 职责 | 源码入口 | 说明 |
-| --- | --- | --- |
-| 拓扑排序 | `src/workflows/dag/topo.ts` `topoSortToRanks` | Kahn 算法，返回 `string[][]` ranks 并检测环 |
-| 单次 rank 执行 | `src/workflows/dag/scheduler.ts` `executeDagRanksOnce` | rank 间遍历、节点执行编排 |
-| run 主循环 | `src/workflows/dag/runner.ts` `runDag` / `executeDagCheckpoint` | 调用 scheduler + persistence + convergence |
-
-`scheduler.ts` `executeDagRanksOnce` 内每个 rank：
-
-1. `pauseGateRunnable`（满足 `isPauseOnHumanDecisionGate` 的节点，来自 `decision-envelope.ts`）**串行**先跑；任一节点触发 pause 即停止后续。
-2. `regularRunnable` 经 `mapConcurrent` 并发执行，`maxConcurrent` 默认 **4**（`runner.ts` `Math.max(1, opts.maxConcurrent ?? 4)`）。
-3. `rankWriterNodeIds`（`executor === "pi"` && `toolProfile === "write"` && `writePolicy === "exclusive"`）注入同 rank 的不相交 writeSet 上下文（`createExecuteNodeForRank`）。
-4. 依赖未就绪的节点标 `SKIPPED`。
-
-`mapConcurrent` 来自 `src/shared/concurrency.ts`（或等价 shared 工具）。
-
-## executor（Pi-only 受治理 runtime）
-
-- 注册表：`src/workflows/dag/executor-registry.ts`
-  `DEFAULT_DAG_EXECUTOR_REGISTRY = { pi, shell, static }`。
-- schema：`src/workflows/dag/types.ts`
-  `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；DagNodeExecutor 默认 `"pi"`（`executor: dagNodeExecutorSchema.default("pi")`）。
-- `executor: "cursor"` 在 schema refine 阶段抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`（Pi-only = ADR 0001）。
-- Pi handler 先 `requireModel(input)` 校验已解析 model，再委托 `executeDagPiNode`（`src/executors/dag-pi-executor.ts`）。
-- shell handler = `executeDagShellNode`（`src/executors/shell-executor.ts`）；static handler = `executeDagStaticNode`（`src/executors/dag-static-executor.ts`）。
-
-Executor 不得依赖 commands 或 CLI formatting；Cursor 不在受治理路径（`runtime-boundaries.md` §Executors）。
-
-## run-owned skill snapshot
-
-每个新 DAG run 在首个节点执行前冻结本次注入 prompt 的 skill 集合，保证 live skill 后续被修改/删除/补建不会影响当前 run：
-
-| 步骤 | 源码入口 |
-| --- | --- |
-| 首节点前创建 | `runDag` 调 `createSkillSnapshot({ mode: "run-start" })`（`src/workflows/dag/skill-snapshot.ts`） |
-| 写入产物 | `writeSkillSnapshot(runDir, snapshot)` → `<runDir>/.runtime/skill-snapshot.json`（常量 `SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json"`） |
-| state 只存相对引用 | `state.skillSnapshotRef` = `{ schemaVersion, path: ".runtime/skill-snapshot.json", sha256, createdAt, mode }`，**不**存绝对路径 |
-| resume 续用 | `prepareSkillSnapshotForContinuation`（resume 路径，`src/workflows/dag/runner.ts` `resumeDagRun`） |
-| 完整性校验 | 普通节点、dynamic child、approve/resume 都执行 integrity gate，ref/artifact/profile/binding 不一致即 fail closed，不回退实时解析 |
-| legacy 兼容 | 旧 run 只在 ref 与 artifact 都不存在时可标 `legacy-resume-backfill` 并冻结剩余节点 |
-
-snapshot 与 controller identity 是两个不同冻结层，详见 `runtime-boundaries.md` §版本化自举边界。
-
-## decision gate 与 pause
-
-- `isPauseOnHumanDecisionGate`（`src/workflows/dag/decision-envelope.ts`）：`task.decisionGate?.mode === "pause-on-human"` 且 decision gate 启用时，该节点在 rank 内**串行先跑**。
-- `shouldPauseOnHumanEscalation`（`decision-envelope.ts`，在 `src/workflows/dag/node-execution.ts` 调用）：decision envelope 判定需人工升级时，写 `human-escalation.json`（与 `human-escalation.md`）并触发 pause。
-- pause 时 `state.pausedByNodeId` + `pauseReason` + `humanDecisionNodeId` 被写入；`human-escalation.json` 落在 `<runDir>/<nodeId>/`。
-
-decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析自文本）是 `advisoryOnly: true` 派生视图，**不**是完成权威（`facts-and-state.md`）。
-
-## 生命周期：active / paused / completed
-
-`src/workflows/dag/lifecycle.ts` 定义三个目录：
-
-| 目录 | 写入规则 |
-| --- | --- |
-| `.harness/dag-runs/active/<runId>/` | run 进行中 |
-| `.harness/dag-runs/paused/<runId>/` | 触发 pause；resume 需 `human-approval.json` |
-| `.harness/dag-runs/completed/<runId>/` | 终态；除 runner 终态写外只读（`completed-facts-guard.ts`） |
-
-扫描顺序：`DAG_LIFECYCLE_SCAN_ORDER = ["paused", "active", "completed"]`（locate/status 等按此顺序解析 runId）。
-
-关键规则：
-
-- **pause → approve → resume**：`dag approve` 在 paused run 写 `human-approval.json`，将状态改回 `running` 并把目录迁回 `active/`；随后 `resumeDagRun`（`runner.ts`）要求 active lifecycle + approval artifact，并用 `prepareSkillSnapshotForContinuation` 复用 run-owned snapshot。
-- **completed 写入**：只有 runner 在终态 `persistState({ allowCompletedFactsWrite: true })`（`runner.ts`）才能写 completed 目录；该 flag 经 `completed-facts-guard.ts` 校验。
-- **显式 recovery mutation**：`dag reconcile-run`（`src/commands/dag-reconcile-run.ts`，命令层）默认仅检查；只有给出 `--action supersede|abandon` + reason，且 liveness 证明 runner 已停止时，才在原 lifecycle 写 reconciliation/state 并迁移到 `completed/`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
-- **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
-
-## convergence（可选、supervised）
-
-- 控制器：`src/workflows/dag/convergence/controller.ts` `runConvergencePassController`，在 runner rank 间被调用。
-- 特性默认 **off**（`task/config-types.ts` `convergence` 默认 `{ enabled: false }`）。
-- 启用后按 `maxPasses`（默认 3）做多轮 repair，回归时可 `pauseOnRegression`。
-- 产物落在 `<runDir>/convergence/pass-<n>/`。
-
-## 完成权威 = shell verification
-
-完成声明的权威是 shell command 的新鲜 exit code 与归档输出。验证命令执行在 `src/executors/shell-executor.ts`，环境与 preset helper 在 `src/executors/shell-verification.ts`；DAG authoring 写入的 `task.shell.verifyEvidence` 元数据由 `src/workflows/dag/node-execution.ts` 复制到 `node.verifyEvidence`。model verdict、Observe 或报告都不能替代这些 shell facts。
-
-## Dynamic Workflow
-
-Dynamic Workflow 是 DAG runtime 上方的逻辑编排/编译层，**不**重写 runner：
-
-```text
-WorkflowSpec (src/workflows/dynamic/spec.ts workflowSpecSchema)
-  → validate (src/workflows/dynamic/validate.ts)
-  → compile (src/workflows/dynamic/compile.ts compileWorkflowToDag) → DagSpec
-  → 同一 run-dag 执行
-```
-
-- 动态语义：`map_agent` / `verify_agent` / `reduce_agent` / `condition` / `loop_until` / `human_gate` / `command` / `artifact_transform`。
-- agent-like 节点 executor 仅 `pi` | `static`（schema 已不含 `cursor`）。
-- 未完全兑现的 runtime limits 强执法、更广 profile、Loop 原生 `workflow` action 深度编排等仍是**设计输入**，见 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。
+# Agent DAG 执行架构
+
+本页说明 Agent DAG 的主调用链、rank 调度、executor、run-owned skill snapshot、decision gate 与 pause/completed 生命周期。命令面与 `test/cli-contract.test.ts` 一致；符号归属以 `src/` 为准。完整 import 边界与 governance hook 见 `runtime-boundaries.md`。
+
+## 主调用链
+
+### 生成 + 校验 + 执行（`dag run-task`）
+
+```text
+src/commands/dag-run-task.ts  runDagRunTask
+  → src/application/dag/generate-task-dag.ts  generateTaskDagUseCase
+      └─ src/workflows/dag/init-hybrid.ts  initHybridDagFromTask     （生成 DagSpec）
+      └─ src/application/dag/validate-dag.ts  validateDagUseCase      （候选 + 最终校验）
+      └─ assertSafeForExecution                               （执行前安全检查）
+      └─ src/application/dag/run-dag.ts  runDagUseCase              （执行）
+```
+
+`generateTaskDagUseCase` 内部先 `initHybridDagFromTask` 生成 `DagSpec`，再调用 `validateDagUseCase` 做候选与最终两次校验，随后 `assertSafeForExecution` 确认 DAG 可安全执行，最后委托 `runDagUseCase` 执行。`runDagRunTask` 还 `export` 了 `assertSafeForExecution` 供命令层复用。
+
+### 直接执行既有 DAG（`run-dag`）
+
+```text
+src/commands/run-dag.ts
+  → src/application/dag/run-dag.ts  runDagUseCase
+      → src/workflows/dag/runner.ts  runDag
+```
+
+`run-dag` 是 top-level 命令，**不**在 `dag` 子树下（与 `dag run-task` 区分）。`runDagUseCase` 是 application 层 typed use-case，`runDag` 是 workflow runtime 核心。
+
+### 校验
+
+```text
+src/commands/dag-validate.ts  runDagValidate
+  → src/application/dag/validate-dag.ts  validateDagUseCase
+```
+
+### runtime contract preflight 与 repair writer 解析
+
+- `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
+- `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
+- `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
+
+## rank 调度
+
+拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：
+
+| 职责 | 源码入口 | 说明 |
+| --- | --- | --- |
+| 拓扑排序 | `src/workflows/dag/topo.ts` `topoSortToRanks` | Kahn 算法，返回 `string[][]` ranks 并检测环 |
+| 单次 rank 执行 | `src/workflows/dag/scheduler.ts` `executeDagRanksOnce` | rank 间遍历、节点执行编排 |
+| run 主循环 | `src/workflows/dag/runner.ts` `runDag` / `executeDagCheckpoint` | 调用 scheduler + persistence + convergence |
+
+`scheduler.ts` `executeDagRanksOnce` 内每个 rank：
+
+1. `pauseGateRunnable`（满足 `isPauseOnHumanDecisionGate` 的节点，来自 `decision-envelope.ts`）**串行**先跑；任一节点触发 pause 即停止后续。
+2. `regularRunnable` 经 `mapConcurrent` 并发执行，`maxConcurrent` 默认 **4**（`runner.ts` `Math.max(1, opts.maxConcurrent ?? 4)`）。
+3. `rankWriterNodeIds`（`executor === "pi"` && `toolProfile === "write"` && `writePolicy === "exclusive"`）注入同 rank 的不相交 writeSet 上下文（`createExecuteNodeForRank`）。
+4. 依赖未就绪的节点标 `SKIPPED`。
+
+`mapConcurrent` 来自 `src/shared/concurrency.ts`（或等价 shared 工具）。
+
+## executor（Pi-only 受治理 runtime）
+
+- 注册表：`src/workflows/dag/executor-registry.ts`
+  `DEFAULT_DAG_EXECUTOR_REGISTRY = { pi, shell, static }`。
+- schema：`src/workflows/dag/types.ts`
+  `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；DagNodeExecutor 默认 `"pi"`（`executor: dagNodeExecutorSchema.default("pi")`）。
+- `executor: "cursor"` 在 schema refine 阶段抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`（Pi-only = ADR 0001）。
+- Pi handler 先 `requireModel(input)` 校验已解析 model，再委托 `executeDagPiNode`（`src/executors/dag-pi-executor.ts`）。
+- shell handler = `executeDagShellNode`（`src/executors/shell-executor.ts`）；static handler = `executeDagStaticNode`（`src/executors/dag-static-executor.ts`）。
+
+Executor 不得依赖 commands 或 CLI formatting；Cursor 不在受治理路径（`runtime-boundaries.md` §Executors）。
+
+## run-owned skill snapshot
+
+每个新 DAG run 在首个节点执行前冻结本次注入 prompt 的 skill 集合，保证 live skill 后续被修改/删除/补建不会影响当前 run：
+
+| 步骤 | 源码入口 |
+| --- | --- |
+| 首节点前创建 | `runDag` 调 `createSkillSnapshot({ mode: "run-start" })`（`src/workflows/dag/skill-snapshot.ts`） |
+| 写入产物 | `writeSkillSnapshot(runDir, snapshot)` → `<runDir>/.runtime/skill-snapshot.json`（常量 `SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json"`） |
+| state 只存相对引用 | `state.skillSnapshotRef` = `{ schemaVersion, path: ".runtime/skill-snapshot.json", sha256, createdAt, mode }`，**不**存绝对路径 |
+| resume 续用 | `prepareSkillSnapshotForContinuation`（resume 路径，`src/workflows/dag/runner.ts` `resumeDagRun`） |
+| 完整性校验 | 普通节点、dynamic child、approve/resume 都执行 integrity gate，ref/artifact/profile/binding 不一致即 fail closed，不回退实时解析 |
+| legacy 兼容 | 旧 run 只在 ref 与 artifact 都不存在时可标 `legacy-resume-backfill` 并冻结剩余节点 |
+
+snapshot 与 controller identity 是两个不同冻结层，详见 `runtime-boundaries.md` §版本化自举边界。
+
+## decision gate 与 pause
+
+- `isPauseOnHumanDecisionGate`（`src/workflows/dag/decision-envelope.ts`）：`task.decisionGate?.mode === "pause-on-human"` 且 decision gate 启用时，该节点在 rank 内**串行先跑**。
+- `shouldPauseOnHumanEscalation`（`decision-envelope.ts`，在 `src/workflows/dag/node-execution.ts` 调用）：decision envelope 判定需人工升级时，写 `human-escalation.json`（与 `human-escalation.md`）并触发 pause。
+- pause 时 `state.pausedByNodeId` + `pauseReason` + `humanDecisionNodeId` 被写入；`human-escalation.json` 落在 `<runDir>/<nodeId>/`。
+
+decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析自文本）是 `advisoryOnly: true` 派生视图，**不**是完成权威（`facts-and-state.md`）。
+
+## 生命周期：active / paused / completed
+
+`src/workflows/dag/lifecycle.ts` 定义三个目录：
+
+| 目录 | 写入规则 |
+| --- | --- |
+| `.harness/dag-runs/active/<runId>/` | run 进行中 |
+| `.harness/dag-runs/paused/<runId>/` | 触发 pause；resume 需 `human-approval.json` |
+| `.harness/dag-runs/completed/<runId>/` | 终态；除 runner 终态写外只读（`completed-facts-guard.ts`） |
+
+扫描顺序：`DAG_LIFECYCLE_SCAN_ORDER = ["paused", "active", "completed"]`（locate/status 等按此顺序解析 runId）。
+
+关键规则：
+
+- **pause → approve → resume**：`dag approve` 在 paused run 写 `human-approval.json`，将状态改回 `running` 并把目录迁回 `active/`；随后 `resumeDagRun`（`runner.ts`）要求 active lifecycle + approval artifact，并用 `prepareSkillSnapshotForContinuation` 复用 run-owned snapshot。
+- **completed 写入**：只有 runner 在终态 `persistState({ allowCompletedFactsWrite: true })`（`runner.ts`）才能写 completed 目录；该 flag 经 `completed-facts-guard.ts` 校验。
+- **显式 recovery mutation**：`dag reconcile-run`（`src/commands/dag-reconcile-run.ts`，命令层）默认仅检查；只有给出 `--action supersede|abandon` + reason，且 liveness 证明 runner 已停止时，才在原 lifecycle 写 reconciliation/state 并迁移到 `completed/`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
+- **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
+
+## convergence（可选、supervised）
+
+- 控制器：`src/workflows/dag/convergence/controller.ts` `runConvergencePassController`，在 runner rank 间被调用。
+- 特性默认 **off**（`task/config-types.ts` `convergence` 默认 `{ enabled: false }`）。
+- 启用后按 `maxPasses`（默认 3）做多轮 repair，回归时可 `pauseOnRegression`。
+- 产物落在 `<runDir>/convergence/pass-<n>/`。
+
+## 完成权威 = shell verification
+
+完成声明的权威是 shell command 的新鲜 exit code 与归档输出。验证命令执行在 `src/executors/shell-executor.ts`，环境与 preset helper 在 `src/executors/shell-verification.ts`；DAG authoring 写入的 `task.shell.verifyEvidence` 元数据由 `src/workflows/dag/node-execution.ts` 复制到 `node.verifyEvidence`。model verdict、Observe 或报告都不能替代这些 shell facts。
+
+## Dynamic Workflow
+
+Dynamic Workflow 是 DAG runtime 上方的逻辑编排/编译层，**不**重写 runner：
+
+```text
+WorkflowSpec (src/workflows/dynamic/spec.ts workflowSpecSchema)
+  → validate (src/workflows/dynamic/validate.ts)
+  → compile (src/workflows/dynamic/compile.ts compileWorkflowToDag) → DagSpec
+  → 同一 run-dag 执行
+```
+
+- 动态语义：`map_agent` / `verify_agent` / `reduce_agent` / `condition` / `loop_until` / `human_gate` / `command` / `artifact_transform`。
+- agent-like 节点 executor 仅 `pi` | `static`（schema 已不含 `cursor`）。
+- 未完全兑现的 runtime limits 强执法、更广 profile、Loop 原生 `workflow` action 深度编排等仍是**设计输入**，见 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。

package/docs/architecture/evolution.md

@@ -1,53 +1,54 @@
-# 架构演进：当前 vs 未来
-
-本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0003、`docs/exec-plans/completed/`。
-
-## 当前已实现（0.11.0）
-
-| 域 | 现状 | 权威入口 |
-| --- | --- | --- |
-| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
-| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
-| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/{spec,validate,compile}.ts`、`website/docs/guides/dynamic-workflow.md` |
-| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
-| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
-| Task Pool | 唯一根 `.harness/task-pool/` | ADR 0002 |
-| Observe | 本地只读暖白运营控制台 R1–R5（derived） | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]` |
-| DagSpec / repair | v3 + `runtimeContract`；显式 `repairNodeId` | `CHANGELOG.md [0.11.0]`、`dag-execution.md` |
-| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
-| 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
-
-### 受治理 runtime 的边界（已实现、不变式）
-
-- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
-- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
-- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
-
-## 未来规划（第 3–6 月，**未实现**）
-
-以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
-
-| 未来方向 | 状态 | 规划来源 |
-| --- | --- | --- |
-| 远程 PR / CI | 规划 / 未实现 | `docs/design/六个月规划.md`（第 3 个月起） |
-| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
-| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
-| 多仓库平台 | 规划 / 未实现 | 同上 |
-| 组织级服务 | 规划 / 未实现 | 同上 |
-| Web Console（远端） | 规划 / 未实现 | 同上 |
-| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
-| Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
-
-> 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
-
-## 已收敛为 archive / 历史基线（非未来）
-
-- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
-- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
-- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
-
-## 文档本体的演进边界
-
-- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface（AC-7）；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
-- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
-- 未来如有能力落地，应先改 `src/`/CLI/ADR/completed plan，再回写本目录的「已实现」表。
+# 架构演进：当前 vs 未来
+
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0004、`docs/exec-plans/completed/` 与 active identity plan 的 progress。
+
+## 当前已实现（0.11.0）
+
+| 域 | 现状 | 权威入口 |
+| --- | --- | --- |
+| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
+| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
+| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/{spec,validate,compile}.ts`、`website/docs/guides/dynamic-workflow.md` |
+| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
+| Task Pool | 唯一根 `.harness/task-pool/`；**feature-scoped** state v2（`TaskPoolTaskRef`） | ADR 0002、ADR 0004 |
+| 本地多 Feature 运营 | 同仓库多 Feature 可共用 Task ID；Ready / retry / Delivery / Observe 按 Feature 隔离 | ADR 0004、`docs/progress/2026-07-15-task-pool-v2-feature-scoped-task-identity.md` |
+| Observe | 本地只读暖白运营控制台 R1–R5（derived）；canonical Task route 为 feature-scoped | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]`、ADR 0004 |
+| DagSpec / repair | v3 + `runtimeContract`；显式 `repairNodeId` | `CHANGELOG.md [0.11.0]`、`dag-execution.md` |
+| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
+
+### 受治理 runtime 的边界（已实现、不变式）
+
+- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
+- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
+- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
+
+## 未来规划（第 3–6 月，**未实现**）
+
+以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+
+| 未来方向 | 状态 | 规划来源 |
+| --- | --- | --- |
+| 远程 PR / CI | 规划 / 未实现 | `docs/design/六个月规划.md`（第 3 个月起） |
+| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
+| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
+| 多仓库平台 | 规划 / 未实现 | 同上 |
+| 组织级服务 | 规划 / 未实现 | 同上 |
+| Web Console（远端） | 规划 / 未实现 | 同上 |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
+| Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
+
+> 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+
+## 已收敛为 archive / 历史基线（非未来）
+
+- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
+- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
+- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
+
+## 文档本体的演进边界
+
+- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface（AC-7）；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
+- 未来如有能力落地，应先改 `src/`/CLI/ADR/completed plan，再回写本目录的「已实现」表。

package/docs/architecture/facts-and-state.md

@@ -1,58 +1,71 @@
-# 事实与状态
-
-本页说明 `.harness/` 各根目录、canonical facts、derived read models 与不可变规则，并逐条标出 canonical|derived 与 writable|read-only。完成权威是 shell verification（ADR 0001）；model verdict、Observe、报告都是 derived 或 advisory 视图。
-
-## 六类运行态对象
-
-| 对象 | 物理根 | 源码入口 | 性质 |
-| --- | --- | --- | --- |
-| Task | `.harness/tasks/<taskId>/` | `src/task/runtime.ts` `getTaskDir` | canonical，可写 |
-| DAG run | `.harness/dag-runs/{active,paused,completed}/<runId>/` | `src/workflows/dag/lifecycle.ts` `DAG_RUNS_DIR` | canonical，active/paused 可写；completed 受 guard |
-| one-shot run | `.harness/runs/{active,completed,failed}/<slug>/` | `src/infrastructure/harness/one-shot-run-store.ts`（逻辑封装见 `src/records/one-shot-runs.ts`） | canonical；active 可写，completed/failed 为终态事实 |
-| Loop | `.harness/tasks/<taskId>/loop/` | `src/workflows/loop/**` | canonical，**不是独立根**，是 task 之上的多轮状态机 |
-| Task Pool | `.harness/task-pool/`（唯一根） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002） | canonical，可写（Worker 专用，可选） |
-| Observe snapshot | Worker 内存/HTTP 派生视图 | `src/worker/observability/read-model.ts` `buildGlobalSnapshot` | **derived**，advisory |
-
-### 区分要点
-
-- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、controller identity（`controller-identity.json`，冻结执行 controller 的 package version/binary 哈希/portable fingerprint，state 记录相对 ref 与内容哈希，resume 时重新校验、漂移 fail closed）、decision envelope、convergence。
-- **DAG run vs one-shot run**：DAG run 在 `.harness/dag-runs/`，有三态 lifecycle；one-shot run（当前主要由 `cursor-prompt` 及显式 one-shot evidence 路径产生）在 `.harness/runs/`，三态为 `active|completed|failed`。`pi-prompt` 当前不创建该目录下的 run evidence。两者是不同根、不同 schema。
-- **Loop 不是顶层根**：Loop 状态在 `.harness/tasks/<taskId>/loop/`，是 task 之上的多轮状态机（round、signal、context、failureStreak、closeout）。
-- **Task Pool 是 Worker 专用可选根**：只有使用 `agent-worker` 产品线时才存在；唯一根 `.harness/task-pool/`。
-- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
-
-## canonical（可写）
-
-- `.harness/tasks/<taskId>/` — `getTaskDir`。
-- `.harness/dag-runs/{active,paused}/<runId>/` — run 进行中 / 暂停。
-- `.harness/runs/active/<slug>/` — one-shot 运行中；完成或失败后通过 store 迁移到终态目录。
-- `.harness/tasks/<taskId>/loop/` — Loop 状态机。
-- `.harness/task-pool/` — Worker Task Pool（可选）。
-
-`.harness/prompts/` 与 `.harness/init-surface.json` 属于初始化投影/控制资料，不是一次执行的 canonical run fact，需与上面的任务和 run 对象区分。
-
-## canonical（只读 / 不可变）
-
-- `.harness/dag-runs/completed/<runId>/` — 除 runner 终态 `persistState({ allowCompletedFactsWrite: true })` 与显式 `dag reconcile-run`（`--action supersede|abandon` + reason，runner 已证明停止）外只读。
-- `.harness/runs/completed/<slug>/` 与 `.harness/runs/failed/<slug>/` — one-shot 终态事实；公共写接口只对 active run 开放，完成/失败通过 store 迁移。
-- `completed-facts-guard.ts`（`src/infrastructure/harness/`）是 completed 路径 enforcement 入口：`assertHarnessWriteAllowed(targetPath, { repoRoot, allowCompletedFactsWrite? })`。
-- promotion（completed → task artifacts 回填）由 `src/records/promotion.ts` 经 `loadCompletedDagEvidence` 读 completed state 后写 task artifacts。
-
-## derived / advisory（不可作完成权威）
-
-| 视图 | 来源 | 为何不可作权威 |
-| --- | --- | --- |
-| Observe snapshot / 首页 KPI | `buildGlobalSnapshot` 投影 `.harness/` + Task Pool | derived；投影失败安全降级 |
-| decision envelope 的 model verdict | `decision` / `riskLevel` 解析自文本 | `advisoryOnly: true`（`decision-envelope.ts` / `decision-evidence.ts` / `lifecycle.ts`） |
-| canvas / event observer | `notifyRunObserver` / `notifyNodeObserver` | try/catch 吞；明确派生视图，不 affect canonical 执行 |
-| DAG report / doctor | `src/application/dag/report-dag.ts` + `src/workflows/dag/report.ts`；doctor 在 `src/workflows/dag/lifecycle.ts` | 只读总结，operator 决策辅助 |
-| knowledge-curator proposal | `src/workflows/dag/knowledge-curator.ts` | advisory process guidance，不改 accepted learned skill |
-| morning report / metrics | `src/worker/report/**` | derived 统计，含分母/样本量/缺失说明 |
-
-## 完成权威
-
-完成权威 = shell command 的 exit code 与归档 stdout/stderr。执行入口是 `src/executors/shell-executor.ts`，环境/preset helper 在 `src/executors/shell-verification.ts`；`node.verifyEvidence` 保存 DAG authoring 提供的验证阶段、命令来源与标签等元数据。model verdict、Observe、报告都不构成完成判定。
-
-## init 投影的 `.harness` 入口
-
-`init --profile full` 在目标项目创建 `.harness/tasks`（directory）、`.harness/dag-runs/active`（directory）、`.harness/prompts/analyze.md`（generated）、`.harness/init-surface.json`（state）。这些是 init surface，不在 `packageExcluded`/`initExcluded` 范围；详见 `docs/init-surface.manifest.json`。
+# 事实与状态
+
+本页说明 `.harness/` 各根目录、canonical facts、derived read models 与不可变规则，并逐条标出 canonical|derived 与 writable|read-only。完成权威是 shell verification（ADR 0001）；model verdict、Observe、报告都是 derived 或 advisory 视图。
+
+## 六类运行态对象
+
+| 对象 | 物理根 | 源码入口 | 性质 |
+| --- | --- | --- | --- |
+| Task | `.harness/tasks/<taskId>/` | `src/task/runtime.ts` `getTaskDir` | canonical，可写 |
+| DAG run | `.harness/dag-runs/{active,paused,completed}/<runId>/` | `src/workflows/dag/lifecycle.ts` `DAG_RUNS_DIR` | canonical，active/paused 可写；completed 受 guard |
+| one-shot run | `.harness/runs/{active,completed,failed}/<slug>/` | `src/infrastructure/harness/one-shot-run-store.ts`（逻辑封装见 `src/records/one-shot-runs.ts`） | canonical；active 可写，completed/failed 为终态事实 |
+| Loop | `.harness/tasks/<taskId>/loop/` | `src/workflows/loop/**` | canonical，**不是独立根**，是 task 之上的多轮状态机 |
+| Task Pool | `.harness/task-pool/`（唯一根；state v2 见下） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002 / 0004） | canonical，可写（Worker 专用，可选） |
+| Observe snapshot | Worker 内存/HTTP 派生视图 | `src/worker/observability/read-model.ts` `buildGlobalSnapshot` | **derived**，advisory |
+
+### 区分要点
+
+- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、controller identity（`controller-identity.json`，冻结执行 controller 的 package version/binary 哈希/portable fingerprint，state 记录相对 ref 与内容哈希，resume 时重新校验、漂移 fail closed）、decision envelope、convergence。
+- **DAG run vs one-shot run**：DAG run 在 `.harness/dag-runs/`，有三态 lifecycle；one-shot run（当前主要由 `cursor-prompt` 及显式 one-shot evidence 路径产生）在 `.harness/runs/`，三态为 `active|completed|failed`。`pi-prompt` 当前不创建该目录下的 run evidence。两者是不同根、不同 schema。
+- **Loop 不是顶层根**：Loop 状态在 `.harness/tasks/<taskId>/loop/`，是 task 之上的多轮状态机（round、signal、context、failureStreak、closeout）。
+- **Task Pool 是 Worker 专用可选根**：只有使用 `agent-worker` 产品线时才存在；唯一根 `.harness/task-pool/`。
+- **Task Pool state identity（ADR 0004）**：canonical 键为 `{ featureId, taskId }`（`TaskPoolTaskRef`），不是裸 `taskId`。
+- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
+
+### Task Pool state 布局与迁移
+
+| 路径 / 对象 | 性质 | 说明 |
+| --- | --- | --- |
+| `.harness/task-pool/states/<featureId>/<taskId>.json` | canonical 可写 | schema v2；路径解码 identity 必须与文件内容一致 |
+| `.harness/task-pool/states/<taskId>.json`（扁平 v1） | legacy | 不得静默猜 Feature；存在时 v2 写入 fail-closed |
+| `.harness/task-pool/runs.jsonl` / `events.jsonl` | canonical append-only | migration 不改写 JSONL；`workerRunId` 仍是执行历史键 |
+| `agent-worker pool doctor` | 只读诊断 | inventory + mapping 证据；exit 0 可有 findings |
+| `agent-worker pool migrate-state` | 显式迁移 | 默认 dry-run；`--apply --owner --reason` 才写入；失败全回滚 |
+
+`readFeatureTaskPoolStates` / `listTaskPoolStates` 是 v2 列表入口；deprecated `readAllTaskPoolStates` 仅扫描 legacy 扁平 state，不合并 v2。
+
+## canonical（可写）
+
+- `.harness/tasks/<taskId>/` — `getTaskDir`。
+- `.harness/dag-runs/{active,paused}/<runId>/` — run 进行中 / 暂停。
+- `.harness/runs/active/<slug>/` — one-shot 运行中；完成或失败后通过 store 迁移到终态目录。
+- `.harness/tasks/<taskId>/loop/` — Loop 状态机。
+- `.harness/task-pool/` — Worker Task Pool（可选）。
+
+`.harness/prompts/` 与 `.harness/init-surface.json` 属于初始化投影/控制资料，不是一次执行的 canonical run fact，需与上面的任务和 run 对象区分。
+
+## canonical（只读 / 不可变）
+
+- `.harness/dag-runs/completed/<runId>/` — 除 runner 终态 `persistState({ allowCompletedFactsWrite: true })` 与显式 `dag reconcile-run`（`--action supersede|abandon` + reason，runner 已证明停止）外只读。
+- `.harness/runs/completed/<slug>/` 与 `.harness/runs/failed/<slug>/` — one-shot 终态事实；公共写接口只对 active run 开放，完成/失败通过 store 迁移。
+- `completed-facts-guard.ts`（`src/infrastructure/harness/`）是 completed 路径 enforcement 入口：`assertHarnessWriteAllowed(targetPath, { repoRoot, allowCompletedFactsWrite? })`。
+- promotion（completed → task artifacts 回填）由 `src/records/promotion.ts` 经 `loadCompletedDagEvidence` 读 completed state 后写 task artifacts。
+
+## derived / advisory（不可作完成权威）
+
+| 视图 | 来源 | 为何不可作权威 |
+| --- | --- | --- |
+| Observe snapshot / 首页 KPI | `buildGlobalSnapshot` 投影 `.harness/` + Task Pool | derived；投影失败安全降级 |
+| decision envelope 的 model verdict | `decision` / `riskLevel` 解析自文本 | `advisoryOnly: true`（`decision-envelope.ts` / `decision-evidence.ts` / `lifecycle.ts`） |
+| canvas / event observer | `notifyRunObserver` / `notifyNodeObserver` | try/catch 吞；明确派生视图，不 affect canonical 执行 |
+| DAG report / doctor | `src/application/dag/report-dag.ts` + `src/workflows/dag/report.ts`；doctor 在 `src/workflows/dag/lifecycle.ts` | 只读总结，operator 决策辅助 |
+| knowledge-curator proposal | `src/workflows/dag/knowledge-curator.ts` | advisory process guidance，不改 accepted learned skill |
+| morning report / metrics | `src/worker/report/**` | derived 统计，含分母/样本量/缺失说明 |
+
+## 完成权威
+
+完成权威 = shell command 的 exit code 与归档 stdout/stderr。执行入口是 `src/executors/shell-executor.ts`，环境/preset helper 在 `src/executors/shell-verification.ts`；`node.verifyEvidence` 保存 DAG authoring 提供的验证阶段、命令来源与标签等元数据。model verdict、Observe、报告都不构成完成判定。
+
+## init 投影的 `.harness` 入口
+
+`init --profile full` 在目标项目创建 `.harness/tasks`（directory）、`.harness/dag-runs/active`（directory）、`.harness/prompts/analyze.md`（generated）、`.harness/init-surface.json`（state）。这些是 init surface，不在 `packageExcluded`/`initExcluded` 范围；详见 `docs/init-surface.manifest.json`。