# Concurrency and Landing

定义单写者模型、本地互斥租约、共享工作树的路径安全、受保护分支落地序列。
在任何 maker 编辑、commit、rebase、push 或发布之前加载本文件。

前提：现在同一台机器上经常有多个 agent / 多个 worktree 共享同一个 git 仓库。
"我是唯一在改这个仓库的人"是一个**必须被证明的假设**，不是默认事实。

## 并发模型

- **产品级归属真相**：外部协调面（Issue claim、任务票、协调评论）——跨 run、跨机器可读。
- **机器级互斥**：仓库 git common directory 下的原子租约——同一 git 仓库内的排他。
- **跨机器正确性栅栏**：Git fast-forward / rebase + 远端 ancestry 回读。

以下**不能**当作开发锁：

- CI/Actions 的 concurrency group（它序列化 workflow，不序列化本地编辑和 commit）；
- worktree 本地的锁文件（共享同一 git 仓库的兄弟 worktree 看不见它）；
- 分支名、Git author/login、进程列表；
- 外部 DB / Redis / 新建 secret。

## Git-common-dir 租约

锁目录：

```bash
$(git rev-parse --path-format=absolute --git-common-dir)/<automation>/locks/
```

用原子 `mkdir` 获取，然后写**不可变**元数据：
`owner`(稳定 owner ID) / `run`(run ID) / `token`(每次获取随机) /
`purpose`(`maker` 或 `landing-<branch>`) / `created_epoch` / `expires_epoch` / `worktree` / `pid`。

写完**逐字段回读**。缺失、重复、格式错误、不匹配或未知元数据一律判为冲突。
**绝不能只凭 PID 推断归属。**

### 过期与释放

- **不要原地续租。** TTL 覆盖一个有界增量即可。
- 过期时，把锁目录**原子重命名**到唯一的 stale 隔离名，再获取新锁。
  因为元数据不可变，过期不会和续租竞争。
- 只有 owner + run + token + purpose 四项都与回读一致时才释放。
  释放方式是原子 rename 到唯一路径再删除该路径；**绝不 `rm -rf` 活锁路径**。
- 进程猝死时，交给下一个 controller 去隔离过期的不可变租约。
- 时间或元数据有歧义时 fail closed。

### Maker 租约

第一次写入之前获取 `maker`，持有一个有界编辑增量。获取后、写入前
**重新校验产品级归属**（Issue claim 可能已被别人接管）。
maker checkpoint + 本地针对性 gate 通过后释放。

只读的调查者/checker 可以不持 maker 租约运行——除非它在一个正在变化的工作树上
跑 dev server。**把浏览器/dev-server checker 视为持有隐式读租约**：
在服务器和浏览器停止之前，不允许启动 maker。

### Landing 租约

在下列整个序列之前获取 `landing-<target>`，并**全程持有**：

路径归属校验 → staging → commit → fetch/rebase → push → 远端 ancestor 回读。

这防止共享同一 git common dir 的两个 worktree 同时成为 commit/push owner。

## 共享工作树路径安全

staging 之前：

1. **拒绝任何已存在的 staged 内容**，包括恰好落在本次请求路径下的内容
   （别人可能刚 stage 了同一个文件）。
2. fetch，并要求 HEAD 等于目标或只落后于目标；干净时快进，**不要 stash**；
   有脏重叠就停。ahead/diverged 状态在 commit 之前就失败。
3. 要求一份**精确、规范化、仓库相对**的文件清单。拒绝绝对路径、仓库外路径、
   目录、glob、重复项、Git 元数据、状态文件、不安全的缺失路径和特殊文件。
4. 逐个 stage 清单文件，并要求 staged 集合**等于**清单；禁止后代目录匹配。
5. 如果一个任务自有路径里同时含有无法归因的并发编辑，停止并报告冲突。

**绝不使用 `git add -A` / `git add .`。**
**绝不 stash / restore / checkout / reset / 覆盖他人的改动。**
同一个文件混合归属且无法安全分离时，停止并报告碰撞。

## 受保护分支落地序列

在 landing 租约下：

1. 校验请求路径、初始索引为空、远端关系、staged diff。
2. 只把任务自有路径提交为**一个** run-owned commit。
3. run-commit 身份校验与清单相等性**分开**校验。如果 hook 改变了提交的路径集合：
   soft-reset 该 HEAD 到记录的父提交、用 mixed reset 恢复初始空索引、回读 HEAD/索引、
   保留所有工作树字节，然后在 push 之前停止。
4. 遇到 non-fast-forward：只有在 checkout 干净时才 rebase/重试。存在他人脏状态时，
   只 soft-reset 已证明属于本 run 的那个 commit 到其父提交、unstage 显式任务路径、
   回读 unstaged diff，然后停止。
5. 其它任何失败的落地路径，**要么证明该 commit 已到达远端，要么执行同样的
   精确单 commit 回滚**；绝不留下孤立的未推送 commit。
6. 用 `git push origin HEAD:refs/heads/<target>` 显式 refspec 推送。
7. 再次 fetch。
8. 要求 `git merge-base --is-ancestor <delivery-sha> origin/<target>` 成功。

**绝不 force push。**

## 远端 non-fast-forward

把 non-fast-forward 拒绝当作**可能的跨机器竞争**，不是覆盖的许可。

最多两个恢复周期：fetch 目标 → 校验本地任务 commit 和路径归属仍可归因 →
rebase 到 fetch 到的目标 → 任何冲突或意外的任务路径变化都停止 →
重试显式 refspec push → fetch 并回读 ancestry。

网络/TLS 重试单独计次。保留原始 Git 错误分类，但不要打印凭据。

**本地租约只证明同 git-common-dir 的排他性，它不能证明另一台机器是空闲的。**
Git 快进/rebase + 远端回读才是跨机器的正确性栅栏。
有界重试后仍无法证明 ancestry、任务路径身份或排他落地归属时，fail closed。

## Review / 部署归属

review 之后的所有最终 mutation 由**同一个 landing owner** 负责。
checker 可以提出修改建议，但**不 commit、不 push**。
修复路由回 maker → 重跑相关 gate → 由 landing owner 执行唯一一次最终落地序列。

一批任务共用一套部署/review，但每一项都要记录自己独立的验收和终态决定。

## 清理时的成果保护顺序

清理必须"先证明成果不会丢失，再删东西"：

1. `git status --short --untracked-files=all`，区分任务文件、用户文件、其它并发任务文件；
2. 确认本任务 commit 已推到目标远端（`git log origin/<t>..HEAD` 为空
   且 `git merge-base --is-ancestor <task-commit> origin/<t>` 成功）；
3. 发现有效但未推送的 commit → 先按保护分支规则 push/rebase，**再**清理；
   推不上去就 hard-stop 并保留 worktree，报告抢救路径。
   **绝不为了"清理干净"删除成果。**
4. 只删除能证明由本任务创建的路径；禁止宽泛 glob；状态文件最后删。

# Evidence and Verification

定义证据分级、事故身份、验证 lane、根因表述和关闭条件。
在设计测试、跑 E2E、写根因结论或决定"能不能关"之前加载本文件。

## 证据阶梯 (Evidence ladder)

每一条实质性结论都必须带证据等级标签。不带标签的"验证通过"不算验证。

