mstar-branch-worktree

Files (2)

• SKILL.md
• parallel-writable-pre-dispatch.md · references/

SKILL.md (first lines)

## Load order（必读顺序）

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

Spec branch naming → mstar-conventions. L1/L2 checkout isolation → Worktree isolation layers below; L2 pre-dispatch → references/parallel-writable-pre-dispatch.md. Ordinary source metadata, coordinator operations and actual serial integration → mstar-iteration/references/phase-2-worktree-lease.md. Cleanup ownership/merge/refusal rules remain solely in Worktree / branch cleanup below; no per-row claim protocol.

## Scope（摘要）

- **仅 PM 决定分支**；其他可写角色不得自行新开分支或切回 `main`。
- **Assignment 须含其一**：`Working branch: <existing>` | `create <new> from <base>` | `Branch policy: direct on <branch> — <reason>`。
- **L1:** Git-derived main/control root + separate recorded integration checkout + distinct row metadata.worktree_path/source branch. Atomic coordination and serial integration remain; no per-row execution lease.
- **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 确认话术模板

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

```markdown
当前检测到在分支：`<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 含 `Worktree path`，先 `cd` 到该目录，并通过 `git rev-parse --show-toplevel` 校验当前检出根目录与该路径一致；不一致则停下并回报 PM，不得写入。分支校验必须在该目录内进行，避免在 primary checkout 上校验分支而误报冲突。
2. 在上一步校验过的检出目录内校验当前分支与 Assignment 是否一致。
3. 只能执行 PM 在 Assignment 中定义的分支策略。
4. 禁止自行切回 `main`/`master` 再重开分支流程。
5. 若 Assignment 含糊或与本地分支状态冲突，先停下并回报 PM。
6. 提交仅用已配置身份；身份缺失或失败则 **Blocked**，不得编造或用 `-c` 覆盖身份 → `mstar-roles/references/_shared/leaf-executor-core.md`「Git NEVER (repo writes)」。

### 回报要求

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

- `Working branch used: <branch-name>`
- 若 Assignment 含 `Worktree path`，还须明确实际使用的绝对检出路径：`Worktree path used: <absolute>`。

## 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) | Ready rows implement concurrently | **Main-worktree control root** (process SSOT) + **integration worktree** (`integration_worktree_path`) + distinct **feature worktrees** from ordinary row source metadata; atomic coordination |
| **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 to iteration Phase 2 source/integration isolation unless an explicit applicable `Worktree mode: waived` exception exists. Any single-plan wave with multiple writable tracks still satisfies L2; source metadata, not a per-row lease, supplies row checkout facts.
- Cross-plan **integration merge** into `spec_integration_branch` remains **serial** (store.db `execution_integration_leases`) even when L1 feature implementation runs in parallel.

### Main-worktree control root, integration worktree, feature worktree (iteration / L1)

The integration checkout is established at Phase 2 entry; the bounded Phase 1 uncommitted-document exception does not switch main. Source metadata and direct completion procedure → `mstar-iteration/references/phase-2-worktree-lease.md`; field semantics → `mstar-artifacts`. No per-plan claim/bind protocol.

From btspoony/mstar-harness, MIT.

More from btspoony/mstar-harness