@tea-agent/loop-agent 0.2.0 → 0.3.0

package/AGENTS.md

@@ -1,5 +1,3 @@
-@/Users/mac/.codex/RTK.md
-
 <!-- CODEGRAPH_START -->
 ## CodeGraph
 
@@ -18,12 +16,15 @@
 - 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
 - 先验证基线，再叠加改动；如果当前基线已坏，优先定位基线问题。
 - 完成定义必须可验证；不能靠删测试、降标准或模糊描述制造“完成”。
-- 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
-- 在 DAG runtime 中，搜索/侦察是显式节点：标准路径是 Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
-- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本确为 Bash 脚本时使用 Git Bash 或已配置的兼容 Bash，不要求 Windows 环境适配 POSIX 路径。
-- 用 loop-agent 迭代本仓库时，控制器必须来自已发布的 npm 安装包；首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制可能改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务。
-- 反复出现的约束要固化为文档、脚本、检查项、测试或模板。
-- 禁止占位实现；除非 contract 明确约定为脚手架且标出后续闭环。
+- 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
+- 在 DAG runtime 中，搜索/侦察是显式节点：标准路径是 Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
+- init surface、runtime 边界、command registry、skill entry 和架构 import 方向是可机器校验的治理契约；相关细节以 `docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/` 和 `scripts/check-*.sh` 为准，顶层 `AGENTS.md` 只指路，不重复维护事实源。
+- 本仓库既是 loop-agent 源项目，也是目标项目初始化体验的默认模板；任何新增命令、脚本、文档、skill、模板或发布包内容，都要判断它应由 npm 包内置提供，还是由 `loop-agent init` 投影到目标项目，避免出现“本项目能用、初始化项目缺能力”。
+- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。
+- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本确为 Bash 脚本时使用 Git Bash 或已配置的兼容 Bash，不要求 Windows 环境适配 POSIX 路径。
+- 用 loop-agent 迭代本仓库时，控制器必须来自已发布的 npm 安装包；首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制可能改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务。
+- 反复出现的约束要固化为文档、脚本、检查项、测试或模板。
+- 禁止占位实现；除非 contract 明确约定为脚手架且标出后续闭环。
 
 ## 开始顺序
 
@@ -37,13 +38,16 @@
    - `docs/development-principles.md`
    - `docs/feature-workflow.md`
    - `docs/verification-matrix.md`
-6. 如果任务涉及测试纪律、验证声明或调试，继续阅读：
+6. 如果任务涉及命令入口、执行流程、executor、初始化投影、skills、脚本矩阵、发布包范围或治理检查，继续阅读：
+   - `docs/architecture/runtime-boundaries.md`
+   - `docs/loop-agent-harness.md`
+7. 如果任务涉及测试纪律、验证声明或调试，继续阅读：
    - `docs/harness-methodology-tdd.md`
    - `docs/harness-methodology-verification.md`
    - `docs/harness-methodology-debugging.md`
-7. 查看最近提交、相关执行计划、progress/report，确认当前上下文。
-8. 检查 `git status --short --branch`。
-9. 运行本次任务相关的最小基线验证。
+8. 查看最近提交、相关执行计划、progress/report，确认当前上下文。
+9. 检查 `git status --short --branch`。
+10. 运行本次任务相关的最小基线验证。
 
 ## 会话协议
 
@@ -52,9 +56,10 @@
 3. Contract：写清本轮交付物、非目标、完成标准、验证方法和失败条件。
 4. Implement：做最小增量实现，同步维护必要文档、脚本和测试。
 5. Verify：优先跑快速反馈，再跑必要的真实路径验证。
-6. Handoff：更新 progress/report/plan 中有长期价值的信息，写清风险、剩余项和下一步。
+6. Converge Docs：检查 README、AGENTS.md、CHANGELOG.md、docs/README.md、相关治理文档、skills references、website docs、初始化模板和脚本说明是否仍与实际行为一致；只更新与本次变更相关的内容，不做顺手文档迁移。
+7. Handoff：更新 progress/report/plan 中有长期价值的信息，写清风险、剩余项和下一步。
 
