@tea-agent/loop-agent 0.2.0 → 0.3.0

package/docs/feature-workflow.md

@@ -1,117 +1,117 @@
-# Feature Workflow
+# 功能工作流
 
-This document separates two layers:
+本文档区分两层：
 
-- Session governance: how the supervising human/agent should structure a work session.
-- Runtime workflows: what the code actually executes under `src/workflows/`.
+- **Session governance**：监督方（人/agent）如何组织一次工作会话
+- **Runtime workflows**：`src/workflows/` 下代码实际执行的内容
 
-## Default Session Protocol
+## 默认会话协议
 
-1. Orient: read `README.md`, `harness.json`, and this docs index.
-2. Select: choose one bounded work block.
-3. Contract: state deliverables, non-goals, completion criteria, verification commands, and failure conditions.
-4. Implement: make the smallest coherent change and update required docs, scripts, and tests.
-5. Verify: run commands from `verification-matrix.md`; use fresh output for any completion claim.
-6. Handoff: record evidence in `docs/progress/`, `docs/reports/`, an exec plan, or an ADR when useful.
+1. **Orient**：读 `README.md`、`harness.json` 与本 docs 索引
+2. **Select**：选一个有限边界的工作块
+3. **Contract**：写明交付物、非目标、完成标准、验证命令、失败条件
+4. **Implement**：做最小连贯变更，同步更新必要文档、脚本与测试
+5. **Verify**：按 `verification-matrix.md` 跑命令；完成声明用新鲜输出
+6. **Handoff**：在 `docs/progress/`、`docs/reports/`、exec plan 或 ADR 中记录证据
 
 ## Orient
 
-Start by understanding the current system rather than assuming absence:
+先理解当前系统，不要默认「没有」：
 
-- read the repository entrypoints listed in `harness.json`
-- check `git status --short --branch` and recent commits
-- search existing source, tests, scripts, docs, and templates before adding new structure
-- run the smallest baseline check if the task depends on a healthy baseline
-- read methodology docs when the task involves TDD, verification claims, or debugging
+- 读 `harness.json` 列出的仓库入口
+- 查 `git status --short --branch` 与最近提交
+- 新增结构前搜索现有源码、测试、脚本、文档与模板
+- 任务依赖健康基线时跑最小基线检查
+- 涉及 TDD、完成声明或调试时读方法论文档
 
-If the baseline is already broken, record the failing command and decide whether the current work block is to repair the baseline or to proceed with a clearly scoped known failure.
+基线已坏时，记录失败命令，并决定当前块是修基线还是在明确范围内接受已知失败。
 
 ## Select
 
-Keep a work block narrow enough to verify. Avoid combining unrelated refactors, features, and documentation migrations.
+工作块要窄到可验证。避免无关重构、功能与文档迁移混在一起。
 
-A selected block should have:
+选中的块应有：
 
-- a single user-visible or maintainer-visible outcome
-- explicit allowed paths when delegating write work
-- known non-goals
-- a verification command that can prove the result
+- 单一用户可见或维护者可见结果
+- 委托写工作时显式 allowed paths
+- 已知非目标
+- 能证明结果的验证命令
 
 ## Contract
 
-For non-trivial work, write or update an execution plan, sprint contract, progress log, or issue-sized note before implementation. The contract should state:
+非平凡工作应在实现前写或更新 execution plan、sprint contract、progress log 或 issue 级笔记。Contract 应包含：
 
-- deliverables
-- non-goals
-- acceptance criteria
-- verification commands
-- failure conditions
-- expected artifacts to update
+- 交付物
+- 非目标
+- 验收标准
+- 验证命令
+- 失败条件
+- 预期更新的 artifacts
 
-For bug fixes, the contract should include the reproduction path and the regression test or smoke check that proves the fix.
+Bug 修复的 contract 应含复现路径，以及证明修复的回归测试或 smoke check。
 
 ## Implement
 
-Make the smallest coherent change that satisfies the contract.
+做满足 contract 的最小连贯变更。
 
-- Prefer existing helpers and directory boundaries.
-- Update tests for behavior changes.
-- Update docs and examples for workflow or command changes.
-- Update `harness.json`, check scripts, or templates for governance changes.
-- Do not submit placeholder implementations as completed work.
-- When a repeated constraint appears, promote it into a durable artifact.
+- 优先现有 helper 与目录边界
+- 行为变更更新测试
+- 工作流或命令变更更新文档与示例
+- 治理变更更新 `harness.json`、检查脚本或模板
+- 不把占位实现当作已完成
+- 重复约束出现时固化为持久产物
 
 ## Verify
 
-Verification is the completion authority.
+验证是完成权威。
 
