@mstar-harness/opencode 2.4.1 → 3.0.1

package/harness-skills/mstar-iteration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mstar-iteration
-description: Morning Star 迭代管理 —— Phase 1（默认 interactive direction lock；opt-in autonomous；specs + `<iteration-id>/` package；禁止直写 knowledge）、Autonomous Execute、iteration-close（compound 提升 package → knowledge）、PR 交付、PR merge-ready loop。分支 SSOT：`status.json` + compass frontmatter。
+description: Morning Star 迭代管理 —— Phase 1（默认 interactive direction lock；opt-in autonomous；specs + `<iteration-id>/` package；禁止直写 knowledge）、Autonomous Execute、iteration-close（compound 提升 package → knowledge）、PR 交付、PR merge-ready loop。分支 SSOT：workflow snapshot（`workflows/<id>/snapshot.json`）+ compass frontmatter。
 ---
 
 # mstar-iteration（迭代管理）
@@ -33,25 +33,25 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 
 - **Phase 3** 在 integration 分支收口 compound / roadmap；**开 PR（Phase 4）≠ 迭代交付完成**。
 - **Phase 5** 是 **merge-ready loop**：修复 →（等 CI/review 波次结束再）push → 再验证，直至 §5.5 exit。**Loop 理念与 push cadence SSOT 在本 skill**（§5.1a）；宿主 command 可叠加额外 **non-`mstar-*`** helper（**优先** `babysit` / `*-babysit`；**`greploop` 可选** — 仅当仓库具备 Greptile/`greploop` 时采用），但不写入 `mstar-*` load order。
-- 一次迭代 = 一个 PR；compound 产物随 PR 合入 `metadata.target_branch`。
+- 一次迭代 = 一个 PR；compound 产物随 PR 合入 snapshot `branch.target`。
 
 ## Phase transition gates（HARD — 防跳步）
 
 | 边界 | 触发 | 必须 | 禁止 |
 |------|------|------|------|
-| **→ Phase 3** | `status.json` 中 compass 登记的全部 plan 均为 `Done` | 打印 `## Phase 3: iteration-close`；执行 §3.0→§3.5；host todo `phase-3-iteration-close` 保持 open 直至 §3.5 | 开 PR；宣称迭代交付完成；仅依赖 final plan closure |
-| **→ Phase 4** | §3.5 exit checklist 全 `[x]`；frontmatter `status: completed` + `end_date` | 打印 `## Phase 4: PR delivery`；开 PR 到 `metadata.target_branch`（§4） | 跳过 §3.1 entry checklist 或 compound Phase 6 |
+| **→ Phase 3** | workflow snapshot（`workflows/<id>/snapshot.json`）中 compass 登记的全部 plan 均为 `Done` | 打印 `## Phase 3: iteration-close`；执行 §3.0→§3.5；host todo `phase-3-iteration-close` 保持 open 直至 §3.5 | 开 PR；宣称迭代交付完成；仅依赖 final plan closure |
+| **→ Phase 4** | §3.5 exit checklist 全 `[x]`；frontmatter `status: completed` + `end_date` | 打印 `## Phase 4: PR delivery`；开 PR 到 snapshot `branch.target`（§4） | 跳过 §3.1 entry checklist 或 compound Phase 6 |
 | **→ Phase 5** | Phase 4 PR 已创建 | 打印 `## Phase 5: PR merge-ready`；执行 §5 loop 至 §5.5 exit（含 §5.1a push cadence） | 开 PR 后停止；跳过 review resolve / CI loop；**CI/AI review 仍在跑时 push** |
 | **→ 迭代交付完成** | §5.5 exit checklist 全 `[x]` | PR mergeable；required CI 全绿；reviews resolved | Phase 4 开 PR 即宣称完成 |
 | **iteration-start → integration branch** | §1.6 Review & Edit chain | 三角色按序 invoke；**specs** 为主产出；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene + compass `status: locked` | PM 代做专业编辑；并行三角色；product/architect 写 knowledge；临时笔记进 specs |
 
-> **Engine check (when available):** run `mstar iteration gate --status <status.json> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the transition gate above. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar iteration gate --workflow <id> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the transition gate above against the workflow snapshot. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
 
 **误判信号**：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 **未** 打印 §3.1 / §3.5 checklist → 视为 **Phase 3 未执行**，回到 §3.0。
 
-**per-plan 状态 SSOT**：`{HARNESS_DIR}/status.json`（per-plan Todo/InProgress/InReview/Done）。
+**per-plan 状态 SSOT**：`{WORKFLOW_DIR}/<id>/snapshot.json` 的 `plans[]` 行（per-plan Todo/InProgress/InReview/Done）；根 `{HARNESS_DIR}/status.json` `workflows[]` 登记活跃 lifecycle。
 **迭代状态 SSOT**：`{ITERATION_DIR}/<id>/delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）。
-**迭代分支 SSOT**：root `metadata.iteration_base_branch` + `metadata.target_branch`（`status.json`）；compass frontmatter 镜像同名字段。解析顺序见 §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。
+**迭代分支 SSOT**：snapshot `branch.base`（= `iteration_base_branch`）+ `branch.target`（= `target_branch`）与 `branch.integration`（= `spec_integration_branch`）（`workflows/<id>/snapshot.json`）；compass frontmatter 镜像同名字段。解析顺序见 §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。
 
 ## 产物存储位置
 
@@ -170,15 +170,15 @@ plans: []
 
 > **Engine check (when available):** import `assertIndexRowObligations` from `@mstar-harness/engine` in a host hook to assert the index-row obligations above (no CLI form yet). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
-### 1.5 登记到 status.json（formal iteration 必填）
+### 1.5 登记到 v2 状态面（formal iteration 必填）
 
-iteration 正式全流程**必须**写入 `{HARNESS_DIR}/status.json`：
+iteration 正式全流程**必须**登记 `{HARNESS_DIR}/status.json`（v2 根）+ `{WORKFLOW_DIR}/<id>/snapshot.json`：
 
