@tea-agent/loop-agent 0.11.0 → 0.13.0-alpha.0

package/CHANGELOG.md

@@ -2,10 +2,79 @@
 
 这里记录每个版本对使用者有影响的变化。命令名和配置字段保持原样，其余内容尽量用日常语言说明。
 
-## [Unreleased]
+## [Unreleased]
+
+## [0.13.0] - Unreleased
+
+### 新增
+
+- 前端 DAG 新增设计修订闭环：首轮 design review 输出 `request-revision` 时通过只读 `frontend-plan-revision-pi` 修订计划后经 `frontend-final-design-review-pi` 和 `frontend-final-design-gate-shell` 最终门禁，不再直接终止。只有最终 `VERDICT: pass` 才授权写入。
+- Observe 节点检查器新增「规范证据」页签，展示 skill 注入状态、已读取规范文件（基于 session event 中成功完成的 read 工具调用）、检索操作（grep/find/ls）以及知识库查询；证据不足时提供明确提示。
+- 规范证据接口强制要求通过 `toolCallId` 配对 `tool_execution_start` 与 `tool_execution_end` 事件；仅有 start 而无匹配成功 end、end 报错（`isError: true`）或缺失 complete 事件的 read 一律不计入已读取。
+
+### 变更
+
+- 前端 design gate shell 失败路由改为 `ContractMismatch` / `frontend-plan-revision-and-rerun`，不再路由为 `ProductBug` / `dev-fix`。
+- 前端实现、design review 和 review skill 要求显式执行并记录规范检索与读取，以便后续新 run 在 Observe 中生成可观察证据。
+
+### 破坏性变更
+
+- Task Pool 任务身份升级为 feature-scoped 复合键 `{ featureId, taskId }`（`TaskPoolTaskRef`，ADR 0004）。新 state 使用 `schemaVersion: 2`，canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`；裸 `taskId` 不再是仓库全局唯一键。
+- `agent-worker task retry` 的 canonical 调用必须携带 `--feature-id`。跨 Feature 同名 Task 时省略 `--feature-id` 会 fail-closed，不会静默猜 Feature。
+- 扁平 legacy `states/<taskId>.json` 在写入 / Ready 路径 fail-closed，不会被静默解释为某个 Feature 的状态。
+
+### 迁移提示
+
+1. 运行 `agent-worker pool doctor --repo <repo> --json` 盘点 v2 / legacy inventory。
+2. 需要迁移时先 `agent-worker pool migrate-state --repo <repo>`（dry-run），确认映射后再 `--apply --owner <owner> --reason <reason>`。
+3. 更新脚本与文档中的 retry 示例为 `task retry <task-id> --feature-id <feature-id> ...`。
+4. Observe / 书签改用 `#/feature/:featureId/task/:taskId`；legacy `#/task/:taskId` 仅在 taskId 全库唯一时兼容。
+5. `runs.jsonl` / `events.jsonl` 不会被 migrate 重写；历史 `workerRunId` 仍可追溯。
+
+### 新增
+
+- `agent-worker pool doctor`：只读 Task Pool inventory 与迁移证据（exit 0 也可带 findings）。
+- `agent-worker pool migrate-state`：legacy → v2 显式迁移；默认 dry-run，apply 需 owner/reason，失败全回滚并保留审计 artifact。
+- `agent-worker batch plan-ready`：零写入预览 TaskSpec priority 驱动的 selected、deferred 与 blocked 计划。
+
+### 变更
+
+- Runner Ready Queue、Feature review/run、Follow-up、Delivery / Closeout、morning report / metrics 与 Observe read-model 均按 Feature 作用域消费 state，同名 Task 跨 Feature 不串线。
+- Observe canonical API：`GET /api/features/:featureId/tasks/:taskId[/runs]`；legacy bare task route 在歧义时返回 409 + `candidates`。
+- Feature dry-run / review / next-action、morning report、GlobalSnapshot、Observe 消费同一 Ready Planner projection；前端与投影层不得独立重选或重排 ready tasks。
+
+### 修复
+
+- Windows 下发布/测试更稳：路径断言对齐 `realpathSync`（避免短路径与长路径比较失败）、Git Bash 解析与生产 `shell-executor` 一致（支持 `LOOP_AGENT_BASH` / `GIT_BASH` 与多候选路径），并放宽 self-host canary、Ring 1 materialize 与 Git-backed Delivery 集成测试在重负载下的超时上限。
+- 前端实现 skill 会完整注入增长后的必需节点契约，不再因单引用预算仍停留在旧上限而截断设计修订闭环规则。
+
+## [0.12.0] - 2026-07-16
+
+### 新增
+
+- 只读 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 与既有执行恢复机制。
+- 测试知识回写专用 DAG：`taskKind: "knowledge-sync"`。生成 collect→draft→validate→apply→pointer；**必须绑定 `featureId`**（`task.json.featureId` 或 hardConstraints / 需求中的 `F-…`），writeSet 收窄到 `features/<featureId>/…`。
+- 业务知识图谱开荒 DAG：`taskKind: "knowledge-graph-bootstrap"`（preflight→inventory→propose→validate→review→gate→promote→materialize）；AI 只写 `knowledge/bootstrap/staging/**`。
+- 图谱辅助脚本与 CLI：`loop-agent knowledge query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare`（薄封装 `scripts/kb-*`）；`knowledge curate` 仍只负责 repair guidance 提案。
+- B1 骨架、Phase A 查询（by_id / by_feature / search）、merge-new-only 晋升、增量 scope 准备与 materialize 索引；设计文档见 `docs/design/knowledge-*.md` 与 active plan `docs/exec-plans/active/2026-07-14-knowledge-sync-and-graph.md`。
+
+### 修复
+
+- `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，为需求、设计、实现和评审节点补充方法指引；未安装时保持原有流程。
@@ -19,6 +88,8 @@
 
 ### 变更
 
+- `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）。
@@ -30,6 +101,8 @@
 
 ### 修复
 
