@tea-agent/loop-agent 0.25.6 → 0.26.0

package/skills/browser-tools/package.json

@@ -1,19 +1,19 @@
-{
-	"name": "browser-tools",
-	"version": "1.0.0",
-	"type": "module",
-	"description": "Minimal CDP tools for collaborative site exploration",
-	"author": "Mario Zechner",
-	"license": "MIT",
-	"dependencies": {
-		"@mozilla/readability": "^0.6.0",
-		"cheerio": "^1.1.2",
-		"jsdom": "^27.0.1",
-		"puppeteer": "^24.31.0",
-		"puppeteer-core": "^23.11.1",
-		"puppeteer-extra": "^3.3.6",
-		"puppeteer-extra-plugin-stealth": "^2.11.2",
-		"turndown": "^7.2.2",
-		"turndown-plugin-gfm": "^1.0.2"
-	}
-}
+{
+	"name": "browser-tools",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "Minimal CDP tools for collaborative site exploration",
+	"author": "Mario Zechner",
+	"license": "MIT",
+	"dependencies": {
+		"@mozilla/readability": "^0.6.0",
+		"cheerio": "^1.1.2",
+		"jsdom": "^27.0.1",
+		"puppeteer": "^24.31.0",
+		"puppeteer-core": "^23.11.1",
+		"puppeteer-extra": "^3.3.6",
+		"puppeteer-extra-plugin-stealth": "^2.11.2",
+		"turndown": "^7.2.2",
+		"turndown-plugin-gfm": "^1.0.2"
+	}
+}

package/skills/code-review-core/SKILL.md

@@ -1,20 +1,20 @@
----
-name: code-review-core
-description: 用于只读 code review 节点，产出带文件与行号引用的优先级 findings。
----
-
-# Code Review Core
-
-本 skill 用于 reviewer 节点。
-
-## Review 重点
-
-- 优先关注 correctness、行为回归、security、数据丢失与缺失验证。
-- findings 须 grounded 在具体文件与行号。
-- 区分 blocking findings 与次要 maintainability 备注。
-- 检查测试是否证明变更行为，文档是否与面向用户的变更一致。
-- 若无 findings，明确说明，并指出 residual test gap（如有）。
-
-## Output
-
-按 severity 排序列出 findings。仅当无 blocking findings 时，才写 `VERDICT: pass`。
+---
+name: code-review-core
+description: 用于只读 code review 节点，产出带文件与行号引用的优先级 findings。
+---
+
+# Code Review Core
+
+本 skill 用于 reviewer 节点。
+
+## Review 重点
+
+- 优先关注 correctness、行为回归、security、数据丢失与缺失验证。
+- findings 须 grounded 在具体文件与行号。
+- 区分 blocking findings 与次要 maintainability 备注。
+- 检查测试是否证明变更行为，文档是否与面向用户的变更一致。
+- 若无 findings，明确说明，并指出 residual test gap（如有）。
+
+## Output
+
+按 severity 排序列出 findings。仅当无 blocking findings 时，才写 `VERDICT: pass`。

package/skills/codebase-scout/SKILL.md

@@ -1,19 +1,19 @@
----
-name: codebase-scout
-description: 用于只读 scout 节点，在实现前定位现有代码、测试、文档与集成点。
----
-
-# Codebase Scout
-
-本 skill 用于 scout 节点。
-
-## 规则
-
-- 从 repo 指令、task source 与邻近测试入手。
-- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
-- 在提议新抽象前，识别现有 helper 与 ownership 边界。
-- 只返回事实，不做编辑。
-
-## Output
-
-列出相关文件、现有模式、风险，以及实现所需的最小 write surface。
+---
+name: codebase-scout
+description: 用于只读 scout 节点，在实现前定位现有代码、测试、文档与集成点。
+---
+
+# Codebase Scout
+
+本 skill 用于 scout 节点。
+
+## 规则
+
+- 从 repo 指令、task source 与邻近测试入手。
+- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
+- 在提议新抽象前，识别现有 helper 与 ownership 边界。
+- 只返回事实，不做编辑。
+
+## Output
+
+列出相关文件、现有模式、风险，以及实现所需的最小 write surface。

package/skills/grill-me/SKILL.md

