@mstar-harness/dsh 3.9.4 → 3.10.0

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

@@ -15,6 +15,7 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 | Plan template (Global Constraints, Interfaces) | `templates/plan.main.md` |
 | knowledge / iterations / specs boundaries and indexes | `references/knowledge-and-designs.md` |
 | `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` |
+| Plan-level workflow lifecycle: delivery-kind declaration, stages, evidence contracts, engine seams | `references/plan-workflow-lifecycle-contract.md` |
 | Empty-repo `status.json` template | `templates/status.empty.json` (`templates/README.md`) |
 | Tech-debt rollup (read-only) | `mstar status tech-debt [path]` (engine `techDebtRollup`; see `references/status-and-residuals.md`) |
 
@@ -32,7 +33,7 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 - **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”).
 - **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.
 
-- **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”).
+- **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”).
 
 > **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.
 
@@ -53,7 +54,7 @@ Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq
 ## Decision Rules
 
 - residual **severity** 是机器字段 SSOT（`references/status-and-residuals.md`）；每条新 finding 只登记 project register（`projects/<id>/residuals.json` → `entries[<plan-id>]`），v1 根级 `residual_findings` 仅 legacy 只读，**禁止**双写。
-- **`Findings cleanup: zero-residual`** 默认（迭代 Phase 2）：可修 findings 当轮 fix → re-review 清干净；仅真 blocker 可 defer 且须 Durable Roadmap。
+- **`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」。
 - 登记前必须过 `validateResidual` / `validateProjectRegister` / `validateStatus`（fail-loud handoff）；malformed → reject + rewrite。
 - **计划行 / register 只经 domain call 修改**：scoped 路线使用 `mstar plan …` 动词（带 `--session` 与 `--expect`），手写 snapshot / register 会被拒（`coordination.direct-write-refused` / `coordination.scoped-writer-required`）；只读校验器（`mstar lease verify` / `mstar worktree check`）是检查而非修改替代。
 
@@ -66,3 +67,4 @@ Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq
 - `references/plan-files-and-reports.md` — 主 plan / review bundle 命名、QC 波次、durable summaries
 - `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
 - `references/knowledge-and-designs.md` — knowledge / iterations / specs 边界与索引
+- `references/plan-workflow-lifecycle-contract.md` — plan-level workflow lifecycle contract: delivery-kind declaration, stages, evidence contracts, engine seams

package/harness-skills/mstar-artifacts/references/plan-files-and-reports.md

@@ -42,7 +42,7 @@ Raw bundle files may disappear after the working context is gone. Before Done, P
   - `Review bundle`: `{SDD_DIR}/review/`
   - `QC inputs`: `qc1.md` / `qc2.md` / `qc3.md` or `qc.md`
   - `Blocking result`: fixed / none / deferred with reason
-  - `Residual findings`: R# ids + short titles + owner/target
+  - `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)
 - Main plan `## QA Gate Summary` when QA applies:
   - `QA gate` / `QA mode`
   - evidence reused vs newly run checks

package/harness-skills/mstar-artifacts/references/plan-quality-bar.md

@@ -76,6 +76,15 @@ Do not add repository-wide build/test/lint/typecheck gates for insurance. Full s
 
 "Works correctly" is not a done criterion.
 
+### 7. Task shape / session fit
+
+Each task fits **one focused implementer round** — the round closes the task's declared Files list and verification gates, not a slice of them:
+
+- **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.
+- **Named split point** — every task states where it breaks if one-round closure fails, so PM can split without re-deriving the boundary.
+- **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.
+- **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.
+
 ## Relationship to existing plan elements
 
 | This quality bar | Existing mstar element |
@@ -86,6 +95,7 @@ Do not add repository-wide build/test/lint/typecheck gates for insurance. Full s
 | STOP conditions | New — not previously formalized |
 | Drift check | SDD `BASE_SHA` — generalized to all plans |
 | Done criteria | `plan.main.md` per-step checkboxes — elevated to machine-checkable |
+| 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 |
 
 ## When to apply
 

package/harness-skills/mstar-artifacts/references/plan-workflow-lifecycle-contract.md

