@tea-agent/loop-agent 0.1.0

package/examples/hybrid-loop-agent-dag.json

@@ -0,0 +1,194 @@
+{
+  "version": 2,
+  "title": "Hybrid DAG 示例：Pi 只读契约 + 并行侦察 + Pi 写入实现",
+  "objective": "演示 v2 hybrid DAG：Pi 节点返回只读契约/审查结论，Pi 节点并行只读侦察，Pi writer 节点通过 toolProfile=write 独占实现。",
+  "successCriteria": [
+    "contract-pi 返回可审计的只读实现契约摘要",
+    "scout-src 与 scout-tests 并行只读侦察且互不写冲突",
+    "implement-core 仅在声明的 writeSet 内修改代码",
+    "review-pi 基于上游输出完成只读审查",
+    "verify-shell 归档确定性验证命令输出",
+    "dag validate 校验通过且 ranks 符合依赖拓扑"
+  ],
+  "globalConstraints": [
+    "Do not commit runtime traces under .harness/dag-runs/",
+    "Do not enable cross-node Pi runtime reuse by default",
+    "Preserve CODE_AGENT_PI_BACKEND=cli-only rollback for Pi nodes",
+    "Every task must explicitly declare executor; defaults.executor is schema-only and not a runtime fallback",
+    "Prefer same-rank parallel read-only scouts over serial chains when outputs are independent",
+    "Add depends_on only when a child truly needs upstream output; challenge single-chain topologies during review",
+    "Same-rank exclusive writeSet entries must be disjoint",
+    "exclusive implementer nodes must use narrow, concrete writeSet paths; never use ** or repo root",
+    "Cursor is optional; no-Cursor environments should use Pi read-only scouts and Pi writer nodes with toolProfile=write",
+    "Read-only nodes must not write root artifacts/**; root artifacts/ is reserved for Level 1/current-work summaries or explicit exclusive write nodes"
+  ],
+  "defaults": {
+    "executor": "pi",
+    "piBackend": "sdk-first",
+    "contextProfile": "slim",
+    "skills": [
+      "ai-engineering-context"
+    ],
+    "writePolicy": "read-only"
+  },
+  "skillsByRole": {
+    "planner": [
+      "loop-agent"
+    ],
+    "scout": [
+      "ai-engineering-context"
+    ],
+    "implementer": [
+      "verification-before-completion"
+    ],
+    "reviewer": [
+      "requesting-code-review"
+    ],
+    "verifier": [
+      "verification-before-completion",
+      "systematic-debugging"
+    ],
+    "closeout": [
+      "loop-agent",
+      "verification-before-completion"
+    ]
+  },
+  "executorModels": {
+    "cursor": {
+      "LOW": "composer-2.5",
+      "MED": "composer-2.5",
+      "HIGH": "composer-2.5"
+    },
+    "pi": {
+      "LOW": "gpt-5.3-codex-spark",
+      "MED": "glm-5.2",
+      "HIGH": "gpt-5.5"
+    }
+  },
+  "tasks": [
+    {
+      "id": "contract-pi",
+      "depends_on": [],
+      "role": "planner",
+      "executor": "pi",
+      "complexity": "MED",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**",
+        "docs/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown implementation contract summary; no file writes.",
+      "subtask_prompt": "阅读 ./README.md 与 docs/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
+    },
+    {
+      "id": "scout-src",
+      "depends_on": [
+        "contract-pi"
+      ],
+      "role": "scout",
+      "executor": "pi",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./src/workflows/dag/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown reconnaissance summary of DAG-related source modules; no file writes.",
+      "subtask_prompt": "只读审计 ./src/workflows/dag/ 中与 DAG 相关的模块，列出关键文件与职责（不要改文件）。"
+    },
+    {
+      "id": "scout-tests",
+      "depends_on": [
+        "contract-pi"
+      ],
+      "role": "scout",
+      "executor": "pi",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./test/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown test coverage gap summary; no file writes.",
+      "subtask_prompt": "只读审计 ./test/ 中与 dag-runner 相关的测试覆盖，列出缺口建议（不要改文件）。"
+    },
+    {
+      "id": "implement-core",
+      "depends_on": [
+        "scout-src",
+        "scout-tests"
+      ],
+      "role": "implementer",
+      "executor": "pi",
+      "complexity": "HIGH",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "./src/workflows/dag/runner.ts"
+      ],
+      "allowedPaths": [
+        "./src/workflows/dag/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Implementation summary with changed files, tests run, and residual risks.",
+      "subtask_prompt": "基于上游侦察结果，在 writeSet 范围内做最小必要改动并说明风险（若无需改动则输出 no-op 理由）。",
+      "toolProfile": "write"
+    },
+    {
+      "id": "review-pi",
+      "depends_on": [
+        "implement-core"
+      ],
+      "role": "reviewer",
+      "executor": "pi",
+      "complexity": "MED",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**",
+        "docs/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown review summary; no file writes.",
+      "subtask_prompt": "审查上游实现与侦察结论是否一致，列出范围漂移、验证缺口与残余风险（只读，不改文件/文档/artifacts）。"
+    },
+    {
+      "id": "verify-shell",
+      "depends_on": [
+        "implement-core"
+      ],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Archived shell verification stdout/stderr with exit codes; no worktree writes.",
+      "subtask_prompt": "Run deterministic loop-agent verification and archive command outputs.",
+      "shell": {
+        "preset": "loop-agent-standard-verify",
+        "cwd": ".",
+        "timeoutMs": 300000
+      }
+    }
+  ]
+}

