@mstar-harness/omp 3.6.0-alpha.4

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mstar-harness/omp",
+  "version": "3.6.0-alpha.4",
+  "description": "Morning Star harness omp (Oh My Pi) plugin — engine-backed runtime gates (status/dispatch/lease) + mstar-* skills, commands, and agents for omp.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btspoony/mstar-harness.git",
+    "directory": "packages/omp"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "harness-skills",
+    "harness-commands",
+    "harness-agents",
+    "hooks",
+    "tools",
+    "skills",
+    "commands",
+    "agents",
+    "assets",
+    "plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle-assets": "bun run scripts/bundle-harness-assets.ts",
+    "build": "bun run bundle-assets && rm -rf dist hooks tools && bun build src/hooks/pre/mstar-gates.ts --target node --outfile dist/hooks/pre/mstar-gates.js && bun build src/tools/mstar_status_validate/index.ts --target node --outfile dist/tools/mstar_status_validate/index.js && bun build src/tools/mstar_worktree_check/index.ts --target node --outfile dist/tools/mstar_worktree_check/index.js && bun build src/tools/mstar_dispatch_validate/index.ts --target node --outfile dist/tools/mstar_dispatch_validate/index.js && bun build src/tools/mstar_iteration_gate/index.ts --target node --outfile dist/tools/mstar_iteration_gate/index.js && bun build src/tools/mstar_lease_verify/index.ts --target node --outfile dist/tools/mstar_lease_verify/index.js && bun build src/tools/mstar_path_resolve/index.ts --target node --outfile dist/tools/mstar_path_resolve/index.js && bunx tsc && cp -R dist/hooks hooks && mkdir -p tools && cp dist/tools/mstar_status_validate/index.js tools/mstar_status_validate.js && cp dist/tools/mstar_worktree_check/index.js tools/mstar_worktree_check.js && cp dist/tools/mstar_dispatch_validate/index.js tools/mstar_dispatch_validate.js && cp dist/tools/mstar_iteration_gate/index.js tools/mstar_iteration_gate.js && cp dist/tools/mstar_lease_verify/index.js tools/mstar_lease_verify.js && cp dist/tools/mstar_path_resolve/index.js tools/mstar_path_resolve.js",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "engines": {
+    "bun": ">=1.2.17"
+  },
+  "omp": {
+    "name": "morning-star-harness",
+    "description": "Morning Star multi-agent harness skills and iteration commands for omp."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@mstar-harness/engine": "workspace:*"
+  }
+}

package/plugin.json

@@ -0,0 +1,49 @@
+{
+  "name": "morning-star-harness",
+  "version": "3.6.0-alpha.4",
+  "description": "Morning Star — Agent Plugin for harness engineering workflows: a TS Harness Workflow Engine (@mstar-harness/engine) that enforces deterministic workflow gates, plus mstar-* judgment skills for multi-agent code delivery across OpenCode, Cursor, Codex, Kimi Code, ZCode, and omp.",
+  "author": {
+    "name": "Bohao Tang",
+    "email": "tech@btang.cn"
+  },
+  "homepage": "https://github.com/btspoony/mstar-harness",
+  "repository": "https://github.com/btspoony/mstar-harness.git",
+  "license": "MIT",
+  "keywords": [
+    "morning-star",
+    "mstar",
+    "harness",
+    "agent",
+    "multi-agent",
+    "omp-plugin",
+    "oh-my-pi",
+    "specification-engineering",
+    "harness-engineering",
+    "quality-gates",
+    "workflow",
+    "role-based-workflow"
+  ],
+  "skills": "./skills/",
+  "commands": "./commands/",
+  "agents": "./agents/",
+  "interface": {
+    "displayName": "Morning Star Harness",
+    "shortDescription": "Multi-agent code harness with role-based workflows and quality gates.",
+    "longDescription": "Morning Star (启明星) provides a multi-agent code harness framework with role-based workflows, quality gates, and unified skills across OpenCode, Cursor, Codex, Kimi Code, ZCode, and omp. Start a usable multi-role workflow quickly with PM routing, specs, implementation tracks, QC review, and QA verification.",
+    "developerName": "Bohao Tang",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "brandColor": "#E6B450",
+    "composerIcon": "./assets/logo.svg",
+    "logo": "./assets/logo.svg",
+    "logoDark": "./assets/logo-dark.svg",
+    "defaultPrompt": [
+      "Start a new project with PM routing and role assignment.",
+      "Run a QC review on recent changes.",
+      "Create a product spec and implementation plan."
+    ]
+  }
+}