+- 修复 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 和集成测试的运行方式，减少环境识别错误与资源竞争导致的误失败。
 

package/README.md

@@ -27,7 +27,7 @@ loop-agent --help
 如果你拒绝版本 A，当前系统用户下不会再提醒 A；之后发布版本 B 时会继续提醒。确认更新时，CLI 会先证明当前安装来自同一 npm global root，然后安装刚确认的精确版本，例如：
 
 ```bash
-npm install -g @tea-agent/loop-agent@0.12.0
+npm install -g @tea-agent/loop-agent@0.13.0
 ```
 
 需要完全关闭自动检查时设置：
@@ -78,7 +78,7 @@ 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 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
 
@@ -95,7 +95,26 @@ 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 节点链。
+当前 `dag run-task` 也支持按 `task.json.taskKind` 选择专用模板；`frontend-implementation` 会生成前端契约、design gate、静态验证、行为验证和 review gate 节点链，`backend-test` 会生成从需求分析、功能用例、pytest 自动化到测试复盘的专用节点链。
+
+测试结论写回与业务知识图谱（结构化 Git，非 RAG）：
+
+```bash
+# 最终验证后：同步结论/用例/缺陷到 features/<F>/testing/**（须 featureId）
+# task.json: { "taskKind": "knowledge-sync", "featureId": "F-2026-004" }
+loop-agent dag run-task <task-id> --strict-models
+
+# 图谱开荒 / 增量（AI 只写 staging，晋升默认不覆盖已有正式文件）
+# task.json: { "taskKind": "knowledge-graph-bootstrap" }
+loop-agent knowledge graph-init --product-name my-app
+loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service order
+loop-agent dag run-task <task-id> --strict-models
+loop-agent knowledge graph-promote
+loop-agent knowledge graph-materialize
+loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
+```
+
+`knowledge curate` 仍只用于 repair/learned guidance 提案，与图谱查询不是同一能力。细节见 `docs/feature-workflow.md` 与 `docs/design/knowledge-graph-ai-bootstrap.md`。
 
 `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
 
@@ -158,7 +177,16 @@ Morning report 和 Observe snapshot/UI 复用同一 Feature reducer，优先展
 
 nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。
 
-自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：旧路径不读取、不迁移、不合并、不重映射；升级意味着本地 Worker Task Pool 历史重置。
+自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
+
+Task Pool **state identity** 进一步固定为 feature-scoped 复合键 `{ featureId, taskId }`（ADR 0004）：
+
+- canonical state 路径：`.harness/task-pool/states/<featureId>/<taskId>.json`（schema v2，文件内容必须携带 `featureId` / `taskId`）
+- 同仓库多 Feature 可安全使用相同 Task ID（例如 `F-A/QA-EXEC-001` 与 `F-B/QA-EXEC-001` 互不覆盖）
+- retry 必须显式指定 Feature：`agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`
+- 诊断与迁移：`agent-worker pool doctor --repo <repo> --json`（只读）；`agent-worker pool migrate-state --repo <repo>` 默认 dry-run，apply 需 `--owner` + `--reason`
+- 扁平 legacy `states/<taskId>.json` 不得静默解释；存在时新写入 fail-closed，必须经 doctor / migrate 处理
+- Observe 只读：canonical `#/feature/:featureId/task/:taskId` 与 `GET /api/features/:featureId/tasks/:taskId`；legacy bare task route 仅在唯一命中时兼容，歧义返回 409 + candidates
 
 ## 核心概念
 
