@tea-agent/loop-agent 0.1.0 → 0.2.0

package/skills/loop-agent/SKILL.md

@@ -2,41 +2,50 @@
 name: loop-agent
 description: >-
   Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG, run-dag, pi-prompt planning/review, or Cursor bounded implementation in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, 结构化开发, 工作流, 需求实现, PRD 实现.
+references:
+  - path: references/harness-policy.md
+    required: true
+  - path: references/hybrid-dag.md
+    required: true
+  - path: references/verification-and-failure-handling.md
+    required: true
+  - path: references/command-reference.md
+    required: true
 ---
 
 # loop-agent Workflow
 
-这是 `loop-agent` 的入口文档。它只描述当前推荐入口，不再保留旧入口作为可选主路径。
+这是 `loop-agent` 的入口文档，只负责 trigger、routing 和硬规则。较长的 command details、workflow 细节与失败处理放在 `references/`，按需加载。
 
 ## Canonical Harness Policy
 
-Shared loop-agent harness workflow rules live in `references/harness-policy.md`. Repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` files should stay thin adapters for local runtime path, governance root, and verification commands.
+Shared loop-agent harness workflow 规则见 `references/harness-policy.md`。Repo-local `docs/loop-agent-harness.md` / `specs/loop-agent-harness.md` 应保持为 local runtime path、governance root、verification commands 的 thin adapters。
 
 ## 默认立场
 
 - 主入口是 **Agent DAG**。
 - 主会话负责编排、审 writeSet、复核验证与 handoff。
-- DAG `pi` executor 默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
+- DAG `pi` executor 默认用于 read-only planning / review / diagnosis；当节点声明 `toolProfile: "write"` 时用于 bounded implementation / repair；Pi 模型矩阵保持 LOW=`gpt-5.3-codex-spark`、MED=`glm-5.2`、HIGH=`gpt-5.5`。
 - `pi-prompt` 与 `cursor-prompt` 都是一次性 full-capability helper；用作 sidecar 时必须在 prompt 和 tool/model 参数里显式收窄。
-- Cursor 是显式启用的可选 bounded write backend；默认 no-Cursor DAG 使用 `executor: "pi"` + `toolProfile: "write"`，必须给出 allowed / forbidden paths。
+- Cursor 是显式启用的可选 bounded write backend；默认 no-Cursor DAG 使用 `executor: "pi"` + `toolProfile: "write"`，必须给出 allowed / forbidden paths。
 - Shell verification 是事实源；任何完成声明都必须有本轮命令输出。
 - 长期结论写回 `docs/exec-plans/`、`docs/reports/`、`docs/progress/` 或 `./skill/`。
 
 ## 唯一推荐执行路径
 
 ```bash
-loop-agent new-task <task-id> "Task Title"
-# write <repo-root>/.harness/tasks/<task-id>/source/需求.md
-# write <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
-
-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>
-```
-
-`loop-agent` 默认指 npm 上已发布的全局 CLI。自举迭代 loop-agent 本仓库时，首次安装或有意升级可用 `npm install -g @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 的任务。`npm run dev -- <args>` 只用于源码调试和聚焦 CLI 开发。
-
-`<temp-dir>` 表示平台原生临时目录。macOS 和 Windows 都应使用实际平台路径；`/` 只用于 repo refs、JSON/Markdown 证据 refs 和 glob 约定。
+loop-agent new-task <task-id> "Task Title"
+# write <repo-root>/.harness/tasks/<task-id>/source/需求.md
+# write <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
+
+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>
+```
+
+`loop-agent` 默认指 npm 上已发布的全局 CLI。自举迭代 loop-agent 本仓库时，首次安装或有意升级可用 `npm install -g @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 的任务。`npm run dev -- <args>` 只用于源码调试和聚焦 CLI 开发。
+
+`<temp-dir>` 表示平台原生临时目录。macOS 和 Windows 都应使用实际平台路径；`/` 只用于 repo refs、JSON/Markdown 证据 refs 和 glob 约定。
 
 执行前必须审阅：
 
@@ -47,181 +56,51 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 - shell verification commands
 - decision gate mode
 
-## Pi Sidecar
+## Pi Sidecar 入口规则
 
