@tea-agent/loop-agent 0.13.0 → 0.14.0

package/docs/agent-dag-runner.md

@@ -1,67 +1,67 @@
-# Agent DAG Runner
-
-Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
-
-## 基本用法
-
-```bash
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
-
-## Executors
-
-- `static`：确定性生成的 artifacts 或 notes
-- `shell`：验证与文件系统检查
-- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-
-## Retry (read-only Pi nodes)
-
-planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
-
-- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
-- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
-- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
-- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
-- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
-
-示例：
-
-```json
-{
-  "retryPolicy": {
-    "maxAttempts": 3,
-    "backoff": "exponential",
-    "initialDelayMs": 2000,
-    "maxDelayMs": 30000,
-    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
-  }
-}
-```
-
-未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
-
-## Skills
-
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `.agents/skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
-
-执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `ai_workspace/loop-agent/.agents/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
-
-目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `.agents/skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
-
-## Artifacts
-
-DAG artifacts 位于：
-
-```text
-.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
-```
-
-根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
-
-## Shell Gates
-
-- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。
+# Agent DAG Runner
+
+Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
+
+## 基本用法
+
+```bash
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
+
+## Executors
+
+- `static`：确定性生成的 artifacts 或 notes
+- `shell`：验证与文件系统检查
+- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
+
+## Retry (read-only Pi nodes)
+
+planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
+
+- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
+- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
+- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
+- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
+- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
+
+示例：
+
+```json
+{
+  "retryPolicy": {
+    "maxAttempts": 3,
+    "backoff": "exponential",
+    "initialDelayMs": 2000,
+    "maxDelayMs": 30000,
+    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
+  }
+}
+```
+
+未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
+
+## Skills
+
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `.agents/skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
+
+执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `ai_workspace/loop-agent/.agents/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
+
+目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `.agents/skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
+
+## Artifacts
+
+DAG artifacts 位于：
+
+```text
+.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
+```
+
+根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
+
+## Shell Gates
+
+- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。

package/docs/architecture/README.md

@@ -1,26 +1,26 @@
-# 架构文档索引
-
-本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
-
-## 阅读路径
-
-建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
-
-1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
-2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
-3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
-4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
-5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
-6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
-
-## 事实与规划的区分
-
-- **当前事实源**：`src/` 源码、发布 CLI、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
-- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
-- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
-
-## 与其他文档的分工
-
-- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
-- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
-- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+# 架构文档索引
+
+本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
+
+## 阅读路径
+
+建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
+
+1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
+2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
+4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
+5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
+6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
+
+## 事实与规划的区分
+
+- **当前事实源**：`src/` 源码、发布 CLI、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
+- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
+
+## 与其他文档的分工
+
+- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
+- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。

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 深度编排等仍是**设计输入**，见 `ai_workspace/loop-agent/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 深度编排等仍是**设计输入**，见 `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。

package/docs/architecture/evolution.md

@@ -1,54 +1,54 @@
-# 架构演进：当前 vs 未来
-
-本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0004、`ai_workspace/loop-agent/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 | `ai_workspace/loop-agent/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
-| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `ai_workspace/loop-agent/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、`ai_workspace/loop-agent/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 `ai_workspace/loop-agent/` 治理；docs-converge | ADR 0003 |
-| 文档治理 | `ai_workspace/loop-agent/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 月，**未实现**）
-
-以下能力来自 `ai_workspace/loop-agent/design/六个月规划.md` 与 `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
-
-| 未来方向 | 状态 | 规划来源 |
-| --- | --- | --- |
-| 远程 PR / CI | 规划 / 未实现 | `ai_workspace/loop-agent/design/六个月规划.md`（第 3 个月起） |
-| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
-| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
-| 多仓库平台 | 规划 / 未实现 | 同上 |
-| 组织级服务 | 规划 / 未实现 | 同上 |
-| Web Console（远端） | 规划 / 未实现 | 同上 |
-| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
-| Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
-
-> 注意：`ai_workspace/loop-agent/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 指针，不在本文展开：`ai_workspace/loop-agent/design/archive/2026-07-12-第二月规划.md`。
-- `ai_workspace/loop-agent/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
-- 活能力短摘要在 `ai_workspace/loop-agent/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`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0004、`ai_workspace/loop-agent/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 | `ai_workspace/loop-agent/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `ai_workspace/loop-agent/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、`ai_workspace/loop-agent/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 `ai_workspace/loop-agent/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | `ai_workspace/loop-agent/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 月，**未实现**）
+
+以下能力来自 `ai_workspace/loop-agent/design/六个月规划.md` 与 `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+
+| 未来方向 | 状态 | 规划来源 |
+| --- | --- | --- |
+| 远程 PR / CI | 规划 / 未实现 | `ai_workspace/loop-agent/design/六个月规划.md`（第 3 个月起） |
+| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
+| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
+| 多仓库平台 | 规划 / 未实现 | 同上 |
+| 组织级服务 | 规划 / 未实现 | 同上 |
+| Web Console（远端） | 规划 / 未实现 | 同上 |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `ai_workspace/loop-agent/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
+| Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
+
+> 注意：`ai_workspace/loop-agent/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 指针，不在本文展开：`ai_workspace/loop-agent/design/archive/2026-07-12-第二月规划.md`。
+- `ai_workspace/loop-agent/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
+- 活能力短摘要在 `ai_workspace/loop-agent/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，再回写本目录的「已实现」表。