@tea-agent/loop-agent 0.13.0 → 0.14.0

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

@@ -1,71 +1,71 @@
-# 事实与状态
-
-本页说明 `.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/`（唯一根；state v2 见下） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002 / 0004） | 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/`。
-- **Task Pool state identity（ADR 0004）**：canonical 键为 `{ featureId, taskId }`（`TaskPoolTaskRef`），不是裸 `taskId`。
-- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
-
-### Task Pool state 布局与迁移
-
-| 路径 / 对象 | 性质 | 说明 |
-| --- | --- | --- |
-| `.harness/task-pool/states/<featureId>/<taskId>.json` | canonical 可写 | schema v2；路径解码 identity 必须与文件内容一致 |
-| `.harness/task-pool/states/<taskId>.json`（扁平 v1） | legacy | 不得静默猜 Feature；存在时 v2 写入 fail-closed |
-| `.harness/task-pool/runs.jsonl` / `events.jsonl` | canonical append-only | migration 不改写 JSONL；`workerRunId` 仍是执行历史键 |
-| `agent-worker pool doctor` | 只读诊断 | inventory + mapping 证据；exit 0 可有 findings |
-| `agent-worker pool migrate-state` | 显式迁移 | 默认 dry-run；`--apply --owner --reason` 才写入；失败全回滚 |
-
-`readFeatureTaskPoolStates` / `listTaskPoolStates` 是 v2 列表入口；deprecated `readAllTaskPoolStates` 仅扫描 legacy 扁平 state，不合并 v2。
-
-## 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` 范围；详见 `ai_workspace/loop-agent/init-surface.manifest.json`。
+# 事实与状态
+
+本页说明 `.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/`（唯一根；state v2 见下） | `src/worker/pool/run-store.ts` `TASK_POOL_RELATIVE_ROOT`（ADR 0002 / 0004） | 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/`。
+- **Task Pool state identity（ADR 0004）**：canonical 键为 `{ featureId, taskId }`（`TaskPoolTaskRef`），不是裸 `taskId`。
+- **Observe snapshot 不是事实源**：`buildGlobalSnapshot` 投影失败返回安全错误摘要而非全零健康，不改变执行成败。
+
+### Task Pool state 布局与迁移
+
+| 路径 / 对象 | 性质 | 说明 |
+| --- | --- | --- |
+| `.harness/task-pool/states/<featureId>/<taskId>.json` | canonical 可写 | schema v2；路径解码 identity 必须与文件内容一致 |
+| `.harness/task-pool/states/<taskId>.json`（扁平 v1） | legacy | 不得静默猜 Feature；存在时 v2 写入 fail-closed |
+| `.harness/task-pool/runs.jsonl` / `events.jsonl` | canonical append-only | migration 不改写 JSONL；`workerRunId` 仍是执行历史键 |
+| `agent-worker pool doctor` | 只读诊断 | inventory + mapping 证据；exit 0 可有 findings |
+| `agent-worker pool migrate-state` | 显式迁移 | 默认 dry-run；`--apply --owner --reason` 才写入；失败全回滚 |
+
+`readFeatureTaskPoolStates` / `listTaskPoolStates` 是 v2 列表入口；deprecated `readAllTaskPoolStates` 仅扫描 legacy 扁平 state，不合并 v2。
+
+## 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` 范围；详见 `ai_workspace/loop-agent/init-surface.manifest.json`。

package/docs/architecture/runtime-boundaries.md

