@mstar-harness/opencode 1.8.3 → 1.8.6

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface re
 
 ## [Unreleased]
 
+## [1.8.6] - 2026-08-06
+
+### Bundled harness skills (`harness-skills/` at publish)
+
+- Sync dispatch field-completeness gate: `mstar-dispatch-gates` self-check + anti-pattern, `mstar-host/references/parallel-dispatch.md` hard rule + self-check, `mstar-host/references/omp.md` Review-&-Edit example + N=1 gotcha.
+- Version alignment with harness **1.8.6** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.6**.
+
+## [1.8.5] - 2026-08-06
+
+### Bundled harness skills (`harness-skills/` at publish)
+
+- Sync `mstar-host` § Resolve loaded skill root + host-reference skill-root cues; `mstar-skill-authoring` anti-pattern for rules/CLI cwd paths.
+- Version alignment with harness **1.8.5** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.5**.
+
+## [1.8.4] - 2026-08-06
+
+- **Bundled skills**: skill-relative script path naming (`mstar-sdd` → `scripts/…`) so agents resolve scripts from the loaded skill directory instead of consumer-cwd `skills/…` paths.
+- Version alignment with harness **1.8.4** (no OpenCode package API change).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.8.4**.
+
 ## [1.8.3] - 2026-08-05
 
 - **Bundled skills**: omp host C5 corrected — prefer live-schema Morning Star role `task.agent` values from discovered `agents/*.md`; keep C5b skill load; update shared host-role-binding + parallel-dispatch docs.

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-dispatch-gates
-description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent、`Execute as` 与 `Delegation`、承接方反递归 NEVER 红线、SDD implement 串行派发、**SDD 路径 plan QC 强制 tri-review（N=3）**、inline 单席 QC 例外、Assignment 文案≠派发、未齐不发。`project-manager` 派发时必读；leaf 动手前必读反递归。worktree 见 `mstar-branch-worktree`；SDD 见 `mstar-sdd`；宿主见 `mstar-host`。
+description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent、`Execute as` 与 `Delegation`、承接方反递归 NEVER 红线、SDD implement 串行派发、**SDD 路径 plan QC 强制 tri-review（N=3）**、inline 单席 QC 例外、Assignment 文案≠派发、未齐不发、**invoke 角色字段必填（漏写=静默 generic 回退=派发未完成）**。`project-manager` 派发时必读；leaf 动手前必读反递归。worktree 见 `mstar-branch-worktree`；SDD 见 `mstar-sdd`；宿主见 `mstar-host`。
 ---
 
 ## Load order（必读顺序）
@@ -58,6 +58,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 - **QC 单席（例外）**：`Execution mode: inline`（hotfix 等），或 Assignment 显式 `QC mode: single` / `QC mode: single — override: <reason>` → `qc-specialist` ×1，`N=1`，写 `{SDD_DIR}/review/qc.md`。
 - **QC targeted re-review**：Assignment 含 **`QC re-review: targeted — reviewers: …`** 时，**N** = 所列席位数（1–3），同条消息发满 **N**。
 - **先自检再发送**：发送前核对「Assignment 条数 = 本条消息中的实际 **派发** 调用条数」。
