@tea-agent/loop-agent 0.11.0 → 0.12.0

package/docs/agent-dag-runner.md

@@ -17,7 +17,32 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 - `static`：确定性生成的 artifacts 或 notes
 - `shell`：验证与文件系统检查
 - `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-- `cursor`：显式启用时的可选有界写后端
+
+## Retry (read-only Pi nodes)
+
+planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
+
+- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
+- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
+- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
+- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
+- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
+
+示例：
+
+```json
+{
+  "retryPolicy": {
+    "maxAttempts": 3,
+    "backoff": "exponential",
+    "initialDelayMs": 2000,
+    "maxDelayMs": 30000,
+    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
+  }
+}
+```
+
+未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
 
 ## Skills
 

package/docs/architecture/dag-execution.md

@@ -34,6 +34,12 @@ src/commands/dag-validate.ts  runDagValidate
   → src/application/dag/validate-dag.ts  validateDagUseCase
 ```
 
+### runtime contract preflight 与 repair writer 解析
+
+- `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
+- `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
+- `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
+
 ## rank 调度
 
 拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：

package/docs/architecture/evolution.md

@@ -2,7 +2,7 @@
 
 本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0003、`docs/exec-plans/completed/`。
 
-## 当前已实现（0.10.0 + 主干 Unreleased）
+## 当前已实现（0.11.0）
 
 | 域 | 现状 | 权威入口 |
 | --- | --- | --- |
@@ -12,7 +12,8 @@
 | 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
 | Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
 | Task Pool | 唯一根 `.harness/task-pool/` | ADR 0002 |
-| Observe | 本地只读暖白控制台（derived） | `website/docs/guides/observe-ui.md` |
+| Observe | 本地只读暖白运营控制台 R1–R5（derived） | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]` |
+| DagSpec / repair | v3 + `runtimeContract`；显式 `repairNodeId` | `CHANGELOG.md [0.11.0]`、`dag-execution.md` |
 | 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
 | 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
 
@@ -24,7 +25,7 @@
 
 ## 未来规划（第 3–6 月，**未实现**）
 
-以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（两文件均带 2026-07-14 校准条，未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
 
 | 未来方向 | 状态 | 规划来源 |
 | --- | --- | --- |

package/docs/architecture/facts-and-state.md

@@ -15,7 +15,7 @@
 
 ### 区分要点
 
-- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、decision envelope、convergence。
+- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、controller identity（`controller-identity.json`，冻结执行 controller 的 package version/binary 哈希/portable fingerprint，state 记录相对 ref 与内容哈希，resume 时重新校验、漂移 fail closed）、decision envelope、convergence。
 - **DAG run vs one-shot run**：DAG run 在 `.harness/dag-runs/`，有三态 lifecycle；one-shot run（当前主要由 `cursor-prompt` 及显式 one-shot evidence 路径产生）在 `.harness/runs/`，三态为 `active|completed|failed`。`pi-prompt` 当前不创建该目录下的 run evidence。两者是不同根、不同 schema。
 - **Loop 不是顶层根**：Loop 状态在 `.harness/tasks/<taskId>/loop/`，是 task 之上的多轮状态机（round、signal、context、failureStreak、closeout）。
 - **Task Pool 是 Worker 专用可选根**：只有使用 `agent-worker` 产品线时才存在；唯一根 `.harness/task-pool/`。

package/docs/design/README.md

