@tea-agent/loop-agent 0.2.1 → 0.4.0

package/docs/agent-dag-runner.md

@@ -1,40 +1,42 @@
-# Agent DAG Runner
-
-Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
-
-## 基本用法
-
-```bash
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-```
-
-`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
-
-## Executors
-
-- `static`：确定性生成的 artifacts 或 notes
-- `shell`：验证与文件系统检查
-- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
-- `cursor`：显式启用时的可选有界写后端
-
-## Skills
-
-DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
-
-`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
-
-## Artifacts
-
-DAG artifacts 位于：
-
-```text
-.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
-```
-
-根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
-
-## Shell Gates
-
-- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。
+# Agent DAG Runner
+
+Agent DAG 是 loop-agent 的声明式编排 runtime。DAG 将工作拆为节点、按序执行 eligible ranks、记录 artifacts，并用 gate 做 review 与验证。
+
+## 基本用法
+
+```bash
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+`<temp-dir>` 为平台原生临时目录。Windows 上 `--output`、`--dag`、`--cwd` 的实际值用原生路径。
+
+## Executors
+
+- `static`：确定性生成的 artifacts 或 notes
+- `shell`：验证与文件系统检查
+- `pi`：规划、review、诊断；节点设 `toolProfile: "write"` 时有界写入
+- `cursor`：显式启用时的可选有界写后端
+
+## Skills
+
+DAG spec 可声明 `defaults.skills`、`skillsByRole` 与节点级 `skills`。Runner 从 `skills/<skill-name>/SKILL.md` 解析本地指令，并在各节点 `skills.json` artifact 中记录解析元数据。
+
+执行前可用 `dag validate --strict-skills` 做 opt-in skill audit；该门禁会在 missing/error/truncated skill 或 unresolved reference 出现时失败。默认 role skill 应来自 `docs/skills/vetted-skill-registry.md` 中记录的 repo-local wrapper。
+
+`loop-agent` skill 位于 `skills/loop-agent/SKILL.md`。遗留根路径 `skill/SKILL.md` 仅为旧 worktree 保留兼容 fallback。
+
+## Artifacts
+
+DAG artifacts 位于：
+
+```text
+.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
+```
+
+根目录 `artifacts/` 不是有效的默认 DAG artifact 位置。
+
+## Shell Gates
+
+- `shell.verdictGate` 从注入的当前 run 目录读取 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`；不应自行发现 active run paths。

package/docs/architecture/runtime-boundaries.md

