# Orchestrator 调度手册（通用）

> **主控执行脚本**。每轮唤醒照本文件从状态续跑，**不依赖聊天历史**。
> **唯一真源** = 本框架的流程总纲（工作区 `docs/process/README.md`）；与本文件冲突时**以总纲为准**，并同步修正本文件。
> **项目适配** = 同目录 `PROJECT.md`。一切项目专属信息（端与目录 / 命令 / 属主路径 / 环境凭据）**只从那里读**，本文件不得硬编码。
> **本框架工具**：状态快照 `process_status` · Gate 摘要骨架 `gate_summary` · journal 记账 `process_journal` · 初始化 `process_init` · 卸载 `process_uninstall`（人确认后清流程载体；已有自定义内容的 `AGENTS.md` / 用户技能不删）。

---

## 1. 唤醒后固定动作（每轮先做）

```text
1. process_status → 取全部包的 (ID, status, gate0, gate1, gate2, gate4, prdVersion) + open bugs
   ——它扫描 input/ 核对件、prd/ PRD、bugs/ 缺陷单的 frontmatter；禁止靠聊天历史或手工 grep 推断状态
2. 读 PROJECT.md → 取端与目录、四个命令槽、产物属主表、环境与凭据
3. git status --porcelain 必须干净；不干净 → 停下报告（避免把 dev 在途改动误判成"已交付"）
4. 看并行会话协调板（总纲 §2.7）：先比对**本包落点**与板上在跑条目的落点，有交集 ⇒ 停下报人；
   无交集再登记自己的条目（ID / session / 时间 / 落点 / 占用资源）；动共享资源（构建通道 / 真机 / 数据库 / 提交窗口）前先登记再使用
   ——协调板路径以 PROJECT.md §1 为准；文件不存在即无并行会话，不必空找
5. 照 §2 状态 → 动作表决定下一个动作
6. 每个动作完成后立即用 process_journal 追加一条（时机见 §7），再进下一步
```

**硬约束**：主控不得绕过 `process_status` 手工推断状态；只要还有活跃包，每轮唤醒都要重取一次快照。

---

## 2. 状态 → 动作表

> 状态位只住在「当前阶段主产物」的 frontmatter，**同一时点只有一个权威源**：环节 0 = `input/<ID>-需求核对件.md`，环节 1 起 = `prd/<ID>.md`。
> `status: frozen` ⟺ `gate1: approved`；两处状态位必须耦合一起改（`terminated` 豁免耦合，见下行）。