| 级别 | 证据 | 它证明了什么 |
| --- | --- | --- |
| L0 | 假设、读代码、防御性推理 | 一个看似合理的机制，不是观察到的行为 |
| L1 | 单元测试 | 局部函数/类的行为 |
| L2 | 集成测试、fixture、构造的 API/浏览器流程 | 在人造身份下的边界接线是通的 |
| L3 | 目标环境上的**原始事故身份**或显式等价数据身份 | 用户报告的那条失败路径确实被修好了 |
| L4 | 部署后的真实复发观测 / 干净巡检 | 后验遥测；有价值，但 L3 通过后不构成关闭前提 |

铁律：

- **绝不能把 L0–L2 描述成历史根因已证实。** 一个防御性兜底阻断了某类失败，
  不等于证明了那类失败就是本次事故的原因。
- fixture-only 的 L2 通过**永远不能关闭**一个用户报告的 bug。
- 加了兜底之后"跑通了"，只说明兜底生效，不说明原路径坏在哪。

## 精确事故身份 (Exact incident identity)

任何用户报告的缺陷，验收前必须先记录隐私安全的事故身份：

- 规范化的来源 URL/ID、产物 ID/hash、会话/任务 ID、请求指纹或等价物；
- 目标环境 + 相关的修复/部署 watermark（用来区分复发和历史残留）；
- 期望行为 vs 实际行为；
- 原件不可用时，替代样本为什么在实质上等价。

禁止持久化：原始邮箱、IP、user agent、token、请求体、secret、支付标识、
未经限制的第三方 payload。用白名单字段和 HMAC/固定分类替代。

如果精确身份不可得、已过期、不安全查看，或由无法访问的外部系统控制，
就报告 **bounded unknown**。fixture 仍可以验证接线，但不能关闭该缺陷。

## 等价身份 (Equivalent identity)

只有在保留了所有与本次修复因果相关的输入时，才接受等价样本：

- 同一 parser / provider / 路由 / 运行时消费方；
- 同一格式/schema/版本和边界条件；
- 同一授权/权益类别；
- 同一目标环境配置；
- 同一触发失败的物质属性。

逐条写出等价论证。"同一个模块""同一个标签""内容差不多"都不够。

## Lane 选择

按**运行时消费方**选 lane，不按文件名选。

- `local-only`：所有改动的消费方都在本地可完整执行的边界内（如纯浏览器 bundle），
  后端/接口契约/环境变量/迁移/运行时加载的 prompt 与配置全部未变，
  本地开发服务器能跑通完整用户旅程。
- `deployed-required`：任何后端/混合消费方、API 或生成客户端契约、迁移、
  env/secret/部署配置、运行时加载的 prompt/skill、认证回调、SSR/edge、
  远端专属行为——**或任何不确定**。
- `verify-only`：无代码变更；一旦需要修复就升级为 bug-fix 类型。

**Fail closed 到 `deployed-required`。** 拿不准就按需要部署处理。

## 客观 gate 设计

代码变更要求这条链：

1. 有针对性的本地检查和测试（命令退出码 0）；
2. 与 lane 匹配的**独立** E2E（checker ≠ maker）；
3. 受保护的落地（见 `concurrency-and-landing.md`）；
4. 独立 review 合并门；
5. 与影响面匹配的 review 后复验；
6. 最终交付审计。

## 运行时证据 vs 表面成功

带静默 fallback 的链路坏掉时功能照常响应——只有日志能暴露。因此：

- 校验请求/响应**和**规范化的持久状态，不只看 UI；
- 校验可访问性语义（role / name / aria-label）和正确的滚动容器；
- 校验 console / network 语义；
- 当 fallback 可能让失败看起来像成功时，必须校验预期的运行时日志 marker、
  数据行或计费/指标记录；
- 取证后关闭 dev server 和浏览器进程。

三条配套规则：

1. **外部凭证的权限面是独立于代码的配置面。** 网关 key 的模型 allowlist、
   API key 的 scope、配额——代码+部署完成不代表凭证就绪；改了调用目标就必须
   同任务核对所有环境的凭证权限。test 验过不代表 prod 凭证同样就绪。
2. **空 catch / 无日志 catch 包外部调用是缺陷，不是风格问题。**
   它把配置漂移变成不可见的降级。发现时必须补可查询的日志 marker。
3. **验证一条链路前先给它加打点。** 打点本身经常当场暴露此前静默存在的故障。

截图只是佐证，不是规范状态的证明。

## 多目标验收（批处理）

一次实现/部署/review 链可以共享，但**验收必须逐项独立**：

```text
目标项 | 事故身份 | 证据等级 | 精确/等价论证 | 期望结果 | 客观证据 | 关闭判定
```

不允许把一批作为整体关闭。A 项过了 L3、B 项还停在 L2 时，
只关 A，B 保留归属和一个有界的下一步动作。

## 根因语言

这四个词必须精确使用，禁止混用：

- `confirmed root cause` —— 有直接的事故/运行时证据把失败连到那个边界；
- `supported mechanism` —— 代码 + L1/L2 证据让该机制"很可能"成立；
- `defensive hardening` —— 改动阻断了一类问题，但没证明历史因果；
- `bounded unknown` —— 事故身份或权威证据缺失。

不要把一个产品方案、一个兜底或一次无关的成功样本说成已证明的根因。

## 独立 review 输入边界

给 checker 的是：确认过的需求、diff/树身份、gates 和证据。
**不给 maker 的推理过程**——否则 checker 只是在复读 maker 的乐观。

要求 blocking review 覆盖：

- 最小安全实现与复用；
- 隐私/secret 与环境边界；
- 注释、i18n、生成客户端、迁移、部署 preserve；
- 未经授权的删减（unauthorized subtraction）与跨服务门漂移；
- 证据等级表述是否准确、是否用 L2 冒充 L3；
- 批次身份与归属终态。

发现问题路由回 maker 修，然后**只重跑受影响的那个 gate**。

## 关闭规则

目标环境部署 + 客观测试 + 独立 review，在精确或显式等价的 L3 证据通过时
**就是充分的**。不要等 L4 自然流量或"下一轮巡检干净"再关。

如果修复本身正确但 L3 身份无法建立，**不要宣称已修复**。
保留归属 + 一个真实的有界技术动作 + 说明缺什么证据和客观的解除条件。

## 部署后观测

把 L4 当遥测处理：

- 干净观测增强信心，但不构成已成立关闭的前置门；
- 精确的 post-watermark 真实复发才触发重开路径；
- 相邻症状或合成回放不构成复发；
- 绝不从隐私保护的聚合证据反推历史身份。

---

## 被同一个假设播种过的 N 个 agent，不构成 N 份独立证据（2026-08-22，独立 checker 抓到）

一次关键词调研派了三个 agent，分别去读日本 SERP、挖日本社区、挖韩国社区。
三份报告都指向同一个结论：「诊断别人」（测伴侣/测父母）是个无人服务的需求。
主循环于是向用户报告：**三种方法、两个国家、互不相干，指向同一件事，
这比任何单一来源都硬。**

**这句话是错的。** 独立 checker 去查每份 brief，发现**三份 brief 都是主循环自己写的，
而且每一份都写了同一句话**：「特别留意那些测别人而不是测自己的东西，
这可能是比自我诊断更大的市场」。

三个 agent 不是三个盲测的观察者，是**三次被下了同一个提示的定向搜索**。
它们各自去自己的平台上找到了支持性证据——引用是真的、来源是独立的、
checker 逐条核实过——但「收敛」这个词描述的强度不成立。
**这是三次确认同一个先验，不是三次独立发现。**

### 判据

派多个 agent 交叉验证同一件事时，问一个问题：

> **如果这个假设是错的，我的 brief 会不会让 agent 也报告「找到了」？**

会 → 那就不是独立验证，是确认偏误的并行放大。
自然语料尤其危险：论坛和 SERP 里几乎总能找到支持任何假设的帖子，
「我找到了 20 条支持它的引用」在样本量足够大时不构成证据。

### 做法

- **要真独立，就不要在 brief 里写假设。** 让 agent 去回答开放问题
  （「这些人在焦虑什么？按主题分组」），而不是去验证一个命题
  （「找找有没有人在测伴侣」）。假设应当从汇总里**浮现**，而不是被派下去。
- 做不到就**如实降级措辞**：不说「三份独立研究收敛」，
  说「三份研究在同一个被提示的方向上各自找到了独立来源的证据」。
  后者依然有价值，只是强度低一档。
- **谁写的 brief，谁负责标注这件事。** 这个错误不是 agent 犯的——
  agent 忠实执行了 brief。是编排者把自己播下的种子当成了发现。

### 与「多数表决」的关系

同理适用于 adversarial verify：派 3 个 skeptic 去质疑同一条结论，
如果 brief 里已经暗示了倾向，三票就不是三票。
对抗性验证的前提是**验证者不知道你希望的答案是什么**。

# Execution Budget

约束 goal、subagent、等待和状态记账的成本。目标是减少空跑和上下文膨胀，
**不降低** maker-checker 分离、验证强度或自包含交付门。
在制定 goal、派 subagent、决定要不要等待、或判断"还能不能再来一轮"时加载本文件。

## 1. Goal 合同

普通任务使用运行状态文件；仅当用户或系统明确要求持久 Goal 时才创建，一个任务最多一个 active goal。phase、重试和 subagent 不另建 goal。

objective 用 1–3 句、最多 600 字符写清可判定终态、客观验证、归属/隐私/环境限制，以及用户或权威自动化合同明确设置的上限。未设置的上限记为 null，不自行设定任务级硬停止次数、时长或 token 预算，也不添加固定 stop phrase。

迭代数、修复回合、耗时和花费持续累计，用于检查进展和调整策略；内部估算只作 checkpoint 阈值。相同失败签名重复三次时，停止原样重试，调查并选择新的可测试路径；仍有安全下一步时继续，不能按估算耗尽宣布 blocked。

任务必要的付费验证可自动执行，不额外索要授权；优先复用现有结果和账户，重复失败必须先调查并调整策略，不能无限重复付费请求。此规则不包含充值、购买订阅或变更套餐。用户明确设置的费用和执行上限始终有效，不得自行抬高。

phase 表和验收矩阵保存在状态文件，goal 只描述终点。只有所有交付和验证条件都成立，才将显式创建的 goal 标记完成。

## 2. Subagent 预算

下表统计的是"**不同 agent 数**"。修复回合优先复用原 agent，
同一 agent 多轮对话不重复计数。

| 任务形态 | 默认上限 | 预期角色 |
| --- | ---: | --- |
| 无候选的周期性 dispatcher | 0 | 只做确定性主线程 preflight |
| 有界的文档 / skill / verify-only / research | 2 | 一个 maker 或调查者 + 一个独立 checker |
| 单子系统代码变更 | 3 | maker + E2E checker + review checker |
| 跨系统或多仓库代码变更 | 4 | 最多两个互不相交的 maker + E2E checker + review checker |

规则：

- 同时只能有**一个写类 maker** 操作同一工作树。
  只读 checker 只有真正独立且能并行推进时才并发。
- 需要超预算时：先 close 已完成的 agent，并在状态文件记录
  缺失的能力、为什么不能复用、新增角色、以及客观的结束条件。
  **"想再确认一次"不是超预算的理由。**
- maker 返回可修 finding 时，把窄修复发回**同一个 maker**；
  checker 只复判，不接管实现。
- 模型档位按宿主平台的能力映射为 routine / critical 两档：
  日常有界 maker、checker 和机械核对走 routine；
  只有跨系统歧义、架构决策、对抗性 review、困难 debug 或准确性关键判断才升级到 critical。
  升级原因记入 telemetry。**不要用"更强总是更好"替代路由判断。**
  不要把某个平台专有的 model ID 或 reasoning 参数强塞给不支持该字段的工具。

## 3. 等待预算

- **只有下一步被该结果阻塞时才等待**；否则立刻推进不重叠的工作。
- 每个委派结果最多做**一次** 90–120 秒的阻塞等待。超时后不立即发起第二次等待。
- 完成其它可推进工作后，最多做一次状态检查；仍无进展时，缩小 brief 并复用/中断原 agent，
  或 close 掉由主线程完成。
- **禁止连续 wait / list 轮询或短周期 polling。**（各平台的等待与列举原语名字不同，
  这条约束与具体工具名无关。）
- CI / 部署等待走另一套节流：核心服务每 3–5 分钟最多查一次，
  旁支服务每 5–10 分钟最多查一次，第一次检查默认延后 5 分钟，
  失败才拉日志且只拉失败 job 的关键片段。不与 subagent 等待预算混用。

## 4. 失败签名与记账

**失败签名 = phase + 客观 gate + 观察到的失败 + 失败边界。**
只有四项**全部相同**时才累加重复计数。

如果前一个 gate 已被证明修好、失败点向下游移动了，
那是 **progressive discovery**：重置该签名的计数，但全局预算继续累计。

一次性的 shell 引号错误、命令拼写错误、harness 瞬态失败属于
**orchestration diagnostic**，改正后记一行即可，**不计入 repair cycle**。
只有产品 gate、实现边界或同一稳定失败签名的失败才计入 repair cycle。

重试必须改变一个**可测试的**假设、边界、实现策略或证据来源。
换个说法、重跑同一个检查、再等一次、"再看一眼"都不是自适应推进。

## 5. Telemetry

每轮只在状态文件记汇总，**不要粘贴完整 agent 输出**：

```text
goal 字符数 | spawned/reused/closed agent 数 | maker/checker 数
| routine/critical 路由数量与升级原因 | wait 与状态检查次数 | context compaction 次数
```

## 6. 按 phase 加载引用（上下文效率）

**不要在任务开始时加载所有引用文件。** 按需加载：

| 时机 | 加载 |
| --- | --- |
| goal / loop / checkpoint | `execution-budget.md` |
| 归属、认领、批次选择 | `ownership-and-tracker.md` |
| maker 编辑 / commit / push | `concurrency-and-landing.md` |
| 测试设计 / E2E / 关闭判定 | `evidence-and-verification.md` |
| 交付、复盘、规则晋升、最终审计 | `learning-and-audit.md` |
| 任务形态模板 | `phase-library.md` 中对应那一节 |

同理：专项 skill 每个任务只发现和加载一次，把选择写进 checkpoint，
后续 phase 直接复用；只有出现此前无法预见的全新专项领域才增量发现一次。

# Learning and Final Audit

定义强制复盘、受控的规则晋升、重复防护、最终审计序列和交付报告。
在交付阶段，以及任何时候一次运行想要修改持久化指导（skill / 规则文件 / 文档）时加载本文件。

## 强制复盘

**每个任务都要复盘，包括一次跑通的干净任务。** 记录：

- 什么证据改变了计划；
- 哪个 gate 抓到了真实缺陷或阻止了浪费；
- 结论是任务专属的还是可泛化的；
- 是否已有规则覆盖了它；
- 晋升是否成立。

