@tea-agent/loop-agent 0.26.0 → 0.26.1

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。

package/skills/loop-agent/references/long-running-loop.md

@@ -1,57 +1,57 @@
-# Long-Running Loop 详细规则
-
-需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
-
-## 最小入口
-
-```bash
-loop-agent loop init <task-id>
-loop-agent loop status <task-id>
-loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
-loop-agent loop run <task-id> --action pi-review
-loop-agent loop run <task-id> --action dag
-loop-agent loop run <task-id> --action dag --execute
-loop-agent loop run <task-id> --auto --max-rounds 3
-loop-agent loop run <task-id> --auto --max-rounds 3
-loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
-loop-agent loop closeout <task-id>
-loop-agent loop record-round <task-id> \
-  --action manual \
-  --result "summary" \
-  --lesson "what to carry forward" \
-  --next "next bounded action" \
-  --decision continue \
-  --ref ".harness/runs/completed/<run-id>/result.json"
-```
-
-## 状态源与记忆规则
-
-- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
-- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
-- `context.md` 每轮重写为压缩记忆，不无限 append。
-- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
-
-## Action 规则
-
-- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
-- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
-- 自动写入只能通过 `loop run --action dag --execute` / auto DAG execute；须读取 task `allowedPaths` / `forbiddenPaths` 并审查 writer writeSet。
-- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
-- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
-
-## Auto mode 与写入边界
-
-- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block。
-- 自动 DAG execute 必须显式 opt-in：`task.json.loopAutoExecutionPolicy="enabled"`，或 `approval-required` 加 pending approval；旧 `loopAutoWritePolicy` fail-fast。
-- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
-
-## Signals
-
-- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
-- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
-
-## Closeout
-
-- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
-- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
-- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。
+# Long-Running Loop 详细规则
+
+需要跨多轮记录目标、压缩记忆、round facts 引用，或使用 `loop init|status|run|record-round|add-signal|closeout` 时使用本文。`loop` 是 experimental outer workflow state：它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。共享 policy 摘要见 `harness-policy.md` 的 "Long-running loop policy" 一节。
+
+## 最小入口
+
+```bash
+loop-agent loop init <task-id>
+loop-agent loop status <task-id>
+loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
+loop-agent loop run <task-id> --action pi-review
+loop-agent loop run <task-id> --action dag
+loop-agent loop run <task-id> --action dag --execute
+loop-agent loop run <task-id> --auto --max-rounds 3
+loop-agent loop run <task-id> --auto --max-rounds 3
+loop-agent loop add-signal <task-id> --type human_followup --message "review this boundary before closeout"
+loop-agent loop closeout <task-id>
+loop-agent loop record-round <task-id> \
+  --action manual \
+  --result "summary" \
+  --lesson "what to carry forward" \
+  --next "next bounded action" \
+  --decision continue \
+  --ref ".harness/runs/completed/<run-id>/result.json"
+```
+
+## 状态源与记忆规则
+
+- `loop/objective.md` 与 `loop/context.md` 是运行态投影；exec plan / task source 仍是需求状态源。
+- `rounds.jsonl` 只引用 canonical facts，不复制完整 executor 日志。
+- `context.md` 每轮重写为压缩记忆，不无限 append。
+- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
+
+## Action 规则
+
+- `loop run --action shell-verify` 是 deterministic action；命令 exit code 决定 verification result，输出摘要写入 `loop/verification/round-N.json`。
+- `loop run --action pi-review` 必须保持 read-only；工具 allowlist 固定为 `read,grep,find,ls`，输出必须包含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`，其中 `recommendedAction` 只能是 `implement_fix|replan|pause|done`。
+- 自动写入只能通过 `loop run --action dag --execute` / auto DAG execute；须读取 task `allowedPaths` / `forbiddenPaths` 并审查 writer writeSet。
+- `loop run --action dag` 默认是 review mode：调用 `dag run-task <task-id> --profile auto --strict-models` 生成 DAG，再用 `dag validate --strict-models --strict-governance` 校验，并记录 review packet。
+- `loop run --action dag --execute` 才会调用 `run-dag`，随后读取 `dag report --json` 作为 round result；paused DAG 会让 loop 进入 `paused`。
+
+## Auto mode 与写入边界
+
+- `loop run --auto --max-rounds N` 使用 deterministic policy 选择下一轮 action；默认只会自动选择 shell-verify、pi-review、dag review 或 policy pause/block。
+- 自动 DAG execute 必须显式 opt-in：`task.json.loopAutoExecutionPolicy="enabled"`，或 `approval-required` 加 pending approval；旧 `loopAutoWritePolicy` fail-fast。
+- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
+
+## Signals
+
+- `loop add-signal` 写入 durable `signals.jsonl`，支持 `human_followup|approval|scope_changed|review_feedback`；urgent/scope_changed 会 pause，review feedback / human follow-up 先走 read-only Pi review，approval 触发下一轮 DAG review packet。
+- Signals 不直接覆盖 `objective.md`；DAG decision envelope / approve / reject / resume 仍由 DAG action 机制管理，loop 只记录 refs。
+
+## Closeout
+
+- `loop closeout` 从 loop state、objective/context、rounds 和 signals 派生 `loop/closeout.md` draft；draft 会标出 workflow path（`dag` / `explicit-fallback` / `missing-dag-evidence` / `micro-or-small`）与 fallback reason。
+- 非 complete 状态必须标 partial/paused/blocked，不能修改 completed facts；medium/large loop 若缺少 DAG round 且没有 `dagFallbackReason`，必须把缺失 DAG 证据列为 remaining risk。
+- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。

package/skills/loop-agent/references/one-shot-runs.md

@@ -1,85 +1,85 @@
-# One-shot Run Evidence（`.harness/runs/`）
-
-当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
-
-## 目录职责
-
-`.harness/runs/` 保存一次性工具调用的运行证据。它不是 task 状态源，也不是 Agent DAG run 目录。
-
-```text
-.harness/runs/active/<run-id>/      # 正在执行或异常残留的 one-shot tool run
-.harness/runs/completed/<run-id>/   # 成功完成的 one-shot run evidence
-.harness/runs/failed/<run-id>/      # 失败的 one-shot run evidence
-```
-
-每个 run directory 通常包含：
-
-```text
-run.md
-meta.json
-artifacts/
-```
-
-`run.md` 是人类可读摘要；`meta.json` 是机器可读 run metadata；`artifacts/` 是该次 one-shot 的交付物目录。
-
-## 什么时候创建
-
-会创建 `.harness/runs/` 的常见入口：
-
-- `loop-agent cursor-prompt ...`
-- Pi `cursor` tool / loop-agent cursor tool 的 one-shot Cursor 调用
-- 内部 two-phase one-shot logging：先 `createActiveCursorRun()`，再 `finalizeCursorRunLog()`
-
-创建条件：
-
-- 调用的 `cwd` 必须是含 `.harness/` 的 harness repo。
-- `cursor-prompt` 会先创建 `.harness/runs/active/<run-id>/`，再把结果归档。
-- 成功时整个目录移动到 `.harness/runs/completed/<run-id>/`。
-- 失败、timeout 或 cancel 时整个目录移动到 `.harness/runs/failed/<run-id>/`。
-
-当前 `pi-prompt` 不创建 `.harness/runs/`。它是 one-shot helper，但不维护 run evidence、task state、verification 或 handoff artifact。
-
-## 与 task / DAG 的关系
-
-| 目录 | 含义 | 是否代表 task 完成 |
-|---|---|---|
-| `.harness/tasks/<task-id>/` | task 运行态状态源 | 是 task 状态源 |
-| `.harness/runs/<state>/<run-id>/` | one-shot tool run evidence | 否，只是一次执行证据 |
-| `.harness/dag-runs/<state>/<run-id>/` | Agent DAG run facts | 否，只是 DAG run facts |
-
-completed one-shot evidence 若要进入 task artifacts，使用：
-
-```bash
-loop-agent promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
-```
-
-`promote-run` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
-
-## Active 目录清理
-
-`.harness/runs/active/` 只应存在 live one-shot run。治理检查发现 active 内容时会 warning：
-
-```text
-[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries
-```
-
-处理规则：
-
-- 如果确有 one-shot 正在执行，可以保留；必要时用 `HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1` 跑治理检查。
-- 如果是已完成、失败或中断残留，应移动到 `completed/` / `failed/`，或在确认无价值后删除。
-- 如果是 `.DS_Store` 等系统垃圾文件，直接删除；它不是合法 run evidence。
-- 不要把 active 残留当作 task 完成证据。
-
-严格检查可用：
-
-```bash
-HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
-```
-
-## 不要做什么
-
-- 不要提交 `.harness/runs/**` 运行态内容。
-- 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
-- 不要把 `.harness/runs/active/**` 当作长期记录。
-- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。
+# One-shot Run Evidence（`.harness/runs/`）
+
+当你使用 `cursor-prompt`、Pi `cursor` tool、`promote-run`，或在治理检查中看到 `.harness/runs/active` warning 时，读本文。
+
+## 目录职责
+
+`.harness/runs/` 保存一次性工具调用的运行证据。它不是 task 状态源，也不是 Agent DAG run 目录。
+
+```text
+.harness/runs/active/<run-id>/      # 正在执行或异常残留的 one-shot tool run
+.harness/runs/completed/<run-id>/   # 成功完成的 one-shot run evidence
+.harness/runs/failed/<run-id>/      # 失败的 one-shot run evidence
+```
+
+每个 run directory 通常包含：
+
+```text
+run.md
+meta.json
+artifacts/
+```
+
+`run.md` 是人类可读摘要；`meta.json` 是机器可读 run metadata；`artifacts/` 是该次 one-shot 的交付物目录。
+
+## 什么时候创建
+
+会创建 `.harness/runs/` 的常见入口：
+
+- `loop-agent cursor-prompt ...`
+- Pi `cursor` tool / loop-agent cursor tool 的 one-shot Cursor 调用
+- 内部 two-phase one-shot logging：先 `createActiveCursorRun()`，再 `finalizeCursorRunLog()`
+
+创建条件：
+
+- 调用的 `cwd` 必须是含 `.harness/` 的 harness repo。
+- `cursor-prompt` 会先创建 `.harness/runs/active/<run-id>/`，再把结果归档。
+- 成功时整个目录移动到 `.harness/runs/completed/<run-id>/`。
+- 失败、timeout 或 cancel 时整个目录移动到 `.harness/runs/failed/<run-id>/`。
+
+当前 `pi-prompt` 不创建 `.harness/runs/`。它是 one-shot helper，但不维护 run evidence、task state、verification 或 handoff artifact。
+
+## 与 task / DAG 的关系
+
+| 目录 | 含义 | 是否代表 task 完成 |
+|---|---|---|
+| `.harness/tasks/<task-id>/` | task 运行态状态源 | 是 task 状态源 |
+| `.harness/runs/<state>/<run-id>/` | one-shot tool run evidence | 否，只是一次执行证据 |
+| `.harness/dag-runs/<state>/<run-id>/` | Agent DAG run facts | 否，只是 DAG run facts |
+
+completed one-shot evidence 若要进入 task artifacts，使用：
+
+```bash
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`promote-run` 只读 `.harness/runs/completed/**`，生成或更新 task `artifacts/修改记录.md` / `artifacts/验证结果.md`，不修改 completed run facts。
+
+## Active 目录清理
+
+`.harness/runs/active/` 只应存在 live one-shot run。治理检查发现 active 内容时会 warning：
+
+```text
+[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries
+```
+
+处理规则：
+
+- 如果确有 one-shot 正在执行，可以保留；必要时用 `HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1` 跑治理检查。
+- 如果是已完成、失败或中断残留，应移动到 `completed/` / `failed/`，或在确认无价值后删除。
+- 如果是 `.DS_Store` 等系统垃圾文件，直接删除；它不是合法 run evidence。
+- 不要把 active 残留当作 task 完成证据。
+
+严格检查可用：
+
+```bash
+HARNESS_STRICT_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh
+```
+
+## 不要做什么
+
+- 不要提交 `.harness/runs/**` 运行态内容。
+- 不要手动改写 `.harness/runs/completed/**` 或 `.harness/runs/failed/**` 事实。
+- 不要把 `.harness/runs/active/**` 当作长期记录。
+- 不要把 one-shot evidence 直接等同于 task artifacts；需要汇总时用 `promote-run`。

package/skills/loop-agent/references/pi-prompt.md

@@ -1,23 +1,23 @@
-# One-shot Pi SDK Prompt Helper（`pi-prompt`）
-
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
-
-### One-shot Pi SDK prompt helper
-
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
-
-```bash
-loop-agent pi-prompt "Reply with exactly OK."
-loop-agent pi-prompt --stdin < <temp-dir>/task.md
-loop-agent pi-prompt --file <temp-dir>/task.md
-loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
-loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
-loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
-loop-agent pi-prompt "Reply with exactly OK."
-```
-
-`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
-
-默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
-
-`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。
+# One-shot Pi SDK Prompt Helper（`pi-prompt`）
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
+
+### One-shot Pi SDK prompt helper
+
+短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时，用 `loop-agent pi-prompt`，勿创建 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt`。`pi-prompt` 是一次性 full-capability helper；是否只读由本次调用的 prompt 与 `--tools` 决定。
+
+```bash
+loop-agent pi-prompt "Reply with exactly OK."
+loop-agent pi-prompt --stdin < <temp-dir>/task.md
+loop-agent pi-prompt --file <temp-dir>/task.md
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools read,grep,find,ls "Review the current diff. Do not edit files."
+loop-agent pi-prompt --cwd ~/go/src/loop-agent --tools subagent,read --timeout 2400000 "Use subagent exactly once ..."
+loop-agent pi-prompt --model gpt-5.5 --cwd ~/go/src/loop-agent "Deeply diagnose this failure."
+loop-agent pi-prompt "Reply with exactly OK."
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
+
+默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
+
+`pi-prompt` 仅用于 quick one-shot SDK call。**不**创建 `.harness/tasks/`、不跑 verification、不写 handoff artifact、不保留 workflow state。须可恢复、可验证的 implementation work 用 DAG 路径；需要隔离写入时使用 bounded Cursor 或 `delegate`。

package/skills/loop-agent/references/pi-subagent-assisted-mode.md

@@ -1,84 +1,84 @@
-# Pi Subagent Assisted Mode
-
-loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
-
-`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
-
-| Mode | analyze | plan | spec | implement | retrospective | verify |
-|------|---------|------|------|-----------|----------------|--------|
-| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
-| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
-| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
-
-### 何时启用
-
-在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
-- task 涉及大规模 codebase 阅读，适合 parallel scout agents
-- analysis 或 planning 需多角度调查（如跨模块比较实现）
-- retrospective review 适合独立 reviewer subagent（`full` mode）
-
-### step 内使用 `subagent` 的指引
-
-subagent 可用时，**仅用于 read-only task**：
-- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
-- **Chain**：一个 subagent scout，另一个基于发现 planning
-- **Reviewer**：用 subagent 在定稿前 review analysis/plan
-
-**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
-
-### 前置条件
-
-- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
-- 推荐用 Pi 自带 example 文件安装：
-
-```bash
-mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
-
-ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
-ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
-
-for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
-  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
-done
-
-for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
-  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
-done
-```
-
-- 最小 smoke check：
-
-```bash
-pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
-```
-
-  预期输出：`OK`
-- mode 按 task opt-in；默认 `off` 保持向后兼容
-- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
-
-### 内置 Project-Local Agents 与 Prompts
-
-本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
-
-**Agents**（`.pi/agents/`）
-
-| Agent | Role | 对应阶段 |
-|-------|------|----------|
-| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
-| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
-| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
-| `loop-agent-worker` | 有界实现与修补 | Implement |
-
-另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
-
-**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
-
-| Template | Flow |
-|----------|------|
-| `loop-agent-scout-and-plan` | parallel scout → planner |
-| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
-| `loop-agent-review-only` | 独立审查计划/实现/验证 |
-| `loop-agent-implement-and-review` | worker → reviewer → worker |
-| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
-
-传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。
+# Pi Subagent Assisted Mode
+
+loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
+
+`task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
+
+| Mode | analyze | plan | spec | implement | retrospective | verify |
+|------|---------|------|------|-----------|----------------|--------|
+| `off`（默认） | read only | read only | read only | +write/edit/bash | read only | read only |
+| `analyze-plan` | **+subagent** | **+subagent** | **+subagent** | 同 off | 同 off | 同 off |
+| `full` | **+subagent** | **+subagent** | **+subagent** | 同 off | **+subagent** | 同 off |
+
+### 何时启用
+
+在 `task.json` 设 `piSubagentMode: "analyze-plan"` 或 `piSubagentMode: "full"` 当：
+- task 涉及大规模 codebase 阅读，适合 parallel scout agents
+- analysis 或 planning 需多角度调查（如跨模块比较实现）
+- retrospective review 适合独立 reviewer subagent（`full` mode）
+
+### step 内使用 `subagent` 的指引
+
+subagent 可用时，**仅用于 read-only task**：
+- **Parallel scout**：dispatch 多个 subagent 同时搜索/阅读不同区域
+- **Chain**：一个 subagent scout，另一个基于发现 planning
+- **Reviewer**：用 subagent 在定稿前 review analysis/plan
+
+**不要**用 subagent 做 writing、editing 或执行命令。subagent 输出仅 advisory；务必 verify 并将发现并入自己的输出。**不要**把 subagent 结果当作权威 state 或 artifact source。
+
+### 前置条件
+
+- Pi runtime 环境须有 `subagent` tool（经 Pi subagent extension 加载）
+- 推荐用 Pi 自带 example 文件安装：
+
+```bash
+mkdir -p ~/.pi/agent/extensions/subagent ~/.pi/agent/agents ~/.pi/agent/prompts
+
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/index.ts ~/.pi/agent/extensions/subagent/index.ts
+ln -sf /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents.ts ~/.pi/agent/extensions/subagent/agents.ts
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/agents/*.md; do
+  ln -sf "$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+for f in /usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$f" ~/.pi/agent/prompts/$(basename "$f")
+done
+```
+
+- 最小 smoke check：
+
+```bash
+pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with exactly OK."
+```
+
+  预期输出：`OK`
+- mode 按 task opt-in；默认 `off` 保持向后兼容
+- 任何 mode 下 `implement` 都不给 `subagent`（防止 nested multi-writer）
+
+### 内置 Project-Local Agents 与 Prompts
+
+本 repo 提供 `.pi/agents/` 与 `.pi/prompts/` 模板，供 `piSubagentMode` 使用：
+
+**Agents**（`.pi/agents/`）
+
+| Agent | Role | 对应阶段 |
+|-------|------|----------|
+| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
+| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
+| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
+| `loop-agent-worker` | 有界实现与修补 | Implement |
+
+另有通用 agents：`scout` / `planner` / `worker` / `reviewer`（中文提示，可被通用 prompt 模板调用）。模型以各 agent frontmatter 为准（当前仓库默认对齐 `harness.json` 的 Pi executor）。
+
+**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 或通用模板名调用
+
+| Template | Flow |
+|----------|------|
+| `loop-agent-scout-and-plan` | parallel scout → planner |
+| `loop-agent-analyze-wide` | 3 parallel scouts → 结构化分析 |
+| `loop-agent-review-only` | 独立审查计划/实现/验证 |
+| `loop-agent-implement-and-review` | worker → reviewer → worker |
+| `scout-and-plan` / `implement` / `implement-and-review` | 通用 chain（调用 `scout`/`planner`/`worker`/`reviewer`） |
+
+传 `agentScope: "both"` + `confirmProjectAgents: false` 以访问 repo-local agents。

package/skills/loop-agent/references/post-implementation-and-patterns.md

@@ -27,7 +27,7 @@ DAG run、promotion、closeout 和最终验证完成后：
 
 ```
 1. new-task <id>
-2. 有 PRD 文件：import-prd；再写 source/需求.md + source/执行约束.md
+2. 有 PRD 文件：import-prd → task source prepare --use-imported-prd --apply（默认不手写两 source）
 3. 非微小：plan create（或挂到已有 active plan）
 4. dag run-task <id> --profile auto --strict-models
 5. dag validate --dag .harness/tasks/<id>/dag.json --strict-models --strict-governance

package/skills/loop-agent/references/source-and-plan-practice.md

@@ -11,7 +11,7 @@ Task 目录布局：`task-workflow.md`。
 | 层 | 命令 / 路径 | 作用 | 主路径 DAG 是否强制 |
 | --- | --- | --- | --- |
 | Source 事实 | `import-prd` → `source/references/*` + `source-manifest.json` | 原始 PRD **不可变**归档 | 否（有 PRD 文件时**强烈推荐**） |
-| Source 契约 | 手写 `source/需求.md`、`执行约束.md` + `task.json` 路径边界 | DAG 生成与验收真源 | **是**（至少 `需求.md`） |
+| Source 契约 | `task source prepare --apply` 投影 `source/需求.md`、`执行约束.md` + managed paths | DAG 生成与验收真源 | **是**（至少 `需求.md`；默认不手写） |
 | Exec-plan | `plan create` / `plan complete` / `plan check` | 仓库级计划索引与交接 | 否（**非微小**推荐） |
 | DAG 运行时 | `dag run-task` → `dag validate` → `run-dag` | 可执行编排 | **是**（常规实现） |
 
@@ -47,7 +47,8 @@ Task 目录布局：`task-workflow.md`。
 ```bash
 loop-agent new-task <task-id> "简短标题"
 loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--json]
-# 再写派生契约（映射 REQ/AC 或原文锚点）
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
+# 默认无 LLM 写 source；工程边界用 flags 显式给出
 #   .harness/tasks/<task-id>/source/需求.md
 #   .harness/tasks/<task-id>/source/执行约束.md
 # 同步 task.json.allowedPaths / forbiddenPaths

package/skills/loop-agent/references/task-workflow.md

@@ -8,7 +8,9 @@
 
 ```bash
 loop-agent new-task <task-id> "Task Title"
-# 有原始 PRD：loop-agent import-prd <task-id> --file <prd>
+# 推荐：详细 PRD → import → prepare（无需手写两 source）
+loop-agent import-prd <task-id> --file <prd>
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
 # 非微小：loop-agent plan create <plan-id> "<title>"（可与 task 解耦，见 source-and-plan-practice.md）
 loop-agent dag run-task <task-id> --profile auto --strict-models
 loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
@@ -35,10 +37,10 @@ loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
   task.json
 ```
 
-- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就 import**；无独立文件才允许只写 `需求.md`（见 `source-and-plan-practice.md` 决策表）。
-- `需求.md` 是派生执行契约：写清目标、验收标准、非目标，并用 REQ/AC 或原文锚点映射回 references。
-- `执行约束.md` 写清允许文件、禁止改动、硬约束和验证命令。
-- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再在 `需求.md` 引用；避免把长 PRD 直接改写成唯一 source。
+- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就 import**。
+- 默认用 `task source prepare --use-imported-prd --apply` 投影 `需求.md` / `执行约束.md` 与 managed paths；**不要**默认让 LLM/主会话手写两 source。
+- 无独立 PRD 的微小任务可用 `task source prepare --from-text ... --apply` escape hatch（见 `source-and-plan-practice.md`）。
+- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再 prepare 派生薄契约；避免把长 PRD 直接改写成唯一 source。
 - 仓库级 exec-plan（`plan create`）与 harness task **解耦**：非微小实现应有 plan 或复用 active plan；微小任务可不建 plan。
 - Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
 - review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。