@tea-agent/loop-agent 0.1.0 → 0.2.1

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

@@ -2,52 +2,52 @@
 
 需要 loop-agent 的精确 CLI 命令、setup 命令、task lifecycle 命令、docs helper、goal 命令或 stats 时使用本文。
 
-## loop-agent 入口
-
-**优先在目标 repo 目录内执行命令** — loop-agent 通过 `harness.json.project` 自动检测使用哪个 repo adapter。跨目录操作时显式加 `--repo-root <target-repo>`。
-
-默认使用全局 CLI：
-
-```bash
-loop-agent <command> ...
-```
-
-面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-npm list -g @tea-agent/loop-agent --depth=0
-loop-agent doctor
-```
-
-一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
-
-发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
-
-发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
-
-## 命令参考
+## loop-agent 入口
+
+**优先在目标 repo 目录内执行命令** — loop-agent 通过 `harness.json.project` 自动检测使用哪个 repo adapter。跨目录操作时显式加 `--repo-root <target-repo>`。
+
+默认使用全局 CLI：
+
+```bash
+loop-agent <command> ...
+```
+
+面向自举迭代和日常使用时，全局 CLI 应来自 npm 上已发布的安装包。首次安装或有意升级使用 `@latest`：
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+npm list -g @tea-agent/loop-agent --depth=0
+loop-agent doctor
+```
+
+一次自举任务启动后不要中途升级控制器；记录 `npm list -g` 显示的实际版本。不要在 DAG 节点中反复用 `npx @latest` 拉取，也不要使用当前工作区的 `npm link` 或 `npm run dev` 作为控制器去修改 loop-agent 本仓库的 CLI、DAG runtime、executor、package metadata 或 build output。`npm run dev -- <command> ...` 只用于源码调试和聚焦 CLI 开发。
+
+发布包入口加载 `dist/cli.js`；开发入口加载 `src/cli.ts`。
+
+发布包携带静态能力资料：`skills/`、`docs/*.md`、`docs/templates/` 和 `examples/`。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 的任务正文属于目标仓库运行中生成的事实，不从 npm 包复制；包内只保留这些目录的 README 说明。
+
+## 命令参考
 
 ## 默认选择模型
 
 选择命令时按以下优先级：
 
-1. **主路径 DAG**，用于常规 autonomous work：
-   ```bash
-   loop-agent new-task <task-id> "Task Title"
-   loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-   loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-   loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
-   ```
-   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
-2. **Operator 工具**，用于 recovery、诊断与 closeout：
-   ```bash
+1. **主路径 DAG**，用于常规 autonomous work：
+   ```bash
+   loop-agent new-task <task-id> "Task Title"
+   loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+   loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+   loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+   ```
+   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
+2. **Operator 工具**，用于 recovery、诊断与 closeout：
+   ```bash
    loop-agent dag status --run-id <run-id>
    loop-agent dag doctor
    loop-agent dag report --latest --markdown
    loop-agent dag closeout-draft --run-id <run-id>
    loop-agent dag reconcile-tasks --glob '<pattern>' --markdown
-   loop-agent dag final-verification <task-id> --output <temp-dir>/<task-id>-final-verification-dag.json
+   loop-agent dag final-verification <task-id> --output <temp-dir>/<task-id>-final-verification-dag.json
    loop-agent status <task-id> --json
    loop-agent instructions task-artifacts --task <task-id> --json
    loop-agent promote-run <task-id> --run-id <run-id>
@@ -60,14 +60,15 @@ loop-agent doctor
    ```bash
    loop-agent delegate <task-id> --executor cursor
    loop-agent harvest <task-id>
+   loop-agent cursor-prompt --cwd <repo-root> --file /tmp/bounded-task.md
    loop-agent pi-prompt "Reply with exactly OK."
    ```
 
-### Setup（首次）
-```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --help
-```
+### Setup（首次）
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --help
+```
 
 ### 检查 repo harness
 ```bash
@@ -141,9 +142,9 @@ loop-agent --repo-root /path/to/target-repo study init <task-id> "Title" \
   --reference-glob "codex-rs/**/goal*.rs"
 
 # 编辑 source/需求.md + source/执行约束.md，然后走 DAG 路径：
-loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent --repo-root <target-repo> dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <target-repo>
+loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent --repo-root <target-repo> dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <target-repo>
 ```
 
 目标 repo 需有 `.harness/prompts/feature-study-analyze.md` 与 `feature-study-plan.md`（缺失时从 loop-agent 复制）。
@@ -152,6 +153,13 @@ loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json
 
 历史顺序式 `run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study` 已移除。新任务不要使用这些命令，也不要在 prompt、skill 或 docs 中把它们描述为 fallback。
 
+### Reference helpers（compatibility）
+```bash
+loop-agent reference index
+```
+
+`reference` 是 compatibility / feature-study 辅助入口，用于维护或检查参考资料索引。常规实现任务不要从 `reference` 起步；按 `new-task` + DAG 路径执行。
+
 ### Task goal lifecycle（compatibility-only / deprecated-candidate）
 ```bash
 loop-agent goal set <task-id> "Objective text" [--token-budget <number|null>]
@@ -176,17 +184,17 @@ loop-agent goal clear <task-id>
 
 ### Agent DAG validation 与 execution
 ```bash
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
-loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
-cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
-(npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
-loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # 存在 cursor node 时失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 执行前若存在 cursor node 则失败
-loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json                 # 常规 validation；无 .harness/dag-runs 副作用
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-models # 非 canonical executorModels 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance # governance warning 时失败
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --strict-governance --spine-task <task-id> # 同时消费 minimal spec spine audit
+loop-agent dag validate --dag docs/templates/agent-dag.supervised-implementation.json --strict-models --strict-governance  # role=supervisor + write-set-gate topology
+cp docs/templates/agent-dag.supervised-implementation.json <temp-dir>/supervised-dag.json
+(npx vitest run test/dag-supervised-template.test.ts test/dag-validate.test.ts test/dag-shell-executor.test.ts --reporter=dot)  # supervised template + shell.verdictGate runtime
+loop-agent dag validate --dag <temp-dir>/hybrid-dag.json --forbid-executor cursor # 存在 cursor node 时失败
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root>          # 执行 Agent DAG
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> --no-cursor # 执行前若存在 cursor node 则失败
+loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <temp-dir>/hybrid-dag.canvas.tsx # 可选 derived Canvas view
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
 loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
 loop-agent dag run-task <task-id> --profile auto         # 推断 governanceProfile，经 workflowPolicy.dag.profileRouting 路由
@@ -213,9 +221,9 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 **In-flight DAG governance**：shell verify node 内用 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`；run 归档到 `completed/` 后，在 DAG 外跑裸 `bash scripts/check-repo.sh`。
 
 - `dag validate` 做 schema/topology/ranks 检查；审 `warnings` 中的显式 `executorModels` drift 与 governance lint。
-- 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
+- 手写临时 DAG spec 执行前用 `dag validate --strict-models`，model-matrix drift 应 fail fast。
 - read-only artifact-boundary 或 DAG 内 shell governance warning 应 fail fast 时用 `dag validate --strict-governance`。
-- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
+- 人工 handoff 视图用 `dag report --markdown`（summary、node timeline、failures、四段 Recovery Plan、artifacts、建议 next action）。仅 derived、advisory；需保存时重定向到平台临时目录或 `docs/reports/`。
 - operator 聚焦最新 paused run 用 `dag report --paused-latest`（等同 `--lifecycle paused --latest`；勿与显式 `--lifecycle` 并用）。
 - 需 operator 关注的 run 用 `dag report --failed-only`、`--latest`、`--action <recovery-action>` 收窄。category→action 映射见 `docs/agent-dag-recovery-playbook.md`。
 - 只读扫描 `.harness/dag-runs/` 下所有 run 的生命周期 health issue 与建议 action 用 `dag doctor`（`advisoryOnly: true`；不 mutate facts）。
@@ -227,6 +235,18 @@ loop-agent dag resume --run-id <run-id>                  # approve 后继续
 - 仅当有意在 `.harness/dag-runs/active/` 下要 active run snapshot 时用 `run-dag --dry-run`。
 - task source 应从 `harness.json.workflowPolicy.dag.profileRouting` 与确定性 candidate `governanceProfile` 选 standard / review-gated / supervised template 时用 `dag run-task --profile auto`。无 `--profile` 仅用于旧 standard-compatible 输出；强制 template family 用 `--profile minimal|standard|reviewed|supervised`。
 
