@mstar-harness/opencode 1.3.2 → 1.5.0

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

@@ -130,6 +130,20 @@ In old JSON, **`"severity": "warning"`** is read and rolled up as **`low`**. **F
 | `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 |
 
+### `plans[].execution_lease` (iteration Phase 2)
+
+Optional when a plan is not owned; **required** while a Phase 2 session owns writable execution for that plan. Normative protocol below; iteration command checklist → `mstar-iteration/references/phase-2-worktree-lease.md`.
+
+| 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.
+
 ### Optional delivery ledger (`phase` + `batches` + `verification`)
 
 For multi-batch or multi-role plans:
@@ -161,6 +175,8 @@ Legacy string `plans[].notes` is OK; new repos should use arrays with time + eve
 | `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 script (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 |
 
 **Formal iteration example** (root `metadata`; values are project-specific — **do not** copy `main` by default):
 
@@ -181,6 +197,157 @@ Plan row (per active iteration plan):
 }
 ```
 
+---
+
+## 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:** status and SDD reads/writes use `<control_worktree_path>/{HARNESS_DIR}/…`. A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT.
+
+### Same-host exclusive write lock (control `status.json`)
+
+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"
+```
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+### Root `metadata.integration_merge_lease` (v1)
+
+Single global lease authorizing one plan feature branch integration into `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. |
+| `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)
+
+- **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.
+
+---
+
 ## General constraints
 
 - Each `plans[]` row may include optional **`metadata`** (`{}` or omit).

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

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

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

@@ -127,6 +127,12 @@ If any item below matches, fix the dispatch/plan state or mark `Blocked`—do **
 - **NEVER** perform specialist document edits in the PM thread when host invoke is required — that is `dispatch incomplete` (`mstar-dispatch-gates`, `mstar-iteration` §1.6).
 - **NEVER** mark the last plan `Done` and then create a PR or declare the iteration complete without **`## Phase 3: iteration-close`** and `mstar-iteration` §3.1–§3.5 checklists.
 - **NEVER** treat final plan closure prose as iteration-close — compound, roadmap `delivered`, and compass `status: completed` require Phase 3.
+- **NEVER** steal or overwrite an active `execution_lease` or `integration_merge_lease` (no TTL, age, or inactivity authority); override only on explicit current-turn user instruction + audit `plans[].notes` (`mstar-plan-artifacts/references/status-and-residuals.md` — “Iteration execution leases”).
+- **NEVER** writable-dispatch for a plan without a **verified** `execution_lease` for that plan (resume only when same `holder` passes verify-held-lease against Assignment `Worktree path` / `Working branch`).
+- **NEVER** writable-dispatch when a plan is `InProgress` but has **no** `execution_lease` — complete orphan recovery first (`mstar-plan-artifacts` — “Orphan recovery”).
+- **NEVER** run or dispatch **parallel** integration merges into `spec_integration_branch` — merge is **serial** via `metadata.integration_merge_lease` from the control worktree (`mstar-iteration` §2.6 · `mstar-branch-worktree` L1).
+- **NEVER** cross-plan writable implement without distinct per-plan verified `execution_lease` + feature worktree; `Plan parallelism: serial` forces serial **scheduling** only — it does **not** waive control worktree or lease gates (`mstar-iteration` §2.0 #5).
+- **NEVER** dispatch **cross-plan parallel** writable implement when same-host exclusive write lock is **not** available on the coordination `status.json` path (cross-host / no shared flock) — default **`Plan parallelism: serial`** or **Blocked** if Assignment still claims parallel; exception only on current-turn user `Cross-host lease race: accepted` (or equivalent) + audit `plans[].notes` — **including when `Worktree mode: waived`** (`mstar-plan-artifacts` — “Hard gate — cross-plan parallel writable implement”).
 
 ---
 

package/harness-skills/pm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pm
-description: "PM entry shim — force project-manager orchestration when user invokes /pm or this skill (Codex and Cursor). General per-plan PM work: this skill + project-manager.md. Formal iteration lifecycle: mstar-iteration (host commands/ may orchestrate Phase 1–5). Boot, routing, dispatch SSOT → mstar-roles/references/project-manager.md and topic mstar-* skills — not here."
+description: "PM entry shim — force project-manager orchestration when user invokes /pm or this skill (Codex, Cursor, OpenCode, and Kimi). General per-plan PM work: this skill + project-manager.md. Formal iteration lifecycle: mstar-iteration (host commands/ may orchestrate Phase 1–5). Boot, routing, dispatch SSOT → mstar-roles/references/project-manager.md and topic mstar-* skills — not here."
 ---
 
 # PM (entry shim)
@@ -14,10 +14,11 @@ description: "PM entry shim — force project-manager orchestration when user in
 | **Codex** | **`/pm`** or this skill → **`project-manager`** for the session |
 | **Cursor** | **`/pm`** or this skill → general PM orchestration (single-plan, hotfix, QC waves, dispatch) **without** starting an iteration. Formal iteration → host **`commands/`** + **`mstar-iteration`** |
 | **OpenCode** | Same as Cursor when no command: **`project-manager`** via `mstar-roles` → `references/project-manager.md` |
+| **Kimi** | **`/skill:pm`** or this skill → **`project-manager`**; iteration → plugin **`commands/`** (`/morning-star-harness:iteration-*`) |
 
 **Iteration lifecycle** (optional): host `commands/` may sequence Phase 1–5; semantics SSOT → **`mstar-iteration`**. Not required for ordinary PM work.
 
-Detect host → **`mstar-host`** → `references/codex.md` | `cursor.md` | `opencode.md`.
+Detect host → **`mstar-host`** → `references/codex.md` | `cursor.md` | `opencode.md` | `kimi.md`.
 
 ## Read next (in order)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {