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

package/AGENTS.md

@@ -24,7 +24,7 @@
 - Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本用 Git Bash / 兼容 Bash。
 - 用 loop-agent 迭代本仓库时，控制器必须来自已发布 npm 包（记录实际版本）；启动后不要中途升级；不要用工作区 `npm link` / `npm run dev` 控制可能改 CLI/runtime/package 的任务。
 - 反复出现的约束固化为文档、脚本、检查、测试或模板；禁止占位实现（除非 contract 标明脚手架）。
-- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `new-task`、结构化路径、`dag run-task`、`dag validate` 与 writeSet 审查。
+- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `task advance`（PRD + 结构化路径边界）、writeSet gate 审查与 `task advance --approve-gate`。
 - **实现默认 DAG，主会话不直接改代码**：只要是实现/修复/行为或展示语义变更（含 observe 文案映射、runtime status、schema、executor、CLI 等），主会话只做 Orient / 建 task / dry-run / validate / writeSet 审查 / 执行与监视 DAG，**不得**自己改 `src/**`、`test/**` 等交付面。仅当用户**明确授权**主会话直接处理（例如「直接改」「主会话改」「one-shot」「不用 DAG」）时，才允许主会话写入；授权后仍须记录边界、allowedPaths 与验证证据。纯答疑、读代码、查状态、提交/推送已有 diff、或用户点名的文档微调（如本文件规则）不在此限。
 - 不要自行引入外部 SDD/spec-first 等强制平行治理树；以本文件与 `docs/` 为准（ADR 0006）。
 
@@ -51,7 +51,7 @@
 
 DAG 执行期间主 agent 必须持续轮询监视直到 run 结束（FINISHED / FAILED / 需要 approve），不能轮询一次就停下等用户；轮询间隔应合理（避免频繁唤醒浪费 token，也不得住一个节点上赌一次就走）。判活必须用可靠方式：看 `state.json` 的 `runner.heartbeatAt` 是否持续刷新 + `session-events.jsonl` 是否在增长 + `dag doctor` 的 `liveness` 字段，不要只用 `tasklist /FI "PID eq X"` 这类过滤语法在 Git Bash 下会误报 DEAD，从而错判一个正常工作的 run 为 orphaned。遇到疑似 stall 先按 `docs/runtime/agent-dag-runner.md` 查 `lastMeaningfulProgressAt` / provider 活动，有真实进展就继续等，绝不盲目 supersede。
 
-DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件（包括 AGENTS.md、docs、根配置等）。bounded writer 节点的 write guard 用「节点运行期间的工作区 diff」作为越界证据，不区分改动来自 pi 还是主会话——主会话在 pi 节点跑的时候改了 writeSet 外文件，会让 write guard 把账算到 pi 头上、判节点 ERROR、下游 cascade skip。需要改文档/约束时，要么在 DAG 启动前改完，要么等 run 结束后改；务必与 DAG 写入节点在时间上互斥。排查任务路由问题时优先用 `resolveTaskDagTemplateSelection` / `classifyTaskDemand` 等纯函数探针或 `--output` 指定临时路径，不要反复 `dag run-task`——每次调用（含 `--dry-run`）都会在 `.harness/dag-runs/active/` 新建一个 run 目录，dry-run 不执行节点但目录残留，堆积成「一堆 active run」的假象。
+DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件（包括 AGENTS.md、docs、根配置等）。bounded writer 节点的 write guard 用「节点运行期间的工作区 diff」作为越界证据，不区分改动来自 pi 还是主会话——主会话在 pi 节点跑的时候改了 writeSet 外文件，会让 write guard 把账算到 pi 头上、判节点 ERROR、下游 cascade skip。需要改文档/约束时，要么在 DAG 启动前改完，要么等 run 结束后改；务必与 DAG 写入节点在时间上互斥。排查任务路由问题时优先用 `resolveTaskDagTemplateSelection` / `classifyTaskDemand` 等纯函数探针或 `--output` 指定临时路径，不要反复 `dag execute --dry-run` / 无必要的 lifecycle 探测——每次可能在 `.harness/dag-runs/active/` 新建 run 目录，dry-run 不执行节点但目录残留，堆积成「一堆 active run」的假象。优先用纯函数探针或 `task status`。
 
 ## 项目地图
 

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+### 修复
+
+- 修复 backend-test collection assess 在 Markdown 已声明安全 mapped `test_*.py`、但 pytest writer 漏生成文件时直接以 `invalid-output` 阻断 repair 的问题：initial facts 升级为 `backend-test-pytest-collection-v2`，可记录 expected/existing/missing scripts、`collectionAttempted=false` 与 `missing-mapped-pytest-script`，复用既有单次 bounded repair 创建精确缺失脚本，并由 final collection、scope、安全和 hash freshness 门禁重新授权业务执行
+
+## [0.27.0] - 2026-08-03
+
+### 重点更新
+
+- 标准操作生命周期统一为 task advance（推进任务）与 task status（查看状态）两个入口
+- 移除十余个旧版公开命令别名，简化操作心智模型
+- task advance 首次执行可自动完成 PRD 导入、契约派生、DAG 生成与校验，停在 writeSet 摘要门禁等待确认
+- Worker 与 Console 全面迁移至新的机器契约，统一通过 task advance 驱动
+
+### 新增
+
+- 新增 task advance 作为标准任务生命周期的唯一推荐变更入口
+- 新增 task status 作为只读任务状态查询入口
+- task advance 支持 --accept-recommendations 参数，通过摘要确认确定性采纳工程边界推荐
+- task advance 新增 Worker 机器契约参数：--profile、--max-concurrent、--run-id、--events-jsonl、--worker-association、--dag-output、--skip-finalize、--no-strict-models
+- ADR 0008 将 run 级 dag recovery/forensic/decision 冻结为永久 advanced 专用，标准 task 面保持简洁
+
+### 改进
+
+- Worker run-task 主路径改为 task advance prepare 到 writeSet 门禁后经 --approve-gate 执行，不再 spawn dag run-task / run-dag / dag validate
+- Console 的 status 调用迁移至 task status，dagRunTask/prepareDagConfirmation 生成路径迁移至 task advance --dag-output
+- 顶层 status 去掉 refreshSourceState 副作用，read-model next 指向 advance/status
+- 标准主路径文档、skills、help、capabilities 全面收敛为 task advance + task status
+
+### 修复
+
+- 完成 task-advance 迁移后对齐残余断言：skill 触发词、workflow defaultEntry、Ring1/Ring2 CLI smoke 及 help-summary 与新生命周期一致
+- 更新 dag/run-task/final-verification/reference-context 预期，pre-push 不再断言已删除的 dag run-task / task contract 公开命令
+
 ## [0.26.4] - 2026-08-03
 
 ### 重点更新

package/README.md

@@ -55,40 +55,30 @@ loop-agent init reconcile --repo-root .
 初始化后，在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」（或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」），初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG，**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证，业务实现由受治理 DAG writer 完成。
 
 ```bash
-loop-agent new-task example-task "实现一个有明确验收标准的小功能"
-
-# 推荐：先有详细 PRD，再归档并确定性派生执行契约（无需手写两个 source 文件）
-# loop-agent import-prd example-task --file path/to/prd.md --json
-loop-agent task source prepare example-task \
-  --use-imported-prd \
+# 标准单任务路径：唯一 mutation 入口 task advance + 可选只读 task status
+loop-agent task advance example-task "实现一个有明确验收标准的小功能" \
+  --prd path/to/prd.md \
   --allowed-path "src/**" \
   --forbidden-path ".harness/**" \
   --verify "typecheck:npm run typecheck" \
-  --apply --json
-
-loop-agent dag run-task example-task \
-  --profile auto \
-  --strict-models \
-  --output .harness/tasks/example-task/dag.json
+  --json
 
-loop-agent dag validate \
-  --dag .harness/tasks/example-task/dag.json \
-  --strict-models \
-  --strict-governance
+# 审查返回的 writeSet / gate.digest 后，同一命令批准并长跑到稳定终态
+loop-agent task advance example-task \
+  --approve-gate "write-set-review:<digest>" \
+  --json
 
-loop-agent run-dag \
-  --dag .harness/tasks/example-task/dag.json \
-  --cwd .
+# 可选只读查询（不 refresh、不 mutation）
+loop-agent task status example-task --json
 ```
 
-省略 `--output` 时默认写入 `.harness/tasks/<task-id>/dag.json`。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
+首次 `task advance` 会 create/import PRD/派生 managed contract/生成并 strict validate DAG，然后停在 writeSet gate；未批准不会启动业务 writer。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
 
 ## 查看执行状态
 
 ```bash
-loop-agent status example-task
-loop-agent dag status
-loop-agent dag doctor --run-id <run-id> --markdown
+loop-agent task status example-task --json
+# advanced forensic（非标准主路径）
 loop-agent dag report --run-id <run-id>
 ```
 