+- **先自检字段再发送（与 count 同级门禁）**：核对**每条** invoke 都携带与 **`Execute as`** 匹配的角色绑定字段——omp **`agent`** / Cursor **`subagent_type`** / OpenCode **`subagent`** / Kimi·ZCode **`subagent_type`**。**漏写或取默认通用值**（omp 漏 `agent` ⇒ 自动回退 generic `task`，无报错）= **派发未完成**，与 paste-only（零 invoke）**同等级**：当场补齐重发，不得进入下一 gate。**N=1 顺序链（Review & Edit）不豁免**——count 门在 N=1 恒过，**字段门是唯一保护**。
 - **前置步骤与派发回合分离（防串行 rollout）**：为派发准备的 **`bash` / `read` / `glob` / `grep`**（如 `merge-base`、`Review range`、`git rev-parse`）**不计入** `N` 次派发；可在上一条仅含准备的消息完成。准备完成后，**下一条派发消息**须**一次性**含 **`N` 次** Task / subagent invoke。**禁止**先发 `1` 次、等返回再补发其余 `N-1` 次。
 - **未齐不发（emit zero until batch-ready）**：需并发 `N≥2` 而当前只能发 `1` 条时，本条应发 **`0` 条派发 invoke`**（可继续 read/bash 补齐），**禁止**「先发一个顶一下」；`N` 份 payload 就绪后**单次消息发满 `N`**。见 **`mstar-host`** → `references/parallel-dispatch.md`（具备 invoke / Task / subagent 工具的宿主共用）。
 
@@ -114,6 +115,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 - Review-and-edit 链未完成即 commit integration 分支；PM 代做专业角色编辑而不 invoke。
 - Phase 1 review-and-edit 链三角色并行派发，或未等上一角色返回即派发下一角色。
 - Assignment 已写、invoke 为零（paste-only）却进入下一 gate。
+- Task/subagent item 漏写角色绑定字段（omp 漏 `agent` / Cursor 漏 `subagent_type` / OpenCode 漏 `subagent`）⇒ **静默回退 generic worker**，却因 count=N 通过而误判「派发完成」；属 paste-only 同级的 **dispatch-incomplete**。N=1 顺序 Review-&-Edit 链最易在此漏字段。
 
 ## References
 

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

@@ -41,6 +41,20 @@ Order matters: check `cursor` → `opencode` → `omp` → `kimi` → `zcode`
 
 When PM dispatches **N >= 2** concurrent assignees (QC tri-review, dual-track implement, etc.) and the host exposes actual invoke / Task / subagent tools, read **`references/parallel-dispatch.md`** in the dispatch round (shared with `mstar-dispatch-gates`). Without a callable invoke tool when dispatch is required → **`Blocked`**; Assignment Markdown alone is not dispatch.
 
+## 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).
+
+| Host | Prefer | Filesystem fallback (only if the host cannot load by name) |
+|------|--------|--------------------------------------------------------------|
+| **omp** | `skill://<name>` / `skill://<name>/<rel>` / `/skill:<name>` | Plugin package root `skills/<name>/` after install/link — not app cwd |
+| **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/` |
+| **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`.
+
 ## Conflict order
 
 1. User explicit instructions (this turn)

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

