@mstar-harness/opencode 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to the `@mstar-harness/opencode` package are documented in t
 
 The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface releases.
 
+## 1.2.1
+
+- Bundled commands: `/iteration-start` Cursor Plan mode path — blank Phase 1 CreatePlan scaffold, staged grill-me plan updates, Build-gated Review chain.
+- Bundled skills: `mstar-iteration` §1.2 host Plan UX scaffold-then-converge; `mstar-host` Cursor Phase 1 Plan mode bridge (no command-name reverse refs).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.2.1**.
+
+## 1.2.0
+
+- Bundled commands: add `/iteration-loop` (autonomous Phase 1→5; optional `direction` + `scale`).
+- Bundled skills: `mstar-iteration` autonomous direction lock / scale budget / branch resolve + `references/autonomous-direction-lock.md`.
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.2.0**.
+
 ## 1.1.0
 
 - Bundled skills: raw QC/QA process reports default to gitignored `{SDD_DIR}/review/`; durable gate summaries and `status.json` residual findings are the tracked handoff surface. `{PLAN_DIR}/reports/` is legacy / explicit audit mode only.

package/README.md

@@ -28,7 +28,7 @@ npx @mstar-harness/cli init --target opencode
 |-----------------|----------|
 | `harness-skills/` | `mstar-harness-core`, `mstar-iteration`, `mstar-sdd`, roles, phase/dispatch gates, … |
 | `harness-agents/` | Role shells (`project-manager`, `fullstack-dev`, `qc-specialist`, …) |
-| `harness-commands/` | `/iteration-start`, `/iteration-drive`, `/mstar-bootstrap` |
+| `harness-commands/` | `/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/mstar-bootstrap` |
 
 The plugin resolves **only paths inside this package** — not `process.cwd()/skills`, so your app repo root does not affect harness loading.
 