+### Saved Dynamic Workflow operator UX
+```bash
+loop-agent workflow list
+loop-agent workflow inspect <name>
+loop-agent workflow save --from /tmp/<task-id>.workflow.json --name <name>
+loop-agent workflow run <name-or-path> --cwd <repo-root>
+loop-agent workflow diff <name> --against /tmp/<task-id>.workflow.json
+loop-agent workflow replay <run-id>
+```
+
+`workflow` 是 Dynamic Workflow 的 saved/operator surface。它读取 `WorkflowSpec`，编译为 DAG，再进入同一套 `run-dag` runtime；不会新增 executor 能力或绕过 DAG governance。真实写入任务仍应检查 compiled DAG 的 executor、writeSet、shell gates 和 completed facts 边界。
+
 ### Cursor worker lifecycle
 ```bash
 loop-agent cursor-worker status   # enabled/running/child/entry path
@@ -259,14 +279,14 @@ loop-agent handoff coverage <task-id> [--json|--markdown]
 
 ### Pi runtime reuse benchmark / decision（无 live call）
 ```bash
-loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
-  --json
-
-loop-agent pi-reuse-benchmark \
-  --report docs/reports/<benchmark-report>.md \
-  --off-executor /path/to/off/executor.jsonl \
-  --on-executor /path/to/on/executor.jsonl \
+loop-agent pi-reuse-benchmark \
+  --report docs/reports/<benchmark-report>.md \
+  --json
+
+loop-agent pi-reuse-benchmark \
+  --report docs/reports/<benchmark-report>.md \
+  --off-executor /path/to/off/executor.jsonl \
+  --on-executor /path/to/on/executor.jsonl \
   --approval /path/to/approval.json \
   --markdown
 ```
@@ -281,6 +301,19 @@ loop-agent loop-benchmark --markdown --output docs/reports/2026-06-30-loop-agent
 
 生成 M0 deterministic baseline，对照 `single-repair`、`3-pass-convergence`、`3-pass-convergence+quota`。**不**跑 live Pi/Cursor call、不创建 task、不改 `convergence.enabled` 默认值。live dogfood 证据缺失时输出 `blocked` 并建议保持 opt-in。
 
+### Long-running loop outer state（experimental）
+```bash
+loop-agent loop init <task-id>
+loop-agent loop status <task-id>
+loop-agent loop run <task-id> --action dag
+loop-agent loop run <task-id> --action shell-verify --command "bash scripts/check-repo.sh"
+loop-agent loop record-round <task-id> --decision continue --summary "..."
+loop-agent loop add-signal <task-id> --kind note --message "..."
+loop-agent loop closeout <task-id>
+```
+
+`loop` 是 Agent DAG 之上的长程状态和 evidence layer，记录 rounds、signals、verification summaries 和 closeout draft。它不是替代 `dag run-task` / `run-dag` 的实现路径；medium/large work 仍需要 DAG evidence 或明确 fallback reason。
+
 ### Minimal spec spine audit
 ```bash
 loop-agent spine audit <task-id> --json
@@ -312,4 +345,13 @@ loop-agent worktree create|list|remove ...
 
 用于 worktree 隔离的 cursor-direct 执行与 merge 收口。常规 autonomous work 应优先 Agent DAG；详见 `multi-worktree.md` 与 `docs/cursor-executor-usage.md`。
 
+### One-shot Cursor sidecar（escape hatch）
+```bash
+loop-agent cursor-prompt --cwd <repo-root> "Review this task without editing files."
+loop-agent cursor-prompt --cwd <repo-root> --file /tmp/bounded-cursor-task.md
+loop-agent cursor-prompt --cwd <repo-root> --model composer-2.5 --timeout 1800000 --file /tmp/bounded-cursor-task.md
+```
+
+`cursor-prompt` 是 one-shot Cursor SDK helper。用于 bounded diagnosis、小修复或调试 executor；写入 prompt 必须包含 task id、objective、allowed paths、forbidden paths、verification 和 preserve-unrelated-changes 要求。需要 `CURSOR_API_KEY`。它会创建 one-shot run evidence，但 Cursor 自报成功不替代 shell verification。
+
 > **Historical（已移除）**：`subagent list|start|wait|wakeup|attach|stop` 与 `dashboard` 已移除，不再出现在 CLI registry。

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

@@ -1,15 +1,15 @@
 # Shared loop-agent Harness Policy
 
-This file is the canonical shared workflow policy for using `.` across repositories. Repo-local harness docs should only describe local adapters: where the runtime lives, which governance root to use, and which verification commands apply.
+本文件是跨仓库使用 `.` 的 canonical shared workflow policy。Repo-local harness docs 只应描述 local adapters：runtime 位置、governance root、适用的 verification commands。
 
 ## Canonical stance
 
-- **Agent DAG** is the default implementation workflow for medium/large, multi-file, architecture-sensitive, public-contract, CI/script, or harness-runtime work.
-- The historical sequential `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow has been removed. Do not present it as a fallback path.
-- **Long-running `loop`** is an outer state/evidence layer above Agent DAG. It records rounds, context compression, signals, and canonical refs; it must not replace DAG writeSet review, Decision Gate, or shell verification for complex work.
-- **Main session** orchestrates: choose one work chunk, prepare source materials, review DAG/writeSet, monitor failures, run final verification, and hand off.
-- **Executors** implement bounded work: Cursor writes within explicit paths, Pi performs read-only planning/review/diagnosis in DAG nodes, shell produces deterministic verification facts.
-- **Shell verification is the completion fact source**. LLM review or advisory output cannot replace command exit codes and archived evidence.
+- **Agent DAG** 是 medium/large、multi-file、architecture-sensitive、public-contract、CI/script 或 harness-runtime 工作的默认 implementation workflow。
+- 历史顺序式 `run analyze|plan|spec|implement|verify|auto|loop|continue` workflow 已移除。不要将其作为 fallback path 呈现。
+- **Long-running `loop`** 是 Agent DAG 之上的 outer state/evidence layer。它记录 rounds、context compression、signals、canonical refs；不得替代 complex work 的 DAG writeSet review、Decision Gate 或 shell verification。
+- **Main session** 负责 orchestrate：选一个 work chunk、准备 source materials、review DAG/writeSet、monitor failures、跑 final verification、hand off。
+- **Executors** 实现 bounded work：Pi 在 DAG nodes 做 read-only planning/review/diagnosis，并在节点声明 `toolProfile: "write"` 时做 bounded implementation/repair；Cursor 是显式启用的可选 bounded writer；shell 产出 deterministic verification facts。
+- **Shell verification 是 completion fact source**。LLM review 或 advisory output 不能替代 command exit codes 与 archived evidence。
 
 ## Command surface tiers
 
@@ -21,7 +21,7 @@ This file is the canonical shared workflow policy for using `.` across repositor
 | Escape hatch | Isolated delegation, one-shot diagnosis or bounded repair | `delegate`, `worktree`, `harvest`, `pi-prompt`, `cursor-prompt`, `cursor-worker` |
 | Experimental | Long-running outer task state | `loop init|status|run|record-round|add-signal|closeout` |
 
-Prompt templates, README snippets, and task instructions should present Primary + Operator first. Compatibility and escape-hatch commands remain available, but must carry their downgrade/fallback meaning.
+Prompt templates、README snippets、task instructions 应优先呈现 Primary + Operator。Compatibility 与 escape-hatch commands 仍可用，但须携带其 downgrade/fallback 含义。
 
 ## Entry selection decision tree
 
@@ -33,7 +33,7 @@ Is this only status, diagnosis, recovery, or closeout?
            yes -> Agent DAG.
 ```
 
-Use Agent DAG rather than broad one-shot execution when any of these signals apply:
+在以下任一 signal 适用时用 Agent DAG 而非 broad one-shot execution：
 
 - loop-agent runtime, DAG schema, run facts, promotion/closeout, scripts/CI, public contract, or shared protocol is touched.
 - The change needs multiple files, multiple scouts, review gates, Decision Gate, repair flow, or shell gate.
@@ -43,53 +43,53 @@ Use Agent DAG rather than broad one-shot execution when any of these signals app
 
 ## Agent DAG path
 
