@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/skills/loop-agent/SKILL.md

@@ -1,151 +1,151 @@
----
-name: loop-agent
-description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现.
-references:
-  - path: references/harness-policy.md
-    required: true
-  - path: references/hybrid-dag.md
-    required: true
-  - path: references/verification-and-failure-handling.md
-    required: true
-  - path: references/command-reference.md
-    required: true
----
-
-# loop-agent Workflow
-
-这是 `loop-agent` 的入口文档，只负责 trigger、routing 和硬规则。较长的 command details、workflow 细节与失败处理放在 `references/`，按需加载。
-
-## Canonical Harness Policy
-
-Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
-
-## 默认立场
-
-- 主入口是 **Agent DAG**。
-- 主会话负责编排、审 writeSet、复核验证与 handoff。
-- DAG `pi` executor 是唯一受治理 Agent runtime：默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
-- `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
-- Cursor 仅是显式、手工触发的 `cursor-prompt` one-shot sidecar，不是受治理 DAG/Loop writer；受治理写入固定为 `implement-pi` / `repair-pi`，必须给出 allowed / forbidden paths 与 writeSet。
-- Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
-- 长期结论写回 `docs/exec-plans/`、`docs/reports/`、`docs/progress/` 或 `./skill/`。
-
-## 唯一推荐执行路径
-
-```bash
-loop-agent new-task <task-id> "Task Title"
-# Prefer immutable original PRD first:
-# loop-agent import-prd <task-id> --file <path-to-original-prd.md>
-# write derived <repo-root>/.harness/tasks/<task-id>/source/需求.md
-# write <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
-
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
-```
-
-`loop-agent` 默认指 npm 上已发布的全局 CLI。自举迭代 loop-agent 本仓库时，首次安装或有意升级可用 `npm install -g @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 的任务。`npm run dev -- <args>` 只用于源码调试和聚焦 CLI 开发。
-
-`<temp-dir>` 表示平台原生临时目录。macOS 和 Windows 都应使用实际平台路径；`/` 只用于 repo refs、JSON/Markdown 证据 refs 和 glob 约定。
-
-执行前必须审阅：
-
-- `profileRouting`
-- `governanceProfile`
-- writer `writeSet`
-- writer `forbiddenPaths`
-- shell verification commands
-- decision gate mode
-
-## Pi Sidecar 入口规则
-
-短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`：
-
-- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
-- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
-- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
-
-## Bounded Write Execution
-
-需要写代码时，默认使用 DAG `pi` executor 的 write tool profile（`implement-pi` / `repair-pi`）。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
-
-`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `docs/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
-
-Pi writer prompt（以及可选 sidecar prompt）都必须包含：
-
-- task id
-- exact objective
-- allowed paths
-- forbidden paths
-- hard constraints
-- expected verification
-- instruction to preserve unrelated files
-
-bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的独立复核章节。
-
-## 进阶主题路由
-
-以下主题只在 references 中维护细节，不在本文展开：
-
-| 主题 | Reference |
-|---|---|
-| Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
-| Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
-| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
-| 伴生 CLI `agent-worker`（TaskSpec / Task Pool / batch / morning report） | `references/command-reference.md` |
-| Post-writer 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
-| Docs Converge（用户可见变更后的站上/治理文档同步检查表） | `references/docs-converge.md` |
-
-## Source Layout
-
-新代码优先从这些目录进入：
-
-| Area | Entry |
-|---|---|
-| CLI command tree / help / commander program | `src/cli/` |
-| DAG workflow | `src/workflows/dag/` |
-| Long-running loop workflow | `src/workflows/loop/` |
-| Task runtime | `src/task/` |
-| Executors | `src/executors/` |
-| Worker TaskSpec pipeline（伴生 CLI `agent-worker`） | `src/worker/` |
-| Run records / promotion / closeout | `src/records/` |
-| Governance | `src/governance/` |
-| Shared helpers | `src/shared/` |
-| Repo adapters | `src/adapters/` |
-
-不要新增平行兼容入口。CLI public export 的唯一入口是 `src/cli/index.ts`；commander command tree 和 help 实现在 `src/cli/program.ts`。
-
-## Hard Rules
-
-1. One task = one bounded work chunk.
-2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`. Prefer immutable originals under `source/references/` via `import-prd` or Worker `source_docs`; treat `需求.md` as a derived contract.
-3. Agent DAG is the implementation workflow. Review must three-way check references + derived source + implementation when originals exist.
-4. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
-5. Pi writer nodes must be bounded by explicit allowed / forbidden paths and writeSet; Cursor remains `cursor-prompt` sidecar only.
-6. Completed DAG and one-shot run facts are read-only.
-7. Do not write root `artifacts/` from read-only DAG or sidecar steps.
-8. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
-9. Verify before completion.
-
-## References
-
-Required（frontmatter 已声明）：
-
-- `references/harness-policy.md`
-- `references/hybrid-dag.md`
-- `references/verification-and-failure-handling.md`
-- `references/command-reference.md`
-
-Optional（按需加载）：
-
-- `references/orchestrator-and-interventions.md`
-- `references/long-running-loop.md`
-- `references/task-workflow.md`
-- `references/pi-prompt.md`
-- `references/one-shot-runs.md`
-- `references/pi-subagent-assisted-mode.md`
-- `references/model-routing.md`
-- `references/multi-worktree.md`
-- `references/post-implementation-and-patterns.md`
-- `references/docs-converge.md` — 用户可见变更后的文档收敛检查表；禁止每次重新规划整站大纲
+---
+name: loop-agent
+description: >-
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现.
+references:
+  - path: references/harness-policy.md
+    required: true
+  - path: references/hybrid-dag.md
+    required: true
+  - path: references/verification-and-failure-handling.md
+    required: true
+  - path: references/command-reference.md
+    required: true
+---
+
+# loop-agent Workflow
+
+这是 `loop-agent` 的入口文档，只负责 trigger、routing 和硬规则。较长的 command details、workflow 细节与失败处理放在 `references/`，按需加载。
+
+## Canonical Harness Policy
+
+Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
+
+## 默认立场
+
+- 主入口是 **Agent DAG**。
+- 主会话负责编排、审 writeSet、复核验证与 handoff。
+- DAG `pi` executor 是唯一受治理 Agent runtime：默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
+- `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
+- Cursor 仅是显式、手工触发的 `cursor-prompt` one-shot sidecar，不是受治理 DAG/Loop writer；受治理写入固定为 `implement-pi` / `repair-pi`，必须给出 allowed / forbidden paths 与 writeSet。
+- Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
+- 长期结论写回 `docs/exec-plans/`、`docs/reports/`、`docs/progress/` 或 `./skill/`。
+
+## 唯一推荐执行路径
+
+```bash
+loop-agent new-task <task-id> "Task Title"
+# Prefer immutable original PRD first:
+# loop-agent import-prd <task-id> --file <path-to-original-prd.md>
+# write derived <repo-root>/.harness/tasks/<task-id>/source/需求.md
+# write <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
+
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+```
+
+`loop-agent` 默认指 npm 上已发布的全局 CLI。自举迭代 loop-agent 本仓库时，首次安装或有意升级可用 `npm install -g @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 的任务。`npm run dev -- <args>` 只用于源码调试和聚焦 CLI 开发。
+
+`<temp-dir>` 表示平台原生临时目录。macOS 和 Windows 都应使用实际平台路径；`/` 只用于 repo refs、JSON/Markdown 证据 refs 和 glob 约定。
+
+执行前必须审阅：
+
+- `profileRouting`
+- `governanceProfile`
+- writer `writeSet`
+- writer `forbiddenPaths`
+- shell verification commands
+- decision gate mode
+
+## Pi Sidecar 入口规则
+
+短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`：
+
+- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
+- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
+- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
+
+## Bounded Write Execution
+
+需要写代码时，默认使用 DAG `pi` executor 的 write tool profile（`implement-pi` / `repair-pi`）。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
+
+`cursor-prompt` 仅作人工 one-shot sidecar intervention，不进入 Loop auto-execute / Delegate auto-run / DAG writer 选择。细节见 `docs/cursor-prompt-sidecar.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+
+Pi writer prompt（以及可选 sidecar prompt）都必须包含：
+
+- task id
+- exact objective
+- allowed paths
+- forbidden paths
+- hard constraints
+- expected verification
+- instruction to preserve unrelated files
+
+bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的独立复核章节。
+
+## 进阶主题路由
+
+以下主题只在 references 中维护细节，不在本文展开：
+
+| 主题 | Reference |
+|---|---|
+| Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
+| Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
+| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
+| 伴生 CLI `agent-worker`（TaskSpec / Task Pool / batch / morning report） | `references/command-reference.md` |
+| Post-writer 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
+| Docs Converge（用户可见变更后的站上/治理文档同步检查表） | `references/docs-converge.md` |
+
+## Source Layout
+
+新代码优先从这些目录进入：
+
+| Area | Entry |
+|---|---|
+| CLI command tree / help / commander program | `src/cli/` |
+| DAG workflow | `src/workflows/dag/` |
+| Long-running loop workflow | `src/workflows/loop/` |
+| Task runtime | `src/task/` |
+| Executors | `src/executors/` |
+| Worker TaskSpec pipeline（伴生 CLI `agent-worker`） | `src/worker/` |
+| Run records / promotion / closeout | `src/records/` |
+| Governance | `src/governance/` |
+| Shared helpers | `src/shared/` |
+| Repo adapters | `src/adapters/` |
+
+不要新增平行兼容入口。CLI public export 的唯一入口是 `src/cli/index.ts`；commander command tree 和 help 实现在 `src/cli/program.ts`。
+
+## Hard Rules
+
+1. One task = one bounded work chunk.
+2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`. Prefer immutable originals under `source/references/` via `import-prd` or Worker `source_docs`; treat `需求.md` as a derived contract.
+3. Agent DAG is the implementation workflow. Review must three-way check references + derived source + implementation when originals exist.
+4. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
+5. Pi writer nodes must be bounded by explicit allowed / forbidden paths and writeSet; Cursor remains `cursor-prompt` sidecar only.
+6. Completed DAG and one-shot run facts are read-only.
+7. Do not write root `artifacts/` from read-only DAG or sidecar steps.
+8. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
+9. Verify before completion.
+
+## References
+
+Required（frontmatter 已声明）：
+
+- `references/harness-policy.md`
+- `references/hybrid-dag.md`
+- `references/verification-and-failure-handling.md`
+- `references/command-reference.md`
+
+Optional（按需加载）：
+
+- `references/orchestrator-and-interventions.md`
+- `references/long-running-loop.md`
+- `references/task-workflow.md`
+- `references/pi-prompt.md`
+- `references/one-shot-runs.md`
+- `references/pi-subagent-assisted-mode.md`
+- `references/model-routing.md`
+- `references/multi-worktree.md`
+- `references/post-implementation-and-patterns.md`
+- `references/docs-converge.md` — 用户可见变更后的文档收敛检查表；禁止每次重新规划整站大纲

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 `docs/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，不承载长流程细节。
-- `docs/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/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 `docs/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，不承载长流程细节。
+- `docs/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/skills/loop-agent` 是指向本目录的 symlink，所以仓库内 edits 会直接更新 Pi skill。