@tea-agent/loop-agent 0.1.0 → 0.2.1

package/docs/templates/hybrid-dag.json

@@ -1,193 +1,193 @@
-{
-  "version": 2,
-  "title": "Hybrid DAG 示例：Pi 只读契约 + 并行侦察 + Pi 写入配置实现",
-  "objective": "演示 v2 hybrid DAG：Pi 节点返回只读契约/审查结论，Pi writer 节点通过 toolProfile=write 执行受控独占实现，shell 节点负责确定性验证。",
-  "successCriteria": [
-    "contract-pi 返回可审计的只读实现契约摘要",
-    "scout-src 与 scout-tests 并行只读侦察且互不写冲突",
-    "implement-core 仅在声明的 writeSet 内修改代码",
-    "review-pi 基于上游输出完成只读审查",
-    "verify-shell 归档确定性验证命令输出",
-    "dag validate 校验通过且 ranks 符合依赖拓扑"
-  ],
-  "globalConstraints": [
-    "Do not commit runtime traces under .harness/dag-runs/",
-    "Do not enable cross-node Pi runtime reuse by default",
-    "Preserve CODE_AGENT_PI_BACKEND=cli-only rollback for Pi nodes",
-    "Every task must explicitly declare executor; defaults.executor is schema-only and not a runtime fallback",
-    "Prefer same-rank parallel read-only scouts over serial chains when outputs are independent",
-    "Add depends_on only when a child truly needs upstream output; challenge single-chain topologies during review",
-    "Same-rank exclusive writeSet entries must be disjoint",
-    "exclusive implementer nodes must use narrow, concrete writeSet paths; never use ** or repo root",
-    "Cursor remains an explicit optional executor; no-Cursor environments use Pi read-only scouts and Pi writer nodes with toolProfile=write",
-    "Read-only nodes must not write root artifacts/**; root artifacts/ is reserved for explicit exclusive write nodes"
-  ],
-  "defaults": {
-    "executor": "pi",
-    "contextProfile": "slim",
-    "skills": [
-      "ai-engineering-context"
-    ],
-    "writePolicy": "read-only"
-  },
-  "skillsByRole": {
-    "planner": [
-      "loop-agent"
-    ],
-    "scout": [
-      "ai-engineering-context"
-    ],
-    "implementer": [
-      "verification-before-completion"
-    ],
-    "reviewer": [
-      "requesting-code-review"
-    ],
-    "verifier": [
-      "verification-before-completion",
-      "systematic-debugging"
-    ],
-    "closeout": [
-      "loop-agent",
-      "verification-before-completion"
-    ]
-  },
-  "executorModels": {
-    "cursor": {
-      "LOW": "composer-2.5",
-      "MED": "composer-2.5",
-      "HIGH": "composer-2.5"
-    },
-    "pi": {
-      "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
-      "HIGH": "gpt-5.5"
-    }
-  },
-  "tasks": [
-    {
-      "id": "contract-pi",
-      "depends_on": [],
-      "role": "planner",
-      "executor": "pi",
-      "complexity": "MED",
-      "writePolicy": "read-only",
-      "allowedPaths": [
-        "./**",
-        "docs/**"
-      ],
-      "forbiddenPaths": [
-        ".harness/**",
-        "artifacts/**"
-      ],
-      "outputContract": "Plain Markdown implementation contract summary; no file writes.",
-      "subtask_prompt": "阅读 ./README.md 与 docs/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
-    },
-    {
-      "id": "scout-src",
-      "depends_on": [
-        "contract-pi"
-      ],
-      "role": "scout",
-      "executor": "pi",
-      "complexity": "LOW",
-      "writePolicy": "read-only",
-      "allowedPaths": [
-        "./src/workflows/dag/**"
-      ],
-      "forbiddenPaths": [
-        ".harness/**",
-        "artifacts/**"
-      ],
-      "outputContract": "Plain Markdown reconnaissance summary of DAG-related source modules; no file writes.",
-      "subtask_prompt": "只读审计 ./src/workflows/dag/ 中与 DAG 相关的模块，列出关键文件与职责（不要改文件）。"
-    },
-    {
-      "id": "scout-tests",
-      "depends_on": [
-        "contract-pi"
-      ],
-      "role": "scout",
-      "executor": "pi",
-      "complexity": "LOW",
-      "writePolicy": "read-only",
-      "allowedPaths": [
-        "./test/**"
-      ],
-      "forbiddenPaths": [
-        ".harness/**",
-        "artifacts/**"
-      ],
-      "outputContract": "Plain Markdown test coverage gap summary; no file writes.",
-      "subtask_prompt": "只读审计 ./test/ 中与 dag-runner 相关的测试覆盖，列出缺口建议（不要改文件）。"
-    },
-    {
-      "id": "implement-core",
-      "depends_on": [
-        "scout-src",
-        "scout-tests"
-      ],
-      "role": "implementer",
-      "executor": "pi",
-      "complexity": "HIGH",
-      "writePolicy": "exclusive",
-      "writeSet": [
-        "./src/workflows/dag/runner.ts"
-      ],
-      "allowedPaths": [
-        "./src/workflows/dag/**"
-      ],
-      "forbiddenPaths": [
-        ".harness/**",
-        "artifacts/**"
-      ],
-      "outputContract": "Implementation summary with changed files, tests run, and residual risks.",
-      "subtask_prompt": "基于上游侦察结果，在 writeSet 范围内做最小必要改动并说明风险（若无需改动则输出 no-op 理由）。",
-      "toolProfile": "write"
-    },
-    {
-      "id": "review-pi",
-      "depends_on": [
-        "implement-core"
-      ],
-      "role": "reviewer",
-      "executor": "pi",
-      "complexity": "MED",
-      "writePolicy": "read-only",
-      "allowedPaths": [
-        "./**",
-        "docs/**"
-      ],
-      "forbiddenPaths": [
-        ".harness/**",
-        "artifacts/**"
-      ],
-      "outputContract": "Plain Markdown review summary; no file writes.",
-      "subtask_prompt": "审查上游实现与侦察结论是否一致，列出范围漂移、验证缺口与残余风险（只读，不改文件/文档/artifacts）。"
-    },
-    {
-      "id": "verify-shell",
-      "depends_on": [
-        "implement-core"
-      ],
-      "role": "verifier",
-      "executor": "shell",
-      "complexity": "LOW",
-      "writePolicy": "read-only",
-      "allowedPaths": [
-        "./**"
-      ],
-      "forbiddenPaths": [
-        ".harness/**",
-        "artifacts/**"
-      ],
-      "outputContract": "Archived shell verification stdout/stderr with exit codes; no worktree writes.",
-      "subtask_prompt": "Run deterministic loop-agent verification and archive command outputs.",
-      "shell": {
-        "preset": "loop-agent-standard-verify",
-        "cwd": ".",
-        "timeoutMs": 300000
-      }
-    }
-  ]
-}
+{
+  "version": 2,
+  "title": "Hybrid DAG 示例：Pi 只读契约 + 并行侦察 + Pi 写入配置实现",
+  "objective": "演示 v2 hybrid DAG：Pi 节点返回只读契约/审查结论，Pi writer 节点通过 toolProfile=write 执行受控独占实现，shell 节点负责确定性验证。",
+  "successCriteria": [
+    "contract-pi 返回可审计的只读实现契约摘要",
+    "scout-src 与 scout-tests 并行只读侦察且互不写冲突",
+    "implement-core 仅在声明的 writeSet 内修改代码",
+    "review-pi 基于上游输出完成只读审查",
+    "verify-shell 归档确定性验证命令输出",
+    "dag validate 校验通过且 ranks 符合依赖拓扑"
+  ],
+  "globalConstraints": [
+    "Do not commit runtime traces under .harness/dag-runs/",
+    "Do not enable cross-node Pi runtime reuse by default",
+    "Preserve CODE_AGENT_PI_BACKEND=cli-only rollback for Pi nodes",
+    "Every task must explicitly declare executor; defaults.executor is schema-only and not a runtime fallback",
+    "Prefer same-rank parallel read-only scouts over serial chains when outputs are independent",
+    "Add depends_on only when a child truly needs upstream output; challenge single-chain topologies during review",
+    "Same-rank exclusive writeSet entries must be disjoint",
+    "exclusive implementer nodes must use narrow, concrete writeSet paths; never use ** or repo root",
+    "Cursor remains an explicit optional executor; no-Cursor environments use Pi read-only scouts and Pi writer nodes with toolProfile=write",
+    "Read-only nodes must not write root artifacts/**; root artifacts/ is reserved for explicit exclusive write nodes"
+  ],
+  "defaults": {
+    "executor": "pi",
+    "contextProfile": "slim",
+    "skills": [
+      "ai-engineering-context"
+    ],
+    "writePolicy": "read-only"
+  },
+  "skillsByRole": {
+    "planner": [
+      "loop-agent"
+    ],
+    "scout": [
+      "ai-engineering-context"
+    ],
+    "implementer": [
+      "verification-before-completion"
+    ],
+    "reviewer": [
+      "requesting-code-review"
+    ],
+    "verifier": [
+      "verification-before-completion",
+      "systematic-debugging"
+    ],
+    "closeout": [
+      "loop-agent",
+      "verification-before-completion"
+    ]
+  },
+  "executorModels": {
+    "cursor": {
+      "LOW": "composer-2.5",
+      "MED": "composer-2.5",
+      "HIGH": "composer-2.5"
+    },
+    "pi": {
+      "LOW": "gpt-5.3-codex-spark",
+      "MED": "glm-5.2",
+      "HIGH": "gpt-5.5"
+    }
+  },
+  "tasks": [
+    {
+      "id": "contract-pi",
+      "depends_on": [],
+      "role": "planner",
+      "executor": "pi",
+      "complexity": "MED",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**",
+        "docs/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown implementation contract summary; no file writes.",
+      "subtask_prompt": "阅读 ./README.md 与 docs/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
+    },
+    {
+      "id": "scout-src",
+      "depends_on": [
+        "contract-pi"
+      ],
+      "role": "scout",
+      "executor": "pi",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./src/workflows/dag/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown reconnaissance summary of DAG-related source modules; no file writes.",
+      "subtask_prompt": "只读审计 ./src/workflows/dag/ 中与 DAG 相关的模块，列出关键文件与职责（不要改文件）。"
+    },
+    {
+      "id": "scout-tests",
+      "depends_on": [
+        "contract-pi"
+      ],
+      "role": "scout",
+      "executor": "pi",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./test/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown test coverage gap summary; no file writes.",
+      "subtask_prompt": "只读审计 ./test/ 中与 dag-runner 相关的测试覆盖，列出缺口建议（不要改文件）。"
+    },
+    {
+      "id": "implement-core",
+      "depends_on": [
+        "scout-src",
+        "scout-tests"
+      ],
+      "role": "implementer",
+      "executor": "pi",
+      "complexity": "HIGH",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "./src/workflows/dag/runner.ts"
+      ],
+      "allowedPaths": [
+        "./src/workflows/dag/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Implementation summary with changed files, tests run, and residual risks.",
+      "subtask_prompt": "基于上游侦察结果，在 writeSet 范围内做最小必要改动并说明风险（若无需改动则输出 no-op 理由）。",
+      "toolProfile": "write"
+    },
+    {
+      "id": "review-pi",
+      "depends_on": [
+        "implement-core"
+      ],
+      "role": "reviewer",
+      "executor": "pi",
+      "complexity": "MED",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**",
+        "docs/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown review summary; no file writes.",
+      "subtask_prompt": "审查上游实现与侦察结论是否一致，列出范围漂移、验证缺口与残余风险（只读，不改文件/文档/artifacts）。"
+    },
+    {
+      "id": "verify-shell",
+      "depends_on": [
+        "implement-core"
+      ],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Archived shell verification stdout/stderr with exit codes; no worktree writes.",
+      "subtask_prompt": "Run deterministic loop-agent verification and archive command outputs.",
+      "shell": {
+        "preset": "loop-agent-standard-verify",
+        "cwd": ".",
+        "timeoutMs": 300000
+      }
+    }
+  ]
+}

package/docs/templates/production-readiness-checklist.md

@@ -0,0 +1,57 @@
+# Production Readiness 检查清单
+
+声称 Production Readiness v0.1 的低/中风险单仓库 DAG 任务使用本清单。
+
+## 范围
+
+- [ ] 单仓库
+- [ ] 单任务或小范围有边界任务
+- [ ] 低或中风险
+- [ ] 无生产 secret 或生产数据库访问
+- [ ] 无自动 merge 或 release
+- [ ] 无 DAG runtime 之外的第二套 runner
+- [ ] 无可写 Dynamic Workflow sharded migration
+
+## Task Contract
+
+- [ ] Task source 存在于 `.harness/tasks/<task-id>/source/`
+- [ ] `allowedPaths` 显式
+- [ ] `forbiddenPaths` 显式
+- [ ] `writeSet` 或预期写 scope 显式
+- [ ] Shell 验证命令显式
+- [ ] 非目标显式
+
+## DAG 主路径
+
+- [ ] 已运行 `loop-agent new-task <task-id> "Task title"` 或 task 已存在
+- [ ] `loop-agent dag run-task <task-id> --profile auto --strict-models --output <dag-path>` 产出 DAG spec
+- [ ] `loop-agent dag validate --dag <dag-path> --strict-models --strict-governance` 通过
+- [ ] `loop-agent run-dag --dag <dag-path> --cwd .` 产出 run id
+- [ ] `loop-agent dag report --run-id <run-id> --markdown` 可读
+- [ ] `loop-agent dag doctor --run-id <run-id>` 能解释失败或 paused run
+
+## 证据
+
+- [ ] 记录 DAG spec path
+- [ ] 记录 DAG validation 输出
+- [ ] 记录 run id
+- [ ] Shell 验证输出是新鲜的
+- [ ] 成功路径有 promotion 与 closeout 证据
+- [ ] 失败路径有 failure handoff 证据
+
+## Failure Routing
+
+- [ ] 存在时保留 raw failure category
+- [ ] 失败 run 有 DAG normalized failure category
+- [ ] 失败 run 有 product-line failure category
+- [ ] 失败 run 有 recommended follow-up
+- [ ] 派生 category 未覆盖已完成 DAG facts
+- [ ] `Unknown` 已说明或为 fixture 有意接受
+
+## 最终门禁
+
+- [ ] `npm run typecheck`
+- [ ] 相关定向 Vitest 文件
+- [ ] `bash scripts/check-repo.sh`
+- [ ] website/docs 变更时 `npm run docs:build`
+- [ ] 最终 sprint closeout 前 `bash scripts/ci.sh`