package/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/skills/mstar-artifacts/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mstar-artifacts
+description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and durable review summaries, `{SDD_DIR}/review/` ephemeral QC/QA bundles, `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` indexes, plus `{HARNESS_DIR}/status.json` (v2 root register) / `{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases) and `{PROJECT_DIR}/<id>/residuals.json` (residual register; severity SSOT, open/close lifecycle). Read when writing plans or QC/QA review bundles, maintaining knowledge/iteration indexes, reading or writing status/snapshot/register, or mapping QC severity to JSON. Required for `@project-manager` on status, residuals, and InReview/QC waves; `@qc-specialist*` before writing review bundle reports; `@qa-engineer` before closing R# when `QA gate: mandatory`. Verdict rules: leaf → `mstar-roles/references/qc-specialist/report-template.md`; PM → `mstar-review-qc`."
+---
+
+## Load order
+
+**Before first Read of this skill: Read `mstar-harness-core` (SKILL.md), and `mstar-conventions` when path symbols matter.** Git branch / worktree / QC checkout → **`mstar-branch-worktree`**. On conflict, **`mstar-harness-core` wins**.
+
+## Scope (plan directory artifacts)
+
+| Topic | See |
+|-------|-----|
+| Main plan, review bundle naming, durable summaries, QC waves, residual and plan index order | `references/plan-files-and-reports.md` |
+| Plan template (Global Constraints, Interfaces) | `templates/plan.main.md` |
+| knowledge / iterations / specs boundaries and indexes | `references/knowledge-and-designs.md` |
+| `status.json` (v2 root), workflow snapshots, project register, residual severity / lifecycle, engine-check queries | `references/status-and-residuals.md` |
+| Empty-repo `status.json` template | `templates/status.empty.json` (`templates/README.md`) |
+| Tech-debt rollup (read-only) | `mstar status tech-debt [path]` (engine `techDebtRollup`; see `references/status-and-residuals.md`) |
+
+**Out of scope:** branch and QC/QA checkout alignment → **`mstar-branch-worktree`**; leaf QC checklist and verdict → **`mstar-roles/references/qc-specialist/`**; PM QC orchestration → **`mstar-review-qc`**; `{HARNESS_DIR}` discovery and init → **`mstar-conventions`**.
+
+## `status.json`, workflow snapshots, and open residual (summary)
+
+- **`{HARNESS_DIR}/status.json` (v2)**: active-lifecycle register — `{ version: 2, updated_at, workflows[] }`. Each entry points at its snapshot dir (`dir: workflows/<id>`); terminal lifecycles are unregistered after the snapshot write.
+- **`{WORKFLOW_DIR}/<id>/snapshot.json`**: per-lifecycle running state — `plans[]` rows (legacy PlanRow shape verbatim) + per-row `execution_lease` + top-level `integration_merge_lease` / `execution_policy` / `branch` anchors / `control_worktree_path`.
+- **`{PROJECT_DIR}/<id>/residuals.json`**: open residual register, `entries[<plan-id>]` arrays — the **open-list SSOT** (severity enum + lifecycle semantics verbatim; project-less flows use `_default`).
+- **Canonical**: register new findings only in the project register (`projects/<id>/residuals.json`); v1 root `residual_findings` is legacy read-only — migrate via `mstar migrate`, do not dual-write.
+
+> **Engine check (when available):** run `mstar status validate <path>` (or `import { validateStatus } from "@mstar-harness/engine"` in a host hook). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+- **Fail-loud handoff**: findings must pass `validateResidual` (per entry) / `validateProjectRegister` (register) before registration; snapshots and the v2 root pass `validateWorkflowSnapshot` / `validateStatus` (`mstar status validate`); malformed → reject + rewrite → **`references/status-and-residuals.md`** (“Fail-loud handoff contract”).
+- **Lifecycle**: open → verified close **in place** in the register (`lifecycle` / `closed_at` / `closure_note`); machine **`severity`** enum in reference. v1 `archived/residuals/` + `archive-residuals` are retired.
+
+- **Findings cleanup**: Assignment **`Findings cleanup: zero-residual | allow-residual`** (the `metadata.findings_cleanup` mirror is deleted); iteration Phase 2 defaults to **`zero-residual`** → **`references/status-and-residuals.md`** (“Findings cleanup modes”).
+
+> **Engine check (when available):** run `mstar status findings-cleanup <plan-id> [--project <id>] [--mode zero-residual|allow-residual]` (or import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook) to enforce the Findings cleanup mode above against the plan's register entries. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+- **`{WORKFLOW_DIR}/<id>/notes.jsonl`**: per-workflow append-only notes ledger (runtime); snapshot plan-row `notes` is the legacy verbatim copy. **Tech-debt rollup**: `mstar status tech-debt <project-dir>` over the project registers — **`references/status-and-residuals.md`**.
+- **Iteration Phase 2 leases** (snapshot: `control_worktree_path`, `plans[].execution_lease`, top-level `integration_merge_lease`): field semantics → **`references/status-and-residuals.md`** (“Iteration execution leases”); Phase 2 execution checklist → **`mstar-iteration`** `references/phase-2-worktree-lease.md`; full protocol prose (single copy) → **`mstar-engine-legacy`** `references/lease-protocol.md`.
+
+> **Engine check (when available):** run `mstar lease verify --workflow <id> [--plan <plan-id>]` or `mstar lease verify-integration --workflow <id>` (or import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook) to validate the iteration leases above on the workflow snapshot (execution_lease / integration_merge_lease). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq` examples → **`references/status-and-residuals.md`**.
+
+**Templates (this skill):** `templates/status.empty.json` — the **v2 shape** (`version: 2`, `updated_at`, `workflows: []`); copy into `{HARNESS_DIR}/` (`templates/README.md`).
+
+## Workflow
+
+产物生命周期主链：主 plan 落盘 `{PLAN_DIR}`（命名见 `references/plan-files-and-reports.md`）→ 实现推进时更新 workflow snapshot（`workflows/<id>/snapshot.json` 的 `plans[]` 行 + 根 `status.json` `workflows[]` 登记）→ 审查波次产出 `{SDD_DIR}/review/` bundle（raw QC/QA reports）+ durable gate summary 回写主 plan / snapshot → 关闭后 residual **in place** close in the project register（`projects/<id>/residuals.json`）。索引（`{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{PLAN_DIR}`）随产物更新。
+
+## Decision Rules
+
+- residual **severity** 是机器字段 SSOT（`references/status-and-residuals.md`）；每条新 finding 只登记 project register（`projects/<id>/residuals.json` → `entries[<plan-id>]`），v1 根级 `residual_findings` 仅 legacy 只读，**禁止**双写。
+- **`Findings cleanup: zero-residual`** 默认（迭代 Phase 2）：可修 findings 当轮 fix → re-review 清干净；仅真 blocker 可 defer 且须 Durable Roadmap。
+- 登记前必须过 `validateResidual` / `validateProjectRegister` / `validateStatus`（fail-loud handoff）；malformed → reject + rewrite。
+
+## Evidence
+
+正确结果 = 可复核产物链：`{SDD_DIR}/review/` 审查 bundle 落盘 + 主 plan / workflow snapshot 的 durable gate summary + residual 生命周期（open → verified close **in place** in the register）。拒绝「仅对话声称」。
+
+## References
+
+- `references/plan-files-and-reports.md` — 主 plan / review bundle 命名、QC 波次、durable summaries
+- `references/status-and-residuals.md` — `status.json` (v2), workflow snapshots, project register, residual severity / lifecycle / engine-check queries
+- `references/knowledge-and-designs.md` — knowledge / iterations / specs 边界与索引