**不要为了凑数强行晋升。** `no-promotion` + 一个理由是合法且必需的结果。

## 候选格式

在状态文件里逐条写：

```text
candidateId:
observed task evidence:      # 本次任务的直接证据
general rule:                # 抽象出来的规则
scope and exclusions:        # 适用范围与排除项
objective gate:              # 客观或可复核的判定方式
duplicate search:            # 查过哪些真相源
eval change:                 # 加/强化了哪个 eval
independent checker:         # 谁独立校验的
decision:                    # promoted / no-promotion / run-specific
reason:
delivery SHA:
```

候选里不得含 secret、个人数据、完整请求体或未经限制的日志。

## 重复搜索与真相源归属

晋升前先搜：目标 skill 的 `SKILL.md`、全部 `references/`、相关脚本与 eval、
同项目的其它 skill、项目规则文件（`CLAUDE.md` / `AGENTS.md`）。

**按职责指定唯一真相源**，例：

- 编排流程规则 → 本 skill 的对应 reference；
- 仓库架构 → 项目规则文件 / 项目 dev skill；
- 测试账号与验收 → 项目 test skill；
- 远程操作与事故命令 → 项目 debug skill；
- review 政策 → 项目 review skill。

**替换或强化已有真相源，不要在入口文件追加一条平行规则。**
两处写同一条规则 = 未来必然漂移。

## 晋升门

全部满足才允许改动权威规则：

1. 一个真实任务产出了直接的、隐私安全的证据；
2. 教训能泛化到单个事故之外；
3. 规则有确定性或可客观复核的 gate；
4. 新增或强化了一个 eval，它在规则前失败、规则后通过；
5. 一个**独立** checker 校验了范围、非重复、证据准确性和该 eval；
6. 规则、eval、脚本/测试和其它必需文档**落在同一个交付 commit**。

真正跨仓库、无法共用一个 commit 的晋升：先定义一个显式交付事务——
两个仓库名、不可变 SHA、ancestry/回读 gate、落地顺序、回滚/前向补齐规则、
一个事务 ID 写进两边的持久协调面，并要求独立 checker 校验这一对。
**不要把两个无关 commit 称为原子，也不要只落一个 SHA 就宣布晋升。**

任一条不满足 → 不改权威规则，记 no-promotion 理由：
run-specific / 证据不足 / 不可泛化 / 与既有规则重复 / 无客观 gate /
无可用 eval / checker 拒绝 / 超出授权范围。

## 入口膨胀防护

- 技能入口 `SKILL.md` 只放：触发条件、铁律、快速流程、阶段路由、导航、红旗。
  细节放进唯一负责的 reference。
- 单个 reference / 源文件保持在 500 行以内，除非是生成产物或协议声明并写明理由。
  超了就**按职责拆分**，不要继续追加。
- 改完 skill 跑结构校验（行数上限、引用完整性、eval、契约），失败按 blocking 处理。

## Eval 设计

正反两面都要覆盖。每条编排规则都应该配对抗性输入，诱导 agent 去：

- 按标签而不是精确根因合批；
- 排除一个仅仅被 assign 了、但尚未开始的 OPEN 工单；
- 接受一个 draft；
- 在存在活跃落地冲突时继续推进；
- 用 mock/fixture 证据关闭用户报告的缺陷；
- 在关闭之前先释放归属；
- 没有证据/eval/checker 就晋升规则；
- 越过 goal 上限继续跑。

期望输出必须客观，并点名相关真相源。

## 最终审计序列

声称完成之前逐项执行：

1. 每个计划内 phase 都已完成，或有理由充分的 N/A；
2. 每个工单都有独立的事故身份、证据、评论和终态决定
   （用**一次**权威快照同时读 URL/状态/标签/assignee/评论，并用同一份快照做终态总结与严格解析）；
3. 已授权远端交付时，每个交付 SHA 都是目标远端分支的 ancestor，且被结构化交付账本归因；
4. 每个交付 commit 的 diff 都落在精确文件清单内、清单中每个文件都被这些 commit 覆盖、
   已授权提交/推送的成果均已交付；仅本地交付允许保留未提交 diff 或本地 commit
   （被删除的文件只有在某个已声明 commit 证明了它的 `D` 转换、
   且当前检出与远端都确实不存在时才算通过）；
5. 至少一条学习决定走完了完整晋升门、被带理由拒绝，或被标为 run-specific；
6. 改了 skill 就跑结构校验；
7. 跑最终审计脚本（若有）；纯 research / verify-only 且无持久交付时必须显式声明该豁免；
8. 所有交付审计通过之后，state-only 模式仅将运行状态标记完成并回读；只有用户或系统明确请求并已创建 Goal 的 explicit-goal 模式，才将该 Goal 标记完成并回读。不得在收尾补建 Goal。

**绝不把 subagent 的一句"done"当作审计证据。**

## 交付报告

写两层，简洁。

### 产品层

- 交付的行为，逐条对回一开始确认的需求回读；
- 精确的验收步骤和期望结果；
- 有意的取舍或被安全关闭（flag-gated）的范围；
- 需要外部决策的动作，尤其是生产发布。

### 技术层

- phase / skill / 结果路线；
- 改动文件、交付 SHA 和远端 ancestry 证明；
- 本地、目标环境和独立 review 的证据；
- 每项的事故/证据/终态矩阵；
- 隐私、secret、迁移、配置和部署 preserve 状态；
- 迭代数、修复回合数和被刹停的失败签名；
- 学习晋升与 no-promotion 理由；
- 只写残余风险，不写流水账。

**把"已完成"和"待外部动作"分开写。绝不把未完成的实现伪装成用户的决策。**

# Ownership and Tracker

定义任务票（GitHub Issue / GitLab / Jira / 任何工单系统）的可选资格、认领与回读、
批次身份、评论节奏、终态归属和续跑租约。
在选择、认领、恢复、评论、重开或关闭任何工单之前加载本文件。

前提：多个 agent 和人共享同一个工单系统。**"没人在做这个"是必须被证明的。**

## 只读可选资格

在选择的**紧邻之前**做一次新鲜读取，然后分类。

普通候选可选，当且仅当全部成立：

- 状态为 OPEN；
- 不是 draft；
- 没有 `in-progress` 类标签；
- 没有有效的预约或其它显式处理中信号；
- 没有有效的外来租约；
- 没有人类/外来接管信号；
- 没有分支、PR、协调评论或其它证据证明工作已经开始。

**已有 assignee 只是弱意图，不是自动排除条件。**
检查时间线和所有开始信号；一个已分配但无更强开始证据的 OPEN 工单仍然可选。
但认领前必须**重读工单并整体替换 assignee 集合**为当前 owner——
**绝不在过期 assignee 上追加**。

歧义时 fail closed。跳过的候选保持**零 mutation**：
不改 assignee、不改标签、不评论、不改状态、不改可执行性分类。

已关闭工单一律排除，只有一条窄复发路径例外：

1. 证明**精确的**根因指纹出现在真实（非探针/非合成）流量中；
2. 证明发生时间在最近一次修复/部署 watermark **之后**；
3. 证明不存在外来/人类 owner、有效外来租约或接管；
4. 在工单**仍为 CLOSED 时**建立并回读规范的 self-owned 认领；
5. 回读成功**之后**才重开。

相邻症状、同标签、同 provider、防御性兜底、合成回放都不构成复发。

## 认领与回读 (Claim & readback)

对每个选中的工单，**串行**执行：