-- root `metadata.iteration_base_branch` — 创建 `spec_integration_branch` 的祖先 ref（**不是**隐式 `main`）
-- root `metadata.target_branch` — iteration-close 后 PR 的目标分支
-- 各 plan `metadata.iteration_refs`、`spec_integration_branch`、`merge_target`（`merge_target` 通常为 `spec_integration_branch`）
+- 根 `status.json` `workflows[]` 增一条 active entry：`{ "id": "<iteration-id>", "type": "iteration", "started_at", "dir": "workflows/<iteration-id>" }`（engine `registerWorkflow`）。
+- snapshot 顶层 `branch` anchors：`base`（= `iteration_base_branch`，创建 `spec_integration_branch` 的祖先 ref——**不是**隐式 `main`）、`integration`（= `spec_integration_branch`）、`target`（= iteration-close 后 PR 的目标分支）。
+- 各 plan 行 `metadata.iteration_refs`、`spec_integration_branch`、`merge_target`（`merge_target` 通常为 `spec_integration_branch`）。
 
-compass frontmatter 的 `iteration_base_branch` / `target_branch` **必须与** `status.json` 一致；若仅写在 compass 而 status 缺失，§2.3 同轮 backfill。
+compass frontmatter 的 `iteration_base_branch` / `target_branch` **必须与** snapshot `branch` 一致；若仅写在 compass 而 snapshot 缺失，§2.3 同轮 backfill。
 
 ### 1.5.5 产物边界（specs · iterations · knowledge）
 
@@ -220,13 +220,13 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 
 进入 Autonomous Execute 前必须满足：
 
-1. `{HARNESS_DIR}/status.json` 中至少一条 plan `status` ≠ `Done`
+1. workflow snapshot（`{WORKFLOW_DIR}/<id>/snapshot.json`）中至少一条 plan `status` ≠ `Done`；根 `status.json` `workflows[]` 含该 iteration entry
 2. **Pre-implement gate = GO**：plan 已 locked、tasks ready（见 `mstar-phase-gates`）
 3. 用户意图为 **continue Autonomous Execute**（推进迭代 Execute、继续 per-plan 循环等）
-4. **Branch metadata gate**：root `metadata.iteration_base_branch`、`metadata.target_branch` 已登记，且至少一条 active plan 有 `metadata.spec_integration_branch`（或可从 compass 同轮 backfill）。**缺失 → STOP**，不得用 `main`/`master` 补位。
-5. **Control-worktree + lease defaults**（iteration 命令；可被 `Worktree mode: waived` 豁免）：除非本轮 Assignment 显式 `Worktree mode: waived`（或等价用户指令），Phase 2 **必须**在入口建立 control worktree、经 control 路径读写默认 gitignored 的 harness 进程产物（`status.json`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{SDD_DIR}` 等），并在可写派发前 claim `plans[].execution_lease` / `integration_merge_lease`。可写 Assignment 须含绝对 feature **`Worktree path`** + 绝对 control 系 **`Plan Path`** / **`SDD dir`**（见 **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」）。**禁止**因 feature worktree 在默认 gitignore 下看不到 plans 而推断 `Worktree mode: waived`。`Plan parallelism: serial` **不** waive 本闸——仅强制跨 plan **implement** 串行调度；control worktree + lease 仍须满足。**跨 plan 并行安全闸**（**不可**被 `Worktree mode: waived` 豁免）：跨 plan **并行可写 implement** 须满足下列之一——(a) coordination 路径（control 或 waived 时主 checkout `{HARNESS_DIR}/status.json`）上 **same-host 独占写锁可用且每次 status/协调变更持锁**；(b) 默认 **`Plan parallelism: serial`**（**waived 时尤其优先默认串行**；**无 flock / 无共享锁时只触发本条，不豁免 worktree**）；(c) 用户本轮显式 `Cross-host lease race: accepted`（或等价）+ `plans[].notes` 审计。**禁止**将 `Worktree mode: waived` 当作跨主机无锁并行的授权。细则 → **`references/phase-2-worktree-lease.md`**。
+4. **Branch metadata gate**：snapshot `branch.base`（`iteration_base_branch`）、`branch.target`（`target_branch`）已登记，且至少一条 active plan 有 `metadata.spec_integration_branch`（或可从 compass 同轮 backfill）。**缺失 → STOP**，不得用 `main`/`master` 补位。
+5. **Control-worktree + lease defaults**（iteration 命令；可被 `Worktree mode: waived` 豁免）：除非本轮 Assignment 显式 `Worktree mode: waived`（或等价用户指令），Phase 2 **必须**在入口建立 control worktree、经 control 路径读写默认 gitignored 的 harness 进程产物（根 `status.json`、`workflows/`、`projects/`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{SDD_DIR}` 等），并在可写派发前 claim workflow snapshot 的 `plans[].execution_lease` / 顶层 `integration_merge_lease`。可写 Assignment 须含绝对 feature **`Worktree path`** + 绝对 control 系 **`Plan Path`** / **`SDD dir`**（见 **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」）。**禁止**因 feature worktree 在默认 gitignore 下看不到 plans 而推断 `Worktree mode: waived`。`Plan parallelism: serial` **不** waive 本闸——仅强制跨 plan **implement** 串行调度；control worktree + lease 仍须满足。**跨 plan 并行安全闸**（**不可**被 `Worktree mode: waived` 豁免）：跨 plan **并行可写 implement** 须满足下列之一——(a) coordination 路径（control snapshot 或 waived 时主 checkout `{HARNESS_DIR}/status.json`）上 **same-host 独占写锁可用且每次 status/协调变更持锁**；(b) 默认 **`Plan parallelism: serial`**（**waived 时尤其优先默认串行**；**无 flock / 无共享锁时只触发本条，不豁免 worktree**）；(c) 用户本轮显式 `Cross-host lease race: accepted`（或等价）+ `plans[].notes` 审计。**禁止**将 `Worktree mode: waived` 当作跨主机无锁并行的授权。细则 → **`references/phase-2-worktree-lease.md`**。
 
-> **Engine check (when available):** run `mstar lease verify <plan-id>` 或 `mstar lease verify-integration`（或 import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook）以校验上述迭代 lease（execution_lease / integration_merge_lease）。On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar lease verify --workflow <id> [--plan <plan-id>]` 或 `mstar lease verify-integration --workflow <id>`（或 import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook）以校验上述迭代 lease（snapshot 的 execution_lease / integration_merge_lease）。On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 任一 false → **stop**。Phase 1 / Prepare 未完成 → 先完成 Phase 1 或 per-plan Prepare，再进入本 Phase。
 
@@ -240,21 +240,21 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 | **Codex** | `update_plan` / Goal UI | 同上 |
 | **OpenCode** | host todo/plan UI（如有） | 同上 |
 
-SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一步。
+SSOT = `{WORKFLOW_DIR}/<id>/snapshot.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一步。
 
 ### 2.2 Read backlog
 
