@mstar-harness/opencode 2.4.0 → 3.0.1

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

@@ -4,6 +4,4 @@ Copy these into `{HARNESS_DIR}` when bootstrapping a project. Path symbols (`{HA
 
 | File | Copy to | Notes |
 |------|---------|--------|
-| `status.empty.json` | `{HARNESS_DIR}/status.json` | Root `residual_findings` only (see **`mstar-plan-artifacts` SKILL.md**). Replace `updated_at` with the real date. Iteration Phase 2 lease fields (`control_worktree_path`, `execution_lease`, `integration_merge_lease`) are added at runtime — not in the empty template. |
-| `notes.empty.json` | `{HARNESS_DIR}/notes.json` | Optional program timeline. Replace `updated_at` when first edited. |
-| `plans-done.empty.json` | `{HARNESS_DIR}/archived/plans-done.json` | **Profile B only** — `{ "plans": [<plan-id>, ...] }` **only** (`references/done-compaction.md`). Append id on each `Done` compaction; no other keys or object elements. |
+| `status.empty.json` | `{HARNESS_DIR}/status.json` | The **v2 root register** shape (`version: 2`, `updated_at`, `workflows: []`) — see **`mstar-plan-artifacts` SKILL.md** + `references/status-and-residuals.md`. Replace `updated_at` with the real date. Per-lifecycle snapshot / register / lease fields are created at runtime by engine writers (`workflows/<id>/snapshot.json`, `projects/<id>/residuals.json`) — not in the empty template. |

package/harness-skills/mstar-plan-artifacts/templates/status.empty.json

@@ -1,7 +1,5 @@
 {
-  "version": 1,
+  "version": 2,
   "updated_at": "1970-01-01",
-  "plans": [],
-  "residual_findings": {},
-  "metadata": {}
+  "workflows": []
 }

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-plan-conventions
-description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{SDD_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` 发现与初始化（默认 `.mstar/`，兼容 `.agents/`）、`docs` 与 harness 子树边界、review bundle、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（显式 base / merge 靶 / PR target）、Morning Star plan-writing path gate、工期预估（agent-oriented）。**必须**在读写 `.mstar/` / `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / review bundle / knowledge → **`mstar-plan-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
+description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{SDD_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` / `{WORKFLOW_DIR}` / `{PROJECT_DIR}` 发现与初始化（默认 `.mstar/`，兼容 `.agents/`）、`docs` 与 harness 子树边界、review bundle、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（显式 base / merge 靶 / PR target）、Morning Star plan-writing path gate、工期预估（agent-oriented）。**必须**在读写 `.mstar/` / `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / review bundle / knowledge → **`mstar-plan-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
 ---
 
 ## Load order（必读顺序）
@@ -10,6 +10,7 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 | 你还可能要 Read | 何时 |
 |-----------------|------|
 | `mstar-plan-artifacts` | 主 plan、review bundle 摘要、`status.json`、residual、InReview/QC 波次、knowledge |
+| `mstar-project-governance` | `projects/<id>/roadmap.md` 编写约定 + `residuals.json` register 生命周期、`_default` 回退 |
 | `mstar-branch-worktree` | Assignment 写分支 / worktree / QC 检出 |
 | `mstar-review-qc` | 派 QC（PM 同轮必读；SDD 强制 tri） |
 | `mstar-sdd` | PM 执行 `Execution mode: sdd` 的 implement 波次 |
@@ -26,20 +27,53 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 | `{PLAN_DIR}` | `{HARNESS_DIR}/plans/` |
 | `{SDD_DIR}` | `{HARNESS_DIR}/sdd/<plan-id>/`（SDD 运行时 scratch + review bundle；gitignored） |
 | `{ITERATION_DIR}` | `{HARNESS_DIR}/iterations/` |
-| `{KNOWLEDGE_DIR}` | `{HARNESS_DIR}/knowledge/` |
+| `{KNOWLEDGE_DIR}` | `{HARNESS_DIR}/knowledge/`（默认；`.mstarc` `knowledge_dir` 声明时用声明值） |
 | `{SPECS_DIR}` | `{HARNESS_DIR}/specs/`（默认）；解析见下文「`{SPECS_DIR}` 解析」 |
+| `{WORKFLOW_DIR}` | `{HARNESS_DIR}/workflows/`（默认；`.mstarc` `workflow_dir` 声明时用声明值）——v3 每 lifecycle 一个 `workflows/<id>/`（`snapshot.json` + `notes.jsonl`） |
+| `{PROJECT_DIR}` | `{HARNESS_DIR}/projects/`（默认；`.mstarc` `project_dir` 声明时用声明值）——v3 项目层 `projects/<id>/roadmap.md` + `residuals.json` |
 
-> **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.
+> **Engine check (when available):** import `resolveHarnessDir` / `resolvePlanDir` / `resolveSddDir` / `resolveIterationDir` / `resolveKnowledgeDir` / `resolveSpecsDir` / `resolveWorkflowDir` / `resolveProjectDir` 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}` 解析顺序（找到即停；探测**永不越过工作区根**——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/`
-3. 否则 `.plans/` 或 `plans/` → 遗留同目录 `{HARNESS_DIR}={PLAN_DIR}`
-4. 皆无 → 未启用 plan；进度走对话与 Completion Report
+1. 显式 override：`opts.harnessDir` / `MSTAR_HARNESS_DIR`（全权优先，短路一切探测与配置文件）
+2. 否则 **`.mstarc`** `[config] harness_dir=<dir>`（仓库本地声明，见下「`.mstarc` 格式」；find-first-stop 向上找最近文件，**不越过工作区根**）
+3. 否则 `.mstar/` → `{HARNESS_DIR}=.mstar/`, `{PLAN_DIR}=.mstar/plans/`
+4. 否则 `.agents/` → legacy `{HARNESS_DIR}=.agents/`, `{PLAN_DIR}=.agents/plans/`
+5. 否则 `.plans/` 或 `plans/` → 遗留同目录 `{HARNESS_DIR}={PLAN_DIR}`
+6. 皆无 → 未启用 plan；进度走对话与 Completion Report
 
 并存时 **`.mstar/` 优先**；仅当项目已有 `.agents/` 且无 `.mstar/` 时继续沿用 `.agents/`。
 
+#### `.mstarc` 格式（INI 子集；默认 gitignored，见下「Git 跟踪策略」）
+
+```ini
+[config]
+harness_dir=.custom_dir
+plan_dir=planning
+sdd_dir=process/sdd
+iteration_dir=process/iterations
+knowledge_dir=knowledge
+specs_dir=specs/custom
+workflow_dir=process/workflows
+project_dir=process/projects
+enforcement=hard
+```
+
+- `#` / `;` 注释；`[section]` 头；`key=value`（去空白）。仅读 `[config]` 段，未知键忽略（向前兼容）。
+- 目录键：`harness_dir`（`{HARNESS_DIR}`）、`plan_dir`（`{PLAN_DIR}`）、`sdd_dir`（`{SDD_DIR}` 的 per-plan 基目录，`<plan-id>` 仍会追加）、`iteration_dir`（`{ITERATION_DIR}`）、`knowledge_dir`（`{KNOWLEDGE_DIR}`）、`specs_dir`（`{SPECS_DIR}`，**权威**——声明后不再走候选链）、`workflow_dir`（`{WORKFLOW_DIR}`）、`project_dir`（`{PROJECT_DIR}`）。全部相对 `.mstarc` 所在目录解析（绝对路径亦可）；无需目录已存在（可后续 scaffold；v3 的 `workflows/` / `projects/` 子目录由 engine writers 按需创建）。
+- **`enforcement=hard|soft`**：仓库级硬门禁策略（`hard` 硬门禁、`soft` 本地回滚；其他值忽略）。优先级：显式 Config > Assignment `Enforcement: hard` 头标记（仅派发闸门）> `.mstarc` > 迭代 compass frontmatter > 默认 warn-only。`.mstarc` `soft` 可回滚 hard compass；`.mstarc` `hard` 硬化无标记的派发与各闸门。
+- 子目录键与 `enforcement` 由 engine `resolvePlanDir` / `resolveSddDir` / `resolveIterationDir` / `resolveKnowledgeDir` / `resolveSpecsDir` / `resolveWorkflowDir` / `resolveProjectDir` / `resolveRepoEnforcement` 读取：从 harness 目录与其父目录（仓库根，`.mstarc` 的文档化位置）向上找最近配置文件。
+- 优先级：显式 override > `.mstarc` > 探测。非默认布局的仓库写一个 `.mstarc` 即可程序化解目录问题，无需逐宿主设置 env / config。
+
+**无 engine 时的手工解析（runtime 缺席，技能文本为权威）：**
+
+1. 从当前目录向上找**最近**的 `.mstarc`（find-first-stop），**不越过工作区根**（CLI=git top-level，非 git=start 自身；dsh=会话工作区）。
+2. 读 `[config]` 段：`key=value`（去空白），`#`/`;` 注释与空行忽略；同一键最后一次出现生效。
+3. `harness_dir` 存在 → 相对该 `.mstarc` 所在目录解析（绝对路径直接用），即 `{HARNESS_DIR}`；无需目录已存在。
+4. 其余键（`plan_dir` / `sdd_dir` / `iteration_dir` / `knowledge_dir` / `specs_dir` / `workflow_dir` / `project_dir`）从 **`{HARNESS_DIR}` 或其父目录**（仓库根）向上找最近 `.mstarc` 读取；值同样相对配置文件目录解析；`specs_dir` 声明后直接采用（跳过「`{SPECS_DIR}` 解析」候选链与空目录规则），`sdd_dir` 只替换基目录（`<plan-id>` 仍追加），`workflow_dir` / `project_dir` 直接替换默认子目录名。
+5. 未声明的键回落默认组合：`{HARNESS_DIR}/plans/`、`{HARNESS_DIR}/sdd/<plan-id>/`、`{HARNESS_DIR}/iterations/`、`{HARNESS_DIR}/knowledge/`、`{HARNESS_DIR}/workflows/`、`{HARNESS_DIR}/projects/`、`{SPECS_DIR}` 候选链。
+
 ### `{SPECS_DIR}` 解析（找到非空目录即停）
 
 1. `{HARNESS_DIR}/specs/`（默认 `.mstar/specs/`）
@@ -72,8 +106,8 @@ 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`** → `mstar sdd workspace <plan-id>` 创建）
+1. 建 `.mstar/`、`plans/`、`status.json`（**v2 空模板**见 **`mstar-plan-artifacts/templates/status.empty.json`**：`version: 2` + `workflows: []`）
+2. 可选 `notes.json`（legacy）、`knowledge/`、`iterations/`、`{HARNESS_DIR}/specs/`、`sdd/`（空目录占位；运行时 per-plan 子目录由 **`mstar-sdd`** → `mstar sdd workspace <plan-id>` 创建；`workflows/` / `projects/` 由 engine writers 按需创建，**不**预建）
 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/`。
 
@@ -95,11 +129,15 @@ PM 在需要持久化追踪时：
 - `iterations/`
 - `plans/`
 - `sdd/`
-- `notes.json`
+- `notes.json`（legacy；运行时 notes 走 `workflows/<id>/notes.jsonl`）
 - `status.json`
+- `workflows/`（v3 每 lifecycle 运行态：`<id>/snapshot.json` + `<id>/notes.jsonl`）
+- `projects/`（v3 项目层：`<id>/roadmap.md` + `<id>/residuals.json`）
 
 Legacy `.agents/` 项目：将上表路径前缀 `.mstar/` 换为 `.agents/`。
 
+**v3 运行时目录的 gitignore 说明（文档化；canonical snippet 零改动）**：`workflows/` 与 `projects/` 都位于已被 **`.mstar/**` 默认忽略**的 `{HARNESS_DIR}` 之下——**不需要**在仓库根 `.gitignore` 增加任何条目，也**不新增** re-include 条目（它们不是 tracked 结果）。`workflows/` / `projects/` 子目录由 **engine writers 按需创建**（`writeWorkflowSnapshot` / `registerWorkflow` / project-register 写入路径），**不是** `scaffoldHarness` 的初始化产物——`mstar init` 不会预建空目录。
+
 **多 worktree（iteration L1）**：默认 gitignored 的进程产物**不会**随 `git worktree add` 进入 feature 检出。读写须经 **control worktree** 绝对路径（`<control_worktree_path>/{HARNESS_DIR}/…`）；产品代码改在 feature worktree。细则与反模式（禁止因 feature 缺 plans 而 `Worktree mode: waived`）→ **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」。
 
 **Canonical `.gitignore` snippet**（skills 与 CLI `init` 对齐）：
@@ -114,6 +152,8 @@ Legacy `.agents/` 项目：将上表路径前缀 `.mstar/` 换为 `.agents/`。
 !.mstar/knowledge/**
 !.mstar/specs/
 !.mstar/specs/**
+# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
+.mstarc
 ```
 
 Legacy `.agents/` 等价：
@@ -138,9 +178,9 @@ Legacy `.agents/` 等价：
 - **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
 - **PR target**：全部 Plans 与 iteration-close 完成后，向显式 `target_branch` 提 PR（窄例外见 Assignment `Branch policy`）。
 - Git 操作与 QC 单一 `HEAD` → **`mstar-branch-worktree`**。
-- `status.json` 登记 root `metadata.iteration_base_branch` / `metadata.target_branch`，以及 plan `metadata.spec_integration_branch` / `merge_target` → **`mstar-plan-artifacts`**。
+- workflow snapshot 登记顶层 `branch.base`（`iteration_base_branch`）/ `branch.target`（`target_branch`）/ `branch.integration`（`spec_integration_branch`），以及 plan 行 `metadata.spec_integration_branch` / `merge_target` → **`mstar-plan-artifacts`**。
 
-**解析顺序**（`mstar-iteration` §2.3）：`status.json` metadata → compass frontmatter → 向用户确认。**禁止**因仓库默认分支名为 `main`/`master` 就自动采用。
+**解析顺序**（`mstar-iteration` §2.3）：workflow snapshot `branch` anchors → compass frontmatter → 向用户确认。**禁止**因仓库默认分支名为 `main`/`master` 就自动采用。
 
 ## Plan-Writing Path Gate
 
@@ -162,7 +202,7 @@ Plans are written to **`{PLAN_DIR}`** when persistent plan tracking is enabled.
 
 ## Evidence
 
-正确结果 = 落盘产物可复核：`{HARNESS_DIR}/status.json` 含对应 plan 行（状态 + `metadata` 分支字段），plan 文件存在于 `{PLAN_DIR}`，`{HARNESS_DIR}/AGENTS.md` 分层与 gitignore 与本文约定一致（进程本地 / 结果共享），`mstar path resolve` 输出与路径符号表一致。
+正确结果 = 落盘产物可复核：`{WORKFLOW_DIR}/<id>/snapshot.json` 含对应 plan 行（状态 + `metadata` 分支字段；根 `status.json` v2 仅 workflows 注册表，无 plan 行），plan 文件存在于 `{PLAN_DIR}`，`{HARNESS_DIR}/AGENTS.md` 分层与 gitignore 与本文约定一致（进程本地 / 结果共享），`mstar path resolve` 输出与路径符号表一致。
 
 ## References
 

package/harness-skills/mstar-plan-conventions/references/artifact-storage-paths.md

@@ -6,7 +6,7 @@
 
 ## Harness 子树内（`{HARNESS_DIR}/` 下）
 
-这些是 agent handoff 用的结构化产物。**Git 跟踪**遵循 `mstar-plan-conventions` SKILL.md「Git 跟踪策略」：**进程本地、结果共享** — `plans/`、`iterations/`、`status.json`、`sdd/` 等默认 gitignored；`AGENTS.md`、`knowledge/`、`specs/` 默认 tracked。
+这些是 agent handoff 用的结构化产物。**Git 跟踪**遵循 `mstar-plan-conventions` SKILL.md「Git 跟踪策略」：**进程本地、结果共享** — `plans/`、`iterations/`、`status.json`、`workflows/`、`projects/`、`sdd/` 等默认 gitignored；`AGENTS.md`、`knowledge/`、`specs/` 默认 tracked。
 
 | 产物 | 解析后路径（默认 `.mstar/`） | 读写的技能 |
 |------|---------------------------|-----------|
@@ -15,12 +15,15 @@
 | **主 plan** | `.mstar/plans/<plan-id>-<name>.md`（gitignored；本地会话 SSOT） | PM / `mstar-plan-artifacts` |
 | **Review bundle（QC/QA 原始过程报告）** | `{HARNESS_DIR}/sdd/<plan-id>/review/`（gitignored；默认 `.mstar/sdd/<plan-id>/review/`） | `mstar-sdd`、`mstar-review-qc`、`qa-engineer` |
 | **SDD scratch** | `{HARNESS_DIR}/sdd/<plan-id>/`（gitignored；含 per-task handoff 与 `review/` bundle） | `mstar-sdd` |
-| **status.json** | `.mstar/status.json`（gitignored；本地会话 SSOT） | `mstar-plan-artifacts` |
+| **status.json（v2 根）** | `.mstar/status.json`（gitignored；本地会话 SSOT；`{version: 2, updated_at, workflows[]}` 活跃 lifecycle 登记） | `mstar-plan-artifacts`、`mstar-iteration` |
+| **workflow snapshot** | `{HARNESS_DIR}/workflows/<id>/snapshot.json`（gitignored；每 lifecycle 运行态：`plans[]` 行 + leases + branch anchors；`<id>` = plan id 或 iteration id） | `mstar-plan-artifacts`、`mstar-iteration`、`mstar-branch-worktree` |
+| **workflow notes ledger** | `{HARNESS_DIR}/workflows/<id>/notes.jsonl`（gitignored；append-only 运行时笔记） | `mstar-plan-artifacts`、`mstar-iteration` |
+| **project roadmap** | `.mstar/projects/<id>/roadmap.md`（gitignored；frontmatter `{project_id, title, status, created_at, milestones[]?, residuals_ref?}` + 正文约定） | `mstar-plan-artifacts`、`mstar-iteration` |
+| **project register** | `.mstar/projects/<id>/residuals.json`（gitignored；open residual SSOT：`entries[<plan-id>]` 数组；项目缺失用 `_default`） | `mstar-plan-artifacts`、`mstar-review-qc` |
 | **迭代 package** | `.mstar/iterations/<iteration-id>/`（gitignored；`delivery-compass.md`、`guides/`、`specs/`、可选 `README.md`） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读；默认排除 compass） |
 | **迭代索引** | `.mstar/iterations/README.md`（gitignored；一行 = 一次迭代） | `mstar-iteration`（读写） |
 | **规格** | `{HARNESS_DIR}/specs/`（默认 tracked；解析见 `mstar-plan-conventions`） | `mstar-plan-artifacts` |
 | **harness AGENTS** | `.mstar/AGENTS.md`（tracked） | PM / init |
-| **archived residuals** | `.mstar/archived/residuals/<plan-id>.json`（gitignored） | `mstar-plan-artifacts` |
 | **archived knowledge** | `.mstar/archived/knowledge/`（保留原 `{KNOWLEDGE_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-plan-artifacts` |
 | **archived specs** | `.mstar/archived/specs/`（保留原 `{SPECS_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-plan-artifacts` |
 

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

@@ -13,14 +13,13 @@
 ## Bootstrap 最小步骤
 
 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`** → `mstar sdd workspace <plan-id>` 创建）。
+2. 初始化 `status.json`：从 **`mstar-plan-artifacts/templates/status.empty.json`** 复制（**v2 形状**：`version: 2` + `workflows: []`）；residual canonical 见 **`mstar-plan-artifacts` SKILL.md**；字段与生命周期见 **`mstar-plan-artifacts/references/status-and-residuals.md`**。`workflows/` 与 `projects/` 子目录由 engine writers 按需创建（**不**在 bootstrap 预建）。
+3. 初始化可选 `notes.json`（legacy）；`sdd/` 空目录占位（per-plan 子目录由 **`mstar-sdd`** → `mstar sdd workspace <plan-id>` 创建）。
 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`。
-7. 创建 `{HARNESS_DIR}/AGENTS.md`（harness 子树规则；**tracked**）：符号表可复述 `{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 与 `docs/` 分工；新项目推荐 `.mstar/AGENTS.md`，已有项目可继续使用 `.agents/AGENTS.md`。
-8. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `{HARNESS_DIR}/AGENTS.md` 作为 harness SSOT。
-9. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
+5. 可选：创建 `{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`。
+6. 创建 `{HARNESS_DIR}/AGENTS.md`（harness 子树规则；**tracked**）：符号表可复述 `{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 与 `docs/` 分工；新项目推荐 `.mstar/AGENTS.md`，已有项目可继续使用 `.agents/AGENTS.md`。
+7. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `{HARNESS_DIR}/AGENTS.md` 作为 harness SSOT。
+8. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
 
 ## Git 跟踪策略（进程 vs 结果）
 
@@ -29,7 +28,7 @@
 | 类别 | 默认 tracked | 默认 gitignored |
 |------|--------------|-----------------|
 | 结果（跨 clone handoff） | `{HARNESS_DIR}/AGENTS.md`、`{KNOWLEDGE_DIR}/**`、`{SPECS_DIR}/**` | — |
-| 进程（本地会话 SSOT） | — | `plans/`、`iterations/`、`status.json`、`notes.json`、`sdd/`、`archived/` |
+| 进程（本地会话 SSOT） | — | `plans/`、`iterations/`、`status.json`、`workflows/`、`projects/`、`notes.json`、`sdd/`、`archived/` |
 
 跨 clone 须持久的 residual 或决策：经 **`mstar-compound`** 提升入 `{KNOWLEDGE_DIR}/`、写入 `{SPECS_DIR}/`，或记入 tracked `{HARNESS_DIR}/AGENTS.md` — **勿**默认 `git add` `status.json` / `plans/`。
 
@@ -42,7 +41,7 @@
 
 ### `{HARNESS_DIR}/AGENTS.md`（harness 层）
 
-- 放：`{HARNESS_DIR}`/`{PLAN_DIR}`/`{ITERATION_DIR}`/`{KNOWLEDGE_DIR}`/`{SPECS_DIR}` 契约、`docs/` 与 harness 子树内容边界、状态推进门禁、QC/QA 对齐规则、residual 生命周期、Done compaction profile（Profile B 时声明 `archived/plans-done.json` 仅为 `{ "plans": [<plan-id>, ...] }`，细则见 **`mstar-plan-artifacts/references/done-compaction.md`**）。
+- 放：`{HARNESS_DIR}`/`{PLAN_DIR}`/`{ITERATION_DIR}`/`{KNOWLEDGE_DIR}`/`{SPECS_DIR}` 契约、`docs/` 与 harness 子树内容边界、状态推进门禁、QC/QA 对齐规则、residual 生命周期。
 - 不放：语言/框架编码细节、业务模块实现约束。
 
 ### `<subdir>/AGENTS.md`（边界层）
@@ -84,7 +83,7 @@
 ## 反模式与修正
 
 - 反模式：在根 `AGENTS.md` 维护当前计划进展与 commit 列表。  
-  修正：迁移到 `status.json` 的 `plans[].metadata` 与 `notes.json`。
+  修正：迁移到 workflow snapshot 的 `plans[].metadata` 与 `workflows/<id>/notes.jsonl`。
 
 - 反模式：每个子目录复制一份完整 harness 规则。  
   修正：保留一行引用 `{HARNESS_DIR}/AGENTS.md`，仅写本目录增量约束。

package/harness-skills/mstar-project-governance/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: mstar-project-governance
+description: Morning Star 项目治理层约定 —— `projects/<id>/roadmap.md` 编写约定（frontmatter schema + body 约定）与 `projects/<id>/residuals.json` register 生命周期（open → verified close in place、severity 枚举、provenance 字段）、`_default` 项目回退规则。写/审 roadmap、登记或关闭 residual、判断项目归属（含无项目流程的 `_default` fallback）、或对齐 roadmap/register 与 engine 校验时 Read。schema 事实与 `packages/engine/src/project.ts` 逐字一致；字段语义 SSOT → `mstar-plan-artifacts`；路径符号 → `mstar-plan-conventions`。
+---
+
+# mstar-project-governance（项目治理层：roadmap + register）
+
+## Load Order
+
+- 先 Read **`mstar-harness-core`**（SKILL.md；冲突时以 core 为准）。
+- 路径符号（`{PROJECT_DIR}` / `{WORKFLOW_DIR}` 解析与 `.mstarc` 声明）→ **`mstar-plan-conventions`**。
+- 字段语义 SSOT（severity 含义、findings cleanup modes、close 协议全文、engine-check 查询）→ **`mstar-plan-artifacts`**（`references/status-and-residuals.md`）。本 skill 只承载**编写约定与生命周期规则**，不重复字段全文。
+
+## Scope
+
+项目层 = `{PROJECT_DIR}/<id>/`（默认 `{HARNESS_DIR}/projects/<id>/`；`.mstarc` `project_dir` 声明时用声明值）：
+
+| 文件 | 内容 |
+|------|------|
+| `roadmap.md` | 项目方向与目标（frontmatter machine-checkable + body 约定） |
+| `residuals.json` | 项目 register：open residual 的 **SSOT**（`entries[<plan-id>]` 数组） |
+
+- **`_default` 回退**：无项目流程（未指定 project id 的 plan / 单 plan / hotfix）落到 **`projects/_default/`**（engine `_DEFAULT_PROJECT`）。项目归属由 plan 的 project id 决定；未归属即 `_default`。
+- 本 skill 的 schema 事实与 **`packages/engine/src/project.ts`** 逐字一致（`validateRoadmap` / `validateProjectRegister` / `findingsCleanupGate` / `techDebtRollup`）；技能文本是语义 SSOT，engine 是确定性校验。
+
+## Roadmap 编写约定（`projects/<id>/roadmap.md`）
+
+### Frontmatter schema（machine-checkable；engine `validateRoadmap`）
+
+```markdown
+---
+project_id: <id>
+title: <title>
+status: active | paused | completed
+created_at: YYYY-MM-DD
+milestones: [ ... ]        # optional
+residuals_ref: residuals.json  # optional
+---
+
+# <title>
+
+## Direction
+...
+```
+
+| 字段 | 必填 | 规则 |
+|------|------|------|
+| `project_id` | 是 | 非空字符串 |
+| `title` | 是 | 非空字符串 |
+| `status` | 是 | 枚举 `active | paused | completed`（其他值 = violation） |
+| `created_at` | 是 | `YYYY-MM-DD` |
+| `milestones` | 否 | 非空字符串列表（空 `milestones:` 视同缺省） |
+| `residuals_ref` | 否 | 非空字符串（指向 register 文件，如 `residuals.json`） |
+
+### Body 约定（warnings only —— 永不翻转 `ok`）
+
+- 应有 **`## Direction`** 小节陈述项目方向。
+- 目标项以 markdown task-list 列出：`- [ ]` 计划/进行中，`- [x]` 已交付。
+- **无 residual→goal 自动链接**（本迭代 Non-Goal）：goal items 不携带 register id；residual 与目标的对齐是人工约定，不是硬门禁。
+
+> **Engine check (when available):** import `validateRoadmap` from `@mstar-harness/engine` in a host hook（无 CLI 命令）校验 `projects/<id>/roadmap.md`。On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Register 生命周期（`projects/<id>/residuals.json`）
+
+### 文档形状、必填字段与枚举（单址 → `mstar-plan-artifacts`）
+
+Register 文档形状（`entries[<plan-id>]` 数组 JSON）、**9 个必填字段**（`id`/`title`/`severity`/`source`/`scope`/`decision`/`owner`/`target`/`tracking`，engine `RESIDUAL_REQUIRED_FIELDS`）与 **severity / decision / lifecycle 枚举**的逐字 schema → **`mstar-plan-artifacts`** `references/status-and-residuals.md`（「Basic structure · project register」+「Residual findings: severity」）。本 skill 只承载编写约定与生命周期规则，**不重复字段全文**。
+
+- `entries[<plan-id>]` 值是**数组** —— v1 `residual_findings[plan-id]` 多 finding 语义逐字保留（一个 plan 可持 2+ open residual）。
+- 每条 = v1 residual entry **逐字** + provenance 字段。
+
+### 生命周期：open → verified close（in place）
+
+- **open**：缺省状态；`lifecycle` 缺省/`false`/`null` = `open`。
+- **close（唯一关闭路径）**：在 register **in place** 置 `lifecycle`（≠ `open`）+ `closed_at`（`YYYY-MM-DD`）+ `closure_note`；推荐 `closure_evidence`。v1 的 `archived/residuals/` 归档路径与 `status archive-residuals` 已移除（该命令现为报错桩，指向 register 状态变更）。
+- **closed 完整性**：`lifecycle` ≠ `open` 时缺 `closed_at` / `closure_note` = violation。
+- **谁更新**：PM 在 consolidated 决策后分配 R# 并登记；`QA gate: mandatory` 时 `qa-engineer` 验证后关闭；`pm-acceptance` 时 PM 验收清单完成后关闭。
+- close 协议全文 → **`mstar-plan-artifacts`** `references/status-and-residuals.md`（「Residual findings lifecycle」）。
+
+### Provenance（register 专属字段）
+
+| 字段 | 规则 |
+|------|------|
+| `source_plan` | 必填非空字符串；**必须等于其 entries key**（不匹配 = 损坏的 provenance，violation） |
+| `registered_at` | 必填 `YYYY-MM-DD` |
+| `lifecycle_id` | 可选非空字符串（迭代拥有该 plan 时的 workflow id） |
+
+### Findings cleanup（与 Assignment 联动）
+
+- Assignment **`Findings cleanup: zero-residual | allow-residual`** 是唯一 mode 来源（`metadata.findings_cleanup` mirror 已删）；迭代 Phase 2 默认 `zero-residual`。
+- `zero-residual`：可修 findings 当轮 fix → re-review 清干净；仅真 blocker 可 defer 且须 Durable Roadmap + `target`；`nit` 必须当场修或删；waived/risk-accepted 必须关闭，不得留 open。
+- `allow-residual`：仅 unresolved **critical** 阻止 Approve。
+- mode 全文与 enforcement → **`mstar-plan-artifacts`** `references/status-and-residuals.md`（「Findings cleanup modes」+ 其 engine check）。
+
+## Workflow
+
+1. 确定项目归属：plan 的 project id（无 → `_default`）。
+2. 写/审 roadmap：frontmatter 过 `validateRoadmap`（schema violations 决定 `ok`；body 约定缺失只出 warnings）。
+3. 登记 residual：新 finding 只写 `{PROJECT_DIR}/<id>/residuals.json` → `entries[<plan-id>]`，登记前过 `validateResidual` / `validateProjectRegister`（fail-loud）。
+4. 关闭：验证后 in place 置 `lifecycle` / `closed_at` / `closure_note`。
+5. 汇总：`mstar status tech-debt [<project-dir>]` 打印跨 register 的 rollup（total_open / by_severity / by_target / by_plan）。
+
+## Decision Rules
+
+- **只写 v2 地址**：open residual 只登记 project register；v1 根级 `residual_findings` 仅 legacy 只读（`mstar migrate` 一次性迁移），**禁止双写**。
+- **fail-loud handoff**：登记前必须过 engine 校验；malformed → reject + rewrite，绝不静默降级写入。
+- **severity 是机器字段**：QC 报告的 Critical / Warning / Suggestion 是**章节标题**，不得逐字抄入 JSON `severity`。
+- **`_default` 不豁免校验**：无项目流程同样走 register（`projects/_default/residuals.json`），schema 与生命周期规则不变。
+
+## Evidence
+
+正确结果 = 可复核产物：`projects/<id>/roadmap.md` 过 `validateRoadmap`（0 violations；warnings 可接受）、`projects/<id>/residuals.json` 过 `validateProjectRegister`、`mstar status findings-cleanup <plan-id>` 按 Assignment mode 绿、`mstar status tech-debt` 输出与 register 一致。拒绝「仅对话声称」。
+
+## References
+
+- **`mstar-plan-artifacts`**（`references/status-and-residuals.md`）— 字段语义 SSOT：severity 含义与门禁关系、findings cleanup modes 全文、close 协议、engine-check 查询示例
+- **`mstar-plan-conventions`** — `{PROJECT_DIR}` / `{WORKFLOW_DIR}` 路径符号、`.mstarc` 声明、gitignore 策略
+- **`mstar-review-qc`** — PM QC 编排与 residual 留档（PM 同轮必读）

package/harness-skills/mstar-review-qc/SKILL.md

@@ -36,11 +36,11 @@ description: "Morning Star QC orchestration — **SDD mandatory plan QC tri-revi
 
 ## Residual Findings 留档门禁（PM）
 
-- 先读 Assignment **`Findings cleanup`**（及可选 `plans[].metadata.findings_cleanup`）→ **`mstar-plan-artifacts/references/status-and-residuals.md`**「Findings cleanup modes」。
+- 先读 Assignment **`Findings cleanup`**（`plans[].metadata.findings_cleanup` mirror 已删——Assignment 是唯一 mode 来源）→ **`mstar-plan-artifacts/references/status-and-residuals.md`**「Findings cleanup modes」。
 - **`Findings cleanup: zero-residual`**（iteration Phase 2 默认）：可修 **Warning / Suggestion / Critical** → **fix-now + targeted re-review**，**禁止**把可修项登记为 open R# 或用 `Approve with residuals` 收口；**`nit`** 当场修或丢弃（无 R#）。仅 **真 blocker-defer**（外部依赖 / 须下轮产品决策 / 用户本轮显式 defer + Durable Roadmap）可登记 open R#（`decision: defer`）。此时 `Approve with residuals` **仅**允许剩余项全是该类 defer。
 - **`Findings cleanup: allow-residual`**（standalone / hotfix / inline 默认）：阻断项修复后仍有 **Warning / Suggestion** 或技术债 → 必须留档；**`Approve with residuals`** 仅当无 open **Critical**；PM 汇总结论须含 residual 清单与跟踪位置。
 - **`severity`** 仅允许 `mstar-plan-artifacts/references/status-and-residuals.md` 枚举。
-- **Open SSOT**：`{HARNESS_DIR}/status.json` 根级 **`residual_findings[<plan-id>]`**；PM 在 consolidated 决策分配 **R1…** 并写入。关闭 → **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**。
+- **Open SSOT**：`{PROJECT_DIR}/<id>/residuals.json`（默认 `{HARNESS_DIR}/projects/<id>/`；无项目流程 `_default`）→ `entries[<plan-id>]`；PM 在 consolidated 决策分配 **R1…** 并写入。关闭 → 在 register 内 **in place** 置 `lifecycle` / `closed_at` / `closure_note`（v1 `archived/residuals/` 与 `archive-residuals` 已移除）。
 - 主 plan 仅作人类索引；不得作为唯一 SSOT。
 - 未完成 residual 留档（`allow-residual`）或未清干净可修 findings（`zero-residual`）→ 不得进入 plan **Done**。
 
@@ -51,7 +51,7 @@ description: "Morning Star QC orchestration — **SDD mandatory plan QC tri-revi
 
 ## PM consolidated 门禁（摘要）
 
-Leaf reviewers apply verdict per **`mstar-roles/references/qc-specialist/report-template.md`**. PM **`{SDD_DIR}/review/qc-consolidated.md`** synthesizes tri (or single-seat `qc.md`) into one gate decision for implement fix waves and QA gate, then records the durable summary in the main plan/status artifacts.
+Leaf reviewers apply verdict per **`mstar-roles/references/qc-specialist/report-template.md`**. PM **`{SDD_DIR}/review/qc-consolidated.md`** synthesizes tri (or single-seat `qc.md`) into one gate decision for implement fix waves and QA gate, then records the durable summary in the main plan / workflow snapshot artifacts.
 
 ### 覆盖语义（未提及 = 未审查）
 

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

@@ -130,7 +130,7 @@ The **`**You are a leaf executor. You MUST NOT:**`** section (previously just pr
 
 ## L1 path fields (iteration Phase 2, lease gate not waived)
 
-When `metadata.control_worktree_path` is set and worktree mode is **not** waived:
+When the workflow snapshot top-level `control_worktree_path` is set and worktree mode is **not** waived:
 
 | Field | Must be |
 |-------|---------|

package/harness-skills/mstar-roles/references/project-manager/plan-management.md

@@ -19,10 +19,8 @@ Legacy fallbacks:
 
 1. Create `{HARNESS_DIR}` and `{PLAN_DIR}` when absent.
 2. Initialize `{HARNESS_DIR}/status.json` from template if available.
-3. Ensure Morning Star **process-artifact** gitignore set is present (canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」): `{HARNESS_DIR}/archived/`, `iterations/`, `plans/`, `sdd/`, `notes.json`, `status.json` (legacy `.agents/` equivalents when applicable). Per-plan `{SDD_DIR}/review/` is created by the SDD/review flow when needed.
-4. Initialize residual archive path: `{HARNESS_DIR}/archived/residuals/`.
-5. **Profile B** only: `{HARNESS_DIR}/archived/plans/` and `archived/plans-done.json` from `mstar-plan-artifacts/templates/plans-done.empty.json` (`{ "plans": [] }` only; see `done-compaction.md`).
-6. Optional: `{HARNESS_DIR}/notes.json`, `{HARNESS_DIR}/knowledge/README.md`.
+3. Ensure Morning Star **process-artifact** gitignore set is present (canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」): `{HARNESS_DIR}/archived/`, `iterations/`, `plans/`, `sdd/`, `notes.json`, `status.json`, `workflows/`, `projects/` (legacy `.agents/` equivalents when applicable). Per-plan `{SDD_DIR}/review/` is created by the SDD/review flow when needed.
+4. Optional: `{HARNESS_DIR}/notes.json` (legacy), `{HARNESS_DIR}/knowledge/README.md`. `workflows/` / `projects/` subdirs are created on demand by engine writers — no pre-creation.
 
 If legacy plan directories already exist, reuse them; avoid dual-structure duplication.
 
@@ -31,13 +29,13 @@ If legacy plan directories already exist, reuse them; avoid dual-structure dupli
 **Principle:** process stays local; results are shared with the team. Full rules → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」.
 
 - **Default tracked** under `{HARNESS_DIR}`: `AGENTS.md`, `{KNOWLEDGE_DIR}/**`, `{SPECS_DIR}/**` (resolved specs path; default `{HARNESS_DIR}/specs/`).
-- **Default gitignored** (local session SSOT / coordination): `archived/`, `iterations/`, `plans/`, `sdd/`, `notes.json`, `status.json`.
-- `status.json` and main plan files remain **local session SSOT** — PM must keep them current on disk, but **do not** default `git add` / `git commit` for cross-clone handoff. Promote durable residuals and decisions into tracked `knowledge/` / `specs/` / `AGENTS.md` (compound) when they must survive clone.
+- **Default gitignored** (local session SSOT / coordination): `archived/`, `iterations/`, `plans/`, `sdd/`, `notes.json`, `status.json`, `workflows/`, `projects/`.
+- `status.json` (v2 root), workflow snapshots, project registers and main plan files remain **local session SSOT** — PM must keep them current on disk, but **do not** default `git add` / `git commit` for cross-clone handoff. Promote durable residuals and decisions into tracked `knowledge/` / `specs/` / `AGENTS.md` (compound) when they must survive clone.
 - If a project explicitly opts into tracking process artifacts, record that policy in `{HARNESS_DIR}/AGENTS.md` and ensure team alignment.
 
 ## PM Responsibilities
 
-- On plan create/update: sync `{HARNESS_DIR}/status.json` in same coordination round.
+- On plan create/update: sync the workflow snapshot (`workflows/<id>/snapshot.json`) + root `{HARNESS_DIR}/status.json` (`workflows[]`) in the same coordination round.
 - Before first non-trivial implement dispatch: ensure main plan file exists and `plan_id` is registered.
 - After each Completion Report: update status before next dispatch (`report-to-status` hard gate).
 - On entering `InReview`: ensure review bundle path (`{SDD_DIR}/review/`) and aligned review metadata are set; write durable gate summaries back to the main plan/status artifacts.
@@ -45,7 +43,7 @@ If legacy plan directories already exist, reuse them; avoid dual-structure dupli
 
 ## PM Plan / Status NEVER
 
-- **NEVER** let `status.json` and on-disk plan truth drift within the same coordination round—update both or mark `Blocked` until reconciled.
+- **NEVER** let the workflow snapshot / root status and on-disk plan truth drift within the same coordination round—update both or mark `Blocked` until reconciled.
 - **NEVER** skip the `report-to-status` sync after a Completion Report when the next dispatch or gate depends on that state.
 
 ## Stage Transitions

package/harness-skills/mstar-roles/references/project-manager/qc-and-residuals.md

@@ -79,7 +79,7 @@ When blocking issues are fixed but non-blocking warnings/suggestions remain:
 
 - Must register residual findings (do not leave as chat-only).
 - Severity enum must follow `mstar-plan-artifacts` SSOT.
-- Canonical store: `{HARNESS_DIR}/status.json` -> root `residual_findings[<plan-id>]`.
+- Canonical store: `{PROJECT_DIR}/<id>/residuals.json` (default `{HARNESS_DIR}/projects/<id>/`; project-less flows `_default`) -> `entries[<plan-id>]`.
 - Required durable gate summary in main plan should list R# ids and decisions, but never replace canonical entries.
 
 Each residual record should include:
@@ -88,12 +88,12 @@ Each residual record should include:
 
 `Approve with residuals` is only valid when no unresolved blocking items remain (and under `zero-residual`, only when leftovers are blocker-defers).
 
-## Residual Closure & Archive
+## Residual Closure
 
 After a residual is fixed/accepted/replaced:
 
-- Update closure fields
-- Archive to `{HARNESS_DIR}/archived/residuals/<plan-id>.json`
-- Remove closed record from open `residual_findings` list in `status.json`
+- Update closure fields (`lifecycle` / `closed_at` / `closure_note`; optional `closure_evidence`)
+- Close **in place** in the register `entries[<plan-id>]` (v1 `archived/residuals/<plan-id>.json` archive path + `archive-residuals` are retired)
+- Or remove the closed entry from the register when the team prefers an empty open list
 
-Do not hard-delete open records without archival semantics.
+Do not hard-delete open records without closure semantics.

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

@@ -8,7 +8,7 @@ Before any non-trivial PM action, read in order:
 4. `mstar-plan-conventions` (path discovery, init, Spec branch summary)
 5. `mstar-review-qc` (same coordination round, **before** any QC dispatch)
 6. **`mstar-sdd`** when implement uses **`Execution mode: sdd`**
-7. **On demand:** `mstar-branch-worktree` (parallel implement, QC/QA checkout); `mstar-plan-artifacts` (`status.json`, R#); `mstar-plan-artifacts` (InReview waves, review bundle naming)
+7. **On demand:** `mstar-branch-worktree` (parallel implement, QC/QA checkout); `mstar-plan-artifacts` (`status.json` v2 root, workflow snapshots, R#); `mstar-plan-artifacts` (InReview waves, review bundle naming)
 
 **Not required:** `mstar-coding-behavior` (orchestration-only PM work).
 
@@ -113,7 +113,7 @@ If any item below matches, fix the dispatch/plan state or mark `Blocked`—do **
 
 - **NEVER** finish a dispatch turn with Assignment Markdown visible but **without** the matching host invokes when assignments were meant to start work (`dispatch incomplete` / paste-only failure).
 - **NEVER** split a required **parallel batch** of `N >= 2` invokes across multiple assistant messages when the host requires a single dispatch turn with all `N` calls.
-- **NEVER** register residuals only inside the plan narrative while skipping root `{HARNESS_DIR}/status.json` `residual_findings[<plan_id>]` when plan conventions require the SSOT field.
+- **NEVER** register residuals only inside the plan narrative while skipping the project register `{PROJECT_DIR}/<id>/residuals.json` → `entries[<plan_id>]` when plan conventions require the SSOT field.
 - **NEVER** write non-canonical residual `severity` strings—use only the machine enum from `mstar-plan-artifacts`.
 - **NEVER** under `Findings cleanup: zero-residual`, park fixable Critical/Warning/Suggestion as open R# or use `Approve with residuals` for them — fix-now + re-review; open residual only for true blocker-defer + Durable Roadmap (`mstar-plan-artifacts` Findings cleanup modes).
 - **NEVER** use `Task category: quick` to skip mandatory Prepare (`specify → clarify → plan`) for substantive work (`mstar-harness-core` hard rule).
@@ -128,12 +128,12 @@ If any item below matches, fix the dispatch/plan state or mark `Blocked`—do **
 - **NEVER** perform specialist document edits in the PM thread when host invoke is required — that is `dispatch incomplete` (`mstar-dispatch-gates`, `mstar-iteration` §1.6).
 - **NEVER** mark the last plan `Done` and then create a PR or declare the iteration complete without **`## Phase 3: iteration-close`** and `mstar-iteration` §3.1–§3.5 checklists.
 - **NEVER** treat final plan closure prose as iteration-close — compound, roadmap `delivered`, and compass `status: completed` require Phase 3.
-- **NEVER** steal or overwrite an active `execution_lease` or `integration_merge_lease` (no TTL, age, or inactivity authority); override only on explicit current-turn user instruction + audit `plans[].notes` (`mstar-plan-artifacts/references/status-and-residuals.md` — “Iteration execution leases”).
+- **NEVER** steal or overwrite an active `execution_lease` or `integration_merge_lease` (no TTL, age, or inactivity authority); override only on explicit current-turn user instruction + audit snapshot plan `notes` / `notes.jsonl` (`mstar-engine-legacy` `references/lease-protocol.md` — “Lease prohibitions”; field semantics → `mstar-plan-artifacts/references/status-and-residuals.md` — “Iteration execution leases”).
 - **NEVER** writable-dispatch for a plan without a **verified** `execution_lease` for that plan (resume only when same `holder` passes verify-held-lease against Assignment `Worktree path` / `Working branch`).
-- **NEVER** writable-dispatch when a plan is `InProgress` but has **no** `execution_lease` — complete orphan recovery first (`mstar-plan-artifacts` — “Orphan recovery”).
-- **NEVER** run or dispatch **parallel** integration merges into `spec_integration_branch` — merge is **serial** via `metadata.integration_merge_lease` from the control worktree (`mstar-iteration` §2.6 · `mstar-branch-worktree` L1).
+- **NEVER** writable-dispatch when a plan is `InProgress` but has **no** `execution_lease` — complete orphan recovery first (`mstar-engine-legacy` `references/lease-protocol.md` — “Orphan recovery”; engine-present: `mstar lease verify --workflow <id>` + iteration checklist).
+- **NEVER** run or dispatch **parallel** integration merges into `spec_integration_branch` — merge is **serial** via the snapshot top-level `integration_merge_lease` from the control worktree (`mstar-iteration` §2.6 · `mstar-branch-worktree` L1).
 - **NEVER** cross-plan writable implement without distinct per-plan verified `execution_lease` + feature worktree; `Plan parallelism: serial` forces serial **scheduling** only — it does **not** waive control worktree or lease gates (`mstar-iteration` §2.0 #5).
-- **NEVER** dispatch **cross-plan parallel** writable implement when same-host exclusive write lock is **not** available on the coordination `status.json` path (cross-host / no shared flock) — default **`Plan parallelism: serial`** or **Blocked** if Assignment still claims parallel; exception only on current-turn user `Cross-host lease race: accepted` (or equivalent) + audit `plans[].notes` — **including when `Worktree mode: waived`** (`mstar-plan-artifacts` — “Hard gate — cross-plan parallel writable implement”).
+- **NEVER** dispatch **cross-plan parallel** writable implement when same-host exclusive write lock is **not** available on the coordination snapshot path (`workflows/<id>/snapshot.json`; cross-host / no shared flock) — default **`Plan parallelism: serial`** or **Blocked** if Assignment still claims parallel; exception only on current-turn user `Cross-host lease race: accepted` (or equivalent) + audit `plans[].notes` — **including when `Worktree mode: waived`** (`mstar-engine-legacy` `references/lease-protocol.md` — full protocol; `mstar-iteration` `references/phase-2-worktree-lease.md` — execution checklist).
 - **NEVER** set `Worktree mode: waived` because default-gitignored `plans/` are missing under a feature worktree — keep feature worktrees; put absolute control **`Plan Path`** / **`SDD dir`** / **`Control harness root`** on Assignments (`mstar-branch-worktree` 「Harness path SSOT under default gitignore」). No flock → serial scheduling only, not worktree waiver.
 
 ---
@@ -214,7 +214,7 @@ Pre-implement Gate Check:
 - PM_Task_Board_published: yes|no
 - batch_strategy_defined: yes|no
 - roadmap_written: yes|no|n/a
-- roadmap_location: <Plan section / PM Task Board / status.json / residual id / n/a>
+- roadmap_location: <Plan section / PM Task Board / workflow snapshot / project register / residual id / n/a>
 - assignment_batch_index: <e.g. 1/3>
 - coverage_ids: <e.g. T1,T2>
 - reason_if_single_assignment: <required when only one batch>

package/harness-skills/mstar-roles/references/qc-specialist/deep-review-lenses.md

@@ -19,7 +19,7 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
 | S2 | **触及敏感模块** | diff 中包含 `auth/`、`payment/`、`security/`、`permission/`、`login/`、`migration/`、`db/migrate/`、`schema/` 路径 |
 | S3 | **首次涉足新领域** | `{KNOWLEDGE_DIR}` 中不存在 diff 触及的模块名；或 plan metadata 标记为首次实现 |
 | S4 | **数据结构变更** | diff 中包含 DDL（`CREATE TABLE`、`ALTER TABLE`、`ADD COLUMN`、schema 文件、migration 文件） |
-| S5 | **plan 显式声明高风险** | plan 正文或 `status.json` 的 plan metadata 中包含 `high-risk`、`critical-path`、`breaking-change` 标记 |
+| S5 | **plan 显式声明高风险** | plan 正文或 workflow snapshot plan 行的 metadata 中包含 `high-risk`、`critical-path`、`breaking-change` 标记 |
 | S6 | **多模块耦合** | diff 跨越 ≥3 个不同模块/包/目录边界 |
 
 **判定**：满足 ≥2 条 → 启用 deep review。QC reviewer 在报告 `## Scope` 节中写明判定依据（例：`Deep review: triggered (S1: 350 lines / 12 files, S2: auth/ + payment/)`）。

package/harness-skills/mstar-roles/references/qc-specialist/report-template.md

@@ -62,7 +62,7 @@ Write under the Assignment-provided **`{SDD_DIR}/review/qc#.md`** (`qc1`…`qc3`
 **Verdict**: Approve | Request Changes | Needs Discussion | Unconfirmed
 ```
 
-Report **Critical / Warning / Suggestion** sections are human-readable; PM maps to machine **`severity`** in `status.json` per `mstar-plan-artifacts/references/status-and-residuals.md`.
+Report **Critical / Warning / Suggestion** sections are human-readable; PM maps to machine **`severity`** in the project register (`projects/<id>/residuals.json`) per `mstar-plan-artifacts/references/status-and-residuals.md`.
 
 ## Verdict rules (reviewer applies)
 

package/harness-skills/mstar-roles/references/qc-specialist/reviewer-workflow.md

@@ -30,7 +30,7 @@ Layer SSOT → `mstar-review-qc/references/review-responsibility-boundaries.md`.
 3. Re-verify branch vs **`Working branch` / `Branch policy`** before concluding.
 4. **Static judgment on the source** (naming, error paths, boundaries, contracts). Default tooling = read/grep only. **Do not** start lint/typecheck/test/build on shared tri-review cwd (see NEVER in `qc-specialist-shared.md`).
 5. Execute **`reviewer-checklist.md`** manually against the diff.
-6. Produce structured findings with severity and evidence. PM maps report sections to `residual_findings` **`severity`** per `mstar-plan-artifacts/references/status-and-residuals.md` — do not invent non-canonical severity strings.
+6. Produce structured findings with severity and evidence. PM maps report sections to register **`severity`** (`projects/<id>/residuals.json` → `entries[<plan-id>]`) per `mstar-plan-artifacts/references/status-and-residuals.md` — do not invent non-canonical severity strings.
 7. **Write report:** Write `.md` to the Assignment-provided `{SDD_DIR}/review/` report path. Do not commit raw bundle reports unless Assignment explicitly says `Review archive mode: tracked reports`.
 8. **No stall:** When done, emit **Completion Report** in the same turn — no “notify PM?” choosers.
 

package/harness-skills/mstar-roles/references/qc-specialist-shared.md

@@ -55,9 +55,9 @@ If any item below matches, **stop** and return `Blocked` to `project-manager`:
 
 - **NEVER** invoke another QC seat or `{role_id}` again, nor `qa-engineer` / dev / `architect` / `project-manager`, unless `Delegation: allowed (...)` lists them.
 - **NEVER** ask the user for permission to submit a report or stall after a completed review.
-- **NEVER** modify business implementation/tests, `status.json` residual fields, or paths outside the Assignment-specified QC report path.
+- **NEVER** modify business implementation/tests, project-register residual fields, or paths outside the Assignment-specified QC report path.
 - **NEVER** `git add .` or commit raw bundle reports by default.
-- **NEVER** close or archive residual entries in `status.json` from QC.
+- **NEVER** close or remove residual entries in the project register (`projects/<id>/residuals.json`) from QC.
 - **NEVER** treat `Handoff` or routing prose as invoke instructions.
 - **NEVER** infer tool exposure implies authorization.
 - **NEVER** run parallel-agent dispatch yourself.

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

@@ -41,7 +41,7 @@ Batch all findings for the human in one message. If clean, proceed silently.
 ## Per-task loop (PM only · Workflow)
 
 1. Record `BASE_SHA` (never use `HEAD~1` later)
-2. `mstar sdd workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `mstar sdd workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
+2. `mstar sdd workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `mstar sdd workspace <plan-id> <control_worktree_path>`；probe 以 v2 根 `status.json`（`workflows[]`）或 workflow snapshot 存在为准，linked worktree 缺文件会 fail closed）
 3. `mstar sdd task-brief <plan> N` → brief file
 4. Dispatch implementer:
     - **`SDD implementer session: fresh`** (default) — new subagent; templates: `references/implementer-prompt.md`
@@ -49,7 +49,7 @@ Batch all findings for the human in one message. If clean, proceed silently.
 5. On `DONE`: `mstar sdd review-package BASE HEAD` → diff file
 6. Dispatch **fresh** task reviewer — role **`code-reviewer`** (L2; **not** `qc-specialist*`; host fallback generic + C5b → `mstar-host` C5) — 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
+8. Append `progress.md`; update the workflow snapshot plan row (`workflows/<id>/snapshot.json` → `plans[]`) `task_commits[]` and `implementer-session.json` `last_task` if sticky
 9. Next task
 
 **Never** dispatch multiple implementers in parallel (write conflicts).

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

@@ -70,7 +70,7 @@ mkdir -p "$SDD_DIR/review"
 mstar sdd 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.
+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 / workflow snapshot + project register (`workflows/<id>/snapshot.json`, `projects/<id>/residuals.json` — session SSOT) and promotes cross-clone decisions into tracked knowledge/specs/`AGENTS.md` per `mstar-plan-conventions` git policy.
 
 ## PM context hygiene