@tea-agent/loop-agent 0.10.0 → 0.11.0

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 只固化决策边界。

package/docs/design/README.md

@@ -2,33 +2,53 @@
 
 `docs/design/` 存放将 `loop-agent` 作为更大产品线 agent 平台内仓库本地 runtime 的规划笔记。这些是设计输入，不是 `src/` 已具备该能力的证明。
 
-## 文档
+## 契约与实现映射（优先读）
 
-| 文档 | 用途 |
-|---|---|
-| `DESIGN-cursor.md` | Observe 暖白运行控制台采用的 Cursor 风格视觉参考与设计 token |
-| `DESIGN-lovable.md` | Lovable 风格的暖色视觉系统参考 |
-| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
-| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
-| `六个月规划.md` | 六个月路线图与目标架构 |
+| 文档 | 用途 |
+|---|---|
 | `taskspec-to-loop-agent-mapping.md` | 将产品线 TaskSpec 适配为 `loop-agent` task 的契约 |
+| `taskspec-to-loop-agent-mapping.yaml` | 同上契约的结构化对照表 |
 | `state-and-failure-taxonomy.md` | 文档、Task Pool、DAG、Loop 共用的 canonical status 与 failure taxonomy |
-| `archive/2026-07-07-agent-worker-plan.md` | 已归档：Worker 落地计划（基线 0.3.0，M1-M7 物化/调用/Task Pool/batch/morning report 路线图；已随 0.8.0 发布实现于 `src/worker/`） |
-| `archive/2026-07-07-taskspec-plan.md` | 已归档：TaskSpec v0.1 schema 设计（基线 0.3.0，TaskSpec/AcceptanceSpec/TaskGraphSpec schema 与 materialize 规则；已实现于 `src/worker/task-spec/`） |
+| `frontend-implementation-workflow.md` | 前端 DAG 实现 / 评审 / 验证工作流与证据约定 |
+
+## 路线与产品线笔记（非实现证明）
+
+| 文档 | 用途 |
+|---|---|
+| `dynamic-workflow-dag-engine-roadmap.md` | Dynamic Workflow 适配分析与阶段规划；**页首有实现状态 / Pi-only 校准条**（已落地 vs 设计输入）；正文 Cursor 叙述视为历史 |
+| `六个月规划.md` | 长期路线；**第 1–2 月已收敛为 archive/reports 指针**，当前有效前瞻从第 3 月起 |
+| `产品线共享知识库.md` | 产品线文档仓库作为上游事实源 |
+| `研发模式.md` | 10 个工作日 Feature 团队工作流 |
+| `腾讯实践对当前项目的指引.md` | 腾讯 Harness Engineering 实践对本仓库的映射笔记 |
+
+## 视觉参考
+
+| 文档 | 用途 |
+|---|---|
+| `2026-07-14-loop-agent-self-update-notifier.md` | loop-agent CLI 自更新提醒设计（设计已确认，尚未实现；覆盖用户级状态、npm global 来源证明、精确安装与验证边界） |
+| `DESIGN-cursor.md` | Observe 暖白运行控制台采用的 Cursor 风格视觉参考与设计 token |
+| `DESIGN-lovable.md` | Lovable 风格的暖色视觉系统参考 |
+
+## 已归档
+
+| 文档 | 用途 |
+|---|---|
+| `archive/2026-07-07-agent-worker-plan.md` | 已归档：Worker 落地计划（基线 0.3.0，M1-M7；已随 0.8.0 发布实现于 `src/worker/`） |
+| `archive/2026-07-07-taskspec-plan.md` | 已归档：TaskSpec v0.1 schema 设计（已实现于 `src/worker/task-spec/`） |
 | `archive/2026-07-10-下一阶段任务-功能开发完成.md` | 已归档：真实样本、失败硬化与 QA 闭环的功能性开发完成记录 |
