@tea-agent/loop-agent 0.2.0 → 0.2.1

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

@@ -1,6 +1,6 @@
 # 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、optional Cursor backend、write policy、DAG template、task-to-DAG 生成，或基于 governance-profile 的 template 选择。
 
 ### DAG workflow 优先级
 
@@ -25,25 +25,25 @@
 
 ### 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 约定的稳定分隔符。
+```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"`
+- 每 node：`role`、`skills`、`writePolicy`、`writeSet`、`piStep`、`shell`、`outputContract`、`executor`（`cursor` | `pi` | `shell` | `static`）；Pi 写入节点额外声明 `toolProfile: "write"`
 
 **Model 生成 DAG 的 template 卫生**：
 
@@ -53,19 +53,19 @@ 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。
+- 默认 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`。
+- **常规 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`。
+- **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`。
+- **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。
@@ -74,7 +74,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 - **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 完成。
+- **勿宣称 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`。
 
@@ -87,9 +87,9 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 **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
+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
 ```
@@ -101,7 +101,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` / 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` |
@@ -114,16 +114,16 @@ Prompt invariant：`docs/templates/agent-dag-process-supervisor.prompt.md`、`do
 
 ### 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
+```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> --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
@@ -135,7 +135,7 @@ loop-agent dag run-task <task-id> --init-only --cwd <repo-root>
 
 ### DAG 与 artifacts source-of-truth 规则
 
-- 临时 DAG input spec 放平台原生临时目录（例如 `<temp-dir>/<topic>-dag.json`）；可复用 template 放 `examples/` 或 `docs/templates/`。
+- 临时 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>`。
@@ -161,7 +161,7 @@ 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 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
@@ -211,6 +211,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，仅在显式启用且 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/model-routing.md

@@ -17,7 +17,7 @@
 
 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 共用同一矩阵：
+`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
 {

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

@@ -98,7 +98,7 @@ main session 编排；不是默认 implementer。in-flight run 期间：
 | 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 |
+| 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 |
 

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

@@ -1,22 +1,22 @@
 # One-shot Pi SDK Prompt Helper（`pi-prompt`）
 
-短时 Pi SDK task、不需要完整 `.harness/tasks/<id>` workflow 时使用本文。替代 ad-hoc 临时代码脚本导入 `executeSingleSdkAttempt` 的做法。
+短时 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` 决定。
+短时 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 "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>` 表示平台原生临时目录；实际命令中使用本机路径。
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用本机路径。
 
 默认：`--provider wizard-local --model glm-5.2`；高复杂度 one-shot 可显式 `--model gpt-5.5`。按需用 `--provider`、`--model`、`--thinking`、`--tools`、`--timeout` 覆盖。
 

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

@@ -22,13 +22,13 @@ DAG run、promotion、closeout 和最终验证完成后：
 ```
 1. new-task <id>
 2. 写 source/需求.md + source/执行约束.md
-3. dag run-task <id> --profile auto --strict-models --output <temp-dir>/<id>-dag.json
-4. dag validate --dag <temp-dir>/<id>-dag.json --strict-models --strict-governance
-5. run-dag --dag <temp-dir>/<id>-dag.json --cwd <repo-root>
-6. promote-run / closeout / final verification
-```
-
-`<temp-dir>` 表示平台原生临时目录；实际命令中使用 macOS/Windows 本机路径。
+3. dag run-task <id> --profile auto --strict-models --output <temp-dir>/<id>-dag.json
+4. dag validate --dag <temp-dir>/<id>-dag.json --strict-models --strict-governance
+5. run-dag --dag <temp-dir>/<id>-dag.json --cwd <repo-root>
+6. promote-run / closeout / final verification
+```
+
+`<temp-dir>` 表示平台原生临时目录；实际命令中使用 macOS/Windows 本机路径。
 
 **关键**：实现 work 由 DAG node 和 executor 执行；main session 负责审 DAG、审 writeSet、跑验证和 handoff。
 

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

@@ -6,18 +6,18 @@
 
 所有需要可恢复、可验证、可交接的实现工作都走 DAG 路径：
 
-```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>` 表示平台原生临时目录。实际文件路径必须兼容 macOS 和 Windows；只有 repo refs、JSON/Markdown 证据 refs 和 glob 约定默认使用 `/`。
-
-当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
-
-低风险的一行修正文档或配置时，可以由 main session 做 surgical patch，但仍必须记录 scope 并运行对应验证命令。
+```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>` 表示平台原生临时目录。实际文件路径必须兼容 macOS 和 Windows；只有 repo refs、JSON/Markdown 证据 refs 和 glob 约定默认使用 `/`。
+
+当目标仓库是 loop-agent 本仓库时，`loop-agent` 命令必须来自 npm 上已发布的安装包。首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制会改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
+
+低风险的一行修正文档或配置时，可以由 main session 做 surgical patch，但仍必须记录 scope 并运行对应验证命令。
 
 ## Source Materials
 
@@ -75,10 +75,10 @@ loop-agent --repo-root /path/to/target-repo <command>
 完成声明必须来自新鲜验证证据。按目标 repo 的 `docs/verification-matrix.md` 选择最小证明命令；loop-agent 自身常用：
 
 ```bash
-npm run typecheck
-npm test
-bash scripts/check-repo.sh
-bash scripts/ci.sh
-```
-
-Windows 上通过 Git Bash 或配置好的兼容 Bash 运行 `scripts/*.sh`；不要把 POSIX 路径假设写入 CLI、模板或 task source。
+npm run typecheck
+npm test
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+```
+
+Windows 上通过 Git Bash 或配置好的兼容 Bash 运行 `scripts/*.sh`；不要把 POSIX 路径假设写入 CLI、模板或 task source。

package/skills/loop-agent/references/verification-and-failure-handling.md

@@ -4,6 +4,40 @@
 
 ## Verify strategy 与 completion audit
 
+## Production Readiness v0.1
+
+低/中风险单 repo DAG 任务如果声明 production-ready v0.1，必须按 `docs/production-readiness.md` 和 `docs/templates/production-readiness-checklist.md` 收口。
+
+支持范围：
+
+- single repo
+- bounded task
+- explicit task source
+- explicit `allowedPaths` / `forbiddenPaths` / write scope
+- shell verification
+- report / doctor / closeout handoff
+
+非目标：
+
+- automatic merge
+- automatic release
+- production secrets
+- production database
+- high-risk migration
+- online Worker Pool
+- writable Dynamic Workflow sharded migration
+
+失败分类是路由字段，不是主状态；不要覆盖 `.harness/dag-runs/completed/**` 的原始事实。报告和 handoff 应保留：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+product-line taxonomy 的事实源是 `docs/design/state-and-failure-taxonomy.md`。
+
 ### Verify 始终在本地跑
 `verify` step 跑确定性命令（check-repo.sh + tests + typecheck）。**不**调用 pi。因此快且可靠。
 
@@ -90,3 +124,5 @@ loop-agent handoff check <task-id>
 ```
 
 active exec plan 实质完成时，用 `docs archive` 归档并更新 active/completed 索引，勿留 stale active status。
+
+failed DAG run 不应生成成功式 closeout。它应该生成 failure handoff，至少包含 what failed、evidence、classification、recommended follow-up、safe retry conditions 和 human decision needed。