Ll Iteration Dev

---
name: ll-iteration-dev
description: 迭代回路 阶段 3/3——多 worktree 并行开发全流程：主会话分解任务、建 worktree、派开发会话、拉取式收货、合并（交专门会话）、独立审计、发版与回写 tasklist。信息通道 = 每线一个状态文件 + 短决策循环（拉取代推送）。v3 增补：角色身份卡、回报格式与篇幅上限、同线超 5 轮踢出范围、管理会话违规自检、承重结论清单。当用户要求"用并行会话/worktree 开发多个任务""分工给几个会话并行做""并行开发然后你合并""发版/出包并回写任务清单"时使用。⚠️ 依赖跨会话协作——未在实验室开启「跨会话通信」总开关时本技能不可用。
runas: inline
---

> **回路位置**：[[ll-iteration-intake]]（初稿）→ [[ll-iteration-plan]]（排序与范围）→ **本技能**（并行开发 → 发版 → 验证 → 回写）。
> 接收阶段 2 的「单轮开发计划」（`handoff/<会话名>-单轮开发计划-YYYYMMDD.md`），其中每条任务的**验收标准必须可证伪**——§5.6/§5.7.2 直接对着它验证。
> **⚠️ 依赖**：需**跨会话协作**（`talk_to_session` / `create_collab_session` / 收件箱）。未在 **设置 → 实验室 → 跨会话通信** 开启总开关时协作工具族不注册，**本技能不可用**；开启前已开的会话需重建控制器。
> **沿革**：v1（parallel-worktree-dev）+ v2（拉取式信息通道，2026-09-21 用户拍板）= 2026-09-21 起唯一并行开发技能（依据 `issues/reports/并行协作跨会话汇报滞后-根因诊断-20260921.md` §8）。**v3** 从 DSH `orchestrator` 预设迁移五项机制，取舍见 §9。

# 并行 worktree 开发（管理只统筹 · 拉取代推送）

主会话 = 指挥官：不写业务代码，负责任务分解、派活、合并协调、审计协调、出包。
开发会话 = 执行者：在独立 worktree 里改代码、自验、写状态文件。
合并会话 = 专门负责合并的会话（⚠️ 合并不由管理会话自己扛）。
审计会话 = 独立第三方：只读审查合并结果，出 PASS/修复项。

## 角色与身份卡（v3）

**每条线开工前，派活消息发对应身份卡的文件路径（一行即可）并要求子会话开工首步 read；回退：子会话无法读文件时才粘全文。** 身份卡让子会话明确「父会话的哪些铁律**不适用于我**」，防止 §0 被误传导，也防止子会话反过来对管理会话复述"你从不自己干活"。

| 角色 | 职责 | 身份卡 | §0 铁律 |
|---|---|---|---|
| 管理会话 | 分解 / 派活 / 收货 / 拍板 / 出包 | 本文件即其规则 | **全部适用** |
| 开发会话 | 在 worktree 里改代码、自验 | `templates/role-dev.md` | ⚠️ **0.1「禁止写代码」不适用** |
| 审计会话 | 只读全量审读，出 PASS/修复项 | `templates/role-audit.md` | ⚠️ **不得改代码**；0.1 其余不适用 |
| 合并会话 | 执行合并 + 合并后全量验证 | `templates/role-merge.md` | ⚠️ **只做合并，不做功能开发** |

配套派活骨架：`templates/dispatch-message.md`。

## 0. 铁律

1. **管理对话不介入具体开发，只负责任务统筹。**
   - **允许**：定位分析、调研、短问题处理、**文档撰写**、执行命令（只读定位类）、派活、拍板
   - **禁止**：**写业务代码**、跑实现类长任务、深挖单点（判据：**同一问题超过 3 次工具调用仍定位不到 → 派给 wt**）
   - **代码合并交给专门的对话**（合并线，如 `wt-merge`）
   - **⚠️ v3：本条现有机器判据**——§4c 违规自检，变更类调用数应为 0。
2. **每轮 = 短决策循环**：`读状态 → drain 收件箱 → 派活/拍板 → 尽快结束 turn`。管理会话轮次应保持**个位数**。
   - 反例实证：某批次管理会话跑到 **100 轮 / 上下文 98.81%**，同期待办区堆 **9 条**跨会话消息——**长 turn 就是滞后的直接原因**。
3. **消息可以带状态正文**（人读方便、不必跳文件），**但同时要落盘一份**（留痕、有据可查）。
4. **回报有格式、有上限（v3）**：所有子会话回报按 4 字段结构，**正文 ≤ 30 行**，超出写成文件给路径。见 `templates/report-schema.md`。理由：管理会话的上下文是唯一瓶颈，一份 200 行回报就能让它提前进入长 turn。

## 1. 状态文件（唯一的进展通道）

- **每个 wt 一个文件**：`tasks/<批次>-进展-<线>.md`（管理会话读目录下多个文件；**不共用单文件**，避免并发追加交错）
- **备选（待用）**：一行一 JSON 的 jsonl（抗交错）——"多文件管理麻烦"或"需结构化查询"再切
- **格式**（一行一条）：

```markdown
| 时间 | 状态 | 轮次 | 阻塞点 | 需要管理决策 |
|---|---|---|---|---|
| 09:12 | 开发中 | — | 无 | — |
| 09:40 | 待收货 | — | commit d5e86f423 已推 | 是否并入本轮出包 |
| 11:05 | 修复中 | 2/5 | 审计 R-2 未过 | 无 |
```

