@tea-agent/loop-agent 0.2.0 → 0.2.1

package/dist/workflows/dag/failure-routing.js

@@ -0,0 +1,82 @@
+export const dagProductLineFailureCategoryValues = [
+    "SpecUnclear",
+    "ContractMismatch",
+    "ProductBug",
+    "TestBug",
+    "EnvFailure",
+    "FlakyTest",
+    "RiskyChange",
+    "DependencyFailure",
+    "NeedsHuman",
+    "Unknown",
+];
+const FOLLOW_UP_BY_PRODUCT_LINE = {
+    SpecUnclear: "spec-clarification",
+    ContractMismatch: "architecture-contract-fix",
+    ProductBug: "dev-fix",
+    TestBug: "qa-fix-test",
+    EnvFailure: "env-fix or retry verify",
+    FlakyTest: "flaky-test-analysis",
+    RiskyChange: "human-review or architecture-review",
+    DependencyFailure: "unblock dependency",
+    NeedsHuman: "human-review",
+    Unknown: "human triage",
+};
+function routeToProductLine(input) {
+    const normalized = input.normalizedFailureCategory;
+    if (!normalized || normalized === "success")
+        return undefined;
+    const raw = input.rawFailureCategory?.toLowerCase() ?? "";
+    const nodeId = input.nodeId?.toLowerCase() ?? "";
+    switch (normalized) {
+        case "write-guard":
+            return "RiskyChange";
+        case "auth":
+        case "executor":
+        case "timeout":
+            return "EnvFailure";
+        case "human-required":
+        case "human-rejected":
+        case "decision-envelope":
+            return "NeedsHuman";
+        case "skipped":
+            return "DependencyFailure";
+        case "shell-command":
+            if (raw.includes("flaky"))
+                return "FlakyTest";
+            if (nodeId.includes("test") || raw.includes("test-bug")) {
+                return "TestBug";
+            }
+            return "ProductBug";
+        case "static-error":
+            return "SpecUnclear";
+        case "validation":
+            if (raw.includes("path") ||
+                raw.includes("write") ||
+                raw.includes("forbidden")) {
+                return "RiskyChange";
+            }
+            if (raw.includes("test-bug") || nodeId.includes("test")) {
+                return "TestBug";
+            }
+            if (raw.includes("test-failure") || raw.includes("verify-failure")) {
+                return "ProductBug";
+            }
+            return "SpecUnclear";
+        case "unknown":
+            return "Unknown";
+        default: {
+            const exhaustive = normalized;
+            return exhaustive;
+        }
+    }
+}
+export function routeDagFailure(input) {
+    const productLineFailureCategory = routeToProductLine(input);
+    if (!productLineFailureCategory)
+        return {};
+    return {
+        productLineFailureCategory,
+        recommendedFollowUp: FOLLOW_UP_BY_PRODUCT_LINE[productLineFailureCategory],
+    };
+}

package/dist/workflows/dag/lifecycle.js

@@ -2,6 +2,8 @@ import { access, mkdir, readFile, readdir, rename, } from "node:fs/promises";
 import path from "node:path";
 import { writeJsonAtomic, } from "../../infrastructure/harness/atomic-write.js";
 import { parseDagSpec } from "./types.js";