-| `archive/2026-07-10-observe-ui.md` | 已归档：agent-worker 本地只读可观测 UI v0 设计（事件流 / SSE / stale 诊断、事件契约与验收边界；OBS-001～010 已完成，0.9.0 暖白重设计在其上演进） |
-| `archive/2026-07-10-observe-ui-optimization.md` | 已归档：Observe UI 中文化、DAG-first 总览、进行中 DAG 置顶、read-model enrichment、Pi `session-events.jsonl` 落盘与过程时间线（UI-1～UI-9 已实现） |
-| `archive/2026-07-10-observe-ui-goal.md` | 已归档：OBS-001～010 逐任务进度看板（全部 ✅ done） |
-| `archive/2026-07-11-第一月规划.md` | 已归档：首月落地计划（0.8.0 发布 + Round 1/2/3 累计 20 runs / 10 success / 50% / 两次 owner morning decision，第一个月闭环目标全部达成） |
-| `archive/2026-07-11-第一月wbs.md` | 已归档：首月 WBS 与分工（与第一月规划配套，任务编号与估算为历史记录） |
-| `archive/2026-07-12-第二月规划.md` | 已归档：第二月本地 Feature 交付闭环计划（M2-01～08 全部完成；F-2026-002 完整 Closeout、F-2026-003 真实失败恢复闭环、月末硬指标全达成；完成审计见 `docs/reports/2026-07-12-m2-completion-audit.md`） |
+| `archive/2026-07-10-observe-ui.md` | 已归档：Observe UI v0 设计（OBS-001～010；0.9.0 暖白重设计在其上演进） |
+| `archive/2026-07-10-observe-ui-optimization.md` | 已归档：Observe UI 中文化与过程时间线（UI-1～UI-9 已实现） |
+| `archive/2026-07-10-observe-ui-goal.md` | 已归档：OBS-001～010 逐任务进度看板（全部 done） |
+| `archive/2026-07-11-第一月规划.md` | 已归档：首月落地计划（0.8.0 + Round 1/2/3 闭环） |
+| `archive/2026-07-11-第一月wbs.md` | 已归档：首月 WBS 与分工（历史记录） |
+| `archive/2026-07-12-第二月规划.md` | 已归档：第二月本地 Feature 交付闭环（M2-01～08；见 `docs/reports/2026-07-12-m2-completion-audit.md`） |
 
 ## 命名约定（2026-07-09 起）
 
 | 名称 | 含义 | 状态 |
 |---|---|---|
 | `loop-agent` | 仓库本地 runtime / 治理控制器 CLI | 已发布 |
-| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI（`bin/agent-worker.js`） | 已发布（0.5.0） |
+| `agent-worker` | 产品线 TaskSpec 批处理适配层 CLI（`bin/agent-worker.js`） | 已发布 |
 | `agent-platform` | 早期规划设想名；**不是**当前 CLI。若出现在六个月目标架构中，仅表示未来产品线 monorepo / 上层服务集合，不得写成可执行命令 |
 
 当前真实分层：
@@ -37,12 +57,12 @@
 产品线 docs / TaskSpec / TaskGraph
   → agent-worker（本地批处理适配）
     → loop-agent（runtime kernel）
-      → Cursor / Pi / shell / static
+      → Pi（受治理 Agent） / shell / static
+      → cursor-prompt（显式手工 one-shot sidecar，非受治理 writer）
 ```
 
 命令示例一律使用 `agent-worker`，不要再写 `agent-platform task ...`。
 
-
 ## 维护规则
 
 设计笔记变更时：
@@ -50,6 +70,7 @@
 1. 保持 TaskSpec 字段、status 名称、failure category 与命令示例与契约文档一致
 2. 未来平台组件标为目标架构，除非已存在于 `src/` 或 `scripts/`
 3. 当前 CLI 命令示例只用 `agent-worker` / `loop-agent`；`agent-platform` 仅可出现在“未来 monorepo/上层服务”语境，并显式标注未实现
-4. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md`
+4. `src/task/config-types.ts` 或 DAG profile routing 变更时更新 `taskspec-to-loop-agent-mapping.md` / `.yaml`
 5. DAG report category、Loop failure class 或 Task Pool state 变更时更新 `state-and-failure-taxonomy.md`
-6. 运行 `bash scripts/check-repo.sh`
+6. 过期月规划 / 已落地专题设计迁入 `archive/`，并更新本 README
+7. 运行 `bash scripts/check-repo.sh`

package/docs/development-principles.md

@@ -20,7 +20,7 @@ loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而
 2. 设计新行为前先搜索现有代码、文档、脚本与测试。
 3. Shell 验证是完成权威。
 4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