1. 重读状态、draft、标签、assignee、时间线、预约、租约、接管、分支/PR；
2. 确认它仍属于未变的批次身份；
3. 移除所有既有 assignee，只添加当前账号；
4. 添加 `in-progress`；
5. 创建规范的认领评论（结构化 block，见下）；
6. 从工单系统读取**权威的** `createdAt`，回填进认领记录，再回读并严格校验；
7. 把评论 ID/URL、源 baseline commit、controller/run 溯源写进状态文件。

**第二次回读成功之前，禁止任何导向实现的调查、编辑、commit、部署或 E2E。**

认领 block 的最小结构（用 HTML 注释 marker 包裹一段严格 JSON）：

```text
<!-- <automation>-claim:v1 -->
{ schema, runId, controllerTaskId, subagentTaskIds[],
  claimedAt, issue{repository,number},
  sourceWorkspace{repository,worktree,branch,baselineCommit}, relatedWorkspaces[] }
```

严格校验：所有字符串非空；`claimedAt` 是工单系统返回的 UTC RFC 3339 时间
（**本地时钟不能替代**）；worktree 是绝对路径；baseline 是开工前
`git rev-parse HEAD` 的完整 OID；数组元素唯一；不接受未知 key、重复 key、
重复 marker 或第二个 claim block。首次写入允许 `claimedAt: null` 作为
"尚未生效"的初始化态，parser 必须把它当作 invalid。

**commit 归属的时间门**用 `git show -s --format=%cI` 的 committer UTC
与权威 claim `createdAt` 比较：早于 claim 的 commit 一定不属于本轮；
不早于 claim 只是必要条件。接受归属还需要闭合 run/controller ID、
交付 hash、worktree/branch、baseline ancestry、协调评论等完整溯源链。
author date、Git author、assignee 或共享账号都不能单独替代这条证据链。

## 批次身份

**最多 4 个**工单一批。

只有全部成立才合批：

- 一个精确的因果边界；
- 一个共享的根因指纹 / repairKey；
- 一个仓库和目标分支；
- 一条发布 lane 和部署边界；
- 一个实现就能修好每一项，不需要按项定制产品行为；
- 一条验证链就能覆盖每一个事故身份；
- 一个回滚/发布决定适用于整个实现。

**以下都不够**：都是 Bug、标签相同、模块相邻、症状相似、
修复恰好碰同一个文件、部署时机方便。

任一条件发散 → 只选确定性最高优先级的**一个**，其余原样留给下一轮。
实现开始后不得扩大 batch，除非新项独立通过可选资格
且 controller 在任何 mutation 之前重写并回读批次 checkpoint。

## 批次执行拓扑

严格一份：一个 controller、一个 active goal、同时一个 maker、
一个落地 owner、一条 commit/push/deploy/review 序列。

严格每项一份：独立认领/回读、精确事故身份、验收 gate 与证据、
阶段评论、关闭/释放决定。

共享的实现证据可以被所有条目引用，但**绝不替代**每一项自己的
精确事故验收和最终评论。

## 评论节奏

controller 是**唯一**的工单写入者，subagent 只回传证据。
在这五个节点发实质性评论：

1. **调查** —— 精确事故、因果边界、范围、最强证据；
2. **实现** —— 交付 SHA 和改变了什么行为；
3. **验证** —— 每项的事故身份和证据等级；
4. **独立 review** —— 结论和已解决的 blocking finding；
5. **最终** —— 产品层总结、技术层证明、学习晋升/拒绝、终态动作。

不发空 ping。不制造多条零散评论当噪音。

最终评论至少包含：问题与根因（含被证伪的重要假设）、实施方案与关键设计选择、
最终 commit hash / 分支 / 关键文件、验证证据（命令与结果、部署环境、
run URL/head SHA、E2E 场景与结果、独立 review 结论）、
用用户视角描述的最终呈现效果（UI 附截图/链接，后台链路附可安全公开的
响应或日志 marker 摘要）、范围与后续（未触碰环境、已知限制、
需外部决策的动作，超范围问题链接独立 follow-up）。

**不得包含** secret、token、cookie、完整隐私数据或只能本机访问的临时绝对路径。
**不得把取消、失败或未执行的验证写成通过。**

## 可执行性分类

把**技术可执行性**和**发布/关闭 gating** 分开判断。默认 **agent-runnable**。

只有在有界调查证明"不存在任何代码、配置、测试环境、诊断、自动化、
兜底或 feature-flag 动作"，且唯一阻塞是不可访问的外部系统、
被禁止索取的凭据或不可委派的人类决策时，才标 `not-agent-runnable`，
并评论具体证据和解除条件。

以下**不得**作为不可执行的理由：跨仓库范围、生产授权、
等待巡检/自然流量/干净观测窗、已有 assignee、已有 `in-progress`。

## 终态归属

**先关闭已验证的工单，再释放自动化归属**——顺序不能反，
否则会留下一个无主的 OPEN 窗口让别的 agent 重复认领：

1. 发最终证据评论；
2. 关闭工单；
3. 移除本轮的可恢复租约；
4. 移除本轮的 `in-progress`；
5. 移除自动化 assignee；
6. 回读终态不变量。

成功不变量：

```text
CLOSED + 无 assignee + 无 in-progress + 无 active/resume-ready 自动化租约
```

`needs-follow-up` 只用于真实未解决的技术动作，并保留显式归属 + 有界下一步。
`fixed-pending-release` 只用于用户明确把生产定为验收终点且尚未部署的情况。
目标环境部署 + 客观测试 + review 之后，**不要等一个自然的干净窗口**再关。

## 续跑租约 (Resume lease)

无人值守自动化要跨轮次续跑时，在同一协调评论里再放一个租约 block：

```text
<!-- <automation>-resume-lease:v1 -->
{ schema, runId, controllerTaskId, subagentTaskIds[],
  owner{login,controllerTaskId}, automation{automationId,invocationId},
  issue, sourceWorkspace, relatedWorkspaces[],
  heartbeatAt, expiresAt, notBefore,
  cumulativeBudget{iterations,repairCycles,elapsedSeconds,tokens,externalCostUsd},
  status, boundedNextAction{kind,summary,objectiveGate},
  release{releasedAt,reason,releasedBy} }
```

关键约束：

- claim block 必须存在、排在 lease 之前、身份完全一致，且不被 lease 更新覆盖；
- `heartbeatAt < expiresAt`；三个时间门用工单系统的 UTC；
- **budget 的 `used` 跨所有恢复轮次累计，永不清零**；limit 仅填写用户或权威自动化合同明确给出的硬上限，未设置为 null，内部估算不得写成 limit；有效非 null limit 达到或超过才算预算耗尽；
- status 只允许 `active` / `resume-ready` / `blocked` / `complete` / `released`；
  前两种必须有非空 bounded next action 且 release 三字段全为 null；
- `released` 必须有 UTC `releasedAt`、非空 `releasedBy`，reason 限于
  `expired` / `budget-exhausted` / `blocked` / `complete` / `human-takeover` /
  `legacy-incomplete` / `manual`；
- **终态不得伪装成可恢复工作。**

### 决策矩阵