+import { normalizeDagFailureCategory, } from "./failure-category.js";
+import { routeDagFailure } from "./failure-routing.js";
 const DAG_LIFECYCLE_SCAN_ORDER = [
     "paused",
     "active",
@@ -470,16 +472,106 @@ export async function runDagStatus(repoRoot, rawArgs) {
     console.log(JSON.stringify(report, null, 2));
 }
 export function parseDagDoctorArgs(args) {
-    for (const arg of args) {
+    let runId;
+    let markdown = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--run-id") {
+            runId = args[++i];
+            if (!runId || runId.startsWith("-")) {
+                throw new Error("dag doctor --run-id requires a value");
+            }
+            continue;
+        }
+        if (arg.startsWith("--run-id=")) {
+            runId = arg.slice("--run-id=".length);
+            if (!runId)
+                throw new Error("dag doctor --run-id requires a value");
+            continue;
+        }
+        if (arg === "--markdown") {
+            markdown = true;
+            continue;
+        }
         if (arg.startsWith("-")) {
             throw new Error(`unknown dag doctor flag: ${arg}`);
         }
         throw new Error(`unexpected positional argument: ${arg}`);
     }
-    return {};
+    return { runId, markdown };
+}
+function findDoctorFailureNode(state) {
+    if (state.pausedByNodeId) {
+        const node = state.nodes[state.pausedByNodeId];
+        return {
+            nodeId: state.pausedByNodeId,
+            status: node?.status,
+            rawFailureCategory: node?.failureCategory,
+        };
+    }
+    const errorEntry = Object.entries(state.nodes).find(([, node]) => node.status === "ERROR");
+    const skippedEntry = Object.entries(state.nodes).find(([, node]) => node.status === "SKIPPED");
+    const selected = errorEntry ?? skippedEntry;
+    if (!selected) {
+        return {
+            rawFailureCategory: state.failureCategory,
+            status: state.status,
+        };
+    }
+    return {
+        nodeId: selected[0],
+        status: selected[1].status,
+        rawFailureCategory: selected[1].failureCategory,
+    };
+}
+async function formatDagDoctorMarkdown(repoRoot, runId) {
+    const located = await locateDagRun(repoRoot, runId);
+    if (!located) {
+        throw new Error(`dag run not found: ${runId}`);
+    }
+    const state = await readDagRunState(located.runDir);
+    const summary = await buildDagStatusReport(repoRoot, runId);
+    const failure = findDoctorFailureNode(state);
+    const rawFailureCategory = failure.rawFailureCategory ??
+        (state.status === "paused" ? "human-required" : state.failureCategory);
+    const failureStatus = state.status === "paused" ? "paused" : failure.status;
+    const normalizedCategory = normalizeDagFailureCategory(rawFailureCategory, failureStatus ?? state.status);
+    const routing = routeDagFailure({
+        rawFailureCategory,
+        normalizedFailureCategory: normalizedCategory,
+        nodeId: failure.nodeId,
+    });
+    const evidence = failure.nodeId
+        ? path.join(located.runDir, failure.nodeId, "result.summary.md")
+        : path.join(located.runDir, "state.json");
+    const nextCommand = summary.nextRecommendedAction ||
+        routing.recommendedFollowUp ||
+        "Inspect run facts and choose a recovery path.";
+    return [
+        "## Diagnosis",
+        "",
+        `- run id: ${runId}`,
+        `- lifecycle: ${located.lifecycle}`,
+        `- failed node: ${failure.nodeId ?? "-"}`,
+        `- raw failure: ${rawFailureCategory ?? "-"}`,
+        `- normalized category: ${normalizedCategory}`,
+        `- product-line category: ${routing.productLineFailureCategory ?? "-"}`,
+        `- recommended follow-up: ${routing.recommendedFollowUp ?? "-"}`,
+        `- evidence: ${evidence}`,
+        `- next command: ${nextCommand}`,
+        "",
+    ].join("\n");
 }
 export async function runDagDoctor(repoRoot, rawArgs) {
-    parseDagDoctorArgs(rawArgs);
+    const parsed = parseDagDoctorArgs(rawArgs);
+    if (parsed.runId) {
+        if (parsed.markdown) {
+            console.log(await formatDagDoctorMarkdown(repoRoot, parsed.runId));
+            return;
+        }
+        console.log(JSON.stringify(await buildDagStatusReport(repoRoot, parsed.runId), null, 2));
+        return;
+    }
     const report = await buildDagDoctorReport(repoRoot);
     console.log(JSON.stringify(report, null, 2));
 }

package/dist/workflows/dag/report.js

@@ -7,6 +7,7 @@ import { repairArtifactSchema } from "./repair-artifact.js";
 import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 export const DAG_CLOSEOUT_DRAFT_DISCLAIMER = "> **Advisory only.** Derived from completed run facts. Canonical source remains `dag report --json` and `.harness/dag-runs/completed/<run-id>/`. Do not treat this draft as authoritative.";
 import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from "./failure-category.js";