-5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
+5. Pi writer 节点必须由显式 allowed/forbidden paths 与 writeSet 约束；Cursor 仅可作为 `cursor-prompt` one-shot sidecar，不进入受治理 DAG/Loop 写入路径。
 6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
 7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
 8. 不要把隐藏流程状态只留在聊天里。
@@ -31,7 +31,7 @@ loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而
 
 - 源码：`src/`
 - 测试：`test/`
-- Skill 指令：`skills/`
+- Skill 指令：源码仓库和 npm 包内置在 `skills/`，目标项目 repo-local skills 在 `.agents/skills/`
 - 验证与维护脚本：`scripts/`
 - 治理与交接产物：`docs/`
 

package/docs/exec-plans/active/README.md

@@ -6,6 +6,6 @@
 
 当前 active execution plan：
 
-- `2026-07-12-observe-warm-console-redesign.md` — 以暖白、细边界和高密度信息架构重构 Observe Dashboard。
+- 暂无。
 
-- 已归档：第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。
+- 已归档：`../completed/2026-07-14-init-canonical-layout.md`、`../completed/2026-07-12-observe-warm-console-redesign.md`、`../completed/2026-07-14-website-docs-ia-and-converge.md`、`../completed/2026-07-13-versioned-self-hosting-bootstrap.md`、`../completed/2026-07-12-pi-only-agent-runtime.md`、第二月 M2-01～M2-08、`../completed/2026-07-11-observe-dashboard-page-system.md`、`../completed/2026-07-11-observe-dashboard-detail-refinement.md`、`../completed/2026-07-11-observe-terminal-dag-kpi.md`、`../completed/2026-07-11-observe-polling-efficiency.md`、`../completed/2026-07-11-command-performance-guardrails.md` 及更早计划。

package/docs/exec-plans/completed/README.md

@@ -4,6 +4,16 @@
 
 npm 包携带本 README 作为目录契约。具体 completed plan 属于目标仓库历史，不从 loop-agent 源码历史复制。
 
+- [`2026-07-14-init-canonical-layout.md`](2026-07-14-init-canonical-layout.md) — 目标项目治理资料统一到 `ai_workspace/loop-agent/` 与 `.agents/skills/`，并为旧布局提供保守安全迁移
+- [`2026-07-14-self-update-notifier-implementation.md`](2026-07-14-self-update-notifier-implementation.md) — 实现 loop-agent CLI 自更新提醒，覆盖拒绝版本、精确安装、npm global 来源证明和验证收口
+- [`2026-07-12-observe-warm-console-redesign.md`](2026-07-12-observe-warm-console-redesign.md) — 以暖白、细边界和高密度信息架构重构 Observe Dashboard；多轮细节调整后按用户确认收口归档。
+- [`2026-07-14-website-docs-ia-and-converge.md`](2026-07-14-website-docs-ia-and-converge.md) — Website 文档信息架构、双树边界与 `docs-converge` 同步机制
+- [`2026-07-14-frontend-spec-source-fallback.md`](2026-07-14-frontend-spec-source-fallback.md) — 统一前端规范来源为知识库优先、失败后强制检索当前项目 `openSpec/`
+- [`2026-07-13-test-environment-stability.md`](2026-07-13-test-environment-stability.md) — 修复 Windows Git Bash、npm CLI 启动与 Git/Delivery 测试资源分类，避免验证节点反复失败并跳过 DAG 收口
+- [`2026-07-13-sdd-embedded-skills.md`](2026-07-13-sdd-embedded-skills.md) — 目标项目 repo-local SDD skills 的可选 DAG 节点嵌入增强，loop-agent 保持流程、状态与写边界控制
+- [`2026-07-13-frontend-skill-contracts.md`](2026-07-13-frontend-skill-contracts.md) — 补齐前端节点 Skill 的输入、输出、证据与阻断契约，并预留组件/设计知识库接入 TODO
+- [`2026-07-13-versioned-self-hosting-bootstrap.md`](2026-07-13-versioned-self-hosting-bootstrap.md) — 固定已发布 controller identity、冻结 run-owned skills，并由隔离候选包完成 deterministic self-hosting takeover canary
+- [`2026-07-12-pi-only-agent-runtime.md`](2026-07-12-pi-only-agent-runtime.md) — 将 DAG、Loop、Delegate 和 Worker 收敛为 Pi-only 受治理 runtime，仅保留独立的 one-shot `cursor-prompt` sidecar
 - [`2026-07-11-m2-01-feature-review-model.md`](2026-07-11-m2-01-feature-review-model.md) — 第二月首个纵向切片：严格派生 Feature 状态、AC/Delivery/Closeout 证据与只读 `feature review`
 - [`2026-07-12-m2-02-feature-run-orchestration.md`](2026-07-12-m2-02-feature-run-orchestration.md) — Feature 级 dry-run 与复用现有 Worker pipeline 的薄编排入口
 - [`2026-07-12-m2-03-follow-up-tracer-bullet.md`](2026-07-12-m2-03-follow-up-tracer-bullet.md) — ProductBug 失败到人工批准 FIX、依赖重连、Ready 与 verified lineage 的纵向闭环