@@ -16,10 +16,10 @@
 | 文档 | 用途 |
 |---|---|
 | `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 适配分析与阶段规划；**页首有实现状态 / Pi-only 校准条**（已落地 vs 设计输入）；正文 Cursor 叙述视为历史 |
-| `六个月规划.md` | 长期路线；**第 1–2 月已收敛为 archive/reports 指针**，当前有效前瞻从第 3 月起 |
-| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
+| `六个月规划.md` | 长期路线；**页首 2026-07-15 / 0.11.0 校准**；第 1–2 月为 archive/reports 指针，当前有效前瞻从第 3 月起 |
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源；**页首 2026-07-15 / 0.11.0 校准**（模板+Feature dogfood 已落地 vs docs-sync 未来） |
 | `研发模式.md` | 10 个工作日 Feature 团队工作流 |
-| `腾讯实践对当前项目的指引.md` | 腾讯 Harness Engineering 实践对本仓库的映射笔记 |
+| `腾讯实践对当前项目的指引.md` | 腾讯 Harness Engineering 实践对本仓库的映射笔记；源文见 `website/docs/practices/tencent-harness-engineering/index.md` |
 
 ## 视觉参考
 
@@ -39,6 +39,7 @@
 | `archive/2026-07-10-observe-ui.md` | 已归档：Observe UI v0 设计（OBS-001～010；0.9.0 暖白重设计在其上演进） |
 | `archive/2026-07-10-observe-ui-optimization.md` | 已归档：Observe UI 中文化与过程时间线（UI-1～UI-9 已实现） |
 | `archive/2026-07-10-observe-ui-goal.md` | 已归档：OBS-001～010 逐任务进度看板（全部 done） |
+| `archive/2026-07-14-observe-ui-roadmap.md` | 已归档：Observe R1–R5 运营控制台路线图（资源池/Batch-Run/Feature 关联/事件时间线/前端模块化；证据见 completed plans + reports） |
 | `archive/2026-07-11-第一月规划.md` | 已归档：首月落地计划（0.8.0 + Round 1/2/3 闭环） |
 | `archive/2026-07-11-第一月wbs.md` | 已归档：首月 WBS 与分工（历史记录） |
 | `archive/2026-07-12-第二月规划.md` | 已归档：第二月本地 Feature 交付闭环（M2-01～08；见 `docs/reports/2026-07-12-m2-completion-audit.md`） |

package/docs/exec-plans/active/README.md

@@ -6,6 +6,4 @@
 
 当前 active execution plan：
 
-- 暂无。
-
-- 已归档：`../completed/2026-07-14-init-canonical-layout.md`、`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。
+- 已归档：`../completed/2026-07-15-repair-artifact-gate-runtime-contract.md`、`../completed/2026-07-14-observe-ui-r5.md`、`../completed/2026-07-14-observe-ui-r4.md`、`../completed/2026-07-14-observe-ui-r3.md`、`../completed/2026-07-14-observe-ui-r2.md`、`../completed/2026-07-14-observe-ui-r1.md`、`../completed/2026-07-14-init-canonical-layout.md`、`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。

package/docs/exec-plans/completed/README.md

@@ -4,6 +4,13 @@
 
 npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
 
+- [`2026-07-15-repair-artifact-gate-runtime-contract.md`](2026-07-15-repair-artifact-gate-runtime-contract.md) — 显式 `repairNodeId` + 严格 repair writer 契约、DagSpec `runtimeContract` capability preflight，以及 run-owned controller identity（resume 漂移 fail-closed）
+- [`2026-07-14-backend-test-dag-template.md`](2026-07-14-backend-test-dag-template.md) — 通过 `taskKind: "backend-test"` 生成需求分析、功能用例、pytest 自动化、执行与复盘的 Pi-only 专用 DAG
+- [`2026-07-14-observe-ui-r5.md`](2026-07-14-observe-ui-r5.md) — Observe 原生 ES module 拆分、四态 helper、Pool hash 筛选与入口 re-export
+- [`2026-07-14-observe-ui-r4.md`](2026-07-14-observe-ui-r4.md) — Observe Batch/Pool 有界事件时间线、cursor/limit、JSONL 容量与投影 fault-first
+- [`2026-07-14-observe-ui-r2.md`](2026-07-14-observe-ui-r2.md) — Observe Batch / Worker Run 证据化详情、三层只读结构与安全 artifact preview
+- [`2026-07-14-observe-ui-r3.md`](2026-07-14-observe-ui-r3.md) — Observe Feature 决策详情、copy-only 建议命令与 canonical 对象关系导航
+- [`2026-07-14-observe-ui-r1.md`](2026-07-14-observe-ui-r1.md) — Observe 资源池总览、Task 下钻、精确对象关联与有界 run history
 - [`2026-07-14-init-canonical-layout.md`](2026-07-14-init-canonical-layout.md) — 目标项目治理资料统一到 `ai_workspace/loop-agent/` 与 `.agents/skills/`，并为旧布局提供保守安全迁移
 - [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — 实现 loop-agent CLI 自更新提醒，覆盖拒绝版本、精确安装、npm global 来源证明和验证收口
 - [`2026-07-12-observe-warm-console-redesign.md`](2026-07-12-observe-warm-console-redesign.md) — 以暖白、细边界和高密度信息架构重构 Observe Dashboard；多轮细节调整后按用户确认收口归档。
@@ -60,3 +67,7 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 - [`2026-07-10-observe-ui-review-remediation.md`](2026-07-10-observe-ui-review-remediation.md) — 修复 Observe UI 事件链路、历史 run 投影、artifact 安全边界与失败状态展示
 
 - [`2026-07-13-exec-plan-lifecycle.md`](2026-07-13-exec-plan-lifecycle.md)
+
+- [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md)
+
+- [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md)

package/docs/feature-workflow.md

@@ -121,6 +121,30 @@ frontend-contract-pi
 ```
 
 这条链在实现前加入 design gate，并将前端静态验证与行为验证分开建模；当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
