# Lane Worktree 物化与代码流转改造计划

本文档定义 `inbox v2` 中 `lane -> worktree -> runtime` 的代码流转改造方案。

目标很明确：

- 保留 `lane` 级隔离执行能力
- 让下游 `lane` 能消费上游 `lane` 的真实代码产物
- 避免 worker summary 充当“伪代码同步”
- 逐步把当前执行模型修正为“依赖图 = 代码图”

本文档按阶段拆分，便于逐步实现和回归。

## 背景

当前系统已经把术语统一到 `lane`，但运行时还存在一个关键缺口：

- `leader` 规划出 task DAG
- 系统按 task 依赖自动派生 execution lanes
- 每个 `lane` 都有独立 `worktree` 和 `podman` 容器
- 但跨 `lane` 的依赖目前只传递 worker summary，不传递代码

这会导致一个结果：

- 调度层认为 `Task B` 依赖 `Task A`
- 运行层却没有把 `Task A` 的代码产物同步给 `Task B`
- `Task B` 只能在自己的空 worktree 里“重建”上游结果

这不是真正的依赖执行，而是“读摘要后重写”。

## 真实问题示例：`todo-lane-smoke-2`

`todo-lane-smoke-2` 的 task 图如下：

1. `Scaffold full-stack project structure`
2. `Implement Todo API with SQLite`
3. `Implement React Todo UI`
4. `Integrate stack and verify runnable demo`
5. `Todo demo ready for review`

其依赖关系如下：

- `Scaffold full-stack project structure`：根任务
- `Implement Todo API with SQLite`：依赖 `Scaffold`
- `Implement React Todo UI`：依赖 `Scaffold`
- `Integrate stack and verify runnable demo`：依赖 `Backend API` + `Frontend App`
- `Todo demo ready for review`：依赖 `Integrate`

当前系统会把它派生成 4 条 execution lanes：

- `Foundation Setup`
- `Backend API`
- `Frontend App`
- `Integration And Verification`

问题在于：

- `Backend API` 和 `Frontend App` 在各自 worktree 中写代码
- `Integration And Verification` 也在自己的 worktree 中执行
- 但它拿不到前两个 lane 的真实代码，只能拿到消息摘要

这意味着 `Integration` 不是在“上游代码之上做集成”，而是在“读了两段总结之后重新拼代码”。

## 总目标

实施完成后，系统应满足以下条件：

- 每个代码型 `lane` 都有可复用的 git 产物，而不是只有未提交改动
- 下游 `lane` 启动前可以显式物化上游 `lane` 的代码输入
- `lane` 之间的依赖关系能在 git 历史中体现出来
- merge 冲突会显式阻塞执行，而不是被摘要绕过
- `milestone` / `gate` 不再滥用独立 worktree
- `lane` 是“代码演进线”，不是“任意 task 容器”

## 术语

本文统一使用以下术语：

- `lane`：执行泳道，代表一条相对连续的代码演进线
- `worktree`：该 `lane` 对应的 git 工作目录
- `runtime`：该 `lane` 对应的容器与 worker 进程
- `snapshot`：某个 `lane` 在成功完成代码任务后的已提交 git 状态
- `materialization`：将上游 `lane` 的代码输入同步到当前 `lane`

## 设计原则

### 1. 代码依赖必须用代码流转表达

只要下游 task 需要基于上游代码继续开发、联调、验证，就必须物化上游代码，而不是只传摘要。

### 2. lane 隔离要保留，但不能成为代码孤岛

`lane` 的价值是隔离并行开发，不是让每个 worker 在自己的平行宇宙里重写同一份实现。

### 3. 失败要显式

如果下游 lane 在物化上游代码时发生 merge 冲突，应显式标记 `blocked`，并触发 replan 或人工介入。

### 4. 优先 clean replacement，不做兼容分叉

不增加“新老同步方式同时存在”的运行时兼容逻辑。

应使用显式 schema / 数据迁移把新模型落下。

### 5. runtime 职责保持窄边界

- `workspaceruntime` 负责 ensure worktree / container
- `taskexec` 负责调度与状态推进
- git 产物提交与代码物化应放在单独模块中

不要把代码同步逻辑散落到 handler、runtime、leader prompt 中。

## 非目标

本计划不包含以下内容：

- 多机调度
- 远程仓库 push / pull
- GitHub / GitLab PR 集成
- 二进制产物仓库
- 通用 artifact storage
- 对历史旧 topic 的运行时兼容兜底

## 理想工作流

拿 `todo-lane-smoke-2` 举例，理想形态如下。

### Lane 拆分

保留 4 条 execution lanes，但语义要变：

