@mstar-harness/dsh 2.4.1 → 3.0.1

package/harness-skills/mstar-engine-legacy/references/lease-protocol.md

@@ -0,0 +1,92 @@
+# Lease claim protocol (full prose, archived)
+
+> Engine-absent fallback: the full lease protocol prose displaced from `mstar-iteration` / `mstar-plan-artifacts` when engine validators (`validateExecutionLease` / `validateIntegrationMergeLease` / CLI `mstar lease verify --workflow <id>`) took over the same contract. Engine-present hosts read the runtime skills' engine-check pointers instead.
+
+## When it applies
+
+**Iteration Phase 2 only** (after control-worktree entry, or primary checkout when `Worktree mode: waived`). Defaults are **hard** unless the current turn explicitly waives via Assignment `Worktree mode: waived` (or equivalent user instruction). `Plan parallelism: serial` is **not** a waiver — it only forces serial cross-plan **implement** scheduling while control worktree + leases remain required. Phase 1 Review & Edit may stay on the primary checkout; the control-worktree gate starts at **Phase 2 entry**. **`Worktree mode: waived` does not waive the cross-plan parallel safety gate**.
+
+## Coordination SSOT and lock discipline
+
+Lease mutations happen on the **control copy** of the coordination file — the v2 workflow snapshot `{WORKFLOW_DIR}/<id>/snapshot.json` (v1: `{HARNESS_DIR}/status.json`, migrated). This is cooperative, not a distributed lock service — non-cooperating processes are out of scope.
+
+**Same-host exclusive write lock** — all control-path lease mutations (claim, release, transfer, plan-status transitions that touch the lease, merge-lease claim/release) MUST run inside a same-host exclusive write lock for the full **read-check-replace-verify** sequence. Hold from first read through post-write verify; release on all exit paths.
+
+- Engine writers acquire the lock automatically: `writeWorkflowSnapshot` / `registerWorkflow` atomic-`mkdir` the lockdir at `<status-file dir>/.status-write.lockdir/` — for the snapshot the lockdir lands **inside `workflows/<id>/`** (next to `snapshot.json`).
+- Manual fallback when no engine writer exists: atomic `mkdir` on `{WORKFLOW_DIR}/<id>/.status-write.lockdir/` — success acquires; existing dir → **Blocked** (another writer holds the lock); `rmdir` the directory only after successful verify or explicit rollback. The dsh notes-ledger writer uses the same lockdir pattern (`{WORKFLOW_DIR}/<id>/.ledger-write.lockdir`). Do **not** invent a distributed CAS CLI.
+
+```bash
+CONTROL_ROOT="<snapshot top-level control_worktree_path>"
+HARNESS=".mstar"   # or resolved {HARNESS_DIR}
+WORKFLOW_ID="<plan-or-iteration-id>"
+SNAPSHOT="$CONTROL_ROOT/$HARNESS/workflows/$WORKFLOW_ID/snapshot.json"
+LOCKDIR="$CONTROL_ROOT/$HARNESS/workflows/$WORKFLOW_ID/.status-write.lockdir"
+(
+  mkdir "$LOCKDIR" || exit 1
+  trap 'rmdir "$LOCKDIR"' EXIT
+  # read → mutate → temp file + atomic replace → re-read verify
+)
+```
+
+**Pre-dispatch re-verify:** immediately before **any** writable implement dispatch, re-read the coordination file and confirm this session still passes verify-held-lease (`holder`, `worktree_path`, `working_branch` match Assignment). Mismatch or absent lease ⇒ **STOP** — do not dispatch.
+
+## Claim-before-`InProgress` (execution lease)
+
+A Phase 2 session **MUST** claim before moving a plan from `Todo`/`Blocked` to `InProgress` and before any writable dispatch for that plan:
+
+1. Re-read the coordination copy; locate exactly one plan row (`id` read compatibility).
+2. **Resume (not steal):** if `execution_lease` exists and `holder` **equals this session** → verify-held: confirm `worktree_path` and `working_branch` match the Assignment; continue (not Blocked, not a new claim).
+3. **Blocked:** if `execution_lease` exists and `holder` **differs** → stop. No timestamp, TTL, or inactivity makes it stealable.
+4. **Orphan:** if `status` is `InProgress` but `execution_lease` is absent → **STOP** (see Orphan recovery). Do not writable-dispatch or invent a lease.
+5. Create or verify the dedicated feature worktree and branch (`worktree_path` ≠ `control_worktree_path`).
+6. Acquire the same-host write lock (above); re-read the coordination file; if row/status/lease changed, restart from step 1.
+7. In **one complete-file update** (under lock), set `status: "InProgress"` and write the full `execution_lease` object. Use a temp file in the same directory + atomic replace; never expose partial JSON.
+8. Re-read the stored row; verify `holder`, `worktree_path`, `working_branch` exactly match the attempted claim. Writable dispatch is forbidden until verification succeeds.
+
+V1: **manual release only** — omit `expires_at`; readers **MUST NOT** treat unknown/draft `expires_at` as authority to steal or release.
+
+## Hold, release, and override
+
+- Lease remains active across `InProgress` and `InReview` (including review fix rounds) unless deliberately released or transferred.
+- **Release:** re-read coordination file; stored `holder` must match this session (mismatch ⇒ **Blocked**, not permission to delete). Delete `execution_lease` in the same complete-file update — never `null`.
+- Voluntary abandonment: may set `status: "Blocked"` and delete the lease in one update.
+- **Done authority** deletes `execution_lease` in the **same** complete-file update as `status: "Done"` — **only after** successful integration merge when the lease gate is not waived. After QC/QA pass the plan stays **`InReview`** with lease retained until merge succeeds.
+- Temporary blockage may retain the lease when the same holder remains responsible and the plan record explains the next action.
+- **Override (only exception to no-steal):** explicit **user instruction in the current turn** may remove or replace another holder's lease. Append an audit note (prior holder, new holder/release, user authorized) to `plans[].notes` / `notes.jsonl`. Agents **MUST NOT** infer override from age, inactivity, `Blocked` status, or a failed session.
+- Cooperative handoff: current holder explicitly agrees; receiving worktree/branch verified; one complete-file update — otherwise old holder releases and new holder follows normal claim.
+
+## Integration merge protocol
+
+Feature implementation may run in parallel across plan IDs **only when** the cross-plan parallel hard gate is satisfied (same-host lock on the coordination file, default `Plan parallelism: serial`, or current-turn `Cross-host lease race: accepted` + audit — **not** by `Worktree mode: waived` alone); when the lease gate is active, each plan also needs a verified `execution_lease` and distinct feature worktree. Mutations of `spec_integration_branch` are **serial**. Plan status after QC/QA is `InReview` with `execution_lease` retained until merge succeeds (when lease gate active); `Done` + lease deletion happen **after** the integration merge commit is recorded.
+
+1. From `control_worktree_path`: clean working tree; checked-out branch = resolved `spec_integration_branch`.
+2. Re-read the coordination file under the same-process write lock. If `integration_merge_lease` exists:
+   - **Resume (not steal):** `holder` equals this session → verify `plan_id`, `source_branch`, `target_branch` match the intended merge; confirm control worktree state; continue (not Blocked).
+   - **Blocked:** `holder` differs → stop. No timestamp, TTL, or inactivity makes it stealable.
+3. If unclaimed, claim the merge lease with the same read-check-replace-verify discipline as execution claims. `source_branch`/`plan_id` must match the feature; `target_branch` must match `spec_integration_branch`.
+4. Only the stored merge-lease holder runs integration from `control_worktree_path`.
+5. On success: record merge commit/evidence; **delete** `integration_merge_lease`; in the **same** locked update set plan `status: "Done"` and **delete** `execution_lease`.
+6. On conflict/failure: retain both leases; plan stays `InReview` — do not set `Done`. Release the merge lease only after the control worktree is clean and in a known state.
+
+Execution and merge leases may coexist; the merge lease does not grant execution ownership for the source plan.
+
+## Orphan recovery (`InProgress` without `execution_lease`)
+
+Runtime skills that detect this state **STOP** and defer recovery — they must not silently add a lease or writable-dispatch. **Immediate gate:** no writable dispatch until recovery completes and a verified `execution_lease` exists (or the plan returns to a non-active status). **Resolver:** `@project-manager` (or explicit human/PM ownership resolution after race or corruption).
+
+| Path | When | Actions |
+| ---- | ---- | ------- |
+| **Reset to `Todo`** | Work abandoned, unknown owner, or safe to restart claim | One complete-file update under write lock: `status: "Todo"`; ensure `execution_lease` absent; append audit note (timestamp, reason, actor). |
+| **Recover with claim (same holder)** | Legitimate in-progress work; worktree/branch verified on disk; **this session's stable `holder`** matches the prior owner | Unattended recovery permitted only for the **same** stable `holder`. Follow claim from step 5 under write lock; append audit note (orphan recovery, same holder, paths verified). |
+| **Recover with claim (different holder)** | New session must take over live work | **Blocked** for unattended recovery. Requires verified quiescence of the prior writer (no live writable work on the feature branch/worktree) **and** explicit cooperative handoff from the prior holder, **or** current-turn user override + audit note. Then normal claim under write lock. |
+| **Escalate / `Blocked`** | Ambiguous ownership, conflicting worktrees, or partial/corrupt state | Set `status: "Blocked"` with `metadata.blocked_reason`; do not writable-dispatch until human/PM resolves. Restore coherent state from the latest complete version if needed. |
+
+After any recovery path, the next session must pass verify-held before writable dispatch.
+
+## Lease prohibitions (SSOT)
+
+- **MUST NOT** steal or overwrite an active `execution_lease` or `integration_merge_lease` (no TTL, age, or inactivity authority).
+- **MUST NOT** writable-dispatch without a verified `execution_lease` for that plan (resume counts only when same `holder` passes verify-held).
+- **MUST NOT** write `null` or tombstone objects for lease keys — **delete** the key on release.
+- **PM NEVER** steals an active lease without explicit current-turn user override + audit note (full list → `mstar-roles/references/project-manager.md`).
+- Writers **MUST preserve** unrelated plan rows, root metadata, and residual data on every lease mutation.

