@tea-agent/loop-agent 0.13.0 → 0.15.0

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` 副作用 |

package/docs/architecture/system-overview.md

@@ -1,93 +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      .agents/skills/loop-agent、.agents/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） |
-| 根目录 `ai_workspace/loop-agent/` | 原则、边界、计划、报告、模板 | 治理权威 |
-| `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
-| `.agents/skills/` | agent 可加载的入口与 reference | 运行时可加载 |
-
-`.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。
+# 系统全景
+
+本页用一张全景图说明 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      .agents/skills/loop-agent、.agents/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） |
+| 根目录 `ai_workspace/loop-agent/` | 原则、边界、计划、报告、模板 | 治理权威 |
+| `website/docs/` | 使用者/贡献者导读与操作说明 | 用法双树 |
+| `.agents/skills/` | agent 可加载的入口与 reference | 运行时可加载 |
+
+`.harness/` 内部哪些可写、哪些只读、哪些是 derived，详见 `facts-and-state.md`。