+
+后端测试任务可通过 `task.json.taskKind = "backend-test"` 选择专用模板；它不新增 governance profile：
+
+```text
+analyze-inputs-pi
+  -> generate-backend-functional-cases-pi
+  -> review-backend-cases-pi
+  -> review-backend-cases-gate-shell
+  -> generate-backend-pytest-pi
+  -> execute-backend-pytest-shell
+  -> test-retrospect-pi
+```
+
+这条链覆盖后端功能测试从需求分析到复盘评级的全链路流程：
+
+1. **analyze-inputs-pi**：读取需求.md 和开发详设等参考文档，产出端到端测试分析契约（范围、风险、策略要点）
+2. **generate-backend-functional-cases-pi**：根据契约生成结构化后端功能测试用例（Markdown），用例 ID 带 `BE-` 前缀（如 `BE-ORDER-001`），写入 `testcase/md/`
+3. **review-backend-cases-pi**：评审后端功能测试用例，输出审查报告 + `VERDICT: pass` / `VERDICT: request-revision`
+4. **review-backend-cases-gate-shell**：只有评审首条 verdict 为 `VERDICT: pass` 时才允许继续生成 pytest
+5. **generate-backend-pytest-pi**：将后端功能用例转化为 pytest 自动化代码，仅写入 `testcase/**/test_*.py`
+6. **execute-backend-pytest-shell**：执行 `pytest testcase/` 并生成 HTML 报告
+7. **test-retrospect-pi**：读取上游审查报告和测试报告，生成复盘报告 + 成熟度评级（A/B/C/D）
+
+前端测试模板（`frontend-test-dag`）后续沿用对称命名即可接入。
 前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
 
 `verify-shell` 使用 adapter 根据 task verify preset/quota 解析出的最终验证命令，并把新鲜 exit code/stdout/stderr 交给后续只读 verifier。review-gated 模板继续插入：
@@ -131,6 +155,10 @@ verify-shell -> verify-pi -> review-pi -> review-gate-shell -> closeout-pi
 
 supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
 