-这套会话协议不是 DAG runtime 的节点序列。复杂实现默认采用 Agent DAG：主 agent 负责拆任务、写 contract、限制路径、审查 DAG/writeSet、盯验证与 handoff；runtime 通过 `loop-agent dag run-task` 生成 DAG、`loop-agent dag validate` 校验、`loop-agent run-dag` 按依赖 ranks 执行节点。标准生成 DAG 的主干默认是 `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`。微小任务或 DAG runtime 自身修复也应优先使用 DAG 或 one-shot `pi-prompt` / `cursor-prompt` escape hatch。
+这套会话协议不是 DAG runtime 的节点序列。复杂实现默认采用 Agent DAG；具体节点拓扑、profile routing、writer 选择和 runner 行为以 `docs/feature-workflow.md` 与 `src/workflows/` 为准。主 agent 负责拆任务、写 contract、把允许/禁止路径写入结构化 task config、审查 DAG/writeSet/profile/shell verification、盯验证与 handoff。微小任务或 DAG runtime 自身修复也应优先使用 DAG，或使用 one-shot `pi-prompt` / `cursor-prompt` escape hatch 并记录边界与验证证据。
 
 ## 项目地图
 
@@ -74,6 +79,11 @@
 - 优先沿用现有 helper、目录边界和局部模式，再考虑新增抽象。
 - 长期决策写入 `docs/`，不要只留在聊天里。
 - 面向使用者的新增、修改、删除或修复，应同步更新根目录 `CHANGELOG.md`；保持版本级摘要即可，不写过细技术细节。
+- 涉及 `loop-agent init` 或目标项目投影的改动，必须同步考虑目标项目生成物：`AGENTS.md`、`README.md`、`harness.json`、`docs/`、`scripts/`、`skills/`、`.harness/prompts` 和 npm 包内置 assets。
+- 涉及初始化能力演化时，按 `docs/init-surface.manifest.json` 与 `scripts/check-init-evolution-needed.sh` 分级处理：小改 advisory，中等 surface-check，高影响才需要模型审查；不要把所有小改动升级成重流程。
+- 通用脚本、skill 和模板可以复制或投影；项目相关 README、验证命令、发布/维护脚本必须基于模板和目标项目真实文件生成，不假定目标项目是 TypeScript、Node、前端、后端或工具项目。
+- 涉及 CLI command、skill entry、runtime boundary、import 方向或发布包范围时，同步更新对应文档、catalog/definition、治理脚本和测试，避免 README、skill reference、CLI help、npm 包内容互相漂移。
+- 完成相关更新后必须做文档收敛：如果 README、AGENTS.md、CHANGELOG.md、docs、skills、website、初始化生成模板或脚本说明不需要更新，应在交接里写明理由。
 - 不提交占位实现。
 - 没有新鲜验证证据时，不声明工作完成。
 - 发现新 bug、技术债或契约漂移时，写回当前 plan、progress 或 report，而不是只在对话里提一句。
@@ -83,16 +93,16 @@
 
 用 `docs/verification-matrix.md` 选择命令。常用门禁：
 
-```bash
-npm run typecheck
-npm test
-npm run build
-node bin/loop-agent.js --help
-bash scripts/check-repo.sh
-bash scripts/ci.sh
-```
-
-Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash。CLI、Node 代码、模板和提示词里的实际文件路径必须兼容 macOS 与 Windows：优先使用平台原生临时目录和 `path`/`os.tmpdir()`；仅在 repo 引用、JSON/Markdown 证据引用和 glob 约定中使用 `/` 作为稳定分隔符。
+```bash
+npm run typecheck
+npm test
+npm run build
+node bin/loop-agent.js --help
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+```
+
+Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash。CLI、Node 代码、模板和提示词里的实际文件路径必须兼容 macOS 与 Windows：优先使用平台原生临时目录和 `path`/`os.tmpdir()`；仅在 repo 引用、JSON/Markdown 证据引用和 glob 约定中使用 `/` 作为稳定分隔符。
 
 文档站相关变更还需要按范围运行：
 
