@tea-agent/loop-agent 0.2.0 → 0.3.0

package/package.json

@@ -1,62 +1,64 @@
-{
-  "name": "@tea-agent/loop-agent",
-  "version": "0.2.0",
-  "type": "module",
-  "bin": {
-    "loop-agent": "bin/loop-agent.js"
-  },
-  "files": [
-    "AGENTS.md",
-    "bin/",
-    "dist/",
-    "docs/*.md",
-    "docs/architecture/runtime-boundaries.md",
-    "docs/decisions/README.md",
-    "docs/design/README.md",
-    "docs/exec-plans/README.md",
-    "docs/exec-plans/active/README.md",
+{
+  "name": "@tea-agent/loop-agent",
+  "version": "0.3.0",
+  "type": "module",
+  "bin": {
+    "loop-agent": "bin/loop-agent.js"
+  },
+  "files": [
+    "AGENTS.md",
+    "bin/",
+    "dist/",
+    "docs/*.md",
+    "docs/architecture/runtime-boundaries.md",
+    "docs/decisions/README.md",
+    "docs/design/README.md",
+    "docs/exec-plans/README.md",
+    "docs/exec-plans/active/README.md",
     "docs/exec-plans/completed/README.md",
+    "docs/init-surface.manifest.json",
     "docs/progress/README.md",
     "docs/reports/README.md",
+    "docs/skills/",
     "docs/templates/",
-    "examples/",
-    "harness.json",
-    "skills/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "dev": "node --import tsx/esm src/cli.ts",
-    "cursor": "node --import tsx/esm src/cli.ts cursor-prompt",
-    "pi-prompt": "node --import tsx/esm src/cli.ts pi-prompt",
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
-    "lint": "tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "docs:dev": "npm --prefix website start",
-    "docs:build": "npm --prefix website run build",
-    "docs:serve": "npm --prefix website run serve",
-    "smoke:stale-serial": "tsx scripts/smoke-stale-plan-serial.ts"
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "zod": "^3.25.76"
-  },
-  "optionalDependencies": {
-    "@cursor/sdk": "^1.0.7",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*"
-  },
-  "devDependencies": {
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
-    "@types/node": "^24.6.0"
-  }
-}
+    "examples/",
+    "harness.json",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "node --import tsx/esm src/cli.ts",
+    "cursor": "node --import tsx/esm src/cli.ts cursor-prompt",
+    "pi-prompt": "node --import tsx/esm src/cli.ts pi-prompt",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "docs:dev": "npm --prefix website start",
+    "docs:build": "npm --prefix website run build",
+    "docs:serve": "npm --prefix website run serve",
+    "smoke:stale-serial": "tsx scripts/smoke-stale-plan-serial.ts"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "zod": "^3.25.76"
+  },
+  "optionalDependencies": {
+    "@cursor/sdk": "^1.0.7",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@types/node": "^24.6.0"
+  }
+}

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

@@ -0,0 +1,20 @@
+---
+name: code-review-core
+description: 用于只读 code review 节点，产出带文件与行号引用的优先级 findings。
+---
+
+# Code Review Core
+
+本 skill 用于 reviewer 节点。
+
+## Review 重点
+
+- 优先关注 correctness、行为回归、security、数据丢失与缺失验证。
+- findings 须 grounded 在具体文件与行号。
+- 区分 blocking findings 与次要 maintainability 备注。
+- 检查测试是否证明变更行为，文档是否与面向用户的变更一致。
+- 若无 findings，明确说明，并指出 residual test gap（如有）。
+
+## Output
+
+按 severity 排序列出 findings。仅当无 blocking findings 时，才写 `VERDICT: pass`。

package/skills/codebase-scout/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: codebase-scout
+description: 用于只读 scout 节点，在实现前定位现有代码、测试、文档与集成点。
+---
+
+# Codebase Scout
+
+本 skill 用于 scout 节点。
+
+## 规则
+
+- 从 repo 指令、task source 与邻近测试入手。
+- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
+- 在提议新抽象前，识别现有 helper 与 ownership 边界。
+- 只返回事实，不做编辑。
+
+## Output
+
+列出相关文件、现有模式、风险，以及实现所需的最小 write surface。