@@ -1,147 +1,147 @@
-# Runtime Boundaries
-
-本文定义 loop-agent 各 runtime 层的 module interface、允许的依赖方向，以及治理检查 hook。目标是把「命令、文档、import 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
-
-## 分层概览
-
-```text
-Skill layer
-  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
-
-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/)
-  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
-
-Infrastructure / Store (src/infrastructure/，逐步引入)
-  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
-
-Governance (scripts/check-*.sh, src/governance/)
-  └─ 防止 command registry、skill entry、import architecture 漂移
-```
-
-## 各层职责
-
-### Skill layer
-
-- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
-- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
-- **禁止**：在入口 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 编排。
-- **允许依赖**：`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 输出格式。
-
-### Infrastructure / Store
-
-- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
-- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
-- **禁止**：把 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 完整性。
-
-## 允许的依赖方向
-
-```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
-
-Application           ──────────>   Workflows / Infrastructure / Task / Records
-Application           ──X──>        CLI formatting
-
-Infrastructure        ──────────>   Shared / node:fs
-Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
-```
-
-**规则摘要**
-
-| 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/cli/**` | commands, adapters, shared, application（目标） | — |
-| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
-
-## 已知过渡耦合
-
-当前没有允许的 `src/workflows/**` 或 `src/executors/**` → `src/commands/**` TypeScript import。
-
-`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
-
-## Governance 钩子
-
-以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
-
-| Script | 检查内容 | 失败条件 |
-|--------|----------|----------|
-| `scripts/check-architecture-boundaries.sh` | `workflows` / `executors` → `commands` 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） |
-
-相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
-
-### 验证命令
-
-```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 架构」从多处维护收敛为可机器校验的边界契约，而不在本阶段改变 runtime 行为。
+
+## 分层概览
+
+```text
+Skill layer
+  └─ 入口策略、reference 路由、硬规则（skills/loop-agent/SKILL.md + references/）
+
+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/)
+  └─ Cursor / Pi / Shell 等外部工具适配；不应依赖 commands 或 CLI formatting
+
+Infrastructure / Store (src/infrastructure/，逐步引入)
+  └─ .harness 文件系统副作用、run lifecycle、原子写入规则
+
+Governance (scripts/check-*.sh, src/governance/)
+  └─ 防止 command registry、skill entry、import architecture 漂移
+```
+
+## 各层职责
+
+### Skill layer
+
+- **位置**：`skills/loop-agent/SKILL.md` 及 `skills/loop-agent/references/**`
+- **职责**：定义 agent 何时启用 loop-agent、默认执行路径（Agent DAG）、硬规则与 reference 路由；不承载完整操作手册。
+- **禁止**：在入口 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 编排。
+- **允许依赖**：`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 输出格式。
+
+### Infrastructure / Store
+
+- **位置**：`src/infrastructure/harness/**`（按计划逐步引入）；过渡期部分逻辑仍在 `src/workflows/dag/lifecycle.ts`、`src/records/**`。
+- **职责**：`.harness/tasks`、`.harness/dag-runs`、`.harness/runs`、loop state 的集中读写；completed run facts 只读约束。
+- **禁止**：把 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 完整性。
+
+## 允许的依赖方向
+
+```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
+
+Application           ──────────>   Workflows / Infrastructure / Task / Records
+Application           ──X──>        CLI formatting
+
+Infrastructure        ──────────>   Shared / node:fs
+Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Application
+```
+
+**规则摘要**
+
+| 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/cli/**` | commands, adapters, shared, application（目标） | — |
+| `skills/**` | （Markdown 引用，非 TS import） | 运行时 TS 模块 |
+
+## 已知过渡耦合
+
+当前没有允许的 `src/workflows/**` 或 `src/executors/**` → `src/commands/**` TypeScript import。
+
+`scripts/check-architecture-boundaries.sh` 的 transitional allowlist 保持为空。任何新增的 `workflows/executors -> commands` import 必须导致检查 **exit 1**；如果未来确有临时例外，必须先写入 active exec plan，说明移除时间和验证门禁。
+
+## Governance 钩子
+
+以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
+
+| Script | 检查内容 | 失败条件 |
+|--------|----------|----------|
+| `scripts/check-architecture-boundaries.sh` | `workflows` / `executors` → `commands` 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） |
+
+相关 exec plan：`docs/exec-plans/active/2026-07-04-runtime-boundary-remediation.md`。
+
+### 验证命令
+
+```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/cursor-executor-usage.md

@@ -1,25 +1,25 @@
-# Cursor Executor 用法
-
-Cursor 用于有界写实现。每个 Cursor 写任务必须显式定义 scope。
-
-## Prompt 必填字段
-
-- task id
-- objective
-- allowed paths
-- forbidden paths
-- constraints
-- expected verification
-- 保留无关变更的指令
-
-## One-Shot Helper
-
-```bash
-loop-agent cursor-prompt \
-  --cwd . \
-  --timeout 1800000 \
-  --model composer-2.5 \
-  "<bounded task prompt>"
-```
-
-Cursor 返回后，主会话必须检查 diff 并运行相关验证命令。
+# Cursor Executor 用法
+
+Cursor 用于有界写实现。每个 Cursor 写任务必须显式定义 scope。
+
+## Prompt 必填字段
+
+- task id
+- objective
+- allowed paths
+- forbidden paths
+- constraints
+- expected verification
+- 保留无关变更的指令
+
+## One-Shot Helper
+
+```bash
+loop-agent cursor-prompt \
+  --cwd . \
+  --timeout 1800000 \
+  --model composer-2.5 \
+  "<bounded task prompt>"
+```
+
+Cursor 返回后，主会话必须检查 diff 并运行相关验证命令。

package/docs/decisions/README.md

@@ -1,3 +1,3 @@
-# 决策
-
-本目录存放架构决策记录（ADR）。
+# 决策
+
+本目录存放架构决策记录（ADR）。

package/docs/design/README.md

@@ -1,36 +1,36 @@
-# 设计笔记
-
-`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
-
-## 文档
-
-| 文档 | 用途 |
-|---|---|
-| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
-| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
-| `1个月规划.md` | 首月落地计划 |
-| `1月wbs.md` | 首月 WBS 与分工 |
-| `六个月规划.md` | 六个月路线图与目标架构 |
-| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
-| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
-
-## 当前实现边界
-
-`loop-agent` 当前拥有：仓库本地 harness、Agent DAG 生成/验证/执行、shell 验证、artifacts、reports、Loop state。它不是产品线 Task Pool、Orchestrator、docs-sync 服务、Git/CI 平台或 artifact store。
-
-设计文档使用两类 profile 名称：
-
-- **Business task profiles**：`backend-feature`、`frontend-feature`、`qa-casegen`、`qa-testcode`、`reviewer-gate`
-- **`loop-agent dag run-task --profile` governance profiles**：`auto`、`minimal`、`standard`、`reviewed`、`supervised`
-
-除非 CLI 显式扩展支持，否则不要把 business task profile 直接传给 `loop-agent dag run-task --profile`。用 `taskspec-to-loop-agent-mapping.md` 将 business profile 路由到当前 governance profile。
-
-## 维护规则
-
-设计笔记变更时：
-
-1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
-2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
-3. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
-4. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
-5. 运行 `bash scripts/check-repo.sh`
+# 设计笔记
+
+`docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
+
+## 文档
+
+| 文档 | 用途 |
+|---|---|
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
+| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
+| `1个月规划.md` | 首月落地计划 |
+| `1月wbs.md` | 首月 WBS 与分工 |
+| `六个月规划.md` | 六个月路线图与目标架构 |
+| `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
+| `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
+
+## 当前实现边界
+
+`loop-agent` 当前拥有：仓库本地 harness、Agent DAG 生成/验证/执行、shell 验证、artifacts、reports、Loop state。它不是产品线 Task Pool、Orchestrator、docs-sync 服务、Git/CI 平台或 artifact store。
+
+设计文档使用两类 profile 名称：
+
+- **Business task profiles**：`backend-feature`、`frontend-feature`、`qa-casegen`、`qa-testcode`、`reviewer-gate`
+- **`loop-agent dag run-task --profile` governance profiles**：`auto`、`minimal`、`standard`、`reviewed`、`supervised`
+
+除非 CLI 显式扩展支持，否则不要把 business task profile 直接传给 `loop-agent dag run-task --profile`。用 `taskspec-to-loop-agent-mapping.md` 将 business profile 路由到当前 governance profile。
+
+## 维护规则
+
+设计笔记变更时：
+
+1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
+2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
+3. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
+4. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
+5. 运行 `bash scripts/check-repo.sh`