| 条件 | 动作 | 停点 |
| --- | --- | --- |
| 有 `input/` 原料但无需求核对件，**表达不足以支撑可断言判据**（判断不了就按不足处理），且人未明确 fast / 不做调研 | 写 `input/<ID>-research-brief.md` → **并行**派 pm（`input/<ID>-prior-art.md`）与 architect（`input/<ID>-tech-scan.md`）→ **汇合**（architect 逐条标注 `C-NN`；pm 反推约束型需求）→ 主控把汇合结论折成核对件 `Q` / `N` → 起草 `input/<ID>-需求核对件.md` | 停下等 **Gate0** |
| 有 `input/` 原料但无需求核对件，**表达清楚**或人明确 fast / 不做调研 | **主控起草** `input/<ID>-需求核对件.md`（人的裁定逐条复述 `R-NN` / 端覆盖与落点 / 需求理解 / 待确认项 `Q-N` / 明确不做 / 风险）；**不派调研** | 停下等 **Gate0** |
| `research-brief` 已存在，但 `prior-art` / `tech-scan` 缺一、或未汇合 | 补齐缺件 / 完成汇合；**没汇合不得当调研完成，不得进 Gate0** | 无（补齐后按第 1 行继续） |
| 核对件 `gate0=pending` | 按人裁定修订核对件，**主控不改 gate 值** | 停下等 **Gate0** |
| 核对件 `gate0=approved` 且 `flow=fast`（人已在 Gate0 定档，不建 PRD） | 不派 pm、不产生 Gate1/Gate2、**不做调研**；直接派 dev（按 §3.1 最小派单包：目标 / 范围 / 命令 / 已知红）+ 存量回归，结论记 journal。触及 schema / RBAC / 金额 / 对外接口 ⇒ 退回全流程（回核对件改 `flow: full`，重走 Gate0 之后的环节） | 无（仅 Gate0；触安全红线另计） |
| `gate0=approved` 且 `flow=managed` 且 `gate1=pending` | **托管**：调 **pm** 产出 PRD + 契约 + 设计与说明（有架构影响加 architect；`uiDesign: required` 加 ui-designer 原型 / UI 规格；按需领域专家）；**完成后置 `gate1: approved`（delegated）**，直接调 test，**不停 Gate1** | 无（检查点，非停点） |
| `gate0=approved` 且 `status=draft` 且 `gate1=pending` | 调 **pm** 产出 PRD + 契约 + 设计与说明（设计与说明必须逐条对齐 `R-NN`）；**有架构影响时**（schema / RBAC / 金额·分摊 / 新增对外接口 / 多端 / 新模块）再调 **architect** 出 `prd/<ID>-arch.md`（决策 + 取舍 + 数据/接口影响 + 风险），随 Gate1 加审；**若核对件 `uiDesign: required`**，再调 **ui-designer** 产出 **HTML 原型**（`prototypes/<ID>/index.html` + `styles.css` + `handoff.md`，交付主件；不产出 PNG/PSD）与 UI 规格 `prd/<ID>-ui-spec.md`（只翻译不发明；每条须可观察；视觉数值须给字面值；交接表须覆盖全部 UI-NN）；**上游产物落盘后**，主控**按需**调 **domain-expert**（预设专家卡或临时卡，见 §3.5）做专业指导，结论折进 Gate1（需持证确认项原样进 `❓`） | 停下等 **Gate1** |
| `gate1=approved` 且 `flow=managed` 且 `gate2=pending` | **托管**：调 **test** 生成 P0 测试并出红灯归因；**完成后置 `gate2: approved`（delegated）**，直接调 dev，**不停 Gate2** | 无（检查点，非停点） |
| `gate1=approved` 且 `status=frozen` 且 `gate2=pending` | 调 **test** 生成 P0 测试并出红灯归因（盘点 N 绿 / M 红） | 停下等 **Gate2** |
| `gate2=approved` 且 `status=red` | 调 **dev** 实现到绿 → 改 `status=implementing` | — |
| `status=implementing` | 由 **test** 独立复跑 **L2 包验证**（裁判运动员分离，总纲 §6.9）；**有 UI 的包**：L2 绿后调 **ui-designer** 做 **UI 还原核对**（`reports/ui-review/<ID>.md`），`fail`/`conditional` 回 dev，`pass` 后才置 `status=uat`；评审三件套不在本步 | — |
| `status=uat` | 调 **uat** 黑盒预验收，写 `reports/uat/<ID>.md`；uat pass 后调 **pm** 做验收完备性审核，写 `reports/pm-review/<ID>.md`。**pm 审核完成 ⇒ 输出 Gate4 摘要停等** | 停下等 **Gate4** |
| `gate4=approved` 且 `status=uat` | 落 `gate4: approved` → `status=done`（两字段一起写）；**默认归档 = 提醒人提交**（session 不 commit，总纲 §9） | — |
| `bugs/*.md` 中 `status=open` | 调 **dev** 修 → 改 `fixed` → **test** 复跑 → `verified`，并跑三级回归 | — |
| **人显式发起**发布回归（不自动触发） | 调 **test** 跑发布前自动化全量（照 PROJECT.md 命令槽）+ **uat** 照功能清单（派生件）跑黑盒 + 跑评审三件套（对象 = 本次发布涉及的全部 `src` diff 与全部台账）；结果**合并**写 `reports/release/<date>.md` | 停下等**人签** |
| `status=terminated`（人裁不发布 / 终止） | **不再流转**：不生成 uat、不做 Gate4；产物原地保留；`gate1`/`gate2` 保留历史真实值，**不得涂改成 rejected** | — |

> 表里出现但状态位缺失（如两个包共用同名 ID、frontmatter 解析失败）⇒ 按「状态位异常」停下报告，不得自行择一推进。
>
> `flow=managed` 的 Gate1/2 **不是消失**：它们是不停的检查点。`gate1/gate2: approved` 必须在检查点完成后由主控写入，`gateHost` 记为 `delegated`；没有 Gate0 的 `delegate` 记录就不得跳过停等。

