@tea-agent/loop-agent 0.1.0 → 0.2.1

package/dist/workflows/loop/closeout.js

@@ -1,10 +1,11 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeLoopCloseout } from "../../infrastructure/harness/loop-store.js";
 import { getLoopPaths } from "./paths.js";
 import { readLoopRounds } from "./rounds.js";
 import { readLoopSignals, pendingLoopSignals } from "./signals.js";
 import { loadLoopState } from "./state.js";
 import { loadTaskConfig } from "../../task/runtime.js";
-import { repoRelativePath } from "../../shared/path-refs.js";
 function unique(values) {
     return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }
@@ -68,7 +69,7 @@ export async function generateLoopCloseout(repoRoot, taskId) {
             : [`Loop status is ${state.status}; treat this closeout as partial.`]),
     ]);
     const recordedAt = new Date().toISOString();
-    const relativeCloseoutPath = repoRelativePath(repoRoot, paths.closeoutPath);
+    const relativeCloseoutPath = path.relative(repoRoot, paths.closeoutPath);
     const record = {
         schemaVersion: 1,
         taskId,
@@ -129,6 +130,6 @@ export async function generateLoopCloseout(repoRoot, taskId) {
         "- It does not modify completed DAG or one-shot run facts.",
         "",
     ].join("\n");
-    await writeFile(paths.closeoutPath, markdown, "utf-8");
+    await writeLoopCloseout(repoRoot, taskId, markdown);
     return record;
 }

package/dist/workflows/loop/context.js

@@ -1,5 +1,4 @@
-import { writeFile } from "node:fs/promises";
-import { getLoopPaths } from "./paths.js";
+import { writeLoopContext } from "../../infrastructure/harness/loop-store.js";
 import { readLoopRounds } from "./rounds.js";
 import { refreshLoopState } from "./state.js";
 import { appendLoopEvent } from "./events.js";
@@ -36,7 +35,7 @@ export async function rewriteLoopContext(repoRoot, taskId) {
         `- Last decision: ${latest.decision}.`,
         "",
     ].join("\n");