- **v3「轮次」列**记该线已用掉的「审计→修复→复审」轮数（`已用/5`）。开发中/待收货填 `—`；进入修复循环后**必填**——这是 §5.8 踢出判据的**唯一依据，不许心算**。
- **wt 义务**（写进派活消息）：① 开工写一行 ② 有意义进展写一行 ③ **需要拍板的事写进最后一列**
- **管理义务**：每个 turn 开始**先读状态文件目录**，不等消息
- **读取成本**：只读需要的部分；文件按批次分、天然有界（防线：别读成"读放大"）

## 1b. 主动检查判据（v4 增补 2026-09-29：防「完成未回信→主对话误判进度」）

轮询律（§2）只定**节奏**；本节定**何时必须主动查**——三信号出现即主动 `read_session_tail`/催收，不等回信：

| 信号 | 判定 | 动作 |
|---|---|---|
| **wt 有新 commit 但无交付信** | `git log` 看到分支 tip 前进，收件箱无交付 | 疑似交付未报/漏报 → 发状态确认信（催补交付信） |
| **子会话 state=idle 且 wt 有 commit** | 干完了但静默 | 同上（idle+commit=完成未报强信号） |
| **state=unknown 且 lastActivity 远早于他人** | 停摆/中断 | `read_session_tail` 看末尾实际动作（跑测试=在途；结束在文本=卡）→ 对症处置（催/换线/踢出） |

**判读关键**：`state=unknown ≠ 不会开工`（0920 教训）；`idle ≠ 已交付`。**交付信是唯一收货凭据**——commit 只证明动过，不证明交付意图。实况教训（2026-09-29）：364 wt 已 commit `aa13981ab` 但无交付信，若只信回信会误判进度一小时。

## 2. 消息通道（信号 + 内容并存）

| 类型 | 内容 | 期望行为 |
|---|---|---|
| **唤醒** | "状态文件已更新"（可带摘要正文） | 管理下一轮读文件 |
| **阻塞** | "需立即拍板：<一句话 + 2-3 个选项>" | 走 steer（即时；窗口错过则排队，wt 可继续做别的） |
| **进展** | 可写在消息里（人读方便）+ **同时写进状态文件**（留痕） | 管理按需读 |

> **[订阅推送]（2026-09-25，任务 284）**：`talk_to_session` 正文以 **`[订阅推送]`** 开头 = 订阅引擎自动推送，非对方手写信——仍正常处理（steer 进 turn），但**回复不必回给对方会话**，按内容处置（事件自处置类无回信对象）；识别后按上表三类归档。

**回信通道选择（2026-09-21 用户要求：主动引导子对话用即时回信，防主对话拿到过时信息）**：
- **里程碑完成（Block / 任务级）→ `delivery=steer`**：管理 turn 运行中即时可见；followup 会积压到 turn 结束才注入——多线并行 + 管理 turn 长时，子对话拿到的是**过时信息**
- **需立即拿决策才能继续 → `talk_to_session(wait=true)`**（同步等待；超时降级为普通消息并改走状态文件）
- **普通进展 / 细节 / 存档 → 状态文件 + followup**（221 实施后队列内多条会合并+折叠，不刷屏）
- **管理会话派活时必须明示回信方式**（例：「里程碑用 steer 汇报；细节写状态文件」）——**不让子对话自己猜**

**等待子对话（禁止占位死等）**：
- **不要用 bash sleep / 长 wait 占位**——死等不感知事件（实例：设 1200s，子对话 500s 已回，浪费 700s）；本环境 bash 后台 job 也不可靠
- **⚠️ 强制轮询律（2026-09-24 用户指令）**：主对话**不得停止等待子会话唤醒**——**每 5 分钟检查一次各在途线进展**（状态文件 + wt commits + status），检查时**顺手收货**（与 §4b 合并执行）。实现 = `sleep 110` 分段循环（**host bash 单命令上限 120s，`sleep 300` 必被掐——2026-09-24 实测三轮全超时**）：sleep 110→检查→sleep 110→检查 ≈4min 一轮（steer 可在运行中即时插入，不堵用户）；全部闭环后停
- **目标形态是 `event_wait`（任务 228，待实施）**：事件触发器（targets + mode=all_idle + timeout），条件满足即被唤醒，等待期间仍可收 steer；落地前的过渡 = `sleep 60` + `get_session_status` 重查并顺手收货

**「需立即拍板」标注标准（三条全满足才可标）**：① 阻塞（不拍板 wt 只能空等）② 有时限（拖延有明确损失）③ 有选项（2-3 个明确选项）。禁止标注：进展汇报 / 知悉类 / "顺便问一下" / wt 可自行决定的小事（自行决定 + 事后写进状态文件）。滥用可查：标注频率可统计，作批次复盘依据。

## 3. steer 的定位

**心智模型（2026-09-21 实测定稿）**：
- `followup` = **挂号信**——恒定排队：等收件方处理完当前 turn 才注入，无例外
- `steer` = **敲门插话**——收件方 turn 运行中就即时插进去（进引导队列）；**对方 idle / turn 已结束 → 自动降级为挂号信**（`DispositionQueuedFollowup`，`internal/control/inbox_steer.go:161-200`）——消息不丢，但**失去即时性**；降级后的消息按任务 221 三档正常参与合并（合并设计对降级透明）
- 推论：**"steer 发出去了" ≠ "对方即时看到了"**——即时性由对方状态决定；需要确认即时性时用 `talk_to_session(wait=true)`