@@ -48,3 +58,5 @@ npm 包携带本 README 作为目录契约。具体 completed plan 属于目标
 - [`2026-07-10-obs-009.md`](2026-07-10-obs-009.md) — stale、quiet 与 timeout-risk 诊断
 - [`2026-07-10-obs-010.md`](2026-07-10-obs-010.md) — Failure Inbox、文档、package surface 与 smoke 验证
 - [`2026-07-10-observe-ui-review-remediation.md`](2026-07-10-observe-ui-review-remediation.md) — 修复 Observe UI 事件链路、历史 run 投影、artifact 安全边界与失败状态展示
+
+- [`2026-07-13-exec-plan-lifecycle.md`](2026-07-13-exec-plan-lifecycle.md)

package/docs/feature-workflow.md

@@ -90,7 +90,7 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 2. `dag validate` 校验 schema、依赖、governance profile、写边界、model routing、shell 验证元数据
 3. `run-dag` 加载 DAG、按拓扑排序为 ranks、有界并发执行可运行节点、持久化到 `.harness/dag-runs/<lifecycle>/<run-id>/`，并转入 `completed` 或 `paused`
 
-标准生成的 hybrid DAG 默认无 Cursor：
+标准生成的 hybrid DAG 固定为 Pi-only writer：
 
 ```text
 contract-pi
@@ -102,7 +102,26 @@ contract-pi
   -> closeout-pi
 ```
 
-`implement-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。当 `harness.json` 显式禁用 Pi 并启用 Cursor 时，实现与修复 writer 节点改用 `implement-cursor` / `repair-cursor`。
+`implement-pi` / `repair-pi` 使用 `executor: "pi"` 与 `toolProfile: "write"`。受治理 runtime 不再生成或接受 `implement-cursor` / `repair-cursor`；旧 Cursor DAG 会在 schema 校验阶段失败，需要重新生成。
+
+前端任务可通过 `task.json.taskKind = "frontend-implementation"` 选择专用模板：
+
+```text
+frontend-contract-pi
+  -> frontend-scout-pi
+  -> frontend-plan-pi
+  -> frontend-design-gate-pi
+  -> frontend-design-gate-shell
+  -> frontend-implement-pi
+  -> frontend-static-verify-shell
+  -> frontend-behavior-verify-shell
+  -> frontend-review-pi
+  -> frontend-review-gate-shell
+  -> frontend-closeout-pi
+```
+
+这条链在实现前加入 design gate，并将前端静态验证与行为验证分开建模；当前 MVP 不包含独立 a11y、视觉回归或浏览器自动化 executor。
+前端 shell 验证优先使用任务源 `需求.md` / `执行约束.md` 中声明的前端验证命令，例如 `npm run typecheck`、`npm run build`、`npm test`；解析不到时再使用 adapter 验证命令和模板 fallback。
 
 `verify-shell` 使用 adapter 根据 task verify preset/quota 解析出的最终验证命令，并把新鲜 exit code/stdout/stderr 交给后续只读 verifier。review-gated 模板继续插入：
 
@@ -112,12 +131,25 @@ verify-shell -> verify-pi -> review-pi -> review-gate-shell -> closeout-pi
 
 supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验证、process supervision、有界 repair、decision gates 与可选 convergence retry。
 
+### 可选 repo-local SDD skill 增强
+
+`dag run-task` 会在目标项目的 `.agents/skills/` 中探测三个可选 skill：
+
+- `SDD-requirement-analysis` → `contract-pi`
+- `SDD-design-analysis` → `plan-pi`
+- `SDD-implementation-test-review` → `implement-pi`、`repair-pi`、`verify-pi`、`review-pi`
+
+命中时，skill 通过节点 `skills` 进入现有 resolved instruction 和 run-owned snapshot 链路，并在节点任务中收到 embedded-mode 约束：只为当前 DAG 阶段提供知识、规范与方法，不得更新 `working_requirements_status.md`、推进 SDD 状态、触发 SDD 用户确认或执行归档。节点的读写边界、当前阶段与输出契约优先；writer 仍只允许写入显式 `writeSet`。`SDD-code-spec-init` 与 `SDD-project-how-to-spec-init` 不会在普通功能 DAG 中自动运行。
+
+探测不到这些 repo-local skills 时，DAG 不追加节点 skill 或约束块，保持当前默认流程。用户级或 npm 包内同名 skill 也不会作为自动启用信号。
+
 源码参考：
 
 - `src/commands/dag-run-task.ts`
 - `src/commands/dag-validate.ts`
 - `src/commands/run-dag.ts`
 - `src/workflows/dag/init-hybrid.ts`
+- `src/workflows/dag/sdd-embedded.ts`
 - `src/workflows/dag/runner.ts`
 
 监督 agent 仍负责：
@@ -130,6 +162,21 @@ supervised 模板在实现路径上增加 write-set audit、soft/hard shell 验
 
 声称 Production Readiness v0.1 的低/中风险单仓库任务，另须遵循 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md`。该标准冻结支持范围、非目标、必需 DAG 证据、failure routing 字段与最终验证门禁。
 
