@tea-agent/loop-agent 0.13.0 → 0.14.0

package/README.md

@@ -1,335 +1,339 @@
-# loop-agent
-
-`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
-
-它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 `.agents/skills/`、`ai_workspace/loop-agent/` 治理资料、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
-
-## 快速开始
-
-到一个新项目时，可以直接对当前 agent 说：
-
-```text
-请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
-```
-
-作为 CLI 使用时，安装已发布包：
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-loop-agent --version
-loop-agent --help
-```
-
-## 自动更新提醒
-
-通过 npm 全局安装的 `loop-agent` 会在普通交互式命令成功结束后检查 `@tea-agent/loop-agent` 是否有新版本。提醒只写入 `stderr`，不会污染命令原本的 `stdout`；失败命令、CI、管道/重定向、`--help`、`--version`、JSON/Markdown 输出以及 DAG/Loop/Delegate/Pi/Cursor 等 controller-sensitive 路径都会跳过。
-
-如果你拒绝版本 A，当前系统用户下不会再提醒 A；之后发布版本 B 时会继续提醒。确认更新时，CLI 会先证明当前安装来自同一 npm global root，然后安装刚确认的精确版本，例如：
-
-```bash
-npm install -g @tea-agent/loop-agent@0.13.0
-```
-
-需要完全关闭自动检查时设置：
-
-```bash
-LOOP_AGENT_DISABLE_UPDATE_CHECK=1
-```
-
-检查当前项目的 loop-agent 配置：
-
-```bash
-loop-agent doctor
-loop-agent inspect
-```
-
-## 初始化目标项目
-
-用户可以用自然语言驱动初始化与维护（这三类入口与目标项目 `AGENTS.md` 的“自然语言入口路由”一致）：
-
-- **初始化**：“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化” — 执行完整确定性初始化闭环，补全 README/验证矩阵并复查。
-- **更新校验**（只读）：“初始化更新校验”“loop agent初始化更新校验”“检查初始化更新” — 只读运行 `loop-agent init check-update --repo-root . --markdown`，汇报动作与风险，不自动写入。
-- **安全更新**（写入型）：“初始化安全更新”“loop agent初始化安全更新”“应用初始化更新” — 先 `check-update`，再 `loop-agent init update --apply-safe`；只执行确定性安全动作，human decisions 存在时停下等用户。
-
-在新项目中，最简单的用法是让当前 agent 执行初始化。需要更稳的执行约束时，可以使用下面这段完整提示词：
-
-```text
-请用 loop-agent 完整初始化当前项目。
-
-如果本机还没有 `loop-agent` 命令，请先运行 `npm install -g @tea-agent/loop-agent@latest`，再记录 `npm list -g @tea-agent/loop-agent --depth=0` 的实际版本。
-
-然后运行 `loop-agent init instructions --repo-root .`，按指引使用 full + merge 初始化。需要选择 provider/model，或涉及凭据、成本、部署副作用时先问我；其他能安全默认的选项直接继续。
-
-初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
-
-最后运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .`、`bash scripts/check-repo.sh`，如项目测试入口可识别也运行 `bash scripts/ci-tests.sh` 或 `bash scripts/ci.sh`，并汇报结果、假设和剩余风险。
-```
-
-如果手动运行 CLI，可以使用：
-
-```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
+
+`loop-agent` 是面向 AI coding agent 的仓库级任务运行时和治理工具。它把一次研发任务组织成可生成、可校验、可执行、可恢复、可交接的 Agent DAG，并用 `.harness/`、`docs/` 和 shell verification 记录执行事实、长期治理资料和完成依据。
+
+它可以作为任意目标项目的稳定控制器：初始化目标项目后，项目会获得 `.agents/skills/`、`ai_workspace/loop-agent/` 治理资料、验证脚本、任务运行态目录和模型执行指引，使 agent 在目标项目里的工作体验尽量与本仓库对齐。
+
+## 快速开始
+
+到一个新项目时，可以直接对当前 agent 说：
+
+```text
+请用 loop-agent 完整初始化当前项目；如果本机没有 loop-agent，请先安装 @tea-agent/loop-agent@latest。按 init instructions 使用 full + merge 初始化，探索项目后补全 README 和验证命令，最后运行 doctor、inspect、docs audit 和 check-repo 并汇报结果。
+```
+
+作为 CLI 使用时，安装已发布包：
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+loop-agent --version
+loop-agent --help
+```
+
+## 自动更新提醒
+
+通过 npm 全局安装的 `loop-agent` 会在普通交互式命令成功结束后检查 `@tea-agent/loop-agent` 是否有新版本。提醒只写入 `stderr`，不会污染命令原本的 `stdout`；失败命令、CI、管道/重定向、`--help`、`--version`、JSON/Markdown 输出以及 DAG/Loop/Delegate/Pi/Cursor 等 controller-sensitive 路径都会跳过。
+
+如果你拒绝版本 A，当前系统用户下不会再提醒 A；之后发布版本 B 时会继续提醒。确认更新时，CLI 会先证明当前安装来自同一 npm global root，然后安装刚确认的精确版本，例如：
+
+```bash
+npm install -g @tea-agent/loop-agent@0.13.0
+```
+
+需要完全关闭自动检查时设置：
+
+```bash
+LOOP_AGENT_DISABLE_UPDATE_CHECK=1
+```
+
+检查当前项目的 loop-agent 配置：
+
+```bash
+loop-agent doctor
+loop-agent inspect
+```
+
+## 自动发布
+
+仓库通过 GitHub Actions 定时检查 `main`，达到提交门槛并通过发布检查后，自动更新版本、生成 Release 说明并发布 GitHub Release 与 npm。手动触发默认只执行 dry-run，不产生远端发布副作用；具体配置、版本规则和恢复步骤见 [`docs/exec-plans/active/2026-07-18-nightly-auto-release.md`](docs/exec-plans/active/2026-07-18-nightly-auto-release.md)。
+
+## 初始化目标项目
+
+用户可以用自然语言驱动初始化与维护（这三类入口与目标项目 `AGENTS.md` 的“自然语言入口路由”一致）：
+
+- **初始化**：“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化” — 执行完整确定性初始化闭环，补全 README/验证矩阵并复查。
+- **更新校验**（只读）：“初始化更新校验”“loop agent初始化更新校验”“检查初始化更新” — 只读运行 `loop-agent init check-update --repo-root . --markdown`，汇报动作与风险，不自动写入。
+- **安全更新**（写入型）：“初始化安全更新”“loop agent初始化安全更新”“应用初始化更新” — 先 `check-update`，再 `loop-agent init update --apply-safe`；只执行确定性安全动作，human decisions 存在时停下等用户。
+
+在新项目中，最简单的用法是让当前 agent 执行初始化。需要更稳的执行约束时，可以使用下面这段完整提示词：
+
+```text
+请用 loop-agent 完整初始化当前项目。
+
+如果本机还没有 `loop-agent` 命令，请先运行 `npm install -g @tea-agent/loop-agent@latest`，再记录 `npm list -g @tea-agent/loop-agent --depth=0` 的实际版本。
+
+然后运行 `loop-agent init instructions --repo-root .`，按指引使用 full + merge 初始化。需要选择 provider/model，或涉及凭据、成本、部署副作用时先问我；其他能安全默认的选项直接继续。
+
+初始化后请立刻探索当前项目的 README、manifest/build/config 文件和源码目录，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步更新 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
+
+最后运行 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .`、`bash scripts/check-repo.sh`，如项目测试入口可识别也运行 `bash scripts/ci-tests.sh` 或 `bash scripts/ci.sh`，并汇报结果、假设和剩余风险。
+```
+
+如果手动运行 CLI，可以使用：
+
+```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>
+```
+
 `init instructions` 会输出给模型/Agent 执行完整初始化的指引包，不要求目标项目已有 `harness.json`。默认初始化会 merge 已有 `AGENTS.md`、`harness.json` 和 loop-agent 治理资料，生成语言无关的治理脚本矩阵、中文根 README 入口、`ai_workspace/loop-agent/` 目标项目治理资料、`.agents/skills/` repo-local skills、`harness.json` IDE schema 指引和 `.harness/` 骨架；不会在目标项目根目录生成 `skills/`，也不会把 loop-agent 生成的治理资料写到根 `docs/`。已有 README 会保留用户正文并插入/更新 loop-agent managed block。初始化还会向 `.gitignore` 合并一个 loop-agent managed block（`# LOOP_AGENT_INIT_START/END`），把 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/live/`、`.harness/cache/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.agents/skills/*/node_modules/`、`.worktrees/` 等个人/会话运行态事实和 repo-local skill 本地依赖忽略掉，同时保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`，也不会覆盖用户已有的 ignore 规则。
-
-新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
-
-```bash
-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
-```
-
-`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。期望 init surface 会自动发现包内 `docs/templates/` 与 `skills/` 的所有文件，因此 fresh `init --profile full` 投影到目标项目的每个 template/skill 文件都会被纳入校验。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 managed block（包括过期的 `.gitignore` managed block），不覆盖已有但无法确认来源的本地文件；对在旧路径被用户修改过的遗留副本，会在对应标准路径上给出 model merge / human decision，不会静默用包内容覆盖。
-
-当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
-
-初始化生成的 `scripts/ci-tests.sh` 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 `package.json`、`Makefile`、`go.mod`、`Cargo.toml`、Python 测试配置、Maven、Gradle、.NET 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
-
-## 运行任务
-
-创建并运行一个标准 Agent DAG：
-
-```bash
-loop-agent new-task <task-id> "任务标题"
-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 .
-```
-
-`dag run-task` 会先尊重显式声明的专用 `taskKind`。对于默认 `standard` 任务，它会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类；只有高置信的前端实现需求才会自动进入前端专用节点链。只读 `frontend-mock-assess-pi` 在计划前读取 Mock/API/schema 证据，并通过确定性 contract gate 选择原生 Mock、浏览器拦截、请求适配层、`not-needed` 或明确阻塞；它只能使用 DAG 生成时已固化的验证入口。可选 `task.json.frontendMock` 可设置 `auto|required|disabled`、既有服务目录和专项验证命令；不安全或不完整的显式 required 合同不会生成 writer。真实请求始终是默认路径，唯一写节点仍是 `frontend-implement-pi`。自动分类不会覆盖显式 profile、`workflowPolicy` 或 supervised quality gate。后端、混合或证据不足的需求继续使用通用模板，也不会自动进入 `backend-test`。Mock 验证只证明前端状态与交互；未实际请求后端时，收尾保留 `Frontend status: mock-validated`、`Real integration: pending`，并给出 `<task-id>-real-api-integration-verify`。该复验任务不会自动创建或执行，需要在后端就绪后显式运行。
-
-测试结论写回与业务知识图谱（结构化 Git，非 RAG）：
-
-```bash
-# 最终验证后：同步结论/用例/缺陷到 features/<F>/testing/**（须 featureId）
-# task.json: { "taskKind": "knowledge-sync", "featureId": "F-2026-004" }
-loop-agent dag run-task <task-id> --strict-models
-
-# 图谱开荒 / 增量（AI 只写 staging，晋升默认不覆盖已有正式文件）
-# task.json: { "taskKind": "knowledge-graph-bootstrap" }
-loop-agent knowledge graph-init --product-name my-app
-loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service order
-loop-agent dag run-task <task-id> --strict-models
-loop-agent knowledge graph-promote
-loop-agent knowledge graph-materialize
-loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
-```
-
-`knowledge curate` 仍只用于 repair/learned guidance 提案，与图谱查询不是同一能力。细节见 `docs/feature-workflow.md` 与 `docs/design/knowledge-graph-ai-bootstrap.md`。
-
-`<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
-
-非微小工作需要 exec-plan 时，使用确定性生命周期命令维护计划与索引；`new-task` 不会自动创建计划：
-
-```bash
-loop-agent plan create <plan-id> "<title>"
-loop-agent plan check
-loop-agent plan complete <plan-id> --summary "<summary>"
-```
-
-`plan create` 优先复用目标项目模板并回退到发布包内置模板，create/complete 失败时会回滚多文件修改。`dag run-task` 在生成 DAG 草稿前运行同源索引检查，避免遗漏登记直到末端 verify 才暴露。
-
-一次性只读评审或有边界写入：
-
-```bash
-loop-agent pi-prompt --cwd . --tools read,grep,find,ls "只读评审这个任务，不要编辑文件。"
-loop-agent pi-prompt --cwd . --tools read,bash,edit,write,grep,find,ls "<包含 allowedPaths 和 forbiddenPaths 的有边界任务说明>"
-```
-
-产品线 feature packet 可用伴生 Worker CLI 做 docs CI；仓库也提供外部 CI/cron wrapper，调度仍由外部系统负责：
-
-```bash
-agent-worker task validate-feature <feature-dir>
-agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>
-agent-worker feature run --feature-dir <feature-dir> --repo <target-repo> --dry-run [--git-mode checkpoint]
-agent-worker feature verify-final --feature-dir <feature-dir> --repo <target-repo> --task-id <qa-execute-id>
-agent-worker feature delivery --feature-dir <feature-dir> --repo <target-repo> --qa-evidence <path> --final-verification <path> [--dry-run]
-agent-worker feature closeout --feature-dir <feature-dir> --repo <target-repo> [--apply --owner <owner>]
-agent-worker report metrics --repo <target-repo> --month <YYYY-MM>
-agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>
-agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id <id> --repo <target-repo> --owner <owner> --dry-run
-bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
-```
-
-写入型 Worker 入口会在目标仓库写入前解析并冻结实际启动的 `loop-agent` controller identity。自举或其他需要精确版本约束的批次，可以额外传入：
-
-```bash
-agent-worker feature run \
-  --feature-dir <feature-dir> \
-  --repo <target-repo> \
-  --loop-agent-bin <published-loop-agent-entry> \
-  --expected-controller-version <version> \
-  --expected-controller-fingerprint <sha256:value>
-```
-
-identity 不只包含 semver，还包含绝对 launch spec、入口 SHA-256，以及覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable package fingerprint。校验失败时会在 materialize、Task Pool `Running` 或其他目标仓库写入前停止，并保留实际 identity 供诊断。
-
-`feature review` 是只读的 Feature 级入口。它从 Feature Packet 和现有 Task Pool 事实派生状态、required AC 覆盖、阻塞、证据和唯一主行动；默认输出简洁人类摘要，`--json` 输出稳定的 schemaVersion 1 读模型。它不会写入 Feature Packet 或 Task Pool。
-
-`feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec，执行独立、不会 promote/closeout 或移动 HEAD 的最终验证，并原子投影 canonical QA aggregate 与 HEAD-bound final-verification evidence。`feature delivery` 复用 checkpoint transaction，校验 branch/HEAD/clean、commit trailers、changed files、成功 run、QA、最终验证和 required AC 后，在 `.harness/task-pool/` 原子生成 Delivery manifest、Acceptance Coverage 与 `PR.md`；`--dry-run` 零写入。`feature closeout` 默认只预览 gates；显式 `--apply --owner <owner>` 才会在前后校验与整体回滚保护下写入 Feature Closeout，重复相同 facts 会幂等复用。
-
-Morning report 和 Observe snapshot/UI 复用同一 Feature reducer，优先展示 Status、Next Action、Why、Evidence。`report metrics` 同时生成 monthly JSON/Markdown，所有比例都包含分子、分母、样本量、UTC 窗口和缺失数据说明。
-
-`feature run` 把 validation、目标仓库 preflight、Ready Queue、现有 `run-ready`、晨报、Observe snapshot 和最终 review 串成一次 Feature 意图。默认不写 Git 且每次最多推进一个 Ready 写任务。显式 `--git-mode checkpoint` 才允许创建本地 `agent/<feature-id>` 分支：每个成功任务通过 write-boundary/sensitive-file audit 后提交 checkpoint；失败任务先保存 binary patch、changed/untracked inventory 与内容，再恢复到最近 checkpoint 并验证 clean。它从不授权 push、远程 PR、merge 或 stash。`--keep-failed-diff` 会保留失败 diff、返回 NeedsAction 并立即停止后续任务。
-
-如果 Task 产生业务失败，`feature run` 仍会完成晨报、snapshot 和最终 review，但结果为 `needs-action`、进程退出非零，并保留 batch 与失败证据；无 Ready 时正常退出，并通过 `noReadyReason` 区分已关闭、可交付、待 QA、需人工处理、依赖阻塞或空 Feature。
-
-失败可通过显式 Follow-up 决策闭环接续：ProductBug、TestBug、FlakyTest、DependencyFailure 会生成可批准 Task 草稿；EnvFailure 最近两次连续失败后才生成 `ENV-CHECK-*`，否则优先给出 retry；SpecUnclear、ContractMismatch、RiskyChange、NeedsHuman、Unknown 只生成人工行动卡，绝不进入 Ready。人工用 `feature approve-followup --dry-run` 复核 baseline、证据 hash、ID 冲突和事务计划，再带 `--owner` 批准。批准后新增 TaskSpec、重连下游依赖并进入 Ready；原失败 run/state/handoff 保持不变，重复 run 的新草稿会 supersede 旧 unresolved 草稿但保留历史。
-
-nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。
-
-自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
-
-Task Pool **state identity** 进一步固定为 feature-scoped 复合键 `{ featureId, taskId }`（ADR 0004）：
-
-- canonical state 路径：`.harness/task-pool/states/<featureId>/<taskId>.json`（schema v2，文件内容必须携带 `featureId` / `taskId`）
-- 同仓库多 Feature 可安全使用相同 Task ID（例如 `F-A/QA-EXEC-001` 与 `F-B/QA-EXEC-001` 互不覆盖）
-- retry 必须显式指定 Feature：`agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`
-- 诊断与迁移：`agent-worker pool doctor --repo <repo> --json`（只读）；`agent-worker pool migrate-state --repo <repo>` 默认 dry-run，apply 需 `--owner` + `--reason`
-- 扁平 legacy `states/<taskId>.json` 不得静默解释；存在时新写入 fail-closed，必须经 doctor / migrate 处理
-- Observe 只读：canonical `#/feature/:featureId/task/:taskId` 与 `GET /api/features/:featureId/tasks/:taskId`；legacy bare task route 仅在唯一命中时兼容，歧义返回 409 + candidates
-
-## 核心概念
-
-- **Agent DAG**：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
-- **任务源绑定与恢复**：新生成 DAG 会冻结任务源路径、SHA-256 和显式 `REQ/BR/AC`；前端计划漏号时会在 writer 前阻断。运行中断后应修复 task source 并重新生成完整 DAG，不要用二手摘要拼接 impl-only 后半段。
-- **`.harness/`**：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
-- **`harness.json`**：描述项目名、治理根目录、模型路由、executor 和验证脚本；目标项目中的 `ai_workspace/loop-agent/templates/harness.schema.json` 为 IDE 提供补全和字段说明，运行时仍由 Zod schema 校验。
-- **repo-local skills**：目标项目本地 skills 统一放在 `.agents/skills/`，便于项目定制 agent 行为并让外部 agent 自动发现。DAG skill 解析顺序为：用户配置目录 → `.agents/skills/` → 发布包内置 `skills/`。
-- **可选 SDD skill 嵌入**：如果目标项目在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，`dag run-task` 会把它们作为知识与方法补充追加到对应的 Contract、Plan、Implement/Repair、Verify、Review 节点。loop-agent 仍控制 DAG、状态、写入边界、验证和收口；不会自动运行 SDD 初始化/扫描 skill，也不会推进 `ai_workspace` 状态或归档。没有这些 repo-local skills 时，生成结果保持原有默认流程。
-- **run-owned skill snapshot**：新 DAG run 会在任何节点执行前，把本次实际注入 prompt 的 resolved skill profiles 冻结到 run 自己的 `.runtime/skill-snapshot.json`。后续节点、dynamic child、approve/resume 都使用同一份 hash-anchored snapshot；run 内修改 skill 只会从下一次 run 生效。
-- **controller identity**：`agent-worker` 把一次 Feature/batch 实际使用的发布包、入口、启动参数和 package 内容 fingerprint 固定下来，并把 identity 传播到 Worker、Task Pool、batch/Feature 与最终验证证据。
-- **只读 Pi 节点安全重试**：仅 planner/scout/reviewer/verifier/closeout 这类没有仓库写入能力的 Pi 节点，遇到模型连接中断、provider 限流、临时不可用或 timeout 时，可在同一 run 内有界重试；生成模板会自动声明默认 `retryPolicy`（总尝试 3 次、最多可配置 5 次、指数退避、单次等待上限 30s）。每次 attempt 保留独立证据，耗时与 Token 用量按尝试聚合，后一次成功不覆盖前一次失败证据。`quota`/`auth`/`invalid-output`/`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点不重试。
-- **`agent-worker` operator skill**：`skills/agent-worker/` 只负责 Feature Packet、TaskSpec、Task Pool、自举 release train 和失败恢复的外层路由；单个 DAG 实现、DAG kernel 修复和节点执行仍由 `loop-agent` 负责，该 skill 不进入默认 DAG role skills。
-- **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
-- **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。
-
-这些治理原则的设计思想吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践：人类掌舵，智能体执行；仓库作为记录系统；任务小步推进；用结构化 handoff 与可复现验证跨 session 保持连续性。背景资料收录在 `website/docs/practices/`。
-
-## 仓库地图
-
-本仓库按职责分区；更细的开工协议与会话规则见 `AGENTS.md`，治理索引见 `docs/README.md`。
-
-| 路径 | 职责 |
-|---|---|
-| `bin/`、`src/` | CLI 入口与运行时代码 |
-| `skills/` | repo-local skill 指令与 references |
-| `.harness/` | task、DAG run、cache、live state 等运行态事实 |
-| `docs/` | 长期治理文档、计划、报告与模板 |
-| `website/` | 面向使用者的文档站 |
-| `scripts/`、`test/` | 验证脚本与测试套件 |
-| `examples/` | 可复制 DAG 示例（默认不投影到目标项目） |
-| `features/`、`dogfood/` | 样板 Feature Packet 与 dogfood 样本（本仓库维护用） |
-| `harness.json`、`AGENTS.md`、`CONTEXT.md` | 项目配置、agent 开工地图与术语表 |
-
-## 能力概览
-
-- 生成、校验、执行和汇总 Agent DAG。
-- 通过 `eval replay` / `eval report` 对 completed DAG evidence 做 hash-anchored、deterministic 的只读重放比较；M1 不执行模型也不授权候选晋升。
-- 通过 `eval candidate register|show|list|transition` 管理不可变 Candidate Bundle 与 append-only lifecycle（M2 registry MVP）；不跑 live Pi/DAG，不移动 incumbent alias。
-- 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
-- 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
-- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入（唯一受治理 Agent writer）。
-- 保留 `cursor-prompt` 作为显式、手工触发的 one-shot sidecar（不是受治理 DAG/Loop writer）。
-- 通过 shell executor 运行确定性的验证命令。
-- 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
-
-## 内置示例
-
-`examples/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
-
-```bash
-loop-agent examples list
-loop-agent examples show example-dag.json
-loop-agent examples copy example-dag.json --repo-root <target-repo>
-```
-
-## 迭代本仓库
-
-如果要用 loop-agent 迭代 loop-agent 本仓库，发布版本 N 必须作为整个维护批次的固定 controller，候选版本 N+1 只能在隔离安装槽中接受接棒验证。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为 controller；首次安装或有意升级可用 `@latest`，但一次自举任务启动后不要中途升级或重新通过 PATH 解析入口。
-
-```bash
-npm install -g @tea-agent/loop-agent@latest
-npm list -g @tea-agent/loop-agent --depth=0
-loop-agent doctor
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
-```
-
-`@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举证据应记录 controller version、portable package fingerprint、候选 commit/tarball hash 和失败 run；semver 相同并不代表 package 内容相同。
-
-源码仓库提供 repo-maintainer deterministic takeover canary。它打包候选、安装到临时隔离 slot，由维护脚本独立计算 canonical package fingerprint 并与候选实现交叉核对，再通过候选包内两个绝对入口执行 full init、doctor、inspect、docs audit、目标项目治理检查、Feature validation/dry-run 和一个只含 static/shell executor 的小型 DAG；所有子进程都有硬超时，PATH trap 证明没有回退全局 `loop-agent` / `agent-worker` 命令，run evidence 则证明没有观察到 Pi/model executor：
-
-```bash
-npm run self-host:canary -- --deterministic --output <evidence.json>
-# 或验证已经构建好的候选 tarball
-npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
-```
-
-该脚本属于源码仓库维护入口，不进入发布包的 `files` surface；`--live` 当前明确拒绝执行。deterministic canary 证明候选包和 static/shell runtime 能接棒，但不会调度 Pi executor，也不承担 Pi skill source 解析证明；run-owned skill snapshot 的候选包解析由 snapshot 定向测试和真实 DAG 证据单独证明。
-
-## 文档导航
-
-| 路径 | 用途 |
-|---|---|
-| `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
-| `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
-| `docs/README.md` | 治理文档索引 |
-| `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
-| `docs/production-readiness.md` | Production Readiness v0.1 支持范围、证据和验收标准 |
-| `docs/architecture/runtime-boundaries.md` | runtime 层边界和依赖方向 |
-| `skills/loop-agent/` | loop-agent skill 入口和 references |
-| `examples/` | 可复用 DAG 示例 |
-| `website/docs/` | 面向使用者的 Docusaurus 文档站内容 |
-| `website/docs/practices/` | Anthropic、OpenAI Codex、腾讯端到端工程与社区 harness 实践资料 |
-
-## 本仓库开发
-
-本地源码开发：
-
-```bash
-npm install
-npm run build
-node bin/loop-agent.js --help
-npm run dev -- --help
-```
-
-常用验证命令：
-
-```bash
-npm run typecheck
-npm test
-bash scripts/check-repo.sh
-bash scripts/ci.sh
-npm run docs:build
-```
-
-当前 CLI 使用 `commander` 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。
-
-Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash，不要求使用 WSL 或 POSIX 路径。实际文件操作和 `--output` / `--dag` / `--cwd` 参数使用当前平台原生路径；仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 `/` 作为稳定分隔符。
-
-## 发布包内容
-
-发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
-
-`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
-
-DAG skill 指令优先从用户配置目录和目标项目 `.agents/skills/` 解析；目标项目未提供本地 skill 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或根 `skills/` 目录才可获得默认 DAG 能力。
-
-## 发布前检查
-
-发布 npm 包前至少运行：
-
-```bash
-npm run typecheck
-npm test
-npm run build
-node bin/loop-agent.js --help
-npm pack --dry-run
-```
-
-发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。
+
+新初始化会写入 `.harness/init-surface.json`，记录当前 controller 版本、初始化投影文件 hash 和 manifest hash。已用旧版本初始化的目标项目，可以用下面的维护入口对齐新版本初始化能力：
+
+```bash
+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
+```
+
+`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。期望 init surface 会自动发现包内 `docs/templates/` 与 `skills/` 的所有文件，因此 fresh `init --profile full` 投影到目标项目的每个 template/skill 文件都会被纳入校验。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 managed block（包括过期的 `.gitignore` managed block），不覆盖已有但无法确认来源的本地文件；对在旧路径被用户修改过的遗留副本，会在对应标准路径上给出 model merge / human decision，不会静默用包内容覆盖。
+
+当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
+
+初始化生成的 `scripts/ci-tests.sh` 不假定目标项目是 TypeScript、Node、前端或后端项目。它会保守探测 `package.json`、`Makefile`、`go.mod`、`Cargo.toml`、Python 测试配置、Maven、Gradle、.NET 等常见入口，只运行实际存在且工具可用的命令；探测不到时会清楚提示需要由初始化模型或用户按目标项目实际技术栈补充。
+
+## 运行任务
+
+创建并运行一个标准 Agent DAG：
+
+```bash
+loop-agent new-task <task-id> "任务标题"
+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 .
+```
+
+`dag run-task` 会先尊重显式声明的专用 `taskKind`。对于默认 `standard` 任务，它会根据任务标题、`source/需求.md` 和结构化 `allowedPaths` 做保守、确定性的需求分类；只有高置信的前端实现需求才会自动进入前端专用节点链。只读 `frontend-mock-assess-pi` 在计划前读取 Mock/API/schema 证据，并通过确定性 contract gate 选择原生 Mock、浏览器拦截、请求适配层、`not-needed` 或明确阻塞；它只能使用 DAG 生成时已固化的验证入口。可选 `task.json.frontendMock` 可设置 `auto|required|disabled`、既有服务目录和专项验证命令；不安全或不完整的显式 required 合同不会生成 writer。真实请求始终是默认路径，唯一写节点仍是 `frontend-implement-pi`。自动分类不会覆盖显式 profile、`workflowPolicy` 或 supervised quality gate。后端、混合或证据不足的需求继续使用通用模板，也不会自动进入 `backend-test`。Mock 验证只证明前端状态与交互；未实际请求后端时，收尾保留 `Frontend status: mock-validated`、`Real integration: pending`，并给出 `<task-id>-real-api-integration-verify`。该复验任务不会自动创建或执行，需要在后端就绪后显式运行。
+
+测试结论写回与业务知识图谱（结构化 Git，非 RAG）：
+
+```bash
+# 最终验证后：同步结论/用例/缺陷到 features/<F>/testing/**（须 featureId）
+# task.json: { "taskKind": "knowledge-sync", "featureId": "F-2026-004" }
+loop-agent dag run-task <task-id> --strict-models
+
+# 图谱开荒 / 增量（AI 只写 staging，晋升默认不覆盖已有正式文件）
+# task.json: { "taskKind": "knowledge-graph-bootstrap" }
+loop-agent knowledge graph-init --product-name my-app
+loop-agent knowledge graph-incremental-prepare --feature F-2026-004 --service order
+loop-agent dag run-task <task-id> --strict-models
+loop-agent knowledge graph-promote
+loop-agent knowledge graph-materialize
+loop-agent knowledge query --mode by_feature --feature F-2026-004 --json
+```
+
+`knowledge curate` 仍只用于 repair/learned guidance 提案，与图谱查询不是同一能力。细节见 `docs/feature-workflow.md` 与 `docs/design/knowledge-graph-ai-bootstrap.md`。
+
+`<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
+
+非微小工作需要 exec-plan 时，使用确定性生命周期命令维护计划与索引；`new-task` 不会自动创建计划：
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+loop-agent plan check
+loop-agent plan complete <plan-id> --summary "<summary>"
+```
+
+`plan create` 优先复用目标项目模板并回退到发布包内置模板，create/complete 失败时会回滚多文件修改。`dag run-task` 在生成 DAG 草稿前运行同源索引检查，避免遗漏登记直到末端 verify 才暴露。
+
+一次性只读评审或有边界写入：
+
+```bash
+loop-agent pi-prompt --cwd . --tools read,grep,find,ls "只读评审这个任务，不要编辑文件。"
+loop-agent pi-prompt --cwd . --tools read,bash,edit,write,grep,find,ls "<包含 allowedPaths 和 forbiddenPaths 的有边界任务说明>"
+```
+
+产品线 feature packet 可用伴生 Worker CLI 做 docs CI；仓库也提供外部 CI/cron wrapper，调度仍由外部系统负责：
+
+```bash
+agent-worker task validate-feature <feature-dir>
+agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>
+agent-worker feature run --feature-dir <feature-dir> --repo <target-repo> --dry-run [--git-mode checkpoint]
+agent-worker feature verify-final --feature-dir <feature-dir> --repo <target-repo> --task-id <qa-execute-id>
+agent-worker feature delivery --feature-dir <feature-dir> --repo <target-repo> --qa-evidence <path> --final-verification <path> [--dry-run]
+agent-worker feature closeout --feature-dir <feature-dir> --repo <target-repo> [--apply --owner <owner>]
+agent-worker report metrics --repo <target-repo> --month <YYYY-MM>
+agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>
+agent-worker feature approve-followup --feature-dir <feature-dir> --followup-id <id> --repo <target-repo> --owner <owner> --dry-run
+bash scripts/worker-nightly.sh <feature-dir> <target-repo> <batch-run-id>
+```
+
+写入型 Worker 入口会在目标仓库写入前解析并冻结实际启动的 `loop-agent` controller identity。自举或其他需要精确版本约束的批次，可以额外传入：
+
+```bash
+agent-worker feature run \
+  --feature-dir <feature-dir> \
+  --repo <target-repo> \
+  --loop-agent-bin <published-loop-agent-entry> \
+  --expected-controller-version <version> \
+  --expected-controller-fingerprint <sha256:value>
+```
+
+identity 不只包含 semver，还包含绝对 launch spec、入口 SHA-256，以及覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable package fingerprint。校验失败时会在 materialize、Task Pool `Running` 或其他目标仓库写入前停止，并保留实际 identity 供诊断。
+
+`feature review` 是只读的 Feature 级入口。它从 Feature Packet 和现有 Task Pool 事实派生状态、required AC 覆盖、阻塞、证据和唯一主行动；默认输出简洁人类摘要，`--json` 输出稳定的 schemaVersion 1 读模型。它不会写入 Feature Packet 或 Task Pool。
+
+`feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec，执行独立、不会 promote/closeout 或移动 HEAD 的最终验证，并原子投影 canonical QA aggregate 与 HEAD-bound final-verification evidence。`feature delivery` 复用 checkpoint transaction，校验 branch/HEAD/clean、commit trailers、changed files、成功 run、QA、最终验证和 required AC 后，在 `.harness/task-pool/` 原子生成 Delivery manifest、Acceptance Coverage 与 `PR.md`；`--dry-run` 零写入。`feature closeout` 默认只预览 gates；显式 `--apply --owner <owner>` 才会在前后校验与整体回滚保护下写入 Feature Closeout，重复相同 facts 会幂等复用。
+
+Morning report 和 Observe snapshot/UI 复用同一 Feature reducer，优先展示 Status、Next Action、Why、Evidence。`report metrics` 同时生成 monthly JSON/Markdown，所有比例都包含分子、分母、样本量、UTC 窗口和缺失数据说明。
+
+`feature run` 把 validation、目标仓库 preflight、Ready Queue、现有 `run-ready`、晨报、Observe snapshot 和最终 review 串成一次 Feature 意图。默认不写 Git 且每次最多推进一个 Ready 写任务。显式 `--git-mode checkpoint` 才允许创建本地 `agent/<feature-id>` 分支：每个成功任务通过 write-boundary/sensitive-file audit 后提交 checkpoint；失败任务先保存 binary patch、changed/untracked inventory 与内容，再恢复到最近 checkpoint 并验证 clean。它从不授权 push、远程 PR、merge 或 stash。`--keep-failed-diff` 会保留失败 diff、返回 NeedsAction 并立即停止后续任务。
+
+如果 Task 产生业务失败，`feature run` 仍会完成晨报、snapshot 和最终 review，但结果为 `needs-action`、进程退出非零，并保留 batch 与失败证据；无 Ready 时正常退出，并通过 `noReadyReason` 区分已关闭、可交付、待 QA、需人工处理、依赖阻塞或空 Feature。
+
+失败可通过显式 Follow-up 决策闭环接续：ProductBug、TestBug、FlakyTest、DependencyFailure 会生成可批准 Task 草稿；EnvFailure 最近两次连续失败后才生成 `ENV-CHECK-*`，否则优先给出 retry；SpecUnclear、ContractMismatch、RiskyChange、NeedsHuman、Unknown 只生成人工行动卡，绝不进入 Ready。人工用 `feature approve-followup --dry-run` 复核 baseline、证据 hash、ID 冲突和事务计划，再带 `--owner` 批准。批准后新增 TaskSpec、重连下游依赖并进入 Ready；原失败 run/state/handoff 保持不变，重复 run 的新草稿会 supersede 旧 unresolved 草稿但保留历史。
+
+nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 morning report、Observe snapshot 和 controller 版本 artifacts。
+
+自 0.8.0 起，`.harness/task-pool/` 是唯一受支持的 Task Pool runtime root，其中包含根级 `runs.jsonl`、`events.jsonl`、`states/`、`artifacts/`、`failure-handoffs/`、`observability/` 和 `reports/`。这是 hard cutover：此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
+
+Task Pool **state identity** 进一步固定为 feature-scoped 复合键 `{ featureId, taskId }`（ADR 0004）：
+
+- canonical state 路径：`.harness/task-pool/states/<featureId>/<taskId>.json`（schema v2，文件内容必须携带 `featureId` / `taskId`）
+- 同仓库多 Feature 可安全使用相同 Task ID（例如 `F-A/QA-EXEC-001` 与 `F-B/QA-EXEC-001` 互不覆盖）
+- retry 必须显式指定 Feature：`agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`
+- 诊断与迁移：`agent-worker pool doctor --repo <repo> --json`（只读）；`agent-worker pool migrate-state --repo <repo>` 默认 dry-run，apply 需 `--owner` + `--reason`
+- 扁平 legacy `states/<taskId>.json` 不得静默解释；存在时新写入 fail-closed，必须经 doctor / migrate 处理
+- Observe 只读：canonical `#/feature/:featureId/task/:taskId` 与 `GET /api/features/:featureId/tasks/:taskId`；legacy bare task route 仅在唯一命中时兼容，歧义返回 409 + candidates
+
+## 核心概念
+
+- **Agent DAG**：把一次任务拆成 contract、scout、plan、implement、verify、closeout 等可审查节点。
+- **任务源绑定与恢复**：新生成 DAG 会冻结任务源路径、SHA-256 和显式 `REQ/BR/AC`；前端计划漏号时会在 writer 前阻断。运行中断后应修复 task source 并重新生成完整 DAG，不要用二手摘要拼接 impl-only 后半段。
+- **`.harness/`**：记录 task、DAG run、one-shot run、cache 和 live state 等运行态事实。
+- **`harness.json`**：描述项目名、治理根目录、模型路由、executor 和验证脚本；目标项目中的 `ai_workspace/loop-agent/templates/harness.schema.json` 为 IDE 提供补全和字段说明，运行时仍由 Zod schema 校验。
+- **repo-local skills**：目标项目本地 skills 统一放在 `.agents/skills/`，便于项目定制 agent 行为并让外部 agent 自动发现。DAG skill 解析顺序为：用户配置目录 → `.agents/skills/` → 发布包内置 `skills/`。
+- **可选 SDD skill 嵌入**：如果目标项目在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，`dag run-task` 会把它们作为知识与方法补充追加到对应的 Contract、Plan、Implement/Repair、Verify、Review 节点。loop-agent 仍控制 DAG、状态、写入边界、验证和收口；不会自动运行 SDD 初始化/扫描 skill，也不会推进 `ai_workspace` 状态或归档。没有这些 repo-local skills 时，生成结果保持原有默认流程。
+- **run-owned skill snapshot**：新 DAG run 会在任何节点执行前，把本次实际注入 prompt 的 resolved skill profiles 冻结到 run 自己的 `.runtime/skill-snapshot.json`。后续节点、dynamic child、approve/resume 都使用同一份 hash-anchored snapshot；run 内修改 skill 只会从下一次 run 生效。
+- **controller identity**：`agent-worker` 把一次 Feature/batch 实际使用的发布包、入口、启动参数和 package 内容 fingerprint 固定下来，并把 identity 传播到 Worker、Task Pool、batch/Feature 与最终验证证据。
+- **只读 Pi 节点安全重试**：仅 planner/scout/reviewer/verifier/closeout 这类没有仓库写入能力的 Pi 节点，遇到模型连接中断、provider 限流、临时不可用或 timeout 时，可在同一 run 内有界重试；生成模板会自动声明默认 `retryPolicy`（总尝试 3 次、最多可配置 5 次、指数退避、单次等待上限 30s）。每次 attempt 保留独立证据，耗时与 Token 用量按尝试聚合，后一次成功不覆盖前一次失败证据。`quota`/`auth`/`invalid-output`/`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点不重试。
+- **`agent-worker` operator skill**：`skills/agent-worker/` 只负责 Feature Packet、TaskSpec、Task Pool、自举 release train 和失败恢复的外层路由；单个 DAG 实现、DAG kernel 修复和节点执行仍由 `loop-agent` 负责，该 skill 不进入默认 DAG role skills。
+- **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
+- **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。
+
+这些治理原则的设计思想吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践：人类掌舵，智能体执行；仓库作为记录系统；任务小步推进；用结构化 handoff 与可复现验证跨 session 保持连续性。背景资料收录在 `website/docs/practices/`。
+
+## 仓库地图
+
+本仓库按职责分区；更细的开工协议与会话规则见 `AGENTS.md`，治理索引见 `docs/README.md`。
+
+| 路径 | 职责 |
+|---|---|
+| `bin/`、`src/` | CLI 入口与运行时代码 |
+| `skills/` | repo-local skill 指令与 references |
+| `.harness/` | task、DAG run、cache、live state 等运行态事实 |
+| `docs/` | 长期治理文档、计划、报告与模板 |
+| `website/` | 面向使用者的文档站 |
+| `scripts/`、`test/` | 验证脚本与测试套件 |
+| `examples/` | 可复制 DAG 示例（默认不投影到目标项目） |
+| `features/`、`dogfood/` | 样板 Feature Packet 与 dogfood 样本（本仓库维护用） |
+| `harness.json`、`AGENTS.md`、`CONTEXT.md` | 项目配置、agent 开工地图与术语表 |
+
+## 能力概览
+
+- 生成、校验、执行和汇总 Agent DAG。
+- 通过 `eval replay` / `eval report` 对 completed DAG evidence 做 hash-anchored、deterministic 的只读重放比较；M1 不执行模型也不授权候选晋升。
+- 通过 `eval candidate register|show|list|transition` 管理不可变 Candidate Bundle 与 append-only lifecycle（M2 registry MVP）；不跑 live Pi/DAG，不移动 incumbent alias。
+- 从任务说明生成标准 DAG，并按依赖顺序运行规划、实现、验证和收口节点。
+- 维护 `loop` 长程任务状态，包括目标、轮次、信号、验证事实和收口草稿。
+- 通过 Pi executor 执行只读规划、评审、诊断和有边界写入（唯一受治理 Agent writer）。
+- 保留 `cursor-prompt` 作为显式、手工触发的 one-shot sidecar（不是受治理 DAG/Loop writer）。
+- 通过 shell executor 运行确定性的验证命令。
+- 检查任务状态、运行态工件、文档链接、skill entry 和 runtime boundary 等治理规则。
+
+## 内置示例
+
+`examples/` 默认不复制到目标项目。可以通过工具内置命令查看或按需复制：
+
+```bash
+loop-agent examples list
+loop-agent examples show example-dag.json
+loop-agent examples copy example-dag.json --repo-root <target-repo>
+```
+
+## 迭代本仓库
+
+如果要用 loop-agent 迭代 loop-agent 本仓库，发布版本 N 必须作为整个维护批次的固定 controller，候选版本 N+1 只能在隔离安装槽中接受接棒验证。不要使用当前工作区的 `npm link` 或 `npm run dev` 作为 controller；首次安装或有意升级可用 `@latest`，但一次自举任务启动后不要中途升级或重新通过 PATH 解析入口。
+
+```bash
+npm install -g @tea-agent/loop-agent@latest
+npm list -g @tea-agent/loop-agent --depth=0
+loop-agent doctor
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
+```
+
+`@latest` 只用于安装或升级，不要在 DAG 节点里反复用 `npx @latest` 拉取。自举证据应记录 controller version、portable package fingerprint、候选 commit/tarball hash 和失败 run；semver 相同并不代表 package 内容相同。
+
+源码仓库提供 repo-maintainer deterministic takeover canary。它打包候选、安装到临时隔离 slot，由维护脚本独立计算 canonical package fingerprint 并与候选实现交叉核对，再通过候选包内两个绝对入口执行 full init、doctor、inspect、docs audit、目标项目治理检查、Feature validation/dry-run 和一个只含 static/shell executor 的小型 DAG；所有子进程都有硬超时，PATH trap 证明没有回退全局 `loop-agent` / `agent-worker` 命令，run evidence 则证明没有观察到 Pi/model executor：
+
+```bash
+npm run self-host:canary -- --deterministic --output <evidence.json>
+# 或验证已经构建好的候选 tarball
+npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
+```
+
+该脚本属于源码仓库维护入口，不进入发布包的 `files` surface；`--live` 当前明确拒绝执行。deterministic canary 证明候选包和 static/shell runtime 能接棒，但不会调度 Pi executor，也不承担 Pi skill source 解析证明；run-owned skill snapshot 的候选包解析由 snapshot 定向测试和真实 DAG 证据单独证明。
+
+## 文档导航
+
+| 路径 | 用途 |
+|---|---|
+| `AGENTS.md` | 本仓库的 agent 开工协议、会话协议和长期工作规则 |
+| `harness.json` | loop-agent 在本仓库的模型、executor、治理根目录和脚本配置 |
+| `docs/README.md` | 治理文档索引 |
+| `docs/verification-matrix.md` | 不同变更类型对应的验证命令 |
+| `docs/production-readiness.md` | Production Readiness v0.1 支持范围、证据和验收标准 |
+| `docs/architecture/runtime-boundaries.md` | runtime 层边界和依赖方向 |
+| `skills/loop-agent/` | loop-agent skill 入口和 references |
+| `examples/` | 可复用 DAG 示例 |
+| `website/docs/` | 面向使用者的 Docusaurus 文档站内容 |
+| `website/docs/practices/` | Anthropic、OpenAI Codex、腾讯端到端工程与社区 harness 实践资料 |
+
+## 本仓库开发
+
+本地源码开发：
+
+```bash
+npm install
+npm run build
+node bin/loop-agent.js --help
+npm run dev -- --help
+```
+
+常用验证命令：
+
+```bash
+npm run typecheck
+npm test
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+npm run docs:build
+```
+
+当前 CLI 使用 `commander` 组织 command tree。顶层 help、子命令 help、参数解析和未知命令错误都由 commander 驱动。
+
+Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash，不要求使用 WSL 或 POSIX 路径。实际文件操作和 `--output` / `--dag` / `--cwd` 参数使用当前平台原生路径；仓库内引用、JSON/Markdown 证据引用和 glob 约定可继续用 `/` 作为稳定分隔符。
+
+## 发布包内容
+
+发布包包含静态运行和指导资料：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与可选的 `agent-worker` operator skill）、`docs/*.md`、`docs/architecture/runtime-boundaries.md`、`docs/skills/`、`docs/templates/`、`docs/init-surface.manifest.json`、`examples/`、`harness.json`、`AGENTS.md`、`README.md` 和 `CHANGELOG.md`。
+
+`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 等目录下的任务正文是目标仓库实时生成或历史事实；npm 包只携带这些目录的 README，不携带本仓库已有历史记录。
+
+DAG skill 指令优先从用户配置目录和目标项目 `.agents/skills/` 解析；目标项目未提供本地 skill 时，CLI 会回退到 npm 包内置的 `skills/`。因此普通项目不需要复制 loop-agent 仓库历史文档或根 `skills/` 目录才可获得默认 DAG 能力。
+
+## 发布前检查
+
+发布 npm 包前至少运行：
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node bin/loop-agent.js --help
+npm pack --dry-run
+```
+
+发布入口 `bin/loop-agent.js` 只加载 `dist/cli.js`；`npm run dev -- <args>` 只用于源码开发和定位问题。