| 观察到的状态 | 动作 |
| --- | --- |
| 唯一、严格有效、self-owned、status 为 active/resume-ready、`notBefore` 已到、未过期、预算可用、bounded action 存在、claim/溯源全匹配 | 恢复同一 run，执行且只执行那个 bounded next action，然后累计预算并回读心跳/过期更新 |
| 其它有效但 `notBefore` 在未来 | 只把下次检查时间写进外部 state / wakeup；不做任何 ownership mutation、实现、commit、部署或释放 |
| 已过期且能证明 self-owned | 先置为 released（写 UTC 时间、`expired`、actor）并回读；再只释放自动化自己添加且未被人改写的 assignee/标签 |
| marker 缺失或重复、JSON/schema/key/type/时间无效、任一身份 mismatch | **Fail closed**：不认领、不恢复、不"修复"记录、不改外来 assignee/标签/评论/分支；只在外部 state 记冲突 |
| 任一累计预算耗尽，或 status 为 blocked/complete | 按 `budget-exhausted`/`blocked`/`complete` 做同样的 self-owned 确定性释放；不开新的 run |
| 人工新增/替换 assignee、移除自动化标签、接管分支/PR 或留言接手 | 以 `human-takeover` 释放自动化自己的租约与归属；保留所有人类 assignee、标签、评论、分支和工作内容，不覆盖、不删除、不重领 |
| 旧评论只有散文式租约 | 仅当每个必填字段都有 durable 证据时原地规范化并回读；证据不全但能证明 self-owned 时以 `legacy-incomplete` 释放；归属也不确定时零 mutation 跳过 |
| 已 released | 只读确认 release 与外来状态未被改写；不再恢复 |

**不要**因为 owner 看起来是同一个账号，就把带 `in-progress` 的工单送进普通可选资格流程。
共享账号和过期散文都不能证明 self ownership。续跑只能走独立的恢复入口。

# Phase Library

按任务类型提供阶段模板和调查清单。
Autopilot 根据分类结果加载对应模板，用调查发现填充具体内容。

模板是参考骨架——根据实际范围增加阶段，但 mandatory 阶段不允许删除。

每个 phase 的 `<gate>` 是客观验证信号（机器可判定的 pass/fail），
不是主观判断。没有 gate 的 phase = 自己判自己的卷。

---

## bug-fix

<scope-checklist type="bug-fix">
  - 拉 GitHub issues：`gh issue list --state open --label Bug --json number,title,body,labels,assignees`
  - 逐条读 body，找同根因 issue 归组
  - 检查是否有人已在做（in-progress 标签 / 近期 commit / 分支 / PR）
  - 快速 trace 受影响代码路径
  - 把 issue body 里的独立现象拆成编号清单（区分症状链 vs 独立问题）
</scope-checklist>

<template type="bug-fix">
  <phase id="claim" order="1" mandatory="true">
    <skill>gh-cli</skill>
    <goal>认领 issue 组（assign + in-progress 标签）</goal>
    <gate>gh issue view 显示 assignee = @me 且 labels 含 in-progress</gate>
    <done-when>组内所有 issue 标记 in-progress 并 assign 给当前账号</done-when>
    <on-fail>若已有人在做则整组跳过，评论告知同根因</on-fail>
  </phase>

  <phase id="investigate" order="2" mandatory="true">
    <skill>项目 dev skill + systematic-debugging</skill>
    <goal>全盘调查，逐一定位每个独立问题的根因</goal>
    <gate>每个问题有"文件:行号 + 根因描述 + 证据引用"三要素</gate>
    <done-when>每个问题的根因定位到具体代码位置，有证据</done-when>
    <on-fail>分类失败原因 → missing-context: 项目 debug skill 查远程日志;
             hallucinated-assumption: 验证假设后重查</on-fail>
  </phase>

  <phase id="plan" order="3" mandatory="true">
    <skill>writing-plans</skill>
    <goal>基于根因制定修复方案，逐一对应每个子问题</goal>
    <gate>方案文件存在且覆盖所有子问题编号</gate>
    <done-when>方案覆盖所有子问题，自主选定最优解并记录理由</done-when>
    <on-fail>brainstorming 探索替代路径</on-fail>
  </phase>

  <phase id="implement" order="4" mandatory="true">
    <skill>项目 dev skill</skill>
    <goal>根因层面修复 + 注释 + i18n</goal>
    <gate>tsc 退出码 0 + 相关测试退出码 0</gate>
    <done-when>本地 tsc + 相关测试通过</done-when>
    <on-fail>分类失败原因 → wrong-approach: 回 plan 重新选方案;
             incomplete-output: 继续实现剩余部分</on-fail>
  </phase>

  <phase id="deploy-1" order="5" mandatory="true">
    <skill>项目 deploy skill</skill>
    <goal>第一轮提交并部署到 test</goal>
    <gate>gh run view 状态 = success（核心服务 job）</gate>
    <done-when>核心服务部署绿</done-when>
    <on-fail>分类失败原因 → environment-issue: 查部署日志定位;
             incomplete-output: 补遗漏的配置/迁移后重推</on-fail>
  </phase>

  <phase id="e2e-1" order="6" mandatory="true">
    <skill>项目 test skill + agent-browser</skill>
    <goal>第一轮 E2E 验证——每个 issue 现象真实消失（独立 checker subagent）</goal>
    <gate>agent-browser 截图/操作结果证明现象消失 + 无回归</gate>
    <done-when>所有子问题验证通过，无回归</done-when>
    <on-fail>分类失败原因后 loop 回对应上游 phase</on-fail>
    <skip-forbidden>本地测试只验证逻辑，E2E 验证部署后真实行为</skip-forbidden>
  </phase>

  <phase id="review" order="7" mandatory="true">
    <skill>simplify + 项目 review skill</skill>
    <goal>代码审查 + 注释合规 + 精细优化（独立 checker subagent）</goal>
    <gate>review skill 输出无 blocking issue + simplify 无新 finding</gate>
    <done-when>review 通过，注释完整准确</done-when>
    <on-fail>按 review 意见修改后重审</on-fail>
    <skip-forbidden>审查拦截注释缺失、兼容漏洞、影响面失控</skip-forbidden>
  </phase>

  <phase id="deploy-2" order="8" mandatory="true">
    <skill>项目 deploy skill</skill>
    <goal>review 修改后二次部署</goal>
    <gate>gh run view 状态 = success</gate>
    <done-when>部署绿</done-when>
    <on-fail>同 deploy-1</on-fail>
    <skip-forbidden>review 修改可能引入新问题，必须经过部署验证</skip-forbidden>
  </phase>

  <phase id="e2e-2" order="9" mandatory="true">
    <skill>项目 test skill + agent-browser</skill>
    <goal>二次 E2E 验证（独立 checker subagent）</goal>
    <gate>agent-browser 截图/操作结果确认功能正常</gate>
    <done-when>验证通过</done-when>
    <on-fail>分类失败原因后 loop 回对应上游 phase</on-fail>
    <skip-forbidden>确保 review 修改没有破坏任何东西</skip-forbidden>
  </phase>

  <phase id="close" order="10" mandatory="true">
    <skill>gh-cli</skill>
    <goal>关闭 issue 并附 commit hash</goal>
    <gate>gh issue view 状态 = closed</gate>
    <done-when>组内所有 issue 关闭</done-when>
    <on-fail>N/A</on-fail>
  </phase>
</template>

---

## feature

<scope-checklist type="feature">
  - 读关联的 spec、issue、PR 描述，提取需求清单
  - 用 context7 检查是否有现成库/模式可复用
  - 定位受影响的模块/文件/store
  - 检查现有代码模式（避免重复造轮子）
  - 评估前后端影响面
  - **运行 feature-completeness-checklist**（见下方），逐项核查并记录到方案文件
