@tea-agent/loop-agent 0.10.0 → 0.11.0

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

@@ -1,28 +1,28 @@
 # Agent DAG Hybrid Workflow（`run-dag` / `dag init-hybrid`）
 
-创建或执行 loop-agent 工作的首选 Agent DAG path 时使用本文：Level 2 Agent DAG orchestration、Pi read-only + Pi `toolProfile: "write"` bounded execution、optional Cursor backend、write policy、DAG template、task-to-DAG 生成，或基于 governance-profile 的 template 选择。
+创建或执行 loop-agent 工作的首选 Agent DAG path 时使用本文：Level 2 Agent DAG orchestration、Pi read-only + Pi `toolProfile: "write"` bounded execution、Pi-only writers、write policy、DAG template、task-to-DAG 生成，或基于 governance-profile 的 template 选择。
 
 ### DAG workflow 优先级
 
 `harness.json.workflowPolicy` 现声明 Agent DAG 为首选 implementation workflow：
 
 - `defaultImplementationWorkflow=agent-dag`
-- `dag.defaultEntry=dag run-task`
-- `dag.outputLanguage=zh-CN`；未配置时也默认中文，显式设为 `en` 可切换英文
-- `dag.profileRouting`：`minimal|standard -> standard-dag`，`reviewed -> review-gated-dag`，`supervised -> supervised-implementation`
+- `dag.defaultEntry=dag run-task`
+- `dag.outputLanguage=zh-CN`；未配置时也默认中文，显式设为 `en` 可切换英文
+- `dag.profileRouting`：`minimal|standard -> standard-dag`，`reviewed -> review-gated-dag`，`supervised -> supervised-implementation`
 - `humanGatePolicy.defaultMode=record-only`；需求不清、架构/公共契约风险、凭据/费用/部署风险、重复 gate failure 或高风险决策时升级人工介入
 
-此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
+此 policy 驱动 `dag run-task --profile auto`：CLI 仍要求显式 `dag run-task`、`dag validate`、`run-dag`，但 `--profile auto` 在确定性 candidate `governanceProfile` 推断后应用 `workflowPolicy.dag.profileRouting`。生成器还会把 `outputLanguage` 写入 DagSpec，runner 在每个 Pi/Cursor 节点 prompt 中注入语言规则；代码、命令、路径、JSON 字段与 gate token 保持原样。`humanGatePolicy` 是默认人机边界声明；真实暂停仍由 DAG 节点的 `decisionGate.mode: "pause-on-human"` 与 decision envelope 触发。无 profile 的 `dag run-task <task-id>` 仍为 standard-compatible，供 legacy/review workflow。
 
 ### DAG workflow 层级
 
 | 优先级 | 入口 | 使用场景 |
 |-------|-------|----------|
 | **Primary / Level 3** | `dag run-task --profile auto` / `dag init-hybrid`（已实现） | 从 task `source/` 自动生成 hybrid DAG；`--profile auto` 路由 standard / review-gated / supervised template；无 profile `run-task` 默认为 standard-compatible generate+validate only |
-| **Primary / Level 2** | `run-dag --dag <path>` | 跨 Cursor + Pi + shell executor 执行 Agent DAG orchestration |
+| **Primary / Level 2** | `run-dag --dag <path>` | 跨 Pi + shell + static executor 执行 Agent DAG orchestration |
 历史顺序式 `run analyze|plan|implement|verify|auto|loop|continue` 已移除。trivial one-line 修正时，记录的 main-session surgical patch 仍可能比建 DAG 更省，但它不是第二套 workflow runtime。
 
-**心智模型**：`run-dag` 是 `.` 内自编的 Agent DAG orchestration；Cursor SDK 仅是 `executor: "cursor"` node 的 leaf executor。Cookbook 式 Cursor DAG 示例同样是基于 Cursor SDK local subagent 的 custom DAG runner，不是 Cursor 原生 DAG API。仅可选地借鉴其 observer/streaming/cancel 模式作为 derived feature；不要替换本 repo 的 hybrid schema、`executorModels`、Pi/shell/static executor 或 `.harness/dag-runs` facts。
+**心智模型**：`run-dag` 是 loop-agent 内自编的 Agent DAG orchestration；受治理 Agent leaf executor 只有 Pi。`cursor-prompt` 是独立 sidecar，不是 DAG node executor。不要把 Cursor 重新引入 hybrid schema / `executorModels` / writer 选择。
 
 ### Level 2 Agent DAG hybrid（`run-dag`）
 
@@ -31,10 +31,8 @@ cp examples/hybrid-loop-agent-dag.json <temp-dir>/hybrid-dag.json
 loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation + ranks；无 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（如 read-only artifact drift）时失败
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # offline/CI/no-key 显式 no-Cursor；存在 cursor node 时失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行（若包含 cursor node 则需 CURSOR_API_KEY）
-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（无需 CURSOR_API_KEY）
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Pi/shell/static DAG
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas
 ```
 
 `<temp-dir>` 表示平台原生临时目录；实际命令中 macOS 与 Windows 都使用本机路径。`/` 只作为 repo refs、JSON/Markdown evidence refs 和 glob 约定的稳定分隔符。
@@ -44,7 +42,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 **v2 字段**（均可选；缺失时行为同 v1）：
 
 - 顶层：`objective`、`successCriteria`、`globalConstraints`、`defaults`、`skillsByRole`、`executorModels`
-- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`cursor` | `pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
+- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
 
 **Model 生成 DAG 的 template 卫生**：
 
@@ -54,14 +52,14 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - 输出独立时优先 same-rank parallel read-only scout（`scout-src`、`scout-tests` 等），而非 serial scout chain。
 - 仅当 child 真正需要 upstream output 时加 `depends_on`；review 时质疑 single-chain topology。
 - `exclusive` implementer node 需 narrow、disjoint 的 `writeSet` path；勿用 `**` 或 repo root。
-- 默认 no-Cursor DAG 使用 `pi` read-only scouts/reviewers 与 `toolProfile: "write"` exclusive implementer；Cursor 是显式启用的可选 scout / writer backend。
+- 固定 Pi-only DAG：`pi` read-only scouts/reviewers 与 `toolProfile: "write"` exclusive implementer（`implement-pi` / `repair-pi`）。
 - model routing 用 `executorModels`；勿用 `defaults.model` 或 legacy 顶层 `models`。
 
 **运维 warning**：
 
-- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。no-Cursor 环境用 `dag validate --dag <path> --forbid-executor cursor` 或 `run-dag --no-cursor` 捕获显式 Cursor 节点；默认生成 DAG 应使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
+- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
 - **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 强制对应 template family（当前 policy 下 minimal/standard 路由到 `standard-dag`），高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
-- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels` 覆盖 `cursor` / `pi` 的 model 名；不选 provider。默认 routing：Cursor 各 complexity 用 `composer-2.5`；Pi read-only 与 Pi write profile 共用 LOW=`wizard-local/gpt-5.3-codex-spark`、MED=`wizard-local/glm-5.2`、HIGH=`wizard-local/gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
+- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖 model 名；不选 provider。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
 - **Active visibility**：真实 `run-dag` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
 - **可选 Canvas**：传 `--canvas-path <abs-path>` 或 `--canvas <name>` 输出 derived `.canvas.tsx` live view。省略 flag 行为不变。`--init-only` + Canvas 无需 `CURSOR_API_KEY`。
 
@@ -102,7 +100,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 | `soft-verify-shell` | supervision 前归档 focused test exit code |
 | `process-supervisor-pi` | read-only audit coverage、boundary drift、verify gap、repair scope；应 prominently 输出 `VERDICT: pass` 或 `VERDICT: request-revision` |
 | `process-gate-shell` | supervisor node JSON 上 runtime `shell.verdictGate`（仅 `pass` 或 `request-revision`） |
