@mstar-harness/opencode 1.8.0 → 1.8.1

package/harness-commands/iteration-start.md

@@ -22,13 +22,13 @@ Start a new Morning Star harness iteration. **Not Done until the Review & Edit c
 
 **完成定义**：compass `status: locked` + 三角色 invoke 已返回 + pre-commit checklist 全 `[x]` — 不是初稿落盘。
 
-Detailed workflow → **`mstar-iteration` § Phase 1**（含 §1.6 Review & Edit chain）；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
+Detailed workflow → **`mstar-iteration` § Phase 1**；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
 
-**Path split（HARD）**：
+## Path split（HARD — 路由）
 
 | 宿主上下文 | 走哪条 |
 |------------|--------|
-| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → §P — **先**空白 CreatePlan，再 **feedback-driven** 自主改同一份 plan；grill-me **仅**在用户明确结束反馈后、仍有阻塞疑问时；**Build 前不执行** Review 链 / commit / integration 分支 |
+| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → **§P** — **先**空白 CreatePlan，再 **feedback-driven** 自主改同一份 plan；grill-me **仅**在用户明确结束反馈后、仍有阻塞疑问时；**Build 前不执行** Review 链 / commit / integration 分支 |
 | **其它**（Agent、OpenCode、非 Plan） | §0 Boot → §1–§6（Research → Explore → grill-me → Write → Review → branch） |
 
 ## 0. Boot
@@ -45,148 +45,24 @@ Detailed workflow → **`mstar-iteration` § Phase 1**（含 §1.6 Review & Edit
 
 ## P. Cursor Plan mode（Phase 1 scaffold → feedback loop → deferred grill → Build）
 
-**Detect**：会话处于 Cursor Plan mode（系统要求 CreatePlan / SwitchMode，或 Plan 工具可用且当前为 Plan 会话）。
+Execute **`mstar-host/references/cursor-plan-mode-bridge.md`** § **"mstar-iteration Phase 1 in Plan mode"**（Detect / 语义 / Single CreatePlan URI（HARD）/ Research → Early CreatePlan → Feedback loop → Feedback-close deferred grill → Pre-Build / Build 全流程 SSOT）。
 
-**语义**：Plan 模式期间 **只维护 CreatePlan + SSOT 草稿**；用户侧是 **纯反馈**（提方向 / 提意见），**不是**答问卷。Agent **探索 + 推荐并直接改 plan**。**不**派发 Review 链；**不** commit；**不**建 integration 分支。点 **Build** 后才执行下方 Build todos（对齐 `mstar-host/references/cursor-plan-mode-bridge.md` · Phase 1 in Plan mode）。
+Command-unique 补充（bridge 未枚举）：
 
-### P.0 Single CreatePlan URI（HARD — 防双 plan）
+- **空白脚手架字段**：Direction / Scope / Acceptance Criteria / Non-Goals / Delivery Branch Policy（`iteration_base_branch` / `spec_integration_branch` / `target_branch`）/ Plans / Feedback log / Deferred grill log
+- **Build 才勾的 todos**（顺序）：`harness-init` → `finalize-compass-plans`（**同一份** CreatePlan 落成 compass + plans + `status.json` 登记 + 索引）→ review-edit-product-manager → review-edit-architect → review-edit-writing-specialist → `pm-lock` → `integration-branch`
 
