@tea-agent/loop-agent 0.26.5-beta.2 → 0.27.1-beta.0

package/docs/templates/production-readiness-checklist.md

@@ -23,10 +23,10 @@
 
 ## DAG 主路径
 
-- [ ] 已运行 `loop-agent new-task <task-id> "Task title"` 或 task 已存在
-- [ ] `loop-agent dag run-task <task-id> --profile auto --strict-models --output <dag-path>` 产出 DAG spec
+- [ ] 已运行 `loop-agent task advance <task-id> "Task title" --prd <prd.md> --allowed-path "<glob>" --json`（或 task 已存在且契约就绪）
+- [ ] `task advance` 产出/刷新 `.harness/tasks/<task-id>/dag.json` 并打开 writeSet gate
 - [ ] `loop-agent dag validate --dag <dag-path> --strict-models --strict-governance` 通过
-- [ ] `loop-agent run-dag --dag <dag-path> --cwd .` 产出 run id
+- [ ] `loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json` 产出 run id / lifecycle 事实（advanced arbitrary DAG 才用 `dag execute`）
 - [ ] `loop-agent dag report --run-id <run-id> --markdown` 可读
 - [ ] `loop-agent dag doctor --run-id <run-id>` 能解释失败或 paused run
 

package/harness.json

@@ -6,7 +6,7 @@
   "workflowPolicy": {
     "defaultImplementationWorkflow": "agent-dag",
     "dag": {
-      "defaultEntry": "dag run-task",
+     "defaultEntry": "task advance",
       "outputLanguage": "zh-CN",
       "profileRouting": {
         "minimal": "standard-dag",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.26.5-beta.2",
+  "version": "0.27.1-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/scripts/kb-bootstrap-init-skeleton.sh

@@ -157,7 +157,8 @@ Structured project knowledge (Git is authority).
 bash scripts/kb-bootstrap-init-skeleton.sh --root .
 # edit knowledge/bootstrap/scope.yaml
 # task.json: { "taskKind": "knowledge-graph-bootstrap", ... }
-loop-agent dag run-task <id> --execute --cwd .
+loop-agent task advance <id> --task-kind knowledge-graph-bootstrap --allowed-path "<glob>" --json
+# then: loop-agent task advance <id> --approve-gate "write-set-review:<digest>" --json
 ```
 
 ## Query (Phase A design)

package/scripts/kb-graph-incremental-prepare.mjs

@@ -354,7 +354,7 @@ function main() {
 			"Next:",
 			"```bash",
 			"# task.json: { \"taskKind\": \"knowledge-graph-bootstrap\", ... }",
-			"loop-agent dag run-task <task-id> --execute --cwd .",
+			"loop-agent task advance <task-id> --task-kind knowledge-graph-bootstrap --json  # then --approve-gate",
 			`bash scripts/kb-graph-materialize.sh --root ${args.root}`,
 			"```",
 			"",
@@ -375,7 +375,7 @@ function main() {
 					services: args.services,
 					domains: args.domains,
 				},
-				next: "set task.json.taskKind=knowledge-graph-bootstrap; dag run-task --execute",
+				next: "set task.json.taskKind=knowledge-graph-bootstrap; task advance --json then --approve-gate",
 			},
 			null,
 			2,

package/skills/loop-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-agent
 description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 Agent DAG/CLI（new-task, dag run-task, dag validate, run-dag），主会话编排而不直接写业务实现.
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG / task advance lifecycle, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, task advance, task status, dag validate, dag execute, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 task advance / Agent DAG CLI，主会话编排而不直接写业务实现.
 references:
   - path: references/harness-policy.md
     required: true
@@ -26,24 +26,29 @@ Entry: routing and hard rules. Required details come from frontmatter references
 ## 唯一推荐执行路径
 
 ```bash
-loop-agent new-task <task-id> "Title"
-# PRD-first default: detailed PRD → import-prd → task source prepare --apply
-# no hand-written/LLM source by default
-loop-agent import-prd <task-id> --file <prd.md>
-loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
-# plan create for non-trivial work (see references/source-and-plan-practice.md)
-loop-agent dag run-task <task-id> --profile auto --strict-models
-# default draft: .harness/tasks/<task-id>/dag.json
-loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
-loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
+# 标准 mutation：task advance（create/import/prepare/generate/validate → writeSet gate）
+loop-agent task advance <task-id> "Title" \
+  --prd <prd.md> \
+  --allowed-path "<glob>" \
+  --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" \
+  --json
+
+# 审查 JSON 中的 gate.writeSet / gate.digest 后批准并长跑
+loop-agent task advance <task-id> \
+  --approve-gate "write-set-review:<digest>" \
+  --json
+
+# 可选只读（无 refresh 副作用）
+loop-agent task status <task-id> --json
 ```
 
-执行前审阅 `profileRouting`、`governanceProfile`、writer `writeSet`、`forbiddenPaths`、decision gate mode。
+非微小跨会话任务仍可先 `plan create`（见 references/source-and-plan-practice.md）。主会话只审 gate/writeSet 与验证证据，不拼低层 prepare/run-task/run-dag/promote/closeout 命令串。
 
 ## 进阶主题路由
 
 | 主题 | Reference |
-|---|---|
+| --- | --- |
 | Harness policy、Loop、SePO-lite | `references/harness-policy.md` |
 | Agent DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
 | Operator commands、`agent-worker` | `references/command-reference.md` |

package/skills/loop-agent/references/README.md

@@ -39,7 +39,7 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 | `task-workflow.md` | 处理 task source material、task config、repo adapter 或 legacy task 目录布局 |
 | `pi-prompt.md` | 运行短时 one-shot Pi SDK task，且不创建 `.harness/tasks/` |
 | `one-shot-runs.md` | 解释 `.harness/runs/{active,completed,failed}` 的创建条件、生命周期、治理清理与 `promote-run` 关系 |
-| `hybrid-dag.md` | 使用 Agent DAG Level 2 `dag validate` / `run-dag`，Level 3 `dag init-hybrid` / `dag run-task`，或查看 write policy、DAG source-of-truth 规则 |
+| `hybrid-dag.md` | 使用 Agent DAG Level 2 `dag validate` / `dag execute`，Level 3 `dag init-hybrid` / `task advance`，或查看 write policy、DAG source-of-truth 规则 |
 | `pi-subagent-assisted-mode.md` | 启用 `piSubagentMode`，或在 Pi step 内配置 read-only scout / planner / reviewer subagent |
 | `model-routing.md` | 查看或修改 model/provider 默认、profile、routing 或 fallback 行为 |
 | `post-implementation-and-patterns.md` | 处理 post-verify handoff、PRD item 拆分、fast bounded task、quick status 或 Pi timeout |

package/skills/loop-agent/references/command-reference.md

@@ -33,30 +33,25 @@ loop-agent doctor
 
 选择命令时按以下优先级：
 
-1. **主路径 DAG**，用于常规 autonomous work：
+1. **主路径 lifecycle**，用于常规 autonomous work：
 
    ```bash
-   loop-agent new-task <task-id> "Task Title"
-   # 推荐默认：详细 PRD → import → prepare（无需手写两 source；默认无 LLM 写 source）
-   loop-agent import-prd <task-id> --file <path-to-prd.md>
-   loop-agent task source prepare <task-id> \
-     --use-imported-prd \
-     --allowed-path "<glob>" \
+   # 非微小 / 跨会话（推荐默认）：loop-agent plan create <plan-id> "<title>"
+   loop-agent task advance <task-id> "Task Title" \
+     --prd <path-to-prd.md> \
+     --accept-recommendations <digest>  # optional P1
+  --allowed-path "<glob>" \
      --forbidden-path ".harness/**" \
      --verify "typecheck:npm run typecheck" \
-     --apply --json
-   # 非微小 / 跨会话（推荐默认）：
-   # loop-agent plan create <plan-id> "<title>"
-   loop-agent dag run-task <task-id> --profile auto --strict-models
-   loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
-   loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
+     --json
+   # 审查 gate.writeSet / gate.digest 后：
+   loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+   loop-agent task status <task-id> --json
    # 有 plan 时收尾：loop-agent plan complete <plan-id> --summary "..."
    ```
 
-   省略 `--output` 时默认写入 `.harness/tasks/<task-id>/dag.json`（CLI JSON 的 `outputPath` / `defaultOutputPath` 为解析后的绝对路径）。显式 `--output` 仍可指向 temp 或任意路径（兼容旧脚本）。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
-
-   **`import-prd` / `plan create` 不是 `dag run-task` 的硬依赖**，但有 PRD 文件或非微小实现时应默认使用；决策表、反模式与案例见 `source-and-plan-practice.md`。
-2. **Operator 工具**，用于 recovery、诊断、评测重放与 closeout：
+   首次 `task advance` 内部完成 create、PRD 归档、managed contract 投影、DAG 生成与 strict validate，并停在 writeSet gate；批准后同一命令长跑到稳定终态并做确定性 promotion/closeout。决策表与反模式见 `source-and-plan-practice.md`。
+2. **Operator 工具**，用于 recovery、诊断、评测重放：
 
    ```bash
    loop-agent eval replay --spec <path> --json
@@ -65,17 +60,10 @@ loop-agent doctor
    loop-agent eval candidate show --candidate-id <id> --json
    loop-agent eval candidate list --json
    loop-agent eval candidate transition --candidate-id <id> --to <state> --reason <text> --json
-   loop-agent dag status --run-id <run-id>
-   loop-agent dag doctor --run-id <run-id> --markdown
-   loop-agent dag report --latest --markdown
-   loop-agent dag closeout-draft --run-id <run-id>
-   loop-agent dag reconcile-run --run-id <run-id>
-   loop-agent dag reconcile-tasks --glob '<pattern>' --markdown
-   loop-agent dag final-verification <task-id> --output <temp-dir>/<task-id>-final-verification-dag.json
-   loop-agent status <task-id> --json
-   loop-agent instructions task-artifacts --task <task-id> --json
-   loop-agent promote-run <task-id> --run-id <run-id>
-   loop-agent closeout task <task-id>
+   loop-agent task status <task-id> --json
+   loop-agent task advance <task-id> --json   # 失败后重跑同一 lifecycle 入口
+   loop-agent dag report --latest --markdown  # advanced forensic
+   loop-agent dag closeout-draft --run-id <run-id>  # advanced forensic handoff draft
    loop-agent spine audit <task-id> --markdown
    loop-agent knowledge curate --markdown --output ai_workspace/loop-agent/reports/<task-id>-learned-proposal.md
    loop-agent loop-benchmark --markdown
@@ -130,7 +118,7 @@ SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback
 | 初始化更新校验 / loop agent初始化更新校验 / 检查初始化更新 | `loop-agent init check-update --repo-root . --markdown`（只读，不得隐含 `apply-safe`） |
 | 初始化安全更新 / loop agent初始化安全更新 / 应用初始化更新 | 先 `loop-agent init check-update --repo-root . --markdown`，再 `loop-agent init update --repo-root . --apply-safe`（surface 缺失时先 `--bootstrap-surface`；human decisions 存在时停下等用户） |
 | 初始化对齐 / 升级后对齐 / init reconcile / 控制器升级后对齐目标项目 | `loop-agent init reconcile --repo-root .`（统一入口：surface 缺失返回 `needs-baseline` 零写入；human decisions 返回 `needs-human-decision` 零写入；活跃 DAG/Worker 或 Worker 状态无法确认时返回 `blocked-active-runtime` 零写入；其余执行 safe actions 后复查） |
-| loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 先 `loop-agent new-task <task-id> "任务标题"`，写 `source/需求.md` 与 `source/执行约束.md`，同步 `task.json.allowedPaths` / `forbiddenPaths`，再 `loop-agent dag run-task <task-id> --profile auto --strict-models`、`dag validate`、`run-dag`；主会话编排而不直接写业务实现 |
+| loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 先 `loop-agent task advance <task-id> "任务标题" --prd <prd.md> --allowed-path "<glob>" --json`，审查 writeSet gate 后 `task advance --approve-gate write-set-review:<digest> --json`；主会话编排而不直接写业务实现 |
 
 ```bash
 loop-agent init instructions --repo-root <target-repo>
@@ -159,43 +147,36 @@ loop-agent examples copy <name> --output examples/<name>
 
 `examples` 只读取或复制包内示例，不会自动写入目标项目。省略 `--output` 时，`copy` 会写到目标项目的 `examples/<name>`。
 
-### 创建新 task
-
-```bash
-loop-agent new-task <task-id> "Task Title"
-```
-
-创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。`artifacts/` 默认只预种 `修改记录.md` 与 `验证结果.md`（供后续 `promote-run` / `closeout` 使用）；不再预种 L1 的 `分析报告.md`、`实现计划.md`、`复盘报告.md`。
-
-### 导入原始 PRD（不可变事实源）
+### 创建 / 推进 task（标准入口）
 
 ```bash
-loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [--name requirement] [--json]
+loop-agent task advance <task-id> "Task Title" \
+  --prd path/to-prd.md \
+  --allowed-path "src/**" \
+  --verify "typecheck:npm run typecheck" \
+  --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
 ```
 
-把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后用 `task source prepare --use-imported-prd --apply` 派生 managed `source/需求.md` / `执行约束.md`；冲突时以 `source/references/*` 为准。
+首次 advance 可 create `.harness/tasks/<task-id>/`（含 `source/`、`artifacts/`、`logs/`），归档 PRD 到 `source/references/`，派生 managed `需求.md` / `执行约束.md`，生成并 strict validate DAG，停在 writeSet gate。批准后同一命令长跑并确定性 promotion/closeout。
 
-`referenceDocs` 是 `{ path, name? }[]` 对象数组，不是路径字符串数组；`import-prd` 会确定性写入正确结构。
+PRD 原文 **不改写**；冲突时以 `source/references/*` 为准。`referenceDocs` 是 `{ path, name? }[]` 对象数组。
 
 ### Task Contract / operator machine surface
 
 ```bash
-loop-agent task contract show <task-id> [--json]
-loop-agent task contract validate --task <task-id> --input <path> --json
-loop-agent task contract diff --task <task-id> --input <path> --json
-loop-agent task contract apply --task <task-id> --input <path> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> --json
-loop-agent task contract adopt --task <task-id> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> --json
-loop-agent task contract doctor --task <task-id> --json
-loop-agent task contract recover --task <task-id> --json
+loop-agent task status <task-id> --json
+loop-agent task advance <task-id> --from-draft <path> --json
 loop-agent operator capabilities [--json]
 ```
 
-`task` 是 Task Contract 边界（show/validate/diff/apply/adopt/doctor/recover）。`operator` 返回 Operator machine envelope capabilities，供 Console/控制面做能力协商。
+`task` 标准面是 advance/status；managed contract 经 `task advance`/`task status`；Console Interview validate/diff 走 in-process application API，无公开 CLI。`operator` 返回 Operator machine envelope capabilities，供 Console/控制面做能力协商。
 
 ### Task action context / artifact instructions
 
 ```bash
-loop-agent status <task-id> --json
+loop-agent task status <task-id> --json
 loop-agent instructions source --task <task-id> --json
 loop-agent instructions dag-draft --task <task-id> --json
 loop-agent instructions task-artifacts --task <task-id> --json
@@ -203,34 +184,32 @@ loop-agent instructions promotion --task <task-id> --json
 loop-agent instructions closeout --task <task-id> --json
 ```
 
-`status` 是 agent 行动上下文入口，返回 `artifactPaths`、`runRefs`、`actionContext` 与 `nextActions`。`instructions` 在写入 source、DAG draft、task artifacts、promotion 或 closeout 前返回目标路径、依赖、模板、写策略与完成标准；blocked artifact 会列出 `missingDependencies`。`instructions task-artifacts` 只要求 promote 桥接的 `修改记录.md` / `验证结果.md`，不要求手写分析/计划/复盘三份 L1 报告。
+`task status` 是只读 lifecycle 入口，返回 `lifecycleState`、`gate`、`blockers` 与单一 `next`。`instructions` 在写入 source、DAG draft、task artifacts、promotion 或 closeout 前返回目标路径、依赖、模板、写策略与完成标准；blocked artifact 会列出 `missingDependencies`。`instructions task-artifacts` 只要求 promote 桥接的 `修改记录.md` / `验证结果.md`，不要求手写分析/计划/复盘三份 L1 报告。
 
 ### Promotion / closeout
 
 ```bash
-loop-agent promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
+loop-agent task advance <task-id> --json
 ```
 
-`promote-run` 从 completed DAG facts 或 one-shot completed run evidence 生成 task `修改记录.md` / `验证结果.md`，不调用 LLM、不修改 completed run facts。`closeout task` 从 task artifacts 生成 `ai_workspace/loop-agent/progress/YYYY-MM-DD-<slug>.md`，验证证据不足时必须写明剩余风险。
+成功路径由 `task advance` 内部从 completed DAG facts 生成 task `修改记录.md` / `验证结果.md` 与 progress handoff，不调用 LLM、不修改 completed run facts。
 
 one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`。`cursor-prompt` 与 Pi `cursor` tool 会创建这类 run evidence；当前 `pi-prompt` 不创建 `.harness/runs/`。active 目录只应保留 live one-shot run，残留或 `.DS_Store` 等系统文件应清理。详见 `one-shot-runs.md`。
 
 ### 运行任何 step 前：准备 source materials
 
-`new-task` 之后，先归档原始 PRD，再 `task source prepare` 派生执行契约：
+标准路径用 `task advance` 一次完成 create、归档 PRD、派生 managed contract：
 
 ```bash
-loop-agent import-prd <task-id> --file <path-to-original-prd.md>
-loop-agent task source prepare <task-id> \
-  --use-imported-prd \
+loop-agent task advance <task-id> "标题" \
+  --prd <path-to-original-prd.md> \
   --allowed-path "<glob>" \
   --forbidden-path ".harness/**" \
   --verify "typecheck:npm run typecheck" \
-  --apply --json
+  --json
 ```
 
-默认无 LLM 写 source；工程边界用 flags 显式给出。不要让 AI 直接改写 `source/references/*`。高级用户仍可手工编辑后 `task contract adopt`。
+默认无 LLM 写 source；工程边界用 flags 显式给出。不要让 AI 直接改写 `source/references/*`。高级用户仍可手工编辑后 `task advance --from-draft`。
 
 ### Feature-study workflow（参考代码 → 轻量实现）
 
@@ -243,9 +222,9 @@ loop-agent --repo-root /path/to/target-repo study init <task-id> "Title" \
   --reference-glob "codex-rs/**/goal*.rs"
 
 # 编辑 source/需求.md + source/执行约束.md，然后走 DAG 路径：
-loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output .harness/tasks/<task-id>/dag.json
+loop-agent --repo-root <target-repo> task advance <task-id> --profile auto --dag-output .harness/tasks/<task-id>/dag.json --json
 loop-agent --repo-root <target-repo> dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
-loop-agent --repo-root <target-repo> run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <target-repo>
+loop-agent --repo-root <target-repo> dag execute --dag .harness/tasks/<task-id>/dag.json --cwd <target-repo>
 ```
 
 目标 repo 需有 `.harness/prompts/feature-study-analyze.md` 与 `feature-study-plan.md`（缺失时从 loop-agent 复制）。
@@ -296,23 +275,15 @@ loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --s
 loop-agent dag validate --dag ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
 cp ai_workspace/loop-agent/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
 (npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG；stderr 默认输出节点进度与 30s 心跳，stdout 保持最终 JSON
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --progress-interval-ms 60000 # 调整心跳；--quiet 可禁用
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
-bash scripts/run-dag-safe.sh --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> [--timeout-secs 7200]  # 后台运行 + 轮询，避免外层 bash timeout 杀进程（见 agent-dag-runner.md §Adaptive liveness）
+loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>     # advanced arbitrary DagSpec；stderr 默认输出节点进度与 30s 心跳，stdout 保持最终 JSON
+loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --progress-interval-ms 60000 # 调整心跳；--quiet 可禁用
+loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
+bash scripts/dag execute-safe.sh --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> [--timeout-secs 7200]  # 后台运行 + 轮询，避免外层 bash timeout 杀进程（见 agent-dag-runner.md §Adaptive liveness）
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
-loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
 loop-agent dag workflow-plan <task-id> --profile pr-review --output .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json
 loop-agent dag workflow-validate --workflow .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json --strict-governance
 loop-agent dag workflow-compile --workflow .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json --output .harness/tasks/<task-id>/workflows/compiled/<name>.dag.json --manifest .harness/tasks/<task-id>/workflows/compiled/<name>.compile-manifest.json
 # compiled workflow DAGs stay explicit; they do not implicitly replace task root dag.json
-loop-agent dag run-task <task-id> --profile auto         # 推断 governanceProfile，经 workflowPolicy.dag.profileRouting 路由
-loop-agent dag run-task <task-id> --profile minimal      # 选择 minimal 通用路由；standard 前端任务仍可自动使用前端 DAG
-loop-agent dag run-task <task-id> --profile standard     # 选择 standard 通用路由；standard 前端任务仍可自动使用前端 DAG
-loop-agent dag run-task <task-id> --profile reviewed     # 选择 reviewed 通用路由；standard 前端任务仍可自动使用前端 DAG
-loop-agent dag run-task <task-id> --profile supervised   # 选择 supervised implementation DAG；自动前端分类不会降级它
-loop-agent dag run-task <task-id> --execute --cwd <repo-root>  # generate + validate + execute（先 narrow writeSet）
-loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>  # generate + validate + active dry-run snapshot
 loop-agent dag status --run-id <run-id>                  # 单次 run JSON 摘要（approvalFlow, healthIssues）
 loop-agent dag doctor                                    # 扫描 active/paused/completed runs；advisoryOnly health report
 loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest] [--action <recovery-action>]  # derived per-node 聚合（只读）；JSON 锁定于 ai_workspace/loop-agent/templates/agent-dag-report.schema.json；--paused-latest 聚焦最新 paused run；playbook: ai_workspace/loop-agent/agent-dag-recovery-playbook.md
@@ -343,17 +314,17 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `ai_workspace/loop-agent/agent-dag-recovery-playbook.md`。
 - 只读扫描 `.harness/dag-runs/` 下所有 run 的生命周期 health issue 与建议 action 用 `dag doctor`（`advisoryOnly: true`；不 mutate facts）。
 - `dag status` / `dag doctor` 的 runner heartbeat 只表示 lease；Pi meaningful progress 由 Provider/tool/output 活动决定。节点可显示 `quiet`、`suspected-stall`、`probing` 或 `needs-attention`，不要仅凭运行时长手工结束。
-- Pi 默认 4h absolute max，`agent-worker` 默认不设置外层 `run-dag` wall-clock；显式 `worker.timeout_ms` 仍是 hard timeout。`termination-unconfirmed` 表示旧 attempt 的退出无法确认，禁止自动 retry，先保留现场并完成 operator 对账。
+- Pi 默认 4h absolute max，`agent-worker` 默认不设置外层 `dag execute` wall-clock；显式 `worker.timeout_ms` 仍是 hard timeout。`termination-unconfirmed` 表示旧 attempt 的退出无法确认，禁止自动 retry，先保留现场并完成 operator 对账。
 - approve/resume 前用 `dag status --run-id <id>` 看单次 lifecycle、`approvalFlow`、`hasHumanApproval`。
 - lifecycle、raw status 与 liveness 冲突时先用 `dag reconcile-run --run-id <id>` 只读检查。只有 runner 已证明停止且 operator 明确给出 `supersede|abandon` 与 reason 时才允许收口；它保存原始 state，不把未执行节点标成成功。
 - task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>'`。默认仅报告；`--patch` 显式且不能伪造 verification evidence。
 - 大型 PRD closeout 用 `dag final-verification <task-id>` 生成确定性 DAG，final verification 在 closeout artifact 创建之后。
 - 从 run facts dry-run envelope 解析用 `dag decision inspect|validate`；`validate` 在无效 envelope 时 exit 1；永不自动 resume/retry。
 - Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`ai_workspace/loop-agent/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
-- 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
-- task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选择治理强度时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；`--profile minimal|standard|reviewed|supervised` 记录治理强度，不替换已识别的专用业务 workflow。
+- 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `dag execute --dry-run`。
+- task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选择治理强度时用 `task advance --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；`--profile minimal|standard|reviewed|supervised` 记录治理强度，不替换已识别的专用业务 workflow。
 - 默认 `standard` 任务先读取 `source/需求.md` 中的结构化任务类型，再结合 `allowedPaths` 与 React/Next/Vue 项目能力做确定性分类。确认是前端项目且任务不是明确后端、混合、排除前端或仅文档/测试范围时，自动选择 `frontend-implementation`，不依赖需求关键词；普通后端实现绝不自动进入 `backend-test`。
-- 新生成 DAG 会冻结任务源路径、SHA-256 和显式 `REQ/BR/AC` 到 `sourceBinding`。前端计划漏号时 `frontend-requirement-coverage-shell` 在 writer 前阻断。中断恢复应修复 task source 后重新运行 `dag run-task`，不要生成只携带上游摘要的 impl-only DAG；strict governance 会拒绝无来源绑定且无只读 planner 上游的 v3 孤立 writer。
+- 新生成 DAG 会冻结任务源路径、SHA-256 和显式 `REQ/BR/AC` 到 `sourceBinding`。前端计划漏号时 `frontend-requirement-coverage-shell` 在 writer 前阻断。中断恢复应修复 task source 后重新运行 `task advance`，不要生成只携带上游摘要的 impl-only DAG；strict governance 会拒绝无来源绑定且无只读 planner 上游的 v3 孤立 writer。
 - 显式专用 `taskKind` 保持兼容并优先于任务源分类，也不扩充 governance profile：`frontend-implementation` 可有意覆盖为带 Mock 规范评估、contract gate、design gate 和验证链的前端模板；可选 `frontendMock` 配置 auto/required/disabled、既有服务目录和专项验证命令，required 合同不完整时不会生成 writer。`backend-test` 显式选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试工程模板。
 
 ### Saved Dynamic Workflow operator UX
@@ -367,7 +338,7 @@ loop-agent workflow diff <name> --against /tmp/<task-id>.workflow.json
 loop-agent workflow replay <run-id>
 ```
 
-`workflow` 是 Dynamic Workflow 的 saved/operator surface。它读取 `WorkflowSpec`，编译为 DAG，再进入同一套 `run-dag` runtime；不会新增 executor 能力或绕过 DAG governance。真实写入任务仍应检查 compiled DAG 的 executor、writeSet、shell gates 和 completed facts 边界。
+`workflow` 是 Dynamic Workflow 的 saved/operator surface。它读取 `WorkflowSpec`，编译为 DAG，再进入同一套 `dag execute` runtime；不会新增 executor 能力或绕过 DAG governance。真实写入任务仍应检查 compiled DAG 的 executor、writeSet、shell gates 和 completed facts 边界。
 
 ### Cursor sidecar
 
@@ -420,7 +391,7 @@ Replay spec 最小结构：
 ### 检查 task status
 
 ```bash
-loop-agent status <task-id>
+loop-agent task status <task-id>
 ```
 
 ### Docs governance helpers
@@ -486,7 +457,7 @@ loop-agent loop add-signal <task-id> --type human_followup --message "..."
 loop-agent loop closeout <task-id>
 ```
 
-`loop` 是 Agent DAG 之上的长程状态和 evidence layer，记录 rounds、signals、verification summaries 和 closeout draft。它不是替代 `dag run-task` / `run-dag` 的实现路径；medium/large work 仍需要 DAG evidence 或明确 fallback reason。
+`loop` 是 Agent DAG 之上的长程状态和 evidence layer，记录 rounds、signals、verification summaries 和 closeout draft。它不是替代 `task advance` 的实现路径；advanced 可用 `dag execute`；medium/large work 仍需要 DAG evidence 或明确 fallback reason。
 
 ### Minimal spec spine audit
 
@@ -569,10 +540,10 @@ agent-worker observe snapshot --repo <repo-root>  # 输出 GlobalSnapshot JSON
 语义要点：
 
 - TaskSpec 声明单个任务的业务上下文、`risk_level`、可选 `capabilities`、验收与 verify 边界；`risk_level` 被确定性映射到 task complexity。`capabilities: [interactive-ui]` 不改变风险或治理 profile，只把 implement/repair writer 路由到 HIGH，并注入禁止 helper-only 逃逸的真实 UI 交付契约。AcceptanceSpec / TaskGraphSpec 声明跨任务验收引用与依赖图，ready queue 决定可运行任务并检测未知依赖/环/文件一致性。
-- 业务 type（`backend-feature`/`frontend-feature`/`qa-testcode` 等）是产品线 profile，不能直接传给 `loop-agent dag run-task --profile`；Worker 会映射到 `auto`/`minimal`/`standard`/`reviewed`/`supervised`。
-- materializer 把 TaskSpec 物化为 `.harness/tasks/<task-id>`：`source_docs` 原样进入 `source/references/`，派生 `需求.md` 带权威声明、Source Docs/hash 追溯，以及 `acceptance_refs` 短摘要；随后 Worker 调用 `dag run-task` / `dag validate` / `run-dag` / `dag report`。review 节点须对照 references + 派生契约 + 实现。成功路径走 `promote-run` + `closeout task`；失败路径收集 `dag doctor` / `dag closeout-draft` evidence，只允许写入 `.harness/task-pool/failure-handoffs/**`，不放宽其他 `.harness/**` 写入边界。
+- 业务 type（`backend-feature`/`frontend-feature`/`qa-testcode` 等）是产品线 profile，不能直接传给 `loop-agent task advance --profile`（Worker 映射后传入）；Worker 会映射到 `auto`/`minimal`/`standard`/`reviewed`/`supervised`。
+- materializer 把 TaskSpec 物化为 `.harness/tasks/<task-id>`：`source_docs` 原样进入 `source/references/`，派生 `需求.md` 带权威声明、Source Docs/hash 追溯，以及 `acceptance_refs` 短摘要；随后 Worker 调用 `task advance` / `dag report`（advanced 可 `dag execute`）。review 节点须对照 references + 派生契约 + 实现。成功路径走 `task advance` 自动 promotion/closeout；失败路径收集 `dag doctor` / `dag closeout-draft` evidence，只允许写入 `.harness/task-pool/failure-handoffs/**`，不放宽其他 `.harness/**` 写入边界。
 - Worker runtime state 落在目标 repo 的 `.harness/task-pool/`（artifacts、JSONL/state、晨报、failure handoffs）。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root；旧路径不读取、不迁移、不合并、不重映射。
-- preflight 在 `new-task` 前跑 `loop-agent --version`、`inspect`、`docs-audit`、`git status --short --branch`，可选 `--check-repo`。一次夜间批处理期间不升级控制器，记录实际 `loop-agent` 版本。
+- preflight 在 `task advance` 前跑 `loop-agent --version`、`inspect`、`docs-audit`、`git status --short --branch`，可选 `--check-repo`。一次夜间批处理期间不升级控制器，记录实际 `loop-agent` 版本。
 - `batch run-ready` 默认在 stderr 输出人类可读进度（批次起止、每个 task 的阶段与耗时、report 决策），stdout 只保留最终 JSON，便于管道取用；加 `--quiet` 可关闭进度。
 - `feature scaffold` 确定性生成 Feature Packet（`backend-only` / `frontend-only` / `fe-with-api`），默认 `profile: generic`，输出到 `<repo>/features/<feature-id>`；写盘前同源 `validate-feature`；`--batch` 全有或全无；不调用模型、不碰 `.harness/**`。
 - `feature review` 只读派生 Feature 状态、required AC 覆盖、阻塞、证据和唯一下一步。默认输出简洁的人类摘要，`--json` 输出 schemaVersion 1 JSON；损坏事实会显式降级，不会写 Feature Packet 或 Task Pool。

package/skills/loop-agent/references/harness-policy.md

@@ -16,8 +16,8 @@
 
 | Tier | Default purpose | Commands |
 | --- | --- | --- |
-| Primary | Normal autonomous implementation（经 CLI） | `new-task` -> `dag run-task --profile auto` -> `dag validate --strict-models --strict-governance` -> `run-dag` |
-| Operator | Diagnose, recover, close out, inspect facts | `status`, `instructions`, `dag status`, `dag doctor`, `dag report`, `dag reconcile-run`, `dag closeout-draft`, `dag reconcile-tasks`, `dag final-verification`, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark`；Inspect：`agent-worker console serve`（`/inspect/`）与兼容 `observe serve\|snapshot` |
+| Primary | Normal autonomous implementation（经 CLI） | `task advance`（到 writeSet gate）→ 审查 digest → `task advance --approve-gate`；只读 `task status` |
+| Operator | Diagnose, recover, close out, inspect facts | `task status`, advanced `dag report` / forensic helpers, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark`；Inspect：`agent-worker console serve`（`/inspect/`）与兼容 `observe serve\|snapshot` |
 | Compatibility (CLI helpers) | Legacy task metadata and feature-study helpers | `goal`, `reference`, `study` |
 | Escape hatch | Isolated delegation, one-shot diagnosis or **显式** bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt`（不得作失败默认恢复） |
 | Experimental | Long-running outer task state | `loop init\|status\|run\|record-round\|add-signal\|closeout` |
@@ -30,15 +30,16 @@ Prompt templates、README snippets、task instructions 应优先呈现 Primary +
 
 ```text
 Is this only status, diagnosis, recovery, or closeout?
-  yes -> Operator CLI only (`status` / `dag doctor` / `dag report` / `reconcile` / Observe / human gate).
+  yes -> Operator CLI only (`task status` / advanced `dag report` / Observe / human gate).
+         Prefer re-running the same `task advance` after fixing external blockers.
          Never recover by main-session Edit of business implementation.
   no  -> Does it need recoverable, reviewable, verifiable implementation state?
            no  -> Read-only pi-prompt / inspect only. Do not main-session implement.
-           yes -> Agent DAG via loop-agent CLI (or agent-worker outer loop that spawns loop-agent).
+           yes -> `task advance` lifecycle via loop-agent CLI (or agent-worker that spawns it).
 ```
 
-失败恢复允许集（主会话）：`dag doctor`、`dag report`、`dag reconcile-run`、worker `task reconcile` / `pool mark-failed`（若适用）、记录 human gate、修正 **source/task.json/DAG 包** 后 re-validate/重跑。
-**禁止**：宿主直接改 `src/**` 等业务实现以绕过失败节点。
+失败恢复允许集（主会话）：读 `task status`、处理 gate/blocker、worker `task reconcile` / `pool mark-failed`（若适用）、修正 **PRD/边界/外部凭据** 后重跑同一 `task advance`。
+**禁止**：宿主直接改 `src/**` 等业务实现以绕过失败节点；禁止主会话拼 `prepare/run-task/dag execute/promote/closeout` 命令串。
 
 在以下任一 signal 适用时用 Agent DAG 而非 broad one-shot execution：
 
@@ -53,25 +54,20 @@ Is this only status, diagnosis, recovery, or closeout?
 Minimum governed path：
 
 ```bash
-loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
-# PRD-first: import-prd → task source prepare --apply
-loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--repo-root <target-repo>]
-loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json [--repo-root <target-repo>]
-
-loop-agent dag run-task <task-id> \
-  --profile auto \
-  --strict-models \
-  --output .harness/tasks/<task-id>/dag.json \
+loop-agent task advance <task-id> "Task Title" \
+  --prd <path-to-original-prd.md> \
+  --allowed-path "<glob>" \
+  --verify "typecheck:npm run typecheck" \
+  --json \
   [--repo-root <target-repo>]
 
-loop-agent dag validate \
-  --dag .harness/tasks/<task-id>/dag.json \
-  --strict-models \
-  --strict-governance
+# Review gate.writeSet + gate.digest, then:
+loop-agent task advance <task-id> \
+  --approve-gate "write-set-review:<digest>" \
+  --json \
+  [--repo-root <target-repo>]
 
-loop-agent run-dag \
-  --dag .harness/tasks/<task-id>/dag.json \
-  --cwd <target-repo>
+loop-agent task status <task-id> --json [--repo-root <target-repo>]
 ```
 
 `loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
@@ -82,7 +78,7 @@ For arbitrary target repositories, DAG skill instructions must not depend on loo
 
 Default DAG draft: `.harness/tasks/<task-id>/dag.json`. Explicit `--output` to temp remains an escape hatch.
 
-Execution 前 review `dag run-task` JSON / `reviewPacket`：
+Execution 前 review `task advance` JSON / `reviewPacket`：
 
 - `profileRouting`：requested profile、selected profile/template、routing reasons。
 - `governanceProfile`：process、delivery、code-change signals。