-1. 读 `mstar-plan-artifacts` + `{HARNESS_DIR}/status.json`
-2. 列出 `status` ∈ `{Todo, InProgress, InReview, Blocked}` 的 plan（优先级：`InProgress` → `InReview` → `Todo` → unblock `Blocked`）
-3. 读 root `metadata.iteration_base_branch` / `metadata.target_branch`，以及 plan `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
+1. 读 `mstar-plan-artifacts` + workflow snapshot（`{WORKFLOW_DIR}/<id>/snapshot.json`）与根 `status.json`
+2. 列出 snapshot 中 `status` ∈ `{Todo, InProgress, InReview, Blocked}` 的 plan（优先级：`InProgress` → `InReview` → `Todo` → unblock `Blocked`）
+3. 读 snapshot `branch.base` / `branch.target`，以及 plan `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
 
 ### 2.3 Integration branch + control worktree（Phase 2 入口）
 
-**Metadata 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
+**Branch anchors 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
 
-1. `{HARNESS_DIR}/status.json` → `metadata.iteration_base_branch`、`metadata.target_branch`；plan → `metadata.spec_integration_branch`
+1. workflow snapshot → `branch.base`（`iteration_base_branch`）、`branch.target`（`target_branch`）、`branch.integration`（`spec_integration_branch`）；plan 行 → `metadata.spec_integration_branch`
 2. 若 (1) 缺字段 → 读当前迭代 compass frontmatter 同名键：优先 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；若无则 legacy `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`
-3. 若 compass 有值而 `status.json` 无 → **同轮 backfill** `status.json`
+3. 若 compass 有值而 snapshot 无 → **同轮 backfill** snapshot `branch`
 4. 仍缺 → 向用户确认 base / PR target；**不得**因 `git symbolic-ref refs/remotes/origin/HEAD` 指向 `main` 就自动采用
 5. 所有参与本轮迭代的 active plan **必须**解析到**同一** `spec_integration_branch`；不一致 → **STOP**
 
@@ -262,13 +262,14 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 
 1. 解析或创建 **control worktree**（通常 primary checkout 或 PM 指定路径），检出到上一步的 `spec_integration_branch`
 2. `git fetch`（按需）；`git branch --show-current` 确认在 `spec_integration_branch`
-3. 将规范绝对仓库根路径写入 control 副本 `metadata.control_worktree_path`（仓库根，非 `{HARNESS_DIR}` 子路径）
+3. 将规范绝对仓库根路径写入 control 副本 snapshot 顶层 `control_worktree_path`（仓库根，非 `{HARNESS_DIR}` 子路径）
 4. 此后 **harness 进程产物 SSOT**（默认 gitignored）均经 control 绝对路径解析：
-   - `<control_worktree_path>/{HARNESS_DIR}/status.json`
+   - `<control_worktree_path>/{HARNESS_DIR}/status.json`（v2 根 register）
+   - `<control_worktree_path>/{WORKFLOW_DIR}/<id>/snapshot.json`（per-lifecycle 运行态 + leases）
+   - `<control_worktree_path>/{PROJECT_DIR}/<id>/`（roadmap.md + residuals.json）
    - `<control_worktree_path>/{PLAN_DIR}/`（主 plan）
    - `<control_worktree_path>/{ITERATION_DIR}/`（compass / iteration package）
    - `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`
-   - 同树：`notes.json`、`archived/`（若使用）
    Feature worktree 只承载产品/源码编辑；其同名 `{HARNESS_DIR}` **不是** SSOT。Assignment **`Plan Path`** / **`SDD dir`** 须写 control 绝对路径。
 5. 若 integration 分支尚不存在：在 control worktree 内 `git checkout -b <spec_integration_branch> <iteration_base_branch>`（**必须**从记录的 base 创建）
 
@@ -278,22 +279,22 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 2. **checkout 或创建** `spec_integration_branch`（同上）
 3. `git branch --show-current` 确认在 `spec_integration_branch`
 
-`spec_integration_branch` 是本迭代内所有 plan feature branch 的 merge target。QC **`Review range` / `Diff basis`** 的 merge-base 参照优先用 `metadata.target_branch`（或 PM 书面指定的 base ref），**禁止**无 Assignment 依据写死 `origin/main`。
+`spec_integration_branch` 是本迭代内所有 plan feature branch 的 merge target。QC **`Review range` / `Diff basis`** 的 merge-base 参照优先用 snapshot `branch.target`（或 PM 书面指定的 base ref），**禁止**无 Assignment 依据写死 `origin/main`。
 
 ### 2.4 Per-plan loop（直到全部 Done）
 
-**跨 plan 默认**（**无论** `Worktree mode: waived`）：**不同 `plan_id` 可并行 implement** 须满足 §2.0 #5 跨 plan 并行安全闸——(a) coordination 路径 same-host 独占写锁可用且每次 status/协调变更持锁，或 (b) **`Plan parallelism: serial`**（waived 时默认），或 (c) 用户本轮 `Cross-host lease race: accepted` + audit `notes`；否则 Assignment 仍写并行 → **Blocked**。**merge 入 `spec_integration_branch` 仍串行**（`metadata.integration_merge_lease`；waived 时无 merge lease 仍须串行 merge）。未 waive 时 **禁止**无 verified `execution_lease` 的跨 plan 可写派发。
+**跨 plan 默认**（**无论** `Worktree mode: waived`）：**不同 `plan_id` 可并行 implement** 须满足 §2.0 #5 跨 plan 并行安全闸——(a) coordination 路径 same-host 独占写锁可用且每次 status/协调变更持锁，或 (b) **`Plan parallelism: serial`**（waived 时默认），或 (c) 用户本轮 `Cross-host lease race: accepted` + audit `notes`；否则 Assignment 仍写并行 → **Blocked**。**merge 入 `spec_integration_branch` 仍串行**（snapshot 顶层 `integration_merge_lease`；waived 时无 merge lease 仍须串行 merge）。未 waive 时 **禁止**无 verified `execution_lease` 的跨 plan 可写派发。
 
 对每个本轮要推进的 active `plan_id`（可交错/并行，非强制 plan A 全 Done 再 plan B）：
 
 1. **Claim / resume — execution lease**（§2.0 #5 未 waive）：
