@mstar-harness/dsh 2.1.1

package/dist/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@mstar-harness/dsh`.
+ * @module @mstar-harness/dsh/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/dist/invariant.js

@@ -0,0 +1,29 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+
+// src/invariant.ts
+var PACKAGE_NAME = "@mstar-harness/dsh";
+var name = "dsh-invariant";
+var inject = ["invariants"];
+var install = () => {};
+var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+export {
+  name,
+  inject,
+  apply
+};

package/dist/service.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `ctx.dshMstar` service — the in-process Morning Star engine surface for
+ * dsh gate plugins. Backed by `@mstar-harness/engine` (bundled into the
+ * plugin dist at build time per the single-version convention; resolved
+ * through the workspace devDependency at dev/test time).
+ *
+ * @module @mstar-harness/dsh
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { EnforcementFlag, FindingsCleanupMode, GateResult, ResolveHarnessDirOptions, ResidualEntry, StatusDoc } from '@mstar-harness/engine';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Morning Star engine service provided by `@mstar-harness/dsh`. */
+        dshMstar: DshMstar;
+    }
+}
+/** Options for constructing the service (resolved plugin config). */
+export interface DshMstarOptions {
+    /**
+     * The boot-resolved `{HARNESS_DIR}`: the explicit `harnessDir` config root
+     * (null when unset). The plugin never probes from the process cwd —
+     * without the explicit config the harness dir resolves per session
+     * workspace at event time (the gates / pre-step catalog / tools), so the
+     * boot value is only the config-known part.
+     */
+    readonly harnessDir: string | null;
+}
+/**
+ * Morning Star engine access for dsh gate plugins.
+ *
+ * Layering: this service is the composition/test façade for
+ * FUTURE inject consumers (host adapters, catalogs, P2/P3 seams) — the
+ * P1 gates in `index.ts` are co-located engine wrappers that import
+ * `@mstar-harness/engine` directly (same plugin, engine bundled at build
+ * time), so the engine stays the single grammar for both paths. The service
+ * is constructed (and thereby self-registered) by the `dsh` function
+ * plugin's `apply`.
+ */
+export declare class DshMstar extends Service {
+    /**
+     * The boot-resolved `{HARNESS_DIR}` (the explicit config root, null when
+     * unset — per-workspace resolution happens at event time, never from the
+     * process cwd).
+     */
+    readonly harnessDir: string | null;
+    constructor(ctx: Context, options: DshMstarOptions);
+    /**
+     * Validate a status.json document or file path.
+     * @param docOrPath - parsed status document or path to a status.json file.
+     */
+    validateStatus(docOrPath: StatusDoc | string): GateResult;
+    /**
+     * Validate one residual entry (status-and-residuals.md § Basic structure).
+     * @param entry - the residual entry as parsed from status.json.
+     */
+    validateResidual(entry: ResidualEntry | unknown): GateResult;
+    /**
+     * Findings cleanup gate for one plan (status-and-residuals.md § Findings
+     * cleanup modes). Mode resolution: explicit `opts.mode` → `plans[].metadata.
+     * findings_cleanup` → `allow-residual`.
+     * @param doc - the parsed status document.
+     * @param planId - the plan whose open residuals are checked.
+     * @param opts - explicit cleanup-mode override.
+     */
+    findingsCleanupGate(doc: StatusDoc, planId: string, opts?: {
+        mode?: FindingsCleanupMode;
+    }): GateResult;
+    /**
+     * Resolve the repo-level hard-enforcement flag from the iteration compass
+     * (`{ITERATION_DIR}/<id>/delivery-compass.md` frontmatter `enforcement: hard`
+     * on active/locked compasses). Hard gates are never the default.
+     * @param harnessDir - the resolved `{HARNESS_DIR}`.
+     */
+    resolveCompassEnforcement(harnessDir: string): EnforcementFlag;
+    /**
+     * Resolve `{HARNESS_DIR}` per plan-conventions resolution order. This is
+     * the generic engine mirror — callers pass the workspace root they probe
+     * from explicitly; the plugin itself never probes from the process cwd.
+     * @param startDir - directory to probe from (defaults to the process cwd).
+     * @param opts - explicit harness-dir override or environment fallback.
+     */
+    resolveHarnessDir(startDir?: string, opts?: ResolveHarnessDirOptions): string | null;
+    /**
+     * Read the harness version (single-version invariant — 2.1.1).
+     * @returns the version string of the bundled/workspace engine manifest.
+     */
+    readHarnessVersion(): string;
+    /**
+     * Apply the `Enforcement: hard` flag to a gate result.
+     * @param gate - gate result to escalate.
+     * @param opts - whether hard enforcement is on.
+     */
+    applyEnforcement(gate: GateResult, opts: {
+        hard: boolean;
+    }): GateResult;
+}

package/dist/types.d.ts

@@ -0,0 +1,241 @@
+/**
+ * `mstar-engine-status` catalog source: a durable `catalog`-form
+ * MessageSource the plugin appends to
+ * every composed step at `agent/pre-step`, so the model-visible engine-status
+ * row is reconstructable from the session log without re-parsing its prose
+ * (model-visible ⟺ logged — dsh packages/AGENTS.md). Merge-extensible
+ * `MessageSourceMap` augmentation mirroring the `@deepseek-ai/dsh-tool-skill`
+ * precedent (declare module '@deepseek-ai/dsh-llm' + catalog-form source).
+ *
+ * `mstar-iteration-gate` is the sibling catalog row: the boot-cached
+ * `evaluatePhaseGate` verdict (tool result shape) appended after the
+ * engine-status row on the same
+ * pre-step listener.
+ *
+ * @module @mstar-harness/dsh
+ */
+import type { EnforcementFlag } from '@mstar-harness/engine';
+/**
+ * Durable provenance for the ONE unified engine-status catalog row. The
+ * catalog is a `catalog`-form context, so it records the facts it published
+ * beside the model-facing prose: a consumer presenting the row must not
+ * re-parse the `<mstar_engine_status>` block, whose framing exists for the
+ * model.
+ */
+export interface MstarEngineStatusSource {
+    readonly kind: 'mstar-engine-status';
+    readonly form: 'catalog';
+    /**
+     * The unified mstar version: the `@mstar-harness/dsh` plugin package
+     * version (own manifest). The single-version invariant pins the bundled
+     * `@mstar-harness/engine` to the same version, so one field covers both.
+     */
+    readonly version: string;
+    /** Resolved `{HARNESS_DIR}` (null when probing found none). */
+    readonly harnessDir: string | null;
+    /** Repo-level hard-enforcement flag from the iteration compass. */
+    readonly enforcement: EnforcementFlag;
+    /**
+     * Iteration phase-gate section: present when a steering compass +
+     * `status.json` resolve (the `mstar iteration gate` tool result shape).
+     */
+    readonly iteration?: MstarIterationGateView;
+    /**
+     * Workspace-state digest section: the plan registry, open residual
+     * counts, branch/policy anchors, active leases, knowledge index digest
+     * and the steering compass direction one-liner. Null when the workspace
+     * has no harness dir or no `status.json` (the state lines are absent).
+     */
+    readonly state: MstarHarnessState | null;
+}
+/** JSON projection of one engine `ValidationResult` (lossless — `fix` omitted when absent). */
+export interface IterationGateViolationView {
+    severity: 'critical' | 'high' | 'medium' | 'low' | 'nit';
+    code: string;
+    message: string;
+    fix?: string;
+}
+/** JSON projection of one engine gate (`GateResult`). */
+export interface IterationGateListView {
+    ok: boolean;
+    violations: IterationGateViolationView[];
+}
+/**
+ * JSON projection of the engine `PhaseGateResult` (snake_case to match the
+ * model-facing tool vocabulary of the CLI's `mstar iteration gate` — the
+ * tool result shape reused verbatim by the pre-step catalog row).
+ */
+export interface IterationGateView {
+    transition: 'phase-2-execute' | 'phase-3-close' | 'phase-4-pr-delivery';
+    all_plans_done: boolean;
+    ok: boolean;
+    entry: IterationGateListView;
+    exit: IterationGateListView;
+    violations: IterationGateViolationView[];
+}
+/** The iteration phase-gate section of the unified engine-status row. */
+export interface MstarIterationGateView {
+    /** Iteration id whose steering compass was evaluated. */
+    readonly iterationId: string;
+    /** Control-path `{HARNESS_DIR}/status.json` evaluated. */
+    readonly statusPath: string;
+    /** The steering `{ITERATION_DIR}/<id>/delivery-compass.md` evaluated. */
+    readonly compassPath: string;
+    /** Cached `evaluatePhaseGate` result (tool result shape). */
+    readonly gate: IterationGateView;
+    /**
+     * The steering compass frontmatter `status` (`'active' | 'locked'`), the
+     * authoritative signal for whether Phase 1 is still in flight vs. complete
+     * (spec panel-f4 §2.3 R9 / §5 D5). Optional and OMITTED when absent or
+     * not one of the two steering values (lossless omit-when-absent — the
+     * `iteration` key's discipline: `Session.append` rejects undefined-valued
+     * properties) — old catalog rows / typed fixtures without the field keep
+     * compiling and the projection degrades to the existing transition-driven
+     * behavior.
+     */
+    readonly compassStatus?: 'active' | 'locked';
+}
+/** One registered plan row of the harness-state digest (id + status + completion date). */
+export interface HarnessPlanView {
+    readonly id: string;
+    readonly status: string;
+    /**
+     * The `status.json` plan row `done_at` (trimmed string). ALWAYS-present
+     * nullable scalar: a missing/empty `done_at` projects to `null` (lossless
+     * JSON — never an `undefined` property; the omit pattern is reserved for
+     * optional fields like `verdict?`).
+     */
+    readonly doneAt: string | null;
+    /**
+     * The `status.json` plan row `metadata.iteration_refs` (array of iteration
+     * ids the plan is registered under). ALWAYS-present array (plan
+     * `20260813-panel-quick-fixes` Task 2): a missing/non-array value projects
+     * to `[]` — the empty default, never an omitted field (lossless JSON).
+     */
+    readonly iterationRefs: string[];
+}
+/** One open residual finding of the harness-state digest (`planId` = the owning `residual_findings` root key). */
+export interface ResidualFindingView {
+    readonly planId: string;
+    /** The finding's `id` (e.g. `R1`); '' when the source entry carries none. */
+    readonly id: string;
+    /** The finding's `severity` (one of the residual severity enum when known). */
+    readonly severity: string;
+    /** The finding's `title`; '' when the source entry carries none. */
+    readonly title: string;
+}
+/** Open residual finding counts by severity (non-zero severities only). */
+export interface HarnessResidualView {
+    readonly severity: 'critical' | 'high' | 'medium' | 'low' | 'nit';
+    readonly count: number;
+}
+/** One active plan execution lease of the harness-state digest. */
+export interface HarnessLeaseView {
+    readonly planId: string;
+    readonly holder: string;
+    readonly worktreePath: string | null;
+}
+/**
+ * The workspace-state digest section of the unified engine-status row: the
+ * plan registry, open residual counts, branch/policy anchors, active
+ * leases, knowledge index digest and the steering compass direction
+ * one-liner. All fields come from the same per-workspace cached build as
+ * the rest of the row (one status.json / compass / knowledge-index read
+ * per cache refresh — the TTL-bounded staleness tradeoff documented on
+ * `buildCatalogSources`).
+ */
+export interface MstarHarnessState {
+    /** Registered plan rows (`plan_id`/`id` + `status`), status.json order. */
+    readonly plans: readonly HarnessPlanView[];
+    /** Open `residual_findings` counts by severity (non-zero only). */
+    readonly residuals: readonly HarnessResidualView[];
+    /**
+     * Open residual findings detail (planId + R# + severity + title), severity
+     * ordered (critical→nit) and capped at 10. Null when the
+     * `residual_findings` root key is missing/unreadable (advisory — same null
+     * pattern as `knowledge`); `[]` when the key exists but has no open
+     * entries. Independent of the `residuals` rollup (which stays
+     * backward-compatible).
+     */
+    readonly residualFindings: readonly ResidualFindingView[] | null;
+    /** `metadata.iteration_base_branch` (compass frontmatter fallback), null when absent. */
+    readonly iterationBaseBranch: string | null;
+    /** `metadata.target_branch` (compass frontmatter fallback), null when absent. */
+    readonly targetBranch: string | null;
+    /** `metadata.spec_integration_branch`, null when absent. */
+    readonly specIntegrationBranch: string | null;
+    /** `metadata.push_policy`, null when absent. */
+    readonly pushPolicy: string | null;
+    /** `metadata.worktree_mode`, null when absent. */
+    readonly worktreeMode: string | null;
+    /** `metadata.control_worktree_path`, null when absent. */
+    readonly controlWorktreePath: string | null;
+    /** Active plan execution leases (holder + worktree). */
+    readonly leases: readonly HarnessLeaseView[];
+    /** Knowledge index digest (docs count + categories), null when no index. */
+    readonly knowledge: {
+        readonly docCount: number;
+        readonly categories: readonly string[];
+    } | null;
+    /** Steering compass direction one-liner (problem statement digest), null when unavailable. */
+    readonly direction: string | null;
+    /**
+     * Actual subagent flow evidence (the agent-flow ledger read — spec
+     * §2.1.3/§2.2): the latest dispatch/settle events (≤50) plus a role ×
+     * outcome summary over the same window. Null when the ledger file is
+     * missing or unreadable (advisory degrade — the agent-flow line is absent
+     * from the model text). Rendered text stays ~1 compact line (only when
+     * `events.length > 0`); the event detail lives in this structured source
+     * only. Same TTL as the rest of the state section (the catalog cache
+     * refreshes the ledger read at most once per `catalogTtlMs`).
+     */
+    readonly agentFlow: AgentFlowView | null;
+}
+/**
+ * One agent-flow ledger event in the catalog view. Optional dispatch/settle
+ * fields are OMITTED (never `undefined`-valued properties — `Session.append`
+ * rejects non-lossless JSON) using the `iterationViolationView` omit pattern.
+ */
+export interface AgentFlowEventView {
+    readonly ts: number;
+    readonly kind: 'dispatch' | 'settle';
+    /** The session's stable id; null when the event carried none. */
+    readonly agent: string | null;
+    /** Assignment `Execute as` ('' for settle rows without a paired identity). */
+    readonly role: string;
+    readonly planId: string | null;
+    readonly taskId: string | null;
+    readonly taskCategory: string | null;
+    /** Dispatch gate verdict (dispatch events only). */
+    readonly verdict?: 'ok' | 'advisory' | 'denied';
+    /** resolveDispatchHard result (dispatch events only). */
+    readonly hard?: boolean;
+    /** Settle outcome (settle events only). */
+    readonly outcome?: 'ok' | 'error' | 'denied';
+    /** Settle duration in ms (settle events only, when recorded). */
+    readonly durationMs?: number | null;
+    /**
+     * Settle rows only (plan `20260811-panel-f4-timeliness` Task 1): true when
+     * the settle carries the PAIRED dispatch's identity (`role`/`planId`/
+     * `taskId` — same fields + semantics as the dispatch event) — the client
+     * pairs exactly on that identity. ABSENT on unpaired (legacy) settles →
+     * they stay unpaired (honest, no owner+time guessing).
+     */
+    readonly paired?: boolean;
+}
+/** One role × outcome count of the agent-flow summary (count desc). */
+export interface AgentFlowSummaryRow {
+    readonly role: string;
+    readonly outcome: string;
+    readonly count: number;
+}
+/** The catalog's agent-flow evidence: latest events first (≤ limit) + summary. */
+export interface AgentFlowView {
+    readonly events: readonly AgentFlowEventView[];
+    readonly summary: readonly AgentFlowSummaryRow[];
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'mstar-engine-status': MstarEngineStatusSource;
+    }
+}

package/harness-commands/codebase-audit.md

@@ -0,0 +1,40 @@
+---
+name: codebase-audit
+description: Survey a codebase as a senior advisor and produce prioritized, self-contained improvement plans. Read-only on source code. Use standalone before iteration-start to discover what's worth doing, or independently to build a prioritized backlog.
+agent: project-manager
+input: "[no args]"
+---
+
+# Audit Codebase
+
+Run a read-only codebase audit that discovers what is worth doing and writes self-contained plans for the normal Prepare → Execute flow.
+
+**Read-only.** No source edits, no state machine, no commits. Output: prioritized plans in `{PLAN_DIR}/audit-<date>/`.
+
+## Boot
+
+1. `mstar-harness-core`
+2. `mstar-audit` → SKILL.md（workflow、hard rules、scope variants、handoff 全量在此）
+3. `mstar-roles` → `references/code-reviewer.md`（执行角色：audit 执行体）
+4. `mstar-plan-conventions` (path symbols — `{PLAN_DIR}`, `{HARNESS_DIR}`)
+5. `mstar-host` → active host reference (invoke capability for parallel subagents)
+
+## Routing（谁执行 audit）
+
+| Context | Who runs the audit |
+|---------|-------------------|
+| **Small repo** (single scan pass feasible) | PM dispatches `@code-reviewer` — single scan pass, then vet and write plans |
+| **Large repo** (parallel categories needed) | `@code-reviewer` fans out read-only `scout` / `explore` subagents per category via Assignment `Delegation: allowed (scout/explore only, read-only)`, then vets and writes plans |
+| **Specialist depth needed** | PM orchestrates an `@architect` consult for architecture/tech-debt depth (separate dispatch, or folded into the audit delegation brief) |
+
+This command is the PM entry point; the audit execution body is `code-reviewer`（PM dispatch）.
+
+The audit is **advisory** — it does not enter the per-plan state machine (`Todo → InProgress → InReview → Done`). Its output is plan *candidates*.
+
+## Execute
+
+Execute **`mstar-audit`** end to end（SKILL.md：Recon → Audit → Vet & prioritize → Write plans；effort `quick` / `standard` / `deep`；scope variants `security` / `perf` / `tests` / `branch` / `next` / `roadmap`）。Plans → `{PLAN_DIR}/audit-<YYYY-MM-DD>/NNN-<slug>.md` + `README.md` index，per **`mstar-plan-artifacts/references/plan-quality-bar.md`**。
+
+Executor: PM dispatches `@code-reviewer`；大型仓库 scout 扇出经 Assignment `Delegation: allowed (scout/explore only, read-only)`（Routing 表）。
+
+Pursued plans feed the normal Prepare → Execute flow（fast-track Prepare — intent gate + clarify still apply）or `/iteration-start` as direction candidates。

package/harness-commands/iteration-drive.md

@@ -0,0 +1,129 @@
+---
+name: iteration-drive
+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. Not Done until Phase 5 exit checklist passes.
+agent: project-manager
+input: "[no args]"
+---
+
+# Drive Iteration
+
+Drive the active Morning Star iteration forward. **Boot loads skills; this command sequences Phase 2 → 3 → 4 → 5.** Phase gate SSOT → **`mstar-iteration`** §2–§5；本 command 仅补充 **可选第三方 helper skill 发现**（Phase 5），不反向写入 `mstar-*`。
+
+## Phase flow（禁止跳步）
+
+`Phase 2: Autonomous Execute → Phase 3: iteration-close → Phase 4: Create PR → Phase 5: PR merge-ready`。Transition gates（HARD）→ **`mstar-iteration`** **Phase transition gates** table。
+
+**Done 定义**：**仅** Phase 5 §5.5 exit checklist 全 `[x]`。**Phase 3 close ≠ Done；Phase 4 开 PR ≠ Done。**
+
+## Continuous execution（HARD — Phase 2–5）
+
+Execute **`mstar-iteration` §2.6**（Continuous execution SSOT：自 Phase 2 进入至 Phase 5 §5.5 exit 前 PM **连续编排**，进度汇报后下一条必须是 dispatch 或下一 phase 步骤，不向用户例行 yes/no check-in）。
+
+**合法 STOP（仅此升级用户）**：
+
+- §2.0 / Phase 4 branch metadata 缺失（`iteration_base_branch` / `target_branch`）
+- **`Blocked`**：真冲突、secrets、不可逆范围缺口、Phase 5 多轮仍无法 merge-ready
+- 用户本轮显式打断
+
+**Turn 收束纪律**：若 host 即将结束本轮，最后一条 assistant 内容必须是 **in-flight 动作**（invoke 已发出、或写明下一 dispatch 的 Assignment 字段），**不得**以对用户的确认问句结尾。
+
+## PM invariants（Phase 2–5 全程有效）
+
+| 禁止（PM 线程） | 必须 |
+|-----------------|------|
+| Write/Edit/Shell 产品代码、写测试、跑 QC 审查（Phase 2） | 每条 implement/QC/QA Assignment ⇒ **1 次 `Task`** |
+| **多 task plan 用 inline 大包派发**（整份 plan / T1–Tn 贴进一个 dev Assignment） | **SDD**：`mstar-sdd` per-task 循环 — `mstar sdd task-brief` → implementer → `mstar sdd review-package` → task reviewer → `progress.md` |
+| 只写 Assignment 就进入下一 gate | 同轮 dispatch：`Subagent invokes issued: N`（N = Assignment 条数） |
+| 最后一个 plan `Done` 后直接开 PR / 汇报结束 | **Phase 3 → 4 → 5** 顺序执行 |
+| Phase 4 开 PR 后停止 | Phase 5 loop 至 merge-ready；**禁止**未过 §5.5 就结束会话 |
+| Phase 5 自己改产品代码 | 需改产品代码时 **dispatch** `fullstack-dev` / `ops-engineer` |
+
+派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。Phase 3 细则 → **`mstar-iteration` §3** + **`mstar-compound`**。
+
+**Session todos**：
+
+| Todo id | 何时追加 | 何时可勾掉 |
+|---------|----------|------------|
+| plan-wave todos | 进入 Phase 2 | 各 plan `Done` |
+| `phase-3-iteration-close` | 仅剩 1 个非 `Done` plan | Phase 3 §3.5 exit 全 `[x]` |
+| `phase-4-create-pr` | Phase 3 完成后 | PR 已创建并记录 URL/number |
+| `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 §5.5 exit 全 `[x]` |
+
+## Boot
+
+1. `mstar-harness-core`
+2. `mstar-roles` → `references/project-manager.md`
+3. `mstar-iteration` → **§ Phase 2–5**（§3 close gate；§4 PR delivery；§5 merge-ready loop）
+4. `mstar-compound` — Phase 3 §3.2 前加载（含 Phase 6 索引登记）
+5. `mstar-dispatch-gates` + host reference
+6. **`mstar-sdd`** — **before first implement dispatch** in Phase 2（per-task loop SSOT；多 task plan 默认 `Execution mode: sdd`）
+7. `mstar-review-qc` — before first QC dispatch in Phase 2
+8. `mstar-plan-artifacts`, `mstar-plan-conventions`, `mstar-branch-worktree`
+9. **`mstar-iteration/references/phase-2-worktree-lease.md`** — Phase 2 control worktree、`execution_lease`、serial `integration_merge_lease`（§2.0 #5 未 waive）
+
+## Phase 2: Autonomous Execute
+
+**Continuous execution applies**（上节）。Execute **`mstar-iteration` § Phase 2** exactly：§2.0 前置五道闸（含 branch metadata #4 + control-worktree/lease #5）→ §2.1 session todos → §2.2 read backlog（`status.json` + branch metadata）→ §2.3 integration branch + control worktree（record `metadata.control_worktree_path`；status/SDD via control path）→ §2.4 per-plan loop（**lease-gated parallel** across plan IDs unless `Plan parallelism: serial`；claim/resume `execution_lease`；feature worktree；**SDD** per-task 串行；QC full tri-review **N=3** + QA；serial merge via `integration_merge_lease`；cross-plan sync → compass）→ §2.5 dispatch-first → §2.6 push 纪律。全部 plan `Done` → **STOP**（Phase flow）→ 打印 `## Phase 3: iteration-close`；**不得**进入 Phase 4。
+
+**Assignment preflight**（`mstar-harness` bin 未安装时静默跳过）: 在每次 implement/QC/QA 派发前（**SDD** 下为最新 `{SDD_DIR}/task-N-brief.md` 或临时写盘的 Assignment），若本机装有 CLI，校验最新 Assignment。模式由迭代 compass frontmatter 的 `enforcement` 键决定（Slice 5）：
+
+- **默认（compass 无 `enforcement: hard`）— 可选 warn-only**：exit 1 仅提示，不阻断派发（Slice 3 行为不变）：
+
+```bash
+command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<latest-assignment-file>"
+```
+
+- **`enforcement: hard`（迭代 compass frontmatter 声明）— fail-fast**：校验失败即 `exit 1` 阻断派发（bin 缺失仍静默跳过）：
+
+```bash
+if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validate "<latest-assignment-file>" || exit 1; fi
+```
+
+> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
+
+## Phase 3: iteration-close
+
+当 **every** plan 为 `Done`：
+
+1. **STOP** per-plan loop — 不得开 PR、不得进入 Phase 4/5、不得输出「迭代完成」摘要。
+2. 打印标题 **`## Phase 3: iteration-close`**（用户可见的 phase 边界）。
+3. Execute **`mstar-iteration` § Phase 3**（→ **`references/phase-3-iteration-close.md`** §3.0→§3.5）：§3.0.5 compass 规范化 → §3.1 close entry checklist（**HARD GATE**，必须打印）→ §3.2 compound + **`<iteration-id>/` package promotion**（`mstar-compound` Phase 6 索引登记）→ §3.3 roadmap → §3.4 frontmatter `status: completed` + `end_date` → §3.5 close exit checklist + commit → push。
+4. §3.5 exit 全 `[x]` 且 compass `status: completed` 后 → 打印 **`## Phase 4: Create PR`**。
+
+**Phase 3 exit（非 iteration-drive Done）**: §3.5 checklist `[x]` + compass frontmatter `completed`。
+
+## Phase 4: Create PR
+
+Execute **`mstar-iteration` § Phase 4**（→ **`references/phase-4-5-pr-delivery.md`**）：打印 `## Phase 4: Create PR` → resolve `metadata.target_branch`（compass fallback；缺失 → **STOP**，never default `main`/`master`）→ 创建 PR `spec_integration_branch` → `target_branch` → 记录 PR URL + number（Phase 5 SSOT）→ 勾掉 host todo `phase-4-create-pr` → **Immediately** 打印 **`## Phase 5: PR merge-ready`**（**禁止**在此停止或汇报 Done）。
+
+**Phase 4 exit（非 iteration-drive Done）**: PR 已创建且 head = `spec_integration_branch`。
+
+## Phase 5: PR merge-ready（babysit loop）
+
+Execute **`mstar-iteration` § Phase 5**（→ **`references/phase-4-5-pr-delivery.md`** §5.0–§5.2；**§5.1a push cadence HARD**）。**§5.5 exit 全 `[x]` = iteration-drive Done.**
+
+本 command **叠加**可选 helper skill 发现（**non-`mstar-*`**；不写入 `mstar-*` load order）：
+
+### 5.0 Discover optional helper skills
+
+Helper 搜索路径 → **`mstar-iteration/references/phase5-helper-discovery.md`**（babysit / `*-babysit` / greploop 路径清单；first readable `SKILL.md` wins per name）。
+
+| Priority | Condition | Read before loop | Primary done signal |
+|----------|-----------|------------------|---------------------|
+| 1 | `babysit` **or** any `*-babysit` found | that skill’s `SKILL.md`（prefer exact `babysit`, else first matching `*-babysit`） | Required CI **all green** + **all** review threads **resolved** |
+| 2 | `greploop` found **and** repo has Greptile/greploop | `greploop` SKILL.md | Greptile score **5/5** on this PR（**additive** — does not replace priority-1 gates） |
+| 3 | else neither babysit/`*-babysit` | —（fallback = babysit 同级 CI + reviews 门禁） | Required CI **all green** + **all** review threads **resolved** |
+
+**Both babysit/`*-babysit` and greploop apply**: run **babysit/`*-babysit` first**（CI + reviews），then optional greploop until Greptile **5/5**（串行；§5.5 仍须满足全部 exit 项）。Do **not** prefer greploop over babysit。**No greploop / repo without Greptile**: skip greploop entirely。**All modes** share §5.5 exit checklist（Greptile 5/5 only when greploop mode ran or repo shows a Greptile score）。
+
+### 5.1 Loop + review fix hygiene（all modes）
+
+Execute **`mstar-iteration` §5.1 loop**（`references/phase-4-5-pr-delivery.md` §5.1）：status（`gh pr view <number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision` 或宿主等价 API）→ merge conflicts → unresolved reviews → CI → **§5.1a idle push**（一批修复一次 push）→ mode-specific pass（babysit SKILL / greploop / fallback）→ §5.1 review fix hygiene（**comment on same thread + resolve**）→ repeat until §5.5。Fixes **push 到 `spec_integration_branch`**（PR head）；禁止另开分支替代。**Checkout（HARD，§5.0）**：直接在 control / 集成分支 checkout 上修；**禁止**另开 Phase 5 fix worktree，**禁止**套用 Phase 2 control 产品编辑禁令。产品代码修复 → **dispatch** dev/ops（Assignment cwd = control）；PM 线程不代写。**禁止**为「让 CI 变绿」而改 workflow，除非用户明确授权。多轮仍 blocked → 升级用户。
+
+### 5.2 Phase 5 exit checklist（iteration-drive Done）
+
+Print **`## Phase 5 exit checklist`** per **`mstar-iteration` §5.2**（`references/phase-4-5-pr-delivery.md` §5.2：PR mergeable、required CI green、review threads resolved（或用户书面 waive）、§5.1 comment + resolve、todo `phase-5-pr-merge-ready`；Greptile 5/5 仅当 greploop mode / repo 可见分数）→ 全 `[x]` 后结束本 command。
+
+**Then** report: iteration id, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。
+
+PR merge itself may still be manual or a separate host action unless user authorized auto-merge.