@@ -169,6 +197,7 @@ nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 mo
 - **可选 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**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。

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

@@ -204,6 +204,9 @@ export async function generateTaskDagUseCase(input) {
     await assertExecPlanIndexConsistent(repoRoot);
     const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
     const isFrontendImplementationTask = taskConfig.taskKind === "frontend-implementation";
+    const isBackendTestTask = taskConfig.taskKind === "backend-test";
+    const isKnowledgeSyncTask = taskConfig.taskKind === "knowledge-sync";
+    const isKnowledgeGraphBootstrapTask = taskConfig.taskKind === "knowledge-graph-bootstrap";
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",
@@ -230,6 +233,48 @@ export async function generateTaskDagUseCase(input) {
             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;
+        }
+    }
+    if (isKnowledgeSyncTask) {
+        profileRouting.selectedTemplate = "knowledge-sync-dag";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "knowledge-sync" selects the dedicated knowledge-sync DAG template',
+        ];
+        if (parsed.profile === "auto") {
+            profileRouting.selectedByProfile =
+                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+        }
+        else if (parsed.profileExplicit) {
+            profileRouting.selectedByProfile = parsed.profile;
+        }
+    }
+    if (isKnowledgeGraphBootstrapTask) {
+        profileRouting.selectedTemplate = "knowledge-graph-bootstrap-dag";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "knowledge-graph-bootstrap" selects the dedicated knowledge-graph bootstrap 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, {

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

@@ -3,6 +3,9 @@ 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 } 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);
 }
