@tea-agent/loop-agent 0.5.0 → 0.6.0

package/docs/init-surface.manifest.json

@@ -1,199 +1,205 @@
-{
-  "version": 1,
-  "description": "Machine-checked contract for files that must remain available through npm packaging and target-project initialization.",
-  "packageRequired": [
-    "AGENTS.md",
-    "CHANGELOG.md",
-    "README.md",
-    "harness.json",
-    "bin/loop-agent.js",
-    "docs/README.md",
-    "docs/init-surface.manifest.json",
-    "docs/architecture/runtime-boundaries.md",
-    "docs/skills/README.md",
-    "docs/skills/vetted-skill-registry.md",
-    "docs/templates/init-evolution-review.md",
-    "docs/templates/production-readiness-checklist.md",
-    "docs/templates/agent-dag.schema.json",
-    "examples/example-dag.json",
-    "skills/loop-agent/SKILL.md",
-    "skills/loop-agent/references/command-reference.md",
-    "skills/ai-engineering-context/SKILL.md",
-    "skills/verification-before-completion/SKILL.md",
-    "skills/systematic-debugging/SKILL.md",
-    "skills/requesting-code-review/SKILL.md",
-    "skills/codebase-scout/SKILL.md",
-    "skills/test-driven-development/SKILL.md",
-    "skills/code-review-core/SKILL.md",
-    "skills/init-capability-evolution/SKILL.md",
-    "skills/webapp-testing/SKILL.md"
-  ],
-  "initFullRequired": [
-    "README.md",
-    "AGENTS.md",
-    ".gitignore",
-    "harness.json",
-    "docs/README.md",
-    "docs/development-principles.md",
-    "docs/feature-workflow.md",
-    "docs/verification-matrix.md",
-    "docs/loop-agent-harness.md",
-    "docs/templates/init-evolution-review.md",
-    "docs/templates/production-readiness-checklist.md",
-    "scripts/check-repo.sh",
-    "scripts/ci-governance.sh",
-    "scripts/ci-tests.sh",
-    "scripts/ci.sh",
-    ".harness/prompts/analyze.md",
-    ".harness/tasks",
-    ".harness/dag-runs/active",
-    "skills/loop-agent/SKILL.md",
-    "skills/loop-agent/references/command-reference.md",
-    "skills/ai-engineering-context/SKILL.md",
-    "skills/verification-before-completion/SKILL.md",
-    "skills/systematic-debugging/SKILL.md",
-    "skills/requesting-code-review/SKILL.md",
-    "skills/codebase-scout/SKILL.md",
-    "skills/test-driven-development/SKILL.md",
-    "skills/code-review-core/SKILL.md",
-    "skills/init-capability-evolution/SKILL.md",
-    "skills/webapp-testing/SKILL.md",
-    ".agents/skills/loop-agent/SKILL.md",
-    ".agents/skills/loop-agent/references/command-reference.md",
-    ".agents/skills/ai-engineering-context/SKILL.md",
-    ".agents/skills/verification-before-completion/SKILL.md",
-    ".agents/skills/systematic-debugging/SKILL.md",
-    ".agents/skills/requesting-code-review/SKILL.md",
-    ".agents/skills/codebase-scout/SKILL.md",
-    ".agents/skills/test-driven-development/SKILL.md",
-    ".agents/skills/code-review-core/SKILL.md",
-    ".agents/skills/init-capability-evolution/SKILL.md",
-    ".agents/skills/webapp-testing/SKILL.md"
-  ],
-  "initSurface": {
-    "README.md": "managed-block",
-    "AGENTS.md": "managed-block",
-    ".gitignore": "managed-block",
-    "harness.json": "generated",
-    "docs/README.md": "generated",
-    "docs/development-principles.md": "generated",
-    "docs/feature-workflow.md": "generated",
-    "docs/verification-matrix.md": "generated",
-    "docs/loop-agent-harness.md": "generated",
-    "docs/templates/init-evolution-review.md": "copied",
-    "docs/templates/production-readiness-checklist.md": "copied",
-    "scripts/check-repo.sh": "generated",
-    "scripts/ci-governance.sh": "generated",
-    "scripts/ci-tests.sh": "generated",
-    "scripts/ci.sh": "generated",
-    ".harness/prompts/analyze.md": "generated",
-    ".harness/tasks": "directory",
-    ".harness/dag-runs/active": "directory",
-    ".harness/init-surface.json": "state",
-    "skills/loop-agent/SKILL.md": "copied",
-    "skills/loop-agent/references/command-reference.md": "copied",
-    "skills/ai-engineering-context/SKILL.md": "copied",
-    "skills/verification-before-completion/SKILL.md": "copied",
-    "skills/systematic-debugging/SKILL.md": "copied",
-    "skills/requesting-code-review/SKILL.md": "copied",
-    "skills/codebase-scout/SKILL.md": "copied",
-    "skills/test-driven-development/SKILL.md": "copied",
-    "skills/code-review-core/SKILL.md": "copied",
-    "skills/init-capability-evolution/SKILL.md": "copied",
-    "skills/webapp-testing/SKILL.md": "copied",
-    ".agents/skills/loop-agent/SKILL.md": "copied",
-    ".agents/skills/loop-agent/references/command-reference.md": "copied",
-    ".agents/skills/ai-engineering-context/SKILL.md": "copied",
-    ".agents/skills/verification-before-completion/SKILL.md": "copied",
-    ".agents/skills/systematic-debugging/SKILL.md": "copied",
-    ".agents/skills/requesting-code-review/SKILL.md": "copied",
-    ".agents/skills/codebase-scout/SKILL.md": "copied",
-    ".agents/skills/test-driven-development/SKILL.md": "copied",
-    ".agents/skills/code-review-core/SKILL.md": "copied",
-    ".agents/skills/init-capability-evolution/SKILL.md": "copied",
-    ".agents/skills/webapp-testing/SKILL.md": "copied"
-  },
-  "packageExcluded": [
-    "docs/progress/20*.md",
-    "docs/reports/20*.md",
-    "docs/exec-plans/active/20*.md",
-    "docs/exec-plans/completed/20*.md"
-  ],
-  "initExcluded": [
-    "examples/example-dag.json",
-    "docs/skills/vetted-skill-registry.md"
-  ],
-  "reviewTriggers": [
-    "AGENTS.md",
-    "README.md",
-    "CHANGELOG.md",
-    "harness.json",
-    "package.json",
-    "src/commands/init.ts",
-    "src/workflows/dag/skills.ts",
-    "src/workflows/dag/init-hybrid.ts",
-    "src/workflows/dag/skill-instructions.ts",
-    "docs/templates/**",
-    "docs/skills/**",
-    "skills/**",
-    "scripts/**"
-  ],
-  "evolutionReview": {
-    "defaultMode": "advisory",
-    "strictReportGlob": "docs/reports/*-init-evolution-review.md",
-    "tiers": [
-      {
-        "name": "model-review",
-        "severity": "high",
-        "strictRequiresReport": true,
-        "description": "Changes that may alter target-project initialization behavior, default DAG role skills, skill resolution, or package/init contracts.",
-        "patterns": [
-          "src/commands/init.ts",
-          "src/workflows/dag/skills.ts",
-          "src/workflows/dag/init-hybrid.ts",
-          "src/workflows/dag/skill-instructions.ts",
-          "src/workflows/dag/prompt.ts",
-          "src/workflows/dag/node-execution.ts",
-          "docs/init-surface.manifest.json",
-          "package.json",
-          "harness.json",
-          "AGENTS.md",
-          "README.md"
-        ]
-      },
-      {
-        "name": "surface-check",
-        "severity": "medium",
-        "strictRequiresReport": false,
-        "description": "Asset surface changes that usually need deterministic package/init smoke checks but not a model review when the checks pass.",
-        "patterns": [
-          "skills/**",
-          "docs/templates/**",
-          "docs/skills/**",
-          "scripts/check-init-surface.sh",
-          "scripts/check-repo.sh"
-        ]
-      },
-      {
-        "name": "advisory",
-        "severity": "low",
-        "strictRequiresReport": false,
-        "description": "Documentation and user-facing guidance changes that should be considered but should not slow normal iteration.",
-        "patterns": [
-          "CHANGELOG.md",
-          "website/docs/**",
-          "docs/*.md",
-          "docs/architecture/**"
-        ]
-      }
-    ],
-    "modelReviewQuestions": [
-      "Does this change alter files or guidance produced by loop-agent init --profile full --merge?",
-      "Does a new or changed skill need to be bundled, projected to target projects, or documented as optional only?",
-      "Do target-project AGENTS.md, README managed blocks, governance docs, templates, or script matrix need updates?",
-      "Does package.json files include every static asset required by the runtime and init projection?",
-      "Does docs/init-surface.manifest.json still match the intended package and init surface?",
-      "Do older initialized target projects need a migration note, manual copy guidance, or future init audit/update support?"
-    ]
-  }
-}
+{
+  "version": 1,
+  "description": "Machine-checked contract for files that must remain available through npm packaging and target-project initialization.",
+  "packageRequired": [
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "README.md",
+    "harness.json",
+    "bin/loop-agent.js",
+    "docs/README.md",
+    "docs/init-surface.manifest.json",
+    "docs/architecture/runtime-boundaries.md",
+    "docs/skills/README.md",
+    "docs/skills/vetted-skill-registry.md",
+    "docs/templates/init-evolution-review.md",
+    "docs/templates/production-readiness-checklist.md",
+    "docs/templates/worker-dogfood-setup.md",
+    "docs/templates/worker-dogfood-evidence.md",
+    "docs/templates/agent-dag.schema.json",
+    "examples/example-dag.json",
+    "skills/loop-agent/SKILL.md",
+    "skills/loop-agent/references/command-reference.md",
+    "skills/ai-engineering-context/SKILL.md",
+    "skills/verification-before-completion/SKILL.md",
+    "skills/systematic-debugging/SKILL.md",
+    "skills/requesting-code-review/SKILL.md",
+    "skills/codebase-scout/SKILL.md",
+    "skills/test-driven-development/SKILL.md",
+    "skills/code-review-core/SKILL.md",
+    "skills/init-capability-evolution/SKILL.md",
+    "skills/webapp-testing/SKILL.md"
+  ],
+  "initFullRequired": [
+    "README.md",
+    "AGENTS.md",
+    ".gitignore",
+    "harness.json",
+    "docs/README.md",
+    "docs/development-principles.md",
+    "docs/feature-workflow.md",
+    "docs/verification-matrix.md",
+    "docs/loop-agent-harness.md",
+    "docs/templates/init-evolution-review.md",
+    "docs/templates/production-readiness-checklist.md",
+    "docs/templates/worker-dogfood-setup.md",
+    "docs/templates/worker-dogfood-evidence.md",
+    "scripts/check-repo.sh",
+    "scripts/ci-governance.sh",
+    "scripts/ci-tests.sh",
+    "scripts/ci.sh",
+    ".harness/prompts/analyze.md",
+    ".harness/tasks",
+    ".harness/dag-runs/active",
+    "skills/loop-agent/SKILL.md",
+    "skills/loop-agent/references/command-reference.md",
+    "skills/ai-engineering-context/SKILL.md",
+    "skills/verification-before-completion/SKILL.md",
+    "skills/systematic-debugging/SKILL.md",
+    "skills/requesting-code-review/SKILL.md",
+    "skills/codebase-scout/SKILL.md",
+    "skills/test-driven-development/SKILL.md",
+    "skills/code-review-core/SKILL.md",
+    "skills/init-capability-evolution/SKILL.md",
+    "skills/webapp-testing/SKILL.md",
+    ".agents/skills/loop-agent/SKILL.md",
+    ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/ai-engineering-context/SKILL.md",
+    ".agents/skills/verification-before-completion/SKILL.md",
+    ".agents/skills/systematic-debugging/SKILL.md",
+    ".agents/skills/requesting-code-review/SKILL.md",
+    ".agents/skills/codebase-scout/SKILL.md",
+    ".agents/skills/test-driven-development/SKILL.md",
+    ".agents/skills/code-review-core/SKILL.md",
+    ".agents/skills/init-capability-evolution/SKILL.md",
+    ".agents/skills/webapp-testing/SKILL.md"
+  ],
+  "initSurface": {
+    "README.md": "managed-block",
+    "AGENTS.md": "managed-block",
+    ".gitignore": "managed-block",
+    "harness.json": "generated",
+    "docs/README.md": "generated",
+    "docs/development-principles.md": "generated",
+    "docs/feature-workflow.md": "generated",
+    "docs/verification-matrix.md": "generated",
+    "docs/loop-agent-harness.md": "generated",
+    "docs/templates/init-evolution-review.md": "copied",
+    "docs/templates/production-readiness-checklist.md": "copied",
+    "docs/templates/worker-dogfood-setup.md": "copied",
+    "docs/templates/worker-dogfood-evidence.md": "copied",
+    "scripts/check-repo.sh": "generated",
+    "scripts/ci-governance.sh": "generated",
+    "scripts/ci-tests.sh": "generated",
+    "scripts/ci.sh": "generated",
+    ".harness/prompts/analyze.md": "generated",
+    ".harness/tasks": "directory",
+    ".harness/dag-runs/active": "directory",
+    ".harness/init-surface.json": "state",
+    "skills/loop-agent/SKILL.md": "copied",
+    "skills/loop-agent/references/command-reference.md": "copied",
+    "skills/ai-engineering-context/SKILL.md": "copied",
+    "skills/verification-before-completion/SKILL.md": "copied",
+    "skills/systematic-debugging/SKILL.md": "copied",
+    "skills/requesting-code-review/SKILL.md": "copied",
+    "skills/codebase-scout/SKILL.md": "copied",
+    "skills/test-driven-development/SKILL.md": "copied",
+    "skills/code-review-core/SKILL.md": "copied",
+    "skills/init-capability-evolution/SKILL.md": "copied",
+    "skills/webapp-testing/SKILL.md": "copied",
+    ".agents/skills/loop-agent/SKILL.md": "copied",
+    ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/ai-engineering-context/SKILL.md": "copied",
+    ".agents/skills/verification-before-completion/SKILL.md": "copied",
+    ".agents/skills/systematic-debugging/SKILL.md": "copied",
+    ".agents/skills/requesting-code-review/SKILL.md": "copied",
+    ".agents/skills/codebase-scout/SKILL.md": "copied",
+    ".agents/skills/test-driven-development/SKILL.md": "copied",
+    ".agents/skills/code-review-core/SKILL.md": "copied",
+    ".agents/skills/init-capability-evolution/SKILL.md": "copied",
+    ".agents/skills/webapp-testing/SKILL.md": "copied"
+  },
+  "packageExcluded": [
+    "docs/progress/20*.md",
+    "docs/reports/20*.md",
+    "docs/exec-plans/active/20*.md",
+    "docs/exec-plans/completed/20*.md"
+  ],
+  "initExcluded": [
+    "examples/example-dag.json",
+    "docs/skills/vetted-skill-registry.md"
+  ],
+  "reviewTriggers": [
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "harness.json",
+    "package.json",
+    "src/commands/init.ts",
+    "src/workflows/dag/skills.ts",
+    "src/workflows/dag/init-hybrid.ts",
+    "src/workflows/dag/skill-instructions.ts",
+    "docs/templates/**",
+    "docs/skills/**",
+    "skills/**",
+    "scripts/**"
+  ],
+  "evolutionReview": {
+    "defaultMode": "advisory",
+    "strictReportGlob": "docs/reports/*-init-evolution-review.md",
+    "tiers": [
+      {
+        "name": "model-review",
+        "severity": "high",
+        "strictRequiresReport": true,
+        "description": "Changes that may alter target-project initialization behavior, default DAG role skills, skill resolution, or package/init contracts.",
+        "patterns": [
+          "src/commands/init.ts",
+          "src/workflows/dag/skills.ts",
+          "src/workflows/dag/init-hybrid.ts",
+          "src/workflows/dag/skill-instructions.ts",
+          "src/workflows/dag/prompt.ts",
+          "src/workflows/dag/node-execution.ts",
+          "docs/init-surface.manifest.json",
+          "package.json",
+          "harness.json",
+          "AGENTS.md",
+          "README.md"
+        ]
+      },
+      {
+        "name": "surface-check",
+        "severity": "medium",
+        "strictRequiresReport": false,
+        "description": "Asset surface changes that usually need deterministic package/init smoke checks but not a model review when the checks pass.",
+        "patterns": [
+          "skills/**",
+          "docs/templates/**",
+          "docs/skills/**",
+          "scripts/check-init-surface.sh",
+          "scripts/check-repo.sh"
+        ]
+      },
+      {
+        "name": "advisory",
+        "severity": "low",
+        "strictRequiresReport": false,
+        "description": "Documentation and user-facing guidance changes that should be considered but should not slow normal iteration.",
+        "patterns": [
+          "CHANGELOG.md",
+          "website/docs/**",
+          "docs/*.md",
+          "docs/architecture/**"
+        ]
+      }
+    ],
+    "modelReviewQuestions": [
+      "Does this change alter files or guidance produced by loop-agent init --profile full --merge?",
+      "Does a new or changed skill need to be bundled, projected to target projects, or documented as optional only?",
+      "Do target-project AGENTS.md, README managed blocks, governance docs, templates, or script matrix need updates?",
+      "Does package.json files include every static asset required by the runtime and init projection?",
+      "Does docs/init-surface.manifest.json still match the intended package and init surface?",
+      "Do older initialized target projects need a migration note, manual copy guidance, or future init audit/update support?"
+    ]
+  }
+}

package/docs/loop-agent-harness.md

@@ -1,42 +1,55 @@
-# 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 文件
+- `.task-pool/` — `agent-worker` 的 Task Pool state、batch artifacts、failure handoffs 与 Observe events；它与 `.harness/` 分离，默认不提交
+
+## 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`
+- `agent-worker task validate|explain-profile|retry`、`agent-worker batch run-ready`、`agent-worker report morning`、`agent-worker observe serve|snapshot`
+
+## Worker Retry
+
+失败 Task Pool task 必须显式 retry，不能删除旧 `.task-pool/runs/runs.jsonl` 或复用失败的 `workerRunId`：
+
+```bash
+agent-worker task retry <task-id> --repo <target-repo> --reason "provider configuration corrected"
+agent-worker batch run-ready --feature-dir <feature-dir> --repo <target-repo>
+```
+
+`task retry` 只接受 `Failed` state，保留旧 run 和 failure handoff，并写入 `retryOfWorkerRunId`。下一次 `run-ready` 生成新的 `workerRunId`；`Blocked`、`Done` 或无 state 的 task 必须先由 operator 处理根因，不能盲目重试。
+
+## 验证 Preset
+
+Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
+
+```bash
+bash scripts/ci.sh
+```