-   - 自 control 路径 **重读** `status.json` 定位 plan 行
+   - 自 control 路径 **重读** workflow snapshot（`{WORKFLOW_DIR}/<id>/snapshot.json`）定位 plan 行
    - 若已有 `execution_lease` 且 `holder` **等于本 session** → **resume**：校验 `worktree_path` / `working_branch` 与 Assignment 一致后继续（**不是** steal / Blocked）
    - 若 `execution_lease` 存在且 `holder` **不同** → **Blocked**
    - 若 `status: InProgress` 但 **无** `execution_lease` → **STOP** 升级（孤儿状态恢复 → **`mstar-plan-artifacts`**；本 skill 不自行补 lease）
    - 否则按 **`references/phase-2-worktree-lease.md`** claim：`Todo`/`Blocked` → `InProgress` + 写入完整 `execution_lease`；verify 通过前 **禁止**可写派发
 2. **Plan start — feature worktree + branch**：创建/校验 dedicated feature worktree；Assignment 须含绝对 `Worktree path` + `Working branch`（与 lease 一致）。plan 内多可写并行轨 → **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**
-3. **Implement → InReview**（`§ 2.5`；产品编辑在 feature worktree；plans / status / iterations / SDD 经 control 绝对路径）：
+3. **Implement → InReview**（`§ 2.5`；产品编辑在 feature worktree；plans / snapshot / iterations / SDD 经 control 绝对路径）：
    - **默认 `Execution mode: sdd`**（多 task plan；hotfix 可 `inline`）。
    - PM 载入 **`mstar-sdd`** 后，按 plan task 顺序 **串行** per-task 循环（**不是**一次派发 dev 做全部 tasks）：
      1. `mstar sdd workspace <plan-id>` → `{SDD_DIR}`
@@ -301,11 +302,11 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
      3. Dispatch **one** implementer subagent（`references/implementer-prompt.md`：brief 路径 + report 路径 + `Model tier`；**禁止**贴整份 plan）
      4. Implementer `DONE` → `mstar sdd review-package BASE HEAD` → task diff 文件
      5. Dispatch **one** task reviewer subagent（brief + report + diff + Global Constraints）
-     6. Fix loop 直至 review clean；append `{SDD_DIR}/progress.md`；更新 `status.json` / plan checkbox
+     6. Fix loop 直至 review clean；append `{SDD_DIR}/progress.md`；更新 snapshot plan 行 / plan checkbox
      7. Next task
-   - 每次 Completion Report 后更新 `status.json` + 主 plan
-4. **QC → QA gate**（plan 保持 **`InReview`**；**保留** `execution_lease`）：per-plan 审查链 → **`mstar-sdd`**（L1–L2）+ **`mstar-review-qc/references/review-responsibility-boundaries.md`**（L3 tri / inline 单席；raw reports in `{SDD_DIR}/review/`，durable summary in main plan/status）+ **`QA gate`**（`mandatory` → `qa-engineer`；`pm-acceptance` → PM checklist）。**禁止**在 integration merge 成功前设 `Done` 或删除 `execution_lease`。
-5. **Plan complete — serial merge back**（§2.0 #5 未 waive）：自 **control worktree** claim/resume `metadata.integration_merge_lease` → 将 plan feature branch 合并入 `spec_integration_branch`（仅 merge-lease holder；细则 → **`references/phase-2-worktree-lease.md`**）→ 记录 merge commit 证据 → 释放 merge lease；**同轮**设 `Done` 并删除 `execution_lease`。merge 失败：保持 `InReview` + 保留 lease，不得标 `Done`。
+   - 每次 Completion Report 后更新 snapshot（`workflows/<id>/snapshot.json`）+ 主 plan
+4. **QC → QA gate**（plan 保持 **`InReview`**；**保留** `execution_lease`）：per-plan 审查链 → **`mstar-sdd`**（L1–L2）+ **`mstar-review-qc/references/review-responsibility-boundaries.md`**（L3 tri / inline 单席；raw reports in `{SDD_DIR}/review/`，durable summary in main plan/snapshot）+ **`QA gate`**（`mandatory` → `qa-engineer`；`pm-acceptance` → PM checklist）。**禁止**在 integration merge 成功前设 `Done` 或删除 `execution_lease`。
+5. **Plan complete — serial merge back**（§2.0 #5 未 waive）：自 **control worktree** claim/resume snapshot 顶层 `integration_merge_lease` → 将 plan feature branch 合并入 `spec_integration_branch`（仅 merge-lease holder；细则 → **`references/phase-2-worktree-lease.md`**）→ 记录 merge commit 证据 → 释放 merge lease；**同轮**设 `Done` 并删除 `execution_lease`。merge 失败：保持 `InReview` + 保留 lease，不得标 `Done`。
 6. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` 的 `## Plans` 表状态列
 7. **Next plan / parallel wave** 从步骤 1 继续（可并行推进其他已 claim 的 plan；merge 仍排队串行）
 
@@ -344,14 +345,14 @@ Iteration Phase 2 附加：
 - 不因 harness 流程问题常问「是否继续」「要不要现在启动」—— **决策、记录、dispatch**
 - 进度汇报 / subagent Completion Report 后，下一条必须是 **dispatch 或下一 gate 动作**，不得以确认问句收束 turn
 - 未知 → 读 `mstar-*`；仅 **`Blocked`**、secrets、不可逆范围缺口、branch metadata 缺失、或 Phase 5 多轮仍 blocked 时升级用户
-- 实际 Git ≠ `working_branch` → **同轮**更新 plan + status + `execution_lease.working_branch`（如适用）
+- 实际 Git ≠ `working_branch` → **同轮**更新 plan + snapshot + `execution_lease.working_branch`（如适用）
 - **跨 plan implement**（**无论** `Worktree mode: waived`）：并行可写 implement 须满足 §2.0 #5 跨 plan 并行安全闸——same-host 独占写锁 + 每次协调变更持锁，或默认 **`Plan parallelism: serial`**（waived 时尤其优先），或用户本轮 `Cross-host lease race: accepted` + audit `notes`；**禁止**将 waived 当作无锁跨主机并行授权；未 waive 时另须 verified `execution_lease` + feature worktree。**integration merge 串行**（`integration_merge_lease` 或 waived 下无 lease 仍须串行 merge）
 - plan 内 SDD task **串行** — 见 §2.4、§2.5、`mstar-sdd` Continuous execution
 - **zero-residual（默认）**：单 plan QC findings 尽量在当轮清干净；仅真 blocker 才 defer 到后续迭代（须 Durable Roadmap）— 见 **`mstar-plan-artifacts`** Findings cleanup modes
 
 ## Phase 3: iteration-close（收口迭代）
 