+### 只读 Pi 节点安全重试
+
+所有生成模板都会为安全的只读 Pi 节点（planner/scout/reviewer/verifier/closeout，且 `writePolicy=read-only|none`、非 writer、非 dynamic、非 decision-gate）自动声明默认 `retryPolicy`（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不在资格范围。仅重试 `timeout`、`network`、`rate-limit`、`unavailable`；`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试。每次 attempt 保留独立证据，详见 [docs/agent-dag-runner.md](./agent-dag-runner.md#retry-read-only-pi-nodes)。
+
 ### 可选 repo-local SDD skill 增强
 
 `dag run-task` 会在目标项目的 `.agents/skills/` 中探测三个可选 skill：

package/docs/progress/README.md

@@ -6,6 +6,15 @@
 
 ## 近期要点（导读）
 
+- [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md) — 修复初始化 surface 升级漏检（自动发现 copied 文件、blockedTargetPaths fail-safe、drift gate）实施交接（已验证）
+- [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md) — 只读 Pi DAG 节点安全重试（默认策略、attempt 证据、validation 门禁）实施交接（已验证）
+- [`2026-07-15-repair-artifact-gate-runtime-contract-implementation.md`](2026-07-15-repair-artifact-gate-runtime-contract-implementation.md) — 显式 repairNodeId、runtime contract preflight 与 run-owned controller identity 实施交接（已验证）
+- [`2026-07-14-observe-ui-r5-boundary-final.md`](2026-07-14-observe-ui-r5-boundary-final.md) — R5 轻量入口与显式模块边界 DAG closeout
+- [`2026-07-14-observe-ui-r5-remediation.md`](2026-07-14-observe-ui-r5-remediation.md) — R5 浏览器状态所有权修复 DAG closeout
+- [`2026-07-14-observe-ui-r5.md`](2026-07-14-observe-ui-r5.md) — Observe 前端模块化与体验收敛（已验证）
+- [`2026-07-14-observe-ui-r4.md`](2026-07-14-observe-ui-r4.md) — Observe 事件时间线、有界 JSONL 与投影健康（已验证）
+- [`2026-07-14-observe-ui-r3.md`](2026-07-14-observe-ui-r3.md) — Observe Feature 决策详情与对象关联导航（已验证）
+- [`2026-07-14-observe-ui-r2.md`](2026-07-14-observe-ui-r2.md) — Observe Batch / Worker Run 证据化详情收口
 - [`2026-07-14-init-canonical-layout-handoff.md`](2026-07-14-init-canonical-layout-handoff.md) — 目标项目初始化布局迁移到 `ai_workspace/loop-agent/` 与 `.agents/skills/` 的跨会话交接
 - [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — loop-agent CLI 自更新提醒实现、TDD 验证和 bounded DAG fallback 交接
 - [`2026-07-14-docs-living-docs-calibration.md`](2026-07-14-docs-living-docs-calibration.md) — 活文档校准（Dynamic Workflow / 六个月 / ADR）
@@ -18,6 +27,15 @@
 
 ## 全量列表（新→旧）
 
+- [`2026-07-15-init-update-surface-coverage.md`](2026-07-15-init-update-surface-coverage.md)
+- [`2026-07-15-readonly-node-retry.md`](2026-07-15-readonly-node-retry.md)
+- [`2026-07-15-repair-artifact-gate-runtime-contract-implementation.md`](2026-07-15-repair-artifact-gate-runtime-contract-implementation.md)
+- [`2026-07-14-observe-ui-r5-boundary-final.md`](2026-07-14-observe-ui-r5-boundary-final.md)
+- [`2026-07-14-observe-ui-r5-remediation.md`](2026-07-14-observe-ui-r5-remediation.md)
+- [`2026-07-14-observe-ui-r5.md`](2026-07-14-observe-ui-r5.md)
+- [`2026-07-14-observe-ui-r4.md`](2026-07-14-observe-ui-r4.md)
+- [`2026-07-14-observe-ui-r3.md`](2026-07-14-observe-ui-r3.md)
+- [`2026-07-14-observe-ui-r2.md`](2026-07-14-observe-ui-r2.md)
 - [`2026-07-14-init-canonical-layout-handoff.md`](2026-07-14-init-canonical-layout-handoff.md)
 - [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md)
 - [`2026-07-14-website-docs-ia-and-converge.md`](2026-07-14-website-docs-ia-and-converge.md)

package/docs/reports/README.md

@@ -8,11 +8,14 @@
 
 - 按日期前缀浏览下方列表（新→旧）
 - init surface 审查：文件名含 `init-evolution-review`
-- 能力基线滚动分析：[`2026-07-02-repository-analysis.md`](2026-07-02-repository-analysis.md)（长文，非单次任务证据）
+- 能力基线滚动分析：[`2026-07-02-repository-analysis.md`](2026-07-02-repository-analysis.md)（**已冻结**；2026-07-15 最终再采样关闭 0.11.0；非第二 CHANGELOG）
 
 ## 近期要点（导读，非权威全集）
 
 - [`current-capability-summary.md`](current-capability-summary.md) — **活**能力摘要（新进展写这里 / CHANGELOG / 新 report）
+- [`2026-07-15-init-update-surface-coverage-init-evolution-review.md`](2026-07-15-init-update-surface-coverage-init-evolution-review.md) — 初始化 surface 升级漏检修复的 init surface 审查（init update required）
+- [`2026-07-15-readonly-node-retry-init-evolution-review.md`](2026-07-15-readonly-node-retry-init-evolution-review.md) — 只读 Pi DAG 节点安全重试的 init surface 审查（surface check only，无需 init evolution）
+- [`2026-07-15-backend-test-dag-init-evolution-review.md`](2026-07-15-backend-test-dag-init-evolution-review.md) — 后端测试专用 DAG 的 package/init surface 审查
 - [`2026-07-15-init-canonical-layout-init-evolution-review.md`](2026-07-15-init-canonical-layout-init-evolution-review.md) — init canonical layout、旧布局安全迁移和废弃 harness 字段清理审查
 - [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — loop-agent CLI 自更新提醒实现、DAG 边界、TDD 与 init surface 非影响证据
 - [`2026-07-14-docs-living-docs-calibration.md`](2026-07-14-docs-living-docs-calibration.md) — 活文档校准（Dynamic Workflow / 六个月 / analysis 冻结 / ADR）
@@ -21,10 +24,13 @@
 - [`2026-07-13-sdd-embedded-skills.md`](2026-07-13-sdd-embedded-skills.md) — repo-local SDD skill 嵌入增强的 DAG、TDD、独立审查、验证和基线风险证据
 - [`2026-07-13-versioned-self-hosting-bootstrap.md`](2026-07-13-versioned-self-hosting-bootstrap.md) — 版本化自举证据
 - [`2026-07-12-m2-completion-audit.md`](2026-07-12-m2-completion-audit.md) — 第二月完成审计
-- [`2026-07-02-repository-analysis.md`](2026-07-02-repository-analysis.md) — **已冻结**仓库能力基线快照（勿再当 CHANGELOG）
+- [`2026-07-02-repository-analysis.md`](2026-07-02-repository-analysis.md) — **已冻结**仓库能力基线快照（2026-07-15 最终再采样至 0.11.0；勿再当 CHANGELOG）
 
 ## 全量列表（新→旧）
 
+- [`2026-07-15-init-update-surface-coverage-init-evolution-review.md`](2026-07-15-init-update-surface-coverage-init-evolution-review.md)
+- [`2026-07-15-readonly-node-retry-init-evolution-review.md`](2026-07-15-readonly-node-retry-init-evolution-review.md)
+- [`2026-07-15-backend-test-dag-init-evolution-review.md`](2026-07-15-backend-test-dag-init-evolution-review.md)
 - [`2026-07-15-init-canonical-layout-init-evolution-review.md`](2026-07-15-init-canonical-layout-init-evolution-review.md)
 - [`dogfood-preflight-static-20260709090443.md`](dogfood-preflight-static-20260709090443.md)
 - [`current-capability-summary.md`](current-capability-summary.md)

package/docs/templates/agent-dag-report.schema.json

@@ -444,6 +444,23 @@
         },
         "pausedByNodeId": { "type": "string" },
         "pauseReason": { "type": "string" },
+        "controllerIdentity": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "capturedAt", "runtimeContractCompatibility"],
+          "properties": {
+            "status": { "enum": ["pinned", "legacy-unpinned"] },
+            "capturedAt": { "type": "string" },
+            "packageName": { "type": "string" },
+            "packageVersion": { "type": "string" },
+            "packageFingerprint": { "type": "string" },
+            "binarySha256": { "type": "string" },
+            "runtimeContractCompatibility": {
+              "enum": ["compatible", "incompatible", "legacy-unspecified"]
+            },
+            "runtimeContractReason": { "type": "string" }
+          }
+        },
         "executorJsonl": { "$ref": "#/$defs/dagArtifactRef" },
         "convergence": { "$ref": "#/$defs/dagConvergence" },
         "nodes": {

package/docs/templates/agent-dag.schema.json

@@ -5,18 +5,29 @@
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "title", "tasks"],
+  "allOf": [
+    {
+      "if": { "properties": { "version": { "const": 3 } }, "required": ["version"] },
+      "then": { "required": ["runtimeContract"] }
+    },
+    {
+      "if": { "required": ["runtimeContract"] },
+      "then": { "properties": { "version": { "const": 3 } } }
+    }
+  ],
   "properties": {
     "$schema": {
       "type": "string"
     },
     "version": {
-      "enum": [1, 2],
+      "enum": [1, 2, 3],
       "default": 1
     },
     "title": {
       "type": "string",
       "minLength": 1
     },
+    "runtimeContract": { "$ref": "#/$defs/runtimeContract" },
     "objective": {
       "type": "string"
     },
@@ -72,6 +83,21 @@
     "required": ["models"]
   },
   "$defs": {
+    "runtimeContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "agentRuntime", "repairWriterProtocol"],
+      "description": "DagSpec v3 controller capability handshake. Compatibility is decided by capability fields first; minimumControllerVersion is enforced when present. Legacy v1/v2 DAGs may omit this block.",
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "agentRuntime": { "const": "pi-only" },
+        "repairWriterProtocol": { "const": "explicit-node-v1" },
+        "minimumControllerVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+([-+].+)?$"
+        }
+      }
+    },
     "complexity": {
       "enum": ["LOW", "MED", "HIGH"]
     },
@@ -140,6 +166,11 @@
         "fromNodeId": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "repairNodeId": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Explicit governed Pi repair writer this gate feeds (executor=pi, toolProfile=write, writePolicy=exclusive, non-empty allowedPaths+writeSet, depends_on the gate). New DAGs must set this; legacy DAGs are only accepted when a unique safe downstream Pi writer can be derived."
         }
       }
     },
@@ -211,6 +242,39 @@
         "status": { "enum": ["success", "error"] }
       }
     },
+    "retryPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maxAttempts"],
+      "description": "Retry policy for safe read-only planner/scout/reviewer/verifier/closeout Pi nodes. Total attempts include the first try and are capped at five. Supervisors, implementers, and side-effecting nodes are ineligible. Only the categories listed in retryCategories are retried; quota/auth/invalid-output/write-guard are never retried.",
+      "properties": {
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5,
+          "description": "Total attempts including the first try. 1 disables retry."
+        },
+        "backoff": { "const": "exponential", "default": "exponential" },
+        "initialDelayMs": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 2000
+        },
+        "maxDelayMs": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 30000
+        },
+        "retryCategories": {
+          "type": "array",
+          "items": {
+            "enum": ["timeout", "network", "rate-limit", "unavailable"]
+          },
+          "default": ["timeout", "network", "rate-limit", "unavailable"],
+          "description": "Failure categories eligible for retry. quota is never eligible."
+        }
+      }
+    },
     "promptSource": {
       "type": "object",
       "additionalProperties": false,
@@ -296,6 +360,10 @@
               "default": "record-only"
             }
           }
+        },
+        "retryPolicy": {
+          "$ref": "#/$defs/retryPolicy",
+          "description": "Opt-in retry policy. Allowed only on safe read-only planner/scout/reviewer/verifier/closeout non-dynamic Pi nodes; validation rejects it on supervisors, implementers, writers, dynamic, shell, static, docs-only, and decision-gate nodes. Generated DAGs declare the default policy on eligible nodes automatically."
         }
       },
       "oneOf": [

package/docs/templates/agent-dag.supervised-implementation.json

@@ -1,7 +1,12 @@
 {
   "$schema": "./agent-dag.schema.json",
-  "version": 2,
+  "version": 3,
   "title": "Agent DAG supervised implementation template",
+  "runtimeContract": {
+    "schemaVersion": 1,
+    "agentRuntime": "pi-only",
+    "repairWriterProtocol": "explicit-node-v1"
+  },
   "objective": "Demonstrate a reusable supervised implementation DAG: contract → parallel scouts → plan → write-set audit → write-set gate → implement → soft verify → process supervisor → repair → hard verify → review verdict → review gate → decision gate → closeout. Write-set, process, and review verdict nodes emit first-line VERDICT for deterministic gates, reducing main-session intervention.",
   "successCriteria": [
     "contract-pi returns a read-only implementation contract with narrow write boundaries",
@@ -318,7 +323,8 @@
           "lineMode": "first-verdict-line"
         },
         "repairArtifactGate": {
-          "fromNodeId": "process-supervisor-pi"
+          "fromNodeId": "process-supervisor-pi",
+          "repairNodeId": "repair-pi"
         },
         "cwd": ".",
         "timeoutMs": 60000

package/docs/templates/backend-test-dag.generate-pytest.prompt.md

@@ -0,0 +1,139 @@
+# Backend Test DAG Generate Pytest Prompt Template
+
+## Purpose
+
+Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts reviewed backend functional test cases into pytest automation code with 1:1 traceability.
+
+Do **not** create a new executor type. This is a standard `executor: pi` writer node.
+
+## Recommended DAG Node Shape
+
+```json
+{
+  "id": "generate-backend-pytest-pi",
+  "depends_on": ["review-backend-cases-gate-shell"],
+  "complexity": "HIGH",
+  "executor": "pi",
+  "role": "implementer",
+  "toolProfile": "write",
+  "writePolicy": "exclusive",
+  "writeSet": ["testcase/**/test_*.py"],
+  "allowedPaths": ["testcase/**/test_*.py"],
+  "forbiddenPaths": [".harness/**", "artifacts/**"],
+  "outputContract": "Pytest test files under tests/backend/ with 1:1 mapping to functional test case IDs. Summary lists generated files, test function count, and any skipped cases with reasons.",
+  "subtask_prompt_markdown": "./backend-test-dag.generate-pytest.prompt.md"
+}
+```
+
+## Prompt Body
+
+You are the Backend Test DAG **pytest code generator**.
+
+Your job is to convert reviewed test cases under `testcase/md/` into pytest automation code. Write test files under `testcase/` only. Stay within `writeSet`. Do not write root `artifacts/**`.
+
+### Output Steps (do in order)
+
+1. First, output a brief summary: how many files, how many test functions planned
+2. Then write each test file under `testcase/`
+
+### Inputs
+
+1. **Reviewed test cases** — files under `testcase/md/` (approved by `review-backend-cases-pi`).
+2. **Target project conventions** — read `conftest.py`, `pytest.ini` / `pyproject.toml` to understand conventions, but do NOT modify them.
+
+Do NOT re-read source documents. Use the reviewed cases only.
+
+### Conversion Rules
+
+#### File Naming
+
+- Every test file must start with `test_` prefix (e.g. `test_order.py`, `test_user_api.py`)
+- pytest collects tests from files matching `test_*.py` or `*_test.py` — use `test_` prefix exclusively
+- Never create test files without the `test_` prefix
+
+#### Write Boundary
+
+- Only **create new** test script files under `testcase/`
+- Do NOT modify existing files: `conftest.py`, `pytest.ini`, `pyproject.toml`, `setup.cfg`, `__init__.py`, or any other framework/config file
+- Reuse existing fixtures; if required fixtures do not exist, report the gap instead of creating or modifying framework files
+- Read existing framework files to understand conventions, but treat them as immutable
+
+#### Naming Conflict Resolution
+
+- If a file with the target name already exists under `testcase/`, add a numeric suffix: `test_order.py` → `test_order_01.py` → `test_order_02.py`
+- Never overwrite or append to existing files — each test script must be a standalone file
+- Check for existing files before writing; if `test_<module>.py` exists, use `test_<module>_01.py`
+
+#### 1:1 Traceability
+
+Every functional test case ID (`BE-<MODULE>-<NNN>`) must map to exactly one pytest function:
+
+```python
+# testcase/md/BE-ORDER-001 → testcase/test_order.py
+def test_BE_ORDER_001_create_order_with_valid_data():
+    """BE-ORDER-001: Create order with valid request body."""
+    ...
+```
+
+- Function name: `test_<CASE_ID_with_underscores>` (e.g. `test_BE_ORDER_001_...`)
+- Docstring first line: `<CASE_ID>: <Case Title>`
+
+#### File Organization
+
+- All test files go under `testcase/` directory in the host project root
+- Group test files by MODULE segment: `BE-ORDER-*` → `testcase/test_order.py`, `BE-USER-*` → `testcase/test_user.py`
+- Follow existing project conventions for import style, fixture scope
+
+#### Fixture Strategy
+
+- Reuse existing project fixtures from `conftest.py` when available
+- Do not create or modify fixture/configuration files in this node
+- Prefer `@pytest.fixture(scope="function")` for test isolation
+- Use `@pytest.mark.parametrize` for boundary condition cases with multiple inputs
+
+#### Test Integrity
+
+- Tests verify implementation correctness — if a test fails, the implementation likely has a bug, not the test
+- Do NOT weaken assertions, remove test cases, or modify test logic to make tests pass
+- Do NOT add workarounds, skips, or try/except blocks to hide failures without explicit justification
+- Report all failures honestly in the output; the downstream `execute-backend-pytest-shell` node captures exit codes and stdout/stderr as-is
+
+#### Assertions
+
+- Use `assert` statements, not `unittest` assertions
+- Assert specific values, not just "no exception"
+- For API tests: assert status code, response body keys, and specific field values
+- For database tests: assert record state after operation
+
+#### Conditional Test Implementation (include ONLY if test cases exist)
+
+- **Authentication tests**: implement ONLY if `testcase/md/` contains auth-related cases
+  - Use `@pytest.mark.auth` marker
+  - Test no token, expired token, invalid token, insufficient permissions, cross-user access
+- **Timeout tests**: implement ONLY if `testcase/md/` contains timeout-related cases
+  - Use `@pytest.mark.timeout` marker
+  - Use `unittest.mock.patch` or `pytest-mock` to simulate slow responses
+- If no such cases exist in the reviewed test cases, do NOT add these tests
+
+#### Markers
+
+- `@pytest.mark.positive` — happy path cases
+- `@pytest.mark.negative` — error/exception cases
+- `@pytest.mark.boundary` — edge cases
+- `@pytest.mark.<MODULE>` — module-specific marker (e.g. `@pytest.mark.order`)
+
+#### Skip Policy
+
+If a test case cannot be automated (requires external service not mockable, requires manual verification), add it with `@pytest.mark.skip(reason="...")` and document the reason. Do not omit the function — traceability requires it exists.
+
+### Output Shape (after summary line)
+
+After the mandatory summary line, provide:
+
+1. **Generated Files** — list of files written under `tests/backend/`.
+2. **Function Mapping Table** — `| Test Case ID | Pytest Function | File | Marker |`.
+3. **Skipped Cases** — if any, list with reason.
+4. **Conventions Observed** — note project fixtures/config discovered and followed.
+5. **Residual Risks** — cases that may need manual verification or environment setup.
+
+Do not include chain-of-thought. Do not write root `artifacts/**`.