@tea-agent/loop-agent 0.22.0 → 0.23.1

package/AGENTS.md

@@ -14,140 +14,74 @@
 
 - 仓库是记录系统：决策、契约、计划、测试、报告优先落到仓库，而不是停留在聊天里。
 - 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
-- 先验证基线，再叠加改动；如果当前基线已坏，优先定位基线问题。
+- 先验证基线，再叠加改动；完成定义必须可验证，不能靠删测试、降标准或模糊描述制造“完成”。
 - Do not consider backward compatibility. Ignore legacy code/libraries.
-- 完成定义必须可验证；不能靠删测试、降标准或模糊描述制造“完成”。
-- 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
-- 受治理 Agent runtime 只有 Pi：DAG writer 固定为 `implement-pi` / `repair-pi`；`cursor-prompt` 仅是显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。
-- 在 DAG runtime 中，搜索/侦察是显式节点：标准路径是 Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
-- init surface、runtime 边界、command registry、skill entry 和架构 import 方向是可机器校验的治理契约；相关细节以 `docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/` 和 `scripts/check-*.sh` 为准，顶层 `AGENTS.md` 只指路，不重复维护事实源。
-- 本仓库既是 loop-agent 源项目，也是目标项目初始化体验的默认模板；任何新增命令、脚本、文档、skill、模板或发布包内容，都要判断它应由 npm 包内置提供，还是由 `loop-agent init` 投影到目标项目，避免出现“本项目能用、初始化项目缺能力”。
-- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。
-- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本确为 Bash 脚本时使用 Git Bash 或已配置的兼容 Bash，不要求 Windows 环境适配 POSIX 路径。
-- 用 loop-agent 迭代本仓库时，控制器必须来自已发布的 npm 安装包；首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制可能改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务。
-- 反复出现的约束要固化为文档、脚本、检查项、测试或模板。
-- 除非用户明确要求，不要自行引入外部 SDD、spec-first、brainstorming 等方法论的强制设计文档、审批门或专用目录；本仓库的工作流程以本文件和 `docs/` 中的治理规则为准。
-- 对非微小的实现或修复，`exec-plan` 只负责记录 Contract、进度和验证证据，不能替代 Agent DAG。除非用户明确要求 one-shot，或在计划中记录了适用的 escape hatch 与理由，否则在改动实现文件前必须完成 `new-task`、结构化 `allowedPaths` / `forbiddenPaths`、`dag run-task` 和 `dag validate`；随后按已校验的 DAG 执行并审查 writer `writeSet`。
-- 禁止占位实现；除非 contract 明确约定为脚手架且标出后续闭环。
+- 搜索先于实现；受治理 Agent runtime 只有 Pi（`implement-pi` / `repair-pi`）；`cursor-prompt` 仅为显式手工 one-shot sidecar。
+- DAG 标准路径：Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
+- 机器校验契约真源：`docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/`、`scripts/check-*.sh`；本文件只指路。
+- 本仓库既是源项目也是 init 默认模板；新增能力必须判断 npm 内置 vs `loop-agent init` 投影。
+- 委托写入前必须结构化 `task.json.allowedPaths` / `forbiddenPaths`，并审查 DAG writer `writeSet`。
+- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本用 Git Bash / 兼容 Bash。
+- 用 loop-agent 迭代本仓库时，控制器必须来自已发布 npm 包（记录实际版本）；启动后不要中途升级；不要用工作区 `npm link` / `npm run dev` 控制可能改 CLI/runtime/package 的任务。
+- 反复出现的约束固化为文档、脚本、检查、测试或模板；禁止占位实现（除非 contract 标明脚手架）。
+- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `new-task`、结构化路径、`dag run-task`、`dag validate` 与 writeSet 审查。
+- 不要自行引入外部 SDD/spec-first 等强制平行治理树；以本文件与 `docs/` 为准（ADR 0006）。
 
 ## 开始顺序
 
 改文件前必须先完成：
 