package/dist/application/dag/args.js

@@ -247,7 +247,7 @@ export function parseDagValidateArgs(args) {
 }
 export function parseRunDagArgs(args, defaultCwd) {
     if (args.length === 0) {
-        throw new Error("usage: run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--quiet] [--progress-interval-ms N] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]] [--events-jsonl <path>] [--json]");
+        throw new Error("usage: dag execute --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--quiet] [--progress-interval-ms N] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]] [--events-jsonl <path>] [--json]");
     }
     let dagPath;
     let cwd;
@@ -328,7 +328,7 @@ export function parseRunDagArgs(args, defaultCwd) {
             workerAssociation = parseWorkerAssociation(arg.slice("--worker-association=".length));
         }
         else if (arg === "--json") {
-            // Accepted for operator/console callers; run-dag always emits JSON stdout.
+            // Accepted for operator/console callers; dag execute always emits JSON stdout.
         }
         else if (!arg.startsWith("-")) {
             if (!dagPath)
@@ -337,11 +337,11 @@ export function parseRunDagArgs(args, defaultCwd) {
                 throw new Error(`unexpected positional argument: ${arg}`);
         }
         else {
-            throw new Error(`unknown run-dag flag: ${arg}`);
+            throw new Error(`unknown dag execute flag: ${arg}`);
         }
     }
     if (!dagPath) {
-        throw new Error("run-dag requires --dag <path>");
+        throw new Error("dag execute requires --dag <path>");
     }
     return {
         dagPath: path.resolve(dagPath),
@@ -368,14 +368,14 @@ function parseProgressIntervalMs(value) {
 }
 function parseWorkerAssociation(raw) {
     if (!raw?.trim()) {
-        throw new Error("run-dag --worker-association requires JSON");
+        throw new Error("dag execute --worker-association requires JSON");
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error("run-dag --worker-association must be valid JSON");
+        throw new Error("dag execute --worker-association must be valid JSON");
     }
     if (!parsed ||
         typeof parsed !== "object" ||
@@ -383,7 +383,7 @@ function parseWorkerAssociation(raw) {
         typeof parsed.workerRunId !== "string" ||
         typeof parsed.featureId !== "string" ||
         typeof parsed.taskId !== "string") {
-        throw new Error("run-dag --worker-association requires {schemaVersion:1,workerRunId,featureId,taskId}");
+        throw new Error("dag execute --worker-association requires {schemaVersion:1,workerRunId,featureId,taskId}");
     }
     return parsed;
 }

package/dist/application/dag/generate-task-dag.js

@@ -75,8 +75,8 @@ function buildNextSteps(taskId, outputPath, cwd) {
     return [
         `Review ${outputPath}`,
         `loop-agent dag validate --dag ${outputPath} --strict-models --strict-governance`,
-        `loop-agent run-dag --dag ${outputPath} --cwd ${cwd}`,
-        `loop-agent dag run-task ${taskId} --execute --cwd ${cwd}`,
+        `loop-agent dag execute --dag ${outputPath} --cwd ${cwd}`,
+        `loop-agent task advance ${taskId} --approve-gate write-set-review:<digest> --json`,
     ];
 }
 function buildBasicValidationLevel(outputPath) {

package/dist/application/dag/run-dag.js

@@ -23,10 +23,9 @@ async function flushCanvasSafely(canvas) {
 }
 function buildRunDagNextSteps(runId) {
     return [
-        `loop-agent dag report --run-id ${runId} --markdown`,
-        `loop-agent dag doctor --run-id ${runId} --markdown`,
-        `loop-agent promote-run <task-id> --run-id ${runId}`,
-        `loop-agent dag closeout-draft --run-id ${runId}`,
+        `loop-agent task advance <task-id> --json  # promote/closeout/recovery via lifecycle entry`,
+        `loop-agent task status <task-id> --json`,
+        `loop-agent dag report --run-id ${runId} --markdown  # advanced forensic`,
     ];
 }
 export async function runDagUseCase(input) {

package/dist/application/dag/validate-dag.js

@@ -161,6 +161,6 @@ export async function validateDagUseCase(input) {
             ...formatModelMatrixWarnings(warnings),
             ...formatGovernanceWarnings(governanceWarnings),
         ],
-        next: [`loop-agent run-dag --dag ${input.dagPath} --cwd ${input.repoRoot}`],
+        next: [`loop-agent dag execute --dag ${input.dagPath} --cwd ${input.repoRoot}`],
     };
 }