package/harness.json

@@ -0,0 +1,92 @@
+{
+  "version": 1,
+  "project": "loop-agent",
+  "governanceRoot": "docs",
+  "workflowPolicy": {
+    "defaultImplementationWorkflow": "agent-dag",
+    "dag": {
+      "defaultEntry": "dag run-task",
+      "profileRouting": {
+        "minimal": "standard-dag",
+        "standard": "standard-dag",
+        "reviewed": "review-gated-dag",
+        "supervised": "supervised-implementation"
+      }
+    },
+    "humanGatePolicy": {
+      "defaultMode": "record-only",
+      "pauseOn": [
+        "requirement-ambiguity",
+        "architecture-or-public-contract-risk",
+        "credential-cost-or-deployment-risk",
+        "repeated-gate-failure",
+        "high-or-critical-decision-risk"
+      ]
+    }
+  },
+  "entrypoints": {
+    "readme": "README.md",
+    "agents": "AGENTS.md",
+    "governanceIndex": "docs/README.md",
+    "principles": "docs/development-principles.md",
+    "workflow": "docs/feature-workflow.md",
+    "verificationMatrix": "docs/verification-matrix.md",
+    "loopAgentHarness": "docs/loop-agent-harness.md",
+    "cursorExecutorUsage": "docs/cursor-executor-usage.md"
+  },
+  "artifacts": {
+    "templatesDir": "docs/templates",
+    "execPlansDir": "docs/exec-plans",
+    "progressDir": "docs/progress",
+    "reportsDir": "docs/reports",
+    "decisionsDir": "docs/decisions"
+  },
+  "scripts": {
+    "checkRepo": "scripts/check-repo.sh",
+    "checkStructure": "scripts/check-engineering-structure.sh",
+    "checkDocIndex": "scripts/check-doc-index.sh",
+    "checkDocLinks": "scripts/check-doc-links.sh",
+    "checkHarnessRuntimeClean": "scripts/check-harness-runtime-clean.sh",
+    "ci": "scripts/ci.sh"
+  },
+  "models": {
+    "analyze": {
+      "provider": "wizard-local",
+      "model": "gpt-5.3-codex-spark",
+      "timeoutMs": 1800000
+    },
+    "plan": {
+      "provider": "wizard-local",
+      "model": "gpt-5.3-codex-spark",
+      "timeoutMs": 1800000
+    },
+    "implement": {
+      "provider": "wizard-local",
+      "model": "gpt-5.3-codex-spark",
+      "timeoutMs": 1800000
+    },
+    "verify": {
+      "provider": "wizard-local",
+      "model": "gpt-5.3-codex-spark",
+      "timeoutMs": 1800000
+    },
+    "retrospective": {
+      "provider": "wizard-local",
+      "model": "gpt-5.3-codex-spark",
+      "timeoutMs": 1800000
+    }
+  },
+  "executors": {
+    "pi": {
+      "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
+      "defaultModel": "gpt-5.3-codex-spark",
+      "requiresApiKey": ""
+    },
+    "cursor": {
+      "description": "Cursor via @cursor/sdk (default model: account default)",
+      "enabled": false,
+      "defaultModel": "default",
+      "requiresApiKey": "CURSOR_API_KEY"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "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"
+  }
+}

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

@@ -0,0 +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.
+---
+
+# AI Engineering Context
+
+Context is an engineering artifact, not chat residue. Keep requirements, role boundaries, write authority, evidence, and handoff facts explicit.
+
+## 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.
+
+Do not use for private platform paths, personal memory, Google Drive rules, or replacing 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.
+
+If sources conflict, stop and name the conflict.
+
+## 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.
+
+## 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.
+
+Read-only nodes must return findings in node output only. They must not create scratch files in the repo.
+
+## 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.
+
+## 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.

package/skills/loop-agent/SKILL.md

@@ -0,0 +1,260 @@
+---
+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 实现.
+---
+
+# loop-agent Workflow
+
+这是 `loop-agent` 的入口文档。它只描述当前推荐入口，不再保留旧入口作为可选主路径。
+
+## 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.
+
+## 默认立场
+
+- 主入口是 **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`。
+- `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。
+- 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 约定。
+
+执行前必须审阅：
+
+- `profileRouting`
+- `governanceProfile`
+- writer `writeSet`
+- writer `forbiddenPaths`
+- shell verification commands
+- decision gate mode
+
+## 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
+
+需要写代码时，默认使用 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 都必须包含：
+
+- 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.
+
+## 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.
+
+## Source Layout
+
+新代码优先从这些目录进入：
+
+| 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/` |
+| Run records / promotion / closeout | `src/records/` |
+| Governance | `src/governance/` |
+| Shared helpers | `src/shared/` |
+| Repo adapters | `src/adapters/` |
+
+不要新增平行兼容入口。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.
+
+## References
+
+- `references/harness-policy.md`
+- `references/hybrid-dag.md`
+- `references/orchestrator-and-interventions.md`
+- `references/command-reference.md`
+- `references/task-workflow.md`
+- `references/pi-prompt.md`
+- `references/one-shot-runs.md`
+- `references/pi-subagent-assisted-mode.md`
+- `references/model-routing.md`
+- `references/multi-worktree.md`
+- `references/post-implementation-and-patterns.md`
+- `references/verification-and-failure-handling.md`