@tea-agent/loop-agent 0.5.0 → 0.7.0

package/dist/workflows/dag/event-observer.js

@@ -0,0 +1,132 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
+import { resolveModelForTask, } from "./types.js";
+const DEFAULT_MAX_OUTPUT_PREVIEW_BYTES = 4096;
+/**
+ * Truncate `text` to fit within `maxBytes` (UTF-8), appending a marker suffix
+ * describing the number of elided bytes. Local implementation to avoid importing
+ * worker observability (which would create a circular dependency).
+ */
+export function truncateEventPreview(text, maxBytes = DEFAULT_MAX_OUTPUT_PREVIEW_BYTES) {
+    return truncateUtf8Preview(text, maxBytes);
+}
+function reportError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[dag-event-observer] ${context} failed: ${message}\n`);
+}
+function findTask(spec, state, nodeId) {
+    const node = state.nodes[nodeId];
+    const task = spec?.tasks.find((candidate) => candidate.id === nodeId);
+    return { task, node };
+}
+function rankOf(state, nodeId) {
+    for (let i = 0; i < state.ranks.length; i += 1) {
+        if (state.ranks[i]?.includes(nodeId))
+            return String(i);
+    }
+    return undefined;
+}
+export function createDagEventObserver(options) {
+    const { eventsJsonlPath } = options;
+    const maxOutputPreviewBytes = options.maxOutputPreviewBytes ?? DEFAULT_MAX_OUTPUT_PREVIEW_BYTES;
+    let writeError = null;
+    const append = async (event) => {
+        try {
+            await mkdir(path.dirname(eventsJsonlPath), { recursive: true });
+            const line = `${JSON.stringify(event)}\n`;
+            await appendFile(eventsJsonlPath, line, "utf8");
+        }
+        catch (error) {
+            writeError = error;
+            reportError(`append ${event.type}`, error);
+        }
+    };
+    const buildBase = (type, state) => ({
+        schemaVersion: 1,
+        id: randomUUID(),
+        at: new Date().toISOString(),
+        dagRunId: state.runId || options.dagRunId || "dag",
+    });
+    const observer = {
+        onRunStart: async (state) => {
+            const event = {
+                ...buildBase("dag.run.started", state),
+                type: "dag.run.started",
+                status: state.status,
+                label: state.title,
+            };
+            await append(event);
+        },
+        onNodeStart: async (nodeId, state) => {
+            const { task, node } = findTask(options.spec, state, nodeId);
+            const event = {
+                ...buildBase("dag.node.started", state),
+                type: "dag.node.started",
+                nodeId,
+                status: node?.status,
+                rank: rankOf(state, nodeId),
+                executor: node?.executor,
+                model: task
+                    ? resolveModelForTask(task, options.spec?.executorModels)
+                    : undefined,
+                label: node?.id,
+            };
+            await append(event);
+        },
+        onNodeOutput: async (nodeId, chunk, state) => {
+            const { task, node } = findTask(options.spec, state, nodeId);
+            const event = {
+                ...buildBase("dag.node.output", state),
+                type: "dag.node.output",
+                nodeId,
+                status: node?.status,
+                rank: rankOf(state, nodeId),
+                executor: node?.executor,
+                model: task
+                    ? resolveModelForTask(task, options.spec?.executorModels)
+                    : undefined,
+                label: node?.id,
+                outputPreview: truncateEventPreview(redactSecrets(chunk), maxOutputPreviewBytes),
+            };
+            await append(event);
+        },
+        onNodeFinish: async (nodeId, state) => {
+            const { task, node } = findTask(options.spec, state, nodeId);
+            const event = {
+                ...buildBase("dag.node.finished", state),
+                type: "dag.node.finished",
+                nodeId,
+                status: node?.status,
+                rank: rankOf(state, nodeId),
+                executor: node?.executor,
+                model: task
+                    ? resolveModelForTask(task, options.spec?.executorModels)
+                    : undefined,
+                label: node?.id,
+                durationMs: node?.durationMs,
+            };
+            await append(event);
+        },
+        onRunFinish: async (state) => {
+            const event = {
+                ...buildBase("dag.run.finished", state),
+                type: "dag.run.finished",
+                status: state.status,
+                label: state.title,
+            };
+            await append(event);
+        },
+    };
+    return {
+        observer,
+        flush: async () => {
+            // No buffering: append is immediate. Surface the last write error
+            // (best-effort) only if the caller asks, but never throw.
+            if (writeError) {
+                reportError("flush", writeError);
+            }
+        },
+    };
+}

package/dist/workflows/dag/init-hybrid.js

@@ -1,4 +1,4 @@
-import { access, readFile, writeFile } from "node:fs/promises";
+import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { assertValidDagSpec } from "./validate.js";
@@ -9,11 +9,40 @@ import { resolveAdapter } from "../../adapters/index.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { buildAuthoritySurfaceAuditNode, buildAuthoritySurfaceGateNode, resolveAuthoritySurfaceAudit, } from "./authority-surface.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
+import { materializeTaskReferenceDocs } from "../../task/source-references.js";
 import { resolveVerifyPreset } from "../../executors/shell-verification.js";
 import { resolveExecutorModelMatrices } from "../../executors/model-routing.js";
 const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
+const REFERENCE_DIRECTORY = "references";
 const MAX_SOURCE_EXCERPT_CHARS = 2000;
+const MAX_SOURCE_REFERENCE_DOCUMENTS = 8;
+const INTERACTIVE_UI_DELIVERY_CONTRACT = [
+    "[INTERACTIVE_UI_DELIVERY_CONTRACT]",
+    "This is an interactive UI delivery task.",
+    "A helper-only, data-only, validation-only, or serializable-view implementation does not satisfy the task.",
+    "Before editing: identify the existing UI framework and component conventions, the real render/integration point, and the user-interaction test seam.",
+    "Required delivery: a framework-native visible component; integration into the declared route or parent; user interaction and visible error rendering; component-level tests using the repository's UI test stack.",
+    "The completion summary must list the component path, integration path, interaction test path, and DOM assertions mapped to acceptance criteria. If any item is missing, do not claim completion.",
+    "[/INTERACTIVE_UI_DELIVERY_CONTRACT]",
+].join("\n");
+function isInteractiveUiTask(taskConfig) {
+    return taskConfig.capabilities?.includes("interactive-ui") ?? false;
+}
+function writerDeliveryContract(taskConfig) {
+    return isInteractiveUiTask(taskConfig)
+        ? INTERACTIVE_UI_DELIVERY_CONTRACT
+        : null;
+}
+function resolveWriterComplexity(taskConfig) {
+    if (isInteractiveUiTask(taskConfig))
+        return "HIGH";
+    if (taskConfig.complexity === "small")
+        return "MED";
+    if (taskConfig.complexity === "large")
+        return "HIGH";
+    return "MED";
+}
 const HYBRID_DEFAULTS = {
     executor: "pi",
     piBackend: "sdk-first",
@@ -101,27 +130,85 @@ function mapTaskComplexity(complexity) {
         return "HIGH";
     return "MED";
 }
-function excerptMarkdown(content, maxChars = MAX_SOURCE_EXCERPT_CHARS) {
+export function excerptMarkdown(content, options = {}) {
+    const maxChars = options.maxChars ?? MAX_SOURCE_EXCERPT_CHARS;
     const trimmed = content.trim();
-    if (trimmed.length <= maxChars)
-        return trimmed;
-    return `${trimmed.slice(0, maxChars)}\n\n...[truncated for draft prompt]`;
+    if (trimmed.length <= maxChars) {
+        return {
+            text: trimmed,
+            truncated: false,
+            originalChars: trimmed.length,
+            maxChars,
+        };
+    }
+    const omitted = trimmed.length - maxChars;
+    const ref = options.sourceRef?.trim();
+    const pointer = ref
+        ? [
+            `...[truncated for draft prompt: showing first ${maxChars} of ${trimmed.length} chars; omitted ${omitted} chars]`,
+            `Full source (authoritative, do not invent missing content): ${ref}`,
+            "When the omitted tail may affect acceptance/non-goals/constraints, re-read that file before deciding.",
+        ].join("\n")
+        : `...[truncated for draft prompt: showing first ${maxChars} of ${trimmed.length} chars; omitted ${omitted} chars]`;
+    return {
+        text: `${trimmed.slice(0, maxChars)}\n\n${pointer}`,
+        truncated: true,
+        originalChars: trimmed.length,
+        maxChars,
+    };
 }
-function extractObjective(requirementMarkdown, title) {
+function isHeadingLine(line) {
+    return /^#{1,6}\s+/.test(line.trim());
+}
+function isMetadataLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return true;
+    if (/^(TaskSpec business id|Feature id|Task type|Risk level)\s*:/i.test(trimmed)) {
+        return true;
+    }
+    if (/^(权威来源|SHA-256|冲突时以)/.test(trimmed))
+        return true;
+    if (/^>/.test(trimmed) && /(权威来源|SHA-256|原始 PRD|reference)/i.test(trimmed)) {
+        return true;
+    }
+    return false;
+}
+export function extractObjective(requirementMarkdown, title) {
+    const sectionMatchers = [
+        /##\s*(目标|Objective|Goals?)\s*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/i,
+        /##\s*Description\s*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/i,
+    ];
+    for (const matcher of sectionMatchers) {
+        const match = requirementMarkdown.match(matcher);
+        if (!match)
+            continue;
+        const body = (match[2] ?? match[1] ?? "").trim();
+        for (const line of body.split("\n")) {
+            const trimmed = line
+                .replace(/^[-*]\s*\[[ xX]\]\s*/, "")
+                .replace(/^[-*]\s*/, "")
+                .trim();
+            if (!trimmed || isHeadingLine(trimmed) || isMetadataLine(trimmed))
+                continue;
+            return trimmed.slice(0, 500);
+        }
+    }
     const lines = requirementMarkdown.split("\n");
     for (const line of lines) {
         const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#"))
+        if (!trimmed || isHeadingLine(trimmed) || isMetadataLine(trimmed))
             continue;
         return trimmed.slice(0, 500);
     }
     return `Implement task: ${title}`;
 }
-function extractSuccessCriteria(requirementMarkdown, taskId) {
+const SUCCESS_CRITERIA_SECTION = /##\s*(验收标准|完成标准|Acceptance(?:\s+References)?|Success Criteria)\s*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/i;
+export function extractSuccessCriteria(requirementMarkdown, taskId) {
     const criteria = [];
-    const sectionMatch = requirementMarkdown.match(/##\s*验收标准\s*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/);
+    const sectionMatch = requirementMarkdown.match(SUCCESS_CRITERIA_SECTION);
     if (sectionMatch) {
-        for (const line of sectionMatch[1].split("\n")) {
+        for (const line of sectionMatch[2].split("\n")) {
             const trimmed = line.replace(/^[-*]\s*\[[ xX]\]\s*/, "").trim();
             if (trimmed.startsWith("-") || trimmed.startsWith("*")) {
                 criteria.push(trimmed.replace(/^[-*]\s*/, "").trim());
@@ -226,20 +313,77 @@ function deriveParallelScoutPaths(taskConfig) {
                 : allowed,
     };
 }
+function toTaskRelativeSourcePath(sources, absolutePath) {
+    return path
+        .relative(sources.taskDir, absolutePath)
+        .replaceAll(path.sep, "/");
+}
 function buildSourceContextBlock(sources) {
+    const requirementRef = toTaskRelativeSourcePath(sources, sources.requirementPath);
+    const requirementExcerpt = excerptMarkdown(sources.requirementMarkdown, {
+        sourceRef: requirementRef,
+    });
     const parts = [
         "## Task source: 需求.md",
-        excerptMarkdown(sources.requirementMarkdown),
+        requirementExcerpt.text,
     ];
     if (sources.constraintMarkdown) {
-        parts.push("## Task source: 执行约束.md", excerptMarkdown(sources.constraintMarkdown));
+        const constraintRef = toTaskRelativeSourcePath(sources, sources.constraintPath);
+        const constraintExcerpt = excerptMarkdown(sources.constraintMarkdown, {
+            sourceRef: constraintRef,
+        });
+        parts.push("## Task source: 执行约束.md", constraintExcerpt.text);
+    }
+    for (const reference of sources.referenceDocuments ?? []) {
+        const relativePath = path
+            .relative(path.join(sources.taskDir, "source"), reference.path)
+            .replaceAll(path.sep, "/");
+        const referenceRef = toTaskRelativeSourcePath(sources, reference.path);
+        const referenceExcerpt = excerptMarkdown(reference.markdown, {
+            sourceRef: referenceRef,
+        });
+        parts.push(`## Task source reference: ${relativePath}`, referenceExcerpt.text);
     }