@@ -36,7 +36,7 @@ The plugin resolves **only paths inside this package** — not `process.cwd()/sk
 
 1. Install the plugin (above).
 2. In OpenCode, start with the **Project Manager** agent (`project-manager`).
-3. For a full iteration: run **`/iteration-start`**, then **`/iteration-drive`** when plans are ready.
+3. For a full iteration: run **`/iteration-start`** then **`/iteration-drive`**, or one-shot **`/iteration-loop`** (autonomous Phase 1→5).
 
 Entry skill: **`mstar-harness-core`** (loaded before other `mstar-*` skills).
 

package/harness-commands/iteration-loop.md

@@ -0,0 +1,297 @@
+---
+name: iteration-loop
+description: Autonomous full iteration loop for cloud agents — Phase 1 (code-first auto direction lock + compass/plans + Review & Edit chain) through Phase 2–5 (execute → close → PR → merge-ready). Optional args: direction, scale (S|M|L, default M). Not Done until Phase 5 exit checklist passes. Minimal human intervention; no grill-me.
+agent: project-manager
+---
+
+# Iteration Loop
+
+Run a **full** Morning Star iteration with minimal human intervention. **Done = Phase 5 §5.5 exit checklist 全 `[x]`** — not Phase 1 lock, not Phase 3 close, not Phase 4 PR open.
+
+**vs other commands:**
+
+| Command | Scope |
+|---------|--------|
+| `iteration-start` | Phase 1 only; **grill-me** with user |
+| `iteration-drive` | Phase 2→5 on an already locked iteration |
+| **`iteration-loop`** | Phase 1→5 end-to-end; **autonomous** direction lock |
+
+Phase gate SSOT → **`mstar-iteration`** §1–§5. This command is a **consumer**; it does not redefine skill semantics.
+
+## Args（最多 2 个）
+
+```
+/iteration-loop [direction] [scale]
+```
+
+| Arg | Meaning | Default |
+|-----|---------|---------|
+| `direction` | Iteration direction / feedback constraint (free text) | Code-first research → **auto-lock recommended** |
+| `scale` | `S` \| `M` \| `L` | **`M`** |
+
+**Scale budget**（写入 compass；约束 **业务** plan 数量）→ **`mstar-iteration`** §1.2 + `references/autonomous-direction-lock.md`：
+
+- **S** → 1 business plan
+- **M** → 2–3 business plans
+- **L** → 3–4 business plans（默认上限 4，除非 `direction` 显式要求更大）
+
+**HARD**：budget **只计**实际业务交付 plan；**不计** harness 流程（Review 链、QC/QA、compound、close、PR、merge-ready、compass/`status.json` 维护等）。流程门禁仍须执行，但不占 S/M/L 名额，也不得写成独立 process plan 来“凑数/占坑”。
+
+Parse: if the last token is exactly `S`/`M`/`L` (case-insensitive), treat it as `scale`; remaining text is `direction`. If only one token and it is `S`/`M`/`L`, that is `scale` with empty `direction`.
+
+## Phase state machine（禁止跳步）
+
+```
+Phase 1: Autonomous start  →  Phase 2: Autonomous Execute  →  Phase 3: close  →  Phase 4: PR  →  Phase 5: merge-ready
+```
+
+| 当前状态 | 允许 | 禁止 |
+|----------|------|------|
+| Phase 1 未 lock | Research → auto-lock → Review chain → integration | 进入 Phase 2 implement；grill-me |
+| compass `locked` + plans registered | **立刻** Phase 2 | 问用户「是否开始 execute」 |
+| 存在非 `Done` plan | Phase 2 dispatch | 进入 Phase 3 或开 PR |
+| **全部** plan `Done` | **立刻** Phase 3 | 宣称 loop 完成、开 PR |
+| Phase 3 exit 全 `[x]` + compass `completed` | Phase 4 | 跳过 compound |
+| PR 已创建 | Phase 5 loop | 汇报结束 |
+| Phase 5 exit 全 `[x]` | **iteration-loop Done** | — |
+
+## Continuous execution（HARD — Phase 1 lock 后至 Phase 5 exit）
+
+自 Phase 1 §6 integration 完成起，至 Phase 5 §5.5 全 `[x]` 前，PM **连续编排**。
+
+| 禁止 | 必须 |
+|------|------|
+| 方向 / plan / phase 边界例行 yes/no（「是否同意该方向」「要不要继续」「是否开 PR」） | 进度摘要后**下一条** = dispatch 或下一 phase 步骤 |
+| 用 Phase 汇报收束 turn 后等待用户 | Phase 1 lock → **立刻** Phase 2；plan Done → 下一 plan 或 Phase 3 |
+| 跨 plan 并行 implement | Per-plan **串行** |
+
+**合法 STOP（仅此升级用户）**：
+
+- Branch metadata 按 **`mstar-iteration`** autonomous resolve 顺序仍无法确定（**禁止**静默默认 `main`/`master`）
+- 代码/roadmap **无可信候选**且无 `direction` 参数
+- **`Blocked`**：真冲突、secrets、不可逆范围缺口、Phase 5 多轮仍无法 merge-ready
+- 用户本轮显式打断
+
+**Turn 收束纪律**：最后一条内容必须是 **in-flight 动作**（invoke 已发出或下一 Assignment），**不得**以确认问句结尾。
+
+## PM invariants
+
+### Phase 1（Review & Edit）
+
+| 禁止（PM 线程） | 必须 |
+|-----------------|------|
+| 自己 Edit 冒充 product-manager / architect / writing-specialist | §5.1 → §5.2 → §5.3 **顺序**各 **1 次 invoke** |
+| 只写 Assignment 就声称 review 完成 | 几条角色 ⇒ 几条 invoke |
+| §5 完成前 commit / 创建 integration | 5.4 PM lock 在 subagent 返回之后 |
+| 加载 `grill-me` | **Autonomous** direction lock（`mstar-iteration` §1.2） |
+
+### Phase 2–5
+
+| 禁止（PM 线程） | 必须 |
+|-----------------|------|
+| Write/Edit/Shell 产品代码、写测试、跑 QC | 每条 implement/QC/QA Assignment ⇒ **1 次 `Task`** |
+| 多 task plan inline 大包派发 | **SDD** per-task 循环 |
+| 最后 plan `Done` 后直接开 PR | **Phase 3 → 4 → 5** |
+| Phase 5 自己改产品代码 | dispatch `fullstack-dev` / `ops-engineer` |
+
+派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。
+
+**Session todos**：
+
+| Todo id | 何时追加 | 何时可勾掉 |
+|---------|----------|------------|
+| `phase-1-autonomous-start` | Boot | compass `locked` + integration committed |
+| plan-wave todos | 进入 Phase 2 | 各 plan `Done` |
+| `phase-3-iteration-close` | 仅剩 1 个非 `Done` plan | Phase 3 §3.5 exit 全 `[x]` |
+| `phase-4-create-pr` | Phase 3 完成后 | PR 已创建 |
+| `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 §5.5 exit 全 `[x]` |
+
+## Boot
+
+1. `mstar-harness-core`
+2. `mstar-roles` → `references/project-manager.md`
+3. `mstar-iteration` → **§ Phase 1**（含 **autonomous** direction lock / scale budget / branch resolve）+ **§ Phase 2–5**
+4. `mstar-dispatch-gates`
+5. `mstar-phase-gates` → Prepare
+6. `mstar-plan-conventions`, `mstar-plan-artifacts`
+7. `mstar-host` → active host reference
+8. `mstar-compound` — before Phase 3 §3.2
+9. **`mstar-sdd`** — before first implement dispatch in Phase 2
+10. `mstar-review-qc` — before first QC dispatch in Phase 2
+11. `mstar-branch-worktree` — when Git/write or QC checkout
+
+**Do not** Read `skills/grill-me/SKILL.md` for this command.
+
+---
+
+## Phase 1: Autonomous start
+
+### 1. Research
+
+Survey structured and unstructured sources（code-first — **explore before guessing**）:
+
+**Structured:**
+- `{HARNESS_DIR}/status.json` → active plans, deferred, residuals
+- `{ITERATION_DIR}/` → prior compasses, roadmap batches
+- `{KNOWLEDGE_DIR}/` → design / architecture notes
+- `{SPECS_DIR}/` → specs, gaps
+
+**Unstructured — Glob then Read:**
+- `**/roadmap*.md`, `**/ROADMAP*.md`, `**/*-roadmap.md`
+- `**/deferred*.md`, `**/DEFERRED*.md`
+- `**/features*.md`, `**/FEATURES*.md`
+- `**/backlog*.md`, `**/TODO*.md`, `**/todo*.md`, `**/*.plan.md`
+
+Prioritize deferred / incomplete items from prior iterations. Read `STRATEGY.md` if present.
+
+### 2. Explore Directions
+
+Scope **2–4** candidates targeting product completeness; each with goals + trade-offs. Prefer deferred / roadmap `next` items.
+
+### 3. Lock Direction — autonomous（NOT grill-me）
+
+**Direction lock mode: `autonomous`**（显式 opt-in → **`mstar-iteration` §1.2**）。
+
+Execute **`mstar-iteration` §1.2 autonomous** direction lock（detail: `references/autonomous-direction-lock.md`）：
+
+1. If `direction` arg present → constrain candidates to that intent; pick the best evidence-backed fit.
+2. If absent → rank candidates（deferred/roadmap next > STRATEGY alignment > product completeness > risk）and **lock the recommended** direction.
+3. Write to compass: locked direction, rationale, success criteria, non-goals, scale budget.
+4. Resolve delivery branch policy via **autonomous branch resolve**（`references/autonomous-direction-lock.md`）— never silent `main`/`master`.
+
+**Do not** ask the user to confirm the chosen direction. Record rationale on disk instead.
+
+**STOP** if no credible candidate and no `direction` arg, or branch policy unresolved after resolve order.
+
+### 4. Write Compass & Plans
+
+Per **`mstar-iteration` §1.3–§1.5**（template: `iteration-compass-template.md`）:
+
+- Compass with `iteration_base_branch`, `target_branch`, `status: active`, scale budget noted in Scope / Plans
+- **Business** plan count within scale budget（exclude harness process from the count）
+- Register plans in `status.json`; update `{ITERATION_DIR}/README.md`
+
+### 5. Review & Edit Chain（HARD GATE）
+
+**顺序（HARD）**：`product-manager` → `architect` → `writing-specialist` → PM lock。**禁止**并行三角色。OpenCode：plain role id — **`mstar-host/references/opencode.md`** § Role-mention hygiene.
+
+| # | Role | Required action |
+|---|------|-----------------|
+| 5.1 | **product-manager** | invoke: **edit** compass, plans, `{SPECS_DIR}/`, `{ITERATION_DIR}/<iteration-id>/` — **禁止** `{KNOWLEDGE_DIR}/` 新增 |
+| 5.2 | **architect** | invoke: **edit** compass, plans, specs / workspace（含 5.1 后版本）— **禁止** knowledge 新增 |
+| 5.3 | **writing-specialist** | invoke: edit docs + **specs corpus hygiene** — `iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md` |
+| 5.4 | **project-manager** | Merge; **lock** compass (`status: locked`); confirm Prepare gates |
+
+Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（顺序链）。Exception: user waives ("PM-only review").
+
+### iteration-loop Phase 1 pre-commit checklist
+
+Print before §6; all must be `[x]`:
+
+- [ ] Autonomous direction lock rationale recorded in compass（not grill-me）
+- [ ] Scale budget applied; **business** plan count within S/M/L（harness process not counted）
+- [ ] Draft compass + plans + `status.json` registered
+- [ ] product-manager invoke completed；**未**向 `{KNOWLEDGE_DIR}/` 新增
+- [ ] architect invoke completed；**未**向 `{KNOWLEDGE_DIR}/` 新增
+- [ ] writing-specialist invoke completed；specs corpus hygiene done
+- [ ] PM final lock: compass `status: locked`; Prepare gates pass
+- [ ] Branch policy locked: `iteration_base_branch`, `spec_integration_branch`, `target_branch` in compass / `status.json`
+- [ ] **THEN**: git commit + push `iteration/<iteration-id>`
+
+### 6. Integration Branch
+
+**Precondition**: §5 complete.
+
+```bash
+git fetch origin   # if needed
+git checkout -b <spec_integration_branch> <iteration_base_branch>
+# or: git checkout <spec_integration_branch>  if it already exists
+```
+
+Register branch fields in compass + `status.json`. Commit docs; push.
+
+**STOP** if `iteration_base_branch` or `target_branch` still missing after autonomous resolve.
+
+**Immediately** print `## Phase 2: Autonomous Execute` → continue below（勾掉 `phase-1-autonomous-start`）。
+
+---
+
+## Phase 2: Autonomous Execute
+
+**Continuous execution applies.** Branch policy first（`mstar-iteration` §2.3）.
+
+Execute **`mstar-iteration` § Phase 2** exactly. Summary:
+
+1. Precondition gate §2.0（four checks）
+2. Session todos §2.1
+3. Read backlog §2.2
+4. Integration branch §2.3
+5. Per-plan loop §2.4 — **SDD** default; serial implementer → task reviewer; QC **full tri-review** N=3; QA gate; merge to integration; next plan
+6. All plans `Done` → print `## Phase 3: iteration-close` → **`mstar-iteration` §3**（不得开 PR）
+
+派发纪律 → **`mstar-dispatch-gates`** + **`mstar-iteration` §2.5**。
+
+## Phase 3: iteration-close
+
+当 every plan 为 `Done`：
+
+1. STOP per-plan loop
+2. Print `## Phase 3: iteration-close`
+3. Execute **`mstar-iteration` §3.0→§3.5**（compound + workspace promotion）
+4. Exit checklist `[x]` + compass `completed` → print `## Phase 4: Create PR`
+
+```bash
+git add {ITERATION_DIR}/ {KNOWLEDGE_DIR}/ CONCEPTS.md
+git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
+git push origin <spec_integration_branch>
+```
+
+## Phase 4: Create PR
+
+Execute **`mstar-iteration` § Phase 4**：
+
+1. Print `## Phase 4: Create PR`
+2. Resolve `metadata.target_branch`（compass fallback）；missing → STOP；never default `main`
+3. Create PR: `spec_integration_branch` → `target_branch`
+4. Record URL/number；勾掉 `phase-4-create-pr`
+5. **Immediately** print `## Phase 5: PR merge-ready` → Phase 5
+
+## Phase 5: PR merge-ready
+
+Execute **`mstar-iteration` § Phase 5**。**§5.5 exit 全 `[x]` = iteration-loop Done.**
+
+### 5.0 Discover optional helper skills（non-`mstar-*`）
+
+| Skill | Search paths（示例） |
+|-------|----------------------|
+| `greploop` | `skills/greploop/SKILL.md`；`~/.cursor/skills-cursor/greploop/SKILL.md`；`~/.agents/skills/greploop/SKILL.md` |
+| `babysit` | `skills/babysit/SKILL.md`；`~/.cursor/skills-cursor/babysit/SKILL.md`；`~/.agents/skills/babysit/SKILL.md` |
+
+| Priority | Condition | Primary done signal |
+|----------|-----------|---------------------|
+| 1 | `greploop` found | Greptile **5/5** |
+| 2 | else `babysit` | Required CI green + reviews resolved |
+| 3 | else neither | Same as babysit（本 command fallback） |
+
+Both present: greploop to 5/5, then babysit（串行）.
+
+### 5.1–5.4 Loop
+
+Same hygiene as drive consumer pattern: status → conflicts → reviews → CI → mode pass → comment+resolve on addressed threads → repeat until §5.5.
+
+Fixes push to `spec_integration_branch` only. PM does not rewrite product code in-thread.
+
+### 5.5 Phase 5 exit checklist（iteration-loop Done）
+
+与 **`mstar-iteration` §5.2** 对齐：
+
+- [ ] PR mergeable
+- [ ] All **required** CI checks green on latest head
+- [ ] All review threads **resolved**（或用户书面 waive）
+- [ ] Greptile **5/5**（若 greploop mode / repo 可见分数）
+- [ ] Review comment + resolve 已覆盖本轮 addressed feedback
+- [ ] Host todo `phase-5-pr-merge-ready` 可勾选
+
+**Then** report: iteration id, locked direction + scale, plans completed, compound summary, PR link, merge-ready evidence.
+
+PR merge itself may remain manual unless user authorized auto-merge.