package/docs/templates/progress-log.md

@@ -1,17 +1,17 @@
-# Progress Log Template
+# 进度日志模板
 
-## Date / Session
+## 日期 / 会话
 
-## What Changed
+## 变更内容
 
-## What Was Verified
+## 已验证项
 
-## Newly Discovered Bugs / Debt / Drift
+## 新发现的 Bug / 技术债 / 漂移
 
 - Bugs:
 - Debt:
 - Drift:
 
-## Known Gaps / Risks
+## 已知缺口 / 风险
 
-## Next Recommended Step
+## 推荐下一步

package/docs/templates/project-start-checklist.md

@@ -1,9 +1,9 @@
-# Project Start Checklist
+# 项目开工检查清单
 
-- [ ] Confirm `pwd`.
-- [ ] Read `README.md`, `harness.json`, and `docs/README.md`.
-- [ ] Check `git status --short --branch`.
-- [ ] Identify the single work block.
-- [ ] Select verification commands from `docs/verification-matrix.md`.
-- [ ] Preserve unrelated user changes.
-- [ ] Record handoff evidence if the work is non-trivial.
+- [ ] 确认 `pwd`
+- [ ] 阅读 `README.md`、`harness.json`、`docs/README.md`
+- [ ] 检查 `git status --short --branch`
+- [ ] 确定单一工作块
+- [ ] 从 `docs/verification-matrix.md` 选择验证命令
+- [ ] 保留无关用户变更
+- [ ] 非平凡工作时记录 handoff 证据