-| `repair-pi` / optional `repair-cursor` | supervisor 请求 revision 时在 repair `writeSet` 内 bounded exclusive fix |
+| `repair-pi` | supervisor 请求 revision 时在 repair `writeSet` 内 bounded exclusive fix |
 | `hard-verify-shell` | lint/typecheck + `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 check-repo.sh` fact |
 | `authority-surface-audit-pi` + `authority-surface-gate-shell` | 可选 permission/state/tool-exposure audit；仅 authority signal 或显式 `authority-surface-audit` marker 时插入；gate 仅接受 `VERDICT: pass` |
 | `review-pi` + `review-gate-shell` | Critical/Important → `request-revision`；node JSON 上 `shell.verdictGate` block，除非 extracted verdict 行为 `VERDICT: pass` |
@@ -124,7 +122,6 @@ loop-agent dag run-task <task-id> --profile standard
 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> --strict-models                              # 非 canonical executorModels 时失败
-loop-agent dag run-task <task-id> --no-cursor                                  # 显式 no-Cursor 校验；generated cursor node 时失败
 loop-agent dag run-task <task-id> --execute --cwd <repo-root>                        # 要求 narrowed implement writeSet
 loop-agent dag run-task <task-id> --dry-run --cwd <repo-root>                        # active snapshot 于 .harness/dag-runs/active/
 loop-agent dag run-task <task-id> --init-only --cwd <repo-root>                      # pending active snapshot，不执行 node
@@ -212,6 +209,6 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | 10 | writeSet planning | scout 应列出链接的 `./skill/references/**` 为 **writeSet expansion candidates**（P2：遗漏链接 skill ref 迫使 main-session patch） |
 | 11 | Evidence summary | `evidence-summary-shell` / leading `EVIDENCE:` 行是 **practice convention**，非 runtime executor、schema field 或 parser |
 | 12 | Featureization | 除非 repeated real-run failure 证明 checklist guidance 不够，勿加 runtime/schema/validator/CLI/executor feature |
-| 13 | writeSet / writer backend | `exclusive` node 用 narrow、disjoint path；无 `**`；默认用 Pi write profile，仅在显式启用且 task-fit 时用 Cursor |
+| 13 | writeSet / writer backend | `exclusive` node 用 narrow、disjoint path；无 `**`；固定用 Pi write profile |
 | 14 | Placeholders | 执行前将 `REPLACE/WITH/...` 换为具体 path |
 | 15 | Governance | in-flight shell：`HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`；archive 后：裸 `bash scripts/check-repo.sh` |

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

@@ -9,11 +9,10 @@ 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 cursor-fix --model composer-2.5
 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 --allow-cursor-fix
+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> \
@@ -36,15 +35,14 @@ loop-agent loop record-round <task-id> \
 
 - `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 cursor-fix` 必须读取 task `allowedPaths` / `forbiddenPaths`，拒绝空 allowedPaths 或 allowed/forbidden overlap；对 `complexity=medium|large` 的任务，还必须已有 loop `dag` round 证据，或在 `task.json.dagFallbackReason` 中写明 DAG runtime fallback 原因。调用现有 Cursor bounded executor，并把 one-shot evidence 归档到 `.harness/runs/completed|failed/`。
-- `cursor-fix` 只表示 bounded write round 已执行；它不会把 loop 标记 complete，下一步必须进入 `shell-verify` 或 review。
+- 自动写入只能通过 `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，不自动触发 Cursor 写入。
-- 自动 `cursor-fix` 必须显式 opt-in：`task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal / `--allow-cursor-fix`。即使 opt-in，也必须通过 `allowedPaths`/`forbiddenPaths`/DAG evidence guard；guard 失败会 pause，不会绕过写入边界。
+- `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

package/skills/loop-agent/references/multi-worktree.md

@@ -17,12 +17,12 @@
 ### 核心命令
 
 ```bash