-短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`。作为只读 sidecar 时必须显式传只读 tools：
-
-```bash
-loop-agent pi-prompt \
-  --cwd ~/go/src/loop-agent \
-  --provider wizard-local \
-  --model glm-5.2 \
-  --tools read,grep,find,ls \
-  --timeout 2400000 \
-  "Read the task source and provide a concise implementation plan. Do not edit files."
-```
-
-规则：
-
-- `pi-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
+短时规划、审查、失败归因可使用 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。需要使用 Cursor 时：
-
-```bash
-loop-agent cursor-prompt \
-  --cwd ~/go/src/loop-agent \
-  --timeout 1800000 \
-  --model composer-2.5 \
-  "<bounded task prompt with allowedPaths and forbiddenPaths>"
-```
-
-Cursor prompt 与 Pi writer prompt 都必须包含：
+
+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 完成后，主会话必须独立执行：
-
-```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>
-```
-
-## Operator Commands
-
-运行状态、恢复和收口只使用这些 operator 面：
-
-```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 promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
-loop-agent inspect
-loop-agent doctor
-loop-agent spine audit <task-id> --markdown
-loop-agent knowledge curate --markdown
-loop-agent loop-benchmark --markdown
-loop-agent docs audit
-loop-agent handoff check <task-id>
-```
-
-## Long-Running Loop
-
-`loop` 是 experimental outer workflow state，用于跨多轮记录目标、压缩记忆和 round facts 引用。它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。
-
-当前已可用的最小入口：
-
-```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。
-- `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`。
-- `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，不会绕过写入边界。
-- `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。
-- `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。
-- `events.jsonl` 只用于 observability，覆盖 loop_start、round_start、action_start、action_finish、context_rewrite、decision、loop_finish；不要把 events 当状态源。
-- auto mode 遇到同类 failure streak 达阈值会 blocked，避免无限重试。
-- 完成声明仍必须由 shell verification、review verdict 和 success criteria coverage 证明。
-
-## Three-Pass Convergence
-
-Supervised DAG convergence is opt-in through task config:
-
-```json
-{
-  "convergence": {
-    "enabled": true,
-    "maxPasses": 3,
-    "stopOnHardVerifyPass": true,
-    "pauseOnRegression": true
-  }
-}
-```
-
-Rules:
-
-- The feature flag `HARNESS_DAG_CONVERGENCE=off` disables DAG convergence and restores single-repair behavior.
-- `process-supervisor-pi` output must include first-line `VERDICT:` plus a `REPAIR_ARTIFACT_JSON` fenced block; `repair-pi` / optional `repair-cursor` should use artifact `failureClass`, `rootCause`, `fixScope`, and `invariant` before raw logs.
-- When `hard-verify-shell` fails with a retryable category and `currentPass < maxPasses`, the runner preserves current pass artifacts under `convergence/pass-N/`, resets the supervisor/process-gate/repair/hard-verify segment plus blocked downstream nodes, and re-enters the DAG ranks.
-- `write-guard`, timeout, spawn/auth, and human-gate failures do not auto-retry.
-- Regression signals such as lower shell success count pause the run as `convergence-regression`.
-- `dag report --json` / markdown exposes `convergence.passHistory`.
-- Final completion still requires full shell verification; intermediate quota/focused checks are cost controls only.
-
-## Repair Artifact / Spine / Knowledge
-
-- `process-supervisor-pi` output for gated supervised DAGs must include first-line `VERDICT:` plus a `REPAIR_ARTIFACT_JSON` fenced block.
-- `process-gate-shell` may set `shell.repairArtifactGate.fromNodeId`; the runner fails closed when the artifact is missing, schema-invalid, or its `fixScope` escapes the downstream repair writer allowedPaths/writeSet.
-- `spine audit <task-id>` checks minimal spec spine evidence: source files, path ownership, allowed/forbidden overlap, requirement coverage, and final verification command labels.
-- `dag validate --strict-governance --spine-task <task-id>` consumes the same spine audit and fails on error findings.
-- `knowledge curate` turns completed convergence patterns into a human-gated learned guidance proposal and runs skill safety preflight; it never edits accepted learned guidance directly.
+- hard constraints
+- expected verification
+- instruction to preserve unrelated files
+
+bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
 
-## SePO-Lite Prompt Evolution
+## 进阶主题路由
 