@@ -23,7 +23,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Avoid absolute local paths unless the user is maintaining this repository or the skill is not installed and must be read from the checkout.
+Use skill names in prompts and references. Avoid absolute local paths unless the user is maintaining this repository or the skill is not installed and must be read from the checkout. Skill-root resolve (plugin `skills/<name>/`, project `.agents/skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
 
 ## Clarify
 

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

@@ -6,6 +6,7 @@ Parallel PM dispatch: **`parallel-dispatch.md`** (Task tool uses same turn model
 
 ## Cursor-only context
 
+- Skill root: load by skill **name**; filesystem fallback → `mstar-host` § Resolve loaded skill root (`~/.cursor/plugins/local/morning-star-harness/skills/<name>/` or project `.cursor/plugins/morning-star-harness/skills/<name>/`). Never app-cwd `skills/<name>/`.
 - Role prompts: `mstar-roles`; **`/pm`** or **`pm` skill** → general PM orchestration (per-plan dispatch, gates, QC) without an iteration command. Host **`commands/`** for formal iteration Phase 1–5 (semantics → **`mstar-iteration`**).
 - Routing-eval: `.cursor/skills/mstar-routing-eval/` — regression tooling only; not runtime load order.
 

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

@@ -25,7 +25,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed.
+Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed. Skill-root resolve (plugin mount `./skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
 
 ## Tools map (default agent)
 

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

@@ -28,7 +28,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Prefer `skill://<name>/…` / `/skill:<name>` over absolute local paths unless maintaining this repository.
+Use skill names in prompts and references. Prefer `skill://<name>/…` / `/skill:<name>` over absolute local paths unless maintaining this repository. Full skill-root table (all hosts) → `mstar-host` § Resolve loaded skill root.
 
 ## Internal URLs
 
@@ -77,6 +77,8 @@ task(
 
 Single-task shorthand may exist depending on host version — always match the live schema. Parallel **N** Morning Star assignees ⇒ **one** `task` call with **N** `tasks[]` entries **or** **N** `task` calls in one assistant message when the host requires that shape. Count emitted dispatches = **N**.
 
+**Construct the envelope first (production cue — prevents the omission at the source, not just at the gate).** When building a `tasks[]` entry, write **`agent`** + **`name`** as the first fields, *before* the long `task` body. The Assignment body is hundreds of lines of structured text and dominates working memory; `agent`/`name` are one-line envelope fields with no intrinsic saliency and no auto-check — writing the body first and the envelope last is how `agent` gets silently dropped (omp then defaults to generic `task`). The pre-send field gate (see **C5** below) catches it, but **envelope-first is the cheaper failure mode**: it makes the high-stakes-but-low-saliency field structural, so it cannot be forgotten by attention drift while authoring the body.
+
 ## Role agents (C5 — hard constraint)
 
 **Live `task` tool schema is SSOT every session.** Exact `agent` names vary by omp version and which `agents/*.md` were discovered after plugin install/link. Read the tool's Available Agents list before dispatch — do not invent names; do not hard-code stale tables over the live list.
@@ -145,7 +147,7 @@ task(
 )
 ```
 
-Review & Edit / Prepare specialist chain (sequential, **N=1** each turn):
+Review & Edit / Prepare specialist chain (sequential, **N=1** each turn — re-set **`agent`** on **every** dispatch; at N=1 the count gate is trivial, so the **field** gate is the only protection):
 
 ```text
 task(
@@ -156,7 +158,18 @@ task(
     task: "<Assignment: Execute as product-manager; Act as + skill load>"
   }]
 )
-# wait for return, then architect, then writing-specialist — each with agent: "<role-id>"
+# pass 2 — architect (re-set agent on EVERY dispatch; a bare tasks:[{task:"…"}] with no agent silently falls back to generic task — C5 anti-pattern)
+task(
+  context: "Review & Edit — architecture",
+  tasks: [{ name: "ReviewEditArchitect", agent: "architect",
+            task: "<Assignment: Execute as architect; Act as + skill load>" }]
+)
+# pass 3 — writing-specialist
+task(
+  context: "Review & Edit — writing",
+  tasks: [{ name: "ReviewEditWriting", agent: "writing-specialist",
+            task: "<Assignment: Execute as writing-specialist; Act as + skill load>" }]
+)
 ```
 
 For explore-only orientation (no Morning Star role deliverable):
@@ -230,3 +243,4 @@ Cannot emit required **N** → **`Blocked`**.
 - omp has no `sessionStart.skill`; new sessions do **not** auto-load PM — invoke `/skill:pm` manually.
 - Do not confuse omp **`task.agent`** with OpenCode **`subagent`** or Cursor **`subagent_type`**.
 - Do not treat Kimi/ZCode “built-ins only → always `coder`/`task`” habits as omp defaults when Morning Star role agents are listed.
+- **Sequential N=1 Review-&-Edit turns are where `agent` gets dropped**: the “all N in one message” pressure is absent and the count gate passes trivially — re-verify **`agent: "<Execute as>"`** on every single dispatch; `tasks:[{task:"…"}]` with no `agent` is a silent generic fallback, not a valid role invoke.

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

@@ -6,6 +6,7 @@ Parallel PM dispatch: **`parallel-dispatch.md`** (read in dispatch rounds).
 
 ## Role loading
 
+- Skill root: load by skill **name** from `@mstar-harness/opencode` (`harness-skills/<name>/` inside the package). Never `process.cwd()/skills/` — see `mstar-host` § Resolve loaded skill root.
 - **PM entry**: **`/pm`** or **`pm` skill** → `project-manager` for general orchestration; host **`commands/`** for formal iteration Phase 1–5 (semantics → **`mstar-iteration`**).
 - **Role shell**: `agents/<id>.md` referenced by `opencode.json` `agent.<id>` (frontmatter + role binding only).
 - **Role body**: `mstar-roles` `references/<id>.md` (or shared references + parameters).

package/harness-skills/mstar-host/references/parallel-dispatch.md

@@ -15,7 +15,7 @@ Printing `## Assignment` in the main thread **without** matching host invocation
 
 ## Mandatory order (dispatch turn)
 
-1. Finalize all `N` Assignment payloads (after any prerequisite turn).
+1. Finalize all `N` Assignment payloads (after any prerequisite turn). **Build each invoke entry envelope-first**: set the role-binding field (omp `agent` / Cursor `subagent_type` / OpenCode `subagent` / Kimi·ZCode `subagent_type`) + `name` *before* writing the long Assignment body — the body is high-volume and will crowd out the one-line envelope field from working memory.
 2. Count distinct `Execute as` sessions (`N`).
 3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type` (JSON field shape → `cursor.md` § Task invoke schema); Kimi: **N `Agent`** calls (each prompt carries **Act as** + skill load; `subagent_type` ∈ {`coder`,`explore`,`plan`} only — see `kimi.md` C5/C5b); omp: **one `task` call with N `tasks[]`** (or N `task` calls) with `agent` = live-schema role id matching `Execute as` when listed (else generic built-in) + **Act as** / skill load (see `omp.md` C5/C5b); each with one Assignment body. For parallel work, **all `N` tool calls in one assistant message** when the host allows.
 4. Optionally post a short **Status Update** after invocations (audit trail only — does not replace step 3).
@@ -26,6 +26,7 @@ Printing `## Assignment` in the main thread **without** matching host invocation
 - Do not end the dispatch turn until **`N` invocations emitted**, or mark `Blocked` / `dispatch incomplete`.
 - Dual-track implement: **`N = 2` ⇒ two invocations in one message** when parallel is required.
 - Status Update on dispatch turns: **`Subagent invokes issued: N`** (must match Assignment count). If Assignments were written but `N = 0` → **`dispatch failed — paste-only`**; fix next message.
+- **Per-item field completeness (same severity as paste-only)**: every invocation must carry the role-binding field set to **`Execute as`** — omp **`agent`** / Cursor **`subagent_type`** / OpenCode **`subagent`** / Kimi·ZCode **`subagent_type`**. A missing field (e.g. omp omitting `agent` ⇒ silent generic `task` fallback) = **dispatch incomplete** even though count = N passes. Sequential **N=1** Review-&-Edit turns are not exempt — re-set the field on **every** dispatch.
 
 ## QC default (initial wave)
 
@@ -62,5 +63,6 @@ Formal iteration Phase 2 uses the same SDD + tri rule — not a separate carve-o
 1. Required assignments this turn? (`N`)
 2. Prerequisite-only message? → **zero** batch dispatches unless `N = 1`.
 3. Dispatch message contains **exactly `N`** invocation calls?
-4. QC initial: **`Execution mode: sdd`** → **N=3**? **`inline`** → **N=1**? Targeted re-review → **N** = Assignment reviewer count?
-5. SDD implement → **serial** (never batch implementers); sticky = **resume** same implementer, not parallel
+4. **Each** invocation carries its role-binding field set to **`Execute as`** (omp `agent` / Cursor `subagent_type` / OpenCode `subagent` / Kimi·ZCode `subagent_type`)? A bare `task`/prompt item with no role field = **incomplete**, even at **N=1**.
+5. QC initial: **`Execution mode: sdd`** → **N=3**? **`inline`** → **N=1**? Targeted re-review → **N** = Assignment reviewer count?
+6. SDD implement → **serial** (never batch implementers); sticky = **resume** same implementer, not parallel

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

@@ -25,7 +25,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2
 4. Load `mstar-roles` and the active role reference.
 5. Load topic skills on demand per the role reference.
 
-Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed.
+Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed. Skill-root resolve (plugin mount `./skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
 
 ## Tools map (default agent)
 

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

@@ -288,10 +288,10 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 3. **Implement → InReview**（`§ 2.5`；产品编辑在 feature worktree；plans / status / iterations / SDD 经 control 绝对路径）：
    - **默认 `Execution mode: sdd`**（多 task plan；hotfix 可 `inline`）。
    - PM 载入 **`mstar-sdd`** 后，按 plan task 顺序 **串行** per-task 循环（**不是**一次派发 dev 做全部 tasks）：
-     1. `sdd-workspace <plan-id>` → `{SDD_DIR}`
-     2. `task-brief <plan-file> N` → `{SDD_DIR}/task-N-brief.md`；记录 `BASE_SHA`
+     1. skill **`mstar-sdd`** → `scripts/sdd-workspace <plan-id>` → `{SDD_DIR}`
+     2. `scripts/task-brief <plan-file> N` → `{SDD_DIR}/task-N-brief.md`；记录 `BASE_SHA`
      3. Dispatch **one** implementer subagent（`references/implementer-prompt.md`：brief 路径 + report 路径 + `Model tier`；**禁止**贴整份 plan）
-     4. Implementer `DONE` → `review-package BASE HEAD` → task diff 文件
+     4. Implementer `DONE` → `scripts/review-package BASE HEAD` → task diff 文件
      5. Dispatch **one** task reviewer subagent（brief + report + diff + Global Constraints）
      6. Fix loop 直至 review clean；append `{SDD_DIR}/progress.md`；更新 `status.json` / plan checkbox
      7. Next task
@@ -320,7 +320,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 | 文件交接 | brief / report / diff / `progress.md` 在 `{SDD_DIR}`；dispatch prompt **只给路径**，不贴 plan 全文或 task 历史 |
 | Assignment 字段 | 每个 implement dispatch 须含 `Execution mode: sdd`、`SDD dir`、`Model tier`；§2.0 #5 未 waive 时还须含绝对 `Worktree path` + verified `execution_lease`；**禁止**省略 `Model tier` |
 | 大包 inline | **禁止**把 T1–Tn 或整份 plan 写进 **一个** `fullstack-dev` leaf Assignment 冒充 SDD |
-| 分支 diff | 全部 task 完成后 `review-package MERGE_BASE HEAD` → `{SDD_DIR}/review/` branch diff → plan QC tri（N=3） |
+| 分支 diff | 全部 task 完成后 skill **`mstar-sdd`** → `scripts/review-package MERGE_BASE HEAD` → `{SDD_DIR}/review/` branch diff → plan QC tri（N=3） |
 
 Iteration Phase 2 附加：
 

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

@@ -475,7 +475,8 @@ Prefer **`archived/residuals/`**; migrate and delete history key when possible.
 # Replace .mstar with your resolved {HARNESS_DIR}; legacy projects may use .agents.
 jq '.residual_findings["01-data-infrastructure"] // .metadata.residual_findings["01-data-infrastructure"]' .mstar/status.json
 jq '.entries[] | select(.id == "R1")' .mstar/archived/residuals/01-data-infrastructure.json
-bash skills/mstar-plan-artifacts/scripts/tech-debt-rollup.sh .mstar/status.json
+# skill mstar-plan-artifacts → scripts/tech-debt-rollup.sh (not a consumer cwd path)
+bash <mstar-plan-artifacts>/scripts/tech-debt-rollup.sh .mstar/status.json
 ```
 
 (`//` right-hand side = legacy read path.)
@@ -508,8 +509,9 @@ Append-only log for merge closure, batch archive, `tech_debt_summary` refresh, e
 **Compute (canonical):** run the read-only script (do **not** hand-count):
 
 ```bash
-# From repo root; pass path to status.json if not .mstar/status.json
-bash skills/mstar-plan-artifacts/scripts/tech-debt-rollup.sh .mstar/status.json
+# Resolve from skill mstar-plan-artifacts → scripts/tech-debt-rollup.sh
+# Pass path to status.json if not .mstar/status.json
+bash <mstar-plan-artifacts>/scripts/tech-debt-rollup.sh .mstar/status.json
 ```
 
 - Prints computed `total_open`, `by_severity`, `by_target`, `by_plan`.

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

@@ -65,7 +65,7 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 PM 在需要持久化追踪时：
 
 1. 建 `.mstar/`、`plans/`、`status.json`（空模板见 **`mstar-plan-artifacts/templates/status.empty.json`**）
-2. 可选 `notes.json`（模板 **`mstar-plan-artifacts/templates/notes.empty.json`**）、`knowledge/`、`iterations/`、`{HARNESS_DIR}/specs/`、`sdd/`（空目录占位；运行时 per-plan 子目录由 `mstar-sdd/scripts/sdd-workspace` 创建）
+2. 可选 `notes.json`（模板 **`mstar-plan-artifacts/templates/notes.empty.json`**）、`knowledge/`、`iterations/`、`{HARNESS_DIR}/specs/`、`sdd/`（空目录占位；运行时 per-plan 子目录由 skill **`mstar-sdd`** → `scripts/sdd-workspace` 创建）
 3. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（见下文「Git 跟踪策略」）— CLI `init` 可自动添加
 4. Git：**进程本地、结果共享** — 默认跟踪 `{HARNESS_DIR}/AGENTS.md`、`{KNOWLEDGE_DIR}/**`、`{SPECS_DIR}/**`；`plans/`、`iterations/`、`status.json` 等为**本地会话 SSOT**，默认 gitignored。跨 clone 持久 handoff = knowledge + specs + `{HARNESS_DIR}/AGENTS.md`（及根 `CONCEPTS.md` / `STRATEGY.md` 若使用）；须跨 clone 的 residual 须提升（compound）或写入 tracked results — **勿**默认 `git add` `status.json` / `plans/`。
 

package/harness-skills/mstar-plan-conventions/references/harness-bootstrap-and-agents-layering.md

@@ -14,7 +14,7 @@
 
 1. 创建 `{HARNESS_DIR}`（推荐 `.mstar/`）与 `{PLAN_DIR}`（推荐 `.mstar/plans/`）。
 2. 初始化 `status.json`：从 **`mstar-plan-artifacts/templates/status.empty.json`** 复制；residual canonical 见 **`mstar-plan-artifacts` SKILL.md**；字段与生命周期见 **`mstar-plan-artifacts/references/status-and-residuals.md`**。
-3. 初始化可选 `notes.json`（**`mstar-plan-artifacts/templates/notes.empty.json`**）；`sdd/` 空目录占位（per-plan 子目录由 `mstar-sdd/scripts/sdd-workspace` 创建）。
+3. 初始化可选 `notes.json`（**`mstar-plan-artifacts/templates/notes.empty.json`**）；`sdd/` 空目录占位（per-plan 子目录由 skill **`mstar-sdd`** → `scripts/sdd-workspace` 创建）。
 4. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」；legacy `.agents/` 有等价表）。
 5. **Profile B**（统一 Done 压缩）时另建 `{HARNESS_DIR}/archived/plans/` 与 `archived/plans-done.json`（自 **`mstar-plan-artifacts/templates/plans-done.empty.json`** 复制；schema 仅 `{ "plans": [] }`，见 **`mstar-plan-artifacts/references/done-compaction.md`**）。
 6. 可选：创建 `{ITERATION_DIR}`（`iterations/` + `README.md`）与 `{KNOWLEDGE_DIR}`（`knowledge/` + `README.md`）；`{HARNESS_DIR}/specs/`（解析后的 `{SPECS_DIR}` 默认落点）；内容边界见 `mstar-plan-conventions` SKILL.md 与 `references/knowledge-and-designs.md`。

package/harness-skills/mstar-roles/references/project-manager/dispatch-and-assignment.md

@@ -137,7 +137,7 @@ When `metadata.control_worktree_path` is set and worktree mode is **not** waived
 | **`Worktree path`** | Absolute **feature** checkout (`execution_lease.worktree_path`) — product/source edits only |
 | **`Control harness root`** | Absolute `<control_worktree_path>/{HARNESS_DIR}` |
 | **`Plan Path`** | Absolute under control harness (not relative from feature cwd) |
-| **`SDD dir`** | Absolute under control harness; run `sdd-workspace` with `MSTAR_CONTROL_ROOT=<control_worktree_path>` when cwd is the feature tree |
+| **`SDD dir`** | Absolute under control harness; run skill **`mstar-sdd`** → `scripts/sdd-workspace` with `MSTAR_CONTROL_ROOT=<control_worktree_path>` when cwd is the feature tree |
 
 Do **not** waive worktree because default-gitignored `plans/` are missing under the feature checkout — see `mstar-branch-worktree` 「Harness path SSOT under default gitignore」.
 ## Completion Report Template

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

@@ -39,12 +39,12 @@ Batch all findings for the human in one message. If clean, proceed silently.
 ## Per-task loop (PM only)
 
 1. Record `BASE_SHA` (never use `HEAD~1` later)
-2. `sdd-workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `sdd-workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
-3. `task-brief <plan> N` → brief file
+2. skill **`mstar-sdd`** → `scripts/sdd-workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `scripts/sdd-workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
+3. `scripts/task-brief <plan> N` → brief file
 4. Dispatch implementer:
    - **`SDD implementer session: fresh`** (default) — new subagent; templates: `references/implementer-prompt.md`
    - **`SDD implementer session: sticky`** — first task: same as fresh + write `{SDD_DIR}/implementer-session.json` with `host_agent_id`; later tasks: host **resume** + `references/implementer-continuation-prompt.md` (see **`references/sticky-implementer-session.md`**)
-5. On `DONE`: `review-package BASE HEAD` → diff file
+5. On `DONE`: `scripts/review-package BASE HEAD` → diff file
 6. Dispatch **fresh** task reviewer — **`subagent_type: generalPurpose`** (L2; **not** `qc-specialist*`) — brief, report, diff, Global Constraints — `references/task-reviewer-prompt.md` — **never** sticky resume for reviewers
 7. Fix loop for Critical/Important; re-review until approved
 8. Append `progress.md`; update `status.json` `task_commits[]` and `implementer-session.json` `last_task` if sticky
@@ -81,7 +81,7 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
 
 ## After all tasks
 
-1. `review-package MERGE_BASE HEAD` → branch diff in `{SDD_DIR}/review/`
+1. `scripts/review-package MERGE_BASE HEAD` → branch diff in `{SDD_DIR}/review/`
 2. PM dispatches **plan QC tri-review (L3)** — **`QC mode: full tri-review`**, **N=3** — with branch review-package path and report paths under `{SDD_DIR}/review/` → **`mstar-review-qc`** · **`mstar-dispatch-gates`**. Layer SSOT → **`mstar-review-qc/references/review-responsibility-boundaries.md`**. PM writes `{SDD_DIR}/review/qc-consolidated.md` and durable main-plan gate summary. **Mandatory whenever `Execution mode: sdd`** (single-plan or iteration).
 3. Critical/Important QC findings → **one** fix dispatch (full list), then targeted re-review
 4. QA gate → **`mstar-harness-core`** Done rules; PM **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**
@@ -109,13 +109,15 @@ Minor findings → `## Minor (for plan QC)` section in same file.
 
 ## Scripts
 
-From repo: `skills/mstar-sdd/scripts/` (bundled in OpenCode as `harness-skills/mstar-sdd/scripts/`).
+Scripts live under this skill: **`mstar-sdd`** → `scripts/<name>`.
+
+Resolve the loaded **`mstar-sdd`** skill directory first, then run the script by skill-relative path. **Do not** treat `skills/mstar-sdd/scripts/...` as a consumer-project cwd path — that layout exists only in the harness source tree (and OpenCode's bundled `harness-skills/mstar-sdd/scripts/`).
 
 | Script | Usage |
 |--------|--------|
-| `sdd-workspace` | `PLAN_ID [CONTROL_ROOT]` → creates `{SDD_DIR}` under control harness when set (`MSTAR_CONTROL_ROOT` or 2nd arg); fail closed on linked worktree without `status.json` |
-| `task-brief` | `PLAN_FILE TASK_N [OUTFILE]` |
-| `review-package` | `BASE HEAD [OUTFILE]` |
+| `scripts/sdd-workspace` | `PLAN_ID [CONTROL_ROOT]` → creates `{SDD_DIR}` under control harness when set (`MSTAR_CONTROL_ROOT` or 2nd arg); fail closed on linked worktree without `status.json` |
+| `scripts/task-brief` | `PLAN_FILE TASK_N [OUTFILE]` |
+| `scripts/review-package` | `BASE HEAD [OUTFILE]` |
 
 ## References
 

package/harness-skills/mstar-sdd/references/file-handoffs.md

@@ -4,12 +4,14 @@ PM and subagents move artifacts as **files**, not pasted text. Pasted content st
 
 ## Before implementer dispatch
 
-1. `export SDD_DIR=$(skills/mstar-sdd/scripts/sdd-workspace <plan-id>)`
+Resolve scripts from skill **`mstar-sdd`** → `scripts/…` (loaded skill directory). Do **not** run `skills/mstar-sdd/scripts/…` from a consumer project cwd.
+
+1. `export SDD_DIR=$(<mstar-sdd>/scripts/sdd-workspace <plan-id>)`
    - Iteration L1 (implementer cwd = feature worktree):  
      `export MSTAR_CONTROL_ROOT=<control_worktree_path>`  
      or `sdd-workspace <plan-id> <control_worktree_path>`  
      so `{SDD_DIR}` lands on the control harness (default-gitignored plans/status/sdd). Do not create a second SDD tree under the feature checkout.
-2. `skills/mstar-sdd/scripts/task-brief <plan-file> <N> "$SDD_DIR/task-N-brief.md"`
+2. `<mstar-sdd>/scripts/task-brief <plan-file> <N> "$SDD_DIR/task-N-brief.md"`
 3. Record `BASE_SHA` (`git rev-parse HEAD` before dispatch).
 4. Dispatch implementer with:
    - One line scene-setting (where task fits)
@@ -31,7 +33,7 @@ Implementer writes full report to `task-N-report.md`. Return to PM only:
 ## After implementer DONE
 
 1. `HEAD_SHA=$(git rev-parse HEAD)`
-2. `skills/mstar-sdd/scripts/review-package "$BASE_SHA" "$HEAD_SHA" "$SDD_DIR/review-....diff"`
+2. `<mstar-sdd>/scripts/review-package "$BASE_SHA" "$HEAD_SHA" "$SDD_DIR/review-....diff"`
 3. Dispatch task reviewer with: brief path, report path, diff path, Global Constraints (verbatim from plan).
 
 **Never use `HEAD~1` as BASE** — multi-commit tasks truncate.
@@ -63,7 +65,7 @@ After all tasks:
 ```bash
 MERGE_BASE=$(git merge-base <target-branch> HEAD)
 mkdir -p "$SDD_DIR/review"
-skills/mstar-sdd/scripts/review-package "$MERGE_BASE" HEAD "$SDD_DIR/review/branch-review-....diff"
+<mstar-sdd>/scripts/review-package "$MERGE_BASE" HEAD "$SDD_DIR/review/branch-review-....diff"
 ```
 
 Pass **branch** diff path and bundle report paths (`$SDD_DIR/review/qc1.md` …) to QC dispatch — not task-level diffs. Raw QC/QA files stay in the gitignored review bundle; PM records durable summary and open residuals in **local** plan/`status.json` (session SSOT) and promotes cross-clone decisions into tracked knowledge/specs/`AGENTS.md` per `mstar-plan-conventions` git policy.

package/harness-skills/mstar-skill-authoring/SKILL.md

@@ -103,6 +103,17 @@ Optional files to read only when needed.
 
 Keep `SKILL.md` focused on the main execution path. Move long examples, templates, schemas, and detailed variants into `references/`, `templates/`, or `scripts/`.
 
+## Skill-relative script and asset paths
+
+When a skill ships executables or assets under `scripts/` / `templates/` / `references/`, name them as **skill → relative path**:
+
+- Good: skill **`mstar-sdd`** → `scripts/sdd-workspace`
+- Good: `<mstar-sdd>/scripts/sdd-workspace` (placeholder for the loaded skill root)
+- Bad in runtime docs: `skills/mstar-sdd/scripts/sdd-workspace` as if it were a consumer-project cwd path
+- Bad in shipped rules / CLI notes: `skills/mstar-host/references/…` as a consumer cwd path — use **`mstar-host`** → `references/…` (omp may also cite `skill://mstar-host/references/…`)
+
+Agents discover skills by **name**; they often miss files when docs present a full repo-relative path and they search that literal string under the app checkout. Resolve the loaded skill directory first, then append `scripts/…` / `references/…`. **How** to resolve differs by host — use **`mstar-host`** § Resolve loaded skill root (omp `skill://`, Cursor plugin checkout under `~/.cursor/plugins/…` or `.cursor/plugins/…`, OpenCode `harness-skills/`, Codex/Kimi/ZCode plugin mounts). Reserve `skills/<name>/…` only for harness-repo maintenance notes that explicitly say "from this repository root".
+
 ## Progressive Disclosure
 
 Use three levels:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "1.8.3",
+  "version": "1.8.6",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {