@tea-agent/loop-agent 0.1.0

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

@@ -0,0 +1,216 @@
+# 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 选择。
+
+### DAG workflow 优先级
+
+`harness.json.workflowPolicy` 现声明 Agent DAG 为首选 implementation workflow：
+
+- `defaultImplementationWorkflow=agent-dag`
+- `dag.defaultEntry=dag run-task`
+- `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`。`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 |
+历史顺序式 `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。
+
+### Level 2 Agent DAG hybrid（`run-dag`）
+
+```bash
+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）
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中 macOS 与 Windows 都使用本机路径。`/` 只作为 repo refs、JSON/Markdown evidence refs 和 glob 约定的稳定分隔符。
+
+完整 schema 与语义：`docs/agent-dag-runner.md`。Workflow 概览：`docs/loop-agent-harness.md`。
+
+**v2 字段**（均可选；缺失时行为同 v1）：
+
+- 顶层：`objective`、`successCriteria`、`globalConstraints`、`defaults`、`skillsByRole`、`executorModels`
+- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`cursor` | `pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
+
+**Model 生成 DAG 的 template 卫生**：
+
+- 执行前将所有 `REPLACE/WITH/...` placeholder 换为具体 repo path。
+- 每个 task 应显式声明 `executor`；`defaults.executor` 仅 schema，非 runtime fallback。
+- 每个 task 应声明 `outputContract`；read-only node 应含 `forbiddenPaths`（至少 `[".harness/**", "artifacts/**"]`）；exclusive write node 也应 forbid `artifacts/**`，除非 legacy root artifacts 显式在 `writeSet` 中并记录迁移计划。
+- 输出独立时优先 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。
+- 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`。
+- **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`。
+- **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`。
+
+- **Shell node**：`executor: "shell"` 串行跑确定性 `shell.commands`，每 command 有 `timeoutMs`；非零 exit / timeout 标 node `ERROR` 并将 command output 归档到 node result 目录。用于 verification fact，非 code repair。
+- **Pi node**：`executor: "pi"` 默认仅用 read-only tool（当前 DAG Pi executor 中 `read`、`grep`、`find`、`ls`），返回 Markdown 结论供 downstream node。声明 `toolProfile: "write"` 后同一个 Pi executor 使用 writer tools 并在执行后跑 write guard；必须配合 `writePolicy=exclusive`、`allowedPaths`、`forbiddenPaths`、`writeSet`。
+- **Root `artifacts/` boundary**：root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy / explicit-write 摘要，不是 Agent DAG read-only scratchpad，也不是新工作流默认 handoff。read-only DAG node 须在 node output 返回发现；runner-owned node artifacts 于 `.harness/dag-runs/<run-id>/` 是 per-run source of truth。
+- **Upstream output artifacts**：直接 `depends_on` 上游 stdout 超过 2000 字符时，runner 写 `<runDir>/<node-id>/stdout.md` 并在下游 `<upstream_context>` 提供 preview + artifact pointer map（绝对路径、`chars`、`sha256`）。下游 agent 可读 runner evidence，但 read-only node 仍不得编辑 `.harness/dag-runs/**`。
+- **`writePolicy=exclusive`** 要求非空 `writeSet`；same-rank exclusive node 的 `writeSet` 条目须 **disjoint**，否则 validation fail fast。v1 DAG 中声明 `writePolicy` 或 `writeSet` 任一即 opt-in write validation。
+- **`forbiddenPaths` 优先于 `allowedPaths`**（writeSet validation）。
+- **Pi rollback**：SDK path 损坏时在 `run-dag` 前 `export CODE_AGENT_PI_BACKEND=cli-only`。
+- **Defaults  caveat**：`defaults.skills` / `defaults.writePolicy` 生效。对 `cursor` / `pi` node，resolved skill 名亦由 DAG runner 映射为有界 inline `SKILL.md` instruction，审计于 `<node>/skills.json`；Pi 仍以 `noSkills` / `--no-skills` 运行，故非 Pi ResourceLoader loading。`defaults.executor`、`defaults.model`、`defaults.piBackend`、`defaults.contextProfile` 接受/保留但尚非 runtime default。runtime execution 用 node `executor` + node `complexity`；各 executor 内部自选 model。live contract 已移除 `models`；executor-specific routing 用 `executorModels`。
+- **默认无**跨 node Pi runtime reuse；各 Pi node 是独立 `executePiStep()` call。
+- **Prompt source**：每个 task 仅用一种 prompt source。v1-compatible DAG 用 inline `subtask_prompt`；markdown-backed prompt 用 canonical `subtask_prompt_markdown`。同时提供两字段、皆不提供、或用连字符 alias `subtask_prompt-markdown` 均 fail fast。
+- **勿宣称 live smoke 已通过**，除非真实 `run-dag` execution 中 Pi read-only、Pi writer、显式 Cursor 或 shell node 均按 DAG 完成。
+
+可复用 template：`docs/templates/agent-dag.base.json`（model 生成 DAG 的首选 base template）、`docs/templates/agent-dag.schema.json`（JSON Schema）、`docs/templates/agent-dag.supervised-implementation.json`（supervised implementation：writeSet audit、soft/hard verify、process supervisor、repair、review verdict gate）、`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（可选 authority surface verifier；authority signal 或显式 enablement 匹配时由 `dag init-hybrid` 插入）、`examples/hybrid-loop-agent-dag.json`、`docs/templates/hybrid-dag.json`。
+
+### Supervised implementation flow（减少 main-session intervention）
+
+长时 implementation 曾迫使 main session 中途 re-verify、re-review 或 surgical-patch 时，用 `docs/templates/agent-dag.supervised-implementation.json`。
+
+**此前 main session 介入原因**：linear hybrid DAG 缺少 in-run writeSet coverage audit、supervision 前归档的 soft verification、read-only process supervisor（`executor: pi`，`role: supervisor` — 非新 executor）、bounded repair exclusive writer、确定性 hard-verify shell fact，以及 fail-closed review verdict gate（除非 whitelist `VERDICT:` 行存在）。
+
+**Supervised topology**（执行前替换所有 `REPLACE/WITH/...` placeholder）：
+
+```text
+contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
+  → write-set-gate-shell → implement-pi → soft-verify-shell → process-supervisor-pi → process-gate-shell
+  → repair-pi → hard-verify-shell
+  → [authority-surface-audit-pi → authority-surface-gate-shell]  # 可选
+  → review-pi → review-gate-shell → decision-pi → closeout-pi
+```
+
+| Stage | 减少 main-session 工作的方式 |
+|-------|------------------------------|
+| `write-set-audit-pi` | implement 前捕获 missing/overlapping writeSet owner |
+| `write-set-gate-shell` | 除非 extracted audit verdict 行为 `VERDICT: pass`，否则 fail-closed block implement |
+| `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 |
+| `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` |
+
+**Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
+
+Prompt invariant：`docs/templates/agent-dag-process-supervisor.prompt.md`、`docs/templates/agent-dag-review-verdict.prompt.md`、`docs/templates/agent-dag-authority-surface-audit.prompt.md`（启用时）。测试：`npx vitest run test/dag-supervised-template.test.ts test/authority-surface.test.ts`。完整叙述：`docs/agent-dag-runner.md` §「Why main-session interventions happened」。
+
+**未实现**：`executor: supervisor`、automatic retry/resume、`executor: human`/`decision`、browser executor，或 read-only node 对 root `artifacts/**` 的 exemption。
+
+### Level 3 task-to-DAG（`dag init-hybrid` / `dag run-task`）
+
+```bash
+loop-agent dag init-hybrid <task-id> [--output <temp-dir>/<task-id>-hybrid-dag.json]
+loop-agent dag run-task <task-id> [--output <temp-dir>/<task-id>-hybrid-dag.json]   # 安全默认：仅 generate + validate，standard-compatible
+loop-agent dag run-task <task-id> --profile auto                                # 推断 candidate governanceProfile，再经 workflowPolicy 路由
+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> --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
+```
+
+默认 `dag run-task` **不**创建 `.harness/dag-runs/**`。placeholder / `**` implement writeSet 会 block `--execute`、`--init-only`、`--dry-run`，直到人工 review narrow path。
+
+`dag run-task` JSON 输出含确定性 `reviewPacket` 供执行前 review。derived 自 generated DAG JSON、embedded validate summary、`profileRouting`；不调用 LLM，不写 completed run facts。`run-dag` 前用它 inspect `profileRouting`、`governanceProfile`、exclusive writer `writeSet`、`broadWriteSetRisk`、`forbiddenOverlapRisk`、`shellGates`（含 `lineMode`）、`shellVerification` / `expectedVerification`、`decisionGates` mode。
+
+### DAG 与 artifacts source-of-truth 规则
+
+- 临时 DAG input spec 放平台原生临时目录（例如 `<temp-dir>/<topic>-dag.json`）；可复用 template 放 `examples/` 或 `docs/templates/`。
+- **不要**在 `.harness/dag-runs/active/` root 保留手写 DAG input 副本。
+- **不要**把 `.harness/dag-runs/` 内容 commit 到 git。
+- canonical per-run DAG 历史是 `.harness/dag-runs/completed/<run-id>/run.json` 及该 run 目录的 `state.json`、`executor.jsonl`、node artifacts；新建 run directory 使用 `YYYYMMDD-<slug>`。
+- root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy current-work / explicit-write 摘要。不是 per-run 不可变历史，也不是新工作流默认交付路径。
+- Agent DAG read-only node 不得写 root `artifacts/`；若须更新 root artifacts，用显式 `exclusive` write node 或记录了理由、验证与迁移计划的 main-session surgical patch。
+- DAG Cursor 节点交付物必须写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；`./artifacts/**` 是错误落点。
+- 长期结论须迁入 `docs/exec-plans/`、`docs/reports/` 或 `docs/progress/`。从 completed run evidence 汇总 task artifacts 时用 `promote-run <task-id> --run-id <run-id>`；再用 `closeout task <task-id>` 生成 progress。二者 deterministic，且不 mutate completed run facts。
+
+**DAG author 的 artifact-boundary 提醒**：大量 *讨论* root `artifacts/**` 的 task 仍遵守同一 write guard — read-only node 仅在 node output 返回发现；exclusive node 保持 `artifacts/**` 在 `forbiddenPaths`，除非 concrete path 在 `writeSet`。不要在 declared writeSet 外 instruct implementer 写 `artifacts/修改记录.md` 或 `artifacts/验证结果.md`（P3 boundary-risk practice）。scout 在链接 skill reference 中发现 stale wording 时，把那些 path 纳入 implementer writeSet，或接受记录的 main-session patch（P2 教训：`hybrid-dag.md` 被 scout 发现但 initial writeSet 遗漏）。
+
+### Decision Gate（M3–M5 runtime）
+
+Pi reviewer node 设 `decisionGate.enabled: true` 时，runner 从 persisted `assistantText`（优先）或 `result.summary.md`（fallback）解析 **恰好一个** info string 为 `DECISION_ENVELOPE_JSON` 的 fenced block。Schema：`docs/templates/agent-dag-decision-envelope.schema.json`。Prompt：`docs/templates/agent-dag-decision-gate.prompt.md`（含 §Recovery Recommendation Consumption 与 schema-adherence 硬规则：勿发明 envelope schema、勿用 `decision: accept`、勿加 extra root key、`audit.runId` 须绑定当前 run id，并填 `audit.nodeId` / `audit.model`）。Playbook：`docs/agent-dag-recovery-playbook.md`。示例 DAG：`examples/decision-gate-agent-dag.json`。
+
+| Milestone | `decisionGate.mode` | 行为 |
+|-----------|---------------------|----------|
+| **M3 record-only** | `record-only`（默认） | 写 `<node-id>/decision.envelope.json` + node record summary；**不 pause**，**不** branch 于 `decision`/`nextAction` |
+| **M4 pause-on-human** | `pause-on-human` | parse OK 且 `requiresHuman=true`：run `status=paused`，移入 `.harness/dag-runs/paused/<run-id>/`，写 `human-escalation.json` / `.md`；downstream node 保持 `PENDING` |
+| **M5 CLI** | （M4 pause 后） | 确定性 human decision — **无 LLM**，**无** `executor: human` / `executor: decision` |
+
+```bash
+loop-agent dag doctor
+loop-agent dag status --run-id <run-id>
+loop-agent dag report --paused-latest [--json|--markdown]   # 最新 paused run；勿与 --lifecycle 并用
+loop-agent dag report [--run-id <run-id>] [--lifecycle active|paused|completed|all] [--json|--markdown] [--failed-only] [--latest] [--action <recovery-action>]  # derived per-node report（只读）；JSON schema: docs/templates/agent-dag-report.schema.json；仅 advisory — 见 docs/agent-dag-recovery-playbook.md
+loop-agent dag closeout-draft [--run-id <run-id>] [--output <path>]  # M5：从 completed run facts 生成确定性 closeout draft；默认平台临时目录；仅 advisory；不 mutate completed facts
+loop-agent promote-run <task-id> --run-id <run-id>                    # 从 completed DAG/one-shot evidence 汇总 task artifacts；不 mutate completed facts
+loop-agent closeout task <task-id>                                    # 从 task artifacts 生成 docs/progress closeout
+loop-agent dag reconcile-tasks --glob '<pattern>' [--json|--markdown]  # 仅报告的 task/run/artifact/verify drift audit
+loop-agent dag final-verification <task-id> [--output <path>]  # 生成 closeout DAG；final verify 依赖 closeout artifact
+loop-agent dag decision inspect --run-id <run-id> [--node-id <node-id>]
+loop-agent dag decision validate --run-id <run-id> [--node-id <node-id>]
+loop-agent dag approve --run-id <run-id> --option <id> [--notes "..."]
+loop-agent dag reject --run-id <run-id> --reason "..."
+loop-agent dag resume --run-id <run-id>   # approve 后继续
+```
+
+**Paused operator flow**：`run-dag` → `paused/` →（`dag status` / 可选 `dag decision validate`）→ `dag approve` → `active/` → `dag resume` → `completed/`；或 `dag reject` → `completed/`（`failed`，`failureCategory=human-rejected`）。
+
+**Stale active detection**：`dag doctor` 标 health code 如 `terminal-in-active`（`active/` 保留 terminal run）；仅 advisory — 按 playbook 手动 archive/remove，尚无 auto cleanup CLI。
+
+**Deferred**：`browser` executor；`dag recover apply`；勿在 DAG JSON 加 `executor: human` 或 `executor: decision`。
+
+**In-flight DAG run 期间的 governance**：live run 内 shell verify node 须用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`。run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
+
+### Evidence summary guidance（practice convention — 非 runtime）
+
+review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-summary-shell** 作为 authoring pattern。**不是** runtime executor、schema field 或 parser。
+
+- soft/hard verify shell node 之后，prompt downstream **read-only** Pi reviewer（`reviewer`、`supervisor`、`closeout`）在 node output 开头用紧凑 `EVIDENCE:` 行（`EVIDENCE: <check> exit=<code> (<one-line fact>)`），再写 prose findings。
+- 与现有 **`shell.verdictGate`** 配对做 fail-closed gate：`VERDICT: pass` 或 `VERDICT: request-revision` 仍是 machine-readable decision；supervised gate 用 `lineMode: "first-verdict-line"`，`EVIDENCE:` 行供扫描事实，不能替代 verdict line。
+- shell node exit code 与 archived command output 为 authoritative；`EVIDENCE:` 摘要供 human/decision-gate 扫描速度，不替代 deterministic shell verification。
+- **不要**期望 runner enforce、parse 或 validate `EVIDENCE:` 格式；**不要**在 `shell.verdictGate` 或 shell exit code 已够用时手写 shell grep `EVIDENCE:`。
+- read-only node 不得写 root `artifacts/**`；compact evidence 属于 `.harness/dag-runs/<run-id>/` 下归档的 node output。
+
+完整叙述：`docs/agent-dag-runner.md` §「Evidence Summary as a Practice Convention」。P1 calibration report：`docs/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md`。
+
+### Authoring checklist（P1–P5 practice guidance — 非 runtime 行为）
+
+> 与 `docs/agent-dag-runner.md` §「Agent DAG authoring checklist」相同。Calibration reports：`docs/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md` … `p5-handoff-closeout-20260608.md`。
+
+| # | Check | Expect |
+|---|-------|--------|
+| 1 | Topology | 优先 same-rank parallel read-only scout/review；仅 output 真正需要时加 `depends_on` |
+| 2 | Executor | 每个 task 显式声明 `executor`；`defaults.executor` 是 schema metadata，非 runtime fallback |
+| 3 | Model routing | 用 node `complexity` + `executorModels`；Pi MED（`glm-5.2`）quota 耗尽时提高 Pi node 到 `complexity: HIGH`（`gpt-5.5`）— 勿 mutate canonical model matrix |
+| 4 | Read-only output | read-only / Pi node 在 **node output** 返回发现；runner 归档于 `.harness/dag-runs/<run-id>/<node-id>/` |
+| 5 | Root `artifacts/**` | 非 read-only handoff target；持久记录去 `docs/reports/`、`docs/progress/`，或 narrow exclusive `writeSet` 写 legacy 摘要并记录迁移计划 |
+| 6 | DAG Cursor artifacts | 写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；不得写入 `./artifacts/**` |
+| 7 | Completed facts | `.harness/dag-runs/completed/**` 仅可读 evidence — 归档后永不 mutate 历史 run 目录、`run.json`、`state.json` 或 `artifacts/**` |
+| 8 | Verdict gate | review/supervisor 应以 `VERDICT: pass` 或 `VERDICT: request-revision` 开头以利阅读；用 current-run `<fromNodeId>.json`（`$HARNESS_DAG_RUN_DIR`）上 `shell.verdictGate` block，exact-match `accept[]`；默认 `lineMode=first-non-empty`，supervised template 用 `first-verdict-line` 容忍 preamble 或第一条 normalized `VERDICT:` 前的常见整行 Markdown emphasis |
+| 9 | Decision Gate | 恰好 emit 一个 `DECISION_ENVELOPE_JSON` block；`audit.runId` 须绑定 **当前** run id；禁止 `decision: accept`、发明 schema、extra root key；填 `audit.nodeId` / `audit.model` |
+| 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 |
+| 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/learned/README.md

@@ -0,0 +1,21 @@
+# Learned loop-agent Patterns
+
+This directory is the human-gated target for SePO-lite prompt evolution.
+
+Rules:
+
+- Files are Markdown guidance only.
+- `retrospective` may propose `.harness/tasks/<task-id>/source/prompt-delta.md`; it must not merge here automatically.
+- Do not add shell commands, credential handling, tool permission expansion, or completion-authority bypass rules.
+- DAG implementer prompts may load the repo-specific file `<repo>.md` or `default.md` as bounded inline guidance when the node already requests the `loop-agent` skill.
+- Keep entries short and pattern-oriented: failure class, fix scope shape, invariant, and verification evidence.
+
+Acceptance checklist before merging a prompt delta:
+
+- The proposal is Markdown-only process guidance.
+- It contains no shell/runtime command lines or fenced command blocks.
+- It does not ask to read, print, export, collect, or handle credentials, tokens, passwords, secrets, or API keys.
+- It does not expand tool permissions, path allowlists, `allowedPaths`, `forbiddenPaths`, or `writeSet`.
+- It does not skip or bypass shell verification, tests, write guards, decision gates, human gates, or completion evidence.
+- It does not modify, rewrite, delete, overwrite, or mutate completed DAG / one-shot run facts.
+- `loop-agent docs audit` passes after the learned file is edited.

package/skills/loop-agent/references/model-routing.md

@@ -0,0 +1,36 @@
+# 模型配置与路由
+
+查看或修改 loop-agent model 默认值、Agent DAG `executorModels` 或 Pi model/provider 设置时使用本文。
+
+## 模型配置
+
+模型设置来自 repo `harness.json`。历史 `models.<step>` 只作为旧 task metadata 兼容读取；新 DAG work 不从这里路由模型。
+
+示例模型记录：
+
+```json
+{
+  "provider": "wizard-local",
+  "model": "gpt-5.3-codex-spark"
+}
+```
+
+Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag validate --strict-models` 检查 canonical matrix 漂移。若变更模型配置，须同步更新 `harness.json`、相关测试、repo docs 与本 skill。
+
+`pi-prompt` 是独立 one-shot helper，不使用 `harness.json.models` 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；读写 profile 共用同一矩阵：
+
+```json
+{
+  "LOW": "gpt-5.3-codex-spark",
+  "MED": "glm-5.2",
+  "HIGH": "gpt-5.5"
+}
+```
+
+始终信任当前 repo config，而非硬编码示例：
+```bash
+loop-agent inspect
+```
+并在输出中核对 `models` 与 Agent DAG 文档中的 `executorModels` 约定。
+
+Pi SDK runtime reuse 仍为 **default-off**（`CODE_AGENT_PI_REUSE_RUNTIME` 未设/`off`/未知）。opt-in 须显式 `auto-run`；`CODE_AGENT_PI_BACKEND=cli-only` 绕过 reuse。无 live call 的确定性 M2/M3 decision 摘要用 `pi-reuse-benchmark`（见 `command-reference.md`）。

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

@@ -0,0 +1,54 @@
+# Multi-Worktree 并行模式
+
+同时驱动两个及以上独立 loop-agent task、委派到 isolated worktree、或 harvest 已完成工作时使用本文。
+
+## Multi-Worktree 并行模式
+
+需要**同时推进两个及以上独立 loop-agent task** 时，用 multi-worktree mode 隔离编辑与测试。
+
+> **Historical（已移除）**：`subagent list|start|attach|stop|wait|wakeup`、`dashboard` 与 `delegate --supervised` 已随 tmux 白盒 lifecycle 移除。并行观察请用各 task 的 `status`、worktree 内 `logs/`，或 Agent DAG `dag status` / `dag report`。
+
+### 何时启用
+
+- 有 ≥ 2 个可独立推进的 task id，且希望在不同 worktree 中并发运行
+- 或希望主 repo 保持干净供审阅，而 leaf executor 在 worktree 内跑 `implement`/`verify`
+- 单一顺序 task 可跳过 — 直接 Agent DAG 或 main-session surgical patch 足够
+
+### 核心命令
+
+```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 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 路径。
+
+`harvest` 是对称 closeout：仅当 `task.status === "completed"` 才运行，然后 merge（默认 `--no-ff`，或 `--squash`），将 `artifacts/`、`logs/`、`.workflow_state.json` 归档回主 repo，移除 worktree + branch。
+
+### 主窗口职责（勿与 executor 重叠）
+
+1. delegate 前与用户 refine `需求.md` / `执行约束.md`
+2. `delegate` 返回后**不要**碰 `plan` 或 `implement` — 让 worktree 内 executor 跑
+3. 用 `status <task-id>` 与 worktree 内 `logs/workflow.log`、`logs/executor.jsonl` 观察进度
+4. task 报告 verify-passed 后，用 `git -C .worktrees/<task-id> log -p main..` 审 diff，再跑 `harvest`
+5. task 失败则**不要** harvest — 进入 worktree 排障并重跑 verify
+
+### 生命周期概览
+
+```
+delegate → executor 跑 spec/implement/verify → completed → harvest → archive + cleanup
+                                          ↘ failed   → worktree 内排障（不 harvest）
+```
+
+### 失败处理
+
+- `delegate` fail-fast：任何 source/conflict 错误在创建 worktree 前 abort
+- `harvest` 拒绝 failed/active task；merge conflict 时打印 conflict 文件（手动解决后重跑）
+- `worktree list` 只读；从任意窗口运行都不影响 in-flight delegate
+
+### 与 Agent DAG 的关系
+
+Agent DAG 是默认 autonomous path；`delegate`/`harvest` 是 cursor-direct 的 worktree escape hatch。多 task 并行时，每个 task 独立 `delegate`，完成后分别 `harvest`。
+
+详见 `docs/cursor-executor-usage.md` 与 `docs/loop-agent-harness.md`。

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

@@ -0,0 +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`。

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

@@ -0,0 +1,169 @@
+# Main Orchestrator、Agent DAG 与受控干预
+
+协调长时 loop-agent work、判断 main session 是否可 edit、在 Agent DAG / one-shot Cursor / one-shot Pi 间选择，或在不失 auditability 的情况下恢复 in-flight workflow 时使用本文。
+
+## 核心立场
+
+**Agent DAG 优先，main session 编排，executor 实现，shell 验证。**
+
+`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。
+
+这不是绝对禁止 edit。main-session 手动 edit 仅允许作为有 verification 与 artifact 记录的 bounded surgical patch。
+
+## 默认执行模型
+
+| Actor | 主角色 | 避免 |
+|---|---|---|
+| 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 的宽写入 |
+| 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 |
+
+## 入口选择
+
+**Agent DAG**（`dag run-task` → review/writeSet → `run-dag`）为默认，用于 autonomous implementation、workflow/harness/docs governance 变更、multi-file work，或任何受益于多 executor、parallel scout、显式 write policy、shell evidence、review gate、Decision Gate 的工作。
+
+**supervised Agent DAG** 用于 `governanceProfile=supervised`，或工作触及 loop-agent runtime、scripts/CI、schema/public contract、多个 exclusive writer、repair flow 或 high-cost path。
+
+**one-shot Pi / Cursor prompt** 仅作受控 sidecar intervention，不是 workflow state source。
+
+**main-session surgical patch** 仅用于 small、obvious、low-risk 的修正，且 delegation 开销会占主导。
+
+## Sidecar intervention 协议
+
+sidecar intervention 是一次性 Pi 或 Cursor prompt，用于 unblock 主 workflow。
+
+调用前说明：
+
+1. 观察到什么问题。
+2. 为何当前 DAG/step 不应盲目继续。
+3. sidecar 是 read-only 还是可写文件。
+4. 可写工作的精确 allowed/forbidden paths。
+5. 预期输出及记录位置。
+
+典型 routing：
+
+| 情况 | 使用 |
+|---|---|
+| 需 quick root-cause analysis、plan critique、log 解读 | one-shot Pi prompt，read-only |
+| 需 codebase-indexed multi-file 诊断或 bounded patch | one-shot Cursor prompt |
+| 需确定性 evidence | shell command / shell DAG node |
+| DAG topology、writeSet 或 source contract 错误 | stop/revise DAG 或 source；不要绕开 patch |
+| requirement、architecture 或 risk 决策不清 | Decision Gate / human approval |
+
+规则：
+
+- 同一 issue 不应反复 sidecar。若需要，pause 并 replan。
+- 可写 sidecar 须在 edit 后跑 targeted verification。
+- sidecar 发现须写入 task artifacts、DAG node artifacts、`docs/progress` 或 report 后再 resume。
+- sidecar 输出为 advisory，直到 deterministic command 验证或并入 canonical workflow state。
+
+### Agent DAG read-only artifact boundary
+
+Agent DAG read-only node **不得**写 root `artifacts/`。
+
+- root `artifacts/修改记录.md` 与 `artifacts/验证结果.md` 是 legacy / explicit-write 摘要；不是 per-node 不可变历史，也不是新工作流默认交付路径。
+- Agent DAG node 发现属于 node output 与 runner-owned artifacts，位于 `.harness/dag-runs/<state>/<run-id>/<node-id>/`；Cursor 节点的 `修改记录.md` / `验证结果.md` 位于 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`。
+- 不要把 root `artifacts/` 当作所有 DAG node 的共享 state 交集；`.harness/dag-runs/<run-id>/` 才是 DAG state 交集。
+- `./artifacts/**` 不是 DAG artifact 位置；出现该目录通常表示 Cursor prompt 没有收到 DAG-owned artifact dir。
+- 若必须更新 root `artifacts/`，用显式 write-capable node 或 narrow scope、verification、recorded rationale 与后续迁移计划的 main-session surgical patch。
+
+**Linked skill-reference writeSet candidates**：DAG task 变更 workflow 语义（artifact boundary、verdict gate、evidence summary、intervention policy）时，scout node 应提议 `./skill/references/**` 下链接文件为 **writeSet expansion candidates**，而非仅 primary docs。P2 表明 implementer writeSet 遗漏 `hybrid-dag.md` 时，虽 scout 已发现 drift，仍须 post-DAG main-session patch。
+
+**Bounded main-session patch 须记录**：DAG run 中或之后任何可接受的 surgical patch（scope、变更文件、verification、rationale）应写入 `docs/reports/`、`docs/progress/` 或 active exec plan — 不可静默应用且无 audit trail。
+
+**勿把 root `artifacts/**` 当 read-only DAG handoff**（P3/P5）：即使 task 文本、scout 或 supervisor 讨论 `artifacts/修改记录.md` / `artifacts/验证结果.md`，read-only DAG node 只能在 node output 返回发现。root `artifacts/` 是 legacy / explicit-write 摘要区，不是 in-flight DAG node 的共享 scratchpad，也不是新工作流默认 handoff。post-DAG 持久 handoff 用 `docs/reports/`、`docs/progress/`、exec-plan 索引与 `.harness/dag-runs/completed/<run-id>/` node artifacts。
+
+### Completed run facts boundary（P3/P5）
+
+`.harness/dag-runs/completed/<run-id>/` 是 canonical per-run 历史。视为 **只读 evidence**，不是可写 workflow state。
+
+- **允许**：读 node JSON、`result.summary.md`、decision envelope、shell stdout、随 run directory 归档的 `artifacts/<node-id>/修改记录.md` / `验证结果.md`，用于 review、Decision Gate 或 post-DAG closeout。
+- **禁止**：run 归档到 `completed/` 后再追加或改写 side file；mutate 历史 `run.json` / `state.json` / `artifacts/**`；把 completed facts 当作 revision DAG 的 write target。
+- **Recovery**：revision DAG 需要 prior evidence 时，在 node output 或 main-session report 中消费 — 不要 in-place patch completed 目录。
+- **Promotion**：需要把 completed DAG 或 one-shot run evidence 汇总为 task artifacts 时，用 deterministic `promote-run <task-id> --run-id <run-id>`；需要长期 progress 时再用 `closeout task <task-id>`。这两个命令消费历史 facts，但不修改历史 facts。
+
+P5 验证：future agent 可从 practice report + completed node artifacts 继续，无需 root `artifacts/**` 摘要。
+
+### Agent DAG run 中的 main-session intervention
+
+main session 编排；不是默认 implementer。in-flight run 期间：
+
+| Action | 何时 | 记录位置 |
+|--------|------|----------|
+| Inspect status / node artifacts | 始终允许 | progress 或 sidecar output 中的 notes |
+| Sidecar read-only Pi/Cursor prompt | 诊断、plan critique、log 解读 | resume 前的 findings |
+| Surgical patch | small、obvious、可 verify；无 active `writeSet` 冲突 | `docs/reports/` 或 exec plan，含 scope + verification |
+| DAG/source repair | topology、writeSet 或 prompt contract 错误 | 编辑平台临时目录中的 DAG 或 plan；re-validate；rerun |
+| Approve/reject/resume | Decision Gate `pause-on-human` | 仅 CLI artifacts |
+| Post-DAG closeout | promotion、report、plan archive、indexes | `promote-run`、`closeout task`、`docs/reports/`、`docs/progress`、exec-plan indexes — 非 root `artifacts/`，除非 explicit narrow writeSet |
+
+**Verdict 与 Decision Gate 提醒**（authoring guidance，非 runtime 变更）：
+
+- `shell.verdictGate` 后的 review/supervisor node：首条非空行须精确为 `VERDICT: pass` 或 `VERDICT: request-revision`（P2/P4）。
+- Decision Gate node：恰好一个 `DECISION_ENVELOPE_JSON` block；`audit.runId` 须为 **当前** run id（P4 misbind 教训；P5 fix）。
+- Pi MED quota 耗尽：提高 Pi node `complexity` 到 `HIGH`，而非改 `executorModels` 或加 auto-retry（P4）。
+
+完整 authoring checklist：`docs/agent-dag-runner.md` §「Agent DAG authoring checklist」与 `hybrid-dag.md` § Authoring checklist。
+
+## Main-session surgical patch policy
+
+仅当以下**全部**成立时允许：
+
+1. 变更 small 且 obvious，通常 1–3 个文件。
+2. 原因已知；不需要 broad system understanding。
+3. 不改变 product requirement、architecture、public API、data model 或 cross-platform contract。
+4. 不与 active DAG node 的 `writeSet` 或其他 executor 声明职责冲突。
+5. 可用 targeted command 立即 verify。
+6. patch 摘要与 verification 结果记录在 artifacts/progress/report。
+
+好例子：
+
+- validation 指出后修正 DAG JSON path 或 schema typo。
+- 修正 doc index link 或 typo。
+- revert 明显 out-of-scope 的生成 scratch file。
+- LSP 或 typecheck 指向确切 issue 时修单个 import/path 错误。
+
+坏例子：
+
+- 手工按 `artifacts/实现计划.md` implement feature。
+- 不委派就修大量 test failure。
+- 改 API/contract 语义。
+- refactor 子系统。
+- 编辑 in-flight exclusive DAG node 拥有的文件。
+
+最小协议：
+
+```text
+1. 标记 intervention / 必要时 pause。
+2. 检查 status 与 dirty files。
+3. 声明 reason 与 scope。
+4. 做最小 edit。
+5. 跑 targeted verification。
+6. 记录 patch 摘要与 verification evidence。
+7. Resume DAG / rerun failed node / restart verify。
+```
+
+## 失败状态机
+
+```text
+Run DAG workflow
+  -> success: verify -> handoff
+  -> node/step failure: diagnose
+       -> transient/tool issue: one-shot sidecar 或 retry -> verify -> resume
+       -> bounded implementation issue: Cursor/Pi fix -> verify -> resume
+       -> DAG design/source issue: stop -> edit DAG/source -> validate/spec -> rerun
+       -> requirement/architecture issue: Decision Gate 或 human approval -> resume/reject
+  -> verification failure: bounded fix loop 或 replan，永不宣称完成
+```
+
+## 记录要求
+
+每次 intervention 须留可恢复 trail：
+
+- Agent DAG：优先 node artifacts 于 `.harness/dag-runs/<state>/<run-id>/<node-id>/`；长期结论写入 `docs/progress`、`docs/reports` 或 `docs/exec-plans`。read-only node 不得写 root `artifacts/`。
+- Repo docs/skill workflow 变更：以 governance checks 结束，practice 变更时更新本 skill。

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

@@ -0,0 +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`。