@tea-agent/loop-agent 0.10.0 → 0.12.0

package/skills/grill-with-docs/context-format.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- `src/ordering/CONTEXT.md` — receives and tracks customer orders
+- `src/billing/CONTEXT.md` — generates invoices and processes payments
+- `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/loop-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-agent
 description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, or Cursor bounded implementation in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, 结构化开发, 工作流, 需求实现, PRD 实现.
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现.
 references:
   - path: references/harness-policy.md
     required: true
@@ -25,9 +25,9 @@ Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Re
 
 - 主入口是 **Agent DAG**。
 - 主会话负责编排、审 writeSet、复核验证与 handoff。
-- DAG `pi` executor 默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
+- DAG `pi` executor 是唯一受治理 Agent runtime：默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
 - `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
-- Cursor 是显式启用的可选 bounded write backend；默认 no-Cursor DAG 使用 `executor: "pi"` + `toolProfile: "write"`，必须给出 allowed / forbidden paths。
+- Cursor 仅是显式、手工触发的 `cursor-prompt` one-shot sidecar，不是受治理 DAG/Loop writer；受治理写入固定为 `implement-pi` / `repair-pi`，必须给出 allowed / forbidden paths 与 writeSet。
 - Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
 - 长期结论写回 `docs/exec-plans/`、`docs/reports/`、`docs/progress/` 或 `./skill/`。
 
@@ -68,11 +68,11 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 ## Bounded Write Execution
 
-需要写代码时，默认使用 DAG `pi` executor 的 write tool profile。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
+需要写代码时，默认使用 DAG `pi` executor 的 write tool profile（`implement-pi` / `repair-pi`）。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
 
-Cursor 只作为显式启用的可选 bounded write backend。调用示例与细节见 `references/pi-prompt.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `docs/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
 
-Pi writer prompt 与 Cursor prompt 都必须包含：
+Pi writer prompt（以及可选 sidecar prompt）都必须包含：
 
 - task id
 - exact objective
@@ -82,7 +82,7 @@ Pi writer prompt 与 Cursor prompt 都必须包含：
 - expected verification
 - instruction to preserve unrelated files
 
-bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
+bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的独立复核章节。
 
 ## 进阶主题路由
 
@@ -94,7 +94,8 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 | Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
 | Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
 | 伴生 CLI `agent-worker`（TaskSpec / Task Pool / batch / morning report） | `references/command-reference.md` |
-| Post-Cursor 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
+| Post-writer 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
+| Docs Converge（用户可见变更后的站上/治理文档同步检查表） | `references/docs-converge.md` |
 
 ## Source Layout
 
@@ -121,7 +122,7 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`. Prefer immutable originals under `source/references/` via `import-prd` or Worker `source_docs`; treat `需求.md` as a derived contract.
 3. Agent DAG is the implementation workflow. Review must three-way check references + derived source + implementation when originals exist.
 4. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
-5. Pi writer nodes and optional Cursor write execution must be bounded by explicit allowed / forbidden paths.
+5. Pi writer nodes must be bounded by explicit allowed / forbidden paths and writeSet; Cursor remains `cursor-prompt` sidecar only.
 6. Completed DAG and one-shot run facts are read-only.
 7. Do not write root `artifacts/` from read-only DAG or sidecar steps.
 8. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
@@ -147,3 +148,4 @@ Optional（按需加载）：
 - `references/model-routing.md`
 - `references/multi-worktree.md`
 - `references/post-implementation-and-patterns.md`
+- `references/docs-converge.md` — 用户可见变更后的文档收敛检查表；禁止每次重新规划整站大纲

package/skills/loop-agent/references/command-reference.md

@@ -60,7 +60,7 @@ loop-agent doctor
    ```
 3. **Escape hatch**，仅用于 worktree 隔离委派、executor 调试或 one-shot 诊断：
    ```bash
-   loop-agent delegate <task-id> --executor cursor
+   loop-agent delegate <task-id> --auto-run
    loop-agent harvest <task-id>
    loop-agent cursor-prompt --cwd <repo-root> --file /tmp/bounded-task.md
    loop-agent pi-prompt "Reply with exactly OK."
@@ -122,7 +122,7 @@ loop-agent examples copy <name> --output examples/<name>
 loop-agent new-task <task-id> "Task Title"
 ```
 
-创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。
+创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。`artifacts/` 默认只预种 `修改记录.md` 与 `验证结果.md`（供后续 `promote-run` / `closeout` 使用）；不再预种 L1 的 `分析报告.md`、`实现计划.md`、`复盘报告.md`。
 
 ### 导入原始 PRD（不可变事实源）
 ```bash
@@ -141,7 +141,7 @@ loop-agent instructions promotion --task <task-id> --json
 loop-agent instructions closeout --task <task-id> --json
 ```
 
-`status` 是 agent 行动上下文入口，返回 `artifactPaths`、`runRefs`、`actionContext` 与 `nextActions`。`instructions` 在写入 source、DAG draft、task artifacts、promotion 或 closeout 前返回目标路径、依赖、模板、写策略与完成标准；blocked artifact 会列出 `missingDependencies`。
+`status` 是 agent 行动上下文入口，返回 `artifactPaths`、`runRefs`、`actionContext` 与 `nextActions`。`instructions` 在写入 source、DAG draft、task artifacts、promotion 或 closeout 前返回目标路径、依赖、模板、写策略与完成标准；blocked artifact 会列出 `missingDependencies`。`instructions task-artifacts` 只要求 promote 桥接的 `修改记录.md` / `验证结果.md`，不要求手写分析/计划/复盘三份 L1 报告。
 
 ### Promotion / closeout
 ```bash
@@ -228,9 +228,7 @@ loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --s
 loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
 cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
 (npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # 存在 cursor node 时失败
 loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 执行前若存在 cursor node 则失败
 loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
 loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
@@ -278,6 +276,7 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`docs/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
 - 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
 - task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选 standard / review-gated / supervised template 时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；强制 template family 用 `--profile minimal|standard|reviewed|supervised`。
+- 业务专用 DAG 通过 `task.json.taskKind` 选择，不扩充 governance profile：`frontend-implementation` 选择前端实现模板，`backend-test` 选择需求分析 → 功能用例 → 评审 → pytest 生成/执行 → 复盘的后端测试模板。
 
 ### Saved Dynamic Workflow operator UX
 ```bash
@@ -291,15 +290,9 @@ loop-agent workflow replay <run-id>
 
 `workflow` 是 Dynamic Workflow 的 saved/operator surface。它读取 `WorkflowSpec`，编译为 DAG，再进入同一套 `run-dag` runtime；不会新增 executor 能力或绕过 DAG governance。真实写入任务仍应检查 compiled DAG 的 executor、writeSet、shell gates 和 completed facts 边界。
 
-### Cursor worker lifecycle
-```bash
-loop-agent cursor-worker status   # enabled/running/child/entry path
-loop-agent cursor-worker stop     # SIGTERM worker 并清 parent state
-loop-agent cursor-worker ping     # 启动 worker 并跑短 execute smoke（之后 stop worker）
-```
+### Cursor sidecar
 
-- DAG / `executeCursorTask({ useWorker: true })` 保持长驻 Cursor SDK child，避免 CLI exit hang。
-- Parent RPC timeout（`timeoutMs + 5s`）返回 `details.timeoutKind=rpc`，终止 worker（`SIGTERM`），defer SDK cancel（`cancelDeferred=true`，`cancelAttempted=false`）；下次 execute 启动新 worker。
+`cursor-worker` 已删除。人工干预使用 `cursor-prompt` one-shot sidecar；见 `docs/cursor-prompt-sidecar.md`。
 
 ### 检查 task status
 ```bash
@@ -311,6 +304,9 @@ loop-agent status <task-id>
 loop-agent docs audit
 loop-agent docs archive docs/exec-plans/active/<plan>.md
 loop-agent plan list
+loop-agent plan create <plan-id> "<title>"
+loop-agent plan complete <plan-id> --summary "<summary>"
+loop-agent plan check
 loop-agent handoff check [task-id]
 loop-agent handoff coverage <task-id> [--json|--markdown]
 ```
@@ -318,6 +314,9 @@ loop-agent handoff coverage <task-id> [--json|--markdown]
 - `docs audit`：扫描文档腐化风险，如 active/completed 漂移、失效链接、host-gap closeout
 - `docs archive`：将 active plan 迁入 completed，并自动重写常见 markdown 引用
 - `plan list`：列出当前 active plans 及其解析状态
+- `plan create`：优先从目标项目模板创建 active exec-plan，不存在时回退发布包内置模板；同步 `active/README.md`，拒绝重复 id、不安全文件名，失败时回滚
+- `plan complete`：将 active exec-plan 标记完成、迁入 completed、追加 `--summary` 并同步 active/completed 索引；失败时回滚所有已触碰文件
+- `plan check`：确定性校验 exec-plan 目录与索引之间的 missing、stale、duplicate、status mismatch；发现问题时输出 JSON 并以非零状态失败
 - `handoff check`：检查任务 source / artifacts / auto-commit scope 是否满足交付闭环
 - `handoff coverage`：从 `source/需求.md` 抽取 checklist / numbered / `REQ-*` 项并输出 coverage audit；未覆盖项 exit 1；`explicitly_out_of_scope` 不计为缺口
 
@@ -434,12 +433,12 @@ loop-agent stats
 ### Worktree delegate / harvest（escape hatch）
 
 ```bash