-loop-agent delegate <task-id> [--executor pi|cursor] [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run] [--no-auto-run]
+loop-agent delegate <task-id> [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run]
 loop-agent harvest <task-id> [--squash] [--no-archive] [--keep-worktree]
 loop-agent worktree list
 ```
 
-`delegate` 是一步原子操作：校验 `task.json` + `source/需求.md` + `source/执行约束.md` → 在 branch `task/<task-id>` 上创建 `git worktree .worktrees/<task-id>` → 同步 `source/` 与 `task.json` 到 worktree → 相对 symlink `./node_modules` → cursor 默认 in-process SDK direct；Pi `--auto-run` 已移除并会提示 DAG 路径。
+`delegate` 是一步原子操作：校验 `task.json` + `source/需求.md` + `source/执行约束.md` → 在 branch `task/<task-id>` 上创建 `git worktree .worktrees/<task-id>` → 同步 `source/` 与 `task.json` 到 worktree → 相对 symlink `./node_modules`。默认只准备 worktree；显式 `--auto-run` 才在其中生成、严格校验并执行 Pi-only DAG。
 
 `harvest` 是对称 closeout：仅当 `task.status === "completed"` 才运行，然后 merge（默认 `--no-ff`，或 `--squash`），将 `artifacts/`、`logs/`、`.workflow_state.json` 归档回主 repo，移除 worktree + branch。
 
@@ -37,8 +37,8 @@ loop-agent worktree list
 ### 生命周期概览
 
 ```