@@ -1,10 +1,10 @@
----
-name: grill-me
-description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
----
-
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
-
-Ask the questions one at a time.
-
-If a question can be answered by exploring the codebase, explore the codebase instead.
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/skills/loop-agent/references/README.md

@@ -1,67 +1,67 @@
-# loop-agent Skill References
-
-本目录是 `../SKILL.md` 的 progressive-disclosure reference layer。`SKILL.md`
-只负责 trigger、入口选择和硬规则；较长的 command details、operational procedures、
-failure handling 与 workflow 细节放在这里，避免主 skill 变成百科。
-
-## 使用方式
-
-1. 先读 `../SKILL.md`，确认当前任务是否真的需要 `loop-agent`。
-2. 根据任务类型只打开相关 reference，不要一次加载整个目录。
-3. 执行时遵循 Agent DAG 路径；历史顺序式 `run ...` workflow 已移除。
-4. 如果 reference 与 `harness.json` 或 repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
-   `harness.json` 的机器可读 policy 和本目录的 shared policy 为准，并回头修正文档漂移。
-
-## 快速路由
-
-| 场景 | 优先读取 |
-|---|---|
-| 通用 loop-agent harness workflow policy、跨 repo 共同规则 | `harness-policy.md` |
-| 中大型 autonomous implementation、harness-governed work | `harness-policy.md`、`hybrid-dag.md`、`orchestrator-and-interventions.md`、`verification-and-failure-handling.md` |
-| 需要查精确 CLI 用法、setup、goal、docs helper、stats | `command-reference.md` |
-| 低风险 micro task、旧任务目录兼容、DAG runtime 修复 | `task-workflow.md`、`verification-and-failure-handling.md` |
-| DAG 运行中要判断 main session 是否能手术式补丁、是否需要 sidecar prompt | `orchestrator-and-interventions.md` |
-| 短时 one-shot Pi SDK 调用，不创建 `.harness/tasks/` | `pi-prompt.md` |
-| 解释 `.harness/runs/`、one-shot evidence、active 残留或 promotion | `one-shot-runs.md` |
-| 多 worktree 并行委派、delegate/harvest | `multi-worktree.md` |
-| 模型、provider、profile、fallback routing | `model-routing.md` |
-| Long-running `loop` 命令、action 规则、auto mode、signals、loop closeout | `long-running-loop.md` |
-| Three-pass convergence、repair artifact / spine audit / knowledge curate、SePO-lite prompt evolution | `harness-policy.md` |
-| Cursor bounded write 后的独立复核、verify knobs、failure handling | `verification-and-failure-handling.md` |
-
-## Reference 索引
-
-| Reference | 使用场景 |
-|---|---|
-| `harness-policy.md` | 通用 loop-agent harness policy：DAG、命令分层、source materials、loop/sidecar 边界、facts/verification/handoff 规则；repo-local harness docs 应引用它而不是复制规则 |
-| `orchestrator-and-interventions.md` | 协调长时间 autonomous DAG work；判断 main session 是否可以 edit；使用 one-shot Pi/Cursor sidecar；恢复 in-flight workflow |
-| `command-reference.md` | 需要 `.` 的精确 CLI 命令、setup、goal lifecycle、docs helper、stats |
-| `task-workflow.md` | 处理 task source material、task config、repo adapter 或 legacy task 目录布局 |
-| `pi-prompt.md` | 运行短时 one-shot Pi SDK task，且不创建 `.harness/tasks/` |
-| `one-shot-runs.md` | 解释 `.harness/runs/{active,completed,failed}` 的创建条件、生命周期、治理清理与 `promote-run` 关系 |
-| `hybrid-dag.md` | 使用 Agent DAG Level 2 `dag validate` / `run-dag`，Level 3 `dag init-hybrid` / `dag run-task`，或查看 write policy、DAG source-of-truth 规则 |
-| `pi-subagent-assisted-mode.md` | 启用 `piSubagentMode`，或在 Pi step 内配置 read-only scout / planner / reviewer subagent |
-| `model-routing.md` | 查看或修改 model/provider 默认、profile、routing 或 fallback 行为 |
-| `post-implementation-and-patterns.md` | 处理 post-verify handoff、PRD item 拆分、fast bounded task、quick status 或 Pi timeout |
-| `multi-worktree.md` | 用 isolated worktree、`delegate` 与 `harvest` 并发执行互不重叠的 independent task |
-| `verification-and-failure-handling.md` | 选择 verify knob、Cursor bounded write 后的独立复核、解释 failure mode、执行 completion audit 与 closeout |
-| `long-running-loop.md` | 使用 experimental long-running `loop` outer state：命令入口、action 规则、auto mode 写入边界、signals 与 loop closeout |
-
-## 边界与状态源
-
-- `references/harness-policy.md` 是 shared workflow policy source，供多个 repo 的 thin adapter docs 引用。
-- `../SKILL.md` 是 skill trigger 与 routing source，不承载长流程细节。
-- `ai_workspace/loop-agent/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
-- `harness.json` 是 workflowPolicy、script entrypoints、artifacts 目录与 model routing 的机器可读 source of truth。
-- `.harness/tasks/<task-id>/` 是 task 运行态状态；不要把运行态事实写进本目录。
-- `.harness/runs/completed/<run-id>/` 是 one-shot tool run evidence；reference 文档只能解释如何读取和 promotion，不应复制 run facts。
-- `.harness/dag-runs/completed/<run-id>/` 是单次 DAG run 的不可变 facts；reference 文档只能解释如何读取和收口，不应复制 run facts。
-
-## 维护规则
-
-- 不要把长段落复制回 `SKILL.md`；需要新增细节时，在本目录新增或更新 reference，并在 `SKILL.md` 添加 routing row。
-- 让 `SKILL.md` 保持 120-180 行以内；reference 文件承担细节。
-- 新 reference 应有清晰标题、触发场景、最小步骤、失败处理和维护边界。
-- 如果某个 reference 变成可独立触发、跨项目通用且不再依赖本仓库上下文，再考虑拆成独立 skill。
-- 更新 command、workflow policy 或 verification 规则时，同步核对 `harness.json`、`references/harness-policy.md`、repo-local harness adapter docs 和 verification matrix。
-- `~/.pi/agent/.agents/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。
+# loop-agent Skill References
+
+本目录是 `../SKILL.md` 的 progressive-disclosure reference layer。`SKILL.md`
+只负责 trigger、入口选择和硬规则；较长的 command details、operational procedures、
+failure handling 与 workflow 细节放在这里，避免主 skill 变成百科。
+
+## 使用方式
+
+1. 先读 `../SKILL.md`，确认当前任务是否真的需要 `loop-agent`。
+2. 根据任务类型只打开相关 reference，不要一次加载整个目录。
+3. 执行时遵循 Agent DAG 路径；历史顺序式 `run ...` workflow 已移除。
+4. 如果 reference 与 `harness.json` 或 repo-local `ai_workspace/loop-agent/loop-agent-harness.md` / `specs/loop-agent-harness.md` 冲突，以
+   `harness.json` 的机器可读 policy 和本目录的 shared policy 为准，并回头修正文档漂移。
+
+## 快速路由
+
+| 场景 | 优先读取 |
+|---|---|
+| 通用 loop-agent harness workflow policy、跨 repo 共同规则 | `harness-policy.md` |
+| 中大型 autonomous implementation、harness-governed work | `harness-policy.md`、`hybrid-dag.md`、`orchestrator-and-interventions.md`、`verification-and-failure-handling.md` |
+| 需要查精确 CLI 用法、setup、goal、docs helper、stats | `command-reference.md` |
+| 低风险 micro task、旧任务目录兼容、DAG runtime 修复 | `task-workflow.md`、`verification-and-failure-handling.md` |
+| DAG 运行中要判断 main session 是否能手术式补丁、是否需要 sidecar prompt | `orchestrator-and-interventions.md` |
+| 短时 one-shot Pi SDK 调用，不创建 `.harness/tasks/` | `pi-prompt.md` |
+| 解释 `.harness/runs/`、one-shot evidence、active 残留或 promotion | `one-shot-runs.md` |
+| 多 worktree 并行委派、delegate/harvest | `multi-worktree.md` |
+| 模型、provider、profile、fallback routing | `model-routing.md` |
+| Long-running `loop` 命令、action 规则、auto mode、signals、loop closeout | `long-running-loop.md` |
+| Three-pass convergence、repair artifact / spine audit / knowledge curate、SePO-lite prompt evolution | `harness-policy.md` |
+| Cursor bounded write 后的独立复核、verify knobs、failure handling | `verification-and-failure-handling.md` |
+
+## Reference 索引
+
+| Reference | 使用场景 |
+|---|---|
+| `harness-policy.md` | 通用 loop-agent harness policy：DAG、命令分层、source materials、loop/sidecar 边界、facts/verification/handoff 规则；repo-local harness docs 应引用它而不是复制规则 |
+| `orchestrator-and-interventions.md` | 协调长时间 autonomous DAG work；判断 main session 是否可以 edit；使用 one-shot Pi/Cursor sidecar；恢复 in-flight workflow |
+| `command-reference.md` | 需要 `.` 的精确 CLI 命令、setup、goal lifecycle、docs helper、stats |
+| `task-workflow.md` | 处理 task source material、task config、repo adapter 或 legacy task 目录布局 |
+| `pi-prompt.md` | 运行短时 one-shot Pi SDK task，且不创建 `.harness/tasks/` |
+| `one-shot-runs.md` | 解释 `.harness/runs/{active,completed,failed}` 的创建条件、生命周期、治理清理与 `promote-run` 关系 |
+| `hybrid-dag.md` | 使用 Agent DAG Level 2 `dag validate` / `run-dag`，Level 3 `dag init-hybrid` / `dag run-task`，或查看 write policy、DAG source-of-truth 规则 |
+| `pi-subagent-assisted-mode.md` | 启用 `piSubagentMode`，或在 Pi step 内配置 read-only scout / planner / reviewer subagent |
+| `model-routing.md` | 查看或修改 model/provider 默认、profile、routing 或 fallback 行为 |
+| `post-implementation-and-patterns.md` | 处理 post-verify handoff、PRD item 拆分、fast bounded task、quick status 或 Pi timeout |
+| `multi-worktree.md` | 用 isolated worktree、`delegate` 与 `harvest` 并发执行互不重叠的 independent task |
+| `verification-and-failure-handling.md` | 选择 verify knob、Cursor bounded write 后的独立复核、解释 failure mode、执行 completion audit 与 closeout |
+| `long-running-loop.md` | 使用 experimental long-running `loop` outer state：命令入口、action 规则、auto mode 写入边界、signals 与 loop closeout |
+
+## 边界与状态源
+
+- `references/harness-policy.md` 是 shared workflow policy source，供多个 repo 的 thin adapter docs 引用。
+- `../SKILL.md` 是 skill trigger 与 routing source，不承载长流程细节。
+- `ai_workspace/loop-agent/loop-agent-harness.md` / repo-local `specs/loop-agent-harness.md` 是本仓库或目标仓库的 adapter 文档：只描述 runtime 位置、governance root、验证入口和本地边界。
+- `harness.json` 是 workflowPolicy、script entrypoints、artifacts 目录与 model routing 的机器可读 source of truth。
+- `.harness/tasks/<task-id>/` 是 task 运行态状态；不要把运行态事实写进本目录。
+- `.harness/runs/completed/<run-id>/` 是 one-shot tool run evidence；reference 文档只能解释如何读取和 promotion，不应复制 run facts。
+- `.harness/dag-runs/completed/<run-id>/` 是单次 DAG run 的不可变 facts；reference 文档只能解释如何读取和收口，不应复制 run facts。
+
+## 维护规则
+
+- 不要把长段落复制回 `SKILL.md`；需要新增细节时，在本目录新增或更新 reference，并在 `SKILL.md` 添加 routing row。
+- 让 `SKILL.md` 保持 120-180 行以内；reference 文件承担细节。
+- 新 reference 应有清晰标题、触发场景、最小步骤、失败处理和维护边界。
+- 如果某个 reference 变成可独立触发、跨项目通用且不再依赖本仓库上下文，再考虑拆成独立 skill。
+- 更新 command、workflow policy 或 verification 规则时，同步核对 `harness.json`、`references/harness-policy.md`、repo-local harness adapter docs 和 verification matrix。
+- `~/.pi/agent/.agents/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。

package/skills/loop-agent/references/docs-converge.md

@@ -1,126 +1,126 @@
-# Docs Converge（文档收敛）
-
-本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
-定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
-
-权威规划：`ai_workspace/loop-agent/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
-站与治理双树边界：`website/README.md`。
-
-## 何时触发
-
-在以下任一情况**加载本文件并跑检查表**：
-
-- 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
-- 新增 / 修改 / 删除 CLI 命令或关键 flags。
-- runtime / 架构边界变更（`ai_workspace/loop-agent/architecture/*`、executor 角色、Worker 边界）。
-- active plan 创建、blocked、完成或归档。
-- 准备发布或写 `CHANGELOG.md` 版本条目。
-- 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
-- handoff 前需要声明「本轮是否更新了站上文档」。
-
-**不要**在无关的纯内部重构（无用户可见行为、无命令面变化）上强制大改站上正文；此时 handoff 写明豁免理由即可。
-
-## 受众矩阵
-
-| 受众 | 主要入口 | 权威细节 |
-| --- | --- | --- |
-| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `ai_workspace/loop-agent/architecture/*`、active plans |
-| 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
-| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `ai_workspace/loop-agent/`、`.agents/skills/`、`scripts/check-*.sh` |
-
-## 页面清单（站上活文档）
-
-| 页面 | 职责 |
-| --- | --- |
-| `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
-| `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
-| `website/docs/overview/architecture.md` | 架构导读；链到 `ai_workspace/loop-agent/architecture/` |
-| `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
-| `website/docs/quick-start/*` | 安装 / init / first-run |
-| `website/docs/guides/*` | 主路径操作说明 |
-| `website/docs/reference/cli.md` | 用户向 CLI 参考 |
-| `website/docs/reference/config.md` | 配置参考 |
-| `website/docs/changelog.md` | 读者摘要；完整版本以根 `CHANGELOG.md` 为准 |
-
-治理全文、exec-plans、reports **不**搬进 Docusaurus。
-
-## 变更 → 文档检查表
-
-按本轮实际 diff 勾选（有则必须处理，无则跳过并记豁免）：
-
-| 若变更了… | 必须检查 / 更新 |
-| --- | --- |
-| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `.agents/skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
-| 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
-| runtime / 边界 | 根 `ai_workspace/loop-agent/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
-| 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
-| active plan 状态 | `overview/roadmap.md` 短索引 + `ai_workspace/loop-agent/exec-plans/active/README.md` |
-| 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
-| skill / init 投影 | `ai_workspace/loop-agent/init-surface.manifest.json`、相关测试、必要时 `ai_workspace/loop-agent/.agents/skills/*` |
-
-跨树链接规则：
-
-- 站内页面用 Docusaurus 相对文档链接。
-- 链到根目录 `ai_workspace/loop-agent/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
-  `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
-  正文同时写出 repo-relative path；禁止伪造站内 `/ai_workspace/loop-agent/architecture/...` 作为根目录文档路由。
-
-## 执行步骤（最小闭环）
-
-1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
-2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
-3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `ai_workspace/loop-agent/`。
-4. **验证**（见下节）。
-5. **Handoff** 二选一：
-   - 已更新：列出改动页面与验证命令结果。
-   - 无需站上更新：写明「本轮无需站上更新，原因：…」。
-
-## 验证命令
-
-站上正文、侧栏或 `docusaurus.config.ts` 有改动时：
-
-```bash
-npm run docs:build
-```
-
-涉及治理文档、脚本、skill、init surface 时再跑：
-
-```bash
-bash scripts/check-repo.sh
-# 或定向：
-bash scripts/check-skill-entry.sh
-bash scripts/check-command-registry-drift.sh
-bash scripts/check-init-surface.sh
-node bin/loop-agent.js docs audit --repo-root .
-```
-
-skill / package 投影相关：
-
-```bash
-npx vitest run test/init-command.test.ts test/package-surface.test.ts
-```
-
-## 禁止事项
-
-- 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
-- 把 `ai_workspace/loop-agent/design/`、exec-plans、reports 全文复制进 `website/docs/`。
-- 在站上建立第二套与 `ai_workspace/loop-agent/architecture/*` 冲突的架构真源。
-- 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
-- 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
-- 新增独立公共 skill 目录承载本检查表（应留在 `.agents/skills/loop-agent/references/`）。
-
-## 与现有能力的关系
-
-| 能力 | 关系 |
-| --- | --- |
-| `loop-agent docs audit` | L0 腐化检查（断链、计划状态等）；**不**替代本表内容审计 |
-| `npm run docs:build` | 站上改动硬门禁（含 Markdown 断链 fail-fast） |
-| `grill-with-docs` | ADR / 术语；不替代本 reference |
-| 历史 2026-07-05 docs governance dogfood | 仅经验输入；新 workflow 必须 Pi-only，不复用已退役原生 Cursor DAG |
-
-## 快速自检（handoff 前 30 秒）
-
-- [ ] 用户可见变更是否对照检查表处理或已豁免？
-- [ ] intro 是否仍是概念地图（而非能力 bullet 堆砌）？
-- [ ] roadmap 是否只含当前有效 active 项？
-- [ ] 需要时 `docs:build` / `check-repo` 是否有新鲜输出？
+# Docs Converge（文档收敛）
+
+本 reference 把会话协议中的 **Converge Docs** 落成可执行检查表。
+定位是**收敛 / 同步**，不是「每次重新 invent 文档大纲」。
+
+权威规划：`ai_workspace/loop-agent/exec-plans/completed/2026-07-14-website-docs-ia-and-converge.md`。
+站与治理双树边界：`website/README.md`。
+
+## 何时触发
+
+在以下任一情况**加载本文件并跑检查表**：
+
+- 用户可见行为变更（CLI 输出、默认工作流、init 投影、Observe/Worker 主路径）。
+- 新增 / 修改 / 删除 CLI 命令或关键 flags。
+- runtime / 架构边界变更（`ai_workspace/loop-agent/architecture/*`、executor 角色、Worker 边界）。
+- active plan 创建、blocked、完成或归档。
+- 准备发布或写 `CHANGELOG.md` 版本条目。
+- 用户明确要求「文档收敛」「docs converge」「同步 website docs」。
+- handoff 前需要声明「本轮是否更新了站上文档」。
+
+**不要**在无关的纯内部重构（无用户可见行为、无命令面变化）上强制大改站上正文；此时 handoff 写明豁免理由即可。
+
+## 受众矩阵
+
+| 受众 | 主要入口 | 权威细节 |
+| --- | --- | --- |
+| 新贡献者 | `website/docs/intro.md` → `overview/architecture` → `overview/roadmap` → first-run | 根 `ai_workspace/loop-agent/architecture/*`、active plans |
+| 使用者 | `overview/feature-map`、`quick-start/*`、`guides/*`、`reference/*` | CLI help、根 `CHANGELOG.md` |
+| 维护者 / agent | 本检查表 + `AGENTS.md` Converge Docs | `ai_workspace/loop-agent/`、`.agents/skills/`、`scripts/check-*.sh` |
+
+## 页面清单（站上活文档）
+
+| 页面 | 职责 |
+| --- | --- |
+| `website/docs/intro.md` | 概念地图 + 30 分钟路径；非能力堆砌 |
+| `website/docs/overview/feature-map.md` | 功能导览 → guide/CLI |
+| `website/docs/overview/architecture.md` | 架构导读；链到 `ai_workspace/loop-agent/architecture/` |
+| `website/docs/overview/roadmap.md` | 当前有效规划短索引 |
+| `website/docs/quick-start/*` | 安装 / init / first-run |
+| `website/docs/guides/*` | 主路径操作说明 |
+| `website/docs/reference/cli.md` | 用户向 CLI 参考 |
+| `website/docs/reference/config.md` | 配置参考 |
+| `website/docs/changelog.md` | 读者摘要；完整版本以根 `CHANGELOG.md` 为准 |
+
+治理全文、exec-plans、reports **不**搬进 Docusaurus。
+
+## 变更 → 文档检查表
+
+按本轮实际 diff 勾选（有则必须处理，无则跳过并记豁免）：
+
+| 若变更了… | 必须检查 / 更新 |
+| --- | --- |
+| 新/改 CLI 命令 | `website/docs/reference/cli.md` + `.agents/skills/loop-agent/references/command-reference.md`（及 agent-worker 相关 reference） |
+| 用户可见行为 | 对应 `guides/*` 或 `quick-start/*`；根 `CHANGELOG.md`；必要时 `overview/feature-map.md` / `intro.md` |
+| runtime / 边界 | 根 `ai_workspace/loop-agent/architecture/*`；站上 `overview/architecture.md` 导语与外链 |
+| 默认工作流 | `intro.md` 流程图 + `guides/agent-dag.md` / `guides/harness-policy.md` |
+| active plan 状态 | `overview/roadmap.md` 短索引 + `ai_workspace/loop-agent/exec-plans/active/README.md` |
+| 发布 | 根 `CHANGELOG.md` 为版本事实源；`website/docs/changelog.md` 只写摘要与链接；roadmap 仅在规划状态变化时更新 |
+| skill / init 投影 | `ai_workspace/loop-agent/init-surface.manifest.json`、相关测试、必要时 `ai_workspace/loop-agent/.agents/skills/*` |
+
+跨树链接规则：
+
+- 站内页面用 Docusaurus 相对文档链接。
+- 链到根目录 `ai_workspace/loop-agent/`、`AGENTS.md`、`CHANGELOG.md` 等时，使用
+  `https://github.com/tea-agent/loop-agent/blob/main/<repo-path>`，
+  正文同时写出 repo-relative path；禁止伪造站内 `/ai_workspace/loop-agent/architecture/...` 作为根目录文档路由。
+
+## 执行步骤（最小闭环）
+
+1. **列出本轮用户可见 diff**（命令、行为、边界、计划状态）。
+2. **对照上表**产出缺口清单（页面路径 + 要改的一句话）。
+3. **最小补丁**：只改清单内页面；禁止顺手重写 practices 或迁移整个 `ai_workspace/loop-agent/`。
+4. **验证**（见下节）。
+5. **Handoff** 二选一：
+   - 已更新：列出改动页面与验证命令结果。
+   - 无需站上更新：写明「本轮无需站上更新，原因：…」。
+
+## 验证命令
+
+站上正文、侧栏或 `docusaurus.config.ts` 有改动时：
+
+```bash
+npm run docs:build
+```
+
+涉及治理文档、脚本、skill、init surface 时再跑：
+
+```bash
+bash scripts/check-repo.sh
+# 或定向：
+bash scripts/check-skill-entry.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-init-surface.sh
+node bin/loop-agent.js docs audit --repo-root .
+```
+
+skill / package 投影相关：
+
+```bash
+npx vitest run test/init-command.test.ts test/package-surface.test.ts
+```
+
+## 禁止事项
+
+- 每次会话从头撰写全新文档大纲或「重新规划整个 docs 树」。
+- 把 `ai_workspace/loop-agent/design/`、exec-plans、reports 全文复制进 `website/docs/`。
+- 在站上建立第二套与 `ai_workspace/loop-agent/architecture/*` 冲突的架构真源。
+- 未读 `website/README.md` 与相关 exec-plan 就扩大 scope。
+- 用删测试、降 `onBrokenMarkdownLinks` 或忽略 `docs:build` 失败制造「完成」。
+- 新增独立公共 skill 目录承载本检查表（应留在 `.agents/skills/loop-agent/references/`）。
+
+## 与现有能力的关系
+
+| 能力 | 关系 |
+| --- | --- |
+| `loop-agent docs audit` | L0 腐化检查（断链、计划状态等）；**不**替代本表内容审计 |
+| `npm run docs:build` | 站上改动硬门禁（含 Markdown 断链 fail-fast） |
+| `grill-with-docs` | ADR / 术语；不替代本 reference |
+| 历史 2026-07-05 docs governance dogfood | 仅经验输入；新 workflow 必须 Pi-only，不复用已退役原生 Cursor DAG |
+
+## 快速自检（handoff 前 30 秒）
+
+- [ ] 用户可见变更是否对照检查表处理或已豁免？
+- [ ] intro 是否仍是概念地图（而非能力 bullet 堆砌）？
+- [ ] roadmap 是否只含当前有效 active 项？
+- [ ] 需要时 `docs:build` / `check-repo` 是否有新鲜输出？

package/skills/loop-agent/references/hybrid-dag.md

@@ -67,7 +67,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 
 - **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
 - **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 与自动 promotion 记录治理强度，已识别的前端业务 workflow 仍使用前端专用模板。高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
-- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖 model 名；不选 provider。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`gpt-5.5`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
+- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖模型。值写成 `provider/model` 时显式选择 Pi provider（只分割第一个 `/`）；裸模型名继续走内置映射或默认 `wizard-local`。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`gpt-5.5`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
 - **Active visibility**：真实 `run-dag` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
 - **可选 Canvas**：传 `--canvas-path <abs-path>` 或 `--canvas <name>` 输出 derived `.canvas.tsx` live view。省略 flag 行为不变。`--init-only` + Canvas 无需 `CURSOR_API_KEY`。
 
@@ -232,7 +232,7 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | --- | ------- | -------- |
 | 1 | Topology | 优先 same-rank parallel read-only scout/review；仅 output 真正需要时加 `depends_on` |
 | 2 | Executor | 每个 task 显式声明 `executor`；`defaults.executor` 是 schema metadata，非 runtime fallback |
-| 3 | Model routing | 用 node `complexity` + `executorModels`；Pi MED 与 HIGH 当前都使用 `gpt-5.5`，切换 complexity 不会切换模型；provider 临时不可用时仅使用有记录、有限范围的 worker `--pi-model` smoke override，勿 mutate canonical model matrix |
+| 3 | Model routing | 用 node `complexity` + `executorModels`；需要固定 provider 时写 `provider/model`，裸模型名保持兼容；Pi MED 与 HIGH 默认都使用 `gpt-5.5`，切换 complexity 不会切换默认模型；provider 临时不可用时仅使用有记录、有限范围的 worker `--pi-model` smoke override，勿 mutate canonical model matrix |
 | 4 | Read-only output | read-only / Pi node 在 **node output** 返回发现；runner 归档于 `.harness/dag-runs/<run-id>/<node-id>/` |
 | 5 | Root `artifacts/**` | 非 read-only handoff target；持久记录去 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/`，或 narrow exclusive `writeSet` 写 legacy 摘要并记录迁移计划 |
 | 6 | DAG Cursor artifacts | 写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；不得写入 `./artifacts/**` |

package/skills/loop-agent/references/learned/README.md

@@ -1,21 +1,21 @@
-# Learned loop-agent Patterns
-
-本目录是 SePO-lite prompt evolution 的 human-gated target。
-
-Rules:
-
-- Files 仅为 Markdown guidance。
-- `retrospective` 可 propose `.harness/tasks/<task-id>/source/prompt-delta.md`；不得自动 merge 到此。
-- 不要添加 shell commands、credential handling、tool permission expansion 或 completion-authority bypass rules。
-- DAG implementer prompts 在 node 已 request `loop-agent` skill 时，可将 repo-specific 文件 `<repo>.md` 或 `default.md` 作为 bounded inline guidance 加载。
-- 保持条目 short 且 pattern-oriented：failure class、fix scope shape、invariant、verification evidence。
-
-Acceptance checklist before merging a prompt delta:
-
-- Proposal 仅为 Markdown-only process guidance。
-- 不含 shell/runtime command lines 或 fenced command blocks。
-- Credential material、tokens、passwords、secrets 与 API keys 保持不可触达。
-- Tool permissions、path allowlists、`allowedPaths`、`forbiddenPaths` 与 `writeSet` 保持既有边界。
-- Shell verification、tests、write guards、decision gates、human gates 与 completion evidence 均为保留门禁。
-- Completed DAG 与 one-shot run facts 保持只读。
-- Learned file 编辑后 `loop-agent docs audit` 须 pass。
+# Learned loop-agent Patterns
+
+本目录是 SePO-lite prompt evolution 的 human-gated target。
+
+Rules:
+
+- Files 仅为 Markdown guidance。
+- `retrospective` 可 propose `.harness/tasks/<task-id>/source/prompt-delta.md`；不得自动 merge 到此。
+- 不要添加 shell commands、credential handling、tool permission expansion 或 completion-authority bypass rules。
+- DAG implementer prompts 在 node 已 request `loop-agent` skill 时，可将 repo-specific 文件 `<repo>.md` 或 `default.md` 作为 bounded inline guidance 加载。
+- 保持条目 short 且 pattern-oriented：failure class、fix scope shape、invariant、verification evidence。
+
+Acceptance checklist before merging a prompt delta:
+
+- Proposal 仅为 Markdown-only process guidance。
+- 不含 shell/runtime command lines 或 fenced command blocks。
+- Credential material、tokens、passwords、secrets 与 API keys 保持不可触达。
+- Tool permissions、path allowlists、`allowedPaths`、`forbiddenPaths` 与 `writeSet` 保持既有边界。
+- Shell verification、tests、write guards、decision gates、human gates 与 completion evidence 均为保留门禁。
+- Completed DAG 与 one-shot run facts 保持只读。
+- Learned file 编辑后 `loop-agent docs audit` 须 pass。