@@ -100,6 +110,13 @@ Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash
 npm run docs:build
 ```
 
+按变更类型补充定向验证：
+
+- 初始化能力或目标项目投影：运行 `test/init-command.test.ts`，并在临时目标项目执行 `loop-agent init --profile full --merge`、`loop-agent init doctor`、`loop-agent inspect`、`loop-agent docs audit` 和目标项目 `bash scripts/check-repo.sh`。
+- init surface 或初始化能力演化：运行 `bash scripts/check-init-evolution-needed.sh` 和 `bash scripts/check-init-surface.sh`；高影响或发布前按需使用 `--strict` 并参考 `skills/init-capability-evolution/` 与 `docs/templates/init-evolution-review.md`。
+- runtime boundary / command registry / skill entry：运行 `bash scripts/check-architecture-boundaries.sh`、`bash scripts/check-command-registry-drift.sh`、`bash scripts/check-skill-entry.sh`，并确保 `bash scripts/check-repo.sh` 覆盖这些检查。
+- 发布包范围：运行 `npm run build`、`node bin/loop-agent.js --help` 和 `npm pack --dry-run`，确认初始化所需静态资料在 package files 中。
+
 ## 交接
 
 较大的工作结束时记录：
@@ -119,3 +136,5 @@ npm run docs:build
 - 不要在缺少验证的情况下宣称完成。
 - 不要假设系统没有某个能力；先搜索再判断。
 - 不要用 stub、假数据通路或注释承诺替代真正交付。
+- 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料；个人工具配置应留在用户级配置或本机会话上下文。
+- 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验；新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目，必须写清原因和替代入口。

package/CHANGELOG.md

@@ -1,53 +1,81 @@
-# 更新日志
-
-这里记录每个版本面向使用者的主要变化。保持简短即可：新增、修改、修复或删除了什么，不需要展开实现细节。
-
-## [0.2.0] - 2026-07-05
+# 更新日志
+
+这里记录每个版本面向使用者的主要变化。保持简短即可：新增、修改、修复或删除了什么，不需要展开实现细节。
+
+## [0.3.0] - 2026-07-06
 
 ### 新增
 
-- 新增 `loop-agent init` 初始化目标项目，包含模型指引输出、merge 初始化、初始化体检、repo-local skills 投影、语言无关治理脚本矩阵、runtime boundary 文档、skill entry/architecture boundary 检查和目标项目版治理文档；根 README 默认生成中文项目入口，并以 managed block 合并已有 README；模型执行初始化时必须在同一轮自动完成项目识别、README/验证矩阵适配和体检闭环；`examples` 改为工具内置查看/按需复制，不在初始化时默认写入目标仓库。
-
-### 修改
-
-- `harness.json` 支持用 `adapter: "loop-agent"` 与真实项目名分离，目标项目无需把 `project` 写成 `loop-agent` 才能使用默认 adapter。
-- README 重组为兼顾 npm/GitHub 展示和本仓库迭代导航的入口，明确区分快速开始、目标项目初始化、任务运行、核心概念、本仓库开发和发布包内容，并补充新项目初始化时可直接交给模型执行的提示词。
+- 新增 init surface manifest 与 `scripts/check-init-surface.sh`，自动校验 npm 发布包范围和 `loop-agent init --profile full` 对目标项目的关键文件投影。
+- 新增 `init-capability-evolution` skill、init evolution review 模板与 `scripts/check-init-evolution-needed.sh`，按 advisory / surface-check / model-review 三档提示初始化能力是否需要模型审查；默认不阻塞小改动。
+- CLI 新增 `-V, --version` / `--version`，输出当前 package 版本且不要求 repo adapter。
+- 新增 `loop-agent init check-update` 与 `loop-agent init update`，为旧版初始化过的目标项目生成 deterministic actions、model merge tasks、human decisions，并支持 `.harness/init-surface.json` baseline bootstrap 与安全补齐。
 
-### 修复
-
-- npm 发布包范围纳入 `docs/architecture/runtime-boundaries.md`，确保 runtime boundary 治理文档随 0.2.0 包一起发布。
-- Cursor DAG worker 在构建产物中使用 `.js` worker 入口且不依赖 `tsx`，避免发布包/本地 build 运行 Cursor 节点时先因 worker 入口解析失败。
-
-## [0.1.0] - 已发布
+## [0.2.1] - 2026-07-06
 
 ### 新增
 
-- Agent DAG 支持 no-Cursor 环境：Pi 只读规划/审查、Pi `toolProfile: "write"` 受控写入、shell 验证。
-- 默认 implementation / repair writer 使用 `executor: "pi"` 加 `toolProfile: "write"`。
-- executor 配置保持 `pi` / `cursor` / `shell` / `static` 四类；Cursor 仍是显式启用的可选 backend。
-- Windows 环境下 shell verification 可自动使用 Git Bash。
-- Dynamic Workflow DAG Engine 的编译、校验、运行与回放命令。
-- 仓库内置 `skills/` 目录，用于 DAG 模板和本项目技能引用。
-- CLI 入口迁移为 commander 驱动的 command tree，顶层 help、子命令 help 和未知命令错误改用 commander 语义，同时保留既有命令能力。
-- `commander` 成为正式运行时依赖。
-- npm 发布包入口加载构建产物 `dist/cli.js`，并携带静态能力资料：`skills/`、顶层治理文档、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
-- DAG skill 指令在目标项目没有本地 skill 时会回退到 npm 包内置 `skills/`，支持发布包作为任意项目的稳定控制器。
+- 新增 Production Readiness v0.1 治理标准、生产可用 checklist 模板，以及 2026-07-06 到 2026-07-12 的生产可用硬化 sprint 执行计划，明确低/中风险单 repo DAG 任务的支持范围、非目标、证据要求、失败分类和最终验证门禁。
+- 新增 DAG production-readiness hardening：`dag validate` / `run-dag` 输出下一步指引，`dag report` 暴露 product-line failure routing 和 Operator Next Steps，`dag doctor --run-id --markdown` 输出失败诊断，failed `dag closeout-draft` 生成 Failure Handoff。
+- `dag run-task`、`dag validate`、`run-dag` 的 JSON 输出新增稳定 `message` summary；`dag validate` 额外输出 write set 与 decision gate check 摘要。
+- Dynamic Workflow node 现在可声明 `skills`，编译到 DAG 时会保留到对应 task、动态展开 child task 和 loop body task。
+- 新增 repo-local vetted skill registry、首批 role skill wrappers，以及 opt-in `dag validate --strict-skills` audit gate。
 
 ### 修改
-
-- 默认 DAG 和模板从 Cursor-heavy 调整为 Pi read-only + Pi write profile + shell verify。
-- 移除独立 Pi 写入 executor 概念，写入能力改由 `toolProfile: "write"` 表达。
-- 文档、示例和 skill 指引将 Cursor 描述为可选 backend，而不是默认路径。
-- 治理和校验说明改为覆盖所有受控写入 executor，不再只绑定 Cursor。
-- 顺序式 Level 1 workflow 入口从推荐/公开路径中移除，DAG 成为主路径。
-- DAG 默认工程上下文 skill 从 `agent-context` 调整为 `ai-engineering-context`。
-- `npm run dev` 明确为源码调试入口；用 loop-agent 迭代本仓库时应使用已发布的 npm 安装包作为稳定控制器，安装或升级可用 `@latest`，单次任务执行期记录并冻结实际安装版本。
-- 发布包不携带已有 `docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 任务正文；这些目录的正文由目标仓库运行时生成。
-
-### 修复
-
-- no-Cursor DAG 生成、校验和 runner 测试可以在没有 Cursor 的环境下通过。
-- Windows 路径和 shell 执行相关的跨平台测试问题。
-- `doctor` 的 Pi CLI 探测支持当前 `@earendil-works/pi-coding-agent` 包名，并兼容 Windows npm shim 与跨平台 global npm 安装。
-- DAG draft、final verification 和 closeout draft 的默认临时输出路径改为平台原生临时目录，不再假设 `/tmp` 存在。
-- exec-plan 索引同步检查兼容发布包目录契约 README，不要求 npm 包内 README 链接未打包的源码历史计划正文。
+
+- 更新本仓库与目标项目初始化后的 `AGENTS.md` 工作协议，新增文档收敛步骤、结构化 DAG 写入边界要求，以及 runtime boundary / command registry / skill entry / 发布包范围的定向验证指引。
+- `loop-agent init` 生成的目标项目 `AGENTS.md` 同步包含文档收敛、`task.json.allowedPaths` / `task.json.forbiddenPaths`、DAG 失败诊断与 failure handoff 规则，目标项目文档也会显式导航 production readiness checklist、`dag report`、`dag doctor --run-id --markdown` 和失败 run 的 `dag closeout-draft`。
+
+### 修复
+
+- 修复 `check-harness-runtime-clean.sh` 与 CLI contract 集成测试在 full-suite 负载下可能因默认 5s Vitest timeout 超时的问题，保留真实 shell/CLI 检查和断言。
+
+## [0.2.0] - 2026-07-05
+
+### 新增
+
+- 新增 `loop-agent init` 初始化目标项目，包含模型指引输出、merge 初始化、初始化体检、repo-local skills 投影、语言无关治理脚本矩阵、runtime boundary 文档、skill entry/architecture boundary 检查和目标项目版治理文档；根 README 默认生成中文项目入口，并以 managed block 合并已有 README；模型执行初始化时必须在同一轮自动完成项目识别、README/验证矩阵适配和体检闭环；`examples` 改为工具内置查看/按需复制，不在初始化时默认写入目标仓库。
+
+### 修改
+
+- `harness.json` 支持用 `adapter: "loop-agent"` 与真实项目名分离，目标项目无需把 `project` 写成 `loop-agent` 才能使用默认 adapter。
+- README 重组为兼顾 npm/GitHub 展示和本仓库迭代导航的入口，明确区分快速开始、目标项目初始化、任务运行、核心概念、本仓库开发和发布包内容，并补充新项目初始化时可直接交给模型执行的提示词。
+
+### 修复
+
+- npm 发布包范围纳入 `docs/architecture/runtime-boundaries.md`，确保 runtime boundary 治理文档随 0.2.0 包一起发布。
+- Cursor DAG worker 在构建产物中使用 `.js` worker 入口且不依赖 `tsx`，避免发布包/本地 build 运行 Cursor 节点时先因 worker 入口解析失败。
+
+## [0.1.0] - 已发布
+
+### 新增
+
+- Agent DAG 支持 no-Cursor 环境：Pi 只读规划/审查、Pi `toolProfile: "write"` 受控写入、shell 验证。
+- 默认 implementation / repair writer 使用 `executor: "pi"` 加 `toolProfile: "write"`。
+- executor 配置保持 `pi` / `cursor` / `shell` / `static` 四类；Cursor 仍是显式启用的可选 backend。
+- Windows 环境下 shell verification 可自动使用 Git Bash。
+- Dynamic Workflow DAG Engine 的编译、校验、运行与回放命令。
+- 仓库内置 `skills/` 目录，用于 DAG 模板和本项目技能引用。
+- CLI 入口迁移为 commander 驱动的 command tree，顶层 help、子命令 help 和未知命令错误改用 commander 语义，同时保留既有命令能力。
+- `commander` 成为正式运行时依赖。
+- npm 发布包入口加载构建产物 `dist/cli.js`，并携带静态能力资料：`skills/`、顶层治理文档、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
+- DAG skill 指令在目标项目没有本地 skill 时会回退到 npm 包内置 `skills/`，支持发布包作为任意项目的稳定控制器。
+
+### 修改
+
+- 默认 DAG 和模板从 Cursor-heavy 调整为 Pi read-only + Pi write profile + shell verify。
+- 移除独立 Pi 写入 executor 概念，写入能力改由 `toolProfile: "write"` 表达。
+- 文档、示例和 skill 指引将 Cursor 描述为可选 backend，而不是默认路径。
+- 治理和校验说明改为覆盖所有受控写入 executor，不再只绑定 Cursor。
+- 顺序式 Level 1 workflow 入口从推荐/公开路径中移除，DAG 成为主路径。
+- DAG 默认工程上下文 skill 从 `agent-context` 调整为 `ai-engineering-context`。
+- `npm run dev` 明确为源码调试入口；用 loop-agent 迭代本仓库时应使用已发布的 npm 安装包作为稳定控制器，安装或升级可用 `@latest`，单次任务执行期记录并冻结实际安装版本。
+- 发布包不携带已有 `docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 任务正文；这些目录的正文由目标仓库运行时生成。
+
+### 修复
+
+- no-Cursor DAG 生成、校验和 runner 测试可以在没有 Cursor 的环境下通过。
+- Windows 路径和 shell 执行相关的跨平台测试问题。
+- `doctor` 的 Pi CLI 探测支持当前 `@earendil-works/pi-coding-agent` 包名，并兼容 Windows npm shim 与跨平台 global npm 安装。
+- DAG draft、final verification 和 closeout draft 的默认临时输出路径改为平台原生临时目录，不再假设 `/tmp` 存在。
+- exec-plan 索引同步检查兼容发布包目录契约 README，不要求 npm 包内 README 链接未打包的源码历史计划正文。

package/README.md

@@ -1,50 +1,51 @@
-# loop-agent
-
-`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
-
-它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
-
-## 快速开始
-
-到一个新项目时，可以直接对当前 agent 说：
-
-```text
-请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
-```
-
-作为 CLI 使用时，安装已发布包：
-
-```bash
+# loop-agent
+
+`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
+
+它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
+
+## 快速开始
+
+到一个新项目时，可以直接对当前 agent 说：
+
+```text
+请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
+```
+
+作为 CLI 使用时，安装已发布包：
+
+```bash
 npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
 loop-agent --help
 ```
