@tea-agent/loop-agent 0.10.0 → 0.12.0

package/docs/architecture/dag-execution.md

@@ -0,0 +1,140 @@
+# Agent DAG 执行架构
+
+本页说明 Agent DAG 的主调用链、rank 调度、executor、run-owned skill snapshot、decision gate 与 pause/completed 生命周期。命令面与 `test/cli-contract.test.ts` 一致；符号归属以 `src/` 为准。完整 import 边界与 governance hook 见 `runtime-boundaries.md`。
+
+## 主调用链
+
+### 生成 + 校验 + 执行（`dag run-task`）
+
+```text
+src/commands/dag-run-task.ts  runDagRunTask
+  → src/application/dag/generate-task-dag.ts  generateTaskDagUseCase
+      └─ src/workflows/dag/init-hybrid.ts  initHybridDagFromTask     （生成 DagSpec）
+      └─ src/application/dag/validate-dag.ts  validateDagUseCase      （候选 + 最终校验）
+      └─ assertSafeForExecution                               （执行前安全检查）
+      └─ src/application/dag/run-dag.ts  runDagUseCase              （执行）
+```
+
+`generateTaskDagUseCase` 内部先 `initHybridDagFromTask` 生成 `DagSpec`，再调用 `validateDagUseCase` 做候选与最终两次校验，随后 `assertSafeForExecution` 确认 DAG 可安全执行，最后委托 `runDagUseCase` 执行。`runDagRunTask` 还 `export` 了 `assertSafeForExecution` 供命令层复用。
+
+### 直接执行既有 DAG（`run-dag`）
+
+```text
+src/commands/run-dag.ts
+  → src/application/dag/run-dag.ts  runDagUseCase
+      → src/workflows/dag/runner.ts  runDag
+```
+
+`run-dag` 是 top-level 命令，**不**在 `dag` 子树下（与 `dag run-task` 区分）。`runDagUseCase` 是 application 层 typed use-case，`runDag` 是 workflow runtime 核心。
+
+### 校验
+
+```text
+src/commands/dag-validate.ts  runDagValidate
+  → src/application/dag/validate-dag.ts  validateDagUseCase
+```
+
+### runtime contract preflight 与 repair writer 解析
+
+- `src/workflows/dag/runtime-contract.ts` `assertRuntimeContractCompatible` 依据 controller capabilities（`DAG_CONTROLLER_CAPABILITIES`：`agentRuntime="pi-only"`、`repairWriterProtocol="explicit-node-v1"`）校验 DagSpec v3 必需的 `runtimeContract`。v3 让旧 controller 在解析阶段拒绝；新 controller 的 `validateDagUseCase`、`runDagUseCase`、`runDag` 与 resume 还会校验 capability 和可选最低版本，不兼容在任何节点执行前 fail-fast。legacy v1/v2 DagSpec 可读但没有 v3 握手。
+- `src/workflows/dag/repair-artifact.ts` `resolveRepairTaskForGate` 解析 `shell.repairArtifactGate`：优先显式 `repairNodeId`，否则推导唯一的下游受治理 Pi writer（`repairWriterContractIssues` 校验 executor/toolProfile/writePolicy/path 契约）。`validate.ts` 与 `node-execution.ts` 复用同一 resolver，runtime 不再按节点名硬编码。
+- `src/workflows/dag/controller-identity.ts` 在 run 创建前要求 controller identity 可解析，再由 `captureControllerIdentity` 冻结到 `<runDir>/controller-identity.json`；`verifyControllerIdentityForResume` 在 resume 前重新校验并对漂移、篡改或 legacy-unpinned run fail closed。
+
+## rank 调度
+
+拓扑排序与按 rank 执行的符号归属（校准版，勿笼统归到 `runner.ts`）：
+
+| 职责 | 源码入口 | 说明 |
+| --- | --- | --- |
+| 拓扑排序 | `src/workflows/dag/topo.ts` `topoSortToRanks` | Kahn 算法，返回 `string[][]` ranks 并检测环 |
+| 单次 rank 执行 | `src/workflows/dag/scheduler.ts` `executeDagRanksOnce` | rank 间遍历、节点执行编排 |
+| run 主循环 | `src/workflows/dag/runner.ts` `runDag` / `executeDagCheckpoint` | 调用 scheduler + persistence + convergence |
+
+`scheduler.ts` `executeDagRanksOnce` 内每个 rank：
+
+1. `pauseGateRunnable`（满足 `isPauseOnHumanDecisionGate` 的节点，来自 `decision-envelope.ts`）**串行**先跑；任一节点触发 pause 即停止后续。
+2. `regularRunnable` 经 `mapConcurrent` 并发执行，`maxConcurrent` 默认 **4**（`runner.ts` `Math.max(1, opts.maxConcurrent ?? 4)`）。
+3. `rankWriterNodeIds`（`executor === "pi"` && `toolProfile === "write"` && `writePolicy === "exclusive"`）注入同 rank 的不相交 writeSet 上下文（`createExecuteNodeForRank`）。
+4. 依赖未就绪的节点标 `SKIPPED`。
+
+`mapConcurrent` 来自 `src/shared/concurrency.ts`（或等价 shared 工具）。
+
+## executor（Pi-only 受治理 runtime）
+
+- 注册表：`src/workflows/dag/executor-registry.ts`
+  `DEFAULT_DAG_EXECUTOR_REGISTRY = { pi, shell, static }`。
+- schema：`src/workflows/dag/types.ts`
+  `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；DagNodeExecutor 默认 `"pi"`（`executor: dagNodeExecutorSchema.default("pi")`）。
+- `executor: "cursor"` 在 schema refine 阶段抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`（Pi-only = ADR 0001）。
+- Pi handler 先 `requireModel(input)` 校验已解析 model，再委托 `executeDagPiNode`（`src/executors/dag-pi-executor.ts`）。
+- shell handler = `executeDagShellNode`（`src/executors/shell-executor.ts`）；static handler = `executeDagStaticNode`（`src/executors/dag-static-executor.ts`）。
+
+Executor 不得依赖 commands 或 CLI formatting；Cursor 不在受治理路径（`runtime-boundaries.md` §Executors）。
+
+## run-owned skill snapshot
+
+每个新 DAG run 在首个节点执行前冻结本次注入 prompt 的 skill 集合，保证 live skill 后续被修改/删除/补建不会影响当前 run：
+
+| 步骤 | 源码入口 |
+| --- | --- |
+| 首节点前创建 | `runDag` 调 `createSkillSnapshot({ mode: "run-start" })`（`src/workflows/dag/skill-snapshot.ts`） |
+| 写入产物 | `writeSkillSnapshot(runDir, snapshot)` → `<runDir>/.runtime/skill-snapshot.json`（常量 `SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json"`） |
+| state 只存相对引用 | `state.skillSnapshotRef` = `{ schemaVersion, path: ".runtime/skill-snapshot.json", sha256, createdAt, mode }`，**不**存绝对路径 |
+| resume 续用 | `prepareSkillSnapshotForContinuation`（resume 路径，`src/workflows/dag/runner.ts` `resumeDagRun`） |
+| 完整性校验 | 普通节点、dynamic child、approve/resume 都执行 integrity gate，ref/artifact/profile/binding 不一致即 fail closed，不回退实时解析 |
+| legacy 兼容 | 旧 run 只在 ref 与 artifact 都不存在时可标 `legacy-resume-backfill` 并冻结剩余节点 |
+
+snapshot 与 controller identity 是两个不同冻结层，详见 `runtime-boundaries.md` §版本化自举边界。
+
+## decision gate 与 pause
+
+- `isPauseOnHumanDecisionGate`（`src/workflows/dag/decision-envelope.ts`）：`task.decisionGate?.mode === "pause-on-human"` 且 decision gate 启用时，该节点在 rank 内**串行先跑**。
+- `shouldPauseOnHumanEscalation`（`decision-envelope.ts`，在 `src/workflows/dag/node-execution.ts` 调用）：decision envelope 判定需人工升级时，写 `human-escalation.json`（与 `human-escalation.md`）并触发 pause。
+- pause 时 `state.pausedByNodeId` + `pauseReason` + `humanDecisionNodeId` 被写入；`human-escalation.json` 落在 `<runDir>/<nodeId>/`。
+
+decision envelope 中的 **model verdict**（`decision` / `riskLevel` 等解析自文本）是 `advisoryOnly: true` 派生视图，**不**是完成权威（`facts-and-state.md`）。
+
+## 生命周期：active / paused / completed
+
+`src/workflows/dag/lifecycle.ts` 定义三个目录：
+
+| 目录 | 写入规则 |
+| --- | --- |
+| `.harness/dag-runs/active/<runId>/` | run 进行中 |
+| `.harness/dag-runs/paused/<runId>/` | 触发 pause；resume 需 `human-approval.json` |
+| `.harness/dag-runs/completed/<runId>/` | 终态；除 runner 终态写外只读（`completed-facts-guard.ts`） |
+
+扫描顺序：`DAG_LIFECYCLE_SCAN_ORDER = ["paused", "active", "completed"]`（locate/status 等按此顺序解析 runId）。
+
+关键规则：
+
+- **pause → approve → resume**：`dag approve` 在 paused run 写 `human-approval.json`，将状态改回 `running` 并把目录迁回 `active/`；随后 `resumeDagRun`（`runner.ts`）要求 active lifecycle + approval artifact，并用 `prepareSkillSnapshotForContinuation` 复用 run-owned snapshot。
+- **completed 写入**：只有 runner 在终态 `persistState({ allowCompletedFactsWrite: true })`（`runner.ts`）才能写 completed 目录；该 flag 经 `completed-facts-guard.ts` 校验。
+- **显式 recovery mutation**：`dag reconcile-run`（`src/commands/dag-reconcile-run.ts`，命令层）默认仅检查；只有给出 `--action supersede|abandon` + reason，且 liveness 证明 runner 已停止时，才在原 lifecycle 写 reconciliation/state 并迁移到 `completed/`。它不是修改既有 completed history 的通用入口。Observe / status / doctor 始终只读。
+- **status 枚举**：`DagRunState.status`；`TERMINAL_RUN_STATUSES` 判终态；`isTerminalDagRunStatus` 工具函数。
+
+## convergence（可选、supervised）
+
+- 控制器：`src/workflows/dag/convergence/controller.ts` `runConvergencePassController`，在 runner rank 间被调用。
+- 特性默认 **off**（`task/config-types.ts` `convergence` 默认 `{ enabled: false }`）。
+- 启用后按 `maxPasses`（默认 3）做多轮 repair，回归时可 `pauseOnRegression`。
+- 产物落在 `<runDir>/convergence/pass-<n>/`。
+
+## 完成权威 = shell verification
+
+完成声明的权威是 shell command 的新鲜 exit code 与归档输出。验证命令执行在 `src/executors/shell-executor.ts`，环境与 preset helper 在 `src/executors/shell-verification.ts`；DAG authoring 写入的 `task.shell.verifyEvidence` 元数据由 `src/workflows/dag/node-execution.ts` 复制到 `node.verifyEvidence`。model verdict、Observe 或报告都不能替代这些 shell facts。
+
+## Dynamic Workflow
+
+Dynamic Workflow 是 DAG runtime 上方的逻辑编排/编译层，**不**重写 runner：
+
+```text
+WorkflowSpec (src/workflows/dynamic/spec.ts workflowSpecSchema)
+  → validate (src/workflows/dynamic/validate.ts)
+  → compile (src/workflows/dynamic/compile.ts compileWorkflowToDag) → DagSpec
+  → 同一 run-dag 执行
+```
+
+- 动态语义：`map_agent` / `verify_agent` / `reduce_agent` / `condition` / `loop_until` / `human_gate` / `command` / `artifact_transform`。
+- agent-like 节点 executor 仅 `pi` | `static`（schema 已不含 `cursor`）。
+- 未完全兑现的 runtime limits 强执法、更广 profile、Loop 原生 `workflow` action 深度编排等仍是**设计输入**，见 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（带 2026-07-14 校准条）。

package/docs/architecture/evolution.md

@@ -0,0 +1,53 @@
+# 架构演进：当前 vs 未来
+
+本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0003、`docs/exec-plans/completed/`。
+
+## 当前已实现（0.11.0）
+
+| 域 | 现状 | 权威入口 |
+| --- | --- | --- |
+| 受治理 Agent runtime | **Pi-only**；`cursor-prompt` 仅显式 one-shot sidecar | ADR 0001、`CHANGELOG.md [0.10.0]` |
+| Agent DAG 主链 | `dag run-task` → generate → validate → `run-dag`；report/doctor/reconcile-run | `dag-execution.md`、`test/cli-contract.test.ts` |
+| Dynamic Workflow | `WorkflowSpec` → validate → compile → 同一 `run-dag`；agent-like 节点仅 `pi\|static` | `src/workflows/dynamic/{spec,validate,compile}.ts`、`website/docs/guides/dynamic-workflow.md` |
+| 版本化自举 | controller identity + run-owned skill snapshot + deterministic canary | `docs/reports/2026-07-13-versioned-self-hosting-bootstrap.md` |
+| Feature 交付（M2） | review/run/approve-followup/delivery/closeout/verify-final | `docs/reports/2026-07-12-m2-completion-audit.md` |
+| Task Pool | 唯一根 `.harness/task-pool/` | ADR 0002 |
+| Observe | 本地只读暖白运营控制台 R1–R5（derived） | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]` |
+| DagSpec / repair | v3 + `runtimeContract`；显式 `repairNodeId` | `CHANGELOG.md [0.11.0]`、`dag-execution.md` |
+| 文档双树 | `website/docs/` 用法 vs `docs/` 治理；docs-converge | ADR 0003 |
+| 文档治理 | `docs/architecture/` 主题文档（本目录）+ package 可达 | 本目录 README |
+
+### 受治理 runtime 的边界（已实现、不变式）
+
+- DAG writer 固定 `implement-pi` / `repair-pi`；`executor: "cursor"`、`implement-cursor` / `repair-cursor`、Cursor worker、`cursor-fix` 已从受治理路径移除。
+- 完成权威 = shell verification；model verdict / Observe / 报告是 derived/advisory。
+- Worker 通过已发布 `loop-agent` 子进程执行，不 in-process import runtime kernel（governance 机器校验）。
+
+## 未来规划（第 3–6 月，**未实现**）
+
+以下能力来自 `docs/design/六个月规划.md` 与 `docs/design/dynamic-workflow-dag-engine-roadmap.md`（六个月规划页首 2026-07-15 / 0.11.0 校准；未交付 phase 为**设计输入**，不是已实现证明）。它们**当前不存在于代码或 CLI**：
+
+| 未来方向 | 状态 | 规划来源 |
+| --- | --- | --- |
+| 远程 PR / CI | 规划 / 未实现 | `docs/design/六个月规划.md`（第 3 个月起） |
+| 线上 / 云 Worker | 规划 / 未实现 | 同上 |
+| 云 Task Pool / SQL / Orchestrator | 规划 / 未实现 | 同上（第 2 月原始设计已调整为本地 Feature 闭环） |
+| 多仓库平台 | 规划 / 未实现 | 同上 |
+| 组织级服务 | 规划 / 未实现 | 同上 |
+| Web Console（远端） | 规划 / 未实现 | 同上 |
+| Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md`（未勾选 phase） |
+| Loop 与 Dynamic Workflow 更深的双向集成、稳定化与自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action，不应误写为完全缺失 |
+
+> 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 是 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
+
+## 已收敛为 archive / 历史基线（非未来）
+
+- 第 1–2 月规划已收敛为 archive/reports 指针，不在本文展开：`docs/design/archive/2026-07-12-第二月规划.md`。
+- `docs/reports/2026-07-02-repository-analysis.md` 自 2026-07-14 起冻结为**历史基线快照**，不再滚动追加 Unreleased 能力。
+- 活能力短摘要在 `docs/reports/current-capability-summary.md`。
+
+## 文档本体的演进边界
+
+- 本目录新增文档随发布包发布（`package.json` `files` + manifest `packageRequired` 显式条目），但 **不**投影到目标项目 init surface（AC-7）；目标项目 init 仍只投影语言无关的 `runtime-boundaries.md`。
+- `runtime-boundaries.md` 是边界真源；本目录其他文档交叉引用，不复制其 import 方向表 / governance-hook 表 / 版本化自举边界表。
+- 未来如有能力落地，应先改 `src/`/CLI/ADR/completed plan，再回写本目录的「已实现」表。