-| 规则 | 说明 |
-|------|------|
-| **CreatePlan 只调用一次** | §P.2 空白脚手架是本会话 **唯一** 一次 CreatePlan |
-| **记录路径** | 记下工具返回的 plan 文件路径（常在 `~/.cursor/plans/*.plan.md`）；后续所有修订都写 **这一份** |
-| **更新方式** | Feedback / deferred grill 后用 **Read + Write/StrReplace 原地改** 该文件；**禁止**再调 CreatePlan 开第二份 |
-| **发现重复** | 若已误开第二份：把有效内容 **合并进第一份**，删除重复文件，并确保用户 View Plan 指向第一份 |
-
-### P.1 Research（只读）
-
-执行与 §1 相同的调研（structured + unstructured + `STRATEGY.md`）。**不要**在本步写 compass/plans 终稿。
-
-### P.2 Early CreatePlan（空白脚手架 — 本会话唯一一次）
-
-Research 后 **立刻** CreatePlan **一次**（**禁止**等方向锁定完成再 CreatePlan；**禁止**之后再 CreatePlan）。
-
-**CreatePlan 最小结构**（session mirror；dual-write 草稿见 P.3）：
-
-```markdown
-# Phase 1: <iteration-id-or-TBD>
-
-## Direction
-TBD
-
-## Scope
-TBD
-
-## Acceptance Criteria
-TBD
-
-## Non-Goals
-TBD
-
-## Delivery Branch Policy
-| Field | Value |
-|-------|-------|
-| iteration_base_branch | TBD |
-| spec_integration_branch | TBD |
-| target_branch | TBD |
-
-## Plans
-| plan_id | Name | Status | Notes |
-|---------|------|--------|-------|
-| TBD | | Todo | |
-
-## Feedback log
-（吸收用户反馈 / agent 推荐决议后追加）
-
-## Deferred grill log
-（仅 P.3.5 若发起 grill 时追加；可空）
-```
-
-**Build 才勾的 todos**（顺序；**不要**把 feedback / grill 写成 Build todo）：
-
-1. `harness-init` — 若 `{HARNESS_DIR}` / `status.json` 缺失则初始化
-2. `finalize-compass-plans` — 将 **同一份** CreatePlan 正文落成 compass + `{PLAN_DIR}/` plans + `status.json` 登记 + `{ITERATION_DIR}` 索引
-3. `review-edit-product-manager` — §5.1 invoke
-4. `review-edit-architect` — §5.2 invoke
-5. `review-edit-writing-specialist` — §5.3 invoke
-6. `pm-lock` — §5.4 compass `status: locked` + Prepare gates
-7. `integration-branch` — §6
-
-### P.3 Feedback loop（主路径 — 直到用户明确结束反馈）
-
-**用户模式**：提方向、提意见、纠正推荐 — **纯反馈**。**不要**把用户当成问卷答题人；**禁止**例行一问一答卡更新。
-
-**Agent 每轮**（可多轮，直到用户喊停）：
-
-1. 探索代码 / harness / roadmap（能靠读回答的先读）
-2. 形成推荐（Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans）
-3. **立刻**原地更新 **§P.2 那一份** CreatePlan（含 `## Feedback log`）+ 推荐 dual-write SSOT 草稿
-4. 吸收用户新反馈 → 再探索/再改 **同一份** plan
-
-**Branch policy**：在 plan 中写入 **推荐值 + 简短 rationale**（不得静默默认 `main`/`master`）；用户可用反馈改掉。**不要**在本阶段为 branch 开 grill。
-
-**禁止**：
-
-- 再调 CreatePlan / 写到另一份 plan 文件
-- 把「等用户回答问题」当作更新 plan 的门禁
-- 在用户结束反馈前加载 / 运行 `grill-me`
-- 固定死反馈轮数；Plan 模式内派发 §5 / commit / §6
-
-### P.3.5 Feedback-close → deferred grill（可选）
-
-**触发**：用户明确表示反馈结束（例如：反馈结束、总结、分析反馈、可以了、准备 Build）。
-
-然后 Agent 自检 CreatePlan：Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans 是否仍有 **阻塞缺口**。
-
-| 结果 | 动作 |
-|------|------|
-| **无阻塞缺口** | **不**开 grill-me；宣布可 Build；确认同一份 CreatePlan + 草稿 SSOT 已反映锁定内容 |
-| **仍有阻塞缺口** | Read `skills/grill-me/SKILL.md`（**仅本命令**）；对 **剩余缺口** 做最小 grill（一段一问）；每段收敛后仍 **原地改同一份** CreatePlan，并追加 `## Deferred grill log` |
-
-**Direction lock mode** 仍为 interactive 语义，但 Plan 会话的 **主路径是 feedback-driven**；grill 是 close 后门禁，不是主循环。
-
-### P.4 Build（执行 Phase 1 可执行门禁）
-
-用户点击 **Build**（或 Plan → Agent）后：
-
-1. 按 Build todos 顺序执行：`harness-init` → `finalize-compass-plans`（以 **View Plan 打开的那一份** CreatePlan 为准）→ §5 Review 链（5.1→5.2→5.3）→ `pm-lock` → §6
-2. **禁止**把 Build 当成重新跑 feedback / grill
-3. pre-commit checklist（见 §5）全 `[x]` 后再 commit / push integration 分支
-
-**非 Plan 路径从这里继续 ↓**
+## 非 Plan 路径从这里继续 ↓
 
 ## 1. Research
 