+## Exec-plan 生命周期
+
+exec-plan 不是手工文档；它有确定性 CLI 生命周期，并与 `dag run-task` 共享同一索引校验源。
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+loop-agent plan complete <plan-id> --summary "<summary>"
+loop-agent plan check
+```
+
+- `new-task` 不自动绑定 exec-plan；微小任务仍可不创建计划。
+- `plan create` 优先读取目标项目 `<governanceRoot>/templates/exec-plan.md`，不存在时回退到发布包内置模板；create/complete 同步 active/completed 索引，拒绝重复 id、路径穿越与不安全文件名，多文件操作均具备回滚保护。
+- `dag run-task` 在生成 DAG 草稿前运行 `plan check` 同源校验，索引漂移立即失败；空仓库与索引一致的仓库不受影响。
+- `plan list`（只读）与 `docs archive`（兼容入口）保留；`scripts/check-exec-plan-index-sync.sh` 仍作为独立最终防线。
+
 ## 已移除的顺序工作流
 
 历史 Level 1 顺序 command surface 已从公开工作流移除。新工作不要用 `loop-agent run analyze|plan|spec|implement|verify|retrospective|auto|loop|continue|study`。
@@ -147,13 +194,12 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 
 ## Outer Loop Runtime
 
-`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review、Cursor 修复或 DAG action，并选择下一自动 action。
+`loop` 命令是长跑任务控制层，与会话治理协议不是一回事。它记录 rounds 与 signals，可跑 shell 验证、Pi review 或 DAG action（review/execute），并选择下一自动 action。自动写入只能通过受治理 Pi-only Agent DAG execute；`loopAutoExecutionPolicy` 控制是否允许自动执行，旧 `loopAutoWritePolicy` 会 fail-fast。
 
 支持的 loop actions：
 
 - `shell-verify`
 - `pi-review`
-- `cursor-fix`
 - `dag`
 - `record-round`
 - `add-signal`

package/docs/harness-methodology-debugging.md

@@ -88,7 +88,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 ### Phase 4：实现
 
-1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `docs/harness-methodology-tdd.md`）
+1. **创建失败测试用例** — 遵循 RED-GREEN-REFACTOR（见 `harness-methodology-tdd.md`）
 2. **实现单一修复** — 解决已识别的根因，一次一个改动，不顺手重构
 3. **验证修复** — 测试通过？其他测试没坏？问题真的解决了？
 4. **如果修复无效**：