</scope-checklist>

<feature-completeness-checklist type="feature">
  功能不是"代码能跑"就算完成。以下清单覆盖历史上反复出现的"半成品上线"模式。
  design phase 必须逐条过一遍；不适用的标 N/A 并写明理由；适用但本次不做的
  必须 flag-gate 关闭并写进 progress.md 的"未完成项"。

  ## A. 多表面一致性（Multi-Surface Consistency）
  同一数据/功能在不同页面/面板/模式下渲染必须一致。
  - [ ] 列出所有会展示此功能的 surface（如：右侧面板、弹窗预览、分享页、移动端、Bot 消息卡片）
  - [ ] 每个 surface 使用同一个渲染组件或同一套 CSS/样式 token
  - [ ] 如果某 surface 需要变体（如分享页用 articleSkin），变体必须在同一 PR 里实现并验证
  - [ ] 禁止"先做主面板，分享页/移动端下次再说"——要么全做，要么 flag-gate 不暴露

  ## B. 用户设置持久化（Settings Persistence）
  任何用户可调节的设置必须能保存和恢复。
  - [ ] 如果功能包含用户设置项（主题、布局、偏好、配置），设置必须持久化到后端或 store
  - [ ] 禁止 useState-only 的设置项——刷新丢失 = 未完成
  - [ ] 如果设置需要在其他 surface 生效（如分享页读用户设定的主题），后端 API 必须返回设置值
  - [ ] 新增持久化字段时，必须同步：后端 DTO/entity/migration + 前端 store action + API 客户端生成

  ## C. 公开页面基础设施（Public Page Infrastructure）
  任何通过 URL 可公开访问的页面必须具备基础的 Web 标准能力。
  - [ ] 公开页面必须有合理的 `<title>` 和 `<meta name="description">`
  - [ ] 如果页面可被社交平台分享，必须有 og:title / og:description / og:image meta tags
  - [ ] 如果页面内容对 SEO 有价值，确认服务端不发 noindex 或有 SSR/预渲染方案
  - [ ] 公开页面的加载状态必须合理（不是 skeleton 模拟未来布局、不是空白屏幕）
  - [ ] 如果 SEO/OG 基础设施当前不存在且不在本次 scope 内，在文档和 progress.md 明确标记为已知缺口

  ## D. 数据完整性（Data Completeness）
  新功能引入的数据必须端到端流通。
  - [ ] 前端写入的字段，后端必须持久化并在读取时返回
  - [ ] 后端返回的字段，前端必须消费（或有意忽略并注释原因）
  - [ ] 如果功能依赖现有数据（如 artifact metadata），确认该数据在目标上下文中可用
  - [ ] 批量/列表接口必须返回足够的摘要字段，不留 N+1 给前端

  ## E. 跨功能影响（Cross-Feature Impact）
  - [ ] 新 surface 是否影响现有功能的导航、布局、权限？
  - [ ] 新设置是否影响导出、分享、打印等下游消费？
  - [ ] 新公开页面是否需要认证/权限检查？匿名访问 vs 登录态？

  每条未通过项必须在 design phase 的方案文件里写明处置决策：
  - 本次做 → 纳入实现阶段
  - 本次不做但安全 → flag-gate 并记入 progress.md 未完成项
  - 不适用 → 标 N/A 并简述理由
</feature-completeness-checklist>

<template type="feature">
  <phase id="research" order="1" mandatory="true">
    <skill>项目 dev skill + context7</skill>
    <goal>理解需求 + 检查可复用的库和现有模式</goal>
    <gate>需求清单列出 + 技术路径确认（有库可复用 / 需自建）</gate>
    <done-when>需求明确，技术可行性确认</done-when>
    <on-fail>deep-research 扩大搜索</on-fail>
  </phase>

  <phase id="design" order="2" mandatory="true">
    <skill>writing-plans</skill>
    <goal>设计实现方案（API / Store / 组件 / 迁移）+ 通过 feature-completeness-checklist</goal>
    <gate>方案文件存在且覆盖所有需求点 + feature-completeness-checklist 每条标记通过/N/A/flag-gated</gate>
    <done-when>方案覆盖所有需求点，符合架构规则，checklist 无遗漏</done-when>
    <on-fail>brainstorming 探索替代方案</on-fail>
  </phase>

  <phase id="implement" order="3" mandatory="true">
    <skill>项目 dev skill + frontend-design</skill>
    <goal>实现功能（后端 + 前端 + i18n + 注释）——覆盖 checklist 中标记"本次做"的所有项</goal>
    <gate>tsc 退出码 0 + build 退出码 0 + 测试退出码 0</gate>
    <done-when>本地 tsc + build + 测试通过</done-when>
    <on-fail>分类失败原因后选对应修复路径</on-fail>
  </phase>

  <phase id="deploy-1" order="4" mandatory="true">
    <skill>项目 deploy skill</skill>
    <goal>部署到 test</goal>
    <gate>gh run view 状态 = success</gate>
    <done-when>部署绿</done-when>
    <on-fail>查日志修复</on-fail>
  </phase>

  <phase id="e2e-1" order="5" mandatory="true">
    <skill>项目 test skill + agent-browser</skill>
    <goal>端到端验证功能正常（独立 checker subagent）</goal>
    <gate>agent-browser 操作/截图确认功能可用 + 无回归</gate>
    <done-when>功能正常工作，无回归</done-when>
    <on-fail>分类失败原因后 loop 回对应上游 phase</on-fail>
    <skip-forbidden>本地 build 通过不等于部署后功能正常</skip-forbidden>
  </phase>

  <phase id="review" order="6" mandatory="true">
    <skill>simplify + 项目 review skill</skill>
    <goal>代码审查 + 注释 + 精细优化（独立 checker subagent）</goal>
    <gate>review skill 输出无 blocking issue</gate>
    <done-when>review 通过</done-when>
    <on-fail>修改后重审</on-fail>
    <skip-forbidden>审查拦截架构违规、注释缺失、兼容漏洞</skip-forbidden>
  </phase>

  <phase id="deploy-2" order="7" mandatory="true">
    <skill>项目 deploy skill</skill>
    <goal>review 修改后二次部署</goal>
    <gate>gh run view 状态 = success</gate>
    <done-when>部署绿</done-when>
    <on-fail>查日志修复</on-fail>
  </phase>

  <phase id="e2e-2" order="8" mandatory="true">
    <skill>项目 test skill + agent-browser</skill>
    <goal>二次 E2E 验证（独立 checker subagent）</goal>
    <gate>agent-browser 确认功能正常</gate>
    <done-when>验证通过</done-when>
    <on-fail>分类失败原因后 loop 回对应上游 phase</on-fail>
  </phase>
</template>

---

## refactor

<scope-checklist type="refactor">
  - 扫描目标区域代码气味、重复、复杂度
  - 检查现有测试覆盖（重构前必须有测试兜底）
  - 评估影响面（谁依赖这些代码）
  - 确认重构后的行为应该完全不变
</scope-checklist>