-Load harness entry, then survey structured and unstructured sources:
+Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ glob for planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）；read matches with iteration-level / deferred-scope information；read `STRATEGY.md`（if exists）。Prioritize deferred / incomplete items from prior iterations。
 
-**Structured harness dirs:**
-- `{HARNESS_DIR}/status.json` → active plans, deferred features, residuals
-- `{ITERATION_DIR}/` → previous iteration compasses, roadmap batches
-- `{KNOWLEDGE_DIR}/` → design knowledge, architecture notes
-- `{SPECS_DIR}/` → existing specs, gaps
-
-**Unstructured discovery — search the repo for planning artifacts by name:**
-- Glob for `**/roadmap*.md`, `**/ROADMAP*.md`, `**/*-roadmap.md`
-- Glob for `**/deferred*.md`, `**/DEFERRED*.md`
-- Glob for `**/features*.md`, `**/FEATURES*.md`
-- Also search for `**/backlog*.md`, `**/TODO*.md`, `**/todo*.md`, `**/*.plan.md`
-- Open and read any matches that carry iteration-level or deferred-scope information
-
-Identify deferred or incomplete items from prior iterations as priority candidates for this iteration.
-
-Also read `STRATEGY.md`（if exists）for strategic alignment.
-
-**Optional — codebase audit**: if a prior `/codebase-audit` run exists under `{PLAN_DIR}/audit-<date>/`, read its findings index. Audit plans are evidence-grounded direction candidates — high-leverage fixes, security issues, tech debt, or feature directions the codebase itself signals. Use them as input to §2 Explore Directions alongside deferred items and roadmap context. Do **not** treat the audit as mandatory; it is one source among many.
+**Optional — codebase audit**: if a prior `/codebase-audit` run exists under `{PLAN_DIR}/audit-<date>/`, read its findings index as evidence-grounded direction candidates for §2（not mandatory；one source among many）。
 
 ## 2. Explore Directions
 
-> **非 Plan 路径**。Cursor Plan mode 已在 §P 处理；勿与 §P 并行再跑一遍。
-
-Explore candidate directions targeting **product completeness**:
-
-- Default to completing deferred items from previous iterations
-- Allow substantive refactoring where it accelerates product maturity
-- Scope 2–4 candidates, each with clear product-completeness goals and trade-offs
+Scope **2–4** candidates targeting **product completeness**（default to deferred items from previous iterations；allow substantive refactoring where it accelerates product maturity）。**非 Plan 路径**（Plan mode 已由 §P 处理）。
 
 ## 3. Lock Direction — bundled `grill-me`
 
@@ -196,73 +72,29 @@ Explore candidate directions targeting **product completeness**:
 
 This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step**（及 §P.3.5 deferred grill）references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
 
-**Before this step:** Read `skills/grill-me/SKILL.md`.
-
-Run **grill-me** to stress-test candidate directions with the user:
-
-- Walk through trade-offs for each candidate
-- Converge on a **single iteration direction** with shared understanding
-- Document: locked direction, success criteria, non-goals
-- Confirm delivery branch policy:
-  - `iteration_base_branch`: branch/ref used to create `spec_integration_branch`
-  - `target_branch`: PR target after iteration-close
-  - If either is not explicit, inspect the current branch and ask. **Do not default to `main` / `master` just because those names exist.**
+**Before this step:** Read `skills/grill-me/SKILL.md`. Run **grill-me** to stress-test candidate directions with the user: walk through trade-offs, converge on a **single iteration direction** with shared understanding, document locked direction + success criteria + non-goals。Confirm delivery branch policy（`iteration_base_branch`、`target_branch`）per **`mstar-iteration` §1.2** — **Do not default to `main` / `master` just because those names exist.**
 
 ## 4. Write Compass & Plans
 