@@ -0,0 +1,115 @@
+# Plan workflow lifecycle contract
+
+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.
+
+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.
+
+## Foundational distinctions
+
+Three meanings that must remain separate:
+
+- **Standalone plan workflow:** an independently owned `type: plan` lifecycle, with its own delivery obligation and terminal close.
+- **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.
+- **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`.
+
+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.
+
+## 1. Delivery-kind declaration
+
+Every workflow declares its delivery kind at registration, as part of the registration evidence (§4a). Declared kinds:
+
+- **`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.
+- **`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.
+
+Binding rules:
+
+- 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.
+- 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.
+- Verification/report-only workflows follow their recorded explicit completion policy, not an accidental PR exemption inferred from missing fields.
+- 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.
+
+## 2. Cardinality stance
+
+- 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.
+- **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).
+- **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.
+
+## 3. Lifecycle stages
+
+The common delivery lifecycle:
+
+```
+register → recall → prepare/lock → execute + review/acceptance → compound disposition → submit PR → merge-ready (milestone) → verify merge → terminal close/unregister/reconcile
+```
+
+| Stage | Producer | Evidence (recorded) | Failure behavior |
+|---|---|---|---|
+| 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. |
+| 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. |
+| 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. |
+| 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). |
+| 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. |
+| 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. |
+| 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). |
+| 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. |
+| 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. |
+
+**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.
+
+## 4. Evidence contracts
+
+**(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.
+
+**(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.
+
+**(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.
+
+**(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.
+
+**(e) Merge-ready.** Leaves the workflow registered and resumable. A requirement to submit a PR implies no authorization to merge it.
+
+**(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.
+
+**(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.
+
+## 5. Failure and abandonment
+
+- Failure and abandonment close through explicit `failed`/`stopped` statuses with a recorded reason. They are never rewritten as successfully completed.
+- `closeWorkflow` preserves an existing valid terminal snapshot unchanged, including `failed`/`stopped` — idempotence this contract keeps.
+- Close never releases leases. Another owner's lease is not released to force closure; strict terminal validation refuses leases without deleting them.
+- Scoped and plan-scoped sessions cannot mutate lifecycle anchors or close sibling workflows (foundational distinctions, third meaning).
+
+## 6. Engine seam inventory
+
+Three named seams. Per-seam acceptance checks state the observable behavior each seam owes. This section specifies seams; it implements none of them.
+
+**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).
+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.
+
+**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.
+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.
+
+**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.
+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.
+
+**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.
+
+## 7. Scope decisions
+
+The direction and reason columns record the reasoning behind each answer; the answers are binding. There are no open decisions in this table.
+
+| Decision | Answer | Direction | Reason |
+|---|---|---|---|
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+
+## Binding negatives
+
+- 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.
+- No forced PR for `verification/report-only` workflows. Their completion follows the policy recorded at registration (§1).
+- No silent completion anywhere. Every stage transition records its evidence; failure renders the workflow blocked/active, never implicitly done.
+- 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.
+- Close never releases leases, and terminal `failed`/`stopped` states are never rewritten as `completed` (§5).

package/harness-skills/mstar-artifacts/references/status-and-residuals.md

@@ -97,6 +97,8 @@ Canonical vs legacy residual definitions → **`mstar-artifacts` SKILL.md**（"`
 - **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.
 - Terminal statuses (`completed` / `failed` / `stopped`) require `ended_at` and no dangling leases.
 - **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`).
+- **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.
+- **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.
 - **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」.
 - `execution_policy` keys are copied from v1 root `metadata` at migrate; values are accepted-but-opaque this iteration (no semantic gate).
 - `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`.
@@ -245,7 +247,7 @@ The v1 `plans[].metadata.findings_cleanup` mirror is **deleted** in v3 — no du
 
 | Context | Default |
 | ------- | ------- |
-| Formal **iteration Phase 2** (Autonomous Execute) | `zero-residual` (compass or Assignment may override to `allow-residual`) |
+| Formal **iteration Phase 2** (Autonomous Execute) | `allow-residual` (compass or Assignment may still override, including to `zero-residual`) |
 | Standalone `/pm`, hotfix, `Execution mode: inline` | `allow-residual` |
 
 ### `zero-residual` (clean-session)
@@ -260,9 +262,14 @@ Intent: clear findings in the current plan session whenever possible. Open resid
 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.
 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`.
 
-### `allow-residual` (legacy default)
+### `allow-residual`
 
-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).
+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:
+
+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.
+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`.
+3. **Critical still blocks**: an unresolved `critical` blocks `Approve`; `medium` / `low` / `nit` may be registered and carried (fix-now remains preferred when cheap).
+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.
 
 > **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.
 
@@ -415,6 +422,20 @@ Per-state `reconcile` outcome **and** the recovery action it requires are **rout
 
 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.
 
+### Prepare workflow amendment (guarded Prepare-only structural delta)
+
+**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.
+
+**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.
+
+**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).
+
+**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.
+
+**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.
+
+**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.
+
 ---
 
 ## General constraints

package/harness-skills/mstar-artifacts/templates/plan.main.md

@@ -10,7 +10,7 @@
 
 **Execution:** mstar-sdd | inline
 
-**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)]
+**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)]
 
 ## Global Constraints
 
@@ -20,6 +20,10 @@
 
 ### Task 1: [Component Name]
 
+**Effort (agent-oriented):** [XS–XL band per `mstar-conventions/references/effort-estimation.md` — a size estimate, not a round ceiling]
+
+**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)]
+
 **Files:**
 - Create: `exact/path/to/file`
 - Modify: `exact/path/existing.py`
@@ -63,6 +67,7 @@ Reuse unaffected evidence with its original range and applicability; do not repe
 1. **Spec coverage:** every spec requirement maps to a task
 2. **Placeholder check:** task-owned paths/checks are concrete; executable tests have a real case, docs/policy have scoped evidence
 3. **Type consistency:** names match across tasks
+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)
 
 ## SDD runtime (ephemeral)
 

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

@@ -13,7 +13,7 @@ description: Morning Star 知识结晶 —— 将已解决问题的经验沉淀
 
 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.
 
-**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.
+**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」).
 
 Knowledge that isn't captured evaporates when the session ends. Knowledge that is captured but not discoverable is equally lost. This skill addresses both.
 
@@ -29,7 +29,7 @@ Knowledge that isn't captured evaporates when the session ends. Knowledge that i
 
 ## Integration with mstar lifecycle
 
-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 是迭代级收口活动。
+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`。
 
 ### Iteration package promotion（iteration-close 强制盘点）
 
@@ -49,9 +49,9 @@ Compound 在迭代收口时触发（`mstar-iteration` § iteration-close），
 
 ## When to use / Skip
 
-**Use**：迭代收口（`mstar-iteration` § iteration-close）批量回顾；独立触发（非迭代或紧急，任何非平凡问题解决后）；重大 bug 修复后（`mstar-iteration` 未启用时手动）。
+**Use**：迭代收口（`mstar-iteration` § iteration-close）批量回顾；独立触发（非迭代或紧急，任何非平凡问题解决后）；重大 bug 修复后（`mstar-iteration` 未启用时手动）；独立 development plan 交付前的 disposition review（PR head 定稿前，见「Integration with mstar lifecycle」）。
 