package/harness-commands/iteration-start.md

@@ -22,17 +22,106 @@ Start a new Morning Star harness iteration. **Not Done until the Review & Edit c
 
 **完成定义**：compass `status: locked` + 三角色 invoke 已返回 + pre-commit checklist 全 `[x]` — 不是初稿落盘。
 
-Detailed workflow → **`mstar-iteration` § Phase 1: iteration-start**（含 §1.6 Review & Edit chain）；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
+Detailed workflow → **`mstar-iteration` § Phase 1**（含 §1.6 Review & Edit chain）；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
+
+**Path split（HARD）**：
+
+| 宿主上下文 | 走哪条 |
+|------------|--------|
+| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → §P（本命令 Plan 分支）— **先**空白 CreatePlan，再动态 grill-me 改文档；**Build 前不执行** Review 链 / commit / integration 分支 |
+| **其它**（Agent、OpenCode、非 Plan） | §0 Boot → §1–§6（Research → Explore → grill-me → Write → Review → branch） |
 
 ## 0. Boot
 
 1. `mstar-harness-core`
 2. `mstar-roles` → `references/project-manager.md`
-3. `mstar-iteration` → **§ Phase 1: iteration-start**（迭代范围、compass 模板、**§1.5.5 产物边界**、§1.6 Review & Edit chain、状态初始化）
+3. `mstar-iteration` → **§ Phase 1**（迭代范围、compass 模板、**§1.5.5 产物边界**、§1.6 Review & Edit chain、状态初始化）
 4. `mstar-dispatch-gates`
 5. `mstar-phase-gates` → Prepare（specify → clarify → plan）
 6. `mstar-plan-conventions`, `mstar-plan-artifacts`
-7. `mstar-host` → active host reference（invoke 能力）
+7. `mstar-host` → active host reference（invoke 能力）；若 Cursor Plan mode → 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）
+
+**若 Cursor Plan mode 活跃 → 进入 §P；否则继续 §1。**
+
+## P. Cursor Plan mode（Phase 1 scaffold → staged grill → Build）
+
+**Detect**：会话处于 Cursor Plan mode（系统要求 CreatePlan / SwitchMode，或 Plan 工具可用且当前为 Plan 会话）。
+
+**语义**：Plan 模式期间 **只维护 CreatePlan + SSOT 草稿**；**不**把 grill 段标成已执行 todo；**不**派发 Review 链；**不** commit；**不**建 integration 分支。点 **Build** 后才执行下方 Build todos（对齐 `mstar-host/references/cursor-plan-mode-bridge.md` · Phase 1 in Plan mode）。
+
+### P.1 Research（只读）
+
+执行与 §1 相同的调研（structured + unstructured + `STRATEGY.md`）。**不要**在本步写 compass/plans 终稿。
+
+### P.2 Early CreatePlan（空白脚手架 — 先于方向锁定）
+
+Research 后 **立刻** CreatePlan（**禁止**等 grill-me 全部完成再 CreatePlan）。
+
+**CreatePlan 最小结构**（session mirror；dual-write 草稿见 P.3）：
+
+```markdown
+# Phase 1: <iteration-id-or-TBD>
+
+## Direction
+TBD
+
+## Scope
+TBD
+
+## Acceptance Criteria
+TBD
+
+## Non-Goals
+TBD
+
+## Delivery Branch Policy
+| Field | Value |
+|-------|-------|
+| iteration_base_branch | TBD |
+| spec_integration_branch | TBD |
+| target_branch | TBD |
+
+## Plans
+| plan_id | Name | Status | Notes |
+|---------|------|--------|-------|
+| TBD | | Todo | |
+
+## Grill-me log
+（每段收敛后追加：日期 / 议题 / 决议）
+```
+
+**Build 才勾的 todos**（顺序；**不要**把 grill 段写成 Build todo）：
+
+1. `harness-init` — 若 `{HARNESS_DIR}` / `status.json` 缺失则初始化
+2. `finalize-compass-plans` — 将 CreatePlan 正文落成 compass + `{PLAN_DIR}/` plans + `status.json` 登记 + `{ITERATION_DIR}/README.md`
+3. `review-edit-product-manager` — §5.1 invoke
+4. `review-edit-architect` — §5.2 invoke
+5. `review-edit-writing-specialist` — §5.3 invoke
+6. `pm-lock` — §5.4 compass `status: locked` + Prepare gates
+7. `integration-branch` — §6
+
+### P.3 Dynamic grill-me（不固定段数）
+
+**Before this step:** Read `skills/grill-me/SKILL.md`（**仅本命令**引用；勿从 `mstar-*` 加载）。
+
+**Direction lock mode: `interactive`**。按决策树 **动态切段**（段数不固定；随用户需求增减）：
+
+- 一段一问；能靠读代码回答的先探索代码
+- 每段收敛后 **立刻** 更新 CreatePlan body（Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans 表）并 **追加** `## Grill-me log`
+- 同轮 dual-write SSOT **草稿**（可选但推荐）：`{ITERATION_DIR}/` compass stub、`{PLAN_DIR}/` plan stubs、`status.json` 业务 plan 行（方向收敛后至少有草稿登记）
+- **禁止**：固定死 4/5 段；把 grill 标成「已执行完的 todo」；Plan 模式内派发 §5 / commit / §6
+
+用户表示方向/范围已够用、可 Build 时 → 停止 grill；确认 CreatePlan 与草稿 SSOT 已反映锁定内容。
+
+### P.4 Build（执行 Phase 1 可执行门禁）
+
+用户点击 **Build**（或 Plan → Agent）后：
+
+1. 按 Build todos 顺序执行：`harness-init` → `finalize-compass-plans` → §5 Review 链（5.1→5.2→5.3）→ `pm-lock` → §6
+2. **禁止**把 Build 当成重新跑一遍 grill-me
+3. pre-commit checklist（见 §5）全 `[x]` 后再 commit / push integration 分支
+
+**非 Plan 路径从这里继续 ↓**
 
 ## 1. Research
 
