@tea-agent/loop-agent 0.22.0 → 0.23.1

package/dist/workflows/dag/recovery-recommendation.js

@@ -8,6 +8,51 @@ export const DAG_RECOVERY_ACTIONS = [
     "inspect-upstream",
     "unknown",
 ];
+const FOLLOW_UP_BY_RAW_CATEGORY = {
+    "nonzero-exit": {
+        nextStepCategory: "repair",
+        reason: "Deterministic command exited nonzero; inspect stdout/stderr and exit code, then repair code, command, or environment before rerun.",
+    },
+    "decision-envelope-invalid": {
+        nextStepCategory: "revision",
+        reason: "Decision gate output violated the envelope protocol; revise the decision node prompt/output and do not infer approval.",
+    },
+    "protocol-invalid": {
+        nextStepCategory: "revision",
+        reason: "Model output violated the required protocol; if deterministic verdict normalization cannot prove exactly one supported verdict, revise/retry the protocol-producing node rather than inferring approval.",
+    },
+    "write-guard": {
+        nextStepCategory: "repair",
+        reason: "Write boundary was violated; narrow writeSet or revert out-of-bound changes before rerun. Write-guard failures must not be converted to success.",
+    },
+    timeout: {
+        nextStepCategory: "retry",
+        reason: "Execution exceeded its activity/wall-clock budget; inspect readiness/resource diagnostics and scoped timeout budget, then retry once the readiness issue is fixed.",
+    },
+    "controller-interrupted": {
+        nextStepCategory: "restart",
+        reason: "Controller was interrupted; reconcile run state from persisted DAG facts, then restart or resume the run.",
+    },
+};
+const UNKNOWN_FOLLOW_UP = {
+    nextStepCategory: "diagnosis",
+    reason: "Failure category is unavailable or unrecognized; run diagnosis/report before selecting repair/retry/restart.",
+};
+/**
+ * Deterministic mapping from a raw failure category to a stable next-step
+ * category and reason. Unknown/missing categories route to diagnosis.
+ *
+ * This is a routing hint only; callers must not use it to change a DAG run's
+ * terminal status or to convert a genuine failure into success.
+ */
+export function recommendFollowUpForFailureCategory(rawFailureCategory) {
+    if (!rawFailureCategory)
+        return { ...UNKNOWN_FOLLOW_UP };
+    const direct = FOLLOW_UP_BY_RAW_CATEGORY[rawFailureCategory];
+    if (direct)
+        return { ...direct };
+    return { ...UNKNOWN_FOLLOW_UP };
+}
 const REPORT_DERIVED_ONLY = "Derived planning hint only; dag report does not execute retry or resume.";
 const TRANSIENT_EXECUTOR_RAW = new Set([
     "network",

package/dist/workflows/dag/report.js

@@ -8,7 +8,7 @@ import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRun
 export const DAG_CLOSEOUT_DRAFT_DISCLAIMER = "> **Advisory only.** Derived from completed run facts. Canonical source remains `dag report --json` and `.harness/dag-runs/completed/<run-id>/`. Do not treat this draft as authoritative.";
 import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from "./failure-category.js";
 import { dagProductLineFailureCategoryValues, routeDagFailure, } from "./failure-routing.js";
-import { DAG_RECOVERY_ACTIONS, planDagRecovery, } from "./recovery-recommendation.js";
+import { DAG_RECOVERY_ACTIONS, planDagRecovery, recommendFollowUpForFailureCategory, } from "./recovery-recommendation.js";
 import { dagNodeExecutorSchema, dagNodeStatusSchema, LEGACY_TOP_LEVEL_MODELS_ERROR, parseDagSpec, resolveModelForTask, } from "./types.js";
 import { checkRuntimeContractCompatible, DAG_CONTROLLER_CAPABILITIES, } from "./runtime-contract.js";
 export const DAG_REPORT_SCHEMA_VERSION = 1;
@@ -141,6 +141,10 @@ const dagNodeReportRowSchema = z
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
     productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
     recommendedFollowUp: z.string().optional(),
+    recommendedFollowUpCategory: z
+        .enum(["repair", "revision", "retry", "restart", "diagnosis"])
+        .optional(),
+    recommendedFollowUpReason: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     backend: z.enum(["sdk", "cli"]).optional(),
     sdkAttempted: z.boolean().optional(),
@@ -166,6 +170,10 @@ const dagRunReportEntrySchema = z
     normalizedFailureCategory: dagNormalizedFailureCategorySchema.optional(),
     productLineFailureCategory: dagProductLineFailureCategorySchema.optional(),
     recommendedFollowUp: z.string().optional(),
+    recommendedFollowUpCategory: z
+        .enum(["repair", "revision", "retry", "restart", "diagnosis"])
+        .optional(),
+    recommendedFollowUpReason: z.string().optional(),
     recoveryRecommendation: dagRecoveryRecommendationSchema.optional(),
     primaryFailure: dagReportPrimaryFailureSchema,
     primaryRecovery: dagRecoveryRecommendationSchema,
@@ -434,6 +442,9 @@ export async function buildDagRunReportEntry(input) {
                 nodeId,
                 executor: node.executor,
             });
+            const followUp = node.status === "ERROR" || node.status === "SKIPPED"
+                ? recommendFollowUpForFailureCategory(node.failureCategory)
+                : undefined;
             nodes.push({
                 nodeId,
                 rank,
@@ -448,6 +459,12 @@ export async function buildDagRunReportEntry(input) {
                 failureCategory: node.failureCategory,
                 normalizedFailureCategory,
                 ...failureRouting,
+                ...(followUp
+                    ? {
+                        recommendedFollowUpCategory: followUp.nextStepCategory,
+                        recommendedFollowUpReason: followUp.reason,
+                    }
+                    : {}),
                 recoveryRecommendation: planDagRecovery({
                     status: node.status,
                     normalizedFailureCategory,
@@ -513,6 +530,10 @@ export async function buildDagRunReportEntry(input) {
         normalizedFailureCategory: runRecoverySource.normalizedFailureCategory,
         nodeId: "nodeId" in runRecoverySource ? runRecoverySource.nodeId : undefined,
     });
+    const runFollowUp = input.state.status === "failed" ||
+        input.state.status === "partial_failed"
+        ? recommendFollowUpForFailureCategory(input.state.failureCategory)
+        : undefined;
     const partialEntry = {
         runId: input.state.runId,
         title: input.state.title,
@@ -524,6 +545,12 @@ export async function buildDagRunReportEntry(input) {
         failureCategory: input.state.failureCategory,
         normalizedFailureCategory,
         ...runFailureRouting,
+        ...(runFollowUp
+            ? {
+                recommendedFollowUpCategory: runFollowUp.nextStepCategory,
+                recommendedFollowUpReason: runFollowUp.reason,
+            }
+            : {}),
         recoveryRecommendation,
         pausedByNodeId: input.state.pausedByNodeId,
         pauseReason: input.state.pauseReason,

package/dist/workflows/dag/rerun-task.js

@@ -193,7 +193,7 @@ function blockedResult(input) {
     };
 }
 function extractRunSummary(generateResult) {
-    if (generateResult.mode === "generate+validate")
+    if (generateResult.mode === "generate+basic-validate")
         return undefined;
     return generateResult.run;
 }

package/dist/workflows/dag/scheduler.js

@@ -17,6 +17,7 @@ function dependencyReadiness(task, nodes) {
     if (task.depends_on.length === 0)
         return "run";
     const softConditionJoin = task.dependsPolicy === "all-or-condition-skip";
+    const toleratedErrors = new Set(task.failureAwareDependsOn ?? []);
     let hasFinished = false;
     let hasPendingUpstream = false;
     let hasHardBlock = false;
@@ -35,6 +36,14 @@ function dependencyReadiness(task, nodes) {
             continue;
         }
         if (dep.status === "ERROR") {
+            // AC1: an explicit read-only recovery/diagnosis/closeout node may
+            // consume a declared upstream ERROR as settled failure evidence. This
+            // does not rewrite the upstream status; it only allows the recovery
+            // node to become runnable so it can read the failure evidence.
+            if (toleratedErrors.has(depId)) {
+                hasFinished = true;
+                continue;
+            }
             hasHardBlock = true;
             continue;
         }

package/dist/workflows/dag/types.js

@@ -27,6 +27,10 @@ export const dagShellVerifyEvidenceSchema = z.object({
     commandCount: z.number().int().nonnegative(),
     commandLabels: z.array(z.string()).default([]),
     commandTexts: z.array(z.string()).default([]),
+    /** Effective timeout applied independently to each shell command. */
+    commandTimeoutMs: z.number().int().positive().optional(),
+    /** Worst-case serial budget: commandCount * commandTimeoutMs. */
+    totalTimeoutBudgetMs: z.number().int().nonnegative().optional(),
     finalFullRequired: z.boolean().optional(),
 });
 export const dagRepairArtifactGateSchema = z.object({
@@ -424,6 +428,14 @@ export const dagTaskSchema = z.object({
      *   every dep is FINISHED or soft condition-skip and at least one is FINISHED (OR-join)
      */
     dependsPolicy: z.enum(["all", "all-or-condition-skip"]).optional(),
+    /**
+     * Explicit opt-in: upstream node ids whose ERROR terminal state this
+     * read-only node may consume as settled failure evidence. Validation
+     * restricts this to read-only Pi recovery/diagnosis/closeout nodes; writers,
+     * shell verifiers, hard gates, and dynamic/decision nodes remain fail-closed.
+     * Every id must also appear in depends_on.
+     */
+    failureAwareDependsOn: z.array(z.string()).optional(),
     /** Execute only when this fail-closed condition resolves true after dependencies settle. */
     runIf: z.string().min(1).optional(),
     complexity: dagComplexitySchema,

package/dist/workflows/dag/validate.js

@@ -614,6 +614,60 @@ function validateDecisionGateTaskConfig(task, issues) {
         });
     }
 }
+/**
+ * AC1: failure-aware dependencies are an explicit, narrow opt-in. Only
+ * read-only Pi nodes acting as recovery/diagnosis/supervision/closeout
+ * (reviewer, verifier, supervisor, closeout roles) may tolerate an upstream
+ * ERROR. Writers, shell verifiers, hard/decision gates, dynamic nodes, and any
+ * node with write capability must remain fail-closed.
+ */
+const FAILURE_AWARE_SAFE_ROLES = new Set([
+    "reviewer",
+    "verifier",
+    "supervisor",
+    "closeout",
+]);
+function validateFailureAwareDependsOn(task, spec, issues) {
+    const tolerated = task.failureAwareDependsOn;
+    if (!tolerated || tolerated.length === 0)
+        return;
+    const isReadOnlyPiRecoveryNode = task.executor === "pi" &&
+        FAILURE_AWARE_SAFE_ROLES.has(task.role ?? "") &&
+        task.toolProfile !== "write" &&
+        (task.writePolicy === undefined ||
+            task.writePolicy === "read-only" ||
+            task.writePolicy === "none") &&
+        (task.writeSet ?? []).length === 0 &&
+        !task.decisionGate?.enabled &&
+        !task.dynamicExpansion &&
+        !task.dynamicReduction &&
+        !task.dynamicCondition &&
+        !task.dynamicLoopUntil;
+    if (!isReadOnlyPiRecoveryNode) {
+        issues.push({
+            type: "invalid-failure-aware-dependency",
+            message: `task ${task.id} declares failureAwareDependsOn but failure-aware dependencies are allowed only for read-only recovery/diagnosis/supervision/closeout-equivalent Pi nodes (reviewer, verifier, supervisor, closeout); writer and shell verification nodes may not tolerate upstream ERROR`,
+        });
+        return;
+    }
+    const dependsOn = new Set(task.depends_on);
+    const knownIds = new Set(spec.tasks.map((entry) => entry.id));
+    for (const upstreamId of tolerated) {
+        if (!knownIds.has(upstreamId)) {
+            issues.push({
+                type: "invalid-failure-aware-dependency",
+                message: `task ${task.id} failureAwareDependsOn references unknown task id ${upstreamId}`,
+            });
+            continue;
+        }
+        if (!dependsOn.has(upstreamId)) {
+            issues.push({
+                type: "invalid-failure-aware-dependency",
+                message: `task ${task.id} failure-aware dependency ${upstreamId} must be listed in depends_on`,
+            });
+        }
+    }
+}
 export function collectExecutorModelWarnings(spec, expectedMatrices = DEFAULT_DAG_EXECUTOR_MODELS) {
     const warnings = [];
     const executors = Object.keys(DEFAULT_DAG_EXECUTOR_MODELS);
@@ -704,6 +758,7 @@ export function validateDagSpec(spec) {
         validateRetryPolicyTaskConfig(task, issues);
         validateOutputProtocolTaskConfig(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
+        validateFailureAwareDependsOn(task, spec, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);

package/docs/README.md

@@ -1,161 +1,78 @@
-# 文档索引
+# Start Here：文档怎么读
 
-`docs/` 是 loop-agent 的治理根目录，包含工作流规则、方法论、验证规则、执行计划、报告、进度日志、决策记录和可复用模板。
+`docs/` 是 loop-agent 源仓的治理文档根目录。新读者不需要先浏览所有文件，先按任务选择入口，再由目录 README 或 `docs/document-catalog.json` 判断文档身份。
 
-顶层 `AGENTS.md` 是操作地图。长期知识应落在此处：决策、契约、计划、验证证据、调试笔记和可复用流程规则应记录在 `docs/` 下，而不是只留在聊天里。
+**维护日：2026-07-25** — 对齐 `@tea-agent/loop-agent@0.23.1`。版本事实以根 `CHANGELOG.md` 与 `package.json` 为准；能力短摘要见 `reports/current-capability-summary.md`。
 
-**索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
+## 我现在要做什么？
 
-**维护日：2026-07-22** — 索引对齐仓库头 `@tea-agent/loop-agent@0.18.0`、reports 按类型分子目录，以及 progress / completed 导读制；版本与能力细节以 `CHANGELOG.md`、`reports/current-capability-summary.md` 与 active plans 为准。
-
-站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
-
-## 阅读路径
-
-1. 根目录 `AGENTS.md` + 本索引（地图）
-2. 活契约：`development-principles.md` → `feature-workflow.md` → `verification-matrix.md`
-3. Runtime / DAG：`loop-agent-harness.md` → `agent-dag-runner.md` → 需要时再读 `agent-dag-recovery-playbook.md`
-4. 架构边界：`architecture/runtime-boundaries.md`，再按 `architecture/README.md` 往下读
-5. 产物目录：active plan → progress handoff → reports 证据；设计输入见 `design/README.md`
-
-## 活契约（根目录）
-
-根目录 `docs/*.md` 是**当前仍生效**的操作契约与手册，不按日期归档、不按主题再拆子目录。
-
-- `development-principles.md` — 仓库开发原则
-- `feature-workflow.md` — 有边界的功能工作流、taskKind / profile、DAG 与 handoff 纪律
-- `verification-matrix.md` — 验证命令选择
-- `loop-agent-harness.md` — runtime 与 command surface 概览
-- `agent-dag-runner.md` — Agent DAG runner 指南
-- `agent-dag-recovery-playbook.md` — DAG 失败分类、recovery action 与 operator 处置手册
-- `backend-test-live-campaign.md` — backend-test 控制器修复与真实宿主循环验证：双仓库隔离、全新 Task/DAG/Run、首错即停、证据归档和中文用例合同
-- `production-readiness.md` — Production Readiness v0.1 范围、证据与 DAG hardening 标准
-- `branch-merge-guideline.md` — 分支合并：快速/标准/深度模式、功能保留、冲突解析、init/package 审计与 source-SHA 报告
-- `github-collaboration.md` — 内部轻量 GitHub 协作：短分支、简短 PR、CI 与 Squash Merge
-- `local-development-environment.md` — Cursor Cloud 等特定本地环境的已知问题与排障
-- `cursor-prompt-sidecar.md` — `cursor-prompt` one-shot sidecar（非受治理 writer）
-- `init-surface.manifest.json` — npm 包范围、目标项目初始化投影与 `init check-update` surface 的机器校验契约
-
-## 架构
-
-入口与阅读顺序见 `architecture/README.md`。
-
-- `architecture/runtime-boundaries.md` — runtime 层边界与依赖方向（边界真源）
-- `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 月未来方向
-
-## 设计入口（非实现证明）
-
-完整索引与归档策略见 `design/README.md`。下列为当前高频活入口：
-
-- `design/backend-test-workflow.md` — backend-test Markdown-first 8 节点流程、单次 pytest、run-owned artifacts 与 L-5
-- `design/frontend-implementation-workflow.md` — 前端实现 / 评审 / 验证工作流（含 Mock/API 策略、capability seed、verification bundle）
-- `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的任务源绑定与中断恢复
-- `design/agent-worker-fullstack-workflow-integration.md` — workflow routing、Task Outcome、artifact-aware Ready、`fullstack-v1` 与 Verification Bundle
-- `design/fullstack-end-to-end-delivery-optimization-roadmap.md` — 全栈端到端优化收敛路线图（release train / Delivery / Final Verification）
-- `design/local-operator-console-from-pi-web.md` — Operator Console 设计输入；MVP 已随 `0.17.0`–`0.17.2` 发布；统一 surface 设计已归档（见下）
-- `design/taskspec-to-loop-agent-mapping.md` — TaskSpec → loop-agent task 兼容契约（文档镜像；runtime 真源在代码）
-
-已实现且仅作历史说明的设计见 `design/archive/`（例如 `design/archive/2026-07-14-loop-agent-self-update-notifier.md`、`design/archive/2026-07-22-console-observe-unified-operator-surface.md`、`design/archive/2026-07-23-operator-task-rerun-and-node-retry.md`、`design/archive/frontend-mock-data-workflow.md`）。
-
-## 进行中 / 近期完成
-
-进行中的完整列表见 `exec-plans/active/README.md`。当前高频 active：
-
-- `exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` — 全栈 release train（0.16.X → 0.17.X；Delivery 仍 open）
-- `exec-plans/active/2026-07-21-frontend-test-dag-success-rate.md` — frontend-test 成功率 hardening（formal smoke 待收口）
-- `exec-plans/active/2026-07-18-backend-test-live-provider-smoke.md` — 真实 provider smoke（blocked-external）
-- `exec-plans/active/2026-07-20-l5-test-report-metrics.md` — L-5 / coverage（实现完成，待审阅归档）
-- `exec-plans/active/2026-07-16-recursive-self-improvement-eval-lab.md` — Eval Lab（实现完成，可归档）
-
-完整 completed 列表与主题速览见 `exec-plans/completed/README.md`。近期高频归档：
-
-- `exec-plans/completed/2026-07-24-backend-test-request-response-logs-report-format.md` — pytest 请求/响应脱敏日志与第 7/8 节点报告版式；真实 `my-webapp` Campaign R04 8/8、17 passed
-- `exec-plans/completed/2026-07-23-backend-test-advisory-gates.md` — 第 4/6 节点改为非阻断 advisory：用例只强制前置条件/步骤/预期，第 6 节点只扫描 Markdown 映射脚本；真实 `my-webapp` Campaign R02 8/8、10 passed
-- `exec-plans/completed/2026-07-23-backend-test-human-readable-artifacts.md` — 中文 README/用例卡片、class-based pytest traceability 与逐条 self-contained HTML 报告；真实 `my-webapp` Campaign Round 04 8/8、16 passed
-- `exec-plans/completed/2026-07-22-backend-markdown-gate-fix.md` — backend-test Markdown gate、traceability、中文生成与真实 Campaign 收口
-- `exec-plans/completed/2026-07-22-backend-test-markdown-first-8-node.md` — backend-test Markdown-first 8 节点
-- `exec-plans/completed/2026-07-22-backend-test-report-first-flow.md` — backend-test 报告优先 12 节点
-- `exec-plans/completed/2026-07-22-backend-test-intake-efficiency.md` — backend-test 首节点 intake 收敛
-- `exec-plans/completed/2026-07-21-console-phase-1-3.md` — Operator Console Phase 1–3 MVP（0.17.0–0.17.2）
-- `exec-plans/completed/2026-07-21-console-phase-0-5-task-contract.md` — Task Contract / operator envelope / DagSpec v4
-- `exec-plans/completed/2026-07-20-frontend-test-rag-outcome-hardening.md` — frontend-test 结果链与 UX 收口
-- `exec-plans/completed/2026-07-19-taskspec-workflow-routing.md` — TaskSpec workflow routing / Outcome / fullstack-v1（M0–M3）
-- `exec-plans/completed/2026-07-19-fullstack-dogfood-remediation.md` — 全栈 dogfood 源码修复基线（live 移交 active train）
-- `exec-plans/completed/2026-07-18-observe-ops-surface-and-rich-timeline.md` — Observe 运营面/执行面与富过程时间线
-- `exec-plans/completed/2026-07-12-pi-only-agent-runtime.md` — Pi-only 受治理 runtime（历史主线入口）
-
-## 设计思想来源
-
-- `../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/archive/`；根设计页保留活输入 |
-| `exec-plans/active/README.md` | 进行中合同 | 源码仓库可放正文；npm 包只带 README 契约 |
-| `exec-plans/completed/README.md` | 已归档合同 | 导读 + 主题速览 + 全量；本身即归档位，不再套 archive |
-| `progress/README.md` | 跨会话 handoff | 导读 + 全量；短交接，不堆长证据 |
-| `reports/README.md` | 验证 / dogfood / merge / init-evolution 证据 | 导读 + 按类型子目录（`reports/feature/`、`reports/init-evolution/`、`reports/merge/`、`reports/fullstack-dogfood/`、`reports/dogfood/`）；活摘要 `reports/current-capability-summary.md` |
-| `decisions/README.md` | ADR | 0001–0004 等；决策边界以 ADR 正文为准 |
-| `skills/README.md` | repo-local skill registry | vetting notes |
-| `templates/` | 可复用规划 / 报告 / DAG 模板 | 见下方模板列表 |
-
-分工一句话：`exec-plans` 写合同，`progress` 写怎么接下一会话，`reports` 写可引用证据。
-
-## 仓库 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` — 非平凡工作的执行计划（active → completed 落点说明见模板头）
-- `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` — 初始化能力演化审查报告模板（落盘 `reports/init-evolution/`）
-- `templates/branch-merge-report.md` — 跨分支合并报告模板（落盘 `reports/merge/`）
-- `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
-```
-
-根目录活契约正文只在行为/命令面真正变化时修改；本索引只负责入口与导航，不复述子目录全量列表。
+| 理解当前能力与边界 | `reports/current-capability-summary.md` | `architecture/README.md`、`website/docs/overview/roadmap.md` |
+| 开始一个受治理功能变更 | `governance/feature-workflow.md` | `governance/verification-matrix.md`、`templates/exec-plan.md` |
+| 跑或恢复 Agent DAG | `runtime/agent-dag-runner.md` | `runtime/agent-dag-recovery-playbook.md`、`runtime/loop-agent-harness.md` |
+| 判断架构边界 | `architecture/README.md` | `architecture/runtime-boundaries.md` |
+| 查设计输入而非实现证明 | `design/README.md` | 对应设计文档；视觉参考见 `design/visual-references/README.md`，归档设计见 `design/archive/README.md` |
+| 接手进行中任务 | `exec-plans/active/README.md` | 对应 active plan，再读 `progress/README.md` |
+| 查已完成依据 | `exec-plans/completed/README.md` | `reports/README.md` 与对应报告分类 |
+| 初始化或升级目标项目 | `init-surface.manifest.json` | `templates/README.md`、`reports/init-evolution/README.md` |
+| 管理文档 freshness | `governance/document-review-policy.md` | `document-catalog.json`、`scripts/check-doc-governance.mjs` |
+
+## 按问题找专题
+
+| 你要解决的问题 | 文档 |
+| --- | --- |
+| 先确认仓库的基本工程原则 | `governance/development-principles.md` |
+| 选择 taskKind、治理 profile 和 Agent DAG 路径 | `governance/feature-workflow.md` |
+| 选择快速、标准或完整验证命令 | `governance/verification-matrix.md` |
+| 理解 CLI、runtime 和初始化能力边界 | `runtime/loop-agent-harness.md` |
+| 运行 DAG、查看报告或处理失败 | `runtime/agent-dag-runner.md`、`runtime/agent-dag-recovery-playbook.md` |
+| 按 TDD、验证和调试纪律推进修复 | `governance/harness-methodology-tdd.md`、`governance/harness-methodology-verification.md`、`governance/harness-methodology-debugging.md` |
+| 执行真实 backend-test provider 验证 | `runtime/backend-test-live-campaign.md` |
+| 判断 Production Readiness | `operations/production-readiness.md` |
+| 合并分支并留下 source-SHA 报告 | `operations/branch-merge-guideline.md` |
+| 使用仓库内 GitHub 协作方式 | `operations/github-collaboration.md` |
+| 排查本机开发环境问题 | `operations/local-development-environment.md` |
+| 使用明确的 Cursor one-shot sidecar | `runtime/cursor-prompt-sidecar.md` |
+| 审查 npm 包与目标项目初始化文件面 | `init-surface.manifest.json` |
+| 判断文档何时需要重新复核 | `governance/document-review-policy.md` |
+
+## 文档身份规则
+
+- **当前优先检索（current-first）**：判断当前能力、状态或下一步时，先读 `CHANGELOG.md`、`reports/current-capability-summary.md`、`exec-plans/active/README.md` 和 `document-catalog.json`；命中 `design/archive/`、`exec-plans/completed/`、`reports/` 或 `reports/handoffs/` 时，必须先按 catalog 中该历史证据根的 `currentFirst` 跳转当前入口，再回看历史证据的时间点和范围。
+- **当前真源**：`document-catalog.json` 中 `status` 为 `当前有效` 且带唯一 `topic` 的条目为该主题的唯一权威入口；同一 `topic` 只能有一个当前真源。
+- **复核 freshness**：catalog 声明 `reviewPolicy.updateRule=verified-content-only`；每个登记文档必须引用有效 `reviewTier`。只有逐项对照 `sourceOfTruth` 并留下证据后才能更新 `lastReviewed`，tier/owner/category/格式修改不得刷新日期；具体规则见 `governance/document-review-policy.md`。
+- **已被替代**：`status` 为 `已被替代` 的条目必须通过 `supersededBy` 指向 catalog 中另一个不同 `path`；目标必须与原条目 `topic` 相同，且状态只能是 `当前有效` 或 `正在推进`。读取时不要继续引用原条目作为事实，应跳转到 `supersededBy` 指向的当前入口或正在推进合同。
+- **内容有误，已撤回**：`status` 为 `内容有误，已撤回` 的条目必须提供非空 `withdrawalReason`。这是撤回声明，不是替代关系；读取时只能保留其撤回原因和历史审计价值，不应把原文当作可信事实。
+- **关系字段**：`supersededBy` 与 `withdrawalReason` 互斥，且不得出现在其他状态条目上。
+- **当前契约 / 手册**：`governance/`、`runtime/`、`operations/` 与 `architecture/`，分别回答怎么推进、怎么运行、怎么维护和边界是什么。
+- **设计输入**：`design/active/`，用于说明仍会影响后续决策的方案、路线和背景；除非有代码、CHANGELOG 或 completed plan 旁证，否则不是已实现证明。
+- **视觉参考**：`design/visual-references/`，用于长期保留产品、交互或界面方向的视觉参考；它不表达实现状态，也不等同于 active 设计输入或 archive 历史证据。
+- **进行中合同**：`exec-plans/active/`。
+- **已完成证据**：`exec-plans/completed/`、`reports/`。
+- **当前交接**：`progress/`，只回答下一会话怎么接；结束后的交接归入 `reports/handoffs/`。
+- **历史资料**：`design/archive/`，保留历史或已被替代的设计上下文，不代表当前能力。
+- **模板库**：`templates/`，随 npm 包与 full init surface 投影。
+
+机器检查：`node scripts/check-doc-governance.mjs --repo-root .`。该检查枚举磁盘文件，不依赖“共 N 篇”这类手工计数。
+
+## 目录职责
+
+| 目录 | 职责 |
+| --- | --- |
+| `governance/` | 开发原则、功能工作流、验证矩阵与工程方法 |
+| `runtime/` | loop-agent harness、DAG 运行/恢复和专用 runtime 手册 |
+| `operations/` | 本地环境、分支合并、GitHub 协作与生产就绪操作 |
+| `architecture/` | 当前架构入口、runtime 边界、DAG 执行与状态事实 |
+| `decisions/` | ADR；决策是否仍有效以 ADR 正文和后续 ADR 为准 |
+| `design/active/` | 仍会影响后续决策的设计输入、路线与契约 |
+| `design/visual-references/` | 长期视觉参考，不表达实现状态 |
+| `design/archive/` | 历史设计和已被实现/替代的阶段性设计 |
+| `exec-plans/active/` | 仍需推进或明确保持 open 的任务合同 |
+| `exec-plans/completed/` | 已完成任务合同归档 |
+| `progress/` | 仍需下一次会话接手的当前 handoff 入口 |
+| `reports/` | 验证、dogfood、merge、init evolution 与历史 handoff 证据 |
+| `skills/` | repo-local skill registry |
+| `templates/` | 可复用任务、报告、DAG 和 init 模板 |
+
+站上使用者文档在 `../website/docs/`；源仓治理事实以本目录、`AGENTS.md`、`harness.json`、`CHANGELOG.md` 和检查脚本为准。

package/docs/architecture/README.md

@@ -2,14 +2,15 @@
 
 本目录是 loop-agent 维护者架构文档入口。每篇文档回答一个具体问题，不重复 `runtime-boundaries.md` 的依赖方向表与 governance-hook 表；遇到契约级事实请回到该文件。
 
-**维护日：2026-07-22** — 索引与演进叙述对齐仓库头 `@tea-agent/loop-agent@0.17.2`（Task Contract / Local Operator Console / 专用 taskKind DAG / reports 分子目录）。边界表仍以 `runtime-boundaries.md` 与 `scripts/check-*.sh` 为准。
+**维护日：2026-07-25** — 索引与演进叙述对齐仓库头 `@tea-agent/loop-agent@0.23.1`。边界表仍以 `runtime-boundaries.md` 与 `scripts/check-*.sh` 为准。
 
 ## 阅读路径
 
 建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
 
 1. `runtime-boundaries.md` — runtime 层边界、依赖方向与治理 hook 的机器校验契约（**先读，是其他文档的边界真源**）。
-2. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+2. `agents-invariants.md` — `AGENTS.md`（source）与 init managed block 的「什么不能删」不变量契约（短语真源 + 行数 guardrail 语义）。
+3. `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 与 Console。
 5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。

package/docs/architecture/dag-execution.md

@@ -44,7 +44,7 @@ src/commands/dag-validate.ts  runDagValidate
 ### 专用 taskKind 与模板选择（架构摘要）
 
 - `initHybridDagFromTask` 按 `task.json.taskKind`（及前端需求自动分类）选择专用拓扑：`frontend-implementation`、`frontend-test`、`backend-test`、`knowledge-sync`、`knowledge-graph-bootstrap` 等；默认 `standard` 走 governance profile 通用实现链。
-- **backend-test（0.17.x）**：Markdown-first 固定短链（环境硬门 → Markdown 用例/Review → 单次 pytest + HTML → 报告与 L-5）；不在本页展开节点清单，见 `docs/design/backend-test-workflow.md` 与 completed markdown-first plan。
+- **backend-test（0.17.x）**：Markdown-first 固定短链（环境硬门 → Markdown 用例/Review → 单次 pytest + HTML → 报告与 L-5）；不在本页展开节点清单，见 `docs/design/active/backend-test-workflow.md` 与 completed markdown-first plan。
 - 专用模板不是新的 governance profile：风险等级仍由 profile 规则判断；写边界仍受 `allowedPaths` / `forbiddenPaths` / `writeSet` 约束。
 
 ## rank 调度
@@ -103,7 +103,7 @@ decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析
 
 ## 自适应 liveness（节点活动 vs runner lease）
 
-实现见 `src/workflows/dag/liveness-policy.ts` 与设计文档 `docs/design/dag-adaptive-liveness-and-supervision.md`。
+实现见 `src/workflows/dag/liveness-policy.ts` 与设计文档 `docs/design/active/dag-adaptive-liveness-and-supervision.md`。
 
 - **runner lease**（`runner.heartbeatAt`，约 15s）只证明 runner 进程事件循环；**不是** Pi meaningful progress。
 - **真实活动**：SDK provider/tool event 与 CLI stdout|stderr 刷新 provider/tool/output；attempt-fenced，旧 attempt 晚到事件 no-op。SDK noisy delta 只续租 transport watchdog，不刷新 meaningful progress。

package/docs/architecture/evolution.md

@@ -2,9 +2,9 @@
 
 本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0005、`docs/exec-plans/completed/` 与 `docs/exec-plans/active/`。
 
-**对照版本：`@tea-agent/loop-agent@0.18.0`（2026-07-22）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
+**对照版本：`@tea-agent/loop-agent@0.23.1`（2026-07-25）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
 
-## 当前已实现（累计至 0.18.0）
+## 当前已实现（累计至 0.22.0）
 
 | 域 | 现状 | 权威入口 |
 | --- | --- | --- |
@@ -17,16 +17,18 @@
 | Ready Planner | priority 选择；`batch plan-ready` 零写入；`run-ready` 冻结 plan；产物门禁 | `CHANGELOG.md [0.13.0]` / `[0.16.0]` |
 | TaskSpec → workflow | 可选 `execution.workflow` → `taskKind`；typed Outcome；`fullstack-v1` Verification Bundle | completed `2026-07-19-taskspec-workflow-routing.md`、`CHANGELOG.md [0.16.0]` |
 | 专用 taskKind DAG | `frontend-implementation` / `frontend-test` / `backend-test` / knowledge* | `website/docs/guides/agent-dag.md`、`CHANGELOG.md [0.12.0]`–`[0.17.x]` |
-| Backend-test | **Markdown-first 8 节点**（env → MD cases/review → 单次 pytest+HTML → report+L-5）；历史 JSON 读兼容 | completed `2026-07-22-backend-test-markdown-first-8-node.md` |
-| Frontend-test | 默认 short-chain RAG；结果链 / Outcome 投影；formal smoke 仍 active | `CHANGELOG.md [0.16.24]`；active success-rate plan |
-| Frontend-implementation | Contract / trace / repair / Mock assess；条件 design/repair 分支 | `CHANGELOG.md [0.13.0]` / `[0.17.x]` |
+| Backend-test | **Markdown-first 8 节点**；Markdown 映射限定 pytest 执行，生成 Markdown 与分层 HTML/脱敏请求响应详情 | completed `2026-07-24-backend-test-scoped-execution-report-ui.md`；`CHANGELOG.md [0.21.0]` / `[0.22.0]` |
+| Frontend-test | 默认 short-chain RAG；内容/evidence 质量进入 advisory findings，路径与安全边界仍 fail-closed | `CHANGELOG.md [0.21.0]` / `[0.22.0]` |
+| Frontend-implementation | Contract / trace / repair / Mock assess；`ai_workspace` + 知识库 + `openspec` 规范发现；lint 基线债务隔离 | `CHANGELOG.md [0.22.0]` |
 | Inspect（原 Observe） | 统一 Console 的 `/inspect/` 只读运营面与富时间线；兼容期仍保留独立 `observe serve` | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [Unreleased]` |
 | Local Operator Console | `agent-worker console serve\|doctor`（loopback）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**非**远端多用户 Console | unify design；ADR 0005 |
 | Task Contract / operator surface | journaled `task contract *`；machine envelope；**DagSpec v4 `taskContractBinding`**（exclusive writer 强制） | `CHANGELOG.md [0.17.0]`–`[0.17.2]`；ADR 0005 |
 | DagSpec / repair | v3 `runtimeContract` + 显式 `repairNodeId`；新 writer 生成默认 v4 binding | `dag-execution.md`、`CHANGELOG.md [0.11.0]` / `[0.17.0]` |
+| 自适应 liveness | runner lease、Provider/tool/output 活动与 meaningful progress 分离；静默 stall 受控终止，退出未确认时禁止自动重试 | `dag-execution.md`、active `2026-07-23-dag-adaptive-liveness.md` |
+| 运行恢复 | 节点内协议纠错重试、`dag rerun` 安全子图续跑、`dag rerun-task` 完整任务重跑与 Console Recovery | `CHANGELOG.md [0.20.1]`、active `2026-07-23-operator-rerun-hardening.md` |
 | Eval Lab | corpus / campaign / promote（人工门禁）；`autoPromote=false`；**非** RSI Level 1 | `CHANGELOG.md [0.15.0]`；active plan 可归档 |
 | 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
-| 文档治理 | 本目录架构主题文档 + package 可达；reports/progress/completed 导读制 | 本目录 README、`docs/README.md` |
+| 文档治理 | 任务式 Start Here、机器可读身份清单、目录默认身份与版本/索引语义检查 | 本目录 README、`docs/README.md`、`docs/document-catalog.json` |
 
 ### 受治理 runtime 的边界（已实现、不变式）
 
@@ -37,25 +39,25 @@
 
 ## 未来规划（第 3–6 月，**未实现**）
 
-以下能力来自 `docs/design/六个月规划.md` 与相关设计输入（页首校准条之后的未交付 phase 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
+以下能力来自 `docs/design/active/六个月规划.md` 与相关设计输入（页首校准条之后的未交付 phase 为**设计输入**）。它们**当前不存在于产品声称的线上形态**，或仅有本地/部分替代：
 
 | 未来方向 | 状态 | 规划来源 |
 | --- | --- | --- |
-| 远程 PR / CI 自动创建与写回 | 规划 / 未实现 | `docs/design/六个月规划.md`（第 3 个月起） |
+| 远程 PR / CI 自动创建与写回 | 规划 / 未实现 | `docs/design/active/六个月规划.md`（第 3 个月起） |
 | 线上 / 云 Worker | 规划 / 未实现 | 同上 |
 | 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
 | 多仓库平台 | 规划 / 未实现 | 同上 |
 | 组织级服务 | 规划 / 未实现 | 同上 |
-| Web Console（远端多用户） | 规划 / 未实现；**不等于**已发布的本地 loopback Operator Console | 同上；对照 `docs/design/local-operator-console-from-pi-web.md` |
+| Web Console（远端多用户） | 规划 / 未实现；**不等于**已发布的本地 loopback Operator Console | 同上；对照 `docs/design/active/local-operator-console-from-pi-web.md` |
 | fullstack Delivery / Final Verification live 闭环 | 进行中（active train） | `docs/exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` |
-| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md` |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/active/dynamic-workflow-dag-engine-roadmap.md` |
 | Loop 与 Dynamic Workflow 更深双向集成 / 自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action |
 | Console Phase 4 General Operator Chat | 规划 / 未实现 | Console design residual |
 | Eval Lab auto-promote / RSI Level 1 产品声称 | **禁止**写成已交付 | Eval Lab design + active plan |
 
-> 本地 Operator Console 统一面（0.18.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
+> 本地 Operator Console 统一面（实际首发 0.19.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
 
-> 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+> 注意：`docs/design/active/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
 
 ## 已收敛为 archive / 历史基线（非未来）