@@ -1,191 +1,191 @@
-# Runtime Boundaries
-
-本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把命令、文档、import 架构、controller identity 与 run-owned execution facts 收敛为可机器校验的边界契约。
-
-## 分层概览
-
-```text
-Skill layer
-  ├─ DAG/runtime 入口策略（.agents/skills/loop-agent/）
-  └─ Feature/Task Pool 外层 operator 路由（.agents/skills/agent-worker/）
-
-CLI layer (src/cli/)
-  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
-
-Application layer (src/application/，逐步引入)
-  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
-
-Workflow runtime (src/workflows/)
-  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
-
-Executors (src/executors/)
-  └─ 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 controller identity，
-     以绝对子进程 launch spec 调用 CLI，不得 in-process import CLI、commands 或 application
-
-Infrastructure / Store (src/infrastructure/，逐步引入)
-  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
-
-Governance (scripts/check-*.sh, src/governance/)
-  └─ 防止 command registry、skill entry、import architecture 漂移
-```
-
-## 各层职责
-
-### Skill layer
-
-- **位置**：`.agents/skills/loop-agent/**` 与 `.agents/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
-
-- **位置**：`src/cli.ts`、`src/cli/**`
-- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
-- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
-- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
-
-### Application layer
-
-- **位置**：`src/application/**`（按计划逐步引入）
-- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
-- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
-- **禁止**：直接承担 CLI formatting 或 argv 解析。
-
-### Workflow runtime
-
-- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
-- **职责**：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/**`
-- **职责**：封装 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/**`、`.agents/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 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 与 init/package surface 完整性。源码仓库另提供 `scripts/self-host-canary.mjs` 作为 repo-maintainer candidate takeover 证据入口；它不属于发布 package surface。
-
-## 允许的依赖方向
-
-```text
-Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
-
-CLI                   ──────────>   Application (目标态)
-CLI                   ──────────>   Commands (handler 薄层)
-Commands              ──────────>   Application / Workflows / Infrastructure
-
-Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
-Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
-
-Executors             ──────────>   Shared / 外部 SDK
-Executors             ──X──>        Commands / CLI
-
-Worker adapter        ──────────>   TaskSpec / Task Pool / observability / 子进程 CLI contract
-Worker adapter        ──X──>        Commands / CLI / Application（in-process）
-
-Application           ──────────>   Workflows / Infrastructure / Task / Records
-Application           ──X──>        CLI formatting
-
-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 |
-|------|------------|-----------------|
-| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
-| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
-| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
-| `src/worker/**` | worker-local modules, task contracts, shared, Node APIs | `src/commands/**`, `src/cli/**`, `src/application/**` |
-| `src/cli/**` | commands, adapters, shared, application（目标） | — |
-| `.agents/skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
-
-## 已知过渡耦合
-
-当前没有允许的 `src/workflows/**` / `src/executors/**` forbidden import，也没有允许的 `src/worker/**` → `src/{cli,commands,application}/**` TypeScript import。
-
-`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors/worker` forbidden import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
-
-## Governance 钩子
-
-以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
-
-| Script | 检查内容 | 失败条件 |
-|--------|----------|----------|
-| `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-exec-plan-index-sync.sh` | `ai_workspace/loop-agent/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：`ai_workspace/loop-agent/exec-plans/active/2026-07-13-versioned-self-hosting-bootstrap.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 并存；两者均不删除或弱化。
-
-### 验证命令
-
-```bash
-bash scripts/check-repo.sh
-bash scripts/check-architecture-boundaries.sh
-bash scripts/check-command-registry-drift.sh
-bash scripts/check-skill-entry.sh
-```
-
-Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
-
-## 演进里程碑
-
-| Phase | 边界变化 |
-|-------|----------|
-| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
-| 1 | CLI command definition 单源 |
-| 2 | Skill entry 瘦身 + frontmatter references |
-| 3 | DAG application use-case；Loop 开始脱离 command JSON |
-| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
-| 7 | Harness Store / Repository 集中 `.harness` 副作用 |
+# Runtime Boundaries
+
+本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把命令、文档、import 架构、controller identity 与 run-owned execution facts 收敛为可机器校验的边界契约。
+
+## 分层概览
+
+```text
+Skill layer
+  ├─ DAG/runtime 入口策略（.agents/skills/loop-agent/）
+  └─ Feature/Task Pool 外层 operator 路由（.agents/skills/agent-worker/）
+
+CLI layer (src/cli/)
+  └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
+
+Application layer (src/application/，逐步引入)
+  └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
+
+Workflow runtime (src/workflows/)
+  └─ DAG / Dynamic / Loop 核心执行规则；不应依赖 commands
+
+Executors (src/executors/)
+  └─ 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 controller identity，
+     以绝对子进程 launch spec 调用 CLI，不得 in-process import CLI、commands 或 application
+
+Infrastructure / Store (src/infrastructure/，逐步引入)
+  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
+
+Governance (scripts/check-*.sh, src/governance/)
+  └─ 防止 command registry、skill entry、import architecture 漂移
+```
+
+## 各层职责
+
+### Skill layer
+
+- **位置**：`.agents/skills/loop-agent/**` 与 `.agents/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
+
+- **位置**：`src/cli.ts`、`src/cli/**`
+- **职责**：解析全局 flag（如 `--repo-root`）、解析 top-level / subcommand、调用 command handler、输出 help / JSON / Markdown。
+- **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
+- **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
+
+### Application layer
+
+- **位置**：`src/application/**`（按计划逐步引入）
+- **职责**：封装一次用户意图的 typed result（如 validate DAG、run DAG、report），供 CLI 与 workflow runtime 共用。
+- **允许依赖**：`src/workflows/**`、`src/infrastructure/**`、`src/task/**`、`src/records/**`。
+- **禁止**：直接承担 CLI formatting 或 argv 解析。
+
+### Workflow runtime
+
+- **位置**：`src/workflows/dag/**`、`src/workflows/dynamic/**`、`src/workflows/loop/**`
+- **职责**：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/**`
+- **职责**：封装 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/**`、`.agents/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 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 与 init/package surface 完整性。源码仓库另提供 `scripts/self-host-canary.mjs` 作为 repo-maintainer candidate takeover 证据入口；它不属于发布 package surface。
+
+## 允许的依赖方向
+
+```text
+Skill (docs)          ──advisory──>  CLI catalog / command-reference（人类可读，机器 drift check）
+
+CLI                   ──────────>   Application (目标态)
+CLI                   ──────────>   Commands (handler 薄层)
+Commands              ──────────>   Application / Workflows / Infrastructure
+
+Workflow runtime      ──────────>   Executors / Task / Records / Application (目标态)
+Workflow runtime      ──X──>        Commands  （目标态禁止；见过渡例外）
+
+Executors             ──────────>   Shared / 外部 SDK
+Executors             ──X──>        Commands / CLI
+
+Worker adapter        ──────────>   TaskSpec / Task Pool / observability / 子进程 CLI contract
+Worker adapter        ──X──>        Commands / CLI / Application（in-process）
+
+Application           ──────────>   Workflows / Infrastructure / Task / Records
+Application           ──X──>        CLI formatting
+
+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 |
+|------|------------|-----------------|
+| `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
+| `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
+| `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
+| `src/worker/**` | worker-local modules, task contracts, shared, Node APIs | `src/commands/**`, `src/cli/**`, `src/application/**` |
+| `src/cli/**` | commands, adapters, shared, application（目标） | — |
+| `.agents/skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+
+## 已知过渡耦合
+
+当前没有允许的 `src/workflows/**` / `src/executors/**` forbidden import，也没有允许的 `src/worker/**` → `src/{cli,commands,application}/**` TypeScript import。
+
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors/worker` forbidden import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+
+## Governance 钩子
+
+以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
+
+| Script | 检查内容 | 失败条件 |
+|--------|----------|----------|
+| `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-exec-plan-index-sync.sh` | `ai_workspace/loop-agent/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：`ai_workspace/loop-agent/exec-plans/active/2026-07-13-versioned-self-hosting-bootstrap.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 并存；两者均不删除或弱化。
+
+### 验证命令
+
+```bash
+bash scripts/check-repo.sh
+bash scripts/check-architecture-boundaries.sh
+bash scripts/check-command-registry-drift.sh
+bash scripts/check-skill-entry.sh
+```
+
+Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
+
+## 演进里程碑
+
+| Phase | 边界变化 |
+|-------|----------|
+| 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
+| 1 | CLI command definition 单源 |
+| 2 | Skill entry 瘦身 + frontmatter references |
+| 3 | DAG application use-case；Loop 开始脱离 command JSON |
+| 6 | `workflows → commands` import check 已从 advisory 改为 **fail** |
+| 7 | Harness Store / Repository 集中 `.harness` 副作用 |