@mstar-harness/dsh 3.9.3 → 3.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/dist/gates/dispatch.d.ts +9 -3
  2. package/dist/index.js +734 -351
  3. package/harness-commands/iteration-drive.md +16 -2
  4. package/harness-skills/mstar-artifacts/SKILL.md +10 -6
  5. package/harness-skills/mstar-artifacts/references/plan-files-and-reports.md +1 -1
  6. package/harness-skills/mstar-artifacts/references/plan-quality-bar.md +10 -0
  7. package/harness-skills/mstar-artifacts/references/plan-workflow-lifecycle-contract.md +115 -0
  8. package/harness-skills/mstar-artifacts/references/status-and-residuals.md +85 -12
  9. package/harness-skills/mstar-artifacts/templates/plan.main.md +6 -1
  10. package/harness-skills/mstar-branch-worktree/SKILL.md +5 -4
  11. package/harness-skills/mstar-compound/SKILL.md +4 -4
  12. package/harness-skills/mstar-conventions/SKILL.md +1 -0
  13. package/harness-skills/mstar-conventions/references/effort-estimation.md +2 -0
  14. package/harness-skills/mstar-dispatch-gates/SKILL.md +11 -2
  15. package/harness-skills/mstar-harness-core/SKILL.md +2 -2
  16. package/harness-skills/mstar-host/SKILL.md +9 -2
  17. package/harness-skills/mstar-host/references/_shared/plan-mode-bridge-core.md +2 -0
  18. package/harness-skills/mstar-host/references/codex.md +1 -1
  19. package/harness-skills/mstar-host/references/dsh.md +14 -4
  20. package/harness-skills/mstar-host/references/omp.md +62 -2
  21. package/harness-skills/mstar-iteration/SKILL.md +13 -1
  22. package/harness-skills/mstar-iteration/references/command-shared-invariants.md +6 -0
  23. package/harness-skills/mstar-iteration/references/phase-1-prepare.md +2 -0
  24. package/harness-skills/mstar-iteration/references/phase-2-worktree-lease.md +121 -15
  25. package/harness-skills/mstar-iteration/references/phase-3-iteration-close.md +3 -3
  26. package/harness-skills/mstar-iteration/references/phase-4-5-pr-delivery.md +3 -2
  27. package/harness-skills/mstar-iteration/references/phase-6-post-merge-close.md +5 -2
  28. package/harness-skills/mstar-iteration/references/plan-scoped-pm.md +181 -0
  29. package/harness-skills/mstar-phase-gates/SKILL.md +7 -5
  30. package/harness-skills/mstar-project-governance/SKILL.md +3 -3
  31. package/harness-skills/mstar-review-qc/SKILL.md +4 -4
  32. package/harness-skills/mstar-review-qc/references/review-responsibility-boundaries.md +1 -1
  33. package/harness-skills/mstar-roles/references/_shared/leaf-executor-core.md +1 -0
  34. package/harness-skills/mstar-roles/references/project-manager/dispatch-and-assignment.md +12 -2
  35. package/harness-skills/mstar-roles/references/project-manager/plan-management.md +15 -0
  36. package/harness-skills/mstar-roles/references/project-manager/qa-trigger-matrix.md +3 -3
  37. package/harness-skills/mstar-roles/references/project-manager/qc-and-residuals.md +7 -5
  38. package/harness-skills/mstar-roles/references/project-manager.md +12 -4
  39. package/harness-skills/mstar-sdd/SKILL.md +8 -3
  40. package/harness-skills/mstar-sdd/references/file-handoffs.md +1 -0
  41. package/harness-skills/mstar-sdd/references/implementer-continuation-prompt.md +4 -1
  42. package/harness-skills/mstar-sdd/references/implementer-prompt.md +4 -0
  43. package/harness-skills/pm/SKILL.md +2 -0
  44. package/package.json +1 -1
@@ -2,7 +2,7 @@
2
2
  name: iteration-drive
