@tea-agent/loop-agent 0.26.5-beta.1 → 0.27.0

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。

package/skills/loop-agent/references/hybrid-dag.md

@@ -1,4 +1,4 @@
-# Agent DAG Hybrid Workflow（`run-dag` / `dag init-hybrid`）
+# Agent DAG Hybrid Workflow（`task advance` / advanced `dag execute`）
 
 创建或执行 loop-agent 工作的首选 Agent DAG path 时使用本文：Level 2 Agent DAG orchestration、Pi read-only + Pi `toolProfile: "write"` bounded execution、Pi-only writers、write policy、DAG template、task-to-DAG 生成，或基于 governance-profile 的 template 选择。
 
@@ -7,12 +7,12 @@
 `harness.json.workflowPolicy` 现声明 Agent DAG 为首选 implementation workflow：
 
 - `defaultImplementationWorkflow=agent-dag`
-- `dag.defaultEntry=dag run-task`
+- `dag.defaultEntry=task advance`
 - `dag.outputLanguage=zh-CN`；未配置时也默认中文，显式设为 `en` 可切换英文
 - `dag.profileRouting`：通用候选映射为 `minimal|standard -> standard-dag`、`reviewed -> review-gated-dag`、`supervised -> supervised-implementation`
 - `humanGatePolicy.defaultMode=record-only`；需求不清、架构/公共契约风险、凭据/费用/部署风险、重复 gate failure 或高风险决策时升级人工介入
 
-此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
+此 policy 驱动标准路径 `task advance --profile auto`：operator 只记 `task advance` / `task status`；advanced arbitrary DagSpec 才用 `dag validate` / `dag execute`。`--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。
 
 对于默认 `standard` 任务，生成器先读取 `source/需求.md` 中的结构化任务类型，再结合 `allowedPaths` 与 React/Next/Vue 强工程证据做确定性分类。确认是前端项目且任务不是明确后端、前后端混合、排除前端或仅文档/测试范围时，默认选择 `frontend-implementation` DAG，不依赖需求关键词。分类不会把普通后端实现路由到 `backend-test`；显式 profile、`workflowPolicy` 或 supervised quality gate 只记录治理强度，不把已识别的前端业务 workflow 换回通用模板。
 
@@ -26,21 +26,21 @@
 
 | 优先级 | 入口 | 使用场景 |
 |-------|-------|----------|
-| **Primary / Level 3** | `dag run-task --profile auto` / `dag init-hybrid`（已实现） | 从 task `source/` 自动生成 hybrid DAG；`--profile auto` 路由 standard / review-gated / supervised template；无 profile `run-task` 默认为 standard-compatible generate+validate only |
-| **Primary / Level 2** | `run-dag --dag <path>` | 跨 Pi + shell + static executor 执行 Agent DAG orchestration |
-历史顺序式 `run analyze|plan|implement|verify|auto|loop|continue` 已移除。主会话是 Operator Assist：业务实现走 Agent DAG CLI。极窄的文档/DAG JSON/task-source 元数据修正不是第二套 workflow runtime，也**不得**在 CLI 失败后变成「主会话直接改实现」。
+| **Primary / Level 3** | `task advance --profile auto` | 从 PRD/managed source 生成 hybrid DAG、strict validate、writeSet gate，批准后长跑 |
+| **Advanced / Level 2** | `dag execute --dag <path>` | 跨 Pi + shell + static executor 执行 arbitrary Agent DAG orchestration |
+历史顺序式 `run analyze|plan|implement|verify|auto|loop|continue` 已移除。主会话是 Operator Assist：业务实现走 `task advance`。极窄的文档/DAG JSON/task-source 元数据修正不是第二套 workflow runtime，也**不得**在 CLI 失败后变成「主会话直接改实现」。
 
-**心智模型**：`run-dag` 是 loop-agent 内自编的 Agent DAG orchestration；受治理 Agent leaf executor 只有 Pi。`cursor-prompt` 是独立 sidecar，不是 DAG node executor。不要把 Cursor 重新引入 hybrid schema / `executorModels` / writer 选择。
+**心智模型**：`task advance` 是标准 task lifecycle；`dag execute` 是 loop-agent 内 advanced Agent DAG orchestration；受治理 Agent leaf executor 只有 Pi。`cursor-prompt` 是独立 sidecar，不是 DAG node executor。不要把 Cursor 重新引入 hybrid schema / `executorModels` / writer 选择。
 
-### Level 2 Agent DAG hybrid（`run-dag`）
+### Level 2 advanced Agent DAG hybrid（`dag execute`）
 
 ```bash
 cp examples/hybrid-loop-agent-dag.json <temp-dir>/hybrid-dag.json
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation + ranks；无 dag-runs 副作用
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时也失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning（如 read-only artifact drift）时失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Pi/shell/static DAG
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas
+loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Pi/shell/static DAG
+loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas
 ```
 
 `<temp-dir>` 表示平台原生临时目录；实际命令中 macOS 与 Windows 都使用本机路径。`/` 只作为 repo refs、JSON/Markdown evidence refs 和 glob 约定的稳定分隔符。
@@ -65,10 +65,10 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 
 **运维 warning**：
 
-- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
-- **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 与自动 promotion 记录治理强度，已识别的前端业务 workflow 仍使用前端专用模板。高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
+- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `dag execute --dry-run`。
+- **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`task advance` 转发 embedded validate step 的同一 candidate `governanceProfile`。`task advance --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `task advance <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 与自动 promotion 记录治理强度，已识别的前端业务 workflow 仍使用前端专用模板。高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
 - **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖模型。值写成 `provider/model` 时显式选择 Pi provider（只分割第一个 `/`）；裸模型名继续走内置映射或默认 `wizard-local`。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`gpt-5.5`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
-- **Active visibility**：真实 `run-dag` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
+- **Active visibility**：真实 `dag execute` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
 - **可选 Canvas**：传 `--canvas-path <abs-path>` 或 `--canvas <name>` 输出 derived `.canvas.tsx` live view。省略 flag 行为不变。`--init-only` + Canvas 无需 `CURSOR_API_KEY`。
 
 - **Shell node**：`executor: "shell"` 串行跑确定性 `shell.commands`，每 command 有 `timeoutMs`；非零 exit / timeout 标 node `ERROR` 并将 command output 归档到 node result 目录。用于 verification fact，非 code repair。
@@ -77,12 +77,12 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **Upstream output artifacts**：直接 `depends_on` 上游 stdout 超过 2000 字符时，runner 写 `<runDir>/<node-id>/stdout.md` 并在下游 `<upstream_context>` 提供 preview + artifact pointer map（绝对路径、`chars`、`sha256`）。下游 agent 可读 runner evidence，但 read-only node 仍不得编辑 `.harness/dag-runs/**`。
 - **`writePolicy=exclusive`** 要求非空 `writeSet`；same-rank exclusive node 的 `writeSet` 条目须 **disjoint**，否则 validation fail fast。v1 DAG 中声明 `writePolicy` 或 `writeSet` 任一即 opt-in write validation。
 - **`forbiddenPaths` 优先于 `allowedPaths`**（writeSet validation）。
-- **Pi rollback**：SDK path 损坏时在 `run-dag` 前 `export CODE_AGENT_PI_BACKEND=cli-only`。
+- **Pi rollback**：SDK path 损坏时在 `dag execute` 前 `export CODE_AGENT_PI_BACKEND=cli-only`。
 - **Defaults  caveat**：`defaults.skills` / `defaults.writePolicy` 生效。对 `cursor` / `pi` node，resolved skill 名亦由 DAG runner 映射为有界 inline `SKILL.md` instruction，审计于 `<node>/skills.json`；Pi 仍以 `noSkills` / `--no-skills` 运行，故非 Pi ResourceLoader loading。`defaults.executor`、`defaults.model`、`defaults.piBackend`、`defaults.contextProfile` 接受/保留但尚非 runtime default。runtime execution 用 node `executor` + node `complexity`；各 executor 内部自选 model。live contract 已移除 `models`；executor-specific routing 用 `executorModels`。
 - **默认无**跨 node Pi runtime reuse；各 Pi node 是独立 `executePiStep()` call。
 - **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
 - **Source binding / recovery**：新生成 DAG 在顶层冻结 `sourceBinding`（任务源相对路径、SHA-256、显式 `REQ/BR/AC`）。前端计划在存在显式编号时经过 `frontend-requirement-coverage-shell`；修订计划为 primary，只在条件分支未产生输出时 fallback 到原计划。主来源存在但缺号时仍在 writer 前 fail closed。中断后重新生成完整 DAG，不要从二手摘要拼接 impl-only DAG；v3 孤立 exclusive writer 若无 `sourceBinding` 且没有只读 planner 上游，会被 strict governance 拒绝。
-- **勿宣称 live smoke 已通过**，除非真实 `run-dag` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
+- **勿宣称 live smoke 已通过**，除非真实 `dag execute` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
 
 可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/frontend-test-dag.json`（FE-test RAG：Markdown case manifest、串行 Playwright CLI case 子节点与逐 case 证据）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
 
@@ -129,29 +129,28 @@ Prompt invariant：`ai_workspace/loop-agent/templates/agent-dag-process-supervis
 
 **未实现**：`executor: supervisor`、whole-run automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。注：有界只读 Pi 节点重试已实现（见下「只读 Pi 节点安全重试」）。
 
-### Level 3 task-to-DAG（`dag init-hybrid` / `dag run-task`）
+### Level 3 task lifecycle（`task advance` / advanced `dag init-hybrid`）
 
 ```bash
+loop-agent task advance <task-id> "Title" \
+  --prd <prd.md> \
+  --allowed-path "<glob>" \
+  --profile auto \
+  --json
+# 审查 writeSet gate digest 后批准并长跑（自动 generate/validate/execute/promote/closeout）
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
+# advanced authoring only:
 loop-agent dag init-hybrid <task-id> [--output .harness/tasks/<task-id>/dag.json]
-loop-agent dag run-task <task-id> [--output .harness/tasks/<task-id>/dag.json]   # 安全默认：仅 generate + validate，standard-compatible
-loop-agent dag run-task <task-id> --profile auto                                # 推断 candidate governanceProfile，再经 workflowPolicy 路由
-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 DAG；自动前端分类不会降级它
-loop-agent dag run-task <task-id> --strict-models                              # 非 canonical executorModels 时失败
-loop-agent dag run-task <task-id> --execute --cwd <repo-root>                        # 要求 narrowed implement writeSet
-loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>                        # active snapshot 于 .harness/dag-runs/active/
-loop-agent dag run-task <task-id> --init-only --cwd <repo-root>                      # pending active snapshot，不执行 node
 ```
 
-默认 `dag run-task` **不**创建 `.harness/dag-runs/**`。placeholder / `**` implement writeSet 会 block `--execute`、`--init-only`、`--dry-run`，直到人工 review narrow path。
+默认首次 `task advance` **不**启动 writer，只推进到 writeSet gate。placeholder / `**` implement writeSet 会在 strict validate / gate 前 fail-closed，直到人工收窄 path。
 
-`dag run-task` JSON 输出含确定性 `reviewPacket` 供执行前 review。derived 自 generated DAG JSON、embedded validate summary、`profileRouting`；不调用 LLM，不写 completed run facts。`run-dag` 前用它 inspect `profileRouting`、`governanceProfile`、exclusive writer `writeSet`、`broadWriteSetRisk`、`forbiddenOverlapRisk`、`shellGates`（含 `lineMode`）、`shellVerification` / `expectedVerification`、`decisionGates` mode。
+`task advance` JSON 含 `gate` / `next` / lifecycle 事实供执行前 review；advanced `dag validate` 可读 generated DAG JSON 的 `profileRouting`、`governanceProfile`、exclusive writer `writeSet`、`shellGates` 等。
 
 ### DAG 与 artifacts source-of-truth 规则
 
-- Canonical task DAG draft: `.harness/tasks/<task-id>/dag.json` (`dag run-task` / `init-hybrid` default).
+- Canonical task DAG draft: `.harness/tasks/<task-id>/dag.json` (`task advance` / advanced `init-hybrid` default).
 - Worker per-run snapshot: `artifacts/<workerRunId>-dag.json`; compiled workflows stay under `workflows/compiled/` and need explicit `--dag`.
 - Platform temp is only an explicit `--output` escape hatch. Reusable templates live in `examples/` or `ai_workspace/loop-agent/templates/`.
 - **不要**在 `.harness/dag-runs/active/` root 保留手写 DAG input 副本。
@@ -160,7 +159,7 @@ loop-agent dag run-task <task-id> --init-only --cwd <repo-root>
 - root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy current-work / explicit-write 摘要。不是 per-run 不可变历史，也不是新工作流默认交付路径。
 - Agent DAG read-only node 不得写 root `artifacts/`；若须更新 root artifacts，用显式 `exclusive` write node（经 CLI），不要用主会话直接写实现或 root artifacts 代替节点。
 - DAG Cursor 节点交付物必须写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；`./artifacts/**` 是错误落点。
-- 长期结论须迁入 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/` 或 `ai_workspace/loop-agent/progress/`。从 completed run evidence 汇总 task artifacts 时用 `promote-run <task-id> --run-id <run-id>`；再用 `closeout task <task-id>` 生成 progress。二者 deterministic，且不 mutate completed run facts。
+- 长期结论须迁入 `ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/reports/` 或 `ai_workspace/loop-agent/progress/`。成功路径由 `task advance` 自动 promotion/closeout；二者 deterministic，且不 mutate completed run facts。
 
 **DAG author 的 artifact-boundary 提醒**：大量 *讨论* root `artifacts/**` 的 task 仍遵守同一 write guard — read-only node 仅在 node output 返回发现；exclusive node 保持 `artifacts/**` 在 `forbiddenPaths`，除非 concrete path 在 `writeSet`。不要在 declared writeSet 外 instruct implementer 写 `artifacts/修改记录.md` 或 `artifacts/验证结果.md`（P3 boundary-risk practice）。scout 在链接 skill reference 中发现 stale wording 时，把那些 path 纳入 implementer writeSet 并在 DAG 内写入（P2 教训：`hybrid-dag.md` 被 scout 发现但 initial writeSet 遗漏）；不要依赖 post-DAG 主会话大段补写。
 
@@ -180,8 +179,7 @@ loop-agent dag status --run-id <run-id>
 loop-agent dag report --paused-latest [--json|--markdown]   # 最新 paused run；勿与 --lifecycle 并用
 loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--action <recovery-action>]  # derived per-node report（只读）；JSON schema: ai_workspace/loop-agent/templates/agent-dag-report.schema.json；仅 advisory — 见 ai_workspace/loop-agent/agent-dag-recovery-playbook.md
 loop-agent dag closeout-draft [--run-id <run-id>] [--output <path>]  # M5：从 completed run facts 生成确定性 closeout draft；默认平台临时目录；仅 advisory；不 mutate completed facts
-loop-agent promote-run <task-id> --run-id <run-id>                    # 从 completed DAG/one-shot evidence 汇总 task artifacts；不 mutate completed facts
-loop-agent closeout task <task-id>                                    # 从 task artifacts 生成 ai_workspace/loop-agent/progress closeout
+loop-agent task advance <task-id> --json                              # 成功路径自动 promotion/closeout；不 mutate completed facts
 loop-agent dag reconcile-tasks --glob '<pattern>' [--json|--markdown]  # 仅报告的 task/run/artifact/verify drift audit
 loop-agent dag final-verification <task-id> [--output <path>]  # 生成 closeout DAG；final verify 依赖 closeout artifact
 loop-agent dag decision inspect --run-id <run-id> [--node-id <node-id>]
@@ -191,7 +189,7 @@ loop-agent dag reject --run-id <run-id> --reason "..."
 loop-agent dag resume --run-id <run-id>   # approve 后继续
 ```
 
-**Paused operator flow**：`run-dag` → `paused/` →（`dag status` / 可选 `dag decision validate`）→ `dag approve` → `active/` → `dag resume` → `completed/`；或 `dag reject` → `completed/`（`failed`，`failureCategory=human-rejected`）。
+**Paused operator flow**：`dag execute` → `paused/` →（`dag status` / 可选 `dag decision validate`）→ `dag approve` → `active/` → `dag resume` → `completed/`；或 `dag reject` → `completed/`（`failed`，`failureCategory=human-rejected`）。
 
 **Stale active detection**：`dag doctor` 标 health code 如 `terminal-in-active`（`active/` 保留 terminal run）；仅 advisory — 按 playbook 手动 archive/remove，尚无 auto cleanup CLI。
 

package/skills/loop-agent/references/long-running-loop.md

@@ -36,8 +36,8 @@ loop-agent loop record-round <task-id> \
 - `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
 - `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
 - 自动写入只能通过 `loop run --action dag --execute` / auto DAG execute；须读取 task `allowedPaths` / `forbiddenPaths` 并审查 writer writeSet。
-- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
-- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
+- `loop run --action dag` 默认是 review mode：调用 `task advance <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
+- `loop run --action dag --execute` 才会调用 `dag execute`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
 
 ## Auto mode 与写入边界
 

package/skills/loop-agent/references/one-shot-runs.md

@@ -1,6 +1,6 @@
 # One-shot Run Evidence（`.harness/runs/`）
 
-当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
+当你使用 `cursor-prompt`、Pi `cursor` tool、`task advance (promotion)`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
 
 ## 目录职责
 
@@ -50,11 +50,10 @@ artifacts/
 completed one-shot evidence 若要进入 task artifacts，使用：
 
 ```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` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
+`task advance (promotion)` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
 
 ## Active 目录清理
 
@@ -82,4 +81,4 @@ HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
 - 不要提交 `.harness/runs/**` 运行态内容。
 - 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
 - 不要把 `.harness/runs/active/**` 当作长期记录。
-- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。
+- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `task advance (promotion)`。