-
-检查当前项目的 loop-agent 配置：
-
-```bash
-loop-agent doctor
-loop-agent inspect
-```
-
-## 初始化目标项目
-
-在新项目中，最简单的用法是让当前 agent 执行初始化。需要更稳的执行约束时，可以使用下面这段完整提示词：
-
-```text
-请用 loop-agent 完整初始化当前项目。
-
-如果本机还没有 `loop-agent` 命令，请先运行 `npm install -g @tea-agent/loop-agent@latest`，再记录 `npm list -g @tea-agent/loop-agent --depth=0` 的实际版本。
-
-然后运行 `loop-agent init instructions --repo-root .`，按指引使用 full + merge 初始化。需要选择 provider/model，或涉及凭据、成本、部署副作用时先问我；其他能安全默认的选项直接继续。
-
-初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
-
-最后运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .`、`bash scripts/check-repo.sh`，如项目测试入口可识别也运行 `bash scripts/ci-tests.sh` 或 `bash scripts/ci.sh`，并汇报结果、假设和剩余风险。
-```
-
-如果手动运行 CLI，可以使用：
-
-```bash
+
+检查当前项目的 loop-agent 配置：
+
+```bash
+loop-agent doctor
+loop-agent inspect
+```
+
+## 初始化目标项目
+
+在新项目中，最简单的用法是让当前 agent 执行初始化。需要更稳的执行约束时，可以使用下面这段完整提示词：
+
+```text
+请用 loop-agent 完整初始化当前项目。
+
+如果本机还没有 `loop-agent` 命令，请先运行 `npm install -g @tea-agent/loop-agent@latest`，再记录 `npm list -g @tea-agent/loop-agent --depth=0` 的实际版本。
+
+然后运行 `loop-agent init instructions --repo-root .`，按指引使用 full + merge 初始化。需要选择 provider/model，或涉及凭据、成本、部署副作用时先问我；其他能安全默认的选项直接继续。
+
+初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
+
+最后运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .`、`bash scripts/check-repo.sh`，如项目测试入口可识别也运行 `bash scripts/ci-tests.sh` 或 `bash scripts/ci.sh`，并汇报结果、假设和剩余风险。
+```
+
+如果手动运行 CLI，可以使用：
+
+```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>
@@ -52,128 +53,140 @@ loop-agent init doctor --repo-root <target-repo>
 
 `init instructions` 会输出给模型/Agent 执行完整初始化的指引包，不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 `docs/`，复制 repo-local `skills/`，生成语言无关的治理脚本矩阵、中文根 README 入口、目标项目版治理文档和 `.harness/` 骨架；已有 README 会保留用户正文并插入/更新 loop-agent managed block。
 