-> **非 Plan 路径**。Plan mode 在 §P.2–P.3.5 维护 **同一份** CreatePlan 草稿，Build 时由 `finalize-compass-plans` 落盘终稿。
-
-Produce harness artifacts per **`mstar-iteration` § 1.3**（template: `mstar-iteration/references/iteration-compass-template.md`）：
-
-- `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`
-- `{PLAN_DIR}/<plan-id>-<name>.md` for each plan in this iteration
-- Register all plans in `{HARNESS_DIR}/status.json`（per `mstar-plan-artifacts` §1.5：root `metadata` + plan `spec_integration_branch`）
-- Update `{ITERATION_DIR}/README.md` index（**一行 = 一次迭代**；per `mstar-iteration` § 1.4）
-- Create package dirs as needed: `{ITERATION_DIR}/<iteration-id>/{guides,specs}/` + optional package `README.md`
+Produce harness artifacts per **`mstar-iteration` §1.3–§1.5**（template: `mstar-iteration/references/iteration-compass-template.md`）：compass（frontmatter **must** include `iteration_base_branch`、`target_branch`、`status: active`）、plans、`status.json` 登记（`mstar-iteration` §1.5）、`{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）、package dirs（`{ITERATION_DIR}/<iteration-id>/{guides,specs}/`）。**非 Plan 路径**。
 
 ## 5. Review & Edit Chain（HARD GATE — do not commit before this）
 
-**STOP**: Do not run §6 Integration Branch until **all** rows below are true.
-
-**顺序（HARD）**：`product-manager` → `architect` → `writing-specialist` → PM lock。后一角色基于前一角色已落盘的修订继续编辑；**禁止**三角色并行 invoke。OpenCode：正文用 plain role id — **`mstar-host/references/opencode.md`** § Role-mention hygiene。
-
-Each role below **reviews and directly edits** the documents. Do not just flag issues — apply the fixes yourself. PM only steps in for the final lock.
-
-| # | Role | Required action | Gate |
-|---|------|-----------------|------|
-| 5.1 | **product-manager** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, **`{ITERATION_DIR}/<iteration-id>/`**（`guides/`、`specs/` 按需）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 完成后方可 5.2 |
-| 5.2 | **architect** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, package `specs/`（含 5.1 后版本）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 5.1 返回后；完成后方可 5.3 |
-| 5.3 | **writing-specialist** | invoke: **edit** compass / plans / specs / iteration 文档; **specs corpus hygiene**（全库 `{SPECS_DIR}/` + 既有 `{KNOWLEDGE_DIR}/` 卫生与错放纠正，**不**新增 knowledge）— `mstar-iteration/references/iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md` | 5.2 返回后 |
-| 5.4 | **project-manager** | Merge subagent edits; resolve conflicts; **lock** compass (`status: locked`); confirm Prepare gates | 5.3 返回后 |
-
-**Evidence of done** = edited compass / plans / **specs** / iteration docs on disk + specs corpus hygiene（及既有 knowledge 归档/错放纠正，如有）+ compass `status: locked`. **No** new `{KNOWLEDGE_DIR}/` from this chain — knowledge → **`mstar-compound`** @ iteration-close. **No** separate iteration review reports under `reports/`.
-
-**Tool rule (hosts with invoke)** — per **`mstar-dispatch-gates`** · specialist review-and-edit dispatch（**顺序链**，非 parallel batch）：
-
-1. 为当前角色写好 Assignment（含须直接编辑的文件路径；5.2/5.3 注明基于上一角色已落盘修订）。
-2. **派发 1 次 invoke** → 等待 Completion Report / 磁盘修订完成。
-3. 按序重复下一角色：**5.1 → 5.2 → 5.3**（每步一条派发消息、一次 invoke）。
-4. 本条链 **禁止** PM 线程代做专业编辑；**禁止** 同条消息并行三角色；**禁止** 未等 5.1 返回就发 5.2/5.3。
-5. 5.3 返回后，PM 线程再做 5.4 merge + lock。
-
-- Exception: user explicitly waives subagent dispatch ("PM-only review").
+Execute **`mstar-iteration` §1.6**（SSOT）：顺序 `product-manager` → `architect` → `writing-specialist` → PM lock（**禁止**并行三角色；OpenCode plain role id — `mstar-host/references/opencode.md` § Role-mention hygiene）；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist specs corpus hygiene（`iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）。Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（每角色 1 invoke，等磁盘修订返回）。Exception: user explicitly waives subagent dispatch ("PM-only review").
 
 **Prepare gate (per plan in compass)**:
+
 - [ ] specify / clarify / plan = done on each plan file
 - [ ] `primary_spec` path exists (if declared)
 - [ ] `blocked_by` / sequential deps documented
 
-Only after 5.4 → proceed to §6.
-
 ### iteration-start pre-commit checklist
 
 PM must print this block before §6; all `[ ]` must be `[x]`:
 
 - [ ] direction lock decisions recorded in compass（Plan 路径：Feedback log + 可选 Deferred grill log；非 Plan：grill-me）
 - [ ] Draft compass + plans + `status.json` registered
-- [ ] product-manager invoke completed — compass / plans / specs / **`<iteration-id>/` package**（按需）；**未**向 `{KNOWLEDGE_DIR}/` 新增
-- [ ] architect invoke completed — compass / **specs** edited；**未**向 `{KNOWLEDGE_DIR}/` 新增
-- [ ] writing-specialist invoke completed — specs + iteration docs edited；**specs corpus hygiene** done（全库 `{SPECS_DIR}/`；既有 knowledge 仅卫生/归档；错放已迁回 `iterations/` 或 archive）
+- [ ] product-manager / architect / writing-specialist invokes completed — 编辑 compass / plans / specs / **`<iteration-id>/` package**；**未**向 `{KNOWLEDGE_DIR}/` 新增；writing-specialist specs corpus hygiene done
 - [ ] PM final lock: compass `status: locked`; Prepare gates pass (blocked plans documented)
 - [ ] Branch policy locked: `iteration_base_branch`, `spec_integration_branch`, and `target_branch` recorded in compass / `status.json`
 - [ ] **THEN**: git commit + push `iteration/<iteration-id>`
@@ -282,6 +114,6 @@ git checkout -b <spec_integration_branch> <iteration_base_branch>
 - Register `iteration_base_branch`, `spec_integration_branch`, and `target_branch` in compass frontmatter **and** `{HARNESS_DIR}/status.json` root `metadata`
 - Commit all documents to the integration branch and push to remote
 
-**Phase 2 note**：integration 分支在此创建；**control worktree + `execution_lease` 门控在 Phase 2 入口**（`iteration-drive` / `iteration-loop`）——见 **`mstar-iteration/references/phase-2-worktree-lease.md`**。
+**Phase 2 note**：control worktree + `execution_lease` 门控在 Phase 2 入口（`iteration-drive` / `iteration-loop`）——见 **`mstar-iteration/references/phase-2-worktree-lease.md`**。
 
 **STOP** if `iteration_base_branch` or `target_branch` is missing. Ask the user or derive only from an already documented project/iteration policy; never silently substitute `main`.

package/harness-skills/mstar-branch-worktree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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`)."
+description: "Morning Star 业务仓 Git 功能分支、worktree 隔离（L1 跨 plan：control worktree + 每 plan feature worktree + `execution_lease`，默认 gitignore 下经 control 绝对路径读写进程产物；L2 同 plan：`references/parallel-writable-pre-dispatch.md`，N 次 invoke ≠ 隔离）、Spec 集成分支、QC/QA 检出对齐（`Review cwd` / `Working branch` / `plan_id` / `Review range` / `Diff basis` 三审 + QA 逐字相同）。Read when PM writes `Working branch` / `Branch policy`, iteration/parallel writable dispatch, or QC/QA checkout alignment is needed."
 ---
 
 ## Load order（必读顺序）
@@ -174,31 +174,42 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 
 **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`**（对业务仓 **只读 diff 审查**）；**一般不必**为每位 reviewer 各开一个 worktree，除非宿主或执行环境要求进程级隔离。
