npm - @mstar-harness/opencode - Versions diffs - 1.3.0 → 1.3.2 - Mend

@mstar-harness/opencode 1.3.0 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,19 @@ 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.3.2
+- Bundled commands: `/iteration-start` Cursor Plan path — feedback-driven plan updates; deferred grill after feedback-close; single CreatePlan URI (in-place edits only).
+- Bundled skills: `mstar-iteration` §1.2 Plan UX feedback-driven + recommended branch policy; `mstar-host` Cursor Phase 1 bridge/rule.
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.3.2**.
+## 1.3.1
+- Bundled skills/commands: iteration package layout — `{ITERATION_DIR}/<id>/delivery-compass.md` + sibling `guides/` / `specs/`; one-row root iteration index; legacy flat compass read-compat.
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.3.1**.
 ## 1.3.0
 - Bundled commands: retire `/mstar-bootstrap`; bootstrap procedure → `mstar-compound-refresh/references/project-knowledge-bootstrap.md`.

package/harness-commands/iteration-drive.md CHANGED Viewed

@@ -131,7 +131,7 @@ Execute **`mstar-iteration` § Phase 2** exactly. Summary:
 |------|---------|------|
 | 1 | §3.0 / §3.0.5 | Phase 边界；legacy compass 规范化（frontmatter + `## Roadmap Position`） |
 | 2 | §3.1 | 打印 close entry checklist，全部 `[x]` |
-| 3 | §3.2 | Compound + **`<iteration-id>/` workspace promotion**；新增 doc 完成 `mstar-compound` Phase 6（`{KNOWLEDGE_DIR}/README.md`） |
+| 3 | §3.2 | Compound + **`<iteration-id>/` package promotion**；新增 doc 完成 `mstar-compound` Phase 6（`{KNOWLEDGE_DIR}/README.md`） |
 | 4 | §3.3 | `## Roadmap Position` current iteration → `delivered`；STRATEGY/tracker 按需更新 |
 | 5 | §3.4 | frontmatter `status: completed` + `end_date`；Compound Summary + Retrospective |
 | 6 | §3.5 | 打印 close exit checklist → commit → push |

package/harness-commands/iteration-loop.md CHANGED Viewed

@@ -178,7 +178,7 @@ Per **`mstar-iteration` §1.3–§1.5**（template: `iteration-compass-template.
 | # | 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.2 | **architect** | invoke: **edit** compass, plans, specs / package（含 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 |
@@ -237,7 +237,7 @@ Execute **`mstar-iteration` § Phase 2** exactly. Summary:
 1. STOP per-plan loop
 2. Print `## Phase 3: iteration-close`
