mstar-branch-worktree

name

mstar-branch-worktree

description

Morning Star business-repo Git feature branches, worktree isolation layers **L1** (iteration cross-plan — control worktree + per-plan feature worktrees + `execution_lease`; under default gitignore, process harness SSOT via absolute control paths — plans/iterations/status/sdd — while product edits stay on the feature worktree; do not waive worktree because feature lacks plans) and **L2** (within-plan — `references/parallel-writable-pre-dispatch.md`; N parallel Task invokes do NOT satisfy isolation), plan/Spec integration branches, and QC/QA checkout alignment (`Review cwd`, `Working branch`, `plan_id`, `Review range` / `Diff basis` must match verbatim across three QC reviewers and QA). Read when PM writes `Working branch` / `Branch policy`, iteration Phase 2 control vs feature worktree paths, dispatches ≥2 concurrent writable implement tracks on one repo, `Worktree isolation: required`, two or more writable streams touch one repo, dispatching QC tri-review or QA after merging to a single `HEAD`, dev/QA/ops before first `git commit`, or explaining worktree paths. Required for `project-manager` parallel implement or pre-QC orchestration; `fullstack-dev*` / `frontend-dev` / `qa-engineer` / `ops-engineer` on repo writes; `qc-specialist*` before review. Does not replace the state machine (`mstar-harness-core`).

Load order（必读顺序）

首次 Read 本 skill 前：必须先 Read mstar-harness-core（SKILL.md）。 冲突时 以 mstar-harness-core 为准。

Spec 多 plan 命名（iteration_base_branch、spec_integration_branch、target_branch PR 门禁）→ mstar-plan-conventions。L1/L2 worktree 分层（迭代 control vs feature、plan 内并行轨）→ 下文 「Worktree isolation layers」；L2 同仓并行可写派发前清单 → references/parallel-writable-pre-dispatch.md；迭代 lease claim/merge 细则 → mstar-iteration references/phase-2-worktree-lease.md（勿在本 skill 重复完整协议表）。下文为分支与 QC/QA 检出对齐主文。

Scope（摘要）

• 仅 PM 决定分支；其他可写角色不得自行新开分支或切回 main。
• Assignment 须含其一：Working branch: <existing> | create <new> from <base> | Branch policy: direct on <branch> — <reason>。
• L1（跨 plan / 迭代 Phase 2）：control worktree（metadata.control_worktree_path，检出 spec_integration_branch）+ 每 plan 独立 feature worktree（execution_lease.worktree_path ≠ control 路径）+ lease；见 「Worktree isolation layers」。
• L2（同 plan 内 ≥2 可写并发）：派发 前 完成 references/parallel-writable-pre-dispatch.md（含 git worktree、绝对 Worktree path；N 次并行 invoke ≠ 已隔离）。单 plan 多轨时 L1 不替代 L2。
• QC/QA 前：待审提交归并到 单一 Working branch HEAD；三审 + QA 共用一套 Review cwd + plan_id + Review range / Diff basis（逐字相同）。

Git 功能分支、同仓并发与 Worktree 对齐

Git 功能分支门禁（业务仓库）

适用于 cwd 为 Git 托管的业务/应用仓库 且本轮会产生仓库内可合并 diff 的任务（代码、业务向测试与 fixture、影响构建或运行时的配置等）。不用于约束 ~/.config/opencode/ 全局配置目录（该目录对 agent 只读；落盘仅由用户执行）。

默认规则

• 不得在默认保护分支（常见名：main、master；以项目约定为准）上直接实现功能改动，除非 Assignment 含显式例外。
• 例外须在 Assignment 中写明一行：Branch policy: direct on <branch> — <reason>（典型：团队约定的热修直接打默认分支）。

<base> 与叠分支（stacked branches）