---

## 3. subagent 派发与复用账

### 3.1 派单纪律

**派单前先问三句**：① 一个角色能不能做完？能 ⇒ 不拆、不并行、不建团；② 需要专业视角吗？需要 ⇒ 加 `domain-expert`（可合并子专业）；③ 需要并行吗？需要 ⇒ 只并行互不依赖的切片，并写明汇合点。**不要为了「流程完整」硬凑角色。**

- **只传文件路径 + ID**，不传聊天记录。派单必附：`rev`（依据的产物版本）+ **只读白名单** + **收口判据** + 交付所需**执行台账格式**。
- **派单包十项**（模板与判据见总纲 §2.8）：包 / 切片 · 目标 TC/AC · 可写 `file:symbol` · 禁碰 · 参照实现 · 命令（环境就绪 / L1 / L2） · 已知红 · 上下文 · 完成判据 · 交付格式。
- **研究波派单**（Gate0 前，仅 full，**按需**）：只在表达不足 / 拿不准时派；**不默认对所有 full 包做**——表达已可断言、单点改动、人明确不用就不派。先写 `input/<ID>-research-brief.md`（原始需求 / 用户原话 / 已知边界 / 要回答的问题 / 输出 schema / 预算 / 种子候选 3~5 个 / **独立完成前不读对方文件** / 汇合要求）；检索优先 GitHub（README / docs / Issues / Releases）+ 公开文档。pm 写 `prior-art`，architect 写 `tech-scan`；**两边都完成后必须汇合**，否则不算交付。fast 路径不派研究波。
- **汇合派单**：两边各自交付后，主控各发一条**续跑消息**（附对方文件路径 + 「只追加到自己的文件，不互相改」）：architect 逐条标注 `C-NN`，pm 反推约束型需求。**两边都回报汇合完成**，主控才折核对件；只交付一份、或没标注 `C-NN` ⇒ 退回补齐。
- **Definition of Ready 缺一不派**：目标已冻结 / 范围能落到 `file:symbol` / 命令可执行 / 已知红有基线 / 参照实现有或明确「无」。缺项先补（pm / 主控），**不让 dev 猜**。
- **快速路径最小集**：目标（期望行为 + 可判定观察）/ 范围 / 命令 / 已知红；无 `TC` 时 DoR ① 以「期望行为可判定」替代。
- **文件范围契约**：写明本次**预期文件清单**；dev 的 `git diff --name-only` 超出清单的逐条解释，**静默超出 = 违规**；显式超出进 Gate `❓` 由人裁。主控只做机械比对，不判实现对错 —— ⑫ 判「文件归谁」，契约判「本次该不该动」。
- **重试上限**：同一失败测试 **3 次**修复尝试；第 3 次仍红 ⇒ 停，报告「试过什么 / 当前红 / 判断」，由主控改派或打回 pm/test。**不设时间 / 文件数 / diff 行数上限**——大改动正常，切片按「可独立验证的 AC 组」切。
- **不发事实型消息**：只发「请重读 `<文件>` 的 rev N」；口径 / 结论 / 背书类变更一律走**勘误追加**，不靠「发一条新消息宣布前面作废」。
- **不给单一角色未复核的旧结论当事实前提**：需要时标注「据某角色、未独立复核」，并要求执行角色先核前提。
- **领域专家派单（按需）**：只在「需要某专业视角」时派（§3.5）。三选一：**预设卡 / 临时卡 / 派单内联设定**；必附专业子视角、待审对象与版本、**视角（默认 owner 甲方自用 / vendor 乙方交付）**、要回答的问题、法域（不清楚写 `not-specified`）、材料清单、报告路径。**合并视角须列全子专业**；三者都没有不派；专家只出建议，不改稿。

### 3.2 复用账（效率取向，不是硬禁令）