-3. Execute **`mstar-iteration` §3.0→§3.5**（compound + workspace promotion）
+3. Execute **`mstar-iteration` §3.0→§3.5**（compound + package promotion）
 4. Exit checklist `[x]` + compass `completed` → print `## Phase 4: Create PR`
 ```bash

package/harness-commands/iteration-start.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: iteration-start
-description: Start a new harness iteration — research, grill-me, compass/plans, Review & Edit chain (long-lived {SPECS_DIR}/ + {ITERATION_DIR}/<id>/ workspace; compound promotes workspace at close only), PM lock, integration branch.
+description: Start a new harness iteration — research, grill-me, compass/plans, Review & Edit chain (long-lived {SPECS_DIR}/ + {ITERATION_DIR}/<id>/ package; compound promotes package at close only), PM lock, integration branch.
 agent: project-manager
 ---
@@ -28,7 +28,7 @@ Detailed workflow → **`mstar-iteration` § Phase 1**（含 §1.6 Review & Edit
 | 宿主上下文 | 走哪条 |
 |------------|--------|
-| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → §P（本命令 Plan 分支）— **先**空白 CreatePlan，再动态 grill-me 改文档；**Build 前不执行** Review 链 / commit / integration 分支 |
+| **Cursor Plan mode**（CreatePlan / Plan 会话活跃） | §0 Boot → §P — **先**空白 CreatePlan，再 **feedback-driven** 自主改同一份 plan；grill-me **仅**在用户明确结束反馈后、仍有阻塞疑问时；**Build 前不执行** Review 链 / commit / integration 分支 |
 | **其它**（Agent、OpenCode、非 Plan） | §0 Boot → §1–§6（Research → Explore → grill-me → Write → Review → branch） |
 ## 0. Boot
@@ -43,19 +43,28 @@ Detailed workflow → **`mstar-iteration` § Phase 1**（含 §1.6 Review & Edit
 **若 Cursor Plan mode 活跃 → 进入 §P；否则继续 §1。**
-## P. Cursor Plan mode（Phase 1 scaffold → staged grill → Build）
+## P. Cursor Plan mode（Phase 1 scaffold → feedback loop → deferred 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）。
+**语义**：Plan 模式期间 **只维护 CreatePlan + SSOT 草稿**；用户侧是 **纯反馈**（提方向 / 提意见），**不是**答问卷。Agent **探索 + 推荐并直接改 plan**。**不**派发 Review 链；**不** commit；**不**建 integration 分支。点 **Build** 后才执行下方 Build todos（对齐 `mstar-host/references/cursor-plan-mode-bridge.md` · Phase 1 in Plan mode）。
+### P.0 Single CreatePlan URI（HARD — 防双 plan）
+| 规则 | 说明 |
+|------|------|
+| **CreatePlan 只调用一次** | §P.2 空白脚手架是本会话 **唯一** 一次 CreatePlan |
+| **记录路径** | 记下工具返回的 plan 文件路径（常在 `~/.cursor/plans/*.plan.md`）；后续所有修订都写 **这一份** |
+| **更新方式** | Feedback / deferred grill 后用 **Read + Write/StrReplace 原地改** 该文件；**禁止**再调 CreatePlan 开第二份 |
+| **发现重复** | 若已误开第二份：把有效内容 **合并进第一份**，删除重复文件，并确保用户 View Plan 指向第一份 |
 ### P.1 Research（只读）
 执行与 §1 相同的调研（structured + unstructured + `STRATEGY.md`）。**不要**在本步写 compass/plans 终稿。
-### P.2 Early CreatePlan（空白脚手架 — 先于方向锁定）
+### P.2 Early CreatePlan（空白脚手架 — 本会话唯一一次）
-Research 后 **立刻** CreatePlan（**禁止**等 grill-me 全部完成再 CreatePlan）。
+Research 后 **立刻** CreatePlan **一次**（**禁止**等方向锁定完成再 CreatePlan；**禁止**之后再 CreatePlan）。
 **CreatePlan 最小结构**（session mirror；dual-write 草稿见 P.3）：
@@ -86,39 +95,62 @@ TBD
 |---------|------|--------|-------|
 | TBD | | Todo | |
-## Grill-me log
-（每段收敛后追加：日期 / 议题 / 决议）
+## Feedback log
+（吸收用户反馈 / agent 推荐决议后追加）
+## Deferred grill log
+（仅 P.3.5 若发起 grill 时追加；可空）
 ```
-**Build 才勾的 todos**（顺序；**不要**把 grill 段写成 Build todo）：
+**Build 才勾的 todos**（顺序；**不要**把 feedback / 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`
+2. `finalize-compass-plans` — 将 **同一份** CreatePlan 正文落成 compass + `{PLAN_DIR}/` plans + `status.json` 登记 + `{ITERATION_DIR}` 索引
 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（不固定段数）
+### P.3 Feedback loop（主路径 — 直到用户明确结束反馈）
+**用户模式**：提方向、提意见、纠正推荐 — **纯反馈**。**不要**把用户当成问卷答题人；**禁止**例行一问一答卡更新。
+**Agent 每轮**（可多轮，直到用户喊停）：
+1. 探索代码 / harness / roadmap（能靠读回答的先读）
+2. 形成推荐（Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans）
+3. **立刻**原地更新 **§P.2 那一份** CreatePlan（含 `## Feedback log`）+ 推荐 dual-write SSOT 草稿
+4. 吸收用户新反馈 → 再探索/再改 **同一份** plan
+**Branch policy**：在 plan 中写入 **推荐值 + 简短 rationale**（不得静默默认 `main`/`master`）；用户可用反馈改掉。**不要**在本阶段为 branch 开 grill。
+**禁止**：
+- 再调 CreatePlan / 写到另一份 plan 文件
+- 把「等用户回答问题」当作更新 plan 的门禁
+- 在用户结束反馈前加载 / 运行 `grill-me`
+- 固定死反馈轮数；Plan 模式内派发 §5 / commit / §6
+### P.3.5 Feedback-close → deferred grill（可选）
-**Before this step:** Read `skills/grill-me/SKILL.md`（**仅本命令**引用；勿从 `mstar-*` 加载）。
+**触发**：用户明确表示反馈结束（例如：反馈结束、总结、分析反馈、可以了、准备 Build）。
-**Direction lock mode: `interactive`**。按决策树 **动态切段**（段数不固定；随用户需求增减）：
+然后 Agent 自检 CreatePlan：Direction / Scope / Acceptance / Non-Goals / Branch policy / Plans 是否仍有 **阻塞缺口**。
-- 一段一问；能靠读代码回答的先探索代码
-- 每段收敛后 **立刻** 更新 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
+| 结果 | 动作 |
+|------|------|
+| **无阻塞缺口** | **不**开 grill-me；宣布可 Build；确认同一份 CreatePlan + 草稿 SSOT 已反映锁定内容 |
+| **仍有阻塞缺口** | Read `skills/grill-me/SKILL.md`（**仅本命令**）；对 **剩余缺口** 做最小 grill（一段一问）；每段收敛后仍 **原地改同一份** CreatePlan，并追加 `## Deferred grill log` |
-用户表示方向/范围已够用、可 Build 时 → 停止 grill；确认 CreatePlan 与草稿 SSOT 已反映锁定内容。
+**Direction lock mode** 仍为 interactive 语义，但 Plan 会话的 **主路径是 feedback-driven**；grill 是 close 后门禁，不是主循环。
 ### 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
+1. 按 Build todos 顺序执行：`harness-init` → `finalize-compass-plans`（以 **View Plan 打开的那一份** CreatePlan 为准）→ §5 Review 链（5.1→5.2→5.3）→ `pm-lock` → §6
+2. **禁止**把 Build 当成重新跑 feedback / grill
 3. pre-commit checklist（见 §5）全 `[x]` 后再 commit / push integration 分支
 **非 Plan 路径从这里继续 ↓**
@@ -156,11 +188,11 @@ Explore candidate directions targeting **product completeness**:
 ## 3. Lock Direction — bundled `grill-me`
-> **非 Plan 路径**。Cursor Plan mode 用 §P.3 动态 grill-me（先 CreatePlan 再分阶段改文档）。
+> **非 Plan 路径**。Cursor Plan mode 用 §P.3 feedback loop + §P.3.5 deferred grill（主路径不是 grill）。
 **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.
+This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step**（及 §P.3.5 deferred grill）references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
 **Before this step:** Read `skills/grill-me/SKILL.md`.
@@ -176,14 +208,15 @@ 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` 落盘终稿。
+> **非 Plan 路径**。Plan mode 在 §P.2–P.3.5 维护 **同一份** CreatePlan 草稿，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`
+- `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`
 - `{PLAN_DIR}/<plan-id>-<name>.md` for each plan in this iteration
 - Register all plans in `{HARNESS_DIR}/status.json`（per `mstar-plan-artifacts` §1.5：root `metadata` + plan `spec_integration_branch`）
-- Update `{ITERATION_DIR}/README.md` index（per `mstar-iteration` § 1.4）
+- Update `{ITERATION_DIR}/README.md` index（**一行 = 一次迭代**；per `mstar-iteration` § 1.4）
+- Create package dirs as needed: `{ITERATION_DIR}/<iteration-id>/{guides,specs}/` + optional package `README.md`
 ## 5. Review & Edit Chain（HARD GATE — do not commit before this）
@@ -196,7 +229,7 @@ Each role below **reviews and directly edits** the documents. Do not just flag i
 | # | Role | Required action | Gate |
 |---|------|-----------------|------|
 | 5.1 | **product-manager** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, **`{ITERATION_DIR}/<iteration-id>/`**（`guides/`、`specs/` 按需）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 完成后方可 5.2 |
-| 5.2 | **architect** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, workspace `specs/`（含 5.1 后版本）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 5.1 返回后；完成后方可 5.3 |
+| 5.2 | **architect** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, package `specs/`（含 5.1 后版本）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 5.1 返回后；完成后方可 5.3 |
 | 5.3 | **writing-specialist** | invoke: **edit** compass / plans / specs / iteration 文档; **specs corpus hygiene**（全库 `{SPECS_DIR}/` + 既有 `{KNOWLEDGE_DIR}/` 卫生与错放纠正，**不**新增 knowledge）— `mstar-iteration/references/iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md` | 5.2 返回后 |
 | 5.4 | **project-manager** | Merge subagent edits; resolve conflicts; **lock** compass (`status: locked`); confirm Prepare gates | 5.3 返回后 |
@@ -223,9 +256,9 @@ Only after 5.4 → proceed to §6.
 PM must print this block before §6; all `[ ]` must be `[x]`:
-- [ ] grill-me decisions recorded in compass
+- [ ] direction lock decisions recorded in compass（Plan 路径：Feedback log + 可选 Deferred grill log；非 Plan：grill-me）
 - [ ] Draft compass + plans + `status.json` registered
-- [ ] product-manager invoke completed — compass / plans / specs / **`<iteration-id>/` workspace**（按需）；**未**向 `{KNOWLEDGE_DIR}/` 新增
+- [ ] product-manager invoke completed — compass / plans / specs / **`<iteration-id>/` package**（按需）；**未**向 `{KNOWLEDGE_DIR}/` 新增
 - [ ] architect invoke completed — compass / **specs** edited；**未**向 `{KNOWLEDGE_DIR}/` 新增
 - [ ] writing-specialist invoke completed — specs + iteration docs edited；**specs corpus hygiene** done（全库 `{SPECS_DIR}/`；既有 knowledge 仅卫生/归档；错放已迁回 `iterations/` 或 archive）
 - [ ] PM final lock: compass `status: locked`; Prepare gates pass (blocked plans documented)

package/harness-skills/mstar-compound/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: mstar-compound
-description: Morning Star 知识结晶 —— 将已解决问题的经验沉淀为结构化知识文档，存入 `{KNOWLEDGE_DIR}`；迭代收口时从 `{ITERATION_DIR}/<iteration-id>/` 工作区提升 specs/guides。支持 Bug track 与 Knowledge track 双轨。含重叠检测、可发现性检查、CONCEPTS.md 协同。触发：iteration-close（`mstar-iteration` §3.2）或独立触发。产出：`{KNOWLEDGE_DIR}/<category>/<slug>.md`。
+description: Morning Star 知识结晶 —— 将已解决问题的经验沉淀为结构化知识文档，存入 `{KNOWLEDGE_DIR}`；迭代收口时从 `{ITERATION_DIR}/<iteration-id>/` package 提升 specs/guides。支持 Bug track 与 Knowledge track 双轨。含重叠检测、可发现性检查、CONCEPTS.md 协同。触发：iteration-close（`mstar-iteration` §3.2）或独立触发。产出：`{KNOWLEDGE_DIR}/<category>/<slug>.md`。
 ---
 # mstar-compound（知识结晶）
@@ -79,18 +79,18 @@ iteration-start → [plan lifecycle × N: specify→...→Done] → iteration-cl
 迭代内所有 plan Done 后，PM 回顾整轮迭代中产生的可结晶知识，批量 compound。per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动。
-### Iteration workspace promotion（iteration-close 强制盘点）
+### Iteration package promotion（iteration-close 强制盘点）
-正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代的 workspace：
+正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代的 package：
-**路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；不含根目录 `*-delivery-compass.md` 除非 PM 显式纳入）。
+**路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；**默认排除** `delivery-compass.md` 除非 PM 显式纳入。Legacy 根目录 `*-delivery-compass.md` 同理排除）。
 | 步骤 | 动作 |
 |------|------|
-| 1. Inventory | 列出 workspace 下全部 `.md`；读各文件 + workspace `README.md`（若有） |
+| 1. Inventory | 列出 package 下全部 `.md`（除默认排除的 compass）；读各文件 + package `README.md`（若有） |
 | 2. Triage | 每篇：**Promote** / **Keep snapshot** / **Skip**（理由写入 compound 摘要） |
 | 3. Promote | 值得跨迭代复用 → 走 Q1–Q8（或轻量判定）→ Phase 2 重叠检测 → Phase 3–6 **结构化重写**进 `{KNOWLEDGE_DIR}/`（**禁止**无改写整文件复制） |
-| 4. Trace | 源文件顶栏或 workspace README：`Promoted to: <knowledge-path>`；`{KNOWLEDGE_DIR}/README.md` 的 Source 可记 `iteration:<iteration-id>/<relpath>` |
+| 4. Trace | 源文件顶栏或 package README：`Promoted to: <knowledge-path>`；`{KNOWLEDGE_DIR}/README.md` 的 Source 可记 `iteration:<iteration-id>/<relpath>` |
 | 5. Summary | PM 写入 compass `## Compound Round Summary`：提升篇数、保留快照、跳过及原因 |
 **Promote 典型**：迭代 spec 已验证且指导未来实现；guide 含非显而易见的过程知识或失败尝试。
@@ -134,7 +134,7 @@ In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
 ## Phase 1: Gather context
-Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** workspace per **Iteration workspace promotion** above.
+Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** package per **Iteration package promotion** above.
 Understand:
 - What problem was solved (the concrete issue)

package/harness-skills/mstar-dispatch-gates/SKILL.md CHANGED Viewed

@@ -95,7 +95,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 - PM 写初稿；各角色通过宿主 invoke **直接编辑**目标文件（**不**另写仅评论式 `reports/` 替代修订）。
 - **1 Assignment ⇒ 1 invoke**。
-- **Phase 1 Review & Edit chain**（`mstar-iteration` §1.6）：主产出 **`{SPECS_DIR}/`** + **`{ITERATION_DIR}/<iteration-id>/`** workspace；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增。close 时 **`mstar-compound`** 提升 workspace → knowledge。
+- **Phase 1 Review & Edit chain**（`mstar-iteration` §1.6）：主产出 **`{SPECS_DIR}/`** + **`{ITERATION_DIR}/<iteration-id>/`** package；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增。close 时 **`mstar-compound`** 提升 package → knowledge。
 - 其他彼此独立、无先后依赖的文档编辑任务：可并行（同条消息发满 N），见 **`parallel-dispatch.md`**。
 - PM 线程代做全部专业编辑 = **反模式**（`mstar-iteration` §1.6、`mstar-harness-core` 反模式索引）。
 - PM merge / lock（如 compass `status: locked`）在链末 subagent 返回后于 PM 线程完成。**不得**在 review-and-edit 链完成前 commit integration 分支。

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

@@ -189,16 +189,21 @@ When starting a **new iteration** under Cursor Plan mode (host command may orche
 | 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 |
+| Early CreatePlan | After read-only research, **CreatePlan once** with blank Phase 1 scaffold + Build-bound todos; **record the returned plan file path** | Wait until direction lock finishes; call CreatePlan again later |
+| Feedback loop | User gives **direction / opinions only** (no questionnaire). Agent explores, recommends, and **edits that same plan file in place** (+ SSOT drafts). Absorb feedback → update again | Routine one-question-at-a-time interview; gate plan updates on user answers; write a second `*.plan.md`; open interview helpers before feedback-close |
+| Feedback-close | When user signals feedback done (e.g. 反馈结束 / 总结 / 准备 Build): if blocking gaps remain → **minimal** deferred interview on gaps only, still editing the **same** plan file; else ready for Build | Start the interview helper as the main Plan-session loop |
 | 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 |
+| Build | Finalize SSOT from the **same** CreatePlan body → sequential Review & Edit → PM lock → integration branch | Replay feedback/interview; finalize from a different plan URI than View Plan |
+**Single CreatePlan URI (HARD)**: one CreatePlan per Phase 1 Plan session. Updates use file edit tools on that path. If a duplicate plan file was created by mistake: merge into the original, delete the duplicate, keep View Plan on the original.
 **Plan mode ≠ executing todos.** Build = Phase 1 executable gate (Review chain, lock, branch).
+**Branch policy in Plan session**: write **recommended** `iteration_base_branch` / `target_branch` (+ short rationale) into the plan — do **not** silently default to `main`/`master`. User may correct via feedback; ask only after feedback-close if still TBD/conflicting.
 **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.
+**Helpers**: third-party interview helpers are **not** named here; host **command** layer may use them only after feedback-close when gaps remain.
 ## Anti-patterns
@@ -211,7 +216,8 @@ When starting a **new iteration** under Cursor Plan mode (host command may orche
 | 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: second CreatePlan / stale open plan | Edit the original plan file only; merge+delete duplicates |
+| Phase 1 Plan mode: interview loop before feedback-close | Feedback-driven autonomous plan updates; deferred interview only after close signal if gaps remain |
 | 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 CHANGED Viewed

@@ -29,7 +29,7 @@ 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.
+**`mstar-iteration` Phase 1 in Plan mode**: CreatePlan **once** (blank scaffold); then **feedback-driven** in-place updates on that same plan file; deferred interview only after user signals feedback-close **and** gaps remain; **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.

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-iteration
-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。
+description: Morning Star 迭代管理 —— Phase 1（默认 interactive direction lock；opt-in autonomous；specs + `<iteration-id>/` package；禁止直写 knowledge）、Autonomous Execute、iteration-close（compound 提升 package → knowledge）、PR 交付、PR merge-ready loop。分支 SSOT：`status.json` + compass frontmatter。
 ---
 # mstar-iteration（迭代管理）
@@ -48,12 +48,12 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 **误判信号**：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 **未** 打印 §3.1 / §3.5 checklist → 视为 **Phase 3 未执行**，回到 §3.0。
 **per-plan 状态 SSOT**：`{HARNESS_DIR}/status.json`（per-plan Todo/InProgress/InReview/Done）。
-**迭代状态 SSOT**：`{ITERATION_DIR}/<id>-delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引。
+**迭代状态 SSOT**：`{ITERATION_DIR}/<id>/delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）。
 **迭代分支 SSOT**：root `metadata.iteration_base_branch` + `metadata.target_branch`（`status.json`）；compass frontmatter 镜像同名字段。解析顺序见 §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。
 ## 产物存储位置
-**SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。迭代 compass → `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`；迭代索引 → `{ITERATION_DIR}/README.md`。
+**SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。迭代 package → `{ITERATION_DIR}/<iteration-id>/`（含 `delivery-compass.md`、`guides/`、`specs/`）；根索引 → `{ITERATION_DIR}/README.md`。Legacy flat `{ITERATION_DIR}/<id>-delivery-compass.md` 仅兼容读。
 ---
@@ -92,17 +92,24 @@ compass/plans 初稿落盘前，必须锁定**单一**迭代方向、成功标
 | **`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 宿主先写空文件。
+**宿主 Plan UX（interactive）**：若宿主提供 Plan 会话（先写 session plan、后点 Build 才执行 todos）：
+- 允许 **先 scaffold 空白 Phase 1 文档/todos**，再以 **用户反馈驱动** 收敛：Agent 探索并写入推荐，**原地更新同一份** session plan；用户提方向/意见，**不以**例行问卷为主路径。
+- Branch policy：在 plan 中写推荐值 + rationale（不得静默 `main`/`master`）；用户可用反馈改正；仅在用户明确结束反馈后仍缺字段时再追问。
+- 访谈式收敛 **仅**在反馈结束后仍有阻塞缺口时可选发起。
+- **禁止**为更新内容再开第二份 session plan。
+**非** 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。
+**Branch policy gate（interactive — 默认路径）**：若用户、现有 roadmap、或项目约定未明确 `iteration_base_branch` / `target_branch`，PM 必须检查当前分支并向用户确认（**Plan 会话**走上方「推荐写入 plan + 反馈改正」；非 Plan 仍须确认）。**不得**因为存在 `main` / `master` 就默认从默认分支开 iteration 或向默认分支提 PR。
 **Autonomous branch resolve**：仅 `autonomous` 模式；解析顺序与 STOP 规则见 **`references/autonomous-direction-lock.md`**（勿把该顺序套用到 interactive 以跳过向用户确认）。
-### 1.3 创建迭代 compass
+### 1.3 创建迭代 package + compass
-写入 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`。**必须**使用 `references/iteration-compass-template.md` 完整结构（YAML frontmatter + `## Roadmap Position` + close 占位节）。`end_date` 仅在 iteration-close 填入；禁止用正文 completion prose 替代 frontmatter `status`。
+创建 `{ITERATION_DIR}/<iteration-id>/`，写入 **`delivery-compass.md`**（canonical；**禁止**新写根目录 `<id>-delivery-compass.md`）。**必须**使用 `references/iteration-compass-template.md` 完整结构（YAML frontmatter + `## Roadmap Position` + close 占位节）。`end_date` 仅在 iteration-close 填入；禁止用正文 completion prose 替代 frontmatter `status`。按需创建 `guides/`、`specs/` 与 package `README.md`。
 ```markdown
 ---
@@ -151,11 +158,11 @@ plans: []
 ### 1.4 更新索引
-在 `{ITERATION_DIR}/README.md` 中添加一行（首次创建时建立表头）：
+在 `{ITERATION_DIR}/README.md` 中添加**一行**（首次创建时建立表头；**一行 = 一次迭代**，不拆 compass/workspace 双行）：
-| Document | Iteration | Description | Status |
-|----------|-----------|-------------|--------|
-| `<iteration-id>-delivery-compass.md` | `<iteration-id>` | `<简短描述>` | `active` |
+| Iteration | Path | Description | Status |
+|-----------|------|-------------|--------|
+| `<iteration-id>` | [`<iteration-id>/`](<iteration-id>/) | `<简短描述>` | `active` |
 ### 1.5 登记到 status.json（formal iteration 必填）
@@ -174,8 +181,8 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 | 树 | iteration-start 主责 | 说明 |
 |----|---------------------|------|
 | **`{SPECS_DIR}/`** | product-manager、architect | **长期**规范性产出：锁定规格、ADR、契约；plan `primary_spec` / `spec_refs` 主要挂此处 |
-| **`{ITERATION_DIR}/`** | product-manager、architect、PM | compass（根）+ **`<iteration-id>/` workspace**（迭代级 specs & guides） |
-| **`{KNOWLEDGE_DIR}/`** | **非** start/execute 直写；**`mstar-compound`** @ iteration-close（含 workspace **提升**） | 可复用实施 SSOT |
+| **`{ITERATION_DIR}/`** | product-manager、architect、PM | **`<iteration-id>/` package**（`delivery-compass.md` + 迭代级 specs & guides） |
+| **`{KNOWLEDGE_DIR}/`** | **非** start/execute 直写；**`mstar-compound`** @ iteration-close（含 package **提升**） | 可复用实施 SSOT |
 **禁止**：product/architect 在 §1.6 向 `{KNOWLEDGE_DIR}/` **新增**；把迭代级草案写入 `{SPECS_DIR}/`（应进 `<iteration-id>/specs/` 或 guides）。
@@ -185,8 +192,8 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 派发机制 → **`mstar-dispatch-gates`**（specialist review-and-edit dispatch，**顺序链**）。PM **不得**将迭代 harness 文档 commit 到 `spec_integration_branch`，直到：
-1. **product-manager** → **architect** → **writing-specialist** 已按序 invoke 编辑 compass、plans、`{SPECS_DIR}/` 与 **`{ITERATION_DIR}/<iteration-id>/`** workspace（guides/specs，按需）；**不得**在 start 链向 `{KNOWLEDGE_DIR}/` 新增
-2. **writing-specialist** 完成 **corpus hygiene**：全库 `{SPECS_DIR}/` + 既有 `{KNOWLEDGE_DIR}/` 卫生；错放迁回 **`<iteration-id>/`** workspace；细则 → **`iteration-corpus-hygiene.md`**、**`iteration-artifact-boundaries.md`**
+1. **product-manager** → **architect** → **writing-specialist** 已按序 invoke 编辑 compass、plans、`{SPECS_DIR}/` 与 **`{ITERATION_DIR}/<iteration-id>/`** package（guides/specs，按需）；**不得**在 start 链向 `{KNOWLEDGE_DIR}/` 新增
+2. **writing-specialist** 完成 **corpus hygiene**：全库 `{SPECS_DIR}/` + 既有 `{KNOWLEDGE_DIR}/` 卫生；错放迁回 **`<iteration-id>/`** package；细则 → **`iteration-corpus-hygiene.md`**、**`iteration-artifact-boundaries.md`**
 3. PM 将 compass `status` 设为 `locked`，并确认各 plan 的 Prepare gate（specify / clarify / plan）
 **顺序理由**：产品范围与优先级 → 架构与长期契约（specs）→ 行文、规格库卫生与错放纠正（须在 PM/architect 定稿后扫全库 specs）。并行会导致后手重复劳动或覆盖前手未定稿内容。OpenCode：plain role id — **`mstar-host/references/opencode.md`** § Role-mention hygiene。
@@ -235,7 +242,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 **Metadata 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
 1. `{HARNESS_DIR}/status.json` → `metadata.iteration_base_branch`、`metadata.target_branch`；plan → `metadata.spec_integration_branch`
-2. 若 (1) 缺字段 → 读当前迭代 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` frontmatter 同名键
+2. 若 (1) 缺字段 → 读当前迭代 compass frontmatter 同名键：优先 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；若无则 legacy `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`
 3. 若 compass 有值而 `status.json` 无 → **同轮 backfill** `status.json`
 4. 仍缺 → 向用户确认 base / PR target；**不得**因 `git symbolic-ref refs/remotes/origin/HEAD` 指向 `main` 就自动采用
@@ -267,7 +274,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
    - 每次 Completion Report v2 后更新 `status.json` + 主 plan
 3. **QC → QA gate → Done**：per-plan 审查链 → **`mstar-sdd`**（L1–L2）+ **`mstar-review-qc/references/review-responsibility-boundaries.md`**（L3 tri / inline 单席；raw reports in `{SDD_DIR}/review/`，durable summary in main plan/status）+ **`QA gate`**（`mandatory` → `qa-engineer`；`pm-acceptance` → PM checklist）。
 4. **Plan complete — merge back**：合并 plan feature branch → `spec_integration_branch`；在下一 plan 或 QC 前解决冲突
-5. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 的 `## Plans` 表状态列
+5. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` 的 `## Plans` 表状态列
 6. **Next plan** 从步骤 1 继续
 全部 plan `Done` → **Phase transition gate**（见上文 **Phase transition gates**）：
@@ -354,12 +361,12 @@ PM **必须**在对话中打印本 checklist；不得默认同过。
 PM 批量触发后须：
 1. 收集本迭代 plan 实现 / debug / review 素材，筛候选知识
-2. **盘点** `{ITERATION_DIR}/<iteration-id>/**` workspace（`guides/`、`specs/`）— **`mstar-compound`**「Iteration workspace promotion」；提升值得保留者进 `{KNOWLEDGE_DIR}/`
+2. **盘点** `{ITERATION_DIR}/<iteration-id>/**` package（`guides/`、`specs/`；默认排除 `delivery-compass.md`）— **`mstar-compound`**「Iteration package promotion」；提升值得保留者进 `{KNOWLEDGE_DIR}/`
 3. 逐条过 `mstar-compound` 自检；跳过项记入 compass `## Compound Round Summary`
 4. 写入或更新 `{KNOWLEDGE_DIR}/<category>/<slug>.md`；新领域词更新 `CONCEPTS.md`
 5. **每篇**新 doc 完成 Phase 6（`{KNOWLEDGE_DIR}/README.md` 登记）
-若无结晶且无 workspace 提升，仍在 `## Compound Round Summary` 写明 `无可结晶知识` / workspace 盘点结论及原因。
+若无结晶且无 package 提升，仍在 `## Compound Round Summary` 写明 `无可结晶知识` / package 盘点结论及原因。
 ### 3.3 更新 roadmap
@@ -383,7 +390,7 @@ PM 批量触发后须：
 PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git commit`；然后进入 **Phase 4**（§4）：
 - [ ] §3.1 前置 gate 已打印并满足
-- [ ] §3.2 compound 完成；**`<iteration-id>/` workspace 已盘点**（提升 / 保留 / 跳过已记入 Compound Summary）；新增 knowledge doc 均已登记 `{KNOWLEDGE_DIR}/README.md`（或已记录无可结晶原因）
+- [ ] §3.2 compound 完成；**`<iteration-id>/` package 已盘点**（提升 / 保留 / 跳过已记入 Compound Summary）；新增 knowledge doc 均已登记 `{KNOWLEDGE_DIR}/README.md`（或已记录无可结晶原因）
 - [ ] §3.3 `## Roadmap Position` current iteration 已标 `delivered`；tracker / STRATEGY 已按需更新
 - [ ] §3.4 frontmatter `status: completed` + `end_date`；Quality Gate Summary + Compound Summary + Retrospective 已填
 - [ ] 当前分支是 `spec_integration_branch`
@@ -392,7 +399,7 @@ PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git co
 **Commit 到 integration 分支**：
 ```bash
-git add {ITERATION_DIR}/<id>-delivery-compass.md {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
+git add {ITERATION_DIR}/<id>/ {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
 git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
 git push origin <spec_integration_branch>
 ```
@@ -471,8 +478,8 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 | `mstar-branch-worktree` | 分支/merge/worktree 隔离 |
 | `mstar-compound` | iteration-close 中触发知识结晶（**唯一**默认 knowledge 新增路径） |
 | `mstar-compound-refresh` | iteration-close 后可触发知识维护 |
-| `references/iteration-artifact-boundaries.md` | Phase 1 specs / iterations workspace / knowledge 分工 |
-| `references/iteration-workspace-readme-template.md` | `<iteration-id>/README.md` 可选模板 |
+| `references/iteration-artifact-boundaries.md` | Phase 1 specs / iteration package / knowledge 分工 |
+| `references/iteration-workspace-readme-template.md` | `<iteration-id>/README.md` 可选模板（Documents 单表） |
 | `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` 对齐方向 |
@@ -492,7 +499,9 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 - 不要将 **Phase 4 开 PR** 等同于 **迭代交付完成** — 必须完成 **Phase 5** §5.5 merge-ready loop
 - **不要在 iteration-start §1.6 由 product/architect 向 `{KNOWLEDGE_DIR}/` 新增文档**（知识 → iteration-close **`mstar-compound`**）
 - **不要把迭代级草案写入 `{SPECS_DIR}/`**（应进 `{ITERATION_DIR}/<iteration-id>/specs/` 或 `guides/`）
-- **不要在 iteration-close 跳过 `<iteration-id>/` workspace 盘点**（compound 提升 SSOT → **`mstar-compound`**）
+- **不要在 iteration-close 跳过 `<iteration-id>/` package 盘点**（compound 提升 SSOT → **`mstar-compound`**）
+- **不要新写根目录 `<iteration-id>-delivery-compass.md`**（canonical：`<iteration-id>/delivery-compass.md`；legacy flat 仅兼容读）
+- **不要在 `{ITERATION_DIR}/README.md` 为同一迭代登记 compass + workspace 双行**（一行 = 一次迭代）
 - **不要在 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 仍为默认）

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

@@ -49,7 +49,7 @@ Count only **business delivery plans** registered in compass / `status.json` who
 |--------------------------|----------|
 | 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 |
+| Phase 3–5 process | Compound / package 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.

package/harness-skills/mstar-iteration/references/iteration-artifact-boundaries.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # iteration-start 产物边界（specs · iterations · knowledge）
-> **When**: Phase 1 — PM 初稿落盘、§1.6 Review & Edit chain；Phase 2 迭代执行期可继续写入 iteration workspace；Phase 3 iteration-close 经 **`mstar-compound`** 提升。
+> **When**: Phase 1 — PM 初稿落盘、§1.6 Review & Edit chain；Phase 2 迭代执行期可继续写入 iteration package；Phase 3 iteration-close 经 **`mstar-compound`** 提升。
 > **Conflict**: 与 `mstar-plan-artifacts/references/knowledge-and-designs.md` 一致；冲突以 **`mstar-harness-core`** 为准。
 ## 三棵树分工（HARD）
@@ -8,48 +8,56 @@
 | 树 | 路径 | 长期价值 | 谁写（何时） | 典型内容 |
 |----|------|----------|--------------|----------|
 | **Specs（仓库级）** | `{SPECS_DIR}/` | **是** — 跨迭代规范性权威 | product / architect @ **iteration-start** | 已锁定产品/API 规格、ADR、契约 |
-| **Iterations** | `{ITERATION_DIR}/` | **迭代级** — 历史快照；可提升 | product / architect / PM @ start & execute | compass + **`<iteration-id>/` workspace** |
-| **Knowledge** | `{KNOWLEDGE_DIR}/` | **是** — 可复用实施 SSOT | **`mstar-compound`** @ **iteration-close**（含 workspace 提升） | 结晶、提升后的长期实施知识 |
+| **Iterations** | `{ITERATION_DIR}/` | **迭代级** — 历史快照；可提升 | product / architect / PM @ start & execute | **`<iteration-id>/` package**（compass + specs/guides） |
+| **Knowledge** | `{KNOWLEDGE_DIR}/` | **是** — 可复用实施 SSOT | **`mstar-compound`** @ **iteration-close**（含 package 提升） | 结晶、提升后的长期实施知识 |
 ```text
 iteration-start / execute
-  product / architect  ──►  {SPECS_DIR}/              已锁定的长期规格
-                         ──►  {ITERATION_DIR}/<id>/   迭代级 specs + guides（工作区）
-                         ✗   {KNOWLEDGE_DIR}/          不直接新增
+  product / architect  ──►  {SPECS_DIR}/                    已锁定的长期规格
+                         ──►  {ITERATION_DIR}/<id>/         迭代 package（compass + specs + guides）
+                         ✗   {KNOWLEDGE_DIR}/                不直接新增
 iteration-close (§3.2)
   mstar-compound       ──►  读 plan 素材 + {ITERATION_DIR}/<id>/**
-                         ──►  {KNOWLEDGE_DIR}/          提升值得保留的 specs/guides
+                         ──►  {KNOWLEDGE_DIR}/                提升值得保留的 specs/guides
 ```
-## `{ITERATION_DIR}/<iteration-id>/` 工作区（迭代级 specs & guides）
+## `{ITERATION_DIR}/<iteration-id>/` 迭代 package（目录优先）
-compass 仍在根目录：`**{ITERATION_DIR}/<iteration-id>-delivery-compass.md**`（现有约定）。**迭代级** specs / guides 放入同名子目录工作区：
+**Canonical layout**（新 iteration-start **只写**此形态）：
 ```text
 {ITERATION_DIR}/
-  README.md
-  <iteration-id>-delivery-compass.md
+  README.md                         # 根索引：每迭代一行 → 指向 <iteration-id>/
   <iteration-id>/
-    README.md              # 可选：本迭代工作区索引
-    guides/                # 探索笔记、过程指南、未锁定权衡
-    specs/                 # 迭代级规格草案（尚未升格到 {SPECS_DIR}/ 或 knowledge）
-    <flat-files>.md        # 允许；大迭代可再分子目录
+    delivery-compass.md             # 迭代状态 SSOT（frontmatter status）
+    README.md                       # 本迭代文档索引（有 guides/specs 时推荐）
+    guides/                         # 探索笔记、过程指南、未锁定权衡
+    specs/                          # 迭代级规格草案
 ```
 | 子路径 | 放什么 | 不放什么 |
 |--------|--------|----------|
-| **`<iteration-id>/guides/`** | 候选方案、调研、会议记录、实施过程说明 | 已锁定的仓库级规范 |
-| **`<iteration-id>/specs/`** | 本迭代演进中的规格、迭代内契约草稿 | 已锁定、跨迭代 `{SPECS_DIR}/` 级权威（应升格或已在 `{SPECS_DIR}/`） |
-| **compass（根）** | 范围、plans 表、验收、分支策略 | 长文探索正文（链到 workspace） |
+| **`delivery-compass.md`** | 范围、plans 表、验收、分支策略、close 摘要 | 长文探索正文（链到 `guides/` / `specs/`） |
+| **`guides/`** | 候选方案、调研、会议记录、实施过程说明 | 已锁定的仓库级规范 |
+| **`specs/`** | 本迭代演进中的规格、迭代内契约草稿 | 已锁定、跨迭代 `{SPECS_DIR}/` 级权威（应升格或已在 `{SPECS_DIR}/`） |
+| **`README.md`** | 本 package 内 documents 索引（单表即可） | 替代根 `{ITERATION_DIR}/README.md` |
-**何时用 workspace 而非单文件 working guide**：一篇 guide 不够时，**默认**用 `<iteration-id>/` 目录；单文件 `<iteration-id>-working-guide.md` 仍允许作轻量入口（可链接进 workspace）。
+**索引**：
-**索引**：`{ITERATION_DIR}/README.md` 登记 compass 行 + workspace 目录行；workspace 内 `README.md` 列出 `guides/`、`specs/` 下文档。
+- **`{ITERATION_DIR}/README.md`**：**一行 = 一次迭代**（指向 `<iteration-id>/` 目录，**不**再拆 compass 行 + workspace 行）。
+- **`<iteration-id>/README.md`**：列出本目录下 `guides/`、`specs/`（及其它文档）；模板 → **`iteration-workspace-readme-template.md`**。
+**Compass 解析顺序**（读）：
+1. `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`（canonical）
+2. Legacy flat：`{ITERATION_DIR}/<iteration-id>-delivery-compass.md`（仅兼容读；新写禁止）
+**禁止（新写）**：根目录 `<iteration-id>-delivery-compass.md`、根目录 `<iteration-id>-working-guide.md`。轻量入口一律进 `<iteration-id>/guides/`。
 ## `{SPECS_DIR}/` 准入（仓库级长期）
-写入 `{SPECS_DIR}/` 前须满足 **至少一条**（与 iteration workspace 区分）：
+写入 `{SPECS_DIR}/` 前须满足 **至少一条**（与 iteration package 区分）：
 - 决策**已锁定**，变更需显式评审
 - 跨 plan、跨迭代仍成立
@@ -59,21 +67,21 @@ compass 仍在根目录：`**{ITERATION_DIR}/<iteration-id>-delivery-compass.md*
 - 仍在迭代内演进的草案 → **`<iteration-id>/specs/`**
 - 探索 scratch → **`<iteration-id>/guides/`**
-- 实施踩坑（未整理）→ 留 workspace 或 plan 素材，**close 时 compound 提升**
+- 实施踩坑（未整理）→ 留 package 或 plan 素材，**close 时 compound 提升**
 ## Knowledge 与 compound 提升
 - **`{KNOWLEDGE_DIR}/` 新增**：默认仅在 **iteration-close** §3.2 **`mstar-compound`**。
-- **提升来源（iteration-close）**：除 plan 实现/debug/review 素材外，**必须盘点** `{ITERATION_DIR}/<iteration-id>/**`（`guides/`、`specs/`、扁平文件）。值得跨迭代复用的内容 → 按 compound 双轨模板**重写**进 `{KNOWLEDGE_DIR}/`（非整文件复制）；细则 → **`mstar-compound`**「Iteration workspace promotion」。
-- **提升后**：在源文件顶部或 workspace `README.md` 标注 `Promoted to: {KNOWLEDGE_DIR}/...`；源文件**保留**为迭代历史（或迁入 `<iteration-id>/archived/` 若团队约定）。
-- **iteration-start §1.6**：product / architect **不得**向 `{KNOWLEDGE_DIR}/` **新增**；误写由 writing-specialist 迁回 **workspace**。
+- **提升来源（iteration-close）**：除 plan 实现/debug/review 素材外，**必须盘点** `{ITERATION_DIR}/<iteration-id>/**`（`guides/`、`specs/`、扁平文件；**默认排除** `delivery-compass.md` 除非 PM 显式纳入）。值得跨迭代复用的内容 → 按 compound 双轨模板**重写**进 `{KNOWLEDGE_DIR}/`（非整文件复制）；细则 → **`mstar-compound`**「Iteration package promotion」。
+- **提升后**：在源文件顶部或 package `README.md` 标注 `Promoted to: {KNOWLEDGE_DIR}/...`；源文件**保留**为迭代历史（或迁入 `<iteration-id>/archived/` 若团队约定）。
+- **iteration-start §1.6**：product / architect **不得**向 `{KNOWLEDGE_DIR}/` **新增**；误写由 writing-specialist 迁回 **package**。
 ## §1.6 各角色编辑范围
 | 角色 | 必须编辑 | 禁止 |
 |------|----------|------|
 | **product-manager** | compass、plans、`{SPECS_DIR}/`、`{ITERATION_DIR}/<iteration-id>/`（guides/specs） | `{KNOWLEDGE_DIR}/` **新增**；迭代草案写入 `{SPECS_DIR}/` |
-| **architect** | 同上 + workspace `specs/` 技术向 | 同上；在 `{SPECS_DIR}/` 堆实施踩坑 |
+| **architect** | 同上 + package `specs/` 技术向 | 同上；在 `{SPECS_DIR}/` 堆实施踩坑 |
 | **writing-specialist** | 当轮文档 + `{SPECS_DIR}/` corpus hygiene + 既有 knowledge 卫生 | 代替 compound **提升**；跳过 specs 全库审查 |
 Phase 2 执行期：各角色可继续向 **`<iteration-id>/`** 追加 guides/specs；**仍不**直写 `{KNOWLEDGE_DIR}/`。
@@ -83,12 +91,13 @@ Phase 2 执行期：各角色可继续向 **`<iteration-id>/`** 追加 guides/sp
 | 内容 | 挂接键 | 路径 |
 |------|--------|------|
 | 仓库级锁定规格 | `primary_spec` / `spec_refs` | `{SPECS_DIR}/` |
-| 迭代上下文 | `iteration_compass` / `iteration_refs` | compass + `{ITERATION_DIR}/<iteration-id>/...` |
+| 迭代上下文 | `iteration_compass` / `iteration_refs` | `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` + 同目录下 docs |
 | 知识库（已有） | 仅历史链接 | `{KNOWLEDGE_DIR}/` — **start 不新增** |
 ## 反模式
 - 用 `{KNOWLEDGE_DIR}/` 存迭代探索（应进 `<iteration-id>/guides/`）
-- 把迭代 workspace 草案直接复制进 `{SPECS_DIR}/` 而不锁定评审
-- iteration-close **只做** plan 素材 compound、**不**盘点 `<iteration-id>/` workspace
+- 把迭代 package 草案直接复制进 `{SPECS_DIR}/` 而不锁定评审
+- iteration-close **只做** plan 素材 compound、**不**盘点 `<iteration-id>/` package
 - 提升时整文件复制到 knowledge（应 compound 结构化重写）
+- 新写仍把 compass 放在 `{ITERATION_DIR}/` 根目录（应用 `<iteration-id>/delivery-compass.md`）

package/harness-skills/mstar-iteration/references/iteration-compass-template.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Iteration Compass Template
-Copy this template when creating a new iteration compass in `{ITERATION_DIR}/`.
+Copy this template when creating `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`.
 ```markdown
 ---
@@ -71,19 +71,15 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
 |------|-----------|--------|------------|
 | <risk> | Low/Med/High | Low/Med/High | <mitigation> |
-## Iteration workspace (optional)
+## Iteration package
-> Iteration-level **specs** and **guides** live under `{ITERATION_DIR}/<iteration-id>/` — not in `{SPECS_DIR}/` or `{KNOWLEDGE_DIR}/`. Promoted to knowledge at iteration-close via **`mstar-compound`**.
+> Sibling paths under `{ITERATION_DIR}/<iteration-id>/` — not in `{SPECS_DIR}/` or `{KNOWLEDGE_DIR}/`. Promoted to knowledge at iteration-close via **`mstar-compound`**.
 | Path | Purpose |
 |------|---------|
-| `<iteration-id>/guides/` | Exploration, process notes |
-| `<iteration-id>/specs/` | Iteration-scoped spec drafts |
-| `<iteration-id>/README.md` | Workspace index (recommended when non-trivial) |
-Link from compass when used:
-- Workspace: `<iteration-id>/` | <one-line purpose>
+| `guides/` | Exploration, process notes |
+| `specs/` | Iteration-scoped spec drafts |
+| `README.md` | Package document index (recommended when non-trivial) |
 ## Quality Gate Summary
@@ -132,7 +128,7 @@ Notes:
 | `## Non-Goals` | Yes | Phase 1 |
 | `## Roadmap Position` | **Yes** | Phase 1（必填节，非散落于 general context prose）；Phase 3 §3.3（current iteration → `delivered`） |
 | `## Risk Register` | Optional | Phase 1, Phase 2 (update) |
-| Iteration workspace (`<iteration-id>/`) | Optional | Phase 1 §1.5.5 — `guides/` + `specs/`; index in `{ITERATION_DIR}/README.md` |
+| Iteration package (`guides/` / `specs/`) | Optional | Phase 1 §1.5.5; root index one row → `{ITERATION_DIR}/README.md` |
 | `## Quality Gate Summary` | Yes | Phase 3 §3.4 |
 | `## Compound Round Summary` | Yes | Phase 3 §3.4 |
 | `## Iteration Retrospective` | Recommended | Phase 3 §3.4 |
@@ -141,5 +137,6 @@ Notes:
 若仓库中已有 compass **无** YAML frontmatter、**无** `## Roadmap Position`，或只有 prose completion status：
-- **新迭代**：Phase 1 必须按本模板重写，不延续 prose-only 惯例。
+- **新迭代**：Phase 1 必须按本模板写入 **`{ITERATION_DIR}/<iteration-id>/delivery-compass.md`**，不延续 prose-only 或根目录 flat 文件惯例。
 - **收口时**：`mstar-iteration` §3.0.5 在 Phase 3 入口规范化，再执行 §3.3–§3.4。
+- **Legacy path**：若仍存在 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`，读时兼容；本轮若改写该迭代，迁入 `<iteration-id>/delivery-compass.md`。

package/harness-skills/mstar-iteration/references/iteration-corpus-hygiene.md CHANGED Viewed

@@ -1,51 +1,45 @@
-# iteration-start corpus hygiene（specs primary · knowledge read-only）
+# Iteration corpus hygiene（writing-specialist · §1.6）
-> **When**: Phase 1 §1.6 — **writing-specialist** only, after product/architect landed compass / plans / `{SPECS_DIR}/` / **`{ITERATION_DIR}/<iteration-id>/`** workspace.
+> **When**: Phase 1 §1.6 — **writing-specialist** only, after product/architect landed compass / plans / `{SPECS_DIR}/` / **`{ITERATION_DIR}/<iteration-id>/`** package.
 > **Boundaries**: **`iteration-artifact-boundaries.md`** — no `{KNOWLEDGE_DIR}/` adds @ start; iteration drafts → **`<iteration-id>/guides/`** or **`specs/`**.
-## Scope (HARD)
+## Scope
-| Priority | Tree | Action |
-|----------|------|--------|
-| **Primary** | `{SPECS_DIR}/**` | Full active corpus review |
-| **Included** | `{ITERATION_DIR}/<iteration-id>/**` | Workspace guides/specs + compass cross-links |
-| **Secondary** | `{KNOWLEDGE_DIR}/**` (existing) | Archive / relocate only — **no** new docs |
-| **Included** | `{PLAN_DIR}/` plans touched this iteration | Spec refs, terminology |
+| | Path | Notes |
+|--|------|-------|
+| **Primary** | `{SPECS_DIR}/**` | Full-tree hygiene (lock vs draft, naming, index) |
+| **Included** | `{ITERATION_DIR}/<iteration-id>/**` | Package guides/specs + compass cross-links |
+| **Existing only** | `{KNOWLEDGE_DIR}/**` | Archive / misplaced correction — **no** new knowledge docs |
+| **Out of scope** | New `{KNOWLEDGE_DIR}/` writes | → **`mstar-compound`** @ iteration-close |
-**Out of scope**: compound promotion (iteration-close); per-plan review bundles (`{SDD_DIR}/review/`); code.
+## Placement corrections
-## Misplaced content (relocate)
-| Found in | Target |
-|----------|--------|
+| Found in | Misplaced as | Move to |
+|----------|--------------|---------|
 | `{SPECS_DIR}/` | Iteration-only draft → `{ITERATION_DIR}/<iteration-id>/specs/` or `guides/` |
-| `{SPECS_DIR}/` | Implementation/debug notes → workspace `guides/` (compound @ close) |
+| `{SPECS_DIR}/` | Implementation pitfall prose → package `guides/` or leave for compound |
 | `{KNOWLEDGE_DIR}/` | New exploration from start chain → `<iteration-id>/guides/` or archive |
-| Flat `{ITERATION_DIR}/*-working-guide.md` | OK as entry; or merge into `<iteration-id>/guides/` when workspace exists |
-## Classification
-Same as before for specs + existing knowledge: Active / Superseded / Redundant / Obsolete / Unclear → archive under `archived/specs/` or `archived/knowledge/` with relative path preserved.
+| Flat `{ITERATION_DIR}/*-working-guide.md`（legacy） | → `<iteration-id>/guides/` |
+| Flat `{ITERATION_DIR}/*-delivery-compass.md`（legacy） | Prefer migrate to `<iteration-id>/delivery-compass.md` when touching that iteration |
-## Index and metadata
+## Index updates（after edits）
-1. `{SPECS_DIR}/README.md` — update as needed
-2. `{KNOWLEDGE_DIR}/README.md` — archive rows only; no new iteration exploration rows
-3. `{ITERATION_DIR}/README.md` — compass + **`<iteration-id>/` workspace** directory row
-4. `{ITERATION_DIR}/<iteration-id>/README.md` — list guides/specs (create if non-trivial)
-5. `plans[].metadata` — `primary_spec` / `spec_refs` → `{SPECS_DIR}/`; `iteration_refs` → workspace paths
+1. `{SPECS_DIR}/README.md`（若存在）— 规格索引
+2. `{KNOWLEDGE_DIR}/README.md` — Status / archive only（无新增行来自 start 链）
+3. `{ITERATION_DIR}/README.md` — **一行 = 一次迭代**（目录链接，非 compass+workspace 双行）
+4. `{ITERATION_DIR}/<iteration-id>/README.md` — Documents 单表列出 guides/specs（非 trivial 时创建）
-## Evidence of done
+## Done signals
-- No iteration scratch left in `{SPECS_DIR}/`
-- Workspace used for iteration-level drafts (`<iteration-id>/guides|specs/`)
-- No new `{KNOWLEDGE_DIR}/` from §1.6 chain
-- Completion Report lists workspace paths + spec hygiene moves
+- Specs tree hygiene complete（draft vs locked clear）
+- Package used for iteration-level drafts (`<iteration-id>/guides|specs/`)
+- Misplaced knowledge / specs moved or archived with index Status updated
+- No new `{KNOWLEDGE_DIR}/` documents from this chain
-## Distinction from compound @ iteration-close
+## Close vs start
-| | §1.6 hygiene | compound workspace promotion |
-|--|--------------|------------------------------|
-| When | iteration-start | iteration-close §3.2 |
+| Tree | Start (§1.6) | Close (§3.2 compound） |
+|------|--------------|------------------------|
+| `{SPECS_DIR}/` | Hygiene + lock clarity | Usually unchanged |
 | `{ITERATION_DIR}/<id>/` | Create/edit drafts | **Inventory → promote** to `{KNOWLEDGE_DIR}/` |
-| `{KNOWLEDGE_DIR}/` | No new writes | Structured new docs |
+| `{KNOWLEDGE_DIR}/` | Hygiene / archive only | **Primary write path** |

package/harness-skills/mstar-iteration/references/iteration-workspace-readme-template.md CHANGED Viewed

@@ -1,23 +1,19 @@
-# Iteration workspace README (template)
+# Iteration package README (template)
-Optional index inside `{ITERATION_DIR}/<iteration-id>/`. Copy when the workspace has more than a few files.
+Optional index inside `{ITERATION_DIR}/<iteration-id>/`. Copy when the package has more than a few files beyond `delivery-compass.md`.
 ```markdown
-# <iteration-id> workspace
+# <iteration-id>
-Iteration-scoped **specs** and **guides** — not `{KNOWLEDGE_DIR}/`. Worthy content is **promoted** at iteration-close via `mstar-compound`.
+Iteration package — `delivery-compass.md` + specs/guides. Not `{KNOWLEDGE_DIR}/`. Worthy content is **promoted** at iteration-close via `mstar-compound`.
-## Guides
+## Documents
-| Document | Description | Status |
-|----------|-------------|--------|
-| [guides/<name>.md](guides/<name>.md) | <purpose> | draft / active / promoted |
-## Specs (iteration-level)
-| Document | Description | Status |
-|----------|-------------|--------|
-| [specs/<name>.md](specs/<name>.md) | <purpose> | draft / locked-in-{SPECS_DIR} / promoted |
+| Document | Kind | Description | Status |
+|----------|------|-------------|--------|
+| [delivery-compass.md](delivery-compass.md) | compass | Scope, plans, branch policy | active / locked / completed |
+| [guides/<name>.md](guides/<name>.md) | guide | <purpose> | draft / active / promoted |
+| [specs/<name>.md](specs/<name>.md) | spec | <purpose> | draft / locked-in-{SPECS_DIR} / promoted |
 ## Promotion log (filled at iteration-close)
@@ -26,4 +22,6 @@ Iteration-scoped **specs** and **guides** — not `{KNOWLEDGE_DIR}/`. Worthy con
 | | | | |
 ```
-**Status values**: `draft` | `active` | `promoted` (link knowledge path) | `superseded` | `snapshot-only`
+**Kind**: `compass` | `guide` | `spec` | `other`
+**Status values**: `draft` | `active` | `locked` | `completed` | `promoted` (link knowledge path) | `superseded` | `snapshot-only`

package/harness-skills/mstar-plan-artifacts/references/knowledge-and-designs.md CHANGED Viewed

@@ -13,26 +13,27 @@
 |------|----------|-------------|
 | **`docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
 | **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap — **跨迭代长期权威** | 产品/API 规范性最高权威；**iteration-start** 由 product/architect 主写 |
-| **`{ITERATION_DIR}`**（可选） | delivery compass + **`<iteration-id>/` workspace**（`guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
+| **`{ITERATION_DIR}`**（可选） | **`<iteration-id>/` package**（`delivery-compass.md` + `guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
 | **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker — **经 `mstar-compound` 结晶** | Agent handoff；**不**在 iteration-start 由 product/architect 新增 |
 | **`{PLAN_DIR}/`** | 单 plan 主文件、durable gate summary、可选 `residuals/` | 计划执行与长期决策留档 |
 **不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC/QA 原始过程报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{SDD_DIR}/review/`；长期 gate 摘要回写主 plan。
-## `{ITERATION_DIR}`（可选·迭代/版本级 compass）
+## `{ITERATION_DIR}`（可选·迭代/版本级 package）
 - **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.mstar/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列；legacy 项目可继续为 `.agents/iterations/`）。
-- **放什么**：delivery compass（根目录 `*-delivery-compass*.md`）；**`<iteration-id>/` 工作区** — `guides/`（探索、过程）、`specs/`（迭代级规格草案）；遗留规划快照。
+- **放什么**：**`<iteration-id>/` package** — `delivery-compass.md`（迭代状态 SSOT）；`guides/`（探索、过程）；`specs/`（迭代级规格草案）；可选 package `README.md`；遗留规划快照。
 - **不放什么**：已锁定的仓库级规范（→ **`{SPECS_DIR}/`**）；已提升的跨迭代实施 SSOT（→ **`{KNOWLEDGE_DIR}/`**，经 compound）；单 plan QC/QA 原始报告（→ `{SDD_DIR}/review/`）。
-- **索引**：`**{ITERATION_DIR}/README.md**` 登记 compass + workspace 目录；`<iteration-id>/README.md` 登记工作区内文档。
-- **维护**：`@product-manager` / `@architect` 起草 workspace；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 workspace 并**提升**至 `{KNOWLEDGE_DIR}/`。
+- **索引**：`**{ITERATION_DIR}/README.md**` **一行 = 一次迭代**（指向 `<iteration-id>/`）；`<iteration-id>/README.md` 登记 package 内文档（Documents 单表）。
+- **维护**：`@product-manager` / `@architect` 起草 package；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 package 并**提升**至 `{KNOWLEDGE_DIR}/`。
+- **Compass 路径**：canonical `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；legacy flat `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 仅兼容读。
 ## `{SPECS_DIR}`（可选·长期规格）
 - `{SPECS_DIR}` 解析：优先 `{HARNESS_DIR}/specs/`，否则 `{HARNESS_DIR}/designs/`；皆无则建议新建 `specs/`。
 - **放什么**：跨迭代有效、已锁定或待锁定的产品/API 规范、ADR、契约 — **iteration-start 主产出**（product/architect）。
-- **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ workspace 或 plan 素材，**close 时 compound 提升**）。
+- **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ package 或 plan 素材，**close 时 compound 提升**）。
 - **索引**：非 trivial 树建议 `{SPECS_DIR}/README.md`；plan **`primary_spec` / `spec_refs`** 主要指向此处。
 ## `{KNOWLEDGE_DIR}`（可选·实施知识库）
@@ -46,7 +47,7 @@
 - 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
 - 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `{KNOWLEDGE_DIR}` 根（除非团队明确约定）。
-- 迭代 compass 文件名宜带版本/迭代标识，放在 `{ITERATION_DIR}/`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间。
+- 迭代 compass 放在 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间；**不要**新写根目录 flat `*-delivery-compass.md`。
 ## 与 `status.json` 的链接
@@ -57,14 +58,14 @@
 1. **新增**：
    - **Specs（长期）**：`{SPECS_DIR}/` → spec 索引（若有）→ `plans[].metadata` 的 `primary_spec` / `spec_refs`
-   - **迭代 workspace**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md` + workspace README → `iteration_refs`
-   - **Knowledge**：**`mstar-compound`** @ iteration-close（含 workspace **提升**）→ `{KNOWLEDGE_DIR}/README.md`
+   - **迭代 package**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md`（目录一行）+ package README → `iteration_refs`
+   - **Knowledge**：**`mstar-compound`** @ iteration-close（含 package **提升**）→ `{KNOWLEDGE_DIR}/README.md`
 2. **阅读**：开发类 agent 在开始编码前，**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
 3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
 4. **归档**：
    - **iteration-start（强制）**：`writing-specialist` §1.6 以 **`{SPECS_DIR}/` 全库卫生为主**；对**既有** `{KNOWLEDGE_DIR}/` 仅归档/错放纠正，**不**新增 knowledge。细则 → **`mstar-iteration/references/iteration-corpus-hygiene.md`**。
    - **其它时机**：当文档内容已完全反映到已合并代码中、且非 iteration-start 扫库时：可将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`；可保留原位或迁入 `archived/knowledge/`。**不要**把知识库产物搬进 `{HARNESS_DIR}/archived/plans/`（该处用于**计划行**冷快照）。
-5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` workspace 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
+5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` package 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
 ## 与 review bundle、`{PLAN_DIR}/residuals/` 的区分
@@ -72,7 +73,7 @@
 - `**主 plan gate summary**`：偏 **长期门禁决策摘要**（verdict、review range、R#、QA gate），随主 plan 追踪。
 - `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与根级 `**residual_findings**` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
 - `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
-- `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 compass 与规划快照，通常按版本索引而非按单 plan 长期复用。
+- `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
 - review bundle、gate summary、residuals、knowledge、iterations 可互链，但职责不混写。
 ---
@@ -87,7 +88,7 @@
 | `**{SDD_DIR}/review/**`       | QC / QA **流程临时证据**（`qc1.md` … `qc-consolidated.md`、`qa.md` 等），gitignored                  |
 | **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文**                  |
 | `**{KNOWLEDGE_DIR}/**`            | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
-| `**{ITERATION_DIR}/**`            | 迭代/版本级 compass；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
+| `**{ITERATION_DIR}/**`            | 迭代 package（`<id>/delivery-compass.md` 等）；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
 **文件命名（推荐）**：`<finding-id>-<short-label>.md`，其中 `**finding-id`** 与该条在 **open 列表**（根级 `**residual_findings**`，见 `mstar-plan-conventions` **SKILL.md** 开篇）中的 `**id**`（如 `R1`）或团队约定的 `**td-*` 等技术债编号**一致，便于 `detail_doc` 与目录互查。

package/harness-skills/mstar-plan-conventions/SKILL.md CHANGED Viewed

@@ -42,7 +42,7 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 |------|------|
 | `docs/` | 人类文档：安装、贡献 |
 | `{SPECS_DIR}` | 冻结规格 / ADR |
-| `{ITERATION_DIR}` | 迭代 compass 快照 |
+| `{ITERATION_DIR}` | 迭代 package（compass + guides/specs） |
 | `{KNOWLEDGE_DIR}` | 实现 SSOT、可复用设计 |
 | `{PLAN_DIR}/` | 主 plan、durable gate summaries、可选 residual prose |

package/harness-skills/mstar-plan-conventions/references/artifact-storage-paths.md CHANGED Viewed

@@ -16,9 +16,8 @@
 | **Review bundle（QC/QA 原始过程报告）** | `{HARNESS_DIR}/sdd/<plan-id>/review/`（gitignored；默认 `.mstar/sdd/<plan-id>/review/`） | `mstar-sdd`、`mstar-review-qc`、`qa-engineer` |
 | **SDD scratch** | `{HARNESS_DIR}/sdd/<plan-id>/`（gitignored；含 per-task handoff 与 `review/` bundle） | `mstar-sdd` |
 | **status.json** | `.mstar/status.json` | `mstar-plan-artifacts` |
-| **迭代 compass** | `.mstar/iterations/<iteration-id>-delivery-compass.md` | `mstar-iteration`（读写） |
-| **迭代工作区** | `.mstar/iterations/<iteration-id>/`（`guides/`、`specs/` 等） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读） |
-| **迭代索引** | `.mstar/iterations/README.md` | `mstar-iteration`（读写） |
+| **迭代 package** | `.mstar/iterations/<iteration-id>/`（`delivery-compass.md`、`guides/`、`specs/`、可选 `README.md`） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读；默认排除 compass） |
+| **迭代索引** | `.mstar/iterations/README.md`（一行 = 一次迭代） | `mstar-iteration`（读写） |
 | **规格** | `specs/`（优先），否则 `designs/` | `mstar-plan-artifacts` |
 | **archived residuals** | `.mstar/archived/residuals/<plan-id>.json` | `mstar-plan-artifacts` |
 | **archived knowledge** | `.mstar/archived/knowledge/`（保留原 `{KNOWLEDGE_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-plan-artifacts` |
@@ -41,7 +40,7 @@
 | 路径 | 说明 |
 |------|------|
 | `docs/` | 人类文档（安装、贡献指南等），知识产物不放此处 |
-| `{ITERATION_DIR}/` | 仅限迭代 compass，知识文档不放此处 |
+| `{ITERATION_DIR}/` | 迭代 package（compass + guides/specs）；知识文档不放此处 |
 | `{SPECS_DIR}/` | 仅限冻结规格/ADR，运行时知识不放此处 |
 | `{PLAN_DIR}/reports/` | Legacy / explicit audit mode only；默认 QC/QA 原始过程报告进 `{SDD_DIR}/review/`，知识文档不放此处 |

package/harness-skills/mstar-roles/references/architect.md CHANGED Viewed

@@ -4,7 +4,7 @@
 **Always:** `mstar-harness-core`, `mstar-dispatch-gates`, `mstar-phase-gates` (Prepare: specify/clarify/plan), `mstar-plan-conventions` (`{PLAN_DIR}`, plan-writing path).
-**Typically:** `mstar-plan-artifacts` (specs, **`{ITERATION_DIR}/<id>/` workspace**); `mstar-design-md`; `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**.
+**Typically:** `mstar-plan-artifacts` (specs, **`{ITERATION_DIR}/<id>/` package**); `mstar-design-md`; `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**.
 **On demand:** `mstar-branch-worktree` (when committing architecture docs to the business repo).

package/harness-skills/mstar-roles/references/product-manager.md CHANGED Viewed

@@ -4,7 +4,7 @@
 **Always:** `mstar-harness-core`, `mstar-dispatch-gates`, `mstar-phase-gates` (Prepare / clarify), `mstar-plan-conventions` (`{PLAN_DIR}`, plan-writing path).
-**Typically:** `mstar-plan-artifacts` (specs, **`{ITERATION_DIR}/<id>/` workspace** — not knowledge @ start); `mstar-design-md`; `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**.
+**Typically:** `mstar-plan-artifacts` (specs, **`{ITERATION_DIR}/<id>/` package** — not knowledge @ start); `mstar-design-md`; `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**.
 **On demand:** `mstar-branch-worktree` (when committing product docs to the business repo).

package/harness-skills/mstar-roles/references/writing-specialist.md CHANGED Viewed

@@ -36,7 +36,7 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
 3. Marketing/copy writing
 4. Script writing
 5. Tone/style adaptation by audience
-6. **iteration-start corpus hygiene** (§1.6 step 3): specs-first hygiene; misplaced drafts → **`{ITERATION_DIR}/<iteration-id>/`** workspace — **`iteration-artifact-boundaries.md`** + **`iteration-corpus-hygiene.md`**. **Promotion** workspace → knowledge is **`mstar-compound`** @ iteration-close only.
+6. **iteration-start corpus hygiene** (§1.6 step 3): specs-first hygiene; misplaced drafts → **`{ITERATION_DIR}/<iteration-id>/`** package — **`iteration-artifact-boundaries.md`** + **`iteration-corpus-hygiene.md`**. **Promotion** package → knowledge is **`mstar-compound`** @ iteration-close only.
 ## Scope Boundaries

package/package.json CHANGED Viewed

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