@tea-agent/loop-agent 0.2.1 → 0.3.0

package/AGENTS.md

@@ -1,7 +1,7 @@
-<!-- CODEGRAPH_START -->
-## CodeGraph
-
-如果仓库根目录存在 `.codegraph/`，在理解或定位代码前优先使用 CodeGraph，再考虑 rg/fd 或手动读文件。
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+如果仓库根目录存在 `.codegraph/`，在理解或定位代码前优先使用 CodeGraph，再考虑 rg/fd 或手动读文件。
 <!-- CODEGRAPH_END -->
 
 # AGENTS.md
@@ -16,14 +16,14 @@
 - 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
 - 先验证基线，再叠加改动；如果当前基线已坏，优先定位基线问题。
 - 完成定义必须可验证；不能靠删测试、降标准或模糊描述制造“完成”。
-- 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
-- 在 DAG runtime 中，搜索/侦察是显式节点：标准路径是 Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
-- runtime 边界、command registry、skill entry 和架构 import 方向是可机器校验的治理契约；相关细节以 `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 的任务。
-- 反复出现的约束要固化为文档、脚本、检查项、测试或模板。
+- 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
+- 在 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 明确约定为脚手架且标出后续闭环。
 
 ## 开始顺序
@@ -34,32 +34,32 @@
 2. 阅读 `README.md`。
 3. 阅读 `harness.json`。
 4. 阅读 `docs/README.md`。
-5. 如果是实现类工作，继续阅读：
-   - `docs/development-principles.md`
-   - `docs/feature-workflow.md`
-   - `docs/verification-matrix.md`
-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`
-8. 查看最近提交、相关执行计划、progress/report，确认当前上下文。
-9. 检查 `git status --short --branch`。
-10. 运行本次任务相关的最小基线验证。
+5. 如果是实现类工作，继续阅读：
+   - `docs/development-principles.md`
+   - `docs/feature-workflow.md`
+   - `docs/verification-matrix.md`
+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`
+8. 查看最近提交、相关执行计划、progress/report，确认当前上下文。
+9. 检查 `git status --short --branch`。
+10. 运行本次任务相关的最小基线验证。
 
 ## 会话协议
 
 1. Orient：读入口文档、相关专题、最近变更和现有实现。
 2. Select：只选一个清晰工作块；避免把重构、新功能、文档迁移混在一轮里。
-3. Contract：写清本轮交付物、非目标、完成标准、验证方法和失败条件。
-4. Implement：做最小增量实现，同步维护必要文档、脚本和测试。
-5. Verify：优先跑快速反馈，再跑必要的真实路径验证。
-6. Converge Docs：检查 README、AGENTS.md、CHANGELOG.md、docs/README.md、相关治理文档、skills references、website docs、初始化模板和脚本说明是否仍与实际行为一致；只更新与本次变更相关的内容，不做顺手文档迁移。
-7. Handoff：更新 progress/report/plan 中有长期价值的信息，写清风险、剩余项和下一步。
+3. Contract：写清本轮交付物、非目标、完成标准、验证方法和失败条件。
+4. Implement：做最小增量实现，同步维护必要文档、脚本和测试。
+5. Verify：优先跑快速反馈，再跑必要的真实路径验证。
+6. Converge Docs：检查 README、AGENTS.md、CHANGELOG.md、docs/README.md、相关治理文档、skills references、website docs、初始化模板和脚本说明是否仍与实际行为一致；只更新与本次变更相关的内容，不做顺手文档迁移。
+7. Handoff：更新 progress/report/plan 中有长期价值的信息，写清风险、剩余项和下一步。
 
-这套会话协议不是 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 并记录边界与验证证据。
+这套会话协议不是 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 并记录边界与验证证据。
 
 ## 项目地图
 
@@ -77,15 +77,16 @@
 - 每次任务只推进一个清晰、有边界的工作块。
 - 保留无关的用户改动，不要回退自己没有做的修改。
 - 优先沿用现有 helper、目录边界和局部模式，再考虑新增抽象。
-- 长期决策写入 `docs/`，不要只留在聊天里。
-- 面向使用者的新增、修改、删除或修复，应同步更新根目录 `CHANGELOG.md`；保持版本级摘要即可，不写过细技术细节。
+- 长期决策写入 `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，而不是只在对话里提一句。
+- 涉及 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，而不是只在对话里提一句。
 - 涉及 harness 流程变化时，优先把变化落到 `harness.json`、模板、脚本或治理文档，而不是只改提示词。
 
 ## 验证