package/docs/templates/qa-report.md

@@ -1,19 +1,19 @@
-# QA Report Template
+# QA 报告模板
 
-## Date / Session
+## 日期 / 会话
 
-## Scope Under Test
+## 测试范围
 
-## Related Contract / Plan
+## 相关 Contract / Plan
 
-## Test Method
+## 测试方法
 
 - 自动化测试：
 - 构建 / 类型检查：
 - Smoke / 手工路径：
 - 其他证据：
 
-## Smoke / Manual Checks
+## Smoke / 手工检查
 
 - CLI smoke：
 - DAG smoke：
@@ -21,22 +21,28 @@
 - Executor smoke：
 - 结果：pass / blocked / fail
 
-## Pass Criteria
+## 通过标准
 
-## Findings
+## 发现项
 
 | ID | Severity | Finding | Evidence | Suggested Fix |
 |----|----------|---------|----------|---------------|
 
-## Newly Discovered Bugs / Drift
+## Failure Routing
+
+| Run / Scenario | Raw Failure | DAG Normalized Category | Product-line Category | Recommended Follow-up | Evidence |
+|---|---|---|---|---|---|
+|  |  |  |  |  |  |
+
+## 新发现的 Bug / 漂移
 
 - 新发现 bug：
 - 发现的契约漂移：
 - 发现的文档/测试不一致：
 
-## Final Verdict
+## 最终结论
 
 - 结论：pass / partial / fail
 - 结论依据：
 
-## Follow-up Items
+## 后续项

package/docs/templates/sprint-contract.md

@@ -1,29 +1,29 @@
 # Sprint Contract
 
-## Objective
+## 目标（Objective）
 
-Describe the bounded work block.
+描述有边界的工作块。
 
-## Deliverables
+## 交付物（Deliverables）
 
 - 
 
-## Non-goals
+## 非目标（Non-goals）
 
 - 
 
-## Verification
-
-```bash
-bash scripts/check-repo.sh
-npm run typecheck
-npm test
-```
-
-On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Use platform-native paths for actual file operations.
-
-## Failure Conditions
-
-- Required verification cannot run or fails.
-- The work requires scope outside this contract.
-- The implementation changes unrelated files.
+## 验证（Verification）
+
+```bash
+bash scripts/check-repo.sh
+npm run typecheck
+npm test
+```
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作用平台原生路径。
+
+## 失败条件（Failure Conditions）
+
+- 必需验证无法运行或失败
+- 工作需要超出本 contract 的范围
+- 实现改动了无关文件