@tea-agent/loop-agent 0.2.0 → 0.3.0

package/docs/verification-matrix.md

@@ -1,30 +1,41 @@
-# Verification Matrix
+# 验证矩阵
 
-Use the narrowest command that proves the claim.
+用能证明声明的最窄命令。
 
-| Change type | Minimum verification | Stronger verification |
+| 变更类型 | 最低验证 | 更强验证 |
 |---|---|---|
-| Docs or governance only | `bash scripts/check-repo.sh` | `bash scripts/ci.sh` |
+| 仅文档或治理 | `bash scripts/check-repo.sh` | `bash scripts/ci.sh` |
 | TypeScript runtime | `npm run typecheck` | `npm test` |
-| CLI behavior | `npm run typecheck` + targeted Vitest | `npm test` + CLI smoke |
-| DAG workflow | targeted DAG tests | `npm test` |
-| Scripts or CI | run the changed script | `bash scripts/ci.sh` |
-| Package / publish entry | `npm run build` + `node bin/loop-agent.js --help` | `npm pack --dry-run` |
-| Full delivery | `bash scripts/ci.sh` | CLI smoke plus relevant manual checks |
-
-Common commands:
-
-```bash
-npm run typecheck
-npm test
-npm run build
-bash scripts/check-repo.sh
-bash scripts/ci.sh
-node bin/loop-agent.js --help
-npm run dev -- --help
-npm pack --dry-run
-```
-
-On Windows, run `scripts/*.sh` through Git Bash or a configured compatible Bash. Cross-platform CLI code should use native paths for real file operations and `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
-
-Never claim completion without fresh command output for the relevant gate.
+| CLI 行为 | `npm run typecheck` + 定向 Vitest | `npm test` + CLI smoke |
+| DAG 工作流 | 定向 DAG 测试 | `npm test` |
+| Production readiness hardening | `bash scripts/check-repo.sh` + 定向 DAG/CLI 测试 | `bash scripts/ci.sh` + docs build + package smoke |
+| 脚本或 CI | 运行变更的脚本 | `bash scripts/ci.sh` |
+| Package / publish 入口 | `npm run build` + `node bin/loop-agent.js --help` | `npm pack --dry-run` |
+| 完整交付 | `bash scripts/ci.sh` | CLI smoke + 相关手工检查 |
+
+常用命令：
+
+```bash
+npm run typecheck
+npm test
+npm run build
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+node bin/loop-agent.js --help
+npm run dev -- --help
+npm pack --dry-run
+```
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行 `scripts/*.sh`。跨平台 CLI 代码对真实文件操作用原生路径；`/` 仅用于稳定 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+没有相关门禁的新鲜命令输出，不得声明完成。
+
+Production Readiness v0.1 工作以 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md` 为验收契约。最终 hardening closeout 需要：
+
+```bash
+bash scripts/ci.sh
+npm run docs:build
+npm run build
+node bin/loop-agent.js --help
+npm pack --dry-run
+```

package/examples/example-dag.json

@@ -1,51 +1,51 @@
-{
-  "version": 2,
-  "title": "示例：审计并行 + 汇总串行",
-  "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": "audit-src",
-      "depends_on": [],
-      "complexity": "LOW",
-      "forbiddenPaths": [
-        ".harness/**"
-      ],
-      "outputContract": "Plain Markdown module inventory; no file writes.",
-      "subtask_prompt": "只读审计 ./src/workflows/dag/ 目录结构，输出模块清单（不要改文件）。"
-    },
-    {
-      "id": "audit-tests",
-      "depends_on": [],
-      "complexity": "LOW",
-      "forbiddenPaths": [
-        ".harness/**"
-      ],
-      "outputContract": "Plain Markdown test gap recommendations; no file writes.",
-      "subtask_prompt": "只读审计 ./test/ 中与 dag 相关的测试缺口，输出建议（不要改文件）。"
-    },
-    {
-      "id": "synthesize-plan",
-      "depends_on": [
-        "audit-src",
-        "audit-tests"
-      ],
-      "complexity": "MED",
-      "forbiddenPaths": [
-        ".harness/**"
-      ],
-      "outputContract": "Plain Markdown improvement plan (<=10 lines); no file writes.",
-      "subtask_prompt": "基于上游审计结果，输出一份 10 行以内的改进计划 Markdown（仍不要改代码）。"
-    }
-  ]
-}
+{
+  "version": 2,
+  "title": "示例：审计并行 + 汇总串行",
+  "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": "audit-src",
+      "depends_on": [],
+      "complexity": "LOW",
+      "forbiddenPaths": [
+        ".harness/**"
+      ],
+      "outputContract": "Plain Markdown module inventory; no file writes.",
+      "subtask_prompt": "只读审计 ./src/workflows/dag/ 目录结构，输出模块清单（不要改文件）。"
+    },
+    {
+      "id": "audit-tests",
+      "depends_on": [],
+      "complexity": "LOW",
+      "forbiddenPaths": [
+        ".harness/**"
+      ],
+      "outputContract": "Plain Markdown test gap recommendations; no file writes.",
+      "subtask_prompt": "只读审计 ./test/ 中与 dag 相关的测试缺口，输出建议（不要改文件）。"
+    },
+    {
+      "id": "synthesize-plan",
+      "depends_on": [
+        "audit-src",
+        "audit-tests"
+      ],
+      "complexity": "MED",
+      "forbiddenPaths": [
+        ".harness/**"
+      ],
+      "outputContract": "Plain Markdown improvement plan (<=10 lines); no file writes.",
+      "subtask_prompt": "基于上游审计结果，输出一份 10 行以内的改进计划 Markdown（仍不要改代码）。"
+    }
+  ]
+}

package/examples/hybrid-loop-agent-dag.json

@@ -1,194 +1,194 @@
-{
-  "version": 2,
-  "title": "Hybrid DAG 示例：Pi 只读契约 + 并行侦察 + Pi 写入实现",
-  "objective": "演示 v2 hybrid DAG：Pi 节点返回只读契约/审查结论，Pi 节点并行只读侦察，Pi writer 节点通过 toolProfile=write 独占实现。",
-  "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 is optional; no-Cursor environments should 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 Level 1/current-work summaries or explicit exclusive write nodes"
-  ],
-  "defaults": {
-    "executor": "pi",
-    "piBackend": "sdk-first",
-    "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 节点并行只读侦察，Pi writer 节点通过 toolProfile=write 独占实现。",
+  "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 is optional; no-Cursor environments should 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 Level 1/current-work summaries or explicit exclusive write nodes"
+  ],
+  "defaults": {
+    "executor": "pi",
+    "piBackend": "sdk-first",
+    "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/harness.json

@@ -46,9 +46,11 @@
     "checkStructure": "scripts/check-engineering-structure.sh",
     "checkDocIndex": "scripts/check-doc-index.sh",
     "checkDocLinks": "scripts/check-doc-links.sh",
-    "checkHarnessRuntimeClean": "scripts/check-harness-runtime-clean.sh",
-    "ci": "scripts/ci.sh"
-  },
+    "checkHarnessRuntimeClean": "scripts/check-harness-runtime-clean.sh",
+    "checkInitEvolutionNeeded": "scripts/check-init-evolution-needed.sh",
+    "checkInitSurface": "scripts/check-init-surface.sh",
+    "ci": "scripts/ci.sh"
+  },
   "models": {
     "analyze": {
       "provider": "wizard-local",
@@ -77,11 +79,11 @@
     }
   },
   "executors": {
-    "pi": {
-      "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
-      "defaultModel": "gpt-5.3-codex-spark",
-      "requiresApiKey": ""
-    },
+    "pi": {
+      "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
+      "defaultModel": "gpt-5.3-codex-spark",
+      "requiresApiKey": ""
+    },
     "cursor": {
       "description": "Cursor via @cursor/sdk (default model: account default)",
       "enabled": false,