package/skills/init-capability-evolution/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: init-capability-evolution
+description: 用于 loop-agent 本仓库的初始化能力演化审查，判断代码、skill、模板、包范围或 DAG 默认能力变化是否需要同步更新目标项目 init surface。
+---
+
+# Init Capability Evolution
+
+本 skill 用于 loop-agent 本仓库。当变更可能影响 `loop-agent init` 初始化其他项目的能力时使用。
+
+## Goal
+
+让模型自行判断并维护初始化能力，而不是依赖人工记忆：
+
+- 新能力是否应该进入目标项目。
+- 新增/修改的 skill 是否应随 npm 包和 `init --profile full` 投影。
+- 目标项目的 `AGENTS.md`、README managed block、治理 docs、scripts 或 templates 是否需要更新。
+- `package.json files` 与 `docs/init-surface.manifest.json` 是否仍覆盖真实发布范围。
+- 是否需要目标项目 smoke、init doctor、docs audit 或 package dry-run 证据。
+
+## Trigger Tiers
+
+按 `docs/init-surface.manifest.json` 的 `evolutionReview.tiers` 判断成本：
+
+- `advisory`：只记录提示，不阻塞。
+- `surface-check`：运行 `bash scripts/check-init-surface.sh`；通过即可。
+- `model-review`：写一份简短 init evolution review，必要时修改 init surface、包范围、文档、skill 或测试。
+
+不要把小改动升级成重流程。只有当变化可能改变目标项目初始化体验、默认 DAG 行为、skill resolution、发布包边界或 init 生成物时，才进入 model-review。
+
+## Review Questions
+
+审查时逐条回答：
+
+1. 本次变更会改变目标项目执行 `loop-agent init --profile full --merge` 后得到的文件、规则或能力吗？
+2. 是否新增、删除或重命名了 `skills/**`，并且目标项目需要 repo-local 可审计副本？
+3. 是否改变了默认 DAG role skills、skill resolution、strict skill audit 或 task prompt 注入？
+4. 是否新增通用治理模板、script matrix、production readiness 或 operator recovery 文档，需要目标项目初始化后可见？
+5. `package.json files` 是否包含所有 npm 运行和初始化所需静态资料？
+6. `docs/init-surface.manifest.json` 是否更新了 package / init / exclude / trigger contract？
+7. 旧目标项目是否只需 advisory、需要手工复制新增文件，还是需要未来 `init audit/update` 迁移能力？
+
+## Output
+
+轻量审查可以只在 handoff 中说明。高影响审查应写入：
+
+```text
+docs/reports/YYYY-MM-DD-init-evolution-review.md
+```
+
+报告保持短小，包含：
+
+- changed surface
+- decision: no init impact / surface check only / init update required
+- files updated
+- verification commands and results
+- residual risk
+
+## Required Verification
+
+按影响面选择最小命令：
+
+```bash
+bash scripts/check-init-surface.sh
+bash scripts/check-repo.sh
+npm test -- init-command dag-skills dag-validate-command
+npm pack --dry-run --ignore-scripts
+```
+
+如果没有新鲜验证证据，不要宣称 init evolution 已完成。

package/skills/loop-agent/SKILL.md

@@ -60,38 +60,38 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 
 短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`：
 
-- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
-- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
-- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
-
-## Bounded Write Execution
-
-需要写代码时，默认使用 DAG `pi` executor 的 write tool profile。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
-
-Cursor 只作为显式启用的可选 bounded write backend。调用示例与细节见 `references/pi-prompt.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
-
-Pi writer prompt 与 Cursor prompt 都必须包含：
+- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
+- 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
+- 输出是 advisory，不能替代 deterministic verification；发现必须写回 task source、report、progress 或 exec plan。
+
+## Bounded Write Execution
+
+需要写代码时，默认使用 DAG `pi` executor 的 write tool profile。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
+
+Cursor 只作为显式启用的可选 bounded write backend。调用示例与细节见 `references/pi-prompt.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
+
+Pi writer prompt 与 Cursor prompt 都必须包含：
 
 - task id
 - exact objective
 - allowed paths
 - forbidden paths
-- hard constraints
-- expected verification
-- instruction to preserve unrelated files
-
-bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
+- hard constraints
+- expected verification
+- instruction to preserve unrelated files
+
+bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
 
 ## 进阶主题路由
 
-以下主题只在 references 中维护细节，不在本文展开：
-
-| 主题 | Reference |
-|---|---|
-| Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
-| Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
-| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
-| Post-Cursor 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
+以下主题只在 references 中维护细节，不在本文展开：
+
+| 主题 | Reference |
+|---|---|
+| Long-Running Loop（`loop` init/status/run/record-round/add-signal/closeout、auto mode、signals） | `references/long-running-loop.md` |
+| Three-Pass Convergence、repair artifact、spine audit、knowledge curate、SePO-lite prompt evolution | `references/harness-policy.md` |
+| Operator commands（status/doctor/report/closeout/promote/inspect/spine/knowledge/docs/handoff） | `references/command-reference.md` |
+| Post-Cursor 独立验证、verify knobs、failure handling、closeout | `references/verification-and-failure-handling.md` |
 
 ## Source Layout
 
@@ -111,17 +111,17 @@ bounded writer 完成后，主会话必须独立复核；命令清单见 `refere
 
 不要新增平行兼容入口。CLI public export 的唯一入口是 `src/cli/index.ts`；commander command tree 和 help 实现在 `src/cli/program.ts`。
 