@@ -29,6 +32,13 @@ function buildRunDagNextSteps(runId) {
 export async function runDagUseCase(input) {
     const spec = await loadDagSpecFromFile(input.dagPath);
     assertValidDagSpec(spec);
+    const runningIdentity = resolveRunningControllerIdentity();
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        ...(runningIdentity
+            ? { controllerVersion: runningIdentity.packageVersion }
+            : {}),
+    });
     const resolvedCanvasPath = resolveCanvasPath({
         canvasPath: input.canvasPath,
         canvasName: input.canvasName,

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

@@ -1,6 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { loadDagSpecFromFile } from "../../workflows/dag/runner.js";
 import { assertValidDagSpec, collectExecutorModelWarnings, collectForbiddenExecutorIssues, collectGovernanceWarnings, validateDagSpec, } 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";
 import { inferGovernanceProfile } from "../../workflows/dag/governance-profile.js";
 import { topoSortToRanks } from "../../workflows/dag/topo.js";
 import { runSpineAudit } from "../../governance/spine-audit.js";
@@ -103,6 +106,14 @@ export async function validateDagUseCase(input) {
     const spec = await loadDagSpecFromFile(input.dagPath);
     const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
     ensureNoForbiddenExecutors(spec, input.forbidExecutors, rawTaskExecutors);
+    // Runtime contract drift is always a hard error at validate time.
+    const runningIdentity = resolveRunningControllerIdentity();
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        ...(runningIdentity
+            ? { controllerVersion: runningIdentity.packageVersion }
+            : {}),
+    });
     const validationIssues = validateDagSpec(spec);
     const expectedMatrices = await loadExpectedExecutorModelMatrices(input.repoRoot);
     const warnings = collectExecutorModelWarnings(spec, expectedMatrices);

package/dist/cli/command-definitions.js

@@ -84,7 +84,14 @@ const HANDOFF_USAGE = "handoff <check|coverage> [taskId]";
 const REFERENCE_SUBCOMMANDS = ["index"];
 const STUDY_SUBCOMMANDS = ["init"];
 const WORKTREE_SUBCOMMANDS = ["create", "list", "remove"];
-const KNOWLEDGE_SUBCOMMANDS = ["curate"];
+const KNOWLEDGE_SUBCOMMANDS = [
+    "curate",
+    "query",
+    "graph-init",
+    "graph-materialize",
+    "graph-promote",
+    "graph-incremental-prepare",
+];
 const DAG_SUBCOMMANDS = [
     "init-hybrid",
     "run-task",
@@ -435,8 +442,8 @@ export const COMMAND_DEFINITIONS = [
         name: "knowledge",
         adapter: "required",
         tier: "operator",
-        intent: "Curate completed convergence patterns into human-gated learned guidance proposals.",
-        usage: "knowledge curate [--json|--markdown] [--output <path>]",
+        intent: "Curate repair guidance proposals, query the structured knowledge graph, and run graph bootstrap helpers (init/materialize/promote/incremental).",
+        usage: "knowledge <curate|query|graph-init|graph-materialize|graph-promote|graph-incremental-prepare> ...",
         subcommands: [...KNOWLEDGE_SUBCOMMANDS],
         handler: async ({ repoRoot, subcommand, rest }) => {
             await runKnowledge(repoRoot, [subcommand, ...rest].filter((arg) => Boolean(arg)));

package/dist/commands/init.js

@@ -1036,15 +1036,62 @@ async function readInitSurfaceManifest(assetRoot) {
     const manifest = JSON.parse(raw);
     const initFullRequired = manifest.initFullRequired ?? [];
     const initSurface = manifest.initSurface ?? {};
-    const entries = initFullRequired.map((relativePath) => ({
-        path: relativePath,
-        mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
-    }));
+    const seenPaths = new Set();
+    const entries = [];
+    for (const relativePath of initFullRequired) {
+        if (seenPaths.has(relativePath))
+            continue;
+        seenPaths.add(relativePath);
+        entries.push({
+            path: relativePath,
+            mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
+        });
+    }
+    // Fresh `init --profile full` copies the entire `docs/templates/` and
+    // `skills/` directories via copyDirMerge. Every file actually projected to a
+    // target project must be represented in the desired init surface so that
+    // check-update can detect missing or stale copies during controller upgrades.
+    // The static manifest intentionally only pins explicit modes for the subset
+    // that needs them; the rest are auto-discovered here as "copied" entries.
+    for (const discovered of await discoverCopiedSurfaceFiles(assetRoot)) {
+        if (seenPaths.has(discovered))
+            continue;
+        seenPaths.add(discovered);
+        entries.push({
+            path: discovered,
+            mode: initSurface[discovered] ?? inferInitSurfaceMode(discovered),
+        });
+    }
     if (!entries.some((entry) => entry.path === INIT_SURFACE_STATE_PATH)) {
         entries.push({ path: INIT_SURFACE_STATE_PATH, mode: "state" });
     }
     return { manifest, raw, sha256: sha256Text(raw), entries };
 }
+/**
+ * Returns manifest-path entries for every file that fresh `init --profile full`
+ * copies from the bundled package into a target project: all of `docs/templates/`
+ * and all of `skills/` (the latter is mirrored to `.agents/skills/` at the
+ * target). Paths use the package source convention so manifestPathToTargetPath
+ * can remap them per governance root.
+ */
+async function discoverCopiedSurfaceFiles(assetRoot) {
+    const discovered = [];
+    const roots = [
+        { source: "docs/templates", prefix: "docs/templates/" },
+        { source: "skills", prefix: "skills/" },
+    ];
+    for (const { source, prefix } of roots) {
+        const rootPath = path.join(assetRoot, source);
+        const rootInfo = await stat(rootPath).catch(() => null);
+        if (!rootInfo?.isDirectory())
+            continue;
+        const files = await listRelativeFiles(rootPath);
+        for (const relativePath of files) {
+            discovered.push(`${prefix}${relativePath}`);
+        }
+    }
+    return discovered.sort();
+}
 function inferInitSurfaceMode(relativePath) {
     if (relativePath === INIT_SURFACE_STATE_PATH)
         return "state";
@@ -1378,8 +1425,9 @@ function hasLegacyHarnessGovernancePaths(harness) {
     return false;
 }
 async function collectRetiredLayoutActions(input) {
+    const blockedTargetPaths = new Set();
     if (!input.recordedState)
-        return [];
+        return { actions: [], blockedTargetPaths };
     const actions = [];
     const retiredOwnedPaths = [];
     const currentPaths = new Set(Object.keys(input.currentState.files));
@@ -1399,6 +1447,9 @@ async function collectRetiredLayoutActions(input) {
                 path: oldPath,
                 reason: `legacy init file may have local edits; review before migrating to ${targetPath}`,
             });
+            // The user owns a modified copy at the legacy path; do not silently
+            // install the package version at the canonical target path.
+            blockedTargetPaths.add(targetPath);
             continue;
         }
         const targetAbsolute = path.join(input.repoRoot, targetPath);
@@ -1442,6 +1493,7 @@ async function collectRetiredLayoutActions(input) {
             path: oldPath,
             reason: `legacy init file is owned, but target path ${targetPath} already exists with different content`,
         });
+        blockedTargetPaths.add(targetPath);
     }
     for (const legacyRoot of ["docs", "skills"]) {
         for (const relativePath of await listRelativeFiles(path.join(input.repoRoot, legacyRoot))) {
@@ -1476,6 +1528,7 @@ async function collectRetiredLayoutActions(input) {
                     path: oldPath,
                     reason: `legacy init-shaped file is not recorded and differs from the current bundled/generated asset; review before migrating to ${targetPath}`,
                 });
+                blockedTargetPaths.add(targetPath);
                 continue;
             }
             if (!targetHash) {
@@ -1492,6 +1545,7 @@ async function collectRetiredLayoutActions(input) {
                 path: oldPath,
                 reason: `legacy init-shaped file matches the package, but target path ${targetPath} already exists with different content`,
             });
+            blockedTargetPaths.add(targetPath);
         }
     }
     for (const dir of collectSafeRetiredDirectories(retiredOwnedPaths)) {
@@ -1501,7 +1555,7 @@ async function collectRetiredLayoutActions(input) {
             reason: "remove directory if it is empty after legacy init files are migrated",
         });
     }