-**Skip**：自检 ≤2 Yes；Q5 高重叠（更新已有而非新建）；纯机械工作（格式化、依赖升级、typo）；问题未经验证。
+**Skip**：自检 ≤2 Yes；Q5 高重叠（更新已有而非新建）；纯机械工作（格式化、依赖升级、typo）；问题未经验证。独立交付 plan 的 disposition 义务不因跳过结晶而消失——结晶跳过时以 reasoned `skipped` 记录结果（记录在 workflow，见「Integration with mstar lifecycle」）。
 
 ## Two tracks
 

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

@@ -179,6 +179,7 @@ Legacy `.agents/` 等价：
 - **Spec 集成分支**：从 `iteration_base_branch` 创建；各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
 - **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
 - **PR target**：全部 Plans 与 iteration-close 完成后，向显式 `target_branch` 提 PR（窄例外见 Assignment `Branch policy`）。
+- **Standalone development plan**：单 plan 交付不经迭代集成序列——交付分支上完成 compound disposition 后向显式 target 提交 PR，PR 身份（repo/head/target）在提交时记录；序列与语义 → `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`（迭代序列不变，见上）。
 - Git 操作与 QC 单一 `HEAD` → **`mstar-branch-worktree`**。
 - workflow snapshot 登记顶层 `branch.base`（`iteration_base_branch`）/ `branch.target`（`target_branch`）/ `branch.integration`（`spec_integration_branch`），以及 plan 行 `metadata.spec_integration_branch` / `merge_target` → **`mstar-artifacts`**。
 

package/harness-skills/mstar-conventions/references/effort-estimation.md

@@ -25,6 +25,8 @@
 
 「**会话**」指：一次连贯的 agent 运行（读上下文 → 实现 → 运行验证），**不是**人类 8 小时工作日。
 
+任务层使用：每 task 的容量判据（单轮闭合其 Files 与验证门、命名 split point）→ **`mstar-artifacts/references/plan-quality-bar.md`** item 7（Task shape / session fit）；本尺码只是规模预估，**不**定义单轮上限。
+
 ## 文档与模板中的字段名（建议）
 
 - **PRD / 产品文档**：**`## Effort (agent-oriented)`** — 仅 **Complexity (XS–XL) + agent session band + 假设**（规格已锁、契约稳定等）。  

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

@@ -72,7 +72,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 
 在支持具名角色 / Task 的宿主上，`## Assignment` **正文不会**拉起子会话。PM 须在**同一条 assistant 消息**（或宿主等价机制）发出与 Assignment **条数一致**的 invoke / Task；仅打印 Markdown = **分派未完成**。**几条 Assignment ⇒ 几次 tool 调用**（默认同消息并行）。
 