@@ -103,17 +104,18 @@ bash scripts/ci.sh
 
 Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash。CLI、Node 代码、模板和提示词里的实际文件路径必须兼容 macOS 与 Windows：优先使用平台原生临时目录和 `path`/`os.tmpdir()`；仅在 repo 引用、JSON/Markdown 证据引用和 glob 约定中使用 `/` 作为稳定分隔符。
 
-文档站相关变更还需要按范围运行：
-
-```bash
-npm run docs:build
-```
-
-按变更类型补充定向验证：
-
+文档站相关变更还需要按范围运行：
+
+```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 中。
+- 发布包范围：运行 `npm run build`、`node bin/loop-agent.js --help` 和 `npm pack --dry-run`，确认初始化所需静态资料在 package files 中。
 
 ## 交接
 
@@ -130,9 +132,9 @@ npm run docs:build
 
 - 不要在未读相关文档的前提下直接大改。
 - 不要一次混合重构、新功能和文档大迁移而没有清晰边界。
-- 不要把仅存在于对话里的约束当作长期知识。
-- 不要在缺少验证的情况下宣称完成。
-- 不要假设系统没有某个能力；先搜索再判断。
-- 不要用 stub、假数据通路或注释承诺替代真正交付。
-- 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料；个人工具配置应留在用户级配置或本机会话上下文。
-- 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验；新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目，必须写清原因和替代入口。
+- 不要把仅存在于对话里的约束当作长期知识。
+- 不要在缺少验证的情况下宣称完成。
+- 不要假设系统没有某个能力；先搜索再判断。
+- 不要用 stub、假数据通路或注释承诺替代真正交付。
+- 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料；个人工具配置应留在用户级配置或本机会话上下文。
+- 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验；新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目，必须写清原因和替代入口。

package/CHANGELOG.md

@@ -2,23 +2,35 @@
 
 这里记录每个版本面向使用者的主要变化。保持简短即可：新增、修改、修复或删除了什么，不需要展开实现细节。
 
-## [0.2.1] - 2026-07-06
+## [0.3.0] - 2026-07-06
 
 ### 新增
 
-- 新增 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。
-
-### 修改
+- 新增 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 与安全补齐。
 
-- 更新本仓库与目标项目初始化后的 `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`。
+## [0.2.1] - 2026-07-06
 
-### 修复
+### 新增
 
-- 修复 `check-harness-runtime-clean.sh` 与 CLI contract 集成测试在 full-suite 负载下可能因默认 5s Vitest timeout 超时的问题，保留真实 shell/CLI 检查和断言。
+- 新增 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。
 
-## [0.2.0] - 2026-07-05
+### 修改
+
+- 更新本仓库与目标项目初始化后的 `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
 
 ### 新增
 

package/README.md

@@ -15,9 +15,10 @@
 作为 CLI 使用时，安装已发布包：
 
 ```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --help
-```
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
+loop-agent --help
+```
 
 检查当前项目的 loop-agent 配置：
 
@@ -45,14 +46,25 @@ loop-agent inspect
 如果手动运行 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>
-```
-
-`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`。
+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>
+```
+
+`init instructions` 会输出给模型/Agent 执行完整初始化的指引包，不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 `docs/`，复制 repo-local `skills/`，生成语言无关的治理脚本矩阵、中文根 README 入口、目标项目版治理文档和 `.harness/` 骨架；已有 README 会保留用户正文并插入/更新 loop-agent managed block。
+
+新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
+
+```bash
+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
+```
+
+`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 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 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
 
@@ -159,7 +171,7 @@ Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash
 
 ## 发布包内容
 
