@tea-agent/loop-agent 0.3.0 → 0.4.0

package/docs/loop-agent-harness.md

@@ -1,42 +1,42 @@
-# loop-agent Harness
-
-loop-agent 提供结构化 agent 工作的本地 harness。
-
-## Runtime 区域
-
-- `.harness/tasks/` — task source、约束、state、loop facts
-- `.harness/dag-runs/` — DAG run state 与 artifacts
-- `.harness/runs/` — one-shot tool run 证据
-- `.harness/cache/` — 本地 runtime 缓存
-- `.harness/live/` — 瞬态 live-session 文件
-
-## Skill 指令
-
-- `skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
-- `skills/<skill-name>/` — DAG 模板引用的 skill 本地副本，含 supervised implementation 角色
-- 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
-
-## Package 资产
-
-npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
-
-生成或历史的 task facts 不是 package 资产。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
-
-从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标本地 skill 目录解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或 `skills/` 目录即可使用默认 DAG 工作流。
-
-## Command Surface
-
-- `new-task`、`status`、`inspect`、`doctor`
-- `dag run-task`、`dag validate`、`run-dag`、`dag report`、`dag resume`
-- `delegate`、`harvest`、`promote-run`、`closeout`
-- `loop init`、`loop run`、`loop status`、`loop closeout`
-- `pi-prompt`、`cursor-prompt`
-- `docs audit`、`handoff check`、`spine audit`、`knowledge curate`
-
-## 验证 Preset
-
-Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
-
-```bash
-bash scripts/ci.sh
-```
+# loop-agent Harness
+
+loop-agent 提供结构化 agent 工作的本地 harness。
+
+## Runtime 区域
+
+- `.harness/tasks/` — task source、约束、state、loop facts
+- `.harness/dag-runs/` — DAG run state 与 artifacts
+- `.harness/runs/` — one-shot tool run 证据
+- `.harness/cache/` — 本地 runtime 缓存
+- `.harness/live/` — 瞬态 live-session 文件
+
+## Skill 指令
+
+- `skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
+- `skills/<skill-name>/` — DAG 模板引用的 skill 本地副本，含 supervised implementation 角色
+- 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
+
+## Package 资产
+
+npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
+
+生成或历史的 task facts 不是 package 资产。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
+
+从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标本地 skill 目录解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或 `skills/` 目录即可使用默认 DAG 工作流。
+
+## Command Surface
+
+- `new-task`、`status`、`inspect`、`doctor`
+- `dag run-task`、`dag validate`、`run-dag`、`dag report`、`dag resume`
+- `delegate`、`harvest`、`promote-run`、`closeout`
+- `loop init`、`loop run`、`loop status`、`loop closeout`
+- `pi-prompt`、`cursor-prompt`
+- `docs audit`、`handoff check`、`spine audit`、`knowledge curate`
+
+## 验证 Preset
+
+Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
+
+```bash
+bash scripts/ci.sh
+```

package/docs/production-readiness.md

