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

package/dist/workflows/dag/types.js

@@ -2,13 +2,9 @@ import { z } from "zod";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
 import { dagRetryPolicySchema } from "./retry-policy.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
-export const dagNodeExecutorSchema = z.enum([
-    "pi",
-    "shell",
-    "static",
-]);
+export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
-export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = 'executorModels.cursor is no longer supported; use executorModels.pi only';
+export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = "executorModels.cursor is no longer supported; use executorModels.pi only";
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
 export const dagShellPresetSchema = z.enum(["loop-agent-standard-verify"]);
 export const dagVerifyQuotaSchema = z.enum(["1", "3", "full"]);
@@ -16,10 +12,7 @@ export const dagVerifyStrategySchema = z
     .object({
     intermediateQuota: dagVerifyQuotaSchema.optional(),
     finalQuota: z.literal("full").optional().default("full"),
-    focusedCommandSource: z
-        .literal("adapter")
-        .optional()
-        .default("adapter"),
+    focusedCommandSource: z.literal("adapter").optional().default("adapter"),
 })
     .optional();
 export const dagShellVerifyEvidenceSchema = z.object({
@@ -69,6 +62,17 @@ export const dagVerdictGateSchema = z.object({
     lineMode: z.enum(["first-non-empty", "first-verdict-line"]).optional(),
     label: z.string().min(1).optional(),
 });
+export const dagRequirementCoverageGateSchema = z.object({
+    fromNodeIds: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fromNodeIds must be kebab-case")).min(1),
+    requiredIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/, "requiredIds must use REQ-*, BR-*, or AC-* identifiers")).min(1),
+    label: z.string().min(1).optional(),
+});
+export const dagJsonArtifactGateSchema = z.object({
+    fromNodeId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    schemaId: z.literal("backend-test-analysis-v1"),
+    artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
+    outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
+});
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
     .union([z.literal(1), z.literal(2), z.literal(3)])
@@ -109,6 +113,8 @@ export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
     verdictGate: dagVerdictGateSchema.optional(),
+    requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
+    jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
     envAllowlist: z.array(z.string()).optional(),