-1. 运行 `pwd`。
-2. 阅读 `README.md`。
-3. 阅读 `harness.json`。
-4. 阅读 `docs/README.md`。
-5. 如果存在 `CONTEXT.md`，阅读项目术语表，避免混用任务源、执行约束、契约、计划等领域概念。
-6. 如果是实现类工作，继续阅读：
-   - `docs/development-principles.md`
-   - `docs/feature-workflow.md`
-   - `docs/verification-matrix.md`
-7. 如果任务涉及命令入口、执行流程、executor、初始化投影、skills、脚本矩阵、发布包范围或治理检查，继续阅读：
-   - `docs/architecture/runtime-boundaries.md`
-   - `docs/loop-agent-harness.md`
-8. 如果任务涉及测试纪律、验证声明或调试，继续阅读：
-   - `docs/harness-methodology-tdd.md`
-   - `docs/harness-methodology-verification.md`
-   - `docs/harness-methodology-debugging.md`
-9. 查看最近提交、相关执行计划、progress/report，确认当前上下文。
-10. 检查 `git status --short --branch`。
-11. 运行本次任务相关的最小基线验证。
-12. 如果用户提到"后端测试"、"接口测试"、"pytest"、"自动化测试"，在任务 `task.json` 中设置 `taskKind: "backend-test"` 再 `dag run-task`；不要用 `--profile backend-test`（CLI 不接受该值，专用模板只走 taskKind）。知识回写用 `taskKind: "knowledge-sync"`（须 `featureId`），图谱开荒用 `taskKind: "knowledge-graph-bootstrap"`。`--profile` 仅表示治理强度：`auto|minimal|standard|reviewed|supervised`。
-13. 如果用户提到"看板"、"observe"、"监控面板"、"启动看板"，使用 `agent-worker console serve --repo . --port 8790` 启动统一 Operator Console；`/inspect/` 提供只读检视。`agent-worker observe serve --repo . --port 8787` 仅为兼容入口。
-14. 如果用户要求“合并 `<source>` 到 `<target>`”或“合并 origin/main 到当前分支”，先阅读 `docs/branch-merge-guideline.md`，按影响自动选择快速、标准或深度模式；始终冻结 source SHA、审查双方功能、运行 merge-tree、生成 source-SHA 合并报告，并在提交前再次 fetch 防止主干前进。
+1. `pwd` → 读 `README.md`、`harness.json`、`docs/README.md`；有 `CONTEXT.md` 则读术语表。
+2. 实现类工作继续读：`docs/governance/development-principles.md`、`docs/governance/feature-workflow.md`、`docs/governance/verification-matrix.md`。
+3. 涉及命令/executor/init/skills/发布包/治理检查时继续读：`docs/architecture/runtime-boundaries.md`、`docs/runtime/loop-agent-harness.md`。
+4. 涉及测试纪律/验证声明/调试时继续读：`docs/governance/harness-methodology-*.md`。
+5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
+6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
+7. 看板/observe → `agent-worker console serve --repo . --port 8790`（`/inspect/` 只读）；`observe serve` 仅为兼容入口。
+8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
 
 ## 会话协议
 
-1. Orient：读入口文档、相关专题、最近变更和现有实现。
-2. Select：只选一个清晰工作块；避免把重构、新功能、文档迁移混在一轮里。
-3. Contract：写清本轮交付物、非目标、完成标准、验证方法和失败条件。
-4. Implement：做最小增量实现，同步维护必要文档、脚本和测试。
-5. Verify：优先跑快速反馈，再跑必要的真实路径验证。
-6. Converge Docs：检查 README、AGENTS.md、CHANGELOG.md、docs/README.md、相关治理文档、skills references、website docs、初始化模板和脚本说明是否仍与实际行为一致；只更新与本次变更相关的内容，不做顺手文档迁移。
-7. Handoff：更新 progress/report/plan 中有长期价值的信息，写清风险、剩余项和下一步。
+1. Orient → 2. Select（一块）→ 3. Contract → 4. Implement → 5. Verify → 6. Converge Docs → 7. Handoff。
 
-这套会话协议不是 DAG runtime 的节点序列。复杂实现默认采用 Agent DAG；具体节点拓扑、profile routing、writer 选择和 runner 行为以 `docs/feature-workflow.md` 与 `src/workflows/` 为准。主 agent 负责拆任务、写 contract、把允许/禁止路径写入结构化 task config、审查 DAG/writeSet/profile/shell verification、盯验证与 handoff。微小任务或 DAG runtime 自身修复也应优先使用 DAG，或使用 one-shot `pi-prompt` / `cursor-prompt` escape hatch 并记录边界与验证证据。
+这不是 DAG 节点序列。复杂实现默认 Agent DAG；主 agent 拆任务、写 contract、结构化路径、审查 DAG/writeSet/profile/shell verification。微小任务可用 one-shot escape hatch 并记录边界与验证证据。
 
 ## 项目地图
 
