@tea-agent/loop-agent 0.1.0 → 0.2.0

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

@@ -6,8 +6,9 @@ Top-level `AGENTS.md` is the operating map. Durable knowledge belongs here: deci
 
 ## Core Documents
 
-- `development-principles.md` — repository development principles
-- `feature-workflow.md` — bounded feature workflow
+- `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

package/docs/architecture/runtime-boundaries.md

@@ -0,0 +1,147 @@
+# Runtime Boundaries
+
+本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把「命令、文档、import 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
+
+## 分层概览
+
+```text
+Skill layer
+  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
+
+CLI layer (src/cli/)
+  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
+
+Application layer (src/application/，逐步引入)
+  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
+
+Workflow runtime (src/workflows/)
+  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
+
+Executors (src/executors/)
+  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
+
+Infrastructure / Store (src/infrastructure/，逐步引入)
+  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
+
+Governance (scripts/check-*.sh, src/governance/)
+  └─ 防止 command registry、skill entry、import architecture 漂移
+```
+
+## 各层职责
+
+### Skill layer
+
+- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
+- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
+- **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
+
+### CLI layer
+
+- **位置**：`src/cli.ts`、`src/cli/**`
+- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
+- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
+- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
+
+### Application layer
+
+- **位置**：`src/application/**`（按计划逐步引入）
+- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
+- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
+- **禁止**：直接承担 CLI formatting 或 argv 解析。
+
+### Workflow runtime
+
+- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
+- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排。
+- **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
+- **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
+
+### Executors
+
+- **位置**：`src/executors/**`
+- **职责**：封装 Cursor SDK/CLI、Pi SDK/CLI、shell 执行与 write guard。
+- **允许依赖**：`src/shared/**`、外部 SDK。
+- **禁止**：依赖 `src/commands/**` 或 CLI 输出格式。
+
+### Infrastructure / Store
+
+- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
+- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
+- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
+
+### Governance
+
+- **位置**：`scripts/check-repo.sh` 及子脚本、`src/governance/**`、相关 Vitest。
+- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、skill entry 完整性。
+
+## 允许的依赖方向
+
+```text
+Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
+
+CLI                   ──────────>   Application (目标态)
+CLI                   ──────────>   Commands (handler 薄层)
+Commands              ──────────>   Application / Workflows / Infrastructure
+
+Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
+Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
+
+Executors             ──────────>   Shared / 外部 SDK
+Executors             ──X──>        Commands / CLI
+
+Application           ──────────>   Workflows / Infrastructure / Task / Records
+Application           ──X──>        CLI formatting
+
+Infrastructure        ──────────>   Shared / node:fs
+Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
+```
+
+**规则摘要**
+
+| From | May import | Must not import |
+|------|------------|-----------------|
+| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
+| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
+| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
+| `src/cli/**` | commands, adapters, shared, application（目标） | — |
+| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+
+## 已知过渡耦合
+
+当前没有允许的 `src/workflows/**` 或 `src/executors/**` → `src/commands/**` TypeScript import。
+
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+
+## Governance hooks
+
+以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
+
+| Script | 检查内容 | 失败条件 |
+|--------|----------|----------|
+| `scripts/check-architecture-boundaries.sh` | `workflows` / `executors` → `commands` import | 新的未 allowlist violation |
+| `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
+| `scripts/check-skill-entry.sh` | `SKILL.md` reference 文件存在、行数阈值 | reference 缺失（fail）；行数 > 220（warn） |
+
+相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
+
+### 验证命令
+
+```bash
+bash scripts/check-repo.sh
+bash scripts/check-architecture-boundaries.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-skill-entry.sh
+```
+
+Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
+
+## 演进里程碑
+
+| Phase | 边界变化 |
+|-------|----------|
+| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
+| 1 | CLI command definition 单源 |
+| 2 | Skill entry 瘦身 + frontmatter references |
+| 3 | DAG application use-case；Loop 开始脱离 command JSON |
+| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
+| 7 | Harness Store / Repository 集中 `.harness` 副作用 |

package/docs/exec-plans/active/README.md

@@ -3,3 +3,7 @@
 Use this directory for execution plans that are currently in progress.
 
 Source repositories may keep concrete active plan files next to this README. The npm package carries this README as a directory contract and does not copy loop-agent source-history active plans; target repositories generate their own active plans.
+
+Current active plans:
+
+- [2026-07-04-dag-role-skill-alignment.md](2026-07-04-dag-role-skill-alignment.md)

package/docs/exec-plans/completed/README.md

@@ -1,5 +1,9 @@
-# Completed Execution Plans
-
+# Completed Execution Plans
+
 Completed plans are moved here after their implementation and verification finish.
 
 The npm package carries this README as a directory contract. Concrete completed plans are target-repository history and are not copied from loop-agent's source history.
+
+- [`2026-07-02-loop-agent-subject-restructure.md`](2026-07-02-loop-agent-subject-restructure.md) — promoted the former `tools/code-agent` runtime to the repository root, renamed it to `loop-agent`, and removed the old memory plugin product lines.
+- [`2026-07-04-remove-level1-fallback.md`](2026-07-04-remove-level1-fallback.md) — removed the historical sequential Level 1 fallback and converged the runtime, docs, and command surface on DAG execution.
+- [`2026-07-04-runtime-boundary-remediation.md`](2026-07-04-runtime-boundary-remediation.md) — consolidated CLI/skill/runtime boundaries, extracted DAG/Loop runtime seams, and centralized harness store/guard policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js"
@@ -10,6 +10,7 @@
     "bin/",
     "dist/",
     "docs/*.md",
+    "docs/architecture/runtime-boundaries.md",
     "docs/decisions/README.md",
     "docs/design/README.md",
     "docs/exec-plans/README.md",

package/skills/ai-engineering-context/SKILL.md

@@ -1,48 +1,48 @@
 ---
 name: ai-engineering-context
-description: Use when an AI coding agent starts loop-agent work, prepares DAG or Loop context, delegates role-specific nodes, or decides where requirements, facts, evidence, and handoff notes belong.
+description: 当 AI coding agent 启动 loop-agent 工作、准备 DAG 或 Loop context、委派 role-specific 节点，或决定 requirements、facts、evidence、handoff notes 应落何处时使用。
 ---
 
 # AI Engineering Context
 
-Context is an engineering artifact, not chat residue. Keep requirements, role boundaries, write authority, evidence, and handoff facts explicit.
+Context 是工程 artifact，不是 chat 残留。须显式保留 requirements、role 边界、write authority、evidence 与 handoff facts。
 
 ## When to Use
 
-Use when starting a task, DAG, workflow, or Loop round; preparing role prompts; delegating to Cursor/Pi/shell/static executors; or handling stale plans, conflicting requirements, or missing evidence.
+在启动 task、DAG、workflow 或 Loop round；准备 role prompt；委派给 Cursor/Pi/shell/static executor；或处理 stale plan、冲突 requirements、缺失 evidence 时使用。
 
-Do not use for private platform paths, personal memory, Google Drive rules, or replacing task skills.
+不要用于 private platform paths、personal memory、Google Drive 规则，或替代 task skills。
 
 ## Context Priority
 
-Prefer facts in this order: latest user instruction; task source/contract; DAG/Loop artifacts; docs/plans/ADRs; code/tests; chat history as hints only.
+按以下顺序优先采信 facts：最新 user instruction；task source/contract；DAG/Loop artifacts；docs/plans/ADRs；code/tests；chat history 仅作 hint。
 
-If sources conflict, stop and name the conflict.
+若 sources 冲突，停止并点明冲突。
 
 ## Role Boundaries
 
-- Planner: contract, DAG shape, write boundary, verification plan; no implementation edits.
-- Scout: code/test/doc/artifact facts; no repo writes.
-- Implementer: bounded changes inside writeSet; no scope widening or completion claims.
-- Reviewer: bugs, regressions, missing tests, risk; no rewrites unless assigned.
-- Verifier: command evidence, reproduction, failure category; model judgment is not proof.
-- Supervisor: gates, escalation, repair scope; no write-guard or human-gate bypass.
-- Closeout: evidence, risks, next steps; no hidden failures.
+- Planner：contract、DAG shape、write boundary、verification plan；不做 implementation edits。
+- Scout：code/test/doc/artifact facts；不写 repo。
+- Implementer：在 writeSet 内做 bounded changes；不扩大 scope 或宣称完成。
+- Reviewer：bugs、regressions、missing tests、risk；除非被指派，否则不重写。
+- Verifier：command evidence、reproduction、failure category；model judgment 不是 proof。
+- Supervisor：gates、escalation、repair scope；不绕过 write-guard 或 human-gate。
+- Closeout：evidence、risks、next steps；不隐藏 failures。
 
 ## Prompt Contract
 
-Every delegated node prompt should include objective, task id, role, executor, allowed paths, forbidden paths, writeSet, upstream artifact refs, concise excerpts, output contract, expected evidence, non-goals, and stop conditions.
+每个 delegated node prompt 应包含：objective、task id、role、executor、allowed paths、forbidden paths、writeSet、upstream artifact refs、concise excerpts、output contract、expected evidence、non-goals、stop conditions。
 
-Read-only nodes must return findings in node output only. They must not create scratch files in the repo.
+read-only node 只能在 node output 返回 findings。不得在 repo 中创建 scratch files。
 
 ## Persistence Rules
 
-Requirements and constraints go in task `source/`. Execution state and node artifacts go in `.harness/`. Durable plans, reports, decisions go in `docs/`. Reusable process guidance goes in `skills/`. Chat is transient only.
+Requirements 与 constraints 写入 task `source/`。Execution state 与 node artifacts 写入 `.harness/`。Durable plans、reports、decisions 写入 `docs/`。可复用 process guidance 写入 `skills/`。Chat 仅 transient。
 
 ## Failure Handling
 
-- Missing context: run scout or read the durable source.
-- Ambiguous requirement: update the contract before implementation.
-- Verification failure: diagnose cause before changing code.
-- Missing skill instructions: treat as context defect; do not assume hidden behavior.
-- Missing fresh verification: do not close out.
+- Missing context：运行 scout 或读取 durable source。
+- Ambiguous requirement：implementation 前更新 contract。
+- Verification failure：改 code 前先 diagnose cause。
+- Missing skill instructions：视为 context defect；不要假设 hidden behavior。
+- Missing fresh verification：不要 close out。