-- Learned prompt deltas are human-gated proposals under task source or skill references.
-- Prompt deltas must be Markdown-only process guidance; they must not add shell commands, credential handling, tool permission expansion, or completion-authority bypass rules.
-- Accepted learned patterns live in `./skill/references/learned/<repo>.md` or `default.md`.
-- DAG implementer prompts that already request the `loop-agent` skill may inline up to three learned Markdown sections as bounded guidance.
-- Learned guidance is advisory and cannot replace shell verification or write governance.
+以下主题只在 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
 
 新代码优先从这些目录进入：
 
-| Area | Entry |
-|---|---|
-| CLI command tree / help / commander program | `src/cli/` |
-| DAG workflow | `src/workflows/dag/` |
+| Area | Entry |
+|---|---|
+| CLI command tree / help / commander program | `src/cli/` |
+| DAG workflow | `src/workflows/dag/` |
 | Long-running loop workflow | `src/workflows/loop/` |
 | Task runtime | `src/task/` |
 | Executors | `src/executors/` |
@@ -230,26 +109,33 @@ Rules:
 | Shared helpers | `src/shared/` |
 | Repo adapters | `src/adapters/` |
 
-不要新增平行兼容入口。CLI public export 的唯一入口是 `src/cli/index.ts`；commander command tree 和 help 实现在 `src/cli/program.ts`。
+不要新增平行兼容入口。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.
+## 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.
+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
 
+Required（frontmatter 已声明）：
+
 - `references/harness-policy.md`
 - `references/hybrid-dag.md`
-- `references/orchestrator-and-interventions.md`
+- `references/verification-and-failure-handling.md`
 - `references/command-reference.md`
+
+Optional（按需加载）：
+
+- `references/orchestrator-and-interventions.md`
+- `references/long-running-loop.md`
 - `references/task-workflow.md`
 - `references/pi-prompt.md`
 - `references/one-shot-runs.md`
@@ -257,4 +143,3 @@ Rules:
 - `references/model-routing.md`
 - `references/multi-worktree.md`
 - `references/post-implementation-and-patterns.md`
-- `references/verification-and-failure-handling.md`

package/skills/loop-agent/references/README.md

@@ -25,6 +25,9 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 | 解释 `.harness/runs/`、one-shot evidence、active 残留或 promotion | `one-shot-runs.md` |
 | 多 worktree 并行委派、delegate/harvest | `multi-worktree.md` |
 | 模型、provider、profile、fallback routing | `model-routing.md` |
+| Long-running `loop` 命令、action 规则、auto mode、signals、loop closeout | `long-running-loop.md` |
+| Three-pass convergence、repair artifact / spine audit / knowledge curate、SePO-lite prompt evolution | `harness-policy.md` |
+| Cursor bounded write 后的独立复核、verify knobs、failure handling | `verification-and-failure-handling.md` |
 
 ## Reference 索引
 
@@ -41,7 +44,8 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 | `model-routing.md` | 查看或修改 model/provider 默认、profile、routing 或 fallback 行为 |
 | `post-implementation-and-patterns.md` | 处理 post-verify handoff、PRD item 拆分、fast bounded task、quick status 或 Pi timeout |
 | `multi-worktree.md` | 用 isolated worktree、`delegate` 与 `harvest` 并发执行互不重叠的 independent task |
-| `verification-and-failure-handling.md` | 选择 verify knob、解释 failure mode、执行 completion audit 与 closeout |
+| `verification-and-failure-handling.md` | 选择 verify knob、Cursor bounded write 后的独立复核、解释 failure mode、执行 completion audit 与 closeout |
+| `long-running-loop.md` | 使用 experimental long-running `loop` outer state：命令入口、action 规则、auto mode 写入边界、signals 与 loop closeout |
 
 ## 边界与状态源
 
@@ -56,7 +60,7 @@ failure handling 与 workflow 细节放在这里，避免主 skill 变成百科
 ## 维护规则
 
 - 不要把长段落复制回 `SKILL.md`；需要新增细节时，在本目录新增或更新 reference，并在 `SKILL.md` 添加 routing row。
-- 让 `SKILL.md` 保持约 200-300 行以内；reference 文件承担细节。
+- 让 `SKILL.md` 保持 120-180 行以内；reference 文件承担细节。
 - 新 reference 应有清晰标题、触发场景、最小步骤、失败处理和维护边界。
 - 如果某个 reference 变成可独立触发、跨项目通用且不再依赖本仓库上下文，再考虑拆成独立 skill。
 - 更新 command、workflow policy 或 verification 规则时，同步核对 `harness.json`、`references/harness-policy.md`、repo-local harness adapter docs 和 verification matrix。