- **判断口诀：看「包」不看「角色」** —— 同一个包**尽量复用**，不同包就该并行。
- **优先复用**：该包内的返工 / 复跑 / 补测 / 复核 / 收尾修正，优先用 `send_message` 接着原来那个 agent 干（它已有本包上下文，省一次重新读档）。
- **允许新建，且无需解释、无需停下报告**：① 前一个 agent 上下文已被无关内容占满；② 需要**独立视角**的复核 / 验收波（裁判运动员分离本就为此）；③ 同包内互不冲突的不同事项要并行推进。
- **禁止把「复用」当串行化的借口**；也禁止让同一个 role agent 同时处理两个包。
- **续跑增量包**：跨切片复用原 agent 时，只发「新增切片 + 自上次后变了什么（文件 / 红项 / 裁定）+ 新增红」，不重读全套。
- **非必要不换**：换新 agent 只限三种情形（独立验收波 / 上下文占满 / 互不冲突并行）；换新时在 journal 记「新建」原因。
- **计量但不判罪**：每波 Gate 摘要的 `📎 依据` 行如实报「**新建 N / 复用 M**」，供人观察成本。

### 3.3 并行约束（派单前必查）

- 冻结边界：一旦进入「验证波」，任何改 `src` 的角色必须退出该波，否则复跑 / 验收结论作废。
- **研究波可并行**：Gate0 前的 pm ∥ architect 只读、不写实现、不跑测试、不占构建通道；各自写自己的文件，**不共写、不互改**。并行必须带汇合：architect 标注 pm 的 `C-NN`，pm 反推约束型需求；**没有汇合 = 调研未完成**，不得进 Gate0。
- 资源锁：同一构建通道、同一设备、同一数据库写入、同一 ID 的 journal 均互斥（互斥范围见总纲；设备/环境占用方式写进 PROJECT.md §1）。研究件写不同文件；journal 追加由工具锁串行化。
- 写入域隔离：每角色只写 PROJECT.md §3 的属主路径；**越界即停**，不得自行发明路径。
- 被测环境的长时间运行服务归**主控托管**，派单里写明由谁持有 / PID / 启动时间 / 如何确认存活；角色不得自行再起一份。
- **派单前置（环境）**：主控托管并登记环境；派单附「环境就绪」证据（命令 + `exit 0` + 时间）与基线。**预热未就绪不派 dev**；dev 只负责因本次改动而变的环境（schema 同步 / 新依赖 / 迁移脚本）。
- **交付核对（范围）**：dev 交付时先比 `git diff --name-only` 与派单预期文件清单；超出逐条要解释，静默超出按违规停下。

### 3.4 角色硬边界速查（派单时把对应行写进任务）

| 角色 | 只做什么 | 硬边界 |
| --- | --- | --- |
| **主控** | 需求核对件 · 调度 · Gate 与交互摘要 · 状态推进 · journal · 进程与环境托管 | 不写实现、不写测试、不替人做 Gate 决策、不自行核实角色产出的技术正确性 |
| **pm** | PRD + 契约 + 设计与说明 + 验收清单 + 验收完备性审核；Gate0 前可做**需求借鉴调研**（`input/<ID>-prior-art.md`） | 禁读业务实现 / 测试 / e2e / 日志（契约层签名与 schema 除外）；源码核实归 architect |
| **architect** | Gate0 前**技术借鉴与约束扫描**（`input/<ID>-tech-scan.md`，与 pm 并行）+ Gate0 后**架构设计与取舍**（`prd/<ID>-arch.md`，按需） | 禁读业务逻辑实现（结构层可读：模块布局 / 依赖 / 构建 / schema / 路由签名 / 中间件接线）；不写 PRD / 契约 / AC / 测试 / 源码；不复制外部代码、不引入依赖 |
| **ui-designer** | **HTML 原型**（`prototypes/<ID>/index.html` + `styles.css` + `handoff.md`，交付主件；不产出 PNG/PSD）+ UI 规格（组件判定 / 状态矩阵 / 文案定稿 / 字面数值）+ **UI 还原核对报告**（`reports/ui-review/<ID>.md`，dev 后） | **仅核对件 `uiDesign: required` 的包**；只翻译不发明业务口径；禁改生产实现源码、禁读后端实现与前端组件内部实现；UI 还原核对只判「实现是否偏离设计」，不代替 UAT |
| **test** | 测试用例 + 独立复跑报告 + 发布前自动化回归 | 只验收 dev 产出物；禁读业务实现细节、禁改 `src` |
| **dev** | `src` 改动 + 交付证据 | 禁改 `test/` / `e2e/`；禁止无证据的"已测试通过"；按派单范围写；同一失败测试 3 次上限；内循环 L1 / 交付前 L2 |
| **uat** | 黑盒验收报告 + 发布前黑盒回归 | 不知代码、不知测过什么；只判"对不对得上预期" |
| **domain-expert** | 按专家卡或派单内联设定（含**视角**：默认甲方自用），对单包 **PRD / 设计与说明 / UI 规格 + HTML 原型**，或一个**发布批次/版本**做专业评审（可合并相邻子专业；`reports/experts/**` 或 `reports/domain-review/**`） | 只出建议、不写别人的稿；禁改 PRD / 设计 / 原型 / 测试 / 源码 / 归档；不跑 DB、不 commit；**不替代持证专业人士**、不做 Gate 决策；**主控按需派** |
| **评审三件套** | 逻辑 / 正确性 / 安全结论与反例 | 只出结论，不贴大段代码、不改 `src`；对象 = 发布批次 `src` diff |