+import { dagProductLineFailureCategoryValues, routeDagFailure, } from "./failure-routing.js";
 import { DAG_RECOVERY_ACTIONS, planDagRecovery, } from "./recovery-recommendation.js";
 import { dagNodeExecutorSchema, dagNodeStatusSchema, LEGACY_TOP_LEVEL_MODELS_ERROR, parseDagSpec, resolveModelForTask, } from "./types.js";
 export const DAG_REPORT_SCHEMA_VERSION = 1;
@@ -21,6 +22,7 @@ const dagRunStatusSchema = z.enum([
     "paused",
 ]);
 const dagRecoveryActionSchema = z.enum(DAG_RECOVERY_ACTIONS);
+const dagProductLineFailureCategorySchema = z.enum(dagProductLineFailureCategoryValues);
 const dagArtifactRefSchema = z
     .object({
     path: z.string(),
@@ -44,6 +46,8 @@ const dagReportPrimaryFailureSchema = z
     nodeStatus: dagNodeStatusSchema.optional(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
 })
     .strict();
 const dagReportDownstreamSkippedNodeSchema = z
@@ -51,6 +55,8 @@ const dagReportDownstreamSkippedNodeSchema = z
     nodeId: z.string(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
 })
     .strict();
 const dagConvergencePassArtifactRefSchema = z