-Minimum governed path:
+Minimum governed path：
 
 ```bash
 loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
 # write <target-repo>/.harness/tasks/<task-id>/source/需求.md
 # write <target-repo>/.harness/tasks/<task-id>/source/执行约束.md
 
-loop-agent dag run-task <task-id> \
-  --profile auto \
-  --strict-models \
-  --output <temp-dir>/<task-id>-dag.json \
-  [--repo-root <target-repo>]
-
-loop-agent dag validate \
-  --dag <temp-dir>/<task-id>-dag.json \
-  --strict-models \
-  --strict-governance
-
-loop-agent run-dag \
-  --dag <temp-dir>/<task-id>-dag.json \
-  --cwd <target-repo>
-```
-
-`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
-
-The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
-
-For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
-
-`<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
-
-Before execution, review `dag run-task` JSON / `reviewPacket`:
-
-- `profileRouting`: requested profile, selected profile/template, routing reasons.
-- `governanceProfile`: process, delivery, and code-change signals.
-- Writer nodes: `writePolicy`, `writeSet`, `allowedPaths`, `forbiddenPaths`, broad entries, forbidden overlaps.
-- Shell gates and verification commands.
-- Decision Gate mode (`record-only` vs `pause-on-human`).
-- Any placeholder, `**`, or repo-root writeSet that must be narrowed before execution.
-
-In-flight DAG shell checks should use the repo's active-run override when required (for example `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`). After the DAG is archived, run the repo check again without the in-flight override.
-
-On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Do not require WSL, `/tmp`, `which`, or other POSIX filesystem assumptions in loop-agent CLI behavior.
+loop-agent dag run-task <task-id> \
+  --profile auto \
+  --strict-models \
+  --output <temp-dir>/<task-id>-dag.json \
+  [--repo-root <target-repo>]
+
+loop-agent dag validate \
+  --dag <temp-dir>/<task-id>-dag.json \
+  --strict-models \
+  --strict-governance
+
+loop-agent run-dag \
+  --dag <temp-dir>/<task-id>-dag.json \
+  --cwd <target-repo>
+```
+
+`loop-agent` is the preferred global CLI. For self-hosting loop-agent development, the controller must be an installed npm-published package. Use `npm install -g @tea-agent/loop-agent@latest` for first install or intentional upgrades, then treat the installed version as frozen for the current task and record `npm list -g @tea-agent/loop-agent --depth=0`. Do not repeatedly fetch `npx @latest` inside DAG nodes, and do not use the current working tree's `npm link` or `npm run dev` to control tasks that may edit CLI, DAG runtime, executors, package metadata, or build output. Use `npm run dev -- <args>` only for source debugging and focused CLI development.
+
+The npm package carries static capability assets: `skills/`, top-level governance docs, `docs/templates/`, `examples/`, `harness.json`, `AGENTS.md`, `README.md`, and `CHANGELOG.md`. Generated or historical task facts under `docs/progress/`, `docs/reports/`, `docs/exec-plans/`, and `docs/decisions/` belong to the target repository; package only their directory README files, not prior run content.
+
+For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to package-bundled `skills/` as the stable default capability set.
+
+`<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
+
+Execution 前 review `dag run-task` JSON / `reviewPacket`：
+
+- `profileRouting`：requested profile、selected profile/template、routing reasons。
+- `governanceProfile`：process、delivery、code-change signals。
+- Writer nodes：`writePolicy`、`writeSet`、`allowedPaths`、`forbiddenPaths`、broad entries、forbidden overlaps。
+- Shell gates 与 verification commands。
+- Decision Gate mode（`record-only` vs `pause-on-human`）。
+- 执行前须 narrow 的 placeholder、`**` 或 repo-root writeSet。
+
+In-flight DAG shell checks 在需要时用 repo active-run override（例如 `HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-repo.sh`）。DAG archived 后，再不带 in-flight override 跑 repo check。
+
+On Windows, run Bash scripts through Git Bash or a configured compatible Bash. Do not require WSL, `/tmp`, `which`, or other POSIX filesystem assumptions in loop-agent CLI behavior.
 
 ## Task source materials
 
-Every handoff-ready task has:
+每个 handoff-ready task 包含：
 
 ```text
 .harness/tasks/<task-id>/
@@ -99,25 +99,25 @@ Every handoff-ready task has:
     执行约束.md
 ```
 
-`需求.md` should state objective, scope, non-goals, acceptance criteria, and links to repo-local specs or plans.
+`需求.md` 应陈述 objective、scope、non-goals、acceptance criteria，并链接 repo-local specs 或 plans。
 
-`执行约束.md` should state:
+`执行约束.md` 应陈述：
 
 - allowed paths
 - forbidden paths
-- current dirty workspace / protected user changes, if any
-- architecture boundaries and invariants
+- 当前 dirty workspace / protected user changes（如有）
+- architecture boundaries 与 invariants
 - expected verification commands
 - acceptance criteria / failure conditions
-- whether DAG fallback is allowed, and the fallback reason if already known
+- 是否允许 DAG fallback，及若已知时的 fallback reason
 
-If source materials change after `spec`, `plan`, or DAG generation, regenerate or revalidate the plan/DAG before implementation.
+若 `spec`、`plan` 或 DAG generation 后 source materials 变更，implementation 前 regenerate 或 revalidate plan/DAG。
 
 ## Long-running loop policy
 
-`loop` is for long-running outer task memory: objective/context projection, round records, signals, derived events, verification summaries, and closeout draft. It is not a substitute for Agent DAG.
+`loop` 用于 long-running outer task memory：objective/context projection、round records、signals、derived events、verification summaries、closeout draft。它不是 Agent DAG 的 substitute。
 
-Typical loop path for governed work:
+Governed work 的典型 loop path：
 
 ```bash
 loop-agent loop init <task-id>
@@ -130,22 +130,22 @@ loop-agent loop run <task-id> --auto --max-rounds 3 --allow-cursor-fix
 loop-agent loop closeout <task-id>
 ```
 
