@tea-agent/loop-agent 0.21.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,103 @@
 
 ## [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
+
+### 重点更新
+
+- 前端规范读取范围扩展，新增 ai_workspace 作为并列来源，并独立展示各类规范证据
+- 前端实现 DAG 引入 lint 债务基线机制，精准区分存量与新增代码问题，减少误阻断
+- 前端预写门禁增强，强制校验真实的规范读取事件，避免遗漏关键上下文
+- 后端测试报告结构优化，新增 Markdown 报告并改进 HTML 报告的分层展示
+
+### 新增
+
+- 前端规范读取将 ai_workspace 目录与 openspec 相关目录作为并列来源，即使缺少 package.json 也能发现本地规范候选
+- Dashboard 规范证据 API 与界面独立展示知识库查询、openspec 检索和成功读取三类证据
+- 后端测试在同目录下新增生成 backend-test.md 报告，便于查阅测试结论与明细
+
+### 改进
+
+- 前端实现 DAG 允许未修改文件中的已知 lint 诊断作为基线债务继续，但对修改文件的新问题严格阻断
+- 后端测试 HTML 报告采用更清晰的分层展示，新增稳定结论图标与可折叠的质量校验明细，移除了原稳定性指标
+- 前端测试用例的内容完整性与证据检查降级为建议性反馈，不再因个别物料缺失阻断最终复盘
+- 设计文档与研发 DAG 拓扑说明同步更新，澄清了 profile/workflow/type 三套正交概念与当前实现状态
+
+### 修复
+
+- 修复前端技能指令可能超出预算限制的问题
+- 修复 DAG 未正确注册 DeepSeek Pi 模型提供者的问题
+- 修复前端目标项目验证路由不够健壮的问题
+- 修复后端测试中无法跨环境便携解析 Python 运行时的问题
+
 ## [0.21.0] - 2026-07-24
 
 ### 重点更新
@@ -18,6 +115,9 @@
 
 - backend-test 第 7 节点现在只执行最终 Markdown `自动化映射` 明确声明且安全校验通过的 pytest 脚本，避免历史或无关 `test_*.py` 混入本轮 JUnit/HTML；空映射、缺失脚本或越界路径会 fail-closed。
 - backend-test HTML 报告升级为更清晰的用例卡片：保留测试结论、质量状态和失败概览，直接展示简洁测试场景、自动化用例名称、结果与耗时，并为通过/失败用例都展示同次执行中脱敏且有界的接口请求参数与响应结果；HTML 不再附带技术证据章节，审计路径与哈希继续保留在 facts/JUnit。
+- frontend-test 第四节点不再扫描或阻断 pytest、原生 Playwright、`npx playwright`、`@playwright/test` 或 Node Playwright API 等可执行工具指令；该节点只保留 manifest、Case/AC/path、非生产 URL 和标准 `playwright-cli open` 前缀等结构与安全门禁，并强烈建议浏览器执行优先使用 `playwright-cli`。
+- frontend-test 用例内容、Case ID、AC 关联与 evidence 完整性检查改为 advisory：缺失或损坏的执行物料不再被自动改写为 blocked，也不阻断最终复盘；finding 汇入结构化结果，并在 Markdown retrospective 后生成中文 HTML 建议报告。路径越界、跨用例 evidence 引用、writeSet、生产环境与凭据安全仍保持硬门禁。
+- frontend-test checklist JavaScript 通过 Base64 参数交给 Node 解码执行，并修正变量声明顺序与重复语句，避免 Git Bash 将 `\s` / `\d`、反引号或引号破坏后再交给 Node。
 - 新初始化项目的 harness 指南同步 adaptive liveness、4h absolute max、stall 状态与 `termination-unconfirmed` 处置；旧项目可由 `init check-update` 识别未修改的受管指南，并通过 `init update --apply-safe` 安全刷新。
 
 ## [0.20.1] - 2026-07-24
@@ -63,6 +163,19 @@
 
 ### 新增
 
