@mstar-harness/opencode 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface re
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-08-13
+
+### Bundled harness skills (`harness-skills/` at publish)
+
+- Added the **dsh host reference** to `mstar-host`: a detect-table row for dsh's `subagent` delegation tool and `references/dsh.md` (tool map, in-process gates/enforcement, bundled commands, PM dispatch, gotchas).
+- **Sync upstream v2.1.1**: merged the upstream `mstar-harness` v2.1.1 line into the dev-dsh branch — adds the `code-reviewer` role (read-only L2 SDD task reviewer / audit executor; replaces `generalPurpose` as the SDD per-task review seat, with generic fallback only when the role agent is absent on the host), ships the canonical default-ignore harness `.gitignore` format (`.mstar/**` + tracked re-includes `AGENTS.md` / `knowledge/` / `specs/`) across the engine, CLI `init` fence and bundled skills, and aligns all 11 version surfaces to 2.1.1.
+- **engine**: `emitGitignoreSnippet` / `validateGitignore` / `HARNESS_PROCESS_GITIGNORE` now emit the default-ignore + re-include format instead of the flat per-directory ignore list; `ROLE_MAPPING` grows to 14 ids with `code-reviewer`.
+- **bundle-assets**: re-synced `packages/dsh/harness-skills` / `harness-commands` from the merged `skills/` tree — the 6+ upstream-touched bundled skills and all `mstar-host/references/*.md` host adapters (cursor/kimi/omp/opencode/zcode) now carry the v2.1.1 wording (SDD task reviewer → `code-reviewer`).
+
+- Version alignment with harness **2.2.0** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **2.2.0**.
+
 ## [2.1.1] - 2026-08-12
 
 ### Harness

package/dist/mstar.js

@@ -1,6 +1,7 @@
 // ../engine/dist/engine.js
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
 import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "node:fs";
 import { join as join4, resolve as resolve4 } from "node:path";
@@ -26,18 +27,45 @@ function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
     return resolve2(start, explicit);
+  const boundary = resolve2(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
   let dir = start;
   for (;; ) {
+    if (!isAtOrBelow(dir, boundary))
+      return null;
     for (const candidate of [join2(dir, ".mstar"), join2(dir, ".agents"), join2(dir, ".plans"), join2(dir, "plans")]) {
       if (isDirectory(candidate))
         return candidate;
     }
+    if (dir === boundary)
+      return null;
     const parent = dirname2(dir);
     if (parent === dir)
       return null;
     dir = parent;
   }
 }
+function defaultWorkspaceRoot(startDir) {
+  try {
+    const cdup = execFileSync("git", ["rev-parse", "--show-cdup"], {
+      cwd: startDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (!cdup)
+      return startDir;
+    let boundary = startDir;
+    for (const segment of cdup.split(/[\\/]/)) {
+      if (segment && segment !== ".")
+        boundary = dirname2(boundary);
+    }
+    return resolve2(boundary);
+  } catch {}
+  return startDir;
+}
+function isAtOrBelow(dir, root) {
+  const rel = relative(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
 function resolveIterationDir(harnessDir) {
   return join2(resolve2(harnessDir), "iterations");
 }

package/harness-commands/codebase-audit.md

@@ -2,6 +2,7 @@
 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

package/harness-commands/iteration-drive.md

@@ -2,6 +2,7 @@
 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
@@ -78,7 +79,7 @@ command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<la
 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 无引号展开（qc2 W-2）。
+> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
 
 ## Phase 3: iteration-close
 

package/harness-commands/iteration-loop.md

@@ -2,6 +2,7 @@
 name: iteration-loop
 description: "Autonomous full iteration loop for cloud agents — Phase 1 (code-first auto direction lock + compass/plans + Review & Edit chain) through Phase 2–5 (execute → close → PR → merge-ready). Optional args: direction, scale (S|M|L|XL, default M). Not Done until Phase 5 exit checklist passes. Minimal human intervention; no grill-me."
 agent: project-manager
+input: "[direction] [scale]"
 ---
 
 # Iteration Loop
@@ -129,7 +130,7 @@ command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<la
 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 无引号展开（qc2 W-2）。
+> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
 
 **Loop 特有**：Phase 5 push cadence（HARD）→ **`mstar-iteration` §5.1a**；exit checklist → **`mstar-iteration` §5.2**（`references/phase-4-5-pr-delivery.md` §5.2）。
 

package/harness-commands/iteration-start.md

@@ -2,6 +2,7 @@
 name: iteration-start
 description: "Start a new harness iteration — optional direction hint, research, grill-me, compass/plans, Review & Edit chain (long-lived {SPECS_DIR}/ + {ITERATION_DIR}/<id>/ package; compound promotes package at close only), PM lock, integration branch; then auto-continue Phase 2→5 (execute → close → PR → merge-ready) unless `pause` arg given."
 agent: project-manager
+input: "[direction] [pause]"
 ---
 
 # Start Iteration
@@ -111,7 +112,7 @@ command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<la
 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 无引号展开（qc2 W-2）。
+> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
 
 **Prepare gate (per plan in compass)**:
 

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

@@ -150,7 +150,7 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 **Naming conventions (PM / ops; examples only — paths MUST be canonical absolute)**
 
 1. **Control worktree** — usually the primary checkout or a PM-designated path on `spec_integration_branch`; record once in `metadata.control_worktree_path`.
-2. **Feature worktree (per plan)** — one distinct sibling directory per active `plan_id`, e.g. `<repo-parent>/worktrees/<plan-id>` or team `.worktrees/<plan-id>`; Assignment **`Worktree path`** must match lease `worktree_path`.
+2. **Feature worktree (per plan)** — one distinct subdirectory under the workspace root **`.worktrees/`** per active `plan_id` (e.g. `.worktrees/<plan-id>-<slug>`; AGENTS.md「Local scratch layout」), gitignored by the repo convention; Assignment **`Worktree path`** must match lease `worktree_path`.
 3. **L2 track worktrees (within-plan)** — additional distinct directories per parallel implement track under the **same** plan (see **`references/parallel-writable-pre-dispatch.md`**), each with its own PM-approved **`Working branch`**.
 
 > **Engine check (when available):** run `mstar worktree check <plan-id>` (L1) / `mstar worktree check --l2 --tracks <json>` (L2) (or `import { l1PreDispatchCheck, l2PreDispatchCheck, assertControlVsFeaturePath, assertBranchAlignment } from "@mstar-harness/engine"` in a host hook) to verify the L1/L2 isolation rules above (lease worktree ≠ control path; checked-out branch matches `Working branch`). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-host
-description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode, omp). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, ZCode Agent/AskUserQuestion/EnterPlanMode with built-in subagent types and role-in-prompt binding, omp task/ask/hub preferring live-schema role agents (agents/*.md) with C5b skill-load binding (generic task/scout only as fallback), sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
+description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode, omp, dsh). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, ZCode Agent/AskUserQuestion/EnterPlanMode with built-in subagent types and role-in-prompt binding, omp task/ask/hub preferring live-schema role agents (agents/*.md) with C5b skill-load binding (generic task/scout only as fallback), dsh (DeepSeek Harness) subagent tool with in-process engine gates and bundled mstar commands, sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
 ---
 
 # Morning Star Host Adapter
@@ -30,12 +30,13 @@ Detect from **session tool shapes and available commands** — not from plugin m
 | **`subagent_type`** param on the Task tool (plus **CreatePlan**/**SwitchMode** when Plan mode is active) | `cursor` | `references/cursor.md`; Plan mode also `references/cursor-plan-mode-bridge.md` |
 | **`question`** tool, or **`task`** tool with **`subagent`** (singular) — no `tasks[]` batch | `opencode` | `references/opencode.md` |
 | **`task`** tool with **`agent`** / **`tasks[]`** batch, **`ask`**, **`hub`** (omp also exposes `/goal`; goal rule is host-agnostic per below) | `omp` | `references/omp.md`; Plan mode also `references/omp-plan-mode-bridge.md` |
+| **`subagent`** tool (dsh's model-facing delegation tool — `@deepseek-ai/dsh-tool-subagent` default `toolName`) | `dsh` | `references/dsh.md` |
 | **`Agent`** / **`AskUserQuestion`** / **`EnterPlanMode`** + **`AgentSwarm`** (Kimi-only) | `kimi` | `references/kimi.md`; Plan mode also `references/kimi-plan-mode-bridge.md` |
 | **`Agent`** / **`AskUserQuestion`** / **`EnterPlanMode`** / **`TodoWrite`**, **no `AgentSwarm`** | `zcode` | `references/zcode.md`; Plan mode also `references/zcode-plan-mode-bridge.md` |
 | `/plan`, `/goal` slash commands; **Goal tools**; `functions.*` / `codex_app.*` tool namespaces; `tool_search`; Browser plugin tools | `codex` | `references/codex.md`; Plan mode also `references/_shared/plan-mode-bridge-core.md` |
-| Still ambiguous | - | Read sections in **`cursor.md`**, **`opencode.md`**, **`codex.md`**, **`kimi.md`**, **`zcode.md`**, and **`omp.md`** that match tools you have; **`mstar-harness-core` wins** on conflict |
+| Still ambiguous | - | Read sections in **`cursor.md`**, **`opencode.md`**, **`codex.md`**, **`kimi.md`**, **`zcode.md`**, **`omp.md`**, and **`dsh.md`** that match tools you have; **`mstar-harness-core` wins** on conflict |
 
-Order matters: check `cursor` → `opencode` → `omp` → `kimi` → `zcode` → `codex`. `subagent_type` (Cursor) vs `subagent` (OpenCode) vs `agent`/`tasks[]` (omp) is the sharpest split among the Task-based hosts.
+Order matters: check `cursor` → `opencode` → `omp` → `dsh` → `kimi` → `zcode` → `codex`. `subagent_type` (Cursor) vs `subagent` (OpenCode) vs `agent`/`tasks[]` (omp) is the sharpest split among the Task-based hosts; dsh's `subagent` tool collides with no other row, so it sits with the agent-tool hosts.
 
 > **Engine check (when available):** run `mstar host detect --signals <comma-list>` (or `import { detectHost } from "@mstar-harness/engine"` in a host hook) to resolve the detection table above from session tool shapes (prints the host id, or `ambiguous` to fall back on the table + judgment). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
@@ -62,6 +63,7 @@ Docs name assets as skill **`<name>`** → `scripts/…` / `references/…`. **R
 | **Cursor** | Skill **name** via plugin skills | Global `~/.cursor/plugins/local/morning-star-harness/skills/<name>/`; project `.cursor/plugins/morning-star-harness/skills/<name>/` |
 | **Codex** | Skill **name** via plugin | Plugin-mounted `skills/<name>/`; project command skills under `.agents/skills/<name>/` |
 | **OpenCode** | Skill **name** via `@mstar-harness/opencode` | Package-internal `harness-skills/<name>/` — never `process.cwd()/skills/` |
+| **dsh** | Skill **name** via the mstar skill-local provider (`providerName: mstar`) | `$DSH_BUNDLED_SKILL_DIR/<name>[/<rel>]` — the packaged `harness-skills/` mirror mounted package-relative by `@mstar-harness/dsh`; never app cwd |
 | **Kimi / ZCode** | Skill **name** / `/skill:<name>` | Plugin mount `./skills/<name>/` from the installed plugin root |
 
 Authoring convention: **`mstar-skill-authoring`** § Skill-relative script and asset paths. Per-host URI / mount detail: `references/<host>.md`.

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

@@ -0,0 +1,502 @@
+# dsh host reference
+
+Load when **`mstar-host`** detection resolves **dsh** (DeepSeek Harness — session
+has the **`subagent`** model-facing delegation tool, the `@deepseek-ai/dsh`
+cordis plugin stack; `@mstar-harness/dsh` mounted via the `web` profile bundle
+or a custom profile).
+
+## dsh-only context
+
+- Plugin markers: **`@mstar-harness/dsh`** (cordis function plugin) + the
+  **profile bundle** (`dsh.bundle.patch` manifest) installed into the `web`
+  profile via `dsh plugin --profile web add <spec>`. The composed app rows:
+  `@deepseek-ai/dsh-skill` (skill registry), `@deepseek-ai/dsh-tools` (tool
+  registry), `@deepseek-ai/dsh-commands` (command registry), then the `mstar`
+  row.
+- Runtime skills: the plugin mounts the packaged **`harness-skills/`** mirror
+  (repo `skills/`, synced by `bundle-assets`) through the dsh skill-local
+  provider as a **single canonical mount** (`providerName: mstar`). Skills are
+  loadable by **name** via `ctx.skills`; the canonical skill-root form is
+  `$DSH_BUNDLED_SKILL_DIR/<name>[/<rel>]`.
+- Plugin commands: the plugin registers the bundled **`harness-commands/`**
+  mirror as slash commands on `ctx.commands` — **`/iteration-start`**,
+  **`/iteration-drive`**, **`/iteration-loop`**, **`/codebase-audit`**. Each
+  command steers its command body into the receiving agent as a USER-source
+  message (the mstar workflow prompt — the model executes it as a task, not
+  injected context), returning a success result.
+- **No `sessionStart.skill`** — enter PM manually via the `pm` skill (the
+  `mstar-roles` load path), then **Read next** → `mstar-harness-core` →
+  `project-manager.md`.
+- Model-facing tools: the plugin registers **`mstar_sdd_workspace`**,
+  **`mstar_sdd_task_brief`**, **`mstar_iteration_gate`**, and the seam
+  validators **`mstar_design_md_validate`** / **`mstar_audit_validate`** /
+  **`mstar_compound_validate`** / **`mstar_roles_validate`** on `ctx.tools`.
+- Web client plugin (workflow panel): the same `mstar` bundle row carries a
+  browser client half (`dsh.client` + `exports["./client"]`) discovered
+  automatically by `ClientModuleHostService` — no separate profile layer or
+  install step. It registers a **`conversation.view`** view-ring tab
+  (`id: 'mstar-workflow'`, `order: 20`) labeled **"MStar 工作流" / "MStar
+  Workflow"** rendering the latest `mstar-engine-status` catalog row as the
+  **MStar Workflow layout** — a right sidebar (plans ≤5 in time-desc order +
+  `+N more`, open residual findings ≤10 with severity chips + overflow hint,
+  policy with **enforcement first** then push / worktree / control worktree,
+  leases, knowledge, direction) over a bottom **fixed meta dock** (version +
+  harness dir; small muted, hairline-separated, does NOT scroll with the
+  sidebar digest — the former header row was removed), and an **HTML/CSS zone
+  dashboard** (the react-flow cyclic graph was removed in plan
+  `20260810-panel-canvas-zones`): the canvas fills the Tab (the page never
+  scrolls; the zone container is the only scroll body) with an **iteration
+  zone** (Step 1–5 stepper + `Step N/5` badge + active-highlight / inactive
+  dimmed state; the steps carry a FOUR-STATE machine — `current` / `next` /
+  `done` / `idle` (plan `20260812-panel-f5-iteration-zone-fix` Task 1): every
+  step BEFORE the current one projects `done`「已完成」(completed — a finished
+  Step 1 must not read as idle while Step 2 is current), `next` is the single
+  forward target, `idle` is schema-only + the branch panel — iteration base /
+  target / spec integration, rendered only while active; the expanded head is
+  a LEFT-RIGHT SPLIT — branches (small left half, WIDTH-CAPPED — `flex: 0 1
+  260px` + `max-width: 280px`, never stretches with the container; the <860px
+  column stack resets to content height) + steps (large right half, `flex: 1 1
+  0` absorbing the remaining width) via `data-iteration-head-split`, stacking
+  on narrow widths, and NO branch panel
+  when there is no active iteration; the current step follows the steering
+  compass: `compassStatus: 'active'` (Phase 1 in flight) → Step 1
+  (iteration-start) is CURRENT with verdict `unknown` — no PASS/FAIL badge,
+  plan `20260811-panel-f4-iteration-zone`; **the iteration info section is
+  SHARED by the tasks AND agents tabs** (plan
+  `20260812-panel-f5-design-system` Task 8, user round-4 decision #4 — one
+  `IterationInfoSection` component, both tabs render the same `view.iteration`
+  block: summary + steps + branches), a **tasks zone** (5-column
+  kanban: Todo / InProgress / InReview / Done / `blocked-unknown` — the
+  Blocked state and the former `unknown` catch-all fold into ONE merged
+  column titled「受阻/未知」/「Blocked / Unknown」, plan
+  `20260813-panel-quick-fixes` Task 1 — with count badges; every column
+  caps its rendered rows at `PLAN_CAP` and shows a clickable 「更多」/「收起」
+  expand button (`data-kanban-more` anchor) unfolding the full column — the
+  projection keeps ALL plan rows, the cap is a render concern never a
+  discard), an **agent-execution zone** (the FOUR EXPECTED_ROLE_FLOW stage/phase
+  columns — review-edit-chain → sdd-implement → qc-tri → qa-gate, the
+  terminal stage; the former `sdd-task-review` stage is removed and its SDD
+  L2 reviewer is now the PIPELINE role `code-reviewer` (v2.1.1, the former
+  `generalPurpose` seat) — a strict FOUR-column layout with NO standalone
+  unknown column (plan `20260812-panel-f5-design-system` Task 5, user
+  2026-08-12 round-2 decision — the former rightmost UNKNOWN column of plan
+  `20260812-panel-f5-agent-layout` is superseded): the `general` bucket
+  sinks into an **unknown SUB-PARTITION at the bottom of the `qa-gate`
+  column** (a `data-sub-bucket="unknown"` caption row 「unknown / 未匹配角色」
+  after the last qa-gate card, then the general cards; the standalone
+  on-demand column was already removed in the agent-layout plan); `explore`
+  is removed — no card, no column. The columns are laid out in **TWO
+  side-by-side Phase groups** (plan `20260812-panel-f5-design-system` Task 8,
+  user round-4 decision #2; side-by-side layout per plan
+  `20260813-panel-agent-canvas-legend-layout` Task 2): the **Phase 1 group
+  on the LEFT** (review-edit-chain — the sequential Review & Edit chain:
+  product-manager → architect → writing-specialist) and the **Phase 2 group
+  on the RIGHT** (sdd-implement → qc-tri → qa-gate — the iterative plan
+  loop), top-aligned (all group label rows share the same `y = PAD_Y`), each
+  with its group label row; the **Phase-2 label annotates the CURRENT PLAN**
+  (projected `agents.activePlanId` = the first InProgress `state.plans[]`
+  row, `data-canvas-group-plan`; `+N more` when several plans run in
+  parallel, muted「无进行中 plan」when none). The `sdd-implement` column is split into SUB-BUCKETS by
+  the PROJECTED `entity.bucket` (never a render guess): the **implementor**
+  partition ABOVE — the flow roles in the stage's original order
+  (fullstack-dev / fullstack-dev-2 / frontend-dev), then the on-demand
+  roles (ops-engineer / prompt-engineer, carrying the **on-demand badge** —
+  the standalone on-demand column is gone) — and the **sdd-reviewer**
+  partition BELOW (code-reviewer, idle included), with the implementor /
+  sdd-reviewer caption labels; `zone: 'on-demand'` entities live in the
+  implementor partition, `zone: 'general'` entities render in the qa-gate
+  column's bottom unknown sub-partition. The subagent ENTITY cards aggregate **by role** from actual
+  dispatch evidence: the same role across sessions folds into one card ×N,
+  and every off-roster dispatch (the former `generalPurpose` SDD reviewer,
+  `scout`, anonymous `role === ''`) folds into the single `general` bucket
+  entity — the card is ROLE-TITLED (the role id, e.g. `fullstack-dev`); the
+  agent session id / task tag (`planId#taskId`) ride the RECORD line, never
+  the title. Cards show the role chip / status point / ×N count; running
+  entities carry the business glow-pulse
+  highlight, un-evidenced stages render the dashed "待执行" pending
+  placeholder with their expected role chips, un-evidenced KNOWN_AGENTS
+  members render dashed idle cards (the full 14-role roster is never
+  hidden), and the header shows the `N executing · M pending` summary.
+  Cards carry the projected **emphasis tier** (plan
+  `20260812-panel-f5-design-system` Task 4, design doc §3): `emphasis:
+  'current' | 'next' | 'off' | null` — the iteration's current-phase roles
+  render at **100%** chrome intensity, later-phase expected roles at **75%**,
+  already-passed / stage-less (on-demand, general) roles at **45%**, and
+  `null` (no iteration / unresolved transition) applies NO override — always
+  a chrome **alpha mix** (`--mstar-canvas-emphasis-*` tokens; never a
+  whole-card `opacity`, so the status point + running glow stay opaque).
+  Settled entities get a **standalone GREEN done frame + green ✓** (plan
+  `20260812-panel-f5-design-system` Task 8, user round-4 decisions #1/#3:
+  `data-agent-done="true"` — a full-strength success border + 1px ring on
+  the rounded card body + the ✓ in the status point) **ONLY when
+  `emphasis ≠ 'off'`** — an off-tier role (already-passed / stage-less
+  on-demand + general) renders the muted dot instead and NEVER shows the
+  completion marker (the completed state never appears on a stage-less
+  role). The canvas filters to the CURRENT iteration only (plan
+  `20260813-panel-quick-fixes` Task 2): dispatch evidence projects for the
+  current iteration's plans — the steering compass `iterationId` when
+  active, else the nearest iteration derived from the catalog
+  `plans[].iterationRefs` (the most-recent plan's refs by 8-digit id date
+  prefix + doneAt); provably cross-iteration events produce no entity/edge
+  (the roster keeps its idle cards); plan-less / unknown-plan / standalone
+  dispatches are never hidden. Status honesty (Task 2): `advisory` is NO
+  LONGER terminal — a soft-enforcement dispatch falls through to its paired
+  settle (green ✓ when a settle exists, `running` when none) while `denied`
+  stays terminal; the advisory verdict still renders in the event log. The
+  canvas legend sits BELOW the viewport (Task 3 — moved from above, user
+  2026-08-13 feedback).
+  Edges (plan `20260812-panel-f5-design-system` Task 5, design doc §2):
+  the `expected` stage skeleton arrows AND the ANIMATED **next** edge (the
+  former `@keyframes agent-dash-flow` dash-flow arrow of plan
+  `20260810-panel-agent-flow-zone`) are **REMOVED** — flow order is implied
+  by the fixed column order + column labels, the current position by the
+  running card glow + status point — leaving TWO semantic kinds: the
+  evidence-driven **`actual` handoff** edges (same-plan ts-adjacent dispatch
+  entity-key pairs, `general` endpoints filtered, ≤1 per entity pair) drawn
+  as **bezier `C` curves** anchored to card **PORTS** — 4 fixed
+  edge-midpoint ports (north / south / east / west; static-invisible,
+  hover-revealed as small dots) with the arrow tip pulled back to a **10px
+  standoff** off the port — the arrow follows the line's local tangent at
+  the anchor (**H1**), and no line's stroke or arrow crosses any text
+  (**H2**: standoff + side-gap routing, design doc §2.0/§2.5/§2.6;
+  tightened in plan `20260813-panel-quick-fixes` Task 3 — same-column
+  vertical flows whose center-x line would cross an in-between card body
+  (e.g. fullstack-dev → frontend-dev skipping an idle fullstack-dev-2)
+  reroute into the column's LEFT side gap, forward AND reverse, and reverse
+  horizontal beziers keep direction-aware control points BETWEEN the
+  endpoints so they never bulge into the adjacent column) — plus
+  the **bidirectional supervise line** (plan `20260812-panel-f5-agent-layout`
+  Task 1/2) — ONE static design-knowledge sub-bucket edge inside the
+  `sdd-implement` column (implementor ↔ sdd-reviewer — the mstar-sdd
+  mutual-supervision contract), now anchored at the **side-gap vertical
+  anchor** (`x = card right edge + 18px`, vertical bezier flow, arrows along
+  the vertical tangent — design doc §2.5/§2.7); dim dashed by default, lit
+  business SOLID when the projected `evidenced` flag is true —
+  evidence-driven lighting, never a fabricated activation); the 事件记录 tab
+  (`EventLogPage`, spec panel-tabs §5, plan `20260811-panel-event-log`) is a
+  NON-canvas log page with two partitions — **Agent 流转事件** (`view.events`
+  ≤50 latest-first; off-pipeline unexpected dispatches fold in once via
+  `expected: false` and carry a dispatch-only 「未匹配角色」 badge — settle
+  rows are completion records and never flag as unexpected) and **违规记录**
+  (`view.violations`, gate violations with severity/code/message); every row
+  is an expandable native `<details>` (no-JS, keyboard-accessible) whose body
+  shows the full catalog fields — missing fields render「—」, never a guessed
+  value. Layout (plan `20260811-panel-f3-agent-general`): the two partitions
+  render SIDE BY SIDE in a locked-height two-column grid
+  (`repeat(2, minmax(0, 1fr))` — the page never scrolls as a whole; each
+  partition pins its title and owns an internal `overflow-y` scroll on its
+  row list; plan `20260813-panel-quick-fixes` Task 4 root-caused the
+  whole-page scroll — the panel root opts into the host
+  `data-conversation-composer-overlay` (the host's documented full-height
+  opt-in), so the host `.viewArea` becomes a definite-height container and
+  `height:100%` resolves: `.rowList`'s `overflow-y: auto` now scrolls
+  INSIDE the partition and the host page no longer scrolls, with bottom
+  clearance reserving the floating composer via the host-published
+  `--dsh-composer-height`), falling back to two stacked 50/50 locked rows
+  below 1200px —
+  the `data-event-log-*` anchor family is unchanged. The canvas-corner **`AgentEventDock`** is REMOVED with the page
+  (无双份日志 — its row layout + status chips migrated into `EventLogPage`);
+  the fixed footer bar (zone legend + gate summary + violations) died with
+  the WorkflowCanvas in plan `20260811-panel-tabs-shell` — the footer that
+  remains is the freshness marker. Empty branches (spec §2 — plan
+  `20260812-panel-f5-agent-layout` Task 3): waiting keeps the muted hint,
+  and NO harness renders a **CENTERED inactive-state card** (folder icon +
+  「No Morning Star harness detected」 title + the hint copy — the detail
+  panel stays inactive, no tabs / no sidebar, activating automatically once
+  a harness is detected; the `data-mstar-empty="no-harness"` anchor stays on
+  the title, `data-mstar-graph` on the main container). Below 1200px
+  the zones stack vertically. Pure `projectGraph` projection (never throws,
+  explicit degraded states — muted empty states, never orange warn boxes).
+  The branches block left the sidebar in plan `20260810-panel-sidebar-info`
+  (its anchor fields stay in the catalog source; the iteration zone renders
+  them via plan `20260810-panel-canvas-zones`); refresh follows the session
+  snapshot, no polling — while the main agent is ACTIVELY orchestrating, a
+  ledger record (dispatch/settle) invalidates the workspace's TTL-cached
+  catalog row so the next pre-step rebuilds and (digest text change)
+  re-injects it, and the panel refreshes per step (seconds, not the 60 s TTL);
+  while the main agent IDLES (waiting, no tool calls) the panel keeps the
+  LAST snapshot — no live push channel (documented limit, plan
+  `20260811-panel-f4-timeliness`). Bundle served at
+  `/plugins/@mstar-harness/dsh/client.js` (closure-factory CJS with NO graph
+  library inlined — react-flow removed; the build asserts the bundle contains
+  no `xyflow`/`reactflow` markers, no `@deepseek-ai/*` value imports, and no
+  `import.meta` / ESM statements — the loader runs plugin bundles as classic
+  scripts). **Known limitations**: the stepper's Step 1 (iteration-start) IS
+  the current step while the steering compass is `status: active` (Phase 1 in
+  flight — catalog `compassStatus` field), carrying NO PASS/FAIL badge (Phase
+  1 has no gate verdict); Step 5 (merge-ready) can never be the CURRENT step —
+  the engine phase gate only evaluates Phase 2→3→4 (merge-ready is never a gate
+  transition); it renders `next` only while Step 4 (pr-delivery) is current,
+  idle otherwise;
+  the current step follows the TTL-refreshed `compassStatus` — up to one
+  catalog interval (60 s) behind a mid-session `active`→`locked` flip (bounded,
+  documented staleness, never a wrong verdict); the agent-entity
+  status derivation pairs a PAIRED settle exactly by its dispatch identity
+  (`agent`, `role`, `planId`, `taskId` — under QC-tri N=3 concurrency each
+  settle lands on ITS dispatch), and an unpaired dispatch stays `running`
+  (no paired settle — never guessed, never faked); the current-iteration
+  filter with NO steering compass infers the iteration from plan ids
+  (8-digit date prefix) + doneAt — deterministic, documented heuristic, and
+  only provably cross-iteration events are dropped; no historical back-scan of
+  resumed long logs; no custom
+  top-level slot (the `conversation.view` tab is the only session-level panel
+  seat without dsh-private layout changes); no-session → shell hero
+  (strict-session view ring). Panel acceptance is dual-track: in-loop browser
+  harness verification (agent-browser/CDP against the rebuilt bundle,
+  iteration guides record the verified runs) plus user-restart final GUI
+  acceptance.
+
+## Skill loading
+
+1. On entry: invoke **`pm`** (skill name via the mstar provider) → **Read
+   next** loads `mstar-harness-core`, then `mstar-roles` →
+   `project-manager.md` when PM is active.
+2. Read `mstar-host` and this dsh reference.
+3. Load `mstar-roles` and the active role reference.
+4. Load topic skills on demand per the role reference (skill **names** —
+   never app-cwd `skills/<name>/…`).
+
+## Tools map
+
+| dsh tool | Harness use |
+|----------|-------------|
+| **`subagent`** | Primary dispatch — the model-facing delegation tool the dispatch gate matches (default `toolName`; a renamed instance must be declared via Config `dispatchTools`) |
+| **`mstar_iteration_gate`** | Evaluate the iteration phase gate in-app (`evaluatePhaseGate` — `mstar iteration gate` parity) |
+| **`mstar_sdd_workspace`** / **`mstar_sdd_task_brief`** | SDD workspace resolve + task brief extraction (`mstar sdd …` parity) |
+| **`mstar_*_validate`** | On-demand seam validators (design-md / audit / compound / roles) |
+| **bash / read / write / edit / grep / glob / web_search** | Standard agent tools — evidence per `mstar-coding-behavior` |
+
+### `subagent` dispatch shape
+
+The dsh `subagent` tool is the delegation channel (schema rendered by
+`@deepseek-ai/dsh-tool-subagent`; `provider`-bound, default toolName
+`subagent`). Dispatch an Assignment the same way as other agent-tool hosts:
+the dispatch gate validates the **Assignment header region** (`## Assignment`
++ `**Execute as**` / `**Delegation**` / `**Task category**` / `**Working
+branch**` / `**Branch policy**` fields — engine `composeDispatchGate`, same
+violation codes as opencode/omp/CLI).
+
+Envelope-first discipline applies: put the header fields at the top of the
+Assignment body — the dsh dispatch gate reads only the header region, so
+body-quoted examples never leak into header fields.
+
+## Gates and enforcement
+
+The plugin wires the engine gates on dsh seams (all in-process):
+
+| Gate | Seam | Hard-mode channel |
+|------|------|-------------------|
+| Status gate | `fs/write-intent` + `fs/edit-intent` on `{HARNESS_DIR}/status.json` | repair-escape advisory (never vetoes the repairing write) |
+| Dispatch gate | `tools/pre-execute` on the `subagent` tool | `PreToolDecision { kind: 'deny', reason }` |
+| Lease gate | inside the dispatch gate (SDD / InProgress dispatches) | deny under hard |
+| Worktree L1/L2 | inside the dispatch gate | deny under hard |
+| Skill-authoring lint | `fs/write-intent` on `SKILL.md` under mounted roots | repair-escape advisory |
+| Seam lints | `fs/write-intent` on DESIGN.md / audit / compound / roles | repair-escape advisory |
+
+**Enforcement semantics**: warn-only by default. `Enforcement: hard` —
+resolved from the plugin Config (`enforcement: hard`), the Assignment header
+flag, or the iteration compass frontmatter — escalates dispatch violations to
+a real veto; status/skill-lint writes are never hard-vetoed because the intent
+waterfall is content-blind (an already-invalid document is allowed as a
+repair escape). Config `soft` is the only local rollback. Hard gates are never
+a global default.
+
+Every composed agent step carries ONE **`<mstar_engine_status>`** catalog
+message: the watermark (unified mstar version, harness dir, enforcement),
+the iteration phase-gate section when a steering compass resolved, and the
+workspace-state digest section (plan registry, open residuals,
+branch/policy anchors, active leases, knowledge digest, compass direction)
+when the workspace has a `status.json`. The row is digest-gated (once per
+turn, re-injected only when it changed) over one per-workspace TTL-cached
+build (`catalogTtlMs`, default 60 s).
+
+## Agent-flow ledger
+
+The plugin records ACTUAL subagent dispatch and real-completion settle events —
+the evidence of what really happened, distinct from the client-side expected
+role flow. The workflow panel's agent-execution zone (the stage/entity
+projection — plan `20260810-panel-agent-flow-zone`) and the 事件记录 tab's
+`EventLogPage` log page (plan `20260811-panel-event-log`) are pure consumers
+of this evidence.
+
+- **Recording point (one core)**: `DshHostAdapter.dispatchGate` is the SINGLE
+  record path behind both dispatch surfaces — the `tools/pre-execute` listener
+  (exec-bound; the lease gate joins here) and the host `beforeDispatch` hook
+  (exec-less). Every Assignment-shaped dispatch that reaches the gate records,
+  including hard denies (verdict derived: ok / advisory / denied); the shape
+  guard lives at the shared core, so non-Assignment text stays silent on BOTH
+  surfaces (the listener's own guard plus the core's guard for the exec-less
+  hook path — no phantom records). Recording is advisory (try/catch-contained,
+  logs only `mstar/agent-flow`) — a failing ledger never blocks dispatch.
+  Known tradeoff: the same logical dispatch crossing BOTH surfaces (a host
+  `beforeDispatch` followed by the identical text as an in-loop subagent tool
+  call) records two dispatch events — the surfaces are mutually exclusive by
+  design; the double record is documented, not deduplicated.
+- **File / bounds**: events append to `{HARNESS_DIR}/agent-flow.jsonl` (JSON
+  Lines, one event per line; harness dirs are gitignored by convention). The
+  ledger assumes ONE dsh process writes each harness dir (single-writer):
+  concurrent dsh sessions on the same repo can lose events (the append itself
+  is near-atomic O_APPEND, but truncation is a read-modify-write) — the loss
+  only under-reports actual flow in the panel, never a gate impact. After each
+  append the file truncates to the most recent **500** events; truncation is
+  size-gated (≈500 lines' typical size — small files stay append-only) and
+  performed as an atomic temp-file rename. The catalog read returns the
+  latest-first view with a default window of **50** and a role × outcome
+  summary. A MISSING file reads as the empty view ("no actual dispatches yet"
+  — recording starts at plan merge); an unreadable file is absent evidence;
+  malformed lines are skipped, never fatal.
+- **Settle = real completion pairing, never faked** (plan
+  `20260811-panel-f4-timeliness`): `tools/post-execute` IS part of the
+  verified dsh-tools registry surface (`runPostExecute` dispatches the
+  waterfall for every tool call — verified against the upstream source and
+  pinned by a real-call probe). The pairing listener matches dispatch TOOLS
+  (Config `dispatchTools`, default `['subagent']`), looks up the exec's
+  `callId` in the apply-scoped pairing store, and branches on the verified
+  result shapes:
+  - `{ kind: 'background', taskId }` → store `taskId → dispatchRef`; the REAL
+    settle arrives via `ctx.tasks.onTaskDone` (terminal mapping
+    completed → ok / killed → denied / failed → error, `durationMs` when
+    available), wired through `ctx.inject(['tasks'])`.
+  - `{ kind: 'continuable', subagentId }` → no terminal signal this round →
+    no settle (documented limit — the child owns its turns).
+  - any other successful value (foreground included) → settle `ok`; a failed
+    result (`isError`) → settle `error`.
+  Pairing is apply-scoped (in-memory `callId → dispatchRef` /
+  `taskId → dispatchRef` maps created in the entry `apply`; an HMR restart
+  resets them, and completions outside the window stay unpaired). Every
+  PAIRED settle carries the paired dispatch's identity (`role`/`planId`/
+  `taskId` — same field names + semantics as the dispatch event; the registry
+  background-task id is never written as `taskId`, `taskRef` is reserved for
+  it). Unpaired payloads (non-dispatch tools, calls outside the pairing
+  window) record NOTHING — the ledger stays dispatch-only, never a
+  fabricated settle.
+- **Catalog**: `state.agentFlow` carries the ledger view (`events` ≤ 50,
+  latest-first, + `summary`); the model-facing `<mstar_engine_status>` text
+  renders ONE compact `agent flow: …` line only when events > 0 (role totals
+  top-5 + latest dispatch with HH:MM — the event detail lives in the
+  structured source, never the model text). A ledger record (dispatch/settle)
+  invalidates the affected workspace's TTL cache entry IMMEDIATELY
+  (apply-scoped `harnessDir → cache key` reverse map + invalidation closure,
+  plan `20260811-panel-f4-timeliness`) → the next pre-step rebuilds and (digest
+  text change) re-injects the row — the 60 s TTL no longer bounds
+  ledger-change latency; it still bounds non-ledger staleness.
+- **Maintainer view**: change the ledger shape (event schema, bounds, settle
+  seam) and update the projections together — `gates/agent-flow.ts` (record /
+  read / settle listener), `gates/catalog.ts` (agent-flow line + `source`
+  view) and `client/panel/graph/project-graph.ts` (the ZoneView flow/agents
+  projection) — the panel renders ONLY what the evidence shows.
+
+## PM dispatch
+
+Harness **dispatch** on dsh = a `subagent` tool call with the full Assignment
+text (role binding in the prompt — `Execute as` / `Act as` + skill load;
+there is no separate `agent` field, the Assignment body IS the prompt). **N
+assignees = N `subagent` calls = N independent delegations** (dispatch-gate
+口径: one assistant message carries all N invokes — the gate counts each
+dispatched Assignment). Paste-only Assignment without an invoke is **not**
+dispatch.
+
+**Execution: concurrent dispatch REQUIRES background mode.** The `subagent`
+tool does **not** declare `isConcurrencySafe` → fail-closed `exclusive`
+classification, so same-message invokes are issued one-at-a-time (the next
+invoke starts only after the previous one settles). Foreground invokes (no
+`run_in_background`) settle only when the child completes → end-to-end serial
+(wall ≈ N× single seat). **Therefore any N≥2 dispatch that needs parallel
+execution MUST set `run_in_background: true` on EVERY invoke of the batch**:
+background invokes settle at task start (task id returned) and their child
+agents run CONCURRENTLY in background tasks (wall ≈ single seat, not N×).
+Foreground N≥2 invokes run SERIALLY and do NOT satisfy an N-parallel
+requirement — emitting them as "the dispatch" is dispatch-incomplete; if the N
+background invokes cannot be emitted in one message → **`Blocked`** (same as
+paste-only). **Future path (upstream suggestion, not editable from this
+repo):** dsh-private declares `isConcurrencySafe: () => true` on the
+tool-subagent so same-message foreground invokes can also run concurrently —
+needs dsh maintainer evaluation (roadmap §7e).
+
+**Leaf completion discipline — closing message, not the report tool (PM
+2026-08-12).** Leaf subagents hand back their Completion Report in the
+**final (closing) message** — do NOT call the `report` tool to deliver it.
+The dsh tool-subagent-report default `reportDelivery: quiet` routes a report
+through `parent.inject` into the parent's **next-step queue**; when the
+parent's turn has ended (no step boundary follows), the report strands in
+the "queued messages" dock instead of reaching the parent (observed on dsh).
+The closing message is the guaranteed delivery channel; reserve `report` for
+MID-turn findings that change what the parent should do next.
+
+### QC default
+
+- **`Execution mode: sdd`**: **N=3** `subagent` dispatches — one per QC seat
+  (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`), each body **Act as**
+  the respective QC role + QC skill load. **MUST dispatch all three with
+  `run_in_background: true` in one message** → the seats run CONCURRENTLY
+  (background children; wall ≈ single seat); foreground (no
+  `run_in_background`) runs serially (wall ≈ 3× single seat) and does NOT
+  count as parallel tri. Cannot emit required **N** → **`Blocked`**.
+- **`inline`**: **N=1**.
+
+### SDD implement (serial)
+
+- **`Execution mode: sdd`**: one implementer `subagent` dispatch per task id;
+  task reviewer = a separate dispatch (SDD review role) — no sticky resume
+  unless the host's continuable-subagent id is available and recorded.
+
+## Commands and skills paths
+
+| Surface | Path / invocation |
+|---------|-------------------|
+| Plugin skills | Skill **name** via the mstar skill-local provider (`ctx.skills`); canonical `$DSH_BUNDLED_SKILL_DIR/<name>` |
+| Plugin commands | `/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/codebase-audit` (registered from `harness-commands/`) |
+| Session entry | `pm` skill → `mstar-harness-core` via pm **Read next** |
+
+## Command delivery (dsh host, updated 2026-08-11)
+
+The dsh web client resolves slash commands against a client-side lexicon driven by the registry's `input.hint`. Every mstar command declares a frontmatter `input` hint (see `commands/*.md`), so the client **claims** it on menu pick: `/name ` is inserted into the composer with the command highlight and the hint as ghost text (e.g. `/iteration-start [direction] [pause]`), the user types follow-up args (or just presses Enter for arg-less commands), and the line submits only on Enter. The handler steers the command body into the receiving agent as a USER-source message, appending the typed args as a `## User input` section when present.
+
+**Degradation fallback:** when a command is NOT claimed client-side (lexicon fetch timing, args parsing, manual typing), the model receives the **bare text** (`/iteration-loop <方向> …`) with NO command body — unlike opencode/cursor/omp where the body always arrives.
+
+**Rule:** when a user message begins with a registered mstar command name (`/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/codebase-audit`) but carries no command body, treat it as that command invoked with the user text as its argument — execute the command's OWN semantics from the repo `commands/<name>.md` (or the mirrored `harness-commands/`): in particular **`/iteration-loop` = autonomous (code-first direction lock, NO grill-me questions)**, `/iteration-drive` = Phase 2–5 on the active iteration, `/iteration-start` = interactive (grill-me). Do not silently substitute the interactive start flow for `/iteration-loop`. Also do not re-ask what the command already specifies (e.g. scale auto → M default, branch policy continuity).
+
+## Harness dir and environment
+
+- `{HARNESS_DIR}` resolves via the engine `resolveHarnessDir` (`.mstar/` →
+  `.agents/` → `.plans/`/`plans/`), with the plugin Config `harnessDir`
+  override winning. The probe starts from the SESSION workspace root (the
+  session cwd — **never the dsh launch/process cwd**) and **STOPS there** — it
+  never walks above the session workspace, so the watermark and gates follow
+  the workspace the session actually works in. Repos using a
+  non-standard harness root (e.g. `.harness/`) MUST set Config `harnessDir`
+  (absolute path) — the gates are inert without a resolvable harness dir.
+- The dispatch gate needs the dispatching agent's own role for the
+  anti-recursion precheck: declare it via Config **`dispatchBinding`** (dsh
+  exposes no per-agent role on the tool-execution context). Under hard
+  enforcement with no binding, the plugin logs the absence.
+
+## Files, shell, and approvals
+
+- Prefer host search/edit tools over shell find/sed when available.
+- Respect dsh approval prompts for destructive operations.
+- Do not edit `$DSH_HOME` credentials or user secrets without explicit consent.
+
+## Git and final evidence
+
+- Git work follows `mstar-branch-worktree` and Assignment **Working branch** /
+  **Branch policy**; the worktree L1/L2 gates run in-process.
+- Completion reports cite concrete commands, artifacts, and commit lines when
+  required.
+
+## Gotchas
+
+- Do not confuse dsh **`subagent`** with opencode **`task_subagent`** or Cursor
+  **`subagent_type`** — the detect rows differ by tool shape.
+- A renamed `subagent` tool (Config `toolName`) silently disables the dispatch
+  gate AND host detection unless `dispatchTools` declares the new name (the
+  plugin warns under hard enforcement).
+- Role binding is prompt-only on dsh: always include **`Execute as`** +
+  **`Act as`** + skill load in the Assignment body — there is no separate
+  `agent` field.
+- Session plan UI / todos are not durable SSOT unless mirrored to
+  `{HARNESS_DIR}`.
+- The plugin's bundled skills/commands mirror is synced by `bundle-assets`
+  (gitignored, package-local) — an explicit `bundledSkillDir` /
+  `skillRoots` Config override wins when a deployment wants a different
+  mirror.

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

@@ -45,7 +45,7 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 | **→ 迭代交付完成** | §5.5 exit checklist 全 `[x]` | PR mergeable；required CI 全绿；reviews resolved | Phase 4 开 PR 即宣称完成 |
 | **iteration-start → integration branch** | §1.6 Review & Edit chain | 三角色按序 invoke；**specs** 为主产出；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene + compass `status: locked` | PM 代做专业编辑；并行三角色；product/architect 写 knowledge；临时笔记进 specs |
 
-> **Engine check (when available):** run `mstar iteration gate --status <status.json> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the transition gate above. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry; qc2 F-003), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar iteration gate --status <status.json> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the transition gate above. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
 
 **误判信号**：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 **未** 打印 §3.1 / §3.5 checklist → 视为 **Phase 3 未执行**，回到 §3.0。
 

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

@@ -1,10 +1,9 @@
 # Phase 2 control worktree + execution lease
 
-Normative field names and claim/release/merge semantics → maintenance ADR
-`.harness/docs/2026-07-22-iteration-worktree-plan-lease.md` (this repo) or
-`mstar-plan-artifacts/references/status-and-residuals.md` (runtime SSOT after
-plan-artifacts sync). This reference is the **iteration-command execution
-checklist**; do not invent alternate lease field names.
+Normative field names and claim/release/merge semantics → runtime SSOT
+`mstar-plan-artifacts/references/status-and-residuals.md`. This reference is
+the **iteration-command execution checklist**; do not invent alternate lease
+field names.
 
 ## When it applies
 

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

@@ -27,7 +27,7 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 
 > **Engine check (when available):** import `resolveHarnessDir` / `resolvePlanDir` / `resolveSddDir` / `resolveIterationDir` / `resolveSpecsDir` from `@mstar-harness/engine` in a host hook — or run `mstar path resolve [path]` (`--json` for machine output) to print the resolved dirs — to confirm the resolution below. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
-### `{HARNESS_DIR}` 解析顺序（找到即停）
+### `{HARNESS_DIR}` 解析顺序（找到即停；探测**永不越过工作区根**——CLI=start 的 git top-level（非 git→start 自身）；dsh=会话工作区）
 
 1. `.mstar/` → `{HARNESS_DIR}=.mstar/`, `{PLAN_DIR}=.mstar/plans/`
 2. 否则 `.agents/` → legacy `{HARNESS_DIR}=.agents/`, `{PLAN_DIR}=.agents/plans/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Morning Star harness OpenCode plugin — skills bootstrap + engine-backed runtime hooks (status lint, dispatch validation, Enforcement: hard gates).",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,6 @@
     "access": "public"
   },
   "devDependencies": {
-    "@mstar-harness/engine": "2.1.1"
+    "@mstar-harness/engine": "2.2.0"
   }
 }