@@ -57,6 +146,8 @@ Also read `STRATEGY.md`（if exists）for strategic alignment.
 
 ## 2. Explore Directions
 
+> **非 Plan 路径**。Cursor Plan mode 已在 §P 处理；勿与 §P 并行再跑一遍。
+
 Explore candidate directions targeting **product completeness**:
 
 - Default to completing deferred items from previous iterations
@@ -65,7 +156,11 @@ Explore candidate directions targeting **product completeness**:
 
 ## 3. Lock Direction — bundled `grill-me`
 
-This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step** references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
+> **非 Plan 路径**。Cursor Plan mode 用 §P.3 动态 grill-me（先 CreatePlan 再分阶段改文档）。
+
+**Direction lock mode: `interactive`**（`mstar-iteration` §1.2 默认；本命令不使用 `autonomous`）。
+
+This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step**（及 §P.3）references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
 
 **Before this step:** Read `skills/grill-me/SKILL.md`.
 
@@ -81,6 +176,8 @@ Run **grill-me** to stress-test candidate directions with the user:
 
 ## 4. Write Compass & Plans
 
+> **非 Plan 路径**。Plan mode 在 §P.2–P.3 维护草稿，Build 时由 `finalize-compass-plans` 落盘终稿。
+
 Produce harness artifacts per **`mstar-iteration` § 1.3**（template: `mstar-iteration/references/iteration-compass-template.md`）：
 
 - `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`

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

@@ -183,6 +183,23 @@ When `/pm` runs under Plan mode:
 - Prepare phase (`specify → clarify → plan`) still applies; `mirror-plan` is the harness **`plan`** artifact, not a substitute for clarify.
 - Before QC dispatch, read **`mstar-review-qc`** (unchanged).
 
+## `mstar-iteration` Phase 1 in Plan mode
+
+When starting a **new iteration** under Cursor Plan mode (host command may orchestrate Phase 1):
+
+| Phase | Behavior | Forbidden |
+|-------|----------|-----------|
+| Early CreatePlan | After read-only research, **immediately** CreatePlan with blank Phase 1 scaffold (Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans / Grill log placeholders) + Build-bound todos | Wait until interactive direction lock finishes before CreatePlan |
+| Staged interactive lock | Dynamic number of clarify stages in the Plan session; after each stage, **update CreatePlan body** and dual-write SSOT **drafts** (`{ITERATION_DIR}` compass stub, `{PLAN_DIR}` plan stubs, `status.json` rows when direction converges) | Treat lock stages as completed Build todos; fix a hard-coded stage count; dispatch Review & Edit / commit / integration branch |
+| Pre-Build | Maintain documents only | Execute Review chain, commit, or create `spec_integration_branch` |
+| Build | Run Phase 1 executable todos: finalize SSOT → sequential Review & Edit (`product-manager` → `architect` → `writing-specialist`) → PM lock → integration branch | Replay interactive direction lock as if Plan session never happened |
+
+**Plan mode ≠ executing todos.** Build = Phase 1 executable gate (Review chain, lock, branch).
+
+**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.
+
+**Helpers**: third-party interview helpers are **not** named here; host **command** layer discovers them when needed.
+
 ## Anti-patterns
 
 | Anti-pattern | Fix |
@@ -194,6 +211,8 @@ When `/pm` runs under Plan mode:
 | Skip `spec-register` | Add `plans[]` row before implement |
 | Build starts coding in the parent session | Resume PM context; dispatch implement work or block on missing Assignment |
 | Follow-up only in chat / no roadmap section | Add `Roadmap / deferred scope` to CreatePlan and SSOT plan before implement |
+| Phase 1 Plan mode: grill/lock finishes before first CreatePlan | CreatePlan blank scaffold first; update body each lock stage |
+| Phase 1 Plan mode: Review / commit / branch before Build | Keep Pre-Build document-only; execute those todos after Build |
 
 ## Related skills
 

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

@@ -29,6 +29,8 @@ Before **SwitchMode → Agent**: mirror plan exists; `status.json` lists `plan_i
 
 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.
 
+**`mstar-iteration` Phase 1 in Plan mode**: CreatePlan blank scaffold **before** interactive direction lock; update CreatePlan + SSOT drafts each lock stage; **do not** run Review & Edit / commit / integration branch until **Build**. Detail → **`cursor-plan-mode-bridge.md`** § `mstar-iteration` Phase 1 in Plan mode.
+
 Enforcement: `rules/mstar-cursor-plan-mode.mdc` when plugin active.
 
 ## `/pm` precedence

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-iteration
-description: Morning Star 迭代管理 —— iteration-start（specs + `<iteration-id>/` workspace；禁止直写 knowledge）、Autonomous Execute、iteration-close（compound 提升 workspace → knowledge）、PR 交付、PR merge-ready loop。分支 SSOT：`status.json` + compass frontmatter。
+description: Morning Star 迭代管理 —— Phase 1（默认 interactive direction lock；opt-in autonomous；specs + `<iteration-id>/` workspace；禁止直写 knowledge）、Autonomous Execute、iteration-close（compound 提升 workspace → knowledge）、PR 交付、PR merge-ready loop。分支 SSOT：`status.json` + compass frontmatter。
 ---
 
 # mstar-iteration（迭代管理）
@@ -69,7 +69,7 @@ PM 在新迭代启动时执行。
 
 ### 1.2 定义迭代范围
 
-与用户/产品对齐后，确定：
+与用户/产品对齐后（或按下方 **autonomous** 模式锁定后），确定：
 
 | 字段 | 说明 |
 |------|------|
@@ -81,10 +81,24 @@ PM 在新迭代启动时执行。
 | **非目标** | 明确排除在本次迭代外的事项 |
 | **Roadmap 上下文** | 本迭代在整体 roadmap 中的位置（current iteration / next iteration） |
 | **Delivery branch policy** | `iteration_base_branch`（integration 分支从何处分出）、`spec_integration_branch`、`target_branch`（最终 PR 目标） |
+| **Scale budget**（可选） | 仅当 caller **显式**给出或选用 **autonomous** 时适用：`S` = 1 **业务** plan；`M` = 2–3；`L` = 3–4（默认上限 4）。**只计实际业务交付 plan**，不计 harness 流程性工作（Review 链 / QC / QA / compound / close / PR 等）。**interactive 默认不强制** S/M/L。计数细则 → **`references/autonomous-direction-lock.md`** § Scale budget |
 
-**Branch policy gate**：若用户、现有 roadmap、或项目约定未明确 `iteration_base_branch` / `target_branch`，PM 必须检查当前分支并向用户确认。**不得**因为存在 `main` / `master` 就默认从默认分支开 iteration 或向默认分支提 PR。
+#### Direction lock modes
 
-**Direction lock**：compass/plans 初稿落盘前，PM 须与用户逐问收敛**单一**迭代方向、成功标准、非目标，并确认 delivery branch policy；决策写入 compass `## Scope` / `## Acceptance Criteria` / `## Non-Goals` 与 Delivery Branch Policy。
+compass/plans 初稿落盘前，必须锁定**单一**迭代方向、成功标准、非目标，并确认 delivery branch policy；决策写入 compass `## Scope` / `## Acceptance Criteria` / `## Non-Goals` 与 Delivery Branch Policy。
+
+| Mode | 何时选用 | 行为 |
+|------|----------|------|
+| **`interactive`** | **默认**（未显式声明 mode 时一律用此） | 与用户/产品**逐问**收敛方向与 branch policy；不得静默默认 `main`/`master` |
+| **`autonomous`** | **仅**当 caller / Assignment **显式**声明 `Direction lock mode: autonomous`（或等价书面 opt-in） | 代码优先调研 → 排序候选 → **锁定推荐方向并落盘 rationale**；不因「是否同意该方向」例行问用户。细则 → **`references/autonomous-direction-lock.md`** |
+
+**宿主 Plan UX（interactive）**：若宿主提供 Plan 会话（先写 session plan、后点 Build 才执行 todos），允许 **先 scaffold 空白 Phase 1 文档/todos，再分阶段收敛**方向与 branch policy，并在每段收敛后更新 scaffold；**非** Plan 会话仍按「收敛后再写 compass/plans 初稿」的默认顺序。此条 **不**改变 autonomous 路径，也 **不**要求非 Plan 宿主先写空文件。
+
+**禁止**：在未显式 opt-in 时自行切换到 `autonomous`（例如仅因读了本 skill 或存在 roadmap next）。
+
+**Branch policy gate（interactive — 默认路径）**：若用户、现有 roadmap、或项目约定未明确 `iteration_base_branch` / `target_branch`，PM 必须检查当前分支并向用户确认。**不得**因为存在 `main` / `master` 就默认从默认分支开 iteration 或向默认分支提 PR。
+
+**Autonomous branch resolve**：仅 `autonomous` 模式；解析顺序与 STOP 规则见 **`references/autonomous-direction-lock.md`**（勿把该顺序套用到 interactive 以跳过向用户确认）。
 
 ### 1.3 创建迭代 compass
 
@@ -460,6 +474,7 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 | `references/iteration-artifact-boundaries.md` | Phase 1 specs / iterations workspace / knowledge 分工 |
 | `references/iteration-workspace-readme-template.md` | `<iteration-id>/README.md` 可选模板 |
 | `references/iteration-corpus-hygiene.md` | §1.6 writing-specialist specs 卫生细则 |
+| `references/autonomous-direction-lock.md` | §1.2 autonomous direction lock、scale budget、branch resolve |
 | `mstar-strategy` | iteration-start 时读 `STRATEGY.md` 对齐方向 |
 
 ## NOT to do
@@ -480,3 +495,6 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 - **不要在 iteration-close 跳过 `<iteration-id>/` workspace 盘点**（compound 提升 SSOT → **`mstar-compound`**）
 - **不要在 iteration-start §1.6 跳过 writing-specialist 全库 specs corpus hygiene**（仅改当轮 compass/plans 而不扫 `{SPECS_DIR}/`）
 - **不要在 SDD plan 上以单席 `qc.md` 收尾**（除非用户书面 `QC mode: single — override`）
