@mstar-harness/opencode 2.4.1 → 3.0.1

package/harness-skills/mstar-engine-legacy/references/status-field-history.md

@@ -0,0 +1,186 @@
+# Status v1→v2 field history (archived contract prose)
+
+> Engine-absent fallback: the full field tables displaced from `mstar-plan-artifacts` when engine validators took over the same contract. Engine-present hosts read `mstar-plan-artifacts/references/status-and-residuals.md` (v2) instead; this file is the historical + fallback full text.
+
+## v1 `{HARNESS_DIR}/status.json` — full shape (historical)
+
+`status.json` lived at `{HARNESS_DIR}/status.json` and was the **SSOT** for `plans[]` row status and open residual findings. Closed residuals were archived to `{HARNESS_DIR}/archived/residuals/<plan-id>.json`.
+
+```json
+{
+  "version": 1,
+  "updated_at": "YYYY-MM-DD",
+  "plans": [
+    {
+      "id": "plan-id",
+      "title": "Plan title",
+      "file": "{PLAN_DIR}/plan-id-feature-name.md",
+      "status": "Todo | InProgress | InReview | Blocked | Done",
+      "owner": "@project-manager",
+      "agents": ["@fullstack-dev"],
+      "progress": 0,
+      "tags": [],
+      "created_at": "YYYY-MM-DD",
+      "updated_at": "YYYY-MM-DD",
+      "done_at": null,
+      "notes": "",
+      "metadata": {}
+    }
+  ],
+  "residual_findings": {
+    "plan-id": [
+      {
+        "id": "R1",
+        "title": "Finding title",
+        "severity": "critical | high | medium | low | nit",
+        "source": "QC-#1 qc1.md F-001 @ <review-range>, QA qa.md, review, …",
+        "scope": "Affected file or component",
+        "decision": "defer | accept | risk-accepted",
+        "owner": "@fullstack-dev",
+        "target": "Before plan 02 / YYYY-MM-DD / milestone",
+        "tracking": "Issue URL or null",
+        "detail_doc": "{PLAN_DIR}/residuals/plan-id/R1-short-label.md"
+      }
+    ]
+  },
+  "metadata": {}
+}
+```
+
+Closed residual entries added: `lifecycle`, `closed_at`, `closure_note`; optional `closure_evidence`, `superseded_by`.
+
+## v1 `plans[]` row fields
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Plan id (legacy alias `plan_id` read-compatible). |
+| `title` / `file` | Display title / main plan path (`{PLAN_DIR}/…`). |
+| `status` | `Todo \| InProgress \| InReview \| Blocked \| Done` (Done only by `@project-manager` / `@qa-engineer`). |
+| `owner` / `agents` / `progress` / `tags` | PM ownership, role agents, progress 0–100, tags. |
+| `created_at` / `updated_at` / `done_at` | `YYYY-MM-DD`; `done_at` set at Done. |
+| `notes` | Per-plan timeline (string array recommended; legacy string OK). |
+| `metadata` | Optional object (see below). |
+
+## v1 `plans[].metadata` standard optional fields
+
+| Key | Type | Purpose |
+| --- | --- | --- |
+| `findings_cleanup` | `zero-residual` \| `allow-residual` | Mirror of Assignment `Findings cleanup`. |
+| `working_branch` | string | Implementation branch; aligns with Assignment `Working branch` (SSOT). |
+| `spec_integration_branch` | string | (Multi-plan same Spec) integration branch; created from root `metadata.iteration_base_branch`. |
+| `merge_target` | string | Next merge target; final PR target is root `metadata.target_branch`. |
+| `branch_policy` | string | One-line policy per `mstar-harness-core`. |
+| `phase` / `priority` / `description` / `scope` | string | Program label; `high\|medium\|low`; one-line scope (pick one key per repo). |
+| `gates` | object | Gate summary (`qc`, `qa`, `typecheck`, `tests`, `lint`, …). |
+| `blocked_since` / `blocked_reason` / `blocked_by_plan_id` / `dependency` / `next_action` | string | Block bookkeeping + deps + next step. |
+| `primary_spec` / `iteration_compass` / `iteration_refs` | string / string[] | Spec / compass pointers. |
+| `qc_status` / `tests` / `commits` | string | InReview/Done snapshots — not a substitute for durable gate summaries or root `residual_findings`. |
+| `sdd_dir` / `sdd_progress` / `review_bundle` / `task_commits` | string / array | SDD scratch path, progress ledger pointer, review bundle pointer, `{task_id,base,head}[]`. |
+
+### v1 `plans[].execution_lease` (iteration Phase 2)
+
+| Field | Type | Required | Semantics |
+| --- | --- | --- | --- |
+| `holder` | non-empty string | Yes | Opaque cooperative owner identity (recommended `<host>:<stable-session-id>`, e.g. `cursor:bc-1234`); stable for claim lifetime; **no credentials**; used for ownership comparison — not `session_label`. |
+| `claimed_at` | RFC 3339 UTC (`Z`) | Yes | Acquisition time (audit only; **not** an expiry clock). |
+| `worktree_path` | absolute path string | Yes | Dedicated feature-worktree root; **MUST** differ from `metadata.control_worktree_path`. |
+| `working_branch` | non-empty string | Yes | Feature branch at `worktree_path`; MUST agree with Assignment `Working branch`. |
+| `session_label` | string | No | Human display only — **MUST NOT** authorize or compare ownership. |
+
+Writers **delete** `execution_lease` on release; `null` and tombstone objects are invalid.
+
+## v1 root `metadata` standard optional fields
+
+| Key | Type | Purpose |
+| --- | --- | --- |
+| `versioning` | object | Cross-plan conventions (team-defined). |
+| `iteration_base_branch` | string | Branch/ref used to create `spec_integration_branch`; required for formal iterations. |
+| `target_branch` | string | Final PR target after iteration-close; required for formal iterations. |
+| `notes` | array | **Legacy** — prefer `{HARNESS_DIR}/notes.json`. |
+| `residual_findings_history` | object | **Legacy** — prefer `archived/residuals/<plan-id>.json`. |
+| `tech_debt_summary` | object | Optional rollup over open R# (engine `techDebtRollup`). |
+| `control_worktree_path` | absolute path string | Iteration Phase 2: canonical repository root checked out to active `spec_integration_branch`; coordination + serial merge cwd. |
+| `integration_merge_lease` | object | While one integration merge is owned; **absent** = unclaimed. Writers **delete** the key on release — never `null`/tombstones. |
+
+## v1 residual entry contract (9 required fields + severity/lifecycle)
+
+Entry keys mirroring engine `RESIDUAL_REQUIRED_FIELDS`: `id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`, `target`, `tracking` (+ optional `detail_doc`). Malformed entries (non-object, missing any required field, or severity outside enum) were rejected fail-loud by `validateResidual` / `validateStatus` — never silent pass-through.
+
+### Severity (machine enum, lowercase English only)
+
+`critical` > `high` > `medium` > `low` > `nit`. `nit` is always lighter than `low`. Forbidden in JSON: `warning`, `Major`, non-English. Legacy `"severity": "warning"` read+rolled up as `low`. QC report **Critical / Warning / Suggestion** are section titles — never copied verbatim into JSON.
+
+### Lifecycle states
+
+`open` (default; omit field) · `resolved` · `waived` · `superseded` · `duplicate`. On close set `closed_at` (`YYYY-MM-DD`) + `closure_note`; recommend `closure_evidence` (PR/commit/test/doc anchor). Owners: fix → implementer; verify → QA (when `QA gate: mandatory`) else PM; write SSOT → PM or QA.
+
+## v1 archive shapes (historical)
+
+**`archived/residuals/<plan-id>.json`** (append to `entries`):
+
+```json
+{
+  "plan_id": "01-data-infrastructure",
+  "schema_version": 1,
+  "entries": [
+    {
+      "id": "R1",
+      "severity": "medium",
+      "lifecycle": "resolved",
+      "closed_at": "2026-04-06",
+      "closure_note": "…",
+      "closure_evidence": "PR #42 / commit …",
+      "archived_at": "2026-04-07"
+    }
+  ]
+}
+```
+
+**`{HARNESS_DIR}/notes.json`** (append-only program timeline):
+
+```json
+{ "schema_version": 1, "updated_at": "YYYY-MM-DD",
+  "entries": [{ "at": "2026-04-08", "message": "Short milestone", "plan_id": "01-data-infrastructure" }] }
+```
+
+`plans[].notes` = per-plan timeline; `notes.json` = cross-plan milestones.
+
+## v1 jq / flock examples (legacy read paths)
+
+```bash
+# Replace .mstar with your resolved {HARNESS_DIR}; legacy projects may use .agents.
+jq '.plans[] | select(.id == "01-data-infrastructure")' .mstar/status.json
+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
+```
+
+Legacy read paths (root `residual_findings` / `metadata.residual_findings` / `archived/residuals/<plan-id>.json`) were **legacy read-only**; `mstar migrate` moved open entries into the register.
+
+## v2 destinations (where each v1 surface landed)
+
+| v1 surface | v2 home |
+| --- | --- |
+| root `plans[]` rows | `{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]` (legacy PlanRow shape verbatim) |
+| root `plans[].execution_lease` | snapshot plan row `execution_lease` |
+| root `metadata.integration_merge_lease` | snapshot top-level `integration_merge_lease` |
+| root `metadata.control_worktree_path` | snapshot top-level `control_worktree_path` |
+| root `metadata.iteration_base_branch` / `target_branch` / `spec_integration_branch` / `merge_target` | snapshot top-level `branch.{base,integration,target}` |
+| root `metadata.plan_parallelism` / `worktree_mode` / `push_policy` | snapshot `execution_policy` |
+| root `metadata.notes` / legacy row `notes` | `{WORKFLOW_DIR}/<id>/notes.jsonl` (runtime ledger; row `notes` kept verbatim as legacy copy) |
+| root `residual_findings` | `{PROJECT_DIR}/<id>/residuals.json` → `entries[<plan-id>]` (array semantics preserved) |
+| `archived/residuals/<plan-id>.json` | register **close in place** (lifecycle/closed_at/closure_note on the entry) |
+| `metadata.tech_debt_summary` | derived `mstar status tech-debt <project-dir>` rollup (v1 stored drift path dead) |
+| root `version: 1` | root `version: 2` + `workflows[]` (active-only registry; terminal rows removed after snapshot write) |
+| v1 root `plans[]`/`residual_findings` trees | migrated first via `mstar migrate [--dry-run] [--path <root>]` |
+
+Root v2 shape:
+
+```json
+{ "version": 2, "updated_at": "YYYY-MM-DD",
+  "workflows": [{ "id": "<plan-or-iteration-id>", "type": "plan | iteration", "started_at": "YYYY-MM-DD", "dir": "workflows/<id>" }] }
+```
+
+## Compatibility
+
+- Read: accept `id` or `plan_id`; write: one canonical key (prefer `id`).
+- Document the canonical key in `{HARNESS_DIR}/AGENTS.md` if migrating.

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

@@ -12,6 +12,7 @@ description: Morning Star (启明星) harness **强制全局入口** —— 信
 - 凡 **`mstar-*`**（`name` ≠ `mstar-harness-core`）假定读者**已 Read 本 skill**。
 - **仅读专题、未读核心** → 未完成 harness 加载。
 - 各专题 SKILL.md 含 **Load order**；按 **`mstar-harness-core`** 专题 skill 索引 + 角色 load contract 按需加载，**禁止**为「保险」通读全部专题。
+- **加载条件（`mstar-engine-legacy`）**：`mstar-engine-legacy` 是**条件契约档案**（engine-absent fallback）。**engine 约束激活（或宿主含 engine 能力）时不加载**——engine-present 宿主以运行时 skills 的 engine-check 指针 + engine 校验为权威；仅 engine-absent 宿主（无 `mstar` CLI / engine import）为找回被 engine 校验接管的 contract 全文而读取（触发契约见其 description）。
 
 ## Standalone harness（`mstar-*` 自洽）
 
@@ -52,7 +53,7 @@ Routing eval（Cursor 插件内回归用，**非**运行时必读）→ `.cursor
 - **`Done`**：仅 `@project-manager` 或 `@qa-engineer`。
 - 实现类可设 **`InReview`**，不可设 **`Done`**。
 
-`status.json` 字段与 residual → **`mstar-plan-artifacts`**。
+`status.json`（v2 根）/ workflow snapshot / project register 字段与 residual → **`mstar-plan-artifacts`**。
 
 ## Task category（路由摘要）
 
@@ -90,10 +91,12 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `mstar-phase-gates` | per-plan 双阶段门禁：Prepare/Execute、意图门禁、hotfix、可验证编辑 |
 | `mstar-iteration` | 迭代管理：Phase 1–5（start / Autonomous Execute / iteration-close / PR delivery / PR merge-ready loop） |
 | `mstar-dispatch-gates` | 派发、Delegation、反递归、SDD 串行、SDD 路径 plan QC 强制 tri |
+| `mstar-engine-legacy` | 条件契约档案（engine-absent fallback）：status v1→v2 字段历史、lease 协议全文、各宿主 N=3/N=1 重述、反递归全清单、Engine-check 样板；engine 激活时不加载 |
 | `mstar-sdd` | Subagent-driven development：file handoff、per-task review、ledger |
 | `mstar-branch-worktree` | 功能分支、worktree、QC/QA 检出对齐 |
 | `mstar-plan-conventions` | `{HARNESS_DIR}` 发现、初始化、Spec 分支模型摘要、产物路径 SSOT |
-| `mstar-plan-artifacts` | 主 plan、review bundle / durable summaries、`status.json`、residual、knowledge、Done 归档 |
+| `mstar-plan-artifacts` | 主 plan、review bundle / durable summaries、`status.json`（v2 根）+ workflow snapshots + project register、residual、knowledge |
+| `mstar-project-governance` | 项目治理层：`projects/<id>/roadmap.md` 编写约定 + `residuals.json` register 生命周期（open → verified close in place）、`_default` 回退、provenance；schema 与 engine `project.ts` 逐字一致 |
 | `mstar-design-md` | DESIGN.md 设计系统规范 —— 创建/审计/维护 design tokens，三级检查清单，light/dark 双主题 |
 | `mstar-review-qc` | PM：QC tri 编排、residual 留档、四层边界；leaf 执行 → `mstar-roles/references/qc-specialist/` |
 | `mstar-coding-behavior` | Think / Simplicity / Surgical / Debugging / Review Feedback / Goal-Driven / Communication |
@@ -148,7 +151,7 @@ Read **`mstar-host`** after this skill; detect host per its table, then Read the
 | 因默认 gitignore 致 feature 缺 plans 而 `Worktree mode: waived`（应保留 feature worktree + control 绝对 Plan Path / SDD dir；无 flock 仅 → `Plan parallelism: serial`） | `mstar-branch-worktree` · `mstar-iteration` §2.0 #5 · `phase-2-worktree-lease` |
 | 并行 writable implement 无隔离（L2 同 plan 多轨：N invoke ≠ worktree；L1 跨 plan：无 verified `execution_lease` + feature worktree） | `mstar-branch-worktree` L1/L2 · `mstar-iteration` §2.6 · `references/parallel-writable-pre-dispatch.md` |
 | 跨 plan 可写派发无 verified `execution_lease` / steal 活跃 lease / 并行 merge 入 `spec_integration_branch` | `mstar-iteration` · `mstar-plan-artifacts`（leases）· `mstar-branch-worktree` L1 |
-| `InProgress` 无 `execution_lease` 未恢复即可写派发 | `mstar-plan-artifacts` — orphan recovery |
+| `InProgress` 无 `execution_lease`（snapshot 行）未恢复即可写派发 | `mstar-plan-artifacts` — orphan recovery |
 | 混淆跨 plan lease 门控并行与单 plan 内 SDD 并行 implementer | `mstar-dispatch-gates` · `mstar-sdd` |
 | residual 只写 plan 不写 SSOT | `mstar-plan-artifacts` |
 | `zero-residual` 下把可修 findings 登记为 open R# / 草草 `Approve with residuals` | `mstar-plan-artifacts` Findings cleanup modes · `mstar-review-qc` |

package/harness-skills/mstar-host/references/_shared/plan-mode-bridge-core.md

@@ -6,13 +6,13 @@ Each per-host bridge (`cursor-plan-mode-bridge.md`, `kimi-plan-mode-bridge.md`,
 
 ## Dual-write SSOT rule
 
-The host **Plan mode** (session plan file, todos, UI) is a **session UX mirror**. Morning Star **SSOT** lives on disk under **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`): the main plan in `{PLAN_DIR}/<plan-id>-<name>.md`, the plan registry in `{HARNESS_DIR}/status.json`, the iteration compass under `{ITERATION_DIR}/…` when in a formal iteration. Mirror every durable plan artifact to the repo; never treat the host plan file/URI/UI alone as the handoff surface.
+The host **Plan mode** (session plan file, todos, UI) is a **session UX mirror**. Morning Star **SSOT** lives on disk under **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`): the main plan in `{PLAN_DIR}/<plan-id>-<name>.md`, the plan registry in `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + per-lifecycle `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows + leases), the iteration compass under `{ITERATION_DIR}/…` when in a formal iteration. Mirror every durable plan artifact to the repo; never treat the host plan file/URI/UI alone as the handoff surface.
 
 ### Priority (hard)
 
 1. User explicit instructions (this turn)
 2. Project `AGENTS.md` / `CLAUDE.md`
-3. **`{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json`** (harness SSOT)
+3. **`{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json` (v2) + workflow snapshot** (harness SSOT)
 4. Host session plan / todos / UI (session UX mirror) — the host bridge names its surfaces
 
 **NEVER** cite only a host plan path / session todo list / chat summary in Assignment **Plan Path**, **Context Loaded**, or Completion Report when `{PLAN_DIR}/<plan-id>-<name>.md` should exist.
@@ -21,7 +21,7 @@ The host **Plan mode** (session plan file, todos, UI) is a **session UX mirror**
 
 1. **Read** (minimum): `mstar-plan-conventions`, `mstar-plan-artifacts` (SKILL.md); Prepare gates from `mstar-phase-gates` if not hotfix.
 2. **Discover** `{HARNESS_DIR}` / `{PLAN_DIR}` per `mstar-plan-conventions` (prefer `.mstar/` + `.mstar/plans/`; reuse legacy `.agents/` only when already present and `.mstar/` is absent).
-3. **Initialize** if absent: `{HARNESS_DIR}/`, `{PLAN_DIR}/`, `status.json` from `mstar-plan-artifacts/templates/status.empty.json`, `archived/residuals/`, Morning Star process-artifact gitignore set (canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」). Full PM checklist: `mstar-roles/references/project-manager/plan-management.md`.
+3. **Initialize** if absent: `{HARNESS_DIR}/`, `{PLAN_DIR}/`, `status.json` from `mstar-plan-artifacts/templates/status.empty.json` (v2 shape), Morning Star process-artifact gitignore set (canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」; `workflows/` / `projects/` subdirs are created on demand by engine writers, not pre-created). Full PM checklist: `mstar-roles/references/project-manager/plan-management.md`.
 
 ## Build resume contract
 
@@ -45,8 +45,8 @@ Not allowed in the parent Build session by default: product implementation, test
 
 | Todo ID (use in title) | Goal | On-disk outcome |
 |------------------------|------|-----------------|
-| **`harness-init`** | Bootstrap harness tree | `{HARNESS_DIR}/`, `{PLAN_DIR}/`, process-artifact gitignore set, `archived/residuals/`, `status.json` initialized |
-| **`spec-register`** | Register plan in SSOT | New `plans[]` row in `status.json` (`id`, `status`, `file`, `metadata`); spec stub in `{SPECS_DIR}` or plan frontmatter |
+| **`harness-init`** | Bootstrap harness tree | `{HARNESS_DIR}/`, `{PLAN_DIR}/`, process-artifact gitignore set, `status.json` (v2) initialized (`workflows/` / `projects/` created on demand by engine writers) |
+| **`spec-register`** | Register plan in SSOT | New root `workflows[]` entry (`{HARNESS_DIR}/status.json` v2) + `plans[]` row in `{WORKFLOW_DIR}/<id>/snapshot.json` (`id`, `status`, `file`, `metadata`); spec stub in `{SPECS_DIR}` or plan frontmatter |
 | **`mirror-plan`** | SSOT main plan file | `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes aligned to the host plan body |
 
 After the host plan is created, keep the host plan body and mirror file **in sync** when scope changes (update both in the same coordination round).
@@ -57,7 +57,7 @@ After the host plan is created, keep the host plan body and mirror file **in syn
 
 1. **Commit**: `git add` + `git commit` on the authorized **Working branch** for this **task id** (one commit per task unless PM explicitly allowed batched commits in Assignment).
 2. **Plan checkbox**: Set `- [x]` on the matching line in `{PLAN_DIR}/<plan-id>-<name>.md`.
-3. **status.json** (when PM round requires): bump `plans[].status` (e.g. `InProgress`) or append coordination notes per `mstar-plan-artifacts`.
+3. **status.json / snapshot** (when PM round requires): bump the snapshot plan row `plans[].status` (e.g. `InProgress`) or append coordination notes to `{WORKFLOW_DIR}/<id>/notes.jsonl` per `mstar-plan-artifacts`.
 4. **Evidence**: Record real `git log -1 --oneline` in Completion Report **Git** (or the plan-mode status note if executing as PM in Plan mode).
 
 **NEVER**
@@ -80,11 +80,11 @@ Dev-role NEVER rules also apply when executing as implementer: `mstar-roles/refe
 
 | Anti-pattern | Fix |
 |--------------|-----|
-| Host plan only, no `{HARNESS_DIR}` files | Run bootstrap todos; write mirror plan + status.json |
+| Host plan only, no `{HARNESS_DIR}` files | Run bootstrap todos; write mirror plan + status.json/snapshot |
 | Todo done, no commit | Commit per task; paste `git log -1` evidence |
 | Drift between host plan and SSOT plan | Update both in same round |
 | Host plan URI as Plan Path | Use `{PLAN_DIR}/...` path |
-| Skip `spec-register` | Add `plans[]` row before implement |
+| Skip `spec-register` | Add the snapshot `plans[]` row + root `workflows[]` entry before implement |
 | Build starts coding in the parent session | Resume PM context; dispatch implement work or block on missing Assignment |
 | Host plan approval treated as Done authority | Check harness plan/status/QC/QA gates first |
 | Resume starts coding from host chat summary | Reload harness context and SSOT plan/status first |

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

@@ -30,7 +30,7 @@ Use skill names in prompts and references. Avoid absolute local paths unless the
 - Codex does not imply an OpenCode-style `question` tool.
 - If a structured user-input tool is available in the active mode, use it for concise 1-3 choice decisions.
 - Otherwise ask one concise Markdown question only after codebase exploration cannot answer it.
-- `update_plan` / local todo UI is session progress only; it does not replace `{PLAN_DIR}` plans or `{HARNESS_DIR}/status.json`.
+- `update_plan` / local todo UI is session progress only; it does not replace `{PLAN_DIR}` plans or `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows).
 - Codex Goal Mode objective is completion criteria for the host thread, not Morning Star Done authority; mirror it into the SSOT plan when the work is implementation-sized.
 
 ## Dispatch and role execution

package/harness-skills/mstar-host/references/cursor-plan-mode-bridge.md

@@ -21,13 +21,24 @@ Bootstrap todos `harness-init` / `spec-register` / `mirror-plan` (emit first, in
 
 ### `spec-register` minimum fields
 
-Add one object to `status.json` → `plans[]`:
+Add a root `workflows[]` entry to `status.json` (v2) + one `plans[]` object to the workflow snapshot:
 
 ```json
+// {HARNESS_DIR}/status.json (v2 root) — active lifecycle entry
+{
+  "id": "<plan-id>",
+  "type": "plan",
+  "started_at": "YYYY-MM-DD",
+  "dir": "workflows/<plan-id>"
+}
+```
+
+```json
+// {WORKFLOW_DIR}/<plan-id>/snapshot.json — plan row (schema_version 1)
 {
   "id": "<plan-id>",
   "status": "Todo",
-        "file": ".mstar/plans/<plan-id>-<short-name>.md",
+  "file": ".mstar/plans/<plan-id>-<short-name>.md",
   "metadata": {
     "primary_spec": "<spec-id or path if known>",
     "description": "<one-line summary>"
@@ -35,14 +46,14 @@ Add one object to `status.json` → `plans[]`:
 }
 ```
 
-Set `updated_at` on `status.json` to today (`YYYY-MM-DD`). Commit **tracked results** in the business repo when applicable: `{HARNESS_DIR}/AGENTS.md`, `{KNOWLEDGE_DIR}/`, `{SPECS_DIR}/` (default git policy — see `mstar-plan-conventions`). Do **not** default `git add` for `status.json`, `plans/`, or `iterations/`.
+Set `updated_at` on `status.json` / the snapshot to today (`YYYY-MM-DD`). Commit **tracked results** in the business repo when applicable: `{HARNESS_DIR}/AGENTS.md`, `{KNOWLEDGE_DIR}/`, `{SPECS_DIR}/` (default git policy — see `mstar-plan-conventions`). Do **not** default `git add` for `status.json`, `workflows/`, `projects/`, `plans/`, or `iterations/`.
 
 ### `mirror-plan` minimum content
 
 - YAML or markdown frontmatter with `plan_id`, title, status (`Todo` / `InProgress` — not `Done` unless PM/QA authority).
 - **Task list** as markdown checkboxes (`- [ ]` / `- [x]`) matching CreatePlan implement todos.
 - **Roadmap / deferred scope** section when delivery is staged, partial, or uses a temporary workaround.
-- Link: “SSOT status: `{HARNESS_DIR}/status.json` → `plans[]` / `residual_findings`.”
+- Link: “SSOT status: `{HARNESS_DIR}/status.json` (v2 `workflows[]`) → `{WORKFLOW_DIR}/<id>/snapshot.json` `plans[]`; open residuals → `{PROJECT_DIR}/<id>/residuals.json`.”
 
 After **CreatePlan**, keep CreatePlan body and mirror file **in sync** when scope changes (update both in the same coordination round).
 
@@ -76,8 +87,8 @@ Use this structure in CreatePlan `plan` markdown; mirror the same sections into
 
 ### Bootstrap (fixed prefix — complete before implement)
 
-1. harness-init — init .mstar/, status.json, process-artifact gitignore set, archived/residuals/
-2. spec-register — register plan_id in status.json; spec stub if applicable
+1. harness-init — init .mstar/, status.json (v2), process-artifact gitignore set
+2. spec-register — register the root `workflows[]` entry + snapshot plan row; spec stub if applicable
 3. mirror-plan — write .mstar/plans/<plan-id>-<short-name>.md
 
 ### Implement
@@ -104,7 +115,7 @@ Commit → SSOT checkbox → `status.json` sync → `git log -1 --oneline` evide
 Before switching from Plan to Agent for implementation (or declaring Plan phase complete):
 
 - [ ] `{PLAN_DIR}/<plan-id>-<name>.md` exists on disk
-- [ ] `status.json` contains `plans[]` entry with matching `id` and `file`
+- [ ] Root `status.json` `workflows[]` contains the entry and `{WORKFLOW_DIR}/<id>/snapshot.json` contains the `plans[]` row with matching `id` and `file`
 - [ ] Bootstrap todos `harness-init`, `spec-register`, `mirror-plan` are **done**
 - [ ] CreatePlan implement todos reference **task ids** traceable to SSOT plan checkboxes
 - [ ] If staged/partial/temporary, CreatePlan and SSOT plan both contain `Roadmap / deferred scope`
@@ -139,7 +150,7 @@ When starting a **new iteration** under Cursor Plan mode (host command may orche
 
 **Single CreatePlan URI (HARD)**: one CreatePlan per Phase 1 Plan session. Updates use file edit tools on that path. If a duplicate plan file was created by mistake: merge into the original, delete the duplicate, keep View Plan on the original.
 
-**Bootstrap relationship**: ordinary per-plan work still uses `harness-init` / `spec-register` / `mirror-plan`. Phase 1 CreatePlan uses Phase 1 todos (`harness-init` → `finalize-compass-plans` → review-edit seats → `pm-lock` → `integration-branch`). Business `plans[]` rows should exist as drafts before Build when direction has converged.
+**Bootstrap relationship**: ordinary per-plan work still uses `harness-init` / `spec-register` / `mirror-plan`. Phase 1 CreatePlan uses Phase 1 todos (`harness-init` → `finalize-compass-plans` → review-edit seats → `pm-lock` → `integration-branch`). Snapshot `plans[]` rows should exist as drafts before Build when direction has converged.
 
 **Helpers**: third-party interview helpers are **not** named here; host **command** layer may use them only after feedback-close when gaps remain.
 

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

@@ -12,7 +12,7 @@ Parallel PM dispatch: **`parallel-dispatch.md`** (Task tool uses same turn model
 
 ## Plan mode × harness dual-write
 
-When **Plan mode** is active, **CreatePlan is session UX**; SSOT is **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`) — `{PLAN_DIR}/<plan-id>-<name>.md`, `{HARNESS_DIR}/status.json`.
+When **Plan mode** is active, **CreatePlan is session UX**; SSOT is **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`) — `{PLAN_DIR}/<plan-id>-<name>.md`, `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows).
 
 Before first **CreatePlan**: Read `mstar-plan-conventions`, `mstar-plan-artifacts`, Prepare gates from `mstar-phase-gates` when not hotfix. Full procedure: **`cursor-plan-mode-bridge.md`**.
 
@@ -20,13 +20,13 @@ Before first **CreatePlan**: Read `mstar-plan-conventions`, `mstar-plan-artifact
 
 | Todo ID | Purpose |
 |---------|---------|
-| `harness-init` | Init `{HARNESS_DIR}`, `{PLAN_DIR}`, process-artifact gitignore set (`plans/`, `iterations/`, `sdd/`, `status.json`, …), `archived/residuals/`, `status.json` |
-| `spec-register` | Register `plan_id` in `status.json.plans[]` + spec stub if applicable |
+| `harness-init` | Init `{HARNESS_DIR}`, `{PLAN_DIR}`, process-artifact gitignore set (`plans/`, `iterations/`, `sdd/`, `status.json`, `workflows/`, `projects/`, …), `status.json` (v2 template) |
+| `spec-register` | Register the root `workflows[]` entry + snapshot plan row (`{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]`) + spec stub if applicable |
 | `mirror-plan` | Write SSOT main plan under `{PLAN_DIR}/` |
 
-Each **implement todo**: per–task-ID **git commit** on Working branch → SSOT `- [x]` → optional `status.json` sync → `git log -1 --oneline` evidence.
+Each **implement todo**: per–task-ID **git commit** on Working branch → SSOT `- [x]` → optional snapshot sync → `git log -1 --oneline` evidence.
 
-Before **SwitchMode → Agent**: mirror plan exists; `status.json` lists `plan_id`; bootstrap todos done. **Never** use only the Cursor plan URI as **Plan Path**.
+Before **SwitchMode → Agent**: mirror plan exists; snapshot lists `plan_id` + root `workflows[]` entry; bootstrap todos done. **Never** use only the Cursor plan URI as **Plan Path**.
 
 After **Build**: treat the run as plan resume, not `/pm` replay. Reload `mstar-harness-core` + this Cursor reference, resume Morning Star plans as `project-manager` orchestration, and dispatch implementation through Task unless the user explicitly overrides the harness.
 

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

@@ -295,11 +295,12 @@ The plugin wires the engine gates on dsh seams (all in-process):
 
 **Enforcement semantics**: warn-only by default. `Enforcement: hard` —
 resolved from the plugin Config (`enforcement: hard`), the Assignment header
-flag, or the iteration compass frontmatter — escalates dispatch violations to
+flag, the repo `.mstarc` `[config] enforcement`, or the iteration compass
+frontmatter — escalates dispatch violations to
 a real veto; status/skill-lint writes are never hard-vetoed because the intent
 waterfall is content-blind (an already-invalid document is allowed as a
-repair escape). Config `soft` is the only local rollback. Hard gates are never
-a global default.
+repair escape). Config / `.mstarc` `soft` are the local rollbacks. Hard gates
+are never a global default.
 
 Every composed agent step carries ONE **`<mstar_engine_status>`** catalog
 message: the watermark (unified mstar version, harness dir, enforcement),
@@ -458,14 +459,16 @@ The dsh web client resolves slash commands against a client-side lexicon driven
 
 ## Harness dir and environment
 
-- `{HARNESS_DIR}` resolves via the engine `resolveHarnessDir` (`.mstar/` →
-  `.agents/` → `.plans/`/`plans/`), with the plugin Config `harnessDir`
+- `{HARNESS_DIR}` resolves via the engine `resolveHarnessDir` (`.mstarc`
+  `[config] harness_dir` → `.mstar/` → `.agents/` → `.plans/`/`plans/`),
+  with the plugin Config `harnessDir`
   override winning. The probe starts from the SESSION workspace root (the
   session cwd — **never the dsh launch/process cwd**) and **STOPS there** — it
   never walks above the session workspace, so the watermark and gates follow
   the workspace the session actually works in. Repos using a
-  non-standard harness root (e.g. `.harness/`) MUST set Config `harnessDir`
-  (absolute path) — the gates are inert without a resolvable harness dir.
+  non-standard harness root MUST set Config `harnessDir`
+  (absolute path) or declare it in a repo `.mstarc` — the gates are inert
+  without a resolvable harness dir.
 - The dispatch gate needs the dispatching agent's own role for the
   anti-recursion precheck: declare it via Config **`dispatchBinding`** (dsh
   exposes no per-agent role on the tool-execution context). Under hard

package/harness-skills/mstar-host/references/kimi-plan-mode-bridge.md

@@ -15,13 +15,13 @@ Kimi **Plan mode** (`EnterPlanMode` / `ExitPlanMode`, `/plan`, or `Shift-Tab`) u
 
 | Step | Kimi session | Harness SSOT |
 |------|--------------|--------------|
-| Enter | `EnterPlanMode` or `/plan on` — explore read-only | Ensure `{HARNESS_DIR}` exists; register `plan_id` in `status.json` when known |
+| Enter | `EnterPlanMode` or `/plan on` — explore read-only | Ensure `{HARNESS_DIR}` exists; register the root `workflows[]` entry + snapshot plan row when known |
 | Design | Edit Kimi plan file with `Write` / `Edit` (when Plan mode allows writes) | Mirror main plan to `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes |
 | Clarify | `AskUserQuestion` for blocking ambiguity only | Record decisions in plan / spec when durable |
-| Exit | `ExitPlanMode` — user approves plan to implement | SSOT plan locked; `status.json` row updated |
+| Exit | `ExitPlanMode` — user approves plan to implement | SSOT plan locked; snapshot plan row updated |
 | Implement | Agent mode resumes | Per-task commits, Working branch, dispatch per `mstar-dispatch-gates` |
 
-`TodoList` and Kimi UI todos are **session progress only** — sync meaningful state to SSOT plan checkboxes and `status.json` when coordination requires it.
+`TodoList` and Kimi UI todos are **session progress only** — sync meaningful state to SSOT plan checkboxes and the workflow snapshot (`{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]`) when coordination requires it.
 
 ## ExitPlanMode gate
 

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

@@ -35,7 +35,7 @@ Use skill names in prompts and references. Avoid absolute local paths unless mai
 | **AgentSwarm** | Parallel batch when **same** role/profile and prompts differ only by task slice; prefer **N× Agent** when roles differ |
 | **AskUserQuestion** | Structured clarify (1–4 questions, 2–4 options each); prefer over free-form when choices are known |
 | **EnterPlanMode** / **ExitPlanMode** | Plan mode entry/approval → **`kimi-plan-mode-bridge.md`** |
-| **TodoList** | Session UX only; mirror to SSOT plan / `status.json` when durable |
+| **TodoList** | Session UX only; mirror to SSOT plan / workflow snapshot (`{WORKFLOW_DIR}/<id>/snapshot.json`) when durable |
 | **Bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
 | **Read** / **ReadMediaFile** | File reads |
 | **Glob** / **Grep** | Search (prefer over shell find/grep) |

package/harness-skills/mstar-host/references/omp-plan-mode-bridge.md

@@ -9,10 +9,10 @@ omp session plans, composer todos, and plan-mode UI text are **session UX only**
 | Artifact | SSOT |
 |----------|------|
 | Main plan | `{PLAN_DIR}/<plan-id>-<name>.md` |
-| Plan registry | `{HARNESS_DIR}/status.json` |
+| Plan registry | `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows) |
 | Iteration compass | `{ITERATION_DIR}/…` when in formal iteration |
 
-Bootstrap before treating a plan as ready for Execute (read `mstar-plan-conventions` + `mstar-plan-artifacts`; ensure `{HARNESS_DIR}` / `{PLAN_DIR}` exist with process-artifact gitignore entries; mirror the active omp plan into the SSOT main plan path; register `plan_id` in `status.json.plans[]` when required by Prepare gates) → core.
+Bootstrap before treating a plan as ready for Execute (read `mstar-plan-conventions` + `mstar-plan-artifacts`; ensure `{HARNESS_DIR}` / `{PLAN_DIR}` exist with process-artifact gitignore entries; mirror the active omp plan into the SSOT main plan path; register the root `workflows[]` entry + snapshot plan row when required by Prepare gates) → core.
 
 **Never** use only the omp session plan / UI todo list as **Plan Path**.
 

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

@@ -211,10 +211,10 @@ Cannot emit required **N** → **`Blocked`**.
 ## In-process engine binding (omp ≥ 17.2.11)
 
 - **Surfaces** (repo root = plugin root): `hooks/pre/mstar-gates.ts` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}/index.ts` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`).