-- `CONTEXT.md`：项目术语表，定义 loop-agent、任务源、执行约束等领域语言
-- `src/`：loop-agent 运行时代码
-- `test/`：Vitest 测试套件
-- `bin/loop-agent.js`：CLI 可执行入口
-- `skills/`：loop-agent 源仓库和 npm 包内置 skill 指令与参考资料；目标项目初始化后只生成 `.agents/skills/`，不再生成根 `skills/`。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block，忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/evaluation/`、`.harness/dogfood-evidence/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实，但保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`。
-- `.harness/`：任务、DAG、run、cache 和 live state 等运行态目录
-- `docs/`：治理文档、计划、报告和模板
-- `website/`：Docusaurus 用户文档站
-- `scripts/`：验证和维护脚本
-
-## 工作规则
-
-- 每次任务只推进一个清晰、有边界的工作块。
-- 保留无关的用户改动，不要回退自己没有做的修改。
-- 优先沿用现有 helper、目录边界和局部模式，再考虑新增抽象。
-- 长期决策写入 `docs/`，不要只留在聊天里。
-- 分支合并遵循 `docs/branch-merge-guideline.md`；快速模式只用于可证明的低风险/no-op 合并，涉及冲突、init/package/runtime/release/public API 时必须升级为标准或深度模式。
-- 后端测试、接口/API 测试、pytest 或明确的后端自动化测试，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"backend-test"`，不得保留默认 `standard`。`backend-test` 是 `taskKind`，不是 `--profile` 的可选值；`dag run-task` 继续使用 `--profile auto` 选择治理等级。仅说“自动化测试”且前后端不明时，先根据任务源和项目技术栈判断，禁止无条件路由。
-- 本地 Operator Console：`agent-worker console serve --repo . --port 8790`，访问 `http://127.0.0.1:8790/`；其中 `/inspect/` 为只读运行检视。默认绑定本机 `127.0.0.1`；可用 `--host 0.0.0.0` / `--debug`，不要直接暴露到公开网络。
-- 面向使用者的新增、修改、删除或修复，应同步更新根目录 `CHANGELOG.md`；保持版本级摘要即可，不写过细技术细节。
-- 面向用户的中文更新日志、README 和说明文档应使用自然、结果导向的表达：先说明用户能获得什么或问题如何改善，保留必要的命令和产品术语，避免逐字翻译、内部实现细节和无意义的中英混杂。
-- 涉及 `loop-agent init` 或目标项目投影的改动，必须同步考虑目标项目生成物：`AGENTS.md`、`README.md`、`harness.json`、`ai_workspace/loop-agent/`、`scripts/`、`.agents/skills/`、`.harness/prompts`、`.gitignore`（loop-agent runtime managed block）和 npm 包内置 assets；目标项目根 `docs/` 和根 `skills/` 的旧投影需要由 `init update --apply-safe` 安全迁移或退役。
-- 涉及初始化能力演化时，按 `docs/init-surface.manifest.json` 与 `scripts/check-init-evolution-needed.sh` 分级处理：小改 advisory，中等 surface-check，高影响才需要模型审查；不要把所有小改动升级成重流程。
-- 通用脚本、skill 和模板可以复制或投影；项目相关 README、验证命令、发布/维护脚本必须基于模板和目标项目真实文件生成，不假定目标项目是 TypeScript、Node、前端、后端或工具项目。
-- 涉及 CLI command、skill entry、runtime boundary、import 方向或发布包范围时，同步更新对应文档、catalog/definition、治理脚本和测试，避免 README、skill reference、CLI help、npm 包内容互相漂移。
-- 完成相关更新后必须做文档收敛：如果 README、AGENTS.md、CHANGELOG.md、docs、skills、website、初始化生成模板或脚本说明不需要更新，应在交接里写明理由。
-- 不提交占位实现。
-- 没有新鲜验证证据时，不声明工作完成。
-- 发现新 bug、技术债或契约漂移时，写回当前 plan、progress 或 report，而不是只在对话里提一句。
-- 涉及 harness 流程变化时，优先把变化落到 `harness.json`、模板、脚本或治理文档，而不是只改提示词。
+- `CONTEXT.md`：术语表
+- `src/`：运行时；`test/`：Vitest；`bin/loop-agent.js`：CLI
+- `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
+- `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
+- `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
+
+## 工作规则（增量约束）
+
+- 保留无关用户改动；优先沿用现有 helper/目录边界。
+- 长期决策写入 `docs/`；面向用户变更更新 `CHANGELOG.md`（结果导向中文）。
+- init/投影变更必须同步目标项目生成物与 package assets；init evolution 按 `docs/init-surface.manifest.json` 分级。
+- CLI/skill entry/runtime boundary/发布包变更同步 catalog、脚本与测试。
+- 没有新鲜验证证据时不声明完成；新债写入 plan/progress/report。
 
 ## 验证
 
-用 `docs/verification-matrix.md` 选择命令。常用门禁：
+权威源：`docs/governance/verification-matrix.md`。常用：
 
 ```bash