-delegate → executor 跑 spec/implement/verify → completed → harvest → archive + cleanup
-                                          ↘ failed   → worktree 内排障（不 harvest）
+delegate --auto-run → Pi DAG 跑 contract/scout/plan/implement/verify → completed → harvest → archive + cleanup
+                                                             ↘ failed   → worktree 内排障（不 harvest）
 ```
 
 ### 失败处理
@@ -49,6 +49,6 @@ delegate → executor 跑 spec/implement/verify → completed → harvest → ar
 
 ### 与 Agent DAG 的关系
 
-Agent DAG 是默认 autonomous path；`delegate`/`harvest` 是 cursor-direct 的 worktree escape hatch。多 task 并行时，每个 task 独立 `delegate`，完成后分别 `harvest`。
+Agent DAG 是默认 autonomous path；`delegate`/`harvest` 提供 worktree 隔离与收口，`--auto-run` 仍只运行 Pi-only DAG。需要人工 Cursor 介入时使用独立的 `cursor-prompt` sidecar，不进入 delegate 或 DAG runtime。多 task 并行时，每个 task 独立 `delegate`，完成后分别 `harvest`。
 
-详见 `docs/cursor-executor-usage.md` 与 `docs/loop-agent-harness.md`。
+详见 `docs/cursor-prompt-sidecar.md` 与 `docs/loop-agent-harness.md`。

package/skills/loop-agent/references/orchestrator-and-interventions.md

@@ -8,7 +8,7 @@
 
 `harness.json.workflowPolicy` 的 repo 级 policy 将 Agent DAG 作为 autonomous 与 harness-governed work 的 implementation workflow。历史顺序式 `run ...` workflow 已移除。
 
-main session 是 decision-maker 与 scheduler，不是默认 implementer。其稀缺 context 应留给 objective 对齐、DAG review、failure triage、executor 选择、verification review 与 handoff。长时 implementation 应委派给 Agent DAG node、Cursor、Pi、shell 或 worktree delegate。
+main session 是 decision-maker 与 scheduler，不是默认 implementer。其稀缺 context 应留给 objective 对齐、DAG review、failure triage、executor 选择、verification review 与 handoff。长时 implementation 应委派给 Pi-only Agent DAG node、shell verification 或 worktree delegate；Cursor 仅作为显式 one-shot sidecar。
 
 这不是绝对禁止 edit。main-session 手动 edit 仅允许作为有 verification 与 artifact 记录的 bounded surgical patch。
 
@@ -18,7 +18,7 @@ main session 是 decision-maker 与 scheduler，不是默认 implementer。其
 |---|---|---|
 | Main session | Objective、contract、DAG review、routing、failure triage、approve/reject/resume、handoff | 成为长时 coder |
 | Agent DAG runner | 可恢复 multi-node orchestration、rank-parallel execution、write policy、run artifacts | 不更新 DAG/source 的 ad-hoc replanning |
-| Cursor executor / prompt | Codebase-indexed search、multi-file implementation、bounded refactor/fix | 无 narrow `writeSet` / path scope 的宽写入 |
+| Cursor one-shot prompt | 有界诊断、人工介入的小修复或 executor 调试 | 作为 DAG executor、自动写入路径或无 path scope 的宽写入 |
 | Pi executor / prompt | Fast reasoning、read-only scouting、planning、review、decision-envelope advice | 充当 hidden state source |
 | Shell executor | 确定性事实：tests、lint、typecheck、build、governance checks | 智能 repair |
 | Human gate | Product、architecture、risk、permission 决策 | 常规 implementation debugging |
@@ -130,7 +130,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 
 坏例子：
 
-- 手工按 `artifacts/实现计划.md` implement feature。
+- 手工按 task `artifacts/实现计划.md` 或根 `artifacts/` 实现功能（应走 DAG plan/implement 节点或 exec-plan）。
 - 不委派就修大量 test failure。
 - 改 API/contract 语义。
 - refactor 子系统。

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

@@ -62,20 +62,23 @@ pi -p --no-session --no-context-files --no-skills --tools subagent "Reply with e
 
 **Agents**（`.pi/agents/`）
 
-| Agent | Role | Model |
-|-------|------|-------|
-| `loop-agent-scout` | Read-only recon：code、tests、docs、governance | `cursor/composer-2.5` |
-| `loop-agent-planner` | Implementation planning：最小可执行 plan | `cursor/composer-2.5` |
-| `loop-agent-reviewer` | Strict review：scope drift、verification gap、contract break | `cursor/composer-2.5` |
-| `loop-agent-worker` | General execution：bounded implementation 与 fix | `cursor/composer-2.5` |
+| Agent | Role | 对应阶段 |
+|-------|------|----------|
+| `loop-agent-scout` | 只读侦察：code、tests、docs、governance | Scout |
+| `loop-agent-planner` | 最小可执行计划；强调验证与回退 | Plan |
+| `loop-agent-reviewer` | 严格审查：范围漂移、验证缺口、契约破坏 | Verify / Review |
+| `loop-agent-worker` | 有界实现与修补 | Implement |
 
-**Prompt Templates**（`.pi/prompts/`）：输入 `/loop-agent-*` 调用
+另有通用 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` | scout → planner chain |
-| `loop-agent-analyze-wide` | 3 parallel scouts → analysis |
-| `loop-agent-review-only` | 独立 review plan/implementation/verification |
-| `loop-agent-implement-and-review` | worker → reviewer → worker loop |
+| `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/task-workflow.md

@@ -77,7 +77,7 @@ loop-agent --repo-root /path/to/target-repo <command>
 
 ## Verification
 
-完成声明必须来自新鲜验证证据。按目标 repo 的 `docs/verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：
+完成声明必须来自新鲜验证证据。按目标 repo 的 `harness.json.governanceRoot` 下 `verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：
 
 ```bash
 npm run typecheck

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **Check for an existing global directory:**
+   ```bash
+   project=$(basename "$(git rev-parse --show-toplevel)")
+   ls -d ~/.worktrees 2>/dev/null
+   ```
+   If found, use it.
+
+4. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+Global directories (`~/.worktrees/`) need no verification.
+
+#### Create the Worktree
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+
+# Determine path based on chosen location
+# For project-local: path="$LOCATION/$BRANCH_NAME"
+# For global: path="~/.worktrees/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+
+## Step 3: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 4: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```bash
+# Use project-appropriate command
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Global path exists | Use it (backward compat) |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Fighting the harness
+
+- **Problem:** Using `git worktree add` when the platform already provides isolation
+- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+
+### Skipping detection
+
+- **Problem:** Creating a nested worktree inside an existing one
+- **Fix:** Always run Step 0 before creating anything
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > global legacy > instruction file > default
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+## Red Flags
+
+**Never:**
+- Create a worktree when Step 0 detects existing isolation
+- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
+- Skip Step 1a by jumping straight to Step 1b's git commands
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+
+**Always:**
+- Run Step 0 detection first
+- Prefer native tools over git fallback
+- Follow directory priority: existing > global legacy > instruction file > default
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline

package/dist/commands/cursor-worker.js

@@ -1,43 +0,0 @@
-import { executeCursorTaskViaWorker, getCursorWorkerEntryPath, isCursorWorkerChild, isCursorWorkerEnabled, isCursorWorkerRunning, stopCursorWorker, } from '../executors/cursor-worker-client.js';
-export function parseCursorWorkerArgs(args) {
-    const action = args[0];
-    if (action === 'status' || action === 'stop' || action === 'ping') {
-        return { action };
-    }
-    throw new Error('usage: cursor-worker <status|stop|ping>');
-}
-export async function runCursorWorker(repoRoot, rawArgs) {
-    const { action } = parseCursorWorkerArgs(rawArgs);
-    if (action === 'status') {
-        console.log(JSON.stringify({
-            enabled: isCursorWorkerEnabled(),
-            running: isCursorWorkerRunning(),
-            child: isCursorWorkerChild(),
-            entry: getCursorWorkerEntryPath(),
-            repoRoot,
-        }, null, 2));
-        return;
-    }
-    if (action === 'stop') {
-        await stopCursorWorker();
-        console.log('cursor worker stopped');
-        return;
-    }
-    if (action === 'ping') {
-        if (!isCursorWorkerEnabled()) {
-            console.error('Set CURSOR_USE_WORKER=1 to enable the worker path.');
-        }
-        try {
-            const result = await executeCursorTaskViaWorker({
-                task: 'Reply with exactly: WORKER_PING_OK',
-                cwd: repoRoot,
-                model: 'default',
-                timeoutMs: 120_000,
-            });
-            console.log(JSON.stringify({ ok: result.ok, stdout: result.stdout.trim() }, null, 2));
-        }
-        finally {
-            await stopCursorWorker();
-        }
-    }
-}

package/dist/cursor-worker-entry.js

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-/**
- * Long-lived Cursor SDK worker (NDJSON on stdin/stdout).
- * Spawned by cursor-worker-client when CURSOR_USE_WORKER=1.
- */
-import { runCursorWorkerOnStreams } from './executors/cursor-worker-server.js';
-process.env.CURSOR_WORKER_CHILD = '1';
-await runCursorWorkerOnStreams(process.stdin, process.stdout);

package/dist/executors/cursor-artifacts.js

@@ -1,33 +0,0 @@
-const MODIFY_LOG_MARKERS = ['修改摘要', '修改文件', '验证', '风险'];
-const VERIFY_RESULT_MARKERS = ['命令', 'exit', 'pass', 'fail', '未运行'];
-export function validateCursorModifyLog(content) {
-    const trimmed = content.trim();
-    if (!trimmed)
-        return ['修改记录.md is empty'];
-    if (!trimmed.includes('# 修改记录'))
-        return ['修改记录.md missing heading: # 修改记录'];
-    const missing = MODIFY_LOG_MARKERS.filter((marker) => !trimmed.includes(marker));
-    return missing.map((marker) => `修改记录.md missing section marker: ${marker}`);
-}
-export function validateCursorVerifyResult(content) {
-    const trimmed = content.trim();
-    if (!trimmed)
-        return ['验证结果.md is empty'];
-    if (!trimmed.includes('# 验证结果'))
-        return ['验证结果.md missing heading: # 验证结果'];
-    const hasCommandMarker = VERIFY_RESULT_MARKERS.some((marker) => trimmed.toLowerCase().includes(marker.toLowerCase()));
-    if (!hasCommandMarker) {
-        return ['验证结果.md missing verification command / exit / pass-fail evidence'];
-    }
-    return [];
-}
-export function validateCursorArtifacts(modifyLog, verifyResult) {
-    return [
-        ...validateCursorModifyLog(modifyLog),
-        ...validateCursorVerifyResult(verifyResult),
-    ];
-}
-export function isEmptyArtifactTemplate(content, templateMarker) {
-    const trimmed = content.trim();
-    return trimmed.includes(templateMarker) && trimmed.split('\n').filter((line) => line.trim().length > 0).length <= 3;
-}

