@tea-agent/loop-agent 0.13.0 → 0.14.0

package/docs/README.md

@@ -1,107 +1,108 @@
-# 文档索引
-
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
-
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
-
-**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
-
-站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
-
-## 核心文档
-
-- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
-- `development-principles.md` — 仓库开发原则
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
-- `architecture/README.md` — 架构文档目录索引与阅读路径
-- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
-- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
-- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
-- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
-- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
-- `feature-workflow.md` — 有边界的功能工作流
-- `verification-matrix.md` — 验证命令选择
-- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
-- `loop-agent-harness.md` — runtime 与 command surface 概览
-- `agent-dag-runner.md` — Agent DAG runner 指南
-- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
-- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
-- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
-- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
-
-## 近期完成合同（入口）
-
-完整列表见 `exec-plans/completed/README.md`。近期高频入口：
-
-- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
-- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
-- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
-- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
-- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
-
-## 设计思想来源
-
-- `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
-
-## 方法论
-
-- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
-- `harness-methodology-verification.md` — 完成声明前的验证纪律
-- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
-
-## 产物目录
-
-- `design/README.md` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
-- `exec-plans/active/README.md` — 进行中的执行计划
-- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
-- `progress/README.md` — 进度交接日志（全量）
-- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
-- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
-- `skills/README.md` — repo-local skill registry and vetting notes
-- `templates/` — 可复用的规划、报告与 DAG 模板
-
-## 仓库 Skills
-
-- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
-- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
-- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
-
-## 模板
-
-- `templates/project-start-checklist.md` — 开工前检查清单
-- `templates/feature-spec.md` — 有边界的功能规格
-- `templates/sprint-contract.md` — 实现契约与验收标准
-- `templates/exec-plan.md` — 非平凡工作的执行计划
-- `templates/progress-log.md` — 进度与交接日志
-- `templates/qa-report.md` — 验证与 QA 证据
-- `templates/worker-dogfood-setup.md` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
-- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
-- `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
-- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
-- `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
-- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+# 文档索引
+
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+
+**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
+
+站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
+
+## 核心文档
+
+- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
+- `development-principles.md` — 仓库开发原则
+- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
+- `architecture/README.md` — 架构文档目录索引与阅读路径
+- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
+- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
+- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
+- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
+- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
+- `feature-workflow.md` — 有边界的功能工作流
+- `verification-matrix.md` — 验证命令选择
+- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
+- `loop-agent-harness.md` — runtime 与 command surface 概览
+- `agent-dag-runner.md` — Agent DAG runner 指南
+- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
+- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
+- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
+
+## 近期完成合同（入口）
+
+完整列表见 `exec-plans/completed/README.md`。近期高频入口：
+
+- `exec-plans/completed/2026-07-18-observe-ops-surface-and-rich-timeline.md` — Observe 运营面/执行面重排、检查器半屏与富执行过程
+- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
+- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
+- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
+- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
+- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
+
+## 设计思想来源
+
+- `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
+
+## 方法论
+
+- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
+- `harness-methodology-verification.md` — 完成声明前的验证纪律
+- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
+
+## 产物目录
+
+- `design/README.md` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
+- `exec-plans/active/README.md` — 进行中的执行计划
+- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
+- `progress/README.md` — 进度交接日志（全量）
+- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
+- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
+- `skills/README.md` — repo-local skill registry and vetting notes
+- `templates/` — 可复用的规划、报告与 DAG 模板
+
+## 仓库 Skills
+
+- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
+- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
+
+## 模板
+
+- `templates/project-start-checklist.md` — 开工前检查清单
+- `templates/feature-spec.md` — 有边界的功能规格
+- `templates/sprint-contract.md` — 实现契约与验收标准
+- `templates/exec-plan.md` — 非平凡工作的执行计划
+- `templates/progress-log.md` — 进度与交接日志
+- `templates/qa-report.md` — 验证与 QA 证据
+- `templates/worker-dogfood-setup.md` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
+- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
+- `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
+- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
+- `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
+- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
 - `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
 - `templates/branch-merge-report.md` — 跨分支合并的功能保留、冲突解析、init/update 与 package surface 审计模板
 - `templates/adr.md` — 架构决策记录（ADR）
-
-## 维护
-
-文档变更后运行：
-
-```bash
-node bin/loop-agent.js docs audit --repo-root .
-bash scripts/check-doc-index.sh
-bash scripts/check-doc-links.sh
-bash scripts/check-repo.sh
-```
-
-涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
-
-Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-完整本地门禁：
-
-```bash
-bash scripts/ci.sh
-```
+
+## 维护
+
+文档变更后运行：
+
+```bash
+node bin/loop-agent.js docs audit --repo-root .
+bash scripts/check-doc-index.sh
+bash scripts/check-doc-links.sh
+bash scripts/check-repo.sh
+```
+
+涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+完整本地门禁：
+
+```bash
+bash scripts/ci.sh
+```

package/docs/agent-dag-recovery-playbook.md

@@ -1,195 +1,195 @@
-# Agent DAG Recovery Playbook（恢复手册）
-
-> **关联**：[`agent-dag-runner.md`](agent-dag-runner.md)（CLI 与 run 语义）· [`templates/agent-dag-decision-gate.prompt.md`](templates/agent-dag-decision-gate.prompt.md)（Decision Gate 消费 recovery 证据）
-
-## 定位
-
-Agent DAG **recovery planning 是只读、派生、advisory** 的。`dag report` 与 `buildDagDecisionGateEvidence()` 从 `.harness/dag-runs/` 的 canonical facts 聚合 `normalizedFailureCategory` → `recoveryRecommendation`，供人工或 Decision Gate prompt 消费。
-
-中断后不要从上游摘要手工生成 impl-only DAG。先修复 `.harness/tasks/<task-id>/source/` 或计划，再对同一 task 重新执行 `dag run-task`、严格 `dag validate` 和新的 `run-dag`。新生成的完整 DAG 会重新冻结 `sourceBinding` 并经过 contract/scout/plan/gate；v3 孤立 writer 如果既无来源绑定、也无只读 planner 上游，会被 strict governance 拒绝。完整规则见 [`design/dag-source-binding-and-recovery.md`](design/dag-source-binding-and-recovery.md)。
-
-Production Readiness v0.1 在 normalized DAG category 之上增加 product-line routing。Report 与 doctor 输出应保留 raw DAG fact 并派生，不重写已完成 facts：
-
-```text
-raw_failure_category
-dag_normalized_failure_category
-product_line_failure_category
-recommended_follow_up
-```
-
-Product-line taxonomy 定义见 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
-
-### 前端设计门禁专用恢复路径
-
-前端 DAG 的 design gate shell 失败（`frontend-first-design-gate-shell`、`frontend-final-design-gate-shell`、`frontend-design-gate-shell`）**不路由为 `ProductBug` / `dev-fix`**。此类失败固定路由为：
-
-- `productLineFailureCategory`: `ContractMismatch`
-- `recommendedFollowUp`: `frontend-plan-revision-and-rerun`
-
-恢复动作由 `planDagRecovery` 根据实际的 `normalizedFailureCategory` 和 run status 决定（通常为 `rerun-after-fix` 或 `manual-review`），但 product-line 维度的分类确保 Task Pool 和 morning report 不会将其混入普通 bug backlog。
-
-**非目标（本 playbook 不覆盖、runner 不实现）：**
-
-- 自动 retry / resume 节点执行
-- 修改 `completed/` 或 `paused/` 下的历史 run facts
-- 把 `autoRetryEligible` 当作 runtime 触发器
-- 仅凭 recovery 派生字段自动 approve Decision Gate
-
-## 快速命令
-
-```bash
-cd .
-
-# 全局 runtime 健康（active/paused/completed 摘要 + healthIssues；advisoryOnly）
-npm run dev -- dag doctor
-
-# 单 run 生命周期（approvalFlow、hasHumanApproval、nextRecommendedAction）
-npm run dev -- dag status --run-id <run-id>
-
-# 聚焦最新 paused run（--paused-latest ≡ --lifecycle paused --latest）
-npm run dev -- dag report --paused-latest [--json|--markdown]
-
-# 默认 compact Markdown 表格
-npm run dev -- dag report --run-id <run-id>
-
-# 机器可读 JSON（含 primaryFailure / primaryRecovery / downstreamSkippedNodes）
-npm run dev -- dag report --run-id <run-id> --json
-
-# 人类交接 Recovery Plan（四段结构化 Markdown）
-npm run dev -- dag report --run-id <run-id> --markdown
-
-# 过滤器
-npm run dev -- dag report --failed-only                              # 仅失败/需恢复
-npm run dev -- dag report --latest --failed-only                    # 最新一条需恢复 run
-npm run dev -- dag report --action retry-node                       # 按 primaryRecovery.action 筛选
-npm run dev -- dag report --lifecycle paused --action resume-or-reject
-
-# Decision Gate envelope dry-run（不 resume/retry；validate 无效时 exit 1）
-npm run dev -- dag decision inspect --run-id <run-id> [--node-id <node-id>]
-npm run dev -- dag decision validate --run-id <run-id> [--node-id <node-id>]
-```
-
-### Paused run operator 路径
-
-1. `dag report --paused-latest --json` 或 `dag doctor` — 定位最新 paused run 与 `primaryRecovery`
-2. `dag status --run-id <id>` — 读 `approvalFlow`、`escalationArtifactPath`、`pendingNodes`
-3. （可选）`dag decision validate --run-id <id>` — envelope preflight
-4. `dag approve --run-id <id> --option <option-id>` → `dag resume --run-id <id>`；或 `dag reject --run-id <id> --reason "..."`
-
-精确 approval 顺序见 [`agent-dag-runner.md`](agent-dag-runner.md) §Paused lifecycle。
-
-Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-decision-evidence.ts`）从 `DagRunReportEntry` 生成 prompt-friendly 摘要，字段与 JSON report 对齐，**不**写回 run state。
-
-## `dag report --json` schema 锁定
-
-- **Schema 文件**：`ai_workspace/loop-agent/templates/agent-dag-report.schema.json`
-- **Envelope**：`{ schemaVersion: 1, runs: DagRunReportEntry[] }`
-- **稳定消费字段**（Decision Gate / tooling 应依赖）：`primaryFailure`、`primaryRecovery`、`downstreamSkippedNodes`、`recoveryRecommendation`、`normalizedFailureCategory`；node 级 `decisionEnvelope`、`artifacts`；paused 级 `pausedByNodeId`、`pauseReason`
-- **测试**：`./test/dag-report.test.ts` §`dag report JSON schema contract` 对 fixture run 做 schema 校验
-- **变更策略**：breaking 字段变更须 bump `schemaVersion` 并同步 schema 文件与测试
-
-## Recovery Action 枚举
-
-| Action | 含义 | 典型触发 |
-|--------|------|----------|
-| `none` | 无需恢复 | 成功完成 |
-| `monitor` | 进行中，等待结束 | `PENDING` / `RUNNING` |
-| `retry-node` | 修复瞬态条件后可重跑节点 | timeout；executor 瞬态（network/quota/rate-limit/unavailable） |
-| `rerun-after-fix` | 先修根因再重跑 | auth、validation、shell-command、static-error、非瞬态 executor |
-| `resume-or-reject` | 人工审批后继续或拒绝 | paused + decision-envelope / human-required |
-| `manual-review` | 人工审查后再定路径 | write-guard、human-rejected、unknown、非 paused 的 decision-envelope |
-| `inspect-upstream` | 先查上游失败 | SKIPPED 下游节点 |
-| `unknown` | 未映射类别（不应出现在正常派生路径） | 内部兜底 |
-
-## Product-Line Routing v0.1
-
-| Product-line category | Default follow-up |
-|---|---|
-| `SpecUnclear` | `spec-clarification` |
-| `ContractMismatch` | `architecture-contract-fix` |
-| `ProductBug` | `dev-fix` |
-| `TestBug` | `qa-fix-test` |
-| `EnvFailure` | `env-fix` 或 retry verify |
-| `FlakyTest` | `flaky-test-analysis` |
-| `RiskyChange` | `human-review` / `architecture-review` |
-| `DependencyFailure` | unblock dependency |
-| `NeedsHuman` | `human-review` |
-| `Unknown` | human triage |
-
-## 类别 → 动作 → operator 指引
-
-| Normalized category | Recovery action | Operator guidance | Anti-patterns |
-|---------------------|-----------------|-------------------|---------------|
-| `success` | `none` | 归档验收；按需 review artifacts | 对成功 run 发起 retry |
-| `timeout` | `retry-node` | 查日志/artifacts 确认瞬态；人工重跑节点 | 未查根因就循环重试；指望 runner 自动 retry |
-| `executor`（network/quota/rate-limit/unavailable） | `retry-node` | 等后端/配额恢复后重跑 | 把 auth/validation 误判为瞬态 executor |
-| `executor`（其他 raw） | `rerun-after-fix` | 查 executor.jsonl、node result | 盲目 retry 非瞬态 backend 错误 |
-| `auth` | `rerun-after-fix` | 更新 API key/凭证后重跑 | 在凭证未修复时 retry |
-| `write-guard` | `manual-review` | 审 writeSet/writePolicy、prompt、result.summary | read-only 节点写根 `artifacts/`；扩大 writeSet 掩盖违规 |
-| `validation` | `rerun-after-fix` | 修 schema/output/test 后再跑 | 跳过验证直接 approve |
-| `shell-command` | `rerun-after-fix` | 读 stdout/stderr、修命令或 repo 状态 | 只重跑 shell 不改命令 |
-| `static-error` | `rerun-after-fix` | 查 static config 与 emitted markdown | 当 LLM 节点 retry |
-| `decision-envelope`（paused） | `resume-or-reject` | `dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` → `dag resume --run-id <id>` | 未读 envelope 就 approve；用 recovery 字段单独 auto-approve |
-| `decision-envelope`（非 paused） | `manual-review` | 读 decision.envelope.json / validation artifact | 绕过 Decision Gate schema |
-| `human-required`（paused） | `resume-or-reject` | 提供人工输入 → approve/resume | 在 escalation 未解决时 resume |
-| `human-required`（非 paused） | `manual-review` | 读 human-escalation artifacts | 忽略 `requiresHuman` |
-| `human-rejected` | `manual-review` | 修订 contract/source；**新 run** | 对同一 contract 自动 retry |
-| `skipped` | `inspect-upstream` | 修上游 ERROR/SKIPPED 再考虑下游 | 直接 retry SKIPPED 节点 |
-| `unknown` | `manual-review` | 读 state.json、executor.jsonl、node artifacts | 假设 `autoRetryEligible` 会触发执行 |
-
-## Handoff Recovery Plan 结构
-
-`dag report --markdown` 的 **Recovery Plan** 含四段（与 JSON 稳定字段一一对应）：
-
-1. **Primary Failure** — `primaryFailure`（node 或 run scope）
-2. **Recovery Action** — `primaryRecovery`（action、summary、reason、flags、commandHint）
-3. **Blocked Downstream / Skipped Nodes** — `downstreamSkippedNodes`
-4. **Recommended Operator Action** — 面向 operator 的步骤摘要
-
-保存 handoff 时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`，不要写入 `.harness/dag-runs/`。
-
-## Decision Gate 消费约定
-
-1. 优先 `dag report --json` 或 `buildDagDecisionGateEvidence()` 的 **verified** 派生摘要。
-2. 映射到 `decision` / `nextAction` 须保守；recovery 证据是 **advisory only, not an execution directive**。
-3. `autoRetryEligible: true` 仅表示「规划上可人工重试」，**不**触发 runner。
-4. paused run 的人类路径仍是 M5 CLI：`dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` / `dag resume --run-id <id>`（见 [`agent-dag-runner.md`](agent-dag-runner.md) §Decision Gate）。
-5. Envelope 干跑：`dag decision inspect|validate` 重解析 run facts；`validate` 无效时 exit 1；**不**写 artifact、**不** resume。
-
-## Active stale run recovery（advisory detection）
-
-`dag doctor` 与 `dag status` 通过 `detectDagRunHealthIssues()` 检测 lifecycle 不一致，**不** mutate run facts。
-
-| Code | 典型场景 | operator 指引 |
-|------|----------|------------|
-| `terminal-in-active` | run 已完成但 `active/<run-id>/` 残留 | 对照 `completed/` canonical facts；手动 archive 或删除 stale 目录 |
-| `paused-in-active` | pause 后目录未迁至 `paused/` | `dag doctor` 诊断；修复 facts 后再 approve/resume |
-| `lifecycle-status-mismatch` | `paused/` 下 status 非 paused | 同上 |
-| `missing-approval-artifact` | approve 后 artifact 缺失 | 勿 resume；re-approve 或 restore artifact |
-| `non-terminal-in-completed` | completed 目录 status 异常 | manual-review only |
-| `run-id-mismatch` / `missing-state-json` | 目录损坏或命名错误 | Inspect；勿 auto-mutate completed facts |
-
-**Deferred runtime**：无 `dag recover apply` 或自动 cleanup；未来可能增加只读 `dag recover plan`（设计占位，未实现）。
-
-## 事实源与边界
-
-| 类型 | 位置 | 规则 |
-|------|------|------|
-| Canonical run facts | `.harness/dag-runs/{active\|paused\|completed}/<run-id>/` | **只读**；report 不写回 |
-| 派生 report | stdout / 重定向文件 | 可随时再生 |
-| 工作块摘要 | 根 `artifacts/` | 非 per-run 历史；read-only DAG 节点不得写 |
-
-## 验证
-
-```bash
-cd . && npx vitest run \
-  test/dag-report.test.ts \
-  test/dag-recovery-recommendation.test.ts \
-  test/dag-decision-gate-recovery-dogfood.test.ts \
-  test/dag-decision-evidence.test.ts \
-  test/dag-decision-envelope.test.ts \
-  test/dag-approve-resume.test.ts \
-  test/cli-contract.test.ts
-```
-
-实现细节与映射逻辑：`./src/core/dag-recovery-recommendation.ts`、`dag-report.ts`、`dag-decision-evidence.ts`。
+# Agent DAG Recovery Playbook（恢复手册）
+
+> **关联**：[`agent-dag-runner.md`](agent-dag-runner.md)（CLI 与 run 语义）· [`templates/agent-dag-decision-gate.prompt.md`](templates/agent-dag-decision-gate.prompt.md)（Decision Gate 消费 recovery 证据）
+
+## 定位
+
+Agent DAG **recovery planning 是只读、派生、advisory** 的。`dag report` 与 `buildDagDecisionGateEvidence()` 从 `.harness/dag-runs/` 的 canonical facts 聚合 `normalizedFailureCategory` → `recoveryRecommendation`，供人工或 Decision Gate prompt 消费。
+
+中断后不要从上游摘要手工生成 impl-only DAG。先修复 `.harness/tasks/<task-id>/source/` 或计划，再对同一 task 重新执行 `dag run-task`、严格 `dag validate` 和新的 `run-dag`。新生成的完整 DAG 会重新冻结 `sourceBinding` 并经过 contract/scout/plan/gate；v3 孤立 writer 如果既无来源绑定、也无只读 planner 上游，会被 strict governance 拒绝。完整规则见 [`design/dag-source-binding-and-recovery.md`](design/dag-source-binding-and-recovery.md)。
+
+Production Readiness v0.1 在 normalized DAG category 之上增加 product-line routing。Report 与 doctor 输出应保留 raw DAG fact 并派生，不重写已完成 facts：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+Product-line taxonomy 定义见 `ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
+
+### 前端设计门禁专用恢复路径
+
+前端 DAG 的 design gate shell 失败（`frontend-first-design-gate-shell`、`frontend-final-design-gate-shell`、`frontend-design-gate-shell`）**不路由为 `ProductBug` / `dev-fix`**。此类失败固定路由为：
+
+- `productLineFailureCategory`: `ContractMismatch`
+- `recommendedFollowUp`: `frontend-plan-revision-and-rerun`
+
+恢复动作由 `planDagRecovery` 根据实际的 `normalizedFailureCategory` 和 run status 决定（通常为 `rerun-after-fix` 或 `manual-review`），但 product-line 维度的分类确保 Task Pool 和 morning report 不会将其混入普通 bug backlog。
+
+**非目标（本 playbook 不覆盖、runner 不实现）：**
+
+- 自动 retry / resume 节点执行
+- 修改 `completed/` 或 `paused/` 下的历史 run facts
+- 把 `autoRetryEligible` 当作 runtime 触发器
+- 仅凭 recovery 派生字段自动 approve Decision Gate
+
+## 快速命令
+
+```bash
+cd .
+
+# 全局 runtime 健康（active/paused/completed 摘要 + healthIssues；advisoryOnly）
+npm run dev -- dag doctor
+
+# 单 run 生命周期（approvalFlow、hasHumanApproval、nextRecommendedAction）
+npm run dev -- dag status --run-id <run-id>
+
+# 聚焦最新 paused run（--paused-latest ≡ --lifecycle paused --latest）
+npm run dev -- dag report --paused-latest [--json|--markdown]
+
+# 默认 compact Markdown 表格
+npm run dev -- dag report --run-id <run-id>
+
+# 机器可读 JSON（含 primaryFailure / primaryRecovery / downstreamSkippedNodes）
+npm run dev -- dag report --run-id <run-id> --json
+
+# 人类交接 Recovery Plan（四段结构化 Markdown）
+npm run dev -- dag report --run-id <run-id> --markdown
+
+# 过滤器
+npm run dev -- dag report --failed-only                              # 仅失败/需恢复
+npm run dev -- dag report --latest --failed-only                    # 最新一条需恢复 run
+npm run dev -- dag report --action retry-node                       # 按 primaryRecovery.action 筛选
+npm run dev -- dag report --lifecycle paused --action resume-or-reject
+
+# Decision Gate envelope dry-run（不 resume/retry；validate 无效时 exit 1）
+npm run dev -- dag decision inspect --run-id <run-id> [--node-id <node-id>]
+npm run dev -- dag decision validate --run-id <run-id> [--node-id <node-id>]
+```
+
+### Paused run operator 路径
+
+1. `dag report --paused-latest --json` 或 `dag doctor` — 定位最新 paused run 与 `primaryRecovery`
+2. `dag status --run-id <id>` — 读 `approvalFlow`、`escalationArtifactPath`、`pendingNodes`
+3. （可选）`dag decision validate --run-id <id>` — envelope preflight
+4. `dag approve --run-id <id> --option <option-id>` → `dag resume --run-id <id>`；或 `dag reject --run-id <id> --reason "..."`
+
+精确 approval 顺序见 [`agent-dag-runner.md`](agent-dag-runner.md) §Paused lifecycle。
+
+Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-decision-evidence.ts`）从 `DagRunReportEntry` 生成 prompt-friendly 摘要，字段与 JSON report 对齐，**不**写回 run state。
+
+## `dag report --json` schema 锁定
+
+- **Schema 文件**：`ai_workspace/loop-agent/templates/agent-dag-report.schema.json`
+- **Envelope**：`{ schemaVersion: 1, runs: DagRunReportEntry[] }`
+- **稳定消费字段**（Decision Gate / tooling 应依赖）：`primaryFailure`、`primaryRecovery`、`downstreamSkippedNodes`、`recoveryRecommendation`、`normalizedFailureCategory`；node 级 `decisionEnvelope`、`artifacts`；paused 级 `pausedByNodeId`、`pauseReason`
+- **测试**：`./test/dag-report.test.ts` §`dag report JSON schema contract` 对 fixture run 做 schema 校验
+- **变更策略**：breaking 字段变更须 bump `schemaVersion` 并同步 schema 文件与测试
+
+## Recovery Action 枚举
+
+| Action | 含义 | 典型触发 |
+|--------|------|----------|
+| `none` | 无需恢复 | 成功完成 |
+| `monitor` | 进行中，等待结束 | `PENDING` / `RUNNING` |
+| `retry-node` | 修复瞬态条件后可重跑节点 | timeout；executor 瞬态（network/quota/rate-limit/unavailable） |
+| `rerun-after-fix` | 先修根因再重跑 | auth、validation、shell-command、static-error、非瞬态 executor |
+| `resume-or-reject` | 人工审批后继续或拒绝 | paused + decision-envelope / human-required |
+| `manual-review` | 人工审查后再定路径 | write-guard、human-rejected、unknown、非 paused 的 decision-envelope |
+| `inspect-upstream` | 先查上游失败 | SKIPPED 下游节点 |
+| `unknown` | 未映射类别（不应出现在正常派生路径） | 内部兜底 |
+
+## Product-Line Routing v0.1
+
+| Product-line category | Default follow-up |
+|---|---|
+| `SpecUnclear` | `spec-clarification` |
+| `ContractMismatch` | `architecture-contract-fix` |
+| `ProductBug` | `dev-fix` |
+| `TestBug` | `qa-fix-test` |
+| `EnvFailure` | `env-fix` 或 retry verify |
+| `FlakyTest` | `flaky-test-analysis` |
+| `RiskyChange` | `human-review` / `architecture-review` |
+| `DependencyFailure` | unblock dependency |
+| `NeedsHuman` | `human-review` |
+| `Unknown` | human triage |
+
+## 类别 → 动作 → operator 指引
+
+| Normalized category | Recovery action | Operator guidance | Anti-patterns |
+|---------------------|-----------------|-------------------|---------------|
+| `success` | `none` | 归档验收；按需 review artifacts | 对成功 run 发起 retry |
+| `timeout` | `retry-node` | 查日志/artifacts 确认瞬态；人工重跑节点 | 未查根因就循环重试；指望 runner 自动 retry |
+| `executor`（network/quota/rate-limit/unavailable） | `retry-node` | 等后端/配额恢复后重跑 | 把 auth/validation 误判为瞬态 executor |
+| `executor`（其他 raw） | `rerun-after-fix` | 查 executor.jsonl、node result | 盲目 retry 非瞬态 backend 错误 |
+| `auth` | `rerun-after-fix` | 更新 API key/凭证后重跑 | 在凭证未修复时 retry |
+| `write-guard` | `manual-review` | 审 writeSet/writePolicy、prompt、result.summary | read-only 节点写根 `artifacts/`；扩大 writeSet 掩盖违规 |
+| `validation` | `rerun-after-fix` | 修 schema/output/test 后再跑 | 跳过验证直接 approve |
+| `shell-command` | `rerun-after-fix` | 读 stdout/stderr、修命令或 repo 状态 | 只重跑 shell 不改命令 |
+| `static-error` | `rerun-after-fix` | 查 static config 与 emitted markdown | 当 LLM 节点 retry |
+| `decision-envelope`（paused） | `resume-or-reject` | `dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` → `dag resume --run-id <id>` | 未读 envelope 就 approve；用 recovery 字段单独 auto-approve |
+| `decision-envelope`（非 paused） | `manual-review` | 读 decision.envelope.json / validation artifact | 绕过 Decision Gate schema |
+| `human-required`（paused） | `resume-or-reject` | 提供人工输入 → approve/resume | 在 escalation 未解决时 resume |
+| `human-required`（非 paused） | `manual-review` | 读 human-escalation artifacts | 忽略 `requiresHuman` |
+| `human-rejected` | `manual-review` | 修订 contract/source；**新 run** | 对同一 contract 自动 retry |
+| `skipped` | `inspect-upstream` | 修上游 ERROR/SKIPPED 再考虑下游 | 直接 retry SKIPPED 节点 |
+| `unknown` | `manual-review` | 读 state.json、executor.jsonl、node artifacts | 假设 `autoRetryEligible` 会触发执行 |
+
+## Handoff Recovery Plan 结构
+
+`dag report --markdown` 的 **Recovery Plan** 含四段（与 JSON 稳定字段一一对应）：
+
+1. **Primary Failure** — `primaryFailure`（node 或 run scope）
+2. **Recovery Action** — `primaryRecovery`（action、summary、reason、flags、commandHint）
+3. **Blocked Downstream / Skipped Nodes** — `downstreamSkippedNodes`
+4. **Recommended Operator Action** — 面向 operator 的步骤摘要
+
+保存 handoff 时重定向到平台临时目录或 `ai_workspace/loop-agent/reports/`，不要写入 `.harness/dag-runs/`。
+
+## Decision Gate 消费约定
+
+1. 优先 `dag report --json` 或 `buildDagDecisionGateEvidence()` 的 **verified** 派生摘要。
+2. 映射到 `decision` / `nextAction` 须保守；recovery 证据是 **advisory only, not an execution directive**。
+3. `autoRetryEligible: true` 仅表示「规划上可人工重试」，**不**触发 runner。
+4. paused run 的人类路径仍是 M5 CLI：`dag approve --run-id <id> --option <option-id>` / `dag reject --run-id <id> --reason "..."` / `dag resume --run-id <id>`（见 [`agent-dag-runner.md`](agent-dag-runner.md) §Decision Gate）。
+5. Envelope 干跑：`dag decision inspect|validate` 重解析 run facts；`validate` 无效时 exit 1；**不**写 artifact、**不** resume。
+
+## Active stale run recovery（advisory detection）
+
+`dag doctor` 与 `dag status` 通过 `detectDagRunHealthIssues()` 检测 lifecycle 不一致，**不** mutate run facts。
+
+| Code | 典型场景 | operator 指引 |
+|------|----------|------------|
+| `terminal-in-active` | run 已完成但 `active/<run-id>/` 残留 | 对照 `completed/` canonical facts；手动 archive 或删除 stale 目录 |
+| `paused-in-active` | pause 后目录未迁至 `paused/` | `dag doctor` 诊断；修复 facts 后再 approve/resume |
+| `lifecycle-status-mismatch` | `paused/` 下 status 非 paused | 同上 |
+| `missing-approval-artifact` | approve 后 artifact 缺失 | 勿 resume；re-approve 或 restore artifact |
+| `non-terminal-in-completed` | completed 目录 status 异常 | manual-review only |
+| `run-id-mismatch` / `missing-state-json` | 目录损坏或命名错误 | Inspect；勿 auto-mutate completed facts |
+
+**Deferred runtime**：无 `dag recover apply` 或自动 cleanup；未来可能增加只读 `dag recover plan`（设计占位，未实现）。
+
+## 事实源与边界
+
+| 类型 | 位置 | 规则 |
+|------|------|------|
+| Canonical run facts | `.harness/dag-runs/{active\|paused\|completed}/<run-id>/` | **只读**；report 不写回 |
+| 派生 report | stdout / 重定向文件 | 可随时再生 |
+| 工作块摘要 | 根 `artifacts/` | 非 per-run 历史；read-only DAG 节点不得写 |
+
+## 验证
+
+```bash
+cd . && npx vitest run \
+  test/dag-report.test.ts \
+  test/dag-recovery-recommendation.test.ts \
+  test/dag-decision-gate-recovery-dogfood.test.ts \
+  test/dag-decision-evidence.test.ts \
+  test/dag-decision-envelope.test.ts \
+  test/dag-approve-resume.test.ts \
+  test/cli-contract.test.ts
+```
+
+实现细节与映射逻辑：`./src/core/dag-recovery-recommendation.ts`、`dag-report.ts`、`dag-decision-evidence.ts`。