-npm run typecheck
-npm test
-npm run build
+npm run typecheck && npm test && npm run build
 node bin/loop-agent.js --help
 bash scripts/check-repo.sh
 bash scripts/ci.sh
 ```
 
-Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash。CLI、Node 代码、模板和提示词里的实际文件路径必须兼容 macOS 与 Windows：优先使用平台原生临时目录和 `path`/`os.tmpdir()`；仅在 repo 引用、JSON/Markdown 证据引用和 glob 约定中使用 `/` 作为稳定分隔符。
-
-文档站相关变更还需要按范围运行：
-
-```bash
-npm run docs:build
-```
-
-按变更类型补充定向验证：
-
-- 初始化能力或目标项目投影：运行 `test/init-command.test.ts`，并在临时目标项目执行 `loop-agent init --profile full --merge`、`loop-agent init doctor`、`loop-agent inspect`、`loop-agent docs audit` 和目标项目 `bash scripts/check-repo.sh`。
-- init surface 或初始化能力演化：运行 `bash scripts/check-init-evolution-needed.sh` 和 `bash scripts/check-init-surface.sh`；高影响或发布前按需使用 `--strict` 并参考 `skills/init-capability-evolution/` 与 `docs/templates/init-evolution-review.md`。
-- runtime boundary / command registry / skill entry：运行 `bash scripts/check-architecture-boundaries.sh`、`bash scripts/check-command-registry-drift.sh`、`bash scripts/check-skill-entry.sh`，并确保 `bash scripts/check-repo.sh` 覆盖这些检查。
-- 发布包范围：运行 `npm run build`、`node bin/loop-agent.js --help` 和 `npm pack --dry-run`，确认初始化所需静态资料在 package files 中。
+文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。
 
 ## 交接
 
-较大的工作结束时记录：
-
-- 改了什么
-- 为什么这样改
-- 执行过哪些验证命令以及结果
-- 是否影响契约、文档、测试或脚本
-- 剩余风险
-- 后续工作
+记录：改了什么、为什么、验证命令与结果、契约/文档/测试影响、剩余风险、后续工作。
 
 ## 禁止事项
 
-- 不要在未读相关文档的前提下直接大改。
-- 不要一次混合重构、新功能和文档大迁移而没有清晰边界。
-- 不要把仅存在于对话里的约束当作长期知识。
-- 不要在缺少验证的情况下宣称完成。
-- 不要假设系统没有某个能力；先搜索再判断。
-- 不要用 stub、假数据通路或注释承诺替代真正交付。
-- 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料；个人工具配置应留在用户级配置或本机会话上下文。
-- 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验；新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目，必须写清原因和替代入口。
+- 未读相关文档就大改；一次混合无关重构/新功能/文档大迁移。
+- 把对话约束当长期知识；缺验证宣称完成；假设系统没有某能力（先搜索）。
+- stub/假数据通路替代交付；把本机绝对路径写入仓库级 AGENTS/README/模板/发布包。
+- 只更新本仓库体验而遗漏目标项目 init 体验。

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 ## [Unreleased]
 
+## [0.23.1] - 2026-07-26
+
+### 重点更新
+
+- **Console Phase 4 — General Operator Chat**：在 `agent-worker console` 内交付 Pi 驱动的自由对话入口，用自然语言多轮编排 loop-agent / agent-worker；暴露全部 operator action（registry 动态派生）+ 内置探查工具 bash/read/grep/find/ls，仍禁文件写入 coding tool；含两轮代码审查的 P1 修复（builtin tool 注册、schema↔dispatcher 契约、server 生命周期、tool policy 统一）与 followup 修复（缩进、SSE 错误兜底、文档同步、waitForIdle 超时+心跳）
+- DAG 新增显式 failure-aware 依赖语义，允许只读恢复节点容忍上游 ERROR 并读取失败证据执行收敛
+- review verdict 协议重试耗尽后支持确定性规范化，缺失或冲突时仍严格报错
+- 新增 recovery recommendation 稳定下一步分类，为各类失败提供明确的修复或重试路由提示
+- loop-agent doctor 新增机器可读 JSON 报告与只读上下文审计能力
+- loop-agent stats context 提供近端 DAG 运行的上下文用量只读聚合统计
+- AGENTS.md 与 init managed block 采用感知源码的精简策略，保留路由与硬约束不变
+- 全面深化文档治理体系，引入目录状态语义、审查策略与外部方法论单轨融入
+
+### 新增
+
+- **Console Phase 4 — General Operator Chat（Pi SDK services 模式）**：
+  - 后端 `src/worker/console/chat/`：`pi-runtime.ts`（services 模式 SDK 包装 + session 隔离 + 显式注册 builtin 探查工具 `tools:[bash,read,grep,find,ls]`）、`tool-adapter.ts`（operator action → Pi tool schema，动态发现 fail-closed）、`session-store.ts`（Gate 3 per-call 授权 + per-session write chain）、`routes.ts`（SSE 流式 HTTP）、`tools.ts`（全 operator action 动态派生白名单）、`resource-loader.ts`（封闭 ResourceLoader）、`model-resolver.ts`（harness.json 动态解析，无硬编码）、`instruction-skills.ts`（9 个只读 skill 白名单）
+  - 前端 `OperatorChat.tsx` + `ChatMarkdown.tsx`：多行 composer、Markdown 气泡、可折叠工具侧栏、停止生成、智能贴底滚动；零依赖 Markdown 渲染
+  - 默认模型从 `harness.json executors.pi.MED` 动态解析，按「bare-id 优先 + 有凭证优先」选取 provider（无硬编码回退）
+  - 红队验证 V12/V14/V15/V16：文件写入 coding tool 必拒、credential 不回传、高风险 action 无 prepared receipt 必失败、模型伪报 complete 不覆盖 deterministic validation
+- DAG 显式 failureAwareDependsOn 依赖语义，支持只读恢复等价节点显式声明容忍指定上游节点的 ERROR
+- review verdict 协议重试耗尽后的确定性规范化：当恰好存在一个合法受支持且无冲突的 verdict 行时自动规范化为首行
+- recovery recommendation 稳定下一步分类：为 nonzero-exit、protocol-invalid 等各类失败提供稳定的 repair/revision/retry 路由提示
+- loop-agent doctor --json 输出单一可 JSON.parse 的 typed DoctorReport，供人与机器共享同一事实源
+- loop-agent doctor --context 提供只读上下文审计，报告默认策略、技能清单与预算跳过情况
+- loop-agent stats context [--last N] [--json] 只读聚合最近 DAG 运行的技能解析与节点结果
+- 新增 scripts/eval-dogfood-context-engineering-ab.sh，支持复现演练 AGENTS map verbose→slim A/B 协议
+- skill registry 增加 verification placement taxonomy（standalone/embedded/chained/PR-bound）创作词汇
+- 新增 docs/architecture/agents-invariants.md 作为源 AGENTS 与 managed block 不变量合同的单一真源
+- 新增 docs/templates/README.md 并纳入 package / full init / init check-update 面
+- 新增文档治理任务式 README、机器可读 document-catalog.json 与 check-doc-governance.mjs 语义检查器
+- 新增文档审查策略与三档 reviewTier freshness 策略，支持按 UTC 日期边界阻断过期文档
+- 新增设计原则与范式转移起源文章，并发布到网站实践文档
+
+### 改进
+
+- supervised 模板的 process-supervisor-pi 可显式消费 soft-verify-shell 的 ERROR，使失败进入有界修复收敛链
+- supervised 中间验证未显式配置时不再继承 verifyQuota: full，默认只取配额 1
+- 生成 DAG 的验证命令默认单命令超时由 5 分钟提升为 30 分钟，避免全量测试误判为超时
+- failure-aware 节点可在 upstream_context 中读取被容忍上游 ERROR 的 stdout/stderr 等作为失败证据
+- loop-agent public skill 增加默认预算完整性回归，确保关键 entry 与 required references 在默认预算下完整解析
+- skills/loop-agent/SKILL.md 将 command-reference.md 从 required 调整为按需 reference，保持在默认预算内
+- doctor 与 stats context 的 JSON 模式不再输出 [loop-agent] banner，保证机器输出可直接解析
+- 源仓库 AGENTS.md 与 init managed block 采用感知源码的精简，长解释指向 docs/，保留开工路由与硬约束
+- 调试纪律要求先建立快速确定性反馈回路再进入根因调查；verifier skill 强调不得越过 writer 边界
+- 任务与 TDD 明确采用垂直 tracer bullet（一测试一实现），避免水平层批处理
+- ADR 增加三门槛过滤；CONTEXT.md 明确只承担术语表职责；grill-with-docs 按 governanceRoot 解析 decisions
+- 外部工程方法论按单轨治理融入 docs/skills/init（ADR 0006），不引入平行状态树
+- 文档治理完成当前权威与内容可信度审计，修正设计入口、能力摘要与网站 roadmap 中的归档状态表述
+- 文档治理完成实际归位，工程规则、runtime 手册和维护操作分别进入清晰目录，当前设计与历史设计分开
+- 文档入口版本与状态对齐 @tea-agent/loop-agent@0.22.0
+- Pi 中等复杂度节点默认模型由 glm-5.2 调整为 gpt-5.5；LOW 与 HIGH 路由保持不变
+
+### 修复
+
+- DAG run-task 持久化 writer 草稿生成前强制要求 managed Task Contract，未管理时在写出前失败并提示人工处理流程
+- Task source 指南修正 verifyCommands 示例为 { label, command, timeoutMs? }[]，并补充旧字符串数组迁移说明
+- 根 Vitest 配置排除 .worktrees/** 隔离 checkout，避免显式测试文件参数误收集旧副本
+- 受监督的 DAG 失败收敛机制修复，确保在有监督失败时保持收敛性
+- DAG bootstrap 合约反馈修复，确保引导阶段正确收敛
+- 修复 check-doc-governance.mjs 未忽略 .DS_Store/Thumbs.db 等 OS 生成文件导致仓库目录测试失败的问题
+- 修复 context-engineering 提案中指向 exec-plans/active/ 的过时链接，更新为实际的 completed/ 路径
+- 校准 context-engineering 提案中的实现证据（测试计数与 AGENTS.md 行数）以匹配当前代码实际产出
+- Console Phase 4 Chat 审查 followup：createSession 缩进规整；handleChatPrompt 加 try/catch+finally 兜底 SSE error 与 res.end；waitForIdle 超时 120s→45s 并新增每 10s heartbeat（SSE comment 帧）防代理超时；设计文档 §7.2.1/V25/§13 同步 widening 契约
+- Console Phase 4 Chat P1 审查修复：`createSessionFromServices` 显式传 `tools:[bash,read,grep,find,ls]`（SDK 默认 builtin 不含 grep/find/ls，否则 setActiveToolsByName 静默 no-op）；schema↔dispatcher 契约对齐（contractValidate/Diff 用 draftJson、workerTaskRetry 补 featureId、动态发现 fail-closed）；server.close() 先 chatRuntime.disposeAll()；resource-loader/system prompt 统一到 widening（hasBash:true）
+- CI 治理：7 个 versionConsumer 文档版本漂移 0.22.0→0.23.0；check-task-pool-root.sh allowlist 增补 codify-constraints.md
+
+
 ## [0.22.0] - 2026-07-24
 
 ### 重点更新

package/README.md

@@ -127,8 +127,11 @@ agent-worker console doctor --repo .
 
 - [`AGENTS.md`](AGENTS.md)：开工协议与工作规则
 - [`docs/README.md`](docs/README.md)：治理文档总索引
-- [`docs/feature-workflow.md`](docs/feature-workflow.md)：会话治理与 runtime workflow
-- [`docs/verification-matrix.md`](docs/verification-matrix.md)：验证命令选择
+- [`docs/governance/`](docs/governance/README.md)：工程原则、工作流与验证方法
+- [`docs/runtime/`](docs/runtime/README.md)：DAG 运行、恢复与 runtime 手册
+- [`docs/operations/`](docs/operations/README.md)：本地环境、合并与协作操作
+- [`docs/governance/feature-workflow.md`](docs/governance/feature-workflow.md)：会话治理与 runtime workflow
+- [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)：验证命令选择
 - [`docs/architecture/`](docs/architecture/README.md)：架构、事实与演进边界
 - [`CHANGELOG.md`](CHANGELOG.md)：版本变化与 breaking changes
 
@@ -146,7 +149,7 @@ bash scripts/check-repo.sh
 
 完整门禁和特定环境排障分别见：
 
-- [`docs/verification-matrix.md`](docs/verification-matrix.md)
-- [`docs/local-development-environment.md`](docs/local-development-environment.md)
+- [`docs/governance/verification-matrix.md`](docs/governance/verification-matrix.md)
+- [`docs/operations/local-development-environment.md`](docs/operations/local-development-environment.md)
 
 发布和初始化 surface 变更还应运行 `npm pack --dry-run` 与 `bash scripts/check-init-surface.sh`。

package/dist/application/context-usage/skill-resolution-stats.js

@@ -0,0 +1,263 @@
+/**
+ * Read-only skill-resolution / context-usage aggregation over recent DAG runs.
+ *
+ * Terminology: this reports resolution / truncation / unresolved-reference
+ * distribution and correlated node outcomes. It does NOT claim skill "execution"
+ * or model compliance rates — snapshots prove parse+inject only.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isDagSkillSnapshotIntegrityError, readSkillSnapshot, } from "../../workflows/dag/skill-snapshot.js";
+const LIFECYCLES = ["active", "paused", "completed"];
+function emptySkillCounts() {
+    return {
+        declared: 0,
+        resolved: 0,
+        missing: 0,
+        error: 0,
+        entryTruncated: 0,
+        referenceTruncated: 0,
+        unresolvedByReason: {},
+    };
+}
+function emptyNodeOutcomes() {
+    return {
+        FINISHED: 0,
+        ERROR: 0,
+        SKIPPED: 0,
+        PENDING: 0,
+        RUNNING: 0,
+        other: 0,
+        failureCategories: {},
+    };
+}
+function bumpReason(map, reason) {
+    map[reason] = (map[reason] ?? 0) + 1;
+}
+function ensureSkill(skills, name) {
+    if (!skills[name])
+        skills[name] = emptySkillCounts();
+    return skills[name];
+}
+export function parseStatsContextArgs(args) {
+    let last = 50;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--json" || token === "--json=true") {
+            json = true;
+            continue;
+        }
+        if (token.startsWith("--json=")) {
+            json = token.slice("--json=".length) === "true";
+            continue;
+        }
+        if (token === "--last") {
+            const raw = args[i + 1];
+            if (!raw || raw.startsWith("-")) {
+                throw new Error("usage: stats context [--last <n>] [--json]");
+            }
+            const parsed = Number.parseInt(raw, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                throw new Error(`--last must be a positive integer, got: ${raw}`);
+            }
+            last = parsed;
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--last=")) {
+            const raw = token.slice("--last=".length);
+            const parsed = Number.parseInt(raw, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                throw new Error(`--last must be a positive integer, got: ${raw}`);
+            }
+            last = parsed;
+            continue;
+        }
+        throw new Error(`unknown argument: ${token}\nusage: stats context [--last <n>] [--json]`);
+    }
+    return { last, json };
+}
+async function listRecentDagRuns(repoRoot, last) {
+    const matches = [];
+    for (const lifecycle of LIFECYCLES) {
+        const lifecycleDir = path.join(repoRoot, ".harness", "dag-runs", lifecycle);
+        let entries = [];
+        try {
+            entries = await readdir(lifecycleDir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!name || name === ".gitkeep")
+                continue;
+            const runDir = path.join(lifecycleDir, name);
+            let st;
+            try {
+                st = await stat(runDir);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isDirectory())
+                continue;
+            matches.push({
+                runId: name,
+                lifecycle,
+                runDir,
+                mtimeMs: st.mtimeMs,
+            });
+        }
+    }
+    matches.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return matches.slice(0, last);
+}
+async function readOptionalJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function ingestSnapshot(skills, snapshot) {
+    for (const profile of snapshot.profiles) {
+        for (const skillName of profile.skills) {
+            ensureSkill(skills, skillName).declared += 1;
+        }
+        for (const instruction of profile.resolvedInstructions) {
+            const row = ensureSkill(skills, instruction.name);
+            if (instruction.resolution === "resolved")
+                row.resolved += 1;
+            else if (instruction.resolution === "missing")
+                row.missing += 1;
+            else if (instruction.resolution === "error")
+                row.error += 1;
+            if (instruction.truncated)
+                row.entryTruncated += 1;
+            for (const ref of instruction.references ?? []) {
+                if (ref.truncated)
+                    row.referenceTruncated += 1;
+            }
+            for (const unresolved of instruction.unresolvedReferences ?? []) {
+                bumpReason(row.unresolvedByReason, unresolved.reason);
+            }
+        }
+    }
+}
+function ingestNodeOutcomes(outcomes, state) {
+    for (const node of Object.values(state.nodes ?? {})) {
+        const status = node.status;
+        if (status === "FINISHED")
+            outcomes.FINISHED += 1;
+        else if (status === "ERROR")
+            outcomes.ERROR += 1;
+        else if (status === "SKIPPED")
+            outcomes.SKIPPED += 1;
+        else if (status === "PENDING")
+            outcomes.PENDING += 1;
+        else if (status === "RUNNING")
+            outcomes.RUNNING += 1;
+        else
+            outcomes.other += 1;
+        if (node.failureCategory) {
+            bumpReason(outcomes.failureCategories, node.failureCategory);
+        }
+    }
+}
+/**
+ * Pure-ish builder: filesystem reads only; never writes `.harness/**`.
+ */
+export async function buildContextUsageReport(repoRoot, options = {}) {
+    const last = options.last ?? 50;
+    const candidates = await listRecentDagRuns(repoRoot, last);
+    const skills = {};
+    const nodeOutcomes = emptyNodeOutcomes();
+    const byLifecycle = {
+        active: 0,
+        paused: 0,
+        completed: 0,
+    };
+    const findings = [];
+    const notes = [
+        "skill-resolution telemetry only; does not claim model compliance or skill execution rates",
+        "corrupted snapshots are reported as findings and are not silently skipped",
+    ];
+    for (const candidate of candidates) {
+        byLifecycle[candidate.lifecycle] += 1;
+        const state = await readOptionalJson(path.join(candidate.runDir, "state.json"));
+        const runJson = await readOptionalJson(path.join(candidate.runDir, "run.json"));
+        const finding = {
+            runId: candidate.runId,
+            lifecycle: candidate.lifecycle,
+            mtimeMs: candidate.mtimeMs,
+            runStatus: state?.status,
+            contextPolicyId: runJson?.defaults?.contextPolicyId,
+            snapshot: "missing",
+        };
+        if (state)
+            ingestNodeOutcomes(nodeOutcomes, state);
+        const ref = state?.skillSnapshotRef;
+        if (!ref) {
+            findings.push(finding);
+            continue;
+        }
+        try {
+            const snapshot = await readSkillSnapshot(candidate.runDir, ref);
+            finding.snapshot = "ok";
+            ingestSnapshot(skills, snapshot);
+        }
+        catch (error) {
+            finding.snapshot = "corrupted";
+            finding.snapshotError = isDagSkillSnapshotIntegrityError(error)
+                ? error.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+        }
+        findings.push(finding);
+    }
+    const corrupted = findings.filter((f) => f.snapshot === "corrupted").length;
+    return {
+        schemaVersion: 1,
+        command: "stats.context",
+        ok: corrupted === 0,
+        scannedRuns: candidates.length,
+        requestedLast: last,
+        byLifecycle,
+        skills,
+        nodeOutcomes,
+        findings,
+        notes,
+    };
+}
+export function formatContextUsageReportHuman(report) {
+    const lines = [];
+    lines.push(`stats context (last ${report.requestedLast}, scanned ${report.scannedRuns})`);
+    lines.push(`lifecycle: active=${report.byLifecycle.active} paused=${report.byLifecycle.paused} completed=${report.byLifecycle.completed}`);
+    lines.push(`nodes: FINISHED=${report.nodeOutcomes.FINISHED} ERROR=${report.nodeOutcomes.ERROR} SKIPPED=${report.nodeOutcomes.SKIPPED} PENDING=${report.nodeOutcomes.PENDING} RUNNING=${report.nodeOutcomes.RUNNING}`);
+    const skillNames = Object.keys(report.skills).sort();
+    if (skillNames.length === 0) {
+        lines.push("skills: (none resolved in scanned snapshots)");
+    }
+    else {
+        lines.push("skills:");
+        for (const name of skillNames) {
+            const s = report.skills[name];
+            const budget = s.unresolvedByReason.budget ?? 0;
+            lines.push(`  ${name}: declared=${s.declared} resolved=${s.resolved} missing=${s.missing} error=${s.error} entryTrunc=${s.entryTruncated} refTrunc=${s.referenceTruncated} budgetSkip=${budget}`);
+        }
+    }
+    const corrupted = report.findings.filter((f) => f.snapshot === "corrupted");
+    if (corrupted.length > 0) {
+        lines.push(`corrupted snapshots: ${corrupted.length}`);
+        for (const finding of corrupted.slice(0, 5)) {
+            lines.push(`  ${finding.lifecycle}/${finding.runId}: ${finding.snapshotError ?? "unknown"}`);
+        }
+    }
+    for (const note of report.notes) {
+        lines.push(`note: ${note}`);
+    }
+    return lines.join("\n");
+}

