@tea-agent/loop-agent 0.13.0-beta.0 → 0.13.0

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 定义见 `docs/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 文件**：`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 消费。
+
+中断后不要从上游摘要手工生成 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`。

package/docs/agent-dag-runner.md

@@ -1,67 +1,67 @@
-# 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"` 时有界写入
-
-## Retry (read-only Pi nodes)
-
-planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
-
-- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
-- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
-- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
-- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
-- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
-
-示例：
-
-```json
-{
-  "retryPolicy": {
-    "maxAttempts": 3,
-    "backoff": "exponential",
-    "initialDelayMs": 2000,
-    "maxDelayMs": 30000,
-    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
-  }
-}
-```
-
-未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
-
-## Skills
-
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `skills/`，并在各节点 `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 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `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"` 时有界写入
+
+## Retry (read-only Pi nodes)
+
+planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
+
+- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
+- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
+- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
+- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
+- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
+
+示例：
+
+```json
+{
+  "retryPolicy": {
+    "maxAttempts": 3,
+    "backoff": "exponential",
+    "initialDelayMs": 2000,
+    "maxDelayMs": 30000,
+    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
+  }
+}
+```
+
+未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
+
+## Skills
+
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `.agents/skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
+
+执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `ai_workspace/loop-agent/.agents/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
+
+目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `.agents/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。

package/docs/architecture/README.md

@@ -1,26 +1,26 @@
-# 架构文档索引
-
-本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
-
-## 阅读路径
-
-建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
-
-1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
-2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
-3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
-4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
-5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
-6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
-
-## 事实与规划的区分
-
-- **当前事实源**：`src/` 源码、发布 CLI、`docs/exec-plans/completed/`、`docs/reports/current-capability-summary.md`、ADR 0001–0003。
-- **规划/设计输入**：`docs/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
-- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
-
-## 与其他文档的分工
-
-- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
-- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
-- 本目录文档随发布包发布（npm `files` 显式条目 + `docs/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+# 架构文档索引
+
+本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
+
+## 阅读路径
+
+建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
+
+1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
+2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
+4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
+5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
+6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
+
+## 事实与规划的区分
+
+- **当前事实源**：`src/` 源码、发布 CLI、`ai_workspace/loop-agent/exec-plans/completed/`、`ai_workspace/loop-agent/reports/current-capability-summary.md`、ADR 0001–0003。
+- **规划/设计输入**：`ai_workspace/loop-agent/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
+
+## 与其他文档的分工
+
+- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
+- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `ai_workspace/loop-agent/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。