@tea-agent/loop-agent 0.1.0-fe-test.0

package/docs/init-surface.manifest.json

@@ -0,0 +1,358 @@
+{
+  "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/governance/harness-methodology-tdd.md",
+    "docs/governance/harness-methodology-verification.md",
+    "docs/governance/harness-methodology-debugging.md",
+    "docs/operations/local-development-environment.md",
+    "docs/init-surface.manifest.json",
+    "docs/architecture/runtime-boundaries.md",
+    "docs/architecture/README.md",
+    "docs/architecture/system-overview.md",
+    "docs/architecture/dag-execution.md",
+    "docs/architecture/worker-and-feature.md",
+    "docs/architecture/facts-and-state.md",
+    "docs/architecture/evolution.md",
+    "docs/skills/README.md",
+    "docs/skills/vetted-skill-registry.md",
+    "docs/templates/README.md",
+    "docs/templates/init-managed-agents.md",
+    "docs/templates/init-evolution-review.md",
+    "docs/templates/exec-plan.md",
+    "docs/templates/production-readiness-checklist.md",
+    "docs/templates/frontend-task-requirement.md",
+    "docs/templates/frontend-task-constraints.md",
+    "docs/templates/frontend-design-contract.md",
+    "docs/templates/worker-dogfood-setup.md",
+    "docs/templates/worker-dogfood-evidence.md",
+    "docs/templates/harness.schema.json",
+    "docs/templates/interactive-ui-round2-experiment.md",
+    "docs/templates/product-line/README.md",
+    "docs/templates/product-line/AGENTS.md",
+    "docs/templates/product-line/requirement.md",
+    "docs/templates/product-line/acceptance.yaml",
+    "docs/templates/product-line/design.md",
+    "docs/templates/product-line/test-plan.md",
+    "docs/templates/product-line/task-graph.yaml",
+    "docs/templates/product-line/task.yaml",
+    "docs/templates/product-line/feature.yaml",
+    "docs/templates/product-line/closeout.yaml",
+    "docs/templates/product-line/links.md",
+    "scripts/kb-bootstrap-init-skeleton.sh",
+    "scripts/kb-query.mjs",
+    "scripts/kb-graph-materialize.mjs",
+    "scripts/kb-graph-promote.mjs",
+    "scripts/kb-graph-incremental-prepare.mjs",
+    "docs/templates/agent-dag.schema.json",
+    "examples/example-dag.json",
+    "skills/agent-worker/SKILL.md",
+    "skills/agent-worker/references/agent-worker-operator.md",
+    "skills/loop-agent/SKILL.md",
+    "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/hybrid-dag.md",
+    "skills/loop-agent/references/source-and-plan-practice.md",
+    "skills/loop-agent/references/docs-converge.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/grill-with-docs/SKILL.md",
+    "skills/grill-with-docs/context-format.md",
+    "skills/grill-with-docs/adr-format.md",
+    "skills/webapp-testing/SKILL.md",
+    "skills/playwright-cli/SKILL.md",
+    "skills/playwright-cli-case-generator/SKILL.md",
+    "skills/frontend-implementation/SKILL.md",
+    "skills/frontend-implementation/references/node-contracts.md",
+    "skills/frontend-implementation/references/design-spec.md",
+    "skills/frontend-implementation/references/code-standards.md",
+    "skills/frontend-bounded-implement/SKILL.md",
+    "skills/frontend-design-review/SKILL.md",
+    "skills/frontend-design-review/references/review-checklist.md",
+    "skills/frontend-review/SKILL.md",
+    "skills/frontend-review/references/review-findings.md",
+    "skills/frontend-verification/SKILL.md",
+    "skills/frontend-verification/references/verification-checklist.md",
+    "docs/templates/backend-test-analysis.schema.json",
+    "docs/templates/backend-test-execution.schema.json",
+    "docs/templates/backend-test-result.schema.json",
+    "docs/templates/backend-test-case-manifest.schema.json"
+  ],
+  "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/harness-methodology-tdd.md",
+    "docs/harness-methodology-verification.md",
+    "docs/harness-methodology-debugging.md",
+    "docs/templates/README.md",
+    "docs/templates/init-evolution-review.md",
+    "docs/templates/production-readiness-checklist.md",
+    "docs/templates/frontend-task-requirement.md",
+    "docs/templates/frontend-task-constraints.md",
+    "docs/templates/frontend-design-contract.md",
+    "docs/templates/worker-dogfood-setup.md",
+    "docs/templates/worker-dogfood-evidence.md",
+    "docs/templates/harness.schema.json",
+    "docs/templates/interactive-ui-round2-experiment.md",
+    "docs/templates/product-line/README.md",
+    "docs/templates/product-line/AGENTS.md",
+    "docs/templates/product-line/requirement.md",
+    "docs/templates/product-line/acceptance.yaml",
+    "docs/templates/product-line/design.md",
+    "docs/templates/product-line/test-plan.md",
+    "docs/templates/product-line/task-graph.yaml",
+    "docs/templates/product-line/task.yaml",
+    "docs/templates/product-line/feature.yaml",
+    "docs/templates/product-line/closeout.yaml",
+    "docs/templates/product-line/links.md",
+    "scripts/check-skill-entry.sh",
+    "scripts/check-product-line-docs.sh",
+    "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",
+    ".agents/skills/agent-worker/SKILL.md",
+    ".agents/skills/agent-worker/references/agent-worker-operator.md",
+    ".agents/skills/loop-agent/SKILL.md",
+    ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/hybrid-dag.md",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md",
+    ".agents/skills/loop-agent/references/docs-converge.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/grill-with-docs/SKILL.md",
+    ".agents/skills/grill-with-docs/context-format.md",
+    ".agents/skills/grill-with-docs/adr-format.md",
+    ".agents/skills/webapp-testing/SKILL.md",
+    ".agents/skills/playwright-cli/SKILL.md",
+    ".agents/skills/playwright-cli-case-generator/SKILL.md",
+    ".agents/skills/frontend-implementation/SKILL.md",
+    ".agents/skills/frontend-implementation/references/node-contracts.md",
+    ".agents/skills/frontend-implementation/references/design-spec.md",
+    ".agents/skills/frontend-implementation/references/code-standards.md",
+    ".agents/skills/frontend-bounded-implement/SKILL.md",
+    ".agents/skills/frontend-design-review/SKILL.md",
+    ".agents/skills/frontend-design-review/references/review-checklist.md",
+    ".agents/skills/frontend-review/SKILL.md",
+    ".agents/skills/frontend-review/references/review-findings.md",
+    ".agents/skills/frontend-verification/SKILL.md",
+    ".agents/skills/frontend-verification/references/verification-checklist.md",
+    "docs/templates/backend-test-analysis.schema.json",
+    "docs/templates/backend-test-execution.schema.json",
+    "docs/templates/backend-test-result.schema.json",
+    "docs/templates/backend-test-case-manifest.schema.json",
+    ".opencode/plugins/loop-agent-transient-retry.js",
+    ".opencode/plugins/loop-agent-context-overflow-compact.js",
+    ".pi/extensions/loop-agent-context-overflow.js",
+    ".pi/settings.json"
+  ],
+  "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/harness-methodology-tdd.md": "copied",
+    "docs/harness-methodology-verification.md": "copied",
+    "docs/harness-methodology-debugging.md": "copied",
+    "docs/templates/README.md": "copied",
+    "docs/templates/init-evolution-review.md": "copied",
+    "docs/templates/production-readiness-checklist.md": "copied",
+    "docs/templates/frontend-task-requirement.md": "copied",
+    "docs/templates/frontend-task-constraints.md": "copied",
+    "docs/templates/frontend-design-contract.md": "copied",
+    "docs/templates/worker-dogfood-setup.md": "copied",
+    "docs/templates/worker-dogfood-evidence.md": "copied",
+    "docs/templates/harness.schema.json": "copied",
+    "docs/templates/interactive-ui-round2-experiment.md": "copied",
+    "docs/templates/product-line/README.md": "copied",
+    "docs/templates/product-line/AGENTS.md": "copied",
+    "docs/templates/product-line/requirement.md": "copied",
+    "docs/templates/product-line/acceptance.yaml": "copied",
+    "docs/templates/product-line/design.md": "copied",
+    "docs/templates/product-line/test-plan.md": "copied",
+    "docs/templates/product-line/task-graph.yaml": "copied",
+    "docs/templates/product-line/task.yaml": "copied",
+    "docs/templates/product-line/feature.yaml": "copied",
+    "docs/templates/product-line/closeout.yaml": "copied",
+    "docs/templates/product-line/links.md": "copied",
+    "scripts/check-skill-entry.sh": "generated",
+    "scripts/check-product-line-docs.sh": "generated",
+    "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",
+    ".agents/skills/agent-worker/SKILL.md": "copied",
+    ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
+    ".agents/skills/loop-agent/SKILL.md": "copied",
+    ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/hybrid-dag.md": "copied",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md": "copied",
+    ".agents/skills/loop-agent/references/docs-converge.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/grill-with-docs/SKILL.md": "copied",
+    ".agents/skills/grill-with-docs/context-format.md": "copied",
+    ".agents/skills/grill-with-docs/adr-format.md": "copied",
+    ".agents/skills/webapp-testing/SKILL.md": "copied",
+    ".agents/skills/playwright-cli/SKILL.md": "copied",
+    ".agents/skills/playwright-cli-case-generator/SKILL.md": "copied",
+    ".agents/skills/frontend-implementation/SKILL.md": "copied",
+    ".agents/skills/frontend-implementation/references/node-contracts.md": "copied",
+    ".agents/skills/frontend-implementation/references/design-spec.md": "copied",
+    ".agents/skills/frontend-implementation/references/code-standards.md": "copied",
+    ".agents/skills/frontend-bounded-implement/SKILL.md": "copied",
+    ".agents/skills/frontend-design-review/SKILL.md": "copied",
+    ".agents/skills/frontend-design-review/references/review-checklist.md": "copied",
+    ".agents/skills/frontend-review/SKILL.md": "copied",
+    ".agents/skills/frontend-review/references/review-findings.md": "copied",
+    ".agents/skills/frontend-verification/SKILL.md": "copied",
+    ".agents/skills/frontend-verification/references/verification-checklist.md": "copied",
+    "docs/templates/backend-test-analysis.schema.json": "copied",
+    "docs/templates/backend-test-execution.schema.json": "copied",
+    "docs/templates/backend-test-result.schema.json": "copied",
+    "docs/templates/backend-test-case-manifest.schema.json": "copied",
+    ".opencode/plugins/loop-agent-transient-retry.js": "generated",
+    ".opencode/plugins/loop-agent-context-overflow-compact.js": "generated",
+    ".pi/extensions/loop-agent-context-overflow.js": "generated",
+    ".pi/settings.json": "generated"
+  },
+  "packageExcluded": [
+    "docs/progress/20*.md",
+    "docs/reports/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",
+    "docs/templates/init-managed-agents.md"
+  ],
+  "reviewTriggers": [
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "harness.json",
+    "package.json",
+    "src/commands/init.ts",
+    "src/commands/client-recovery.ts",
+    "src/commands/init-upgrade.ts",
+    "src/cli.ts",
+    "src/cli/update/init-surface-notifier.ts",
+    "src/cli/update/policy.ts",
+    "src/cli/update/runtime-activity.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/*-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/commands/client-recovery.ts",
+          "src/commands/init-upgrade.ts",
+          "src/cli.ts",
+          "src/cli/update/init-surface-notifier.ts",
+          "src/cli/update/policy.ts",
+          "src/cli/update/runtime-activity.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/operations/README.md

@@ -0,0 +1,15 @@
+# 维护与协作
+
+这里收录维护仓库时会直接照着执行的操作手册。
+
+## 入口
+
+- [`local-development-environment.md`](local-development-environment.md)：本地环境、Windows 差异和常见排障。
+- [`branch-merge-guideline.md`](branch-merge-guideline.md)：按风险选择合并模式并留下 source-SHA 证据。
+- [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定及发布通道。
+- [`version-and-release-management.md`](version-and-release-management.md)：版本发布管理——next / release-x.y / latest 渠道、workflow 与 promote 手册。
+- [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
+- [`agent-worker-production-readiness.md`](agent-worker-production-readiness.md)：agent-worker Feature/Task Pool 外层编排的 Production Readiness v1 操作合同。
+- [`backend-test-jacoco-coverage.md`](backend-test-jacoco-coverage.md)：Java 被测服务挂载 JaCoCo tcpserver agent 的 Maven、`java -jar` 与 Docker 操作手册。
+
+验证命令仍以 [`../governance/verification-matrix.md`](../governance/verification-matrix.md) 为准。

package/docs/operations/local-development-environment.md

@@ -0,0 +1,77 @@
+# 本地开发环境排障
+
+本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](../governance/verification-matrix.md) 为准。
+
+## Git hooks（本仓库）
+
+每个 clone 安装一次：
+
+```bash
+bash scripts/install-git-hooks.sh
+```
+
+| Hook | 行为 |
+| --- | --- |
+| `pre-commit` | `bash scripts/check-repo.sh`（快，不含 `npm test`） |
+| `pre-push` | `node scripts/pre-push-verify.mjs`：同 tree/env receipt 命中则复用；miss 时 full `bash scripts/ci.sh`（check-repo + typecheck + 全量 `npm test`） |
+
+可选：`npm run verify:tree` 对当前 clean HEAD 提前 full 验证并写 receipt；`node scripts/pre-push-verify.mjs --explain-current-tree` 只读诊断。二者都不是默认必经步骤。
+
+编辑与实现阶段只跑 verification-matrix 的「最低验证」；全量测试由 push 前 hook 或可选 `verify:tree` 承担。紧急跳过一次（非标准去重）：
+
+```bash
+LOOP_AGENT_SKIP_PRE_PUSH_TESTS=1 git push
+```
+
+## Cursor Cloud
+
+Cursor Cloud VM 当前有两个需要特别注意的环境问题。
+
+### Node.js 版本
+
+VM 默认 `node`（`/exec-daemon/node`）可能是 v22.14.0，但可选依赖 `@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 要求 Node.js `>=22.19.0`。版本过低时，`npm install` / `npm ci` 可能跳过这些依赖，随后 `npm run typecheck` 或 `npm run build` 会报告：
+
+```text
+Cannot find module '@earendil-works/...'
+```
+
+在 Cursor Cloud 中执行安装或验证前，先切换到已配置的 Node.js 22：
+
+```bash
+nvm use 22
+node --version
+npm ci
+```
+
+当前 VM 预装版本为 v22.22.2；应以 `node --version` 的实际输出为准，不依赖交互式 shell 的默认 PATH。
+
+### Git 提交签名导致测试超时
+
+Cursor Cloud 的全局 Git 配置可能通过 `cursor-git-ssh-keygen` 为每次提交签名（`gpg.format=ssh`、`commit.gpgsign=true`）。该 helper 可能阻塞 7–30 秒，使会在临时仓库中频繁提交的测试（尤其 `test/worker/delivery/**`、`test/worker/feature/**`）触发 15/30 秒超时。
+
+运行 `npm test` 或其他 Git 密集型测试前，可仅对子进程关闭提交签名：
+
+```bash
+export GIT_CONFIG_COUNT=1
+export GIT_CONFIG_KEY_0=commit.gpgsign
+export GIT_CONFIG_VALUE_0=false
+npm test
+```
+
+也可以只在当前目标仓库设置：
+
+```bash
+git config commit.gpgsign false
+```
+
+该设置只用于本地开发和测试稳定性，不应写入仓库代码、模板或发布包配置。
+
+## Windows clean Shell 与用户级 Python
+
+DAG Shell/verification 默认使用安全的 clean environment，不继承完整宿主环境。在 Windows 上，clean baseline 会保留 `APPDATA`，使 Python/pip 能按标准规则定位 `%APPDATA%/Python/PythonXY/site-packages` 中的用户级安装，同时 token、credential 与其他未授权变量仍被过滤。不要在仓库中硬编码用户目录、盘符、Python 版本或 `site-packages` 路径；业务环境变量仍应通过任务/DAG 的显式 `envAllowlist` 授权。
+
+## 维护规则
+
+- 仅把可复现、会反复影响开发或验证的环境问题写入本文。
+- 通用且跨环境成立的要求应写入开发原则或验证矩阵，不应堆在本页。
+- 问题消失或基础镜像修复后，应删除过期说明，避免把临时环境状态长期固化为项目规则。

package/docs/skills/README.md

@@ -0,0 +1,7 @@
+# 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.
+- `../../skills/agent-worker/SKILL.md` — optional outer-loop operator skill for Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canaries, and Worker recovery. Single DAG implementation or runtime repair stays with `loop-agent`; this skill is not a default DAG role skill.
+- `../../scripts/check-skill-entry.sh` — validates both public skill entries, their required references, line budgets, and the `agent-worker` trigger vocabulary.

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

@@ -0,0 +1,49 @@
+# 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 | Entry 紧凑在 `perSkillMaxChars=3000` 以内；3 个 required refs 在默认 baseline-v1 budget 下完整 resolved。`command-reference.md` 降级为按需 reference（路由表仍列出），不默认常驻每个 DAG node。 |
+| `agent-worker` | local operator skill | `skills/agent-worker/SKILL.md` | outer-loop operator only | never a default DAG role | Routes Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canary, and failure recovery. Must not launch recursively from DAG leaves or duplicate executor/kernel behavior. |
+| `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 + feedback-loop-first gate | `skills/systematic-debugging/SKILL.md` | implementer, verifier | verifier | Advisory prompt guidance only; does not run tools by itself. Requires pass/fail loop before root-cause guessing; verifier must not cross writer boundaries. |
+| `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 + vertical one-test-one-impl cycle | `skills/test-driven-development/SKILL.md` | implementer | implementer | Does not force tests in mechanical-only docs changes; implementer still follows task contract. Forbids batch-all-RED-then-all-GREEN. |
+| `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. |
+| `grill-with-docs` | local operator skill adapted from domain grilling + ADR/glossary discipline | `skills/grill-with-docs/SKILL.md` | explicit interactive operator only | never a default DAG role | Resolves decisions via `harness.json.governanceRoot`; required refs `context-format.md` / `adr-format.md`; respects writeSet; not in `DEFAULT_SKILLS_BY_ROLE`. |
+| `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. |
+| `playwright-cli` | repo-local Playwright CLI instructions | `skills/playwright-cli/SKILL.md` | FE-test case executor | FE-test only | Direct browser commands require isolated test environments, per-case evidence paths, and explicit credential/data handling. |
+| `playwright-cli-case-generator` | adapted from the repo-local playwright CLI case-generator contract | `skills/playwright-cli-case-generator/SKILL.md` | FE-test case generator | FE-test only | Generates Markdown cases and a compact manifest from RAG facts; does not execute browsers, create test code, or invent API/data constraints. |
+
+## Verification placement taxonomy
+
+Authoring vocabulary for where a check or verification skill should live. Prefer deterministic placement over model soft-chaining. Do **not** add free-text placement comments to every `SKILL.md`, and do **not** extend frontmatter schema until a runtime/checker consumer exists.
+
+| placement | 本项目映射 | 何时选用 |
+|---|---|---|
+| **standalone** | 显式 operator skill / 独立只读检查（如 `loop-agent doctor`、`docs audit`、`stats context`） | 跨任务聚合、repo/runtime 健康、不绑定单一 DAG 节点 |
+| **embedded** | DAG 节点自带 shell gate、role skill 或节点内 verify | 节点完成条件可本地判定；失败应阻断该节点 |
+| **chained** | 可 `dag validate` 的 DAG dependencies / ranks；不用模型软调用串联 | 多步顺序或分叉必须可机读、可恢复 |
+| **PR-bound** | CI / GitHub workflow（`scripts/ci.sh`、repo checks） | 合并前门禁；仅在团队流程稳定后启用 |
+
+约束：
+
+- Skill 软 chaining **不是**主流程；验证循环优先进入 DAG topology、shell gates、review nodes 与 CI。
+- Registry / authoring guide 使用本表做决策说明即可；placement 不是 runtime 字段。
+
+## Vetting Rules
+
+- Default role mappings may reference only repo-local skills that resolve cleanly under `dag validate --strict-skills`.
+- `agent-worker` is explicitly outside default role mappings. Its trigger description must cover `agent-worker`, Feature Packet, TaskSpec, Task Pool, self-host/candidate and the `loop-agent` routing boundary; `scripts/check-skill-entry.sh` enforces this public entry contract.
+- `grill-with-docs` is an explicit interactive operator skill only; it must stay outside `DEFAULT_SKILLS_BY_ROLE`.
+- 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.
+- External engineering methodologies may inspire local skill text, but must follow ADR 0006: fuse into existing docs/skills/templates/checks/DAG; do not create parallel governance trees.
+- When choosing where a verification lives, use the placement taxonomy above; do not invent a parallel checklist tree.

package/docs/templates/README.md

@@ -0,0 +1,67 @@
+# 模板库
+
+本目录保存可复用的执行计划、报告、DAG、schema、评测与产品线初始化模板。这里的文件是“可以拿来使用的起点”，不是某次任务的执行证据。
+
+`docs/templates/README.md` 随 npm 包发布，并由 full init 复制到目标治理根；旧项目可通过 `init check-update` / `init update --apply-safe` 追踪缺失的模板入口和受管模板。源仓专用的文档治理脚本不会默认复制到目标项目。
+
+## 通用任务、报告与治理
+
+- `init-managed-agents.md` — **package-only**：目标项目 `AGENTS.md` managed block 的可编辑正文真源（`__LOOP_AGENT_PROJECT_NAME__` / `__LOOP_AGENT_GOVERNANCE_ROOT__` 占位符；由 `init` 渲染注入，**不**复制到目标治理 `templates/`）。
+- `project-start-checklist.md` — 开工检查。
+- `feature-spec.md`、`sprint-contract.md` — 功能规格与短周期合同。
+- `exec-plan.md`、`progress-log.md`、`qa-report.md` — 执行计划、交接与验证报告。
+- `adr.md` — 架构决策记录。
+- `branch-merge-report.md` — source-SHA 分支合并报告。
+- `init-evolution-review.md` — 初始化能力演化审查。
+- `production-readiness-checklist.md` — Production Readiness 检查。
+- `agent-worker-production-readiness-checklist.md` — agent-worker Feature/Task Pool Production Readiness v1 campaign 检查清单。
+- `worker-dogfood-setup.md`、`worker-dogfood-evidence.md` — 已发布控制器下的 Worker dogfood 设置与证据。
+- `interactive-ui-round2-experiment.md` — 交互式 UI 对照实验。
+
+## Agent DAG
+
+- `agent-dag.base.json`、`agent-dag.supervised-implementation.json`、`agent-dag.final-verification.json` — 通用 DAG 拓扑。
+- `agent-dag.schema.json`、`agent-dag-report.schema.json`、`agent-dag-decision-envelope.schema.json` — DAG、报告和决策 envelope schema。
+- `hybrid-dag.json` — hybrid DAG 示例。
+- `agent-dag-authority-surface-audit.prompt.md` — 权威面审查提示。
+- `agent-dag-decision-gate.prompt.md`、`agent-dag-decision-gate-dogfood-report.md` — 决策门与 dogfood 报告。
+- `agent-dag-process-supervisor.prompt.md` — 过程监督提示。
+- `agent-dag-review-verdict.prompt.md` — review verdict 提示。
+
+## Backend-test
+
+- `backend-test-dag.json` — backend-test DAG 模板；其中 `generate-backend-md-cases-pi` 是唯一允许 `writer-empty-diff` 重试的 writer（总共两次，仅限 post-write-guard attribution 确认的空 diff）。
+- `backend-test-dag.classify.prompt.md`、`backend-test-dag.generate-pytest.prompt.md`、`backend-test-dag.review-cases.prompt.md`、`backend-test-dag.retrospect.prompt.md` — 分类、生成、审查和复盘提示。
+- `backend-test-analysis.schema.json`、`backend-test-execution.schema.json`、`backend-test-result.schema.json`、`backend-test-case-manifest.schema.json` — 分析、执行、结果与用例清单 schema。
+
+## Frontend
+
+- `frontend-task-requirement.md`、`frontend-task-constraints.md`、`frontend-design-contract.md` — 前端任务输入与设计合同。
+- `frontend-implementation-contract.schema.json` — 前端实现合同 schema。
+- `frontend-test-dag.json` — frontend-test DAG 模板；其 deterministic checklist 会拒绝 alternative executable instructions，仅允许 allowlisted `playwright-cli` command。Pi generator/reviser 的 runtime writeSet 仅授权下列目标项目生成路径（不是本仓库文档索引目标）：
+
+  ~~~text
+  testcase/frontend/cases/FE-*.md
+  testcase/frontend/cases/index.md
+  testcase/frontend/cases/manifest.draft.json
+  ~~~
+
+  Pi writer writeSet 不包含 final manifest（文件名 manifest.json）。依赖 checklist 的 exclusive shell materializer 是 final manifest 的唯一写入者，以 temp+rename 原子生成 final，后续 map 只消费该 materializer 输出。
+- `frontend-test-dag.retrieve-context.prompt.md`、`frontend-test-dag.generate-cases.prompt.md`、`frontend-test-dag.review-cases.prompt.md`、`frontend-test-dag.review-execution.prompt.md`、`frontend-test-dag.retrospect.prompt.md` — 上下文、用例、审查、执行审查和复盘提示。
+- `frontend-test-case-checklist.md` — 前端测试用例检查清单。
+- `frontend-test-case.example.md` — 中文优先的 playwright-cli 前端用例填空模板（说明与步骤意图用中文；命令/编号保持机器字段）。需登录则先打开登录页再进入目标页；无需登录或已登录则打开或跳转目标页。
+- `frontend-test-standard-scenarios.v1.json` — frontend-test 标准场景规范（generate 覆盖 must 场景；运行时可物化到目标项目 testcase/frontend/rag 下的 standard-scenarios.v1.json）。
+
+## 知识同步与配置
+
+- `knowledge-sync-dag.json`、`knowledge-graph-bootstrap-dag.json` — 知识同步与图谱初始化 DAG。
+- `knowledge-sync-draft.schema.json` — 知识同步草稿 schema。
+- `harness.schema.json` — `harness.json` 的 IDE JSON Schema。
+
+## 子目录
+
+- `product-line/README.md` — Feature、Task、Acceptance、Graph、Closeout 等产品线骨架。
+- `evaluation/` — 通用评测模板与 schema。
+- `frontend-eval/` — 前端评测模板、功能样例和失败 fixture。
+
+新增、删除或重命名模板时，应同步本页、`docs/init-surface.manifest.json` 和相关 init/package 测试；完整性由 `scripts/check-doc-governance.mjs` 枚举校验。

package/docs/templates/adr.md

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