-    parts.push("## Task config summary", `- taskId: ${sources.taskConfig.taskId}`, `- flow: ${sources.taskConfig.flow}`, `- complexity: ${sources.taskConfig.complexity}`, `- contextProfile: ${sources.taskConfig.contextProfile}`, `- allowedPaths: ${sources.taskConfig.allowedPaths.join(", ") || "(none — review before execute)"}`, `- forbiddenPaths: ${sources.taskConfig.forbiddenPaths.join(", ") || "(none)"}`, '- Pi DAG nodes are read-only unless toolProfile="write" is explicitly selected for a bounded writer node.', "- Agent DAG read-only nodes must not write root artifacts/**; root artifacts/ is not a per-node scratchpad.");
+    parts.push("## Task config summary", `- taskId: ${sources.taskConfig.taskId}`, `- flow: ${sources.taskConfig.flow}`, `- complexity: ${sources.taskConfig.complexity}`, `- contextProfile: ${sources.taskConfig.contextProfile}`, `- allowedPaths: ${sources.taskConfig.allowedPaths.join(", ") || "(none — review before execute)"}`, `- forbiddenPaths: ${sources.taskConfig.forbiddenPaths.join(", ") || "(none)"}`, '- Pi DAG nodes are read-only unless toolProfile="write" is explicitly selected for a bounded writer node.', "- Agent DAG read-only nodes must not write root artifacts/**; root artifacts/ is not a per-node scratchpad.", "- source/references/* are immutable user/source facts; source/需求.md is the derived execution contract.");
     if (sources.taskConfig.hardConstraints.length > 0) {
         parts.push("- hardConstraints:", ...sources.taskConfig.hardConstraints.map((c) => `  - ${c}`));
     }
     return parts.join("\n\n");
 }