-## Hard Rules
-
-1. One task = one bounded work chunk.
-2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`.
-3. Agent DAG is the implementation workflow.
-4. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
-5. Pi writer nodes and optional Cursor write execution must be bounded by explicit allowed / forbidden paths.
-6. Completed DAG and one-shot run facts are read-only.
-7. Do not write root `artifacts/` from read-only DAG or sidecar steps.
-8. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
-9. Verify before completion.
+## Hard Rules
+
+1. One task = one bounded work chunk.
+2. Source materials are mandatory: `source/需求.md` and `source/执行约束.md`.
+3. Agent DAG is the implementation workflow.
+4. DAG `pi` executor stays read-only unless the node sets `toolProfile: "write"`; `pi-prompt` / `cursor-prompt` are full-capability one-shot helpers and must be bounded per call.
+5. Pi writer nodes and optional Cursor write execution must be bounded by explicit allowed / forbidden paths.
+6. Completed DAG and one-shot run facts are read-only.
+7. Do not write root `artifacts/` from read-only DAG or sidecar steps.
+8. Do not keep hidden workflow state in chat only; write durable conclusions to repo artifacts.
+9. Verify before completion.
 
 ## References
 

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

@@ -2,52 +2,53 @@
 
 需要 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`：
-
+## 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 --version
 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 说明。
-
-## 命令参考
+
+一次自举任务启动后不要中途升级控制器；记录 `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`。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
+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,12 +61,14 @@ 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（首次）
+### Setup（首次）
 ```bash
 npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
 loop-agent --help
 ```
 
@@ -75,10 +78,10 @@ loop-agent inspect                                           # 当前 repo（自
 loop-agent --repo-root /path/to/target-repo inspect           # 指定 repo
 ```
 
-### 健康检查
-```bash
-loop-agent doctor
-```
+### 健康检查
+```bash
+loop-agent doctor
+```
 
 `doctor` 报告当前生效的 Pi backend 及 SDK/CLI 可用性。Pi step 默认 SDK-first 执行：
 
@@ -87,11 +90,26 @@ export CODE_AGENT_PI_BACKEND=sdk-first   # 默认：先试 Pi SDK，允许时 fa
 export CODE_AGENT_PI_BACKEND=cli-only    # 紧急回滚：纯 CLI 路径
 ```
 
-SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
-
-### 创建新 task
-```bash
-loop-agent new-task <task-id> "Task Title"
+SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback 路径须与现有 workflow 行为兼容。
+
+### 初始化与旧项目更新
+```bash
+loop-agent init instructions --repo-root <target-repo>
+loop-agent init --repo-root <target-repo> --profile full --merge
+loop-agent init doctor --repo-root <target-repo>
+loop-agent init check-update --repo-root <target-repo> --json
+loop-agent init check-update --repo-root <target-repo> --markdown
+loop-agent init update --repo-root <target-repo> --bootstrap-surface
+loop-agent init update --repo-root <target-repo> --apply-safe
+```
+
+`init check-update` 是只读升级报告，用于发现目标项目是否落后于当前包内初始化 surface。输出会区分 deterministic actions、model merge tasks、human decisions 和 recommended next。`--markdown` 会渲染可直接交给模型执行的合并指引，包含 `allowedPaths`、`forbiddenPaths`、`mergeRules` 和 `verification`。
+
+`init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；已有但无法确认与当前包一致的文件会进入 model merge tasks，不会被覆盖。
+
+### 创建新 task
+```bash
+loop-agent new-task <task-id> "Task Title"
 ```
 
 创建 `.harness/tasks/<task-id>/`，含 `source/`、`artifacts/`、`logs/` 及初始 state。
@@ -141,9 +159,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 +170,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 +201,18 @@ 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-skills # missing/error/truncated skill 或 unresolved reference 时失败
+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 +239,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 +253,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 +297,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 +319,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 +363,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。