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

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`、以及实现/验证证据。