**分诊口诀**：发现前置缺失 ⇒ **退回**对应角色；发现结论缺证据 ⇒ **退回**对应角色；主控**不代做**别人专责（代做的代价是责任人无从追溯）。

### 3.5 按需领域专家（预设 / 临时卡 / 内联设定）

**触发**：需求或设计里有专业领域判断（合规 / 教学 / 运营 / 结构 / 电气 / 医疗 / 财税 / 安全…），pm / ui-designer 没有该专业背景；**发布批次 / 版本回顾**（人发起）需要专业视角复核一批改动；人点名；或高风险面需要独立专业视角。**不默认每包都派**；fast 路径不派（没有 PRD / 原型）。

**派单三选一（都没有 ⇒ 不派）**：

1. **预设卡**：`docs/process/experts/<slug>.md`（11 张）。
2. **临时卡**：`docs/process/input/<ID>-expert-<slug>.md`（主控检索公开来源后生成，随包清理）。
3. **内联设定**：派单里直接写全——专业子视角 / 对象与版本 / **视角** / 法域 / 要回答的问题 / 材料清单 / 报告路径 / 只读边界。

**合并视角（允许，但要守边界）**：

- 相邻专业可合并成一次派单（例：电力 + 数据中心现场运维），尤其对象与材料相同（同一版本 / 同一园区 / 同一批 UAT 证据）。
- 必须列全**子专业**；报告每条发现标 `[子专业]`；持证结论按子专业分开标「需持证确认」。
- **不把一个专业的结论套到另一个专业**；跨度过大（法律 + 结构 + 电气 + 医疗）⇒ 拆单。
- 合并不能替代持证签章，也不能把「三个专业都看过」写成一句「合规」。

**视角（甲方 / 乙方）**：

- 默认 `owner`（甲方 / 业主 / 自建自用）：问「对我自己的运营、安全、成本、合规、审计、可维护性有什么风险」；**不要把「客户验收 / SLA / 合同 / 回款」当判据**。
- 只有对外交付才用 `vendor`（乙方）：问「客户验收 / SLA / 合同边界 / 交付责任」。
- 报告声明块必须写视角；同一事实在两个视角下结论可能相反，不得混用两套语言。

**版本级回顾**：对象 = 一批包 + 发布说明 + UAT 证据 + 归档；报告默认 `reports/domain-review/<date>-<version>.md`（以 `PROJECT.md` §3 / 派单为准）；**不设新 Gate**，结论进发布结论 / 人裁。

**内联派单模板**：

```text
你是 domain-expert 角色。请先加载并按其执行 `domain-expert` 技能。
任务：对 <版本 / 批次> 做领域视角回顾（<子专业 A> + <子专业 B>；视角：<owner 甲方自用 / vendor 乙方交付>），只出问题与建议，不改稿、不做 Gate 决策。
仓库根 = <path>

## 评审范围
<只审哪些包 / 哪些改动；人已定的范围>

## 材料（只读）
<RELEASE / CHANGELOG / 发布说明 / UAT 证据 / 归档；归档解 /tmp>

## 你要评的
<按子专业列问题；要现场后果，不要代码细节>

## 产出
<报告路径>（中文；§1 结论 / §2 P0-P1-P2 / §3 好设计 / §4 不覆盖 / §5 最小改动）

## 硬边界
只写这一个文件；禁改源码 / PRD / 契约 / 归档；不跑 DB；不 commit；不冒充持证专业人士。
```