3
3
  description: Drive the active iteration to completion — Phase 2 Autonomous Execute, Phase 3 iteration-close, Phase 4 Create PR, Phase 5 PR merge-ready loop (prefer babysit/*-babysit; optional greploop when repo has it; else CI fallback) until mergeable, then Phase 6 post-merge close once the PR is verified merged. Not Done until Phase 6 close completes.
4
4
  agent: project-manager
5
- input: "[no args]"
5
+ input: "[no args] | --assignment <absolute-md-path> | --workflow <id> --plan <id> | --resume <absolute-session-json-path>"
6
6
  ---
7
7
 
8
8
  # Drive Iteration
@@ -15,14 +15,28 @@ Drive the active Morning Star iteration forward. **Boot loads skills; this comma
15
15
 
16
16
  **Done 定义**:Phase 5 §5.5 exit checklist 全 `[x]` **且** PR merged 后 Phase 6 §6.1–§6.4 完成。**Phase 3 close ≠ Done;Phase 4 开 PR ≠ Done;§5.5 exit / PR merged ≠ Done。**
17
17
 
18
+ **Scoped route 的 Done 边界**:plan 会话的 finish 是 **durable handoff**(plan 保持 `InReview`、保留 `execution_lease`);`status: Done` 与两个 lease 的删除由 **coordinator** 在验证 Git 合并后**同一次** snapshot 写入中完成。Phase 3–6 与 PR 仍归 coordinator → **`references/plan-scoped-pm.md`** §5–§6。
19
+
18
20
  ## 共享 invariants / preflight / todos / STOP
19
21
 
20
- Phase 2–5 共享内容(PM invariants、assignment preflight、session todos、continuous-execution STOP)→ **`mstar-iteration/references/command-shared-invariants.md`**(SSOT;不在本命令重复)。
22
+ Phase 2–5 共享内容(PM invariants、assignment preflight、session todos、continuous-execution STOP)→ **`mstar-iteration/references/command-shared-invariants.md`**(SSOT;不在本命令重复)。**Scoped route(下节)例外**:其 session todos / STOP 为 plan-local,不 seed 全局 phase 条目 → **`references/plan-scoped-pm.md`**。
23
+
24
+ ## Route(先于 Boot 判定)
25
+
26
+ | 调用形态 | 走向 |
27
+ |---|---|
28
+ | **无参数** | 下方 Boot → Phase 2 → 3 → 4 → 5 → 6(**语义不变**) |
29
+ | `--assignment <绝对 md 路径>` / `--workflow <id> --plan <id>` / `--resume <绝对 session json 路径>` | **scoped route** → **`mstar-iteration/references/plan-scoped-pm.md`**(scoped boot 先于全局 boot;不加载 compound / Phase 3–6 detail) |
30
+ | 其他任何非空参数形态(重复 flag、未知 flag、位置参数、缺值/空值、混用形态、半对 `--workflow`/`--plan`) | **fail closed**:在 bind 与 boot 之前停止并报告接受的形态;**禁止**回落为整迭代路线 |
31
+
32
+ **Leaf 边界**:leaf executor 收到本命令 → 角色边界拒绝(`mstar-dispatch-gates`),**不得**晋升为 PM 或递归分派。
21
33
 
22
34
  ## Boot
23
35
 
24
36
  按 **`mstar-iteration`** Load order 加载(`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration`(按当前 Phase 查 route map,只加载一行 detail)+ `command-shared-invariants.md` → `mstar-compound` → `mstar-dispatch-gates` + host reference → **`mstar-sdd`**(first implement dispatch 前)→ `mstar-review-qc`(first QC 前)→ `mstar-artifacts` / `mstar-conventions` / `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**)。完整 load list → **`mstar-roles`**。
25
37
 
38
+ **Scoped route 例外**:先按 **`references/plan-scoped-pm.md`** §2 建立 primary PM identity → 一次 `mstar plan bind` → `show` 并把会话约束到返回的 scope,再按本条加载;**不**加载 `mstar-compound`,也**不**加载 Phase 3–6 detail(scoped boot ≠ 整迭代 boot)。
39
+
26
40
  ## Phase 2: Autonomous Execute
27
41
 
28
42
  Execute **`mstar-iteration/references/phase-2-worktree-lease.md`** §2.0–§2.5 exactly(§2.0 五道闸 → §2.1 session todos → §2.2 backlog → §2.3 integration branch + control worktree → §2.4 per-plan loop(lease-gated;SDD independent ready tasks parallel with isolation;changed-scope QC tri N=3 + unit-only QA;serial merge)→ §2.5 dispatch-first;§2.6 push 纪律 → main skill `## 2.6`)。全部 plan `Done` → **STOP** → 打印 `## Phase 3: iteration-close`。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mstar-artifacts
3
- description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and durable review summaries, `{SDD_DIR}/review/` ephemeral QC/QA bundles, `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` indexes, plus `{HARNESS_DIR}/status.json` (v2 root register) / `{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases) and `{PROJECT_DIR}/<id>/residuals.json` (residual register; severity SSOT, open/close lifecycle). Read when writing plans or QC/QA review bundles, maintaining knowledge/iteration indexes, reading or writing status/snapshot/register, or mapping QC severity to JSON. Required for `@project-manager` on status, residuals, and InReview/QC waves; `@qc-specialist*` before writing review bundle reports; `@qa-engineer` before closing R# when `QA gate: mandatory`. Verdict rules: leaf → `mstar-roles/references/qc-specialist/report-template.md`; PM → `mstar-review-qc`."
3
+ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and durable review summaries, `{SDD_DIR}/review/` ephemeral QC/QA bundles, `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` indexes, plus `{HARNESS_DIR}/status.json` (v2 root register) / `{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases + plan-scoped `coordination`/session/handoff/revision semantics) and `{PROJECT_DIR}/<id>/residuals.json` (residual register; severity SSOT, open/close lifecycle). Read when writing plans or QC/QA review bundles, maintaining knowledge/iteration indexes, reading or writing status/snapshot/register, or mapping QC severity to JSON. Required for `@project-manager` on status, residuals, and InReview/QC waves; `@qc-specialist*` before writing review bundle reports; `@qa-engineer` before closing R# when `QA gate: mandatory`. Verdict rules: leaf → `mstar-roles/references/qc-specialist/report-template.md`; PM → `mstar-review-qc`."
4
4
  ---
5
5
 
6
6
  ## Load order
@@ -14,7 +14,8 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
14
14
  | Main plan, review bundle naming, durable summaries, QC waves, residual and plan index order | `references/plan-files-and-reports.md` |
15
15
  | Plan template (Global Constraints, Interfaces) | `templates/plan.main.md` |
16
16
  | knowledge / iterations / specs boundaries and indexes | `references/knowledge-and-designs.md` |
17
- | `status.json` (v2 root), workflow snapshots, project register, residual severity / lifecycle, engine-check queries | `references/status-and-residuals.md` |
17
+ | `status.json` (v2 root), workflow snapshots, plan-scoped `coordination` / session / handoff / revision schema, project register, residual severity / lifecycle, engine-check queries | `references/status-and-residuals.md` |
18
+ | Plan-level workflow lifecycle: delivery-kind declaration, stages, evidence contracts, engine seams | `references/plan-workflow-lifecycle-contract.md` |
18
19
  | Empty-repo `status.json` template | `templates/status.empty.json` (`templates/README.md`) |
19
20
  | Tech-debt rollup (read-only) | `mstar status tech-debt [path]` (engine `techDebtRollup`; see `references/status-and-residuals.md`) |
20
21
 
@@ -32,12 +33,13 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
32
33
  - **Fail-loud handoff**: findings must pass `validateResidual` (per entry) / `validateProjectRegister` (register) before registration; snapshots and the v2 root pass `validateWorkflowSnapshot` / `validateStatus` (`mstar status validate`); malformed → reject + rewrite → **`references/status-and-residuals.md`** (“Fail-loud handoff contract”).
33
34
  - **Lifecycle**: open → verified close **in place** in the register (`lifecycle` / `closed_at` / `closure_note`); machine **`severity`** enum in reference. v1 `archived/residuals/` + `archive-residuals` are retired.
34
35
 
35
- - **Findings cleanup**: Assignment **`Findings cleanup: zero-residual | allow-residual`** (the `metadata.findings_cleanup` mirror is deleted); iteration Phase 2 defaults to **`zero-residual`** → **`references/status-and-residuals.md`** (“Findings cleanup modes”).
36
+ - **Findings cleanup**: Assignment **`Findings cleanup: zero-residual | allow-residual`** (the `metadata.findings_cleanup` mirror is deleted); iteration Phase 2 defaults to **`allow-residual`** (register + disclose duties apply) → **`references/status-and-residuals.md`** (“Findings cleanup modes”).
36
37
 
37
38
  > **Engine check (when available):** run `mstar status findings-cleanup <plan-id> [--project <id>] [--mode zero-residual|allow-residual]` (or import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook) to enforce the Findings cleanup mode above against the plan's register entries. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
38
39
 
39
40
  - **`{WORKFLOW_DIR}/<id>/notes.jsonl`**: per-workflow append-only notes ledger (runtime); snapshot plan-row `notes` is the legacy verbatim copy. **Tech-debt rollup**: `mstar status tech-debt <project-dir>` over the project registers — **`references/status-and-residuals.md`**.
40
41
  - **Iteration Phase 2 leases** (snapshot: `integration_worktree_path`, `plans[].execution_lease`, top-level `integration_merge_lease`): field semantics → **`references/status-and-residuals.md`** (“Iteration execution leases”); Phase 2 execution checklist → **`mstar-iteration`** `references/phase-2-worktree-lease.md`; full protocol prose (single copy) → **`mstar-engine-legacy`** `references/lease-protocol.md`.
42
+ - **Plan-scoped coordination is a domain-call surface**: plan-row `coordination` block (`prepared` / `revision` / `duplicate-holder`), session JSON, handoff record, and `--expect <revision>` semantics have their **single runtime home** in **`references/status-and-residuals.md`**; flag shapes and exit codes → `docs/cli.md`; route semantics → **`mstar-iteration`** `references/plan-scoped-pm.md`. Every plan-row mutation goes through the verbs (`mstar plan bind | show | prepare | progress | residual-add | residual-close | handoff | accept | return | integration-start | integration-accept | complete | reconcile`) — hand-editing snapshot rows or the register outside those verbs is **not** an authorized path.
41
43
 
42
44
  > **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 iteration leases above on the workflow 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.
43
45
 
@@ -47,13 +49,14 @@ Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq
47
49
 
48
50
  ## Workflow
49
51
 
50
- 产物生命周期主链:主 plan 落盘 `{PLAN_DIR}`(命名见 `references/plan-files-and-reports.md`)→ 实现推进时更新 workflow snapshot(`workflows/<id>/snapshot.json` 的 `plans[]` 行 + 根 `status.json` `workflows[]` 登记)→ 审查波次产出 `{SDD_DIR}/review/` bundle(raw QC/QA reports)+ durable gate summary 回写主 plan / snapshot → 关闭后 residual **in place** close in the project register(`projects/<id>/residuals.json`)。索引(`{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{PLAN_DIR}`)随产物更新。
52
+ 产物生命周期主链:主 plan 落盘 `{PLAN_DIR}`(命名见 `references/plan-files-and-reports.md`)→ 实现推进时经 **domain call** 更新 workflow snapshot 的 `plans[]` 行(scoped 路线:`mstar plan progress | handoff | complete --session <session.json> [--expect <revision>]`;直接文件编辑仅限 CLI 缺失的 legacy 路线),根 `status.json` `workflows[]` 的登记/注销由生命周期动词负责(如 `mstar status workflow-close`)→ 审查波次产出 `{SDD_DIR}/review/` bundle(raw QC/QA reports)+ durable gate summary 回写主 plan / snapshot → 关闭后 residual **in place** close in the project register(`projects/<id>/residuals.json`)。索引(`{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{PLAN_DIR}`)随产物更新。
51
53
 
52
54
  ## Decision Rules
53
55
 
54
56
  - residual **severity** 是机器字段 SSOT(`references/status-and-residuals.md`);每条新 finding 只登记 project register(`projects/<id>/residuals.json` → `entries[<plan-id>]`),v1 根级 `residual_findings` 仅 legacy 只读,**禁止**双写。
55
- - **`Findings cleanup: zero-residual`** 默认(迭代 Phase 2):可修 findings 当轮 fix → re-review 清干净;仅真 blocker 可 defer 且须 Durable Roadmap。
57
+ - **`Findings cleanup: allow-residual`** 默认(迭代 Phase 2):open R# 先登记 project register,且各决策面披露(清单 + severity + 跟踪位置;close 面另含 blocker-defer 标记);unresolved `critical` 仍阻断 Approve;`zero-residual` 为显式 opt-in —— 细则 → **`references/status-and-residuals.md`**「Findings cleanup modes」。
56
58
  - 登记前必须过 `validateResidual` / `validateProjectRegister` / `validateStatus`(fail-loud handoff);malformed → reject + rewrite。
59
+ - **计划行 / register 只经 domain call 修改**:scoped 路线使用 `mstar plan …` 动词(带 `--session` 与 `--expect`),手写 snapshot / register 会被拒(`coordination.direct-write-refused` / `coordination.scoped-writer-required`);只读校验器(`mstar lease verify` / `mstar worktree check`)是检查而非修改替代。
57
60
 
58
61
  ## Evidence
59
62
 
@@ -62,5 +65,6 @@ Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq
62
65
  ## References
63
66
 
64
67
  - `references/plan-files-and-reports.md` — 主 plan / review bundle 命名、QC 波次、durable summaries
65
- - `references/status-and-residuals.md` — `status.json` (v2), workflow snapshots, project register, residual severity / lifecycle / engine-check queries
68
+ - `references/status-and-residuals.md` — `status.json` (v2), workflow snapshots, plan-scoped coordination (bind / revision / session / handoff / reconcile), project register, residual severity / lifecycle / engine-check queries
66
69
  - `references/knowledge-and-designs.md` — knowledge / iterations / specs 边界与索引
70
+ - `references/plan-workflow-lifecycle-contract.md` — plan-level workflow lifecycle contract: delivery-kind declaration, stages, evidence contracts, engine seams
@@ -42,7 +42,7 @@ Raw bundle files may disappear after the working context is gone. Before Done, P
42
42
  - `Review bundle`: `{SDD_DIR}/review/`
43
43
  - `QC inputs`: `qc1.md` / `qc2.md` / `qc3.md` or `qc.md`
44
44
  - `Blocking result`: fixed / none / deferred with reason
45
- - `Residual findings`: R# ids + short titles + owner/target
45
+ - `Residual findings`: each open R# — id + short title + severity + tracking location (register `entries[<plan-id>]`) + owner/target + blocker-defer flag (`N/A — none open` when none)
46
46
  - Main plan `## QA Gate Summary` when QA applies:
47
47
  - `QA gate` / `QA mode`
48
48
  - evidence reused vs newly run checks
@@ -76,6 +76,15 @@ Do not add repository-wide build/test/lint/typecheck gates for insurance. Full s
76
76
 
77
77
  "Works correctly" is not a done criterion.
78
78
 
79
+ ### 7. Task shape / session fit
80
+
81
+ Each task fits **one focused implementer round** — the round closes the task's declared Files list and verification gates, not a slice of them:
82
+
83
+ - **Effort (agent-oriented)** — every task cites its band from the existing XS–XL scale (`mstar-conventions/references/effort-estimation.md`). A size estimate and a one-round closure assertion are distinct: a multi-session band never authorizes a multi-round task — split until each task can close its own Files and gates.
84
+ - **Named split point** — every task states where it breaks if one-round closure fails, so PM can split without re-deriving the boundary.
85
+ - **Split strategies** — apply the review split shapes (`mstar-audit/references/pr-review.md` § Sizing & change shape) to task boundaries, each slice with explicit interfaces and independent proof: stack · by file group · horizontal (shared code first) · vertical (full-stack slices). They shape task boundaries; PR line-count thresholds stay review-owned.
86
+ - **Verification is not the shock absorber** — **Budget pressure MUST NOT shorten or waive any assigned scoped verification.** If the round cannot close, stop and report for split/re-dispatch instead of cutting checks.
87
+
79
88
  ## Relationship to existing plan elements
80
89
 
81
90
  | This quality bar | Existing mstar element |
@@ -86,6 +95,7 @@ Do not add repository-wide build/test/lint/typecheck gates for insurance. Full s
86
95
  | STOP conditions | New — not previously formalized |
87
96
  | Drift check | SDD `BASE_SHA` — generalized to all plans |
88
97
  | Done criteria | `plan.main.md` per-step checkboxes — elevated to machine-checkable |
98
+ | Task shape / session fit | `plan.main.md` per-task **Effort (agent-oriented)** / **Split point** slots + `mstar-phase-gates` capacity quick-check — one-round Files-plus-gates closure per task |
89
99
 
90
100
  ## When to apply
91
101
 
@@ -0,0 +1,115 @@
1
+ # Plan workflow lifecycle contract
2
+
3
+ The authoritative semantics for plan-level workflow delivery: what a `type: plan` workflow declares at registration, the stages it walks, the evidence each stage owes, and the engine seams that enforce them (§6). Corpus surfaces cite this file pointer-level instead of restating it; where a skill's prose and this contract disagree on lifecycle semantics, this contract is the wording authority until it is formally amended.
4
+
5
+ This file owns semantics only. The `packages/engine/src/*` line ranges below are orientation, not stable anchors — re-read the module before relying on a range.
6
+
7
+ ## Foundational distinctions
8
+
9
+ Three meanings that must remain separate:
10
+
11
+ - **Standalone plan workflow:** an independently owned `type: plan` lifecycle, with its own delivery obligation and terminal close.
12
+ - **Plan row inside an iteration:** a work unit inside the iteration's existing lifecycle. Its completion does not independently create a second delivery PR obligation.
13
+ - **Plan-scoped primary PM session:** bounded execution authority that ends in handoff to its coordinator. It does not gain lifecycle authority because its role name includes PM. See `skills/mstar-iteration/references/plan-scoped-pm.md:21,62–68,95–109,145`.
14
+
15
+ Four facts that are not interchangeable: plan-row `Done`, workflow `completed`, PR opened, and PR merged are distinct facts. A workflow with completed implementation but an outstanding delivery PR must remain active and resumable.
16
+
17
+ ## 1. Delivery-kind declaration
18
+
19
+ Every workflow declares its delivery kind at registration, as part of the registration evidence (§4a). Declared kinds:
20
+
21
+ - **`development`** — the full lifecycle of §3 applies: PR submission, merge-ready milestone, verified merge, and evidence-backed terminal close. The PR obligation is the declared delivery path, not an optional extra.
22
+ - **`verification/report-only`** — an explicit alternative completion policy is recorded at registration and names what evidence completes the workflow (for example the acceptance artifacts or report location). Terminal close still runs through the same evidence-backed close ordering (§4g); only the PR/merge stages are replaced by the recorded policy.
23
+
24
+ Binding rules:
25
+
26
+ - The declared kind is recorded at registration. It is never inferred retroactively from runtime behavior, from the presence or absence of fields, or from convenience.
27
+ - Absence of `branch.target` (or of any other registration field) is not an implicit exemption. Missing fields never select a kind and never waive the declared obligation; a `development` workflow with missing branch fields is incomplete registration, not an exempt workflow.
28
+ - Verification/report-only workflows follow their recorded explicit completion policy, not an accidental PR exemption inferred from missing fields.
29
+ - An iteration uses the same outer lifecycle around its multiple plan rows (§3). Its child plan rows are not standalone workflows and gain no independent delivery PR obligation.
30
+
31
+ ## 2. Cardinality stance
32
+
33
+ - The new normal route is **one independently owned development plan per `type: plan` workflow**. A `type: plan` label alone does not establish cardinality; this contract fixes it for the new normal route only.
34
+ - **Producers.** The known multi-row `type: plan` producer is audit promotion (`promoteAuditPlans`), which constructs one plan row per selected plan file (`packages/engine/src/audit.ts:1250-1272`). Existing specialized producers are `audit promote` and `migrate`; the generic normal-entry register producer is seam S1 (§6).
35
+ - **Decision:** audit promotion is explicitly **grandfathered** as a multi-row specialized producer. No schema-level one-row invariant is imposed on the grandfathered producer; it keeps working and is not silently broken. Any future schema tightening must migrate audit promotion off the multi-row shape first, and must re-inventory producers before enforcement. Until such a migration lands, the one-plan norm governs the new normal route and new registrations, not the grandfathered producer.
36
+
37
+ ## 3. Lifecycle stages
38
+
39
+ The common delivery lifecycle:
40
+
41
+ ```
42
+ register → recall → prepare/lock → execute + review/acceptance → compound disposition → submit PR → merge-ready (milestone) → verify merge → terminal close/unregister/reconcile
43
+ ```
44
+
45
+ | Stage | Producer | Evidence (recorded) | Failure behavior |
46
+ |---|---|---|---|
47
+ | register | PM via an authorized domain operation (seam S1) | Create-only snapshot + root `workflows[]` entry under one lock; records snapshot type, delivery kind, owned plan, project, source/target branches and coordinator. Registration does not authorize implementation; advisory research and unselected candidates are not silently promoted. | Missing or failed registration blocks execution (admission refusal, seam S2). A failed register write is never treated as partial activation success. |
48
+ | recall | PM, during Prepare before plan lock | Recall receipt: relevant knowledge/research inputs recorded, reused and rejected decisions noted, or a truthful empty result when none apply. No full-corpus scan; no invented knowledge. | Plan lock is not reached without the receipt. Existing implement-time re-alignment still applies when source inputs change. |
49
+ | prepare/lock | PM per `mstar-phase-gates` | Locked plan under the existing Prepare/clarify gates; their ownership and risk rules are unchanged. Workflow unification removes no gates. | Clarify/Prepare gate failure keeps the workflow active in Prepare; nothing advances silently. |
50
+ | execute + review/acceptance | Dev implementers, plan QC tri, QA per existing ownership | The existing per-plan gate evidence (implementation checks, QC tri, QA gate). | Gate failure leaves rows and workflow blocked/active — never silently completed. Row `Done` is not workflow completion (foundational facts). |
51
+ | compound disposition | PM/implementer on the delivery branch/worktree, before the PR head is finalized | Outcome ∈ {`created`, `updated`, reasoned `skipped`} recorded on the workflow. No mandatory new document; high overlap updates an existing document rather than generating a duplicate. | Missing disposition blocks PR head finalization. A reasoned `skipped` is a valid recorded outcome, not an omission. |
52
+ | submit PR | PM/owner | Real PR identity recorded at submission: repo, head, target (§4d). | Missing credentials, remote, or submission failure leaves the workflow blocked/active, not completed. A local commit or a pre-existing unrelated PR does not satisfy this stage. |
53
+ | merge-ready (milestone) | PM declares after submission | Milestone marker only. The workflow stays registered and resumable while the PR is open. | Not a completion state: an outstanding delivery PR keeps the workflow active (foundational facts). |
54
+ | verify merge | PM check — never the close verb | Provider merge evidence. PR opened, mergeable, and merged are different facts; missing or unavailable provider evidence is not accepted as merged. | Unverified merge keeps the workflow registered/resumable. Local close validation is never described as proof of a remote merge. |
55
+ | terminal close/unregister/reconcile | Authorized close path (seam S3): `closeWorkflow` semantics + phase-6 ordering | Terminal snapshot write → root unregister → projection reconcile, ordered and retryable; every row `Done`; delivery-kind evidence consulted (§6 S3). | Refusal when evidence or row state is insufficient. Root-removal failure is explicit partial closure; retry must not rewrite the terminal timestamp. |
56
+
57
+ **Iteration application.** An iteration uses the same outer lifecycle around its multiple plan rows, adding only iteration-specific scope planning, dependency scheduling, integration and package/compass projections. Child plan handoffs do not trigger per-child delivery PRs or premature parent closure; only the iteration workflow itself walks submit PR → verify merge → terminal close.
58
+
59
+ ## 4. Evidence contracts
60
+
61
+ **(a) Registration is an authorized domain operation.** It writes the create-only snapshot and the root entry under one lock. The primitive reference is the audit-promotion sequence `packages/engine/src/audit.ts:1250-1324`: plan-row/snapshot construction, entry validation, then the atomic root-lock section — create-only `writeWorkflowSnapshot` → `registerWorkflowEntryLocked`, with rollback that removes only the exact snapshot version that call created. The generic producer (seam S1) reuses these primitives; it does not invent a second registration mechanism.
62
+
63
+ **(b) Admission consumes registration.** `packages/engine/src/sdd.ts:1185-1194` falls back to branch-alignment-only when no active workflow row applies, or a non-InProgress row has no lease — so the SDD seam does not enforce the registration obligation by itself. On the normal plan route that fallback closes with a precise refusal code, and the refusal documents the registration command and the recovery path (seam S2). Registration/recovery semantics: a crash between snapshot creation and root registration leaves no partial activation; recovery re-runs the authorized producer without duplicating identity.
64
+
65
+ **(c) Compound disposition.** The outcome ∈ {`created`, `updated`, reasoned `skipped`} is recorded on the workflow before PR head finalization. Engine checks can validate the disposition and referenced artifacts; that is not semantic-quality proof. Existing compound document/index validation is reused as-is.
66
+
67
+ **(d) PR identity.** Repo, head, and target are recorded at submission. Neither a local commit nor a pre-existing unrelated PR satisfies the obligation; a failed submission leaves the workflow blocked/active, not completed.
68
+
69
+ **(e) Merge-ready.** Leaves the workflow registered and resumable. A requirement to submit a PR implies no authorization to merge it.
70
+
71
+ **(f) Verified merge.** A PM check, never the close verb. It distinguishes opened, mergeable, and merged; missing or unavailable provider evidence is not accepted as merged.
72
+
73
+ **(g) Terminal close.** Existing `closeWorkflow` semantics (`packages/engine/src/workflow.ts:665-725`): close-timestamp validation, snapshot identity check, coordinated-writer authority, every row `Done`, strict terminal validation that refuses leases without deleting them, and idempotent preservation of an existing valid terminal snapshot (including `failed`/`stopped`); it never releases leases. Ordering per phase-6 (`packages/engine/src/iteration.ts:514-616` reuse): snapshot terminal → unregister → reconcile. The local gate deliberately does not verify remote merge — that verification is the PM's separate check in (f). `closeWorkflow` does not inspect PR or compound evidence; seam S3 adds exactly that delivery-kind evidence consultation while reusing every existing guard.
74
+
75
+ ## 5. Failure and abandonment
76
+
77
+ - Failure and abandonment close through explicit `failed`/`stopped` statuses with a recorded reason. They are never rewritten as successfully completed.
78
+ - `closeWorkflow` preserves an existing valid terminal snapshot unchanged, including `failed`/`stopped` — idempotence this contract keeps.
79
+ - Close never releases leases. Another owner's lease is not released to force closure; strict terminal validation refuses leases without deleting them.
80
+ - Scoped and plan-scoped sessions cannot mutate lifecycle anchors or close sibling workflows (foundational distinctions, third meaning).
81
+
82
+ ## 6. Engine seam inventory
83
+
84
+ Three named seams. Per-seam acceptance checks state the observable behavior each seam owes. This section specifies seams; it implements none of them.
85
+
86
+ **S1 — Generic register producer.** A general authorized registration path for normal plan workflows, reusing the §4a primitives (create-only snapshot + root entry under one lock, rollback of only the created version).
87
+ Acceptance checks: a standalone development plan registers before execution; a missing registration, failed register write, or ambiguous owner blocks execution without partial activation being treated as success; crash/retry between snapshot creation and registration preserves identity, timestamps, ownership and resumability; existing producers (audit promotion) use the same primitives.
88
+
89
+ **S2 — Admission consumption.** The SDD admission fallback (`packages/engine/src/sdd.ts:1185-1194`) closes on the normal plan route: execution without a registered running workflow row is refused with a precise refusal code, and the refusal documents the registration command and recovery path.
90
+ Acceptance checks: an unregistered plan's execution is refused, not silently continued on branch alignment alone; the refusal names registration and recovery; no partial activation is treated as success.
91
+
92
+ **S3 — Standalone close path.** The close path consults the registered delivery kind's evidence before completing. The local post-merge gate is snapshot-type-generic; the delta is the delivery-kind evidence consultation, reusing `closeWorkflow` guards and phase-6 ordering unchanged.
93
+ Acceptance checks: a registered `development` workflow with missing or incomplete delivery evidence refuses the close and stays registered/resumable; `Done` rows without required PR/compound evidence cannot be used to declare the workflow delivered; close retry after the terminal write preserves the original timestamp; `failed`/`stopped` workflows are never rewritten as successfully completed; close never releases leases; crash/retry between terminal write and unregister preserves identity, timestamps, ownership and resumability.
94
+
95
+ **Explicit deferral.** Mid-lifecycle advancement-gate breadth is deferred: per-stage engine gates across recall, prepare/lock, execute, compound disposition and PR submission are not part of this contract. `evaluatePhaseGate` stays iteration-shaped. The process obligations for those stages are carried by corpus pointers to this contract; only registration admission (S2) and terminal evidence (S3) are wired into code, plus the S1 producer.
96
+
97
+ ## 7. Scope decisions
98
+
99
+ The direction and reason columns record the reasoning behind each answer; the answers are binding. There are no open decisions in this table.
100
+
101
+ | Decision | Answer | Direction | Reason |
102
+ |---|---|---|---|
103
+ | Does every `type: plan` mean a development PR? | **No.** Delivery kind is declared at registration (§1). Development plans require PR; verification/report-only workflows follow the explicit alternative completion policy recorded at registration. | Declare the delivery obligation explicitly for the workflow's purpose. Development plans require PR; verification/report-only workflows need an explicit alternative completion contract. | `type: plan` is also used for independent verification. Do not force empty PRs or make absence of `branch.target` an implicit escape hatch. The strict universal alternative is possible but must be consciously selected. |
104
+ | Is `type: plan` exactly one plan row? | **One independently owned development plan per workflow for the new normal route; audit promotion grandfathered as an explicitly inventoried multi-row producer (§2).** | Prefer one independently owned development plan for the new normal route; inventory current multi-row producers before tightening schema. | A type label alone does not establish cardinality. Audit promotion must be considered before enforcing a one-row invariant. |
105
+ | Where does compound run for a standalone plan? | **On its delivery branch/worktree, before the PR head is finalized (§3, §4c).** | On its delivery branch/worktree before the PR head is finalized. | Do not invent an iteration compass or extra integration branch solely to reuse iteration-close. Preserve control-root process artifacts versus tracked-result write ownership. |
106
+ | What completes the workflow? | **Verified merge plus common close; PR submission and merge-ready remain resumable milestones (§3, §4e–g).** | Verified merge plus common close; PR submission and merge-ready remain resumable milestones. | Preserves the stronger existing post-merge-close semantics. A user request to submit a PR is not authorization to merge it. |
107
+ | How should failure/abandonment close? | **Explicit failed/stopped handling with reason, never successful completed-close; no lease release by close (§5).** | Explicit failed/stopped handling with reason, never successful completed-close. | Preserve the existing distinction and do not release another owner's lease to force closure. |
108
+
109
+ ## Binding negatives
110
+
111
+ - No part of this contract authorizes auto-merge. Submitting a PR never implies merge authorization; merging is a separate authorized act, verified by the PM check in §4f.
112
+ - No forced PR for `verification/report-only` workflows. Their completion follows the policy recorded at registration (§1).
113
+ - No silent completion anywhere. Every stage transition records its evidence; failure renders the workflow blocked/active, never implicitly done.
114
+ - No cleanup authorization is implied by lifecycle completion: worktree/branch deletion stays explicit and ownership/merge-guarded, exactly as the existing post-merge-close contract requires.
115
+ - Close never releases leases, and terminal `failed`/`stopped` states are never rewritten as `completed` (§5).
@@ -94,9 +94,12 @@ Canonical vs legacy residual definitions → **`mstar-artifacts` SKILL.md**("`
94
94
  - The example above depicts the **held** state (both leases populated, illustrative placeholder values) and passes `validateWorkflowSnapshot`; the released state is **key absence** (delete-key-on-release below), never `null` or `{}`, and enum scalars (`type` / `status` / plan-row `status`) are always single values — the full enum sets are `type`: `plan | iteration`, snapshot `status`: `running | paused | completed | failed | stopped`, plan-row `status`: `Todo | InProgress | InReview | Blocked | Done`.
95
95
 
96
96
  - `plans[]` rows are the **legacy PlanRow shape verbatim** (unknown row fields preserved, never re-bucketed). Per-row `execution_lease` stays on the row; `integration_merge_lease` is **top-level** (the v1 root-`metadata` home is gone).
97
+ - **Scoped coordination (optional):** top-level `coordination.coordinator` plus per-row `coordination` (`revision` / `prepared` / `session` / `progress` / `handoff`) appear only on the scoped route — field table, session envelopes and version rules → § Plan-scoped coordination below.
97
98
  - Terminal statuses (`completed` / `failed` / `stopped`) require `ended_at` and no dangling leases.
98
99
  - **Completed close (Phase 6)** runs `mstar status workflow-close --workflow <id> [--harness <path>] [--ended-at <date>]`: engine `closeWorkflow` rereads the latest snapshot under the snapshot write lock, refuses any dangling lease / non-`Done` row (fail-loud, bytes unchanged), writes `completed` + `ended_at`, then unregisters the root entry. Unregister failure after the snapshot write is a reported **partial close** — retry finishes unregister without rewriting `ended_at`; a fully closed retry rewrites neither file. An already-terminal `failed` / `stopped` snapshot keeps its actual status (close never fabricates `completed`).
99
- - **Physical cleanup is out of close's scope**: it is the separate `mstar worktree cleanup --workflow <id> …` verb (dry-run default), run in its own timing lane — same-round after a plan's integration merge (Phase 2) or after §6.1–§6.3 + PR merged (Phase 6). Close and cleanup never release leases — owners release manually before either. Guard/decision codes (`cleanup.keep.*`, `cleanup.refuse.*`, `cleanup.remove.merged`) → **`mstar-branch-worktree`**「Worktree / branch cleanup」.
100
+ - **Delivery-evidence consultation before the close (seam S3):** a `type: plan` snapshot's registered delivery kind is consulted **before** the terminal write (`completed` closes only — a `failed`/`stopped` close is never demanded delivery evidence, §5) — an incomplete `development` delivery (no compound disposition / PR identity / PM-recorded verified-merge evidence, or a PR whose `head`/`target` are not the registered `branch.source`/`branch.target`), or an unfulfilled `verification/report-only` completion policy, refuses with the `PHASE6_DELIVERY_*` codes, leaving the snapshot `running` and the root entry registered (bytes unchanged, workflow resumable). Record the missing evidence with `mstar workflow evidence --workflow <id> --file <payload.json> [--session <path>]` — the same coordinator-session gate as the close, idempotent (identical evidence rewrites nothing) and stage-by-stage mergeable; the PR identity (§4d) is recorded **once** (a different pair is refused), the compound disposition and the merge record stay updatable. It refuses an already-terminal lifecycle plus a non-`plan` snapshot without a registered kind. The read-only `mstar iteration gate --phase 6` shares this same consultation, so gate and close never disagree.
101
+ - **Delivery kind is declared at registration by every producer** (§1/§4a): `mstar workflow register` (normal entry), `mstar audit promote --delivery-kind <kind>` (required flag) and `mstar migrate --delivery-kind <kind>` (a lift that would create an ACTIVE kind-less plan snapshot is refused as usage, exit 2; the declaration is ONE delivery identity, so a tree whose lift creates 2+ ACTIVE standalone plans is refused the same way with the plan ids — migrate in batches of one declared plan) all declare it explicitly — never inferred, never defaulted in code — and one shared rule pairs `development` with `--branch-source`/`--branch-target` and `verification/report-only` with `--completion-policy`. An **ACTIVE** `type: plan` snapshot that predates this (the historical audit-promotion / v1-lift population) is repaired once with `mstar workflow evidence --workflow <id> --declare-kind <development|verification/report-only> [--branch-source <b> --branch-target <b> | --completion-policy <text>] [--session <path>]`: the declaration is one-time (a second one, even with the same kind, is refused) and refuses a terminal snapshot — a supplied anchor fills a MISSING delivery anchor or restates the registered one, while a value conflicting with an anchor the snapshot already carries is refused (the registered anchor is the delivery identity, never overwritten); a legacy **terminal** kind-less snapshot keeps its documented owner-amendment path.
102
+ - **Physical cleanup is out of close's scope**: it is the separate `mstar worktree cleanup --workflow <id> …` verb (dry-run default), run in its own timing lane — same-round after a plan's integration merge (Phase 2) or after §6.1–§6.3 + PR merged (Phase 6). Close and cleanup never release leases — on the scoped route the plan row's lease is moved/deleted by `mstar plan accept | return | complete` (never by close or cleanup, and never by a standalone release verb); on the whole-iteration route the owner releases before either. Guard/decision codes (`cleanup.keep.*`, `cleanup.refuse.*`, `cleanup.remove.merged`) → **`mstar-branch-worktree`**「Worktree / branch cleanup」.
100
103
  - `execution_policy` keys are copied from v1 root `metadata` at migrate; values are accepted-but-opaque this iteration (no semantic gate).
101
104
  - `notes`: a plan row's `notes` array is the **legacy verbatim copy** preserved at migrate; the **runtime ledger is `notes.jsonl`** in the workflow dir (see `workflows/<id>/notes.jsonl` below). New notes append to the ledger only — never dual-write the row `notes`.
102
105
 
@@ -244,7 +247,7 @@ The v1 `plans[].metadata.findings_cleanup` mirror is **deleted** in v3 — no du
244
247
 
245
248
  | Context | Default |
246
249
  | ------- | ------- |
247
- | Formal **iteration Phase 2** (Autonomous Execute) | `zero-residual` (compass or Assignment may override to `allow-residual`) |
250
+ | Formal **iteration Phase 2** (Autonomous Execute) | `allow-residual` (compass or Assignment may still override, including to `zero-residual`) |
248
251
  | Standalone `/pm`, hotfix, `Execution mode: inline` | `allow-residual` |
249
252
 
250
253
  ### `zero-residual` (clean-session)
@@ -259,9 +262,14 @@ Intent: clear findings in the current plan session whenever possible. Open resid
259
262
  6. **`waived` / `risk-accepted`**: still require PM + user/architect alignment; **close in the register** (do not leave open). Prefer a cheap fix over waive-as-shortcut.
260
263
  7. Plan **Done**: prefer an empty `entries[<plan_id>]` in the register. If any open entries remain, **every** one must be blocker-defer + roadmap and none may be `critical` (item 4); otherwise keep `InReview` / `Blocked`.
261
264
 
262
- ### `allow-residual` (legacy default)
265
+ ### `allow-residual`
263
266
 
264
- Non-blocking register entries — `severity` below `critical` on the §3 axis — may ship with open entries and `Approve with residuals` when no unresolved `critical` remains (existing residual lifecycle unchanged).
267
+ Non-blocking register entries — `severity` below `critical` on the §3 axis — may ship with open entries and `Approve with residuals` when no unresolved `critical` remains (existing residual lifecycle unchanged). This is the default mode (see Defaults above; `zero-residual` is the explicit opt-in). Registration and disclosure are hard duties under `allow-residual` — they replace the speed-vs-discipline tradeoff, not the audit trail:
268
+
269
+ 1. **Register before InReview exit**: every open R# is entered in the project register `{PROJECT_DIR}/<id>/residuals.json` → `entries[<plan-id>]` with machine-enum `severity` before the plan leaves InReview.
270
+ 2. **Disclose on every decision surface**: every consolidated QC decision, Completion Report, and Status Update states the residual situation — the list, each entry's `severity`, and its tracking location. Silence about open residuals is a gate violation, not a style issue; when nothing is open, say `N/A — none open`.
271
+ 3. **Critical still blocks**: an unresolved `critical` blocks `Approve`; `medium` / `low` / `nit` may be registered and carried (fix-now remains preferred when cheap).
272
+ 4. **Close-time disclosure**: close-time artifacts carry the same residual list with `id` + `severity` + tracking location + blocker-defer flag — each plan's durable `## Review Gate Summary` (main plan), the iteration compass `## Quality Gate Summary`, and the PR delivery body (`N/A — none open` when empty). A close without these disclosures is not a close. Disclosure does not override critical-blocking, explicit `zero-residual` requirements, or register lifecycle rules: terminalizing a workflow never silently closes its open findings. `mstar status tech-debt` remains the cross-iteration visibility rollup.
265
273
 
266
274
  > **Engine check (when available):** run `mstar status findings-cleanup <plan-id> [--project <id>] [--mode zero-residual|allow-residual]` (or import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook) to enforce the mode above against the plan's register entries. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
267
275
 
@@ -308,11 +316,11 @@ Optional when a plan is not owned; **required** while a Phase 2 session owns wri
308
316
  | `working_branch` | non-empty string | Yes | Feature branch at `worktree_path`; MUST agree with Assignment **`Working branch`**. |
309
317
  | `session_label` | string | No | Human display only — **MUST NOT** authorize or compare ownership. |
310
318
 
311
- Writers **delete** `execution_lease` on release; `null` and tombstone objects are invalid.
319
+ Writers **delete** `execution_lease` on release; `null` and tombstone objects are invalid. On the scoped route the deletion happens **only** through `mstar plan accept | return | complete` (§ Plan-scoped coordination) — never by hand.
312
320
 
313
321
  **Ownership survives release**: later `mstar worktree cleanup` attributes a released plan row through the retained row `metadata.working_branch` / `metadata.worktree_path` and retained track Assignments — never by branch-name inference. Guard codes and the cleanup contract → **`mstar-branch-worktree`**「Worktree / branch cleanup」.
314
322
 
315
- V1: **manual release only** — omit `expires_at`; readers **MUST NOT** treat unknown or draft `expires_at` as authority to steal or release.
323
+ V1: **manual release only** — omit `expires_at`; readers **MUST NOT** treat unknown or draft `expires_at` as authority to steal or release. There is also **no standalone release verb / flag**: on the scoped route a plan session's lease moves only through the `accept` → (`integration-start` → `integration-accept`) → `complete` sequence, or returns to the plan session on `return`; `--force`, takeover and TTL/idle theft do not exist.
316
324
 
317
325
  ### Snapshot top-level fields
318
326
 
@@ -342,7 +350,7 @@ Leases live in the **workflow snapshot** `{WORKFLOW_DIR}/<id>/snapshot.json` (`p
342
350
 
343
351
  **Protocol home (single canonical copy):** the full lease protocol prose — same-host exclusive write lock, hard gate, claim-before-`InProgress`, hold/release/override, integration merge protocol, orphan recovery, lease prohibitions — lives in **`mstar-engine-legacy`** `references/lease-protocol.md` (engine-absent fallback). The Phase 2 iteration-command **execution checklist** → **`mstar-iteration`** `references/phase-2-worktree-lease.md`. This file carries the **field semantics** only (tables below + the lockdir location summary).
344
352
 
345
- **Same-host exclusive write lock (snapshot / root):** all control-path lease mutations (execution claim/release/transfer, plan-status transitions that touch leases, `integration_merge_lease` claim/release) **MUST** run inside a same-host exclusive write lock for the full read-check-replace-verify sequence. Engine writers handle this automatically (`writeWorkflowSnapshot` / `registerWorkflow` acquire `<status-file dir>/.status-write.lockdir/` next to the file — for snapshots the lockdir lands inside `workflows/<id>/`). Prefer the engine-check commands below over hand-rolled `flock` snippets; the atomic-mkdir alternative (`.status-write.lockdir/` in the same directory as the file) remains the documented fallback when no engine writer exists. Hard gate, cross-host exception and pre-dispatch re-verify → `mstar-engine-legacy/references/lease-protocol.md`.
353
+ **Same-host exclusive write lock (snapshot / root):** all control-path lease mutations (execution claim/release/transfer, plan-status transitions that touch leases, `integration_merge_lease` claim/release) **MUST** run inside a same-host exclusive write lock for the full read-check-replace-verify sequence. Engine writers handle this automatically (`writeWorkflowSnapshot` / `registerWorkflow` acquire `<status-file dir>/.status-write.lockdir/` next to the file — for snapshots the lockdir lands inside `workflows/<id>/`). The lock protects only callers that **actually acquire it**: scoped verbs run their whole read-check-replace-verify inside the same lockdir, whereas a hand-written update that bypasses `writeWorkflowSnapshot` is both unprotected and unauthorized (`coordination.direct-write-refused`). Prefer the engine-check commands below over hand-rolled `flock` snippets; the atomic-mkdir alternative (`.status-write.lockdir/` in the same directory as the file) remains the documented fallback when no engine writer exists. On the **scoped route** that fallback does not reopen a manual path: the verbs own the lock (`mstar plan bind | progress | residual-add | residual-close | handoff | accept | return | integration-start | integration-accept | complete | reconcile`), a missing CLI **fails closed** instead of degrading to hand-written flock/atomic-mkdir, and read-only validators stay checks — never mutation substitutes. Hard gate, cross-host exception and pre-dispatch re-verify → `mstar-engine-legacy/references/lease-protocol.md`.
346
354
 
347
355
  > **Lease Engine-check:** single canonical callout in `mstar-artifacts` `SKILL.md`(Engine-check lease 行)— pointer only, do not re-vendor.
348
356
 
@@ -361,7 +369,72 @@ Single global lease authorizing one plan feature branch integration into `branch
361
369
 
362
370
  ### Claim-before-`InProgress`, hold/release/override, integration merge, orphan recovery, prohibitions
363
371
 
364
- These are **full-protocol prose** — the single canonical copy lives in **`mstar-engine-legacy`** `references/lease-protocol.md` (engine-absent fallback); the Phase 2 iteration-command **execution checklist** is **`mstar-iteration`** `references/phase-2-worktree-lease.md`. This file carries the field semantics (tables above) and the engine checks only — do not re-state the protocol here. `V1: manual release only` — omit `expires_at`; readers **MUST NOT** treat unknown or draft `expires_at` as authority to steal or release (see the `execution_lease` field table).
372
+ These are **full-protocol prose** — the single canonical copy lives in **`mstar-engine-legacy`** `references/lease-protocol.md` (engine-absent fallback); the Phase 2 iteration-command **execution checklist** is **`mstar-iteration`** `references/phase-2-worktree-lease.md`. This file carries the field semantics (tables above) and the engine checks only — do not re-state the protocol here. `V1: manual release only` — omit `expires_at`; readers **MUST NOT** treat unknown or draft `expires_at` as authority to steal or release (see the `execution_lease` field table). On the **scoped route** this prose is executed only through the verbs — `bind` (claim), `accept` / `return` (transfer / give-back), `integration-start` → `integration-accept` (merge), `complete` (release both) — with **no** override / `--force` / TTL path and no standalone release verb; the runtime contract is § Plan-scoped coordination above, and the legacy prose is the engine-absent fallback only.
373
+
374
+ ---
375
+
376
+ ## Plan-scoped coordination (bind / revision / session / handoff) — sole runtime field home
377
+
378
+ The scoped route(`/iteration-drive --assignment | --workflow <id> --plan <id> | --resume <session.json>` → `mstar plan …`)keeps **one process authority**: the same workflow snapshot (`workflows/<id>/snapshot.json`) and the same root `status.json` — no per-plan snapshot clone, database, daemon or second status copy. This section is the **single runtime home** for the coordination / session / handoff / revision fields; command flags and exit codes → `docs/cli.md`; route semantics → **`mstar-iteration`** `references/plan-scoped-pm.md`; engine API shapes → `packages/engine/src/coordination.ts`.
379
+
380
+ ### Snapshot fields
381
+
382
+ | Level | Field | Type | Semantics |
383
+ | --- | --- | --- | --- |
384
+ | top | `coordination.coordinator` | object | `{ session_id, session_file, bound_at }` — one coordinator per workflow; a second fresh coordinator bind fails exactly like a duplicate plan holder. Created only from the verified main worktree or the recorded integration worktree, with a registered running iteration. |
385
+ | row | `coordination.revision` | nonnegative integer | Optimistic-concurrency token; absent `coordination` = `0`. **`--expect <revision>` always means this row value** — never snapshot `schema_version` or a date. |
386
+ | row | `coordination.prepared` | object | `{ assignment_path, assignment_sha256, plan_sha256, qa_gate, findings_cleanup, prepared_by, prepared_at }` — the reviewed-Assignment authorization. Hashes are SHA-256 of the exact UTF-8 bytes; after claim the Assignment is immutable and every show/resume/mutation rechecks its hash — a changed file fails `coordination.assignment-stale` without changing state. |
387
+ | row | `coordination.session` | object | `{ session_id, session_file, bound_at }` — the bound plan-PM session; the UUID is engine-allocated, never derived from plan, assignment path, PID or terminal label. |
388
+ | row | `coordination.progress` | object | `{ status, summary, evidence_paths[], track_branches? }`; `status` ∈ `InProgress` / `InReview` / `Blocked` only; nonblank `summary`; evidence paths must be existing canonical absolute artifacts inside this plan's resolved plan/SDD area; `track_branches` must belong to its recorded L2 Assignments/worktrees. |
389
+ | row | `coordination.handoff` | object | Immutable submitted handoff record: engine-generated UUID / attempt / timestamps plus Git pins and evidence hashes. Input can never set state, holder or target. |
390
+
391
+ ### Session envelopes and credentials
392
+
393
+ - Session JSON lives at `<resolved-workflow-dir>/<workflow-id>/sessions/<session-id>.json`, created exclusively, mode `0600`.
394
+ - It is a **credential / pointer**, not a second process-SSOT copy: session identity, resolved harness root and pointers — never copied snapshot state, never a portable handoff address. Cross-primary handoff references are readable absolute **control-root filesystem paths**; `local://` is not portable.
395
+ - Session paths and `--expect` revisions stay with the dispatching PM/coordinator and are **never** handed to a leaf implementer/reviewer (`mstar-dispatch-gates` § Plan 作用域与 credential 不下发).
396
+ - Supported writers are cooperative same-machine interfaces, not a filesystem sandbox: copying a session file or editing protected files by hand is not prevented, and is not an authorized path.
397
+
398
+ ### Revision and version protocol
399
+
400
+ - `--expect <revision>` (row) and `--expect-register <version>` (register; artifact version = `sha256:<64 lowercase hex>`, missing = `absent`) are required by every mutating verb. `bind` is the only exception: it checks and claims atomically against current ownership without a caller snapshot, and `--resume` returns context without changing ownership or revision.
401
+ - Every row operation **except residual-only writes** increments only that row's revision. A sibling plan's mutation leaves this row's revision untouched; a stale same-row expectation fails `coordination.version-conflict`.
402
+ - Global coordinator binding takes the snapshot lock but increments no row revision — it changes only top `coordination.coordinator` and `updated_at`.
403
+ - No automatic retry / rebase exists for caller replacements: missing version = `coordination.expected-version-required`, mismatch = version conflict, and no mtime / date / schema version is ever used as CAS.
404
+ - Residual writes touch only `entries[<planId>]` and bump no snapshot revision, so there is no two-document commit pretending to be atomic.
405
+
406
+ ### Verbs and row / register ownership
407
+
408
+ | Actor | May write |
409
+ | --- | --- |
410
+ | coordinator — `mstar plan prepare · accept · return · integration-start · integration-accept · complete · reconcile` | selected row `coordination.prepared` and handoff transitions, `status`, both coordination leases, `Done` |
411
+ | plan session — `mstar plan progress · residual-add · residual-close · handoff` | its own row `status` + `coordination.progress`, `metadata.track_branches`, its `entries[<planId>]` register bucket, and the handoff record |
412
+ | anyone else | nothing scoped — sibling rows, lifecycle anchors, root register, `execution_policy`, `compass_ref`, shared indexes, the iteration PR and Phase 3–6 stay on the coordinator / global route |
413
+
414
+ - **State machine:** `Todo → InProgress` (bind) → `InReview` (handoff; lease kept) → `accepted` → `integrating` → `merged` → `completed` ⇒ `Done`. `progress` allows only `InProgress → InProgress | InReview | Blocked`, `Blocked → Blocked | InProgress`, and `InReview → InReview | InProgress | Blocked` **before** handoff — never `Todo` / `Done` / lease removal. After handoff, all scoped progress/residual mutations are rejected until `return`.
415
+ - **`complete` is the one atomic write** that sets `Done` (with verified Git proof and the findings gate), retains row `metadata.working_branch` / `metadata.worktree_path` and existing `track_branches`, and deletes the row `execution_lease` plus the coordinator's `integration_merge_lease`. `accept` is ownership transfer only — no merge, no `Done`; `integration-accept` keeps both leases and `InReview` until `complete`.
416
+ - **Legacy helpers refuse coordinated keys:** `appendProjectRegisterEntries` / `closeProjectRegisterEntry` / backlog next-free-key and `persist` replacements reject an existing coordinated plan bucket with `coordination.scoped-writer-required` (directing the caller to `residual-add` / `residual-close`), and hand writes to protected snapshot / register / root targets are refused with `coordination.direct-write-refused`. Root and global lifecycle operations stay on the existing coordinator route and are never `mutatePlanCoordination` targets.
417
+ - Read-only validators (`mstar lease verify`, `mstar lease verify-integration`, `mstar worktree check`, `mstar status validate`) remain **checks** — never mutation substitutes.
418
+
419
+ ### Reconcile outcomes (crash recovery)
420
+
421
+ Per-state `reconcile` outcome **and** the recovery action it requires are **route semantics, not fields**: single canonical copy → **`mstar-iteration`** `references/plan-scoped-pm.md` §6.7(outcome table)with §7(`show` refresh before a stale retry). The `retry-ready` path therefore resumes `show` → `integration-start`(re-pin `base_sha`, re-acquire the merge lease)→ the coordinator's `git merge --no-ff` → `integration-accept` — **never a bare merge**.
422
+
423
+ Reconciliation observes **Git ancestry / HEAD facts** in the recorded repository and never trusts a caller's success flag, and never performs a second merge. A crash after `complete` but before CLI output is handled by `show` + `reconcile`; a crash before the session binding leaves only an inert envelope. `return` after a failed merge requires an explicit Git abort plus reconcile first — a merge lease is never discarded while Git may still be in flight. Lost credentials or an abandoned active owner need explicit human recovery outside the normal verbs; no automatic takeover flag is introduced.
424
+
425
+ ### Prepare workflow amendment (guarded Prepare-only structural delta)
426
+
427
+ **Coordinator authority only.** The amendment is addressed by the workflow's **coordinator** session envelope (`mstar plan bind --coordinator --workflow <id>` → `top.coordination.coordinator`); identity is never a flag, and the envelope's own harness root / workflow id are the only address. A plan session, an unbound or foreign workflow, a mismatched envelope, or an unregistered / non-`running` root entry refuses before any mutation. The top-level coordinator binding is the sole permitted coordination state.
428
+
429
+ **When it is lawful** (all of it, evaluated inside the snapshot write lock): `status: running` in `phase: phase-1-prepare`, the root register entry still **`running`** (`paused` is active in the register but not admissible here — the refusal reports the observed entry status), and **no execution ownership anywhere** — every row `Todo` with progress 0, no row `execution_lease`, no row `coordination` block (preparation, session binding, progress/QC evidence, handoff and reconcile state all live there), and no top-level `integration_merge_lease`. Resetting a row to `Todo` would erase nothing — it is exactly what this entry must not do, so an evidence-bearing row refuses instead.
430
+
431
+ **What it may change** (minimum delta): append explicitly approved **unique Todo** plan rows — constructed by the engine, never supplied with runtime row state — and fill the reviewed `integration_worktree_path`; the sole editable policy key is `execution_policy.plan_parallelism` (`serial` | `parallel`). Every prior row, unknown field, timestamp, revision, history, root entry and other workflow survives **by value**; only the appended rows, those two requested projections and the snapshot `updated_at` are new. It creates and switches nothing, is not a scheduler, and is not a general snapshot replacement. **One engine-owned exception to that enumeration:** a stored legacy `control_worktree_path` is normalized in memory by the canonical snapshot reader, so this authorized write emits the canonical `integration_worktree_path` and drops the legacy key with the value preserved — the migration the engine's own `workflow.snapshot.legacy-control-worktree-path` diagnostic prescribes (writers emit only the canonical key).
432
+
433
+ **Both byte tokens, always.** The amendment carries the current raw-byte SHA-256 of the **snapshot bytes** and of the workflow's reviewed **compass Markdown bytes** (`sha256:<64 lowercase hex>`, read from the read-only `show-prepare`); both are required even on the first amendment, and neither is a per-plan `coordination.revision`. The compass token binds the reviewed declaration: the resulting plan-id **set** must equal the compass `plans:` list exactly, and its `spec_integration_branch` / `integration_worktree_path` declarations must agree with what the call would leave recorded. The compass is re-read immediately before the single atomic commit.
434
+
435
+ **Refusals are mutation-free.** `coordination.prepare-amendment.{stale, invalid-patch, not-prepare, execution-started, duplicate-plan, invalid-plan, compass-mismatch, invalid-worktree}` (`coordination-write.ts`), plus the existing auth/scope errors; when each fires, the exact exit code and payload → `docs/cli.md` § `mstar-harness workflow`. The protected snapshot, root register, other workflows and the compass stay byte-identical.
436
+
437
+ **Prepare-only, no force.** Recovery from a `stale` token is re-read `show-prepare` → review again → retry with the fresh tokens. There is no force, no replacement snapshot, no reset and no hand-editing workaround for a workflow that has left Prepare or already owns execution.
365
438
 
366
439
  ---
367
440
 
@@ -395,7 +468,7 @@ These are **full-protocol prose** — the single canonical copy lives in **`msta
395
468
  | ------ | ----- | ---- |
396
469
  | Implement fix | `@fullstack-dev` / assignee | Completion Report cites R# + evidence |
397
470
  | Verify | `@qa-engineer` when **`QA gate: mandatory`**; else PM per acceptance checklist | Regression / acceptance; open R# close requires verify before close |
398
- | Write the register | **`@project-manager`** or **`@qa-engineer`** | After verification; waivers after PM + user/architect alignment |
471
+ | Write the register | **`@project-manager`** or **`@qa-engineer`** | After verification; waivers after PM + user/architect alignment. On the scoped route the write is the `residual-add` / `residual-close` verb, never a hand edit |
399
472
 
400
473
  Do not claim “R3 fixed” in chat/plan only without SSOT update.
401
474
 
@@ -405,15 +478,15 @@ PM should register open items after **`Approve with residuals`**; QA should stat
405
478
 
406
479
  After **`closed_at`**, **`closure_note`**, and PM/QA confirm close:
407
480
 
408
- 1. Set `lifecycle` / `closed_at` / `closure_note` on the entry **in place** in the register (`projects/<id>/residuals.json` → `entries[<plan-id>]`).
409
- 2. Optional: delete the entry from the register instead when the team prefers an empty open list — the closed record's `lifecycle` + `closed_at` is the durable record either way.
481
+ 1. Close through the **domain call**: `mstar plan residual-close --session <plan-session> --entry <id> --note <text> --expect <revision> --expect-register <version>` on the scoped route (legacy `closeProjectRegisterEntry` under lock elsewhere). It sets `lifecycle` / `closed_at` / `closure_note` **in place** in `entries[<plan-id>]`, requires a nonblank evidence-bearing note, and bumps no snapshot revision. A coordinated plan bucket rejects the legacy helper with `coordination.scoped-writer-required`; hand edits are not an authorized path.
482
+ 2. Optional: delete the entry from the register instead when the team prefers an empty open list — the closed record's `lifecycle` + `closed_at` is the durable record either way. (A coordinated bucket keeps its entries; close, do not delete.)
410
483
  3. Delete empty **`plan-id`** keys; update root `updated_at`; optional milestone entry in the workflow `notes.jsonl`.
411
484
 
412
485
  Closed records live in the register + durable plan summaries; raw review bundles are ephemeral and not part of the long-term record.
413
486
 
414
487
  ### Short in-place close (transition only)
415
488
 
416
- May set `lifecycle` / `closed_*` in the register for one PR; same milestone close/delete as above.
489
+ May set `lifecycle` / `closed_*` in the register for one PR — through `mstar plan residual-close` (or `residual-add` with a new entry) when the plan is coordinated; same milestone close/delete as above.
417
490
 
418
491
  ### Hard delete
419
492
 
@@ -10,7 +10,7 @@
10
10
 
11
11
  **Execution:** mstar-sdd | inline
12
12
 
13
- **Main worktree branch:** [recorded residency of the primary checkout (main worktree) — PM observes and records before the lifecycle writes, then passes it unchanged in writable Assignments; never invented at check time, and never `branch.base` (that is a creation/merge anchor, not a residency fact)]
13
+ **Main worktree branch**: [recorded residency of the primary checkout (main worktree) — PM observes and records before the lifecycle writes, then passes it unchanged in writable Assignments; never invented at check time, and never `branch.base` (that is a creation/merge anchor, not a residency fact)]
14
14
 
15
15
  ## Global Constraints
16
16
 
@@ -20,6 +20,10 @@
20
20
 
21
21
  ### Task 1: [Component Name]
22
22
 
23
+ **Effort (agent-oriented):** [XS–XL band per `mstar-conventions/references/effort-estimation.md` — a size estimate, not a round ceiling]
24
+
25
+ **Split point:** [where the task splits if it cannot close its Files and gates in one round — capacity criterion → `mstar-artifacts/references/plan-quality-bar.md` item 7 (Task shape / session fit)]
26
+
23
27
  **Files:**
24
28
  - Create: `exact/path/to/file`
25
29
  - Modify: `exact/path/existing.py`
@@ -63,6 +67,7 @@ Reuse unaffected evidence with its original range and applicability; do not repe
63
67
  1. **Spec coverage:** every spec requirement maps to a task
64
68
  2. **Placeholder check:** task-owned paths/checks are concrete; executable tests have a real case, docs/policy have scoped evidence
65
69
  3. **Type consistency:** names match across tasks
70
+ 4. **Capacity (task shape / session fit):** every task closes its declared Files and verification gates in one implementer round — effort band declared, split point named, budget pressure never shortens verification (`mstar-artifacts/references/plan-quality-bar.md` item 7)
66
71
 
67
72
  ## SDD runtime (ephemeral)
68
73
 
@@ -144,7 +144,7 @@ Default process artifacts are **gitignored** (`mstar-conventions`「Git 跟踪
144
144
  - 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 process-SSOT copy there.
145
145
  - Absolute **`Worktree path`** (feature) MUST appear in the writable Assignment and in `execution_lease.worktree_path` before first writable implement dispatch for that plan.
146
146
  - 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: <main-repo-root>/{HARNESS_DIR}`**.
147
- - 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.
147
+ - 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. Scoped route: the plan session is established by `mstar plan bind` (claim executed inside its own lock) and scope is read from the returned row — hand-written snapshot updates are not a path (`mstar-iteration` `references/plan-scoped-pm.md` §2/§8).
148
148
 
149
149
  **Anti-pattern (forbidden)**
150
150
 
@@ -242,7 +242,7 @@ mstar worktree cleanup --workflow <id> [--harness <path>] [--apply] [--remote] [
242
242
  - **信任模型**:`--harness <path>` 为操作者提供且受信——dry-run 与 `--apply` 的全部状态事实(snapshot、lease、行归属元数据、protected 锚点)均读自该目录。
243
243
  - **坏 sibling 不再阻塞,且不丢保护**:扫描 `workflows/*/snapshot.json` 时,**非选中**的坏 snapshot 不会让命令失败(exit 1)。**JSON 可解析但校验失败**者以**降级保守形态**入安全集:只携带具保护性的声明(`branch.base` / `branch.integration` / `branch.target`、lifecycle worktree path、merge / execution lease、行 ownership 元数据),且 lifecycle 与行状态一律强制为非终态——故只会**增加** keep/refuse 判定,绝不减少(它保护的分支/worktree 会被 `cleanup.keep.protected-ref` 或 `cleanup.refuse.*` 拦住)。**完全不可解析**者声明不可知:默认 **withhold 全部 remove**(改判 `cleanup.refuse.unreadable-snapshot`,plan 仍完整打印),仅当操作者给出 `--ignore-unreadable-snapshots` 断言时才按可读 snapshot 判定。**选中** workflow 自身 snapshot 不可读仍是探测失败(exit 1);任何坏 snapshot 的字节**永不**被修复、改写或删除。
244
244
 
245
- **Ownership(禁止命名推断)**:候选归属只来自 snapshot 行元数据(`plans[].execution_lease`;lease 释放后为保留的行 `metadata.working_branch` / `metadata.worktree_path` 与 retained track Assignments)或已验证的显式 `--worktree` 断言。归属缺失 / 歧义 / 他属 → `cleanup.refuse.foreign-worktree` / `cleanup.refuse.foreign-branch`。**归属生产者义务(owner=PM)**:设 `Done` 并删除 `execution_lease` 的**同一 locked update** 内,owner 必须把 `metadata.working_branch` + `metadata.worktree_path` 持久化到该 plan 行(值以本轮 Assignment 为准)——这是 lease 释放后 ownership 检查读取的持久归属;缺失时已 merge 的 Done 行也会被 `cleanup.refuse.foreign-*` 拒绝,回收只能靠手工补写快照。
245
+ **Ownership(禁止命名推断)**:候选归属只来自 snapshot 行元数据(`plans[].execution_lease`;lease 释放后为保留的行 `metadata.working_branch` / `metadata.worktree_path` 与 retained track Assignments)或已验证的显式 `--worktree` 断言。归属缺失 / 歧义 / 他属 → `cleanup.refuse.foreign-worktree` / `cleanup.refuse.foreign-branch`。**归属生产者义务(owner=PM)**:设 `Done` 并删除 `execution_lease` 的**同一 locked update** 内,owner 必须把 `metadata.working_branch` + `metadata.worktree_path` 持久化到该 plan 行(值以本轮 Assignment 为准)——这是 lease 释放后 ownership 检查读取的持久归属;缺失时已 merge 的 Done 行也会被 `cleanup.refuse.foreign-*` 拒绝。scoped 路线上这条义务由 coordinator 的 `mstar plan complete` 一次原子写入承担(`Done` + 保留 `metadata.working_branch` / `metadata.worktree_path` / `track_branches` + 删除 `execution_lease` 与 `integration_merge_lease`);whole-iteration 路线仍是 owner 的同一 locked update。**禁止**手工补写快照来修归属——scoped 路线回到 `mstar plan complete` / `reconcile`(`mstar-iteration` `references/plan-scoped-pm.md` §6)。
246
246
 
247
247
  **合并证据硬前置**:本地资格 = `git branch --merged <base>` 成员资格,base 取候选自己的锚(plan/track → `branch.integration`;standalone plan / integration 分支 → `branch.target`)。远端证据绑定 {branch, tip, base} **同一分支化身**;当前 harness 无 PR-merged 记录源(`prMerged` 恒为 null)→ 远端仅走 tip-ancestor 历史残留路线。squash-only(tip 非 base 祖先)**保留并报告,绝不 `git branch -D`**;旧 merged PR 不能授权已复用分支的新化身。
248
248
 
@@ -252,7 +252,7 @@ mstar worktree cleanup --workflow <id> [--harness <path>] [--apply] [--remote] [
252
252
 
253
253
  **顺序(--apply;worktree 移除 ≠ 分支删除)**:普通 `git worktree remove`(**永不 force**)移除 eligible attached worktree → **重新探测 + 重新规划** → 删除**现已**未检出的分支(`git branch -d`,**永不 `-D`**)→ 远端 expected-OID compare-and-delete(`git push --force-with-lease=refs/heads/<branch>:<observed-oid> origin :refs/heads/<branch>`;ref 已移动 → `cleanup.refuse.facts-changed`,**不**自动用新 OID 重试)。dry-run 打印 worktree `remove` + 其分支 `refuse(checked-out)` 是合法状态。**禁止**全局 `git worktree prune`(会动 foreign 注册);Git 调用默认在 main worktree root,`git branch -d` 在该分支证据 base 的检出处执行(`-d` merged-into-HEAD 语义所需)——任何 Git 调用**永不位于移除候选内**。
254
254
 
255
- **Lease 释放是手工 owner 动作、cleanup 范围外**:cleanup(与 close)**从不**释放 lease;owner 先手工释放再清理,释放后归属靠保留的行元数据 / Assignments 维持。
255
+ **Lease 的释放/转移在 cleanup 范围外,且没有独立 release 动词**:cleanup(与 close)**从不**释放 lease。scoped 路线由 `mstar plan accept`(转移)→ `integration-start` / `integration-accept` → `complete`(一次原子删除两 lease)或 `return`(交回 plan session)完成;whole-iteration 路线由 owner 释放。释放后归属靠保留的行元数据 / Assignments 维持。
256
256
 
257
257
  **两条时序车道(唯一合法时机)**:
258
258
 
@@ -263,13 +263,14 @@ mstar worktree cleanup --workflow <id> [--harness <path>] [--apply] [--remote] [
263
263
 
264
264
  ## Workflow
265
265
 
266
- 主链:**PM 唯一分支决策**(`Working branch` / `Branch policy`,写进 Assignment)→ 实现者在 feature worktree 写产品编辑(L1:control root(主 checkout)管进程 SSOT、integration worktree 管 merge、feature 管源码)→ **QC 前**全部待审提交归并到**单一 `Working branch` `HEAD`** → 派 QC 三审 / QA 时共用**同一套对齐字段**(`Review cwd` / `Working branch` / `plan_id` / `Review range` / `Diff basis`,逐字相同)→ 集成分支 merge 串行(`integration_merge_lease`,在 integration worktree 执行)。并发写流在派发**前**完成 worktree 隔离(L1 跨 plan / L2 同 plan);主 worktree 驻留分支 = 计划头记录的 **`Main worktree branch`**,全程不切换。
266
+ 主链:**PM 唯一分支决策**(`Working branch` / `Branch policy`,写进 Assignment)→ 实现者在 feature worktree 写产品编辑(L1:control root(主 checkout)管进程 SSOT、integration worktree 管 merge、feature 管源码)→ **QC 前**全部待审提交归并到**单一 `Working branch` `HEAD`** → 派 QC 三审 / QA 时共用**同一套对齐字段**(`Review cwd` / `Working branch` / `plan_id` / `Review range` / `Diff basis`,逐字相同)→ 集成分支 merge 串行(`integration_merge_lease`,在 integration worktree 执行;scoped 路线:`mstar plan integration-start` → 显式 `git -C <integration-path> merge --no-ff --no-edit <pinned-source-sha>` → `integration-accept` → `complete`,`reconcile` 是唯一恢复动词)。并发写流在派发**前**完成 worktree 隔离(L1 跨 plan / L2 同 plan);主 worktree 驻留分支 = 计划头记录的 **`Main worktree branch`**,全程不切换。
267
267
 
268
268
  ## References
269
269
 
270
270
  - 派发与反递归红线 → **`mstar-dispatch-gates`**
271
271
  - SDD implement 波次(file handoff / reviewer)→ **`mstar-sdd`**
272
272
  - 迭代 Phase 2 integration worktree + lease 细则 → **`mstar-iteration`** §2(`references/phase-2-worktree-lease.md`)
273
+ - scoped plan 路线(bind / scope 边界 / handoff / coordinator merge 序列 / reconcile)→ **`mstar-iteration`** `references/plan-scoped-pm.md`
273
274
 
274
275
  ### L1 refusal diagnostics across hosts
275
276
 
@@ -13,7 +13,7 @@ description: Morning Star 知识结晶 —— 将已解决问题的经验沉淀
13
13
 
14
14
  After solving a non-trivial problem, `mstar-compound` captures the learning as a structured document in `{KNOWLEDGE_DIR}`, so future plan research, debugging, and implementation can find and reuse it.
15
15
 
16
- **In the mstar lifecycle**, compound is triggered at iteration-close (`mstar-iteration` § Phase 3), not per-plan Done. It can also be invoked standalone for ad-hoc captures outside formal iterations.
16
+ **In the mstar lifecycle**, compound is triggered at iteration-close (`mstar-iteration` § Phase 3), not per-plan Done. It can also be invoked standalone for ad-hoc captures outside formal iterations. Standalone development plans additionally owe a compound disposition before their delivery PR head is finalized (see「Integration with mstar lifecycle」).
17
17
 
18
18
  Knowledge that isn't captured evaporates when the session ends. Knowledge that is captured but not discoverable is equally lost. This skill addresses both.
19
19
 
@@ -29,7 +29,7 @@ Knowledge that isn't captured evaporates when the session ends. Knowledge that i
29
29
 
30
30
  ## Integration with mstar lifecycle
31
31
 
32
- Compound 在迭代收口时触发(`mstar-iteration` § iteration-close),不在 per-plan Done 后单独执行:`iteration-start → [plan lifecycle × N] → iteration-close → mstar-compound(per-iteration round)→ {KNOWLEDGE_DIR} → feeds next iteration's specify/plan`。迭代内所有 plan Done 后,PM 回顾整轮迭代可结晶知识,批量 compound。per-plan Done 是 per-plan 闭环终点;compound 是迭代级收口活动。
32
+ Compound 在迭代收口时触发(`mstar-iteration` § iteration-close),不在 per-plan Done 后单独执行:`iteration-start → [plan lifecycle × N] → iteration-close → mstar-compound(per-iteration round)→ {KNOWLEDGE_DIR} → feeds next iteration's specify/plan`。迭代内所有 plan Done 后,PM 回顾整轮迭代可结晶知识,批量 compound。per-plan Done 是 per-plan 闭环终点;compound 是迭代级收口活动。独立交付 development plan 并行负有 disposition 义务:交付 PR head 定稿前在其交付分支/worktree 运行 review,结果 ∈ {`created` / `updated` / reasoned `skipped`} 记录在 workflow 上——reasoned skipped 是有效结果,高重叠时更新既有文档而非新建,**不强制新文档**。语义权威 → `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`。
33
33
 
34
34
  ### Iteration package promotion(iteration-close 强制盘点)
35
35
 
@@ -49,9 +49,9 @@ Compound 在迭代收口时触发(`mstar-iteration` § iteration-close),
49
49
 
50
50
  ## When to use / Skip
51
51
 
52
- **Use**:迭代收口(`mstar-iteration` § iteration-close)批量回顾;独立触发(非迭代或紧急,任何非平凡问题解决后);重大 bug 修复后(`mstar-iteration` 未启用时手动)。
52
+ **Use**:迭代收口(`mstar-iteration` § iteration-close)批量回顾;独立触发(非迭代或紧急,任何非平凡问题解决后);重大 bug 修复后(`mstar-iteration` 未启用时手动);独立 development plan 交付前的 disposition review(PR head 定稿前,见「Integration with mstar lifecycle」)。
53
53
 
54
- **Skip**:自检 ≤2 Yes;Q5 高重叠(更新已有而非新建);纯机械工作(格式化、依赖升级、typo);问题未经验证。
54
+ **Skip**:自检 ≤2 Yes;Q5 高重叠(更新已有而非新建);纯机械工作(格式化、依赖升级、typo);问题未经验证。独立交付 plan 的 disposition 义务不因跳过结晶而消失——结晶跳过时以 reasoned `skipped` 记录结果(记录在 workflow,见「Integration with mstar lifecycle」)。
55
55
 
56
56
  ## Two tracks
57
57