-- Use `docs/verification-matrix.md` to choose the narrowest proving command.
-- Run the full command fresh.
-- Read the exit code and output.
-- Fix failures or report the exact failing state.
-- Do not claim completion from stale output or partial checks.
+- 用 `docs/verification-matrix.md` 选最窄的证明命令
+- 完整重跑命令
+- 读 exit code 与输出
+- 修失败或报告确切失败状态
+- 不用陈旧输出或部分检查声明完成
 
 ## Agent DAG First
 
-For complex implementation work, prefer the DAG workflow:
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-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 .
-```
-
-`<temp-dir>` means the platform-native temp directory. Use native paths for actual file operations on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
-
-This is not a linear OS-CIVH runtime state machine. In code, DAG has three command phases:
-
-1. `dag run-task` loads `.harness/tasks/<task-id>/source/需求.md`, optional `执行约束.md`, `task.json`, and adapter verification commands, then writes a DAG spec.
-2. `dag validate` validates schema, dependencies, governance profile, write boundaries, model routing, and shell verification metadata.
-3. `run-dag` loads the DAG, topologically sorts tasks into ranks, executes runnable nodes with bounded concurrency, persists `.harness/dag-runs/<lifecycle>/<run-id>/`, and transfers the run to `completed` or `paused`.
-
-The standard generated hybrid DAG defaults to no-Cursor execution:
-
-```text
-contract-pi
-  -> scout-src + scout-tests
-  -> plan-pi
-  -> implement-pi
-  -> verify-pi
-  -> closeout-pi
-```
-
-`implement-pi` uses `executor: "pi"` with `toolProfile: "write"`. When `harness.json` explicitly disables Pi and enables Cursor, the implementation and repair writer nodes use `implement-cursor` / `repair-cursor` instead.
-
-The review-gated template inserts:
+复杂实现优先 DAG 工作流：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+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 .
+```
+
+`<temp-dir>` 为平台原生临时目录。macOS/Windows 上实际文件操作用原生路径；`/` 仅用于稳定 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+这不是线性 OS-CIVH runtime 状态机。代码里 DAG 有三个命令阶段：
+
+1. `dag run-task` 加载 `.harness/tasks/<task-id>/source/需求.md`、可选 `执行约束.md`、`task.json` 与 adapter 验证命令，写出 DAG spec
+2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
+3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
+
+标准生成的 hybrid DAG 默认无 Cursor：
+
+```text
+contract-pi
+  -> scout-src + scout-tests
+  -> plan-pi
+  -> implement-pi
+  -> verify-pi
+  -> closeout-pi
+```
+
+`implement-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。当 `harness.json` 显式禁用 Pi 并启用 Cursor 时，实现与修复 writer 节点改用 `implement-cursor` / `repair-cursor`。
+
+review-gated 模板插入：
 
 ```text
 verify-pi -> review-pi -> review-gate-shell -> closeout-pi
 ```
 
-The supervised template adds write-set audit, soft/hard shell verification, process supervision, bounded repair, decision gates, and optional convergence retry passes around the implementation path.
+supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
 
-Source references:
+源码参考：
 
 - `src/commands/dag-run-task.ts`
 - `src/commands/dag-validate.ts`
@@ -119,34 +119,36 @@ Source references:
 - `src/workflows/dag/init-hybrid.ts`
 - `src/workflows/dag/runner.ts`
 
-The supervising agent remains responsible for:
+监督 agent 仍负责：
+
+- 写 contract
+- 限定 allowed/forbidden paths
+- 审查 DAG/writeSet 范围
+- 选择验证命令
+- 记录 handoff 证据
 
-- writing the contract
-- bounding allowed and forbidden paths
-- reviewing DAG/writeSet scope
-- selecting verification commands
-- recording handoff evidence
+声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
 
-## Removed Sequential Workflow
+## 已移除的顺序工作流
 
-The historical Level 1 sequential command surface has been removed from the public workflow. Do not use `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study` for new work.
+历史 Level 1 顺序 command surface 已从公开工作流移除。新工作不要用 `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study`。
 
-Use the DAG path instead:
+改用 DAG 路径：
 
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-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 .
-```
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+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 .
+```
 
-Legacy `.harness/tasks/<task-id>/.workflow_state.json` files may still be read for compatibility until task status is fully migrated to the DAG-oriented read model. They are not the authority for new task completion.
+遗留 `.harness/tasks/<task-id>/.workflow_state.json` 在 task status 完全迁移到 DAG 导向读模型前仍可读，但不是新任务完成的权威。
 
 ## Outer Loop Runtime
 
-The `loop` command is a long-running task-control layer, not the same thing as the session governance protocol. It records rounds and signals, can run shell verification, Pi review, Cursor fixes, or DAG actions, and can choose the next automatic action.
+`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review、Cursor 修复或 DAG action，并选择下一自动 action。
 
-Supported loop actions are:
+支持的 loop actions：
 
 - `shell-verify`
 - `pi-review`
