@tea-agent/loop-agent 0.2.1 → 0.3.0

package/dist/workflows/dynamic/compile.js

@@ -40,6 +40,9 @@ function dagRoleForNode(node) {
 function executorForAgentLikeNode(node) {
     return node.executor ?? "pi";
 }
+function nodeSkillsField(node) {
+    return node.skills && node.skills.length > 0 ? { skills: node.skills } : {};
+}
 function dagWriteFields(spec, node) {
     if (node?.writePolicy === "none") {
         return {
@@ -111,6 +114,7 @@ function compileHumanGateNode(spec, node) {
         executor: "pi",
         role: "supervisor",
         ...dagWriteFields(spec, node),
+        ...nodeSkillsField(node),
         decisionGate: { enabled: true, mode: "pause-on-human" },
         outputContract: node.approvalSchema
             ? `Workflow approvalSchema:\n${JSON.stringify(node.approvalSchema, null, 2)}`
@@ -172,6 +176,7 @@ function compileLoopBodyTask(spec, node) {
         dependsOn: node.dependsOn,
         executor,
         role: dagRoleForNode(node),
+        ...nodeSkillsField(node),
         complexity: node.type === "reduce_agent" ? "MED" : "LOW",
         subtaskPromptTemplate: buildAgentPrompt(node),
         staticResultTemplate: node.staticResultTemplate ?? node.transform?.template ?? undefined,
@@ -189,6 +194,7 @@ function compileLoopUntilNode(spec, node) {
         executor: "static",
         role: dagRoleForNode(node),
         ...dagWriteFields(spec, node),
+        ...nodeSkillsField(node),
         static: {
             resultMarkdown: `Dynamic loop_until barrier for ${node.id}.`,
         },
@@ -212,6 +218,7 @@ function compileAgentLikeNode(spec, node) {
             executor: "static",
             role: dagRoleForNode(node),
             ...dagWriteFields(spec, node),
+            ...nodeSkillsField(node),
             static: {
                 resultMarkdown: node.staticResultTemplate ?? `Workflow node ${node.id} completed.`,
             },
@@ -226,6 +233,7 @@ function compileAgentLikeNode(spec, node) {
         executor: "pi",
         role: dagRoleForNode(node),
         ...dagWriteFields(spec, node),
+        ...nodeSkillsField(node),
         outputContract: stringifyOutputSchema(node.outputSchema),
     };
 }
@@ -258,6 +266,7 @@ function compileDynamicExpansionNode(spec, node) {
     const childTask = {
         executor: childExecutor,
         role: dagRoleForNode(node),
+        ...nodeSkillsField(node),
         complexity: "LOW",
         subtaskPromptTemplate: childPrompt,
         staticResultTemplate: node.staticResultTemplate,
@@ -273,6 +282,7 @@ function compileDynamicExpansionNode(spec, node) {
         writePolicy: "none",
         allowedPaths: [],
         forbiddenPaths: [],
+        ...nodeSkillsField(node),
         static: {
             resultMarkdown: `Dynamic ${node.type} expansion barrier for ${node.id}.`,
         },
@@ -299,6 +309,7 @@ function compileDynamicReductionNode(spec, node) {
         executor: "static",
         role: dagRoleForNode(node),
         ...dagWriteFields(spec, node),
+        ...nodeSkillsField(node),
         static: {
             resultMarkdown: `Dynamic reducer ${node.reducer?.type ?? "unknown"} for ${node.id}.`,
         },

package/dist/workflows/dynamic/spec.js

@@ -46,6 +46,7 @@ export const workflowNodeSchema = z.object({
     dependsOn: z.array(z.string()).default([]),
     executor: z.enum(["pi", "static"]).optional(),
     role: z.string().optional(),
+    skills: z.array(z.string().min(1)).optional(),
     prompt: z.string().optional(),
     staticResultTemplate: z.string().optional(),
     writePolicy: z.enum(["none", "read-only", "exclusive"]).optional(),

package/docs/README.md

@@ -14,7 +14,8 @@
 - `loop-agent-harness.md` — runtime 与 command surface 概览
 - `agent-dag-runner.md` — Agent DAG runner 指南
 - `cursor-executor-usage.md` — Cursor executor 用法
-- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
+- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
 
 ## 方法论
 
@@ -30,6 +31,7 @@
 - `progress/README.md` — 进度交接日志
 - `reports/README.md` — 验证与审计报告
 - `decisions/README.md` — 架构决策
+- `skills/README.md` — repo-local skill registry and vetting notes
 - `templates/` — 可复用的规划、报告与 DAG 模板
 
 ## 仓库 Skills
@@ -44,9 +46,10 @@
 - `templates/sprint-contract.md` — 实现契约与验收标准
 - `templates/exec-plan.md` — 非平凡工作的执行计划
 - `templates/progress-log.md` — 进度与交接日志
-- `templates/qa-report.md` — 验证与 QA 证据
-- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
-- `templates/adr.md` — 架构决策记录（ADR）
+- `templates/qa-report.md` — 验证与 QA 证据
+- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
+- `templates/adr.md` — 架构决策记录（ADR）
 
 ## 维护
 

package/docs/agent-dag-runner.md

@@ -23,6 +23,8 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 
 DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
 
+执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `docs/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
+
 `loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
 
 ## Artifacts

package/docs/exec-plans/active/README.md

@@ -4,7 +4,4 @@
 
 源码仓库可在本 README 旁保留具体 active plan 文件。npm 包只携带本 README 作为目录契约，不复制 loop-agent 源码历史的 active plan；目标仓库自行生成 active plan。
 
-当前 active plan：
-
-- [2026-07-04-dag-role-skill-alignment.md](2026-07-04-dag-role-skill-alignment.md)
-- [2026-07-06-production-readiness-hardening.md](2026-07-06-production-readiness-hardening.md)
+当前 active plan：无。

package/docs/exec-plans/completed/README.md

@@ -7,3 +7,5 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 - [`2026-07-02-loop-agent-subject-restructure.md`](2026-07-02-loop-agent-subject-restructure.md) — 将原 `tools/code-agent` runtime 提升到仓库根、重命名为 `loop-agent`，移除旧 memory plugin 产品线
 - [`2026-07-04-remove-level1-fallback.md`](2026-07-04-remove-level1-fallback.md) — 移除历史顺序 Level 1 fallback，runtime、文档与 command surface 收敛到 DAG 执行
 - [`2026-07-04-runtime-boundary-remediation.md`](2026-07-04-runtime-boundary-remediation.md) — 整合 CLI/skill/runtime 边界，抽出 DAG/Loop runtime seam，集中 harness store/guard 策略
+- [`2026-07-04-dag-role-skill-alignment.md`](2026-07-04-dag-role-skill-alignment.md) — 对齐 DAG/Dynamic Workflow role 与 repo-local vetted skills，新增 strict skill audit
+- [`2026-07-06-production-readiness-hardening.md`](2026-07-06-production-readiness-hardening.md) — 冻结 Production Readiness v0.1，打磨 DAG 主路径 next steps、failure routing、doctor/report/failure handoff 与 dogfood 验证

package/docs/init-surface.manifest.json

@@ -0,0 +1,175 @@
+{
+  "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",
+    "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"
+  ],
+  "initSurface": {
+    "README.md": "managed-block",
+    "AGENTS.md": "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"
+  },
+  "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/skills/README.md

@@ -0,0 +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.
+

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

@@ -0,0 +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. |
+| `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.
+

package/docs/templates/init-evolution-review.md

@@ -0,0 +1,33 @@
+# Init Evolution Review
+
+Date:
+Base:
+Head:
+
+## Changed Surface
+
+- 
+
+## Decision
+
+Choose one:
+
+- No init impact
+- Surface check only
+- Init update required
+
+Rationale:
+
+## Updates Made
+
+- 
+
+## Verification
+
+```bash
+# commands and results
+```
+
+## Residual Risk
+
+- 

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js"
@@ -15,10 +15,12 @@
     "docs/design/README.md",
     "docs/exec-plans/README.md",
     "docs/exec-plans/active/README.md",
-    "docs/exec-plans/completed/README.md",
-    "docs/progress/README.md",
-    "docs/reports/README.md",
-    "docs/templates/",
+    "docs/exec-plans/completed/README.md",
+    "docs/init-surface.manifest.json",
+    "docs/progress/README.md",
+    "docs/reports/README.md",
+    "docs/skills/",
+    "docs/templates/",
     "examples/",
     "harness.json",
     "skills/",

package/skills/code-review-core/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: code-review-core
+description: 用于只读 code review 节点，产出带文件与行号引用的优先级 findings。
+---
+
+# Code Review Core
+
+本 skill 用于 reviewer 节点。
+
+## Review 重点
+
+- 优先关注 correctness、行为回归、security、数据丢失与缺失验证。
+- findings 须 grounded 在具体文件与行号。
+- 区分 blocking findings 与次要 maintainability 备注。
+- 检查测试是否证明变更行为，文档是否与面向用户的变更一致。
+- 若无 findings，明确说明，并指出 residual test gap（如有）。
+
+## Output
+
+按 severity 排序列出 findings。仅当无 blocking findings 时，才写 `VERDICT: pass`。

package/skills/codebase-scout/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codebase-scout
+description: 用于只读 scout 节点，在实现前定位现有代码、测试、文档与集成点。
+---
+
+# Codebase Scout
+
+本 skill 用于 scout 节点。
+
+## 规则
+
+- 从 repo 指令、task source 与邻近测试入手。
+- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
+- 在提议新抽象前，识别现有 helper 与 ownership 边界。
+- 只返回事实，不做编辑。
+
+## Output
+
+列出相关文件、现有模式、风险，以及实现所需的最小 write surface。

package/skills/init-capability-evolution/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: init-capability-evolution
+description: 用于 loop-agent 本仓库的初始化能力演化审查，判断代码、skill、模板、包范围或 DAG 默认能力变化是否需要同步更新目标项目 init surface。
+---
+
+# Init Capability Evolution
+
+本 skill 用于 loop-agent 本仓库。当变更可能影响 `loop-agent init` 初始化其他项目的能力时使用。
+
+## Goal
+
+让模型自行判断并维护初始化能力，而不是依赖人工记忆：
+
+- 新能力是否应该进入目标项目。
+- 新增/修改的 skill 是否应随 npm 包和 `init --profile full` 投影。
+- 目标项目的 `AGENTS.md`、README managed block、治理 docs、scripts 或 templates 是否需要更新。
+- `package.json files` 与 `docs/init-surface.manifest.json` 是否仍覆盖真实发布范围。
+- 是否需要目标项目 smoke、init doctor、docs audit 或 package dry-run 证据。
+
+## Trigger Tiers
+
+按 `docs/init-surface.manifest.json` 的 `evolutionReview.tiers` 判断成本：
+
+- `advisory`：只记录提示，不阻塞。
+- `surface-check`：运行 `bash scripts/check-init-surface.sh`；通过即可。
+- `model-review`：写一份简短 init evolution review，必要时修改 init surface、包范围、文档、skill 或测试。
+
+不要把小改动升级成重流程。只有当变化可能改变目标项目初始化体验、默认 DAG 行为、skill resolution、发布包边界或 init 生成物时，才进入 model-review。
+
+## Review Questions
+
+审查时逐条回答：
+
+1. 本次变更会改变目标项目执行 `loop-agent init --profile full --merge` 后得到的文件、规则或能力吗？
+2. 是否新增、删除或重命名了 `skills/**`，并且目标项目需要 repo-local 可审计副本？
+3. 是否改变了默认 DAG role skills、skill resolution、strict skill audit 或 task prompt 注入？
+4. 是否新增通用治理模板、script matrix、production readiness 或 operator recovery 文档，需要目标项目初始化后可见？
+5. `package.json files` 是否包含所有 npm 运行和初始化所需静态资料？
+6. `docs/init-surface.manifest.json` 是否更新了 package / init / exclude / trigger contract？
+7. 旧目标项目是否只需 advisory、需要手工复制新增文件，还是需要未来 `init audit/update` 迁移能力？
+
+## Output
+
+轻量审查可以只在 handoff 中说明。高影响审查应写入：
+
+```text
+docs/reports/YYYY-MM-DD-init-evolution-review.md
+```
+
+报告保持短小，包含：
+
+- changed surface
+- decision: no init impact / surface check only / init update required
+- files updated
+- verification commands and results
+- residual risk
+
+## Required Verification
+
+按影响面选择最小命令：
+
+```bash
+bash scripts/check-init-surface.sh
+bash scripts/check-repo.sh
+npm test -- init-command dag-skills dag-validate-command
+npm pack --dry-run --ignore-scripts
+```
+
+如果没有新鲜验证证据，不要宣称 init evolution 已完成。

package/skills/loop-agent/references/command-reference.md

@@ -14,11 +14,12 @@ loop-agent <command> ...
 
 面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
 
-```bash
-npm install -g @tea-agent/loop-agent@latest
-npm list -g @tea-agent/loop-agent --depth=0
-loop-agent doctor
-```
+```bash
+npm install -g @tea-agent/loop-agent@latest
+npm list -g @tea-agent/loop-agent --depth=0
+loop-agent --version
+loop-agent doctor
+```
 
 一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
 
@@ -39,7 +40,7 @@ loop-agent doctor
    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 <repo-root>
    ```
-   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
+   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
 2. **Operator 工具**，用于 recovery、诊断与 closeout：
    ```bash
    loop-agent dag status --run-id <run-id>
@@ -65,10 +66,11 @@ loop-agent doctor
    ```
 
 ### Setup（首次）
-```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --help
-```
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
+loop-agent --help
+```
 
 ### 检查 repo harness
 ```bash
@@ -76,10 +78,10 @@ loop-agent inspect                                           # 当前 repo（自
 loop-agent --repo-root /path/to/target-repo inspect           # 指定 repo
 ```
 
-### 健康检查
-```bash
-loop-agent doctor
-```
+### 健康检查
+```bash
+loop-agent doctor
+```
 
 `doctor` 报告当前生效的 Pi backend 及 SDK/CLI 可用性。Pi step 默认 SDK-first 执行：
 
@@ -88,11 +90,26 @@ export CODE_AGENT_PI_BACKEND=sdk-first   # 默认：先试 Pi SDK，允许时 fa
 export CODE_AGENT_PI_BACKEND=cli-only    # 紧急回滚：纯 CLI 路径
 ```
 
-SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
-
-### 创建新 task
-```bash
-loop-agent new-task <task-id> "Task Title"
+SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
+
+### 初始化与旧项目更新
+```bash
+loop-agent init instructions --repo-root <target-repo>
+loop-agent init --repo-root <target-repo> --profile full --merge
+loop-agent init doctor --repo-root <target-repo>
+loop-agent init check-update --repo-root <target-repo> --json
+loop-agent init check-update --repo-root <target-repo> --markdown
+loop-agent init update --repo-root <target-repo> --bootstrap-surface
+loop-agent init update --repo-root <target-repo> --apply-safe
+```
+
+`init check-update` 是只读升级报告，用于发现目标项目是否落后于当前包内初始化 surface。输出会区分 deterministic actions、model merge tasks、human decisions 和 recommended next。`--markdown` 会渲染可直接交给模型执行的合并指引，包含 `allowedPaths`、`forbiddenPaths`、`mergeRules` 和 `verification`。
+
+`init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；已有但无法确认与当前包一致的文件会进入 model merge tasks，不会被覆盖。
+
+### 创建新 task
+```bash
+loop-agent new-task <task-id> "Task Title"
 ```
 
 创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。
@@ -187,6 +204,7 @@ loop-agent goal clear <task-id>
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-skills # missing/error/truncated skill 或 unresolved reference 时失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
 loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
 cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: test-driven-development
+description: 用于需要回归覆盖的行为变更与 bug 修复。保持小循环：写失败测试 → 变绿 → 仅在 green 后 refactor。
+---
+
+# Test-Driven Development
+
+本 skill 用于会改变 runtime 行为的 implementation 节点。
+
+## 规则
+
+- 行为是新增或已损坏时，在 production code 之前写或更新聚焦测试。
+- 运行聚焦测试，确认因预期原因失败。
+- 做最小实现变更使测试变绿。
+- refactor 仅在 green 之后，且仍在同一 bounded write set 内。
+- 能测真实本地 module 时，不要用 broad mock。
+
+## Output
+
+报告 red 命令、green 命令，以及仍需要的 broader verification。