@tea-agent/loop-agent 0.10.0 → 0.12.0

package/dist/workflows/dag/validate.js

@@ -1,7 +1,9 @@
 import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, } from "./types.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { resolveRepairTaskForGate } from "./repair-artifact.js";
 import { topoSortToRanks } from "./topo.js";
+import { isSafeReadOnlyPiRetryCandidate } from "./retry-policy.js";
 const GOVERNANCE_WARNING_TYPES = new Set([
     "read-only-missing-artifacts-forbidden",
     "read-only-prompt-mentions-artifact-writes",
@@ -176,14 +178,65 @@ function validateRepairArtifactGateConfig(task, spec, issues) {
         });
     }
     const upstream = spec.tasks.find((candidate) => candidate.id === repairArtifactGate.fromNodeId);
-    if (!upstream)
-        return;
-    if (upstream.executor === "shell") {
+    if (upstream && upstream.executor === "shell") {
         issues.push({
             type: "invalid-repair-artifact-gate-config",
             message: `task ${task.id} shell.repairArtifactGate.fromNodeId "${repairArtifactGate.fromNodeId}" must reference a non-shell upstream artifact node`,
         });
     }
+    const resolution = resolveRepairTaskForGate({
+        tasks: spec.tasks,
+        gateTask: task,
+    });
+    if (!resolution.ok) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: `task ${task.id} ${resolution.reason}`,
+        });
+        return;
+    }
+    const hardVerifyCandidates = spec.tasks.filter((candidate) => candidate.depends_on.includes(resolution.repairTask.id) &&
+        candidate.executor === "shell" &&
+        candidate.role === "verifier" &&
+        candidate.shell?.verifyEvidence?.phase === "final" &&
+        candidate.shell.verifyEvidence.quota === "full" &&
+        candidate.shell.verifyEvidence.finalFullRequired === true);
+    if (hardVerifyCandidates.length !== 1) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: hardVerifyCandidates.length === 0
+                ? `task ${task.id} repair node "${resolution.repairTask.id}" must have one direct downstream final/full hard verification shell node with finalFullRequired=true`
+                : `task ${task.id} repair node "${resolution.repairTask.id}" has multiple hard verification shell nodes (${hardVerifyCandidates.map((candidate) => candidate.id).join(", ")})`,
+        });
+        return;
+    }
+    const hardVerify = hardVerifyCandidates[0];
+    const descendantIds = new Set();
+    const queue = [hardVerify.id];
+    while (queue.length > 0) {
+        const parentId = queue.shift();
+        for (const candidate of spec.tasks) {
+            if (candidate.depends_on.includes(parentId) &&
+                !descendantIds.has(candidate.id)) {
+                descendantIds.add(candidate.id);
+                queue.push(candidate.id);
+            }
+        }
+    }
+    const reviewCandidates = spec.tasks.filter((candidate) => descendantIds.has(candidate.id) &&
+        candidate.executor === "pi" &&
+        candidate.role === "reviewer" &&
+        !candidate.decisionGate?.enabled &&
+        candidate.writePolicy === "read-only" &&
+        (candidate.outputContract?.includes("VERDICT:") ?? false));
+    if (reviewCandidates.length !== 1) {
+        issues.push({
+            type: "invalid-repair-artifact-gate-config",
+            message: reviewCandidates.length === 0
+                ? `task ${task.id} hard verification node "${hardVerify.id}" must reach one read-only Pi reviewer with a VERDICT output contract`
+                : `task ${task.id} hard verification node "${hardVerify.id}" has multiple Pi reviewer nodes (${reviewCandidates.map((candidate) => candidate.id).join(", ")})`,
+        });
+    }
 }
 function validateShellVerdictGateGovernance(task, commands, issues) {
     if (task.executor !== "shell") {
@@ -229,7 +282,7 @@ function writeSetEntriesOverlap(a, b) {
         pathMatchesPattern(probeB, a)));
 }
 function shouldValidateWritePolicy(spec, task) {
-    return (spec.version === 2 ||
+    return (spec.version >= 2 ||
         task.writePolicy !== undefined ||
         task.writeSet !== undefined);
 }
@@ -319,20 +372,17 @@ function validateSameRankWriteSetConflicts(spec, ranks, issues) {
         }
     }
 }