-> **Engine check (when available):** run `mstar dispatch validate <assignment-file> [--branch <branch>]` (or `import { validateAssignmentFields, assertDefaultBranchProtected } from "@mstar-harness/engine"` in a host hook) to validate the Assignment field contract and the default-branch gate (normative default-branch prose: **`mstar-branch-worktree`** SKILL.md § "Git 功能分支门禁（业务仓库）" — this skill covers dispatch mechanics only). 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 dispatch validate <assignment-file> [--branch <branch>]` (or `import { validateAssignmentFields, assertDefaultBranchProtected } from "@mstar-harness/engine"` in a host hook) to validate the Assignment field contract — including the canonical **`Task budget (implement / ops rounds)`** header field on non-review / non-audit rounds: presence-only in the header region, absent / empty / `N/A` → validation fail (field guidance → `mstar-roles/references/project-manager/dispatch-and-assignment.md`; capacity criterion → `mstar-artifacts/references/plan-quality-bar.md` item 7) — and the default-branch gate (normative default-branch prose: **`mstar-branch-worktree`** SKILL.md § "Git 功能分支门禁（业务仓库）" — this skill covers dispatch mechanics only). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ## SDD implement 波次（PM only）
 

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

@@ -32,7 +32,7 @@ description: Morning Star (启明星) harness **生命周期 / 授权语义权
 
 ## 最小交付循环
 
-**per-plan**：`specify → clarify → plan` → `plan(locked) → tasks → implement`（多 task 默认 SDD）→ plan QC tri + **QA gate**（`mandatory` 派 QA 或 `pm-acceptance`）→ Done（`inline` 单席例外）。阶段细则 → **`mstar-phase-gates`**；QA 分级 → **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**。
+**per-plan**：`specify → clarify → plan` → `plan(locked) → tasks → implement`（多 task 默认 SDD）→ plan QC tri + **QA gate**（`mandatory` 派 QA 或 `pm-acceptance`）→ Done（`inline` 单席例外）。阶段细则 → **`mstar-phase-gates`**；QA 分级 → **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**。独立交付 development plan 在 Done 后继续交付尾段 `compound disposition → submit PR → merge-ready（resumable milestone）→ verify merge → terminal close/unregister/reconcile`（`verification/report-only` 按注册声明的替代完成政策，无强制 PR；注册与尾段语义/失败行为的权威 = 冻结契约 **`mstar-artifacts/references/plan-workflow-lifecycle-contract.md`**，PM 步骤序列 → **`mstar-roles/references/project-manager/plan-management.md`**）。迭代内 plan 行不各自走尾段，迭代整体走一次（见下行）。
 
 **迭代级**：`iteration-start → [per-plan cycle × N] → iteration-close → PR delivery → PR merge-ready loop`。细则 → **`mstar-iteration`**。
 
@@ -72,7 +72,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `docs` | `@product-manager` / `@architect` / `@writing-specialist` |
 | `audit` | `@code-reviewer`（mstar-audit 承载；大型仓库经 Assignment `Delegation: allowed (scout/explore only, read-only)` 扇出只读 scout；read-only advisory；不进入状态机） |
 
-**硬规则**：`quick` **从不**跳过 `specify → clarify → plan`；禁止把新 CLI/API/多模块/新测例标为 `quick`。已启用 `{HARNESS_DIR}` 时，首次 implement 前须有主 plan 路径 + `status.json` 登记（见 **`mstar-conventions`**）。
+**硬规则**：`quick` **从不**跳过 `specify → clarify → plan`；禁止把新 CLI/API/多模块/新测例标为 `quick`。已启用 `{HARNESS_DIR}` 时，首次 implement 前须有主 plan 路径 + `status.json` 登记（见 **`mstar-conventions`**）。workflow 注册本身是 authorized domain operation（经授权 producer 的引擎原语，不自创第二注册机制），语义 → 冻结契约 `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`。
 
 ## `@explore` 边界
 

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

@@ -52,14 +52,20 @@ On **dsh** only, read-only fan-out of **N ≥ 3** seats runs through the native
 
 ## `/goal` directive (host-agnostic)
 
-**Applicability is by capability, not host identity**: any host that exposes a `/goal` command (currently Codex Goal Mode and omp; other code agents may add it later) attaches a persistent objective to the thread. **Exception — dsh:** mstar **stops arming** a goal there and never uses a `/goal` objective or a goal round loop as the progression driver — dsh runs on the native workflow (workflow snapshot phases + dispatch gates + **subagent settle notifications**; Phase 2 is a PM-local dispatch → wait for the child's settle notification → next dispatch, and a manually armed `/goal` stays outside mstar's flow). Full rule → `references/dsh.md`. Rule — **always set the goal to running the complete flow to the end**, never a sub-stage:
+**Applicability is by capability, not host identity**: any host that exposes a `/goal` command (currently Codex Goal Mode and omp; other code agents may add it later) attaches a persistent objective to the thread. **Exception — dsh:** mstar **stops arming** a goal there and never uses a `/goal` objective or a goal round loop as the progression driver — dsh runs on the native workflow (workflow snapshot phases + dispatch gates + **subagent settle notifications**; each settle notification is a **`result-settled` Rescheduling checkpoint** — run that checkpoint and dispatch the ready independent work before any wait, never "one settle → one dispatch", per `mstar-iteration` `references/phase-2-worktree-lease.md` §2.4; a manually armed `/goal` stays outside mstar's flow). Full rule → `references/dsh.md`. Rule — **always set the goal to running the complete flow to the end**, never a sub-stage:
 
 - **Advancing an iteration**: set the goal to **complete the entire iteration flow** (`iteration-start → per-plan cycles → iteration-close → PR delivery → PR merge-ready loop`). Do not set a sub-stage goal (e.g. "finish Phase 1 only").
-- **Advancing non-iteration work** (single plan / hotfix / one-off task): set the goal to **complete the entire per-plan flow** (`specify → clarify → plan → tasks → implement → plan QC tri + QA gate → Done`). Do not set a sub-stage goal (e.g. "write the plan" or "implement one task").
+- **Advancing non-iteration work** (single plan / hotfix / one-off task): set the goal to **complete the entire per-plan flow** (`specify → clarify → plan → tasks → implement → plan QC tri + QA gate → Done`; standalone development plans continue through the delivery tail to verified merge + terminal close — `mstar-harness-core`「最小交付循环」/ `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`). Do not set a sub-stage goal (e.g. "write the plan" or "implement one task").
 - **Scoped primary route** (`/iteration-drive --assignment | --workflow <id> --plan <id> | --resume <session.json>`): the goal is the **active plan scope only** — `mstar plan bind` → constrain → tasks → per-task review → plan QC tri / QA → `mstar plan handoff`. Never set a goal that spans the iteration flow, sibling plans, or Phase 3–6: those stay in the coordinator's own primary session, not this plan-scoped one (`mstar-iteration` `references/plan-scoped-pm.md` §5).
 
 Goal text is a session-level objective only: `{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json` remain SSOT, and goal completion is **not** harness Done. Mirror goal success criteria into the SSOT plan; when the goal changes, update goal text and the SSOT in the same round.
 
+## Phase-transition todo refresh (host-agnostic)
+
+At **every phase transition** (Prepare → Execute → InReview waves → Phase 3 close → Phase 4 PR → Phase 5 merge-ready → Phase 6 post-merge; likewise per-plan gate crossings), the PM refreshes the host session `todo` list **before the next action or dispatch**: close only the finished phase's **completed** entries, preserve any still-pending gate or future-phase item, and append the next phase's entries. Scoped primary sessions project only their assigned plan through handoff — never global Phase 3–6 tasks (`mstar-iteration` `references/command-shared-invariants.md` § Session todos; `references/phase-2-worktree-lease.md` §2.1).
+
+`todo` entries are a projection, not SSOT: they reflect existing snapshot phase / plan states and named plan/gate evidence, and cannot authorize or invent a state transition. Snapshot and plan artifacts remain the state authorities; this is freshness discipline, not a new host hook, tool, or deterministic enforcement mechanism.
+
 ## Resolve loaded skill root
 
 Docs name assets as skill **`<name>`** → `scripts/…` / `references/…`. **Resolve the loaded skill directory first** — do **not** open `skills/<name>/…` from a consumer app cwd (that layout exists in the harness source / plugin package only).

package/harness-skills/mstar-host/references/_shared/plan-mode-bridge-core.md

@@ -49,6 +49,8 @@ Not allowed in the parent Build session by default: product implementation, test
 | **`spec-register`** | Register plan in SSOT | New root `workflows[]` entry (`{HARNESS_DIR}/status.json` v2) + `plans[]` row in `{WORKFLOW_DIR}/<id>/snapshot.json` (`id`, `status`, `file`, `metadata`); spec stub in `{SPECS_DIR}` or plan frontmatter |
 | **`mirror-plan`** | SSOT main plan file | `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes aligned to the host plan body |
 
+`spec-register` is an authorized domain operation (engine producer primitives), declares the workflow's delivery kind, and blocks implementation until complete — plan-mode resumes owe the same registration obligation. Semantics → `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`.
+
 After the host plan is created, keep the host plan body and mirror file **in sync** when scope changes (update both in the same coordination round).
 
 ## Implement todo completion gate (every code todo)

package/harness-skills/mstar-host/references/dsh.md

@@ -360,10 +360,14 @@ armed and the agent is idle, and it knows nothing about running subagents, so
 an operator who arms `/goal` manually can still get rounds firing while a
 dispatched child owns the critical path.
 
-**Phase 2 continuous execution is a PM-local loop**: dispatch → **wait for the
-child's settle notification** → next dispatch. When a dispatched child owns the
-critical path, the correct action is to **wait** — not to open another unit of
-work against the same worktree.
+**Phase 2 continuous execution is a PM-local loop**, not a one-wave-at-a-time
+queue: each child's settle notification is a **`result-settled`
+`Rescheduling checkpoint`** — run that checkpoint and dispatch what is already
+ready and authorized (independent plans and plan-local tasks, each in its own
+isolated track) before waiting, and wait only when it finds none. Waiting stays
+the correct action for work a running child already owns — never open another
+unit of work **against the same worktree**. Procedure (and its frozen reason
+vocabulary) → `mstar-iteration/references/phase-2-worktree-lease.md` §2.4.
 
 The **scoped plan route** changes none of this: `/iteration-drive --assignment |
 --workflow --plan | --resume` still never arms a goal on dsh, and its

package/harness-skills/mstar-host/references/omp.md

@@ -210,7 +210,9 @@ Cannot emit required **N** → **`Blocked`**.
 
 ## In-process engine binding (omp ≥ 17.2.11)
 
-- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers these by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`.
+- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `extensions/model-handoff.js` — the coordinator model-handoff extension, published through the manifest `omp.extensions` entry (see **Model handoff** below); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers `hooks/` and `tools/` by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`; `extensions/` is discovered from the manifest entry.
+
+- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `extensions/phase2-orchestration.js` — the Phase-2 reminder + launch-bookkeeping extension (`mstar_phase2`), published through the manifest `omp.extensions` entry (see **Phase-2 plan instances** below); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers these by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`.
 |- **Enforcement semantics**: block ONLY under `Enforcement: hard`. Both gates read the repo `.mstarc` `[config] enforcement`, else the harness compass frontmatter (`enforcement: hard`, active/locked iterations only); the dispatch gate ALSO honors each Assignment's own header flag (`assignmentHeaderRegion` — a body example never hardens). A hard repo setting therefore hardens flag-less dispatches (Gate 1 / dsh `resolveDispatchHard` parity). Soft-mode dispatch violations are warn-logged through the extension logger (never blocked); soft status-write violations stay a silent pass. Rollback = unset the flag (or `.mstarc` `soft`). Never global.
 - **Anti-recursion scope (issue #156)**: the engine's `antiRecursionPrecheck` is **caller-scoped** — it compares the DISPATCHING agent's own role against the new Assignment's `Execute as`. omp's `tool_call` event carries no caller identity and the task entry `agent` is the spawn TARGET, which equals `Execute as` on every compliant dispatch (C5 above) — so Gate 2 does NOT run the precheck on omp (the pre-#156 wiring hard-blocked every compliant hard-mode dispatch on `self-type`, or on `empty-binding` when `agent` was omitted). The NEVER red line stays prompt-level on this host (`mstar-dispatch-gates`); dsh enforces it in-engine via Config `dispatchBinding`.
 - **Engine dependency**: the npm package **bundles the engine inline** into every hook/tool bundle at build time — zero runtime package resolution, so module link can never fail on a missing package (the 2026-09-03 hotfix for the bare-import load failure). The maintainer `omp plugin link` path (now `<repo>/packages/omp`) still resolves the engine via the workspace member — run `bun install && bun run engine:build && bun run --cwd packages/omp build` in the checkout first (the member's `dist/` and the package's generated mirrors are gitignored).
@@ -220,6 +222,64 @@ Cannot emit required **N** → **`Blocked`**.
 - **Engine version compatibility**: the hook and tools degrade gracefully until the engine release exporting both `composeDispatchGate` and `parseCompassFrontmatter` (published 2.0.2 predates both). Missing exports never fail module load: the hook's dispatch gate needs `composeDispatchGate` — on older engines Gate 2 (task dispatch) is skipped with a one-time warning while Gate 1 (status) stays active — and `mstar_dispatch_validate` / `mstar_iteration_gate` report an explicit upgrade error instead of loading (no silent absence; CLI fallbacks: `mstar dispatch validate`, `mstar iteration gate`).
 - **Reload**: edits are picked up by a new session (`?mtime` cache-buster); in-session `/reload-plugins` (omp ≥ 17.2.11) applies them without a new session.
 
+## Model handoff (native settings)
+
+A second extension entry from this package: `extensions/model-handoff.js` (manifest `omp.extensions`; engine inlined, its single `@oh-my-pi/pi-coding-agent` import resolved by the running host). It is a **coordinator model policy owned by native settings**, not a user command — no session, flag, goal or prose can enable it.
+
+| Surface | Contract |
+|---|---|
+| Native path | `/settings` → **Plugins** → **`@mstar-harness/omp`** — the rows are the schema keys: `modelHandoff` (boolean, default `false`) and `handoffTarget` (`@default` \| `@smol`, default `@default`). No activation command, no harness settings file, no second settings UI. |
+| Persistence | Host plugin settings (user-scope `omp-plugins.lock.json`, plus project `plugin-overrides.json`), reread through the exported helper at entry **and again at fire time** — a mid-flight enable never retro-arms an iteration already under way, and disabling at fire time suppresses the switch without terminalizing the binding. |
+| Scope | That panel lists **user-scope** installs; a project-scope npm install has no native row (host limitation, documented rather than worked around). Use the user-scope path — never double-install or add a private settings parser/UI. |
+| Supported entries | `/iteration-start`, `/iteration-loop`, and a natural-language / skill-driven start (`skill-start`) as labelled from the host's own `input` event. `/iteration-drive` in any form never arms — the scoped-plan route only restores the session's existing binding, and a start call after it is refused `scoped-plan-route`. |
+| Inert contexts | Ordinary chat, unrelated commands, leaf/subagent sessions (host `session_init` marker), plan-scoped PM sessions, other hosts, and an iteration whose coordinator never armed. |
+| PM binding | Tool `mstar_model_handoff`: the PM's **first preparation action** of a new iteration (`{operation:"start", workflowId:"<id>"}`) and the completion checkpoint (`{operation:"phase1-complete", …}`). Session identity, cwd, entry route, task-session state and coordinator authority are host-derived from the ledger, the workflow's own session envelopes and the root register; the call carries an explicit workflow id and nothing else. |
+| Ownership | One explicitly named workflow and control root own the coordinator. Missing, foreign or ambiguous ownership fails closed — no `workflows[0]`, latest-mtime, unique-new-row or "most recent" inference, and a concurrent sibling iteration stays untouched. Only the bound coordinator session changes model; role mappings, other sessions, subagents, goal objective and workflow snapshot status are never written. |
+| Full readiness | Fire requires the sequential specialist returns for that iteration, PM-confirmed Prepare gates for every registered plan with `compass status: locked`, a distinct same-repository integration checkout on its recorded branch, and a remote tip equal to the validated integration HEAD. `evaluatePhaseGate` is a later-phase gate and is never readiness evidence; a draft compass, a lock alone, a missing checkout or an unpushed commit is not ready. |
+| Cancellation | While pending, an unowned model change — history or live model — cancels the not-yet-executed switch, and the arm's own transition can never cancel it. Cancellation is deliberately conservative (it can also catch another extension's change; there is no exact user-selection event), and it never clears the saved preference. Navigation arriving during an invoked action is refused immediately; navigation arriving first fences the action instead of letting it start. |
+| Replay | Full session ledger with exact session-id filtering. A persisted attempt with no recorded outcome restores as `uncertain` — never retried, never reported as a successful handoff because the current model happens to match. Tree/branch/reload replay the ledger; a fork or new session id inherits nothing. |
+| Failure visibility | Refusals appear in the tool result, state transitions also as a durable session notice; the session keeps the model it actually has and there is no automatic retry loop. Missing auth, an unresolvable role and missing evidence are reported as failures, never as a handoff. |
+| Modes | Arming is observed from the host's `input` event, so it is documented for the interactive entries above only — no print/JSON/RPC automatic-behaviour claim exists (E1 boundary). The completion checkpoint is an ordinary tool call whose result the host renders like any other tool result. |
+
+Do not describe this feature as a `pause` flag, as a goal, or as a switch performed by any other session, and do not require a provider-side or upstream change to use it.
+
+## Phase-2 plan instances (native settings + optional transport)
+
+An extension entry from this package: `extensions/phase2-orchestration.js` (manifest `omp.extensions`; engine inlined, and its one runtime host import — `getPluginSettings` from `@oh-my-pi/pi-coding-agent/extensibility/plugins`, the public uncached settings reader — resolved by the running host, declared as an optional peer). It supplies one bounded Phase-2 advisory plus the `mstar_phase2` bookkeeping tool. It never spawns, merges, rewrites workflow state or releases leases — the optional skill below performs every CLI call, and engine scope/lease/revision/worktree/merge verbs stay authoritative.
+
+Phase 2 only. Ordinary sessions, leaf/subagent sessions, scoped-plan PM sessions and Phase 1/3–6 never activate the reminder or a launch.
+
+| Surface | Contract |
+|---|---|
+| Native path | `/settings` → **Plugins** → **`@mstar-harness/omp`** — the rows are the schema keys: `phase2PlanInstances` (boolean, default `false`) and `maxPlanInstances` (number, default `2`, minimum `1`, step `1`) with **no ceiling of 2**. |
+| Launch-only opt-in | `phase2PlanInstances` gates **extra primary launches only**. Native background task concurrency and the bounded reminder are independent of it: a disabled opt-in neither silences the reminder nor limits ordinary `task` dispatch. |
+| Configurable capacity | `maxPlanInstances` counts concurrently active **plan-scoped primaries** plus owned pending launch intents — the union by plan id, each counted once. The iteration coordinator and task subagents are excluded. Lowering it stops further launches and never kills running work. |
+| Invalid values | A present-but-malformed key (non-boolean, non-integer, below 1, unparsable) **fails visibly** and authorizes no launch — never coerced to the default, never an unbounded mode, never a silent hard limit. Absent keys take the schema defaults. |
+| Reminder | At most one advisory per **changed** opportunity observation, emitted at `agent_end` only; the observation key is recorded before the message, so identical unchanged state never re-fires and A→B→A does not re-nudge A. No timer, no polling, no invented job-settled event; a `null` snapshot means "unavailable", never "no jobs". Native completion delivery stays authoritative and is never duplicated. The advisory text asserts nothing about a plan being ready. |
+| Checkpoint pointer | The advisory only points at the shared Phase-2 rescheduling checkpoint (`mstar-iteration/references/phase-2-worktree-lease.md` §2.4). It never copies the decision matrix — this section does not either. |
+| Scope limitation (host behaviour) | The native `/settings` → Plugins panel lists **user-scope** plugin installs; a `--scope project` install has no row there (documented, not worked around). The runtime still reads the saved preference through the host's own settings helper. |
+
+### PM call sequence (tool `mstar_phase2`)
+
+Not a user activation command: nothing is spawned, merged, leased or written to engine state by the tool, and no session/flag/goal/prose can substitute for the calls below.
+
+1. **`bind`** — the coordinator's **first Phase-2 host action**, independent of any setting or model handoff, and also required on a no-argument `/iteration-drive` resume: `{operation:"bind", workflowId, coordinatorSessionPath}`. Authority is derived host-side from the session envelope plus the named snapshot, never from the call: it re-reads the engine coordinator/session identity, the workflow id, the control harness root, the accepted phase (`phase-2-execute`; an unknown/missing phase is disabled) and the checkout root (main worktree or the recorded integration worktree), and it rejects leaf/`session_init` sessions, foreign workflows, scoped-plan PM sessions and terminal workflows. It records a session **identity pointer** only — this is plugin observation binding, not engine `plan bind`, and it writes no engine credential.
+2. **`checkpoint`** — acknowledge that PM ran the shared scheduling procedure against the sample taken at that moment: `{operation:"checkpoint", reason, decision, note}`, `reason` ∈ `before-wait | result-settled | dependency-changed | ownership-changed | capacity-changed`, `decision` ∈ `dispatched | wait | blocked`. The runtime attaches the sampled key; the caller cannot choose or reset it. `blocked` suppresses advisory continuation until a new explicit user turn or a later checkpoint clears it — never a timer or incidental snapshot churn. A checkpoint carries a decision and note, never a ready list.
+3. **`reserve-launch`** — `{operation:"reserve-launch", planId, transport:"herdr"|"tmux", skill:{name,source}, capability:{executable,version,target}}`. Admission additionally requires the enabled opt-in, a valid latest capacity, a coordinator-prepared row with no plan binding/lease/handoff, the identical prepared Assignment hash, an existing canonical **distinct** feature worktree on its assigned branch, and the transport prerequisites. Only `applied:true` authorizes a side effect; an identical duplicate returns the recorded intent with `applied:false` and authorizes nothing, while a different live intent/binding for that plan refuses. Intents are journaled at `<workflow dir>/omp-launches.json` — a plugin-owned transport journal, never a lifecycle register.
+4. **`record-launch`** — one transition per observed step, each recorded **before** its matching side effect: `{operation:"record-launch", intentId, observation, target?, evidencePath}` with `observation` ∈ `starting | created | submitting | submitted | refused | uncertain`. Strict forward order `reserved → starting → created → submitting → submitted`; `starting` permits pane creation, `created` (which **requires the returned opaque target**) permits starting OMP in it, `submitting` permits the single scoped prompt. Only a newly persisted transition reports `applied:true`; PM acts only on that. `refused` is legal only for an observed failure that provably precedes any process/prompt side effect; from `submitting` onward a lost outcome is `uncertain`, which is terminal. A recorded target is never re-pointed, and settings/capacity/ownership are re-read before each side-effecting transition.
+
+### Optional transport (skill-driven — no compiled bridge)
+
+Every prerequisite is required and checked per launch: the **corresponding optional skill actually present in the catalog and read** (the `herdr` skill today; a tmux skill only if one truly exists — binary existence is not skill availability), the CLI executable available, and this session actually inside the matching managed environment (`HERDR_ENV=1`; `TMUX` set for tmux). Two managed environments visible at once is a visible refusal, not a focus-based choice. A missing prerequisite is a **visible no-op**: no process start, no silently substituted plan, native background scheduling intact, never a fabricated success. This never becomes a mandatory load-order dependency of the standalone `mstar-*` skill set.
+
+**Herdr** (the currently available contract — read the skill and its current group help/status at use): create the pane with `herdr pane split --current --direction <chosen> --cwd <prepared-worktree> --no-focus` and use the returned `result.pane.pane_id` verbatim as the opaque target; then `herdr agent start <unique-name> --kind omp --pane <returned-id>`; then submit exactly once with `herdr agent prompt <unique-name> "/iteration-drive --assignment <absolute-prepared-assignment>"`, without waiting for plan completion. Preserve CLI argument boundaries.
+
+**tmux** (conditional): only where a matching tmux skill is actually present **and read**, the CLI supports that skill's command forms, `TMUX` identifies this caller, and its explicit target is resolved. Use the skill's detached/non-focus creation with explicit cwd and returned pane id, launch OMP in it, and submit the same absolute scoped route; inspect help instead of guessing flags, and never shell-type into the user's focused pane. **No tmux skill exists in the current catalog**, so tmux is unavailable here — an unsupported seam to be named honestly, not a failed implementation and not a silent Herdr substitution.
+
+**Uncertainty, scope and ownership**: PM uses only returned opaque targets, records the observed command output before proceeding, and treats `agent_not_ready`, blocked UI, a timeout, a vanished response or a stalled submission as terminal — reported, never re-sent, never retried, with no fabricated id and no credential passed (no session JSON path, no `--expect` revision, no `--resume`). A created empty pane may be removed only with proven ownership and no possibly-active primary; panes are never killed to free capacity. Pane ready/idle/done means prompt transport is ready — never plan completion, lease release or ownership. The child obtains its own engine session through a fresh `plan bind`, runs only the prepared scope and stops at its durable handoff; the coordinator alone keeps serial integration and Phase 3–6 closure.
+
+**Evidence boundary**: this transport guidance is supported by **simulated** scripted skill/CLI observation traces (PM action sequences scored for command order, prepared cwd, non-focus creation, credential absence, opaque-target reuse, stopping on uncertainty and no blind resend) — not by a native end-to-end Herdr/tmux run, not by any probe of user terminals, and not by a real OMP child process.
+
 ## Files, shell, and approvals
 
 - Prefer host search/edit tools over shell find/sed when available.

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

@@ -99,7 +99,7 @@ Phase 6: post-merge close —— PR merged 后 §6.1–§6.4
 - 实际 Git ≠ `working_branch` → **同轮**更新 plan + snapshot + `execution_lease.working_branch`（如适用）
 - **跨 plan implement 并行安全闸**与 **integration merge 串行** → `references/phase-2-worktree-lease.md` §2.0 #5 /「Multi-plan parallelism」（**无论** `Worktree mode: waived`）
 - plan 内 SDD 独立 ready tasks **并行**，真实依赖与共享写目标串行 — phase-2 reference §2.4、§2.5、`mstar-sdd` Ready-task scheduling
-- **zero-residual（默认）**：单 plan QC findings 尽量当轮清干净；仅真 blocker 才 defer（须 Durable Roadmap）— 见 **`mstar-artifacts`** Findings cleanup modes
+- **allow-residual（默认）**：open R# 先登记 project register，且各决策面披露（清单 + severity + 跟踪位置；close 面另含 blocker-defer 标记）；unresolved `critical` 仍阻断 Approve；`zero-residual` 为显式 opt-in（可修当轮清干净，仅真 blocker-defer + Durable Roadmap）— 登记与披露职责 → **`mstar-artifacts`** Findings cleanup modes
 - iteration 命令共享的 PM invariants / preflight / todos / STOP → **`references/command-shared-invariants.md`**
 
 **Push cadence（§5.1a HARD）**：本地可提前修，**禁止**在 CI / AI review 波次未结束时 `git push` — 细则 → `references/phase-4-5-pr-delivery.md` §5.1a。

package/harness-skills/mstar-iteration/references/command-shared-invariants.md

@@ -54,6 +54,8 @@ if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validat
 | `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 §5.5 exit 全 `[x]` |
 | `phase-6-post-merge-close` | §5.2 exit 后 PR **已 merge**（mergeable ≠ merged） | Phase 6 §6.1–§6.4 完成（`mstar status workflow-close --workflow <id>` exit 0 + 投影一致） |
 
+Phase/gate 转换时按 **`mstar-host`**「Phase-transition todo refresh (host-agnostic)」按上表刷新会话 todos：先按 snapshot / plan 证据勾掉已完成 phase 条目，保留未决 gate / 未来 phase 条目，再追加下一 phase 条目；todos 只是投影，不授权状态转换。
+
 ## Continuous execution STOP list（重叠行；start / drive / loop 共有）
 
 Execute **`mstar-iteration` §2.6**（Continuous execution SSOT：自 Phase 2 进入至 Phase 5 §5.5 exit 前 PM **连续编排**，进度汇报后下一条必须是 dispatch 或下一 phase 步骤，不向用户例行 yes/no check-in）。

package/harness-skills/mstar-iteration/references/phase-1-prepare.md

@@ -124,6 +124,8 @@ iteration 正式全流程**必须**登记 `{HARNESS_DIR}/status.json`（v2 根
 
 compass frontmatter 的 `iteration_base_branch` / `target_branch` **必须与** snapshot `branch` 一致；若仅写在 compass 而 snapshot 缺失，Phase 2 §2.3 同轮 backfill。
 
+**中途增减范围（已存在且仍在 Prepare 的 workflow）**：用户/产品批准的范围扩张**不得**手改受保护状态。先以 `mstar plan bind --coordinator --workflow <id>` 建立该 workflow 的 coordinator 会话，再经受守卫入口 `mstar workflow show-prepare` 读取快照与 compass 两个字节版本，并以 `mstar workflow amend-prepare` 追加已批准的 Todo 行、登记已 review 的 integration checkout 与 `plan_parallelism`（仅 Prepare 且无执行所有权时可用；无 force/replace/init 通道）。守卫与字段权威 → **`mstar-artifacts`** `references/status-and-residuals.md`「Prepare workflow amendment」；forms / exit codes → `docs/cli.md` § `mstar-harness workflow`。
+
 ## 1.5.5 产物边界（specs · iterations · knowledge）
 
 Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（HARD）：