+async function loadMaterializedSourceReferences(sourceDir) {
+    const referenceDir = path.join(sourceDir, REFERENCE_DIRECTORY);
+    const referencePaths = [];
+    async function collect(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const entryPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await collect(entryPath);
+            }
+            else if (entry.isFile()) {
+                // Skip index/manifest sidecars; keep only user/source reference content.
+                if (entry.name === "index.json" || entry.name === "source-manifest.json") {
+                    continue;
+                }
+                referencePaths.push(entryPath);
+            }
+        }
+    }
+    await collect(referenceDir);
+    referencePaths.sort((left, right) => left.localeCompare(right));
+    return Promise.all(referencePaths.slice(0, MAX_SOURCE_REFERENCE_DOCUMENTS).map(async (filePath) => ({
+        path: filePath,
+        markdown: await readFile(filePath, "utf-8"),
+    })));
+}
 export async function loadTaskHybridSources(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
     const requirementPath = path.join(paths.sourceDir, REQUIREMENT_FILE);
@@ -265,6 +409,12 @@ export async function loadTaskHybridSources(repoRoot, taskId) {
         // optional
     }
     const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    await materializeTaskReferenceDocs({
+        repoRoot,
+        taskId,
+        taskConfig,
+    });
+    const referenceDocuments = await loadMaterializedSourceReferences(paths.sourceDir);
     const manifest = await loadHarnessManifest(repoRoot);
     const strategy = resolveDagVerifyStrategy(taskConfig);
     let verifyCommands;
@@ -300,6 +450,7 @@ export async function loadTaskHybridSources(repoRoot, taskId) {
         constraintPath,
         requirementMarkdown,
         constraintMarkdown,
+        referenceDocuments,
         taskConfig,
         enabledExecutors: resolveEnabledExecutors(manifest.executors),
         executorModelMatrix: resolveExecutorModelMatrices(manifest),
@@ -312,11 +463,7 @@ export function buildStandardHybridDagFromTask(sources) {
     const implementPaths = resolveImplementPaths(taskConfig);
     const scoutPaths = deriveParallelScoutPaths(taskConfig);
     const scoutComplexity = mapTaskComplexity(taskConfig.complexity);
-    const implementComplexity = taskConfig.complexity === "small"
-        ? "MED"
-        : taskConfig.complexity === "large"
-            ? "HIGH"
-            : "MED";
+    const implementComplexity = resolveWriterComplexity(taskConfig);
     const writerExecutor = resolveImplementationExecutor(sources);
     const implementId = implementationNodeId(writerExecutor);
     const sourceContext = buildSourceContextBlock(sources);
@@ -418,8 +565,9 @@ export function buildStandardHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "Implement the approved plan with minimal focused changes.",
                     "Stay within writeSet. Do not write root artifacts/** unless artifacts paths are explicitly declared in writeSet.",
+                    writerDeliveryContract(taskConfig),
                     sourceContext,
-                ].join("\n\n"),
+                ].filter((value) => Boolean(value)).join("\n\n"),
             },
             {
                 id: "verify-pi",
@@ -509,6 +657,14 @@ function buildReviewNode(sources) {
             "Review upstream implementation and verification evidence.",
             "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
             "List Critical/Important findings when present; any Critical/Important finding must force request-revision. Read-only: do not modify files.",
+            [
+                "Three-way source fidelity check (required):",
+                "1) immutable originals under source/references/ (especially requirement* and acceptance*);",
+                "2) derived source/需求.md execution contract (and source/执行约束.md);",
+                "3) actual implementation/diff + verification evidence.",
+                "If 需求.md conflicts with source/references/*, prefer references and request-revision when the implementation only satisfies the derived summary.",
+                "If prompt excerpts are truncated, re-read the Full source paths before verdict.",
+            ].join(" "),
             buildSourceContextBlock(sources),
         ].join("\n\n"),
     };