@@ -130,6 +136,8 @@ const dagNodeReportRowSchema = z
     tokensUsed: z.number().nonnegative().optional(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     backend: z.enum(["sdk", "cli"]).optional(),
     sdkAttempted: z.boolean().optional(),
@@ -150,6 +158,8 @@ const dagRunReportEntrySchema = z
     finishedAt: z.string().optional(),
     failureCategory: z.string().optional(),
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
+    productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
+    recommendedFollowUp: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     primaryFailure: dagReportPrimaryFailureSchema,
     primaryRecovery: dagRecoveryRecommendationSchema,
@@ -250,12 +260,18 @@ function buildPrimaryFailure(run, primaryNode) {
             nodeStatus: primaryNode.status,
             failureCategory: primaryNode.failureCategory,
             normalizedFailureCategory: primaryNode.normalizedFailureCategory,
+            productLineFailureCategory: primaryNode.productLineFailureCategory,
+            recommendedFollowUp: primaryNode.recommendedFollowUp,
         };
     }
     return {
         scope: "run",
         failureCategory: run.failureCategory,
         normalizedFailureCategory: run.normalizedFailureCategory,
+        ...routeDagFailure({
+            rawFailureCategory: run.failureCategory,
+            normalizedFailureCategory: run.normalizedFailureCategory,
+        }),
     };
 }
 function resolvePrimaryRecovery(run, primaryNode) {
@@ -302,6 +318,8 @@ function collectDownstreamSkippedNodes(nodes, spec, primaryNode) {
         nodeId: node.nodeId,
         failureCategory: node.failureCategory,
         normalizedFailureCategory: node.normalizedFailureCategory,
+        productLineFailureCategory: node.productLineFailureCategory,
+        recommendedFollowUp: node.recommendedFollowUp,
     }));
 }
 function isFailedReportRun(run) {
@@ -342,6 +360,12 @@ export async function buildDagRunReportEntry(input) {
                 continue;
             const task = tasks.get(nodeId);
             const normalizedFailureCategory = normalizeDagFailureCategory(node.failureCategory, node.status);
+            const failureRouting = routeDagFailure({
+                rawFailureCategory: node.failureCategory,
+                normalizedFailureCategory,
+                nodeId,
+                executor: node.executor,
+            });
             nodes.push({
                 nodeId,
                 rank,
@@ -355,6 +379,7 @@ export async function buildDagRunReportEntry(input) {
                 tokensUsed: node.tokensUsed,
                 failureCategory: node.failureCategory,
                 normalizedFailureCategory,
+                ...failureRouting,
                 recoveryRecommendation: planDagRecovery({
                     status: node.status,
                     normalizedFailureCategory,
@@ -406,6 +431,11 @@ export async function buildDagRunReportEntry(input) {
         lifecycle: input.lifecycle,
         runStatus: input.state.status,
     });
+    const runFailureRouting = routeDagFailure({
+        rawFailureCategory: runRecoverySource.failureCategory,
+        normalizedFailureCategory: runRecoverySource.normalizedFailureCategory,
+        nodeId: "nodeId" in runRecoverySource ? runRecoverySource.nodeId : undefined,
+    });
     const partialEntry = {
         runId: input.state.runId,
         title: input.state.title,
@@ -416,6 +446,7 @@ export async function buildDagRunReportEntry(input) {
         finishedAt: input.state.finishedAt,
         failureCategory: input.state.failureCategory,
         normalizedFailureCategory,
+        ...runFailureRouting,
         recoveryRecommendation,
         pausedByNodeId: input.state.pausedByNodeId,
         pauseReason: input.state.pauseReason,
@@ -638,11 +669,15 @@ function formatPrimaryFailureSection(run) {
         return [
             `- **Node**: ${failure.nodeId} (${failure.nodeStatus ?? "unknown"})`,
             `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+            `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+            `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
         ];
     }
     return [
         `- **Scope**: run`,
         `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+        `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+        `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
     ];
 }
 function formatPrimaryRecoverySection(run) {
@@ -784,7 +819,7 @@ export function formatDagReportHandoffMarkdown(report) {
                 ? `- **Failure (raw/normalized)**: ${node.failureCategory} / ${node.normalizedFailureCategory ?? "-"}`
                 : "", `- **Executor**: ${node.executor}${node.backend ? ` (backend: ${node.backend})` : ""}`, `- **Model**: ${node.model ?? "—"}`, `- **Duration**: ${formatDuration(node.durationMs)}`, `- **Tokens**: ${formatTokens(node.tokensUsed)}`, `- **Started**: ${formatTimestamp(node.startedAt)}`, `- **Finished**: ${formatTimestamp(node.finishedAt)}`, "");
         }
-        lines.push("## Failures", ...formatFailureSection(run), "", "## Recovery Plan", ...formatRecoveryPlanSection(run), "", "## Artifacts", ...formatArtifactsSection(run), "", "## Suggested Next Action", `- ${suggestedNextAction(run)}`, "");
+        lines.push("## Failures", ...formatFailureSection(run), "", "## Recovery Plan", ...formatRecoveryPlanSection(run), "", "## Operator Next Steps", ...formatRecommendedOperatorAction(run), "", "## Artifacts", ...formatArtifactsSection(run), "", "## Suggested Next Action", `- ${suggestedNextAction(run)}`, "");
         return lines
             .filter((line) => line !== undefined)
             .join("\n");
@@ -869,6 +904,8 @@ function formatCloseoutPrimaryFailureSection(run) {
             `- **Scope**: node`,
             `- **Node**: ${failure.nodeId} (${failure.nodeStatus ?? "unknown"})`,
             `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+            `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+            `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
         ];
     }
     if (run.primaryRecovery.action === "none" &&
@@ -879,6 +916,8 @@ function formatCloseoutPrimaryFailureSection(run) {
     return [
         `- **Scope**: ${failure.scope}`,
         `- **Category (raw/normalized)**: ${failure.failureCategory ?? "-"} / ${failure.normalizedFailureCategory ?? "-"}`,
+        `- **Product-line category**: ${failure.productLineFailureCategory ?? "-"}`,
+        `- **Recommended follow-up**: ${failure.recommendedFollowUp ?? "-"}`,
     ];
 }
 function formatCloseoutRecoverySection(run) {
@@ -939,6 +978,39 @@ function formatRemainingRisksSection(run) {
     return risks;
 }
 export function formatDagCloseoutDraftMarkdown(run) {
+    if (isFailedReportRun(run)) {
+        const lines = [
+            `# Failure Handoff: ${run.runId}`,
+            "",
+            DAG_CLOSEOUT_DRAFT_DISCLAIMER,
+            "",
+            "## What failed",
+            ...formatCloseoutPrimaryFailureSection(run),
+            "",
+            "## Evidence",
+            ...formatCloseoutVerificationEvidence(run),
+            "",
+            "## Classification",
+            `- raw_failure_category: ${run.primaryFailure.failureCategory ?? "-"}`,
+            `- dag_normalized_failure_category: ${run.primaryFailure.normalizedFailureCategory ?? "-"}`,
+            `- product_line_failure_category: ${run.primaryFailure.productLineFailureCategory ?? "-"}`,
+            `- recommended_follow_up: ${run.primaryFailure.recommendedFollowUp ?? "-"}`,
+            "",
+            "## Recommended follow-up",
+            ...formatCloseoutRecoverySection(run),
+            "",
+            "## Safe retry conditions",
+            `- Retry only after completing \`${run.primaryFailure.recommendedFollowUp ?? run.primaryRecovery.action}\` and preserving the original DAG run facts.`,
+            "- Do not rewrite `.harness/dag-runs/completed/**`; create a new run or task artifact for follow-up evidence.",
+            "",
+            "## Human decision needed",
+            run.primaryRecovery.humanRequired
+                ? "- Yes. Human review is required before retry or promotion."
+                : "- No required human gate was derived, but review the failure evidence before retry.",
+            "",
+        ];
+        return lines.join("\n");
+    }
     const lines = [
         `# DAG Closeout Draft: ${run.runId}`,
         "",

package/docs/README.md

@@ -1,62 +1,64 @@
-# Documentation Index
+# 文档索引
 
-`docs/` is the governance root for loop-agent. It contains workflow rules, methodology, verification rules, execution plans, reports, progress logs, decisions, and reusable templates.
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
 
-Top-level `AGENTS.md` is the operating map. Durable knowledge belongs here: decisions, contracts, plans, verification evidence, debugging notes, and reusable process rules should be recorded under `docs/` instead of staying only in chat.
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
 
-## Core Documents
+## 核心文档
 
-- `development-principles.md` — repository development principles
-- `architecture/runtime-boundaries.md` — runtime layer boundaries and dependency direction
-- `feature-workflow.md` — bounded feature workflow
-- `verification-matrix.md` — verification command selection
-- `loop-agent-harness.md` — runtime and command surface overview
-- `agent-dag-runner.md` — Agent DAG runner guide
-- `cursor-executor-usage.md` — Cursor executor usage
-- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine roadmap and fit analysis
+- `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 路线图与适配分析
 
-## Methodology
+## 方法论
 
-- `harness-methodology-tdd.md` — TDD discipline for behavior changes and bug fixes
-- `harness-methodology-verification.md` — verification discipline before completion claims
-- `harness-methodology-debugging.md` — systematic debugging workflow before fixes
+- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
+- `harness-methodology-verification.md` — 完成声明前的验证纪律
+- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
 
-## Artifacts
+## 产物目录
 
-- `design/README.md` — draft design notes and implementation contracts
-- `exec-plans/active/README.md` — active execution plans
-- `exec-plans/completed/README.md` — completed execution plans
-- `progress/README.md` — progress handoff logs
-- `reports/README.md` — verification and audit reports
-- `decisions/README.md` — architecture decisions
-- `templates/` — reusable planning, reporting, and DAG templates
+- `design/README.md` — 设计草稿与实现契约
+- `exec-plans/active/README.md` — 进行中的执行计划
+- `exec-plans/completed/README.md` — 已完成的执行计划
+- `progress/README.md` — 进度交接日志
+- `reports/README.md` — 验证与审计报告
+- `decisions/README.md` — 架构决策
+- `templates/` — 可复用的规划、报告与 DAG 模板
 
-## Repository Skills
+## 仓库 Skills
 
-- `../skills/loop-agent/` — loop-agent's own skill instructions and references.
-- Each additional skill uses its own subdirectory under repository-root `../skills/`; these local copies are referenced by DAG templates so maintenance does not depend on external agent skill directories.
+- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
 
-## Templates
+## 模板
 
-- `templates/project-start-checklist.md` — pre-work checklist
-- `templates/feature-spec.md` — bounded feature specification
-- `templates/sprint-contract.md` — implementation contract and acceptance criteria
-- `templates/exec-plan.md` — execution plan for non-trivial work
-- `templates/progress-log.md` — progress and handoff log
-- `templates/qa-report.md` — verification and QA evidence
-- `templates/adr.md` — architecture decision record
+- `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/adr.md` — 架构决策记录（ADR）
 
-## Maintenance
+## 维护
 
-After docs changes, run:
-
-```bash
-bash scripts/check-repo.sh
-```
-
-On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Use platform-native paths for actual file operations; reserve `/` for repo refs, JSON/Markdown evidence refs, and glob conventions.
-
-For a full local gate, run:
+文档变更后运行：
+
+```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,4 +1,4 @@
-# Agent DAG Recovery Playbook
+# 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 证据）
 
@@ -6,6 +6,17 @@
 
 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 节点执行
@@ -47,7 +58,7 @@ 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 操作员路径
+### Paused run operator 路径
 
 1. `dag report --paused-latest --json` 或 `dag doctor` — 定位最新 paused run 与 `primaryRecovery`
 2. `dag status --run-id <id>` — 读 `approvalFlow`、`escalationArtifactPath`、`pendingNodes`
@@ -79,7 +90,22 @@ Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-de
 | `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 |
 |---------------------|-----------------|-------------------|---------------|
@@ -107,9 +133,9 @@ Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-de
 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** — 面向操作员的步骤摘要
+4. **Recommended Operator Action** — 面向 operator 的步骤摘要
 
-保存 handoff 时重定向到平台临时目录或 `docs/reports/`，不要写入 `.harness/dag-runs/`。
+保存 handoff 时重定向到平台临时目录或 `docs/reports/`，不要写入 `.harness/dag-runs/`。
 
 ## Decision Gate 消费约定
 
@@ -123,7 +149,7 @@ Decision Gate prompt 侧：`buildDagDecisionGateEvidence()`（`./src/core/dag-de
 
 `dag doctor` 与 `dag status` 通过 `detectDagRunHealthIssues()` 检测 lifecycle 不一致，**不** mutate run facts。
 
-| Code | 典型场景 | 操作员指引 |
+| Code | 典型场景 | operator 指引 |
 |------|----------|------------|
 | `terminal-in-active` | run 已完成但 `active/<run-id>/` 残留 | 对照 `completed/` canonical facts；手动 archive 或删除 stale 目录 |
 | `paused-in-active` | pause 后目录未迁至 `paused/` | `dag doctor` 诊断；修复 facts 后再 approve/resume |

package/docs/agent-dag-runner.md

@@ -1,40 +1,40 @@
 # Agent DAG Runner
 
-Agent DAG is loop-agent's declarative orchestration runtime. A DAG decomposes work into nodes, runs eligible ranks in order, records artifacts, and uses gates for review and verification.
+Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
 
-## Basic Use
+## 基本用法
 
 ```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>` is the platform-native temp directory. On Windows, pass native paths for actual `--output`, `--dag`, and `--cwd` values.
+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`: deterministic generated artifacts or notes
-- `shell`: verification and file-system checks
-- `pi`: planning, review, diagnosis, and bounded writing when a node sets `toolProfile: "write"`
-- `cursor`: optional bounded write backend when explicitly enabled
+- `static`：确定性生成的 artifacts 或 notes
+- `shell`：验证与文件系统检查
+- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
+- `cursor`：显式启用时的可选有界写后端
 
 ## Skills
 
-DAG specs may declare `defaults.skills`, `skillsByRole`, and node-level `skills`. The runner resolves local instructions from `skills/<skill-name>/SKILL.md` and records resolution metadata in each node's `skills.json` artifact.
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
 
-The `loop-agent` skill lives at `skills/loop-agent/SKILL.md`. The legacy root `skill/SKILL.md` path is retained only as a compatibility fallback for older worktrees.
+`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
 
 ## Artifacts
 
-DAG artifacts belong under:
+DAG artifacts 位于：
 
 ```text
 .harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
 ```
 
-Root `artifacts/` is not a valid default DAG artifact location.
+根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
 
 ## Shell Gates
 
-- `shell.verdictGate` reads `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json` from the injected current run directory; 不应自行发现 active run paths.
+- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。

package/docs/architecture/runtime-boundaries.md

@@ -112,7 +112,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 
 `scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
 
-## Governance hooks
+## Governance 钩子
 
 以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：