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

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 换回通用模板。
 
@@ -20,27 +20,27 @@
 
 > Backend-test Markdown-first：先由确定性环境 Shell 检查 clean env 中 Python/pytest、常见配置、conftest/fixture、test root、server entry 和 HTML renderer，失败时不消耗模型调用。随后 Pi 生成中文 README 索引与模块用例卡片并独立 Review `testcase/md/**`。第 4 节点只把前置条件、操作步骤、预期结果作为必选章节，并检查 Case ID、业务 AC、步骤/预期和占位措辞；不校验需求来源引用有效性或 Markdown sensitive-shaped 内容。pytest writer 为每次真实接口调用记录脱敏、有界的请求 method/URL/参数摘要和响应 status/body 摘要。第 6 节点只扫描每条 Case 明确映射的 pytest 脚本，同时支持模块级函数和 pytest class 方法，并把缺少请求/响应日志、递归脱敏或有界截断证据记录为 advisory。第 4/6 节点均写 PASS/FAIL findings 而不阻断后续；pytest 仍只运行一次，生成 JUnit，并把 Markdown 名称/场景/脚本映射与同一 JUnit 合成为按测试概览、质量校验、失败概览、用例执行明细和技术证据组织的中文 self-contained HTML 与 Markdown facts。最终 Pi 按固定简洁结构汇总 advisory 状态、执行事实和 L-5 结论。active 流程不要求模型生成 backend-test 业务 JSON。
 
-显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **12 个真实顶层节点**的 Markdown-first DAG：环境硬门、Markdown cases、独立 Review/修订、第 4 节点 advisory Markdown 校验、pytest 转换、initial collection assessment、仅 `REPAIRABLE` 时最多一次 generated-test repair、hash-bound effective collection、scoped traceability、facts-only manifest、单次业务 pytest + pytest-html/HTML/facts、最终 Markdown 报告与 L-5。绿色路径 collection 一次，repair 路径两次，但测试体始终只执行一次；依赖/plugin/生产模块/环境/安全/未知 collection error 不得 repair，assertion/API failure不触发 repair 或 rerun。历史 JSON contract/materializer 可继续读取旧 DAG，但新 runtime/template 不再生成模型业务 JSON。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。
+显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **12 个真实顶层节点**的 Markdown-first DAG：环境硬门、Markdown cases、独立 Review/修订、第 4 节点 advisory Markdown 校验、pytest 转换、initial collection assessment、仅 `REPAIRABLE` 时最多一次 generated-test repair、hash-bound effective collection、scoped traceability、facts-only manifest、单次业务 pytest + pytest-html/HTML/facts、最终 Markdown 报告与 L-5。initial assessment 先解析 expected/existing/missing mapped scripts；writer 漏生成的安全唯一 mapped `test_*.py` 不启动 pytest而直接形成 `missing-mapped-pytest-script` REPAIRABLE facts，repair 只能创建该精确路径；映射齐全时才执行 initial collection。绿色路径 collection 一次，repair 路径在修复后执行一次 final collection，测试体始终只执行一次；依赖/plugin/生产模块/环境/安全/未知 collection error 不得 repair，assertion/API failure不触发 repair 或 rerun。历史 JSON contract/materializer 可继续读取旧 DAG，但新 runtime/template 不再生成模型业务 JSON。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。
 
 ### DAG workflow 层级
 
 | 优先级 | 入口 | 使用场景 |
 |-------|-------|----------|