@@ -695,7 +851,11 @@ function buildRepairNode(sources) {
         role: "implementer",
         executor: writerExecutor,
         toolProfile: "write",
-        complexity: sources.taskConfig.complexity === "small" ? "MED" : "HIGH",
+        complexity: isInteractiveUiTask(sources.taskConfig)
+            ? "HIGH"
+            : sources.taskConfig.complexity === "small"
+                ? "MED"
+                : "HIGH",
         writePolicy: "exclusive",
         writeSet: implement.writeSet,
         allowedPaths: implement.allowedPaths,
@@ -705,8 +865,9 @@ function buildRepairNode(sources) {
             "If process-supervisor-pi returned VERDICT: request-revision, apply bounded fixes within writeSet addressing its REPAIR_ARTIFACT_JSON.fixScope and preserving REPAIR_ARTIFACT_JSON.invariant.",
             "Use REPAIR_ARTIFACT_JSON.failureClass and rootCause to choose the smallest repair strategy. Raw log is fallback evidence only when rawLogFallbackAllowed is true.",
             "If VERDICT: pass, return no-op with evidence. Re-run focused tests when you change code.",
+            writerDeliveryContract(sources.taskConfig),
             buildSourceContextBlock(sources),
-        ].join("\n\n"),
+        ].filter((value) => Boolean(value)).join("\n\n"),
     };
 }
 function buildHardVerifyNode(sources) {

package/dist/workflows/dag/observer-compose.js

@@ -0,0 +1,52 @@
+function reportError(context, observerIndex, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[dag-observer-compose] observer#${observerIndex} ${context} failed: ${message}\n`);
+}
+const HOOK_NAMES = [
+    "onRunStart",
+    "onNodeStart",
+    "onNodeOutput",
+    "onNodeFinish",
+    "onRunFinish",
+];
+/**
+ * Compose multiple `DagRunObserver`s into one. Each hook is invoked in order.
+ * A throw in a single observer's hook is reported to stderr and does not stop
+ * subsequent observers — observers are derived views and must not affect
+ * canonical DAG execution. Returns `undefined` when no observers are provided.
+ */
+export function composeDagRunObservers(observers) {
+    const active = observers.filter((observer) => Boolean(observer));
+    if (active.length === 0)
+        return undefined;
+    const observer = {
+        onRunStart: async (state) => {
+            await runHook("onRunStart", active, (obs) => obs.onRunStart?.(state));
+        },
+        onNodeStart: async (nodeId, state) => {
+            await runHook("onNodeStart", active, (obs) => obs.onNodeStart?.(nodeId, state));
+        },
+        onNodeOutput: async (nodeId, chunk, state) => {
+            await runHook("onNodeOutput", active, (obs) => obs.onNodeOutput?.(nodeId, chunk, state));
+        },
+        onNodeFinish: async (nodeId, state) => {
+            await runHook("onNodeFinish", active, (obs) => obs.onNodeFinish?.(nodeId, state));
+        },
+        onRunFinish: async (state) => {
+            await runHook("onRunFinish", active, (obs) => obs.onRunFinish?.(state));
+        },
+    };
+    return observer;
+}
+async function runHook(hookName, active, invoke) {
+    for (let i = 0; i < active.length; i += 1) {
+        try {
+            await invoke(active[i]);
+        }
+        catch (error) {
+            reportError(hookName, i, error);
+        }
+    }
+}
+// Re-exported for tests/inspection of hook coverage.
+export const COMPOSED_HOOK_NAMES = HOOK_NAMES;

package/docs/README.md

@@ -1,72 +1,75 @@
-# 文档索引
-
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
-
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
-
-## 核心文档
-
-- `development-principles.md` — 仓库开发原则
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
-- `feature-workflow.md` — 有边界的功能工作流
-- `verification-matrix.md` — 验证命令选择
-- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
-- `loop-agent-harness.md` — runtime 与 command surface 概览
-- `agent-dag-runner.md` — Agent DAG runner 指南
-- `cursor-executor-usage.md` — Cursor executor 用法
-- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
-
-## 设计思想来源
-
-- `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
-
-## 方法论
-
-- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
-- `harness-methodology-verification.md` — 完成声明前的验证纪律
-- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
-
-## 产物目录
-
-- `design/README.md` — 设计草稿与实现契约
-- `exec-plans/active/README.md` — 进行中的执行计划
-- `exec-plans/completed/README.md` — 已完成的执行计划
-- `progress/README.md` — 进度交接日志
-- `reports/README.md` — 验证与审计报告
-- `decisions/README.md` — 架构决策
-- `skills/README.md` — repo-local skill registry and vetting notes
-- `templates/` — 可复用的规划、报告与 DAG 模板
-
-## 仓库 Skills
-
-- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
-- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
-
-## 模板
-
-- `templates/project-start-checklist.md` — 开工前检查清单
-- `templates/feature-spec.md` — 有边界的功能规格
-- `templates/sprint-contract.md` — 实现契约与验收标准
-- `templates/exec-plan.md` — 非平凡工作的执行计划
-- `templates/progress-log.md` — 进度与交接日志
-- `templates/qa-report.md` — 验证与 QA 证据
-- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
-- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
-- `templates/adr.md` — 架构决策记录（ADR）
-
-## 维护
-
-文档变更后运行：
-
-```bash
-bash scripts/check-repo.sh
-```
-
-Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-完整本地门禁：
-
-```bash
-bash scripts/ci.sh
-```
+# 文档索引
+
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+
+## 核心文档
+
+- `development-principles.md` — 仓库开发原则
+- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
+- `feature-workflow.md` — 有边界的功能工作流
+- `verification-matrix.md` — 验证命令选择
+- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
+- `loop-agent-harness.md` — runtime 与 command surface 概览
+- `agent-dag-runner.md` — Agent DAG runner 指南
+- `cursor-executor-usage.md` — Cursor executor 用法
+- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
+
+## 设计思想来源
+
+- `../website/docs/practices/` — Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 与社区 agent harness 实践资料。当前仓库的“人类掌舵、智能体执行”、仓库即记录系统、小步增量、结构化 handoff 和 shell verification 纪律均受这些实践启发；权威执行规则仍以本目录治理文档、根目录 AGENTS.md、harness.json、skills 目录和脚本检查为准。
+
+## 方法论
+
+- `harness-methodology-tdd.md` — 行为变更与 bug 修复的 TDD 纪律
+- `harness-methodology-verification.md` — 完成声明前的验证纪律
+- `harness-methodology-debugging.md` — 修复前的系统化调试工作流
+
+## 产物目录
+
+- `design/README.md` — 设计草稿与实现契约
+- `exec-plans/active/README.md` — 进行中的执行计划
+- `exec-plans/completed/README.md` — 已完成的执行计划
+- `progress/README.md` — 进度交接日志
+- `reports/README.md` — 验证与审计报告
+- `decisions/README.md` — 架构决策
+- `skills/README.md` — repo-local skill registry and vetting notes
+- `templates/` — 可复用的规划、报告与 DAG 模板
+
+## 仓库 Skills
+
+- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- 每个额外 skill 在仓库根 `../skills/` 下使用独立子目录；这些本地副本由 DAG 模板引用，维护不依赖外部 agent skill 目录
+
+## 模板
+
+- `templates/project-start-checklist.md` — 开工前检查清单
+- `templates/feature-spec.md` — 有边界的功能规格
+- `templates/sprint-contract.md` — 实现契约与验收标准
+- `templates/exec-plan.md` — 非平凡工作的执行计划
+- `templates/progress-log.md` — 进度与交接日志
+- `templates/qa-report.md` — 验证与 QA 证据
+- `templates/worker-dogfood-setup.md` — 发布控制器下的真实 Worker sample setup 与 retry 纪律
+- `templates/worker-dogfood-evidence.md` — BE/FE/QA sample、Observe、morning report 与 coverage evidence 模板
+- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
+- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
+- `templates/adr.md` — 架构决策记录（ADR）
+
+## 维护
+
+文档变更后运行：
+
+```bash
+bash scripts/check-repo.sh
+```
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+完整本地门禁：
+
+```bash
+bash scripts/ci.sh
+```