@tea-agent/loop-agent 0.1.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/learned/README.md

@@ -1,21 +1,21 @@
 # Learned loop-agent Patterns
 
-This directory is the human-gated target for SePO-lite prompt evolution.
+本目录是 SePO-lite prompt evolution 的 human-gated target。
 
 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.
+- Files 仅为 Markdown guidance。
+- `retrospective` 可 propose `.harness/tasks/<task-id>/source/prompt-delta.md`；不得自动 merge 到此。
+- 不要添加 shell commands、credential handling、tool permission expansion 或 completion-authority bypass rules。
+- DAG implementer prompts 在 node 已 request `loop-agent` skill 时，可将 repo-specific 文件 `<repo>.md` 或 `default.md` 作为 bounded inline guidance 加载。
+- 保持条目 short 且 pattern-oriented：failure class、fix scope shape、invariant、verification evidence。
 
 Acceptance checklist before merging a prompt delta:
 
-- 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.
+- Proposal 仅为 Markdown-only process guidance。
+- 不含 shell/runtime command lines 或 fenced command blocks。
+- Credential material、tokens、passwords、secrets 与 API keys 保持不可触达。
+- Tool permissions、path allowlists、`allowedPaths`、`forbiddenPaths` 与 `writeSet` 保持既有边界。
+- Shell verification、tests、write guards、decision gates、human gates 与 completion evidence 均为保留门禁。
+- Completed DAG 与 one-shot run facts 保持只读。
+- Learned file 编辑后 `loop-agent docs audit` 须 pass。

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

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

package/skills/loop-agent/references/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/pi-subagent-assisted-mode.md

@@ -2,8 +2,6 @@
 
 loop-agent task 启用 `piSubagentMode`、在 analyze/plan/spec/retrospective 内需要 read-only scout/planner/reviewer subagents，或配置 project-local agents/prompts 时使用本文。
 
-## Pi Subagent Assisted Mode
-
 `task.json` 支持可选字段 `piSubagentMode`，用于 step 级 `subagent` tool delegation：
 
 | Mode | analyze | plan | spec | implement | retrospective | verify |

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。因此快且可靠。
 
@@ -56,6 +90,24 @@
 
 最佳实践：保持 `allowedPaths` 准确。auto-commit 用 task path 约束，避免把无关 dirty 文件扫进 progress commit。
 
+### Cursor bounded write 后的独立复核
+
+Cursor bounded execution 完成后，主会话必须独立执行：
+
+```bash
+git status --short
+git diff --stat
+bash scripts/check-repo.sh
+npm run lint
+npm test
+npm run typecheck
+loop-agent inspect
+loop-agent docs audit
+loop-agent handoff check <task-id>
+```
+
+Cursor 自己报告的完成不算 verification fact；以上命令的 exit code 与输出才是完成声明的证据。
+
 ### 失败处理
 
 child agent 失败时：
@@ -72,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。

package/skills/requesting-code-review/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: requesting-code-review
-description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+description: 在完成任务、实现 major features，或 merge 前验证 work 是否满足 requirements 时使用
 ---
 
 # Requesting Code Review
 
-Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+Dispatch code reviewer subagent，在问题级联前捕获 issue。Reviewer 获得精确 crafted 的 evaluation context — 绝不是你的 session history。这使 reviewer 聚焦 work product，而非你的 thought process，并保留你自己的 context 以继续工作。
 
-**Core principle:** Review early, review often.
+**Core principle：** Review early, review often.
 
 ## When to Request Review
 
-**Mandatory:**
-- After each task in subagent-driven development
-- After completing major feature
-- Before merge to main
+**Mandatory：**
+- subagent-driven development 中每个 task 之后
+- 完成 major feature 之后
+- merge 到 main 之前
 
-**Optional but valuable:**
-- When stuck (fresh perspective)
-- Before refactoring (baseline check)
-- After fixing complex bug
+**Optional but valuable：**
+- 卡住时（fresh perspective）
+- refactoring 前（baseline check）
+- 修复 complex bug 之后
 
 ## How to Request
 
@@ -29,19 +29,19 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Use the code reviewer template** (`code-reviewer.md` in this skill directory):
+**2. Use the code reviewer template**（本 skill 目录下的 `code-reviewer.md`）：
 
 **Placeholders:**
-- `{DESCRIPTION}` - Brief summary of what you built
-- `{PLAN_OR_REQUIREMENTS}` - What it should do (contract, exec plan, or requirements)
-- `{BASE_SHA}` - Starting commit
-- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` — 简要 summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` — 它应做什么（contract、exec plan 或 requirements）
+- `{BASE_SHA}` — Starting commit
+- `{HEAD_SHA}` — Ending commit
 
 **3. Act on feedback:**
-- Fix Critical issues immediately
-- Fix Important issues before proceeding
-- Note Minor issues for later
-- Push back if reviewer is wrong (with reasoning)
+- Critical issues 立即修复
+- Important issues 在继续前修复
+- Minor issues 稍后处理
+- Reviewer 有误时 push back（附 reasoning）
 
 ## Example
 
@@ -72,30 +72,30 @@ You: [Fix progress indicators]
 
 ## Integration with Harness Workflow
 
-**After each work chunk (Plan → Contract → Implement → Verify → Handoff):**
-- Review after Implement, before Verify
-- Catch issues before they compound
-- Fix before moving to next task
+**每个 work chunk 之后（Plan → Contract → Implement → Verify → Handoff）：**
+- Implement 之后、Verify 之前 review
+- 在问题 compound 前捕获
+- 进入 next task 前修复
 
-**Before merge / Handoff:**
-- Review before declaring complete
-- Verify against contract acceptance criteria
+**Before merge / Handoff：**
+- 宣称 complete 前 review
+- 对照 contract acceptance criteria 验证
 
-**Ad-Hoc Development:**
-- Review before merge
-- Review when stuck
+**Ad-Hoc Development：**
+- merge 前 review
+- 卡住时 review
 
 ## Red Flags
 
-**Never:**
-- Skip review because "it's simple"
-- Ignore Critical issues
-- Proceed with unfixed Important issues
-- Argue with valid technical feedback
+**Never：**
+- 因 "it's simple" 跳过 review
+- 忽略 Critical issues
+- 带着未修复的 Important issues 继续
+- 与 valid technical feedback 争辩
 
-**If reviewer wrong:**
-- Push back with technical reasoning
-- Show code/tests that prove it works
-- Request clarification
+**If reviewer wrong：**
+- 用 technical reasoning push back
+- 展示证明其有效的 code/tests
+- 请求 clarification
 
-See template at: requesting-code-review/code-reviewer.md
+Template 见：requesting-code-review/code-reviewer.md

package/skills/requesting-code-review/code-reviewer.md

@@ -1,8 +1,8 @@
 # Code Reviewer Prompt Template
 
-Use this template when dispatching a code reviewer subagent.
+Dispatch code reviewer subagent 时使用本 template。
 
-**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+**Purpose：** 在 work cascade 成更多工作之前，对照 requirements 与 code quality standards review completed work。
 
 ```
 Task tool (general-purpose):
@@ -123,11 +123,11 @@ Task tool (general-purpose):
 
 **Placeholders:**
 - `{DESCRIPTION}` — brief summary of what was built
-- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements)
+- `{PLAN_OR_REQUIREMENTS}` — 它应做什么（plan file path、task text 或 requirements）
 - `{BASE_SHA}` — starting commit
 - `{HEAD_SHA}` — ending commit
 
-**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+**Reviewer returns：** Strengths、Issues (Critical / Important / Minor)、Recommendations、Assessment
 
 ## Example Output