@tea-agent/loop-agent 0.10.0 → 0.12.0

package/AGENTS.md

@@ -17,6 +17,7 @@
 - 先验证基线，再叠加改动；如果当前基线已坏，优先定位基线问题。
 - 完成定义必须可验证；不能靠删测试、降标准或模糊描述制造“完成”。
 - 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
+- 受治理 Agent runtime 只有 Pi：DAG writer 固定为 `implement-pi` / `repair-pi`；`cursor-prompt` 仅是显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。
 - 在 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` 投影到目标项目，避免出现“本项目能用、初始化项目缺能力”。
@@ -70,7 +71,7 @@
 - `src/`：loop-agent 运行时代码
 - `test/`：Vitest 测试套件
 - `bin/loop-agent.js`：CLI 可执行入口
-- `skills/`：loop-agent 和 DAG 模板引用的本地 skill 指令与参考资料；`init --profile full` 还会把同一份 skills 镜像到目标项目的 `.agents/skills/`（外部 agent 兼容路径，包内仍只带 `skills/`）。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block，忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实，但保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`。
+- `skills/`：loop-agent 源仓库和 npm 包内置 skill 指令与参考资料；目标项目初始化后只生成 `.agents/skills/`，不再生成根 `skills/`。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block，忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实，但保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`。
 - `.harness/`：任务、DAG、run、cache 和 live state 等运行态目录
 - `docs/`：治理文档、计划、报告和模板
 - `website/`：Docusaurus 用户文档站
@@ -84,7 +85,7 @@
 - 长期决策写入 `docs/`，不要只留在聊天里。
 - 面向使用者的新增、修改、删除或修复，应同步更新根目录 `CHANGELOG.md`；保持版本级摘要即可，不写过细技术细节。
 - 面向用户的中文更新日志、README 和说明文档应使用自然、结果导向的表达：先说明用户能获得什么或问题如何改善，保留必要的命令和产品术语，避免逐字翻译、内部实现细节和无意义的中英混杂。
-- 涉及 `loop-agent init` 或目标项目投影的改动，必须同步考虑目标项目生成物：`AGENTS.md`、`README.md`、`harness.json`、`docs/`、`scripts/`、`skills/`、`.agents/skills/`（skills 镜像）、`.harness/prompts`、`.gitignore`（loop-agent runtime managed block）和 npm 包内置 assets。
+- 涉及 `loop-agent init` 或目标项目投影的改动，必须同步考虑目标项目生成物：`AGENTS.md`、`README.md`、`harness.json`、`ai_workspace/loop-agent/`、`scripts/`、`.agents/skills/`、`.harness/prompts`、`.gitignore`（loop-agent runtime managed block）和 npm 包内置 assets；目标项目根 `docs/` 和根 `skills/` 的旧投影需要由 `init update --apply-safe` 安全迁移或退役。
 - 涉及初始化能力演化时，按 `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 包内容互相漂移。
@@ -143,3 +144,10 @@ npm run docs:build
 - 不要用 stub、假数据通路或注释承诺替代真正交付。
 - 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料；个人工具配置应留在用户级配置或本机会话上下文。
 - 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验；新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目，必须写清原因和替代入口。