-当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
-
-初始化生成的 `scripts/ci-tests.sh` 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 `package.json`、`Makefile`、`go.mod`、`Cargo.toml`、Python 测试配置、Maven、Gradle、.NET 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
-
-## 运行任务
-
-创建并运行一个标准 Agent DAG：
+新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
 
 ```bash
-loop-agent new-task <task-id> "任务标题"
-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 .
+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
 ```
 
-`<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
-
-一次性只读评审或有边界写入：
-
-```bash
-loop-agent pi-prompt --cwd . --tools read,grep,find,ls "只读评审这个任务，不要编辑文件。"
-loop-agent pi-prompt --cwd . --tools read,bash,edit,write,grep,find,ls "<包含 allowedPaths 和 forbiddenPaths 的有边界任务说明>"
-```
-
-## 核心概念
-
-- **Agent DAG**：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
-- **`.harness/`**：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
-- **`harness.json`**：描述项目名、治理根目录、模型路由、executor 和验证脚本。
-- **repo-local skills**：目标项目本地的 `skills/` 优先于发布包内置 skills，便于项目定制 agent 行为。
-- **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
-- **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。
-
-## 能力概览
-
-- 生成、校验、执行和汇总 Agent DAG。
-- 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
-- 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
-- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入。
-- 保留 Cursor executor 作为显式启用的可选后端。
-- 通过 shell executor 运行确定性的验证命令。
-- 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
+`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 managed block，不覆盖已有但无法确认来源的本地文件。
 