-function isWriteGuardedAgentTask(task) {
-    return (task?.executor === "cursor" ||
-        (task?.executor === "pi" && task.toolProfile === "write"));
+function isAgentTask(task) {
+    return task?.executor === "pi";
 }
 function validateSameRankAgentAttributionRisks(spec, ranks, issues) {
     const taskById = new Map(spec.tasks.map((task) => [task.id, task]));
     for (const rank of ranks) {
-        const guardedTasks = rank
-            .map((id) => taskById.get(id))
-            .filter(isWriteGuardedAgentTask);
-        const hasExclusiveWriter = guardedTasks.some((task) => resolveWritePolicy(task, spec) === "exclusive");
+        const agentTasks = rank.map((id) => taskById.get(id)).filter(isAgentTask);
+        const hasExclusiveWriter = agentTasks.some((task) => resolveWritePolicy(task, spec) === "exclusive");
         if (!hasExclusiveWriter)
             continue;
-        for (const task of guardedTasks) {
+        for (const task of agentTasks) {
             const policy = resolveWritePolicy(task, spec) ?? "read-only";
             if (policy === "read-only" || policy === "none") {
                 issues.push({
@@ -417,6 +467,16 @@ function validateStaticTaskConfig(task, issues) {
         });
     }
 }
+function validateRetryPolicyTaskConfig(task, issues) {
+    if (task.retryPolicy === undefined)
+        return;
+    if (!isSafeReadOnlyPiRetryCandidate(task)) {
+        issues.push({
+            type: "invalid-retry-policy",
+            message: `task ${task.id} declares retryPolicy but is not a safe read-only non-dynamic Pi node; retry is only allowed for read-only/none Pi planner/scout/reviewer/verifier/closeout nodes without write, supervisor, or dynamic capabilities`,
+        });
+    }
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -515,6 +575,7 @@ export function validateDagSpec(spec) {
         validateShellTaskConfig(task, spec, issues);
         validateStaticTaskConfig(task, issues);
         validateDecisionGateTaskConfig(task, issues);
+        validateRetryPolicyTaskConfig(task, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);

package/dist/workflows/loop/actions/dag-action.js

@@ -64,8 +64,6 @@ export async function runLoopDagAction(repoRoot, taskId, options = {}) {
         if (options.maxConcurrent !== undefined) {
             runArgs.push("--max-concurrent", String(options.maxConcurrent));
         }
-        if (options.noCursor)
-            runArgs.push("--no-cursor");
         const runSummary = asRecord(await runner("run-dag", runArgs), "run-dag");
         runId = stringField(runSummary, "runId", "run-dag");
         const report = await runner("dag-report", [

package/dist/workflows/loop/actions/shared.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { repoRelativePath, toPosixPath } from "../../../shared/path-refs.js";
 import { workflowReportSchema } from "../../dynamic/artifacts.js";
-import { normalizePattern } from "../policy/cursor-fix-policy.js";
+import { normalizePattern } from "../policy/path-patterns.js";
 export const SUMMARY_LIMIT = 1200;
 export function truncateSummary(text) {
     const normalized = text.trim();

package/dist/workflows/loop/actions.js

@@ -7,21 +7,17 @@ import { validateDagUseCase } from "../../application/dag/validate-dag.js";
 import { formatDagReportHandoffMarkdown, formatDagReportMarkdown, } from "../dag/report.js";
 import { loadTaskConfig } from "../../task/runtime.js";
 import { appendLoopEvent } from "./events.js";
-import { appendLoopRound, readLoopRounds } from "./rounds.js";
+import { appendLoopRound } from "./rounds.js";
 import { rewriteLoopContext } from "./context.js";
 import { loadLoopState } from "./state.js";
 import { drainLoopSignals, pendingLoopSignals, readLoopSignals, } from "./signals.js";
 import { decideNextLoopAutoAction, } from "./policy/auto-policy.js";
-import { validateLoopCursorFixPolicy } from "./policy/cursor-fix-policy.js";
 import { configureLoopDagDefaultRunner, } from "./actions/dag-action.js";
 import { readLatestPiReviewRecord } from "./actions/pi-review.js";
 import { runLoopWorkflowGateSignalAction, } from "./actions/workflow-action.js";
-import { hasDagRound } from "./actions/shared.js";
 export { decideNextLoopAutoAction } from "./policy/auto-policy.js";
-export { validateLoopCursorFixPolicy } from "./policy/cursor-fix-policy.js";
 export { resolveLoopShellVerifyCommands, runLoopShellVerification } from "./actions/shell-verify.js";
 export { buildLoopPiReviewPrompt, runLoopPiReview, } from "./actions/pi-review.js";
-export { buildLoopCursorFixPrompt, runLoopCursorFix } from "./actions/cursor-fix.js";
 export { runLoopDagAction } from "./actions/dag-action.js";
 export { runLoopWorkflowAction, runLoopWorkflowGateSignalAction, } from "./actions/workflow-action.js";
 async function defaultDagCommandRunner(repoRoot, command, args) {
@@ -58,6 +54,17 @@ async function defaultDagCommandRunner(repoRoot, command, args) {
 configureLoopDagDefaultRunner(defaultDagCommandRunner);
 async function defaultAutoActionRunner(input) {
     if (isLoopActionName(input.action)) {
+        if (input.action === "dag") {
+            await runLoopAction({
+                action: "dag",
+                repoRoot: input.repoRoot,
+                taskId: input.taskId,
+                options: {
+                    mode: input.dagMode ?? "review",
+                },
+            });
+            return;
+        }
         await runLoopAction({
             action: input.action,
             repoRoot: input.repoRoot,
@@ -81,7 +88,6 @@ async function defaultAutoActionRunner(input) {
 function isLoopActionName(action) {
     return (action === "shell-verify" ||
         action === "pi-review" ||
-        action === "cursor-fix" ||
         action === "dag" ||
         action === "workflow");
 }
@@ -117,33 +123,10 @@ export async function runLoopAuto(repoRoot, taskId, options = {}) {
             }
             continue;
         }
-        const hasApprovalSignal = pendingLoopSignals(signals).some((signal) => signal.type === "approval");
-        const policyAllowsCursorFix = taskConfig.loopAutoWritePolicy === "enabled" ||
-            (taskConfig.loopAutoWritePolicy === "approval-required" &&
-                (Boolean(options.allowCursorFix) || hasApprovalSignal));
-        let cursorFixPolicyError;
-        if (policyAllowsCursorFix &&
-            state.lastAction === "pi-review" &&
-            latestPiReview?.structured.recommendedAction === "implement_fix") {
-            try {
-                const rounds = await readLoopRounds(repoRoot, taskId);
-                validateLoopCursorFixPolicy({
-                    allowedPaths: taskConfig.allowedPaths,
-                    forbiddenPaths: taskConfig.forbiddenPaths,
-                    complexity: taskConfig.complexity,
-                    dagFallbackReason: taskConfig.dagFallbackReason ?? "",
-                    hasDagRound: hasDagRound(rounds),
-                });
-            }
-            catch (error) {
-                cursorFixPolicyError = error instanceof Error ? error.message : String(error);
-            }
-        }
         const next = decideNextLoopAutoAction(state, signals, {
-            loopAutoWritePolicy: taskConfig.loopAutoWritePolicy,
-            allowCursorFix: options.allowCursorFix,
+            loopAutoExecutionPolicy: taskConfig.loopAutoExecutionPolicy,
+            approvalGranted: options.approvalGranted,
             latestPiReview: latestPiReview?.structured,
-            cursorFixPolicyError,
         });
         actions.push(next);
         await appendLoopEvent(repoRoot, taskId, {

package/dist/workflows/loop/benchmark.js

@@ -194,7 +194,7 @@ export const LOOP_BENCHMARK_FIXTURE_SAMPLES = [
             regressionPause: false,
             changedPaths: 1,
             repairPasses: 1,
-        }, ["./test/loop-workflow.test.ts"], "Approval or enabled policy triggers bounded cursor-fix."),
+        }, ["./test/loop-workflow.test.ts"], "Approval or enabled policy triggers bounded DAG execute."),
         result("3-pass-convergence+quota", {
             pass: true,
             fullVerifyPass: true,

package/dist/workflows/loop/index.js

@@ -5,4 +5,4 @@ export { rewriteLoopContext } from "./context.js";
 export { appendLoopSignal, drainLoopSignals, parseLoopSignalType, pendingLoopSignals, readLoopSignals, } from "./signals.js";
 export { appendLoopEvent, readLoopEvents } from "./events.js";
 export { generateLoopCloseout } from "./closeout.js";
-export { buildLoopPiReviewPrompt, buildLoopCursorFixPrompt, decideNextLoopAutoAction, resolveLoopShellVerifyCommands, runLoopAuto, runLoopCursorFix, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowGateSignalAction, runLoopWorkflowAction, validateLoopCursorFixPolicy, } from "./actions.js";
+export { buildLoopPiReviewPrompt, decideNextLoopAutoAction, resolveLoopShellVerifyCommands, runLoopAuto, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowGateSignalAction, runLoopWorkflowAction, } from "./actions.js";

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

@@ -55,28 +55,34 @@ export function decideNextLoopAutoAction(state, signals = [], options = {}) {
     }
     if (state.lastAction === "pi-review") {
         if (options.latestPiReview?.recommendedAction === "implement_fix") {
-            const policy = options.loopAutoWritePolicy ?? "off";
+            const policy = options.loopAutoExecutionPolicy ?? "off";
             const approvalSignal = pendingSignals.find((signal) => signal.type === "approval");
-            const allowedByPolicy = policy === "enabled" ||
-                (policy === "approval-required" &&
-                    (Boolean(options.allowCursorFix) || Boolean(approvalSignal)));
-            if (options.cursorFixPolicyError) {
+            const approved = Boolean(options.approvalGranted) || Boolean(approvalSignal);
+            if (policy === "off") {
                 return {
-                    action: "pause",
-                    reason: `cursor-fix policy guard failed: ${options.cursorFixPolicyError}`,
-                    decision: "pause",
+                    action: "dag",
+                    dagMode: "review",
+                    reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=off (DAG review only)`,
+                    decision: "continue",
                 };
             }
-            if (allowedByPolicy) {
+            if (policy === "approval-required" && !approved) {
                 return {
-                    action: "cursor-fix",
-                    reason: `pi-review recommended implement_fix; loopAutoWritePolicy=${policy}`,
-                    decision: "continue",
+                    action: "pause",
+                    reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=approval-required without approval`,
+                    decision: "pause",
                 };
             }
+            return {
+                action: "dag",
+                dagMode: "execute",
+                reason: `pi-review recommended implement_fix; loopAutoExecutionPolicy=${policy}`,
+                decision: "continue",
+            };
         }
         return {
             action: "dag",
+            dagMode: "review",
             reason: "read-only review produced next action; generate a governed DAG review packet",
             decision: "continue",
         };
@@ -85,19 +91,21 @@ export function decideNextLoopAutoAction(state, signals = [], options = {}) {
     if (approvalSignal) {
         return {
             action: "dag",
+            dagMode: "review",
             reason: `approval signal received; generate next governed DAG packet: ${approvalSignal.message}`,
             decision: "continue",
         };
     }
-    if (state.lastAction === "cursor-fix" || state.lastAction === "dag") {
+    if (state.lastAction === "dag") {
         return {
             action: "shell-verify",
-            reason: `${state.lastAction} round must be followed by deterministic shell verification`,
+            reason: "dag round must be followed by deterministic shell verification",
             decision: "continue",
         };
     }
     return {
         action: "dag",
+        dagMode: "review",
         reason: "default to DAG governed review packet for the next bounded round",
         decision: "continue",
     };

package/dist/workflows/loop/policy/path-patterns.js

@@ -0,0 +1,13 @@
+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));
+}

package/docs/README.md

@@ -4,27 +4,40 @@
 
 顶层 `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 概览
-- `exec-plans/completed/2026-07-11-m2-01-feature-review-model.md` — 第二月 Feature read model 与 `feature review` 已完成实施合同
-- `exec-plans/completed/2026-07-12-m2-02-feature-run-orchestration.md` — 第二月 Feature run 薄编排已完成实施合同
-- `exec-plans/completed/2026-07-12-m2-03-follow-up-tracer-bullet.md` — 第二月 ProductBug Follow-up tracer bullet 已完成合同
-- `exec-plans/completed/2026-07-12-m2-04-follow-up-hardening.md` — 第二月 Follow-up 全分类与事务故障注入已完成合同
-- `exec-plans/completed/2026-07-12-m2-05-git-transaction.md` — 第二月显式授权 Git checkpoint 与失败恢复已完成合同
-- `exec-plans/completed/2026-07-12-m2-06-delivery-closeout-preview.md` — 第二月 Delivery、Acceptance Coverage 与 Closeout preview 已完成合同
-- `exec-plans/completed/2026-07-12-m2-07-feature-decision-metrics.md` — 第二月 Feature 决策体验与 metrics 已完成合同
-- `exec-plans/completed/2026-07-12-m2-08-closeout-dogfood-release.md` — 第二月 Closeout apply、真实 dogfood 与发布证据已完成合同
 - `agent-dag-runner.md` — Agent DAG runner 指南
-- `cursor-executor-usage.md` — Cursor executor 用法
-- `dynamic-workflow-dag-engine-roadmap.md` — Dynamic Workflow DAG Engine 路线图与适配分析
+- `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 目录和脚本检查为准。
@@ -37,34 +50,19 @@
 
 ## 产物目录
 
-- `design/README.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/2026-07-11-round3-worker-expansion.md` — Round 3 Worker 扩量、0.7.4 FE green、QA review blocker 与第二轮 owner decision
-- `reports/2026-07-11-observe-dag-visualization.md` — Observe DAG edges、SVG 图形化、交互与真实 Chrome smoke 验证证据
-- `reports/2026-07-11-0.7.5-init-evolution-review.md` — 0.7.5 package/version 变化对目标项目初始化 surface 的影响审查
-- `reports/2026-07-11-command-performance-audit.md` — 命令并发、验证、Observe 和子进程输出的性能审计
-- `reports/2026-07-11-command-performance-followups.md` — Observe 快照复用、输出缓冲和 reference index 遍历优化的验证记录
-- `reports/2026-07-11-observe-terminal-dag-kpi.md` — 终态 DAG 被误计为活跃数的修复记录
-- `reports/2026-07-12-observe-warm-console-redesign.md` — 暖白运行控制台视觉重构与桌面验证记录
-- `reports/2026-07-12-dag-state-reconciliation.md` — DAG 实际状态判定、安全收口命令与历史失联运行处理记录
-- `reports/2026-07-12-dag-state-reconciliation-init-evolution-review.md` — DAG 状态收口能力对初始化 surface 的影响审查
-- `reports/2026-07-12-observe-dag-node-model.md` — Dashboard DAG 节点模型显示与历史运行兼容修复记录
-- `reports/2026-07-12-observe-dag-node-model-init-evolution-review.md` — 节点模型持久化与 Observe 投影对初始化 surface 的影响审查
-- `reports/2026-07-12-dag-output-language.md` — Agent DAG 默认中文输出与可配置语言规则实现记录
-- `reports/2026-07-12-dag-output-language-init-evolution-review.md` — DAG 输出语言配置对初始化 surface 的影响审查
-- `reports/2026-07-12-init-evolution-strict-report-range.md` — 严格 init 演化校验拒绝无关历史报告的修复与验证证据
-- `reports/2026-07-12-dag-liveness-recovery.md` — DAG runner 心跳、孤儿运行诊断与 Observe 活跃筛选的修复记录
-- `reports/2026-07-12-dag-liveness-init-evolution-review.md` — DAG 活性元数据对初始化投影和旧项目兼容性的审查
-- `decisions/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 目录
 
 ## 模板
@@ -75,8 +73,8 @@
 - `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/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
@@ -89,9 +87,14 @@
 文档变更后运行：
 
 ```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 约定。
 
 完整本地门禁：

package/docs/agent-dag-recovery-playbook.md

@@ -15,7 +15,7 @@ product_line_failure_category
 recommended_follow_up
 ```
 
-Product-line taxonomy 定义见 `docs/design/state-and-failure-taxonomy.md`。
+Product-line taxonomy 定义见 `docs/design/state-and-failure-taxonomy.md`。
 
 **非目标（本 playbook 不覆盖、runner 不实现）：**
 

package/docs/agent-dag-runner.md

@@ -17,15 +17,40 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 - `static`：确定性生成的 artifacts 或 notes
 - `shell`：验证与文件系统检查
 - `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-- `cursor`：显式启用时的可选有界写后端
+
+## Retry (read-only Pi nodes)
+
+planner/scout/reviewer/verifier/closeout 角色的只读 Pi 节点可声明 opt-in `retryPolicy`，用于在同一 run 内有界重试模型连接中断、provider 限流、临时不可用或请求 timeout。生成器会为这些安全节点自动声明默认策略：总尝试次数 3（手工配置上限 5），指数退避，单次等待上限 30s。
+
+- 仅以下原始失败分类默认可重试：`timeout`、`network`、`rate-limit`、`unavailable`。
+- `quota`、`auth`、`invalid-output`、`write-guard`、`decision-envelope` 与未知失败不重试。`quota` 不是 rate limit，不会被自动重试。
+- 资格由确定性 helper 判断：仅 `writePolicy=read-only|none`（或 Pi 默认只读）的 planner/scout/reviewer/verifier/closeout 可用。supervisor、implementer、writer（`toolProfile=write` 或 `writePolicy=exclusive`）、docs-only、dynamic、shell、static 与 decision-gate 节点一律不重试，DAG validation 会拒绝其策略。
+- 每次 attempt 写入独立不可变证据（`<node-id>/attempt-<n>.json`，run-relative path），最终 node record 的 `attempts` 字段引用完整 attempt 历史；后一次成功不会覆盖前一次失败证据。
+- 重试期间复用同一 run、controller identity、skill snapshot、prompt、model 与上游输入。节点终态的 `durationMs`、`tokensUsed`、`parsedEvents` 聚合全部 attempts；退避等待会刷新 `lastActivityAt`，避免被误判为 node-quiet。当前退避会占用该节点所在的并发槽。
+
+示例：
+
+```json
+{
+  "retryPolicy": {
+    "maxAttempts": 3,
+    "backoff": "exponential",
+    "initialDelayMs": 2000,
+    "maxDelayMs": 30000,
+    "retryCategories": ["timeout", "network", "rate-limit", "unavailable"]
+  }
+}
+```
+
+未声明 `retryPolicy` 的历史 DAG 行为不变（单次执行、无 `attempts` 字段，也不新增 attempt artifact）。
 
 ## Skills
 
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 优先从目标项目 `.agents/skills/<skill-name>/SKILL.md` 解析本地指令，再回退到包内 `skills/`，并在各节点 `skills.json` artifact 中记录解析元数据。
 
 执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `docs/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
 
-`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
+目标项目的 `loop-agent` skill 位于 `.agents/skills/loop-agent/SKILL.md`。loop-agent 源仓库和 npm 包内置版本仍位于 `skills/loop-agent/SKILL.md`；遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
 
 ## Artifacts
 

package/docs/architecture/README.md

@@ -0,0 +1,26 @@
+# 架构文档索引
+
+本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
+
+## 阅读路径
+
+建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
+
+1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
+2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+3. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
+4. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature 与 Observe。
+5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
+6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
+
+## 事实与规划的区分
+
+- **当前事实源**：`src/` 源码、发布 CLI、`docs/exec-plans/completed/`、`docs/reports/current-capability-summary.md`、ADR 0001–0003。
+- **规划/设计输入**：`docs/design/`（含 `dynamic-workflow-dag-engine-roadmap.md`、`六个月规划.md`）。这些文件已带 2026-07-14 校准条；凡未兑现的 phase 段落是设计输入，**不是**已实现证明。
+- 凡本目录文档描述未来能力，一律使用「规划 / 未实现 / 前瞻」标签。
+
+## 与其他文档的分工
+
+- 本目录不复制 `runtime-boundaries.md` 的 import 方向表、governance-hook 表与版本化自举边界表，只交叉引用。
+- 用法与操作说明在 `website/docs/`（使用者双树），不在本目录重复。
+- 本目录文档随发布包发布（npm `files` 显式条目 + `docs/init-surface.manifest.json` `packageRequired`），但 **不**投影到目标项目 init surface；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。