# Multi-Session Collaboration Rules

这份文档只解决一个问题：

**当多个 Session 或多个 Agent 同时操作 TVU 设计系统仓库时，如何避免互相覆盖、互相引用旧结论，或把 Figma-first 规范做散。**

## 目标

协作时优先保证下面四件事：

1. 规范口径只有一个来源
2. 共享总线文件只由主线程合并
3. 局部实现可以并行，但决策不能并行漂移
4. 最终状态只以主线程的全量验证为准

## 核心原则

1. 同一时间只允许一个主 Session 负责规范决策。
2. 其他 Session 或 Agent 可以并行实现局部任务，但不能各自改写规范结论。
3. 所有新的结构性决定都必须先写回 `docs/`，再允许后续 Session 继续扩展。
4. 判断是否“符合 TVU 设计规范”，不能只看局部页面，必须看主线程的全量 `build/test/audit` 结果。

## 角色划分

### Claude / Codex 单一决策源模式

当前默认协作模式：

- Claude 负责产出一版路线图 / prompt，并把结构性决策写入仓库文档。
- Codex 不再做“加料式评论”，不在 Claude 的路线图基础上继续扩展新路线。
- Codex 只做三件事：
  1. 检查是否有明显风险或 blocker（误删、误 commit、改 Figma、范围不可验证、与仓库规则冲突）。
  2. 执行 prompt 指定任务。
  3. 报告改动、验证结果和未解决项。
- 如果 Codex 不同意，只指出会导致失败的 blocker，不扩展替代路线。
- 一旦路线图 v2 或同等阶段计划落仓库并经用户确认，所有新 Session 以该文档为准，不在对话里反复发明新框架。

### 主 Session

主 Session 负责：

- 决定信息架构
- 决定 Figma-first 口径
- 合并共享文件改动
- 更新 handoff / audit / review docs
- 运行最终全量验证

### 子 Session / Agent

子 Session 或 Agent 负责：

- 单个组件或单个页面的局部实现
- 不跨模块的样式或 wrapper 调整
- 只读审查或局部验证
- 输出“改了哪些文件、还有什么共享 follow-up”

子 Session 或 Agent 不负责：

- 修改全局规范
- 单独宣布某轮工作“全库完成”
- 在未同步 handoff 的情况下继续扩散新结构

## 文件所有权

### 只能由主 Session 修改的共享文件

下面这些文件默认视为“共享总线文件”，只能由主 Session 合并修改：

- `docs/session-handoff.md`
- `docs/2026-04-27-component-completeness-audit.md`
- `docs/figma-provenance-audit.md`
- `docs/conformance-issue-log.md`
- `playground/docs/navigation.ts`
- `playground/docs/DocsShell.vue`
- `playground/docs/figmaFirstRegistry.ts`
- `src/index.ts`
- `src/canonical/index.ts`
- 任何新的规范说明文档

### 可以分配给子 Session / Agent 的局部文件

下面这些文件适合并行：

- `playground/docs/pages/*.vue`
- `src/components/<Component>/*`
- `src/canonical/<Component>.vue`
- 与当前组件直接对应的测试文件

前提是不同 Agent 的写入范围不重叠。

## 并行工作的标准流程

1. 主 Session 先确定本轮结构决策。
2. 主 Session 把任务拆成互不重叠的写入范围。
3. 子 Session / Agent 只修改自己负责的局部文件。
4. 子 Session / Agent 返回时，必须说明：
   - 改了哪些文件
   - 哪些共享文件还需要主线程接线
   - 是否存在阻塞或未验证项
5. 主 Session 最后统一处理共享文件、文档同步和全量验证。

## 禁止事项

1. 不要让两个 Session 同时修改同一个共享总线文件。
2. 不要让两个 Session 同时定义同一个组件页的信息架构。
3. 不要让子 Session 直接更新 handoff，然后主线程又按旧结论继续工作。
4. 不要把局部 `pnpm test` 通过，当成全局规范已稳定。
5. 不要让一个 Session 继续按照过期审计结论修复已经完成的问题。