-**入口**：Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入。本 Phase 在 **integration 分支**上运行；产出物 commit 到该分支，随迭代 PR 合入 `metadata.target_branch`。
+**入口**：Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入。本 Phase 在 **integration 分支**上运行；产出物 commit 到该分支，随迭代 PR 合入 snapshot `branch.target`。
 
 完整流程（§3.0 phase boundary、§3.0.5 compass 规范化、§3.1 entry checklist **HARD GATE**、§3.2 compound、§3.3 roadmap、§3.4 标记完成、§3.5 exit checklist + commit、§3.6 可选 compound-refresh）→ **`references/phase-3-iteration-close.md`**。
 

package/harness-skills/mstar-iteration/references/autonomous-direction-lock.md

@@ -42,7 +42,7 @@ Write into compass (and plan Scope as needed):
 
 ### What counts toward the budget（HARD）
 
-Count only **business delivery plans** registered in compass / `status.json` whose primary outcome is product, feature, bugfix, user-facing docs, API/contract, or architecture work for the locked direction.
+Count only **business delivery plans** registered in compass / workflow snapshot (`workflows/<id>/snapshot.json`) whose primary outcome is product, feature, bugfix, user-facing docs, API/contract, or architecture work for the locked direction.
 
 **Do not count** harness / process work as plans (and do not invent plans whose sole job is process):
 
@@ -71,7 +71,7 @@ When a free-text direction / feedback constraint is supplied by the caller:
 
 Resolve `iteration_base_branch` and `target_branch` in order（first hit wins per field）:
 
-1. `{HARNESS_DIR}/status.json` root `metadata`
+1. Workflow snapshot `branch` anchors（`{WORKFLOW_DIR}/<id>/snapshot.json` → `branch.base` / `branch.target`；缺失则根 `status.json` `workflows[]` 无该 entry 时先登记）
 2. Existing / prior iteration compass frontmatter
 3. Current git branch **only if** it is already a documented delivery, integration, or project-policy branch（not merely “whatever HEAD is”）
 4. Still missing → **STOP** — escalate; **never** substitute `main` / `master` because those names exist

package/harness-skills/mstar-iteration/references/iteration-compass-template.md

@@ -57,7 +57,7 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
 
 ## Delivery Branch Policy
 
-> Mirror of frontmatter; keep in sync with `{HARNESS_DIR}/status.json` `metadata`.
+> Mirror of frontmatter; keep in sync with workflow snapshot `{WORKFLOW_DIR}/<id>/snapshot.json` `branch` anchors.
 
 | Field | Value |
 |-------|-------|
@@ -83,7 +83,7 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
 
 ## Quality Gate Summary
 
-> Filled at iteration-close. Human summary only; per-plan gate details stay in each main plan, and open residual SSOT stays in `{HARNESS_DIR}/status.json`.
+> Filled at iteration-close. Human summary only; per-plan gate details stay in each main plan, and open residual SSOT stays in `{PROJECT_DIR}/<id>/residuals.json`.
 
 | plan_id | QC decision | QA gate | Residuals | Durable summary |
 |---------|-------------|---------|-----------|-----------------|
@@ -92,7 +92,7 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
 Notes:
 
 - Raw review bundle: `{SDD_DIR}/review/` (ephemeral; do not rely on it after Done).
-- Open residual SSOT: `{HARNESS_DIR}/status.json` root `residual_findings[<plan-id>]`.
+- Open residual SSOT: `{PROJECT_DIR}/<id>/residuals.json` `entries[<plan-id>]` (default `{HARNESS_DIR}/projects/<id>/`).
 
 ## Compound Round Summary
 

package/harness-skills/mstar-iteration/references/phase-2-worktree-lease.md

@@ -1,9 +1,11 @@
 # Phase 2 control worktree + execution lease
 
-Normative field names and claim/release/merge semantics → runtime SSOT
-`mstar-plan-artifacts/references/status-and-residuals.md`. This reference is
-the **iteration-command execution checklist**; do not invent alternate lease
-field names.
+Normative field names → field SSOT
+`mstar-plan-artifacts/references/status-and-residuals.md`; the **full lease
+protocol prose** (single canonical copy) → `mstar-engine-legacy/references/lease-protocol.md`
+(engine-absent fallback). This reference is the **iteration-command execution
+checklist** — do not invent alternate lease field names; do not re-state the
+full protocol here.
 
 ## When it applies
 
@@ -27,16 +29,17 @@ starts at **Phase 2 entry**.
    PM-designated path) checked out to that `spec_integration_branch`.
 3. Verify `git branch --show-current` equals `spec_integration_branch`; working
    tree clean before merge operations.
-4. Record canonical absolute repository-root path in
-   `metadata.control_worktree_path` (not `{HARNESS_DIR}`; canonicalize symlinks).
+4. Record canonical absolute repository-root path in the workflow
+   snapshot top-level `control_worktree_path` (not `{HARNESS_DIR}`; canonicalize symlinks).
 5. Resolve coordination paths from that root (default-gitignored process artifacts live on the **control filesystem**, not as Git blobs):