-Loop action rules:
+Loop action rules：
 
-- `shell-verify` is deterministic; exit code determines the verification record.
-- `pi-review` is read-only; tools are limited to `read,grep,find,ls` and output is structured advisory evidence. Its structured JSON must include `findingSummary`, `failureCategory`, `nextHypothesis`, `recommendedAction`, `fixScope`, and `rootCause`; `recommendedAction` is exactly `implement_fix|replan|pause|done`.
-- `cursor-fix` is bounded write; it must read task `allowedPaths` / `forbiddenPaths`, reject empty `allowedPaths`, reject allowed/forbidden overlap, preserve unrelated files, and be followed by shell verification or review.
-- For `task.json.complexity = medium | large`, `cursor-fix` additionally requires either:
-  - a previous loop `dag` round, or
-  - an explicit `task.json.dagFallbackReason` explaining why DAG could not be used.
-- `loop run --auto` does not write by default. Auto `cursor-fix` requires `task.json.loopAutoWritePolicy="enabled"`, or `loopAutoWritePolicy="approval-required"` plus a pending approval signal or `--allow-cursor-fix`; write guards still fail closed and pause.
-- `loop closeout` must report workflow path: `dag`, `explicit-fallback`, `missing-dag-evidence`, or `micro-or-small`.
-- Medium/large closeout without DAG evidence and without `dagFallbackReason` must list that as a remaining risk.
-- `record-round --decision complete` is only a loop-state candidate; completion still requires shell verification, review verdict, and success-criteria coverage.
+- `shell-verify` 是 deterministic；exit code 决定 verification record。
+- `pi-review` 是 read-only；tools 限于 `read,grep,find,ls`，output 为 structured advisory evidence。Structured JSON 须含 `findingSummary`、`failureCategory`、`nextHypothesis`、`recommendedAction`、`fixScope`、`rootCause`；`recommendedAction`  exactly 为 `implement_fix|replan|pause|done`。
+- `cursor-fix` 是 bounded write；须读 task `allowedPaths` / `forbiddenPaths`，reject empty `allowedPaths`、allowed/forbidden overlap，preserve unrelated files，且须 follow shell verification 或 review。
+- 对 `task.json.complexity = medium | large`，`cursor-fix`  additionally 需要：
+  - previous loop `dag` round，或
+  - explicit `task.json.dagFallbackReason` 说明为何不能用 DAG。
+- `loop run --auto` 默认不 write。Auto `cursor-fix` 需要 `task.json.loopAutoWritePolicy="enabled"`，或 `loopAutoWritePolicy="approval-required"` 加 pending approval signal 或 `--allow-cursor-fix`；write guards 仍 fail closed 并 pause。
+- `loop closeout` 须报告 workflow path：`dag`、`explicit-fallback`、`missing-dag-evidence` 或 `micro-or-small`。
+- 无 DAG evidence 且无 `dagFallbackReason` 的 medium/large closeout 须将其列为 remaining risk。
+- `record-round --decision complete` 仅是 loop-state candidate；completion 仍须 shell verification、review verdict、success-criteria coverage。
 
 ## Supervised DAG convergence
 
-Supervised DAG convergence is optional and task-config driven:
+Supervised DAG convergence 可选且由 task-config 驱动：
 
 ```json
 {
@@ -160,13 +160,13 @@ Supervised DAG convergence is optional and task-config driven:
 
 Rules:
 
-- Default remains single repair unless `convergence.enabled=true`; `HARNESS_DAG_CONVERGENCE=off` is the rollback switch.
-- The supervised process supervisor must emit first-line `VERDICT:` and a `REPAIR_ARTIFACT_JSON` fenced block. Repair prompts should consume artifact `failureClass`, `rootCause`, `fixScope`, and `invariant` first; raw logs are fallback evidence only when the artifact allows it.
-- On retryable `hard-verify-shell` failure before `maxPasses`, preserve current pass evidence under `convergence/pass-N/`, reset the process-supervisor/process-gate/repair/hard-verify segment plus blocked downstream nodes, and re-enter the existing DAG rank execution loop.
-- Do not retry write guards, timeout/spawn/auth failures, or human-gate failures.
-- Pause instead of retrying when conservative regression signals appear, such as a lower shell success count.
-- `dag report --json` and markdown must expose `convergence.passHistory`.
-- Final completion authority remains full shell verification; quota/focused commands are intermediate cost controls only.
+- 默认保持 single repair，除非 `convergence.enabled=true`；`HARNESS_DAG_CONVERGENCE=off` 是 rollback switch。
+- Supervised process supervisor 须 emit 首行 `VERDICT:` 与 `REPAIR_ARTIFACT_JSON` fenced block。Repair prompts 应先消费 artifact `failureClass`、`rootCause`、`fixScope`、`invariant`；raw logs 仅在 artifact 允许时为 fallback evidence。
+- 在 `maxPasses` 前 retryable `hard-verify-shell` failure 时，preserve current pass evidence 于 `convergence/pass-N/`，reset process-supervisor/process-gate/repair/hard-verify segment 及 blocked downstream nodes，再进入现有 DAG rank execution loop。
+- 不要 retry write guards、timeout/spawn/auth failures 或 human-gate failures。
+- 出现 conservative regression signals（如 lower shell success count）时 pause 而非 retry。
+- `dag report --json` 与 markdown 须 expose `convergence.passHistory`。
+- Final completion authority 仍是 full shell verification；quota/focused commands 仅为 intermediate cost controls。
 
 ## Structured repair, spine audit, and curator gates
 
@@ -177,17 +177,17 @@ Rules:
 
 ## SePO-lite prompt evolution
 
-- Learned prompt deltas are human-gated proposals; they must be reviewed before becoming reusable guidance.
-- Prompt deltas are Markdown-only process guidance; they must not include shell commands, credential handling, tool permission expansion, or completion-authority bypass.
-- Accepted learned guidance lives under `./skill/references/learned/<repo>.md` or `default.md`.
-- DAG implementer prompts that already request `loop-agent` may inline at most three human-gated learned Markdown sections.
-- Learned guidance is advisory and never replaces writeSet governance, Decision Gate policy, or shell verification.
+- Learned prompt deltas 是 human-gated proposals；成为 reusable guidance 前须 review。
+- Prompt deltas 为 Markdown-only process guidance；不得含 shell commands、credential handling、tool permission expansion 或 completion-authority bypass。
+- Accepted learned guidance 位于 `./skill/references/learned/<repo>.md` 或 `default.md`。
+- 已 request `loop-agent` 的 DAG implementer prompts 可 inline 最多三个 human-gated learned Markdown sections。
+- Learned guidance 为 advisory，永不替代 writeSet governance、Decision Gate policy 或 shell verification。
 
 ## Sidecar interventions
 
-`pi-prompt` and `cursor-prompt` are sidecar interventions, not workflow state.
+`pi-prompt` 与 `cursor-prompt` 是 sidecar interventions，不是 workflow state。
 
-Use `pi-prompt` for short read-only planning, log explanation, or failure diagnosis. When read-only, pass read-only tools and say not to edit files:
+用 `pi-prompt` 做短时 read-only planning、log explanation 或 failure diagnosis。Read-only 时传 read-only tools 并写明不 edit files：
 
 ```bash
 loop-agent pi-prompt \