+
+## Cursor Cloud specific instructions
+
+这些是 Cursor Cloud VM 上非显而易见、会反复踩的两个环境坑。标准命令仍以 `README.md` 与 `docs/verification-matrix.md` 为准，这里不重复。启动时的 update script 已执行 `nvm use 22` + `npm ci`。
+
+- Node 版本：VM 默认 `node`（`/exec-daemon/node`）是 v22.14.0，但可选依赖 `@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 要求 Node `>=22.19.0`，否则 `npm install`/`npm ci` 会静默跳过它们，导致 `npm run typecheck` 和 `npm run build` 报 `Cannot find module '@earendil-works/...'`。交互式 shell 默认仍是系统 node，跑任何 `npm install`/`npm ci` 前先执行 `nvm use 22`（已预装 v22.22.2）。
+- Git 提交签名会让 git 密集型测试超时：全局 git 配置默认对每次 commit 用 `cursor-git-ssh-keygen`（`gpg.format=ssh` + `commit.gpgsign=true`）签名，该 helper 会间歇性卡住 7–30s，使 `test/worker/delivery/**`、`test/worker/feature/**` 等在临时仓库里做多次 commit 的用例撞上 15/30s 超时而失败（单独跑却能过）。跑 `npm test` 或任何会频繁 commit 的工作前，先对子进程 git 关闭签名：`export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgsign GIT_CONFIG_VALUE_0=false`（或在目标仓库 `git config commit.gpgsign false`）。关闭后整套 `npm test` 约 60s 全绿。这只影响本地/测试环境，不改仓库代码。

package/CHANGELOG.md

@@ -4,36 +4,99 @@
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-07-16
+
 ### 新增
 
-- 严格初始化演化检查现在接受 `Head` 为当前 `HEAD` 可解析祖先提交的报告：只要 `Base` 精确匹配 `--base`、`Head` 是 `HEAD` 或其祖先，且 `reportHead..HEAD` 区间没有新的 `model-review` 高影响路径即可通过。仅 `advisory` 或 `surface-check` 的后续变化不会让已完成的高影响审查失效；`working tree` 等不可解析 Head 与无关历史报告仍被拒绝。
+- 只读 Pi DAG 节点支持 opt-in 安全重试：仅 planner/scout/reviewer/verifier/closeout 角色且无写入能力的 Pi 节点可声明 `retryPolicy`，在同一 run 内重试模型连接中断（`network`）、provider 限流（`rate-limit`）、临时不可用（`unavailable`）或请求 timeout。生成模板默认总尝试 3 次，手工配置最多 5 次，并使用有上限的指数退避。每次 attempt 保留独立证据，节点耗时、Token 与事件数按尝试聚合；后一次成功不会覆盖前一次失败证据。`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点声明策略会在校验阶段失败。未声明策略的历史 DAG 不新增 attempt artifact，行为保持不变。
+- 新增 `taskKind: "backend-test"` 专用 DAG：从需求分析开始，生成并评审后端功能用例，再生成和执行 pytest 自动化，最后产出测试复盘报告；新 DAG 沿用当前 Pi-only runtime、版本化 runtime contract 与既有执行恢复机制。
+
+### 修复
+
+- `loop-agent init check-update` / `init update --apply-safe` 漏检初始化投影文件：fresh `init --profile full` 通过目录复制把整个 `docs/templates/` 与 `skills/`（镜像到 `.agents/skills/`）投影到目标项目，但期望 init surface 只跟踪其中一个子集。旧版本（如 0.11.0）初始化的项目升级 controller 后，缺失的 backend-test 模板、agent-dag schema/prompt、`loop-agent` 必需 references 等文件无法被报告或补齐，`check-update` 会错误返回 `ok: true`。现在期望 surface 会自动发现包内 `docs/templates/` 与 `skills/` 的所有文件并纳入校验；`check-update` 会报告全部缺失/陈旧 surface；`apply-safe` 会确定性补齐缺失文件，对无法证明 ownership 的旧文件仍保持 fail-safe（给出 model merge / human decision，不覆盖用户内容）。`scripts/check-init-surface.sh` 新增 drift 门，阻止“fresh init 会复制、surface 却不跟踪”的漂移。
+
+## [0.11.0] - 2026-07-15
+
+### 新增
+
+- 受治理 DAG 的 repair 环节改为显式声明：`shell.repairArtifactGate` 新增 `repairNodeId`，新生成的 supervised DAG 会直接写明由哪个 Pi 修复节点承接 supervisor 的修订请求；旧 DAG 未声明时，只有在能唯一、安全地推导出下游 Pi 修复节点时才继续兼容，缺失、歧义或修复节点不满足受治理写入契约都会在执行前明确报错。
+- 新生成的 DagSpec 升级为 `version: 3`，并携带必需的 `runtimeContract`（`agentRuntime` / `repairWriterProtocol` / 可选最低 controller 版本）。旧 controller 会因不认识 v3 而在解析阶段拒绝，新 controller 则在 `dag validate`、执行和 resume 前检查 capability 与最低版本，避免版本漂移运行到中途才失败；legacy v1/v2 DAG 继续可读。
+- 每个新的 DAG run 必须把实际执行的 controller identity（package version、binary SHA-256、portable fingerprint）冻结为 run-owned 事实并记录内容哈希；identity 无法解析时不创建 run。`dag report` 会展示 identity 与 runtime-contract compatibility，resume 时重新校验；身份漂移、artifact 篡改或 legacy-unpinned run 都会拒绝继续。
+- Observe R5：控制台前端拆为原生 ES modules（router/api/format/state/views 等），`app.js` 作轻量入口并 re-export 可测 API；统一 loading/empty/degraded/error 状态 helper；资源池支持可分享的 hash 筛选（`status`/`q`）；不引入框架或构建器，R1–R4 路由/API/行为保持。
+- Observe R4：Batch/Pool 有界事件历史 `GET /api/batches/:batchRunId/events` 与 `GET /api/events`（默认 limit 50、硬顶 200，opaque `cursor`/`nextCursor`，与 SSE/run 整数 `after` 分离）；服务端尾部有界 JSONL 扫描；snapshot 事件归约容量硬顶并暴露 `projectionWarnings`；Pool 投影失败 fault-first，避免健康零值 KPI。
+- Observe R3：`#/feature/:featureId` 决策详情（状态、AC 覆盖、blocking、risk、follow-ups、evidence、projectionWarnings）；总览 Feature 可下钻；Feature/Task/Batch/Run/DAG 统一对象关系条，仅 snapshot 可证对象出链；建议命令仅可复制，与已执行事实分区。
+- Observe R2：Batch 详情展示完整 summary（含 additive `recordErrors?`/`runErrors?`）、派生总耗时、Task 诊断列（失败分类、follow-up、harnessTaskId、起止）与页内安全 artifact preview；Worker Run 收敛为「主事实 / 执行过程 / 诊断证据」三层，Task/Batch/DAG 深链仅在 canonical 字段且 snapshot 命中时生成。`TaskSummary.batchRunId?` 对外保留。
+- Observe R1：顶栏「资源池」与 `#/pool` 盘点当前 Worker Task（状态分布、最新 run、更新时间、失败分类）；`#/task/:taskId` 下钻当前事实、真实关联 batch/run/DAG、失败证据与有界 run history（`GET /api/tasks/:taskId/runs`，limit/cursor，`retryOfWorkerRunId`）。`TaskSummary` additive `updatedAt?`；snapshot additive `taskPool.present` 区分未使用与空池。
+- 新增版本更新提醒。发现新版本时可以直接确认升级；忽略某个版本后不会重复提醒，后续新版本仍会正常提示。可用 `LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 关闭检查。
+- 新增 `loop-agent plan create`、`plan complete` 和 `plan check`，统一维护执行计划及其索引，并在生成 DAG 前发现遗漏或不一致。
+- 目标项目可以选择复用本地 SDD skills，为需求、设计、实现和评审节点补充方法指引；未安装时保持原有流程。
+- 新增 `docs/architecture/` 全景、DAG 执行、Worker/Feature、运行态事实与演进五篇主题文档及目录索引，并在 npm package（不投影到 init）内可达。
+- Worker 和 DAG 运行会固定本次使用的 loop-agent 版本与 skill 配置，避免执行过程中因环境变化产生不一致结果。
+- 新增 `npm run self-host:canary -- --deterministic`，可在隔离环境中检查候选发布包是否能够接管常用 CLI、初始化和 DAG 流程。
+- 新增可选的 `agent-worker` skill，为 Feature、Task、交付和失败恢复提供统一的操作指引。
+- 文档站新增功能导览、架构导读与当前规划入口，并把文档收敛检查固化到 `skills/loop-agent`，减少站上文档与仓库治理文档漂移。
+- 前端 DAG 的 repo-local skills 补齐节点输入、输出、证据和失败规则；前端规范会优先查知识库，失败时回退到当前项目 `openSpec/`。
+- 目标项目旧布局迁移：`init check-update`（只读）报告旧根 `docs/` / `skills/` 可安全迁移的 loop-agent owned 文件、空目录和 `harness.json` 中已废弃的模型字段；`init update --apply-safe` 迁移确认未修改的文件、清理空目录并清理废弃字段，本地修改过、来源不明或目标冲突的文件只进入人工决策，不会被覆盖或删除。
+
+### 变更
+
+- `observe serve` 提高对外访问稳定性：HTTP keep-alive 默认约 65s（避免 Node 5s 默认导致连接池复用失败），SSE 增加 keepalive comment 与 `X-Accel-Buffering: no`；新增 `--debug` 在 stderr 打印请求来源/方法/路径/状态/耗时。
+- `observe serve` 允许显式绑定非 loopback 地址（如 `--host 0.0.0.0`）以便局域网访问；默认仍是 `127.0.0.1`，非本机绑定时会在 stderr 提示无鉴权风险。
+- 根 README 在「核心概念」后增加极简「仓库地图」，方便一眼区分 `src/`、`skills/`、`.harness/`、`docs/` 等职责；细节仍以 `AGENTS.md` 与 `docs/README.md` 为准。
+- 文档治理收敛：站上「当前规划」与 active plan 同步（无进行中计划时明确写出）；`docs/README` 只索引核心契约与产物目录入口，progress/report 全量列表下沉到子目录 README；Dynamic Workflow 路线图迁入 `docs/design/`；补齐 design 漏索引与 DAG recovery playbook 入口。
+- 活文档校准：Dynamic Workflow 路线图页首标明已落地 vs 设计输入（Pi-only）；六个月规划第 1–2 月改为 archive/reports 指针；`repository-analysis` 冻结为基线快照，新增 `docs/reports/current-capability-summary.md`；落地 ADR 0001–0003（Pi-only、Task Pool 根、双树/docs-converge）。
+- 统一 Feature Packet 的推荐目录和中文说明，相关检查同时兼容现有产品线目录。
+- 目标项目初始化布局收敛：默认把 loop-agent 治理资料生成到 `ai_workspace/loop-agent/`，不再在目标项目根生成 `docs/`；`--profile full` 只把 repo-local skills 写到 `.agents/skills/`，不再生成根 `skills/`。
+- `new-task` 不再预种 L1 空报告模板（`分析报告.md` / `实现计划.md` / `复盘报告.md`）；任务 `artifacts/` 默认只保留 `修改记录.md` 与 `验证结果.md`，由 `promote-run` 从 completed run 回填。
+- 运行期间修改 skill 不会影响当前任务，新配置会从下一次运行开始生效。
+- Observe 自动刷新时会保留依赖图、检查器和日志的阅读位置，查看长时间任务时不再被频繁打断。
+
+### 修复
+
+- 修复 supervised convergence DAG 在 `process-gate-shell` 报「repair artifact gate cannot find downstream repair task」的问题：修复环节不再按固定节点名（历史上的 `repair-cursor` / `repair-pi`）猜测，而是根据 gate 声明的 `repairNodeId` 或唯一安全的下游 Pi 写入节点解析，合法的 `request-revision` 修订请求能正常走完 repair、hard verify 与 review。
+- Observe UI R5：可变 UI 状态改为 `uiState` plain object，修复 Chrome 中 ES module namespace 赋值导致的路由崩溃；`app.js` 收为约 136 行 bootstrap/route/listeners/re-export，KPI、DAG helpers、run processing 与 shell chrome 迁入职责模块，移除 nullable `registerShell/getShell` locator；Pool grouped filters、四态、DAG inspector ARIA/方向键同步收敛，并通过 focused tests、构建治理与 fresh dist Chrome 验证。
+- 前端 DAG 从 `需求.md` / `执行约束.md` 读取验证命令时不再交给 shell 解释执行；命令会先解析为受限参数列表并拒绝 shell 特殊语法，避免任务文本触发额外命令。
+- 改进 Windows 下 Git Bash、npm 和集成测试的运行方式，减少环境识别错误与资源竞争导致的误失败。
 
-- 新增只读的 `agent-worker feature review`。用户无需翻查原始日志，即可查看 Feature 当前状态、主要阻塞、required AC 覆盖、证据位置和下一条建议命令；`--json` 可供脚本稳定消费。
-- 新增 `agent-worker feature run`。它会先校验 Feature 和目标仓库，再复用现有 Worker pipeline 推进一个 Ready Task，随后刷新晨报、Observe snapshot 和 Feature review；`--dry-run` 可在零写入下预览步骤与产物。
-- 新增 ProductBug Follow-up 人工接续流程。`agent-worker task draft-followup` 生成可审查、可去重的修复草稿；`agent-worker feature approve-followup --dry-run` 可先检查变更计划，批准后再新增 FIX Task、重连下游依赖并进入 Ready，同时保留原失败证据。
-- Follow-up 现已覆盖全部失败分类：可执行类生成严格 TaskSpec，Spec/Risk/Human 类生成行动卡，EnvFailure 只有连续两次失败后才建议环境检查任务；审批事务增加多阶段回滚验证，避免 Packet、Ready state、approval 或 index 半写。
-- `agent-worker feature run --git-mode checkpoint` 新增显式授权的本地 Feature 分支事务。成功任务形成带 Feature/Task/AC/run 信息的 checkpoint commit；失败任务保存 patch 与 untracked 证据后恢复 clean。默认仍不 commit，也不会 push、stash、merge 或创建远程 PR。
-- 新增 `agent-worker feature verify-final`、`feature delivery` 与 Feature Closeout。用户可在 clean Delivery HEAD 上生成 canonical QA/最终验证证据，再从 checkpoint、成功 run 和 required AC 形成带 hash 的 Delivery Package、Acceptance Coverage 与 PR 草稿；Closeout 默认预览，只有显式 `--apply --owner` 才原子写回并保留幂等、stale facts 与回滚保护。
-- Morning report 与 Observe 首页新增共享的 Feature Decision Summary，优先显示状态、下一步、原因、证据和 required AC。新增 `agent-worker report metrics --month YYYY-MM`，同时输出带分母、样本量、时间窗口和缺失数据说明的 JSON/Markdown。
-- Observe 总览新增仓库横幅，显示仓库名与绝对路径；KPI 按主要执行链路排列为“Worker 执行”在前、“DAG 运行”在后，DAG 组明确展示活跃运行、执行中/等待节点、暂停和需处理运行，“活跃 Task”更名为“活跃 Worker Task”，每张卡片新增可键盘聚焦的问号帮助，解释数据来源与统计口径。
-- Observe 总览的 Feature 决策仅在存在“运行中”或“需处理”的 Feature 时显示；只有可执行、待验收、已交付或已关闭记录时不再占用总览空间。
+## [0.10.0] - 2026-07-12
+
+### 破坏性变更
+
+- DAG、Loop、Delegate 和 Worker 统一使用 Pi，不再支持 Cursor executor 及相关旧配置。
+- Cursor 仍可通过 `loop-agent cursor-prompt` 手动调用，但不再参与自动执行和受治理写入。
+- Delegate 默认只创建 worktree；需要自动生成并执行 DAG 时必须显式使用 `--auto-run`。
+
+### 迁移提示
+
+1. 删除 harness 和 task 中的 Cursor executor 配置，只保留 `executors.pi`。
+2. 把 `loopAutoWritePolicy` 改为 `loopAutoExecutionPolicy`（`off` | `approval-required` | `enabled`）。
+3. 重新运行 `dag run-task` 并使用 `dag validate` 校验 DAG。
+4. 需要 Cursor 人工辅助时使用 `loop-agent cursor-prompt`，完成后仍需运行项目验证命令。
+
+### 新增
+
+- `agent-worker feature review` 可汇总 Feature 状态、阻塞、验收覆盖、证据和下一步；`--json` 可供脚本读取。
+- `agent-worker feature run` 可检查并推进一个就绪任务，`--dry-run` 可在不写入的情况下预览执行结果。
+- 新增失败接续流程，可根据失败类型生成修复任务或人工行动建议，并在批准前保留原始失败证据。
+- `feature run --git-mode checkpoint` 可为成功任务创建本地检查点，并在任务失败后恢复干净工作区；不会自动 push、merge 或创建远程 PR。
+- 新增 `feature verify-final`、`feature delivery` 和 `feature closeout`，覆盖最终验证、交付材料和显式确认后的收尾操作。
+- 晨报、Observe 和 `report metrics` 会集中展示 Feature 状态、下一步、验收覆盖和统计口径。
+- 初始化演化检查可以复用仍然有效的历史审查结果，减少低影响后续改动造成的重复评审。
 
 ### 修改
 
-- 根目录 `design/` 已并入 `docs/design/`，视觉参考与产品线设计笔记现在统一从治理文档目录查找，相关索引和引用已同步更新。
-- Agent DAG 的 Pi/Cursor 节点现在默认使用简体中文输出说明、分析、报告和文档；可通过 `workflowPolicy.dag.outputLanguage: "en"` 切换英文，代码、命令、路径、JSON 字段和固定协议 token 不会被翻译。
-- Dashboard 将“运行活性”调整为更直观的“执行器状态”，并明确区分执行器正常、心跳中断、已经退出、其他主机运行以及旧记录没有心跳等情况。
-- 修复 Dashboard 综合 DAG 状态使用中文文案后丢失徽章颜色的问题；完成、失败、暂停、中断和任务已另行完成现在恢复对应的语义颜色。
-- Dashboard 节点耗时达到 60 秒后改为按“分钟 + 秒”显示，例如 `2min 5s`，长任务更容易快速阅读。
-- Dashboard 的 DAG 节点模型列现在会显示 Pi/Cursor 节点实际路由到的模型；历史运行从 `run.json` 模型矩阵推导，新运行会直接把解析后的模型写入节点状态，Shell/Static 节点仍显示 `-`。
-- Dashboard 现在优先展示由生命周期、原始状态和运行活性共同判定的 DAG 当前状态，并单独保留原始记录；新增 `dag reconcile-run`，可在确认执行器已停止后将历史失联 DAG 显式标记为“任务已另行完成”或“已放弃”，同时保存收口前证据。
-- Observe DAG 详情页主信息区精简为单一“状态”，已结束 DAG 不再展示执行器心跳等无意义内部维度，状态一致或不允许恢复/收口时也不再显示“一致”或“否”；不一致、可恢复或可收口的警告与操作能力仍在主视图可见，原始状态、生命周期、活性、状态一致性与恢复资格折叠在“诊断信息”中保留。
-- DAG 运行现在记录本机执行器 PID、主机和持续心跳；`dag status` / `dag doctor` 可区分活跃、节点长时间无活动、心跳停滞、执行器已退出和远端状态未知，Observe 也不会再把已知孤儿或 paused 运行计为活跃 DAG。
-- 节点检查器支持拖动左边缘调整宽度，长 Markdown 表格和输出更容易查看；点击外部空白区域可平滑收起面板。
-- 执行过程改为更清晰的事件轨道：工具调用、AI 回复和 Agent 生命周期更容易区分；没有时间记录时会按采集顺序展示，连续协议事件会自动合并，减少无关噪声。
-- Observe 风险区拆为“需处理 DAG”与“Worker 风险”两个子块；DAG 按运行去重，不会因同一运行同时存在多个异常信号而重复计数，也不会让历史失败记录长期占用当前风险；Snapshot 投影失败不再静默显示为全零健康状态，而是返回安全错误摘要并在总览提示“指标暂不可用”，不含堆栈或敏感信息。
-- 修复旧版（未写 runner 心跳元数据）的运行中 DAG 被 Observe 误判为不活跃的问题：`effectiveStatus=unknown` 只表示活性证据不足，不再覆盖 `lifecycle=active` 且原始 `status` 为 `running`/`pending` 的运行事实，也不再掩盖存在 RUNNING/PENDING 节点的运行。服务端健康计数（活跃运行、执行中节点、等待节点）与前端进行中 DAG 列表现在使用一致的判定语义；`paused`、`terminal`、`stale`、`orphaned` 等明确非活跃事实仍优先于原始 `running`。
-- `npm test` 会先运行可并行的纯测试，再串行运行会启动 CLI 或子进程的集成测试。纯测试会根据机器可用并行度自动选择 1 至 4 个 Worker，低配和高配环境都能在稳定性与速度之间取得更合适的平衡。
+- `design/` 已并入 `docs/design/`，设计资料统一从治理文档目录查找。
+- Agent DAG 默认使用简体中文输出；可通过 `workflowPolicy.dag.outputLanguage: "en"` 切换为英文。
+- Observe 和 Dashboard 更集中地展示运行状态、风险、模型、耗时和下一步，并减少已经结束任务中的无关诊断信息。
+- 新增 `dag reconcile-run`，可在执行器已经停止后安全收尾历史失联的 DAG。
+- DAG 详情的节点检查器、事件记录和风险区域更易阅读，长内容和异常状态也能得到清楚提示。
+- 测试会根据机器资源安排并行和串行任务，降低资源竞争造成的不稳定。
+
+### 修复
+
+- 修复 `cursor-prompt --stream` 超时或异常后可能残留连接或进程的问题。
+- 修复部分运行中 DAG 被误判为不活跃、状态颜色丢失以及风险统计重复的问题。
+- 运行快照暂时无法生成时会明确提示指标不可用，不再显示具有误导性的全零状态。
 
 ## [0.9.0] - 2026-07-12
 
@@ -155,6 +218,8 @@
 
 ### 新增
 
+- 新增 `frontend-implementation` 任务类型与专用 Agent DAG 模板，支持前端 contract / scout / design gate / implement / static verify / behavior verify / review gate / closeout 节点链，并附带 repo-local `frontend-implementation` skill 骨架。
+- 补齐前端 DAG 的 repo-local skills：前端实现、design gate review、实现 review 和 verification closeout，并纳入 npm package / `loop-agent init --profile full` 初始化投影。
 - `loop-agent init` 支持检查和更新已初始化项目，可提示缺失文件、过期配置和需要人工确认的变更。
 - 新增 `--version`，可直接查看当前安装的 loop-agent 版本。
 - 初始化内容和 npm 包内容会进行一致性检查，减少“本仓库可用、初始化项目缺文件”的情况。
@@ -173,6 +238,8 @@
 
 ### 修复
 
+- 前端 DAG 的 static / behavior shell 验证会优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，避免被通用 adapter 验证命令覆盖。
+- 前端 DAG 节点不再默认注入通用 DAG role skills，改为只加载节点显式声明的前端 skills，避免前端 skill references 被上下文预算挤出。
 - 修复完整测试运行时，部分真实命令可能因默认超时时间过短而失败的问题。
 
 ## [0.2.0] - 2026-07-05

package/README.md

@@ -2,7 +2,7 @@
 
 `loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
 
-它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 repo-local skills、治理文档、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
+它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 `.agents/skills/`、`ai_workspace/loop-agent/` 治理资料、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
 
 ## 快速开始
 
@@ -20,6 +20,22 @@ loop-agent --version
 loop-agent --help
 ```
 
+## 自动更新提醒
+
+通过 npm 全局安装的 `loop-agent` 会在普通交互式命令成功结束后检查 `@tea-agent/loop-agent` 是否有新版本。提醒只写入 `stderr`，不会污染命令原本的 `stdout`；失败命令、CI、管道/重定向、`--help`、`--version`、JSON/Markdown 输出以及 DAG/Loop/Delegate/Pi/Cursor 等 controller-sensitive 路径都会跳过。
+
+如果你拒绝版本 A，当前系统用户下不会再提醒 A；之后发布版本 B 时会继续提醒。确认更新时，CLI 会先证明当前安装来自同一 npm global root，然后安装刚确认的精确版本，例如：
+
+```bash
+npm install -g @tea-agent/loop-agent@0.12.0
+```
+
+需要完全关闭自动检查时设置：
+
+```bash
+LOOP_AGENT_DISABLE_UPDATE_CHECK=1
+```
+
 检查当前项目的 loop-agent 配置：
 
 ```bash
@@ -38,7 +54,7 @@ loop-agent inspect
 
 然后运行 `loop-agent init instructions --repo-root .`，按指引使用 full + merge 初始化。需要选择 provider/model，或涉及凭据、成本、部署副作用时先问我；其他能安全默认的选项直接继续。
 
-初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
+初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `ai_workspace/loop-agent/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`，并汇报结果、假设和剩余风险。
 ```
@@ -51,7 +67,7 @@ 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/` 并同步镜像到 `.agents/skills/`（agent 兼容路径，如 OpenCode 自动发现），生成语言无关的治理脚本矩阵、中文根 README 入口、目标项目版治理文档、`harness.json` IDE schema 指引和 `.harness/` 骨架；已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block（`# LOOP_AGENT_INIT_START/END`），把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等个人/会话运行态事实忽略掉，同时保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`，也不会覆盖用户已有的 ignore 规则。
+`init instructions` 会输出给模型/Agent 执行完整初始化的指引包，不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 loop-agent 治理资料，生成语言无关的治理脚本矩阵、中文根 README 入口、`ai_workspace/loop-agent/` 目标项目治理资料、`.agents/skills/` repo-local skills、`harness.json` IDE schema 指引和 `.harness/` 骨架；不会在目标项目根目录生成 `skills/`，也不会把 loop-agent 生成的治理资料写到根 `docs/`。已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block（`# LOOP_AGENT_INIT_START/END`），把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等个人/会话运行态事实忽略掉，同时保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`，也不会覆盖用户已有的 ignore 规则。
 
 新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
 
@@ -62,9 +78,9 @@ 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（包括过期的 `.gitignore` managed block），不覆盖已有但无法确认来源的本地文件。
+`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。期望 init surface 会自动发现包内 `docs/templates/` 与 `skills/` 的所有文件，因此 fresh `init --profile full` 投影到目标项目的每个 template/skill 文件都会被纳入校验。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 managed block（包括过期的 `.gitignore` managed block），不覆盖已有但无法确认来源的本地文件；对在旧路径被用户修改过的遗留副本，会在对应标准路径上给出 model merge / human decision，不会静默用包内容覆盖。
 
-当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `docs/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
+当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
 
 初始化生成的 `scripts/ci-tests.sh` 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 `package.json`、`Makefile`、`go.mod`、`Cargo.toml`、Python 测试配置、Maven、Gradle、.NET 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
 
@@ -79,8 +95,20 @@ loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --st
 loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 ```
 
+当前 `dag run-task` 也支持按 `task.json.taskKind` 选择专用模板；`frontend-implementation` 会生成前端契约、design gate、静态验证、行为验证和 review gate 节点链，`backend-test` 会生成从需求分析、功能用例、pytest 自动化到测试复盘的专用节点链。
+
 `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
 
+非微小工作需要 exec-plan 时，使用确定性生命周期命令维护计划与索引；`new-task` 不会自动创建计划：
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+loop-agent plan check
+loop-agent plan complete <plan-id> --summary "<summary>"
+```
+
+`plan create` 优先复用目标项目模板并回退到发布包内置模板，create/complete 失败时会回滚多文件修改。`dag run-task` 在生成 DAG 草稿前运行同源索引检查，避免遗漏登记直到末端 verify 才暴露。
+
 一次性只读评审或有边界写入：
 
 ```bash
@@ -103,6 +131,19 @@ agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id
 bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
 ```
 
+写入型 Worker 入口会在目标仓库写入前解析并冻结实际启动的 `loop-agent` controller identity。自举或其他需要精确版本约束的批次，可以额外传入：
+
+```bash
+agent-worker feature run \
+  --feature-dir <feature-dir> \
+  --repo <target-repo> \
+  --loop-agent-bin <published-loop-agent-entry> \
+  --expected-controller-version <version> \
+  --expected-controller-fingerprint <sha256:value>
+```
+
+identity 不只包含 semver，还包含绝对 launch spec、入口 SHA-256，以及覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable package fingerprint。校验失败时会在 materialize、Task Pool `Running` 或其他目标仓库写入前停止，并保留实际 identity 供诊断。
+
 `feature review` 是只读的 Feature 级入口。它从 Feature Packet 和现有 Task Pool 事实派生状态、required AC 覆盖、阻塞、证据和唯一主行动；默认输出简洁人类摘要，`--json` 输出稳定的 schemaVersion 1 读模型。它不会写入 Feature Packet 或 Task Pool。
 
 `feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec，执行独立、不会 promote/closeout 或移动 HEAD 的最终验证，并原子投影 canonical QA aggregate 与 HEAD-bound final-verification evidence。`feature delivery` 复用 checkpoint transaction，校验 branch/HEAD/clean、commit trailers、changed files、成功 run、QA、最终验证和 required AC 后，在 `.harness/task-pool/` 原子生成 Delivery manifest、Acceptance Coverage 与 `PR.md`；`--dry-run` 零写入。`feature closeout` 默认只预览 gates；显式 `--apply --owner <owner>` 才会在前后校验与整体回滚保护下写入 Feature Closeout，重复相同 facts 会幂等复用。
@@ -124,19 +165,40 @@ nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 mo
 - **Agent DAG**：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
 - **`.harness/`**：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
 - **`harness.json`**：描述项目名、治理根目录、模型路由、executor 和验证脚本；`docs/templates/harness.schema.json` 为 IDE 提供补全和字段说明，运行时仍由 Zod schema 校验。
-- **repo-local skills**：目标项目本地的 `skills/`（loop-agent 主路径）优先于发布包内置 skills，便于项目定制 agent 行为；`init --profile full` 还会把同一份 skills 镜像到 `.agents/skills/`，让外部 agent（如 OpenCode）也能自动发现。DAG skill 解析顺序为：用户配置目录 → `skills/` → `.agents/skills/` → 发布包内置。
+- **repo-local skills**：目标项目本地 skills 统一放在 `.agents/skills/`，便于项目定制 agent 行为并让外部 agent 自动发现。DAG skill 解析顺序为：用户配置目录 → `.agents/skills/` → 发布包内置 `skills/`。
+- **可选 SDD skill 嵌入**：如果目标项目在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，`dag run-task` 会把它们作为知识与方法补充追加到对应的 Contract、Plan、Implement/Repair、Verify、Review 节点。loop-agent 仍控制 DAG、状态、写入边界、验证和收口；不会自动运行 SDD 初始化/扫描 skill，也不会推进 `ai_workspace` 状态或归档。没有这些 repo-local skills 时，生成结果保持原有默认流程。
+- **run-owned skill snapshot**：新 DAG run 会在任何节点执行前，把本次实际注入 prompt 的 resolved skill profiles 冻结到 run 自己的 `.runtime/skill-snapshot.json`。后续节点、dynamic child、approve/resume 都使用同一份 hash-anchored snapshot；run 内修改 skill 只会从下一次 run 生效。
+- **controller identity**：`agent-worker` 把一次 Feature/batch 实际使用的发布包、入口、启动参数和 package 内容 fingerprint 固定下来，并把 identity 传播到 Worker、Task Pool、batch/Feature 与最终验证证据。
+- **只读 Pi 节点安全重试**：仅 planner/scout/reviewer/verifier/closeout 这类没有仓库写入能力的 Pi 节点，遇到模型连接中断、provider 限流、临时不可用或 timeout 时，可在同一 run 内有界重试；生成模板会自动声明默认 `retryPolicy`（总尝试 3 次、最多可配置 5 次、指数退避、单次等待上限 30s）。每次 attempt 保留独立证据，耗时与 Token 用量按尝试聚合，后一次成功不覆盖前一次失败证据。`quota`/`auth`/`invalid-output`/`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点不重试。
+- **`agent-worker` operator skill**：`skills/agent-worker/` 只负责 Feature Packet、TaskSpec、Task Pool、自举 release train 和失败恢复的外层路由；单个 DAG 实现、DAG kernel 修复和节点执行仍由 `loop-agent` 负责，该 skill 不进入默认 DAG role skills。
 - **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
 - **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。
 
 这些治理原则的设计思想吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践：人类掌舵，智能体执行；仓库作为记录系统；任务小步推进；用结构化 handoff 与可复现验证跨 session 保持连续性。背景资料收录在 `website/docs/practices/`。
 
+## 仓库地图
+
+本仓库按职责分区；更细的开工协议与会话规则见 `AGENTS.md`，治理索引见 `docs/README.md`。
+
+| 路径 | 职责 |
+|---|---|
+| `bin/`、`src/` | CLI 入口与运行时代码 |
+| `skills/` | repo-local skill 指令与 references |
+| `.harness/` | task、DAG run、cache、live state 等运行态事实 |
+| `docs/` | 长期治理文档、计划、报告与模板 |
+| `website/` | 面向使用者的文档站 |
+| `scripts/`、`test/` | 验证脚本与测试套件 |
+| `examples/` | 可复制 DAG 示例（默认不投影到目标项目） |
+| `features/`、`dogfood/` | 样板 Feature Packet 与 dogfood 样本（本仓库维护用） |
+| `harness.json`、`AGENTS.md`、`CONTEXT.md` | 项目配置、agent 开工地图与术语表 |
+
 ## 能力概览
 
 - 生成、校验、执行和汇总 Agent DAG。
 - 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
 - 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
-- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入。
-- 保留 Cursor executor 作为显式启用的可选后端。
+- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入（唯一受治理 Agent writer）。
+- 保留 `cursor-prompt` 作为显式、手工触发的 one-shot sidecar（不是受治理 DAG/Loop writer）。
 - 通过 shell executor 运行确定性的验证命令。
 - 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
 
@@ -152,7 +214,7 @@ loop-agent examples copy example-dag.json --repo-root <target-repo>
 
 ## 迭代本仓库
 
-如果要用 loop-agent 迭代 loop-agent 本仓库，控制器必须来自已发布的 npm 安装包。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器；首次安装或有意升级可用 `@latest`，但一次自举任务启动后不要在任务中途升级控制器。
+如果要用 loop-agent 迭代 loop-agent 本仓库，发布版本 N 必须作为整个维护批次的固定 controller，候选版本 N+1 只能在隔离安装槽中接受接棒验证。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为 controller；首次安装或有意升级可用 `@latest`，但一次自举任务启动后不要中途升级或重新通过 PATH 解析入口。
 
 ```bash
 npm install -g @tea-agent/loop-agent@latest
@@ -161,7 +223,17 @@ loop-agent doctor
 loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 ```
 
-`@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举任务应记录 `npm list -g` 显示的实际版本号。
+`@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举证据应记录 controller version、portable package fingerprint、候选 commit/tarball hash 和失败 run；semver 相同并不代表 package 内容相同。
+
+源码仓库提供 repo-maintainer deterministic takeover canary。它打包候选、安装到临时隔离 slot，由维护脚本独立计算 canonical package fingerprint 并与候选实现交叉核对，再通过候选包内两个绝对入口执行 full init、doctor、inspect、docs audit、目标项目治理检查、Feature validation/dry-run 和一个只含 static/shell executor 的小型 DAG；所有子进程都有硬超时，PATH trap 证明没有回退全局 `loop-agent` / `agent-worker` 命令，run evidence 则证明没有观察到 Pi/model executor：
+
+```bash
+npm run self-host:canary -- --deterministic --output <evidence.json>
+# 或验证已经构建好的候选 tarball
+npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
+```
+
+该脚本属于源码仓库维护入口，不进入发布包的 `files` surface；`--live` 当前明确拒绝执行。deterministic canary 证明候选包和 static/shell runtime 能接棒，但不会调度 Pi executor，也不承担 Pi skill source 解析证明；run-owned skill snapshot 的候选包解析由 snapshot 定向测试和真实 DAG 证据单独证明。
 
 ## 文档导航
 
@@ -205,11 +277,11 @@ Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash
 
 ## 发布包内容
 
-发布包包含静态运行和指导资料：`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`。
+发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、`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 能力。
+DAG skill 指令优先从用户配置目录和目标项目 `.agents/skills/` 解析；目标项目未提供本地 skill 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或根 `skills/` 目录才可获得默认 DAG 能力。
 
 ## 发布前检查
 

package/dist/application/dag/args.js

@@ -16,12 +16,11 @@ function parseMaxConcurrent(value) {
 }
 export function parseDagRunTaskArgs(args, defaultCwd) {
     if (args.length === 0) {
-        throw new Error("usage: dag run-task <task-id> [--output <path>] [--profile auto|minimal|standard|reviewed|supervised] [--strict-models] [--no-cursor] [--execute] [--init-only] [--dry-run] [--cwd <dir>] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]]");
+        throw new Error("usage: dag run-task <task-id> [--output <path>] [--profile auto|minimal|standard|reviewed|supervised] [--strict-models] [--execute] [--init-only] [--dry-run] [--cwd <dir>] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]]");
     }
     let taskId;
     let outputPath;
     let strictModels = false;
-    let noCursor = false;
     let execute = false;
     let initOnly = false;
     let dryRun = false;
@@ -50,10 +49,6 @@ export function parseDagRunTaskArgs(args, defaultCwd) {
             strictModels = true;
             continue;
         }
-        if (arg === "--no-cursor") {
-            noCursor = true;
-            continue;
-        }
         if (arg === "--execute") {
             execute = true;
             continue;
@@ -135,7 +130,6 @@ export function parseDagRunTaskArgs(args, defaultCwd) {
         taskId,
         outputPath: outputPath ? path.resolve(outputPath) : undefined,
         strictModels,
-        noCursor,
         execute,
         initOnly,
         dryRun,
@@ -257,7 +251,6 @@ export function parseRunDagArgs(args, defaultCwd) {
     let dryRun = false;
     let maxConcurrent;
     let runId;
-    let noCursor = false;
     let canvasPath;
     let canvasName;
     let canvasesDir;
@@ -288,9 +281,6 @@ export function parseRunDagArgs(args, defaultCwd) {
         else if (arg === "--run-id") {
             runId = args[++i];
         }
-        else if (arg === "--no-cursor") {
-            noCursor = true;
-        }
         else if (arg === "--canvas-path") {
             canvasPath = args[++i];
         }
@@ -335,7 +325,6 @@ export function parseRunDagArgs(args, defaultCwd) {
         dryRun,
         maxConcurrent,
         runId,
-        noCursor,
         canvasPath,
         canvasName,
         canvasesDir,

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

@@ -4,7 +4,9 @@ import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { parseDagSpec } from "../../workflows/dag/types.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
+import { assertExecPlanIndexConsistent } from "../../governance/exec-plans.js";
 import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
+import { loadTaskConfig } from "../../task/runtime.js";
 import { validateDagUseCase } from "./validate-dag.js";
 import { runDagUseCase } from "./run-dag.js";
 const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
@@ -14,7 +16,7 @@ function buildValidateInput(repoRoot, dagPath, parsed) {
         dagPath,
         strictModelMatrix: parsed.strictModels,
         strictGovernance: false,
-        forbidExecutors: parsed.noCursor ? ["cursor"] : [],
+        forbidExecutors: [],
     };
 }
 function shouldRunExecution(parsed) {
@@ -196,6 +198,13 @@ async function resolveProfileRouting(repoRoot, parsed, candidateProfile) {
 }
 export async function generateTaskDagUseCase(input) {
     const { repoRoot, ...parsed } = input;
+    // Deterministic exec-plan preflight: fail closed on real index drift
+    // before any expensive DAG generation or execution. Empty/consistent
+    // repos stay compatible so the default DAG flow is unblocked.
+    await assertExecPlanIndexConsistent(repoRoot);
+    const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
+    const isFrontendImplementationTask = taskConfig.taskKind === "frontend-implementation";
+    const isBackendTestTask = taskConfig.taskKind === "backend-test";
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",
@@ -208,6 +217,34 @@ export async function generateTaskDagUseCase(input) {
         codeChange: [],
         reasons: ["dag run-task validate did not report governanceProfile"],
     });
+    if (isFrontendImplementationTask) {
+        profileRouting.selectedTemplate = "frontend-implementation";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "frontend-implementation" selects the dedicated frontend DAG template',
+        ];
+        if (parsed.profile === "auto") {
+            profileRouting.selectedByProfile =
+                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+        }
+        else if (parsed.profileExplicit) {
+            profileRouting.selectedByProfile = parsed.profile;
+        }
+    }
+    if (isBackendTestTask) {
+        profileRouting.selectedTemplate = "backend-test-dag";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "backend-test" selects the dedicated backend test DAG template',
+        ];
+        if (parsed.profile === "auto") {
+            profileRouting.selectedByProfile =
+                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+        }
+        else if (parsed.profileExplicit) {
+            profileRouting.selectedByProfile = parsed.profile;
+        }
+    }
     const initResult = profileRouting.selectedTemplate === "standard-dag"
         ? candidateResult
         : await initHybridDagFromTask(repoRoot, parsed.taskId, {
@@ -258,7 +295,6 @@ export async function generateTaskDagUseCase(input) {
         dryRun: parsed.dryRun,
         maxConcurrent: parsed.maxConcurrent,
         runId: parsed.runId,
-        noCursor: parsed.noCursor,
         canvasPath: parsed.canvasPath,
         canvasName: parsed.canvasName,
         canvasesDir: parsed.canvasesDir,

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

@@ -1,30 +1,11 @@
-import { readFile } from "node:fs/promises";
 import { createDagEventObserver } from "../../workflows/dag/event-observer.js";
 import { composeDagRunObservers } from "../../workflows/dag/observer-compose.js";
 import { createDagCanvasObserver, resolveCanvasPath, } from "../../workflows/dag/canvas-observer.js";
 import { loadDagSpecFromFile, runDag } from "../../workflows/dag/runner.js";
-import { assertValidDagSpec, collectForbiddenExecutorIssues, } from "../../workflows/dag/validate.js";
-async function loadRawTaskExecutorMap(dagPath) {
-    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
-    const map = new Map();
-    for (const task of raw.tasks ?? []) {
-        if (typeof task.id === "string")
-            map.set(task.id, task.executor);
-    }
-    return map;
-}
-function assertNoCursorTasks(spec, rawTaskExecutors) {
-    const issues = collectForbiddenExecutorIssues(spec, ["cursor"]);
-    if (issues.length === 0)
-        return;
-    const details = issues
-        .map((issue) => {
-        const implicitDefault = rawTaskExecutors.get(issue.taskId) === undefined;
-        return `task=${issue.taskId}${implicitDefault ? " (implicit cursor default)" : ""}`;
-    })
-        .join("; ");
-    throw new Error(`--no-cursor forbids cursor executor tasks: ${details}`);
-}
+import { assertValidDagSpec } from "../../workflows/dag/validate.js";
+import { assertRuntimeContractCompatible } from "../../workflows/dag/runtime-contract.js";
+import { DAG_CONTROLLER_CAPABILITIES } from "../../workflows/dag/runtime-contract.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 function getCanvasFlushErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -50,11 +31,14 @@ function buildRunDagNextSteps(runId) {
 }
 export async function runDagUseCase(input) {
     const spec = await loadDagSpecFromFile(input.dagPath);
-    if (input.noCursor) {
-        const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
-        assertNoCursorTasks(spec, rawTaskExecutors);
-    }
     assertValidDagSpec(spec);
+    const runningIdentity = resolveRunningControllerIdentity();
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        ...(runningIdentity
+            ? { controllerVersion: runningIdentity.packageVersion }
+            : {}),
+    });
     const resolvedCanvasPath = resolveCanvasPath({
         canvasPath: input.canvasPath,
         canvasName: input.canvasName,