## 结构变更的落地要求

只要涉及下面任一项，就必须由主 Session 统一落地：

- 新增一级 docs page
- 修改导航结构
- 修改 capability page 的归并关系
- 修改 public exports
- 修改 Figma-first registry
- 更新“缺页 / 风险 / 优先级”类审计结论

## 新 Session 的启动要求

新 Session 在继续前，必须先读：

- `docs/session-handoff.md`
- `docs/multi-session-collaboration-rules.md`
- 当前阶段相关的 audit / provenance / conformance 文档

如果 handoff 与实际代码不一致，优先修文档同步，再继续开发。

## Session Handoff Protocol

> 任何 session 结束时**留下未完成工作**（用户主动暂停 / 阶段切换 / context window 满 / 跨日），必须写一份 handoff 文件，供下个 session 直接接上。

### 何时必须写

满足任一条 → 必须写 handoff：

- 用户说"先收尾" / "下个 session 继续" / "存一下"等明确暂停信号
- 当前对话已产出 ≥ 3 个结构性升级（与触发器 D 复盘门槛同）
- 已完成阶段子任务，下个阶段不在本 session 做
- 多日跨越（隔日不算结束 session 也建议落一份）

### Handoff 文件归属

| 任务性质 | 落到哪 |
|---|---|
| **设计系统库本身**的工作（component / variable / 规则修改） | `tvu-design-system/docs/session-handoff.md` |
| **产品消费 TVU 库**的工作（mockup / 产品代码 / 产品决策） | `{Product}/docs/handoffs/{YYYY-MM-DD}-{topic}.md` |
| **跨产品 / 跨仓库**协作 | 主仓库放主 handoff + 各 sub-handoff 链接到主 |

### Handoff 必须包含的段（顺序固定）

```markdown
# Session Handoff — {YYYY-MM-DD}

## 起手必读（按顺序）
[新 session 起手要读的文件路径，绝对路径或相对真源路径，按读取顺序排]

## 上个 Session 已完成
### {模块 / 维度 1}
[具体清单，逐条可验证]
### {模块 / 维度 2}
...

## 本 Session 待做
### 🟢 P0 [优先级]
| # | 操作 | 落到哪 | 价值 |
[每条必须有：操作内容 / 文件路径 / 为什么做]
### 🟡 P1
### 🔵 P2

## 验证锚点
[新 session AI 必须答出的事实题。答不出 → 没真读规则，重读]
1. ...
2. ...
```

### 验证锚点段的设计标准

验证锚点必须是：

- **事实题**（有唯一正确答案），不是开放讨论题
- **来自已读文件**（如果 AI 答错，说明没读）
- **3-5 条**（少了不严，多了浪费）
- **覆盖关键 trap**（如本次 retrospection 暴露的同名库陷阱）

### 反模式

- ❌ Handoff 只列任务，不列已完成（新 session 重做已完成的工作）
- ❌ Handoff 不列必读文件（新 session 凭直觉开工，重蹈覆辙）
- ❌ Handoff 无验证锚点（无法判断新 session 是否真 onboard）
- ❌ 必读文件路径用相对 cwd 不能确定的路径（如 `../foo.md`，新 session cwd 不同就找不到）
- ❌ Handoff 写在 chat 里没落仓库（关 session 就丢）

### 实证

- `MicroApps Console/docs/handoffs/2026-05-11-next-session.md` —— 第一份按本协议产出的 handoff，结合 `retrospection/2026-05-11-library-key-confusion.md` 用

## 最终验收规则

只有主 Session 可以给出本轮最终状态，且必须同时满足：

- 共享文件已同步
- handoff 已更新
- 必要审计结论已更新
- `pnpm build` 通过
- `pnpm test` 通过

如果只完成了局部组件实现，应明确标记为“局部完成，待主线程合并验证”。