1. `Foundation Setup lane`
   从 `main` 起步，产出基础脚手架代码快照。

2. `Backend API lane`
   从 `Foundation Setup` 的代码快照起步，负责后端与 SQLite。

3. `Frontend App lane`
   从 `Foundation Setup` 的代码快照起步，负责 React 前端。

4. `Integration And Verification lane`
   在开始执行前，先物化：
   - `Foundation Setup`
   - `Backend API`
   - `Frontend App`

   然后再做联调、启动脚本、验证、补丁修复。

5. `Todo demo ready for review`
   这是 `milestone`，不需要独立 worktree。

### Git 视角下的理想状态

- `Foundation Setup lane` 成功后，lane 分支上至少有一笔提交
- `Backend API lane` 成功后，lane 分支上至少有一笔提交
- `Frontend App lane` 成功后，lane 分支上至少有一笔提交
- `Integration` 开始前，自己的 branch 已显式 merge 上游分支

换句话说，`Integration` 看到的应该是：

- `foundation commit`
- `backend commit`
- `frontend commit`

而不是：

- “Backend worker 说自己完成了”
- “Frontend worker 说自己完成了”

## 当前缺口

### 缺口 1：代码没有被自动提交

当前 worker 执行成功后，代码通常还停留在未提交状态。

这会导致：

- 上游 `lane` 没有稳定的可消费产物
- 下游即使要 merge，也没有明确的输入 commit

### 缺口 2：下游 lane 没有物化步骤

当前 `taskexec` 在给 worker 分配任务前，不会把依赖 lanes 的代码同步进当前 lane。

### 缺口 3：merge_request 模型未接入执行主路径

系统里虽然有 `merge_requests` 表和 API，但当前并没有把它们接入 `leaderloop` / `taskexec` 的主执行链路。

### 缺口 4：lane 拆分策略过于宽松

当前 task DAG 会自动派生 lane，但不会约束：

- 哪些任务必须共用 lane
- 哪些任务值得独立 lane
- 哪些节点根本不需要独立 worktree

## 目标架构

建议引入两个新模块和一个新的持久化记录层。

### 模块 A：`lanesnapshot`

建议路径：

- `inbox/internal/app/lanesnapshot/`

职责：

- 检查 lane worktree 是否有代码变更
- 过滤不应纳入版本控制的运行时垃圾
- 生成 lane 的提交快照
- 把最新提交记录回 lane 元数据

它不负责：

- 分配任务
- merge 上游 lane
- 启动容器

### 模块 B：`lanematerialize`

建议路径：

- `inbox/internal/app/lanematerialize/`

职责：

- 根据 task 依赖关系识别当前 task 的上游 lanes
- 将上游 lane 的最新代码快照同步到当前 lane
- 记录 merge / 物化结果
- 冲突时产生结构化阻塞信息

它不负责：

- 选择哪个 task 该执行
- 自动 replan
- worker prompt 组装

### 模块 C：lane 同步记录

建议新增表：

- `lane_syncs`

建议字段：

- `id`
- `workspace_id`
- `topic_id`
- `downstream_lane_id`
- `upstream_lane_id`
- `task_id`
- `upstream_commit`
- `merge_commit`
- `status`
- `error_message`
- `created_at`
- `updated_at`

用途：

- 保证物化过程可观测
- 避免重复 merge 同一输入时缺乏依据
- 为 dashboard / 调试 / 重试提供基础数据

## 数据模型改造

### 阶段性最小变更

在现有 `lanes` 表上新增字段：

- `head_commit TEXT NOT NULL DEFAULT ''`

说明：

- 领域名词与底层表名现在都使用 `lane / lanes`
- 先在现有 `lanes` 表上扩字段，避免一次性大迁移

### 后续可选扩展

如需更强的可观测性，可继续新增：

- `last_materialized_at`
- `last_materialized_commit`
- `last_sync_error`

但这些不是第一阶段必需项。

## 关键执行点

### 1. 成功 task 完成后，自动生成 lane snapshot

建议接入点：

- `inbox/internal/app/taskexec/service.go`
- `Complete(...)` 主路径

顺序建议：

1. worker 返回成功
2. 宿主机确认 lane runtime 与 worktree 可访问
3. `lanesnapshot` 检查并提交 worktree 代码
4. 成功后才真正把 task 标成 `succeeded`
5. 如果提交失败，则这次 run 视为失败或阻塞

原因：

- 一旦 task 已被标成成功，但代码并未形成稳定快照，下游 lane 仍然无法消费
- 所以“成功完成 task”的定义应当包含“代码产物已稳定落盘到 git”