package/harness-skills/mstar-engine-legacy/references/qc-seat-n-restatements.md

@@ -0,0 +1,57 @@
+# QC seat N restatements (per-host, archived)
+
+> Engine-absent fallback: the per-host N=3/N=1 restatements that runtime host references (`mstar-host/references/*`) consolidate. Engine-present hosts read `mstar-host` → `parallel-dispatch.md` + `executionModeToN` instead; this file is the consolidated full restatement text.
+
+## Canonical N mapping (any host)
+
+| `Execution mode` | QC seats | N |
+| --- | --- | --- |
+| `sdd` (multi-task plan, single plan, or iteration Phase 2) | `qc-specialist` / `qc-specialist-2` / `qc-specialist-3` in **one** dispatch turn | **N=3** |
+| `inline` (hotfix) / explicit `QC mode: single` override | `qc-specialist` ×1 | **N=1** |
+| Targeted re-review (`QC re-review: targeted — reviewers: <ids>`) | the listed seats only | N = listed count (1–3) |
+
+Rules that never change: tri seats dispatch **in one message** with a branch review-package path (`{SDD_DIR}/review/qc1.md`…`qc3.md` + `qc-consolidated.md`); post-dispatch verify three distinct agent ids; `Execution mode: inline` with `QC mode: full tri-review` still launches the three seats; SDD implement/reviewer dispatches stay **serial** (never parallel implementers for the same plan); each invoke must carry the role-binding field set to `Execute as` even at N=1.
+
+## Per-host restatements (full text)
+
+### omp (`task` tool, `agent` field)
+
+- **`Execution mode: sdd`**: **N=3** task entries — prefer `agent: "qc-specialist"`, `"qc-specialist-2"`, `"qc-specialist-3"` when listed; each body still **Act as** the respective QC role + QC skill load. If a seat is missing from the live schema, fall back per C5 (generic + C5b) for that seat only. N rules → `parallel-dispatch.md`.
+- **`inline`**: **N=1** per `parallel-dispatch.md`.
+- Cannot emit required **N** → **`Blocked`**.
+- SDD implement: one implementer `task` entry per task id with `agent` matching the implementer role when listed; task reviewer = new entry with `agent: "code-reviewer"` (omp L2 review; not qc-specialist*) or `agent: "reviewer"`/`"task"` fallback + C5b; serial rule → `parallel-dispatch.md`.
+
+### opencode (`task` tool, `subagent` field)
+
+- Parallel batch **N** = **N task tool calls** in one assistant message when the host allows (`parallel-dispatch.md`); 1 Assignment ⇒ 1 invoke.
+- Prepare phase serial roles (`explore → product-manager → architect`) still require a real task-tool call per handoff (**N=1** per dispatch turn) — Assignment Markdown alone does not open subagent sessions.
+- SDD task reviewer: new task tool call with `subagent: "code-reviewer"` (OpenCode L2; not qc-specialist*), no sticky resume for reviewers.
+
+### cursor (Task tool, `subagent_type` field)
+
+- **`Execution mode: sdd`**: **N=3** Tasks (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) + branch review-package path (N rules → `parallel-dispatch.md`).
+- **`inline`**: **N=1** per `parallel-dispatch.md`.
+- SDD implement/reviewer: serial — implementer Task per task id with `subagent_type` matching the implementer role when listed; task reviewer = new Task with `subagent_type: "code-reviewer"` (Cursor L2; not qc-specialist*) when listed, else generic fallback per C5 — no `resume` for reviewers.
+
+### codex (custom-agent / multi-agent tools only)
+
+- QC: N rules → `parallel-dispatch.md` (**`Execution mode: sdd`** → N=3; **`inline`** → N=1) when a callable invoke tool exists. Cannot emit required **N** → **`Blocked`**.
+- If no invoke tool is present when dispatch is required → **`Blocked`** — report missing invoke capability; do not substitute single-session role execution in the PM thread unless the user explicitly overrides harness dispatch this turn.
+
+### kimi (`Agent` tool, `subagent_type` ∈ {`coder`,`explore`,`plan`})
+
+- **`Execution mode: sdd`**: **N=3** `Agent` calls (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) — each prompt **Act as** the respective QC role, all `subagent_type: "coder"` (N rules → `parallel-dispatch.md`).
+- **`inline`**: **N=1** per `parallel-dispatch.md`. Cannot emit required **N** → **`Blocked`**.
+- SDD implement: one implementer `Agent` per task id; task reviewer = new `Agent` with **Act as `code-reviewer`** (Kimi L2; not qc-specialist*), generic fallback `subagent_type: "coder"` per C5 — no sticky resume unless the host adds it later.
+
+### zcode (`Agent` tool, `subagent_type` ∈ {`general-purpose`, …})
+
+- **`Execution mode: sdd`**: **N=3** `Agent` calls (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) — each prompt **Act as** the respective QC role, all `subagent_type: "general-purpose"` (N rules → `parallel-dispatch.md`).
+- **`inline`**: **N=1** per `parallel-dispatch.md`. Cannot emit required **N** → **`Blocked`**.
+- SDD implement: one implementer `Agent` per task id; task reviewer = new `Agent` with **Act as `code-reviewer`** (ZCode L2; not qc-specialist*), generic fallback `subagent_type: "general-purpose"` per C5 — no sticky resume unless the host adds it later.
+
+### dsh (`subagent` dispatches)
+
+- **`Execution mode: sdd`**: **N=3** `subagent` dispatches — one per QC seat (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`), each body **Act as** the respective QC role + QC skill load. **MUST dispatch all three with `run_in_background: true` in one message** → the seats run CONCURRENTLY (background children; wall ≈ single seat); foreground (no `run_in_background`) runs serially (wall ≈ 3× single seat) and does NOT count as parallel tri. Cannot emit required **N** → **`Blocked`**.
+- **`inline`**: **N=1**.
+- SDD implement: one implementer `subagent` dispatch per task id; task reviewer = a separate dispatch (SDD review role) — no sticky resume unless the host's continuable-subagent id is available and recorded.

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