-| **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)`。

package/skills/loop-agent/references/orchestrator-and-interventions.md

@@ -25,7 +25,7 @@ main session 是 decision-maker 与 scheduler，**不是** implementer。稀缺
 
 ## 入口选择
 
-**Agent DAG**（`dag run-task` → review/writeSet → `run-dag`）为默认，用于 autonomous implementation、workflow/harness/docs governance 变更、multi-file work，或任何受益于多 executor、parallel scout、显式 write policy、shell evidence、review gate、Decision Gate 的工作。
+**Agent DAG**（`task advance` → review/writeSet → `dag execute`）为默认，用于 autonomous implementation、workflow/harness/docs governance 变更、multi-file work，或任何受益于多 executor、parallel scout、显式 write policy、shell evidence、review gate、Decision Gate 的工作。
 
 **supervised Agent DAG** 用于 `governanceProfile=supervised`，或工作触及 loop-agent runtime、scripts/CI、schema/public contract、多个 exclusive writer、repair flow 或 high-cost path。
 
@@ -129,7 +129,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 
 好例子：
 
-- 修 DAG JSON path / schema typo 后 `dag validate` + `run-dag`。
+- 修 DAG JSON path / schema typo 后 `dag validate` + `dag execute`。
 - 修正 doc index link 或 typo。
 - 删除明显 out-of-scope 的生成 scratch。
 - 补全 `source/执行约束.md` 中的 allowedPaths 列表后 regenerate DAG。
@@ -149,7 +149,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 1. dag doctor / dag report / status
 2. 分类失败；需要时 reconcile-run 或 human gate
 3. 仅当 source/DAG 包错误时最小修正元数据
-4. dag validate → run-dag / worker 重试
+4. dag validate → dag execute / worker 重试
 5. shell verification
 6. 记录 evidence；禁止主会话实现收尾
 ```

package/skills/loop-agent/references/post-implementation-and-patterns.md

@@ -27,12 +27,12 @@ DAG run、promotion、closeout 和最终验证完成后：
 
 ```
 1. new-task <id>
-2. 有 PRD 文件：import-prd → task source prepare --use-imported-prd --apply（默认不手写两 source）
+2. 有 PRD 文件：task advance --prd + 工程边界 flags（默认不手写两 source）
 3. 非微小：plan create（或挂到已有 active plan）
-4. dag run-task <id> --profile auto --strict-models
+4. task advance <id> --profile auto --strict-models
 5. dag validate --dag .harness/tasks/<id>/dag.json --strict-models --strict-governance
-6. run-dag --dag .harness/tasks/<id>/dag.json --cwd <repo-root>
-7. promote-run / closeout / final verification
+6. dag execute --dag .harness/tasks/<id>/dag.json --cwd <repo-root>
+7. task advance (promotion) / closeout / final verification
 8. 有 plan：plan complete
 ```
 

package/skills/loop-agent/references/source-and-plan-practice.md

@@ -1,27 +1,27 @@
 # Source 与 Exec-plan 最佳实践
 
-很多用户只跑「主路径 DAG」四步，**漏掉** `import-prd` 与 `plan create`。二者**不是** `dag run-task` 的硬依赖，但在「有原始 PRD / 非微小实现」场景下应成为默认纪律。本文给出**何时用、何时可跳、命令顺序与案例**。
+很多用户只跑最短 runtime 命令，**漏掉** PRD 归档纪律与 `plan create`。二者**不是** `task advance` 的硬依赖，但在「有原始 PRD / 非微小实现」场景下应成为默认纪律。本文给出**何时用、何时可跳、命令顺序与案例**。
 
-相关命令细节：`command-reference.md`（import-prd / plan / status）。  
+相关命令细节：`command-reference.md`（task advance / plan / status）。
 Task 目录布局：`task-workflow.md`。  
 仓库治理全文：目标仓 `governanceRoot` 下 `feature-workflow.md`（若有）。
 
 ## 先分清三层
 
-| 层 | 命令 / 路径 | 作用 | 主路径 DAG 是否强制 |
+| 层 | 命令 / 路径 | 作用 | 主路径是否强制 |
 | --- | --- | --- | --- |
-| Source 事实 | `import-prd` → `source/references/*` + `source-manifest.json` | 原始 PRD **不可变**归档 | 否（有 PRD 文件时**强烈推荐**） |
-| Source 契约 | `task source prepare --apply` 投影 `source/需求.md`、`执行约束.md` + managed paths | DAG 生成与验收真源 | **是**（至少 `需求.md`；默认不手写） |
+| Source 事实 | `task advance --prd` → `source/references/*` + `source-manifest.json` | 原始 PRD **不可变**归档 | 否（有 PRD 文件时**强烈推荐**） |
+| Source 契约 | `task advance` 投影 `source/需求.md`、`执行约束.md` + managed paths | DAG 生成与验收真源 | **是**（至少 `需求.md`；默认不手写） |
 | Exec-plan | `plan create` / `plan complete` / `plan check` | 仓库级计划索引与交接 | 否（**非微小**推荐） |
-| DAG 运行时 | `dag run-task` → `dag validate` → `run-dag` | 可执行编排 | **是**（常规实现） |
+| Task lifecycle | `task advance` → writeSet gate → `--approve-gate` → `task status` | 可执行编排与证据 | **是**（常规实现） |
 
 规则记忆：
 
-1. **`new-task` 不自动 import-prd，也不自动绑 plan。**
-2. **`dag run-task` 主要消费派生 `需求.md`**；会校验 plan **索引一致性**，但不要求当前 task 已有 active plan。
+1. **`task advance` 在有 `--prd` 时会归档 PRD，但不自动绑 plan。**
+2. **`task advance` 主要消费派生 `需求.md`**；会校验 plan **索引一致性**，但不要求当前 task 已有 active plan。
 3. 冲突时：**`source/references/*`（原始）> 派生 `需求.md` > 聊天口述。**
 
-## 决策：何时 `import-prd`
+## 决策：何时使用 `--prd`（原 import-prd 纪律）
 
 ### 应该用（默认「有就 import」）
 
@@ -30,11 +30,11 @@ Task 目录布局：`task-workflow.md`。
 - Worker / 多人协作：后续 review 必须三方对照 references + 需求.md + 实现。
 - 目标仓 `ai_workspace/loop-agent/` 或 `docs/` 里已有权威 PRD/spec，任务只是执行切片。
 
-### 可以跳过 import-prd
+### 可以跳过 PRD 归档
 
 - 真正微小：单文件 typo、一行配置、纯脚本命令说明，**没有**独立需求文档。
-- 用户只在聊天里给了 3～5 条验收点，且你当场写入 `需求.md` 并标明「来源：会话 YYYY-MM-DD」（仍建议短小、可验证）。
-- 已有 task 的 `source/references/` 与 manifest 完好，本次只是 re-run DAG。
+- 用户只在聊天里给了 3～5 条验收点，可用 `--from-text` 并标明「来源：会话 YYYY-MM-DD」。
+- 已有 task 的 `source/references/` 与 manifest 完好，本次只是 re-run lifecycle。
 
 ### 反模式
 
@@ -45,19 +45,17 @@ Task 目录布局：`task-workflow.md`。
 ### 推荐顺序（有 PRD 时）
 
 ```bash
-loop-agent new-task <task-id> "简短标题"
-loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--json]
-loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
+loop-agent task advance <task-id> "简短标题" \
+  --prd <path-to-original-prd.md> \
+  --allowed-path "<glob>" \
+  --json
 # 默认无 LLM 写 source；工程边界用 flags 显式给出
-#   .harness/tasks/<task-id>/source/需求.md
-#   .harness/tasks/<task-id>/source/执行约束.md
-# 同步 task.json.allowedPaths / forbiddenPaths
-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>
+# 内部投影：source/需求.md、source/执行约束.md、task.json paths/verify
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
 ```
 
-`import-prd` 后用 `status` / `instructions source` 确认 source readiness，再生成 DAG。
+首次 advance 后用 `task status` 确认 lifecycle / gate；不要再拼已删除的 import-prd / prepare / run-task 命令串。
 
 ## 决策：何时 `plan create`
 
@@ -86,21 +84,17 @@ loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
 ```bash
 loop-agent plan create <plan-id> "<title>"
 # 在 plan 中写清范围、非目标、验证、允许路径（人类/agent 共读）
-loop-agent new-task <task-id> "切片标题"
-loop-agent import-prd <task-id> --file <prd>
-# 写 需求.md / 执行约束.md / task.json 边界
-loop-agent dag run-task <task-id> --profile auto --strict-models
-# … validate → run-dag → promote-run → closeout …
+loop-agent task advance <task-id> "切片标题" --prd <prd> --allowed-path "<glob>" --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
 loop-agent plan complete <plan-id> --summary "结果导向摘要 + 验证证据"
 ```
 
 微小 escape hatch（须在 handoff / plan 或 task 备注写明边界）：
 
 ```bash
-loop-agent new-task <task-id> "微小修复"
-# 直接 需求.md（可选 import-prd）
-loop-agent dag run-task <task-id> --profile auto --strict-models
-# …
+loop-agent task advance <task-id> "微小修复" --from-text "..." --allowed-path "<glob>" --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
 ```
 
 ## 实践案例