package/dist/executors/cursor-execution-log.js

@@ -1,81 +0,0 @@
-import { access, appendFile, mkdir } from 'node:fs/promises';
-import path from 'node:path';
-import { buildCursorPrompt, buildRedactedExecutorRecord, } from './cursor-executor.js';
-import { appendExecutorRecord } from '../shared/logger.js';
-export function resolveDelegateExecutionMode(executor) {
-    if (executor === 'pi')
-        return 'pi-worktree';
-    if (executor === 'cursor')
-        return 'direct';
-    return undefined;
-}
-export function buildCursorExecutionLogRecord(input) {
-    const base = buildRedactedExecutorRecord({
-        executor: 'cursor',
-        model: input.model,
-        durationMs: input.result.durationMs,
-        failureCategory: input.result.failureCategory,
-        ok: input.result.ok,
-        status: input.result.status,
-        prompt: input.prompt,
-        result: input.result,
-        apiKey: input.apiKey,
-    });
-    return {
-        ...base,
-        channel: input.context.channel,
-        executionMode: input.context.executionMode,
-        cwd: input.context.cwd,
-        taskId: input.context.taskId,
-        dagRunId: input.context.dagRunId,
-        dagNodeId: input.context.dagNodeId,
-        recordedAt: new Date().toISOString(),
-    };
-}
-export async function persistCursorExecutionLog(logsDir, record, fileName = 'executor.jsonl') {
-    await mkdir(logsDir, { recursive: true });
-    await appendFile(path.join(logsDir, fileName), `${JSON.stringify(record)}\n`, 'utf-8');
-}
-/** Append a unified record to `<taskDir>/logs/executor.jsonl`. */
-export async function appendCursorExecutionLog(taskDir, record) {
-    await appendExecutorRecord(taskDir, record);
-}
-export async function persistCursorToolExecution(cwd, input) {
-    try {
-        await access(path.join(cwd, '.harness'));
-    }
-    catch {
-        return;
-    }
-    const cacheDir = path.join(cwd, '.harness', 'cache');
-    const record = buildCursorExecutionLogRecord({
-        context: { channel: 'tool', cwd },
-        model: input.model,
-        prompt: buildCursorPrompt(input.task),
-        result: input.result,
-        apiKey: input.apiKey,
-    });
-    await persistCursorExecutionLog(cacheDir, record, 'cursor-executions.jsonl');
-}
-export function formatCursorFailureMessage(category) {
-    switch (category) {
-        case 'missing-api-key':
-            return 'CURSOR_API_KEY is not set.';
-        case 'auth':
-            return 'Cursor API authentication failed.';
-        case 'network':
-            return 'Cursor API network error.';
-        case 'timeout':
-            return 'Cursor execution timed out.';
-        case 'invalid-output':
-            return 'Cursor output or artifacts are invalid.';
-        case 'path-violation':
-            return 'Cursor task violated path boundaries.';
-        case 'nonzero-exit':
-            return 'Cursor agent did not complete successfully.';
-        case 'success':
-            return 'OK';
-        default:
-            return 'Cursor execution failed.';
-    }
-}