package/dist/application/dag/generate-task-dag.js

@@ -68,6 +68,15 @@ function buildNextSteps(taskId, outputPath, cwd) {
         `loop-agent dag run-task ${taskId} --execute --cwd ${cwd}`,
     ];
 }
+function buildBasicValidationLevel(outputPath) {
+    return {
+        level: "basic",
+        strictGovernance: false,
+        strictGovernanceValidationRequiredSeparately: true,
+        standaloneStrictGovernanceCommand: `loop-agent dag validate --dag ${outputPath} --strict-models --strict-governance`,
+        note: "Internal generation validation is basic only; standalone strict governance validation must be confirmed separately.",
+    };
+}
 function isBroadWriteSetEntryForPacket(entry) {
     const normalized = entry.trim().replace(/\\/g, "/").replace(/^\.\//, "");
     if (!normalized || normalized === "." || normalized === "./")
@@ -168,6 +177,7 @@ async function buildReviewPacket(input) {
                 ? (task.decisionGate.mode ?? "record-only")
                 : "disabled",
         })),
+        validation: buildBasicValidationLevel(input.dagPath),
         expectedVerification: shellVerification.flatMap((entry) => entry.commands),
     };
 }
@@ -281,10 +291,12 @@ export async function generateTaskDagUseCase(input) {
         profileRouting,
         governanceProfile,
     });
+    const validation = buildBasicValidationLevel(outputPath);
+    const message = "DAG draft created with basic validation; standalone strict governance validation still requires separate confirmation.";
     if (!shouldRunExecution(parsed)) {
         return {
-            mode: "generate+validate",
-            message: "DAG draft created",
+            mode: "generate+basic-validate",
+            message,
             ok: true,
             taskId: initResult.taskId,
             outputPath,
@@ -296,6 +308,7 @@ export async function generateTaskDagUseCase(input) {
             governanceProfile,
             profileRouting,
             reviewPacket,
+            validation,
             warnings: validateSummary.warnings,
             next: buildNextSteps(parsed.taskId, outputPath, parsed.cwd),
         };
@@ -327,7 +340,7 @@ export async function generateTaskDagUseCase(input) {
     });
     return {
         mode: resolveExecutionMode(parsed),
-        message: "DAG draft created",
+        message,
         ok: true,
         taskId: initResult.taskId,
         outputPath,
@@ -338,6 +351,7 @@ export async function generateTaskDagUseCase(input) {
         governanceProfile,
         profileRouting,
         reviewPacket,
+        validation,
         warnings: validateSummary.warnings,
         run: runSummary,
     };