- ⇒ steer 是**尽力而为**的即时通道：**紧急拍板 / 阻塞 / 里程碑完成**；仍**不当细节级日常汇报**通道（细节走状态文件）
- ⇒ 判断标准：**"这条消息晚 10 分钟到达会有什么损失？"** 无损失 → 状态文件；里程碑/阻塞 → steer；需回话才能继续 → sync
- `interrupt`（中止当前 turn）**暂不做**；出现"必须立刻停某条线"的事故再立项

## 4. 触发方式

- **信号（a）**：wt 更新状态文件后发一条唤醒消息
- **轮询兜底（b）**：管理侧用 heartbeat 定时拉一次状态目录
- **⚠️ 任务完成后必须关闭对应心跳任务**（轮询型心跳是临时手段；忘关会常驻烧资源）

## 4b. 子对话活体巡检（防主对话傻等 · 2026-09-24 用户指令）

**规则**：派活后**定期**（每次决策循环 drain 时，或每 15-30 分钟）检查每个**在途子对话**。**子会话异常（中断/卡死/决策框挂起）后不会主动交付，主对话若只依赖拉取式收件箱会一直傻等**——文件是被动信箱，对方停止后不会来读（211 教训的活体版）。

**判据三步**（Phase 0，详见 session-recovery-cleanup）：
1. `get_session_status` state——`unknown` = 进程不可见 **≠ 死**（inbox 消息仍会驱动），勿据此判
2. `read_session_tail` 最后活动——注意**尾部 = 最后那轮的中段**，lastActivity 老 ≠ 卡死（可能长 turn 未结束）
3. **jsonl mtime + 尾部结构（权威）**：`<120s` = 在写；分钟级冻结 = 卡；尾部见 `interrupted_turn:{pending:true}` = **派活 turn 被中断挂起**；空 tool 行 +「转用户决定 op_xxx」= 决策框挂起（不可自行重发）

**处置按形态**：
- `interrupted_turn pending` → **发一条消息续跑**（inbox 驱动打断 pending turn，实测 15s 苏醒）——常见于**出包 relaunch 窗口**打断派活 turn
- 决策框挂起 → 发**处置指令**（不重提交被禁 op + 跳过受限点先交付能交的 + 回报状态），冻结由用户在面板解
- mtime 长冻结且无回执 → 报告用户（考虑重建会话）

> **重启更新 / 出包窗口的判据**（`execute` 报「a turn is running…」怎么解、build 与 running 版本错位、为何不能靠结束自己 turn 绕）见 `templates/liveness-and-restart.md`。

## 4c. 管理会话违规自检（v3 · 把 §0.1 从自觉变成可测）

**动机**：§0.1 此前**只靠自觉**，没有任何机制能发现管理会话偷偷跑了实现类任务——而 §0.2 那条反例（100 轮 / 98.81%）正是这么发生的。

**命令**（每次 §4b 巡检时顺手跑；**用绝对路径**，技能加载后 cwd 不保证在技能目录）：

```bash
python "%APPDATA%\reasonix\skills\ll-iteration-dev\scripts\session_violation_scan.py" --session <管理会话名或 jsonl 路径>
```

**判据**：会话 jsonl 的 `role:"assistant"` 记录里，每个 tool_call 带 **`tool_recovery.read_only`**（**应用自己算的**）：

- `read_only: false` = **变更类调用**（`edit_file` / `write_file` / `use_capability` / 会改文件的 `bash`）
- `read_only: true` = 只读（`read_file` / `bash_output` / 只读 `bash` / `todo_write`）

⇒ **管理会话的变更类调用数应为 0**（`todo_write` 与只读命令不计）。

**为什么不用自己写正则**：`bash` 两类都大量出现（同会话实测 595 变更 vs 369 只读），**应用已替我们分好类**；约 17% 调用 `tool_recovery` 为 `null`，脚本回退到工具名白名单、双用途工具计「未知」（不猜），`--deep` 可看命令原文。

**处置**：
- 计数 >0 → 先看明细（脚本按「应用判定 / 工具名回退 / 命令特征」拆开列），排除只读定位的误报
- 确认越界 → **立即停止实现类工作，整段转派给 wt**，并如实告知该线已产生的改动
- **同一批次连续 2 次巡检越界 → 必须在下次向用户汇报中明示**（不许静默）

**边界**：本自检**后验**（拦不住，只能发现），且**只对管理会话有意义**——扫开发/合并会话必然显示大量变更调用，属正常。

## 4d. 心跳守护（v3.1 · 防批次中断——定时唤醒主对话）

**动机**：批次长跑中主对话可能停摆（中断循环/碎轮早收/turn 死锁，303 族），子对话空转无人收——用**复用型守护心跳**定时兜底（类 openclaw 心跳；2026-09-25 用户定）。

**动作（批次开工创建 / 收尾删除）**：注册 `parallel-dev-watchdog-<批次号>` 到 `heartbeat-tasks.json`（interval=`10` 分钟（2026-09-30 用户指令：从 20 降至 10，最大空闲时间减半），已核 `heartbeat_schedule.go` 支持分钟级无下限）；**单守护多批次**——共用一个任务读批次清单文件，不每批次建。注册与唤醒消息细节：`templates/watchdog-heartbeat.md`。

