fleur-worktree

Fleur Worktree

当同一个 fleur 仓库需要同时推进多个 Codex/agent 任务时，使用这个 skill。目标是一任务一 worktree、一任务一分支、一套明确验证和清理规则，避免 agent 互相踩文件、共享运行时状态或把未完成分支混入主工作区。

依据

• OpenAI Codex app 公开材料强调并行 agent、内置 worktrees、隔离环境和可审阅 diff。
• OpenAI harness engineering 文章提到让应用可按每个 Git worktree 启动，使 Codex 能为每个变更管理独立实例。
• Git 官方 git-worktree 文档定义了 add、list、remove、prune 等生命周期命令；清理 worktree 时优先用 Git 命令而不是直接删除目录。

原则

• 每个并行任务使用独立 worktree 和独立 branch。
• worktree 放在仓库外部的兄弟目录，不放进 fleur/ 内部。
• 不从脏工作区创建新任务，除非用户明确要求把当前未提交改动带过去。
• worktree 只隔离文件系统和 Git checkout，不隔离 S3、PostgreSQL、Dagster run storage、端口、后台进程或外部 API。
• 能串行就不伪装并行：两个任务会改同一模块、同一迁移、同一资产契约或同一运行状态时，指定 integrator 分支串行合并。
• 合并前必须在目标分支上重新验证；合并后必须清理 worktree 和 stale metadata。

布局

主仓库：

/storage/program/fleur

推荐 worktree 根目录：

/storage/program/fleur-worktrees/

命名规则：

• worktree 目录：<yyyymmdd>-<short-task>
• branch：codex/<yyyymmdd>-<short-task>
• slug 只用小写字母、数字和 -。

示例：

/storage/program/fleur-worktrees/20260531-scheduler-runner
branch: codex/20260531-scheduler-runner

创建流程

在主仓库或任意干净 worktree 中执行：

git status --short
git worktree list
git fetch --all --prune

mkdir -p ../fleur-worktrees
git worktree add -b codex/20260531-topic ../fleur-worktrees/20260531-topic HEAD

如果要基于远端主线创建，先确认默认分支名，再显式指定：

git branch --show-current
git worktree add -b codex/20260531-topic ../fleur-worktrees/20260531-topic origin/main

进入新 worktree 后先同步依赖：

cd ../fleur-worktrees/20260531-topic/pipeline
uv sync --all-packages --all-groups

环境隔离

.env 不提交。需要运行本地命令时，按任务选择：

• 只做文档、静态代码、单测：通常不需要复制 .env。
• 需要访问同一套外部 S3/PostgreSQL/API：可以复制或软链接 .env，但必须确认任务不会写入生产或共享状态。
• 需要并行运行 Dagster、服务或数据库相关任务：不要共享 DAGSTER_HOME、端口、临时目录或本地数据库 schema。

Dagster 运行建议：

• dg check defs、ruff、pyright、pytest 可在 feature worktree 内运行。
• 物化、回填、OCR、外部 API 写入类任务默认不要从普通 feature worktree 执行。
• 如果确实要在 worktree 中运行 Dagster，使用该 worktree 自己的 .dagster，并在命令前显式设置 DAGSTER_HOME="$PWD/.dagster"。
• 任何涉及真实 S3/PostgreSQL 写入的操作，先使用 docs/skills/fleur-dagster-backfill-runbook/SKILL.md 判断是否应该切回主工作区或专用 ops worktree。