@@ -1,96 +1,96 @@
-# Production Readiness v0.1
-
-本文档冻结 2026-07-06 至 2026-07-12 hardening sprint 的单任务 production readiness 标准。
-
-`loop-agent` production readiness v0.1 指：低/中风险的仓库本地 DAG 任务能以稳定、可解释、可验证、可恢复的方式运行。这不是组织级平台 readiness 声明。
-
-## 支持范围
-
-- 单仓库
-- 单任务或小范围有边界任务
-- 低/中风险的代码与文档变更
-- 显式 task source
-- 显式 `allowedPaths`、`forbiddenPaths`、`writeSet`
-- shell 验证命令
-- 通过 `dag report`、`dag doctor`、`promote-run`、`closeout` 交接
-
-## 非目标
-
-- 自动 merge
-- 自动 release
-- 生产 secrets
-- 生产数据库访问
-- 高风险 migration
-- 在线 Worker Pool
-- 多仓库 feature 编排
-- 可写的 Dynamic Workflow sharded migration
-- DAG runtime 之外的第二套 runner
-
-## 必需证据
-
-每个 production-ready v0.1 任务必须保留或产出以下证据：
-
-| 证据 | 要求 |
-|---|---|
-| DAG spec path | 生成的 DAG JSON 路径记录在 CLI 输出、report 或 task artifacts 中 |
-| DAG validation result | `dag validate --strict-models --strict-governance` 有新鲜输出 |
-| Run id | `run-dag` 打印或记录 run id |
-| Shell verification output | 完成声明引用新鲜命令输出，而非 model 自报 |
-| Failure category | 失败 run 在可用时具备 raw、normalized、product-line 与 recommended follow-up 字段 |
-| Closeout 或 failure handoff | 成功 run 可 promote 并 closeout；失败 run 产出 failure handoff 证据而非成功 closeout |
-
-## 必需命令
-
-标准任务路径：
-
-```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 .
-loop-agent dag report --run-id <run-id> --markdown
-loop-agent dag doctor --run-id <run-id>
-loop-agent promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
-```
-
-`<temp-dir>` 使用平台原生临时目录。
-
-## 必需标准
-
-| ID | 标准 | 验收 |
-|---|---|---|
-| PRD-01 | 新任务仅推荐 DAG 路径 | README、docs、website、skills 不把已移除的 Level 1 顺序命令当作 fallback |
-| PRD-02 | 写任务有显式边界 | strict DAG governance 在需要时拒绝缺失 `allowedPaths`、`forbiddenPaths` 或 `writeSet` |
-| PRD-03 | 每次 DAG run 有可读 report | `loop-agent dag report --latest --markdown` 显示 status、failure summary 与 next step |
-| PRD-04 | 失败 run 可诊断 | `loop-agent dag doctor` 报告 category 与 recommended follow-up |
-| PRD-05 | Shell 验证是完成权威 | closeout 不接受 model 自报替代新鲜命令输出 |
-| PRD-06 | Failure category 覆盖失败 fixture | validation、write guard、shell、timeout、auth、unknown fixture 均有映射 |
-| PRD-07 | 已完成 DAG facts 不可变 | completed facts guard 仍由测试覆盖 |
-| PRD-08 | CLI 主路径输出指引下一步 | `dag run-task`、`dag validate`、`run-dag`、`dag report` 打印 operator next commands |
-| PRD-09 | 文档面一致 | doc 更新后 `bash scripts/check-repo.sh` 与 `npm run docs:build` 通过 |
-| PRD-10 | sprint 完成前完整本地门禁通过 | 最终 hardening closeout 时 `bash scripts/ci.sh` 通过 |
-
-## Failure Routing
-
-Failure category 是路由字段，不是主任务状态。保留 raw DAG facts，仅在 report、doctor 输出、closeout draft、task artifacts 或后续 Task Pool 记录中追加派生字段。
-
-四层结构：
-
-```text
-raw_failure_category
-dag_normalized_failure_category
-product_line_failure_category
-recommended_follow_up
-```
-
-Product-line category 事实源：`docs/design/state-and-failure-taxonomy.md`。
-
-## Sprint Gate
-
-2026-07-06 sprint 仅在 active execution plan 记录以下内容时视为完成：
-
-- M1–M4 最终状态
-- 必需验证门禁的命令输出
-- 成功、write-guard、shell-failure 场景的 dogfood 证据
-- 剩余风险与后续工作
+# Production Readiness v0.1
+
+本文档冻结 2026-07-06 至 2026-07-12 hardening sprint 的单任务 production readiness 标准。
+
+`loop-agent` production readiness v0.1 指：低/中风险的仓库本地 DAG 任务能以稳定、可解释、可验证、可恢复的方式运行。这不是组织级平台 readiness 声明。
+
+## 支持范围
+
+- 单仓库
+- 单任务或小范围有边界任务
+- 低/中风险的代码与文档变更
+- 显式 task source
+- 显式 `allowedPaths`、`forbiddenPaths`、`writeSet`
+- shell 验证命令
+- 通过 `dag report`、`dag doctor`、`promote-run`、`closeout` 交接
+
+## 非目标
+
+- 自动 merge
+- 自动 release
+- 生产 secrets
+- 生产数据库访问
+- 高风险 migration
+- 在线 Worker Pool
+- 多仓库 feature 编排
+- 可写的 Dynamic Workflow sharded migration
+- DAG runtime 之外的第二套 runner
+
+## 必需证据
+
+每个 production-ready v0.1 任务必须保留或产出以下证据：
+
+| 证据 | 要求 |
+|---|---|
+| DAG spec path | 生成的 DAG JSON 路径记录在 CLI 输出、report 或 task artifacts 中 |
+| DAG validation result | `dag validate --strict-models --strict-governance` 有新鲜输出 |
+| Run id | `run-dag` 打印或记录 run id |
+| Shell verification output | 完成声明引用新鲜命令输出，而非 model 自报 |
+| Failure category | 失败 run 在可用时具备 raw、normalized、product-line 与 recommended follow-up 字段 |
+| Closeout 或 failure handoff | 成功 run 可 promote 并 closeout；失败 run 产出 failure handoff 证据而非成功 closeout |
+
+## 必需命令
+
+标准任务路径：
+
+```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 .
+loop-agent dag report --run-id <run-id> --markdown
+loop-agent dag doctor --run-id <run-id>
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`<temp-dir>` 使用平台原生临时目录。
+
+## 必需标准
+
+| ID | 标准 | 验收 |
+|---|---|---|
+| PRD-01 | 新任务仅推荐 DAG 路径 | README、docs、website、skills 不把已移除的 Level 1 顺序命令当作 fallback |
+| PRD-02 | 写任务有显式边界 | strict DAG governance 在需要时拒绝缺失 `allowedPaths`、`forbiddenPaths` 或 `writeSet` |
+| PRD-03 | 每次 DAG run 有可读 report | `loop-agent dag report --latest --markdown` 显示 status、failure summary 与 next step |
+| PRD-04 | 失败 run 可诊断 | `loop-agent dag doctor` 报告 category 与 recommended follow-up |
+| PRD-05 | Shell 验证是完成权威 | closeout 不接受 model 自报替代新鲜命令输出 |
+| PRD-06 | Failure category 覆盖失败 fixture | validation、write guard、shell、timeout、auth、unknown fixture 均有映射 |
+| PRD-07 | 已完成 DAG facts 不可变 | completed facts guard 仍由测试覆盖 |
+| PRD-08 | CLI 主路径输出指引下一步 | `dag run-task`、`dag validate`、`run-dag`、`dag report` 打印 operator next commands |
+| PRD-09 | 文档面一致 | doc 更新后 `bash scripts/check-repo.sh` 与 `npm run docs:build` 通过 |
+| PRD-10 | sprint 完成前完整本地门禁通过 | 最终 hardening closeout 时 `bash scripts/ci.sh` 通过 |
+
+## Failure Routing
+
+Failure category 是路由字段，不是主任务状态。保留 raw DAG facts，仅在 report、doctor 输出、closeout draft、task artifacts 或后续 Task Pool 记录中追加派生字段。
+
+四层结构：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+Product-line category 事实源：`docs/design/state-and-failure-taxonomy.md`。
+
+## Sprint Gate
+
+2026-07-06 sprint 仅在 active execution plan 记录以下内容时视为完成：
+
+- M1–M4 最终状态
+- 必需验证门禁的命令输出
+- 成功、write-guard、shell-failure 场景的 dogfood 证据
+- 剩余风险与后续工作

package/docs/progress/README.md

@@ -1,3 +1,3 @@
-# 进度日志
-
-本目录存放应超越聊天上下文的简洁 handoff 日志。
+# 进度日志
+
+本目录存放应超越聊天上下文的简洁 handoff 日志。

package/docs/reports/README.md

@@ -1,5 +1,5 @@
-# 报告
-
-本目录存放验证、审计、benchmark 与 closeout 报告。
-
-- [`2026-07-12-production-readiness-hardening.md`](2026-07-12-production-readiness-hardening.md)
+# 报告
+
+本目录存放验证、审计、benchmark 与 closeout 报告。
+
+- [`2026-07-12-production-readiness-hardening.md`](2026-07-12-production-readiness-hardening.md)

package/docs/skills/README.md

@@ -1,6 +1,6 @@
-# Skill Registry
-
-This directory records repo-local skill wrappers and vetting notes used by Agent DAG role mapping.
-
-- `vetted-skill-registry.md` — supported roles, source inspiration, risk notes, and default/optional usage.
-
+# Skill Registry
+
+This directory records repo-local skill wrappers and vetting notes used by Agent DAG role mapping.
+
+- `vetted-skill-registry.md` — supported roles, source inspiration, risk notes, and default/optional usage.
+

package/docs/skills/vetted-skill-registry.md

@@ -1,26 +1,26 @@
-# Vetted Skill Registry
-
-This registry records repo-local skills that may be referenced by default DAG role mapping or task/profile-specific `skills`.
-
-The entries below are local wrappers or existing local skills. They are not wholesale vendored copies of third-party skill repositories.
-
-| Skill | Source / Inspiration | Local Path | Supported Roles | Default Use | Risk Notes |
-|---|---|---|---|---|---|
-| `ai-engineering-context` | local existing | `skills/ai-engineering-context/SKILL.md` | scout, default context | default/scout | Read-only engineering context; not a private platform memory skill. |
-| `loop-agent` | local existing | `skills/loop-agent/SKILL.md` | planner, supervisor, closeout | planner/closeout | Long references may be resolved by strict audit with expanded budget; executor behavior unchanged. |
-| `verification-before-completion` | local wrapper inspired by verification discipline | `skills/verification-before-completion/SKILL.md` | implementer, verifier, closeout | implementer/verifier/closeout | Requires shell evidence before completion claims. |
-| `systematic-debugging` | local wrapper inspired by systematic debugging discipline | `skills/systematic-debugging/SKILL.md` | implementer, verifier | verifier | Advisory prompt guidance only; does not run tools by itself. |
-| `requesting-code-review` | local existing | `skills/requesting-code-review/SKILL.md` | reviewer | reviewer | Review prompt guidance only. |
-| `test-driven-development` | local wrapper inspired by TDD practice | `skills/test-driven-development/SKILL.md` | implementer | implementer | Does not force tests in mechanical-only docs changes; implementer still follows task contract. |
+# Vetted Skill Registry
+
+This registry records repo-local skills that may be referenced by default DAG role mapping or task/profile-specific `skills`.
+
+The entries below are local wrappers or existing local skills. They are not wholesale vendored copies of third-party skill repositories.
+
+| Skill | Source / Inspiration | Local Path | Supported Roles | Default Use | Risk Notes |
+|---|---|---|---|---|---|
+| `ai-engineering-context` | local existing | `skills/ai-engineering-context/SKILL.md` | scout, default context | default/scout | Read-only engineering context; not a private platform memory skill. |
+| `loop-agent` | local existing | `skills/loop-agent/SKILL.md` | planner, supervisor, closeout | planner/closeout | Long references may be resolved by strict audit with expanded budget; executor behavior unchanged. |
+| `verification-before-completion` | local wrapper inspired by verification discipline | `skills/verification-before-completion/SKILL.md` | implementer, verifier, closeout | implementer/verifier/closeout | Requires shell evidence before completion claims. |
+| `systematic-debugging` | local wrapper inspired by systematic debugging discipline | `skills/systematic-debugging/SKILL.md` | implementer, verifier | verifier | Advisory prompt guidance only; does not run tools by itself. |
+| `requesting-code-review` | local existing | `skills/requesting-code-review/SKILL.md` | reviewer | reviewer | Review prompt guidance only. |
+| `test-driven-development` | local wrapper inspired by TDD practice | `skills/test-driven-development/SKILL.md` | implementer | implementer | Does not force tests in mechanical-only docs changes; implementer still follows task contract. |
 | `code-review-core` | local wrapper inspired by code review practice | `skills/code-review-core/SKILL.md` | reviewer | reviewer | No external tools or network by default. |
 | `codebase-scout` | local wrapper | `skills/codebase-scout/SKILL.md` | scout | scout | Read-only reconnaissance guidance. |
 | `init-capability-evolution` | local wrapper | `skills/init-capability-evolution/SKILL.md` | supervisor, maintenance | optional | Used only when changes may affect target-project initialization, package surface, or init projection rules. |
 | `webapp-testing` | local wrapper inspired by frontend/browser testing practice | `skills/webapp-testing/SKILL.md` | verifier, reviewer | optional | Only applies when task explicitly involves browser-rendered behavior; no default Playwright/Semgrep execution. |
-
-## Vetting Rules
-
-- Default role mappings may reference only repo-local skills that resolve cleanly under `dag validate --strict-skills`.
-- Optional/security/web skills remain task- or profile-specific until their tool, network, credential, and write behavior is reviewed.
-- This registry records source inspiration, not license clearance for vendored third-party content. Vendoring requires a separate license/security review.
-- `SKILL.md` is the entry point. References must be declared in frontmatter and stay within the skill directory.
-
+
+## Vetting Rules
+
+- Default role mappings may reference only repo-local skills that resolve cleanly under `dag validate --strict-skills`.
+- Optional/security/web skills remain task- or profile-specific until their tool, network, credential, and write behavior is reviewed.
+- This registry records source inspiration, not license clearance for vendored third-party content. Vendoring requires a separate license/security review.
+- `SKILL.md` is the entry point. References must be declared in frontmatter and stay within the skill directory.
+

package/docs/templates/adr.md

@@ -1,60 +1,60 @@
-# ADR 模板
-
-## 标题
-
-> 建议文件名：`0001-<topic>.md`
-
-## 状态
-
-- proposed / accepted / superseded
-
-## 背景
-
-- 当前遇到的工程或架构问题是什么？
-- 为什么现在必须做决定？
-- 相关上下文、历史方案、约束有哪些？
-
-## 决策
-
-- 最终选择什么方案？
-- 明确边界、适用范围、默认行为是什么？
-
-## 备选方案
-
-1. 方案 A：
-2. 方案 B：
-3. 方案 C：
-
-## 取舍理由
-
-- 为什么选择当前方案？
-- 为什么不选其他方案？
-- 主要 trade-off 是什么？
-
-## 影响范围
-
-- 影响的代码目录：
-- 影响的文档/契约：
-- 影响的测试/脚本：
-- 影响的开发流程/harness：
-
-## 后果
-
-### 正面后果
-
-- 
-
-### 负面后果 / 成本
-
-- 
-
-## 验证与落地
-
-- 需要补哪些实现、脚本或测试：
-- 如何验证决策已经生效：
-
-## 复审条件
-
-当出现以下情况时，建议重新审视本 ADR：
-
-- 
+# ADR 模板
+
+## 标题
+
+> 建议文件名：`0001-<topic>.md`
+
+## 状态
+
+- proposed / accepted / superseded
+
+## 背景
+
+- 当前遇到的工程或架构问题是什么？
+- 为什么现在必须做决定？
+- 相关上下文、历史方案、约束有哪些？
+
+## 决策
+
+- 最终选择什么方案？
+- 明确边界、适用范围、默认行为是什么？
+
+## 备选方案
+
+1. 方案 A：
+2. 方案 B：
+3. 方案 C：
+
+## 取舍理由
+
+- 为什么选择当前方案？
+- 为什么不选其他方案？
+- 主要 trade-off 是什么？
+
+## 影响范围
+
+- 影响的代码目录：
+- 影响的文档/契约：
+- 影响的测试/脚本：
+- 影响的开发流程/harness：
+
+## 后果
+
+### 正面后果
+
+- 
+
+### 负面后果 / 成本
+
+- 
+
+## 验证与落地
+
+- 需要补哪些实现、脚本或测试：
+- 如何验证决策已经生效：
+
+## 复审条件
+
+当出现以下情况时，建议重新审视本 ADR：
+
+-