@@ -108,55 +102,55 @@ loop-agent dag run-task <task-id> --profile auto --strict-models
 ### 案例 A — 用户丢来一份 PRD 文件（默认完整路径）
 
 **信号**：`帮我按这个 PRD 实现…` + 附件/路径。  
-**做法**：非微小则先 `plan create`（或复用 active plan）→ `new-task` → **`import-prd`** → 派生 `需求.md`（目标/非目标/AC，锚回 references）→ 路径边界 → DAG。  
+**做法**：非微小则先 `plan create`（或复用 active plan）→ **`task advance --prd`** → 审查 writeSet gate → `--approve-gate`。
 **验收**：`source/references/` 有原文；manifest hash 在；review 能三方对照。
 
-### 案例 B — 聊天里三句话小需求（可跳过 import + plan）
+### 案例 B — 聊天里三句话小需求（可跳过 PRD + plan）
 
 **信号**：`把 X 按钮文案改成 Y`，单文件。  
-**做法**：`new-task` → 短 `需求.md`（写清唯一验收）→ `dag run-task`…  
-**不要**：为了「流程完整」空跑 `import-prd`（无文件）或堆一个空洞 plan。
+**做法**：`task advance --from-text` → approve gate…
+**不要**：为了「流程完整」空跑不存在的 PRD 文件步骤或堆一个空洞 plan。
 
 ### 案例 C — 源仓改 CLI 默认行为（必须 plan，PRD 视情况）
 
 **信号**：行为变更、CHANGELOG、skills/init 多表面。  
-**做法**：**`plan create`** 先冻结契约与工作块 → 按块 `new-task` → 有设计文档则 import → DAG → 定向验证 → `plan complete`。  
-**验收**：active/completed 索引与 plan 正文一致；`plan check` / `dag run-task` 索引 preflight 不红。
+**做法**：**`plan create`** 先冻结契约与工作块 → 按块 `task advance` → 定向验证 → `plan complete`。
+**验收**：active/completed 索引与 plan 正文一致；`plan check` / `task advance` 索引 preflight 不红。
 
 ### 案例 D — agent-worker / Feature 已 materialize source_docs
 
 **信号**：TaskSpec 已把 `source_docs` 拷进 `source/references/`。  
-**做法**：通常 **不必再 import-prd** 同一文件；检查 references + 派生 `需求.md` 顶部「冲突以 references 为准」→ 补边界 → DAG。  
+**做法**：通常 **不必再 import 同一文件**；检查 references + 派生 `需求.md` 顶部「冲突以 references 为准」→ 补边界 → `task advance`。
 **仍建议**：产品线级大功能在 Feature / 仓库层有 plan 或 Feature Packet 记录。
 
 ### 案例 E — 用户说「loop-agent 帮我完成 XXX」无附件
 
 **信号**：强路由进 DAG，但无 PRD 路径。  
-**做法**：主会话 **先问清**是否有 PRD 文件；有则 import；无则把会话共识写入 `需求.md` 并标来源 → 判断微小 vs 非微小决定是否 `plan create` → 再 `dag run-task`。  
-**禁止**：主会话直接写业务代码代替 DAG。
+**做法**：主会话 **先问清**是否有 PRD 文件；有则 `--prd`；无则 `--from-text` 写入共识并标来源 → 判断微小 vs 非微小决定是否 `plan create` → 再 `task advance`。
+**禁止**：主会话直接写业务代码代替 lifecycle。
 
 ## 宿主 agent 检查清单（编排时）
 
-在第一次 `dag run-task` 前快速自问：
+在第一次 `task advance` 前快速自问：
 
-1. 是否存在用户/仓库原始需求文件？→ **有则 `import-prd`**。
-2. `source/需求.md` 是否含目标、非目标、可验证验收？→ **无则先写**。
-3. `allowedPaths` / `forbiddenPaths` 是否已结构化？→ **无则先写**。
+1. 是否存在用户/仓库原始需求文件？→ **有则 `--prd`**。
+2. `source/需求.md` 是否含目标、非目标、可验证验收？→ **无则由 advance 投影或补 flags**。
+3. `allowedPaths` / `forbiddenPaths` 是否已结构化？→ **无则先写 flags**。
 4. 是否非微小 / 跨会话 / 高 blast-radius？→ **`plan create` 或更新已有 active plan**。
 5. 是否仅聊天约束？→ **落盘到 source 或 plan**，不要只留在对话。
 