**纪律**：

- 专家卡只写「这个专业看什么」，**不写项目结论**；卡 / 内联设定与现行法域 / 标准冲突 ⇒ 停下报告，不自行改。
- 可多专家并行（只读、不占构建通道）；同一专家同一对象不重复派。
- **专家不是持证专业人士**：法律 / 结构 / 电气 / 医疗结论只能写「需确认什么」，由人 / 持证方定。
- 临时卡随包清理（`input/**`）；反复用到同一专业 ⇒ 由人决定是否升级为 `experts/**` 预设卡。
- **报告路径必须在 `PROJECT.md` §3 专家行内**；越界 ⇒ 停下报告。

---

## 4. Gate 摘要生成步骤（两段式）

**适用范围 = 主控对人的一切输出**（Gate 停等、进度汇报、中途提问、待裁定件、收口说明）——同一个形状，不按交互类型换格式。生成步骤：

1. **收齐本波产物路径**，确认每个 subagent 的写入都已在 journal 留痕。
2. **调 `gate_summary(<ID>)`** 取骨架：它自动填抬头（`【ID】<ID>　<status> → <下一步>　（Gate<N>）`）、gate 值、journal 尾部、产物路径与 open bugs；`✅` / `❓` 内容段由主控填。
3. **填 `✅ 完成了什么`**：1~3 条人话，每条 ≤ 40 字，只讲结论；代号只作括注。
4. **填 `❓ 还需要裁定什么`**：每条必须能被人**直接回一句**（同意 / 不同意 / 选 A / 给个数）；回不了一句的纯陈述进 `✅`；**没有待裁项就写「无，可放行」，不得省略这一节**。
5. **加一行 `📎 依据`**（需要时）：改动文件数与目录（不列全表）｜断言 `+a/-b`｜本波 subagent 新建 N / 复用 M｜报告路径。**禁止**贴大段代码或日志。
6. **实物优先**：凡需要人判断的环节，摘要里必须给出**可看 / 可跑的东西**（HTML 原型路径 + 状态切换方式、启动命令、diff 摘要）；PRD / 设计与说明 / 报告只作 `📎` 引用 —— **人判的是实物，不是叙述**（总纲 §4）。
7. **按 Gate 折叠专项**：
   - Gate0：人的裁定条数、`Q` 总数与是否收敛（未收敛 ⇒ `❓` 各列一条，标注「建议非结论」）；**做过借鉴调研的**另报候选 n / 采纳为 Q m / 不采纳 k（各一句理由），调研文件进 `📎`。
   - Gate1：**`✅` 给实物**（**打开 `prototypes/<ID>/index.html`**、状态切换方式、可跑命令，人先看这个）；**机器侧进 `📎`**：设计与说明 ↔ `R-NN` 对齐结论、UI 规格 ↔ 设计与说明 对齐结论、**视觉数值是否给足字面值**、**HTML 原型门禁原始输出**（`data-ui` / `handoff.md` / 外链 / 本地链接）；**未落实项 / 偏差 / 不可断言 / 无理由新增组件 ⇒ `❓` 列条**。**只有 PNG/PSD、没有 HTML ⇒ 按未交付处理**。
   - **托管包**（`flow=managed`）：进度线显示「托管（Gate1/2 已在 Gate0 授权）」；Gate1/2 不得写成 `human` 签，验收 Gate4 仍必停。
   - 派过**领域专家**的：报「专家意见 n 条 / 采纳 m / 未采纳 k / 未处理 j」；**需持证专业人士确认的项原样进 `❓`**；未派写「未派（按需）」。
   - Gate2：**只给人归因三行**（`401` 基建假红 / `200` 真缺口 / `404` 契约漂移各几条、是否含阻断项）；**另加一行验证层级 / 范围**（L2 / L3、全量是否跑，见总纲 §6.9）；断言全文不贴，归 dev 与 test。
   - 触及数据层（schema 变更）：`📎` 加「列变更 / 补偿 SQL / 回滚」，`❓` 写「是否同意该 schema 变更」。
   - 共享账号 / 数据库被改动：**摘要第一行 ⚠ 置顶**（改了什么 / 原值 / 恢复方案）——这是唯一允许出现在两段之外的行。
   - 收口说明（包 `done` / 终止）：**固定三样** —— `改了什么`（diff 摘要）· `怎么跑`（≤3 行）· `试什么`（3~5 条）。
   - **所有 Gate 共用**：把 `gate_summary` 生成的「**🔒 本轮门禁证据**」段照抄进摘要（本 Gate 跑过的门禁命令 + **真实退出码**，取自 journal 的 `action:"run"` 记录）；**查不到记录就写「未记录」** —— 「跑过了」这句话本身不是证据。若该段标出批准是 `🤖AI托管` 或 `⚠无留痕`，必须在 `❓` 里如实交代，不得含糊过去。
8. **停下等 approve**，不得自行 approve；人签后**先改 frontmatter 状态位，再记 journal**（`action:"approve"` + `gate` + `via:"human"`，见总纲 §7 第 9 条），然后照 §2 推进。**AI 托管的批准只许出现在验收 / 回归装置里**（端到端跑通场景），且必须记 `via:"ai-hosted"` —— 它会在状态里显示成 `🤖AI托管`，**不得冒充人签**。

---

## 5. 缺口清单收口

**机制**：验证阶段（test 复跑 / uat 黑盒 / 评审）发现的缺口**不立即触发修复**，先由主控登记入缺口清单 `reports/gaps/<ID>.md`；达到窗口关闭条件后，一次性派 dev 修全部，随后一次重构建 + 一次验证。理由：修复常是分钟级、验证是小时级，逐个发现会重复付出整条链的代价。

**窗口关闭条件（满足其一即收口）**：① 当前验证轮次自然结束；② 清单累积到 ≥3 条；③ 到 Gate 前要求收口。

**必须立即修、不进窗口的例外**：① 阻断性缺口（后续验证无法进行）；② 安全红线（越权 / 数据泄露 / 注入 / 密钥外泄）；③ 会使已得验证结论失效的缺口；④ 明确要求立即修的。

**清单格式（一行一条，必须有人话名）**：

| 编号 | 来源轮次 | 人话说明 | 分诊 | 目标角色 | 是否阻断 | 状态 |
| --- | --- | --- | --- | --- | --- | --- |
| `G-1` | `r1` | <谁·什么场景·发生了什么不对> | <真缺口 / 契约漂移 / 装置问题> | <角色> | 是 / 否 | 待修 |

**纪律**：分诊归主控，但清单**不改变「红不得掩盖」**——缺口仍须显式登记，不得静默关闭或静默延期；批量修完后的验证必须**逐条覆盖清单全部条目**，禁止「修了 5 条只验 2 条」；窗口期内的 Gate 摘要必须附清单概况（共几条 / 是否含阻断项 / 预计几批修完）。

---

## 6. 包收口与归档

1. **收口判据**（缺一不可）：Gate4 已签（`gate4: approved`）→ `status=done` → journal 有对应收口条目。
2. **状态位与产物一致**：PRD / 设计与说明 / 契约（有 `prd/<ID>-arch.md` 时加 arch）的状态与变更记录同步；`terminated` 包按总纲保留历史值并新增「终止结论与不可重做理由」。
3. **提醒人提交，不自动 commit**：提交范围**以包为单位**；工作区多包在途时逐文件核对身份，不属本包的留在工作区，并在回报里显式列出「有意排除」清单。包 `done` 后提醒人提交（message 带 ID）。
4. **归档**：**默认归档 = 人提交**（提交过即可回溯）；仅当工作区要整体清空且尚未提交时，才把需求专属产物与过程产物打成归档包（`tar.gz` + `MANIFEST` + `sha256`）落 `reports/_archives/**`。
5. **清场**：批次结束按总纲「保留 / 不留存」表清理，**只留流程骨架**（总纲、本手册、`PROJECT.md`、四份模板；有归档包时含归档区）。
6. **追溯归属**：结论进保留文档或 commit message；过程产物即弃——不得以「写在报告里了」代替规范落地。