-    return actions;
+    return { actions, blockedTargetPaths };
 }
 async function resolveInitProjectContext(input) {
     const harness = await readJsonIfExists(path.join(input.repoRoot, "harness.json"));
@@ -1771,6 +1825,13 @@ function buildTargetFeatureWorkflow(input) {
         "",
         "Before executing a DAG, review profile routing, governance profile, writer writeSet, allowed paths, forbidden paths, shell verification, and decision gate mode.",
         "",
+        "## Specialized Task Kinds",
+        "",
+        "Set `taskKind` in `.harness/tasks/<task-id>/task.json` to route a task to a dedicated DAG profile instead of the default auto profile:",
+        "",
+        "- `taskKind: \"backend-test\"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project's pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.",
+        "- Only eligible read-only Pi nodes (planner, scout, reviewer, verifier, closeout with no write-capable tool profile) receive the conservative automatic retry policy. Supervisor, implementer, writer, docs-only, dynamic, shell, static, and decision-gate nodes are not retried automatically. Eligible nodes cannot write repository files; the controller only records immutable attempt evidence under `.harness/dag-runs/<state>/<run-id>/<node-id>/attempt-<n>.json`.",
+        "",
         "## Verification",
         "",
         `Use \`${input.governanceRoot}/verification-matrix.md\` to choose the narrowest command that proves the claim.`,
@@ -2169,7 +2230,7 @@ export async function checkInitUpdate(input) {
     const deterministicActions = [];
     const modelMergeTasks = [];
     const humanDecisions = [];
-    const retiredLayoutActions = await collectRetiredLayoutActions({
+    const retiredLayoutResult = await collectRetiredLayoutActions({
         assetRoot,
         repoRoot,
         projectName,
@@ -2178,9 +2239,15 @@ export async function checkInitUpdate(input) {
         currentState,
         humanDecisions,
     });
+    const retiredLayoutActions = retiredLayoutResult.actions;
     const retiredTargetPaths = new Set(retiredLayoutActions
         .filter((action) => action.type === "migrate-owned-file" && action.targetPath)
         .map((action) => action.targetPath));
+    // Targets occupied by a user-modified legacy copy must not be silently
+    // (re)installed from the package; preserve them for a human/model merge.
+    for (const blockedPath of retiredLayoutResult.blockedTargetPaths) {
+        retiredTargetPaths.add(blockedPath);
+    }
     if (!recordedState) {
         deterministicActions.push({
             type: "bootstrap-surface",