@tea-agent/loop-agent 0.22.0 → 0.24.0

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-27** — 对齐 `@tea-agent/loop-agent@0.24.0`。版本事实以根 `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,18 +2,19 @@
 
 本目录是 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-27** — 索引与演进叙述对齐仓库头 `@tea-agent/loop-agent@0.24.0`。边界表仍以 `runtime-boundaries.md` 与 `scripts/check-*.sh` 为准。
 
 ## 阅读路径
 
 建议按以下顺序阅读——先全景，再主路径，再边界/事实，最后路线：
 
 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 与 Console。
-5. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
-6. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
+2. `agents-invariants.md` — `AGENTS.md`（source）与 init managed block 的「什么不能删」不变量契约（短语真源 + 行数 guardrail 语义）。
+3. `system-overview.md` — loop-agent / agent-worker / 治理层 / 外部系统的全景关系。
+4. `dag-execution.md` — Agent DAG 主调用链、rank 调度、executor、skill snapshot、生命周期。
+5. `worker-and-feature.md` — agent-worker 子进程边界、controller identity、Task Pool、Feature、Observe 与 Console。
+6. `facts-and-state.md` — `.harness/` 各根目录、canonical facts、derived read models 与不可变规则。
+7. `evolution.md` — 当前已实现能力 vs 第 3–6 月未来方向（明确标注规划/未实现）。
 
 ## 事实与规划的区分
 

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.24.0`（2026-07-27）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
 
-## 当前已实现（累计至 0.18.0）
+## 当前已实现（累计至 0.24.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 |
+| Local Operator Console | `agent-worker console serve\|doctor`（loopback）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**0.23.x 起含 General Operator Chat**（Pi SDK services session、operator-only tool surface）；**非**远端多用户 Console | unify design；ADR 0005；completed `2026-07-25-console-phase-4-general-operator-chat.md` |
 | 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 |
+| Operator Chat 作为主操作会话（裸 bash 收敛、真 human gate、durable session/turn、Operation 闭环、完整 CLI action coverage、默认入口切换） | 设计输入 / 未达主会话门槛 | `docs/design/active/operator-chat-primary-session-roadmap.md`；Phase 4 General Operator Chat 本体已实现归档（`docs/exec-plans/completed/2026-07-25-console-phase-4-general-operator-chat.md`） |
 | 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 / 历史基线（非未来）
 

package/docs/architecture/system-overview.md

@@ -64,7 +64,7 @@ workflow runtime（调度 Pi / shell / static 节点）
 - `agent-worker console serve|doctor` 提供 loopback Operator Console（默认 `127.0.0.1:8790`）；Happy Path / Interview 策略面、Task Contract 落地与 recovery CTA 已随 **0.17.0–0.17.2** 发布。
 - canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
 - Observe 保持**独立**只读进程（默认 `8787`）；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
-- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
+- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/active/local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
 
 ## 外部边界
 

package/docs/architecture/worker-and-feature.md

@@ -2,7 +2,7 @@
 
 本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与统一 Operator Console（Operate + Inspect）。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
 
-**维护校准：2026-07-22 / `@tea-agent/loop-agent@0.18.0`** — 统一 Operator Console（Operate + Inspect）已落地；细节以 `CHANGELOG.md` 与 active unify plan 为准。
+**维护校准：2026-07-27 / `@tea-agent/loop-agent@0.24.0`** — 统一 Operator Console（Operate + Inspect）、恢复操作面与自适应 liveness 已落地；细节以 `CHANGELOG.md` 与对应 active/completed plan 为准。
 
 ## 核心事实：子进程，非 in-process
 
@@ -25,7 +25,7 @@
 - 显式 `worker.timeout_ms` → hard kill（可 capped），观察到 exit 后可报 `timedOut`。
 - 客户端 `onHeartbeat` 仍是监管心跳，不等于 Pi meaningful progress。
 
-设计真源：`docs/design/dag-adaptive-liveness-and-supervision.md`。
+设计真源：`docs/design/active/dag-adaptive-liveness-and-supervision.md`。
 
 ## controller identity（冻结的已发布 controller）
 
@@ -62,7 +62,7 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 - schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
 - 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
 - **0.16.0+**：可选 `execution.workflow` 映射到 loop-agent `taskKind`（如 agent-dag / frontend-implementation / backend-test / frontend-test）；typed Task Outcome 与 artifact-aware Ready 门禁见 completed `2026-07-19-taskspec-workflow-routing.md`。
-- 文档映射镜像：`docs/design/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
+- 文档映射镜像：`docs/design/active/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
 
 ### Task Pool
 

package/docs/governance/README.md