package/docs/architecture/facts-and-state.md

@@ -0,0 +1,58 @@
+# 事实与状态
+
+本页说明 `.harness/` 各根目录、canonical facts、derived read models 与不可变规则，并逐条标出 canonical|derived 与 writable|read-only。完成权威是 shell verification（ADR 0001）；model verdict、Observe、报告都是 derived 或 advisory 视图。
+
+## 六类运行态对象
+
+| 对象 | 物理根 | 源码入口 | 性质 |
+| --- | --- | --- | --- |
+| Task | `.harness/tasks/<taskId>/` | `src/task/runtime.ts` `getTaskDir` | canonical，可写 |
+| DAG run | `.harness/dag-runs/{active,paused,completed}/<runId>/` | `src/workflows/dag/lifecycle.ts` `DAG_RUNS_DIR` | canonical，active/paused 可写；completed 受 guard |
+| one-shot run | `.harness/runs/{active,completed,failed}/<slug>/` | `src/infrastructure/harness/one-shot-run-store.ts`（逻辑封装见 `src/records/one-shot-runs.ts`） | canonical；active 可写，completed/failed 为终态事实 |
+| Loop | `.harness/tasks/<taskId>/loop/` | `src/workflows/loop/**` | canonical，**不是独立根**，是 task 之上的多轮状态机 |
+| Task Pool | `.harness/task-pool/`（唯一根） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002） | canonical，可写（Worker 专用，可选） |
+| Observe snapshot | Worker 内存/HTTP 派生视图 | `src/worker/observability/read-model.ts` `buildGlobalSnapshot` | **derived**，advisory |
+
+### 区分要点
+
+- **Task vs DAG run**：Task 是用户意图的源（`source/`、需求、执行约束、artifacts）；DAG run 是一次执行实例，`<runId>/` 下落 spec、state、节点 artifacts、skill snapshot、controller identity（`controller-identity.json`，冻结执行 controller 的 package version/binary 哈希/portable fingerprint，state 记录相对 ref 与内容哈希，resume 时重新校验、漂移 fail closed）、decision envelope、convergence。
+- **DAG run vs one-shot run**：DAG run 在 `.harness/dag-runs/`，有三态 lifecycle；one-shot run（当前主要由 `cursor-prompt` 及显式 one-shot evidence 路径产生）在 `.harness/runs/`，三态为 `active|completed|failed`。`pi-prompt` 当前不创建该目录下的 run evidence。两者是不同根、不同 schema。
+- **Loop 不是顶层根**：Loop 状态在 `.harness/tasks/<taskId>/loop/`，是 task 之上的多轮状态机（round、signal、context、failureStreak、closeout）。
+- **Task Pool 是 Worker 专用可选根**：只有使用 `agent-worker` 产品线时才存在；唯一根 `.harness/task-pool/`。
+- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
+
+## canonical（可写）
+
+- `.harness/tasks/<taskId>/` — `getTaskDir`。
+- `.harness/dag-runs/{active,paused}/<runId>/` — run 进行中 / 暂停。
+- `.harness/runs/active/<slug>/` — one-shot 运行中；完成或失败后通过 store 迁移到终态目录。
+- `.harness/tasks/<taskId>/loop/` — Loop 状态机。
+- `.harness/task-pool/` — Worker Task Pool（可选）。
+
+`.harness/prompts/` 与 `.harness/init-surface.json` 属于初始化投影/控制资料，不是一次执行的 canonical run fact，需与上面的任务和 run 对象区分。
+
+## canonical（只读 / 不可变）
+
+- `.harness/dag-runs/completed/<runId>/` — 除 runner 终态 `persistState({ allowCompletedFactsWrite: true })` 与显式 `dag reconcile-run`（`--action supersede|abandon` + reason，runner 已证明停止）外只读。
+- `.harness/runs/completed/<slug>/` 与 `.harness/runs/failed/<slug>/` — one-shot 终态事实；公共写接口只对 active run 开放，完成/失败通过 store 迁移。
+- `completed-facts-guard.ts`（`src/infrastructure/harness/`）是 completed 路径 enforcement 入口：`assertHarnessWriteAllowed(targetPath, { repoRoot, allowCompletedFactsWrite? })`。
+- promotion（completed → task artifacts 回填）由 `src/records/promotion.ts` 经 `loadCompletedDagEvidence` 读 completed state 后写 task artifacts。
+
+## derived / advisory（不可作完成权威）
+
+| 视图 | 来源 | 为何不可作权威 |
+| --- | --- | --- |
+| Observe snapshot / 首页 KPI | `buildGlobalSnapshot` 投影 `.harness/` + Task Pool | derived；投影失败安全降级 |
+| decision envelope 的 model verdict | `decision` / `riskLevel` 解析自文本 | `advisoryOnly: true`（`decision-envelope.ts` / `decision-evidence.ts` / `lifecycle.ts`） |
+| canvas / event observer | `notifyRunObserver` / `notifyNodeObserver` | try/catch 吞；明确派生视图，不 affect canonical 执行 |
+| DAG report / doctor | `src/application/dag/report-dag.ts` + `src/workflows/dag/report.ts`；doctor 在 `src/workflows/dag/lifecycle.ts` | 只读总结，operator 决策辅助 |
+| knowledge-curator proposal | `src/workflows/dag/knowledge-curator.ts` | advisory process guidance，不改 accepted learned skill |
+| morning report / metrics | `src/worker/report/**` | derived 统计，含分母/样本量/缺失说明 |
+
+## 完成权威
+
+完成权威 = shell command 的 exit code 与归档 stdout/stderr。执行入口是 `src/executors/shell-executor.ts`，环境/preset helper 在 `src/executors/shell-verification.ts`；`node.verifyEvidence` 保存 DAG authoring 提供的验证阶段、命令来源与标签等元数据。model verdict、Observe、报告都不构成完成判定。
+
+## init 投影的 `.harness` 入口
+
+`init --profile full` 在目标项目创建 `.harness/tasks`（directory）、`.harness/dag-runs/active`（directory）、`.harness/prompts/analyze.md`（generated）、`.harness/init-surface.json`（state）。这些是 init surface，不在 `packageExcluded`/`initExcluded` 范围；详见 `docs/init-surface.manifest.json`。