@@ -156,29 +158,29 @@ Supported loop actions are:
 - `add-signal`
 - `closeout`
 
-Source references:
+源码参考：
 
 - `src/commands/loop.ts`
 - `src/workflows/loop/actions.ts`
 - `src/workflows/loop/state.ts`
 - `src/workflows/loop/rounds.ts`
 
-## Debugging And TDD
+## 调试与 TDD
 
-Use the methodology docs when the task demands it:
+任务需要时使用方法论文档：
 
-- behavior changes and bug fixes: `docs/harness-methodology-tdd.md`
-- completion or handoff claims: `docs/harness-methodology-verification.md`
-- failures and unexpected behavior: `docs/harness-methodology-debugging.md`
+- 行为变更与 bug 修复：`docs/harness-methodology-tdd.md`
+- 完成或 handoff 声明：`docs/harness-methodology-verification.md`
+- 失败与意外行为：`docs/harness-methodology-debugging.md`
 
 ## Handoff
 
-A handoff should state:
+Handoff 应说明：
 
-- what changed
-- what was intentionally left out
-- which verification commands ran
-- whether contracts, docs, tests, or scripts were affected
-- any remaining risks or follow-up work
+- 改了什么
+- 有意未做什么
+- 跑了哪些验证命令
+- 是否影响契约、文档、测试或脚本
+- 剩余风险或后续工作
 
-For substantial work, update `docs/progress/`, `docs/reports/`, the active exec plan, or `docs/decisions/` so the next session can resume without relying on chat history.
+较大工作应更新 `docs/progress/`、`docs/reports/`、active exec plan 或 `docs/decisions/`，以便下一会话不依赖聊天历史。

package/docs/harness-methodology-verification.md

@@ -1,27 +1,27 @@
-# Verification Methodology
+# 验证方法论
 
-Completion claims require current evidence.
+完成声明需要当前证据。
 
-## Gate Function
+## 门禁函数
 
-1. Identify the command that proves the claim.
-2. Run the full command.
-3. Read the output and exit code.
-4. Fix failures or report the exact failing state.
-5. Only then claim the result.
+1. 确定能证明声明的命令
+2. 完整运行该命令
+3. 读输出与 exit code
+4. 修失败或报告确切失败状态
+5. 然后再声明结果
 
-## Common Gates
+## 常见门禁
 
-| Claim | Command |
+| 声明 | 命令 |
 |---|---|
-| Governance is valid | `bash scripts/check-repo.sh` |
-| TypeScript compiles | `npm run typecheck` |
-| Behavior is covered | `npm test` |
-| Full local delivery is valid | `bash scripts/ci.sh` |
+| 治理有效 | `bash scripts/check-repo.sh` |
+| TypeScript 编译通过 | `npm run typecheck` |
+| 行为有覆盖 | `npm test` |
+| 完整本地交付有效 | `bash scripts/ci.sh` |
 
 ## Red Flags
 
-- claiming completion from intent
-- relying on stale command output
-- using a narrow check for a broad claim
-- skipping failed command details
+- 凭意图声明完成
+- 依赖陈旧命令输出
+- 用窄检查支撑宽声明
+- 跳过失败命令的细节

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/loop-agent-harness.md

@@ -1,41 +1,41 @@
 # loop-agent Harness
 
-loop-agent provides a local harness for structured agent work.
-
-## Runtime Areas
-
-- `.harness/tasks/` stores task source, constraints, state, and loop facts.
-- `.harness/dag-runs/` stores DAG run state and artifacts.
-- `.harness/runs/` stores one-shot tool run evidence.
-- `.harness/cache/` stores local runtime cache.
-- `.harness/live/` stores transient live-session files.
-
-## Skill Instructions
-
-- `skills/loop-agent/` stores loop-agent's repo-owned skill instructions and references.
-- `skills/<skill-name>/` stores local copies of skills referenced by DAG templates, including supervised implementation roles.
-- Historical `skill/` is no longer a required repository path; runtime lookup keeps it only as a compatibility fallback for `loop-agent`.
-
-## Package Assets
-
-The npm package includes static capability assets needed to run and explain the harness: `bin/`, `dist/`, `skills/`, top-level `docs/*.md`, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`.
-
-Generated or historical task facts are not package assets. Existing files under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository's history; the package carries only the directory README files for those areas.
-
-When `loop-agent` is installed from npm and used against another project, DAG skill instructions resolve from configured, user, or target-local skill directories when present, then fall back to the package-bundled `skills/`. A target project may add local skills, but it does not need loop-agent's source history or a copied `skills/` directory to use the default DAG workflow.
-
-## Command Surfaces
-
-- `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`
-
-## Verification Preset
-
-The shell preset `loop-agent-standard-verify` runs typecheck and focused DAG tests. Full delivery should still use:
+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