-发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
+发布包包含静态运行和指导资料：`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，不携带本仓库已有历史记录。
 

package/dist/application/dag/args.js

@@ -159,6 +159,7 @@ export function parseDagValidateArgs(args) {
     let dagPath;
     let strictModelMatrix = false;
     let strictGovernance = false;
+    let strictSkills = false;
     const forbidExecutors = [];
     let spineTaskId;
     for (let i = 0; i < args.length; i += 1) {
@@ -185,6 +186,10 @@ export function parseDagValidateArgs(args) {
             strictGovernance = true;
             continue;
         }
+        if (arg === "--strict-skills") {
+            strictSkills = true;
+            continue;
+        }
         if (arg === "--forbid-executor") {
             const executor = args[++i];
             if (!executor) {
@@ -230,6 +235,7 @@ export function parseDagValidateArgs(args) {
         dagPath: path.resolve(dagPath),
         strictModelMatrix,
         strictGovernance,
+        strictSkills,
         forbidExecutors,
         spineTaskId,
     };

package/dist/application/dag/generate-task-dag.js

@@ -233,6 +233,7 @@ export async function generateTaskDagUseCase(input) {
     if (!shouldRunExecution(parsed)) {
         return {
             mode: "generate+validate",
+            message: "DAG draft created",
             ok: true,
             taskId: initResult.taskId,
             outputPath,
@@ -264,6 +265,7 @@ export async function generateTaskDagUseCase(input) {
     });
     return {
         mode: resolveExecutionMode(parsed),
+        message: "DAG draft created",
         ok: true,
         taskId: initResult.taskId,
         outputPath,

package/dist/application/dag/run-dag.js

@@ -72,6 +72,7 @@ export async function runDagUseCase(input) {
         const canvasError = await flushCanvasSafely(canvas);
         return {
             mode: "dry-run",
+            message: "DAG run prepared",
             title: spec.title,
             taskCount: spec.tasks.length,
             ranks: summary.ranks,
@@ -94,6 +95,7 @@ export async function runDagUseCase(input) {
     if (resolvedCanvasPath) {
         return {
             ...summary,
+            message: "DAG run finished",
             next: buildRunDagNextSteps(summary.runId),
             canvasPath: resolvedCanvasPath,
             ...(canvasError ? { canvasError } : {}),
@@ -101,6 +103,7 @@ export async function runDagUseCase(input) {
     }
     return {
         ...summary,
+        message: "DAG run finished",
         next: buildRunDagNextSteps(summary.runId),
     };
 }

package/dist/application/dag/validate-dag.js

@@ -4,6 +4,8 @@ import { assertValidDagSpec, collectExecutorModelWarnings, collectForbiddenExecu
 import { inferGovernanceProfile } from "../../workflows/dag/governance-profile.js";
 import { topoSortToRanks } from "../../workflows/dag/topo.js";
 import { runSpineAudit } from "../../governance/spine-audit.js";
+import { resolveDagNodeSkills } from "../../workflows/dag/skills.js";
+import { resolveDagSkillInstructions } from "../../workflows/dag/skill-instructions.js";
 function formatModelMatrixWarnings(warnings) {
     return warnings.map((warning) => ({
         executor: warning.executor,
@@ -55,6 +57,36 @@ function ensureNoForbiddenExecutors(spec, forbidExecutors, rawTaskExecutors) {
         .join("; ");
     throw new Error(`forbidden executor present: ${details}`);
 }
+async function ensureStrictSkillResolution(spec, repoRoot) {
+    const failures = [];
+    for (const task of spec.tasks) {
+        if (task.executor !== "pi" && task.executor !== "cursor")
+            continue;
+        const skills = resolveDagNodeSkills(spec, task);
+        if (skills.length === 0)
+            continue;
+        const resolved = await resolveDagSkillInstructions(skills, {
+            cwd: repoRoot,
+            perSkillMaxChars: 100_000,
+            totalMaxChars: 1_000_000,
+        });
+        for (const entry of resolved) {
+            if (entry.resolution !== "resolved") {
+                failures.push(`${task.id}:${entry.name}:${entry.resolution}${entry.error ? `:${entry.error}` : ""}`);
+                continue;
+            }
+            if (entry.truncated) {
+                failures.push(`${task.id}:${entry.name}:truncated`);
+            }
+            for (const unresolved of entry.unresolvedReferences ?? []) {
+                failures.push(`${task.id}:${entry.name}:unresolved-reference:${unresolved.path}:${unresolved.reason}`);
+            }
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(`strict skill audit failed: ${failures.join("; ")}`);
+    }
+}
 export async function validateDagUseCase(input) {
     const spec = await loadDagSpecFromFile(input.dagPath);
     const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
@@ -65,6 +97,9 @@ export async function validateDagUseCase(input) {
     if (input.strictModelMatrix) {
         ensureStrictModelMatrix(warnings);
     }
+    if (input.strictSkills) {
+        await ensureStrictSkillResolution(spec, input.repoRoot);
+    }
     const spineAudit = input.spineTaskId
         ? await runSpineAudit(input.repoRoot, input.spineTaskId)
         : undefined;
@@ -81,9 +116,14 @@ export async function validateDagUseCase(input) {
     const { ranks } = topoSortToRanks(spec);
     const governanceProfile = inferGovernanceProfile(spec);
     return {
+        message: "DAG validation passed",
         title: spec.title,
         taskCount: spec.tasks.length,
         ranks,
+        checks: {
+            writeSets: "checked",
+            decisionGates: "checked",
+        },
         governanceProfile,
         spineAudit: spineAudit
             ? {

package/dist/cli/command-definitions.js

@@ -50,7 +50,7 @@ export function formatSubcommandUsageError(name, subcommands) {
     return `usage: ${formatSubcommandUsage(name, subcommands)}`;
 }
 const DOCS_SUBCOMMANDS = ["audit", "archive"];
-const INIT_SUBCOMMANDS = ["instructions", "doctor"];
+const INIT_SUBCOMMANDS = ["instructions", "doctor", "check-update", "update"];
 const EXAMPLES_SUBCOMMANDS = ["list", "show", "copy"];
 const CLOSEOUT_SUBCOMMANDS = ["task"];
 const PLAN_SUBCOMMANDS = ["list"];
@@ -145,7 +145,7 @@ export const COMMAND_DEFINITIONS = [
         adapter: "none",
         tier: "primary",
         intent: "Initialize a target repository with loop-agent harness capabilities.",
-        usage: "init [instructions|doctor] [--profile full|minimal] [--merge]",
+        usage: "init [instructions|doctor|check-update|update] [--profile full|minimal] [--merge] [--json|--markdown] [--bootstrap-surface|--apply-safe]",
         subcommands: [...INIT_SUBCOMMANDS],
         handler: async ({ repoRoot, subcommand, rest }) => {
             await runInit(repoRoot, [subcommand, ...rest].filter(Boolean));

package/dist/cli/program.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
 import { resolveAdapter } from "../adapters/index.js";
@@ -50,10 +51,22 @@ import { handleStandaloneOneShotCommandError } from "../shared/one-shot-prompt-a
 import { runDagDecisionInspect, runDagDecisionValidate, } from "../workflows/dag/decision-envelope.js";
 import { runDagDoctor, runDagStatus } from "../workflows/dag/lifecycle.js";
 import { CODE_AGENT_COMMAND_MANIFEST } from "./catalog.js";
-function resolveRepoRootOnly(command, defaultRepoRoot) {
+function readPackageVersion() {
+    try {
+        const raw = readFileSync(new URL("../../package.json", import.meta.url), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string")
+            return parsed.version;
+    }
+    catch {
+        // Fall back only if the package metadata is unexpectedly unavailable.
+    }
+    return "0.0.0";
+}
+function resolveRepoRootOnly(command, defaultRepoRoot, behavior) {
     const options = collectGlobalOptions(command);
     const repoRoot = path.resolve(options.repoRoot ?? defaultRepoRoot);
-    if (options.repoRoot)
+    if (options.repoRoot && !behavior?.quiet)
         console.log(`[loop-agent] repo root: ${repoRoot}`);
     return repoRoot;
 }
@@ -341,6 +354,7 @@ function configureDagValidate(command) {
         .option("--dag <path>", "DAG spec path")
         .option("--strict-models", "fail on model routing warnings")
         .option("--strict-governance", "fail on governance warnings")
+        .option("--strict-skills", "fail on missing, errored, truncated, or unresolved skill instructions")
         .option("--forbid-executor <executor>", "forbid executor", (value, previous = []) => [
         ...previous,
         value,
@@ -474,7 +488,9 @@ async function runPiPromptCommand(args) {
     }
 }
 async function runInitCommand(args, command, defaultRepoRoot) {
-    await runInit(resolveRepoRootOnly(command, defaultRepoRoot), commandArgsWithOptions(args, command));
+    const initArgs = commandArgsWithOptions(args, command);
+    const quiet = initArgs.includes("--json") || initArgs.includes("--markdown");
+    await runInit(resolveRepoRootOnly(command, defaultRepoRoot, { quiet }), initArgs);
 }
 async function runExamplesCommand(args, command, defaultRepoRoot) {
     await runExamples(resolveRepoRootOnly(command, defaultRepoRoot), commandArgsWithOptions(args, command));
@@ -484,6 +500,7 @@ export function buildLoopAgentProgram(options) {
     program
         .name("loop-agent")
         .description("Loop Agent task and DAG automation CLI")
+        .version(readPackageVersion(), "-V, --version", "display version")
         .showHelpAfterError()
         .option("--repo-root <path>", "repository root")
         .option("--adapter <name>", "harness adapter name")
@@ -526,7 +543,10 @@ export function buildLoopAgentProgram(options) {
                 .option("--no-merge", "skip existing files")
                 .option("--provider <provider>", "model provider")
                 .option("--model <model>", "model name")
-                .option("--json", "print JSON");
+                .option("--json", "print JSON")
+                .option("--markdown", "print Markdown")
+                .option("--bootstrap-surface", "write an inferred .harness/init-surface.json baseline")
+                .option("--apply-safe", "apply deterministic safe init updates");
             command.action(async (args, _options, actionCommand) => runInitCommand(args, actionCommand, options.defaultRepoRoot));
             addStandaloneSubcommands(command, entry.subcommands ?? [], (args, actionCommand) => runInitCommand(args, actionCommand, options.defaultRepoRoot));
             program.addCommand(command);