### 2. 下游 task 被 claim 前，先做 lane materialization

建议接入点：

- `inbox/internal/app/taskexec/service.go`
- `ClaimNext(...)` 主路径

顺序建议：

1. 找到当前 lane 中下一个 ready task
2. 识别其依赖 tasks
3. 推导依赖 tasks 所属的上游 lanes
4. `lanematerialize` 将上游 lane commits 同步到当前 lane
5. 同步成功后再真正 claim task
6. 如冲突，则不 claim，改为 `blocked`

原因：

- worker 启动时就应该处于“已拿到所有上游代码输入”的环境
- 不要把 merge 责任甩给 worker

### 3. `workspaceruntime` 不做业务同步

`workspaceruntime` 继续只负责：

- ensure repository
- ensure worktree
- ensure container
- stop container

不要把以下逻辑塞进去：

- 依赖 lanes 分析
- 自动 commit
- 自动 merge
- 冲突策略判断

## 推荐 merge 策略

第一版建议使用最朴素、最可审计的策略：

- 上游 lane 产物必须先成为 git commit
- 下游 lane 物化时使用显式 `git merge`
- 保留 merge commit，不做 squash

原因：

- 依赖关系能在历史中直接看见
- 调试时容易定位是哪条 lane 带进来的改动
- 比起复制文件或 patch 应用，git merge 更符合当前 worktree 模型

### 合并顺序

建议按依赖拓扑顺序进行 merge。

以 `Integration And Verification` 为例，建议顺序：

1. `Foundation Setup`
2. `Backend API`
3. `Frontend App`

如果 `Backend` 和 `Frontend` 都已经是从 `Foundation` 分化出来的，并且各自分支历史完整，也可以只 merge 最终两个分支，由 git 自动通过共同祖先处理基础提交。

第一版不要求做最优优化，要求的是语义正确和行为稳定。

### 冲突处理

发生冲突时：

- 停止当前 materialization
- 记录 `lane_syncs.status = failed`
- task 标记为 `blocked`
- lane 可标记为 `blocked`
- 通过 message 或 task event 通知 leader

不要做以下行为：

- 自动硬解冲突
- 静默 fallback 为“只读摘要继续执行”
- 自动丢弃上游改动

## lane 拆分策略建议

除了代码流转，lane 数量本身也要更收敛。

### 应当独立 lane 的情况

- 明确并行价值高
- 文件边界清晰
- 预期实现时间较长
- 失败隔离有意义
- 产物可以作为其他 lane 的明确输入

### 应当共用 lane 的情况

- 前后两个 task 本质上是同一条连续实现链
- 第二个 task 高度依赖第一个 task 的局部未抽象代码
- 拆开后只会制造频繁 merge 和冲突

### 不应拥有独立代码 lane 的情况

- `milestone`
- 纯 `gate`
- 单纯汇报 / 审阅 / 总结型节点

## 分阶段实施

### 阶段 0：基线梳理与命名统一

目标：

- 明确以 `lane` 为统一术语
- 建立当前缺口的自动化验证样例

实现内容：

- 文档统一使用 `lane`
- 为 `todo-lane-smoke-2` 这类场景补回归测试描述
- 梳理现有旧命名残留，不要求立刻全量改名

验收标准：

- 团队对外讨论统一使用 `lane`
- 有一份可复现“下游 lane 看不到上游代码”的基线案例

### 阶段 1：lane snapshot 落地

目标：

- 成功的代码型 task 必须沉淀为 lane 分支上的 commit

实现内容：

- 在 `lanes` 表新增 `head_commit`
- 新增 `lanesnapshot` 模块
- 在 task 成功完成路径中自动：
  - 检查 worktree dirty 状态
  - 执行 `git add`
  - 执行 `git commit`
  - 写回 `head_commit`

建议约束：

- 只对 `execution` / `verification` 这类代码型 task 做 snapshot
- `milestone` / `gate` 不生成代码提交

验收标准：

- `todo-lane-smoke-2` 中 `foundation` / `backend` / `frontend` 成功后，各自 lane 均有非空 `head_commit`
- worktree 不再只停留在未提交改动

### 阶段 2：下游 lane materialization

目标：

- 下游 lane 能在 worker 执行前拿到上游 lane 的真实代码输入

实现内容：

- 新增 `lanematerialize` 模块
- 新增 `lane_syncs` 表
- 在 `ClaimNext(...)` 中对 candidate task 执行 materialization
- materialization 成功后才 claim task

验收标准：

- `Integration And Verification` 在执行前能看到 `Backend API` 和 `Frontend App` 的真实代码
- 回归时不再依赖 worker summary 重建实现