-- **Enforcement semantics**: block ONLY under `Enforcement: hard`. The status gate reads the harness compass frontmatter (`enforcement: hard`, active/locked iterations only); the dispatch gate reads each Assignment's own header flag (`assignmentHeaderRegion` — a body example never hardens). Soft / no flag → silent pass. Rollback = unset the flag. Never global.
+|- **Enforcement semantics**: block ONLY under `Enforcement: hard`. The status gate reads the repo `.mstarc` `[config] enforcement`, else the harness compass frontmatter (`enforcement: hard`, active/locked iterations only); the dispatch gate reads each Assignment's own header flag (`assignmentHeaderRegion` — a body example never hardens). Soft / no flag → silent pass. Rollback = unset the flag (or `.mstarc` `soft`). Never global.
 - **Engine dependency**: the adapters import the published engine package (root `package.json` `dependencies` entry). omp git/npm plugin installs run `bun install <spec>` in the plugins tree → declared deps installed; a bare `-l` / `omp plugin link` symlink install without `node_modules` cannot resolve the modules.
 - **Graceful degradation (explicit)**: module load failure → `mstar_*` tools skipped, hook absent (no blocking), `commands/*.md` shell-out fallback intact. Caveat: a partial failure is SILENT — no in-band signal that gates are off; verify with `omp -p '/extensions'`.
