mnote/design/10-review/reference/mnote-dev-squad-protocol-v1.md

[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 或更强模型。

目录约定

每轮协作创建：

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

模板位于：

/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，例如：

/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，不直接硬删。

推荐：

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

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