---

## 7. journal 记账时机

**每次 subagent 写入产物后立即追加**（用 `process_journal`，它负责锁 + 指纹校验 + 原子替换；**禁止**手工读-改-写 journal）。**缺 journal 条目视为未交付。**

**必记时机**：① 每个 Gate 的产出落盘后；② 每次派单后（含 `rev` 与只读白名单）；③ dev 每次交付后（把 `git diff` 存 `reports/dev-patches/<ID>-<n>.patch` 并登记）；④ 每次复跑 / 验证的**命令与结果**；⑤ 每次裁定（含人裁结论与依据文档）；⑥ 包收口。

**字段**：`id`（包 ID）/ `at`（**机器时间**，禁用模型自述时间）/ `step`（pm/architect/domain-expert/test/dev/uat/review/archives…）/ `actor`（能定位到具体角色）/ `action`（write/run/approve…）/ `phase`（阶段，用于复算阶段耗时与返工次数）/ `note`（一句话事实；`action:"run"` 必须写明层级与范围 L1/L2/L3；研究汇合写「pm+architect 调研汇合完成」）/ `files`（涉及文件）。

**托管授权**：`action:"approve"` + `gate:"gate0"` + `via:"human"` 时另带 `delegate: ["gate1","gate2"]`（数组，至少一项）；Gate1/2 不另写人签，`gateHost` 由这条记录解释为 `delegated`。

**纪律**：append-only，单行追加，每行自带 `actor`；并发只允许追加、不得读-改-写；主控只记四类（裁定 / 派单 / 收口 / 研究汇合），其余由各角色各自的写入同步登记。

---

## 8. 硬规则（违反即停下报告）

1. 发现 **dev 改了 `test/` 或 `e2e/`** → 立即停止。
2. 发现 **test 产物的 import 落在白名单外** → 立即停止。
3. **Gate 前必须暂停**，不得自行 approve；人签之前不得带出下一环节产物。
4. **不自动 commit**；验收通过前一律停在未提交态，人审且验收过后才可 commit。
5. **缺 journal 条目 = 未交付**；每次产物落盘必须同步追加。
6. **subagent 禁用一切改变工作区的 git 命令**（stash / checkout / restore / reset / clean / commit），只允许只读（status / diff / log）；发现即停止。
7. **主控不代写 subagent 产物**（实现 / 测试用例归专职角色）。主控只做：调度 / 复核 / 恢复被破坏改动 / 代跑被拦命令；代跑必须标注「主控代跑」，其结果只作附录。
8. **主控不得自行核实角色产出的技术正确性**：怀疑结论时，把核对作为任务派给流程内对应角色，主控只登记「待核」并排进派单。
9. **项目专属信息只从 `PROJECT.md` 读**；执行中发现确需写到属主表之外的位置 ⇒ 停下报告，不得自行发明路径。
10. **本包落点与协调板上在跑条目有交集** ⇒ 立即停下报人，不得强行开工，也不得改写别人的条目（总纲 §2.7）。
11. **提交归人**：session 只读 git（`status` / `diff` / `log`），**禁止 `commit` / `add -A` / `push`**；唯一例外是人当轮明确授权。
12. **同一失败测试 3 次仍红** ⇒ 停下报告，不得无限重试，也不得靠放宽判据「修绿」。
13. **dev diff 静默超出派单文件范围** ⇒ 停下报告；显式超出进 Gate `❓` 交人裁定。
14. **环境预热未就绪 / 已知红无基线** ⇒ 不派 dev；**用 L2 冒充 L3** ⇒ 停下报告。
15. **fast 路径不派研究波**；表达模糊就建议 `full`，不得用 fast 绕过「候选 → 裁定」。
16. **研究波没汇合 = 调研未完成** ⇒ 不得进 Gate0；两份研究件缺一、或 `C-NN` 没被逐条标注 ⇒ 不算交付。
17. **借鉴调研不得编引用 / 不得抄代码 / 不得引入依赖**；候选不得直接进 AC，必须由主控折成核对件 `Q` / `N`。