-loop-agent delegate <task-id> [--executor pi|cursor] [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run] [--no-auto-run]
+loop-agent delegate <task-id> [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run]
 loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
 loop-agent worktree create|list|remove ...
 ```
 
-用于 worktree 隔离的 cursor-direct 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-executor-usage.md`。
+用于 worktree 隔离以及可选的 Pi-only DAG 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-prompt-sidecar.md`。
 
 ### One-shot Cursor sidecar（escape hatch）
 ```bash

package/skills/loop-agent/references/docs-converge.md

@@ -0,0 +1,126 @@
+# Docs Converge（文档收敛）
+
+本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
+定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
+
+权威规划：`docs/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
+站与治理双树边界：`website/README.md`。
+
+## 何时触发
+
+在以下任一情况**加载本文件并跑检查表**：
+
+- 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
+- 新增 / 修改 / 删除 CLI 命令或关键 flags。
+- runtime / 架构边界变更（`docs/architecture/*`、executor 角色、Worker 边界）。
+- active plan 创建、blocked、完成或归档。
+- 准备发布或写 `CHANGELOG.md` 版本条目。
+- 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
+- handoff 前需要声明「本轮是否更新了站上文档」。
+
+**不要**在无关的纯内部重构（无用户可见行为、无命令面变化）上强制大改站上正文；此时 handoff 写明豁免理由即可。
+
+## 受众矩阵
+
+| 受众 | 主要入口 | 权威细节 |
+| --- | --- | --- |
+| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `docs/architecture/*`、active plans |
+| 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
+| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `docs/`、`skills/`、`scripts/check-*.sh` |
+
+## 页面清单（站上活文档）
+
+| 页面 | 职责 |
+| --- | --- |
+| `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
+| `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
+| `website/docs/overview/architecture.md` | 架构导读；链到 `docs/architecture/` |
+| `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
+| `website/docs/quick-start/*` | 安装 / init / first-run |
+| `website/docs/guides/*` | 主路径操作说明 |
+| `website/docs/reference/cli.md` | 用户向 CLI 参考 |
+| `website/docs/reference/config.md` | 配置参考 |
+| `website/docs/changelog.md` | 读者摘要；完整版本以根 `CHANGELOG.md` 为准 |
+
+治理全文、exec-plans、reports **不**搬进 Docusaurus。
+
+## 变更 → 文档检查表
+
+按本轮实际 diff 勾选（有则必须处理，无则跳过并记豁免）：
+
+| 若变更了… | 必须检查 / 更新 |
+| --- | --- |
+| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
+| 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
+| runtime / 边界 | 根 `docs/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
+| 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
+| active plan 状态 | `overview/roadmap.md` 短索引 + `docs/exec-plans/active/README.md` |
+| 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
+| skill / init 投影 | `docs/init-surface.manifest.json`、相关测试、必要时 `docs/skills/*` |
+
+跨树链接规则：
+
+- 站内页面用 Docusaurus 相对文档链接。
+- 链到根目录 `docs/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
+  `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
+  正文同时写出 repo-relative path；禁止伪造站内 `/docs/architecture/...` 作为根目录文档路由。
+
+## 执行步骤（最小闭环）
+
+1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
+2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
+3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `docs/`。
+4. **验证**（见下节）。
+5. **Handoff** 二选一：
+   - 已更新：列出改动页面与验证命令结果。
+   - 无需站上更新：写明「本轮无需站上更新，原因：…」。
+
+## 验证命令
+
+站上正文、侧栏或 `docusaurus.config.ts` 有改动时：
+
+```bash
+npm run docs:build
+```
+
+涉及治理文档、脚本、skill、init surface 时再跑：
+
+```bash
+bash scripts/check-repo.sh
+# 或定向：
+bash scripts/check-skill-entry.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-init-surface.sh
+node bin/loop-agent.js docs audit --repo-root .
+```
+
+skill / package 投影相关：
+
+```bash
+npx vitest run test/init-command.test.ts test/package-surface.test.ts
+```
+
+## 禁止事项
+
+- 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
+- 把 `docs/design/`、exec-plans、reports 全文复制进 `website/docs/`。
+- 在站上建立第二套与 `docs/architecture/*` 冲突的架构真源。
+- 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
+- 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
+- 新增独立公共 skill 目录承载本检查表（应留在 `skills/loop-agent/references/`）。
+
+## 与现有能力的关系
+
+| 能力 | 关系 |
+| --- | --- |
+| `loop-agent docs audit` | L0 腐化检查（断链、计划状态等）；**不**替代本表内容审计 |
+| `npm run docs:build` | 站上改动硬门禁（含 Markdown 断链 fail-fast） |
+| `grill-with-docs` | ADR / 术语；不替代本 reference |
+| 历史 2026-07-05 docs governance dogfood | 仅经验输入；新 workflow 必须 Pi-only，不复用已退役原生 Cursor DAG |
+
+## 快速自检（handoff 前 30 秒）
+
+- [ ] 用户可见变更是否对照检查表处理或已豁免？
+- [ ] intro 是否仍是概念地图（而非能力 bullet 堆砌）？
+- [ ] roadmap 是否只含当前有效 active 项？
+- [ ] 需要时 `docs:build` / `check-repo` 是否有新鲜输出？

package/skills/loop-agent/references/harness-policy.md

@@ -8,7 +8,7 @@
 - 历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow 已移除。不要将其作为 fallback path 呈现。
 - **Long-running `loop`** 是 Agent DAG 之上的 outer state/evidence layer。它记录 rounds、context compression、signals、canonical refs；不得替代 complex work 的 DAG writeSet review、Decision Gate 或 shell verification。
 - **Main session** 负责 orchestrate：选一个 work chunk、准备 source materials、review DAG/writeSet、monitor failures、跑 final verification、hand off。
-- **Executors** 实现 bounded work：Pi 在 DAG nodes 做 read-only planning/review/diagnosis，并在节点声明 `toolProfile: "write"` 时做 bounded implementation/repair；Cursor 是显式启用的可选 bounded writer；shell 产出 deterministic verification facts。
+- **Executors** 实现 bounded work：Pi 是唯一受治理 Agent runtime（read-only planning/review/diagnosis，以及 `toolProfile: "write"` 的 bounded implementation/repair）；shell 产出 deterministic verification facts；`cursor-prompt` 仅是 one-shot sidecar。
 - **Shell verification 是 completion fact source**。LLM review 或 advisory output 不能替代 command exit codes 与 archived evidence。
 
 ## Command surface tiers
@@ -18,7 +18,7 @@
 | Primary | Normal autonomous implementation | `new-task` -> `dag run-task --profile auto` -> `dag validate --strict-models --strict-governance` -> `run-dag` |
 | Operator | Diagnose, recover, close out, inspect facts | `status`, `instructions`, `dag status`, `dag doctor`, `dag report`, `dag closeout-draft`, `dag reconcile-tasks`, `dag final-verification`, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark` |
 | Compatibility | Legacy task metadata and feature-study helpers | `goal`, `reference`, `study` |
-| Escape hatch | Isolated delegation, one-shot diagnosis or bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt`, `cursor-worker` |
+| Escape hatch | Isolated delegation, one-shot diagnosis or bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt` |
 | Experimental | Long-running outer task state | `loop init|status|run|record-round|add-signal|closeout` |
 
 Prompt templates、README snippets、task instructions 应优先呈现 Primary + Operator。Compatibility 与 escape-hatch commands 仍可用，但须携带其 downgrade/fallback 含义。
@@ -130,7 +130,7 @@ loop-agent loop run <task-id> --action dag
 loop-agent loop run <task-id> --action dag --execute
 loop-agent loop run <task-id> --action shell-verify --command "<repo-check>"
 loop-agent loop run <task-id> --action pi-review
-loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
+loop-agent loop run <task-id> --auto --max-rounds 3
 loop-agent loop closeout <task-id>
 ```
 
@@ -138,11 +138,11 @@ Loop action rules：
 
 - `shell-verify` 是 deterministic；exit code 决定 verification record。
 - `pi-review` 是 read-only；tools 限于 `read,grep,find,ls`，output 为 structured advisory evidence。Structured JSON 须含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`；`recommendedAction`  exactly 为 `implement_fix|replan|pause|done`。
-- `cursor-fix` 是 bounded write；须读 task `allowedPaths` / `forbiddenPaths`，reject empty `allowedPaths`、allowed/forbidden overlap，preserve unrelated files，且须 follow shell verification 或 review。
-- 对 `task.json.complexity = medium | large`，`cursor-fix`  additionally 需要：
+- 自动写入只能通过 Pi-only Agent DAG execute；须读 task `allowedPaths` / `forbiddenPaths`，审查 writer `writeSet`，并 follow shell verification 或 review。
+- 对 `task.json.complexity = medium | large`，自动 DAG execute  additionally 需要：
   - previous loop `dag` round，或
   - explicit `task.json.dagFallbackReason` 说明为何不能用 DAG。
-- `loop run --auto` 默认不 write。Auto `cursor-fix` 需要 `task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal 或 `--allow-cursor-fix`；write guards 仍 fail closed 并 pause。
+- `loop run --auto` 默认不 write。Auto DAG execute 需要 `task.json.loopAutoExecutionPolicy="enabled"`，或 `loopAutoExecutionPolicy="approval-required"` 加 pending approval signal；旧 `loopAutoWritePolicy` fail-fast；write guards 仍 fail closed 并 pause。
 - `loop closeout` 须报告 workflow path：`dag`、`explicit-fallback`、`missing-dag-evidence` 或 `micro-or-small`。
 - 无 DAG evidence 且无 `dagFallbackReason` 的 medium/large closeout 须将其列为 remaining risk。
 - `record-round --decision complete` 仅是 loop-state candidate；completion 仍须 shell verification、review verdict、success-criteria coverage。
@@ -220,7 +220,7 @@ Sidecar output 为 advisory。若须成为 task evidence，通过 loop-agent run
 - `harness.json.models.<step>` 下 historical step models 是 legacy metadata，不是新 DAG work 的 routing。
 - `pi-prompt` / `cursor-prompt` models 来自 CLI flags 或 runtime defaults，须 per intervention 选择。
 - Pi DAG nodes 默认 read-only planning/review/diagnosis；声明 `toolProfile: "write"` 时是 bounded writers，须有 explicit write scope。
-- Cursor nodes 是显式启用的可选 bounded writers，须有 explicit write scope。
+- 受治理 writer 固定为 `implement-pi` / `repair-pi`，须有 explicit write scope；`cursor-prompt` 不进入 DAG schema。
 - Shell nodes 产出 deterministic verification facts 与 gates。
 
 ## Artifacts and facts boundary

package/skills/loop-agent/references/hybrid-dag.md

@@ -1,28 +1,30 @@
 # Agent DAG Hybrid Workflow（`run-dag` / `dag init-hybrid`）
 
-创建或执行 loop-agent 工作的首选 Agent DAG path 时使用本文：Level 2 Agent DAG orchestration、Pi read-only + Pi `toolProfile: "write"` bounded execution、optional Cursor backend、write policy、DAG template、task-to-DAG 生成，或基于 governance-profile 的 template 选择。
+创建或执行 loop-agent 工作的首选 Agent DAG path 时使用本文：Level 2 Agent DAG orchestration、Pi read-only + Pi `toolProfile: "write"` bounded execution、Pi-only writers、write policy、DAG template、task-to-DAG 生成，或基于 governance-profile 的 template 选择。
 
 ### DAG workflow 优先级
 
 `harness.json.workflowPolicy` 现声明 Agent DAG 为首选 implementation workflow：
 
 - `defaultImplementationWorkflow=agent-dag`
-- `dag.defaultEntry=dag run-task`
-- `dag.outputLanguage=zh-CN`；未配置时也默认中文，显式设为 `en` 可切换英文
-- `dag.profileRouting`：`minimal|standard -> standard-dag`，`reviewed -> review-gated-dag`，`supervised -> supervised-implementation`
+- `dag.defaultEntry=dag run-task`
+- `dag.outputLanguage=zh-CN`；未配置时也默认中文，显式设为 `en` 可切换英文
+- `dag.profileRouting`：`minimal|standard -> standard-dag`，`reviewed -> review-gated-dag`，`supervised -> supervised-implementation`
 - `humanGatePolicy.defaultMode=record-only`；需求不清、架构/公共契约风险、凭据/费用/部署风险、重复 gate failure 或高风险决策时升级人工介入
 
-此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
+此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
+
+`task.json.taskKind` 负责选择业务专用模板，不扩充 governance profile：`frontend-implementation` 选择前端实现 DAG，`backend-test` 选择后端测试 DAG。后端测试链为 `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`，治理等级仍由既有 `minimal|standard|reviewed|supervised` 规则推断。
 
 ### DAG workflow 层级
 
 | 优先级 | 入口 | 使用场景 |
 |-------|-------|----------|
 | **Primary / Level 3** | `dag run-task --profile auto` / `dag init-hybrid`（已实现） | 从 task `source/` 自动生成 hybrid DAG；`--profile auto` 路由 standard / review-gated / supervised template；无 profile `run-task` 默认为 standard-compatible generate+validate only |
-| **Primary / Level 2** | `run-dag --dag <path>` | 跨 Cursor + Pi + shell executor 执行 Agent DAG orchestration |
+| **Primary / Level 2** | `run-dag --dag <path>` | 跨 Pi + shell + static executor 执行 Agent DAG orchestration |
 历史顺序式 `run analyze|plan|implement|verify|auto|loop|continue` 已移除。trivial one-line 修正时，记录的 main-session surgical patch 仍可能比建 DAG 更省，但它不是第二套 workflow runtime。
 
-**心智模型**：`run-dag` 是 `.` 内自编的 Agent DAG orchestration；Cursor SDK 仅是 `executor: "cursor"` node 的 leaf executor。Cookbook 式 Cursor DAG 示例同样是基于 Cursor SDK local subagent 的 custom DAG runner，不是 Cursor 原生 DAG API。仅可选地借鉴其 observer/streaming/cancel 模式作为 derived feature；不要替换本 repo 的 hybrid schema、`executorModels`、Pi/shell/static executor 或 `.harness/dag-runs` facts。
+**心智模型**：`run-dag` 是 loop-agent 内自编的 Agent DAG orchestration；受治理 Agent leaf executor 只有 Pi。`cursor-prompt` 是独立 sidecar，不是 DAG node executor。不要把 Cursor 重新引入 hybrid schema / `executorModels` / writer 选择。
 
 ### Level 2 Agent DAG hybrid（`run-dag`）
 
@@ -31,10 +33,8 @@ cp examples/hybrid-loop-agent-dag.json <temp-dir>/hybrid-dag.json
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation + ranks；无 dag-runs 副作用
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时也失败
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning（如 read-only artifact drift）时失败
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # offline/CI/no-key 显式 no-Cursor；存在 cursor node 时失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行（若包含 cursor node 则需 CURSOR_API_KEY）
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 存在 cursor node 时执行前失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas（无需 CURSOR_API_KEY）
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Pi/shell/static DAG
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas
 ```
 
 `<temp-dir>` 表示平台原生临时目录；实际命令中 macOS 与 Windows 都使用本机路径。`/` 只作为 repo refs、JSON/Markdown evidence refs 和 glob 约定的稳定分隔符。
@@ -44,7 +44,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 **v2 字段**（均可选；缺失时行为同 v1）：
 
 - 顶层：`objective`、`successCriteria`、`globalConstraints`、`defaults`、`skillsByRole`、`executorModels`
-- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`cursor` | `pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
+- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`；安全只读 Pi 节点可选声明 `retryPolicy`（生成器自动注入默认值）
 
 **Model 生成 DAG 的 template 卫生**：
 
@@ -54,14 +54,14 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - 输出独立时优先 same-rank parallel read-only scout（`scout-src`、`scout-tests` 等），而非 serial scout chain。
 - 仅当 child 真正需要 upstream output 时加 `depends_on`；review 时质疑 single-chain topology。
 - `exclusive` implementer node 需 narrow、disjoint 的 `writeSet` path；勿用 `**` 或 repo root。
-- 默认 no-Cursor DAG 使用 `pi` read-only scouts/reviewers 与 `toolProfile: "write"` exclusive implementer；Cursor 是显式启用的可选 scout / writer backend。
+- 固定 Pi-only DAG：`pi` read-only scouts/reviewers 与 `toolProfile: "write"` exclusive implementer（`implement-pi` / `repair-pi`）。
 - model routing 用 `executorModels`；勿用 `defaults.model` 或 legacy 顶层 `models`。
 
 **运维 warning**：
 
-- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。no-Cursor 环境用 `dag validate --dag <path> --forbid-executor cursor` 或 `run-dag --no-cursor` 捕获显式 Cursor 节点；默认生成 DAG 应使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
+- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
 - **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 强制对应 template family（当前 policy 下 minimal/standard 路由到 `standard-dag`），高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
-- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels` 覆盖 `cursor` / `pi` 的 model 名；不选 provider。默认 routing：Cursor 各 complexity 用 `composer-2.5`；Pi read-only 与 Pi write profile 共用 LOW=`wizard-local/gpt-5.3-codex-spark`、MED=`wizard-local/glm-5.2`、HIGH=`wizard-local/gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
+- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖 model 名；不选 provider。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
 - **Active visibility**：真实 `run-dag` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
 - **可选 Canvas**：传 `--canvas-path <abs-path>` 或 `--canvas <name>` 输出 derived `.canvas.tsx` live view。省略 flag 行为不变。`--init-only` + Canvas 无需 `CURSOR_API_KEY`。
 
@@ -77,7 +77,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
 - **勿宣称 live smoke 已通过**，除非真实 `run-dag` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
 
-可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
+可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/backend-test-dag.json`（后端测试专用模板）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
 
 ### Supervised implementation flow（减少 main-session intervention）
 
@@ -102,16 +102,20 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 | `soft-verify-shell` | supervision 前归档 focused test exit code |
 | `process-supervisor-pi` | read-only audit coverage、boundary drift、verify gap、repair scope；应 prominently 输出 `VERDICT: pass` 或 `VERDICT: request-revision` |
 | `process-gate-shell` | supervisor node JSON 上 runtime `shell.verdictGate`（仅 `pass` 或 `request-revision`） |
-| `repair-pi` / optional `repair-cursor` | supervisor 请求 revision 时在 repair `writeSet` 内 bounded exclusive fix |
+| `repair-pi` | supervisor 请求 revision 时在 repair `writeSet` 内 bounded exclusive fix |
 | `hard-verify-shell` | lint/typecheck + `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 check-repo.sh` fact |
 | `authority-surface-audit-pi` + `authority-surface-gate-shell` | 可选 permission/state/tool-exposure audit；仅 authority signal 或显式 `authority-surface-audit` marker 时插入；gate 仅接受 `VERDICT: pass` |
 | `review-pi` + `review-gate-shell` | Critical/Important → `request-revision`；node JSON 上 `shell.verdictGate` block，除非 extracted verdict 行为 `VERDICT: pass` |
 
 **Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
 
+**Repair artifact gate contract（`shell.repairArtifactGate`）**：声明 `fromNodeId`（supervisor artifact 节点）与 `repairNodeId`（承接修订的 Pi 修复节点）。runner **不再**按节点名（历史 `repair-cursor` / `repair-pi`）猜测 repair 节点：显式 `repairNodeId` 必须存在、直接 `depends_on` gate、且是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`+`writeSet` 非空且 `writeSet` 不与 `forbiddenPaths` 冲突）。新生成的 supervised DAG 总是写入 `repairNodeId`；旧 DAG 缺失时只在能唯一、安全地推导出下游 Pi writer 时兼容，零个或多个候选、或候选不满足契约都在执行前 fail closed。validation 覆盖存在性、直接下游、writer 属性与路径边界。
+
+**Runtime contract 与 controller identity**：新生成的 DagSpec 使用 `version: 3`，并必须携带 `runtimeContract`（`schemaVersion` / `agentRuntime: "pi-only"` / `repairWriterProtocol: "explicit-node-v1"` / 可选 `minimumControllerVersion`）。v3 是旧 controller 无法忽略的解析边界；capability 与最低版本是新 controller 的执行前兼容门。`init-hybrid` 不硬编码 `minimumControllerVersion`，手写 spec 可按需 pin。每个新 run 必须解析并冻结 controller identity（package version、binary SHA-256、portable fingerprint）到 `controller-identity.json`；解析失败不创建 run。`dag report` 展示 identity 与 runtime-contract compatibility，resume 对漂移、篡改或 legacy-unpinned run 全部 fail closed；legacy run 仍可只读报告或显式 reconcile。
+
 Prompt invariant：`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（启用时）。测试：`npx vitest run test/dag-supervised-template.test.ts test/authority-surface.test.ts`。完整叙述：`docs/agent-dag-runner.md` §「Why main-session interventions happened」。
 
-**未实现**：`executor: supervisor`、automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。
+**未实现**：`executor: supervisor`、whole-run automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。注：有界只读 Pi 节点重试已实现（见下「只读 Pi 节点安全重试」）。
 
 ### Level 3 task-to-DAG（`dag init-hybrid` / `dag run-task`）
 
@@ -124,7 +128,6 @@ loop-agent dag run-task <task-id> --profile standard
 loop-agent dag run-task <task-id> --profile reviewed                            # 强制 review-gated DAG
 loop-agent dag run-task <task-id> --profile supervised                          # 强制 supervised implementation DAG
 loop-agent dag run-task <task-id> --strict-models                              # 非 canonical executorModels 时失败
-loop-agent dag run-task <task-id> --no-cursor                                  # 显式 no-Cursor 校验；generated cursor node 时失败
 loop-agent dag run-task <task-id> --execute --cwd <repo-root>                        # 要求 narrowed implement writeSet
 loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>                        # active snapshot 于 .harness/dag-runs/active/
 loop-agent dag run-task <task-id> --init-only --cwd <repo-root>                      # pending active snapshot，不执行 node
@@ -182,6 +185,19 @@ loop-agent dag resume --run-id <run-id>   # approve 后继续
 
 **In-flight DAG run 期间的 governance**：live run 内 shell verify node 须用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`。run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
 
+### 只读 Pi 节点安全重试（read-only retry）
+
+planner/scout/reviewer/verifier/closeout 角色的安全只读 Pi 节点可声明 `retryPolicy`，在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成模板自动注入默认策略（总尝试 3 次，手工配置最多 5 次，指数退避，单次等待上限 30s）。supervisor 与 implementer 明确不重试。
+
+- 仅重试原始分类：`timeout`、`network`、`rate-limit`、`unavailable`。`quota` **不**是 rate limit，不重试；`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败同样不重试。
+- 资格由确定性 helper 判断，executor 内不硬编码循环；仅 `writePolicy=read-only|none`（或 Pi 默认只读）的上述角色可用。supervisor / implementer / writer / docs-only / dynamic / shell / static / decision-gate 节点声明 `retryPolicy` 会在 DAG validation 阶段失败。
+- 每次 attempt 写入独立不可变证据 `<node-id>/attempt-<n>.json`（run-relative path），最终 node record `attempts` 字段引用完整历史；后一次成功不覆盖前一次失败证据。
+- 重试复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入；退避等待刷新 `lastActivityAt` 避免误判 node-quiet。
+- 节点终态聚合全部 attempts 的耗时、Token 与事件数；当前 backoff 等待会占用该节点的并发槽。
+- 未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行，不新增 attempt artifact）。
+
+实现：`src/workflows/dag/retry-policy.ts`、`node-execution.ts`、`validate.ts`。测试：`npx vitest run test/dag-node-retry.test.ts test/dag-validate.test.ts test/dag-init-hybrid.test.ts`。
+
 ### Evidence summary guidance（practice convention — 非 runtime）
 
 review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-summary-shell** 作为 authoring pattern。**不是** runtime executor、schema field 或 parser。
@@ -212,6 +228,6 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | 10 | writeSet planning | scout 应列出链接的 `./skill/references/**` 为 **writeSet expansion candidates**（P2：遗漏链接 skill ref 迫使 main-session patch） |
 | 11 | Evidence summary | `evidence-summary-shell` / leading `EVIDENCE:` 行是 **practice convention**，非 runtime executor、schema field 或 parser |
 | 12 | Featureization | 除非 repeated real-run failure 证明 checklist guidance 不够，勿加 runtime/schema/validator/CLI/executor feature |
-| 13 | writeSet / writer backend | `exclusive` node 用 narrow、disjoint path；无 `**`；默认用 Pi write profile，仅在显式启用且 task-fit 时用 Cursor |
+| 13 | writeSet / writer backend | `exclusive` node 用 narrow、disjoint path；无 `**`；固定用 Pi write profile |
 | 14 | Placeholders | 执行前将 `REPLACE/WITH/...` 换为具体 path |
 | 15 | Governance | in-flight shell：`HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`；archive 后：裸 `bash scripts/check-repo.sh` |

package/skills/loop-agent/references/long-running-loop.md

@@ -9,11 +9,10 @@ loop-agent loop init <task-id>
 loop-agent loop status <task-id>
 loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
 loop-agent loop run <task-id> --action pi-review
-loop-agent loop run <task-id> --action cursor-fix --model composer-2.5
 loop-agent loop run <task-id> --action dag
 loop-agent loop run <task-id> --action dag --execute
 loop-agent loop run <task-id> --auto --max-rounds 3
-loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
+loop-agent loop run <task-id> --auto --max-rounds 3
 loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
 loop-agent loop closeout <task-id>
 loop-agent loop record-round <task-id> \
@@ -36,15 +35,14 @@ loop-agent loop record-round <task-id> \
 
 - `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
 - `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
-- `loop run --action cursor-fix` 必须读取 task `allowedPaths` / `forbiddenPaths`，拒绝空 allowedPaths 或 allowed/forbidden overlap；对 `complexity=medium|large` 的任务，还必须已有 loop `dag` round 证据，或在 `task.json.dagFallbackReason` 中写明 DAG runtime fallback 原因。调用现有 Cursor bounded executor，并把 one-shot evidence 归档到 `.harness/runs/completed|failed/`。
-- `cursor-fix` 只表示 bounded write round 已执行；它不会把 loop 标记 complete，下一步必须进入 `shell-verify` 或 review。
+- 自动写入只能通过 `loop run --action dag --execute` / auto DAG execute；须读取 task `allowedPaths` / `forbiddenPaths` 并审查 writer writeSet。
 - `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
 - `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
 
 ## Auto mode 与写入边界
 
-- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block，不自动触发 Cursor 写入。
-- 自动 `cursor-fix` 必须显式 opt-in：`task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal / `--allow-cursor-fix`。即使 opt-in，也必须通过 `allowedPaths`/`forbiddenPaths`/DAG evidence guard；guard 失败会 pause，不会绕过写入边界。
+- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block。
+- 自动 DAG execute 必须显式 opt-in：`task.json.loopAutoExecutionPolicy="enabled"`，或 `approval-required` 加 pending approval；旧 `loopAutoWritePolicy` fail-fast。
 - auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
 
 ## Signals