-   - status SSOT: `<control_worktree_path>/{HARNESS_DIR}/status.json`
+   - status register: `<control_worktree_path>/{HARNESS_DIR}/status.json` (v2 root — active workflow entries)
+   - snapshot SSOT: `<control_worktree_path>/{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases + branch anchors)
+   - project register: `<control_worktree_path>/{PROJECT_DIR}/<id>/residuals.json`
    - plans SSOT: `<control_worktree_path>/{PLAN_DIR}/` (or `<control>/{HARNESS_DIR}/plans/`)
    - iterations SSOT: `<control_worktree_path>/{ITERATION_DIR}/`
    - SDD tree: `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`
-   - also under control harness root when used: `notes.json`, `archived/`
 
-All sessions MUST reread the **control copy** of `status.json` immediately before
+All sessions MUST reread the **control copy** of the workflow snapshot immediately before
 claim, release, transfer, plan-status transition, or merge-lease mutation.
 
 **Do not** set `Worktree mode: waived` because a feature worktree lacks
@@ -48,37 +51,45 @@ control **`Plan Path`** / **`SDD dir`** in Assignments
 
 All control-path lease mutations (claim, release, transfer, merge-lease
 claim/release) **MUST** run inside a same-host exclusive write lock for the full
-read-check-replace-verify sequence. Prefer `flock` on
-`{HARNESS_DIR}/.status-write.lock`; alternative: atomic `mkdir` on
-`{HARNESS_DIR}/.status-write.lockdir/`. Do **not** invent a distributed CAS CLI.
+read-check-replace-verify sequence. Engine writers acquire the lock
+automatically (`writeWorkflowSnapshot` / `registerWorkflow` use
+`<status-file dir>/.status-write.lockdir/` — for snapshots the lockdir lands
+inside `workflows/<id>/`); for manual edits prefer the engine-check commands
+(`mstar lease verify --workflow <id>`, `mstar worktree check`) over hand-rolled
+`flock`. The atomic-mkdir alternative (`.status-write.lockdir/` in the same
+directory as the file) remains the documented fallback. Do **not** invent a
+distributed CAS CLI.
 
 **Cross-plan parallel hard gate:** Applies **whether or not** `Worktree mode: waived`.
 Lease-gated **cross-plan parallel** writable implement is allowed **only when**
-this same-host lock is **available on the coordination `status.json` path and
-used for every status/coordination mutation** in that Phase 2 session (control
-path when lease gate active; primary checkout `{HARNESS_DIR}/status.json` when
-waived). Agents on **different hosts** or with **no shared flock/lockdir** →
+this same-host lock is **available on the coordination snapshot path and
+used for every coordination mutation** in that Phase 2 session (control path
+when lease gate active; primary checkout `{HARNESS_DIR}/status.json` + snapshot
+when waived). Agents on **different hosts** or with **no shared flock/lockdir** →
 default **`Plan parallelism: serial`** (preferred when waived). **No flock
 does not waive** control worktree / feature worktree / leases — serial
 scheduling only. Assignment still
 claiming cross-plan parallel without lock availability → **Blocked** until PM
 sets serial scheduling or the user gives current-turn override
-`Cross-host lease race: accepted` (or equivalent) + audit on `plans[].notes`.
+`Cross-host lease race: accepted` (or equivalent) + audit on snapshot plan
+`notes` / `notes.jsonl`.
 **`Worktree mode: waived` alone is not** this override.
 
-Immediately before **any** writable implement dispatch, re-read control
-`status.json` and re-verify `execution_lease` holder + paths match this session;
+Immediately before **any** writable implement dispatch, re-read the control
+snapshot and re-verify `execution_lease` holder + paths match this session;
 mismatch → **STOP**.
 
+> **Engine check (when available):** run `mstar lease verify --workflow <id> [--plan <plan-id>]` or `mstar lease verify-integration --workflow <id>` (or import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook) to validate the leases on the control copy of the workflow snapshot. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
 ## Feature worktree (per plan)
 
 - Each concurrently active plan uses a **distinct** absolute feature-worktree
   path and dedicated feature branch from `spec_integration_branch`.
 - `execution_lease.worktree_path` MUST differ from
-  `metadata.control_worktree_path` (never reuse the control checkout for product
+  `control_worktree_path` (never reuse the control checkout for product
   edits).
-- `Worktree path` MUST appear in the writable Assignment and in
-  `plans[].execution_lease.worktree_path` before first writable implement dispatch.
+- `Worktree path` MUST appear in the writable Assignment and in the snapshot
+  plan row's `execution_lease.worktree_path` before first writable implement dispatch.
 - Product/source edits run from the feature worktree; plans, iterations,
   status, and SDD coordination reads/writes run through **absolute control
   paths** (never relative `.mstar/...` from the feature cwd when L1 is active).
@@ -87,20 +98,21 @@ mismatch → **STOP**.
 - Default **L1**: one writable track per plan. Within-plan multi-writable tracks
   still follow L2 `parallel-writable-pre-dispatch` (`mstar-branch-worktree`).
 
-## Execution lease (`plans[].execution_lease`)
+## Execution lease (`plans[].execution_lease` in the workflow snapshot)
 
 Required shape (v1): `holder`, `claimed_at` (RFC 3339 UTC with `Z`),
 `worktree_path`, `working_branch`; optional `session_label` (display only).
+Lives on the snapshot plan row — `{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]`.
 
 ### Claim (before `InProgress` or writable dispatch)
 
-1. Read control `status.json`; locate exactly one plan row (`id` or `plan_id`).
+1. Read the control snapshot; locate exactly one plan row (`id` read compatibility).
 2. If `execution_lease` exists:
    - **Same `holder` as this session** → **resume**: verify `worktree_path` and
      `working_branch` match the Assignment; continue (not steal/block).
    - **Different `holder`** → **Blocked** (no timestamp makes it stealable).
 3. Create or verify dedicated feature worktree + branch.
-4. Re-read `status.json` under write lock; if row/status/lease changed, restart claim.
+4. Re-read the snapshot under write lock; if row/status/lease changed, restart claim.
 5. One complete-file update (still under lock): `status: "InProgress"` + full `execution_lease`.
    Use temp file + atomic replace; never expose partial JSON.
 6. Re-read and verify `holder`, `worktree_path`, `working_branch` match before
@@ -110,18 +122,18 @@ Required shape (v1): `holder`, `claimed_at` (RFC 3339 UTC with `Z`),
 
 - Lease stays active across `InProgress` and `InReview` (including post-QC/QA
   ready-to-merge) unless released or transferred.
-- Normal release: re-read control `status.json` under write lock; confirm stored `holder` matches
+- Normal release: re-read the control snapshot under write lock; confirm stored `holder` matches
   this session — mismatch → **Blocked**; then **delete** `execution_lease`
   (never `null` or tombstone).
 - `Done` authority deletes `execution_lease` in the same update as `status: "Done"`
   — **only after** successful integration merge (when lease gate not waived).
 - Override of another holder requires **explicit user instruction this turn** +
-  audit note on plan `notes` (prior holder, new holder/release, user authorized).
+  audit note on snapshot plan `notes` / `notes.jsonl` (prior holder, new holder/release, user authorized).
 - V1: **manual release only** — no `expires_at`, TTL, or heartbeat authority.
 
 ### Orphan `InProgress` without lease
 
-If a plan row is `InProgress` but has **no** `execution_lease`, STOP and
+If a plan row is `InProgress` but has **no** `execution_lease` in the snapshot, STOP and
 escalate — do not invent a lease or writable-dispatch. Unattended "Recover with
 claim" is permitted **only** for the **same** stable `holder`; different holder
 requires verified quiescence + handoff or current-turn user override + audit.
@@ -135,26 +147,27 @@ waived` is in effect — waiver does **not** authorize lockless cross-host paral
 - **Feature implementation** MAY proceed in parallel across **different plan IDs**
   only when **one** of:
   1. Same-host exclusive write lock is available on the coordination