• 门禁的目标是不在未授权的默认分支上直接提交，不是「只能从 main 开新分支」。
• 当需要从已有功能分支继续拆新分支时，Assignment 应写清祖先分支 <base>，例如：create feature/foo-part2 from feature/foo。
• <base> 可取：main / master（或项目默认分支名）、任意已存在的 feature/* / fix/*、远程跟踪分支名、或 current（表示以执行者检出时的 HEAD 为祖先，用于「就在当前分支上再拉一枝」）。
• 若只写 Working branch: feature/foo且无「create … from …」：表示沿用 / 切到该已存在分支上开发，不要求新建。
• 若写新建但未写 <base>：实现侧应停下问 project-manager（或按项目 AGENTS.md 的默认 base）；禁止擅自假设「一定是 main」。

角色职责

• project-manager（唯一分支决策入口）：向 product-manager（向项目仓库提交产品文档时）、architect（向项目仓库提交技术/架构/契约类文档时）、fullstack-dev / frontend-dev / fullstack-dev-2、以及会向仓库提交工件的 qa-engineer、会改仓库内文件的 ops-engineer、对项目仓库落盘的 prompt-engineer 分派前，核对分支策略；在 Assignment 中写明 Working branch（沿用已有分支名，或 create <new-branch> from <base>，其中 <base> 遵守上一节）。若用户已指定分支/祖先，照抄进 Assignment。只有 project-manager 可以决定是否新开分支、从哪个 <base> 开分支。
• 实现 / QA / 运维 / prompt / product-manager / architect（项目侧）：在首次编辑仓库内文件或执行 git commit 前，核对当前分支与 Assignment，并在回报中明确"正在哪个分支上工作"。**禁止自行决定新开分支、禁止自行切回 main/master 重开分支。**若未授权 Branch policy 且当前在默认分支，则仅可按 PM 已写明的 Working branch 执行切换/开枝；若 Assignment 未写清或与现场分支不一致，先回报 project-manager，不得擅自处理。

分支协作契约（Branch Collaboration Contract）

适用范围

• 当任务会在项目 Git 仓库产生可合并 diff 时适用。
• 适用于 project-manager、product-manager、architect、fullstack-dev、frontend-dev、fullstack-dev-2、qa-engineer、ops-engineer、prompt-engineer（项目侧写入）。

唯一分支决策者

• 只有 project-manager 可以决定分支策略：
  • 继续在现有分支开发，或
  • 使用 create <new-branch> from <base> 新开分支，或
  • 使用 Branch policy: direct on <branch> — <reason>。
• 其他可写角色不得自行决定开分支。

PM 必须先与用户确认

在派发实现任务前，PM 必须先检查当前分支；若已在非默认开发分支（如 feature/*、fix/*），必须先与用户确认。

未获得用户明确确认前，PM 不得切回 main/master 并新开分支。

PM 确认话术模板

面向用户沟通时，使用以下结构：

当前检测到在分支：`<current-branch>`。
请确认本次任务是：
1) 继续在 `<<current-branch>>` 上开发
2) 新开分支：`<new-branch>`，基于 `<base-branch>`

未确认前，我不会切回 `main`/`master` 或新开分支。

Assignment 要求（PM）

每个可写 Assignment 必须且只能包含以下之一：

• Working branch: <existing-branch>
• Working branch: create <new-branch> from <base>
• Branch policy: direct on <branch> — <reason>

若是新开分支但缺少 <base>，必须暂停并向用户澄清，不能猜测。

可写角色执行规则

在首次写仓库或 commit 之前：

1. 校验当前分支与 Assignment 是否一致。
2. 只能执行 PM 在 Assignment 中定义的分支策略。
3. 禁止自行切回 main/master 再重开分支流程。
4. 若 Assignment 含糊或与本地分支状态冲突，先停下并回报 PM。

回报要求

可写角色在 Completion Report 中必须明确当前工作分支，例如：

• Working branch used: <branch-name>

Worktree isolation layers (L1 vs L2)

Two complementary worktree isolation layers coexist. Do not conflate them with SDD review layers (L1–L4 in mstar-review-qc/references/review-responsibility-boundaries.md).

Layer	Scope	When	Mechanism
L1	Cross-plan (iteration Phase 2)	Multiple plans may implement concurrently in one iteration	Control worktree + per-plan feature worktrees + plans[].execution_lease
L2	Within-plan	Same plan_id, same business repo, ≥2 concurrent writable implement tracks	references/parallel-writable-pre-dispatch.md — distinct absolute Worktree path per track

Stacking rules

• Default L1 capacity is one writable track per plan. If one plan runs ≥2 concurrent writable tracks, each track also satisfies L2; L1 does not replace L2.
• L1 applies under iteration commands with Phase 2 control-worktree defaults (unless explicit Worktree mode: waived this turn). Single-plan waves without iteration leases still require L2 when ≥2 parallel writable tracks share one repo.
• Cross-plan integration merge into spec_integration_branch remains serial (metadata.integration_merge_lease) even when L1 feature implementation runs in parallel.

Control worktree vs feature worktree (iteration / L1)

Established at iteration Phase 2 entry (Phase 1 Review & Edit may stay on the primary checkout). Normative field names and claim/release/merge protocol → mstar-iteration references/phase-2-worktree-lease.md and maintenance ADR 2026-07-22-iteration-worktree-plan-lease.md. Do not invent alternate lease field names in this skill.

Worktree role	Checked-out branch	Path recorded in status.json	Writable product edits
Control worktree	Resolved spec_integration_branch (same across active plans)	metadata.control_worktree_path — canonical repository root (not {HARNESS_DIR})	Forbidden — harness coordination SSOT + serial integration merge only
Feature worktree (per plan)	Plan Working branch / feature branch from integration	plans[].execution_lease.worktree_path	Required cwd for that plan's product/source edits

Harness path SSOT under default gitignore (L1)

Default process artifacts (plans/, iterations/, status.json, sdd/, notes.json, archived/) are gitignored (mstar-plan-conventions「Git 跟踪策略」). git worktree add does not copy them into a new feature checkout. They live on the control worktree filesystem (the checkout of spec_integration_branch), not as Git blobs on that branch.

Path role	Resolve from
Control harness root	<control_worktree_path>/{HARNESS_DIR}/
Process / coordination SSOT (read + write)	Absolute under control harness root: status.json, plans/, iterations/, sdd/<plan-id>/, notes.json, archived/
Tracked results (AGENTS.md, knowledge/, specs/)	Available in any worktree via Git; absolute control paths in Assignment are still fine
Product / source edits	Feature worktree only (execution_lease.worktree_path)

Hard rules

• execution_lease.worktree_path MUST differ from metadata.control_worktree_path.
• A feature worktree's same-looking {HARNESS_DIR} path is not the SSOT — never treat it as the source of plans/status/SDD, and never bootstrap a second plans/status/SDD tree there.
• Absolute Worktree path (feature) MUST appear in the writable Assignment and in execution_lease.worktree_path before first writable implement dispatch for that plan.
• When L1 lease gate is active (not Worktree mode: waived), Assignment Plan Path and SDD dir MUST be absolute paths under the control harness root (not relative .mstar/... resolved from the feature cwd). Prefer also writing Control harness root: <control_worktree_path>/{HARNESS_DIR}.
• Writable dispatch for a plan requires a verified execution_lease (same read-check-replace-verify discipline as the iteration reference). Full claim tables are not duplicated here.

Anti-pattern (forbidden)

• Inferring Worktree mode: waived because “feature worktree has no plans” under default gitignore. Correct response: keep feature worktrees; route harness I/O through control absolute paths. Missing same-host write lock → Plan parallelism: serial only — that is a separate gate and does not waive worktree/lease.

Naming conventions (PM / ops; examples only — paths MUST be canonical absolute)

1. Control worktree — usually the primary checkout or a PM-designated path on spec_integration_branch; record once in metadata.control_worktree_path.
2. Feature worktree (per plan) — one distinct sibling directory per active plan_id, e.g. <repo-parent>/worktrees/<plan-id> or team .worktrees/<plan-id>; Assignment Worktree path must match lease worktree_path.
3. L2 track worktrees (within-plan) — additional distinct directories per parallel implement track under the same plan (see references/parallel-writable-pre-dispatch.md), each with its own PM-approved Working branch.

同仓并发写入与 Git worktree（强制）

首要场景是开发阶段（L2；迭代多 plan 时另见上文 L1）：多条可写流 并发 改 同一仓库 时，用 worktree 做 写入侧目录隔离。派发前清单 → references/parallel-writable-pre-dispatch.md。下列规则针对该类开发并发；QC / QA 阶段的检出约定见下一小节。

当 project-manager 在同一调度轮次内并发启动多个 subagent（含宿主侧「并行 Task / 并行 subagent」），且 ≥2 个承接方可能对 **同一 Git 仓库的同一工作区（同一 cwd 检出目录）**产生写文件或 git commit 级改动时：

• 必须为每条并发写流使用 独立检出目录：优先使用宿主原生 worktree/checkout 隔离能力；没有原生能力时使用 git worktree，并按本 skill 的目录、分支和 QC/QA 对齐规则执行。
• 必须与既有分支门禁一致：每个可写承接方的 Assignment 仍须含 PM 已批准的 Working branch / Branch policy；在某一 worktree 内 不得擅自 checkout 到未授权分支或私自新建分支。
• PM 须在 Assignment 中写清各并发写流的 检出约定（例如预期 Worktree path / 命名规则，或「由承接方创建/使用隔离 worktree 并在 Completion Report 回报路径」），避免多代理默认共享同一目录导致互相覆盖、冲突或半写入状态。
• 同仓、同一 plan、≥2 可写并行轨：派发各轨实现 Assignment 之前 确认 Branch policy 与 plan 集成分支 / topic 分支关系（见下节 「默认编排」），并完成 reference 清单中的 worktree 步骤。

可不强制新开 worktree 的情形包括：并发流 全部为只读；各写入者针对 不同 Git 仓库根；或写入 串行（同一时刻仅一个代理持有该仓工作区）。

并发 subagent 与同仓工作树（对齐）

当多个可写 subagent 并发修改 同一仓库 时，不得共用同一检出目录作为写入 cwd。PM 在分派前应规划 worktree/checkout 隔离，并在各承接方 Assignment 中写明 Working branch / Branch policy 及 检出路径约定（或要求回报实际 worktree 路径）。单分支决策权仍仅属 PM；worktree 只解决「目录与工作区隔离」，不替代分支授权。

同仓、同一 plan、多可写并行轨：挂齐各轨 worktree 之前 先确认 plan 集成分支与各轨 topic 分支及 merge 靶；QC 前归并到单一 Working branch HEAD。分步见下节 「默认编排」。

QC / QA 与 feature：开发常在 feature 分支的 worktree 中完成；进入 QC 三审与随后的 QA 验证时，PM 须在 Assignment 中写明 Review cwd / Worktree path、Working branch、plan_id（无 plan 流程时 N/A + 不可歧义 Feature / scope label）与 Review range / Diff basis；三份 QC Assignment 与 QA Assignment 中 plan_id 与 Review range / Diff basis 须逐字相同，保证三票审 同一 plan/feature 与同一 diff 范围。

多 worktree 并行开发与 QC / QA 的门禁衔接（强制；避免误派）

• 语义区分（必须理解）：开发阶段可以存在 多个 Worktree path（每条约流一条检出目录）；一轮正式 QC 三审及与之 逐字对齐 的 QA 验证，在 harness 中仍只对应 一套 Review cwd / Worktree path + Working branch + Review range / Diff basis（三票 QC 与 QA 共用且逐字相同）。不要把「多个开发 worktree」误解成「QC 应轮流进多个目录各审一半」。
• 默认编排：先建 plan 集成分支，再挂各 worktree（PM）：在 同仓、同一 plan 且 ≥2 条可写并行轨 时，按下列顺序编排可最大幅度降低 QC/QA 误用单一开发目录的风险。不是唯一合法 Git 拓扑；若采用其它拓扑，仍须满足本节下文 强制条款（派发前 worktree 隔离 + 派 QC 前 单一待审 HEAD + 一套对齐字段）。
  1. 先起集成分支（再挂 worktree）：在派发各轨 实现 Assignment 之前，PM 与用户确认 Branch policy，并建立 plan 集成分支（Assignment 使用 Working branch: create <plan-integration-branch> from <base> 或等价明确写法；<base> 必须是 PM 明确记录的 base，例如 root metadata.iteration_base_branch、现有 feature 分支、远程跟踪分支或团队既定主线，不得未授权假设）。分支名由 PM 指定；下文 feature/<plan-id>-integrate、integrate/<plan-id> 仅为命名示例，非强制。多 plan_id 同源一条 primary_spec（Spec 文档）时：该集成分支在计划语义上即 Spec 集成分支；各 Plan 的 feature 线 merge 回此线，全部 Plans 完成后 向显式 target_branch 走 PR（见 mstar-plan-conventions SKILL.md「Spec 驱动的分支模型」）。
  2. 再挂各轨 worktree：为每条并行轨分配 独立 git worktree + Worktree path；各轨 Working branch 一般为 从集成分支出 的 topic 分支（create <topic-i> from <plan-integration-branch>）或 PM 书面约定的等价结构（例如从同一 <base> 出 topic、但 书面指定 合并时 以集成分支为靶）。禁止承接方擅自把未授权功能提交直接堆在 main/master。
  3. 进 QC 之前：将全部 须同一轮三审覆盖 的提交 merge / rebase / cherry-pick（以 PM 指定的团队方式）归并到 同一条 PM 将作为 QC Working branch 的分支的 HEAD（通常即 plan 集成分支；若 PM 已将集成分支重命名或快进为最终 feature/*，以 Assignment 为准）。在此解决冲突；勿在 QC Assignment 仍指向「只含部分轨」的旧 HEAD 时派三审。
  4. QC / QA 的 Working branch 与合并主线：派发 QC 三审与对齐的 QA 时，Working branch 即为上一步 已含全部待审提交 的那条分支（常见为 plan 集成分支）。Review range / Diff basis 通常相对 尚未合并 feature 的显式目标或 base 参照（例如 merge-base: <target_branch-or-base-ref> + tip: HEAD），审查的是 「feature 线 vs 目标线」 的差异；默认不要求在 QC 通过前 已把该分支 merge 进目标分支（除非 Branch policy 或用户明确约定 trunk 式例外）。
  5. 本推荐不适用时：单轨、多仓库、或 plan 已 拆 scope / 多轮增量三审（见 mstar-plan-conventions）— 仍须 逐轮满足 强制条款：每轮 QC 对应 一条快照、一套逐字相同的 plan_id + Review range / Diff basis。
• 单一待审 Git 快照（派 QC 前置条件）：若本 plan 下曾有多条 可写 并行轨落在 同一业务仓 且其成果分布在 不同分支、或 未互相合并进同一条分支的 HEAD，则在派发 QC 三审（及同范围的 QA）之前，必须先在 Git 中完成 归并（merge / rebase / 按团队约定的集成方式），使 全部待审提交都出现在 同一条 PM 指定的 Working branch 的 HEAD 上；然后再填写 一个 Review cwd（可为该分支上新开的只读审查 worktree）与 一个 可复现的 Review range / Diff basis。禁止仅填写并行轨 A 的开发用 Worktree path 作为 Review cwd，却期望审查覆盖仍只存在于并行轨 B 的分支或提交上的变更（在该变更 未进入 轨 A 所检出分支的 HEAD 时，这在 Git 上不可复现，属 Assignment 错误）。
• 不应合并为一次审时的做法：若两轨 有意保持独立可合并单元（例如两条独立 PR），不得共用 同一套 plan_id + Review range / Diff basis 假装「一轮三审覆盖全部」。应 拆分 scope：分轮次审查、不同 Feature / scope label、不同 plan_id、或按 mstar-plan-conventions 写明的 显式增量三审 例外，使每轮 QC 各对应 一条分支快照与 一套对齐字段。
• 同分支多目录的例外：若所有并行轨 始终在同一条已授权的 Working branch 上协作（每流仅目录不同、提交已互相 pull/推送收敛），则任一该分支的检出目录在 更新到含全部提交的 HEAD 后，均可作为 Review cwd；不得使用仍停留在旧提交的 worktree 路径。

QC 三审、QA 验证与 feature 检出上下文（强制）

开发在 feature 分支上完成（往往在 独立 worktree 中实现）后，QC 审查与 QA 验证针对的都是这份 feature，而不是 main 或任意未对齐的默认 cwd。

• project-manager 分派 QC 时须在 Assignment 写明与待审实现一致的 Working branch，并写明 Review cwd / Worktree path：优先沿用开发 Completion Report 中回报的业务仓 实现检出路径（即「该 feature 的 worktree」）当且仅当该路径上的检出分支 HEAD 已包含本轮待审的全部提交（含曾发生在其他并行 worktree、现已归并到该分支的变更）。否则 必须改用 集成完成后的 Working branch 与对应检出路径（或在该分支上 另开 审查专用 worktree）。若开发未用 worktree，则写明单一明确的业务仓根路径。若审查需与开发目录 物理分离 但仍审 同一分支，可指示在 Working branch 上 另加 一个 worktree 专供审查（只读使用业务仓）。多流并行开发时的前置归并、推荐默认编排（plan 集成分支先行） 与误派禁令见上一小节。
• 三票审同一功能（强制对齐）：分派 QC 三审时，除上述字段外，必须在 三份 Assignment 中逐字写入相同的 plan_id 与 Review range / Diff basis：
  • plan_id：与 {SDD_DIR} 的 <plan-id> 段、主 Plan Path、status.json.plans[].id 一致；无 {PLAN_DIR} 流程时写 plan_id: N/A，并另给一行 Feature / scope label（不可歧义，足以与并行其它 feature 区分）。
  • Review range / Diff basis：明确本次审查所针对的 diff/提交范围（例如 merge-base: <target_branch-or-base-ref> + tip: HEAD；或 rev-range: <full-40>..<full-40>；或一句 equivalent to: git diff <merge-base>...HEAD，以团队可复现为准）。三名 reviewer 的 Assignment 间该字段必须完全一致；qa-engineer 验证同一 feature 时 复用同一 plan_id 与同一 Review range / Diff basis。热修 / QC 单审路径也须含 同一组字段，仅承接方份数为 1。
• 三审并行时，三名 reviewer 共用同一组 Review cwd / Worktree path + Working branch + plan_id + Review range / Diff basis（对业务仓只读分析）；一般不必为每位 reviewer 各开一个 worktree，除非宿主或执行环境要求进程级隔离。
• QC 的 报告落盘默认仅限 Assignment 指定的 {SDD_DIR}/review/；上述约定保证 git diff、git log、lint 与所读文件与 待合并 feature 一致。PM 另行提交主 plan gate summary / status.json residual changes as durable artifacts.
• project-manager 分派 qa-engineer 时（仅 QA gate: mandatory），Assignment 须与 QC 逐字相同的 Review cwd / Worktree path、Working branch、plan_id、Review range / Diff basis（QC 已写清则 QA 照抄）。qa-engineer 执行业务仓命令前须核对检出与分支；Report-only 且无路径依赖时，回报须说明验证环境，否则 Blocked。
• 若 QA 与同仓其他可写角色并发提交测试代码，仍须遵守上文「同仓并发写入」的 worktree 规则（可为 QA 单开一条写入 worktree，同一 Working branch，由 PM 在 Assignment 写明）。

派发前清单与常见反模式 → references/parallel-writable-pre-dispatch.md。