-    await writeFile(getLoopPaths(repoRoot, taskId).contextPath, content, "utf-8");
+    await writeLoopContext(repoRoot, taskId, content);
     await refreshLoopState(repoRoot, taskId);
     await appendLoopEvent(repoRoot, taskId, {
         type: "context_rewrite",

package/dist/workflows/loop/events.js

@@ -1,4 +1,5 @@
-import { appendFile, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { appendLoopEventLine } from "../../infrastructure/harness/loop-store.js";
 import { getLoopPaths } from "./paths.js";
 export async function appendLoopEvent(repoRoot, taskId, input) {
     const now = new Date().toISOString();
@@ -12,7 +13,7 @@ export async function appendLoopEvent(repoRoot, taskId, input) {
         refs: input.refs ?? [],
         recordedAt: now,
     };
-    await appendFile(getLoopPaths(repoRoot, taskId).eventsPath, `${JSON.stringify(entry)}\n`, "utf-8");
+    await appendLoopEventLine(repoRoot, taskId, entry);
     return entry;
 }
 export async function readLoopEvents(repoRoot, taskId) {

package/dist/workflows/loop/policy/auto-policy.js

@@ -0,0 +1,104 @@
+import { pendingLoopSignals } from "../signals.js";
+export function decideNextLoopAutoAction(state, signals = [], options = {}) {
+    const pendingSignals = pendingLoopSignals(signals);
+    const urgent = pendingSignals.find((signal) => signal.urgent);
+    if (urgent) {
+        return {
+            action: "pause",
+            reason: `urgent ${urgent.type} signal: ${urgent.message}`,
+            decision: "pause",
+        };
+    }
+    const scopeChanged = pendingSignals.find((signal) => signal.type === "scope_changed");
+    if (scopeChanged) {
+        return {
+            action: "pause",
+            reason: `scope changed signal requires objective/context review: ${scopeChanged.message}`,
+            decision: "pause",
+        };
+    }
+    const reviewSignal = pendingSignals.find((signal) => signal.type === "review_feedback" || signal.type === "human_followup");
+    if (reviewSignal) {
+        return {
+            action: "pi-review",
+            reason: `${reviewSignal.type} signal requires read-only review: ${reviewSignal.message}`,
+            decision: "continue",
+        };
+    }
+    if (state.round >= state.maxRounds) {
+        return {
+            action: "blocked",
+            reason: `loop maxRounds reached (${state.round}/${state.maxRounds})`,
+            decision: "blocked",
+        };
+    }
+    if (state.failureStreak.category && state.failureStreak.count >= 2) {
+        return {
+            action: "blocked",
+            reason: `repeated failure category ${state.failureStreak.category} x${state.failureStreak.count}`,
+            decision: "blocked",
+        };
+    }
+    if (state.freshness.sourceStale) {
+        return {
+            action: "pause",
+            reason: "task source changed; rebuild or review action prompt before continuing",
+            decision: "pause",
+        };
+    }
+    if (state.lastAction === "shell-verify") {
+        return {
+            action: "pi-review",
+            reason: "shell verification already ran; request read-only review before next implementation decision",
+            decision: "continue",
+        };
+    }
+    if (state.lastAction === "pi-review") {
+        if (options.latestPiReview?.recommendedAction === "implement_fix") {
+            const policy = options.loopAutoWritePolicy ?? "off";
+            const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
+            const allowedByPolicy = policy === "enabled" ||
+                (policy === "approval-required" &&
+                    (Boolean(options.allowCursorFix) || Boolean(approvalSignal)));
+            if (options.cursorFixPolicyError) {
+                return {
+                    action: "pause",
+                    reason: `cursor-fix policy guard failed: ${options.cursorFixPolicyError}`,
+                    decision: "pause",
+                };
+            }
+            if (allowedByPolicy) {
+                return {
+                    action: "cursor-fix",
+                    reason: `pi-review recommended implement_fix; loopAutoWritePolicy=${policy}`,
+                    decision: "continue",
+                };
+            }
+        }
+        return {
+            action: "dag",
+            reason: "read-only review produced next action; generate a governed DAG review packet",
+            decision: "continue",
+        };
+    }
+    const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
+    if (approvalSignal) {
+        return {
+            action: "dag",
+            reason: `approval signal received; generate next governed DAG packet: ${approvalSignal.message}`,
+            decision: "continue",
+        };
+    }
+    if (state.lastAction === "cursor-fix" || state.lastAction === "dag") {
+        return {
+            action: "shell-verify",
+            reason: `${state.lastAction} round must be followed by deterministic shell verification`,
+            decision: "continue",
+        };
+    }
+    return {
+        action: "dag",
+        reason: "default to DAG governed review packet for the next bounded round",
+        decision: "continue",
+    };
+}

package/dist/workflows/loop/policy/cursor-fix-policy.js

@@ -0,0 +1,31 @@
+import { pathMatchesPattern } from "../../../shared/git-progress.js";
+export function normalizePattern(pattern) {
+    return pattern.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/\*\*$/, "");
+}
+export function patternsOverlap(allowed, forbidden) {
+    const a = normalizePattern(allowed);
+    const f = normalizePattern(forbidden);
+    return (a === f ||
+        a.startsWith(`${f}/`) ||
+        f.startsWith(`${a}/`) ||
+        pathMatchesPattern(a, forbidden) ||
+        pathMatchesPattern(f, allowed));
+}
+export function validateLoopCursorFixPolicy(input) {
+    if (input.allowedPaths.length === 0) {
+        throw new Error("loop cursor-fix requires non-empty task allowedPaths");
+    }
+    for (const allowed of input.allowedPaths) {
+        for (const forbidden of input.forbiddenPaths) {
+            if (patternsOverlap(allowed, forbidden)) {
+                throw new Error(`loop cursor-fix allowed/forbidden paths overlap: ${allowed} vs ${forbidden}`);
+            }
+        }
+    }
+    if (input.complexity !== undefined &&
+        input.complexity !== "small" &&
+        !input.hasDagRound &&
+        !input.dagFallbackReason?.trim()) {
+        throw new Error("loop cursor-fix for medium/large tasks requires a prior loop dag round or task dagFallbackReason");
+    }
+}

package/dist/workflows/loop/rounds.js

@@ -1,4 +1,5 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { writeLoopRounds } from "../../infrastructure/harness/loop-store.js";
 import { getLoopPaths } from "./paths.js";
 import { refreshLoopState } from "./state.js";
 import { appendLoopEvent } from "./events.js";
@@ -33,14 +34,13 @@ export async function appendLoopRound(repoRoot, taskId, input) {
         failureCategory: input.failureCategory ?? "",
         completedCriteria: input.completedCriteria ?? [],
     };
-    const paths = getLoopPaths(repoRoot, taskId);
     await appendLoopEvent(repoRoot, taskId, {
         type: "round_start",
         round: entry.round,
         message: `recording round ${entry.round} action ${entry.action}`,
         refs: entry.refs,
     });
-    await writeFile(paths.roundsPath, `${rounds.map((round) => JSON.stringify(round)).join("\n")}${rounds.length > 0 ? "\n" : ""}${JSON.stringify(entry)}\n`, "utf-8");
+    await writeLoopRounds(repoRoot, taskId, [...rounds, entry]);
     const previousState = await refreshLoopState(repoRoot, taskId, {
         status: statusForDecision(entry.decision),
         round: entry.round,

package/dist/workflows/loop/signals.js

@@ -1,4 +1,5 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { writeLoopSignals as persistLoopSignals } from "../../infrastructure/harness/loop-store.js";
 import { getLoopPaths } from "./paths.js";
 import { LOOP_SIGNAL_TYPES, } from "./types.js";
 export function parseLoopSignalType(value) {
@@ -31,7 +32,7 @@ export async function appendLoopSignal(repoRoot, taskId, input) {
     if (!entry.message) {
         throw new Error("loop signal message cannot be empty");
     }
-    await writeLoopSignals(repoRoot, taskId, [...signals, entry]);
+    await persistLoopSignals(repoRoot, taskId, [...signals, entry]);
     return entry;
 }
 export function pendingLoopSignals(signals) {
@@ -46,10 +47,6 @@ export async function drainLoopSignals(repoRoot, taskId, ids) {
     const drained = signals.map((signal) => idSet.has(signal.id) && !signal.drainedAt
         ? { ...signal, drainedAt: now }
         : signal);
-    await writeLoopSignals(repoRoot, taskId, drained);
+    await persistLoopSignals(repoRoot, taskId, drained);
     return drained;
 }
-async function writeLoopSignals(repoRoot, taskId, signals) {
-    await writeFile(getLoopPaths(repoRoot, taskId).signalsPath, signals.map((signal) => JSON.stringify(signal)).join("\n") +
-        (signals.length > 0 ? "\n" : ""), "utf-8");
-}

package/dist/workflows/loop/state.js

@@ -1,6 +1,7 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureLoopDir, writeLoopContext, writeLoopObjective, writeLoopRounds, writeLoopSignals, writeLoopEvents, writeLoopState, } from "../../infrastructure/harness/loop-store.js";
 import { getTaskDir } from "../../task/runtime.js";
-import { repoRelativePath } from "../../shared/path-refs.js";
 import { hashFileIfPresent, hashTaskSource } from "./hash.js";
 import { getLoopPaths } from "./paths.js";
 import { defaultContext, defaultObjective } from "./templates.js";
@@ -21,7 +22,7 @@ async function exists(filePath) {
     }
 }
 function rel(repoRoot, filePath) {
-    return repoRelativePath(repoRoot, filePath);
+    return path.relative(repoRoot, filePath);
 }
 export async function buildLoopState(repoRoot, taskId, paths = getLoopPaths(repoRoot, taskId), previous) {
     const now = new Date().toISOString();
@@ -59,8 +60,7 @@ export async function buildLoopState(repoRoot, taskId, paths = getLoopPaths(repo
     };
 }
 export async function saveLoopState(repoRoot, taskId, state) {
-    const paths = getLoopPaths(repoRoot, taskId);
-    await writeFile(paths.statePath, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+    await writeLoopState(repoRoot, taskId, state);
 }
 export async function loadLoopState(repoRoot, taskId) {
     const paths = getLoopPaths(repoRoot, taskId);
@@ -86,21 +86,21 @@ export async function initializeLoop(repoRoot, taskId, options = {}) {
     if (stateExists && !options.recover) {
         throw new Error(`loop already initialized for task: ${taskId}`);
     }
-    await mkdir(paths.loopDir, { recursive: true });
+    await ensureLoopDir(repoRoot, taskId);
     if (!(await exists(paths.objectivePath))) {
-        await writeFile(paths.objectivePath, defaultObjective(taskId), "utf-8");
+        await writeLoopObjective(repoRoot, taskId, defaultObjective(taskId));
     }
     if (!(await exists(paths.contextPath))) {
-        await writeFile(paths.contextPath, defaultContext(), "utf-8");
+        await writeLoopContext(repoRoot, taskId, defaultContext());
     }
     if (!(await exists(paths.roundsPath))) {
-        await writeFile(paths.roundsPath, "", "utf-8");
+        await writeLoopRounds(repoRoot, taskId, []);
     }
     if (!(await exists(paths.signalsPath))) {
-        await writeFile(paths.signalsPath, "", "utf-8");
+        await writeLoopSignals(repoRoot, taskId, []);
     }
     if (!(await exists(paths.eventsPath))) {
-        await writeFile(paths.eventsPath, "", "utf-8");
+        await writeLoopEvents(repoRoot, taskId, []);
     }
     const previous = stateExists ? await loadLoopState(repoRoot, taskId) : undefined;
     const state = await buildLoopState(repoRoot, taskId, paths, {

package/docs/README.md

@@ -1,61 +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
-- `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。