@tea-agent/loop-agent 0.2.1 → 0.4.0

package/docs/dynamic-workflow-dag-engine-roadmap.md

@@ -1,1749 +1,1749 @@
-# loop-agent Dynamic Workflow DAG Engine 阶段规划
-
-版本：0.2
-日期：2026-07-04
-适用项目：`loop-agent`
-目标读者：项目维护者、实现者、后续接手的 coding agent
-
----
-
-## 0. 摘要
-
-`loop-agent` 当前已经具备一个较成熟的 **DAG runtime**：它能把 AI coding task 固化为本地任务目录，生成/校验 Agent DAG，调度 Cursor、Pi、shell、static 等 executor，保存 artifacts、logs、decision envelope、report，并以 shell verification 作为完成证据。
-
-2026-07-04 复核当前代码后，结论是：
-
-> 这个架构方向适合当前项目，但只适合作为 **现有 DAG runtime 上方的逻辑编排/编译层**。
-> 不适合重写 runner，不适合恢复已删除的 Level 1 顺序 fallback，也不适合照搬 Claude Dynamic Workflows 的 JavaScript script 形态。
-
-当前更合适的方向是：
-
-> 在现有 DAG runtime 上方新增一个 **Dynamic Workflow DAG Engine**。
-> LLM 或 profile 先生成受 schema 约束的 `WorkflowSpec`；engine 对其做校验、风险分析、动态展开和编译；最终产物仍然交给现有 `run-dag` 执行。
-
-核心分层：
-
-```text
-Loop Task
-  管多轮目标、round、signal、context、failureStreak、closeout
-
-Dynamic Workflow DAG Engine
-  管一次 run 内的动态拆解、map/reduce/verify/condition/loop_until/human_gate
-
-DAG runtime
-  管 concrete DAG 的 validate、schedule、execute、retry、resume、artifact、report
-
-Executors
-  Cursor / Pi / shell / static
-```
-
-一句话定位：
-
-> DAG runtime 解决“如何可靠执行具体 DAG”；Dynamic Workflow DAG Engine 解决“如何把复杂任务动态编译成具体 DAG”；Loop Task 解决“多次 workflow/DAG/shell/review round 如何形成长期目标闭环”。
-
-### 0.1 适配性判断
-
-| 判断 | 结论 | 原因 |
-|---|---|---|
-| 是否值得做 | 值得，但应分阶段 | 现有 DAG runtime 已经提供 executor、artifact、approval、report、resume 的深 Module，Dynamic Workflow 可以复用这些 leverage |
-| 是否应改 runner 为 JS workflow runtime | 不应 | 任意脚本会削弱 schema 审计、权限分析和 repo governance |
-| 是否应先做自动修代码 workflow | 不应 | 当前最稳的 MVP 是 read-only PR/code review，先验证 fan-out、verifier、reducer |
-| 是否应马上接入 Loop | 不应前置 | Loop 现在已有 `dag` action；workflow action 应在 WorkflowSpec/compile/report 稳定后再接 |
-| 最大技术风险 | runtime expansion | 当前 `run-dag` 基于静态 `DagSpec.tasks` 和 topo ranks；真正动态插入节点需要 runner 层扩展 |
-| 第一优先级 | WorkflowSpec schema + validator + static compiler | 这能先形成可审查 artifact，并证明能编译到现有 `DagSpec` |
-
-### 0.2 当前代码对本设计的约束
-
-- `DagTask.id` 当前必须是 kebab-case：`/^[a-z][a-z0-9-]*$/`。WorkflowSpec 示例也应使用 kebab-case，或由 compiler 显式维护 workflow id 到 DAG id 的映射。
-- `DagSpec` 目前没有通用 metadata 字段；未知字段不会成为稳定契约。若要保留 `workflowRef`、`workflowNodeId`、compile manifest，应新增明确 schema 字段或使用 sidecar manifest。
-- `run-dag` 当前启动时从完整 `DagSpec.tasks` 计算 topo ranks；Phase 3 以前不应假设 child nodes 能自然“进入 existing scheduler”。
-- DAG 已有 `decisionGate`、`dag approve`、`dag reject`、`dag resume` 和 paused lifecycle。`human_gate` 应优先编译到这套已有机制，而不是发明第二套 approval runtime。
-- `loop` 当前支持 `shell-verify`、`pi-review`、`cursor-fix`、`dag`、`record-round`、`add-signal`、`closeout`；没有 `workflow` action。
-- Level 1 顺序 fallback 已在 `refactor: remove level1 fallback` 后删除；本文档不得再把 `src/workflows/level1/` 描述为保留兼容路径。
-
----
-
-## 1. 思想来源
-
-### 1.1 Claude Dynamic Workflows 的核心启发
-
-Claude Code Dynamic Workflows 的官方定义是：Claude 为任务写出一个 JavaScript orchestration script，runtime 在后台执行它；workflow 适用于 codebase audit、大规模 migration、cross-checked research 等超出单轮对话协调能力的任务。官方文档强调，workflow 与 subagents / skills / agent teams 的关键区别不是“能不能多 agent”，而是 **谁持有计划**：subagent 和 agent team 仍由 Claude 或 lead agent 逐轮决定下一步；workflow 由 script 决定下一步，中间状态存在 script variables 中，而不是反复塞回模型上下文。官方文档还明确提到 workflow 可以将 repeatable quality pattern 编码化，例如让独立 agents adversarially review each other’s findings，再进入最终报告。[1]
-
-Claude 方案的关键模式：
-
-```text
-用户目标
-  -> workflow script / runtime 持有计划
-  -> fan-out 多个 subagents
-  -> 中间结果留在 runtime state
-  -> verifier / reducer 过滤、去重、排序
-  -> session 只接收最终结果
-```
-
-官方文档列出的典型场景包括：
-
-- 审计许多文件中的同一类问题。
-- 持续修复直到检查通过。
-- 并行迁移大量文件。
-- Review every changed file and write one summary。
-- 跨多个来源 research 并交叉验证。
-- Find issues until the list stops growing。[1]
-
-### 1.2 对 loop-agent 更合适的改造：JS script -> Dynamic DAG IR
-
-Claude 的 JS workflow 具有强表达力，但对 `loop-agent` 这种希望产品化、可审计、本地治理的 runtime 来说，JS script 不是最优 IR。更好的方向是：
-
-```text
-LLM / profile 生成 WorkflowSpec JSON
-  -> schema validator
-  -> risk / permission analyzer
-  -> compiler / dynamic expander
-  -> concrete Agent DAG
-  -> existing DAG runtime
-```
-
-原因：
-
-| 维度 | Claude JS workflow | Dynamic DAG IR |
-|---|---|---|
-| 表达力 | 很强，天然支持 JS loop / branch / variables | 中等，需要 node type 扩展 |
-| 安全审计 | 需要审 JS code | 可以审 schema + primitive |
-| 权限分析 | 较难静态判断 | 容易做 limits / permissions / writeSet 检查 |
-| 可视化 | 脚本不天然图形化 | DAG / logical workflow 天然可视化 |
-| 恢复与重放 | 可以，但依赖 script runtime | 可以基于 run state / artifact ref / compiled DAG 做强恢复 |
-| 产品化 | 面向 Claude Code 内部体验 | 更适合 repo-local CLI + governance |
-
-因此，本项目不应追求“复刻 Claude 的 JS script”，而应复刻其操作系统思想：
-
-> 编排权离开模型上下文，进入一个可读、可校验、可恢复、可复跑的 workflow artifact。
-
-### 1.3 本项目已有思想基础
-
-`loop-agent` 当前已经具备以下基础：
-
-- repo-local task harness。
-- Agent DAG 编排。
-- DAG validation。
-- DAG report / doctor / recovery recommendation。
-- decision envelope、human approval/rejection、paused/resume lifecycle。
-- supervised DAG convergence pass。
-- Cursor / Pi / shell / static executor registry。
-- `shell-verification` Module，供 DAG shell executor 复用。
-- DAG-oriented task read model。
-- `.harness/` 运行态状态与 artifacts。
-- shell verification 作为完成权威。
-- governance 检查。
-- Loop 长周期 round / signal / closeout 状态机。
-
-这些能力说明当前项目已经拥有 Dynamic Workflow 所需的执行内核和治理底座。缺少的不是“再写一个 runtime”，而是上一层的 **WorkflowSpec + workflow validator + risk analyzer + compiler + dynamic expansion + workflow report + workflow/loop integration**。
-
----
-
-## 2. 当前代码现状判断
-
-基于当前仓库分析，`loop-agent` 可以被描述为：
-
-> 一个 repo-local agent workflow runtime。它为 AI coding agent 提供任务 harness、Agent DAG 编排、Cursor/Pi 执行器集成、确定性 shell 验证、运行证据归档和治理检查，让长期或复杂的 agent 实现工作可以被审查、恢复和交付。
-
-本次复核依据的关键代码与文档：
-
-- `docs/feature-workflow.md`
-- 源码仓库历史 completed execution plan: remove-level1-fallback
-- `src/workflows/dag/types.ts`
-- `src/workflows/dag/validate.ts`
-- `src/workflows/dag/runner.ts`
-- `src/workflows/dag/lifecycle.ts`
-- `src/workflows/dag/report.ts`
-- `src/workflows/dag/init-hybrid.ts`
-- `src/workflows/loop/actions.ts`
-- `src/commands/loop.ts`
-- `src/commands/dag-run-task.ts`
-- `src/commands/dag-validate.ts`
-- `src/task/read-model.ts`
-- `src/cli/catalog.ts`
-
-### 2.1 当前主路径
-
-当前主推荐路径已经是 DAG：
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output /tmp/<task-id>-dag.json
-loop-agent dag validate --dag /tmp/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag /tmp/<task-id>-dag.json --cwd .
-```
-
-主路径语义：
-
-| 命令 | 作用 |
-|---|---|
-| `new-task` | 创建 `.harness/tasks/<taskId>` 和 task config/source 结构；legacy workflow state 只作为兼容读输入 |
-| `dag run-task` | 根据任务上下文生成 DAG 草案 |
-| `dag validate` | 校验依赖、写入策略、shell 配置、decision gate、同 rank 写冲突等 |
-| `run-dag` | 执行 DAG，生成 `.harness/dag-runs/<lifecycle>/<runId>` 下的状态、节点 artifacts、报告材料 |
-
-### 2.2 当前目录职责
-
-| 路径 | 当前职责 | 对 Dynamic Workflow 的意义 |
-|---|---|---|
-| `src/workflows/dag/` | Agent DAG 类型、校验、执行、报告、decision envelope、recovery 建议 | 保留为 concrete DAG runtime 内核 |
-| `src/commands/` | 顶层命令实现，当前命令文件是扁平布局 | 先新增 `dag workflow-*` 子命令实现；稳定后再考虑顶层 `workflow` |
-| `src/task/` | `.harness/tasks/<taskId>` 的 task config、state、artifact、source hash、read model | WorkflowSpec / compiled DAG 可以落在 task 目录下，read model 后续应能暴露 workflow refs |
-| `src/executors/` | Cursor、Pi、shell、static executor 适配 | Dynamic engine 不绕过 executor，只生成节点给 executor 执行 |
-| `src/governance/` | skill safety、repo governance 等规则检查 | 扩展到 workflow-level risk / permission analyzer |
-| `.harness/` | runtime state、tasks、dag-runs、runs、prompts、缓存、live state | 新增 workflow planned/compiled/report state |
-| `src/executors/shell-verification.ts` | shell verification preset、command execution/report/env policy | Workflow command node 应复用这里的 shell 语义 |
-| `src/task/read-model.ts` | DAG-oriented task status / next action 推导 | 后续纳入 workflow planned/compiled/run/report refs |
-
-### 2.3 当前 Loop 语义
-
-顶层 `loop` 已经是 DAG 之上的长周期任务状态机：
-
-```text
-DAG 管一轮怎么执行和验证；
-Loop 管多轮为什么继续、下一步做什么、哪些事实已经验证、何时暂停或收口。
-```
-
-Loop 当前维护：
-
-```text
-.harness/tasks/<taskId>/loop/
-  objective.md
-  context.md
-  state.json
-  rounds.jsonl
-  signals.jsonl
-  events.jsonl
-  verification/
-  review/
-  closeout.md
-```
-
-Loop state 中已有适合与 Dynamic Workflow 对接的字段：
-
-| 字段 | 结合点 |
-|---|---|
-| `openFrontier` | 选择下一轮 workflow profile |
-| `failureStreak` | 决定继续、暂停、升级或换 workflow |
-| `completedCriteria` | 判断 closeout 是否可完成 |
-| `signals.jsonl` | 将 human instruction / approval / scope change 作为 workflow inputs |
-| `rounds.jsonl` | 记录 workflow run ref、report ref、verification summary |
-
-### 2.4 当前项目已有优势
-
-1. **执行内核已有**：不需要重新实现 executor pool、artifact store、shell verification。
-2. **治理方向正确**：已经强调 shell verification 是完成权威，模型输出不能替代验证。
-3. **DAG lifecycle 已有**：active/paused/completed run 目录、approval/rejection、resume/report 已经是现成底座。
-4. **任务状态正在 DAG 化**：`task-read-model` 已经把 source、DAG draft、DAG run、promotion、closeout 作为主状态面。
-5. **Loop 已能记录长期事实**：适合承接 workflow run 结果，但不应在 MVP 前置。
-6. **测试基础较强**：已有 DAG runner、DAG validate、DAG report、decision gate、executor、task runtime、governance、loop workflow 等测试覆盖。
-
-### 2.5 当前主要缺口
-
-| 缺口 | 表现 | 需要新增 |
-|---|---|---|
-| 没有 WorkflowSpec IR | 当前 DAG 是 concrete execution graph，不表达 logical primitive | `src/workflows/dynamic/spec.ts` |
-| 没有 workflow-level validator | 现有 validator 只理解 `DagSpec` | `src/workflows/dynamic/validate.ts` |
-| 没有 workflow compiler | 不能从 logical workflow 编译到现有 Agent DAG | `src/workflows/dynamic/compile.ts` |
-| 没有 workflow metadata 保留策略 | `DagSpec` 当前没有稳定 metadata 字段 | `compile manifest` sidecar 或显式扩展 `DagSpec` schema |
-| 没有 dynamic expansion | 静态 DAG 不能自然表达 discover -> map N items；runner ranks 当前启动时固定 | `map_agent` expansion runtime + DAG runner expansion seam |
-| verification 不是一等 workflow pattern | 可以审查，但没有 Finding/Verification 标准 artifact | `verify_agent` + artifact schema |
-| bounded loop 未进入 workflow 层 | 当前 DAG convergence 是固定 supervised chain，不是通用 `loop_until` primitive | `loop_until` bounded expansion |
-| workflow 与 Loop 未打通 | Loop 当前有 `dag` action，但没有 `workflow` action | `loop run --action workflow`，在 compiler/report 稳定后做 |
-| saved workflow/replay 未产品化 | DAG 可保存和 report，但 workflow 复用层还没有 | `.loop-agent/workflows/` / `workflow run` |
-
----
-
-## 3. 三层定位：Dynamic Workflow Engine、DAG runtime、Loop Task
-
-### 3.1 DAG runtime
-
-一句话：
-
-> 给我一个 concrete DAG，我负责可靠、安全、可恢复地执行它。
-
-职责：
-
-- validate concrete DAG。
-- 检查依赖、环、缺失节点、writeSet 冲突、shell config、cwd 越界。
-- 调度 ready nodes。
-- 控制并发、retry、timeout、resume。
-- 调用 Cursor / Pi / shell / static executors。
-- 记录 node artifacts、stdout/stderr、executor result、decision envelope。
-- 生成 DAG report。
-
-不负责：
-
-- 决定复杂任务要拆成多少动态节点。
-- 根据上游输出生成新的 logical work。
-- 管理多轮目标、用户反馈、长期 lesson。
-
-适合场景：
-
-- 固定步骤 coding task。
-- 已经生成好的 DAG。
-- 小规模 feature / bug fix。
-- shell verification / deterministic gate。
-
-### 3.2 Dynamic Workflow DAG Engine
-
-一句话：
-
-> 给我一个目标、profile 或 WorkflowSpec，我负责把它动态编排、校验、展开、编译成 concrete DAG。
-
-职责：
-
-- 定义 `WorkflowSpec` schema。
-- 校验 logical workflow。
-- 做 workflow-level risk / permission analysis。
-- 支持 `agent`、`map_agent`、`verify_agent`、`reduce_agent`、`condition`、`loop_until`、`human_gate`、`artifact_transform`。
-- 根据上游 output 做 dynamic expansion。
-- 将 logical workflow 编译成 runtime 可执行的 concrete DAG。
-- 生成 workflow-level report。
-- 支持 workflow save / inspect / replay。
-
-不负责：
-
-- 直接执行 shell 或写文件。
-- 跳过现有 DAG runtime 调 executor。
-- 管理跨多轮目标。
-- 改写 completed DAG facts。
-
-适合场景：
-
-- PR changed files review。
-- codebase-wide audit。
-- 多文件迁移。
-- finding -> independent verifier -> reducer。
-- fix-until-pass 的单 run bounded loop。
-- 多来源 research / cross-check synthesis。
-
-### 3.3 Loop Task
-
-一句话：
-
-> 管一个长期目标跨多轮为什么继续、下一步做什么、哪些事实已验证、何时暂停或 closeout。
-
-职责：
-
-- 维护 objective、context、state、rounds、signals、closeout。
-- 记录每轮 action / result / verification / lesson / next / decision。
-- 接收 human feedback、approval、scope change。
-- 根据 `openFrontier` 与 `failureStreak` 决定下一轮动作。
-- 汇总多个 workflow/DAG/shell/review run 形成 closeout。
-
-不负责：
-
-- 执行 node。
-- 展开 map_agent。
-- 校验 workflow schema。
-- 直接修改 DAG run artifacts。
-
-适合场景：
-
-- 任务跨多轮，单次 DAG 或 workflow 难以完成。
-- 需要保留失败教训和下一步策略。
-- 需要吸收人工反馈、审批、范围变化。
-- 需要把多次 DAG run / workflow run / shell verification 汇总为交付证据。
-
-### 3.4 三者关系图
-
-```mermaid
-flowchart TD
-  U[User Task / Objective] --> T[Task Harness]
-  T --> L[Loop Task]
-  L -->|chooses bounded action| W[Dynamic Workflow DAG Engine]
-  W -->|WorkflowSpec validate / risk / compile / expand| D[Concrete Agent DAG]
-  D --> R[DAG runtime]
-  R --> E[Cursor / Pi / shell / static executors]
-  E --> A[Artifacts / logs / verification / reports]
-  A --> R
-  R -->|dagRunRef / reportRef| L
-  L --> C[Loop closeout]
-```
-
----
-
-## 4. 目标架构
-
-### 4.1 新增模块建议
-
-```text
-src/workflows/dynamic/
-  spec.ts                 # WorkflowSpec 类型定义
-  schema.ts               # JSON schema / zod schema
-  validate.ts             # logical workflow validator
-  risk.ts                 # workflow-level risk / permission analyzer
-  compile.ts              # WorkflowSpec -> AgentDAG compiler
-  expandMap.ts            # map_agent dynamic expansion
-  expandLoop.ts           # loop_until bounded expansion
-  artifactRefs.ts         # workflow artifact reference helpers
-  artifacts.ts            # Finding / Verification / WorkflowReport types
-  profiles/
-    prReview.ts
-    auditAuth.ts
-    fixUntilCheckPasses.ts
-  report.ts               # workflow-level report
-  fixtures/
-    pr-review.workflow.json
-```
-
-命令层：
-
-```text
-src/commands/dag-workflow-plan.ts
-src/commands/dag-workflow-validate.ts
-src/commands/dag-workflow-compile.ts
-src/commands/dag-workflow-run.ts       # 可选，内部组合 validate + compile + run-dag
-src/commands/workflow-*.ts             # 稳定后再提升为顶层 workflow 命令
-```
-
-Loop 对接：
-
-```text
-src/workflows/loop/actions.ts          # 先沿用当前 Loop action 聚合文件
-src/commands/loop.ts                   # 增加 --action workflow 分派
-```
-
-### 4.2 运行态目录建议
-
-```text
-.harness/tasks/<taskId>/
-  task.json
-
-  workflows/
-    planned/
-      pr-review.workflow.json
-    validation/
-      pr-review.validation.json
-      pr-review.risk.json
-    compiled/
-      pr-review.dag.json
-      pr-review.compile-manifest.json
-    reports/
-      pr-review.workflow-report.md
-
-  loop/
-    objective.md
-    context.md
-    state.json
-    rounds.jsonl
-    signals.jsonl
-    closeout.md
-
-.harness/dag-runs/<lifecycle>/<runId>/
-  run.json
-  state.json
-  <node-id>.json
-  <node-id>/
-  expansions/
-    review-each-file.expansion.json
-    verify-findings.expansion.json
-  # DAG report is derived by `dag report` from run facts.
-```
-
-说明：
-
-- `.harness/tasks/<taskId>/workflows/` 保存 workflow 的计划、校验、风险、编译和 workflow-level report，是 task-local artifact。
-- `.harness/dag-runs/<lifecycle>/<runId>/` 仍然保存 concrete DAG run facts，是执行事实源。
-- compiled DAG 应通过 sidecar `compile-manifest.json` 或明确扩展后的 `DagSpec` 字段保留 workflow 来源。不能依赖未知 JSON 字段隐式穿过 `parseDagSpec`。
-- Phase 3 之前，`expansions/` 只是设计目标；当前 runner 不会自动创建这个目录。
-
-### 4.3 WorkflowSpec v0.1 草案
-
-```json
-{
-  "version": "0.1",
-  "kind": "dynamic-agent-workflow",
-  "meta": {
-    "name": "pr-review",
-    "description": "Review changed files and produce a ranked summary",
-    "riskLevel": "low"
-  },
-  "inputs": {
-    "base": "main",
-    "head": "HEAD"
-  },
-  "limits": {
-    "maxConcurrency": 8,
-    "maxAgentRuns": 100,
-    "maxExpandedNodes": 200,
-    "maxRetriesPerNode": 1,
-    "maxIterations": 3,
-    "maxWallClockMinutes": 30
-  },
-  "permissions": {
-    "filesystem": "read_only",
-    "shell": {
-      "mode": "allowlist",
-      "commands": ["git diff --name-only"]
-    },
-    "network": "deny",
-    "edits": "deny"
-  },
-  "nodes": [
-    {
-      "id": "discover-changed-files",
-      "type": "command",
-      "dependsOn": [],
-      "command": "git diff --name-only {{inputs.base}}...{{inputs.head}}",
-      "outputSchema": {
-        "type": "object",
-        "required": ["files"],
-        "properties": {
-          "files": {
-            "type": "array",
-            "items": { "type": "string" }
-          }
-        }
-      }
-    },
-    {
-      "id": "review-each-file",
-      "type": "map_agent",
-      "dependsOn": ["discover-changed-files"],
-      "itemsFrom": "$.nodes['discover-changed-files'].output.files",
-      "itemName": "file",
-      "concurrency": 8,
-      "role": "code-reviewer",
-      "prompt": "Review {{file}} for correctness issues. Return concrete findings only.",
-      "outputSchema": {
-        "type": "object",
-        "required": ["file", "findings"],
-        "properties": {
-          "file": { "type": "string" },
-          "findings": { "type": "array" }
-        }
-      }
-    },
-    {
-      "id": "verify-findings",
-      "type": "verify_agent",
-      "dependsOn": ["review-each-file"],
-      "itemsFrom": "$.nodes['review-each-file'].output[*].findings[*]",
-      "role": "adversarial-verifier",
-      "prompt": "Independently verify this finding. Try to refute it. Return verified, refuted, or uncertain.",
-      "outputSchema": {
-        "type": "object",
-        "required": ["findingId", "status", "reason"],
-        "properties": {
-          "findingId": { "type": "string" },
-          "status": { "type": "string", "enum": ["verified", "refuted", "uncertain"] },
-          "reason": { "type": "string" }
-        }
-      }
-    },
-    {
-      "id": "final-report",
-      "type": "reduce_agent",
-      "dependsOn": ["verify-findings"],
-      "role": "report-writer",
-      "prompt": "Create a ranked, deduplicated report. Include verified findings by default; put uncertain findings separately.",
-      "outputSchema": {
-        "type": "object",
-        "required": ["summary", "findings"],
-        "properties": {
-          "summary": { "type": "string" },
-          "findings": { "type": "array" }
-        }
-      }
-    }
-  ],
-  "final": {
-    "from": "final-report"
-  }
-}
-```
-
-命名约束：
-
-- Workflow node id 推荐直接使用 kebab-case，并满足现有 `DagTask.id` 约束。
-- 如果后续允许 workflow node id 比 DAG node id 更宽，compiler 必须产出显式 id mapping，并在 expansion manifest、report、Loop round 中使用同一映射。
-- JSONPath/selector 对 kebab-case id 使用 bracket notation，例如 `$.nodes['review-each-file']...`。
-
-### 4.4 核心约束
-
-Validator 必须强制：
-
-- 每个 workflow 必须有 `version`、`kind`、`nodes`、`final`。
-- 每个 agent-like node 必须有 `outputSchema`。
-- `map_agent` / `verify_agent` 必须有 `itemsFrom`。
-- `command` 必须在 allowlist 内。
-- `loop_until` 必须有 `maxIterations`。
-- 所有 node id 唯一。
-- 所有 dependsOn 指向存在节点。
-- 禁止环，除非通过 `loop_until` 这种 bounded primitive 表达。
-- 禁止 `eval` / arbitrary JS / arbitrary shell。
-- 高风险权限必须要求 `human_gate`。
-- producer 不能 verify 自己的 finding。
-- reducer 默认不能新增 facts，只能 dedupe / rank / group / format。
-- limits 必须存在默认值与硬上限。
-
----
-
-## 5. 分阶段落地计划
-
-下面的阶段按“每一步都能独立验证”的原则设计。不要一次性实现完整 engine。
-
----
-
-## Phase 0：边界与命名收敛
-
-### 目标
-
-先把概念边界固化，避免后续代码把 `DAG`、`Workflow`、`Loop` 混在一起。
-
-### 产物
-
-- 将本文档作为 v0.2 roadmap 落到 `docs/`。
-- 新增或更新对象关系图文档：`Task -> WorkflowSpec -> Compiled DAG -> DAG Run -> Loop Round -> Closeout`。
-- CLI help 中明确：
-  - `dag` 是 concrete DAG 主路径。
-  - `dag workflow-*` 是 logical dynamic workflow 的实验入口。
-  - `loop` 是多轮长期控制层。
-- 明确 Level 1 fallback 已删除，不作为 Dynamic Workflow 的实现基础。
-
-### 不做
-
-- 不改 executor。
-- 不改 DAG runner。
-- 不新增动态展开。
-
-### 验证方式
-
-```bash
-bash scripts/check-repo.sh
-```
-
-### 退出标准
-
-- 文档能让新实现者清楚说明三层边界。
-- 没有新增行为风险。
-- 不再把 Loop、Workflow、DAG runner 描述成同一层东西。
-- 不再把 `src/workflows/level1/` 描述成当前可用路径。
-
----
-
-## Phase 1：WorkflowSpec schema 与 validator
-
-### 目标
-
-新增 logical workflow 的类型系统和校验器，但不执行。
-
-### 新增代码
-
-```text
-src/workflows/dynamic/spec.ts
-src/workflows/dynamic/schema.ts
-src/workflows/dynamic/validate.ts
-src/workflows/dynamic/errors.ts
-src/workflows/dynamic/fixtures/*.workflow.json
-src/commands/dag-workflow-validate.ts
-```
-
-### 支持 node types，仅做 schema
-
-```text
-agent
-map_agent
-verify_agent
-reduce_agent
-command
-condition
-loop_until
-human_gate
-artifact_transform
-```
-
-这些是 WorkflowSpec logical primitive，不等同于现有 `DagTask.executor`。Phase 1 只校验 logical Interface，不把它们直接塞进 `DagSpec.tasks`。
-
-Phase 1 不要求全部能执行，只要求能被识别、校验、报错。
-
-### CLI
-
-```bash
-loop-agent dag workflow-validate \
-  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
-  --strict-governance
-```
-
-命令应挂在现有 `dag` 子命令下；不要先新增顶层 `workflow`，避免在 IR 未稳定时扩大公共 Interface。
-
-### Validator 规则
-
-最低必做：
-
-- invalid JSON fail。
-- missing `kind` fail。
-- missing `final` fail。
-- duplicate node id fail。
-- missing dependency fail。
-- unbounded `loop_until` fail。
-- `map_agent` without `itemsFrom` fail。
-- `command` without allowlist fail。
-- agent-like node without `outputSchema` fail。
-- unknown node type fail。
-- unknown permission mode fail。
-- node id 非 kebab-case fail，除非 compiler 已支持显式 id mapping。
-- `itemsFrom` selector 必须只引用已存在上游节点。
-- `permissions.edits != deny` 时必须有 `allowedPaths` / `forbiddenPaths` / `writeSet`。
-- broad write permissions 必须要求 `human_gate` 或编译成现有 DAG decision gate。
-
-### 测试
-
-```text
-test/dynamic-workflow-validate.test.ts
-  valid-pr-review.workflow.json passes
-  missing-final.workflow.json fails
-  duplicate-node-id.workflow.json fails
-  map-without-itemsFrom.workflow.json fails
-  command-without-allowlist.workflow.json fails
-  loop-without-maxIterations.workflow.json fails
-  agent-without-outputSchema.workflow.json fails
-  non-kebab-node-id.workflow.json fails
-```
-
-### 退出标准
-
-- 可以把一个 `WorkflowSpec` 当成可审查 artifact。
-- 错误信息能指出具体 node id 和路径。
-- 不接触 DAG runner，不引入执行风险。
-
----
-
-## Phase 2：WorkflowSpec -> AgentDAG compiler v0
-
-### 目标
-
-证明 logical workflow 可以稳定编译到现有 concrete Agent DAG。
-
-### 范围
-
-Phase 2 先支持静态可编译 node：
-
-```text
-agent
-reduce_agent
-command
-artifact_transform
-human_gate placeholder
-```
-
-`map_agent` / `verify_agent` 在 Phase 2 可以先编译成 placeholder/barrier node，或者只支持显式 `items` 的静态展开：
-
-```json
-{
-  "type": "map_agent",
-  "items": ["a.ts", "b.ts"]
-}
-```
-
-动态 `itemsFrom` 留到 Phase 3。
-
-### 新增代码
-
-```text
-src/workflows/dynamic/compile.ts
-src/workflows/dynamic/compileTypes.ts
-src/workflows/dynamic/artifactRefs.ts
-src/commands/dag-workflow-compile.ts
-```
-
-### CLI
-
-```bash
-loop-agent dag workflow-compile \
-  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
-  --output .harness/tasks/<taskId>/workflows/compiled/pr-review.dag.json
-```
-
-### 编译规则
-
-- 保留 workflow node -> concrete DAG task 映射。
-- 如果 `DagSpec` schema 暂不扩展 origin/metadata 字段，必须写 `compile-manifest.json` sidecar；不要依赖未知字段穿过 `parseDagSpec`。
-- 每个 node 的 `outputSchema` 先转成 `outputContract` 文本或 compile manifest 约束；runtime schema enforcement 可后置。
-- `permissions` 转成 `writePolicy`、`allowedPaths`、`forbiddenPaths`、`writeSet`、shell config 等现有 executor constraints。
-- `limits` 转成 DAG run options、workflow validator hard cap 或 compile manifest；不要假设现有 `DagSpec` 已有全部 limit 字段。
-- `command` 编译成 `executor: "shell"`，并复用现有 `shell` config / allowlist / timeout / cwd 约束。
-- `agent` / `reduce_agent` 编译成 `pi` 或 `static` 节点；read-only profile 先默认 `pi`。
-- `human_gate` 优先编译成现有 DAG `decisionGate` / paused lifecycle；不要新增第二套 approval runtime。
-- `artifact_transform` 在 Phase 2 只允许 deterministic transform；不能引入 stub executor 作为完成实现。
-
-### 测试
-
-```text
-test/dynamic-workflow-compile.test.ts
-  simple workflow compiles to existing AgentDAG shape
-  command node preserves allowlist metadata
-  reduce node depends on all upstream nodes
-  human_gate compiles to existing DAG decision gate semantics
-  workflow metadata is preserved in compile manifest or explicit DagSpec field
-```
-
-Golden fixture：
-
-```text
-test/fixtures/dynamic/simple.workflow.json
-测试输出：test/fixtures/dynamic/simple.compiled-dag.json
-```
-
-### 验证命令
-
-```bash
-loop-agent dag workflow-validate --workflow test/fixtures/dynamic/simple.workflow.json
-loop-agent dag workflow-compile --workflow test/fixtures/dynamic/simple.workflow.json --output /tmp/simple.dag.json
-loop-agent dag validate --dag /tmp/simple.dag.json --strict-governance
-```
-
-### 退出标准
-
-- WorkflowSpec 能编译成现有 DAG validator 接受的 DAG。
-- 现有 `run-dag` 不需要大改。
-- 编译产物可 diff、可审查。
-- 编译产物不包含未知 `DagSpec` 字段，或相关字段已经加入 `DagSpec` schema 和 tests。
-
----
-
-## Phase 3：Dynamic expansion v0：map_agent
-
-### 目标
-
-实现真正的 dynamic workflow 核心：
-
-```text
-discover targets
-  -> map_agent dynamically expands N concrete nodes
-  -> reduce_agent fan-in
-```
-
-### 设计选择
-
-推荐采用 **runtime expansion manifest**，而不是把所有动态能力塞进 planner。
-
-当前 `run-dag` 在运行开始时根据 `DagSpec.tasks` 计算固定 ranks。真正的 dynamic expansion 需要新增一个明确的 runner seam，不能只在 compiler 中生成占位节点后假设 scheduler 会自动接收 child nodes。
-
-执行到 `map_agent` 时：
-
-1. 读取 `itemsFrom` 指向的上游 JSON output。
-2. 校验 items 是 array。
-3. 检查 `maxItems`、`maxExpandedNodes`、`maxAgentRuns`。
-4. 生成 concrete child nodes：
-
-```text
-review-each-file-0001
-review-each-file-0002
-review-each-file-0003
-```
-
-5. 写入：
-
-```text
-.harness/dag-runs/<lifecycle>/<runId>/expansions/review-each-file.expansion.json
-```
-
-6. runner 更新 state/ranks 或通过 expansion-aware checkpoint 调度 child nodes。
-7. `map_agent` barrier 在所有 child completed 后 completed。
-
-### 新增代码
-
-```text
-src/workflows/dynamic/expandMap.ts
-src/workflows/dag/runtimeExpansion.ts      # 如果需要在 DAG runner 层接入
-src/workflows/dag/expansionManifest.ts
-```
-
-### Expansion manifest 草案
-
-```json
-{
-  "workflowNodeId": "review-each-file",
-  "expandedAt": "2026-07-04T00:00:00.000Z",
-  "itemsFrom": "$.nodes['discover-changed-files'].output.files",
-  "itemCount": 3,
-  "children": [
-    {
-      "nodeId": "review-each-file-0001",
-      "itemRef": "$.items[0]",
-      "itemValueHash": "sha256:..."
-    }
-  ]
-}
-```
-
-### CLI 验证场景
-
-先用 static executor 或 command fixture：
-
-```text
-discover-files static output: { "files": ["a.ts", "b.ts"] }
-map_agent review-each-file over files
-reduce_agent final-report
-```
-
-命令：
-
-```bash
-loop-agent dag workflow-compile --workflow test/fixtures/dynamic/map.workflow.json --output /tmp/map.dag.json
-loop-agent run-dag --dag /tmp/map.dag.json --cwd .
-```
-
-### 测试
-
-```text
-test/dynamic-workflow-expand-map.test.ts
-  expands N children from upstream JSON output
-  fails when itemsFrom path missing
-  fails when itemsFrom is not array
-  respects maxItems
-  respects maxExpandedNodes
-  writes expansion manifest
-  expanded child ids are valid DagTask ids
-  resume does not duplicate already-expanded children
-```
-
-### 退出标准
-
-- 可以跑通 discover -> map -> reduce。
-- resume 不重复生成 child nodes。
-- expansion manifest 可审查。
-- map fan-out 被 limits 约束。
-
----
-
-## Phase 4：Finding / Verification / Reducer 标准 artifact
-
-### 目标
-
-把 Claude Dynamic Workflows 中最有价值的质量模式一等化：
-
-```text
-producer -> finding
-finding -> independent verifier
-verified finding -> reducer
-```
-
-### 新增标准 artifact
-
-```ts
-type Finding = {
-  id: string
-  sourceNodeId: string
-  targetRef: string
-  title: string
-  severity: 'low' | 'medium' | 'high' | 'critical'
-  evidence: EvidenceRef[]
-  recommendation: string
-}
-
-type Verification = {
-  findingId: string
-  verifierNodeId: string
-  status: 'verified' | 'refuted' | 'uncertain'
-  reason: string
-  evidence: EvidenceRef[]
-}
-
-type WorkflowReport = {
-  summary: string
-  verifiedFindings: Finding[]
-  uncertainFindings: Finding[]
-  refutedFindingsRef?: ArtifactRef
-  evidenceRefs: ArtifactRef[]
-}
-```
-
-### 新增 node semantics
-
-```text
-verify_agent:
-  - 本质是受约束的 map_agent
-  - itemsFrom 通常指向 findings
-  - verifier 不能是 producer node
-  - verifier prompt 只能看到 finding + evidence + target artifact
-  - verifier 不看 producer chain-of-thought
-```
-
-```text
-reduce_agent:
-  - 只做 dedupe / rank / group / format
-  - 默认不能新增事实发现
-  - final report 默认只包含 verified findings
-  - uncertain findings 单列
-  - refuted findings 只进入 appendix / trace
-```
-
-### 内置 profile：`pr-review`
-
-第一条真实可演示 workflow：
-
-```text
-discover-changed-files
-  -> map_agent(review-each-file)
-  -> verify_agent(verify-each-finding)
-  -> reduce_agent(final-ranked-summary)
-```
-
-CLI：
-
-```bash
-loop-agent dag workflow-plan <taskId> --profile pr-review \
-  --output .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json
-
-loop-agent dag workflow-validate \
-  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
-  --strict-governance
-
-loop-agent dag workflow-compile \
-  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
-  --output .harness/tasks/<taskId>/workflows/compiled/pr-review.dag.json
-
-loop-agent run-dag \
-  --dag .harness/tasks/<taskId>/workflows/compiled/pr-review.dag.json \
-  --cwd .
-```
-
-### 测试
-
-```text
-test/dynamic-workflow-verification.test.ts
-  verify_agent expands per finding
-  producer cannot verify own finding
-  verified/refuted/uncertain statuses are preserved
-  reducer includes only verified findings by default
-  uncertain findings are separated
-  refuted findings are excluded from main report
-```
-
-### 退出标准
-
-- `pr-review` profile 能在 fixture repo 或 static executor 下跑通。
-- final report 能体现 verified / uncertain / refuted 分层。
-- reducer 不新增未验证 fact。
-
----
-
-## Phase 5：Dynamic Workflow 与 Loop Task 打通
-
-### 目标
-
-让 Dynamic Workflow 成为 Loop 的一种 bounded action。
-
-当前 Loop 已有：
-
-```text
-loop run --action shell-verify
-loop run --action pi-review
-loop run --action cursor-fix
-loop run --action dag [--execute]
-```
-
-新增：
-
-```bash
-loop-agent loop run <taskId> --action workflow --profile pr-review --execute
-```
-
-或：
-
-```bash
-loop-agent loop run <taskId> \
-  --action workflow \
-  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
-  --execute
-```
-
-### Loop round 记录格式
-
-```json
-{
-  "round": 4,
-  "action": "workflow",
-  "workflow": "pr-review",
-  "workflowRef": ".harness/tasks/T/workflows/planned/pr-review.workflow.json",
-  "compiledDagRef": ".harness/tasks/T/workflows/compiled/pr-review.dag.json",
-  "compileManifestRef": ".harness/tasks/T/workflows/compiled/pr-review.compile-manifest.json",
-  "runRef": ".harness/dag-runs/<lifecycle>/run-123",
-  "reportRef": ".harness/tasks/T/workflows/reports/pr-review.workflow-report.md",
-  "result": "Reviewed 17 changed files; produced 8 findings.",
-  "verification": "5 verified, 2 refuted, 1 uncertain.",
-  "lesson": "Most issues are concentrated in CLI routing.",
-  "next": "Fix verified high severity findings.",
-  "decision": "continue"
-}
-```
-
-### Loop context 更新原则
-
-Loop `context.md` 只吸收高层事实，不复制全部 node outputs：
-
-```text
-已验证事实：
-- pr-review workflow scanned 17 files.
-- 5 findings verified.
-- 1 finding uncertain.
-- no code edits were made.
-
-下一步：
-- run fix-verified-findings workflow after human approval.
-```
-
-### signals -> workflow inputs
-
-`signals.jsonl` 中的人工反馈应成为 workflow inputs：
-
-```json
-{
-  "severityFilter": ["high", "critical"],
-  "forbiddenPaths": ["billing/**"],
-  "humanInstructionsRef": ".harness/tasks/T/loop/signals.jsonl"
-}
-```
-
-### 测试
-
-```text
-test/loop-workflow-action.test.ts
-  loop workflow action records workflowRef/runRef/reportRef
-  loop context updates from workflow summary
-  loop does not rewrite DAG run artifacts
-  loop closeout includes workflow evidence
-  loop --auto can choose workflow from openFrontier
-```
-
-### 退出标准
-
-- Loop 可以运行 workflow action。
-- Workflow run facts 以 ref 形式进入 `rounds.jsonl`。
-- `loop closeout` 能引用 workflow evidence。
-- Loop 不直接改写 completed DAG facts。
-
----
-
-## Phase 6：condition 与 loop_until
-
-### 目标
-
-支持单次 workflow 内的 bounded dynamic control。
-
-### condition
-
-`condition` 根据结构化 output 决定边：
-
-```json
-{
-  "id": "choose-next",
-  "type": "condition",
-  "dependsOn": ["run-typecheck"],
-  "cases": [
-    {
-      "when": "$.nodes['run-typecheck'].output.status == 'passed'",
-      "then": "final-report"
-    },
-    {
-      "when": "$.nodes['run-typecheck'].output.status == 'failed'",
-      "then": "analyze-errors"
-    }
-  ],
-  "default": "human-gate"
-}
-```
-
-### loop_until
-
-`loop_until` 必须 bounded：
-
-```json
-{
-  "id": "fix-until-tsc-passes",
-  "type": "loop_until",
-  "maxIterations": 5,
-  "stopWhen": {
-    "any": [
-      "$.last.output.status == 'passed'",
-      "$.stagnation.rounds >= 2"
-    ]
-  },
-  "body": [
-    { "id": "analyze-errors", "type": "agent" },
-    { "id": "apply-fixes", "type": "agent" },
-    { "id": "rerun-tsc", "type": "command" }
-  ]
-}
-```
-
-实现建议：
-
-```text
-不要允许真正无限环。
-编译时或 runtime expansion 时展开成最多 N 轮：
-round_1 -> condition_1 -> round_2 -> condition_2 -> ... -> round_N
-```
-
-### 内置 profile
-
-```text
-fix-until-check-passes
-```
-
-流程：
-
-```text
-run-check
-  -> loop_until(maxIterations=3)
-       analyze-errors
-       apply-bounded-fix
-       rerun-check
-  -> final-report
-```
-
-### 测试
-
-```text
-test/dynamic-workflow-condition.test.ts
-test/dynamic-workflow-loop-until.test.ts
-  condition follows expected branch
-  condition uses default branch on no match
-  loop_until stops on passed status
-  loop_until stops on maxIterations
-  loop_until detects no-progress sentinel
-  loop_until fails validation without maxIterations
-```
-
-### 退出标准
-
-- bounded loop 可以跑 shell/static fixture。
-- 没有任何 unbounded cycle 能通过 validator。
-- loop_until 结果能进入 DAG report 与 workflow report。
-
----
-
-## Phase 7：human_gate、approval、pause/resume
-
-### 目标
-
-把高风险 workflow 的审批点纳入 runtime，而不是依靠 prompt 约定。
-
-### human_gate 语义
-
-```json
-{
-  "id": "approve-auth-edits",
-  "type": "human_gate",
-  "dependsOn": ["plan-auth-changes"],
-  "reason": "Auth middleware edits require explicit approval",
-  "approvalSchema": {
-    "type": "object",
-    "required": ["approved", "scope"],
-    "properties": {
-      "approved": { "type": "boolean" },
-      "scope": { "type": "array", "items": { "type": "string" } }
-    }
-  }
-}
-```
-
-### 命令
-
-当前仓库已经有 DAG approval 命令；`human_gate` 应编译到这套机制：
-
-```bash
-loop-agent dag approve --run-id <runId> --option <option-id> [--notes <text>]
-loop-agent dag reject --run-id <runId> --reason "Need manual review"
-loop-agent dag resume --run-id <runId>
-```
-
-Loop integration：
-
-```bash
-loop-agent loop add-signal <taskId> --type approval --message "Approved high severity auth fixes"
-loop-agent loop run <taskId> --auto
-```
-
-### 测试
-
-```text
-test/dynamic-workflow-human-gate.test.ts
-  human_gate pauses run
-  approval resumes descendants
-  rejection marks workflow blocked
-  loop signal can satisfy pending gate
-```
-
-### 退出标准
-
-- 高风险 workflow 可以在 gate 暂停。
-- approval/rejection 都进入 audit trail。
-- Loop 能记录 pending approval 并 resume。
-
----
-
-## Phase 8：saved workflows、replay、operator UX
-
-### 目标
-
-把 workflow 从一次性 plan 变成可复用、可 diff、可 replay 的产品能力。
-
-### 保存位置
-
-```text
-.loop-agent/workflows/          # repo shared
-~/.loop-agent/workflows/        # personal
-.harness/tasks/<taskId>/workflows/  # task-local generated plans
-```
-
-### 命令
-
-```bash
-loop-agent workflow list
-loop-agent workflow inspect pr-review
-loop-agent workflow run pr-review --args '{"base":"main","head":"HEAD"}'
-loop-agent workflow save --from .harness/tasks/T/workflows/planned/pr-review.workflow.json --name pr-review
-loop-agent workflow diff pr-review --against .harness/tasks/T/workflows/planned/pr-review.workflow.json
-loop-agent workflow replay <runId>
-```
-
-DAG operator UX：
-
-```bash
-loop-agent dag status --run-id <runId>
-loop-agent dag doctor
-loop-agent dag report --run-id <runId> --json --lifecycle all
-loop-agent dag decision inspect --run-id <runId>
-loop-agent dag decision validate --run-id <runId>
-loop-agent dag resume --run-id <runId>
-```
-
-未来如果需要更细粒度 operator UX，再新增 `inspect-node`、`restart-node`、`stop` 等命令；不要在 saved workflow 阶段顺手扩大 DAG control plane。
-
-### 测试
-
-```text
-test/workflow-list.test.ts
-test/workflow-run.test.ts
-test/workflow-save.test.ts
-test/workflow-replay.test.ts
-test/dag-operator-status.test.ts
-```
-
-### 退出标准
-
-- workflow 可保存、可复用、可传 args。
-- replay 不重复已完成 artifacts，或明确说明哪些节点重新执行。
-- operator 能定位失败 node、查看 expansion、查看 verifier 结果。
-
----
-
-## Phase 9：大规模迁移与 worktree/shard execution
-
-### 目标
-
-支持更高风险、更高价值的场景：多文件 migration。
-
-### 原则
-
-- 不允许多个 writer agent 在同一工作树无隔离并发写。
-- 使用 shard / worktree / delegate / harvest 模式。
-- 每个 shard 有独立 verification。
-- merge patch 前做 conflict 和 test gate。
-
-### Workflow pattern
-
-```text
-discover-targets
-  -> shard-targets
-  -> map_agent(migrate-shard-in-isolated-worktree)
-  -> map_agent(verify-shard)
-  -> reduce_agent(merge-plan)
-  -> human_gate(approve-merge)
-  -> apply-merge
-  -> final-shell-verify
-```
-
-### 测试
-
-```text
-test/dynamic-workflow-sharded-migration.test.ts
-  writeSet conflicts rejected
-  shards get isolated workspaces
-  failed shard does not block successful shard artifacts
-  merge requires human_gate when writeSet is broad
-```
-
-### 退出标准
-
-- 可以安全 dogfood 一个低风险 repo migration。
-- 每个 shard 的 patch、verification、failure reason 独立可追踪。
-- 最终 merge 有明确 approval 和 shell verification。
-
----
-
-## 6. 建议 MVP 顺序
-
-不要先做自动修代码。MVP 应分成两层：
-
-1. **工程 MVP**：`WorkflowSpec -> validate -> compile -> dag validate`，不要求 runtime dynamic expansion。
-2. **产品 MVP**：read-only PR review，因为它最能展示 Dynamic Workflow 的价值，同时风险低。
-
-这样安排的原因是：当前 `run-dag` 还没有动态插入节点的 seam。先做工程 MVP 可以验证 Interface 和 compiler depth，再进入 map/verify/reduce 的产品 MVP。
-
-### 6.1 工程 MVP：static workflow compile
-
-目标：
-
-```text
-simple-readonly-workflow.workflow.json
-  -> dag workflow-validate
-  -> dag workflow-compile
-  -> dag validate --strict-governance
-```
-
-验收：
-
-```bash
-loop-agent dag workflow-validate --workflow test/fixtures/dynamic/simple-readonly.workflow.json --strict-governance
-loop-agent dag workflow-compile --workflow test/fixtures/dynamic/simple-readonly.workflow.json --output /tmp/simple-readonly.dag.json
-loop-agent dag validate --dag /tmp/simple-readonly.dag.json --strict-models --strict-governance
-```
-
-退出标准：
-
-- 不改 `run-dag`。
-- 编译产物通过现有 DAG validator。
-- compile manifest 能解释每个 workflow node 对应哪个 DAG task。
-
-### 6.2 产品 MVP：PR Review Workflow
-
-MVP workflow：
-
-```text
-discover-changed-files
-  -> map_agent(review-each-file)
-  -> verify_agent(verify-each-finding)
-  -> reduce_agent(final-ranked-summary)
-```
-
-### 为什么选它
-
-- 文件数量运行时才知道，能验证 dynamic expansion。
-- findings 数量运行时才知道，能验证 second-order expansion。
-- verifier/reducer 能展示质量闭环。
-- read-only，风险低。
-- 最终 report 容易人工评估。
-- 可后续接 Loop：如果有 verified high severity findings，下一轮再进入 fix workflow。
-- read-only PR review 不要求 writer concurrency，因此不会先触发多 writer/worktree 风险。
-
-### MVP 验收
-
-```bash
-loop-agent new-task pr-review-demo "Review changed files"
-loop-agent dag workflow-plan pr-review-demo --profile pr-review --output .harness/tasks/pr-review-demo/workflows/planned/pr-review.workflow.json
-loop-agent dag workflow-validate --workflow .harness/tasks/pr-review-demo/workflows/planned/pr-review.workflow.json --strict-governance
-loop-agent dag workflow-compile --workflow .harness/tasks/pr-review-demo/workflows/planned/pr-review.workflow.json --output .harness/tasks/pr-review-demo/workflows/compiled/pr-review.dag.json
-loop-agent dag validate --dag .harness/tasks/pr-review-demo/workflows/compiled/pr-review.dag.json --strict-governance
-loop-agent run-dag --dag .harness/tasks/pr-review-demo/workflows/compiled/pr-review.dag.json --cwd .
-```
-
-验收结果：
-
-- `.harness/dag-runs/.../expansions/review-each-file.expansion.json` 存在。
-- `.harness/dag-runs/.../expansions/verify-findings.expansion.json` 存在。
-- final report 区分 verified / uncertain / refuted。
-- run-dag report 可引用到每个 verifier artifact。
-- workflow-level report 可复制给用户。
-
----
-
-## 7. 测试与验证金字塔
-
-### 7.1 Unit tests
-
-```text
-WorkflowSpec parser
-schema validation
-risk analyzer
-JSONPath itemsFrom resolver
-map expansion
-loop_until expansion
-artifact ref resolver
-Finding / Verification schema
-```
-
-### 7.2 Golden tests
-
-输入：
-
-```text
-*.workflow.json
-```
-
-输出：
-
-```text
-*.compiled-dag.json
-*.validation.json
-*.risk.json
-```
-
-目的：保证 IR 编译稳定、可 diff。
-
-### 7.3 Dry-run tests
-
-```bash
-loop-agent dag workflow-validate --workflow fixture.workflow.json
-loop-agent dag workflow-compile --workflow fixture.workflow.json --output /tmp/fixture.dag.json
-loop-agent dag validate --dag /tmp/fixture.dag.json --strict-governance
-```
-
-### 7.4 Static executor integration tests
-
-用 `static` executor 模拟：
-
-- discover files output。
-- reviewer findings output。
-- verifier status output。
-- reducer report output。
-
-不依赖外部模型，CI 稳定。
-
-### 7.5 Shell-only smoke tests
-
-用只读 command：
-
-```bash
-git diff --name-only main...HEAD
-```
-
-测试真实 command allowlist、cwd、stdout parsing、artifact。
-
-### 7.6 Model executor dogfood tests
-
-在本地或非 CI 环境跑：
-
-- Pi reviewer。
-- Pi verifier。
-- Cursor read-only reviewer。
-- 小 repo / 小目录。
-
-### 7.7 Loop integration tests
-
-验证：
-
-- workflow action append round。
-- workflow report ref 进入 closeout。
-- signal -> workflow input。
-- failureStreak 影响 `loop --auto`。
-- Loop 不改写 completed DAG facts。
-
----
-
-## 8. 风险与治理策略
-
-### 8.1 禁止任意代码作为 workflow IR
-
-不要支持：
-
-```json
-{ "eval": "some JavaScript" }
-```
-
-也不要支持：
-
-```json
-{ "shell": "{{model_generated_command}}" }
-```
-
-表达力不够时，新增 bounded primitive：
-
-```text
-agent
-map_agent
-verify_agent
-reduce_agent
-command
-condition
-loop_until
-human_gate
-artifact_transform
-subworkflow
-```
-
-### 8.2 强制 limits
-
-WorkflowSpec 必须有默认 limits，且 runtime 有硬上限：
-
-```json
-{
-  "maxConcurrency": 8,
-  "maxAgentRuns": 100,
-  "maxExpandedNodes": 200,
-  "maxRetriesPerNode": 1,
-  "maxIterations": 3,
-  "maxWallClockMinutes": 30
-}
-```
-
-不能相信 planner 自己节制。
-
-### 8.3 权限与写入范围
-
-- read-only workflow 默认风险低。
-- edits 必须声明 `allowedPaths` / `forbiddenPaths` / `writeSet`。
-- 同 rank writeSet 冲突必须 fail。
-- broad writeSet 必须 human_gate。
-- command 必须 allowlist。
-- network 默认 deny。
-- secrets 默认不可见。
-
-### 8.4 Verifier 独立性
-
-- producer 不能 verify 自己的 finding。
-- verifier 只看 finding、evidence、target artifact。
-- reducer 不新增 facts。
-- final report 默认只包含 verified findings。
-
-### 8.5 Completed facts 不可改写
-
-- DAG run artifact 是事实源。
-- Workflow report 可以 summarize，但不改写 node output。
-- Loop 可以引用 workflow/DAG facts，但不改写 completed DAG facts。
-
----
-
-## 9. 推荐 PR 顺序
-
-### PR 1：文档与对象边界
-
-- 添加/更新本文档。
-- 必要时更新 CLI help 文案，但不要在没有实现的情况下承诺 `workflow` 顶层命令。
-- 明确 DAG / Workflow / Loop 分层。
-- 明确 Level 1 fallback 已删除，不能作为 workflow 基础。
-
-### PR 2：WorkflowSpec schema + validator
-
-- 新增 `src/workflows/dynamic/spec.ts`。
-- 新增 validator。
-- 加 fixture tests。
-- 新增 `dag workflow-validate` 实验入口。
-
-### PR 3：workflow compile v0
-
-- 支持 agent / command / reduce / artifact_transform。
-- 产出 existing AgentDAG。
-- 通过 existing `dag validate`。
-- 产出 compile manifest 或扩展后的稳定 `DagSpec` origin 字段。
-
-### PR 4：map_agent dynamic expansion
-
-- 支持 `itemsFrom`。
-- 写 expansion manifest。
-- 支持 resume 不重复展开。
-- 明确 runner expansion seam，不隐式改写 completed DAG facts。
-
-### PR 5：verify_agent + Finding/Verification artifact
-
-- 标准化 finding / verification。
-- reducer 默认只包含 verified。
-
-### PR 6：pr-review profile
-
-- read-only MVP。
-- fixture + static executor + optional model dogfood。
-
-### PR 7：loop workflow action
-
-- `loop run --action workflow`。
-- round 记录 workflowRef / runRef / reportRef。
-- closeout 汇总 workflow evidence。
-
-### PR 8：condition / loop_until
-
-- bounded loop。
-- fix-until-check-passes profile。
-
-### PR 9：workflow save / run / replay
-
-- `.loop-agent/workflows/`。
-- `workflow list/inspect/run/save/replay`。
-
-### PR 10：operator UX
-
-- 优先增强现有 status / doctor / report / decision / resume。
-- 只有在真实操作痛点出现后，再考虑 inspect-node / restart-node / stop。
-
----
-
-## 10. 非目标
-
-短期不要做：
-
-- 完整 JS workflow runtime。
-- 任意代码 eval。
-- 无限制 autonomous loop。
-- 大规模自动改代码。
-- 多 writer agent 在同一 worktree 并发写。
-- 用 Loop 替代 DAG runner。
-- 用 reducer 重新审计 facts。
-- 用模型自述替代 shell verification。
-- 在 IR 未稳定前新增顶层 `workflow` 公共命令。
-- 为了支持 Dynamic Workflow 恢复 Level 1 顺序工作流。
-
----
-
-## 11. 成功标准
-
-### 技术成功标准
-
-- WorkflowSpec 是稳定、可审查、可 diff 的 artifact。
-- Dynamic workflow 可以编译成现有 Agent DAG。
-- compile manifest 或 `DagSpec` origin 字段能追踪 workflow node 到 DAG task 的映射。
-- map_agent 可以根据上游 output 动态展开。
-- verify_agent 可以独立验证 findings。
-- reducer 可以输出 verified-first report。
-- Loop 可以记录 workflow run evidence。
-- 所有阶段都有 deterministic tests。
-
-### 产品成功标准
-
-用户可以这样理解系统：
-
-```text
-普通任务：用 DAG runtime。
-一次复杂并行任务：用 Dynamic Workflow。
-长期多轮任务：用 Loop Task 管多个 workflow/DAG/shell/review round。
-```
-
-### 治理成功标准
-
-- 高风险 workflow 必须审批。
-- 所有 fan-out 有硬上限。
-- 所有 shell 命令可审计。
-- 所有写入范围可审计。
-- 所有 completed facts 有 artifact ref。
-- closeout 有 verification evidence。
-
----
-
-## 12. 最终定位文案
-
-中文：
-
-> `loop-agent` 是一个 repo-local AI coding workflow runtime。它以 DAG runtime 作为执行内核，在其上通过 Dynamic Workflow DAG Engine 把复杂任务动态编译为可验证的 Agent DAG；对于长期目标，Loop Task 将多次 workflow run、DAG run、shell verification、人工反馈和 closeout 串成可恢复、可审查、可交付的工程闭环。
-
-英文：
-
-> `loop-agent` is a repo-local AI coding workflow runtime. Its DAG runtime executes concrete Agent DAGs with artifacts and verification. The Dynamic Workflow DAG Engine compiles high-level workflow specs into expanded, verifiable Agent DAGs. For long-running objectives, Loop Task coordinates multiple workflow, DAG, shell, and review rounds into a recoverable and auditable delivery loop.
-
----
-
-## 参考来源
-
-[1] Anthropic Claude Code Docs, “Orchestrate subagents at scale with dynamic workflows”, accessed 2026-07-04.
-https://code.claude.com/docs/en/workflows
-
-[2] 用户上传文档：`粘贴的 markdown (1).md`，关于用 DAG JSON 复刻 Claude Dynamic Workflows 的设计说明。
-
-[3] 用户上传文档：`2026-07-02-repository-analysis.md`，关于当前 `loop-agent` 仓库结构、DAG 主路径、Loop 语义、治理边界与健康度的分析报告。
-
-[4] 当前源码仓库历史 completed execution plan，关于删除 Level 1 fallback、抽取 shell verification、建立 DAG-oriented task read model 的完成记录；发布包只携带 execution plan 目录说明，不携带具体历史计划正文。
-
-[5] 当前源码复核：`src/workflows/dag/types.ts`、`src/workflows/dag/validate.ts`、`src/workflows/dag/runner.ts`、`src/workflows/loop/actions.ts`、`src/task/read-model.ts`、`src/cli/catalog.ts`。
+# loop-agent Dynamic Workflow DAG Engine 阶段规划
+
+版本：0.2
+日期：2026-07-04
+适用项目：`loop-agent`
+目标读者：项目维护者、实现者、后续接手的 coding agent
+
+---
+
+## 0. 摘要
+
+`loop-agent` 当前已经具备一个较成熟的 **DAG runtime**：它能把 AI coding task 固化为本地任务目录，生成/校验 Agent DAG，调度 Cursor、Pi、shell、static 等 executor，保存 artifacts、logs、decision envelope、report，并以 shell verification 作为完成证据。
+
+2026-07-04 复核当前代码后，结论是：
+
+> 这个架构方向适合当前项目，但只适合作为 **现有 DAG runtime 上方的逻辑编排/编译层**。
+> 不适合重写 runner，不适合恢复已删除的 Level 1 顺序 fallback，也不适合照搬 Claude Dynamic Workflows 的 JavaScript script 形态。
+
+当前更合适的方向是：
+
+> 在现有 DAG runtime 上方新增一个 **Dynamic Workflow DAG Engine**。
+> LLM 或 profile 先生成受 schema 约束的 `WorkflowSpec`；engine 对其做校验、风险分析、动态展开和编译；最终产物仍然交给现有 `run-dag` 执行。
+
+核心分层：
+
+```text
+Loop Task
+  管多轮目标、round、signal、context、failureStreak、closeout
+
+Dynamic Workflow DAG Engine
+  管一次 run 内的动态拆解、map/reduce/verify/condition/loop_until/human_gate
+
+DAG runtime
+  管 concrete DAG 的 validate、schedule、execute、retry、resume、artifact、report
+
+Executors
+  Cursor / Pi / shell / static
+```
+
+一句话定位：
+
+> DAG runtime 解决“如何可靠执行具体 DAG”；Dynamic Workflow DAG Engine 解决“如何把复杂任务动态编译成具体 DAG”；Loop Task 解决“多次 workflow/DAG/shell/review round 如何形成长期目标闭环”。
+
+### 0.1 适配性判断
+
+| 判断 | 结论 | 原因 |
+|---|---|---|
+| 是否值得做 | 值得，但应分阶段 | 现有 DAG runtime 已经提供 executor、artifact、approval、report、resume 的深 Module，Dynamic Workflow 可以复用这些 leverage |
+| 是否应改 runner 为 JS workflow runtime | 不应 | 任意脚本会削弱 schema 审计、权限分析和 repo governance |
+| 是否应先做自动修代码 workflow | 不应 | 当前最稳的 MVP 是 read-only PR/code review，先验证 fan-out、verifier、reducer |
+| 是否应马上接入 Loop | 不应前置 | Loop 现在已有 `dag` action；workflow action 应在 WorkflowSpec/compile/report 稳定后再接 |
+| 最大技术风险 | runtime expansion | 当前 `run-dag` 基于静态 `DagSpec.tasks` 和 topo ranks；真正动态插入节点需要 runner 层扩展 |
+| 第一优先级 | WorkflowSpec schema + validator + static compiler | 这能先形成可审查 artifact，并证明能编译到现有 `DagSpec` |
+
+### 0.2 当前代码对本设计的约束
+
+- `DagTask.id` 当前必须是 kebab-case：`/^[a-z][a-z0-9-]*$/`。WorkflowSpec 示例也应使用 kebab-case，或由 compiler 显式维护 workflow id 到 DAG id 的映射。
+- `DagSpec` 目前没有通用 metadata 字段；未知字段不会成为稳定契约。若要保留 `workflowRef`、`workflowNodeId`、compile manifest，应新增明确 schema 字段或使用 sidecar manifest。
+- `run-dag` 当前启动时从完整 `DagSpec.tasks` 计算 topo ranks；Phase 3 以前不应假设 child nodes 能自然“进入 existing scheduler”。
+- DAG 已有 `decisionGate`、`dag approve`、`dag reject`、`dag resume` 和 paused lifecycle。`human_gate` 应优先编译到这套已有机制，而不是发明第二套 approval runtime。
+- `loop` 当前支持 `shell-verify`、`pi-review`、`cursor-fix`、`dag`、`record-round`、`add-signal`、`closeout`；没有 `workflow` action。
+- Level 1 顺序 fallback 已在 `refactor: remove level1 fallback` 后删除；本文档不得再把 `src/workflows/level1/` 描述为保留兼容路径。
+
+---
+
+## 1. 思想来源
+
+### 1.1 Claude Dynamic Workflows 的核心启发
+
+Claude Code Dynamic Workflows 的官方定义是：Claude 为任务写出一个 JavaScript orchestration script，runtime 在后台执行它；workflow 适用于 codebase audit、大规模 migration、cross-checked research 等超出单轮对话协调能力的任务。官方文档强调，workflow 与 subagents / skills / agent teams 的关键区别不是“能不能多 agent”，而是 **谁持有计划**：subagent 和 agent team 仍由 Claude 或 lead agent 逐轮决定下一步；workflow 由 script 决定下一步，中间状态存在 script variables 中，而不是反复塞回模型上下文。官方文档还明确提到 workflow 可以将 repeatable quality pattern 编码化，例如让独立 agents adversarially review each other’s findings，再进入最终报告。[1]
+
+Claude 方案的关键模式：
+
+```text
+用户目标
+  -> workflow script / runtime 持有计划
+  -> fan-out 多个 subagents
+  -> 中间结果留在 runtime state
+  -> verifier / reducer 过滤、去重、排序
+  -> session 只接收最终结果
+```
+
+官方文档列出的典型场景包括：
+
+- 审计许多文件中的同一类问题。
+- 持续修复直到检查通过。
+- 并行迁移大量文件。
+- Review every changed file and write one summary。
+- 跨多个来源 research 并交叉验证。
+- Find issues until the list stops growing。[1]
+
+### 1.2 对 loop-agent 更合适的改造：JS script -> Dynamic DAG IR
+
+Claude 的 JS workflow 具有强表达力，但对 `loop-agent` 这种希望产品化、可审计、本地治理的 runtime 来说，JS script 不是最优 IR。更好的方向是：
+
+```text
+LLM / profile 生成 WorkflowSpec JSON
+  -> schema validator
+  -> risk / permission analyzer
+  -> compiler / dynamic expander
+  -> concrete Agent DAG
+  -> existing DAG runtime
+```
+
+原因：
+
+| 维度 | Claude JS workflow | Dynamic DAG IR |
+|---|---|---|
+| 表达力 | 很强，天然支持 JS loop / branch / variables | 中等，需要 node type 扩展 |
+| 安全审计 | 需要审 JS code | 可以审 schema + primitive |
+| 权限分析 | 较难静态判断 | 容易做 limits / permissions / writeSet 检查 |
+| 可视化 | 脚本不天然图形化 | DAG / logical workflow 天然可视化 |
+| 恢复与重放 | 可以，但依赖 script runtime | 可以基于 run state / artifact ref / compiled DAG 做强恢复 |
+| 产品化 | 面向 Claude Code 内部体验 | 更适合 repo-local CLI + governance |
+
+因此，本项目不应追求“复刻 Claude 的 JS script”，而应复刻其操作系统思想：
+
+> 编排权离开模型上下文，进入一个可读、可校验、可恢复、可复跑的 workflow artifact。
+
+### 1.3 本项目已有思想基础
+
+`loop-agent` 当前已经具备以下基础：
+
+- repo-local task harness。
+- Agent DAG 编排。
+- DAG validation。
+- DAG report / doctor / recovery recommendation。
+- decision envelope、human approval/rejection、paused/resume lifecycle。
+- supervised DAG convergence pass。
+- Cursor / Pi / shell / static executor registry。
+- `shell-verification` Module，供 DAG shell executor 复用。
+- DAG-oriented task read model。
+- `.harness/` 运行态状态与 artifacts。
+- shell verification 作为完成权威。
+- governance 检查。
+- Loop 长周期 round / signal / closeout 状态机。
+
+这些能力说明当前项目已经拥有 Dynamic Workflow 所需的执行内核和治理底座。缺少的不是“再写一个 runtime”，而是上一层的 **WorkflowSpec + workflow validator + risk analyzer + compiler + dynamic expansion + workflow report + workflow/loop integration**。
+
+---
+
+## 2. 当前代码现状判断
+
+基于当前仓库分析，`loop-agent` 可以被描述为：
+
+> 一个 repo-local agent workflow runtime。它为 AI coding agent 提供任务 harness、Agent DAG 编排、Cursor/Pi 执行器集成、确定性 shell 验证、运行证据归档和治理检查，让长期或复杂的 agent 实现工作可以被审查、恢复和交付。
+
+本次复核依据的关键代码与文档：
+
+- `docs/feature-workflow.md`
+- 源码仓库历史 completed execution plan: remove-level1-fallback
+- `src/workflows/dag/types.ts`
+- `src/workflows/dag/validate.ts`
+- `src/workflows/dag/runner.ts`
+- `src/workflows/dag/lifecycle.ts`
+- `src/workflows/dag/report.ts`
+- `src/workflows/dag/init-hybrid.ts`
+- `src/workflows/loop/actions.ts`
+- `src/commands/loop.ts`
+- `src/commands/dag-run-task.ts`
+- `src/commands/dag-validate.ts`
+- `src/task/read-model.ts`
+- `src/cli/catalog.ts`
+
+### 2.1 当前主路径
+
+当前主推荐路径已经是 DAG：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output /tmp/<task-id>-dag.json
+loop-agent dag validate --dag /tmp/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag /tmp/<task-id>-dag.json --cwd .
+```
+
+主路径语义：
+
+| 命令 | 作用 |
+|---|---|
+| `new-task` | 创建 `.harness/tasks/<taskId>` 和 task config/source 结构；legacy workflow state 只作为兼容读输入 |
+| `dag run-task` | 根据任务上下文生成 DAG 草案 |
+| `dag validate` | 校验依赖、写入策略、shell 配置、decision gate、同 rank 写冲突等 |
+| `run-dag` | 执行 DAG，生成 `.harness/dag-runs/<lifecycle>/<runId>` 下的状态、节点 artifacts、报告材料 |
+
+### 2.2 当前目录职责
+
+| 路径 | 当前职责 | 对 Dynamic Workflow 的意义 |
+|---|---|---|
+| `src/workflows/dag/` | Agent DAG 类型、校验、执行、报告、decision envelope、recovery 建议 | 保留为 concrete DAG runtime 内核 |
+| `src/commands/` | 顶层命令实现，当前命令文件是扁平布局 | 先新增 `dag workflow-*` 子命令实现；稳定后再考虑顶层 `workflow` |
+| `src/task/` | `.harness/tasks/<taskId>` 的 task config、state、artifact、source hash、read model | WorkflowSpec / compiled DAG 可以落在 task 目录下，read model 后续应能暴露 workflow refs |
+| `src/executors/` | Cursor、Pi、shell、static executor 适配 | Dynamic engine 不绕过 executor，只生成节点给 executor 执行 |
+| `src/governance/` | skill safety、repo governance 等规则检查 | 扩展到 workflow-level risk / permission analyzer |
+| `.harness/` | runtime state、tasks、dag-runs、runs、prompts、缓存、live state | 新增 workflow planned/compiled/report state |
+| `src/executors/shell-verification.ts` | shell verification preset、command execution/report/env policy | Workflow command node 应复用这里的 shell 语义 |
+| `src/task/read-model.ts` | DAG-oriented task status / next action 推导 | 后续纳入 workflow planned/compiled/run/report refs |
+
+### 2.3 当前 Loop 语义
+
+顶层 `loop` 已经是 DAG 之上的长周期任务状态机：
+
+```text
+DAG 管一轮怎么执行和验证；
+Loop 管多轮为什么继续、下一步做什么、哪些事实已经验证、何时暂停或收口。
+```
+
+Loop 当前维护：
+
+```text
+.harness/tasks/<taskId>/loop/
+  objective.md
+  context.md
+  state.json
+  rounds.jsonl
+  signals.jsonl
+  events.jsonl
+  verification/
+  review/
+  closeout.md
+```
+
+Loop state 中已有适合与 Dynamic Workflow 对接的字段：
+
+| 字段 | 结合点 |
+|---|---|
+| `openFrontier` | 选择下一轮 workflow profile |
+| `failureStreak` | 决定继续、暂停、升级或换 workflow |
+| `completedCriteria` | 判断 closeout 是否可完成 |
+| `signals.jsonl` | 将 human instruction / approval / scope change 作为 workflow inputs |
+| `rounds.jsonl` | 记录 workflow run ref、report ref、verification summary |
+
+### 2.4 当前项目已有优势
+
+1. **执行内核已有**：不需要重新实现 executor pool、artifact store、shell verification。
+2. **治理方向正确**：已经强调 shell verification 是完成权威，模型输出不能替代验证。
+3. **DAG lifecycle 已有**：active/paused/completed run 目录、approval/rejection、resume/report 已经是现成底座。
+4. **任务状态正在 DAG 化**：`task-read-model` 已经把 source、DAG draft、DAG run、promotion、closeout 作为主状态面。
+5. **Loop 已能记录长期事实**：适合承接 workflow run 结果，但不应在 MVP 前置。
+6. **测试基础较强**：已有 DAG runner、DAG validate、DAG report、decision gate、executor、task runtime、governance、loop workflow 等测试覆盖。
+
+### 2.5 当前主要缺口
+
+| 缺口 | 表现 | 需要新增 |
+|---|---|---|
+| 没有 WorkflowSpec IR | 当前 DAG 是 concrete execution graph，不表达 logical primitive | `src/workflows/dynamic/spec.ts` |
+| 没有 workflow-level validator | 现有 validator 只理解 `DagSpec` | `src/workflows/dynamic/validate.ts` |
+| 没有 workflow compiler | 不能从 logical workflow 编译到现有 Agent DAG | `src/workflows/dynamic/compile.ts` |
+| 没有 workflow metadata 保留策略 | `DagSpec` 当前没有稳定 metadata 字段 | `compile manifest` sidecar 或显式扩展 `DagSpec` schema |
+| 没有 dynamic expansion | 静态 DAG 不能自然表达 discover -> map N items；runner ranks 当前启动时固定 | `map_agent` expansion runtime + DAG runner expansion seam |
+| verification 不是一等 workflow pattern | 可以审查，但没有 Finding/Verification 标准 artifact | `verify_agent` + artifact schema |
+| bounded loop 未进入 workflow 层 | 当前 DAG convergence 是固定 supervised chain，不是通用 `loop_until` primitive | `loop_until` bounded expansion |
+| workflow 与 Loop 未打通 | Loop 当前有 `dag` action，但没有 `workflow` action | `loop run --action workflow`，在 compiler/report 稳定后做 |
+| saved workflow/replay 未产品化 | DAG 可保存和 report，但 workflow 复用层还没有 | `.loop-agent/workflows/` / `workflow run` |
+
+---
+
+## 3. 三层定位：Dynamic Workflow Engine、DAG runtime、Loop Task
+
+### 3.1 DAG runtime
+
+一句话：
+
+> 给我一个 concrete DAG，我负责可靠、安全、可恢复地执行它。
+
+职责：
+
+- validate concrete DAG。
+- 检查依赖、环、缺失节点、writeSet 冲突、shell config、cwd 越界。
+- 调度 ready nodes。
+- 控制并发、retry、timeout、resume。
+- 调用 Cursor / Pi / shell / static executors。
+- 记录 node artifacts、stdout/stderr、executor result、decision envelope。
+- 生成 DAG report。
+
+不负责：
+
+- 决定复杂任务要拆成多少动态节点。
+- 根据上游输出生成新的 logical work。
+- 管理多轮目标、用户反馈、长期 lesson。
+
+适合场景：
+
+- 固定步骤 coding task。
+- 已经生成好的 DAG。
+- 小规模 feature / bug fix。
+- shell verification / deterministic gate。
+
+### 3.2 Dynamic Workflow DAG Engine
+
+一句话：
+
+> 给我一个目标、profile 或 WorkflowSpec，我负责把它动态编排、校验、展开、编译成 concrete DAG。
+
+职责：
+
+- 定义 `WorkflowSpec` schema。
+- 校验 logical workflow。
+- 做 workflow-level risk / permission analysis。
+- 支持 `agent`、`map_agent`、`verify_agent`、`reduce_agent`、`condition`、`loop_until`、`human_gate`、`artifact_transform`。
+- 根据上游 output 做 dynamic expansion。
+- 将 logical workflow 编译成 runtime 可执行的 concrete DAG。
+- 生成 workflow-level report。
+- 支持 workflow save / inspect / replay。
+
+不负责：
+
+- 直接执行 shell 或写文件。
+- 跳过现有 DAG runtime 调 executor。
+- 管理跨多轮目标。
+- 改写 completed DAG facts。
+
+适合场景：
+
+- PR changed files review。
+- codebase-wide audit。
+- 多文件迁移。
+- finding -> independent verifier -> reducer。
+- fix-until-pass 的单 run bounded loop。
+- 多来源 research / cross-check synthesis。
+
+### 3.3 Loop Task
+
+一句话：
+
+> 管一个长期目标跨多轮为什么继续、下一步做什么、哪些事实已验证、何时暂停或 closeout。
+
+职责：
+
+- 维护 objective、context、state、rounds、signals、closeout。
+- 记录每轮 action / result / verification / lesson / next / decision。
+- 接收 human feedback、approval、scope change。
+- 根据 `openFrontier` 与 `failureStreak` 决定下一轮动作。
+- 汇总多个 workflow/DAG/shell/review run 形成 closeout。
+
+不负责：
+
+- 执行 node。
+- 展开 map_agent。
+- 校验 workflow schema。
+- 直接修改 DAG run artifacts。
+
+适合场景：
+
+- 任务跨多轮，单次 DAG 或 workflow 难以完成。
+- 需要保留失败教训和下一步策略。
+- 需要吸收人工反馈、审批、范围变化。
+- 需要把多次 DAG run / workflow run / shell verification 汇总为交付证据。
+
+### 3.4 三者关系图
+
+```mermaid
+flowchart TD
+  U[User Task / Objective] --> T[Task Harness]
+  T --> L[Loop Task]
+  L -->|chooses bounded action| W[Dynamic Workflow DAG Engine]
+  W -->|WorkflowSpec validate / risk / compile / expand| D[Concrete Agent DAG]
+  D --> R[DAG runtime]
+  R --> E[Cursor / Pi / shell / static executors]
+  E --> A[Artifacts / logs / verification / reports]
+  A --> R
+  R -->|dagRunRef / reportRef| L
+  L --> C[Loop closeout]
+```
+
+---
+
+## 4. 目标架构
+
+### 4.1 新增模块建议
+
+```text
+src/workflows/dynamic/
+  spec.ts                 # WorkflowSpec 类型定义
+  schema.ts               # JSON schema / zod schema
+  validate.ts             # logical workflow validator
+  risk.ts                 # workflow-level risk / permission analyzer
+  compile.ts              # WorkflowSpec -> AgentDAG compiler
+  expandMap.ts            # map_agent dynamic expansion
+  expandLoop.ts           # loop_until bounded expansion
+  artifactRefs.ts         # workflow artifact reference helpers
+  artifacts.ts            # Finding / Verification / WorkflowReport types
+  profiles/
+    prReview.ts
+    auditAuth.ts
+    fixUntilCheckPasses.ts
+  report.ts               # workflow-level report
+  fixtures/
+    pr-review.workflow.json
+```
+
+命令层：
+
+```text
+src/commands/dag-workflow-plan.ts
+src/commands/dag-workflow-validate.ts
+src/commands/dag-workflow-compile.ts
+src/commands/dag-workflow-run.ts       # 可选，内部组合 validate + compile + run-dag
+src/commands/workflow-*.ts             # 稳定后再提升为顶层 workflow 命令
+```
+
+Loop 对接：
+
+```text
+src/workflows/loop/actions.ts          # 先沿用当前 Loop action 聚合文件
+src/commands/loop.ts                   # 增加 --action workflow 分派
+```
+
+### 4.2 运行态目录建议
+
+```text
+.harness/tasks/<taskId>/
+  task.json
+
+  workflows/
+    planned/
+      pr-review.workflow.json
+    validation/
+      pr-review.validation.json
+      pr-review.risk.json
+    compiled/
+      pr-review.dag.json
+      pr-review.compile-manifest.json
+    reports/
+      pr-review.workflow-report.md
+
+  loop/
+    objective.md
+    context.md
+    state.json
+    rounds.jsonl
+    signals.jsonl
+    closeout.md
+
+.harness/dag-runs/<lifecycle>/<runId>/
+  run.json
+  state.json
+  <node-id>.json
+  <node-id>/
+  expansions/
+    review-each-file.expansion.json
+    verify-findings.expansion.json
+  # DAG report is derived by `dag report` from run facts.
+```
+
+说明：
+
+- `.harness/tasks/<taskId>/workflows/` 保存 workflow 的计划、校验、风险、编译和 workflow-level report，是 task-local artifact。
+- `.harness/dag-runs/<lifecycle>/<runId>/` 仍然保存 concrete DAG run facts，是执行事实源。
+- compiled DAG 应通过 sidecar `compile-manifest.json` 或明确扩展后的 `DagSpec` 字段保留 workflow 来源。不能依赖未知 JSON 字段隐式穿过 `parseDagSpec`。
+- Phase 3 之前，`expansions/` 只是设计目标；当前 runner 不会自动创建这个目录。
+
+### 4.3 WorkflowSpec v0.1 草案
+
+```json
+{
+  "version": "0.1",
+  "kind": "dynamic-agent-workflow",
+  "meta": {
+    "name": "pr-review",
+    "description": "Review changed files and produce a ranked summary",
+    "riskLevel": "low"
+  },
+  "inputs": {
+    "base": "main",
+    "head": "HEAD"
+  },
+  "limits": {
+    "maxConcurrency": 8,
+    "maxAgentRuns": 100,
+    "maxExpandedNodes": 200,
+    "maxRetriesPerNode": 1,
+    "maxIterations": 3,
+    "maxWallClockMinutes": 30
+  },
+  "permissions": {
+    "filesystem": "read_only",
+    "shell": {
+      "mode": "allowlist",
+      "commands": ["git diff --name-only"]
+    },
+    "network": "deny",
+    "edits": "deny"
+  },
+  "nodes": [
+    {
+      "id": "discover-changed-files",
+      "type": "command",
+      "dependsOn": [],
+      "command": "git diff --name-only {{inputs.base}}...{{inputs.head}}",
+      "outputSchema": {
+        "type": "object",
+        "required": ["files"],
+        "properties": {
+          "files": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    {
+      "id": "review-each-file",
+      "type": "map_agent",
+      "dependsOn": ["discover-changed-files"],
+      "itemsFrom": "$.nodes['discover-changed-files'].output.files",
+      "itemName": "file",
+      "concurrency": 8,
+      "role": "code-reviewer",
+      "prompt": "Review {{file}} for correctness issues. Return concrete findings only.",
+      "outputSchema": {
+        "type": "object",
+        "required": ["file", "findings"],
+        "properties": {
+          "file": { "type": "string" },
+          "findings": { "type": "array" }
+        }
+      }
+    },
+    {
+      "id": "verify-findings",
+      "type": "verify_agent",
+      "dependsOn": ["review-each-file"],
+      "itemsFrom": "$.nodes['review-each-file'].output[*].findings[*]",
+      "role": "adversarial-verifier",
+      "prompt": "Independently verify this finding. Try to refute it. Return verified, refuted, or uncertain.",
+      "outputSchema": {
+        "type": "object",
+        "required": ["findingId", "status", "reason"],
+        "properties": {
+          "findingId": { "type": "string" },
+          "status": { "type": "string", "enum": ["verified", "refuted", "uncertain"] },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    {
+      "id": "final-report",
+      "type": "reduce_agent",
+      "dependsOn": ["verify-findings"],
+      "role": "report-writer",
+      "prompt": "Create a ranked, deduplicated report. Include verified findings by default; put uncertain findings separately.",
+      "outputSchema": {
+        "type": "object",
+        "required": ["summary", "findings"],
+        "properties": {
+          "summary": { "type": "string" },
+          "findings": { "type": "array" }
+        }
+      }
+    }
+  ],
+  "final": {
+    "from": "final-report"
+  }
+}
+```
+
+命名约束：
+
+- Workflow node id 推荐直接使用 kebab-case，并满足现有 `DagTask.id` 约束。
+- 如果后续允许 workflow node id 比 DAG node id 更宽，compiler 必须产出显式 id mapping，并在 expansion manifest、report、Loop round 中使用同一映射。
+- JSONPath/selector 对 kebab-case id 使用 bracket notation，例如 `$.nodes['review-each-file']...`。
+
+### 4.4 核心约束
+
+Validator 必须强制：
+
+- 每个 workflow 必须有 `version`、`kind`、`nodes`、`final`。
+- 每个 agent-like node 必须有 `outputSchema`。
+- `map_agent` / `verify_agent` 必须有 `itemsFrom`。
+- `command` 必须在 allowlist 内。
+- `loop_until` 必须有 `maxIterations`。
+- 所有 node id 唯一。
+- 所有 dependsOn 指向存在节点。
+- 禁止环，除非通过 `loop_until` 这种 bounded primitive 表达。
+- 禁止 `eval` / arbitrary JS / arbitrary shell。
+- 高风险权限必须要求 `human_gate`。
+- producer 不能 verify 自己的 finding。
+- reducer 默认不能新增 facts，只能 dedupe / rank / group / format。
+- limits 必须存在默认值与硬上限。
+
+---
+
+## 5. 分阶段落地计划
+
+下面的阶段按“每一步都能独立验证”的原则设计。不要一次性实现完整 engine。
+
+---
+
+## Phase 0：边界与命名收敛
+
+### 目标
+
+先把概念边界固化，避免后续代码把 `DAG`、`Workflow`、`Loop` 混在一起。
+
+### 产物
+
+- 将本文档作为 v0.2 roadmap 落到 `docs/`。
+- 新增或更新对象关系图文档：`Task -> WorkflowSpec -> Compiled DAG -> DAG Run -> Loop Round -> Closeout`。
+- CLI help 中明确：
+  - `dag` 是 concrete DAG 主路径。
+  - `dag workflow-*` 是 logical dynamic workflow 的实验入口。
+  - `loop` 是多轮长期控制层。
+- 明确 Level 1 fallback 已删除，不作为 Dynamic Workflow 的实现基础。
+
+### 不做
+
+- 不改 executor。
+- 不改 DAG runner。
+- 不新增动态展开。
+
+### 验证方式
+
+```bash
+bash scripts/check-repo.sh
+```
+
+### 退出标准
+
+- 文档能让新实现者清楚说明三层边界。
+- 没有新增行为风险。
+- 不再把 Loop、Workflow、DAG runner 描述成同一层东西。
+- 不再把 `src/workflows/level1/` 描述成当前可用路径。
+
+---
+
+## Phase 1：WorkflowSpec schema 与 validator
+
+### 目标
+
+新增 logical workflow 的类型系统和校验器，但不执行。
+
+### 新增代码
+
+```text
+src/workflows/dynamic/spec.ts
+src/workflows/dynamic/schema.ts
+src/workflows/dynamic/validate.ts
+src/workflows/dynamic/errors.ts
+src/workflows/dynamic/fixtures/*.workflow.json
+src/commands/dag-workflow-validate.ts
+```
+
+### 支持 node types，仅做 schema
+
+```text
+agent
+map_agent
+verify_agent
+reduce_agent
+command
+condition
+loop_until
+human_gate
+artifact_transform
+```
+
+这些是 WorkflowSpec logical primitive，不等同于现有 `DagTask.executor`。Phase 1 只校验 logical Interface，不把它们直接塞进 `DagSpec.tasks`。
+
+Phase 1 不要求全部能执行，只要求能被识别、校验、报错。
+
+### CLI
+
+```bash
+loop-agent dag workflow-validate \
+  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
+  --strict-governance
+```
+
+命令应挂在现有 `dag` 子命令下；不要先新增顶层 `workflow`，避免在 IR 未稳定时扩大公共 Interface。
+
+### Validator 规则
+
+最低必做：
+
+- invalid JSON fail。
+- missing `kind` fail。
+- missing `final` fail。
+- duplicate node id fail。
+- missing dependency fail。
+- unbounded `loop_until` fail。
+- `map_agent` without `itemsFrom` fail。
+- `command` without allowlist fail。
+- agent-like node without `outputSchema` fail。
+- unknown node type fail。
+- unknown permission mode fail。
+- node id 非 kebab-case fail，除非 compiler 已支持显式 id mapping。
+- `itemsFrom` selector 必须只引用已存在上游节点。
+- `permissions.edits != deny` 时必须有 `allowedPaths` / `forbiddenPaths` / `writeSet`。
+- broad write permissions 必须要求 `human_gate` 或编译成现有 DAG decision gate。
+
+### 测试
+
+```text
+test/dynamic-workflow-validate.test.ts
+  valid-pr-review.workflow.json passes
+  missing-final.workflow.json fails
+  duplicate-node-id.workflow.json fails
+  map-without-itemsFrom.workflow.json fails
+  command-without-allowlist.workflow.json fails
+  loop-without-maxIterations.workflow.json fails
+  agent-without-outputSchema.workflow.json fails
+  non-kebab-node-id.workflow.json fails
+```
+
+### 退出标准
+
+- 可以把一个 `WorkflowSpec` 当成可审查 artifact。
+- 错误信息能指出具体 node id 和路径。
+- 不接触 DAG runner，不引入执行风险。
+
+---
+
+## Phase 2：WorkflowSpec -> AgentDAG compiler v0
+
+### 目标
+
+证明 logical workflow 可以稳定编译到现有 concrete Agent DAG。
+
+### 范围
+
+Phase 2 先支持静态可编译 node：
+
+```text
+agent
+reduce_agent
+command
+artifact_transform
+human_gate placeholder
+```
+
+`map_agent` / `verify_agent` 在 Phase 2 可以先编译成 placeholder/barrier node，或者只支持显式 `items` 的静态展开：
+
+```json
+{
+  "type": "map_agent",
+  "items": ["a.ts", "b.ts"]
+}
+```
+
+动态 `itemsFrom` 留到 Phase 3。
+
+### 新增代码
+
+```text
+src/workflows/dynamic/compile.ts
+src/workflows/dynamic/compileTypes.ts
+src/workflows/dynamic/artifactRefs.ts
+src/commands/dag-workflow-compile.ts
+```
+
+### CLI
+
+```bash
+loop-agent dag workflow-compile \
+  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
+  --output .harness/tasks/<taskId>/workflows/compiled/pr-review.dag.json
+```
+
+### 编译规则
+
+- 保留 workflow node -> concrete DAG task 映射。
+- 如果 `DagSpec` schema 暂不扩展 origin/metadata 字段，必须写 `compile-manifest.json` sidecar；不要依赖未知字段穿过 `parseDagSpec`。
+- 每个 node 的 `outputSchema` 先转成 `outputContract` 文本或 compile manifest 约束；runtime schema enforcement 可后置。
+- `permissions` 转成 `writePolicy`、`allowedPaths`、`forbiddenPaths`、`writeSet`、shell config 等现有 executor constraints。
+- `limits` 转成 DAG run options、workflow validator hard cap 或 compile manifest；不要假设现有 `DagSpec` 已有全部 limit 字段。
+- `command` 编译成 `executor: "shell"`，并复用现有 `shell` config / allowlist / timeout / cwd 约束。
+- `agent` / `reduce_agent` 编译成 `pi` 或 `static` 节点；read-only profile 先默认 `pi`。
+- `human_gate` 优先编译成现有 DAG `decisionGate` / paused lifecycle；不要新增第二套 approval runtime。
+- `artifact_transform` 在 Phase 2 只允许 deterministic transform；不能引入 stub executor 作为完成实现。
+
+### 测试
+
+```text
+test/dynamic-workflow-compile.test.ts
+  simple workflow compiles to existing AgentDAG shape
+  command node preserves allowlist metadata
+  reduce node depends on all upstream nodes
+  human_gate compiles to existing DAG decision gate semantics
+  workflow metadata is preserved in compile manifest or explicit DagSpec field
+```
+
+Golden fixture：
+
+```text
+test/fixtures/dynamic/simple.workflow.json
+测试输出：test/fixtures/dynamic/simple.compiled-dag.json
+```
+
+### 验证命令
+
+```bash
+loop-agent dag workflow-validate --workflow test/fixtures/dynamic/simple.workflow.json
+loop-agent dag workflow-compile --workflow test/fixtures/dynamic/simple.workflow.json --output /tmp/simple.dag.json
+loop-agent dag validate --dag /tmp/simple.dag.json --strict-governance
+```
+
+### 退出标准
+
+- WorkflowSpec 能编译成现有 DAG validator 接受的 DAG。
+- 现有 `run-dag` 不需要大改。
+- 编译产物可 diff、可审查。
+- 编译产物不包含未知 `DagSpec` 字段，或相关字段已经加入 `DagSpec` schema 和 tests。
+
+---
+
+## Phase 3：Dynamic expansion v0：map_agent
+
+### 目标
+
+实现真正的 dynamic workflow 核心：
+
+```text
+discover targets
+  -> map_agent dynamically expands N concrete nodes
+  -> reduce_agent fan-in
+```
+
+### 设计选择
+
+推荐采用 **runtime expansion manifest**，而不是把所有动态能力塞进 planner。
+
+当前 `run-dag` 在运行开始时根据 `DagSpec.tasks` 计算固定 ranks。真正的 dynamic expansion 需要新增一个明确的 runner seam，不能只在 compiler 中生成占位节点后假设 scheduler 会自动接收 child nodes。
+
+执行到 `map_agent` 时：
+
+1. 读取 `itemsFrom` 指向的上游 JSON output。
+2. 校验 items 是 array。
+3. 检查 `maxItems`、`maxExpandedNodes`、`maxAgentRuns`。
+4. 生成 concrete child nodes：
+
+```text
+review-each-file-0001
+review-each-file-0002
+review-each-file-0003
+```
+
+5. 写入：
+
+```text
+.harness/dag-runs/<lifecycle>/<runId>/expansions/review-each-file.expansion.json
+```
+
+6. runner 更新 state/ranks 或通过 expansion-aware checkpoint 调度 child nodes。
+7. `map_agent` barrier 在所有 child completed 后 completed。
+
+### 新增代码
+
+```text
+src/workflows/dynamic/expandMap.ts
+src/workflows/dag/runtimeExpansion.ts      # 如果需要在 DAG runner 层接入
+src/workflows/dag/expansionManifest.ts
+```
+
+### Expansion manifest 草案
+
+```json
+{
+  "workflowNodeId": "review-each-file",
+  "expandedAt": "2026-07-04T00:00:00.000Z",
+  "itemsFrom": "$.nodes['discover-changed-files'].output.files",
+  "itemCount": 3,
+  "children": [
+    {
+      "nodeId": "review-each-file-0001",
+      "itemRef": "$.items[0]",
+      "itemValueHash": "sha256:..."
+    }
+  ]
+}
+```
+
+### CLI 验证场景
+
+先用 static executor 或 command fixture：
+
+```text
+discover-files static output: { "files": ["a.ts", "b.ts"] }
+map_agent review-each-file over files
+reduce_agent final-report
+```
+
+命令：
+
+```bash
+loop-agent dag workflow-compile --workflow test/fixtures/dynamic/map.workflow.json --output /tmp/map.dag.json
+loop-agent run-dag --dag /tmp/map.dag.json --cwd .
+```
+
+### 测试
+
+```text
+test/dynamic-workflow-expand-map.test.ts
+  expands N children from upstream JSON output
+  fails when itemsFrom path missing
+  fails when itemsFrom is not array
+  respects maxItems
+  respects maxExpandedNodes
+  writes expansion manifest
+  expanded child ids are valid DagTask ids
+  resume does not duplicate already-expanded children
+```
+
+### 退出标准
+
+- 可以跑通 discover -> map -> reduce。
+- resume 不重复生成 child nodes。
+- expansion manifest 可审查。
+- map fan-out 被 limits 约束。
+
+---
+
+## Phase 4：Finding / Verification / Reducer 标准 artifact
+
+### 目标
+
+把 Claude Dynamic Workflows 中最有价值的质量模式一等化：
+
+```text
+producer -> finding
+finding -> independent verifier
+verified finding -> reducer
+```
+
+### 新增标准 artifact
+
+```ts
+type Finding = {
+  id: string
+  sourceNodeId: string
+  targetRef: string
+  title: string
+  severity: 'low' | 'medium' | 'high' | 'critical'
+  evidence: EvidenceRef[]
+  recommendation: string
+}
+
+type Verification = {
+  findingId: string
+  verifierNodeId: string
+  status: 'verified' | 'refuted' | 'uncertain'
+  reason: string
+  evidence: EvidenceRef[]
+}
+
+type WorkflowReport = {
+  summary: string
+  verifiedFindings: Finding[]
+  uncertainFindings: Finding[]
+  refutedFindingsRef?: ArtifactRef
+  evidenceRefs: ArtifactRef[]
+}
+```
+
+### 新增 node semantics
+
+```text
+verify_agent:
+  - 本质是受约束的 map_agent
+  - itemsFrom 通常指向 findings
+  - verifier 不能是 producer node
+  - verifier prompt 只能看到 finding + evidence + target artifact
+  - verifier 不看 producer chain-of-thought
+```
+
+```text
+reduce_agent:
+  - 只做 dedupe / rank / group / format
+  - 默认不能新增事实发现
+  - final report 默认只包含 verified findings
+  - uncertain findings 单列
+  - refuted findings 只进入 appendix / trace
+```
+
+### 内置 profile：`pr-review`
+
+第一条真实可演示 workflow：
+
+```text
+discover-changed-files
+  -> map_agent(review-each-file)
+  -> verify_agent(verify-each-finding)
+  -> reduce_agent(final-ranked-summary)
+```
+
+CLI：
+
+```bash
+loop-agent dag workflow-plan <taskId> --profile pr-review \
+  --output .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json
+
+loop-agent dag workflow-validate \
+  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
+  --strict-governance
+
+loop-agent dag workflow-compile \
+  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
+  --output .harness/tasks/<taskId>/workflows/compiled/pr-review.dag.json
+
+loop-agent run-dag \
+  --dag .harness/tasks/<taskId>/workflows/compiled/pr-review.dag.json \
+  --cwd .
+```
+
+### 测试
+
+```text
+test/dynamic-workflow-verification.test.ts
+  verify_agent expands per finding
+  producer cannot verify own finding
+  verified/refuted/uncertain statuses are preserved
+  reducer includes only verified findings by default
+  uncertain findings are separated
+  refuted findings are excluded from main report
+```
+
+### 退出标准
+
+- `pr-review` profile 能在 fixture repo 或 static executor 下跑通。
+- final report 能体现 verified / uncertain / refuted 分层。
+- reducer 不新增未验证 fact。
+
+---
+
+## Phase 5：Dynamic Workflow 与 Loop Task 打通
+
+### 目标
+
+让 Dynamic Workflow 成为 Loop 的一种 bounded action。
+
+当前 Loop 已有：
+
+```text
+loop run --action shell-verify
+loop run --action pi-review
+loop run --action cursor-fix
+loop run --action dag [--execute]
+```
+
+新增：
+
+```bash
+loop-agent loop run <taskId> --action workflow --profile pr-review --execute
+```
+
+或：
+
+```bash
+loop-agent loop run <taskId> \
+  --action workflow \
+  --workflow .harness/tasks/<taskId>/workflows/planned/pr-review.workflow.json \
+  --execute
+```
+
+### Loop round 记录格式
+
+```json
+{
+  "round": 4,
+  "action": "workflow",
+  "workflow": "pr-review",
+  "workflowRef": ".harness/tasks/T/workflows/planned/pr-review.workflow.json",
+  "compiledDagRef": ".harness/tasks/T/workflows/compiled/pr-review.dag.json",
+  "compileManifestRef": ".harness/tasks/T/workflows/compiled/pr-review.compile-manifest.json",
+  "runRef": ".harness/dag-runs/<lifecycle>/run-123",
+  "reportRef": ".harness/tasks/T/workflows/reports/pr-review.workflow-report.md",
+  "result": "Reviewed 17 changed files; produced 8 findings.",
+  "verification": "5 verified, 2 refuted, 1 uncertain.",
+  "lesson": "Most issues are concentrated in CLI routing.",
+  "next": "Fix verified high severity findings.",
+  "decision": "continue"
+}
+```
+
+### Loop context 更新原则
+
+Loop `context.md` 只吸收高层事实，不复制全部 node outputs：
+
+```text
+已验证事实：
+- pr-review workflow scanned 17 files.
+- 5 findings verified.
+- 1 finding uncertain.
+- no code edits were made.
+
+下一步：
+- run fix-verified-findings workflow after human approval.
+```
+
+### signals -> workflow inputs
+
+`signals.jsonl` 中的人工反馈应成为 workflow inputs：
+
+```json
+{
+  "severityFilter": ["high", "critical"],
+  "forbiddenPaths": ["billing/**"],
+  "humanInstructionsRef": ".harness/tasks/T/loop/signals.jsonl"
+}
+```
+
+### 测试
+
+```text
+test/loop-workflow-action.test.ts
+  loop workflow action records workflowRef/runRef/reportRef
+  loop context updates from workflow summary
+  loop does not rewrite DAG run artifacts
+  loop closeout includes workflow evidence
+  loop --auto can choose workflow from openFrontier
+```
+
+### 退出标准
+
+- Loop 可以运行 workflow action。
+- Workflow run facts 以 ref 形式进入 `rounds.jsonl`。
+- `loop closeout` 能引用 workflow evidence。
+- Loop 不直接改写 completed DAG facts。
+
+---
+
+## Phase 6：condition 与 loop_until
+
+### 目标
+
+支持单次 workflow 内的 bounded dynamic control。
+
+### condition
+
+`condition` 根据结构化 output 决定边：
+
+```json
+{
+  "id": "choose-next",
+  "type": "condition",
+  "dependsOn": ["run-typecheck"],
+  "cases": [
+    {
+      "when": "$.nodes['run-typecheck'].output.status == 'passed'",
+      "then": "final-report"
+    },
+    {
+      "when": "$.nodes['run-typecheck'].output.status == 'failed'",
+      "then": "analyze-errors"
+    }
+  ],
+  "default": "human-gate"
+}
+```
+
+### loop_until
+
+`loop_until` 必须 bounded：
+
+```json
+{
+  "id": "fix-until-tsc-passes",
+  "type": "loop_until",
+  "maxIterations": 5,
+  "stopWhen": {
+    "any": [
+      "$.last.output.status == 'passed'",
+      "$.stagnation.rounds >= 2"
+    ]
+  },
+  "body": [
+    { "id": "analyze-errors", "type": "agent" },
+    { "id": "apply-fixes", "type": "agent" },
+    { "id": "rerun-tsc", "type": "command" }
+  ]
+}
+```
+
+实现建议：
+
+```text
+不要允许真正无限环。
+编译时或 runtime expansion 时展开成最多 N 轮：
+round_1 -> condition_1 -> round_2 -> condition_2 -> ... -> round_N
+```
+
+### 内置 profile
+
+```text
+fix-until-check-passes
+```
+
+流程：
+
+```text
+run-check
+  -> loop_until(maxIterations=3)
+       analyze-errors
+       apply-bounded-fix
+       rerun-check
+  -> final-report
+```
+
+### 测试
+
+```text
+test/dynamic-workflow-condition.test.ts
+test/dynamic-workflow-loop-until.test.ts
+  condition follows expected branch
+  condition uses default branch on no match
+  loop_until stops on passed status
+  loop_until stops on maxIterations
+  loop_until detects no-progress sentinel
+  loop_until fails validation without maxIterations
+```
+
+### 退出标准
+
+- bounded loop 可以跑 shell/static fixture。
+- 没有任何 unbounded cycle 能通过 validator。
+- loop_until 结果能进入 DAG report 与 workflow report。
+
+---
+
+## Phase 7：human_gate、approval、pause/resume
+
+### 目标
+
+把高风险 workflow 的审批点纳入 runtime，而不是依靠 prompt 约定。
+
+### human_gate 语义
+
+```json
+{
+  "id": "approve-auth-edits",
+  "type": "human_gate",
+  "dependsOn": ["plan-auth-changes"],
+  "reason": "Auth middleware edits require explicit approval",
+  "approvalSchema": {
+    "type": "object",
+    "required": ["approved", "scope"],
+    "properties": {
+      "approved": { "type": "boolean" },
+      "scope": { "type": "array", "items": { "type": "string" } }
+    }
+  }
+}
+```
+
+### 命令
+
+当前仓库已经有 DAG approval 命令；`human_gate` 应编译到这套机制：
+
+```bash
+loop-agent dag approve --run-id <runId> --option <option-id> [--notes <text>]
+loop-agent dag reject --run-id <runId> --reason "Need manual review"
+loop-agent dag resume --run-id <runId>
+```
+
+Loop integration：
+
+```bash
+loop-agent loop add-signal <taskId> --type approval --message "Approved high severity auth fixes"
+loop-agent loop run <taskId> --auto
+```
+
+### 测试
+
+```text
+test/dynamic-workflow-human-gate.test.ts
+  human_gate pauses run
+  approval resumes descendants
+  rejection marks workflow blocked
+  loop signal can satisfy pending gate
+```
+
+### 退出标准
+
+- 高风险 workflow 可以在 gate 暂停。
+- approval/rejection 都进入 audit trail。
+- Loop 能记录 pending approval 并 resume。
+
+---
+
+## Phase 8：saved workflows、replay、operator UX
+
+### 目标
+
+把 workflow 从一次性 plan 变成可复用、可 diff、可 replay 的产品能力。
+
+### 保存位置
+
+```text
+.loop-agent/workflows/          # repo shared
+~/.loop-agent/workflows/        # personal
+.harness/tasks/<taskId>/workflows/  # task-local generated plans
+```
+
+### 命令
+
+```bash
+loop-agent workflow list
+loop-agent workflow inspect pr-review
+loop-agent workflow run pr-review --args '{"base":"main","head":"HEAD"}'
+loop-agent workflow save --from .harness/tasks/T/workflows/planned/pr-review.workflow.json --name pr-review
+loop-agent workflow diff pr-review --against .harness/tasks/T/workflows/planned/pr-review.workflow.json
+loop-agent workflow replay <runId>
+```
+
+DAG operator UX：
+
+```bash
+loop-agent dag status --run-id <runId>
+loop-agent dag doctor
+loop-agent dag report --run-id <runId> --json --lifecycle all
+loop-agent dag decision inspect --run-id <runId>
+loop-agent dag decision validate --run-id <runId>
+loop-agent dag resume --run-id <runId>
+```
+
+未来如果需要更细粒度 operator UX，再新增 `inspect-node`、`restart-node`、`stop` 等命令；不要在 saved workflow 阶段顺手扩大 DAG control plane。
+
+### 测试
+
+```text
+test/workflow-list.test.ts
+test/workflow-run.test.ts
+test/workflow-save.test.ts
+test/workflow-replay.test.ts
+test/dag-operator-status.test.ts
+```
+
+### 退出标准
+
+- workflow 可保存、可复用、可传 args。
+- replay 不重复已完成 artifacts，或明确说明哪些节点重新执行。
+- operator 能定位失败 node、查看 expansion、查看 verifier 结果。
+
+---
+
+## Phase 9：大规模迁移与 worktree/shard execution
+
+### 目标
+
+支持更高风险、更高价值的场景：多文件 migration。
+
+### 原则
+
+- 不允许多个 writer agent 在同一工作树无隔离并发写。
+- 使用 shard / worktree / delegate / harvest 模式。
+- 每个 shard 有独立 verification。
+- merge patch 前做 conflict 和 test gate。
+
+### Workflow pattern
+
+```text
+discover-targets
+  -> shard-targets
+  -> map_agent(migrate-shard-in-isolated-worktree)
+  -> map_agent(verify-shard)
+  -> reduce_agent(merge-plan)
+  -> human_gate(approve-merge)
+  -> apply-merge
+  -> final-shell-verify
+```
+
+### 测试
+
+```text
+test/dynamic-workflow-sharded-migration.test.ts
+  writeSet conflicts rejected
+  shards get isolated workspaces
+  failed shard does not block successful shard artifacts
+  merge requires human_gate when writeSet is broad
+```
+
+### 退出标准
+
+- 可以安全 dogfood 一个低风险 repo migration。
+- 每个 shard 的 patch、verification、failure reason 独立可追踪。
+- 最终 merge 有明确 approval 和 shell verification。
+
+---
+
+## 6. 建议 MVP 顺序
+
+不要先做自动修代码。MVP 应分成两层：
+
+1. **工程 MVP**：`WorkflowSpec -> validate -> compile -> dag validate`，不要求 runtime dynamic expansion。
+2. **产品 MVP**：read-only PR review，因为它最能展示 Dynamic Workflow 的价值，同时风险低。
+
+这样安排的原因是：当前 `run-dag` 还没有动态插入节点的 seam。先做工程 MVP 可以验证 Interface 和 compiler depth，再进入 map/verify/reduce 的产品 MVP。
+
+### 6.1 工程 MVP：static workflow compile
+
+目标：
+
+```text
+simple-readonly-workflow.workflow.json
+  -> dag workflow-validate
+  -> dag workflow-compile
+  -> dag validate --strict-governance
+```
+
+验收：
+
+```bash
+loop-agent dag workflow-validate --workflow test/fixtures/dynamic/simple-readonly.workflow.json --strict-governance
+loop-agent dag workflow-compile --workflow test/fixtures/dynamic/simple-readonly.workflow.json --output /tmp/simple-readonly.dag.json
+loop-agent dag validate --dag /tmp/simple-readonly.dag.json --strict-models --strict-governance
+```
+
+退出标准：
+
+- 不改 `run-dag`。
+- 编译产物通过现有 DAG validator。
+- compile manifest 能解释每个 workflow node 对应哪个 DAG task。
+
+### 6.2 产品 MVP：PR Review Workflow
+
+MVP workflow：
+
+```text
+discover-changed-files
+  -> map_agent(review-each-file)
+  -> verify_agent(verify-each-finding)
+  -> reduce_agent(final-ranked-summary)
+```
+
+### 为什么选它
+
+- 文件数量运行时才知道，能验证 dynamic expansion。
+- findings 数量运行时才知道，能验证 second-order expansion。
+- verifier/reducer 能展示质量闭环。
+- read-only，风险低。
+- 最终 report 容易人工评估。
+- 可后续接 Loop：如果有 verified high severity findings，下一轮再进入 fix workflow。
+- read-only PR review 不要求 writer concurrency，因此不会先触发多 writer/worktree 风险。
+
+### MVP 验收
+
+```bash
+loop-agent new-task pr-review-demo "Review changed files"
+loop-agent dag workflow-plan pr-review-demo --profile pr-review --output .harness/tasks/pr-review-demo/workflows/planned/pr-review.workflow.json
+loop-agent dag workflow-validate --workflow .harness/tasks/pr-review-demo/workflows/planned/pr-review.workflow.json --strict-governance
+loop-agent dag workflow-compile --workflow .harness/tasks/pr-review-demo/workflows/planned/pr-review.workflow.json --output .harness/tasks/pr-review-demo/workflows/compiled/pr-review.dag.json
+loop-agent dag validate --dag .harness/tasks/pr-review-demo/workflows/compiled/pr-review.dag.json --strict-governance
+loop-agent run-dag --dag .harness/tasks/pr-review-demo/workflows/compiled/pr-review.dag.json --cwd .
+```
+
+验收结果：
+
+- `.harness/dag-runs/.../expansions/review-each-file.expansion.json` 存在。
+- `.harness/dag-runs/.../expansions/verify-findings.expansion.json` 存在。
+- final report 区分 verified / uncertain / refuted。
+- run-dag report 可引用到每个 verifier artifact。
+- workflow-level report 可复制给用户。
+
+---
+
+## 7. 测试与验证金字塔
+
+### 7.1 Unit tests
+
+```text
+WorkflowSpec parser
+schema validation
+risk analyzer
+JSONPath itemsFrom resolver
+map expansion
+loop_until expansion
+artifact ref resolver
+Finding / Verification schema
+```
+
+### 7.2 Golden tests
+
+输入：
+
+```text
+*.workflow.json
+```
+
+输出：
+
+```text
+*.compiled-dag.json
+*.validation.json
+*.risk.json
+```
+
+目的：保证 IR 编译稳定、可 diff。
+
+### 7.3 Dry-run tests
+
+```bash
+loop-agent dag workflow-validate --workflow fixture.workflow.json
+loop-agent dag workflow-compile --workflow fixture.workflow.json --output /tmp/fixture.dag.json
+loop-agent dag validate --dag /tmp/fixture.dag.json --strict-governance
+```
+
+### 7.4 Static executor integration tests
+
+用 `static` executor 模拟：
+
+- discover files output。
+- reviewer findings output。
+- verifier status output。
+- reducer report output。
+
+不依赖外部模型，CI 稳定。
+
+### 7.5 Shell-only smoke tests
+
+用只读 command：
+
+```bash
+git diff --name-only main...HEAD
+```
+
+测试真实 command allowlist、cwd、stdout parsing、artifact。
+
+### 7.6 Model executor dogfood tests
+
+在本地或非 CI 环境跑：
+
+- Pi reviewer。
+- Pi verifier。
+- Cursor read-only reviewer。
+- 小 repo / 小目录。
+
+### 7.7 Loop integration tests
+
+验证：
+
+- workflow action append round。
+- workflow report ref 进入 closeout。
+- signal -> workflow input。
+- failureStreak 影响 `loop --auto`。
+- Loop 不改写 completed DAG facts。
+
+---
+
+## 8. 风险与治理策略
+
+### 8.1 禁止任意代码作为 workflow IR
+
+不要支持：
+
+```json
+{ "eval": "some JavaScript" }
+```
+
+也不要支持：
+
+```json
+{ "shell": "{{model_generated_command}}" }
+```
+
+表达力不够时，新增 bounded primitive：
+
+```text
+agent
+map_agent
+verify_agent
+reduce_agent
+command
+condition
+loop_until
+human_gate
+artifact_transform
+subworkflow
+```
+
+### 8.2 强制 limits
+
+WorkflowSpec 必须有默认 limits，且 runtime 有硬上限：
+
+```json
+{
+  "maxConcurrency": 8,
+  "maxAgentRuns": 100,
+  "maxExpandedNodes": 200,
+  "maxRetriesPerNode": 1,
+  "maxIterations": 3,
+  "maxWallClockMinutes": 30
+}
+```
+
+不能相信 planner 自己节制。
+
+### 8.3 权限与写入范围
+
+- read-only workflow 默认风险低。
+- edits 必须声明 `allowedPaths` / `forbiddenPaths` / `writeSet`。
+- 同 rank writeSet 冲突必须 fail。
+- broad writeSet 必须 human_gate。
+- command 必须 allowlist。
+- network 默认 deny。
+- secrets 默认不可见。
+
+### 8.4 Verifier 独立性
+
+- producer 不能 verify 自己的 finding。
+- verifier 只看 finding、evidence、target artifact。
+- reducer 不新增 facts。
+- final report 默认只包含 verified findings。
+
+### 8.5 Completed facts 不可改写
+
+- DAG run artifact 是事实源。
+- Workflow report 可以 summarize，但不改写 node output。
+- Loop 可以引用 workflow/DAG facts，但不改写 completed DAG facts。
+
+---
+
+## 9. 推荐 PR 顺序
+
+### PR 1：文档与对象边界
+
+- 添加/更新本文档。
+- 必要时更新 CLI help 文案，但不要在没有实现的情况下承诺 `workflow` 顶层命令。
+- 明确 DAG / Workflow / Loop 分层。
+- 明确 Level 1 fallback 已删除，不能作为 workflow 基础。
+
+### PR 2：WorkflowSpec schema + validator
+
+- 新增 `src/workflows/dynamic/spec.ts`。
+- 新增 validator。
+- 加 fixture tests。
+- 新增 `dag workflow-validate` 实验入口。
+
+### PR 3：workflow compile v0
+
+- 支持 agent / command / reduce / artifact_transform。
+- 产出 existing AgentDAG。
+- 通过 existing `dag validate`。
+- 产出 compile manifest 或扩展后的稳定 `DagSpec` origin 字段。
+
+### PR 4：map_agent dynamic expansion
+
+- 支持 `itemsFrom`。
+- 写 expansion manifest。
+- 支持 resume 不重复展开。
+- 明确 runner expansion seam，不隐式改写 completed DAG facts。
+
+### PR 5：verify_agent + Finding/Verification artifact
+
+- 标准化 finding / verification。
+- reducer 默认只包含 verified。
+
+### PR 6：pr-review profile
+
+- read-only MVP。
+- fixture + static executor + optional model dogfood。
+
+### PR 7：loop workflow action
+
+- `loop run --action workflow`。
+- round 记录 workflowRef / runRef / reportRef。
+- closeout 汇总 workflow evidence。
+
+### PR 8：condition / loop_until
+
+- bounded loop。
+- fix-until-check-passes profile。
+
+### PR 9：workflow save / run / replay
+
+- `.loop-agent/workflows/`。
+- `workflow list/inspect/run/save/replay`。
+
+### PR 10：operator UX
+
+- 优先增强现有 status / doctor / report / decision / resume。
+- 只有在真实操作痛点出现后，再考虑 inspect-node / restart-node / stop。
+
+---
+
+## 10. 非目标
+
+短期不要做：
+
+- 完整 JS workflow runtime。
+- 任意代码 eval。
+- 无限制 autonomous loop。
+- 大规模自动改代码。
+- 多 writer agent 在同一 worktree 并发写。
+- 用 Loop 替代 DAG runner。
+- 用 reducer 重新审计 facts。
+- 用模型自述替代 shell verification。
+- 在 IR 未稳定前新增顶层 `workflow` 公共命令。
+- 为了支持 Dynamic Workflow 恢复 Level 1 顺序工作流。
+
+---
+
+## 11. 成功标准
+
+### 技术成功标准
+
+- WorkflowSpec 是稳定、可审查、可 diff 的 artifact。
+- Dynamic workflow 可以编译成现有 Agent DAG。
+- compile manifest 或 `DagSpec` origin 字段能追踪 workflow node 到 DAG task 的映射。
+- map_agent 可以根据上游 output 动态展开。
+- verify_agent 可以独立验证 findings。
+- reducer 可以输出 verified-first report。
+- Loop 可以记录 workflow run evidence。
+- 所有阶段都有 deterministic tests。
+
+### 产品成功标准
+
+用户可以这样理解系统：
+
+```text
+普通任务：用 DAG runtime。
+一次复杂并行任务：用 Dynamic Workflow。
+长期多轮任务：用 Loop Task 管多个 workflow/DAG/shell/review round。
+```
+
+### 治理成功标准
+
+- 高风险 workflow 必须审批。
+- 所有 fan-out 有硬上限。
+- 所有 shell 命令可审计。
+- 所有写入范围可审计。
+- 所有 completed facts 有 artifact ref。
+- closeout 有 verification evidence。
+
+---
+
+## 12. 最终定位文案
+
+中文：
+
+> `loop-agent` 是一个 repo-local AI coding workflow runtime。它以 DAG runtime 作为执行内核，在其上通过 Dynamic Workflow DAG Engine 把复杂任务动态编译为可验证的 Agent DAG；对于长期目标，Loop Task 将多次 workflow run、DAG run、shell verification、人工反馈和 closeout 串成可恢复、可审查、可交付的工程闭环。
+
+英文：
+
+> `loop-agent` is a repo-local AI coding workflow runtime. Its DAG runtime executes concrete Agent DAGs with artifacts and verification. The Dynamic Workflow DAG Engine compiles high-level workflow specs into expanded, verifiable Agent DAGs. For long-running objectives, Loop Task coordinates multiple workflow, DAG, shell, and review rounds into a recoverable and auditable delivery loop.
+
+---
+
+## 参考来源
+
+[1] Anthropic Claude Code Docs, “Orchestrate subagents at scale with dynamic workflows”, accessed 2026-07-04.
+https://code.claude.com/docs/en/workflows
+
+[2] 用户上传文档：`粘贴的 markdown (1).md`，关于用 DAG JSON 复刻 Claude Dynamic Workflows 的设计说明。
+
+[3] 用户上传文档：`2026-07-02-repository-analysis.md`，关于当前 `loop-agent` 仓库结构、DAG 主路径、Loop 语义、治理边界与健康度的分析报告。
+
+[4] 当前源码仓库历史 completed execution plan，关于删除 Level 1 fallback、抽取 shell verification、建立 DAG-oriented task read model 的完成记录；发布包只携带 execution plan 目录说明，不携带具体历史计划正文。
+
+[5] 当前源码复核：`src/workflows/dag/types.ts`、`src/workflows/dag/validate.ts`、`src/workflows/dag/runner.ts`、`src/workflows/loop/actions.ts`、`src/task/read-model.ts`、`src/cli/catalog.ts`。