-## 内置示例
-
-`examples/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
-
-```bash
-loop-agent examples list
-loop-agent examples show example-dag.json
-loop-agent examples copy example-dag.json --repo-root <target-repo>
-```
-
-## 迭代本仓库
-
-如果要用 loop-agent 迭代 loop-agent 本仓库，控制器必须来自已发布的 npm 安装包。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器；首次安装或有意升级可用 `@latest`，但一次自举任务启动后不要在任务中途升级控制器。
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-npm list -g @tea-agent/loop-agent --depth=0
-loop-agent doctor
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
-```
-
-`@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举任务应记录 `npm list -g` 显示的实际版本号。
-
-## 文档导航
-
-| 路径 | 用途 |
-|---|---|
-| `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
-| `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
-| `docs/README.md` | 治理文档索引 |
-| `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
-| `docs/architecture/runtime-boundaries.md` | runtime 层边界和依赖方向 |
-| `skills/loop-agent/` | loop-agent skill 入口和 references |
-| `examples/` | 可复用 DAG 示例 |
-| `website/docs/` | 面向使用者的 Docusaurus 文档站内容 |
-
-## 本仓库开发
-
-本地源码开发：
-
-```bash
-npm install
-npm run build
-node bin/loop-agent.js --help
-npm run dev -- --help
-```
-
-常用验证命令：
-
-```bash
-npm run typecheck
-npm test
-bash scripts/check-repo.sh
-bash scripts/ci.sh
-npm run docs:build
-```
-
-当前 CLI 使用 `commander` 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。
-
-Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash，不要求使用 WSL 或 POSIX 路径。实际文件操作和 `--output` / `--dag` / `--cwd` 参数使用当前平台原生路径；仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 `/` 作为稳定分隔符。
-
-## 发布包内容
-
-发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
-
-`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
-
-DAG skill 指令优先从目标项目或用户配置目录解析；目标项目未提供本地 `skills/` 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或内置 skills 才能获得默认 DAG 能力。
-
-## 发布前检查
-
-发布 npm 包前至少运行：
-
-```bash
-npm run typecheck
-npm test
-npm run build
-node bin/loop-agent.js --help
-npm pack --dry-run
-```
-
-发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。
+当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
+
+初始化生成的 `scripts/ci-tests.sh` 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 `package.json`、`Makefile`、`go.mod`、`Cargo.toml`、Python 测试配置、Maven、Gradle、.NET 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
+
+## 运行任务
+
+创建并运行一个标准 Agent DAG：
+
+```bash
+loop-agent new-task <task-id> "任务标题"
+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>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
+
+一次性只读评审或有边界写入：
+
+```bash
+loop-agent pi-prompt --cwd . --tools read,grep,find,ls "只读评审这个任务，不要编辑文件。"
+loop-agent pi-prompt --cwd . --tools read,bash,edit,write,grep,find,ls "<包含 allowedPaths 和 forbiddenPaths 的有边界任务说明>"
+```
+
+## 核心概念
+
+- **Agent DAG**：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
+- **`.harness/`**：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
+- **`harness.json`**：描述项目名、治理根目录、模型路由、executor 和验证脚本。
+- **repo-local skills**：目标项目本地的 `skills/` 优先于发布包内置 skills，便于项目定制 agent 行为。
+- **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
+- **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。
+
+## 能力概览
+
+- 生成、校验、执行和汇总 Agent DAG。
+- 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
+- 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
+- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入。
+- 保留 Cursor executor 作为显式启用的可选后端。
+- 通过 shell executor 运行确定性的验证命令。
+- 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
+
+## 内置示例
+
+`examples/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
+
+```bash
+loop-agent examples list
+loop-agent examples show example-dag.json
+loop-agent examples copy example-dag.json --repo-root <target-repo>
+```
+
+## 迭代本仓库
+
+如果要用 loop-agent 迭代 loop-agent 本仓库，控制器必须来自已发布的 npm 安装包。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器；首次安装或有意升级可用 `@latest`，但一次自举任务启动后不要在任务中途升级控制器。
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+npm list -g @tea-agent/loop-agent --depth=0
+loop-agent doctor
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+```
+
+`@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举任务应记录 `npm list -g` 显示的实际版本号。
+
+## 文档导航
+
+| 路径 | 用途 |
+|---|---|
+| `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
+| `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
+| `docs/README.md` | 治理文档索引 |
+| `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
+| `docs/production-readiness.md` | Production Readiness v0.1 支持范围、证据和验收标准 |
+| `docs/architecture/runtime-boundaries.md` | runtime 层边界和依赖方向 |
+| `skills/loop-agent/` | loop-agent skill 入口和 references |
+| `examples/` | 可复用 DAG 示例 |
+| `website/docs/` | 面向使用者的 Docusaurus 文档站内容 |
+
+## 本仓库开发
+
+本地源码开发：
+
+```bash
+npm install
+npm run build
+node bin/loop-agent.js --help
+npm run dev -- --help
+```
+
+常用验证命令：
+
+```bash
+npm run typecheck
+npm test
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+npm run docs:build
+```
+
+当前 CLI 使用 `commander` 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。
+
+Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash，不要求使用 WSL 或 POSIX 路径。实际文件操作和 `--output` / `--dag` / `--cwd` 参数使用当前平台原生路径；仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 `/` 作为稳定分隔符。
+
+## 发布包内容
+
+发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
+
+`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
+
+DAG skill 指令优先从目标项目或用户配置目录解析；目标项目未提供本地 `skills/` 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或内置 skills 才能获得默认 DAG 能力。
+
+## 发布前检查
+
+发布 npm 包前至少运行：
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node bin/loop-agent.js --help
+npm pack --dry-run
+```
+
+发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。