@@ -0,0 +1,15 @@
+# 工程治理
+
+这里放的是“怎么推进一次工作”的长期规则。开始实现前先读工作流，需要选择验证命令时再看验证矩阵；三份方法论文档用于测试、完成声明和故障排查。
+
+## 入口
+
+- [`development-principles.md`](development-principles.md)：工程原则与完成纪律。
+- [`feature-workflow.md`](feature-workflow.md)：会话治理、taskKind、profile 与 Agent DAG 路径。
+- [`verification-matrix.md`](verification-matrix.md)：按变更类型选择验证命令。
+- [`harness-methodology-tdd.md`](harness-methodology-tdd.md)：测试先行的方法与边界。
+- [`harness-methodology-verification.md`](harness-methodology-verification.md)：如何用新鲜命令结果支持完成声明。
+- [`harness-methodology-debugging.md`](harness-methodology-debugging.md)：系统化定位故障，不用猜测代替证据。
+- [`document-review-policy.md`](document-review-policy.md)：文档 freshness、`reviewTier` 与 `lastReviewed` 更新边界。
+
+架构事实见 [`../architecture/README.md`](../architecture/README.md)，运行手册见 [`../runtime/README.md`](../runtime/README.md)，日常维护操作见 [`../operations/README.md`](../operations/README.md)。

package/docs/{harness-methodology-debugging.md → governance/harness-methodology-debugging.md}

@@ -10,6 +10,27 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 没有完成 Phase 1（根因调查），就不能提出任何修复方案。修症状 = 失败。
 
+## 前置：构建反馈回路（Phase 1 的地基）
+
+在读代码猜原因、列假设或动手修复之前，先建立一条**快速、确定性、Agent 可运行**的 pass/fail 信号。后续复现、假设、插桩和修复都消费这条回路，而不是依赖聊天里的印象。
+
+按优先级选用（能用更靠前的就不要降级）：
+
+1. 失败测试（已有或最小新增）
+2. HTTP / API 脚本（固定输入 → 断言状态码或响应）
+3. CLI fixture / snapshot
+4. 浏览器脚本（确定性交互 + 断言）
+5. Trace / log replay
+6. 一次性本地 harness（最小复现命令）
+7. Property / fuzz（非确定性边界）
+8. `git bisect run`（回归定位）
+9. 新旧版本 differential
+10. 结构化 HITL 脚本（仅当自动化回路不可得，且人工步骤可重复）
+
+把回路本身当作产品优化：更快、更锋利、更确定性。间歇性问题先提高复现率，再进入根因调查。
+
+**不能建立回路时：停下。** 请求缺失的环境、artifact、凭据或临时插桩许可；不要在没有 pass/fail 信号时继续猜。
+
 ## 何时使用
 
 适用于任何技术问题：
@@ -28,7 +49,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 ## 四阶段流程
 
-每个阶段必须完成才能进入下一个。
+每个阶段必须完成才能进入下一个。反馈回路是 Phase 1 的地基，不是第五阶段。
 
 ### Phase 1：根因调查
 
@@ -113,6 +134,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 ## Red Flags：停止并回到 Phase 1
 
 如果你发现自己这样想：
+- "没有 pass/fail 回路，先读代码猜原因"
 - "先快速修一下，后面再调查"
 - "试试改 X 看看行不行"
 - "一次改多个东西然后跑测试"
@@ -121,13 +143,14 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 - "不太确定但可能有用"
 - "再试一个修复"（已经试了 2+ 次）
 
-**以上任何一种 → 停止。回到 Phase 1。**
+**以上任何一种 → 停止。回到反馈回路 / Phase 1。**
 
 ## 和 Harness 工作流的对齐
 
 | 调试阶段 | Harness 步骤 |
 |---------|-------------|
-| Phase 1：根因调查 | Baseline：先验证当前基线，确认 bug 是可复现的 |
+| 反馈回路 | Baseline / Reproduction evidence：先有可重复的 pass/fail 信号 |
+| Phase 1：根因调查 | Baseline：确认 bug 可复现，并收集证据 |
 | Phase 2：模式分析 | Orient：读相关代码、文档、测试，找参考 |
 | Phase 3：假设测试 | Contract：写清修复假设和验证方法 |
 | Phase 4：实现 | Implement → Verify（TDD：先写失败测试） |
@@ -137,6 +160,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 | 阶段 | 关键活动 | 成功标准 |
 |------|---------|---------|
+| 0. 反馈回路 | 建立快速确定性 pass/fail 信号 | 有可重复命令与退出码 |
 | 1. 根因 | 读错误、复现、查变更、收集证据 | 理解 WHAT 和 WHY |
 | 2. 模式 | 找工作中的例子、对比 | 识别差异 |
 | 3. 假设 | 形成理论、最小测试 | 确认或新假设 |

