@mstar-harness/opencode 2.4.0 → 3.0.1

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

@@ -1,21 +1,55 @@
-# `{HARNESS_DIR}/status.json` and Residual Findings (Morning Star)
+# `{HARNESS_DIR}/status.json` (v2), Workflow Snapshots and Project Registers (Morning Star)
 
 > **Load order (same as other `mstar-*` skills):** Before changing SSOT / residual fields using this reference, Read **`mstar-harness-core`** (SKILL.md; same-repo branches and worktrees → **`mstar-branch-worktree`**). On conflict, **`mstar-harness-core` wins**; skill index in that SKILL.md.
 
-`status.json` lives at **`{HARNESS_DIR}/status.json`**. It is the **single source of truth (SSOT)** for **`plans[]` row status** and **open residual findings**.  
-Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md** (“`status.json` and open residual (summary)”); this file covers **fields, severity, lifecycle, archive, and `jq` examples**.  
-**Closed** residuals should not accumulate here long-term; authoritative archive → **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`** (see “Residual findings lifecycle”).
+v3 布局把 v1 的「单文件 `status.json`（根 `plans[]` + 根级 `residual_findings` + `metadata`）」拆成三层。**只使用 v2 地址；v1 地址（根 `plans[]` / 根级 `residual_findings` / `archived/residuals/`）由 `mstar migrate` 一次性迁移，不再读写**。v1 字段形状/历史全文（v1 行表、v1 `metadata` 表、jq/flock 读路径示例）→ **`mstar-engine-legacy`** `references/status-field-history.md`（engine-absent 历史 + fallback）；本文件只保留 v2 地址与一次性 legacy 只读警告。
 
-**Why this matters:** Within a working copy, the open list in `status.json` and `archived/residuals/` are the **local session SSOT** for risk and decisions. Non-blocking conclusions that stay only in chat or a gitignored review bundle **without local SSOT update** cannot be inherited reliably in that session; `Done` drifts from visible known debt. **`@project-manager`** should register trackable open items soon after review closure; close/archive after verification per **`QA gate`** (`qa-engineer` when `mandatory`, else PM acceptance checklist).
+- **根 `{HARNESS_DIR}/status.json`（v2）** — 活跃生命周期登记：`{ "version": 2, "updated_at", "workflows": [...] }`。只登记 **active**（`running` / `paused`）lifecycle；terminal 时先写 snapshot 再从根列表移除（removal-at-terminal）。由 engine `validateStatus`（v2）/ `registerWorkflow` / `unregisterWorkflow` 读写。
+- **`{WORKFLOW_DIR}/<id>/snapshot.json`** — 每 lifecycle 的运行态快照（`schema_version: 1`）：**`plans[]` 行（legacy PlanRow 形状逐字保留）**、per-row **`execution_lease`**、顶层 **`integration_merge_lease`** / **`execution_policy`** / **`branch` anchors** / **`control_worktree_path`** / `compass_ref`。`<id>` = plan id 或 iteration id。
+- **`{PROJECT_DIR}/<id>/roadmap.md` + `residuals.json`** — 项目层：roadmap frontmatter（machine-checkable）+ residual **register**（`entries[<plan-id>]` 数组；severity 枚举与 lifecycle 语义**逐字保留**）。无项目的流程回落到 `_default` 项目。
 
-**Cross-clone handoff** (default git policy): tracked `{HARNESS_DIR}/AGENTS.md`, `{KNOWLEDGE_DIR}/**`, `{SPECS_DIR}/**`, and root `CONCEPTS.md` / `STRATEGY.md` when used. Residuals that must survive clone must be **promoted** (compound) or written into those tracked results — do not treat `status.json` / `plans/` as the default clone handoff surface.
+`status.json`（根）、workflow snapshot 与 project register 都是 **SSOT**：plan 行状态与 lease 在 snapshot，open residual 在 register。  
+Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md**（"`status.json`, workflow snapshots, and open residual (summary)"）；本文件 covers **fields, severity, lifecycle, v2 地址与 engine-check 命令**。  
+**Closed** residuals close **in place** in the register（`lifecycle` / `closed_at` / `closure_note`）— v1 的 `archived/residuals/<plan-id>.json` 归档路径与 `archive-residuals` 已移除（`mstar status archive-residuals` 在 v3 仅报错并指向 register 状态变更）。
+
+**Why this matters:** Within a working copy, the workflow snapshot and project registers are the **local session SSOT** for risk and decisions. Non-blocking conclusions that stay only in chat or a gitignored review bundle **without local SSOT update** cannot be inherited reliably in that session; `Done` drifts from visible known debt. **`@project-manager`** should register trackable open items soon after review closure; close after verification per **`QA gate`** (`qa-engineer` when `mandatory`, else PM acceptance checklist).
+
+**Cross-clone handoff** (default git policy): tracked `{HARNESS_DIR}/AGENTS.md`, `{KNOWLEDGE_DIR}/**`, `{SPECS_DIR}/**`, and root `CONCEPTS.md` / `STRATEGY.md` when used. Residuals that must survive clone must be **promoted** (compound) or written into those tracked results — do not treat `status.json` / `workflows/` / `projects/` / `plans/` as the default clone handoff surface.
 
 ## Basic structure
 
+**Root `{HARNESS_DIR}/status.json` (v2)** — active lifecycle register:
+
+```json
+{
+  "version": 2,
+  "updated_at": "YYYY-MM-DD",
+  "workflows": [
+    {
+      "id": "<plan-id-or-iteration-id>",
+      "type": "plan | iteration",
+      "started_at": "YYYY-MM-DD",
+      "dir": "workflows/<id>"
+    }
+  ]
+}
+```
+
+- `dir` is **harness-relative** (`workflows/<id>`), never absolute.
+- Terminal writers unregister AFTER the snapshot write (removal-at-terminal): terminal snapshots are **not** listed in the root.
+
+**`workflows/<id>/snapshot.json`** — lifecycle snapshot (`schema_version: 1`; engine `validateWorkflowSnapshot` / `writeWorkflowSnapshot`):
+
 ```json
 {
-  "version": 1,
+  "schema_version": 1,
+  "id": "<plan-id-or-iteration-id>",
+  "type": "plan | iteration",
+  "status": "running | paused | completed | failed | stopped",
+  "started_at": "YYYY-MM-DD",
+  "ended_at": null,
   "updated_at": "YYYY-MM-DD",
+  "phase": "phase-2-execute",
   "plans": [
     {
       "id": "plan-id",
@@ -29,11 +63,34 @@ Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md**
       "created_at": "YYYY-MM-DD",
       "updated_at": "YYYY-MM-DD",
       "done_at": null,
-      "notes": "",
-      "metadata": {}
+      "notes": [],
+      "metadata": {},
+      "execution_lease": {}
     }
   ],
-  "residual_findings": {
+  "execution_policy": {
+    "plan_parallelism": "serial",
+    "worktree_mode": "",
+    "push_policy": ""
+  },
+  "integration_merge_lease": {},
+  "branch": { "base": "", "integration": "", "target": "" },
+  "control_worktree_path": "/abs/repo/root",
+  "legacy_metadata": {},
+  "compass_ref": "iterations/<iteration-id>/delivery-compass.md"
+}
+```
+
+- `plans[]` rows are the **legacy PlanRow shape verbatim** (unknown row fields preserved, never re-bucketed). Per-row `execution_lease` stays on the row; `integration_merge_lease` is **top-level** (the v1 root-`metadata` home is gone).
+- Terminal statuses (`completed` / `failed` / `stopped`) require `ended_at` and no dangling leases.
+- `execution_policy` keys are copied from v1 root `metadata` at migrate; values are accepted-but-opaque this iteration (no semantic gate).
+- `notes`: a plan row's `notes` array is the **legacy verbatim copy** preserved at migrate; the **runtime ledger is `notes.jsonl`** in the workflow dir (see `workflows/<id>/notes.jsonl` below). New notes append to the ledger only — never dual-write the row `notes`.
+
+**`projects/<id>/residuals.json`** — project register (entries keyed by plan id, each an ARRAY):
+
+```json
+{
+  "entries": {
     "plan-id": [
       {
         "id": "R1",
@@ -45,15 +102,42 @@ Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md**
         "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"
+        "detail_doc": "{PLAN_DIR}/residuals/plan-id/R1-short-label.md",
+        "source_plan": "plan-id",
+        "registered_at": "YYYY-MM-DD",
+        "lifecycle_id": "<workflow id when owned by an iteration>"
       }
     ]
-  },
-  "metadata": {}
+  }
 }
 ```
 
-**Empty-repo templates:** **`templates/status.empty.json`**; optional **`templates/notes.empty.json`** → `{HARNESS_DIR}/notes.json`. See **`templates/README.md`**.
+- `entries[<plan-id>]` values are **arrays** — v1 `residual_findings[plan-id]` multi-finding semantics preserved verbatim (a plan may hold 2+ open residuals).
+- Register entries = the v1 residual entry **verbatim** + provenance: `source_plan` (must equal its entries key), `registered_at` (`YYYY-MM-DD`), optional `lifecycle_id` (owning workflow id when an iteration owns the plan).
+- Project-less flows use the fallback **`_default`** project (`projects/_default/`).
+- Register document validation delegates verbatim to `validateResidual` (severity enum + lifecycle states preserved at the new address).
+
+**`projects/<id>/roadmap.md`** — roadmap frontmatter (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
+...
+```
+
+Body conventions (`## Direction` + goal items as `- [ ]` / `- [x]` markdown task-list items) are **warnings only** — never a hard gate.
+
+**Empty-repo template:** **`templates/status.empty.json`** — the v2 shape (`version: 2`, `updated_at`, `workflows: []`). See **`templates/README.md`**.
 
 **Closed entries** add: `lifecycle`, `closed_at`, `closure_note`; optional `closure_evidence`, `superseded_by`. See “Residual findings lifecycle”.
 
@@ -61,7 +145,7 @@ Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md**
 
 ## Fail-loud handoff contract
 
-Findings must pass engine validation **before** registration into `residual_findings`: `validateResidual(entry)` per entry, `validateStatus(doc)` for the whole file (`mstar status validate` / engine import). Malformed entries — **non-object**, missing any of the nine required fields (`id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`, `target`, `tracking` — mirroring engine `RESIDUAL_REQUIRED_FIELDS` in `packages/engine/src/status.ts`), or **severity** outside the enum — are **rejected** (`ok:false` + violation): fix and rewrite — never silent pass-through, downgrade-write, or “write then patch”.
+Findings must pass engine validation **before** registration into the project register: `validateResidual(entry)` per entry, `validateProjectRegister(doc)` for the whole register, `validateWorkflowSnapshot(doc)` for the snapshot, `validateStatus` for the v2 root (`mstar status validate <path>` / engine import). Malformed entries — **non-object**, missing any of the nine required fields (`id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`, `target`, `tracking` — mirroring engine `RESIDUAL_REQUIRED_FIELDS` in `packages/engine/src/status.ts`), or **severity** outside the enum — are **rejected** (`ok:false` + violation): fix and rewrite — never silent pass-through, downgrade-write, or “write then patch”.
 
 dsh-derived findings map their keys per the engine-residual validation verification spec §5; dsh keys never enter the schema.
 
@@ -69,7 +153,7 @@ dsh-derived findings map their keys per the engine-residual validation verificat
 
 ## Residual findings: `severity` (SSOT, machine field)
 
-Each `residual_findings[<plan-id>][]` entry’s **`severity`** must be from this enum (legacy read paths → **`jq` examples** at end). QC report Markdown **Critical / Warning / Suggestion** are **section titles** — **do not** copy them verbatim into JSON `severity`.
+Each register entry (`projects/<id>/residuals.json` → `entries[<plan-id>][]`)’s **`severity`** must be from this enum. QC report Markdown **Critical / Warning / Suggestion** are **section titles** — **do not** copy them verbatim into JSON `severity`.
 
 ### 1. Allowed values
 
@@ -92,13 +176,13 @@ Only these five, **lowercase English**:
 | `high` | Not blocking but high impact (security, correctness, data, significant tech debt); fix, escalate, or open residual with PM follow-up. |
 | `medium` | Should address this or next milestone; may be open residual. |
 | `low` | Small impact, cheap fix; may be open residual. |
-| `nit` | Style, naming, wording, non-behavior doc nits; **lighter than `low`**. PM may omit from `residual_findings` if no tracking needed. |
+| `nit` | Style, naming, wording, non-behavior doc nits; **lighter than `low`**. PM may omit from the register if no tracking needed. |
 
 Summary vs `mstar-review-qc`: unresolved **`critical`** → usually `Request Changes`; **`high`** often “fix or explicit decision before merge”; **`medium` / `low` / `nit`** may ship with residual tracking (final **Verdict** = PM consolidation).
 
 ### 4. QC report section → JSON `severity`
 
-When registering into root **`residual_findings`** (template in `mstar-review-qc`):
+When registering into the project register (template in `mstar-review-qc`):
 
 | Report Findings section | JSON `severity` |
 | ----------------------- | --------------- |
@@ -116,14 +200,15 @@ In old JSON, **`"severity": "warning"`** is read and rolled up as **`low`**. **F
 
 ## Findings cleanup modes
 
-Plan-level policy for whether non-blocking QC/QA findings may remain as open residuals or must be cleared in the current plan session.
+Plan-level policy for whether non-blocking QC/QA findings may remain as open residual entries or must be cleared in the current plan session.
 
-### Assignment + metadata
+### Assignment (SSOT)
 
 | Surface | Values |
 | ------- | ------ |
 | Assignment **`Findings cleanup`** | `zero-residual` \| `allow-residual` |
-| `plans[].metadata.findings_cleanup` | same strings (optional mirror; Assignment wins when both set) |
+
+The v1 `plans[].metadata.findings_cleanup` mirror is **deleted** in v3 — no dual-track. Assignment wins; the register is the only residual store.
 
 **Defaults**
 
@@ -141,23 +226,26 @@ Intent: clear findings in the current plan session whenever possible. Open resid
 3. **`nit`**: fix in-session **or** drop with no R# (existing “no tracking needed”); **never** open residual for style-only nits.
 4. **`Approve with residuals`** only when every remaining open item is a true blocker-defer (`decision: defer`, `target` = next iteration/milestone, Durable Roadmap Gate written).
 5. **True defer** only: external dependency; product/scope decision for a later iteration; or explicit **current-turn** user defer — plus Durable Roadmap Gate.
-6. **`waived` / `risk-accepted`**: still require PM + user/architect alignment; **close/archive** (do not leave open). Prefer a cheap fix over waive-as-shortcut.
-7. Plan **Done**: prefer empty `residual_findings[<plan_id>]`. If any open R# remain, **every** entry must be blocker-defer + roadmap; otherwise keep `InReview` / `Blocked`.
+6. **`waived` / `risk-accepted`**: still require PM + user/architect alignment; **close in the register** (do not leave open). Prefer a cheap fix over waive-as-shortcut.
+7. Plan **Done**: prefer an empty `entries[<plan_id>]` in the register. If any open entries remain, **every** one must be blocker-defer + roadmap; otherwise keep `InReview` / `Blocked`.
 
 ### `allow-residual` (legacy default)
 
-Non-blocking Warning/Suggestion may ship with open R# registration and `Approve with residuals` when no unresolved Critical remains (existing residual lifecycle unchanged).
+Non-blocking Warning/Suggestion may ship with open register entries and `Approve with residuals` when no unresolved Critical remains (existing residual lifecycle unchanged).
+
+> **Engine check (when available):** run `mstar status findings-cleanup <plan-id> [--project <id>] [--mode zero-residual|allow-residual]` (or import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook) to enforce the mode above against the plan's register entries. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ---
 
-## `plans[].metadata` standard optional fields
+## Snapshot plan-row fields (`plans[].metadata` standard optional fields)
+
+Snapshot plan rows keep the v1 PlanRow shape verbatim; the standard optional `metadata` keys below are unchanged from v1:
 
 | Key | Type | Purpose |
 | --- | --- | --- |
-| `findings_cleanup` | `zero-residual` \| `allow-residual` | Mirror of Assignment **`Findings cleanup`**; see **Findings cleanup modes** |
 | `working_branch` | string | Implementation branch; aligns with Assignment **`Working branch`** (SSOT) |
-| `spec_integration_branch` | string | (Multi-plan same **Spec**) integration branch name; created from root `metadata.iteration_base_branch`; plan branches merge here before final PR (`mstar-plan-conventions`) |
-| `merge_target` | string | Next merge target; multi-plan + Spec → usually `spec_integration_branch`; final PR target is root `metadata.target_branch` |
+| `spec_integration_branch` | string | (Multi-plan same **Spec**) integration branch name; created from snapshot `branch.base` / `execution_policy` context; plan branches merge here before final PR (`mstar-plan-conventions`) |
+| `merge_target` | string | Next merge target; multi-plan + Spec → usually `spec_integration_branch`; final PR target is snapshot `branch.target` |
 | `branch_policy` | string | One-line policy per `mstar-harness-core` |
 | `phase` | string | Program/roadmap label |
 | `priority` | `high` \| `medium` \| `low` | PM scheduling |
@@ -171,11 +259,12 @@ Non-blocking Warning/Suggestion may ship with open R# registration and `Approve
 | `primary_spec` | string | Main spec path (`{KNOWLEDGE_DIR}/…`, `{SPECS_DIR}/…`) |
 | `iteration_compass` | string | Optional `{ITERATION_DIR}/…` |
 | `iteration_refs` | string[] | Optional multiple compass paths |
-| `qc_status` / `tests` / `commits` | string | InReview/Done snapshots; not a substitute for durable plan gate summaries or root `residual_findings` |
+| `knowledge_refs` | string[] | Optional knowledge-doc references (e.g. `{KNOWLEDGE_DIR}/…` paths or doc ids) linked from this plan; written by `mstar-compound` Phase 6 / `mstar-compound-refresh` Phase 4; v1 root `status.json` metadata references are legacy read-only |
+| `qc_status` / `tests` / `commits` | string | InReview/Done snapshots; not a substitute for durable plan gate summaries or the project register |
 | `sdd_dir` | string | SDD scratch path, e.g. `{HARNESS_DIR}/sdd/<plan-id>/` (gitignored; `mstar-sdd`) |
 | `sdd_progress` | string | Optional pointer to `{SDD_DIR}/progress.md` ledger |
 | `review_bundle` | string | Optional pointer to `{SDD_DIR}/review/` for current ephemeral QC/QA evidence |
-| `task_commits` | array\<object\> | SDD recovery: `{ "task_id": "T1", "base": "<sha>", "head": "<sha>" }` per completed task |
+| `task_commits` | array\<object\> | SDD recovery: `{ "task_id": "T1", "base": "<sha>", "head": "<sha>" }` per completed task — recorded on the snapshot plan row |
 
 ### `plans[].execution_lease` (iteration Phase 2)
 
@@ -185,223 +274,72 @@ Optional when a plan is not owned; **required** while a Phase 2 session owns wri
 | --- | --- | --- | --- |
 | `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`. |
+| `worktree_path` | absolute path string | Yes | Dedicated feature-worktree root; **MUST** differ from `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.
 
-### Optional delivery ledger (`phase` + `batches` + `verification`)
+V1: **manual release only** — omit `expires_at`; readers **MUST NOT** treat unknown or draft `expires_at` as authority to steal or release.
 
-For multi-batch or multi-role plans:
+### Snapshot top-level fields
 
-| Key | Type | Purpose |
+| Field | Type | Semantics |
 | --- | --- | --- |
-| `phase` | string | Delivery phase label |
-| `batches` | array\<object\> | Per-batch task coverage, owner, status, commits, self-audit |
-| `verification` | object | Command-level verification snapshot |
+| `integration_merge_lease` | object | While one integration merge is owned; **absent** = unclaimed. Writers **delete** the key on release — never `null` or tombstones |
+| `execution_policy` | object | `plan_parallelism` / `worktree_mode` / `push_policy` — first-class (copied from v1 root `metadata` at migrate; values accepted-but-opaque this iteration) |
+| `branch` | object | Iteration branch anchors: `base` (from `iteration_base_branch`), `integration` (the `spec_integration_branch`), `target` (final PR target) |
+| `control_worktree_path` | absolute path string | Iteration Phase 2: canonical **repository root** (not `{HARNESS_DIR}`) checked out to the `branch.integration` branch; coordination + serial merge cwd |
+| `compass_ref` | string | Relative pointer to the iteration delivery compass |
+| `legacy_metadata` | object | Catch-all for unmapped v1 root-`metadata` keys at migrate |
 
-Recommended `batches[]` subfields: `index`, `covers`, `status`, `owner`, `commits`, `a2_self_audit` (or synonym), `verification`.
-
-> `batches` / `verification` are evidence indexes — not replacements for durable plan gate summaries or root `residual_findings`.
-
-### `plans[].notes` vs `{HARNESS_DIR}/notes.json`
-
-- `plans[].notes`: per-plan timeline (string array recommended).
-- `{HARNESS_DIR}/notes.json`: cross-plan program milestones.
-
-Legacy string `plans[].notes` is OK; new repos should use arrays with time + event + evidence anchor.
-
-## 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#; maintain via engine rollup (below) |
-| `control_worktree_path` | absolute path string | Iteration Phase 2: canonical **repository root** (not `{HARNESS_DIR}`) 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 write `null` or tombstone objects |
+### Snapshot `notes` vs `{WORKFLOW_DIR}/<id>/notes.jsonl`
 
-**Formal iteration example** (root `metadata`; values are project-specific — **do not** copy `main` by default):
-
-```json
-"metadata": {
-  "iteration_base_branch": "release/1.76",
-  "target_branch": "release/1.77"
-}
-```
-
-Plan row (per active iteration plan):
-
-```json
-"metadata": {
-  "spec_integration_branch": "iteration/v1.77-live-teels",
-  "merge_target": "iteration/v1.77-live-teels",
-  "iteration_refs": ["v1.77"]
-}
-```
+- `plans[].notes`: per-plan timeline — **legacy verbatim copy** (read-only; preserved at migrate; never a dual-write target).
+- `{WORKFLOW_DIR}/<id>/notes.jsonl`: **runtime notes ledger** — append-only; new notes go here only (`kind` + `ts` + `text` JSON lines; `mstar migrate` seeds it from v1 arrays).
 
 ---
 
 ## Iteration execution leases (Phase 2)
 
-Cooperative coordination through the **control worktree** copy of `{HARNESS_DIR}/status.json`. Not a distributed lock service — non-cooperating processes are out of scope. **Same-host** writers use an exclusive write lock (below) around lease mutations; **cross-plan parallel writable implement** is permitted only when that lock is available on the control path and held for every lease mutation (see hard gate below).
-
-**When fields apply:** iteration Phase 2 (after control worktree entry, or primary checkout when `Worktree mode: waived`). Control worktree + lease fields are waived only by explicit current-turn user instruction (`Worktree mode: waived` or equivalent). `Plan parallelism: serial` does **not** waive leases. **`Worktree mode: waived` does not waive the cross-plan parallel safety gate** (see hard gate below).
-
-**Path SSOT:** Default-gitignored process artifacts — `status.json`, `plans/`, `iterations/`, `sdd/`, `notes.json`, `archived/` — read/write via `<control_worktree_path>/{HARNESS_DIR}/…` (absolute). A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT. Missing plans under a feature checkout (gitignore) is **not** grounds for `Worktree mode: waived` — keep feature worktrees and use control absolute **`Plan Path`** / **`SDD dir`**. Detail → **`mstar-branch-worktree`** 「Harness path SSOT under default gitignore」.
-
-### Same-host exclusive write lock (control `status.json`)
+Leases live in the **workflow snapshot** `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[].execution_lease` per row; `integration_merge_lease` top-level). Coordination happens through the **control worktree** copy of that file. This is cooperative, not a distributed lock service — non-cooperating processes are out of scope.
 
-Lease mutations on the **control** copy of `{HARNESS_DIR}/status.json` — execution claim/release/transfer, plan-status transitions that touch leases, and `integration_merge_lease` claim/release — **MUST** run inside a **same-host exclusive write lock** for the full read-check-replace-verify sequence.
-
-**Preferred (same machine, shared filesystem):** advisory lock on `{HARNESS_DIR}/.status-write.lock` via `flock` (or equivalent). Hold from first read through post-write verify; release on all exit paths (success or failure).
-
-```bash
-CONTROL_ROOT="<metadata.control_worktree_path>"
-HARNESS=".harness"   # or resolved {HARNESS_DIR}
-STATUS="$CONTROL_ROOT/$HARNESS/status.json"
-LOCK="$CONTROL_ROOT/$HARNESS/.status-write.lock"
-(
-  flock -x 9 || exit 1
-  # read → mutate → temp file + atomic replace → re-read verify
-) 9>"$LOCK"
-```
+**When fields apply:** iteration Phase 2 (after control worktree entry, or primary checkout when `Worktree mode: waived`). Control worktree + lease fields are waived only by explicit current-turn user instruction (`Worktree mode: waived` or equivalent). `Plan parallelism: serial` does **not** waive leases. **`Worktree mode: waived` does not waive the cross-plan parallel safety gate.**
 
-**Alternative when `flock` unavailable:** atomic `mkdir` on `{HARNESS_DIR}/.status-write.lockdir/` — success acquires; existing dir → **Blocked** (another writer holds the lock); remove the directory only after successful verify or explicit rollback.
+**Path SSOT:** Default-gitignored process artifacts — `status.json`, `workflows/`, `projects/`, `plans/`, `iterations/`, `sdd/` — read/write via `<control_worktree_path>/{HARNESS_DIR}/…` (absolute). A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT. Missing plans under a feature checkout (gitignore) is **not** grounds for `Worktree mode: waived` — keep feature worktrees and use control absolute **`Plan Path`** / **`SDD dir`**. Detail → **`mstar-branch-worktree`** 「Harness path SSOT under default gitignore」.
 
-**Hard gate — cross-plan parallel writable implement:** Applies **whether or not** `Worktree mode: waived`. Lease-gated **cross-plan parallel** writable implement (when lease gate active) is allowed **only when** a same-host exclusive write lock is **available on the coordination `status.json` filesystem and held for every status/coordination mutation** in that Phase 2 session (execution claim/release/transfer, plan-status transitions, `integration_merge_lease` claim/release when lease gate active). When waived, the coordination path is primary checkout `{HARNESS_DIR}/status.json` — the same lock discipline applies to any shared status mutation before parallel writable dispatch. If agents span hosts or the coordination path has **no shared flock/lockdir** (distinct machines, non-shared mount), **default `Plan parallelism: serial`** for cross-plan implement scheduling — one plan writable wave at a time (**preferred default when waived**). If Assignment still claims cross-plan parallel implement without same-host lock availability → **Blocked** until PM aligns Assignment (`Plan parallelism: serial`) or the user supplies the override below. **`Worktree mode: waived` alone is not** the cross-host parallel override. v1 does **not** add a distributed CAS CLI.
+**Protocol home (single canonical copy):** the full lease protocol prose — same-host exclusive write lock, hard gate, claim-before-`InProgress`, hold/release/override, integration merge protocol, orphan recovery, lease prohibitions — lives in **`mstar-engine-legacy`** `references/lease-protocol.md` (engine-absent fallback). The Phase 2 iteration-command **execution checklist** → **`mstar-iteration`** `references/phase-2-worktree-lease.md`. This file carries the **field semantics** only (tables below + the lockdir location summary).
 
-**Exception — documented cross-host residual:** Explicit **current-turn** user instruction such as `Cross-host lease race: accepted` (or equally unambiguous equivalent) **plus** audit entry on affected `plans[].notes` (timestamp, hosts/sessions involved, residual race risk acknowledged) permits cooperative multi-host cross-plan parallel with documented residual risk.
+**Same-host exclusive write lock (snapshot / root):** all control-path lease mutations (execution claim/release/transfer, plan-status transitions that touch leases, `integration_merge_lease` claim/release) **MUST** run inside a same-host exclusive write lock for the full read-check-replace-verify sequence. Engine writers handle this automatically (`writeWorkflowSnapshot` / `registerWorkflow` acquire `<status-file dir>/.status-write.lockdir/` next to the file — for snapshots the lockdir lands inside `workflows/<id>/`). Prefer the engine-check commands below over hand-rolled `flock` snippets; the atomic-mkdir alternative (`.status-write.lockdir/` in the same directory as the file) remains the documented fallback when no engine writer exists. Hard gate, cross-host exception and pre-dispatch re-verify → `mstar-engine-legacy/references/lease-protocol.md`.
 
-**Pre-dispatch re-verify:** Immediately before **any** writable implement dispatch, reread control `status.json` and confirm this session still passes verify-held-lease (`holder`, `worktree_path`, `working_branch` match Assignment). Mismatch or absent lease → **STOP** — do not dispatch.
+> **Engine check (when available):** run `mstar lease verify --workflow <id> [--plan <plan-id>]` or `mstar lease verify-integration --workflow <id>` (or import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook) to validate the leases above on the workflow snapshot. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
-### Root `metadata.integration_merge_lease` (v1)
+### `integration_merge_lease` (snapshot top-level)
 
-Single global lease authorizing one plan feature branch integration into `spec_integration_branch`.
+Single global lease authorizing one plan feature branch integration into `branch.integration` (the `spec_integration_branch`).
 
 | Field | Type | Required | Semantics |
 | --- | --- | --- | --- |
 | `holder` | non-empty string | Yes | Same format and comparison rules as `execution_lease.holder`. |
 | `claimed_at` | RFC 3339 UTC (`Z`) | Yes | Acquisition time (audit only). |
-| `plan_id` | non-empty string | Yes | `plans[].id` (or legacy `plan_id`) of the feature being integrated. |
+| `plan_id` | non-empty string | Yes | `plans[].id` of the feature being integrated. |
 | `source_branch` | non-empty string | Yes | Plan feature branch to integrate. |
 | `target_branch` | non-empty string | Yes | Resolved `spec_integration_branch` — no other target is valid. |
 | `session_label` | string | No | Display only. |
 
-Example fragments:
-
-```json
-{
-  "metadata": {
-    "control_worktree_path": "/repo",
-    "integration_merge_lease": {
-      "holder": "cursor:bc-1234",
-      "claimed_at": "2026-07-22T04:00:00Z",
-      "plan_id": "plan-a",
-      "source_branch": "feature/plan-a",
-      "target_branch": "iteration/2026-07",
-      "session_label": "Integrate plan A"
-    }
-  },
-  "plans": [
-    {
-      "id": "plan-a",
-      "status": "InProgress",
-      "execution_lease": {
-        "holder": "cursor:bc-1234",
-        "claimed_at": "2026-07-22T02:30:00Z",
-        "worktree_path": "/repo-worktrees/plan-a",
-        "working_branch": "feature/plan-a",
-        "session_label": "Plan A implementation"
-      },
-      "metadata": {
-        "spec_integration_branch": "iteration/2026-07",
-        "merge_target": "iteration/2026-07"
-      }
-    }
-  ]
-}
-```
-
-### Claim-before-`InProgress` (execution lease)
-
-A Phase 2 session **MUST** claim **before** moving a plan from `Todo` or `Blocked` to `InProgress` and **before** any writable dispatch for that plan:
-
-1. Reread the control copy of `status.json`; locate exactly one plan row (`id` or `plan_id` read compatibility).
-2. **Resume (not steal):** if `execution_lease` exists and `holder` **equals this session** → verify-held-lease: confirm `worktree_path` and `working_branch` match the Assignment; continue (this is **not** Blocked and **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” below). 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 same-host write lock (see above); reread `status.json`; if row, status, or lease state 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 and atomically replace `status.json`.
-8. Reread the stored row; verify `holder`, `worktree_path`, and `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 or 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:** reread control `status.json`; 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 any `execution_lease` in the **same** complete-file update as `status: "Done"` — **only after** successful integration merge into `spec_integration_branch` when Phase 2 lease gate is not waived (see “Integration merge protocol” and `mstar-iteration` §2.4). After QC/QA pass, 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 entry to `plans[].notes` with timestamp, prior holder, new holder (or release), and that the user authorized override. 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 above is satisfied (same-host lock on coordination `status.json`, default **`Plan parallelism: serial`**, or current-turn `Cross-host lease race: accepted` + audit `plans[].notes` — **not** by `Worktree mode: waived` alone); when 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. Reread root `metadata` under the same-host write lock (above). If `integration_merge_lease` exists:
-   - **Resume (not steal):** `holder` **equals this session** → verify-held-merge-lease: confirm `plan_id`, `source_branch`, and `target_branch` match the intended merge; confirm control worktree state (clean or documented in-progress resolution); continue (this is **not** Blocked).
-   - **Blocked:** `holder` **differs** → stop. No timestamp, TTL, or inactivity makes it stealable.
-3. If unclaimed, claim merge lease with the same read-check-replace-verify discipline as execution claims. `source_branch` and `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 per plan/status conventions; **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 merge lease only after control worktree is clean and in a known state.
-
-Execution and merge leases may coexist; merge lease does not grant execution ownership for the source plan.
-
-### Orphan recovery (`InProgress` without `execution_lease`)
-
-Runtime skills that detect this state (e.g. `mstar-iteration`) **STOP** and defer recovery here — 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 plan is returned 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 `plans[].notes` audit (timestamp, reason, actor). |
-| **Recover with claim (same holder)** | Legitimate in-progress work; feature 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-before-`InProgress` from step 5 under write lock; append `plans[].notes` audit (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 `notes` (prior holder, new holder, user authorized). Then normal claim under write lock. |
-| **Escalate / `Blocked`** | Ambiguous ownership, conflicting worktrees, or partial/corrupt `status.json` | Set `status: "Blocked"` with `metadata.blocked_reason`; do **not** writable-dispatch until human/PM resolves. Restore coherent `status.json` from latest complete state if needed. |
-
-After any recovery path, the next session must pass verify-held-lease before writable dispatch.
-
-### Agent prohibitions (lease SSOT)
+### Claim-before-`InProgress`, hold/release/override, integration merge, orphan recovery, prohibitions
 
-- **MUST NOT** steal or overwrite an active `execution_lease` or `integration_merge_lease` (no TTL, age, or inactivity authority in v1).
-- **MUST NOT** writable-dispatch without a verified `execution_lease` for that plan (resume counts only when same `holder` passes verify-held-lease).
-- **MUST NOT** write `null` or tombstone objects for lease keys — **delete** the key on release.
-- **PM NEVER** steal an active lease without explicit current-turn user override + audit `notes` (full list → `mstar-roles/references/project-manager.md` § PM-Specific NEVER Rules).
-
-Preservation: writers **MUST** preserve unrelated plan rows, root metadata, and `residual_findings` on every lease mutation.
+These are **full-protocol prose** — the single canonical copy lives in **`mstar-engine-legacy`** `references/lease-protocol.md` (engine-absent fallback); the Phase 2 iteration-command **execution checklist** is **`mstar-iteration`** `references/phase-2-worktree-lease.md`. This file carries the field semantics (tables above) and the engine checks only — do not re-state the protocol here. `V1: manual release only` — omit `expires_at`; readers **MUST NOT** treat unknown or draft `expires_at` as authority to steal or release (see the `execution_lease` field table).
 
 ---
 
 ## General constraints
 
-- Each `plans[]` row may include optional **`metadata`** (`{}` or omit).
-- Init with `"residual_findings": {}`; **no dual-write** with legacy side (see SKILL.md). Program timeline → **`notes.json`**, not long `metadata.notes` in `status.json`.
-- **`plans[].id`** keys must align with root **`residual_findings`** keys and `{SDD_DIR}` plan-id segments. Do not store `residual_findings_plan_id`.
-- **Empty `plan-id` key:** when no open items remain, **delete** the key from root **`residual_findings`** (and legacy side if present) — no `"plan-id": []`. Whether **`plans[]`** keeps the row is separate (`done-compaction.md`).
-- **`residual_summary` (optional):** one-line human summary of **open** items only.
+- Each snapshot `plans[]` row may include optional **`metadata`** (`{}` or omit).
+- A workflow root entry is **active only** (`running` | `paused`); terminal writers unregister the root entry after the snapshot write (removal-at-terminal).
+- **`plans[].id`** keys must align with register `entries` keys and `{SDD_DIR}` plan-id segments. Do not store `residual_findings_plan_id`.
+- **Empty `plan-id` key:** when no open entries remain, **delete** the key from the register (`entries`) — no `"plan-id": []`.
+- **`residual_summary` (optional):** one-line human summary of **open** entries only.
 
 ---
 
@@ -424,156 +362,99 @@ Preservation: writers **MUST** preserve unrelated plan rows, root metadata, and
 | Action | Owner | When |
 | ------ | ----- | ---- |
 | Implement fix | `@fullstack-dev` / assignee | Completion Report cites R# + evidence |
-| Verify | `@qa-engineer` when **`QA gate: mandatory`**; else PM per acceptance checklist | Regression / acceptance; open R# close requires verify before archive |
-| Write `status.json` | **`@project-manager`** or **`@qa-engineer`** | After verification; waivers after PM + user/architect alignment |
+| Verify | `@qa-engineer` when **`QA gate: mandatory`**; else PM per acceptance checklist | Regression / acceptance; open R# close requires verify before close |
+| Write the register | **`@project-manager`** or **`@qa-engineer`** | After verification; waivers after PM + user/architect alignment |
 
 Do not claim “R3 fixed” in chat/plan only without SSOT update.
 
 PM should register open items after **`Approve with residuals`**; QA should state each related R# (open / resolved this round / needs waiver).
 
-### Recommended: archive to `archived/residuals/<plan-id>.json`
+### Close in place (the only close path)
 
 After **`closed_at`**, **`closure_note`**, and PM/QA confirm close:
 
-1. **Append** to **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**.
-2. **Remove** from open list (root **`residual_findings[<plan-id>]`**; legacy side if used). Delete empty **`plan-id`** keys.
-3. Update root **`updated_at`**; optional milestone in **`notes.json`**.
-
-Archive file shape (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"
-    }
-  ]
-}
-```
+1. Set `lifecycle` / `closed_at` / `closure_note` on the entry **in place** in the register (`projects/<id>/residuals.json` → `entries[<plan-id>]`).
+2. Optional: delete the entry from the register instead when the team prefers an empty open list — the closed record's `lifecycle` + `closed_at` is the durable record either way.
+3. Delete empty **`plan-id`** keys; update root `updated_at`; optional milestone entry in the workflow `notes.jsonl`.
 
-- Each archived entry needs **`archived_at`** (`YYYY-MM-DD`).
-- Closed records live in archive + durable plan summaries; raw review bundles are ephemeral and not part of the long-term open list.
-- After batch archive/close, **refresh `tech_debt_summary`** (engine rollup below).
+Closed records live in the register + durable plan summaries; raw review bundles are ephemeral and not part of the long-term record.
 
 ### Short in-place close (transition only)
 
-May set `lifecycle` / `closed_*` in open list for one PR; **same milestone** move to archive + delete from open list.
-
-### Legacy `metadata.residual_findings_history`
-
-Prefer **`archived/residuals/`**; migrate and delete history key when possible.
+May set `lifecycle` / `closed_*` in the register for one PR; same milestone close/delete as above.
 
 ### Hard delete
 
 - **Forbidden** for **open** entries.
-- Do not delete archived entries; correct via new entry or new R# referencing old `id`.
-- Mistaken open-only entry: PM may delete or mark **`duplicate`** then close/archive.
+- Do not delete closed entries; correct via new entry or new R# referencing old `id`.
+- Mistaken open-only entry: PM may delete or mark **`duplicate`** then close.
 
-### Query open and archived (examples)
+### Query open and closed (examples)
 
 ```bash
-# Replace .mstar with your resolved {HARNESS_DIR}; legacy projects may use .agents.
-jq '.residual_findings["01-data-infrastructure"] // .metadata.residual_findings["01-data-infrastructure"]' .mstar/status.json
-jq '.entries[] | select(.id == "R1")' .mstar/archived/residuals/01-data-infrastructure.json
-# Engine rollup (read-only): import { techDebtRollup } from "@mstar-harness/engine" in a host hook — CLI form: mstar status tech-debt <path>
+# Engine-check (read-only): validate the register / rollup / cleanup gate
+mstar status validate <path-to-residuals-or-root.json>   # schema
+mstar status tech-debt <project-dir>                     # rollup over registers
+mstar status findings-cleanup <plan-id> --project <id>   # mode gate
 ```
 
-(`//` right-hand side = legacy read path.)
+- The v1 read paths (root `residual_findings` / `metadata.residual_findings` / `archived/residuals/<plan-id>.json`) are **legacy read-only** — `mstar migrate` moved open entries into the register; old files may remain for history.
 
 ---
 
-## `{HARNESS_DIR}/notes.json` (optional program timeline)
+## `{WORKFLOW_DIR}/<id>/notes.jsonl` (per-workflow notes ledger)
 
-Append-only log for merge closure, batch archive, `tech_debt_summary` refresh, etc. Does not compete with **`plans[].status`** / open residual SSOT.
+Append-only JSON-lines log for merge closure, batch close, register refreshes, etc. Does not compete with **snapshot `plans[].status`** / open residual SSOT.
 
-```json
-{
-  "schema_version": 1,
-  "updated_at": "YYYY-MM-DD",
-  "entries": [
-    { "at": "2026-04-08", "message": "Short milestone", "plan_id": "01-data-infrastructure" }
-  ]
-}
+```jsonl
+{"kind": "note", "ts": "2026-04-08", "text": "Short milestone"}
 ```
 
-- **`@project-manager`** maintains; do not rewrite past `entries` — add correction as new entry.
-- **`plans[].notes`**: per-plan; **`notes.json`**: cross-plan.
+- **`@project-manager`** maintains; do not rewrite past lines — add a correction as a new line.
+- **`plans[].notes`**: per-plan legacy verbatim array; **`notes.jsonl`**: runtime ledger — new notes append here only (no dual-write).
 
 ---
 
-## `metadata.tech_debt_summary` (optional rollup)
+## `mstar status tech-debt` (project-register rollup)
 
-**Role:** Cross-plan aggregate over **open** R# in root **`residual_findings`** (and legacy read path if present). Does **not** replace per-entry SSOT.
+**Role:** Cross-plan aggregate over **open** register entries across every `{PROJECT_DIR}/<id>/residuals.json` register. Does **not** replace per-entry SSOT. The v1 stored-summary drift check (`metadata.tech_debt_summary`) is a **v1 dead path** — the register is the source of truth, so `stored` is always null and the retained `checks`/`overall` fields report DRIFT (export-surface compatibility).
 
-**Compute (canonical):** engine import (do **not** hand-count):
+**Compute (canonical):** engine / CLI (do **not** hand-count):
 
 ```ts
-// Engine check (when available) — pass status.json path if not .mstar/status.json
+// Engine check (when available) — pass the project dir (default: resolved {PROJECT_DIR})
 import { techDebtRollup } from "@mstar-harness/engine";
-const rollup = techDebtRollup(".mstar/status.json"); // { computed, stored, checks, overall }
-// CLI form (same output; exit 1 on DRIFT): mstar status tech-debt <path> (default: {HARNESS_DIR}/status.json)
-```
-
-- Prints computed `total_open`, `by_severity`, `by_target`, `by_plan`.
-- Prints **PASS** / **DRIFT** vs stored `metadata.tech_debt_summary`.
-- The engine call **does not write** `status.json` — PM copies computed values into `metadata.tech_debt_summary` after DRIFT or milestone refresh.
-
-**When to refresh:** after QC waves, batch archive of resolved items, or release freeze. Optional `notes.json` entry: “refreshed tech_debt_summary”.
-
-**Recommended stored shape** (`cross_cutting` optional; engine does not compute `cross_cutting` — maintain manually if used):
-
-```json
-{
-  "tech_debt_summary": {
-    "updated_at": "YYYY-MM-DD",
-    "total_open": 29,
-    "by_severity": { "critical": 0, "high": 10, "medium": 10, "low": 5, "nit": 1 },
-    "by_target": { "V1.0": 5, "V1.1": 18 },
-    "by_plan": { "domain-models": 4, "cli-daemon-foundation": 11 },
-    "cross_cutting": [
-      {
-        "id": "DEBT-X1",
-        "title": "Cross-plan theme",
-        "severity": "high",
-        "relates_to": ["CLI-R9", "SYNC-R4"]
-      }
-    ]
-  }
-}
+const rollup = techDebtRollup("{HARNESS_DIR}/projects"); // { computed, stored: null, checks, overall }
+// CLI form (same output; informational exit 0): mstar status tech-debt <path> (default: {PROJECT_DIR})
 ```
 
-- **`by_plan`** keys: short labels or `plans[].id` prefixes per repo convention.
-- **`cross_cutting`**: themes spanning plans/R#; explain intentional count differences in `notes.json` or here.
+- Prints computed `total_open`, `by_severity`, `by_target`, `by_plan` (`by_plan` keyed by plan id — the snapshot/register plan linkage; legacy `"warning"` → `low`, `null`/`""` → `medium`; closed entries skipped; missing `target` groups under `"unspecified"`).
+- The engine call **does not write** anything.
 
 ---
 
-## Pre-merge: `status.json` should match reality
+## Pre-merge: snapshot + register should match reality
 
-Before merge/PR, **`@project-manager`** (or delegate) should verify: `plans[].status`, `metadata.gates`, root **`residual_findings`** (no accidental dual-write), **`tech_debt_summary`** (if used — run engine rollup), **`notes.json`** (if used), vs review/CI.
+Before merge/PR, **`@project-manager`** (or delegate) should verify: snapshot `plans[].status`, `metadata.gates`, project register (no accidental leftovers), vs review/CI.
 
 **Common gaps:**
 
-- R# added/closed but **`tech_debt_summary` not refreshed** (engine rollup shows DRIFT).
-- Finding only in **`plans[].notes`** or chat, not in **`residual_findings[<plan-id>]`**.
-- Major milestone with no **`notes.json`** entry when team uses program timeline.
+- R# added/closed but the register was not updated.
+- Finding only in `plans[].notes` or chat, not in the register `entries[<plan-id>]`.
+- Major milestone with no `notes.jsonl` entry when team uses the workflow ledger.
 
 ## Compatibility: plan key names
 
-- Read: accept `id` or `plan_id`.
+- Read: accept `id` or `plan_id` (v1 rows / entries read compatibility).
 - Write: one canonical key (prefer `id`).
-- Document canonical key in `{HARNESS_DIR}/AGENTS.md` if migrating.
+- Document the canonical key in `{HARNESS_DIR}/AGENTS.md` if migrating.
 
 ## Common queries
 
 ```bash
-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
+# Engine-check (recommended): validate any v2 artifact
+mstar status validate .mstar/status.json                  # root v2
+mstar status validate .mstar/workflows/<id>/snapshot.json # snapshot
+mstar status tech-debt .mstar/projects                     # register rollup
 ```
+v1 trees (root `plans[]` / `residual_findings`) are migrated first: `mstar migrate [--dry-run] [--path <root>]`.