-     `status.json` path (control path when lease gate active; primary checkout
-     `{HARNESS_DIR}/status.json` when waived) and used for every status/coordination
+     snapshot path (control path when lease gate active; primary checkout
+     `{HARNESS_DIR}/status.json` + snapshot when waived) and used for every coordination
      mutation in that session; **and** when lease gate is not waived, each plan
      holds a verified, distinct `execution_lease` and feature worktree.
   2. **`Plan parallelism: serial`** (default when waived; preferred default under
      waiver).
   3. Current-turn `Cross-host lease race: accepted` (or equivalent) + audit
-     `plans[].notes`.
+     snapshot plan `notes` / `notes.jsonl`.
   Cross-host / no shared lock without (2) or (3) → **Blocked** if Assignment still
   claims cross-plan parallel writable implement.
 - **Integration merge** into `spec_integration_branch` is **serial** (one at a time),
   with or without lease gate.
 
-## Integration merge lease (`metadata.integration_merge_lease`)
+## Integration merge lease (snapshot top-level `integration_merge_lease`)
 
 Required shape (v1): `holder`, `claimed_at`, `plan_id`, `source_branch`,
 `target_branch` (= resolved `spec_integration_branch`); optional `session_label`.
+Lives top-level on the snapshot — `{WORKFLOW_DIR}/<id>/snapshot.json`.
 
 1. From control worktree: clean tree; branch = `spec_integration_branch`.
-2. Under write lock, reread root `metadata`. If `integration_merge_lease` exists:
+2. Under write lock, re-read the snapshot. If `integration_merge_lease` exists:
    - **Same `holder` as this session** → **resume**: verify `plan_id`,
      `source_branch`, `target_branch` match intended merge; confirm control
      worktree state; continue (not steal/block).
@@ -176,16 +189,15 @@ waives **only**:
 
 - Control worktree establishment and control-path SSOT routing
 - Per-plan feature worktree defaults
-- `plans[].execution_lease` and `metadata.integration_merge_lease` claim/hold/release
-  defaults
+- Snapshot lease claim/hold/release defaults (`plans[].execution_lease` and top-level `integration_merge_lease`)
 
 It does **not** waive the **cross-plan parallel safety gate**. Under waiver,
 cross-plan **parallel writable** implement still requires same-host exclusive
-write lock on the coordination `status.json` path, default **`Plan parallelism:
+write lock on the coordination snapshot path, default **`Plan parallelism:
 serial`**, or current-turn `Cross-host lease race: accepted` + audit
-`plans[].notes`. **Prefer serial scheduling when waived**; parallel under waiver
+snapshot plan `notes` / `notes.jsonl`. **Prefer serial scheduling when waived**; parallel under waiver
 only with the race-accepted override (or same-host lock when mutating shared
-status).
+state).
 
 `Plan parallelism: serial` does **not** waive control worktree or leases.
 

package/harness-skills/mstar-iteration/references/phase-3-iteration-close.md

@@ -2,7 +2,7 @@
 
 > Loaded by `mstar-iteration` SKILL.md when entering Phase 3. **Read `mstar-harness-core` first.** Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入本 Phase。
 
-PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支上运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 root `metadata.target_branch`。入口：Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入。
+PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支上运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 snapshot `branch.target`（`target_branch`）。入口：Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入。
 
 **Close Done 定义**：§3.1→§3.5 全部完成；compass frontmatter 写入 `status: completed` + `end_date`；每篇新增 knowledge doc 已登记 `{KNOWLEDGE_DIR}/README.md`。只在 final plan 中写了 compound / roadmap / PR 说明，不算 iteration-close 完成。
 
@@ -30,9 +30,9 @@ PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支
 
 **STOP**: 打印下方 checklist，且全部为 `[x]` 后，才可进入 §3.2 Compound。
 
-- [ ] 所有 compass 中登记的 plan 在 `{HARNESS_DIR}/status.json` 均为 `Done`
-- [ ] 所有 plan 的 residual findings 已收口：优先 empty open 列表；若仍有 open R#，须均为 Phase 2 `zero-residual` 允许的 blocker-defer + roadmap，或已 closed/accepted/waived 归档（见 `mstar-plan-artifacts` Findings cleanup modes）
-- [ ] compass `## Plans` 表状态列已与 `status.json` 同步
+- [ ] 所有 compass 中登记的 plan 在 workflow snapshot（`{WORKFLOW_DIR}/<id>/snapshot.json`）均为 `Done`
+- [ ] 所有 plan 的 residual findings 已收口：优先 empty register 条目（`projects/<id>/residuals.json` → `entries[<plan-id>]`）；若仍有 open R#，须均为 Phase 2 `zero-residual` 允许的 blocker-defer + roadmap，或已 closed（`lifecycle` / `closed_at` / `closure_note`，见 `mstar-plan-artifacts` Findings cleanup modes）
+- [ ] compass `## Plans` 表状态列已与 snapshot 同步
 - [ ] 迭代 `## Acceptance Criteria` 已达成或显式豁免（compass 或对话记录原因）
 - [ ] compass shape 已满足（frontmatter + `## Roadmap Position` + close 占位节）
 
@@ -57,7 +57,7 @@ PM 批量触发后须：
 1. 更新 compass **`## Roadmap Position`**（§3.0.5 已确保本节存在）：
    - current iteration 行标记为 **`delivered`**（或等价明确措辞）
    - next iteration 更新为即将开始的内容、触发条件、owner
-2. 若 `status.json` 中有 `plans[].metadata.roadmap` 字段，同步更新
+2. 若项目层 roadmap（`{PROJECT_DIR}/<id>/roadmap.md`）存在，同步更新（frontmatter `status` / goal-item checkboxes）；若 snapshot plan 行含 `metadata.roadmap` 字段，同步更新
 3. 若存在 deferred-features / roadmap tracker 类文档，按项目惯例刷新
 4. 若 `STRATEGY.md` 存在，可更新 `## Decision Log`（重大架构决策时）
 