package/docs/architecture/runtime-boundaries.md

@@ -1,12 +1,13 @@
 # Runtime Boundaries
 
-本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把「命令、文档、import 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
+本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把命令、文档、import 架构、controller identity 与 run-owned execution facts 收敛为可机器校验的边界契约。
 
 ## 分层概览
 
 ```text
 Skill layer
-  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
+  ├─ DAG/runtime 入口策略（skills/loop-agent/）
+  └─ Feature/Task Pool 外层 operator 路由（skills/agent-worker/）
 
 CLI layer (src/cli/)
   └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
@@ -18,11 +19,14 @@ Workflow runtime (src/workflows/)
   └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
 
 Executors (src/executors/)
-  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
+  └─ Pi / Shell / Static 等受治理外部工具适配；不应依赖 commands 或 CLI formatting
+
+Sidecars (src/sidecars/)
+  └─ 显式手工 one-shot 工具（如 cursor-prompt）；不得被 workflows/application/task/worker 依赖
 
 Worker adapter (src/worker/)
-  └─ 产品线 TaskSpec / Task Pool / Observe 本地适配；以子进程调用已发布 loop-agent CLI，
-     不得 in-process import CLI、commands 或 application
+  └─ 产品线 TaskSpec / Task Pool / Observe 本地适配；冻结已发布 loop-agent controller identity，
+     以绝对子进程 launch spec 调用 CLI，不得 in-process import CLI、commands 或 application
 
 Infrastructure / Store (src/infrastructure/，逐步引入)
   └─ .harness 文件系统副作用、run lifecycle、原子写入规则
@@ -35,8 +39,9 @@ Governance (scripts/check-*.sh, src/governance/)
 
 ### Skill layer
 
-- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
-- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
+- **位置**：`skills/loop-agent/**` 与 `skills/agent-worker/**`
+- **职责**：`loop-agent` skill 定义单个 DAG/runtime 工作的入口、硬规则与 reference 路由；`agent-worker` skill 只定义 Feature Packet、TaskSpec、Task Pool、controller pinning、自举 release train 与失败恢复的外层 operator 路由。
+- **路由边界**：DAG leaf node 不得递归启动 `agent-worker`；`agent-worker` 不得加入 `DEFAULT_SKILLS_BY_ROLE`，也不实现 executor、scheduler、prompt 或 write guard。
 - **禁止**：在入口 skill 中重复维护 CLI command 列表或与 `src/cli/catalog.ts` 冲突的事实源。
 
 ### CLI layer
@@ -56,35 +61,44 @@ Governance (scripts/check-*.sh, src/governance/)
 ### Workflow runtime
 
 - **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
-- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排。
+- **职责**：DAG spec 校验与执行、dynamic workflow 编译与 expansion、Loop 状态机与 action 编排；新 DAG run 在任何节点执行前创建 run-owned resolved skill profile snapshot，并在普通节点、dynamic child、approve/resume 路径执行 integrity gate。
+- **skill snapshot 契约**：snapshot ref 使用 run-relative `.runtime/skill-snapshot.json` 与原始 bytes SHA-256；ref、artifact、profile 或 binding 不一致时 fail closed，不允许回退 live skill resolution。旧 run 只有在 ref 与 artifact 都不存在时，才可在 resume 前标记为 `legacy-resume-backfill` 并冻结剩余节点。
 - **允许依赖**：`src/executors/**`、`src/task/**`、`src/records/**`、`src/shared/**`、application use-case（目标态）。
 - **禁止**：`import` 来自 `src/commands/**`（见下方过渡例外）。
 
 ### Executors
 
 - **位置**：`src/executors/**`
-- **职责**：封装 Cursor SDK/CLI、Pi SDK/CLI、shell 执行与 write guard。
-- **允许依赖**：`src/shared/**`、外部 SDK。
-- **禁止**：依赖 `src/commands/**` 或 CLI 输出格式。
+- **职责**：封装 Pi SDK、shell 执行、static 输出与 write guard。受治理 Agent runtime 只有 Pi。
+- **允许依赖**：`src/shared/**`、外部 SDK（不含 `@cursor/sdk`）。
+- **禁止**：依赖 `src/commands/**`、CLI 输出格式，或 import `src/sidecars/**` / `@cursor/sdk`。
+
+### Sidecars
+
+- **位置**：`src/sidecars/cursor-prompt/**`
+- **职责**：`cursor-prompt` one-shot 手工干预；仅在显式调用时动态加载 `@cursor/sdk`。
+- **禁止**：被 `src/workflows/**`、`src/application/**`、`src/task/**`、`src/worker/**` 或普通 `src/executors/**` import。
 
 ### Worker adapter
 
 - **位置**：`src/worker/**`，独立 `agent-worker` CLI 为 `src/worker/cli.ts`。
 - **职责**：TaskSpec 校验与物化、Task Pool batch/retry/morning report under `.harness/task-pool/`、失败路由，以及只读 Observe 事件/快照/UI；实际 DAG 执行通过 `LoopAgentClient` 启动已发布的 `loop-agent` 子进程。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root，旧路径不读取、不迁移、不合并、不重映射。
+- **controller identity**：写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前解析并冻结 schemaVersion 1 identity，包括 package name/version、绝对 entry/real entry、直接可执行 launch spec、binary SHA-256 和覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable fingerprint。expected version/fingerprint 不匹配时 fail-fast；后续 spawn 不重新查询 PATH。
+- **证据传播**：canonical Worker record、Task Pool run、batch/Feature、QA/final evidence 可选携带同一 identity；只有所有相关层都省略 identity 时才按 legacy evidence 接受，部分缺失或锚点不一致会拒绝。
 - **允许依赖**：TaskSpec、Task Pool、observability、Node filesystem/path 与明确的 shared/task contract；它不是第二套 executor 或 DAG kernel。
 - **禁止**：in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`。
 
 ### Infrastructure / Store
 
 - **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
-- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
-- **DAG recovery mutation**：`dag reconcile-run` 是显式 operator 边界；默认仅检查，只有给出 action + reason 且 runner 已证明停止时才能保存原始快照、写 terminal reconciliation facts 并迁移 lifecycle。Observe、status 和 doctor 始终只读。
-- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
+- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。DAG run 自有的 `.runtime/skill-snapshot.json` 随 lifecycle 目录整体迁移，state 只保存相对 ref 和 hash，不保存 active/paused/completed 绝对路径。
+- **DAG recovery mutation**：`dag reconcile-run` 是显式 operator 边界；默认仅检查，只有给出 action + reason 且 runner 已证明停止时才能保存原始快照、写 terminal reconciliation facts 并迁移 lifecycle。Observe、status 和 doctor 始终只读。
+- **禁止**：把 raw path mutation 扩散给 runner、loop action 或 command handler。
 
 ### Governance
 
 - **位置**：`scripts/check-repo.sh` 及子脚本、`src/governance/**`、相关 Vitest。
-- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、skill entry 完整性。
+- **职责**：在 CI / in-flight DAG 中检测文档链接、exec plan 状态、架构 import、command registry 漂移、两个公共 skill entry 与 init/package surface 完整性。源码仓库另提供 `scripts/self-host-canary.mjs` 作为 repo-maintainer candidate takeover 证据入口；它不属于发布 package surface。
 
 ## 允许的依赖方向
 
@@ -111,6 +125,17 @@ Infrastructure        ──────────>   Shared / node:fs
 Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
 ```
 
+## 版本化自举边界
+
+版本化自举包含两个不同的冻结层，不能用其中一个替代另一个：
+
+| 层 | 冻结对象 | 生命周期 | 权威证据 |
+|---|---|---|---|
+| Controller identity | 实际发布包、entry/realEntry、launch spec、binary hash、portable package fingerprint | Feature/batch/Task/final verification | Worker、Task Pool、batch/Feature、QA/final evidence 中的 `controllerIdentity` |
+| DAG skill snapshot | 某个 run 实际注入 prompt 的 ordered skill profiles、learned flag、budgets 与 dynamic bindings | 单个 DAG run，包括 pause/resume | `state.skillSnapshotRef` + `<runDir>/.runtime/skill-snapshot.json` |
+
+源码仓库的 deterministic candidate canary 是第三类、只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，并只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false`、`modelExecutorObserved=false` 和 `featureExecutedTasks=[]`，因此不能被描述为 live Pi takeover，也不承担 candidate-package Pi skill source resolution 证明；snapshot 定向测试和真实 DAG evidence 单独承担后者。
+
 **规则摘要**
 
 | From | May import | Must not import |
@@ -136,9 +161,12 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 |--------|----------|----------|
 | `scripts/check-architecture-boundaries.sh` | workflow/executor forbidden import，及 Worker → CLI/commands/application import | 新的未 allowlist violation |
 | `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
-| `scripts/check-skill-entry.sh` | `SKILL.md` reference 文件存在、行数阈值 | reference 缺失（fail）；行数 > 220（warn） |
+| `scripts/check-exec-plan-index-sync.sh` | `docs/exec-plans/{active,completed}` 目录文件 vs 对应 `README.md` 索引 | 任一 plan 文件未在索引登记 |
+| `scripts/check-skill-entry.sh` | `loop-agent` / `agent-worker` 的 frontmatter、required references、入口行数与 operator trigger vocabulary | 任一公共 skill 缺失、reference/trigger 漂移或入口超过 hard limit |
+
+版本化自举相关 exec plan：`docs/exec-plans/active/2026-07-13-versioned-self-hosting-bootstrap.md`。
 
-相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
+`src/governance/exec-plans.ts` 是 exec-plan 创建、完成与索引校验的共享 TypeScript 事实源：`plan create`/`plan complete`/`plan check` 与 `dag run-task` 前置校验都调用它。`scripts/check-exec-plan-index-sync.sh` 是独立的 shell 最终防线，与 TypeScript checker 并存；两者均不删除或弱化。
 
 ### 验证命令
 

package/docs/architecture/system-overview.md

@@ -0,0 +1,93 @@
+# 系统全景
+
+本页用一张全景图说明 loop-agent、agent-worker、治理层与外部系统的关系。依赖方向、import 边界与 governance hook 是契约级事实，权威源是 `runtime-boundaries.md`（本页只交叉引用，不复制）。
+
+## 两个 CLI 二进制
+
+发布包 `@tea-agent/loop-agent` 提供两个入口（见 `package.json` `bin`）：
+
+| 二进制 | 入口 | 角色 |
+| --- | --- | --- |
+| `loop-agent` | `bin/loop-agent.js` → `src/cli.ts` | 仓库级 AI coding 任务运行时与治理控制器 |
+| `agent-worker` | `bin/agent-worker.js` → `src/worker/cli.ts` | 产品线 TaskSpec / Feature / Task Pool / Observe 外层适配 |
+
+两个二进制是独立进程，不共享 in-process runtime。`agent-worker` 真正执行 DAG 时通过已发布的 `loop-agent` 子进程调用（详见 `worker-and-feature.md`）。
+
+## 分层概览（交叉引用）
+
+完整分层图、各层职责、允许/禁止的 import 方向见 `runtime-boundaries.md` §分层概览 与 §各层职责。一句话摘要：
+
+```text
+Skill layer      skills/loop-agent、skills/agent-worker（Markdown，非 TS import）
+CLI layer        src/cli/ — argv 解析、调用 application/handler、格式化输出
+Application      src/application/ — typed use-case（validate/run/generate DAG 等）
+Workflow runtime src/workflows/ — DAG / Dynamic / Loop 核心执行规则
+Executors        src/executors/ — Pi / shell / static 受治理外部工具适配
+Sidecars         src/sidecars/cursor-prompt — 显式手工 one-shot；不得被 workflow 自动依赖
+Worker adapter   src/worker/ — 产品线适配 + Observe；子进程调用已发布 loop-agent
+Infrastructure   src/infrastructure/ — .harness 副作用、run lifecycle、原子写入
+Governance       scripts/check-*.sh、src/governance/ — 防漂移机器校验
+```
+
+## 两条入口路径
+
+### 直接任务路径
+
+```text
+人类 / 主 agent
+  │  写任务源与执行约束（.harness/tasks/<taskId>/source）
+  ▼
+loop-agent（runtime + 治理控制器）
+  │  dag run-task / validate / run-dag / report / doctor / reconcile-run
+  ▼
+workflow runtime（调度 Pi / shell / static 节点）
+  │  证据落入 .harness/dag-runs/{active,paused,completed}/<runId>/
+  └─ report / doctor / promote / closeout 读取并投影证据
+```
+
+### 产品线 Feature 路径
+
+```text
+人类 / 外部调度器
+  → agent-worker（TaskSpec / Feature / Task Pool）
+  → 冻结 controller identity
+  → spawn 已发布 loop-agent 子进程
+  → 同一 DAG runtime 与 executor registry
+  → DAG facts + Task Pool records
+  → Feature review / morning report / Observe（派生只读视图）
+```
+
+`agent-worker` 位于核心 runtime 的**上游调用侧**，不是 DAG 执行完成后的必经下游。Observe 可以在任一路径后读取现有事实，但不会改变执行结果。
+
+## 外部边界
+
+- npm 发布包：`@tea-agent/loop-agent`，包含两个 bin 与静态能力资料。
+- 目标仓库：`loop-agent init` 投影语言无关治理资料；源码仓库专用架构文档只随包可读，不默认投影。
+- 本地文件系统：`.harness/` 保存运行态事实；Git 工作树保存代码、治理文档与长期交接资料。
+- 远程 Git/PR/CI、云 Worker 与云 Task Pool 当前不是核心 runtime 的已实现内置边界，见 `evolution.md`。
+
+## 治理层入口
+
+治理检查是机器校验，不是文档约定。主入口：
+
+- `scripts/check-repo.sh` — 聚合入口，CI / in-flight DAG 均调它。
+- 子脚本：`scripts/check-architecture-boundaries.sh`（import 边界）、`scripts/check-command-registry-drift.sh`（command registry）、`scripts/check-skill-entry.sh`（公共 skill entry）、`scripts/check-doc-index.sh` / `scripts/check-doc-links.sh`（文档链接）、`scripts/check-init-surface.sh`（package/init surface 契约）、`scripts/check-init-evolution-needed.sh`（高影响变更需报告）。
+- `src/governance/**` — 治理逻辑与相关 Vitest。
+- `scripts/self-host-canary.mjs` — 源码仓库的 deterministic candidate takeover 证据入口；**不**属于发布 package surface。
+
+完整的 governance hook 表（哪个脚本检查什么、失败条件）见 `runtime-boundaries.md` §Governance 钩子。
+
+## 受治理 Agent runtime = Pi-only
+
+自 0.10.0 起受治理 Agent runtime 硬切为 Pi-only（ADR 0001）。DAG 中 `dagNodeExecutorSchema = z.enum(["pi","shell","static"])`；`executor: "cursor"` 会抛 `CURSOR_DAG_EXECUTOR_REMOVED_ERROR`。`cursor-prompt` 仅保留为显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。详见 `dag-execution.md` 与 `runtime-boundaries.md` §Executors / §Sidecars。
+
+## 运行态 vs 治理资料 vs 用法文档
+
+| 位置 | 内容 | 权威性质 |
+| --- | --- | --- |
+| `.harness/` | 任务、DAG run、one-shot run、Task Pool、live state | 运行态事实（canonical + derived） |
+| 根目录 `docs/` | 原则、边界、计划、报告、模板 | 治理权威 |
+| `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
+| `skills/` | agent 可加载的入口与 reference | 运行时可加载 |
+
+`.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。

package/docs/architecture/worker-and-feature.md

@@ -0,0 +1,81 @@
+# Worker 与 Feature 架构
+
+本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与 Observe。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
+
+## 核心事实：子进程，非 in-process
+
+`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
+
+| 事实 | 源码入口 |
+| --- | --- |
+| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
+| 执行入口 | `LoopAgentClient.run(args, options)` |
+| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
+| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
+
+`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
+
+## controller identity（冻结的已发布 controller）
+
+每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `schemaVersion` | 固定 `1` |
+| `packageName` | 必须为 `@tea-agent/loop-agent` |
+| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
+| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
+| `binarySha256` | `actualEntry` 二进制 hash |
+| `packageVersion` | `package.json` version |
+| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
+
+关键方法：
+
+- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
+- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
+- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
+
+CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
+
+controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
+
+## 独立 CLI
+
+`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
+
+## 产品线 read model
+
+### TaskSpec
+
+- schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
+- 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
+
+### Task Pool
+
+- 唯一 runtime root：`src/worker/pool/run-store.ts`
+  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
+- 旧顶层路径不读取、不迁移、不合并、不重映射。
+- batch/retry/morning report 等都基于此根。
+
+### Feature（M2 交付闭环）
+
+- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
+- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
+- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
+- 权威证据：`CHANGELOG.md [0.10.0]`、`docs/reports/2026-07-12-m2-completion-audit.md`。
+
+### Observe（只读 read model）
+
+- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
+- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
+- Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
+
+## 版本化自举的 deterministic canary
+
+源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
+
+## 不变式
+
+- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
+- Worker 不实现 executor、scheduler、prompt 或 write guard。
+- `agent-worker` skill（`skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。

package/docs/cursor-prompt-sidecar.md

@@ -0,0 +1,36 @@
+# cursor-prompt Sidecar
+
+`cursor-prompt` 是显式、手工触发的 one-shot sidecar。它不是受治理 Agent runtime，也不参与 DAG、Loop 自动写入、Delegate `--auto-run` 或 task writer 选择。
+
+## 产品定位
+
+| 路径 | 角色 |
+|---|---|
+| Pi DAG (`implement-pi` / `repair-pi`) | 唯一受治理 Agent writer |
+| shell / static | 确定性验证与静态输出 |
+| `cursor-prompt` | 人工 one-shot 干预；成功不等于任务完成 |
+
+## 用法
+
+```bash
+loop-agent cursor-prompt --cwd . "bounded task prompt"
+loop-agent cursor-prompt --file <path>
+loop-agent cursor-prompt --stdin
+loop-agent cursor-prompt --model <id>
+loop-agent cursor-prompt --timeout <ms>
+loop-agent cursor-prompt --stream
+loop-agent cursor-prompt --list-models
+```
+
+调用时才加载 `@cursor/sdk`。缺少 SDK 或 `CURSOR_API_KEY` 时，只有这条命令失败；普通 Agent DAG / doctor / init 不要求 Cursor。
+
+## 约束
+
+- 不读取 `harness.json` task config / DAG facts 作为授权来源。
+- 不复制 DAG `writeSet`、repair、resume 或 Loop auto-execute 能力。
+- 返回后由主会话检查 diff，并显式运行 shell verification。
+- one-shot evidence 写入 `.harness/runs/{active,completed,failed}`。
+
+## 迁移说明
+
+旧 `executor: "cursor"` DAG、`executors.cursor`、`loopAutoWritePolicy` 与 `cursor-fix` 已硬切删除。需要写入时请重新生成 Pi-only DAG，或仅在人工干预场景使用本 sidecar。

package/docs/decisions/README.md

@@ -1,3 +1,15 @@
 # 决策
 
-本目录存放架构决策记录（ADR）。
+本目录存放架构决策记录（ADR）。模板见 `docs/templates/adr.md`。
+
+## 索引
+
+| ADR | 状态 | 摘要 |
+| --- | --- | --- |
+| [`0001-pi-only-agent-runtime.md`](0001-pi-only-agent-runtime.md) | accepted | 受治理 Agent 仅 Pi；`cursor-prompt` 为显式 sidecar |
+| [`0002-task-pool-runtime-root.md`](0002-task-pool-runtime-root.md) | accepted | Task Pool 唯一根 `.harness/task-pool/`，旧 `.task-pool/` 不兼容 |
+| [`0003-docs-dual-tree-converge.md`](0003-docs-dual-tree-converge.md) | accepted | `website/docs/` 用法 vs `docs/` 治理；docs-converge 检查表 |
+
+新增跨版本架构取舍时：用模板新增 `NNNN-title.md`，并更新本表。不要把 ADR 正文复制进 `website/docs/`。
+
+实施细节与证据仍以对应 `docs/exec-plans/completed/` 与 `CHANGELOG.md` 为准；ADR 只固化决策边界。