<template type="refactor">
  <phase id="analyze" order="1" mandatory="true">
    <skill>项目 dev skill</skill>
    <goal>分析目标区域，识别重构点和依赖关系</goal>
    <gate>重构范围清单 + 受影响模块列表</gate>
    <done-when>重构范围明确，影响面已评估</done-when>
    <on-fail>缩小范围</on-fail>
  </phase>

  <phase id="test-lock" order="2" mandatory="true">
    <skill>项目 test skill</skill>
    <goal>确认现有测试覆盖，补必要回归测试锁定行为</goal>
    <gate>目标代码路径有测试覆盖 + 测试全绿</gate>
    <done-when>重构范围有足够测试覆盖</done-when>
    <on-fail>先补测试再重构</on-fail>
    <skip-forbidden>没有测试兜底的重构 = 盲改</skip-forbidden>
  </phase>

  <phase id="implement" order="3" mandatory="true">
    <skill>项目 dev skill</skill>
    <goal>执行重构（结构改善，行为不变）</goal>
    <gate>tsc 退出码 0 + 全部既有测试退出码 0</gate>
    <done-when>tsc + 全部既有测试通过</done-when>
    <on-fail>回退到安全状态，缩小重构范围</on-fail>
  </phase>

  <phase id="verify" order="4" mandatory="true">
    <skill>项目 test skill</skill>
    <goal>确认行为没有变化</goal>
    <gate>所有测试绿 + build 退出码 0</gate>
    <done-when>所有测试绿 + build 通过</done-when>
    <on-fail>loop 回 implement</on-fail>
  </phase>

  <phase id="review" order="5" mandatory="true">
    <skill>simplify + 项目 review skill</skill>
    <goal>审查重构质量（独立 checker subagent）</goal>
    <gate>review skill 输出无 blocking issue</gate>
    <done-when>review 通过</done-when>
    <on-fail>修改后重审</on-fail>
  </phase>
</template>

---

## test

<scope-checklist type="test">
  - 定位未覆盖的路径/模块
  - 读项目 test skill 获取测试账号和环境配置
  - 检查现有测试模式和框架（jest / pytest / playwright）
  - 评估需要覆盖的场景数量
</scope-checklist>

<template type="test">
  <phase id="scope" order="1" mandatory="true">
    <skill>项目 dev skill + 项目 test skill</skill>
    <goal>识别未覆盖路径，规划测试场景</goal>
    <gate>测试场景清单存在 + 按优先级排序</gate>
    <done-when>测试清单列出，优先级排序</done-when>
    <on-fail>缩小范围到最关键路径</on-fail>
  </phase>

  <phase id="implement" order="2" mandatory="true">
    <skill>项目 test skill</skill>
    <goal>编写测试用例</goal>
    <gate>所有计划的测试文件已创建</gate>
    <done-when>所有计划的测试用例写完</done-when>
    <on-fail>修复测试代码错误</on-fail>
  </phase>

  <phase id="run" order="3" mandatory="true">
    <skill>项目 test skill</skill>
    <goal>运行测试并确认全绿</goal>
    <gate>测试命令退出码 0 + 0 failures</gate>
    <done-when>所有测试通过</done-when>
    <on-fail>loop 回 implement 修测试或修被测代码</on-fail>
  </phase>

  <phase id="review" order="4" mandatory="true">
    <skill>项目 review skill</skill>
    <goal>审查测试质量（覆盖是否充分、断言是否有意义）（独立 checker subagent）</goal>
    <gate>review skill 输出无 blocking issue</gate>
    <done-when>review 通过</done-when>
    <on-fail>补充/修改测试</on-fail>
  </phase>
</template>

---

## research

<scope-checklist type="research">
  - 收集症状、日志、用户报告
  - 定位相关代码路径
  - 判断是否需要远程日志/环境信息
  - 确定产出形式（口头结论 / findings 文件 / issue 评论）
</scope-checklist>

<template type="research">
  <phase id="gather" order="1" mandatory="true">
    <skill>项目 dev skill + 项目 debug skill</skill>
    <goal>收集所有相关证据（代码、日志、配置、现象）</goal>
    <gate>至少 2 个独立证据源收集到相关数据</gate>
    <done-when>关键证据收集完毕</done-when>
    <on-fail>deep-research 扩大信息源</on-fail>
  </phase>

  <phase id="analyze" order="2" mandatory="true">
    <skill>systematic-debugging</skill>
    <goal>分析证据，形成假设，验证或排除</goal>
    <gate>假设有证据链支撑 + 至少排除 1 个替代假设</gate>
    <done-when>根因/结论有证据支撑</done-when>
    <on-fail>扩大调查范围</on-fail>
  </phase>

  <phase id="report" order="3" mandatory="true">
    <skill>writing-plans</skill>
    <goal>输出结论和建议（含后续行动建议）</goal>
    <gate>结论文件存在 + 包含可执行的下一步</gate>
    <done-when>结论清晰、可执行</done-when>
    <on-fail>N/A</on-fail>
  </phase>
</template>

---

## deploy

<scope-checklist type="deploy">
  - 确认当前分支状态和待部署 diff
  - 检查 CI/CD pipeline 状态
  - 按用户明确范围确定目标；仅说“发版”“发布”“上线”时，默认当前项目所有适用发布面及其约定环境，不询问范围，不扩到无关项目
  - 检查是否有待运行的迁移
</scope-checklist>

<template type="deploy">
  <phase id="prepare" order="1" mandatory="true">
    <skill>项目 deploy skill</skill>
    <goal>同步分支、确认 diff 正确、检查迁移</goal>
    <gate>git status 干净 + diff 只含预期文件</gate>
    <done-when>分支干净、diff 符合预期</done-when>
    <on-fail>解决冲突/补遗漏</on-fail>
  </phase>

  <phase id="push" order="2" mandatory="true">
    <skill>项目 deploy skill</skill>
    <goal>推送并监控部署</goal>
    <gate>gh run view 状态 = success（目标服务 job）</gate>
    <done-when>目标服务部署绿</done-when>
    <on-fail>查失败日志，修复后重推</on-fail>
  </phase>

  <phase id="verify" order="3" mandatory="true">
    <skill>项目 test skill + agent-browser</skill>
    <goal>部署后验证功能正常（独立 checker subagent）</goal>
    <gate>agent-browser 操作/截图确认关键功能可用</gate>
    <done-when>关键功能正常，无回归</done-when>
    <on-fail>回退或修复后重部署</on-fail>
  </phase>
</template>

---

## quality

<scope-checklist type="quality">
  - 确定审查范围（全仓库 / 指定模块 / 最近变更）
  - 跑 lint / type-check 看现有状态
  - 识别高优先级区域（最近改动多 / 复杂度高 / 缺注释）
</scope-checklist>

<template type="quality">
  <phase id="scan" order="1" mandatory="true">
    <skill>项目 dev skill</skill>
    <goal>扫描目标范围，识别问题分类和优先级</goal>
    <gate>问题清单存在 + 按优先级排序 + lint/tsc 基线记录</gate>
    <done-when>问题清单按优先级排好</done-when>
    <on-fail>缩小范围</on-fail>
  </phase>

  <phase id="fix" order="2" mandatory="true">
    <skill>项目 dev skill + simplify</skill>
    <goal>逐一修复/优化（行为保持不变）</goal>
    <gate>tsc 退出码 0 + build 退出码 0 + 测试退出码 0</gate>
    <done-when>tsc + build + 测试通过</done-when>
    <on-fail>回退有风险的改动</on-fail>
  </phase>

  <phase id="review" order="3" mandatory="true">
    <skill>项目 review skill</skill>
    <goal>最终审查确认质量提升且无回归（独立 checker subagent）</goal>
    <gate>review skill 输出无 blocking issue</gate>
    <done-when>review 通过</done-when>
    <on-fail>修改后重审</on-fail>
  </phase>
</template>