@tea-agent/loop-agent 0.26.0 → 0.26.2

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/SKILL.md

@@ -27,8 +27,11 @@ Entry: routing and hard rules. Required details come from frontmatter references
 
 ```bash
 loop-agent new-task <task-id> "Title"
-# Prefer import-prd when a PRD exists; plan create for non-trivial work
-# (see references/source-and-plan-practice.md)
+# PRD-first default: detailed PRD → import-prd → task source prepare --apply
+# no hand-written/LLM source by default
+loop-agent import-prd <task-id> --file <prd.md>
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
+# plan create for non-trivial work (see references/source-and-plan-practice.md)
 loop-agent dag run-task <task-id> --profile auto --strict-models
 # default draft: .harness/tasks/<task-id>/dag.json
 loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance

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/command-reference.md

@@ -37,9 +37,14 @@ loop-agent doctor
 
    ```bash
    loop-agent new-task <task-id> "Task Title"
-   # 有原始 PRD 文件时（推荐默认）：
-   # loop-agent import-prd <task-id> --file <path-to-prd.md>
-   # 写 source/需求.md、执行约束.md，并同步 task.json 路径边界
+   # 推荐默认：详细 PRD → import → prepare（无需手写两 source；默认无 LLM 写 source）
+   loop-agent import-prd <task-id> --file <path-to-prd.md>
+   loop-agent task source prepare <task-id> \
+     --use-imported-prd \
+     --allowed-path "<glob>" \
+     --forbidden-path ".harness/**" \
+     --verify "typecheck:npm run typecheck" \
+     --apply --json
    # 非微小 / 跨会话（推荐默认）：
    # loop-agent plan create <plan-id> "<title>"
    loop-agent dag run-task <task-id> --profile auto --strict-models
@@ -168,7 +173,7 @@ loop-agent new-task <task-id> "Task Title"
 loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [--name requirement] [--json]
 ```
 
-把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
+把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后用 `task source prepare --use-imported-prd --apply` 派生 managed `source/需求.md` / `执行约束.md`；冲突时以 `source/references/*` 为准。
 
 `referenceDocs` 是 `{ path, name? }[]` 对象数组，不是路径字符串数组；`import-prd` 会确定性写入正确结构。
 
@@ -213,22 +218,19 @@ one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`
 
 ### 运行任何 step 前：准备 source materials
 
-`new-task` 之后，先归档原始 PRD，再写派生执行契约：
+`new-task` 之后，先归档原始 PRD，再 `task source prepare` 派生执行契约：
 
 ```bash
 loop-agent import-prd <task-id> --file <path-to-original-prd.md>
-# then write derived contract:
-mkdir -p <repo-root>/.harness/tasks/<task-id>/source
-cat > <repo-root>/.harness/tasks/<task-id>/source/需求.md
+loop-agent task source prepare <task-id> \
+  --use-imported-prd \
+  --allowed-path "<glob>" \
+  --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" \
+  --apply --json
 ```
 
-`需求.md` 写目标、范围、非目标与验收标准，并映射回 `source/references/*`；不要让 AI 直接改写原始 PRD。
-
-若 task 有硬约束（仅允许特定文件、禁止改动），另加：
-
-```bash
-cat > <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
-```
+默认无 LLM 写 source；工程边界用 flags 显式给出。不要让 AI 直接改写 `source/references/*`。高级用户仍可手工编辑后 `task contract adopt`。
 
 ### Feature-study workflow（参考代码 → 轻量实现）
 

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/harness-policy.md

@@ -54,10 +54,9 @@ Minimum governed path：
 
 ```bash
 loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
-# Prefer import-prd for PRD files; plan create for non-trivial work (source-and-plan-practice.md)
-# loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--repo-root <target-repo>]
-# write derived <target-repo>/.harness/tasks/<task-id>/source/需求.md
-# write <target-repo>/.harness/tasks/<task-id>/source/执行约束.md
+# PRD-first: import-prd → task source prepare --apply
+loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--repo-root <target-repo>]
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json [--repo-root <target-repo>]
 
 loop-agent dag run-task <task-id> \
   --profile auto \