@@ -78,7 +78,7 @@ PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git co
 - [ ] §3.3 `## Roadmap Position` current iteration 已标 `delivered`；tracker / STRATEGY 已按需更新
 - [ ] §3.4 frontmatter `status: completed` + `end_date`；Quality Gate Summary + Compound Summary + Retrospective 已填
 - [ ] 当前分支是 `spec_integration_branch`
-- [ ] PR base = `metadata.target_branch`（与 compass frontmatter 一致）；**不是**未记录的 `main`
+- [ ] PR base = snapshot `branch.target`（`target_branch`，与 compass frontmatter 一致）；**不是**未记录的 `main`
 
 **Commit 到 integration 分支**：
 
@@ -88,7 +88,7 @@ git commit -m "chore(iteration): close <iteration-id> — compound round, roadma
 git push origin <spec_integration_branch>
 ```
 
-PR 目标使用 root `metadata.target_branch`；缺失时停止并补齐，不得默认 `main`。
+PR 目标使用 snapshot `branch.target`；缺失时停止并补齐，不得默认 `main`。
 
 ## 3.6 可选：触发 compound-refresh
 

package/harness-skills/mstar-iteration/references/phase-4-5-pr-delivery.md

@@ -7,7 +7,7 @@
 **Precondition**: Phase 3 §3.5 exit 全 `[x]`；close commit 已 push 到 `spec_integration_branch`。
 
 1. 打印 **`## Phase 4: PR delivery`**
-2. Resolve target：`metadata.target_branch`（compass frontmatter 镜像）；缺失 → **STOP**，问用户
+2. Resolve target：snapshot `branch.target`（`target_branch`；compass frontmatter 镜像）；缺失 → **STOP**，问用户
 3. 创建 PR：`spec_integration_branch` → `target_branch`
 4. 记录 PR URL / number（Phase 5 会话 SSOT）
 5. **Immediately** 进入 **Phase 5** — **Phase 4 exit ≠ 迭代交付完成**
@@ -24,7 +24,7 @@
 
 - Phase 5 在 PR head（`spec_integration_branch`）上 push 修复；**禁止**另开替代分支
 - **Checkout / worktree（HARD）**：Phase 5 是 PR 级 **hotfix** loop，**不是** Phase 2 plan 实现。修复直接在 **control worktree**（已检出 `spec_integration_branch` 的 checkout）上编辑、commit、再按 §5.1a push。**禁止**为 Phase 5 另开 feature / fix worktree；**禁止**把 Phase 2「control 禁止产品编辑 / 须 feature worktree」套用到 Phase 5。另开 worktree 浪费时间、磁盘与计算，与 Phase 5 快速收敛 CI/review 的目标相悖。
-- 产品代码修复 → PM **dispatch** dev/ops（`mstar-dispatch-gates`）；Assignment **`Worktree path`** / cwd = control（`metadata.control_worktree_path` 或当前已在集成分支上的 checkout）；PM 线程不代写实现
+- 产品代码修复 → PM **dispatch** dev/ops（`mstar-dispatch-gates`）；Assignment **`Worktree path`** / cwd = control（snapshot `control_worktree_path` 或当前已在集成分支上的 checkout）；PM 线程不代写实现
 - 禁止为「让 CI 变绿」而改 workflow，除非用户明确授权
 - **Push cadence** → **§5.1a**（本地可提前修；**禁止**在 CI / AI review 波次未结束时 push）
 

package/harness-skills/mstar-phase-gates/SKILL.md

@@ -74,12 +74,12 @@ per-plan 门禁通过后，PM 在**迭代层面**管理以下活动（不计入
 
 per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动，不影响 per-plan 状态判定。
 
-> **Engine check (when available):** run `mstar iteration gate --status <status.json> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the iteration phase-transition gate (Phase 2 → 3 → 4) when iteration-level activities above are reached — per-plan Prepare/Execute gate judgment stays prompt. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar iteration gate --workflow <id> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the iteration phase-transition gate (Phase 2 → 3 → 4) against the workflow snapshot when iteration-level activities above are reached — per-plan Prepare/Execute gate judgment stays prompt. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ## Plan 目录与审查证据（启用 `{PLAN_DIR}` 时）
 
-- 进入 `InReview` 后，QC/QA 原始过程报告默认落入 `{SDD_DIR}/review/`（**SDD 默认 tri** `qc1`…`qc-consolidated`；**inline** 单席 `qc.md`）。**fix 后默认 targeted re-review**。SDD per-task review 在 implement 波次内完成（`mstar-sdd` task reviewer）。PM 将 durable gate summary 回写主 plan / `status.json`，而不是把 raw reports 作为默认 git 产物。
-- 非阻断项与后续技术债：PM 汇总后写入 `{HARNESS_DIR}/status.json` 根级 `residual_findings[<plan-id>]`（**open**，与 `plans` 平级；canonical 见 **`mstar-plan-artifacts` SKILL.md**）；关闭后迁入 `{HARNESS_DIR}/archived/residuals/<plan-id>.json`，与 `mstar-review-qc` 一致。每条 **`severity`** 遵守 **`mstar-plan-artifacts/references/status-and-residuals.md`**「Residual findings：severity（SSOT，机器字段）」。
+- 进入 `InReview` 后，QC/QA 原始过程报告默认落入 `{SDD_DIR}/review/`（**SDD 默认 tri** `qc1`…`qc-consolidated`；**inline** 单席 `qc.md`）。**fix 后默认 targeted re-review**。SDD per-task review 在 implement 波次内完成（`mstar-sdd` task reviewer）。PM 将 durable gate summary 回写主 plan / workflow snapshot，而不是把 raw reports 作为默认 git 产物。
+- 非阻断项与后续技术债：PM 汇总后写入 project register `{PROJECT_DIR}/<id>/residuals.json` → `entries[<plan-id>]`（**open**，默认 `{HARNESS_DIR}/projects/<id>/`；canonical 见 **`mstar-plan-artifacts` SKILL.md**）；关闭时在 register 内 **in place** 置 `lifecycle` / `closed_at` / `closure_note`，与 `mstar-review-qc` 一致。每条 **`severity`** 遵守 **`mstar-plan-artifacts/references/status-and-residuals.md`**「Residual findings：severity（SSOT，机器字段）」。
 
 ## 快速判定（PM）