# [reference] mnote-dev-squad 协作协议 v1

## 目的

把 mnote 开发固定为一个轻量协作组：Hermes 主控，多个 Codex worker 在独立 worktree 实现，Reasonix flash 做真实浏览器 smoke，每个环节都用 Markdown 交接。

本协议不使用 Codex harness；不允许多个写入型 agent 同时改同一个 checkout。

## 角色

### Hermes 主控

- 读取 mnote 当前设计与 AGENTS.md。
- 拆分任务 lane。
- 创建 run 目录与 task/result/smoke/review Markdown。
- 创建或指定 Codex worktree。
- 启动/观察 Codex worker。
- 启动 Reasonix smoke。
- 阅读 RESULT.md、SMOKE.md、git diff 后做合并裁决。

### Codex worker

- 一个 worker 只负责一个 lane。
- 一个 worker 只在自己的 worktree 中写入。
- 默认不提交、不推送、不改允许范围外文件。
- 必须输出 RESULT.md。

### Reasonix smoke tester

- 默认使用 Reasonix flash。
- 负责真实浏览器 smoke、截图、console、final URL、可见文本证据。
- 默认不改代码。
- 必须输出 SMOKE.md。

### Reviewer / 仲裁

- 默认由 Hermes + 主控 Codex完成。
- 有争议时升级到 gpt-5.5 或更强模型。

## 目录约定

每轮协作创建：

```text
/mnt/Data1T/mnote/tmp/agent-runs/<run-id>/
  PLAN.md
  codex-<lane>/TASK.md
  codex-<lane>/RESULT.md
  smoke/SMOKE.md
  REVIEW.md
```

模板位于：

```text
/mnt/Data1T/mnote/.agent-templates/task.md
/mnt/Data1T/mnote/.agent-templates/result.md
/mnt/Data1T/mnote/.agent-templates/smoke.md
/mnt/Data1T/mnote/.agent-templates/review.md
```

## Worktree 约定

Codex worker 使用独立 worktree，例如：

```text
/mnt/Data1T/mnote-wt-<lane>-<YYYYMMDD-HHMM>
```

推荐 lane：

- `rust-kernel`
- `mnote-web`
- `tree-domain`
- `editor-interaction`
- `onlyoffice`
- `ai-runtime`
- `docs-review`
- `qa-smoke`

## Ownership 规则

每个 TASK.md 必须写清：

- 允许修改范围
- 禁止修改范围
- 验收命令
- 交付物路径

若两个 lane 需要改同一个核心文件，必须停下来由 Hermes 重新拆分或指定唯一 owner。

## 交付标准

Codex worker 完成不等于可合并。可合并必须满足：

1. RESULT.md 存在。
2. 修改文件符合 ownership。
3. 验证命令已执行或明确说明阻塞原因。
4. Reasonix smoke 已完成，或明确说明该任务不需要浏览器 smoke。
5. Hermes / reviewer 已读 diff。

## Smoke 标准

涉及 UI、文档页、编辑器、树、拖拽、选择、hover、click、快捷键等，SMOKE.md 必须包含：

- 测试 URL / 环境
- 浏览器动作
- final URL
- screenshot 路径
- console error 数量
- PASS / FAIL
- 问题与复现步骤

块编辑器验收中，hover / click / drag / select 是强制步骤；缺任一步只能算未完成验收。

## 升级规则

升级到 gpt-5.5 / 主控 Codex 深度复核的情况：

- Reasonix smoke 与 Codex 结论冲突。
- smoke evidence 不足。
- 失败原因涉及架构边界。
- 涉及 AGENTS.md 中的长期方向判断。
- 需要合并多个 worktree 的重叠改动。

## 回收规则

旧 worktree、失败 worktree、临时实验目录优先软删除到 recycle，不直接硬删。

推荐：

```text
/mnt/Data1T/recycle/<reason>-<timestamp>/
```

保留 MANIFEST 或 README，说明来源与恢复方法。