@tea-agent/loop-agent 0.1.0 → 0.2.1

package/package.json

@@ -1,61 +1,62 @@
-{
-  "name": "@tea-agent/loop-agent",
-  "version": "0.1.0",
-  "type": "module",
-  "bin": {
-    "loop-agent": "bin/loop-agent.js"
-  },
-  "files": [
-    "AGENTS.md",
-    "bin/",
-    "dist/",
-    "docs/*.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/progress/README.md",
-    "docs/reports/README.md",
-    "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"
-  }
-}
+{
+  "name": "@tea-agent/loop-agent",
+  "version": "0.2.1",
+  "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/progress/README.md",
+    "docs/reports/README.md",
+    "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"
+  }
+}

package/skills/ai-engineering-context/SKILL.md

@@ -1,48 +1,48 @@
 ---
 name: ai-engineering-context
-description: Use when an AI coding agent starts loop-agent work, prepares DAG or Loop context, delegates role-specific nodes, or decides where requirements, facts, evidence, and handoff notes belong.
+description: 当 AI coding agent 启动 loop-agent 工作、准备 DAG 或 Loop context、委派 role-specific 节点，或决定 requirements、facts、evidence、handoff notes 应落何处时使用。
 ---
 
 # AI Engineering Context
 
-Context is an engineering artifact, not chat residue. Keep requirements, role boundaries, write authority, evidence, and handoff facts explicit.
+Context 是工程 artifact，不是 chat 残留。须显式保留 requirements、role 边界、write authority、evidence 与 handoff facts。
 
 ## When to Use
 
-Use when starting a task, DAG, workflow, or Loop round; preparing role prompts; delegating to Cursor/Pi/shell/static executors; or handling stale plans, conflicting requirements, or missing evidence.
+在启动 task、DAG、workflow 或 Loop round；准备 role prompt；委派给 Cursor/Pi/shell/static executor；或处理 stale plan、冲突 requirements、缺失 evidence 时使用。
 
-Do not use for private platform paths, personal memory, Google Drive rules, or replacing task skills.
+不要用于 private platform paths、personal memory、Google Drive 规则，或替代 task skills。
 
 ## Context Priority
 
-Prefer facts in this order: latest user instruction; task source/contract; DAG/Loop artifacts; docs/plans/ADRs; code/tests; chat history as hints only.
+按以下顺序优先采信 facts：最新 user instruction；task source/contract；DAG/Loop artifacts；docs/plans/ADRs；code/tests；chat history 仅作 hint。
 
-If sources conflict, stop and name the conflict.
+若 sources 冲突，停止并点明冲突。
 
 ## Role Boundaries
 
-- Planner: contract, DAG shape, write boundary, verification plan; no implementation edits.
-- Scout: code/test/doc/artifact facts; no repo writes.
-- Implementer: bounded changes inside writeSet; no scope widening or completion claims.
-- Reviewer: bugs, regressions, missing tests, risk; no rewrites unless assigned.
-- Verifier: command evidence, reproduction, failure category; model judgment is not proof.
-- Supervisor: gates, escalation, repair scope; no write-guard or human-gate bypass.
-- Closeout: evidence, risks, next steps; no hidden failures.
+- Planner：contract、DAG shape、write boundary、verification plan；不做 implementation edits。
+- Scout：code/test/doc/artifact facts；不写 repo。
+- Implementer：在 writeSet 内做 bounded changes；不扩大 scope 或宣称完成。
+- Reviewer：bugs、regressions、missing tests、risk；除非被指派，否则不重写。
+- Verifier：command evidence、reproduction、failure category；model judgment 不是 proof。
+- Supervisor：gates、escalation、repair scope；不绕过 write-guard 或 human-gate。
+- Closeout：evidence、risks、next steps；不隐藏 failures。
 
 ## Prompt Contract
 