package/docs/init-surface.manifest.json

@@ -8,10 +8,10 @@
     "harness.json",
     "bin/loop-agent.js",
     "docs/README.md",
-    "docs/harness-methodology-tdd.md",
-    "docs/harness-methodology-verification.md",
-    "docs/harness-methodology-debugging.md",
-    "docs/local-development-environment.md",
+    "docs/governance/harness-methodology-tdd.md",
+    "docs/governance/harness-methodology-verification.md",
+    "docs/governance/harness-methodology-debugging.md",
+    "docs/operations/local-development-environment.md",
     "docs/init-surface.manifest.json",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
@@ -22,6 +22,7 @@
     "docs/architecture/evolution.md",
     "docs/skills/README.md",
     "docs/skills/vetted-skill-registry.md",
+    "docs/templates/README.md",
     "docs/templates/init-evolution-review.md",
     "docs/templates/exec-plan.md",
     "docs/templates/production-readiness-checklist.md",
@@ -63,6 +64,9 @@
     "skills/test-driven-development/SKILL.md",
     "skills/code-review-core/SKILL.md",
     "skills/init-capability-evolution/SKILL.md",
+    "skills/grill-with-docs/SKILL.md",
+    "skills/grill-with-docs/context-format.md",
+    "skills/grill-with-docs/adr-format.md",
     "skills/webapp-testing/SKILL.md",
     "skills/playwright-cli/SKILL.md",
     "skills/playwright-cli-case-generator/SKILL.md",
@@ -91,6 +95,10 @@
     "docs/feature-workflow.md",
     "docs/verification-matrix.md",
     "docs/loop-agent-harness.md",
+    "docs/harness-methodology-tdd.md",
+    "docs/harness-methodology-verification.md",
+    "docs/harness-methodology-debugging.md",
+    "docs/templates/README.md",
     "docs/templates/init-evolution-review.md",
     "docs/templates/production-readiness-checklist.md",
     "docs/templates/frontend-task-requirement.md",
@@ -133,6 +141,9 @@
     ".agents/skills/test-driven-development/SKILL.md",
     ".agents/skills/code-review-core/SKILL.md",
     ".agents/skills/init-capability-evolution/SKILL.md",
+    ".agents/skills/grill-with-docs/SKILL.md",
+    ".agents/skills/grill-with-docs/context-format.md",
+    ".agents/skills/grill-with-docs/adr-format.md",
     ".agents/skills/webapp-testing/SKILL.md",
     ".agents/skills/playwright-cli/SKILL.md",
     ".agents/skills/playwright-cli-case-generator/SKILL.md",
@@ -161,6 +172,10 @@
     "docs/feature-workflow.md": "generated",
     "docs/verification-matrix.md": "generated",
     "docs/loop-agent-harness.md": "generated",
+    "docs/harness-methodology-tdd.md": "copied",
+    "docs/harness-methodology-verification.md": "copied",
+    "docs/harness-methodology-debugging.md": "copied",
+    "docs/templates/README.md": "copied",
     "docs/templates/init-evolution-review.md": "copied",
     "docs/templates/production-readiness-checklist.md": "copied",
     "docs/templates/frontend-task-requirement.md": "copied",
@@ -204,6 +219,9 @@
     ".agents/skills/test-driven-development/SKILL.md": "copied",
     ".agents/skills/code-review-core/SKILL.md": "copied",
     ".agents/skills/init-capability-evolution/SKILL.md": "copied",
+    ".agents/skills/grill-with-docs/SKILL.md": "copied",
+    ".agents/skills/grill-with-docs/context-format.md": "copied",
+    ".agents/skills/grill-with-docs/adr-format.md": "copied",
     ".agents/skills/webapp-testing/SKILL.md": "copied",
     ".agents/skills/playwright-cli/SKILL.md": "copied",
     ".agents/skills/playwright-cli-case-generator/SKILL.md": "copied",

package/docs/operations/README.md

@@ -0,0 +1,12 @@
+# 维护与协作
+
+这里收录维护仓库时会直接照着执行的操作手册。
+
+## 入口
+
+- [`local-development-environment.md`](local-development-environment.md)：本地环境、Windows 差异和常见排障。
+- [`branch-merge-guideline.md`](branch-merge-guideline.md)：按风险选择合并模式并留下 source-SHA 证据。
+- [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定。
+- [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
+
+验证命令仍以 [`../governance/verification-matrix.md`](../governance/verification-matrix.md) 为准。

package/docs/{local-development-environment.md → operations/local-development-environment.md}

@@ -1,6 +1,6 @@
 # 本地开发环境排障
 
-本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](verification-matrix.md) 为准。
+本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](../governance/verification-matrix.md) 为准。
 
 ## Cursor Cloud