@tea-agent/loop-agent 0.7.5 → 0.9.0

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

@@ -1,44 +1,44 @@
-# 实现后处理与常见模式
-
-用于 post-verify handoff、多 item PRD 处理、fast bounded task、快速 status 检查与 Pi timeout 处理。
-
-## 实现后处理
-
-DAG run、promotion、closeout 和最终验证完成后：
-1. 检查 git diff 确认预期变更
-2. 用 git commit 并 push
-3. 用户说「继续」时，跑 `status` 看 task 是否 `completed`，再创建下一个 task
-
-## 常见模式
-
-### 处理多 item PRD
-```
-1. new-task <id>-r1  → 准备 source → dag run-task → dag validate → run-dag → promote/closeout
-2. new-task <id>-r2  → 重复
-3. ...
-```
-
-### Bounded task 路径
-```
-1. new-task <id>
-2. 写 source/需求.md + source/执行约束.md
-3. dag run-task <id> --profile auto --strict-models --output <temp-dir>/<id>-dag.json
-4. dag validate --dag <temp-dir>/<id>-dag.json --strict-models --strict-governance
-5. run-dag --dag <temp-dir>/<id>-dag.json --cwd <repo-root>
-6. promote-run / closeout / final verification
-```
-
-`<temp-dir>` 表示平台原生临时目录；实际命令中使用 macOS/Windows 本机路径。
-
-**关键**：实现 work 由 DAG node 和 executor 执行；main session 负责审 DAG、审 writeSet、跑验证和 handoff。
-
-### 跨所有 task 快速 status
-```bash
-loop-agent stats
-```
-
-### 处理 pi timeout
-- 默认每 step timeout 现为 30 分钟 — 通常足够
-- pi step 仍 timeout 时，用 `stats` 看 duration 分布
-- Bash tool call 应用宽松 timeout：analyze/plan 300s，implement 480s+，verify/retrospective 240s+
-- 失败时优先读 `dag report` / `dag doctor`，再决定 repair DAG、bounded Cursor fix 或暂停
+# 实现后处理与常见模式
+
+用于 post-verify handoff、多 item PRD 处理、fast bounded task、快速 status 检查与 Pi timeout 处理。
+
+## 实现后处理
+
+DAG run、promotion、closeout 和最终验证完成后：
+1. 检查 git diff 确认预期变更
+2. 用 git commit 并 push
+3. 用户说「继续」时，跑 `status` 看 task 是否 `completed`，再创建下一个 task
+
+## 常见模式
+
+### 处理多 item PRD
+```
+1. new-task <id>-r1  → 准备 source → dag run-task → dag validate → run-dag → promote/closeout
+2. new-task <id>-r2  → 重复
+3. ...
+```
+
+### Bounded task 路径
+```
+1. new-task <id>
+2. 写 source/需求.md + source/执行约束.md
+3. dag run-task <id> --profile auto --strict-models --output <temp-dir>/<id>-dag.json
+4. dag validate --dag <temp-dir>/<id>-dag.json --strict-models --strict-governance
+5. run-dag --dag <temp-dir>/<id>-dag.json --cwd <repo-root>
+6. promote-run / closeout / final verification
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用 macOS/Windows 本机路径。
+
+**关键**：实现 work 由 DAG node 和 executor 执行；main session 负责审 DAG、审 writeSet、跑验证和 handoff。
+
+### 跨所有 task 快速 status
+```bash
+loop-agent stats
+```
+
+### 处理 pi timeout
+- 默认每 step timeout 现为 30 分钟 — 通常足够
+- pi step 仍 timeout 时，用 `stats` 看 duration 分布
+- Bash tool call 应用宽松 timeout：analyze/plan 300s，implement 480s+，verify/retrospective 240s+
+- 失败时优先读 `dag report` / `dag doctor`，再决定 repair DAG、bounded Cursor fix 或暂停

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

@@ -1,89 +1,89 @@
-# Task Workflow 规则
-
-本文只保留 legacy task 目录和 source material 的读取规则。历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` 工作流已经移除，不再作为 micro、fallback 或 compatibility 执行路径。
-
-## 当前执行入口
-
-所有需要可恢复、可验证、可交接的实现工作都走 DAG 路径：
-
-```bash
-loop-agent new-task <task-id> "Task Title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
-```
-
-`<temp-dir>` 表示平台原生临时目录。实际文件路径必须兼容 macOS 和 Windows；只有 repo refs、JSON/Markdown 证据 refs 和 glob 约定默认使用 `/`。
-
-当目标仓库是 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>`。
-
-低风险的一行修正文档或配置时，可以由 main session 做 surgical patch，但仍必须记录 scope 并运行对应验证命令。
-
-## Source Materials
-
-`new-task` 后至少维护：
-
-```text
-.harness/tasks/<task-id>/
-  source/
-    references/          # 原始 PRD / design / acceptance（不可变）
-    source-manifest.json # import-prd 写入的 hash 清单
-    需求.md              # 派生执行契约
-    执行约束.md
-  task.json
-```
-
-- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。
-- `需求.md` 是派生执行契约：写清目标、验收标准、非目标，并用 REQ/AC 或原文锚点映射回 references。
-- `执行约束.md` 写清允许文件、禁止改动、硬约束和验证命令。
-- 若 `docs/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再在 `需求.md` 引用；避免把长 PRD 直接改写成唯一 source。
-- Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
-- review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。
-
-## Task State
-
-当前 task 状态由 DAG-oriented read model 推导：
-
-- source readiness
-- DAG draft
-- latest DAG run
-- promotion
-- closeout
-- loop state
-- legacy workflow snapshot
-
-旧 `.workflow_state.json` 只能作为兼容读取输入，不是新任务 next action 或完成状态的权威来源。
-
-## Repo Adapters
-
-loop-agent 自动检测所在 repo，并按目标 repo 的 `harness.json` 与治理根目录选择验证入口。跨目录操作时显式传入目标仓库：
-
-```bash
-loop-agent --repo-root /path/to/target-repo <command>
-```
-
-## Task Config
-
-新任务不应写入旧 `flow` 字段。常用字段是：
-
-- `taskId`
-- `title`
-- `complexity`
-- `allowedPaths`
-- `forbiddenPaths`
-- `hardConstraints`
-- `verifyCommands` / adapter verification settings
-- `dagFallbackReason`，仅用于记录为何某个长期 loop 缺少 DAG round evidence
-
-## Verification
-
-完成声明必须来自新鲜验证证据。按目标 repo 的 `docs/verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：
-
-```bash
-npm run typecheck
-npm test
-bash scripts/check-repo.sh
-bash scripts/ci.sh
-```
-
-Windows 上通过 Git Bash 或配置好的兼容 Bash 运行 `scripts/*.sh`；不要把 POSIX 路径假设写入 CLI、模板或 task source。
+# Task Workflow 规则
+
+本文只保留 legacy task 目录和 source material 的读取规则。历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` 工作流已经移除，不再作为 micro、fallback 或 compatibility 执行路径。
+
+## 当前执行入口
+
+所有需要可恢复、可验证、可交接的实现工作都走 DAG 路径：
+
+```bash
+loop-agent new-task <task-id> "Task Title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+```
+
+`<temp-dir>` 表示平台原生临时目录。实际文件路径必须兼容 macOS 和 Windows；只有 repo refs、JSON/Markdown 证据 refs 和 glob 约定默认使用 `/`。
+
+当目标仓库是 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>`。
+
+低风险的一行修正文档或配置时，可以由 main session 做 surgical patch，但仍必须记录 scope 并运行对应验证命令。
+
+## Source Materials
+
+`new-task` 后至少维护：
+
+```text
+.harness/tasks/<task-id>/
+  source/
+    references/          # 原始 PRD / design / acceptance（不可变）
+    source-manifest.json # import-prd 写入的 hash 清单
+    需求.md              # 派生执行契约
+    执行约束.md
+  task.json
+```
+
+- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。
+- `需求.md` 是派生执行契约：写清目标、验收标准、非目标，并用 REQ/AC 或原文锚点映射回 references。
+- `执行约束.md` 写清允许文件、禁止改动、硬约束和验证命令。
+- 若 `docs/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再在 `需求.md` 引用；避免把长 PRD 直接改写成唯一 source。
+- Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
+- review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。
+
+## Task State
+
+当前 task 状态由 DAG-oriented read model 推导：
+
+- source readiness
+- DAG draft
+- latest DAG run
+- promotion
+- closeout
+- loop state
+- legacy workflow snapshot
+
+旧 `.workflow_state.json` 只能作为兼容读取输入，不是新任务 next action 或完成状态的权威来源。
+
+## Repo Adapters
+
+loop-agent 自动检测所在 repo，并按目标 repo 的 `harness.json` 与治理根目录选择验证入口。跨目录操作时显式传入目标仓库：
+
+```bash
+loop-agent --repo-root /path/to/target-repo <command>
+```
+
+## Task Config
+
+新任务不应写入旧 `flow` 字段。常用字段是：
+
+- `taskId`
+- `title`
+- `complexity`
+- `allowedPaths`
+- `forbiddenPaths`
+- `hardConstraints`
+- `verifyCommands` / adapter verification settings
+- `dagFallbackReason`，仅用于记录为何某个长期 loop 缺少 DAG round evidence
+
+## Verification
+
+完成声明必须来自新鲜验证证据。按目标 repo 的 `docs/verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：
+
+```bash
+npm run typecheck
+npm test
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+```
+
+Windows 上通过 Git Bash 或配置好的兼容 Bash 运行 `scripts/*.sh`；不要把 POSIX 路径假设写入 CLI、模板或 task source。

package/skills/loop-agent/references/verification-and-failure-handling.md

@@ -1,128 +1,133 @@
-# Verification 与失败处理
-
-选择 verify strategy knobs、解读 verify 结果、决定失败后是否继续，或 closeout workflow/runtime/docs/skill 变更时使用本文。
-
-## Verify strategy 与 completion audit
-
-## Production Readiness v0.1
-
-低/中风险单 repo DAG 任务如果声明 production-ready v0.1，必须按 `docs/production-readiness.md` 和 `docs/templates/production-readiness-checklist.md` 收口。
-
-支持范围：
-
-- single repo
-- bounded task
-- explicit task source
-- explicit `allowedPaths` / `forbiddenPaths` / write scope
-- shell verification
-- report / doctor / closeout handoff
-
-非目标：
-
-- automatic merge
-- automatic release
-- production secrets
-- production database
-- high-risk migration
-- online Worker Pool
-- writable Dynamic Workflow sharded migration
-
-失败分类是路由字段，不是主状态；不要覆盖 `.harness/dag-runs/completed/**` 的原始事实。报告和 handoff 应保留：
-
-```text
-raw_failure_category
-dag_normalized_failure_category
-product_line_failure_category
-recommended_follow_up
-```
-
-product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md`。
-
-### Verify 始终在本地跑
-`verify` step 跑确定性命令（check-repo.sh + tests + typecheck）。**不**调用 pi。因此快且可靠。
-
-### Verify strategy knobs
-需要更紧的 verify 控制时，用 task-level config：
-```json
-{
-  "verifyPreset": "auto",
-  "verifyMode": "parallel",
-  "verifyRetryCount": 0,
-  "verifyFailFast": false
-}
-```
-
-- `verifyPreset`：`auto | quick | standard | full`
-  - `auto`：`small -> quick`，`medium -> standard`，`large -> full`
-- 默认 `parallel`
-- 命令争抢共享资源时用 `serial`
-- `verifyFailFast` 仅在 `serial` mode 有意义
-- retry 保持小；用于 flaky 环境问题，不要掩盖真实失败
-
-### Verify 后的 goal completion audit
-- 有 active task goal 且 `verify` 通过时，loop-agent 跑 goal completion audit。
-- 若 `source/需求.md` 仍有未勾 checklist（`- [ ]`），task **不会**以 completed 结束。
-- 若确定性 requirement coverage audit 发现未覆盖需求，task **不会**以 completed 结束。
-- `explicitly_out_of_scope` 需求（如 `## 非目标` 下）**不算** coverage gap。
-- 独立 audit 报告用 `handoff coverage <task-id> [--json|--markdown]`。
-- task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>' [--json|--markdown]`。默认仅报告；`--patch` 不能伪造 verification evidence。
-
-### Verify 默认保存进度
-`verify` 成功后，loop-agent 默认：
-
-1. 在当前 task scope 内选文件
-2. 跑 `git add`
-3. 创建 commit 保存已验证进度
-
-默认行为：
-
-- `autoCommitAfterVerify: true`
-- commit message：`chore(task): save verified progress for <taskId>`
-
-`task.json` 可选覆盖：
-
-```json
-{
-  "autoCommitAfterVerify": false,
-  "autoCommitMessage": "docs(workflow): save verified progress"
-}
-```
-
-最佳实践：保持 `allowedPaths` 准确。auto-commit 用 task path 约束，避免把无关 dirty 文件扫进 progress commit。
-
-### Cursor bounded write 后的独立复核
-
-Cursor bounded execution 完成后，主会话必须独立执行：
-
-```bash
-git status --short
-git diff --stat
-bash scripts/check-repo.sh
-npm run lint
-npm test
-npm run typecheck
-loop-agent inspect
-loop-agent docs audit
-loop-agent handoff check <task-id>
-```
-
-Cursor 自己报告的完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
-
-### 失败处理
-
-child agent 失败时：
-
-- **业务/测试失败**：让 child agent 在同一 task bounds 内修复
-- **Workflow runtime 失败**（如 `loop-agent` runtime 问题、部分 artifact 生成、输出聚合 crash）：保持 task contract，但允许 main agent 或 child agent 在同一 scoped implementation 内手动完成，仍跑 `verify`
-- **意外残留**（tmp 文件、探索性 mock、scratch 输出）：handoff 前删除
-
-### Closeout 规则
-workflow/runtime/docs/skill 变更结束时：
-```bash
-loop-agent docs audit
-loop-agent handoff check <task-id>
-```
-
-active exec plan 实质完成时，用 `docs archive` 归档并更新 active/completed 索引，勿留 stale active status。
-
-failed DAG run 不应生成成功式 closeout。它应该生成 failure handoff，至少包含 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。
+# Verification 与失败处理
+
+选择 verify strategy knobs、解读 verify 结果、决定失败后是否继续，或 closeout workflow/runtime/docs/skill 变更时使用本文。
+
+## Verify strategy 与 completion audit
+
+## Production Readiness v0.1
+
+低/中风险单 repo DAG 任务如果声明 production-ready v0.1，必须按 `docs/production-readiness.md` 和 `docs/templates/production-readiness-checklist.md` 收口。
+
+支持范围：
+
+- single repo
+- bounded task
+- explicit task source
+- explicit `allowedPaths` / `forbiddenPaths` / write scope
+- shell verification
+- report / doctor / closeout handoff
+
+非目标：
+
+- automatic merge
+- automatic release
+- production secrets
+- production database
+- high-risk migration
+- online Worker Pool
+- writable Dynamic Workflow sharded migration
+
+失败分类是路由字段，不是主状态；不要覆盖 `.harness/dag-runs/completed/**` 的原始事实。报告和 handoff 应保留：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md`。
+
+### Verify 始终在本地跑
+`verify` step 跑确定性命令（check-repo.sh + tests + typecheck）。**不**调用 pi。因此快且可靠。
+
+### Verify strategy knobs
+需要更紧的 verify 控制时，用 task-level config：
+```json
+{
+  "verifyPreset": "auto",
+  "verifyMode": "serial",
+  "verifyRetryCount": 0,
+  "verifyFailFast": false
+}
+```
+
+- `verifyPreset`：`auto | quick | standard | full`
+  - `auto`：`small -> quick`，`medium -> standard`，`large -> full`
+- 默认 `serial`，优先避免本机测试、构建和治理检查互相争抢资源
+- 确认命令互不影响且机器资源充足时，才显式使用 `parallel`
+- `verifyFailFast` 仅在 `serial` mode 有意义
+- retry 保持小；用于 flaky 环境问题，不要掩盖真实失败
+
+### 长输出处理
+
+- DAG shell 命令和 Worker 子进程只在内存中保留最近一段 stdout/stderr，并在结果中标明是否截断及原始字节数。
+- 需要完整日志时读取运行 artifact 中的 `stdout.txt`、`stderr.txt` 或 DAG 节点的 `commands/*.stdout.txt`、`commands/*.stderr.txt`；不要依赖页面摘要还原全部输出。
+
+### Verify 后的 goal completion audit
+- 有 active task goal 且 `verify` 通过时，loop-agent 跑 goal completion audit。
+- 若 `source/需求.md` 仍有未勾 checklist（`- [ ]`），task **不会**以 completed 结束。
+- 若确定性 requirement coverage audit 发现未覆盖需求，task **不会**以 completed 结束。
+- `explicitly_out_of_scope` 需求（如 `## 非目标` 下）**不算** coverage gap。
+- 独立 audit 报告用 `handoff coverage <task-id> [--json|--markdown]`。
+- task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>' [--json|--markdown]`。默认仅报告；`--patch` 不能伪造 verification evidence。
+
+### Verify 默认保存进度
+`verify` 成功后，loop-agent 默认：
+
+1. 在当前 task scope 内选文件
+2. 跑 `git add`
+3. 创建 commit 保存已验证进度
+
+默认行为：
+
+- `autoCommitAfterVerify: true`
+- commit message：`chore(task): save verified progress for <taskId>`
+
+`task.json` 可选覆盖：
+
+```json
+{
+  "autoCommitAfterVerify": false,
+  "autoCommitMessage": "docs(workflow): save verified progress"
+}
+```
+
+最佳实践：保持 `allowedPaths` 准确。auto-commit 用 task path 约束，避免把无关 dirty 文件扫进 progress commit。
+
+### Cursor bounded write 后的独立复核
+
+Cursor bounded execution 完成后，主会话必须独立执行：
+
+```bash
+git status --short
+git diff --stat
+bash scripts/check-repo.sh
+npm run lint
+npm test
+npm run typecheck
+loop-agent inspect
+loop-agent docs audit
+loop-agent handoff check <task-id>
+```
+
+Cursor 自己报告的完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
+
+### 失败处理
+
+child agent 失败时：
+
+- **业务/测试失败**：让 child agent 在同一 task bounds 内修复
+- **Workflow runtime 失败**（如 `loop-agent` runtime 问题、部分 artifact 生成、输出聚合 crash）：保持 task contract，但允许 main agent 或 child agent 在同一 scoped implementation 内手动完成，仍跑 `verify`
+- **意外残留**（tmp 文件、探索性 mock、scratch 输出）：handoff 前删除
+
+### Closeout 规则
+workflow/runtime/docs/skill 变更结束时：
+```bash
+loop-agent docs audit
+loop-agent handoff check <task-id>
+```
+
+active exec plan 实质完成时，用 `docs archive` 归档并更新 active/completed 索引，勿留 stale active status。
+
+failed DAG run 不应生成成功式 closeout。它应该生成 failure handoff，至少包含 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。