@@ -147,6 +153,10 @@ export const dagDynamicExpansionSchema = z.object({
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, "childIdPrefix must be kebab-case"),
     childTask: dagDynamicExpansionChildTaskSchema,
+    tokenBudget: z.object({
+        maxTokensPerCase: z.number().int().positive().optional(),
+        maxTotalTokens: z.number().int().positive().optional(),
+    }).optional(),
 });
 export const dagDynamicReductionSchema = z.object({
     type: z.literal("verified_findings_report"),
@@ -176,9 +186,7 @@ export const dagDynamicConditionSchema = z.object({
         .optional(),
 });
 export const dagDynamicLoopBodyTaskSchema = z.object({
-    id: z
-        .string()
-        .regex(/^[a-z][a-z0-9-]*$/, "body task id must be kebab-case"),
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/, "body task id must be kebab-case"),
     dependsOn: z.array(z.string()).default([]),
     executor: dagNodeExecutorSchema.default("pi"),
     role: dagRoleSchema.optional(),
@@ -217,6 +225,7 @@ export const dagConvergenceSpecSchema = z
     stopOnVerdictPass: z.boolean().optional().default(true),
     stopOnHardVerifyPass: z.boolean().optional().default(true),
     pauseOnRegression: z.boolean().optional().default(true),
+    chainNodeIds: z.array(z.string()).optional(),
 })
     .optional();
 export const dagTaskSchema = z.object({
@@ -264,11 +273,33 @@ export const dagExecutorModelsSchema = z
     .strict();
 export const dagOutputLanguageSchema = z.enum(["zh-CN", "en"]);
 export const DEFAULT_DAG_OUTPUT_LANGUAGE = "zh-CN";
+export const dagEvaluationBindingSchema = z
+    .object({
+    campaignId: z.string().min(1),
+    candidateId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    bundleHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    seed: z.number().int().nonnegative(),
+    split: z.enum(["public", "private", "held_out"]).optional(),
+    taskRef: z.string().min(1).optional(),
+})
+    .strict();
+export const dagSourceBindingSchema = z.object({
+    schemaVersion: z.literal(1),
+    taskId: z.string().min(1),
+    sources: z.array(z.object({
+        kind: z.enum(["requirement", "constraint", "reference"]),
+        path: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+    })).min(1),
+    requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
+});
 export const dagSpecSchema = z
     .object({
     version: dagVersionSchema,
     title: z.string().min(1),
     runtimeContract: dagRuntimeContractSchema.optional(),
+    evaluation: dagEvaluationBindingSchema.optional(),
+    sourceBinding: dagSourceBindingSchema.optional(),
     outputLanguage: dagOutputLanguageSchema.optional(),
     objective: z.string().optional(),
     successCriteria: z.array(z.string()).optional(),
@@ -281,6 +312,13 @@ export const dagSpecSchema = z
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {
+    if (spec.evaluation && spec.version !== 3) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "evaluation requires DagSpec version 3",
+            path: ["evaluation"],
+        });
+    }
     if (spec.runtimeContract && spec.version !== 3) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/dist/workflows/dag/upstream-artifacts.js

@@ -37,6 +37,7 @@ export function relocateNodeArtifactPaths(node, oldRunDir, newRunDir) {
     };
     node.stdoutArtifactPath = rewrite(node.stdoutArtifactPath);
     node.assistantArtifactPath = rewrite(node.assistantArtifactPath);
+    node.structuredArtifactPath = rewrite(node.structuredArtifactPath);
     node.nodeRecordPath = rewrite(node.nodeRecordPath);
 }
 export function relocateConvergenceArtifactPaths(convergence, oldRunDir, newRunDir) {

package/dist/workflows/dag/validate.js

@@ -12,6 +12,7 @@ const GOVERNANCE_WARNING_TYPES = new Set([
     "shell-verdict-gate-grep-pattern",
     "shell-verdict-gate-multi-command-state",
     "shell-verdict-gate-handwritten-inline",
+    "orphan-writer-source-binding",
 ]);
 const ROOT_ARTIFACT_PATH_PROBES = [
     "artifacts/修改记录.md",
@@ -238,6 +239,25 @@ function validateRepairArtifactGateConfig(task, spec, issues) {
         });
     }
 }
+function validateRequirementCoverageGateConfig(task, spec, issues) {
+    const gate = task.shell?.requirementCoverageGate;
+    if (!gate)
+        return;
+    if (task.executor !== "shell") {
+        issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate requires executor=shell` });
+        return;
+    }
+    const dependencyIds = new Set(task.depends_on);
+    for (const fromNodeId of gate.fromNodeIds) {
+        if (!dependencyIds.has(fromNodeId)) {
+            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate.fromNodeIds entry "${fromNodeId}" must appear in depends_on` });
+        }
+        const upstream = spec.tasks.find((candidate) => candidate.id === fromNodeId);
+        if (upstream?.executor === "shell") {
+            issues.push({ type: "invalid-requirement-coverage-gate-config", message: `task ${task.id} shell.requirementCoverageGate source "${fromNodeId}" must be a non-shell node` });
+        }
+    }
+}
 function validateShellVerdictGateGovernance(task, commands, issues) {
     if (task.executor !== "shell") {
         return;
@@ -406,7 +426,7 @@ function validateShellTaskConfig(task, spec, issues) {
         return;
     }
     const commands = resolveShellCommands(shell);
-    if (commands.length === 0) {
+    if (commands.length === 0 && !shell.jsonArtifactGate) {
         issues.push({
             type: "missing-shell-commands",
             message: `shell task ${task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`,
@@ -452,9 +472,46 @@ function validateShellTaskConfig(task, spec, issues) {
         });
     }
     validateVerdictGateConfig(task, spec, issues);
+    validateRequirementCoverageGateConfig(task, spec, issues);
+    if (shell.jsonArtifactGate && !task.depends_on.includes(shell.jsonArtifactGate.fromNodeId)) {
+        issues.push({
+            type: "missing-dependency",
+            message: `shell task ${task.id} jsonArtifactGate source ${shell.jsonArtifactGate.fromNodeId} must be a direct dependency`,
+        });
+    }
     validateRepairArtifactGateConfig(task, spec, issues);
     validateShellVerdictGateGovernance(task, commands, issues);
 }
+function hasReadOnlyPlannerAncestor(spec, writer) {
+    const taskById = new Map(spec.tasks.map((task) => [task.id, task]));
+    const pending = [...writer.depends_on];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const id = pending.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const task = taskById.get(id);
+        if (!task)
+            continue;
+        if (task.executor === "pi" && task.role === "planner" && resolveWritePolicy(task, spec) === "read-only")
+            return true;
+        pending.push(...task.depends_on);
+    }
+    return false;
+}
+function validateWriterSourceBinding(spec, issues) {
+    if (spec.version < 3 || spec.sourceBinding)
+        return;
+    for (const task of spec.tasks) {
+        if (resolveWritePolicy(task, spec) !== "exclusive" || hasReadOnlyPlannerAncestor(spec, task))
+            continue;
+        issues.push({
+            type: "orphan-writer-source-binding",
+            message: `task ${task.id} is an exclusive writer without source binding or a read-only planner ancestor; recovery/partial writer DAGs must bind authoritative task sources`,
+        });
+    }
+}
 function validateStaticTaskConfig(task, issues) {
     if (task.executor !== "static") {
         return;
@@ -579,6 +636,7 @@ export function validateDagSpec(spec) {
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);
+    validateWriterSourceBinding(spec, issues);
     return issues;
 }
 export function assertValidDagSpec(spec, options = {}) {

package/docs/README.md

@@ -1,104 +1,106 @@
-# 文档索引
-
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
-
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
-
-**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
-
-站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
-
-## 核心文档
-
-- `design/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计与实现依据
-- `development-principles.md` — 仓库开发原则
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
-- `architecture/README.md` — 架构文档目录索引与阅读路径
-- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
-- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
-- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
-- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
-- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
-- `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 指南
-- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
-- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
-
-## 近期完成合同（入口）
-
-完整列表见 `exec-plans/completed/README.md`。近期高频入口：
-
-- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
-- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
-- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
-- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
-- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
-
-## 设计思想来源
-
-- `../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` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
-- `exec-plans/active/README.md` — 进行中的执行计划
-- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
-- `progress/README.md` — 进度交接日志（全量）
-- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
-- `decisions/README.md` — 架构决策（ADR 0001–0003）
-- `skills/README.md` — repo-local skill registry and vetting notes
-- `templates/` — 可复用的规划、报告与 DAG 模板
-
-## 仓库 Skills
-
-- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
-- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
-- 每个额外 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` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
-- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
-- `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
-- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
-- `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
-- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
-- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
-- `templates/adr.md` — 架构决策记录（ADR）
-
-## 维护
-
-文档变更后运行：
-
-```bash
-node bin/loop-agent.js docs audit --repo-root .
-bash scripts/check-doc-index.sh
-bash scripts/check-doc-links.sh
-bash scripts/check-repo.sh
-```
-
-涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
-
-Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
-
-完整本地门禁：
-
-```bash
-bash scripts/ci.sh
-```
+# 文档索引
+
+`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+
+顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+
+**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
+
+站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
+
+## 核心文档
+
+- `design/archive/2026-07-14-loop-agent-self-update-notifier.md` — loop-agent CLI 自更新提醒设计（已实现；历史设计说明）
+- `development-principles.md` — 仓库开发原则
+- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向
+- `architecture/README.md` — 架构文档目录索引与阅读路径
+- `architecture/system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统全景
+- `architecture/dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期
+- `architecture/worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe
+- `architecture/facts-and-state.md` — harness 事实与状态、canonical/derived、可写/只读边界
+- `architecture/evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向
+- `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 指南
+- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
+- `design/frontend-mock-data-workflow.md` — 已实现的前端 Mock 数据节点、触发条件、规范证据、验证与失败路由
+- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的权威任务源绑定、前端需求编号覆盖门禁与中断恢复规则
+- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar 用法（非受治理 writer）
+- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 分类的机器校验契约
+
+## 近期完成合同（入口）
+
+完整列表见 `exec-plans/completed/README.md`。近期高频入口：
+
+- `exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md` — Website IA、双树边界与 docs-converge
+- `exec-plans/completed/2026-07-13-versioned-self-hosting-bootstrap.md` — 版本化自举与 candidate canary
+- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime
+- `exec-plans/completed/2026-07-12-observe-warm-console-redesign.md` — Observe 暖白运行控制台
+- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout 与 dogfood 收口（M2-01～08 见 completed 索引）
+
+## 设计思想来源
+
+- `../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` — 设计草稿、契约映射与路线图（含 design/dynamic-workflow-dag-engine-roadmap.md）
+- `exec-plans/active/README.md` — 进行中的执行计划
+- `exec-plans/completed/README.md` — 已完成的执行计划（全量）
+- `progress/README.md` — 进度交接日志（全量）
+- `reports/README.md` — 验证与审计报告（全量）；活能力摘要见 `reports/current-capability-summary.md`
+- `decisions/README.md` — 架构决策（ADR 0001–0004；0004 = Task Pool feature-scoped identity）
+- `skills/README.md` — repo-local skill registry and vetting notes
+- `templates/` — 可复用的规划、报告与 DAG 模板
+
+## 仓库 Skills
+
+- `../skills/loop-agent/` — loop-agent 自身的 skill 指令与参考资料
+- `../skills/agent-worker/` — Feature Packet / Task Pool / versioned self-hosting 的可选 outer-loop operator skill；不进入默认 DAG role skills
+- 每个额外 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` — 发布 controller identity 固定、真实 Worker sample、candidate canary 与 retry 纪律
+- `templates/worker-dogfood-evidence.md` — controller fingerprint、skill snapshot、canary、BE/FE/QA、Observe 与 failure evidence 模板
+- `templates/harness.schema.json` — `harness.json` 的 IDE JSON Schema，随初始化投影到目标项目
+- `templates/interactive-ui-round2-experiment.md` — interactive UI prompt/model A/B/C 对照实验与统一指标模板
+- `templates/product-line/` — 可投影的 Feature/Task/QA/Links 产品线包；配合 `agent-worker task validate-feature` 做 docs CI
+- `templates/production-readiness-checklist.md` — 低/中风险单仓库 DAG readiness 检查清单
+- `templates/init-evolution-review.md` — 初始化能力演化审查报告模板
+- `templates/adr.md` — 架构决策记录（ADR）
+
+## 维护
+
+文档变更后运行：
+
+```bash
+node bin/loop-agent.js docs audit --repo-root .
+bash scripts/check-doc-index.sh
+bash scripts/check-doc-links.sh
+bash scripts/check-repo.sh
+```
+
+涉及 `website/docs/` 时再跑 `npm run docs:build`，并按 `skills/loop-agent/references/docs-converge.md` 同步 `overview/roadmap.md` 等站上活页。
+
+Windows 上通过 Git Bash 或已配置的兼容 Bash 运行脚本。实际文件操作使用平台原生路径；`/` 仅用于 repo 引用、JSON/Markdown 证据引用和 glob 约定。
+
+完整本地门禁：
+
+```bash
+bash scripts/ci.sh
+```