### 阶段 3：阻塞与 replan 闭环

目标：

- merge 冲突成为受控状态，而不是隐性失败

实现内容：

- 统一 materialization failure 到 `blocked`
- 增加 task event / message，向 leader 报告冲突
- leader 收到冲突后走 patch replan

验收标准：

- 冲突 topic 会稳定停在 `blocked`
- leader 能基于冲突信息重新编排，而不是盲目新起 lanes

### 阶段 4：lane 拆分规则收紧

目标：

- 减少不必要的 lane / worktree / container 增生

实现内容：

- 调整 leader prompt 与 lane 派生规则
- 倾向于把连续实现链保留在同一 lane
- 仅在明确并行或集成汇聚点时拆新 lane
- `milestone` / `gate` 不派生代码 lane

验收标准：

- 类似 `todo-lane-smoke-2` 的 topic 中，lane 数量与实际代码边界一致
- 不再出现“为了一个收口任务额外生成空 lane”的情况

### 阶段 5：可观测性与回收策略

目标：

- 让 lane 运行时资源与代码同步状态都可追踪、可回收

实现内容：

- dashboard 展示：
  - `head_commit`
  - 最新 materialization 状态
  - lane sync 历史
- topic 完成后可选执行：
  - 停止 lane runtime
  - 延迟回收容器
  - 延迟清理 worktree

说明：

- 本阶段是运维优化，不阻塞前四阶段主路径落地

验收标准：

- topic 完成后不再长期残留无意义运行中的 lane runtime
- 调试时能直接看到 lane 的代码输入输出链路

## 需要修改的主要模块

### 必改

- `inbox/internal/app/taskexec/service.go`
- `inbox/internal/store/sqlite/taskexec_store.go`
- `inbox/internal/store/sqlite/migrations/`
- `inbox/internal/domain/lane/`

### 新增建议

- `inbox/internal/app/lanesnapshot/`
- `inbox/internal/app/lanematerialize/`
- `inbox/internal/domain/lanesync/`
- `inbox/internal/store/sqlite/lane_syncs_store.go`

### 暂不建议承载业务逻辑的模块

- `inbox/internal/app/workspaceruntime/`
- `inbox/internal/httpapi/`
- `inbox/internal/app/leaderloop/`

这些模块可以消费结果，不应承担主要 git 业务逻辑。

## 测试建议

### 单元测试

- snapshot 成功创建提交
- worktree 无变化时不重复提交
- materialization 能识别依赖 lanes
- materialization 在冲突时稳定失败并写入 `blocked`

### 集成测试

以 `todo-lane-smoke-2` 类型流程验证：

1. `Foundation Setup` 成功后生成 commit
2. `Backend API` / `Frontend App` 都从基础快照继续开发
3. `Integration` 在启动前合并上游代码
4. `milestone` 自动完成且不新建代码 lane

### 回归重点

- 不能破坏当前单 lane 串行执行
- 不能让 `gate` / `milestone` 意外触发 git commit
- 不能把未提交脏状态错误标记成“已可下游消费”

## 开放问题

### 1. 自动提交的粒度

第一版建议：

- 每个成功 task 最多生成一笔提交

不建议第一版支持：

- 一个 task 内自动切多笔提交

### 2. merge 粒度是按 task 还是按 lane

第一版建议按 `lane` 的最新成功快照物化。

原因：

- 实现简单
- 与当前 runtime 粒度一致
- 更符合“lane 是代码演进线”的模型

### 3. 是否必须使用 merge request 模型

第一版不必强制接入 `merge_requests`。

建议先把：

- 真实 commit 产物
- lane materialization
- 冲突阻塞

这三个核心闭环做完。

之后再决定是否把 `merge_requests` 升级成：

- lane 间同步记录
- 人工审批面板
- 最终 topic 合并机制

## 最小可上线版本

如果只做最小闭环，建议范围如下：

1. `lanes.head_commit`
2. 成功 task 后自动提交
3. `ClaimNext` 前 merge 上游 lane commits
4. merge 冲突时标记 `blocked`

做到这一步，系统就已经从“摘要依赖”升级成“代码依赖”。

## 结论

这次改造的本质，不是“再加一个 merge 功能”，而是修正整个 lane 执行模型的语义：

- 上游 `lane` 的产物应该是代码快照
- 下游 `lane` 的输入应该是上游代码状态
- worker summary 应回归为编排证据，而不是代码同步手段

对 `todo-lane-smoke-2` 这样的 DAG 来说，这不是优化，而是让系统终于按自己宣称的依赖关系去工作。