-Every delegated node prompt should include objective, task id, role, executor, allowed paths, forbidden paths, writeSet, upstream artifact refs, concise excerpts, output contract, expected evidence, non-goals, and stop conditions.
+每个 delegated node prompt 应包含：objective、task id、role、executor、allowed paths、forbidden paths、writeSet、upstream artifact refs、concise excerpts、output contract、expected evidence、non-goals、stop conditions。
 
-Read-only nodes must return findings in node output only. They must not create scratch files in the repo.
+read-only node 只能在 node output 返回 findings。不得在 repo 中创建 scratch files。
 
 ## Persistence Rules
 
-Requirements and constraints go in task `source/`. Execution state and node artifacts go in `.harness/`. Durable plans, reports, decisions go in `docs/`. Reusable process guidance goes in `skills/`. Chat is transient only.
+Requirements 与 constraints 写入 task `source/`。Execution state 与 node artifacts 写入 `.harness/`。Durable plans、reports、decisions 写入 `docs/`。可复用 process guidance 写入 `skills/`。Chat 仅 transient。
 
 ## Failure Handling
 
-- Missing context: run scout or read the durable source.
-- Ambiguous requirement: update the contract before implementation.
-- Verification failure: diagnose cause before changing code.
-- Missing skill instructions: treat as context defect; do not assume hidden behavior.
-- Missing fresh verification: do not close out.
+- Missing context：运行 scout 或读取 durable source。
+- Ambiguous requirement：implementation 前更新 contract。
+- Verification failure：改 code 前先 diagnose cause。
+- Missing skill instructions：视为 context defect；不要假设 hidden behavior。
+- Missing fresh verification：不要 close out。

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,42 +56,21 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
 - shell verification commands
 - decision gate mode
 
-## Pi Sidecar
-
-短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`。作为只读 sidecar 时必须显式传只读 tools：
+## Pi Sidecar 入口规则
 
-```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."
-```
-
-规则：
+短时规划、审查、失败归因可使用 full-capability `pi-prompt`，默认模型是 `glm-5.2`：
 
-- `pi-prompt` 本身具备完整能力；只读 sidecar 必须使用 `--tools read,grep,find,ls` 并在 prompt 中写明不编辑文件。
+- 只读 sidecar 必须显式传 `--tools read,grep,find,ls`，并在 prompt 中写明不编辑文件。
 - 高复杂度 one-shot 诊断可显式加 `--model gpt-5.5`。
-- 输出是 advisory，不能替代 deterministic verification。
-- 发现必须写回 task source、report、progress 或 exec plan。
+- 输出是 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。
+需要写代码时，默认使用 DAG `pi` executor 的 write tool profile。Pi writer 节点必须包含 task id、目标、allowed paths、forbidden paths、writeSet、硬约束和预期验证，并在执行后由主会话独立运行 shell verification。
 
-Cursor 只作为显式启用的可选 bounded write backend。需要使用 Cursor 时：
+Cursor 只作为显式启用的可选 bounded write backend。调用示例与细节见 `references/pi-prompt.md`、`references/harness-policy.md` 和 `references/verification-and-failure-handling.md`。
 
-```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 都必须包含：
+Pi writer prompt 与 Cursor prompt 都必须包含：
 
 - task id
 - exact objective
@@ -92,136 +80,27 @@ Cursor prompt 与 Pi writer prompt 都必须包含：
 - 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>
-```
+bounded writer 完成后，主会话必须独立复核；命令清单见 `references/verification-and-failure-handling.md` 的 "Cursor bounded write 后的独立复核"。
 
-## Long-Running Loop
+## 进阶主题路由
 
-`loop` 是 experimental outer workflow state，用于跨多轮记录目标、压缩记忆和 round facts 引用。它不替代 Agent DAG，也不等同于已移除的顺序式 `run loop`。
+以下主题只在 references 中维护细节，不在本文展开：
 
-当前已可用的最小入口：
-
-```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.
-
-## 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.
+| 主题 | 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,15 +109,15 @@ 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.
-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.
+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.
@@ -246,10 +125,17 @@ Rules:
 
 ## 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。