+- **不要在未显式 `Direction lock mode: autonomous` 时跳过与用户收敛方向**（interactive 仍为默认）
+- **不要在 `autonomous` mode 下例行问用户「是否同意该方向」**（须落盘 rationale；无候选且无约束时 STOP）
+- **不要把 harness 流程（Review 链 / QC / QA / compound / close / PR 等）计进 Scale budget 的 plan 数量**，也不得为此单独建 process plan 占坑

package/harness-skills/mstar-iteration/references/autonomous-direction-lock.md

@@ -0,0 +1,89 @@
+# Autonomous direction lock
+
+Capability detail for Phase 1 when direction lock mode is **`autonomous`**.
+
+**Opt-in only.** Default Phase 1 mode remains **`interactive`** (user-converged). Do **not** apply this reference unless the caller / Assignment explicitly declares `Direction lock mode: autonomous` (or equivalent written opt-in). Reading this file alone is not opt-in.
+
+## Preconditions
+
+- Research (§1.1) and candidate exploration already done — **read repo artifacts before ranking**.
+- Do not invent roadmap items that have no file or status evidence.
+- Scale budget (`S`/`M`/`L`) applies in this mode (or when the caller supplies one); do not retrofit a scale cap onto an interactive start that never asked for one.
+
+## Ranking heuristics（highest first）
+
+1. **Deferred / roadmap next** — prior compass `## Roadmap Position` next iteration, deferred-features, residuals marked for follow-up
+2. **STRATEGY alignment** — `STRATEGY.md` vision / decision principles when present
+3. **Product completeness** — closes a user-visible gap or unfinished capability
+4. **Risk / blast radius** — prefer smaller, shippable slices when candidates are otherwise equal
+
+Document trade-offs for **each** shortlisted candidate (2–4), then lock **one**.
+
+## Lock outputs（must land on disk）
+
+Write into compass (and plan Scope as needed):
+
+| Field | Content |
+|-------|---------|
+| Locked direction | Single sentence |
+| Rationale | Why this candidate won（cite paths / roadmap lines） |
+| Acceptance criteria | Iteration-level Done |
+| Non-goals | Explicit exclusions |
+| Scale budget | `S` \| `M` \| `L` and resulting plan-count cap |
+
+## Scale budget
+
+| Budget | **Business** plan count |
+|--------|-------------------------|
+| `S` | 1 |
+| `M` | 2–3 |
+| `L` | 3–4（default cap 4 unless a written constraint requires more） |
+
+### What counts toward the budget（HARD）
+
+Count only **business delivery plans** registered in compass / `status.json` whose primary outcome is product, feature, bugfix, user-facing docs, API/contract, or architecture work for the locked direction.
+
+**Do not count** harness / process work as plans (and do not invent plans whose sole job is process):
+
+| Exclude from scale count | Examples |
+|--------------------------|----------|
+| Phase 1 process | Research, direction lock, Review & Edit chain, compass/index/`status.json` bootstrap |
+| Phase 2 process | Per-task SDD briefs/reviews, plan QC tri, QA gate, branch merge-back |
+| Phase 3–5 process | Compound / workspace promotion, iteration-close, Create PR, merge-ready / CI babysit |
+| Meta “plans” | “run QC”, “do compound”, “open PR”, “setup harness”, “write compass only” |
+
+Harness steps remain **mandatory gates** outside the budget — they do not consume S/M/L slots and must not be padded into the plan list to “fill” the budget.
+
+If evidence suggests more **business** work than the budget allows, keep overflow in compass `## Roadmap Position` → next iteration — do not silently expand past the budget, and do not replace business plans with process plans to stay under the cap.
+
+## Direction constraint（optional input）
+
+When a free-text direction / feedback constraint is supplied by the caller:
+
+- Filter or re-rank candidates to fit that intent
+- Still require code/roadmap evidence; do not lock a direction that contradicts the repo without documenting the conflict
+- If constraint and evidence conflict irreconcilably → **Blocked**（escalate）
+
+## Autonomous branch resolve
+
+**Only in `autonomous` mode.** Do not use this order to skip user confirmation under `interactive`.
+
+Resolve `iteration_base_branch` and `target_branch` in order（first hit wins per field）:
+
+1. `{HARNESS_DIR}/status.json` root `metadata`
+2. Existing / prior iteration compass frontmatter
+3. Current git branch **only if** it is already a documented delivery, integration, or project-policy branch（not merely “whatever HEAD is”）
+4. Still missing → **STOP** — escalate; **never** substitute `main` / `master` because those names exist
+
+`spec_integration_branch` defaults to `iteration/<iteration-id>` once base/target are known.
+
+## Anti-patterns
+
+- Applying this reference without explicit autonomous opt-in
+- Asking the user “do you agree with this direction?” as a routine gate in autonomous mode
+- Locking without reading roadmap / status / STRATEGY when those files exist
+- Silent default to `main` / `master` for base or PR target
+- Skipping written rationale because “it was obvious”
+- Forcing S/M/L plan caps on interactive starts that did not request a scale budget
+- Counting harness process (Review chain / QC / QA / compound / close / PR) toward the scale budget
+- Creating process-only plans to fill or absorb S/M/L slots

package/package.json

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