-- **并行 QC 禁止**在共享检出上跑 **test / build / install / lint / typecheck** 等会争用缓存或锁的命令（否则 peer QC 易 `Blocked`）。L3 默认手段：`git diff` / `git log` / `git show` / Read / Grep。运行时验证留给 **L1 证据** 与 **`qa-engineer`（L4）** — 见 `mstar-review-qc/references/review-responsibility-boundaries.md`。
-- QC 的 **报告落盘**默认仅限 Assignment 指定的 `{SDD_DIR}/review/`；上述约定保证 `git diff`、`git log` 与所读文件与 **待合并 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 写明）。
+## QC / QA 检出对齐与多 worktree 门禁衔接（强制；避免误派）
+
+### 对齐字段契约（canonical）
+
+分派 **QC 三审** 与对齐的 **QA 验证** 时，PM **必须**在 Assignment 写明与待审实现一致的 **`Review cwd` / `Worktree path`**、**`Working branch`**、**`plan_id`**、**`Review range` / `Diff basis`**。开发在 **feature 分支**（往往在独立 worktree 中）完成后，QC/QA 针对的都是这份 feature，不是 `main` 或任意未对齐默认 cwd。
+
+- **`Review cwd` / `Worktree path`**：**优先**沿用开发 Completion Report 回报的业务仓实现检出路径（该 feature 的 worktree）**当且仅当**该路径检出分支 `HEAD` 已含本轮待审全部提交（含曾发生在其他并行 worktree、现已归并到该分支的变更）。否则**必须**改用集成完成后的 `Working branch` 与对应检出路径（或在该分支上**另开**只读审查 worktree）。开发未用 worktree → 写明单一业务仓根路径。
+- **`Working branch`**：含全部待审提交的那条分支（常见 plan 集成分支）。
+- **`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`，以团队可复现为准）。
+- **逐字对齐（强制）**：三份 QC Assignment 与 QA Assignment 间 **`plan_id`** 与 **`Review range` / `Diff basis`**（连同 `Review cwd` / `Working branch`）**必须完全相同**；**`qa-engineer`** 验证同一 feature 时**复用同一组字段**。**热修 / QC 单审**路径也须含**同一组字段**，仅承接方份数为 1。
+- 三审并行时三名 reviewer **共用同一组**字段（对业务仓**只读 diff 审查**）；一般不必为每位 reviewer 各开 worktree，除非宿主/环境要求进程级隔离。
+
+### 多 worktree 并行 → 单一待审快照（派 QC 前置）
+
+**语义区分（必须理解）**：开发阶段可存在 **多个** `Worktree path`（每条流一条检出目录）；**一轮**正式 QC 三审 + 对齐 QA 只对应 **一套**对齐字段（上文）。**不要**把「多个开发 worktree」误解成「QC 应轮流进多个目录各审一半」。
+
+**单一待审 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 错误**）。
+
+**推荐默认编排（plan 集成分支先行）**——同仓、同一 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 明确记录，例如 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 指定团队方式）到同一条将作 QC **`Working branch`** 的分支 **`HEAD`**（**通常即 plan 集成分支**；PM 已重命名/快进为最终 `feature/*` 则以 Assignment 为准）。**在此**解决冲突；**勿**在 QC Assignment 仍指向「只含部分轨」旧 `HEAD` 时派三审。
+4. **QC/QA 的 `Working branch` 与合并主线**：`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`。
+
+**不应合并为一次审时**：若两轨**有意**保持独立可合并单元（例如两条独立 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 执行约束
+
+- **并行 QC 禁止**在共享检出跑 **test / build / install / lint / typecheck** 等争用缓存或锁的命令（否则 peer QC 易 `Blocked`）。L3 默认手段：`git diff` / `git log` / `git show` / Read / Grep。运行时验证留给 **L1 证据**与 **`qa-engineer`（L4）** — 见 `mstar-review-qc/references/review-responsibility-boundaries.md`。
+- QC **报告落盘**默认仅限 Assignment 指定的 `{SDD_DIR}/review/`；上述约定保证 `git diff`、`git log` 与所读文件与**待合并 feature** 一致。PM 另行提交主 plan gate summary / `status.json` residual changes as durable artifacts。
+- **`qa-engineer`**（仅 **`QA gate: mandatory`**）Assignment 用 QC 逐字相同的对齐字段（QC 已写清则 QA 照抄）；执行业务仓命令前须核对检出与分支；Report-only 且无路径依赖时回报须说明验证环境，否则 `Blocked`。
+- 若 **QA 与同仓其他可写角色并发**提交测试代码，仍须遵守上文「同仓并发写入」**worktree** 规则（可为 QA 单开一条写入 worktree，**同一 `Working branch`**，由 PM 在 Assignment 写明）。
 
 派发前清单与常见反模式 → **`references/parallel-writable-pre-dispatch.md`**。