-- **`MSTAR_HARNESS_DIR` override**: the hook and tools discover `{HARNESS_DIR}` via `resolveHarnessDir`, which probes only `.mstar/` → `.agents/` → `.plans/`/`plans/` roots. Repos using a non-standard harness root (e.g. this plugin repo's own `.harness/`) MUST export `MSTAR_HARNESS_DIR` (absolute path) in the omp session env — without it the status gate does not cover those roots and tools like `mstar_path_resolve` / `mstar_lease_verify` error out (parity with the opencode binding).
+|- **`MSTAR_HARNESS_DIR` override / `.mstarc`**: the hook and tools discover `{HARNESS_DIR}` via `resolveHarnessDir` — a repo `.mstarc` `[config] harness_dir` (gitignored local config) first, then the probe `.mstar/` → `.agents/` → `.plans/`/`plans/`. Repos using a non-standard harness root can declare it in `.mstarc` or MUST export `MSTAR_HARNESS_DIR` (absolute path) in the omp session env — without either the status gate does not cover those roots and tools like `mstar_path_resolve` / `mstar_lease_verify` error out (parity with the opencode binding).
 - **Edit-path limitation**: the status gate validates the on-disk file for `edit` events (pre-edit state) — a corrupting edit is caught by the next write or `mstar_status_validate` (known v1 limitation, parity with opencode).
 - **Engine version compatibility**: the hook and tools degrade gracefully until the engine release exporting both `composeDispatchGate` and `parseCompassFrontmatter` (published 2.0.2 predates both). Missing exports never fail module load: the hook's dispatch gate needs `composeDispatchGate` — on older engines Gate 2 (task dispatch) is skipped with a one-time warning while Gate 1 (status) stays active — and `mstar_dispatch_validate` / `mstar_iteration_gate` report an explicit upgrade error instead of loading (no silent absence; CLI fallbacks: `mstar dispatch validate`, `mstar iteration gate`).
 - **Reload**: edits are picked up by a new session (`?mtime` cache-buster); in-session `/reload-plugins` (omp ≥ 17.2.11) applies them without a new session.

package/harness-skills/mstar-host/references/zcode-plan-mode-bridge.md

@@ -15,13 +15,13 @@ ZCode **Plan mode** (`EnterPlanMode` / `ExitPlanMode`) uses read-only exploratio
 
 | Step | ZCode session | Harness SSOT |
 |------|---------------|--------------|
-| Enter | `EnterPlanMode` — explore read-only | Ensure `{HARNESS_DIR}` exists; register `plan_id` in `status.json` when known |
+| Enter | `EnterPlanMode` — explore read-only | Ensure `{HARNESS_DIR}` exists; register the root `workflows[]` entry + snapshot plan row when known |
 | Design | Draft plan content; surface via `ExitPlanMode` plan text | Mirror main plan to `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes |
 | Clarify | `AskUserQuestion` for blocking ambiguity only | Record decisions in plan / spec when durable |
-| Exit | `ExitPlanMode` — user approves plan to implement | SSOT plan locked; `status.json` row updated |
+| Exit | `ExitPlanMode` — user approves plan to implement | SSOT plan locked; snapshot plan row updated |
 | Implement | Agent mode resumes | Per-task commits, Working branch, dispatch per `mstar-dispatch-gates` |
 
-`TodoWrite` and ZCode UI todos are **session progress only** — sync meaningful state to SSOT plan checkboxes and `status.json` when coordination requires it.
+`TodoWrite` and ZCode UI todos are **session progress only** — sync meaningful state to SSOT plan checkboxes and the workflow snapshot (`{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]`) when coordination requires it.
 
 ## ExitPlanMode gate
 

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

@@ -34,7 +34,7 @@ Use skill names in prompts and references. Avoid absolute local paths unless mai
 | **Agent** | Primary dispatch — delegate one subagent task (`subagent_type`: built-in profiles such as `general-purpose` / `Explore`) |
 | **AskUserQuestion** | Structured clarify (1–4 questions, 2–4 options each); prefer over free-form when choices are known |
 | **EnterPlanMode** / **ExitPlanMode** | Plan mode entry/approval → **`zcode-plan-mode-bridge.md`** |
-| **TodoWrite** | Session UX only; mirror to SSOT plan / `status.json` when durable |
+| **TodoWrite** | Session UX only; mirror to SSOT plan / workflow snapshot (`{WORKFLOW_DIR}/<id>/snapshot.json`) when durable |
 | **Bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
 | **Read** | File reads (text + images) |
 | **Edit** / **Write** | Edits |