package/skills/mstar-artifacts/references/knowledge-and-designs.md

@@ -0,0 +1,110 @@
+# `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 迭代 compass / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
+
+**路径符号（默认）**：`**{KNOWLEDGE_DIR}** = **{HARNESS_DIR}/knowledge/**`；`**{ITERATION_DIR}** = **{HARNESS_DIR}/iterations/**`。完整符号表见 `mstar-conventions` SKILL.md「Harness 与 Plan 目录发现」。
+
+本节将「用户文档」与「agent / 实施用知识」分开，**与具体业务仓库无关**；项目可在根目录 `AGENTS.md` 用一小段指向本 reference 或复述分界关键词，避免重复维护长文。
+
+## 与公开文档目录的分工（典型为 `docs/`）
+
+
+| 区域 | 典型内容 | 受众 / 权威 |
+|------|----------|-------------|
+| **`docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
+| **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap — **跨迭代长期权威** | 产品/API 规范性最高权威；**iteration-start** 由 product/architect 主写 |
+| **`{ITERATION_DIR}`**（可选） | **`<iteration-id>/` package**（`delivery-compass.md` + `guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
+| **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker — **经 `mstar-compound` 结晶** | Agent handoff；**不**在 iteration-start 由 product/architect 新增 |
+| **`{PROJECT_DIR}/<id>/references/`**（可选） | 主题化研究：surveys、epic roadmaps、第三方 notes — **与项目绑定**，非跨迭代 corpora | 项目所有者 / operator；engine 只列文件名，**无 markdown schema** |
+| **`{PLAN_DIR}/`** | 单 plan 主文件、durable gate summary、可选 `residuals/` | 计划执行与长期决策留档 |
+
+
+**不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC/QA 原始过程报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{SDD_DIR}/review/`；长期 gate 摘要回写主 plan。
+
+## `{ITERATION_DIR}`（可选·迭代/版本级 package）
+
+- **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.mstar/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列；legacy 项目可继续为 `.agents/iterations/`）。
+- **放什么**：**`<iteration-id>/` package** — `delivery-compass.md`（迭代状态 SSOT）；`guides/`（探索、过程）；`specs/`（迭代级规格草案）；可选 package `README.md`；遗留规划快照。
+- **不放什么**：已锁定的仓库级规范（→ **`{SPECS_DIR}/`**）；已提升的跨迭代实施 SSOT（→ **`{KNOWLEDGE_DIR}/`**，经 compound）；单 plan QC/QA 原始报告（→ `{SDD_DIR}/review/`）。
+- **索引**：`**{ITERATION_DIR}/README.md**` **一行 = 一次迭代**（指向 `<iteration-id>/`）；`<iteration-id>/README.md` 登记 package 内文档（Documents 单表）。
+- **维护**：`@product-manager` / `@architect` 起草 package；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 package 并**提升**至 `{KNOWLEDGE_DIR}/`。
+- **Compass 路径**：canonical `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`（迭代状态 SSOT）；legacy flat `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 仅兼容读。
+
+## `{SPECS_DIR}`（可选·长期规格）
+
+- `{SPECS_DIR}` 解析（非空即停）：`{HARNESS_DIR}/specs/` → `docs/specs/` → 仓库根 `specs/`；皆无或皆空则 init 创建 `{HARNESS_DIR}/specs/`。Legacy 只读：`{HARNESS_DIR}/designs/` 或根 `designs/` 非空时可用。细则 → `mstar-conventions` SKILL.md「`{SPECS_DIR}` 解析」。
+- **放什么**：跨迭代有效、已锁定或待锁定的产品/API 规范、ADR、契约 — **iteration-start 主产出**（product/architect）。
+- **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ package 或 plan 素材，**close 时 compound 提升**）。
+- **索引**：非 trivial 树建议 `{SPECS_DIR}/README.md`；plan **`primary_spec` / `spec_refs`** 主要指向此处。
+
+## `{KNOWLEDGE_DIR}`（可选·实施知识库）
+
+- **新增 SSOT 默认路径**：**iteration-close** 时经 **`mstar-compound`** 写入；**iteration-start §1.6 禁止** product/architect 新增（见 **`mstar-iteration/references/iteration-artifact-boundaries.md`**）。
+- **必须**维护 `**{KNOWLEDGE_DIR}/README.md**` 作为**目录索引**：至少包含表格列 **Document（链接）**、**Source Plan（`plans[].id`）**、**Description**、**Status**（如 `Active` / `Superseded by implementation (<plan-id>)` / `Archived`）。
+- 可选：目录级 `**{KNOWLEDGE_DIR}/AGENTS.md**` 承载命名、维护节奏、与 `{SPECS_DIR}` 的权威边界（Nexus 模式）；harness 宽规则仍以 `mstar-conventions` 与本 reference 为准。
+- 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
+
+## `{PROJECT_DIR}/<id>/references/`（可选·主题化研究语料）
+
+- **物理路径**：`**{PROJECT_DIR}/<id>/references/**`（默认 `{HARNESS_DIR}/projects/<id>/references/`；`.mstarc` `project_dir` 声明时用声明值）。
+- **放什么**：**主题化研究** — surveys、epic roadmaps、第三方 notes，与拥有它的项目（`<id>`）绑定（compass ruling 1）。项目缺失用 `_default`（`{PROJECT_DIR}/_default/references/`）。
+- **不放什么**：冻结规格 / ADR（→ `{SPECS_DIR}/`）；compound 结晶的实现 SSOT（→ `{KNOWLEDGE_DIR}/`）；迭代内 ranking notes 与草稿 spec（→ `{ITERATION_DIR}/<id>/guides|specs/`）。研究**不**迁入这三处 corpora，三处内容也**不**迁入 `references/`。
+- **engine 职责边界**：`listProjectReferenceFiles(projectDir)` 只返回**文件名**（相对路径、`/` 分隔、code-unit 排序；跳过根级 `roadmap.md` / `residuals.json`；缺失目录 → `[]`）；**不**读文件正文，**不**做 markdown schema 校验 — 归属语义是本 reference（技能散文）契约，不是 engine 校验。
+- **历史 dump**：harness 根 `.mstar/references/` 已退役（dogfood 后缺省或仅一行 redirect）；当前路径由 `mstar-project-governance` Scope 表与 `mstar-conventions` `references/artifact-storage-paths.md` 命名。
+
+## 文件命名
+
+- 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
+- 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `{KNOWLEDGE_DIR}` 根（除非团队明确约定）。
+- 迭代 compass 放在 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间；**不要**新写根目录 flat `*-delivery-compass.md`。
+
+## 与 `status.json` 的链接
+
+- 某 plan 的**权威设计输入**在规格、迭代 compass 或（已有）知识库中时，在 `**plans[].metadata**` 中登记路径：`**primary_spec**` / `**spec_refs**` → 优先 **`{SPECS_DIR}/`**；`**iteration_compass**` / `**iteration_refs**` → **`{ITERATION_DIR}/`**；已有 **`{KNOWLEDGE_DIR}/`** 链接保留，但 **iteration-start 不得新增** knowledge 路径。
+- 执行方在 **implement 前**：先扫 `{KNOWLEDGE_DIR}/README.md` 索引（若存在），发现并阅读与当轮相关的 **Active** 行（发现式阅读，不要求通读全库）；再按 metadata 读取已登记路径；均与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
+
+## 维护规则
+
+1. **新增**：
+   - **Specs（长期）**：`{SPECS_DIR}/` → spec 索引（若有）→ `plans[].metadata` 的 `primary_spec` / `spec_refs`
+   - **迭代 package**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md`（目录一行）+ package README → `iteration_refs`
+   - **Knowledge**：**`mstar-compound`** @ iteration-close（含 package **提升**）→ `{KNOWLEDGE_DIR}/README.md`
+2. **阅读**：开发类 agent 在开始编码前，**先扫** `{KNOWLEDGE_DIR}/README.md` 索引（若存在），发现并阅读与当轮相关的 **Active** 行（不要求通读全库）；随后**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
+3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
+4. **归档**：
+   - **iteration-start（强制）**：`writing-specialist` §1.6 以 **`{SPECS_DIR}/` 全库卫生为主**；对**既有** `{KNOWLEDGE_DIR}/` 仅归档/错放纠正，**不**新增 knowledge。细则 → **`mstar-iteration/references/iteration-corpus-hygiene.md`**。
+   - **其它时机**：当文档内容已完全反映到已合并代码中、且非 iteration-start 扫库时：可将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`；可保留原位或迁入 `archived/knowledge/`。
+5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` package 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
+
+## 与 review bundle、`{PLAN_DIR}/residuals/` 的区分
+
+- `**{SDD_DIR}/review/`**：偏 **审查流程临时证据**（review package、QC1/2/3、consolidated、QA），gitignored，可在 Done 后丢失。
+- `**主 plan gate summary**`：偏 **长期门禁决策摘要**（verdict、review range、R#、QA gate），随主 plan 追踪。
+- `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与 project register `entries[<plan-id>]` 配套，canonical 见 `mstar-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
+- `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
+- `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
+- `**{PROJECT_DIR}/<id>/references/**`：偏 **主题化研究**（surveys、epic 备注、第三方 notes），随项目绑定；与 specs / knowledge / iteration guides 职责不混写。
+- review bundle、gate summary、residuals、knowledge、iterations 可互链，但职责不混写。
+
+---
+
+## `{PLAN_DIR}/residuals/<plan-id>/`（可选·open residual 散文详情）
+
+当某条 open residual 需要**多于** register（`projects/<id>/residuals.json` → `entries[<plan-id>]`）里结构化字段所能承载的叙述时，可在本目录增加 **Markdown 散文**，作为 **SSOT 的补充**（**不替代** JSON；**权威仍以 register 中的 open 条目为准**）。
+
+
+| 与相邻目录的分工                                  | 典型内容                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `**{SDD_DIR}/review/**`       | QC / QA **流程临时证据**（`qc1.md` … `qc-consolidated.md`、`qa.md` 等），gitignored                  |
+| **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文**                  |
+| `**{KNOWLEDGE_DIR}/**`            | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
+| `**{ITERATION_DIR}/**`            | 迭代 package（`<id>/delivery-compass.md` 等）；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
+
+
+**文件命名（推荐）**：`<finding-id>-<short-label>.md`，其中 `**finding-id`** 与该条在 register（`projects/<id>/residuals.json` → `entries[<plan-id>]`，见 `mstar-conventions` **SKILL.md** 开篇）中的 `**id`**（如 `R1`）或团队约定的 `**td-*` 等技术债编号**一致，便于 `detail_doc` 与目录互查。
+
+**登记**：在对应 open 条目中填写可选 `**detail_doc`**（仓库内相对路径，常形如 `**{PLAN_DIR}/residuals/<plan-id>/R1-….md**`）。**禁止**只写散文、不在 register 中登记 open 行。
+
+**维护**：`**@project-manager`**（或与 Assignment 一致的可写角色）；`**@qc-specialist***` 宿主白名单通常**不含**本目录——审查结论仍以 Assignment 指定的 `**{SDD_DIR}/review/`** 为准，散文由 PM/实现方据结论整理。
+
+**关闭**：当该条在 register 中 close（`lifecycle` / `closed_at` / `closure_note`）或从 `entries[<plan-id>]` 移除时，应将对应 `**.md**` 一并收口：可迁入 `**{HARNESS_DIR}/archived/knowledge/**`（若视为历史考据）、或团队约定的归档子路径（与 register 变更同批可追溯）；并在关闭条目的 `**closure_evidence` / `closure_note**`（或团队约定字段）中**写明散文最终路径**。勿长期保留「JSON 已关闭而散文仍留在 `residuals/` 且声称仍 open」的状态。

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

@@ -0,0 +1,98 @@
+# Plan 文件与 Review Bundle 留档（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 排 review bundle / QC 波次前，须已 Read **`mstar-harness-core`** skill（SKILL.md；多 worktree 与 QC 单一 `HEAD` 见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
+
+## Plan 文件（`{PLAN_DIR}/<name>.md`）
+
+每个 plan 的详细内容（任务清单、决策、Sign-off）。
+
+**命名（推荐）**：`<plan-id>-<plan-name>.md`（例：`01-data-infrastructure.md`）。snapshot plan 行的 `file` 字段填相对仓库根或 `{PLAN_DIR}` 下的实际路径。
+
+## Review bundle（`{SDD_DIR}/review/`）
+
+QC/QA 原始过程报告默认是 **ephemeral review bundle**，置于 `{SDD_DIR}/review/`（即 `{HARNESS_DIR}/sdd/<plan-id>/review/`）。该目录随 `{SDD_DIR}` gitignored，不作为长期 git 审计链。
+
+**QC basename rule**：`{SDD_DIR}` 已含 `<plan-id>` — **do not** repeat it in report filenames. Put `plan_id` in YAML frontmatter only.
+
+| 类型 | 文件名（相对 `{SDD_DIR}/review/`） |
+|------|--------|
+| QC 三审报告（**SDD 默认** `Execution mode: sdd`） | `qc1.md`、`qc2.md`、`qc3.md` |
+| QC 单席报告（**`inline` / hotfix 例外**） | `qc.md` |
+| QC 汇总结论（tri 模式） | `qc-consolidated.md` |
+| QA 验收报告（`QA gate: mandatory`） | `qa.md`（或 Assignment 指定的同目录 basename） |
+
+
+## SDD 运行时（不入 reports）
+
+Per-task briefs, implementer reports, review diffs, branch review packages, and QC/QA bundle files live under **`{SDD_DIR}`** (`mstar-conventions`). Gitignored. Main plan may index `{SDD_DIR}` / `{SDD_DIR}/review/` paths only — do not paste SDD bodies or raw QC/QA reports into plan markdown.
+
+Plan template with Global Constraints / Interfaces → **`templates/plan.main.md`**.
+
+## QC 模式（L3 plan 级）
+
+职责分层 L1–L4 → **`mstar-review-qc/references/review-responsibility-boundaries.md`**。bundle basename 见上表；触发时机与 re-review 波次见下节 **§ QC 三审触发时机**。
+
+## Durable summaries（主 plan / status）
+
+Raw bundle files may disappear after the working context is gone. Before Done, PM must preserve the durable decision surface:
+
+- Main plan `## Review Gate Summary`:
+  - `Decision`: `Approve` | `Approve with residuals` | `Request Changes` | `Needs Discussion`
+  - `Review range / Diff basis`
+  - `Review bundle`: `{SDD_DIR}/review/`
+  - `QC inputs`: `qc1.md` / `qc2.md` / `qc3.md` or `qc.md`
+  - `Blocking result`: fixed / none / deferred with reason
+  - `Residual findings`: R# ids + short titles + owner/target
+- Main plan `## QA Gate Summary` when QA applies:
+  - `QA gate` / `QA mode`
+  - evidence reused vs newly run checks
+  - related R# closure recommendations
+- `{PROJECT_DIR}/<id>/residuals.json` (default `{HARNESS_DIR}/projects/<id>/`): open R# machine SSOT — `entries[<plan-id>]`.
+
+The durable summary is not a paste of raw reports. It is a small gate record sufficient for handoff after `{SDD_DIR}` is unavailable.
+
+## Residual findings（R#）：权威在哪、和主 plan 谁先谁后？
+
+- **Open 条目的单一事实来源（SSOT）**是 **`{PROJECT_DIR}/<id>/residuals.json`**（默认 `{HARNESS_DIR}/projects/<id>/`；无项目流程用 `_default`）的 **`entries[<plan-id>]`**（canonical 见 `mstar-artifacts` **SKILL.md** 开篇；字段见 `mstar-artifacts/references/status-and-residuals.md`）。**同一工作副本内**的会话 handoff、关闭流程**以该数组为准**（本地 SSOT，默认 gitignored）；**跨 clone** 须持久的 residual 须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 等（见 `mstar-conventions`「Git 跟踪策略」）。
+- **推荐操作顺序**（避免 plan 与 JSON 两套 ID 漂移）：
+  1. `project-manager` 读完 review bundle 并完成「QC 三审轻量汇总」：对 finding **去重合并**，为每条待跟踪项分配**稳定 `id`**（如 `R1`、`R2`，全 plan 内唯一）。
+  2. **立即**将上述条目写入 register **`entries[<plan-id>]`**（含 `source` 指向 reviewer seat + bundle basename + finding id + review range，便于回溯；`source_plan` = plan id，`registered_at` = 当日）；v1 根级 `residual_findings` 仅 legacy 只读，**勿**双写。
+  3. **可选**：在主 plan 中增加 **「Residual findings（索引）」** 小节，**仅复述** `id` + 短标题 + 决策摘要，并写明「**权威列表见** `projects/<id>/residuals.json` `entries[<plan-id>]`（见 `mstar-conventions` **SKILL.md** 开篇）」。**不要**只在主 plan 里「发明」R# 而不写回 SSOT。
+- **不要**反过来把主 plan 当作唯一登记处：若仅更新 plan、register 未同步，下一任 agent **无法**依赖 SSOT 继承债务状态。
+
+## QC 三审触发时机（单 plan · 多 batch）
+
+- **默认（SDD）**：同一 **`plan_id`** 下，**plan QC tri-review**（`qc-specialist` ×3 → `{SDD_DIR}/review/qc1.md`…`qc3.md` + `qc-consolidated.md`）**仅在** dev team 按该 plan 约定范围全部交付、且 **L2 task reviewers** 均已通过后执行 **一次**。**不要**在每个中间 batch 跑完整三审。
+- **单席例外**：`Execution mode: inline` / hotfix → 交付完成后 **一次** `qc.md`（`QC mode: single`）。
+- **batch 之间**：依赖实现方按 **`mstar-coding-behavior`** 提供完成证据、主 plan 任务勾选与 PM 协调；需要书面中间意见时，用对话、主 plan 批注或**非三审**的定向检查（如单审、架构 review），**不**默认等同「又一轮完整三审」。
+- **After `Request Changes` (default — targeted re-review)**：PM maps each **blocking** finding to the QC seat that raised it (`source` on R#, consolidated table, or the originating `qcN.md` / `F-###`). Dispatch **only** those reviewers (`QC re-review: targeted — reviewers: qc-specialist, qc-specialist-2, …`). Each re-reviewing QC **updates the same** bundle file (`qc1.md` / `qc2.md` / `qc3.md`) in place (add `## Revalidation`, refresh verdict / `generated_at`); **do not** add `qc1-rev2.md` siblings for targeted re-review. PM **updates the same** `qc-consolidated.md` and durable plan summary.
+- **Full tri re-review (exception)**：Only when Assignment states **`QC re-review: full tri-review`**. Run **three** parallel reviews again; use **new bundle basenames** (`qc1-rev2.md` … `qc3-rev2.md`, `qc-consolidated-rev2.md`) so wave-1 files stay distinct; PM states **active wave** in consolidated decision and durable plan summary. See `mstar-review-qc` · `mstar-dispatch-gates`.
+- **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用 `{SDD_DIR}/review/<scope>/` 子目录，避免与终局 `qc1..3.md` 混名。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-branch-worktree` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 向显式 `target_branch` **走 PR**，见 `mstar-conventions` SKILL.md **「Spec 驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
+
+### 多 `plan_id` 同时 `InReview`（PM 编排）
+
+- **流程**：实现完成 → 该 **`plan_id`** 进入 **`InReview`** → **QC 三审（仅针对该 plan 的 `Review range`）** → PM consolidated → **QA** → **`Done`**。**禁止**在多个 `plan_id` 已 `InReview` 的情况下，只推进新实现、不派 QC，或把多个 plan 的变更**伪装成**一套三审字段（单一 `plan_id` / 单一 diff 范围覆盖多 plan）。
+- **并行 vs 串行**：不同 `plan_id` **相互独立**时，可 **并行**派发多组三审（每组各自的 Assignment 与 `{SDD_DIR}/review/`）；若 PM 选择串行，须在 Status Update 写明顺序——**每组仍须完整三审 + QA**，不是「一个大 QC」混审。
+- **读 skill**：书写或派发 QC 相关 Assignment 前，PM **必须** Read **`mstar-review-qc`**（编排与 residual）；leaf `qc-specialist*` → **`mstar-roles/references/qc-specialist/`**。见 `mstar-conventions` SKILL.md **QC pre-dispatch gate**。
+
+**QC 落盘与宿主权限**：`qc-specialist` / `qc-specialist-2` / `qc-specialist-3` 在支持路径白名单的宿主上（如 OpenCode 的 **`permission.edit`**），默认 **仅可** Write/Edit Assignment 指定的 **`{SDD_DIR}/review/`** 下 **`.md`**。全局 agent 提示词应允许 `.mstar/sdd/**`、`.agents/sdd/**` 及 `.worktrees/**`。报告文件**必须**以 YAML **frontmatter** 开头（键见各 QC agent 提示词）。
+
+**QC 报告与 Git**：默认 raw QC/QA bundle **不**执行 `git add` / `git commit`。PM 将 durable gate summary 写入主 plan（本地会话 SSOT；默认 gitignored）并在当轮更新 project register 的 open residuals（本地 SSOT，默认 gitignored）。**跨 clone 须持久的** residual 或决策须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 或 `{HARNESS_DIR}/AGENTS.md`（见 `mstar-conventions`「Git 跟踪策略」）— **勿**默认 `git add` `status.json` / `workflows/` / `projects/` / `plans/`。若项目显式 opt-in 跟踪审计报告，在 Assignment 写 `Review archive mode: tracked reports` 并使用项目 allow rules。
+
+## 主 plan 内任务清单（Markdown checkbox）
+
+- **谁应更新**：`fullstack-dev` / `frontend-dev` / `fullstack-dev-2`、`qa-engineer`、`ops-engineer`、`architect`、`product-manager` 在**完成本人 Assignment 范围内的工作后**，须在主 plan（`<plan-id>-<plan-name>.md`）中把**对应条目**的 Markdown 任务标记为已完成（常见：`- [ ]` → `- [x]`；若项目用其它清单记号，保持同文件内一致）。与 Completion Report **并列**，作为跨会话可核对的**落盘痕迹**。
+- **范围**：**只勾选与当前任务直接对应、且已由本角色交付证据支撑的条目**；不得代为勾选他人负责或未完工项。若正文用分段、Owner 或角色标签区分任务，以 Assignment 与文内约定为准。
+- **与 snapshot / frontmatter 的关系**：勾选任务**不**等于整条计划收口。snapshot `plans[].status` 及主 plan frontmatter 的 **`Done`** 仍**仅** `project-manager` / `qa-engineer`（见「状态更新权限」）。`architect` / `product-manager` **不得**擅自将整条计划标为 `Done`；是否将 snapshot 推进为 `InReview` 等仍按下文「状态更新权限」与 Assignment。
+- **`qc-specialist*`**：**不得**修改主 plan（宿主仅允许 Assignment 指定的 review bundle `.md`）；审查结论落在 `{SDD_DIR}/review/` 内。若主 plan 需新增或勾选与审查相关的条目，由 `project-manager` 或 Assignment 明确授权的角色据报告回写。
+- **只读角色**：不直接改主 plan；将建议交给 `project-manager` 代为更新清单。
+
+Plan 正文与 snapshot 行必须保持一致；不一致时以 snapshot `plans[].status` 为准并尽快纠正正文或登记 notes（`workflows/<id>/notes.jsonl`）。
+
+## Done 标记方式
+
+1. **Frontmatter**（首选）：添加 `status: Done` 和可选的 `done_at: YYYY-MM-DD`。
+2. **文件名**（备选）：重命名为 `DONE__<name>.md` 或 `<name>.done.md`。
+
+同时更新 snapshot 对应 plan 行（`workflows/<id>/snapshot.json` → `plans[]`）与根 `status.json` `workflows[]` 登记。

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

@@ -0,0 +1,99 @@
+# Plan Quality Bar
+
+The standard every implementation plan must meet before it is locked and dispatched. Applies to `{PLAN_DIR}` main plans, SDD task-briefs derived from them, and audit-generated plans. Extends the Plan 质量门 in **`mstar-phase-gates`** and the `plan.main.md` template.
+
+## Core principle: write for a zero-context executor
+
+SDD implementers start with a fresh session — they have not seen the Prepare conversation, the spec, or other tasks. Audit plans may be executed sessions or days later by a different model. If a plan references "the pattern discussed above" or "as agreed in clarify", it is broken.
+
+The plan is the spec. Everything the executor needs must be in the file or reachable from a file path it names.
+
+## Quality checklist
+
+Before a plan is locked, verify every item:
+
+### 1. Self-contained context
+
+- Every task names **exact file paths** (create / modify / test), not "the relevant module".
+- **Current-state excerpts** — when a task modifies existing code, include the code as it exists today (short, with `file:line` markers), enough that the executor can confirm it is looking at the right thing.
+- **Conventions to follow** — name the repo pattern (error handling, naming, layering) and point to one exemplar file: "Error handling follows the Result pattern — see `src/lib/result.ts` and its use in `src/users/api.ts:40-60`. Match it."
+- **Interfaces** — consumed and produced signatures are listed verbatim, not paraphrased.
+
+### 2. Verification gates
+
+Every step ends with a **command and its expected result**, not a judgment call.
+
+| Pattern | Weak (do not use) | Strong (required) |
+|---------|-------------------|-------------------|
+| Test step | "run the tests" | `pnpm test -- orders` → all pass, including 2 new tests |
+| Typecheck | "make sure it compiles" | `pnpm typecheck` → exit 0, no errors |
+| Removal | "clean up the old code" | `grep -rn "oldPattern" src/` → no matches |
+
+The executor should never have to *judge* whether a step succeeded — it runs a command and compares output.
+
+### 3. Hard boundaries
+
+Each task lists:
+
+- **In scope** — the only files the executor should modify.
+- **Out of scope** — files that look related but must not be touched, with a one-line reason ("deprecated path, scheduled for deletion").
+
+### 4. STOP conditions
+
+Plan-specific escape hatches — not boilerplate. Name the risks particular to this work:
+
+- "If `config.ts` no longer exports `getDb`, STOP — the migration in plan 003 may have landed first."
+- "If the test in step 2 fails for a reason other than the missing import, STOP — the assumption that `User.email` is non-nullable may be false."
+
+The executor stops and reports instead of improvising. This is what lets a weaker model execute safely.
+
+### 5. Drift check
+
+Stamp the commit the plan was written against. Before execution, the executor (or PM) runs:
+
+```
+git diff --stat <planned-at-sha>..HEAD -- <in-scope-paths>
+```
+
+If any in-scope file changed, the executor compares the plan's "current state" excerpts against live code before proceeding. On mismatch → STOP condition.
+
+In SDD, this maps to the `BASE_SHA` recorded before Task 1.
+
+### 6. Done criteria (machine-checkable)
+
+ALL must hold — commands and expected results, not prose:
+
+```markdown
+## Done criteria
+
+- [ ] `pnpm typecheck` exits 0
+- [ ] `pnpm test` exits 0; new tests for <X> exist and pass
+- [ ] `grep -rn "<old-pattern>" src/` returns no matches
+- [ ] No files outside the in-scope list are modified (`git status`)
+```
+
+"Works correctly" is not a done criterion.
+
+## Relationship to existing plan elements
+
+| This quality bar | Existing mstar element |
+|------------------|----------------------|
+| Self-contained context | `plan.main.md` Global Constraints + per-task Files/Interfaces |
+| Verification gates | `plan.main.md` per-step "Run: `cmd`" lines |
+| Hard boundaries | `plan.main.md` per-task Files (Create/Modify) — extended with explicit Out-of-scope |
+| STOP conditions | New — not previously formalized |
+| Drift check | SDD `BASE_SHA` — generalized to all plans |
+| Done criteria | `plan.main.md` per-step checkboxes — elevated to machine-checkable |
+
+## When to apply
+
+| Plan source | Applies |
+|-------------|---------|
+| PM/architect Prepare | Full bar before `plan(locked)` |
+| SDD task-brief (extracted from plan) | Inherits from plan; `mstar sdd task-brief` carries excerpts forward |
+| Audit-generated plan (`mstar-audit`) | Full bar — audit plans are the most context-isolated |
+| Hotfix (`inline`) | Relaxed — see `mstar-phase-gates` hotfix exception |
+
+## Attribution
+
+The self-containment, verification-gate, STOP-condition, and drift-check concepts are adapted from the [improve](https://github.com/shadcn/improve) skill (MIT, © shadcn), integrated into Morning Star's plan-artifact conventions.