**四条铁律（判据）**：
1. **先查再唤 + 宽口径**：主对话 running 或静默 <40min（2×周期）不打扰——长思考/长工具会误判；
2. **唤醒带自证上下文**：批次号 + 线程 hash 链 + 状态文件指针 + "你最后处理到 X"——主对话压缩/重启后凭一条消息即续（211 教训）；
3. **自愈清理优先**：心跳自检批次完结/不存在 → 自删任务；主对话收尾删除只是兜底（防中断遗留僵尸心跳——9614 族）；
4. **心跳禁干活**：只查 + 唤 + 自删，变更类调用应为 0（可跑 §4c 脚本验证）。

**子对话状态检查（2026-09-30 用户指令新增，模板已同步）**：每次心跳唤醒主对话时，prompt 必须要求主对话用 `get_session_status` 检查全部在飞子对话——三条行动触发：
- **备案免报**（20260930 晚补）：台账/状态文件已备案「空闲原因」（交付完待命/等待外部输入）的线不报停滞——只报未备案的 >2h+inbox0 线（防误报已备案线浪费注意力）；模板见 `templates/watchdog-heartbeat.md`。
- **交付未收**：子对话交付了新件但主对话未收到回信 → `read_session_tail` 查看实际进展，补发审单/派单
- **空闲+收件箱空**：子对话 state=idle 且 unreadInbox=0 → 可能有交付被漏收，`read_session_tail` 确认后补审
- **unknown+过时**：state=unknown 且 lastActivity 超过 1h → `read_session_tail` 确认停摆原因，必要时改派

**待办面板同步（2026-09-30 用户指令）**：心跳唤醒时若批次任务状态有变（过审/交付/新立项），同步更新 fork 桌面端右侧待办面板数据——Block 末由 plan 计划文档的阶段门保底全量同步，心跳做**细粒度增量**（单件状态变化即刷）。面板与 tasklist 的关系：面板=桌面端可视化快照，tasklist=权威源；面板更新从 tasklist 投影，不反向。

**派单台账对账（2026-09-30 用户指令）**：守护唤醒 prompt 必须同时要求主对话对账「派单跟踪台账」（批次总表内）——派单即登记（线/件/派出时刻/期望回执/状态四色），唤醒第一动作=逐行核对，>2h 无回执且无进展=催办，二次停滞=改派。子对话「停止不回信」造成的协调真空由台账机制兜底（状态：✅完成/🔵在途/⚠️超时催办/⏸依赖等待）。

**目标 = 零空闲**：子对话交付完的下一分钟就应该有新指令或审单到达（10 分钟心跳间隔确保最大空闲 ≤10 分钟）。

**未来迁移**：高级定时器（定时 sleep + 可被提前唤醒）落地后**只换触发源**为会话内 scheduler 自唤醒（不建任务、零额外会话），上述契约原样保留；注意 eventtrigger 一族有 interval 下限，迁移时核对。

## 5. 流程七步

### 5.1 任务分解（动手前）

- 每个任务先读 tasklist 正文，确认「要做/验收」细节；没写清的自己补全再派
- **按域分组**：同域任务给同一会话（前端归前端、Go 归 Go、全栈单独），减少跨会话文件交集
- **v3：同时产出两份清单**（派活与审计的输入）：
  - **承重结论清单**（`templates/load-bearing-claims.md`）——本轮哪些结论是**交付所依赖**的（运行时契约、发版依据、用户可见行为、跨线接口假设）。审计火力优先压在这些上
  - **共享产物清单**——判据是三类，**第三类最易漏**：① 同一批**文件**（老规矩）② **命名方案**（新配置键、新 tasklist 标记、新会话/分支命名）③ **接口契约**（渲染表、七件套链路、跨模块签名）。**②③ 必须写进所有相关线的派活消息**，不能只给"负责那部分"的线
- 每个会话的指令必须含：worktree 绝对路径 + 分支名 + 基线 commit、任务正文位置（文件+行号）、具体范围、验收标准、汇报要求、禁项（不 push / 不出包 / 不动 tasklist）

### 5.2 基建（worktree + junction）

```bash
git worktree add ../worktrees/wt-A -b wt-A main-v2-stable   # 基线取当前 main-v2-stable HEAD
git worktree add ../worktrees/wt-B -b wt-B main-v2-stable
# 前端任务需要 node_modules：建 junction 指向主仓（省 2min install）
cmd //c "mklink /J wt-B\\desktop\\frontend\\node_modules ..\\..\\..\\reasonix\\desktop\\frontend\\node_modules"
```

- 命名规范：`wt-<主题>`（放 `github-repo/worktrees/`，无下划线前缀）
- **junction 是借主仓的依赖，不是自己的**——派活消息写明「pnpm 结构若报缺依赖就用主仓跑」

### 5.3 会话编排

- **统一分组**：所有 wt 开发/审计会话必须 `create_collab_session(group=...)` 建进**同一个对话分组**，不要散建
- **归组规则（2026-09-22 用户补充）**：若已有用于收纳相关对话的组，新建对话必须放进该组，**不得落到未分组**。判断方法：看相关对话命名——大部分带 `wt-` 前缀
- **命名规范**：开发/审计子对话同样以 `wt-` 前缀开头（如「wt-232 开发」「批四审计-1」），使命名即分组线索
- **复用优先是偏好，不是硬规则**：默认先 `list_addressable_sessions(query)` 查目录，同领域已有会话**倾向复用**（积累经验 + 缓存成本低）；新建也有正当好处（干净上下文、任务隔离）。① 权衡后选择即可 ② **用户要求新建时一律以用户为准** ③ 新会话 purpose 写清职责
- **v3（0930 改路径式）：派活必须附身份卡**——按角色发 `templates/role-dev.md` / `role-audit.md` / `role-merge.md` 的**文件路径（一行，主对话输出最省、无歧义），并要求子会话开工首步 read**（卡里已含 §0 豁免声明 + 回报格式）；子会话无法读文件时才粘全文。**不要**只发任务正文让子会话自己猜角色
- 建完立刻用返回的 contact_id 派活（`talk_to_session`, `to=contact_id`），**派活消息里写 contact_id 让对方回信有址**
- 审计会话此时就建好（省一轮），等各线齐再派审计指令
- 一批活跃会话 **≤6 个**（2026-09-22 放宽，原 ≤4），防 429；**Block 数仍 ≤3、单线串行深度仍 ≤3**

### 5.4 收货（拉取式）

```text
管理会话每个 turn：
  1. 读 tasks/<批次>-进展-*.md（先拉，不等）
  2. drain 收件箱（steer 已在 turn 中即时收过，此处主要是 followup）
  3. 对"待收货"的线：核对 commit / 验证清单 / 预存失败归属（三件）
  4. 派下一步 / 拍板；合并类工作交给专门会话
  5. 结束 turn（不顺手做实现）
```

- 核对三件：commit hash 落在指定分支、验证清单全绿、预存失败用 `git stash` 对照标注归属
- **汇报里的「预存失败」必须逐条处置**：本轮引入 → 立即修；确为预存 → 记录归属，不阻塞合并
- 收货确认消息发回开发会话（它完成了，可以休息）

**v3：回报格式（强制）**——4 段，**正文 ≤ 30 行**，超出写文件给路径：

```text
① 目标：<一句话>
② 做了什么：<改动文件 + commit hash>
③ 验了什么：<跑了什么命令、看到什么结果>   ← 必填，不许省
④ 没验什么 / 阻塞点：<逐条，没有就写"无">
```

- **③ 缺失 = 回报按未完成处理**，直接打回重报。worker 自报天然乐观（"测试过了""文件改了"都可能是错的）
- 给证据用**路径 + 行号 + 关键几行**，不要贴大段日志或文件原文。模板：`templates/report-schema.md`

### 5.5 合并（专门会话做，不在管理会话里合）

```bash
git worktree add ../worktrees/wt-merge -b wt-merge main-v2-stable
cd ../worktrees/wt-merge
git merge wt-A --no-edit && git merge wt-B --no-edit && git merge wt-C --no-edit
# 合并后全量验证：go build 两模块 + 相关包 test + tsc + 关键 tsx
```

- **零冲突 ≠ 语义正确**：必须核对「**基线独有改动是否被 ours 侧保留**」（三分支都从旧基线建时，diff 里的删除行可能是**基线领先**而非分支删除）
- **v3：交叠点清单按三类核对**（对齐 §5.1）——① 文件级（render.go 键、bundle budget ratchet 数值、共享组件两特性共存）② **命名方案**（两线是否各自引入了同义不同名的键/标记/命名）③ **接口契约**（跨模块签名、渲染表、七件套链路是否被单侧改动）
- 跨线「改动是否真在包里」：diff 非空 ≠ 被冲掉（基准错位），用**祖先性 + 关键行逐字**双证据

### 5.6 审计（独立会话，只读——2026-09-22 用户三原则强化）

**三原则（硬要求；2026-09-22 用户两轮定稿）**：
1. **审计主会话自行派子对话**：管理会话只派 **1 个审计主会话**（附任务清单与文件域参考），由它**自行决定分工并派自己的审计子对话**，再由它汇总回管理会话——比管理会话预切分更公平，避免指挥官偏见传导进审计
2. **全量审计，不得跳过**：每个审计子对话对其负责的任务做**逐任务全量代码审读**（实现逐行级 + 验收锚点逐条核对），禁止「风险点优先抽查式」跳过——抽查只能作为全量之上的补充视角
3. **子对话合起来必须覆盖全部任务**：派活前先做任务→子对话分配表（`templates/audit-split.md`），确认无遗漏、无重叠；汇总回信时附**覆盖声明**

**v3：承重结论优先（加码，不是减码）**——全量审读照旧，但派审计时**附 §5.1 的承重结论清单**：清单内每条必须给**实证**（真跑一遍命令 / 真读一遍产物），不能只"看代码觉得对"。理由：worker 自报乐观，而"测试通过""文件已更新"这类**承重**结论一旦错，整批交付就是错的。

**产出**：
- **PASS / 修复项**：修复项回开发会话迭代（或合并线修）；PASS 则闭环。**修复项必须编号**（R-1、R-2…），供 §5.8 记轮次
- **⚠️ PASS 只能由审计线给**：开发会话的自验**不构成 PASS**——它说"改好了"只代表它认为改好了
- 审计的「建议级」（S1-S4）/note 逐条处置：能立即核实的核实；UX/健壮性类记 tasklist 后续；流程类写进本 skill
- 回信通道：**要求审计子对话用 steer 回信**（管理消息队列有滞后）

**Block 间审计闸门（多 Block 批次适用）**：每个 Block 结束 = 合并 → 测试 → **审计** → 通过才进下一 Block 的开发。**禁止把审计攒到批次末尾**（批次末审计只覆盖增量）。

### 5.7 发版与回写（后半程）