-## 与「主路径 DAG」文档的关系
+## 与「主路径」文档的关系
 
-`SKILL.md` / `command-reference.md` 的 **主路径 DAG** 仍是最短 runtime 闭环（便于抄命令）。  
+`SKILL.md` / `command-reference.md` 的 **主路径** 仍是最短 runtime 闭环（便于抄命令）。
 **系统化默认**应读作：
 
 ```text
 [非微小?] plan create（或复用 active plan）
-new-task
-[有 PRD?] import-prd
-派生 需求.md / 执行约束.md / task.json 路径边界
-dag run-task → validate → run-dag → promote/closeout
+task advance [--prd | --from-text] + 工程边界 flags
+审查 writeSet gate
+task advance --approve-gate
+task status
 [有 plan?] plan complete
 ```
 
-不要把 `import-prd` / `plan create` 伪造成「无文件也必须执行」的假步骤；用本节决策表选择，而不是一律省略。
+不要把 PRD 归档 / `plan create` 伪造成「无文件也必须执行」的假步骤；用本节决策表选择，而不是一律省略。

package/skills/loop-agent/references/task-workflow.md

@@ -4,20 +4,19 @@
 
 ## 当前执行入口
 
-所有需要可恢复、可验证、可交接的实现工作都走 DAG 路径：
+所有需要可恢复、可验证、可交接的实现工作都走 `task advance` lifecycle（内部驱动 Agent DAG）：
 
 ```bash
-loop-agent new-task <task-id> "Task Title"
-# 推荐：详细 PRD → import → prepare（无需手写两 source）
-loop-agent import-prd <task-id> --file <prd>
-loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
 # 非微小：loop-agent plan create <plan-id> "<title>"（可与 task 解耦，见 source-and-plan-practice.md）
-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>
+loop-agent task advance <task-id> "Task Title" \
+  --prd <prd> \
+  --allowed-path "<glob>" \
+  --json
+loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
+loop-agent task status <task-id> --json
 ```
 
-默认 DAG 草稿为 `.harness/tasks/<task-id>/dag.json`。repo-relative 示例用 `/`；Windows 由 Node 解析本地路径。何时必须 `import-prd` / `plan create`：见 `source-and-plan-practice.md`。
+默认 DAG 草稿仍为 `.harness/tasks/<task-id>/dag.json`。repo-relative 示例用 `/`；Windows 由 Node 解析本地路径。何时必须 PRD / `plan create`：见 `source-and-plan-practice.md`。
 
 当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
 
@@ -25,22 +24,22 @@ loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
 
 ## Source Materials
 
-`new-task` 后至少维护：
+`task advance` 创建 task 后至少维护：
 
 ```text
 .harness/tasks/<task-id>/
   source/
     references/          # 原始 PRD / design / acceptance（不可变）
-    source-manifest.json # import-prd 写入的 hash 清单
+    source-manifest.json # task advance --prd 写入的 hash 清单
     需求.md              # 派生执行契约
     执行约束.md
   task.json
 ```
 
-- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就 import**。
-- 默认用 `task source prepare --use-imported-prd --apply` 投影 `需求.md` / `执行约束.md` 与 managed paths；**不要**默认让 LLM/主会话手写两 source。
-- 无独立 PRD 的微小任务可用 `task source prepare --from-text ... --apply` escape hatch（见 `source-and-plan-practice.md`）。
-- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再 prepare 派生薄契约；避免把长 PRD 直接改写成唯一 source。
+- 用户原始 PRD 用 `task advance --prd <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就归档**。
+- 默认用 `task advance`（带 `--allowed-path` / `--verify`）投影 `需求.md` / `执行约束.md` 与 managed paths；**不要**默认让 LLM/主会话手写两 source。
+- 无独立 PRD 的微小任务可用 `task advance --from-text ...` escape hatch（见 `source-and-plan-practice.md`）。
+- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `task advance --prd` 归档并派生薄契约；避免把长 PRD 直接改写成唯一 source。
 - 仓库级 exec-plan（`plan create`）与 harness task **解耦**：非微小实现应有 plan 或复用 active plan；微小任务可不建 plan。
 - Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
 - review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。