@@ -197,7 +197,7 @@ loop-agent pi-prompt \
   "Read the task source and diagnose the failure. Do not edit files."
 ```
 
-Use `cursor-prompt` for bounded multi-file diagnosis or small repair only when the prompt includes:
+用 `cursor-prompt` 做 bounded multi-file diagnosis 或 small repair，prompt 须含：
 
 - task id
 - exact objective
@@ -207,52 +207,52 @@ Use `cursor-prompt` for bounded multi-file diagnosis or small repair only when t
 - expected verification
 - instruction to preserve unrelated files
 
-Sidecar output is advisory. If it must become task evidence, promote or summarize it through loop-agent run/task artifacts; do not manually mutate completed DAG or one-shot run facts.
+Sidecar output 为 advisory。若须成为 task evidence，通过 loop-agent run/task artifacts promote 或 summarize；completed DAG 与 one-shot run facts 保持只读。
 
 ## Model and executor boundaries
 
-- Agent DAG uses DAG JSON `executorModels` plus node `executor` / `complexity`; do not infer DAG models from repo `harness.json.models`.
-- DAG `shell` and `static` nodes do not use models.
-- Historical step models under `harness.json.models.<step>` are legacy metadata, not routing for new DAG work.
-- `pi-prompt` / `cursor-prompt` models come from CLI flags or runtime defaults and must be selected per intervention.
-- Pi DAG nodes are read-only planning/review/diagnosis by default.
-- Cursor nodes are bounded writers and must have explicit write scope.
-- Shell nodes produce deterministic verification facts and gates.
+- Agent DAG 用 DAG JSON `executorModels` 加 node `executor` / `complexity`；不要从 repo `harness.json.models` 推断 DAG models。
+- DAG `shell` 与 `static` nodes 不用 models。
+- `harness.json.models.<step>` 下 historical step models 是 legacy metadata，不是新 DAG work 的 routing。
+- `pi-prompt` / `cursor-prompt` models 来自 CLI flags 或 runtime defaults，须 per intervention 选择。
+- Pi DAG nodes 默认 read-only planning/review/diagnosis；声明 `toolProfile: "write"` 时是 bounded writers，须有 explicit write scope。
+- Cursor nodes 是显式启用的可选 bounded writers，须有 explicit write scope。
+- Shell nodes 产出 deterministic verification facts 与 gates。
 
 ## Artifacts and facts boundary
 
-- `.harness/tasks/<task-id>/` is task runtime state.
-- `.harness/tasks/<task-id>/loop/` is loop runtime projection; it does not replace task source or repo specs.
-- `.harness/dag-runs/{active,paused,completed}/<run-id>/` is DAG run fact storage. Completed facts are read-only.
-- `.harness/runs/{active,completed,failed}/<run-id>/` is one-shot Pi/Cursor evidence. Completed/failed facts are read-only.
-- Root `artifacts/` is legacy/current-work summary space, not a DAG read-only scratchpad and not default handoff for new DAG work.
-- Long-term conclusions belong in repo governance docs, progress, reports, decisions, tests, or scripts.
+- `.harness/tasks/<task-id>/` 是 task runtime state。
+- `.harness/tasks/<task-id>/loop/` 是 loop runtime projection；不替代 task source 或 repo specs。
+- `.harness/dag-runs/{active,paused,completed}/<run-id>/` 是 DAG run fact storage。Completed facts 为 read-only。
+- `.harness/runs/{active,completed,failed}/<run-id>/` 是 one-shot Pi/Cursor evidence。Completed/failed facts 为 read-only。
+- Root `artifacts/` 是 legacy/current-work summary space，不是 DAG read-only scratchpad，也不是新 DAG work 的 default handoff。
+- Long-term conclusions 属于 repo governance docs、progress、reports、decisions、tests 或 scripts。
 
-Do not submit runtime histories from `.harness/dag-runs/`, `.harness/runs/`, or `.harness/cache/` unless a task explicitly promotes a trimmed report into repo governance docs.
+除非 task 显式 promote trimmed report 到 repo governance docs，不要提交 `.harness/dag-runs/`、`.harness/runs/` 或 `.harness/cache/` 的 runtime histories。
 
 ## Baseline, dirty workspace, and verification
 
-Before complex implementation:
+Complex implementation 前：
 
-1. Check current directory and target repo.
-2. Read repo entrypoints (`README`, `AGENTS`, `harness.json`, governance index).
-3. Capture minimal baseline verification for the affected area.
-4. If the workspace is dirty, choose one:
-   - isolated worktree, or
-   - explicit user confirmation to work in the current workspace and preserve/possibly include existing changes.
-5. Record known baseline failures with enough detail to distinguish pre-existing failures from task regressions.
+1. Check current directory 与 target repo。
+2. Read repo entrypoints（`README`、`AGENTS`、`harness.json`、governance index）。
+3. Capture affected area 的 minimal baseline verification。
+4. 若 workspace dirty，选一：
+   - isolated worktree，或
+   - explicit user confirmation 在当前 workspace 工作并 preserve/possibly include existing changes。
+5. Record known baseline failures，足以区分 pre-existing failures 与 task regressions。
 
-Verification should be selected from the target repo's verification matrix. For cross-repo documentation refactors, run checks in each affected repo.
+Verification 应从 target repo verification matrix 选择。Cross-repo documentation refactors 时在 each affected repo 跑 checks。
 
 ## Handoff requirements
 
-Every task handoff should answer:
+每个 task handoff 应回答：
 
-1. What changed and why.
-2. Which workflow path was used: DAG, sidecar, or main-session surgical patch.
-3. If downgraded from DAG, the explicit reason and evidence.
-4. Executors used and their boundaries.
-5. Verification commands run and results.
-6. DAG / one-shot / loop refs, if any.
-7. Remaining risks and follow-up tasks.
-8. Whether new rules should be promoted to docs, tests, scripts, or shared skill references.
+1. What changed and why。
+2. 用了哪条 workflow path：DAG、sidecar 或 main-session surgical patch。
+3. 若从 DAG downgrade，explicit reason 与 evidence。
+4. Executors used 及其 boundaries。
+5. Verification commands run 与 results。
+6. DAG / one-shot / loop refs（如有）。
+7. Remaining risks 与 follow-up tasks。
+8. 是否应将 new rules promote 到 docs、tests、scripts 或 shared skill references。