@tea-agent/loop-agent 0.4.0 → 0.5.0

package/docs/README.md

@@ -1,72 +1,72 @@
-# 文档索引
-
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
-
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
-
-## 核心文档
-
-- `development-principles.md` — 仓库开发原则
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
-- `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 指南
-- `cursor-executor-usage.md` — Cursor executor 用法
-- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
-
-## 设计思想来源
-
-- `../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` — 设计草稿与实现契约
-- `exec-plans/active/README.md` — 进行中的执行计划
-- `exec-plans/completed/README.md` — 已完成的执行计划
-- `progress/README.md` — 进度交接日志
-- `reports/README.md` — 验证与审计报告
-- `decisions/README.md` — 架构决策
-- `skills/README.md` — repo-local skill registry and vetting notes
-- `templates/` — 可复用的规划、报告与 DAG 模板
-
-## 仓库 Skills
-
-- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
-- 每个额外 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/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
-- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
-- `templates/adr.md` — 架构决策记录（ADR）
-
-## 维护
-
-文档变更后运行：
-
-```bash
-bash scripts/check-repo.sh
-```
-
-Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-完整本地门禁：
-
-```bash
-bash scripts/ci.sh
-```
+# 文档索引
+
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+
+## 核心文档
+
+- `development-principles.md` — 仓库开发原则
+- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
+- `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 指南
+- `cursor-executor-usage.md` — Cursor executor 用法
+- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
+
+## 设计思想来源
+
+- `../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` — 设计草稿与实现契约
+- `exec-plans/active/README.md` — 进行中的执行计划
+- `exec-plans/completed/README.md` — 已完成的执行计划
+- `progress/README.md` — 进度交接日志
+- `reports/README.md` — 验证与审计报告
+- `decisions/README.md` — 架构决策
+- `skills/README.md` — repo-local skill registry and vetting notes
+- `templates/` — 可复用的规划、报告与 DAG 模板
+
+## 仓库 Skills
+
+- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- 每个额外 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/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
+- `templates/adr.md` — 架构决策记录（ADR）
+
+## 维护
+
+文档变更后运行：
+
+```bash
+bash scripts/check-repo.sh
+```
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+完整本地门禁：
+
+```bash
+bash scripts/ci.sh
+```

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

@@ -1,184 +1,184 @@
-# 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 消费。
-
-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 定义见 `design/state-and-failure-taxonomy.md`。
-
-**非目标（本 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 文件**：`docs/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 时重定向到平台临时目录或 `docs/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 消费。
+
+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 定义见 `design/state-and-failure-taxonomy.md`。
+
+**非目标（本 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 文件**：`docs/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 时重定向到平台临时目录或 `docs/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`。

package/docs/agent-dag-runner.md

@@ -1,42 +1,42 @@
-# Agent DAG Runner
-
-Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
-
-## 基本用法
-
-```bash
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
-
-## Executors
-
-- `static`：确定性生成的 artifacts 或 notes
-- `shell`：验证与文件系统检查
-- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-- `cursor`：显式启用时的可选有界写后端
-
-## Skills
-
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
-
-执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `docs/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
-
-`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
-
-## Artifacts
-
-DAG artifacts 位于：
-
-```text
-.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
-```
-
-根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
-
-## Shell Gates
-
-- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。
+# Agent DAG Runner
+
+Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
+
+## 基本用法
+
+```bash
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
+
+## Executors
+
+- `static`：确定性生成的 artifacts 或 notes
+- `shell`：验证与文件系统检查
+- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
+- `cursor`：显式启用时的可选有界写后端
+
+## Skills
+
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
+
+执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `docs/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
+
+`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
+
+## Artifacts
+
+DAG artifacts 位于：
+
+```text
+.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
+```
+
+根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
+
+## Shell Gates
+
+- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。