@tea-agent/loop-agent 0.1.0

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

@@ -0,0 +1,63 @@
+# 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` |
+
+## 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、解释 failure mode、执行 completion audit 与 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` 保持约 200-300 行以内；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。

package/skills/loop-agent/references/command-reference.md

@@ -0,0 +1,315 @@
+# loop-agent 命令参考
+
+需要 loop-agent 的精确 CLI 命令、setup 命令、task lifecycle 命令、docs helper、goal 命令或 stats 时使用本文。
+
+## loop-agent 入口
+
+**优先在目标 repo 目录内执行命令** — loop-agent 通过 `harness.json.project` 自动检测使用哪个 repo adapter。跨目录操作时显式加 `--repo-root <target-repo>`。
+
+默认使用全局 CLI：
+
+```bash
+loop-agent <command> ...
+```
+
+面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+npm list -g @tea-agent/loop-agent --depth=0
+loop-agent doctor
+```
+
+一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
+
+发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
+
+发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
+
+## 命令参考
+
+## 默认选择模型
+
+选择命令时按以下优先级：
+
+1. **主路径 DAG**，用于常规 autonomous work：
+   ```bash
+   loop-agent new-task <task-id> "Task Title"
+   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>
+   ```
+   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
+2. **Operator 工具**，用于 recovery、诊断与 closeout：
+   ```bash
+   loop-agent dag status --run-id <run-id>
+   loop-agent dag doctor
+   loop-agent dag report --latest --markdown
+   loop-agent dag closeout-draft --run-id <run-id>
+   loop-agent dag reconcile-tasks --glob '<pattern>' --markdown
+   loop-agent dag final-verification <task-id> --output <temp-dir>/<task-id>-final-verification-dag.json
+   loop-agent status <task-id> --json
+   loop-agent instructions task-artifacts --task <task-id> --json
+   loop-agent promote-run <task-id> --run-id <run-id>
+   loop-agent closeout task <task-id>
+   loop-agent spine audit <task-id> --markdown
+   loop-agent knowledge curate --markdown --output docs/reports/<task-id>-learned-proposal.md
+   loop-agent loop-benchmark --markdown
+   ```
+3. **Escape hatch**，仅用于 worktree 隔离委派、executor 调试或 one-shot 诊断：
+   ```bash
+   loop-agent delegate <task-id> --executor cursor
+   loop-agent harvest <task-id>
+   loop-agent pi-prompt "Reply with exactly OK."
+   ```
+
+### Setup（首次）
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --help
+```
+
+### 检查 repo harness
+```bash
+loop-agent inspect                                           # 当前 repo（自动检测）
+loop-agent --repo-root /path/to/target-repo inspect           # 指定 repo
+```
+
+### 健康检查
+```bash
+loop-agent doctor
+```
+
+`doctor` 报告当前生效的 Pi backend 及 SDK/CLI 可用性。Pi step 默认 SDK-first 执行：
+
+```bash
+export CODE_AGENT_PI_BACKEND=sdk-first   # 默认：先试 Pi SDK，允许时 fallback 到 CLI
+export CODE_AGENT_PI_BACKEND=cli-only    # 紧急回滚：纯 CLI 路径
+```
+
+SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
+
+### 创建新 task
+```bash
+loop-agent new-task <task-id> "Task Title"
+```
+
+创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。
+
+### Task action context / artifact instructions
+```bash
+loop-agent status <task-id> --json
+loop-agent instructions source --task <task-id> --json
+loop-agent instructions dag-draft --task <task-id> --json
+loop-agent instructions task-artifacts --task <task-id> --json
+loop-agent instructions promotion --task <task-id> --json
+loop-agent instructions closeout --task <task-id> --json
+```
+
+`status` 是 agent 行动上下文入口，返回 `artifactPaths`、`runRefs`、`actionContext` 与 `nextActions`。`instructions` 在写入 source、DAG draft、task artifacts、promotion 或 closeout 前返回目标路径、依赖、模板、写策略与完成标准；blocked artifact 会列出 `missingDependencies`。
+
+### Promotion / closeout
+```bash
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`promote-run` 从 completed DAG facts 或 one-shot completed run evidence 生成 task `修改记录.md` / `验证结果.md`，不调用 LLM、不修改 completed run facts。`closeout task` 从 task artifacts 生成 `docs/progress/YYYY-MM-DD-<slug>.md`，验证证据不足时必须写明剩余风险。
+
+one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`。`cursor-prompt` 与 Pi `cursor` tool 会创建这类 run evidence；当前 `pi-prompt` 不创建 `.harness/runs/`。active 目录只应保留 live one-shot run，残留或 `.DS_Store` 等系统文件应清理。详见 `one-shot-runs.md`。
+
+### 运行任何 step 前：准备 source materials
+`new-task` 之后，至少添加 `需求.md`：
+```bash
+mkdir -p <repo-root>/.harness/tasks/<task-id>/source
+cat > <repo-root>/.harness/tasks/<task-id>/source/需求.md
+```
+然后写明需求、目标范围与约束。
+
+若 task 有硬约束（仅允许特定文件、禁止改动），另加：
+```bash
+cat > <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
+```
+
+### Feature-study workflow（参考代码 → 轻量实现）
+例如「分析参考仓库的一项功能，并在目标仓库实现轻量版本」：
+
+```bash
+loop-agent --repo-root /path/to/target-repo study init <task-id> "Title" \
+  --reference-repo codex:/Users/mac/go/src/codex \
+  --reference-doc plan:/Users/mac/plans/codex-goal-feature.md \
+  --reference-glob "codex-rs/**/goal*.rs"
+
+# 编辑 source/需求.md + source/执行约束.md，然后走 DAG 路径：
+loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent --repo-root <target-repo> dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <target-repo>
+```
+
+目标 repo 需有 `.harness/prompts/feature-study-analyze.md` 与 `feature-study-plan.md`（缺失时从 loop-agent 复制）。
+
+### Removed sequential workflow
+
+历史顺序式 `run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study` 已移除。新任务不要使用这些命令，也不要在 prompt、skill 或 docs 中把它们描述为 fallback。
+
+### Task goal lifecycle（compatibility-only / deprecated-candidate）
+```bash
+loop-agent goal set <task-id> "Objective text" [--token-budget <number|null>]
+loop-agent goal set <task-id> "Replacement objective" --force
+loop-agent goal get <task-id>
+loop-agent goal pause <task-id>
+loop-agent goal resume <task-id>
+loop-agent goal clear <task-id>
+```
+
+- 已有 goal 且 objective 不同时，替换须显式 `--force`。
+- `harness.json` 可用 `features.goals=false` 关闭此 surface。
+- `status` 现含 `goal`（`objective/status/tokenBudget/tokensUsed/timeUsedSeconds/continuationRuns`）、`verifyEnv`、`maxGoalContinuationsPerRun` 及可选 `flowHint`
+- 在 `source/需求.md` 用 `<!-- goal-scope -->` … `<!-- /goal-scope -->` 包裹仅 goal 验收项；范围外 `- [ ]` 不阻塞 goal 完成
+- `task.json`：`verifyEnv=clean`（默认）；goal continuation 需 verify 重试时用 `flow=loop`，避免盲目 implement 循环
+- continuation 是 runtime policy，不是普通用户消息：
+  - continuation prompts are legacy compatibility metadata under `.harness/prompts/`
+  - 触发时叠加 `.harness/prompts/objective_updated.md` 与 `.harness/prompts/budget_limit.md`
+  - 将渲染文本注入隐藏 `<goal_context>...</goal_context>` 片段供 step 执行
+  - 用于保持 continuation 行为一致，减少聊天式历史噪音
+  - preflight 含 state/mode guard + 启动前 goal 一致性复检
+
+### Agent DAG validation 与 execution
+```bash
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
+loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
+cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
+(npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # 存在 cursor node 时失败
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 执行前若存在 cursor node 则失败
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
+loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
+loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
+loop-agent dag run-task <task-id> --profile auto         # 推断 governanceProfile，经 workflowPolicy.dag.profileRouting 路由
+loop-agent dag run-task <task-id> --profile minimal      # 强制当前 minimal 路由（standard-dag）
+loop-agent dag run-task <task-id> --profile standard     # 强制 standard-dag
+loop-agent dag run-task <task-id> --profile reviewed     # 强制 review-gated DAG
+loop-agent dag run-task <task-id> --profile supervised   # 强制 supervised implementation DAG
+loop-agent dag run-task <task-id> --execute --cwd <repo-root>  # generate + validate + execute（先 narrow writeSet）
+loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>  # generate + validate + active dry-run snapshot
+loop-agent dag status --run-id <run-id>                  # 单次 run JSON 摘要（approvalFlow, healthIssues）
+loop-agent dag doctor                                    # 扫描 active/paused/completed runs；advisoryOnly health report
+loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--paused-latest] [--action <recovery-action>]  # derived per-node 聚合（只读）；JSON 锁定于 docs/templates/agent-dag-report.schema.json；--paused-latest 聚焦最新 paused run；playbook: docs/agent-dag-recovery-playbook.md
+loop-agent dag reconcile-tasks --glob '<pattern>'         # 仅报告的 task/run/artifact/verify drift audit
+loop-agent dag final-verification <task-id>               # 生成 closeout DAG，closeout artifact 后再 final verify
+loop-agent dag decision inspect --run-id <run-id> [--node-id <node-id>]   # dry-run envelope 重解析；除 run 缺失外 exit 0
+loop-agent dag decision validate --run-id <run-id> [--node-id <node-id>]  # 同上；envelope 无效时 exit 1
+loop-agent dag approve --run-id <run-id> --option <id>   # decision gate 人工 approve
+loop-agent dag reject --run-id <run-id> --reason "..."   # reject paused run
+loop-agent dag resume --run-id <run-id>                  # approve 后继续
+```
+
+**Decision gate（M3–M5）**：Pi node 上 `decisionGate.enabled: true` 启用 envelope 解析（M3 `record-only` 或 M4 `pause-on-human`）。M4 pause 后用 `dag approve/reject/resume/status/doctor` — 仅确定性 artifact，无新 `human`/`decision` executor。用 `dag report --paused-latest` 聚焦最新 paused run；`dag decision inspect|validate` 做 envelope dry-run（永不自动 resume/retry）。`browser` 仍 deferred。
+
+**In-flight DAG governance**：shell verify node 内用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`；run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
+
+- `dag validate` 做 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。
+- 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
+- read-only artifact-boundary 或 DAG 内 shell governance warning 应 fail fast 时用 `dag validate --strict-governance`。
+- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
+- operator 聚焦最新 paused run 用 `dag report --paused-latest`（等同 `--lifecycle paused --latest`；勿与显式 `--lifecycle` 并用）。
+- 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `docs/agent-dag-recovery-playbook.md`。
+- 只读扫描 `.harness/dag-runs/` 下所有 run 的生命周期 health issue 与建议 action 用 `dag doctor`（`advisoryOnly: true`；不 mutate facts）。
+- approve/resume 前用 `dag status --run-id <id>` 看单次 lifecycle、`approvalFlow`、`hasHumanApproval`。
+- task status、source/artifacts、DAG outcome、verification 记录可能 drift 时用 `dag reconcile-tasks --glob '<pattern>'`。默认仅报告；`--patch` 显式且不能伪造 verification evidence。
+- 大型 PRD closeout 用 `dag final-verification <task-id>` 生成确定性 DAG，final verification 在 closeout artifact 创建之后。
+- 从 run facts dry-run envelope 解析用 `dag decision inspect|validate`；`validate` 在无效 envelope 时 exit 1；永不自动 resume/retry。
+- Decision Gate prompt 可用 `buildDagDecisionGateEvidence()`（`src/workflows/dag/decision-evidence.ts`）做与 `dag report --json`、`docs/templates/agent-dag-report.schema.json` 对齐的只读摘要；不 mutate run state，不执行 retry/resume。
+- 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
+- task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选 standard / review-gated / supervised template 时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；强制 template family 用 `--profile minimal|standard|reviewed|supervised`。
+
+### Cursor worker lifecycle
+```bash
+loop-agent cursor-worker status   # enabled/running/child/entry path
+loop-agent cursor-worker stop     # SIGTERM worker 并清 parent state
+loop-agent cursor-worker ping     # 启动 worker 并跑短 execute smoke（之后 stop worker）
+```
+
+- DAG / `executeCursorTask({ useWorker: true })` 保持长驻 Cursor SDK child，避免 CLI exit hang。
+- Parent RPC timeout（`timeoutMs + 5s`）返回 `details.timeoutKind=rpc`，终止 worker（`SIGTERM`），defer SDK cancel（`cancelDeferred=true`，`cancelAttempted=false`）；下次 execute 启动新 worker。
+
+### 检查 task status
+```bash
+loop-agent status <task-id>
+```
+
+### Docs governance helpers
+```bash
+loop-agent docs audit
+loop-agent docs archive docs/exec-plans/active/<plan>.md
+loop-agent plan list
+loop-agent handoff check [task-id]
+loop-agent handoff coverage <task-id> [--json|--markdown]
+```
+
+- `docs audit`：扫描文档腐化风险，如 active/completed 漂移、失效链接、host-gap closeout
+- `docs archive`：将 active plan 迁入 completed，并自动重写常见 markdown 引用
+- `plan list`：列出当前 active plans 及其解析状态
+- `handoff check`：检查任务 source / artifacts / auto-commit scope 是否满足交付闭环
+- `handoff coverage`：从 `source/需求.md` 抽取 checklist / numbered / `REQ-*` 项并输出 coverage audit；未覆盖项 exit 1；`explicitly_out_of_scope` 不计为缺口
+
+### Pi runtime reuse benchmark / decision（无 live call）
+```bash
+loop-agent pi-reuse-benchmark \
+  --report docs/reports/<benchmark-report>.md \
+  --json
+
+loop-agent pi-reuse-benchmark \
+  --report docs/reports/<benchmark-report>.md \
+  --off-executor /path/to/off/executor.jsonl \
+  --on-executor /path/to/on/executor.jsonl \
+  --approval /path/to/approval.json \
+  --markdown
+```
+
+对已有 benchmark plan/report 文件及可选 `executor.jsonl` evidence 做确定性摘要。**不**跑 live Pi call、不创建 task、不改 `CODE_AGENT_PI_REUSE_RUNTIME`（默认仍为 `off`）。输出 `defer`、`maintain-opt-in` 或 `eligible-for-human-review` — 永不 default-on。
+
+### Loop convergence benchmark baseline（无 live call）
+```bash
+loop-agent loop-benchmark --markdown
+loop-agent loop-benchmark --markdown --output docs/reports/2026-06-30-loop-agent-loop-benchmark.md
+```
+
+生成 M0 deterministic baseline，对照 `single-repair`、`3-pass-convergence`、`3-pass-convergence+quota`。**不**跑 live Pi/Cursor call、不创建 task、不改 `convergence.enabled` 默认值。live dogfood 证据缺失时输出 `blocked` 并建议保持 opt-in。
+
+### Minimal spec spine audit
+```bash
+loop-agent spine audit <task-id> --json
+loop-agent spine audit <task-id> --markdown
+```
+
+检查 task 的 `source/需求.md`、`source/执行约束.md`、`task.json.allowedPaths` / `forbiddenPaths`、需求覆盖与 final verification command labels。`medium` / `large` task 的空 `allowedPaths`、allowed/forbidden overlap、未覆盖验收项、无 final verify command 都会让 audit 非零退出。
+
+### Knowledge curator proposal
+```bash
+loop-agent knowledge curate --markdown
+loop-agent knowledge curate --markdown --output docs/reports/<task-id>-learned-proposal.md
+```
+
+读取 `.harness/knowledge/patterns.jsonl` 中 completed convergence repair pattern，按 `failureClass + fixScope shape + invariant` 去重，生成 human-gated learned guidance proposal。命令只生成 proposal，不直接修改 `./skill/references/learned/*.md`；输出会先通过 skill safety audit。
+
+### 查看 duration statistics
+```bash
+loop-agent stats
+```
+
+### Worktree delegate / harvest（escape hatch）
+
+```bash
+loop-agent delegate <task-id> [--executor pi|cursor] [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run] [--no-auto-run]
+loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
+loop-agent worktree create|list|remove ...
+```
+
+用于 worktree 隔离的 cursor-direct 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-executor-usage.md`。
+
+> **Historical（已移除）**：`subagent list|start|wait|wakeup|attach|stop` 与 `dashboard` 已移除，不再出现在 CLI registry。

package/skills/loop-agent/references/harness-policy.md

@@ -0,0 +1,258 @@
+# Shared loop-agent Harness Policy
+
+This file is the canonical shared workflow policy for using `.` across repositories. Repo-local harness docs should only describe local adapters: where the runtime lives, which governance root to use, and which verification commands apply.
+
+## Canonical stance
+
+- **Agent DAG** is the default implementation workflow for medium/large, multi-file, architecture-sensitive, public-contract, CI/script, or harness-runtime work.
+- The historical sequential `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow has been removed. Do not present it as a fallback path.
+- **Long-running `loop`** is an outer state/evidence layer above Agent DAG. It records rounds, context compression, signals, and canonical refs; it must not replace DAG writeSet review, Decision Gate, or shell verification for complex work.
+- **Main session** orchestrates: choose one work chunk, prepare source materials, review DAG/writeSet, monitor failures, run final verification, and hand off.
+- **Executors** implement bounded work: Cursor writes within explicit paths, Pi performs read-only planning/review/diagnosis in DAG nodes, shell produces deterministic verification facts.
+- **Shell verification is the completion fact source**. LLM review or advisory output cannot replace command exit codes and archived evidence.
+
+## Command surface tiers
+
+| Tier | Default purpose | Commands |
+|---|---|---|
+| Primary | Normal autonomous implementation | `new-task` -> `dag run-task --profile auto` -> `dag validate --strict-models --strict-governance` -> `run-dag` |
+| Operator | Diagnose, recover, close out, inspect facts | `status`, `instructions`, `dag status`, `dag doctor`, `dag report`, `dag closeout-draft`, `dag reconcile-tasks`, `dag final-verification`, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark` |
+| Compatibility | Legacy task metadata and feature-study helpers | `goal`, `reference`, `study` |
+| Escape hatch | Isolated delegation, one-shot diagnosis or bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt`, `cursor-worker` |
+| Experimental | Long-running outer task state | `loop init|status|run|record-round|add-signal|closeout` |
+
+Prompt templates, README snippets, and task instructions should present Primary + Operator first. Compatibility and escape-hatch commands remain available, but must carry their downgrade/fallback meaning.
+
+## Entry selection decision tree
+
+```text
+Is this only status, diagnosis, recovery, or closeout?
+  yes -> Operator commands.
+  no  -> Does it need recoverable, reviewable, verifiable implementation state?
+           no  -> Use read-only pi-prompt for analysis, or a tiny main-session surgical patch only if obvious and immediately verifiable.
+           yes -> Agent DAG.
+```
+
+Use Agent DAG rather than broad one-shot execution when any of these signals apply:
+
+- loop-agent runtime, DAG schema, run facts, promotion/closeout, scripts/CI, public contract, or shared protocol is touched.
+- The change needs multiple files, multiple scouts, review gates, Decision Gate, repair flow, or shell gate.
+- `writeSet` is broad, multiple exclusive writers exist, or public interfaces / architecture boundaries change.
+- Requirement, architecture, credential, cost, deployment, security, or authority surface is unclear.
+- A failure repeats and needs recovery planning rather than blind retry.
+
+## Agent DAG path
+
+Minimum governed path:
+
+```bash
+loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
+# write <target-repo>/.harness/tasks/<task-id>/source/需求.md
+# write <target-repo>/.harness/tasks/<task-id>/source/执行约束.md
+
+loop-agent dag run-task <task-id> \
+  --profile auto \
+  --strict-models \
+  --output <temp-dir>/<task-id>-dag.json \
+  [--repo-root <target-repo>]
+
+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 <target-repo>
+```
+
+`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
+
+The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
+
+For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
+
+`<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
+
+Before execution, review `dag run-task` JSON / `reviewPacket`:
+
+- `profileRouting`: requested profile, selected profile/template, routing reasons.
+- `governanceProfile`: process, delivery, and code-change signals.
+- Writer nodes: `writePolicy`, `writeSet`, `allowedPaths`, `forbiddenPaths`, broad entries, forbidden overlaps.
+- Shell gates and verification commands.
+- Decision Gate mode (`record-only` vs `pause-on-human`).
+- Any placeholder, `**`, or repo-root writeSet that must be narrowed before execution.
+
+In-flight DAG shell checks should use the repo's active-run override when required (for example `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`). After the DAG is archived, run the repo check again without the in-flight override.
+
+On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Do not require WSL, `/tmp`, `which`, or other POSIX filesystem assumptions in loop-agent CLI behavior.
+
+## Task source materials
+
+Every handoff-ready task has:
+
+```text
+.harness/tasks/<task-id>/
+  task.json
+  source/
+    需求.md
+    执行约束.md
+```
+
+`需求.md` should state objective, scope, non-goals, acceptance criteria, and links to repo-local specs or plans.
+
+`执行约束.md` should state:
+
+- allowed paths
+- forbidden paths
+- current dirty workspace / protected user changes, if any
+- architecture boundaries and invariants
+- expected verification commands
+- acceptance criteria / failure conditions
+- whether DAG fallback is allowed, and the fallback reason if already known
+
+If source materials change after `spec`, `plan`, or DAG generation, regenerate or revalidate the plan/DAG before implementation.
+
+## Long-running loop policy
+
+`loop` is for long-running outer task memory: objective/context projection, round records, signals, derived events, verification summaries, and closeout draft. It is not a substitute for Agent DAG.
+
+Typical loop path for governed work:
+
+```bash
+loop-agent loop init <task-id>
+loop-agent loop run <task-id> --action dag
+# review DAG packet / writeSet / shell gates
+loop-agent loop run <task-id> --action dag --execute
+loop-agent loop run <task-id> --action shell-verify --command "<repo-check>"
+loop-agent loop run <task-id> --action pi-review
+loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
+loop-agent loop closeout <task-id>
+```
+
+Loop action rules:
+
+- `shell-verify` is deterministic; exit code determines the verification record.
+- `pi-review` is read-only; tools are limited to `read,grep,find,ls` and output is structured advisory evidence. Its structured JSON must include `findingSummary`, `failureCategory`, `nextHypothesis`, `recommendedAction`, `fixScope`, and `rootCause`; `recommendedAction` is exactly `implement_fix|replan|pause|done`.
+- `cursor-fix` is bounded write; it must read task `allowedPaths` / `forbiddenPaths`, reject empty `allowedPaths`, reject allowed/forbidden overlap, preserve unrelated files, and be followed by shell verification or review.
+- For `task.json.complexity = medium | large`, `cursor-fix` additionally requires either:
+  - a previous loop `dag` round, or
+  - an explicit `task.json.dagFallbackReason` explaining why DAG could not be used.
+- `loop run --auto` does not write by default. Auto `cursor-fix` requires `task.json.loopAutoWritePolicy="enabled"`, or `loopAutoWritePolicy="approval-required"` plus a pending approval signal or `--allow-cursor-fix`; write guards still fail closed and pause.
+- `loop closeout` must report workflow path: `dag`, `explicit-fallback`, `missing-dag-evidence`, or `micro-or-small`.
+- Medium/large closeout without DAG evidence and without `dagFallbackReason` must list that as a remaining risk.
+- `record-round --decision complete` is only a loop-state candidate; completion still requires shell verification, review verdict, and success-criteria coverage.
+
+## Supervised DAG convergence
+
+Supervised DAG convergence is optional and task-config driven:
+
+```json
+{
+  "convergence": {
+    "enabled": true,
+    "maxPasses": 3,
+    "stopOnHardVerifyPass": true,
+    "pauseOnRegression": true
+  }
+}
+```
+
+Rules:
+
+- Default remains single repair unless `convergence.enabled=true`; `HARNESS_DAG_CONVERGENCE=off` is the rollback switch.
+- The supervised process supervisor must emit first-line `VERDICT:` and a `REPAIR_ARTIFACT_JSON` fenced block. Repair prompts should consume artifact `failureClass`, `rootCause`, `fixScope`, and `invariant` first; raw logs are fallback evidence only when the artifact allows it.
+- On retryable `hard-verify-shell` failure before `maxPasses`, preserve current pass evidence under `convergence/pass-N/`, reset the process-supervisor/process-gate/repair/hard-verify segment plus blocked downstream nodes, and re-enter the existing DAG rank execution loop.
+- Do not retry write guards, timeout/spawn/auth failures, or human-gate failures.
+- Pause instead of retrying when conservative regression signals appear, such as a lower shell success count.
+- `dag report --json` and markdown must expose `convergence.passHistory`.
+- Final completion authority remains full shell verification; quota/focused commands are intermediate cost controls only.
+
+## Structured repair, spine audit, and curator gates
+
+- `shell.repairArtifactGate.fromNodeId` validates the upstream supervisor artifact before repair. Missing/invalid JSON, missing request-revision `fixScope`, or scope outside the downstream repair writer allowedPaths/writeSet fails closed.
+- `spine audit <task-id>` is the deterministic minimal spec spine checker for task source, ownership paths, requirement coverage, and final verification commands.
+- `dag validate --strict-governance --spine-task <task-id>` may consume the same spine audit as part of strict validation.
+- `knowledge curate` reads completed convergence patterns and writes only human-gated proposal Markdown after skill safety preflight.
+
+## SePO-lite prompt evolution
+
+- Learned prompt deltas are human-gated proposals; they must be reviewed before becoming reusable guidance.
+- Prompt deltas are Markdown-only process guidance; they must not include shell commands, credential handling, tool permission expansion, or completion-authority bypass.
+- Accepted learned guidance lives under `./skill/references/learned/<repo>.md` or `default.md`.
+- DAG implementer prompts that already request `loop-agent` may inline at most three human-gated learned Markdown sections.
+- Learned guidance is advisory and never replaces writeSet governance, Decision Gate policy, or shell verification.
+
+## Sidecar interventions
+
+`pi-prompt` and `cursor-prompt` are sidecar interventions, not workflow state.
+
+Use `pi-prompt` for short read-only planning, log explanation, or failure diagnosis. When read-only, pass read-only tools and say not to edit files:
+
+```bash
+loop-agent pi-prompt \
+  --cwd <repo-root> \
+  --tools read,grep,find,ls \
+  --timeout 2400000 \
+  "Read the task source and diagnose the failure. Do not edit files."
+```
+
+Use `cursor-prompt` for bounded multi-file diagnosis or small repair only when the prompt includes:
+
+- task id
+- exact objective
+- allowed paths
+- forbidden paths
+- hard constraints
+- expected verification
+- instruction to preserve unrelated files
+
+Sidecar output is advisory. If it must become task evidence, promote or summarize it through loop-agent run/task artifacts; do not manually mutate completed DAG or one-shot run facts.
+
+## Model and executor boundaries
+
+- Agent DAG uses DAG JSON `executorModels` plus node `executor` / `complexity`; do not infer DAG models from repo `harness.json.models`.
+- DAG `shell` and `static` nodes do not use models.
+- Historical step models under `harness.json.models.<step>` are legacy metadata, not routing for new DAG work.
+- `pi-prompt` / `cursor-prompt` models come from CLI flags or runtime defaults and must be selected per intervention.
+- Pi DAG nodes are read-only planning/review/diagnosis by default.
+- Cursor nodes are bounded writers and must have explicit write scope.
+- Shell nodes produce deterministic verification facts and gates.
+
+## Artifacts and facts boundary
+
+- `.harness/tasks/<task-id>/` is task runtime state.
+- `.harness/tasks/<task-id>/loop/` is loop runtime projection; it does not replace task source or repo specs.
+- `.harness/dag-runs/{active,paused,completed}/<run-id>/` is DAG run fact storage. Completed facts are read-only.
+- `.harness/runs/{active,completed,failed}/<run-id>/` is one-shot Pi/Cursor evidence. Completed/failed facts are read-only.
+- Root `artifacts/` is legacy/current-work summary space, not a DAG read-only scratchpad and not default handoff for new DAG work.
+- Long-term conclusions belong in repo governance docs, progress, reports, decisions, tests, or scripts.
+
+Do not submit runtime histories from `.harness/dag-runs/`, `.harness/runs/`, or `.harness/cache/` unless a task explicitly promotes a trimmed report into repo governance docs.
+
+## Baseline, dirty workspace, and verification
+
+Before complex implementation:
+
+1. Check current directory and target repo.
+2. Read repo entrypoints (`README`, `AGENTS`, `harness.json`, governance index).
+3. Capture minimal baseline verification for the affected area.
+4. If the workspace is dirty, choose one:
+   - isolated worktree, or
+   - explicit user confirmation to work in the current workspace and preserve/possibly include existing changes.
+5. Record known baseline failures with enough detail to distinguish pre-existing failures from task regressions.
+
+Verification should be selected from the target repo's verification matrix. For cross-repo documentation refactors, run checks in each affected repo.
+
+## Handoff requirements
+
+Every task handoff should answer:
+
+1. What changed and why.
+2. Which workflow path was used: DAG, sidecar, or main-session surgical patch.
+3. If downgraded from DAG, the explicit reason and evidence.
+4. Executors used and their boundaries.
+5. Verification commands run and results.
+6. DAG / one-shot / loop refs, if any.
+7. Remaining risks and follow-up tasks.
+8. Whether new rules should be promoted to docs, tests, scripts, or shared skill references.