+- 继续收紧前端实现证据门禁：禁止空 verification contract，校验验证目标与 requirement/UI state/授权路径绑定；新版 review context 缺失 writer baseline 时直接阻断，非 `not-needed` Mock 策略必须提供 endpoint 与 consumer 证据。
+- 前端写入前重新校验 DAG 绑定源文件的 SHA-256；Mock endpoint 现在必须声明 fixture 与 consumer，且验证 trace 必须记录成功的 Mock 命令。
+- 前端验证 bundle 现在冻结实际命令文本，并将实现契约 targets 限制在 writer writeSet 内，避免验证证据与可写范围漂移。
+- 同步前端 prewrite/review context 的 DAG JSON Schema，避免生成 DAG 因 freshness、writeSet 或 baseline 字段漂移而被错误拒绝。
+- 前端 prewrite 现在强制校验需求源新鲜度，验证 Schema 也要求声明实际命令文本，减少旧 DAG 和证据配置的隐式降级。
+- 前端实现 DAG 的验证命令与侦察范围改为从目标项目自身的 package scripts、包管理器和允许路径推导，不再假设目标项目沿用 loop-agent 的目录与命令布局。
+
+### 改进
+
+- 前端实现 DAG 的验证命令与侦察范围改为从目标项目自身的 package scripts、包管理器和允许路径推导，不再假设目标项目沿用 loop-agent 的目录与命令布局。
+- 后端测试用例默认生成中文 README 索引与模块用例卡片，步骤、预期、需求依据和自动化映射更便于测试、研发与评审人员阅读。
+- 后端测试 HTML 主报告现在逐条展示用例编号、中文名称与场景、脚本、测试函数、结果、耗时和失败原因，完整技术详情可折叠查看。
+
 - streamline implementation DAG (#61)
 - improve human-readable artifacts
 
@@ -86,6 +199,7 @@
 ### 改进
 
 - `frontend-implementation` 保留独立 contract/scout，并把 Mock 策略与 implementation contract 合入 plan，把写前授权、验证/失败评估、复验和 review context 分别收敛为组合 shell 节点。standard/high-risk 固定 15 个顶层节点、small-risk 13 个；绿色路径执行 11 个节点、7 次 Pi，同时保留唯一 prewrite 写入授权、同 writeSet repair、真实 diff review 与 fail-closed closeout。
+- 加强前端实现节点的证据链：Trace 只绑定本次实际成功执行的验证命令，契约兼容转换不再补入占位文件或默认验证目标，Prewrite 要求上游节点明确完成，review context 校验 artifact 绑定，并以 writer 前工作区快照隔离既有用户改动。
 - 优化操作与观测统一界面的导航与布局，合并确认与运行为「开始运行」，DAG 详情跳转路径更加准确
 
 ### 修复

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/adapters/loop-agent.js

@@ -63,6 +63,11 @@ function getVerifyCommands(repoRoot, options) {
     if (manifestCommands) {
         return applyQuota(manifestCommands, options);
     }
+    if (options.taskConfig?.taskKind === 'frontend-implementation') {
+        const frontendCommands = getFrontendProjectVerifyCommands(repoRoot, options);
+        if (frontendCommands)
+            return frontendCommands;
+    }
     const quickCommands = [
         {
             args: ['bash', 'scripts/check-repo.sh'],
@@ -91,6 +96,53 @@ function getVerifyCommands(repoRoot, options) {
             : [...quickCommands, ...standardCommands, ...fullCommands];
     return applyQuota(selectedCommands, options);
 }
+function getFrontendProjectVerifyCommands(repoRoot, options) {
+    let scripts;
+    try {
+        const packageJson = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+        if (!packageJson.scripts || typeof packageJson.scripts !== 'object')
+            return undefined;
+        scripts = packageJson.scripts;
+    }
+    catch {
+        return undefined;
+    }
+    let packageManager = 'npm';
+    for (const [lockfile, manager] of [
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['bun.lockb', 'bun'],
+        ['bun.lock', 'bun'],
+    ]) {
+        try {
+            readFileSync(path.join(repoRoot, lockfile));
+            packageManager = manager;
+            break;
+        }
+        catch {
+            // Try the next package-manager marker.
+        }
+    }
+    const hasScript = (name) => typeof scripts[name] === 'string' && String(scripts[name]).trim().length > 0;
+    const commandFor = (name) => ({
+        args: name === 'test'
+            ? [packageManager, 'test']
+            : [packageManager, 'run', name],
+        cwd: repoRoot,
+        label: `${packageManager} ${name === 'test' ? 'test' : `run ${name}`}`,
+    });
+    const collect = (names) => names.filter(hasScript).map(commandFor);
+    const staticCommands = collect(['typecheck', 'check-types', 'lint', 'check', 'build']);
+    const behaviorCommands = collect(['test:unit', 'test:frontend', 'test:component', 'test', 'test:e2e', 'e2e']);
+    if (staticCommands.length === 0 && behaviorCommands.length === 0)
+        return undefined;
+    const selected = options.phase === 'final'
+        ? [...staticCommands, ...behaviorCommands]
+        : staticCommands;
+    if (selected.length === 0)
+        return behaviorCommands;
+    return applyQuota(selected, options);
+}
 function applyQuota(commands, options) {
     if (options.phase === 'final' || !options.quota || options.quota === 'full') {
         return commands;