> **逐条命令、台账纪律、标记写法、收尾归档顺序**见 `templates/release-and-tasklist.md`。要点：

- **5.7.0 出包前测试文档（必做）**：改动点清单 + 每条验证方法 + **已知未含项（v3 必列：§5.8 踢出范围的线）**。**缺此文档不得出包**
- **5.7.1 发版链**：版本号不自增（复用 `1.38.3` + 时间戳包名）；release notes 先于构建、只写增量；正式发版走 `release-fork.yml` 手动 dispatch + tag；**出包只在用户明确要求时做**；构建前 `TestDesktopRenderTableCoversEveryKey` 必须绿；台账每次追加一节；**不自动合并主线**
- **5.7.2 人机协同验证**：**证据三件套**（现象 + 日志 + 截图，缺一不算验过；修复类给改前/改后对照）；**基线对照铁律**（同一条命令改动前后各跑一遍）；性能类用 `scripts/perf-probe/`，内存类先做 heap profile；**装机验证是硬闸**；验收条目逐条勾，**勾不了的写「未验 + 为什么」**
- **5.7.3 回写 tasklist**：脚本路径禁手搬；**标记写法写错 = 状态静默不生效**；**回写依据是提交不是记忆**；**v3：被踢出的线不得标 `done`**；tasklist 只由主会话统一更新
- **5.7.4 收尾归档**：handoff 自包含（3 天保留）；一次性脚本归档到 `scripts/<主题>/`；**先删 junction（必须验证成功）→ worktree remove → branch -D**

### 5.8 同线超轮次踢出与最终报告（v3）

**问题**：§5.6「审计通过才进下一 Block」是硬闸门，但**没定义「某条线反复修不过去」怎么办**——按原规则，整批会被一条病线锁死。

**轮次定义**：一轮 = 一次「审计出修复项 → 回线修复 → 复审」闭环。轮次记在状态文件的「轮次」列（§1），**不许心算**。

**上限**：**同一条线最多 5 轮**。第 5 轮复审仍不 PASS → **触发踢出，不再进入第 6 轮**。

**踢出动作（四件，缺一不可）**：
1. 状态文件该线标 `⏸ 阻塞（超轮次 5/5）`，写明**未通过的具体验收条目**
2. 从**本轮出包范围**剔除，写进 §5.7.0 验证文档的「已知未含项」
3. tasklist 按实情标 `partial` / `⏸ 阻塞`（**不得标 done**）
4. **查依赖**：若被踢出的线是其他任务的前置，标注受影响的**下游任务**

**最终报告必列（硬要求）**——批次收尾时，被踢出的线**单独一节**，每条五项，**缺项即报告不合格**：
① 线 / 任务号　② 已用轮次（如 `5/5`）　③ **每轮修复项**（R-1…R-5 逐条，含当轮审计结论；**不是只写"修了 5 轮"**）　④ **未通过的验收条目**（引用阶段 2 原文，不要自己重述——重述会悄悄降低标准）　⑤ 阻塞原因与建议（技术根因 + 下一步：拆分？换方案？需用户决策？）

模板：`templates/batch-final-report.md`。

**为什么必须进报告**：踢出范围是**降低交付范围**的决定，不是"任务消失"。用户的装机验证清单、tasklist 状态、下一阶段 plan 都依赖这份账；**少写一条 = 静默缩水**。

## 5b. 界面自验（指针 · 2026-09-27 用户指令拆分）

装机/预览级界面验证的**技术细节全部在 `references/gui-self-verify.md`**（主文件不重复）：CDP 自验链五步、**窗口全屏铁律+缩放注意**、gui-click-verify 脚本坑序（pit1-8）、切换耗时日志判读（切出 save/dag nil_cache 归因 196）、截图纪律。流程上记住三条即可：

1. **一律全屏/最大化测试**（`window.runtime.WindowMaximise()` 后核 viewport≥1280）——小窗口遮挡会产生误导性失败；
2. 验证实例必须独立 REASONIX_HOME/APPDATA，用完按「清理五件」收尾；
3. 结果 json 会被后续跑覆盖——留档先备份。

## 6. 大坑与教训（实战全部踩过）

> 一行版在此；**现象 / 根因 / 逃生步骤的完整版**见 `templates/pitfalls.md`。

1. **`rm -rf` 会跟随 Windows junction 删掉目标内容**——先 `cmd /c rmdir <junction>`（只删链接），必须验证成功，绝不吞错（首轮就是这么删掉主仓 `node_modules` 的）
2. **junction 删除失败会被 `git worktree remove` 以 "Directory not empty" 拒绝**——先清 junction
3. **new Desktop keys 必须带 render.go 渲染行**，否则保存被静默丢弃（`TestDesktopRenderTableCoversEveryKey` 是唯一防线）
4. **新实验开关走全链路七件套**：config→setter→渲染表→UI→bridge→types→locales（漏一环 = 保存丢）
5. **boot 快照 vs 调用时求值（S4 约定）**：collab 类工具的会话路径/身份一律**调用时求值**
6. **前端测试用 `npx tsx <file>` 直跑，绝不用 vitest 路由**——vitest 报 `No test suite found` 是正常现象
7. **heredoc 写含反引号的 markdown 会被命令替换**——markdown 一律用 `write_file`/`edit_file`
8. **主会话派活消息必须带收信地址**（contact_id），否则对方回不了信
9. **worktree 里跑构建可能报命令找不到**——先确认 junction/依赖完整再归因代码
10. **并行会话写同一 tasklist 文件会冲突**——tasklist 只由主会话统一更新
11. **跨会话回信 thread_id 必须用「自己收到的入向消息 id」**；送达判定看对方 `inbox.jsonl` + `seen.json`，`queued` ≠ 已读
12. **对大文件 edit 前必须一次完整 read**——分段读的累计覆盖不被承认；中文文件禁 PowerShell `Set-Content`（写坏 UTF-8）
13. **对应用会写回的配置文件打补丁，幂等判定必须段级**（应用渲染会重排字段 + 加注释）
14. **批次交付/出包须出验证清单**：🤖 已自验 与 👤 待人工 两类分列；人工项通过后任务才转 `verified`；**v3 增补：清单必含「已知未含项」**
15. **同 turn「先写后派子代理」在保守态会被父写 claim fail-fast**（报错文案已区分「父持写」并给绕法，任务 315）：派**写权能**子代理（explore、task 无只读 profile——它们声明 WholeWorkspace 写槽）前，等本轮写工具结束再派，或改派 `read_only_task`/`read_only_skill`（只读不占写槽、永不被父写挡）；`optimistic_write=true`（乐观并行开）时父写不拦任何子代理，无需规避

16. **交付信没发出但现场齐 → 直接派审**（343 实例，0928）：进展文档+commit+分支都在=事实交付，不等信；对施工方只补一封「现场收讫」即可，避免审计空等
17. **两件改同一行（逐字同改）= git 自动合幂等**：冲突预警先看内容——同改取一无冲突、另一 cherry 变 empty=skip 无害；派单时点名「与 X 件同改」让合并线有预期（save_records 补参实例）
18. **验收口径「条件 PASS」**：装机值无法当场测时——bench 实测+等比推算先行过审，**以装机实测为最终判据**（end 打点回填）；推算超阈值则「过审+报批下一方案」并行（334 方案2 实例），不 silently 扩面
19. **三态盘点表=出口检查资产**（305 实例）：每 Block 结束做「有测试/应补/不适用」逐件标注（commit stat 抽测试文件名），盘点过程中顺手抓基线坏测试（333 加参未同步 193 即此役抓获）
20. **node_modules 会二次损坏**（279 后 305 复发）：特征=.bin 空/依赖丢/多文件假失败——rm + pnpm store 重建（26s，先例在档）；**多文件莫名假失败先查环境再改代码**；recovery 类「预存红」若环境修复后全绿，做 A/B 回退对照才可判环境性（343 裁决以三态归属法为准，不轻翻）
## 7. 时序参考（首轮实测）

分解 10min → 基建 5min → 三线并行开发 ~60-90min（Go 全量测试 3-6min/线）→ 合并+验证 15min → 审计 20min → 收尾 ~15min，全程约 2.5-3.5h，比串行（六任务 ×1.5h）省一半以上。
> v3：若某线走满 5 轮，按 §5.8 **及时踢出**——**不要为了让所有线都绿而延长批次**，那正是长 turn 与上下文爆炸的来源。

## 7-b. 进展汇报格式（2026-09-23 用户定）

向用户汇报进展时，**SVG 直观展示在前 + 文字汇报在后**：

1. **SVG 进展图在前**：各线/会话状态可视化（进行中/待命/完成/阻塞分色），含批次总览、在途任务、审计/开发会话资源位
2. **文字汇报在后**：状态表 + 关键数据（hash 链/测试结果）+ 待决事项
3. 单次汇报内 SVG **只画当前快照不堆历史**；里程碑级汇报（Block 收官/出包）图上标注对账数（如 verified +N）
4. **v3：轮次可视化**——修复中的线标「R2/5」；被踢出的线用阻塞色并标「超轮次」

**模板**：`templates/progress-board.svg.tpl`——**复制全文**改 `{{}}` 占位符 + 按数量增删卡片（高 52px 步长 60px），**勿从零写**。状态色四选一：进行中 🟡 `#f9e2af` / 就绪 ⬜ `#89b4fa` / 闭环 ✅ `#a6e3a1` / 阻塞 🔴 `#f38ba8`。
**输出姿势（2026-09-23 实测修正）**：SVG 落盘 → 对话里**附件行在前** `![进展板](x.svg)`（渲染器只认附件行，内联 `<svg>` 会剥成纯文本）→ 文字汇报在后。

## 8. 反模式

1. 管理会话跑实现类任务 → 长 turn → 消息全排队（截图实证）。**v3：现在有 §4c 可测**
2. 把 steer 当日常汇报通道（"尽力而为 + 被拒降级"不适合做稳定通道）
3. 多线共写同一个状态文件（并发追加会交错）——用**每线一文件**
4. 指望"优化消息传输速度"解题（延迟来自"等 turn 结束"，不在路上）
5. 用完心跳不关（轮询型心跳是临时手段）
6. **（v3）让子会话自己猜角色**——不附身份卡，等于赌它不会把父会话的铁律套到自己头上
7. **（v3）为了"全绿"无限修同一条线**——超过 5 轮就该踢出范围并记账，不是继续烧上下文
8. **（v3）接受了没写「验了什么」的回报**——那是把乐观自报当成事实

## 9. 本文档的尺寸预算与维护

**为什么**：本技能 `runas: inline`，**每次加载整份进上下文**。正文每涨 1KB，都是全批次的重复税。

- **预算**：`SKILL.md` 正文 **≤ 32KB**（v2 28KB → v3 30KB → v3.1 32KB：+4d 心跳守护）。**棘轮规则**：上调须一次到位（+2KB 步长）并在本行记「哪次变更、实际字节、为什么取该值」；超预算不许直接堆正文——细节外移 templates/
- **新增经验的落位规则**：
  - **判据 / 触发器 / 一句话规则** → 进正文（必须 1 行说清，且是**动作指令**）
  - **现象 / 根因 / 实证 / 长表格 / 命令清单** → 进 `templates/`（正文留一行 + 指针）
- **templates/（13）**：身份卡 `role-{dev,audit,merge}.md`｜派活回报 `dispatch-message.md`、`report-schema.md`｜v3 `batch-final-report.md`、`load-bearing-claims.md`｜运维 `pitfalls.md`、`release-and-tasklist.md`、`liveness-and-restart.md`、`watchdog-heartbeat.md`（§4d）｜沿用 `audit-split.md`、`progress-board.svg.tpl`
- **scripts/**：`session_violation_scan.py`（§4c，调用用绝对路径）
- **自检**：改完正文后跑一次体积检查

## 关联

- 迭代回路：[[ll-iteration-intake]]（阶段 1）｜ [[ll-iteration-plan]]（阶段 2）
- 诊断：`issues/reports/并行协作跨会话汇报滞后-根因诊断-20260921.md`（拉取式通道的决定记录）
- 任务：143（steer|followup）、**202**（C 阶段状态流引擎化，落地后人工写状态退为兜底）、19（协作底座 done）
- 方案文档：`docs/自主迭代-执行层缺口分析与落地方案-20260920.md`
- `reasonix-win-build`（出包细节）；`gh-issue-submit`（上游反馈）；`session-recovery-cleanup`（巡检 Phase 0）
- fork 开发八条铁律（memory）；出包台账 `handoff/fork开发-出包台账-20260914.md`
- **v3 迁移来源**：DSH Preset Square 的 `orchestrator`（分解委派模式）预设（`preset-a42d73`）。迁移 5 项机制，**刻意未迁移**：① 其硬拦截插件（root 连 `read` 都禁——与 §0.1 允许"只读定位"冲突）② "worker 不得二次委派"（与 §5.6 三原则之 1 冲突）③ "承重审计替代全量审计"（§5.6 全量为用户定稿，只做加码）


---

## 心跳任务模板（2026-10-07 精炼版，源自 guard-fork3 守护心跳多轮迭代实测）

> 多轮迭代沉淀的守护心跳写法。四件套定位：心跳=触发点（到点点名），流程细节在技能，状态在留言板/tasklist，判据在本模板。

### 模板骨架（六段，直接套用）

```
【总览·<日期> <定调来源>】
① <主对话角色与协调节奏>（contact/topicId）
② <执行线核心目标，分 A/B/C 组>（每件带任务号与交付形态）
③ <在飞收尾件>（tip/sha 现状）

【唤醒先读（两通道互不替代）】
① 总线收件箱：get_session_status / peek_own_inbox / read_session_tail（不可用时 drain_inbox）；
② 外部留言板：<板路径>（独立状态源，非总线降级通道）。
两通道皆无新留言、且无状态变化 → 一句话结束。

【职责（禁令照旧）】
只做三件事，禁止写代码 / 改任务 / 跑测试：
① 读状态：<板路径>（有新留言必须在唤醒消息里提示主对话收货）+ <人工核实清单路径>；
② 查活跃：get_session_status 查主会话（topicId=<id>）与全部在飞子对话；
③ 唤醒决策：主会话 running → 不打扰，一句话结束。

【判据（实测沉淀，继续有效）】
- auto_guard 检查不算实质推进；主会话近 2 小时无实质动作（无板写入 / 无 git 提交 / 无派单）⇒ 即使 running 也发常规唤醒（带状态指针：在飞件/待收货件/阻塞项）；
- 留言板例外：板上有未收货新留言（新于主对话最后「已读至」游标）⇒ 周期到即发【守护唤醒·留言板收货】；
- ❌ 不要报告「在飞子代理 N 个」（无观测通道）；worktree dirty ≠ 有子代理在飞；
- ✅ 只报告可直接观测事实四项：① 板新留言+字节数；② 主线 tip+未动时长；③ 已交付未合并分支数（wt-* tip 不在主线祖先链）；④ 主对话 lastActivity。

【项目专属上下文】
- <仓库路径与 worktree 规范>；<tasklist 工具与权威源>；<口径约定>；<出包/装机脚本与验证命令>；<报告目录>

自愈：删除本心跳以用户明确确认为准。
```

### 迭代沉淀的四条硬判据（模板的核心价值，勿删）

1. **2h 无实质动作即唤醒（即使 running）**——auto_guard 自答不算推进（2026-10-06 zcode 队列清零空转 1.5h 实测）；
2. **留言板例外优先于静默**——有未收货留言必唤醒，不等 2h；
3. **不臆测不可观测态**——「在飞子代理数」无通道即不报；`worktree dirty ≠ 子代理在飞`（误报实录两起）；
4. **只报四项可观测事实**——板字节/tip 时长/未合分支数/lastActivity，每项带实测命令。

### 配套：执行线并行度心跳（zcode 日/夜切换）

- 夜间（23:00）放宽 zcode 并行子代理上限至 6~9；日间（09:00）收敛回常规——两条独立心跳，prompt 各 3~5 行只改并行度数值与窗口说明。