@mstar-harness/opencode 1.2.1 → 1.3.1

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 (25) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +1 -1
  3. package/harness-commands/iteration-drive.md +1 -1
  4. package/harness-commands/iteration-loop.md +2 -2
  5. package/harness-commands/iteration-start.md +6 -5
  6. package/harness-skills/mstar-compound/SKILL.md +7 -7
  7. package/harness-skills/mstar-compound-refresh/SKILL.md +11 -1
  8. package/{harness-commands/mstar-bootstrap.md → harness-skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md} +3 -9
  9. package/harness-skills/mstar-dispatch-gates/SKILL.md +1 -1
  10. package/harness-skills/mstar-harness-core/SKILL.md +1 -1
  11. package/harness-skills/mstar-host/references/codex.md +1 -1
  12. package/harness-skills/mstar-host/references/cursor-plan-mode-bridge.md +1 -1
  13. package/harness-skills/mstar-iteration/SKILL.md +24 -22
  14. package/harness-skills/mstar-iteration/references/autonomous-direction-lock.md +1 -1
  15. package/harness-skills/mstar-iteration/references/iteration-artifact-boundaries.md +38 -29
  16. package/harness-skills/mstar-iteration/references/iteration-compass-template.md +9 -12
  17. package/harness-skills/mstar-iteration/references/iteration-corpus-hygiene.md +30 -36
  18. package/harness-skills/mstar-iteration/references/iteration-workspace-readme-template.md +13 -15
  19. package/harness-skills/mstar-plan-artifacts/references/knowledge-and-designs.md +13 -12
  20. package/harness-skills/mstar-plan-conventions/SKILL.md +1 -1
  21. package/harness-skills/mstar-plan-conventions/references/artifact-storage-paths.md +3 -4
  22. package/harness-skills/mstar-roles/references/architect.md +1 -1
  23. package/harness-skills/mstar-roles/references/product-manager.md +1 -1
  24. package/harness-skills/mstar-roles/references/writing-specialist.md +1 -1
  25. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,19 @@ All notable changes to the `@mstar-harness/opencode` package are documented in t
4
4
 
5
5
  The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface releases.
6
6
 
7
+ ## 1.3.1
8
+
9
+ - 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.
10
+
11
+ See root [CHANGELOG.md](../../CHANGELOG.md) **1.3.1**.
12
+
13
+ ## 1.3.0
14
+
15
+ - Bundled commands: retire `/mstar-bootstrap`; bootstrap procedure → `mstar-compound-refresh/references/project-knowledge-bootstrap.md`.
16
+ - Bundled skills: `mstar-compound-refresh` and `mstar-harness-core` short pointers for project knowledge bootstrap.
17
+
18
+ See root [CHANGELOG.md](../../CHANGELOG.md) **1.3.0**.
19
+
7
20
  ## 1.2.1
8
21
 
9
22
  - Bundled commands: `/iteration-start` Cursor Plan mode path — blank Phase 1 CreatePlan scaffold, staged grill-me plan updates, Build-gated Review chain.
package/README.md CHANGED
@@ -28,7 +28,7 @@ npx @mstar-harness/cli init --target opencode
28
28
  |-----------------|----------|
29
29
  | `harness-skills/` | `mstar-harness-core`, `mstar-iteration`, `mstar-sdd`, roles, phase/dispatch gates, … |
30
30
  | `harness-agents/` | Role shells (`project-manager`, `fullstack-dev`, `qc-specialist`, …) |
31
- | `harness-commands/` | `/iteration-start`, `/iteration-drive`, `/iteration-loop`, `/mstar-bootstrap` |
31
+ | `harness-commands/` | `/iteration-start`, `/iteration-drive`, `/iteration-loop` |
32
32
 
33
33
  The plugin resolves **only paths inside this package** — not `process.cwd()/skills`, so your app repo root does not affect harness loading.
34
34
 
package/harness-commands/iteration-drive.md CHANGED
@@ -131,7 +131,7 @@ Execute **`mstar-iteration` § Phase 2** exactly. Summary:
131
131
  |------|---------|------|
132
132
  | 1 | §3.0 / §3.0.5 | Phase 边界；legacy compass 规范化（frontmatter + `## Roadmap Position`） |
133
133
  | 2 | §3.1 | 打印 close entry checklist，全部 `[x]` |
134
- | 3 | §3.2 | Compound + **`<iteration-id>/` workspace promotion**；新增 doc 完成 `mstar-compound` Phase 6（`{KNOWLEDGE_DIR}/README.md`） |
134
+ | 3 | §3.2 | Compound + **`<iteration-id>/` package promotion**；新增 doc 完成 `mstar-compound` Phase 6（`{KNOWLEDGE_DIR}/README.md`） |
135
135
  | 4 | §3.3 | `## Roadmap Position` current iteration → `delivered`；STRATEGY/tracker 按需更新 |
136
136
  | 5 | §3.4 | frontmatter `status: completed` + `end_date`；Compound Summary + Retrospective |
137
137
  | 6 | §3.5 | 打印 close exit checklist → commit → push |
package/harness-commands/iteration-loop.md CHANGED
@@ -178,7 +178,7 @@ Per **`mstar-iteration` §1.3–§1.5**（template: `iteration-compass-template.
178
178
  | # | Role | Required action |
179
179
  |---|------|-----------------|
180
180
  | 5.1 | **product-manager** | invoke: **edit** compass, plans, `{SPECS_DIR}/`, `{ITERATION_DIR}/<iteration-id>/` — **禁止** `{KNOWLEDGE_DIR}/` 新增 |
181
- | 5.2 | **architect** | invoke: **edit** compass, plans, specs / workspace（含 5.1 后版本）— **禁止** knowledge 新增 |
181
+ | 5.2 | **architect** | invoke: **edit** compass, plans, specs / package（含 5.1 后版本）— **禁止** knowledge 新增 |
182
182
  | 5.3 | **writing-specialist** | invoke: edit docs + **specs corpus hygiene** — `iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md` |
183
183
  | 5.4 | **project-manager** | Merge; **lock** compass (`status: locked`); confirm Prepare gates |
184
184
 
@@ -237,7 +237,7 @@ Execute **`mstar-iteration` § Phase 2** exactly. Summary:
237
237
 
238
238
  1. STOP per-plan loop
239
239
  2. Print `## Phase 3: iteration-close`
240
- 3. Execute **`mstar-iteration` §3.0→§3.5**（compound + workspace promotion）
240
+ 3. Execute **`mstar-iteration` §3.0→§3.5**（compound + package promotion）
241
241
  4. Exit checklist `[x]` + compass `completed` → print `## Phase 4: Create PR`
242
242
 
243
243
  ```bash
package/harness-commands/iteration-start.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: iteration-start
3
- 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.
3
+ 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.
4
4
  agent: project-manager
5
5
  ---
6
6
 
@@ -180,10 +180,11 @@ Run **grill-me** to stress-test candidate directions with the user:
180
180
 
181
181
  Produce harness artifacts per **`mstar-iteration` § 1.3**（template: `mstar-iteration/references/iteration-compass-template.md`）：
182
182
 
183
- - `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`
183
+ - `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`
184
184
  - `{PLAN_DIR}/<plan-id>-<name>.md` for each plan in this iteration
185
185
  - Register all plans in `{HARNESS_DIR}/status.json`（per `mstar-plan-artifacts` §1.5：root `metadata` + plan `spec_integration_branch`）
186
- - Update `{ITERATION_DIR}/README.md` index（per `mstar-iteration` § 1.4）
186
+ - Update `{ITERATION_DIR}/README.md` index（**一行 = 一次迭代**；per `mstar-iteration` § 1.4）
187
+ - Create package dirs as needed: `{ITERATION_DIR}/<iteration-id>/{guides,specs}/` + optional package `README.md`
187
188
 
188
189
  ## 5. Review & Edit Chain（HARD GATE — do not commit before this）
189
190
 
@@ -196,7 +197,7 @@ Each role below **reviews and directly edits** the documents. Do not just flag i
196
197
  | # | Role | Required action | Gate |
197
198
  |---|------|-----------------|------|
198
199
  | 5.1 | **product-manager** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, **`{ITERATION_DIR}/<iteration-id>/`**（`guides/`、`specs/` 按需）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 完成后方可 5.2 |
199
- | 5.2 | **architect** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, workspace `specs/`（含 5.1 后版本）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 5.1 返回后；完成后方可 5.3 |
200
+ | 5.2 | **architect** | invoke: **edit** compass, plans, **`{SPECS_DIR}/`**, package `specs/`（含 5.1 后版本）— **禁止** `{KNOWLEDGE_DIR}/` 新增 | 5.1 返回后；完成后方可 5.3 |
200
201
  | 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 返回后 |
201
202
  | 5.4 | **project-manager** | Merge subagent edits; resolve conflicts; **lock** compass (`status: locked`); confirm Prepare gates | 5.3 返回后 |
202
203
 
@@ -225,7 +226,7 @@ PM must print this block before §6; all `[ ]` must be `[x]`:
225
226
 
226
227
  - [ ] grill-me decisions recorded in compass
227
228
  - [ ] Draft compass + plans + `status.json` registered
228
- - [ ] product-manager invoke completed — compass / plans / specs / **`<iteration-id>/` workspace**（按需）；**未**向 `{KNOWLEDGE_DIR}/` 新增
229
+ - [ ] product-manager invoke completed — compass / plans / specs / **`<iteration-id>/` package**（按需）；**未**向 `{KNOWLEDGE_DIR}/` 新增
229
230
  - [ ] architect invoke completed — compass / **specs** edited；**未**向 `{KNOWLEDGE_DIR}/` 新增
230
231
  - [ ] writing-specialist invoke completed — specs + iteration docs edited；**specs corpus hygiene** done（全库 `{SPECS_DIR}/`；既有 knowledge 仅卫生/归档；错放已迁回 `iterations/` 或 archive）
231
232
  - [ ] PM final lock: compass `status: locked`; Prepare gates pass (blocked plans documented)
package/harness-skills/mstar-compound/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mstar-compound
3
- 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`。
3
+ 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`。
4
4
  ---
5
5
 
6
6
  # mstar-compound（知识结晶）
@@ -79,18 +79,18 @@ iteration-start → [plan lifecycle × N: specify→...→Done] → iteration-cl
79
79
 
80
80
  迭代内所有 plan Done 后，PM 回顾整轮迭代中产生的可结晶知识，批量 compound。per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动。
81
81
 
82
- ### Iteration workspace promotion（iteration-close 强制盘点）
82
+ ### Iteration package promotion（iteration-close 强制盘点）
83
83
 
84
- 正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代的 workspace：
84
+ 正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代的 package：
85
85
 
86
- **路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；不含根目录 `*-delivery-compass.md` 除非 PM 显式纳入）。
86
+ **路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；**默认排除** `delivery-compass.md` 除非 PM 显式纳入。Legacy 根目录 `*-delivery-compass.md` 同理排除）。
87
87
 
88
88
  | 步骤 | 动作 |
89
89
  |------|------|
90
- | 1. Inventory | 列出 workspace 下全部 `.md`；读各文件 + workspace `README.md`（若有） |
90
+ | 1. Inventory | 列出 package 下全部 `.md`（除默认排除的 compass）；读各文件 + package `README.md`（若有） |
91
91
  | 2. Triage | 每篇：**Promote** / **Keep snapshot** / **Skip**（理由写入 compound 摘要） |
92
92
  | 3. Promote | 值得跨迭代复用 → 走 Q1–Q8（或轻量判定）→ Phase 2 重叠检测 → Phase 3–6 **结构化重写**进 `{KNOWLEDGE_DIR}/`（**禁止**无改写整文件复制） |
93
- | 4. Trace | 源文件顶栏或 workspace README：`Promoted to: <knowledge-path>`；`{KNOWLEDGE_DIR}/README.md` 的 Source 可记 `iteration:<iteration-id>/<relpath>` |
93
+ | 4. Trace | 源文件顶栏或 package README：`Promoted to: <knowledge-path>`；`{KNOWLEDGE_DIR}/README.md` 的 Source 可记 `iteration:<iteration-id>/<relpath>` |
94
94
  | 5. Summary | PM 写入 compass `## Compound Round Summary`：提升篇数、保留快照、跳过及原因 |
95
95
 
96
96
  **Promote 典型**：迭代 spec 已验证且指导未来实现；guide 含非显而易见的过程知识或失败尝试。
@@ -134,7 +134,7 @@ In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
134
134
 
135
135
  ## Phase 1: Gather context
136
136
 
137
- Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** workspace per **Iteration workspace promotion** above.
137
+ Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** package per **Iteration package promotion** above.
138
138
 
139
139
  Understand:
140
140
  - What problem was solved (the concrete issue)
package/harness-skills/mstar-compound-refresh/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mstar-compound-refresh
3
- description: Morning Star 知识维护 —— 审查 `{KNOWLEDGE_DIR}` 中文档是否仍准确、去重叠合并、清理过期知识。触发：`mstar-compound` 发现可合并文档、定期维护、或显式调用。产出：更新/合并/删除/标记为 stale 的文档 + 维护报告。
3
+ description: Morning Star 知识维护与项目知识 bootstrap —— 审查 `{KNOWLEDGE_DIR}` 文档是否仍准确、去重叠合并、清理过期知识；或从代码库提炼 STRATEGY.md、CONCEPTS.md、基线 knowledge 脚手架（无/残旧/空白 knowledge）。触发：`mstar-compound` 发现可合并文档、定期维护、项目缺 STRATEGY.md/CONCEPTS.md/{KNOWLEDGE_DIR}、stale knowledge scaffolding、显式 bootstrap 请求、或显式 refresh。产出：更新/合并/删除知识文档 + 维护报告；或 bootstrap 产物（STRATEGY.md、CONCEPTS.md、基线 knowledge）。
4
4
  ---
5
5
 
6
6
  # mstar-compound-refresh（知识维护）
@@ -25,6 +25,16 @@ Knowledge documents in `{KNOWLEDGE_DIR}` age. Code changes, conventions evolve,
25
25
  | Scheduled maintenance | "It's been a quarter, let's audit knowledge" |
26
26
  | Domain refactored | After a major module rewrite |
27
27
  | Explicit user request | `/pm compound-refresh performance-issues` |
28
+ | **Project knowledge bootstrap** | No/stale/partial `STRATEGY.md`, `CONCEPTS.md`, or `{KNOWLEDGE_DIR}` — see below |
29
+
30
+ ## Bootstrap vs refresh
31
+
32
+ | Mode | When | Procedure |
33
+ |------|------|-----------|
34
+ | **Refresh** | `{KNOWLEDGE_DIR}` exists; audit accuracy, merge overlaps, delete stale docs | This skill § Process (Phases 1–6) |
35
+ | **Bootstrap** | No knowledge scaffolding, or artifacts are absent/stale enough to warrant full distillation from codebase | **`references/project-knowledge-bootstrap.md`** (7-phase: survey → STRATEGY.md → CONCEPTS.md → baseline knowledge → indexing → harness init → commit) |
36
+
37
+ Read the bootstrap reference on demand; do not paste its body into this SKILL.md.
28
38
 
29
39
  ## Maintenance outcomes
30
40
 
package/{harness-commands/mstar-bootstrap.md → harness-skills/mstar-compound-refresh/references/project-knowledge-bootstrap.md} RENAMED
@@ -1,23 +1,17 @@
1
- ---
2
- name: mstar-bootstrap
3
- description: Bootstrap or refresh a project's knowledge scaffolding — distill STRATEGY.md, CONCEPTS.md, and baseline knowledge docs from the existing codebase and any docs. Use when a project has no knowledge infrastructure, stale/partial docs, or needs a fresh distillation.
4
- agent: project-manager
5
- ---
6
-
7
1
  # Bootstrap Project Knowledge
8
2
 
9
3
  Distill a coherent knowledge baseline from the current project — useful when the project has no `STRATEGY.md` / `CONCEPTS.md` / `{KNOWLEDGE_DIR}`, has partial or outdated ones, or has accumulated documentation debt.
10
4
 
11
5
  **Goal**: produce a minimal, accurate, opinionated knowledge foundation that future iteration-start and plan-work can ground in.
12
6
 
13
- ## Boot
7
+ ## Load order (bootstrap)
14
8
 
15
9
  1. `mstar-harness-core`
16
- 2. `mstar-roles` → `references/project-manager.md`
10
+ 2. `mstar-compound-refresh` (this skill)
17
11
  3. `mstar-plan-conventions`（路径符号）
18
12
  4. `mstar-strategy` → **§ STRATEGY.md structure** + **§ Creating STRATEGY.md**
19
13
  5. `mstar-compound` → **references/concepts-vocabulary.md**（CONCEPTS.md 规则）
20
- 6. `mstar-compound-refresh` → **§ Core rules**（知识维护基线）
14
+ 6. This reference — **§ Core rules** in `mstar-compound-refresh/SKILL.md`（知识维护基线）
21
15
 
22
16
  ## Phase 1: Survey — understand what exists
23
17
 
package/harness-skills/mstar-dispatch-gates/SKILL.md CHANGED
@@ -95,7 +95,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
95
95
 
96
96
  - PM 写初稿；各角色通过宿主 invoke **直接编辑**目标文件（**不**另写仅评论式 `reports/` 替代修订）。
97
97
  - **1 Assignment ⇒ 1 invoke**。
98
- - **Phase 1 Review & Edit chain**（`mstar-iteration` §1.6）：主产出 **`{SPECS_DIR}/`** + **`{ITERATION_DIR}/<iteration-id>/`** workspace；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增。close 时 **`mstar-compound`** 提升 workspace → knowledge。
98
+ - **Phase 1 Review & Edit chain**（`mstar-iteration` §1.6）：主产出 **`{SPECS_DIR}/`** + **`{ITERATION_DIR}/<iteration-id>/`** package；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增。close 时 **`mstar-compound`** 提升 package → knowledge。
99
99
  - 其他彼此独立、无先后依赖的文档编辑任务：可并行（同条消息发满 N），见 **`parallel-dispatch.md`**。
100
100
  - PM 线程代做全部专业编辑 = **反模式**（`mstar-iteration` §1.6、`mstar-harness-core` 反模式索引）。
101
101
  - PM merge / lock（如 compass `status: locked`）在链末 subagent 返回后于 PM 线程完成。**不得**在 review-and-edit 链完成前 commit integration 分支。
package/harness-skills/mstar-harness-core/SKILL.md CHANGED
@@ -97,7 +97,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
97
97
  | `mstar-review-qc` | PM：QC tri 编排、residual 留档、四层边界；leaf 执行 → `mstar-roles/references/qc-specialist/` |
98
98
  | `mstar-coding-behavior` | Think / Simplicity / Surgical / Debugging / Review Feedback / Goal-Driven / Communication |
99
99
  | `mstar-compound` | 知识结晶 —— 已解决问题→结构化知识文档，双轨（Bug/Knowledge），「是否值得结晶」自检清单，重叠检测，可发现性检查，CONCEPTS.md 协同 |
100
- | `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档 |
100
+ | `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档；**项目知识 bootstrap**（无/残旧 STRATEGY.md、CONCEPTS.md、`{KNOWLEDGE_DIR}`）→ `references/project-knowledge-bootstrap.md` |
101
101
  | `mstar-strategy` | `STRATEGY.md` 全局战略方向 —— 产品愿景、技术方向、决策原则 |
102
102
  | `mstar-skill-authoring` | mstar-native skill authoring: trigger contracts, progressive disclosure, pressure scenarios, behavior-change evidence |
103
103
  | `mstar-roles` | 角色正文 hub |
package/harness-skills/mstar-host/references/codex.md CHANGED
@@ -11,7 +11,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an
11
11
  - Plugin source: `.codex-plugin/plugin.json`.
12
12
  - Runtime skills: repo `skills/` mounted by the Codex plugin (`"skills": "./skills/"`).
13
13
  - Custom agent source: repo `codex/agents/*.toml`; CLI/manual install links these into `~/.codex/agents/` or project `.codex/agents/`.
14
- - **`/pm`** or **`pm` skill**: force PM entry → `mstar-roles` → `project-manager.md` (Codex primary; Cursor/OpenCode for general per-plan work). **`commands/`** when running iteration Phase 1–5.
14
+ - **`/pm`** or **`pm` skill**: force PM entry → `mstar-roles` → `project-manager.md` (Codex primary; Cursor/OpenCode for general per-plan work). **`commands/`** when running iteration Phase 1–5; project CLI install (`mstar-harness init --target codex --scope project`) materializes `iteration-start`, `iteration-drive`, and `iteration-loop` as `.agents/skills/<name>/SKILL.md` symlinks.
15
15
  - Role files under root `agents/` are for hosts that load OpenCode/Cursor-style agent shells; Codex uses `codex/agents/*.toml` and still loads `mstar-roles` references directly.
16
16
  - Tool and plugin availability can be lazy-loaded or session-dependent. Use the tools actually present in the current session; do not infer capability from documentation alone.
17
17
 
package/harness-skills/mstar-host/references/cursor-plan-mode-bridge.md CHANGED
@@ -190,7 +190,7 @@ When starting a **new iteration** under Cursor Plan mode (host command may orche
190
190
  | Phase | Behavior | Forbidden |
191
191
  |-------|----------|-----------|
192
192
  | 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 |
193
- | 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 |
193
+ | 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}/<id>/delivery-compass.md` 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 |
194
194
  | Pre-Build | Maintain documents only | Execute Review chain, commit, or create `spec_integration_branch` |
195
195
  | 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 |
196
196
 
package/harness-skills/mstar-iteration/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mstar-iteration
3
- 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。
3
+ 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。
4
4
  ---
5
5
 
6
6
  # mstar-iteration（迭代管理）
@@ -48,12 +48,12 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
48
48
  **误判信号**：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 **未** 打印 §3.1 / §3.5 checklist → 视为 **Phase 3 未执行**，回到 §3.0。
49
49
 
50
50
  **per-plan 状态 SSOT**：`{HARNESS_DIR}/status.json`（per-plan Todo/InProgress/InReview/Done）。
51
- **迭代状态 SSOT**：`{ITERATION_DIR}/<id>-delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引。
51
+ **迭代状态 SSOT**：`{ITERATION_DIR}/<id>/delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）。
52
52
  **迭代分支 SSOT**：root `metadata.iteration_base_branch` + `metadata.target_branch`（`status.json`）；compass frontmatter 镜像同名字段。解析顺序见 §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。
53
53
 
54
54
  ## 产物存储位置
55
55
 
56
- **SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。迭代 compass → `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`；迭代索引 → `{ITERATION_DIR}/README.md`。
56
+ **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` 仅兼容读。
57
57
 
58
58
  ---
59
59
 
@@ -100,9 +100,9 @@ compass/plans 初稿落盘前，必须锁定**单一**迭代方向、成功标
100
100
 
101
101
  **Autonomous branch resolve**：仅 `autonomous` 模式；解析顺序与 STOP 规则见 **`references/autonomous-direction-lock.md`**（勿把该顺序套用到 interactive 以跳过向用户确认）。
102
102
 
103
- ### 1.3 创建迭代 compass
103
+ ### 1.3 创建迭代 package + compass
104
104
 
105
- 写入 `{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`。
105
+ 创建 `{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`。
106
106
 
107
107
  ```markdown
108
108
  ---
@@ -151,11 +151,11 @@ plans: []
151
151
 
152
152
  ### 1.4 更新索引
153
153
 
154
- 在 `{ITERATION_DIR}/README.md` 中添加一行（首次创建时建立表头）：
154
+ 在 `{ITERATION_DIR}/README.md` 中添加**一行**（首次创建时建立表头；**一行 = 一次迭代**，不拆 compass/workspace 双行）：
155
155
 
156
- | Document | Iteration | Description | Status |
157
- |----------|-----------|-------------|--------|
158
- | `<iteration-id>-delivery-compass.md` | `<iteration-id>` | `<简短描述>` | `active` |
156
+ | Iteration | Path | Description | Status |
157
+ |-----------|------|-------------|--------|
158
+ | `<iteration-id>` | [`<iteration-id>/`](<iteration-id>/) | `<简短描述>` | `active` |
159
159
 
160
160
  ### 1.5 登记到 status.json（formal iteration 必填）
161
161
 
@@ -174,8 +174,8 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
174
174
  | 树 | iteration-start 主责 | 说明 |
175
175
  |----|---------------------|------|
176
176
  | **`{SPECS_DIR}/`** | product-manager、architect | **长期**规范性产出：锁定规格、ADR、契约；plan `primary_spec` / `spec_refs` 主要挂此处 |
177
- | **`{ITERATION_DIR}/`** | product-manager、architect、PM | compass（根）+ **`<iteration-id>/` workspace**（迭代级 specs & guides） |
178
- | **`{KNOWLEDGE_DIR}/`** | **非** start/execute 直写；**`mstar-compound`** @ iteration-close（含 workspace **提升**） | 可复用实施 SSOT |
177
+ | **`{ITERATION_DIR}/`** | product-manager、architect、PM | **`<iteration-id>/` package**（`delivery-compass.md` + 迭代级 specs & guides） |
178
+ | **`{KNOWLEDGE_DIR}/`** | **非** start/execute 直写；**`mstar-compound`** @ iteration-close（含 package **提升**） | 可复用实施 SSOT |
179
179
 
180
180
  **禁止**：product/architect 在 §1.6 向 `{KNOWLEDGE_DIR}/` **新增**；把迭代级草案写入 `{SPECS_DIR}/`（应进 `<iteration-id>/specs/` 或 guides）。
181
181
 
@@ -185,8 +185,8 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
185
185
 
186
186
  派发机制 → **`mstar-dispatch-gates`**（specialist review-and-edit dispatch，**顺序链**）。PM **不得**将迭代 harness 文档 commit 到 `spec_integration_branch`，直到：
187
187
 
188
- 1. **product-manager** → **architect** → **writing-specialist** 已按序 invoke 编辑 compass、plans、`{SPECS_DIR}/` 与 **`{ITERATION_DIR}/<iteration-id>/`** workspace（guides/specs，按需）；**不得**在 start 链向 `{KNOWLEDGE_DIR}/` 新增
189
- 2. **writing-specialist** 完成 **corpus hygiene**：全库 `{SPECS_DIR}/` + 既有 `{KNOWLEDGE_DIR}/` 卫生；错放迁回 **`<iteration-id>/`** workspace；细则 → **`iteration-corpus-hygiene.md`**、**`iteration-artifact-boundaries.md`**
188
+ 1. **product-manager** → **architect** → **writing-specialist** 已按序 invoke 编辑 compass、plans、`{SPECS_DIR}/` 与 **`{ITERATION_DIR}/<iteration-id>/`** package（guides/specs，按需）；**不得**在 start 链向 `{KNOWLEDGE_DIR}/` 新增
189
+ 2. **writing-specialist** 完成 **corpus hygiene**：全库 `{SPECS_DIR}/` + 既有 `{KNOWLEDGE_DIR}/` 卫生；错放迁回 **`<iteration-id>/`** package；细则 → **`iteration-corpus-hygiene.md`**、**`iteration-artifact-boundaries.md`**
190
190
  3. PM 将 compass `status` 设为 `locked`，并确认各 plan 的 Prepare gate（specify / clarify / plan）
191
191
 
192
192
  **顺序理由**：产品范围与优先级 → 架构与长期契约（specs）→ 行文、规格库卫生与错放纠正（须在 PM/architect 定稿后扫全库 specs）。并行会导致后手重复劳动或覆盖前手未定稿内容。OpenCode：plain role id — **`mstar-host/references/opencode.md`** § Role-mention hygiene。
@@ -235,7 +235,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
235
235
  **Metadata 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
236
236
 
237
237
  1. `{HARNESS_DIR}/status.json` → `metadata.iteration_base_branch`、`metadata.target_branch`；plan → `metadata.spec_integration_branch`
238
- 2. 若 (1) 缺字段 → 读当前迭代 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` frontmatter 同名键
238
+ 2. 若 (1) 缺字段 → 读当前迭代 compass frontmatter 同名键：优先 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；若无则 legacy `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`
239
239
  3. 若 compass 有值而 `status.json` 无 → **同轮 backfill** `status.json`
240
240
  4. 仍缺 → 向用户确认 base / PR target；**不得**因 `git symbolic-ref refs/remotes/origin/HEAD` 指向 `main` 就自动采用
241
241
 
@@ -267,7 +267,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
267
267
  - 每次 Completion Report v2 后更新 `status.json` + 主 plan
268
268
  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）。
269
269
  4. **Plan complete — merge back**：合并 plan feature branch → `spec_integration_branch`；在下一 plan 或 QC 前解决冲突
270
- 5. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 的 `## Plans` 表状态列
270
+ 5. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` 的 `## Plans` 表状态列
271
271
  6. **Next plan** 从步骤 1 继续
272
272
 
273
273
  全部 plan `Done` → **Phase transition gate**（见上文 **Phase transition gates**）：
@@ -354,12 +354,12 @@ PM **必须**在对话中打印本 checklist；不得默认同过。
354
354
  PM 批量触发后须：
355
355
 
356
356
  1. 收集本迭代 plan 实现 / debug / review 素材，筛候选知识
357
- 2. **盘点** `{ITERATION_DIR}/<iteration-id>/**` workspace（`guides/`、`specs/`）— **`mstar-compound`**「Iteration workspace promotion」；提升值得保留者进 `{KNOWLEDGE_DIR}/`
357
+ 2. **盘点** `{ITERATION_DIR}/<iteration-id>/**` package（`guides/`、`specs/`；默认排除 `delivery-compass.md`）— **`mstar-compound`**「Iteration package promotion」；提升值得保留者进 `{KNOWLEDGE_DIR}/`
358
358
  3. 逐条过 `mstar-compound` 自检；跳过项记入 compass `## Compound Round Summary`
359
359
  4. 写入或更新 `{KNOWLEDGE_DIR}/<category>/<slug>.md`；新领域词更新 `CONCEPTS.md`
360
360
  5. **每篇**新 doc 完成 Phase 6（`{KNOWLEDGE_DIR}/README.md` 登记）
361
361
 
362
- 若无结晶且无 workspace 提升，仍在 `## Compound Round Summary` 写明 `无可结晶知识` / workspace 盘点结论及原因。
362
+ 若无结晶且无 package 提升，仍在 `## Compound Round Summary` 写明 `无可结晶知识` / package 盘点结论及原因。
363
363
 
364
364
  ### 3.3 更新 roadmap
365
365
 
@@ -383,7 +383,7 @@ PM 批量触发后须：
383
383
  PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git commit`；然后进入 **Phase 4**（§4）：
384
384
 
385
385
  - [ ] §3.1 前置 gate 已打印并满足
386
- - [ ] §3.2 compound 完成；**`<iteration-id>/` workspace 已盘点**（提升 / 保留 / 跳过已记入 Compound Summary）；新增 knowledge doc 均已登记 `{KNOWLEDGE_DIR}/README.md`（或已记录无可结晶原因）
386
+ - [ ] §3.2 compound 完成；**`<iteration-id>/` package 已盘点**（提升 / 保留 / 跳过已记入 Compound Summary）；新增 knowledge doc 均已登记 `{KNOWLEDGE_DIR}/README.md`（或已记录无可结晶原因）
387
387
  - [ ] §3.3 `## Roadmap Position` current iteration 已标 `delivered`；tracker / STRATEGY 已按需更新
388
388
  - [ ] §3.4 frontmatter `status: completed` + `end_date`；Quality Gate Summary + Compound Summary + Retrospective 已填
389
389
  - [ ] 当前分支是 `spec_integration_branch`
@@ -392,7 +392,7 @@ PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git co
392
392
  **Commit 到 integration 分支**：
393
393
 
394
394
  ```bash
395
- git add {ITERATION_DIR}/<id>-delivery-compass.md {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
395
+ git add {ITERATION_DIR}/<id>/ {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
396
396
  git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
397
397
  git push origin <spec_integration_branch>
398
398
  ```
@@ -471,8 +471,8 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
471
471
  | `mstar-branch-worktree` | 分支/merge/worktree 隔离 |
472
472
  | `mstar-compound` | iteration-close 中触发知识结晶（**唯一**默认 knowledge 新增路径） |
473
473
  | `mstar-compound-refresh` | iteration-close 后可触发知识维护 |
474
- | `references/iteration-artifact-boundaries.md` | Phase 1 specs / iterations workspace / knowledge 分工 |
475
- | `references/iteration-workspace-readme-template.md` | `<iteration-id>/README.md` 可选模板 |
474
+ | `references/iteration-artifact-boundaries.md` | Phase 1 specs / iteration package / knowledge 分工 |
475
+ | `references/iteration-workspace-readme-template.md` | `<iteration-id>/README.md` 可选模板（Documents 单表） |
476
476
  | `references/iteration-corpus-hygiene.md` | §1.6 writing-specialist specs 卫生细则 |
477
477
  | `references/autonomous-direction-lock.md` | §1.2 autonomous direction lock、scale budget、branch resolve |
478
478
  | `mstar-strategy` | iteration-start 时读 `STRATEGY.md` 对齐方向 |
@@ -492,7 +492,9 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
492
492
  - 不要将 **Phase 4 开 PR** 等同于 **迭代交付完成** — 必须完成 **Phase 5** §5.5 merge-ready loop
493
493
  - **不要在 iteration-start §1.6 由 product/architect 向 `{KNOWLEDGE_DIR}/` 新增文档**（知识 → iteration-close **`mstar-compound`**）
494
494
  - **不要把迭代级草案写入 `{SPECS_DIR}/`**（应进 `{ITERATION_DIR}/<iteration-id>/specs/` 或 `guides/`）
495
- - **不要在 iteration-close 跳过 `<iteration-id>/` workspace 盘点**（compound 提升 SSOT → **`mstar-compound`**）
495
+ - **不要在 iteration-close 跳过 `<iteration-id>/` package 盘点**（compound 提升 SSOT → **`mstar-compound`**）
496
+ - **不要新写根目录 `<iteration-id>-delivery-compass.md`**（canonical：`<iteration-id>/delivery-compass.md`；legacy flat 仅兼容读）
497
+ - **不要在 `{ITERATION_DIR}/README.md` 为同一迭代登记 compass + workspace 双行**（一行 = 一次迭代）
496
498
  - **不要在 iteration-start §1.6 跳过 writing-specialist 全库 specs corpus hygiene**（仅改当轮 compass/plans 而不扫 `{SPECS_DIR}/`）
497
499
  - **不要在 SDD plan 上以单席 `qc.md` 收尾**（除非用户书面 `QC mode: single — override`）
498
500
  - **不要在未显式 `Direction lock mode: autonomous` 时跳过与用户收敛方向**（interactive 仍为默认）
package/harness-skills/mstar-iteration/references/autonomous-direction-lock.md CHANGED
@@ -49,7 +49,7 @@ Count only **business delivery plans** registered in compass / `status.json` who
49
49
  |--------------------------|----------|
50
50
  | Phase 1 process | Research, direction lock, Review & Edit chain, compass/index/`status.json` bootstrap |
51
51
  | Phase 2 process | Per-task SDD briefs/reviews, plan QC tri, QA gate, branch merge-back |
52
- | Phase 3–5 process | Compound / workspace promotion, iteration-close, Create PR, merge-ready / CI babysit |
52
+ | Phase 3–5 process | Compound / package promotion, iteration-close, Create PR, merge-ready / CI babysit |
53
53
  | Meta “plans” | “run QC”, “do compound”, “open PR”, “setup harness”, “write compass only” |
54
54
 
55
55
  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
@@ -1,6 +1,6 @@
1
1
  # iteration-start 产物边界（specs · iterations · knowledge）
2
2
 
3
- > **When**: Phase 1 — PM 初稿落盘、§1.6 Review & Edit chain；Phase 2 迭代执行期可继续写入 iteration workspace；Phase 3 iteration-close 经 **`mstar-compound`** 提升。
3
+ > **When**: Phase 1 — PM 初稿落盘、§1.6 Review & Edit chain；Phase 2 迭代执行期可继续写入 iteration package；Phase 3 iteration-close 经 **`mstar-compound`** 提升。
4
4
  > **Conflict**: 与 `mstar-plan-artifacts/references/knowledge-and-designs.md` 一致；冲突以 **`mstar-harness-core`** 为准。
5
5
 
6
6
  ## 三棵树分工（HARD）
@@ -8,48 +8,56 @@
8
8
  | 树 | 路径 | 长期价值 | 谁写（何时） | 典型内容 |
9
9
  |----|------|----------|--------------|----------|
10
10
  | **Specs（仓库级）** | `{SPECS_DIR}/` | **是** — 跨迭代规范性权威 | product / architect @ **iteration-start** | 已锁定产品/API 规格、ADR、契约 |
11
- | **Iterations** | `{ITERATION_DIR}/` | **迭代级** — 历史快照；可提升 | product / architect / PM @ start & execute | compass + **`<iteration-id>/` workspace** |
12
- | **Knowledge** | `{KNOWLEDGE_DIR}/` | **是** — 可复用实施 SSOT | **`mstar-compound`** @ **iteration-close**（含 workspace 提升） | 结晶、提升后的长期实施知识 |
11
+ | **Iterations** | `{ITERATION_DIR}/` | **迭代级** — 历史快照；可提升 | product / architect / PM @ start & execute | **`<iteration-id>/` package**（compass + specs/guides） |
12
+ | **Knowledge** | `{KNOWLEDGE_DIR}/` | **是** — 可复用实施 SSOT | **`mstar-compound`** @ **iteration-close**（含 package 提升） | 结晶、提升后的长期实施知识 |
13
13
 
14
14
  ```text
15
15
  iteration-start / execute
16
- product / architect ──► {SPECS_DIR}/ 已锁定的长期规格
17
- ──► {ITERATION_DIR}/<id>/ 迭代级 specs + guides（工作区）
18
- ✗ {KNOWLEDGE_DIR}/ 不直接新增
16
+ product / architect ──► {SPECS_DIR}/ 已锁定的长期规格
17
+ ──► {ITERATION_DIR}/<id>/ 迭代 package（compass + specs + guides）
18
+ ✗ {KNOWLEDGE_DIR}/ 不直接新增
19
19
 
20
20
  iteration-close (§3.2)
21
21
  mstar-compound ──► 读 plan 素材 + {ITERATION_DIR}/<id>/**
22
- ──► {KNOWLEDGE_DIR}/ 提升值得保留的 specs/guides
22
+ ──► {KNOWLEDGE_DIR}/ 提升值得保留的 specs/guides
23
23
  ```
24
24
 
25
- ## `{ITERATION_DIR}/<iteration-id>/` 工作区（迭代级 specs & guides）
25
+ ## `{ITERATION_DIR}/<iteration-id>/` 迭代 package（目录优先）
26
26
 
27
- compass 仍在根目录：`**{ITERATION_DIR}/<iteration-id>-delivery-compass.md**`（现有约定）。**迭代级** specs / guides 放入同名子目录工作区：
27
+ **Canonical layout**（新 iteration-start **只写**此形态）：
28
28
 
29
29
  ```text
30
30
  {ITERATION_DIR}/
31
- README.md
32
- <iteration-id>-delivery-compass.md
31
+ README.md # 根索引：每迭代一行 → 指向 <iteration-id>/
33
32
  <iteration-id>/
34
- README.md # 可选：本迭代工作区索引
35
- guides/ # 探索笔记、过程指南、未锁定权衡
36
- specs/ # 迭代级规格草案（尚未升格到 {SPECS_DIR}/ 或 knowledge）
37
- <flat-files>.md # 允许；大迭代可再分子目录
33
+ delivery-compass.md # 迭代状态 SSOT（frontmatter status）
34
+ README.md # 本迭代文档索引（有 guides/specs 时推荐）
35
+ guides/ # 探索笔记、过程指南、未锁定权衡
36
+ specs/ # 迭代级规格草案
38
37
  ```
39
38
 
40
39
  | 子路径 | 放什么 | 不放什么 |
41
40
  |--------|--------|----------|
42
- | **`<iteration-id>/guides/`** | 候选方案、调研、会议记录、实施过程说明 | 已锁定的仓库级规范 |
43
- | **`<iteration-id>/specs/`** | 本迭代演进中的规格、迭代内契约草稿 | 已锁定、跨迭代 `{SPECS_DIR}/` 级权威（应升格或已在 `{SPECS_DIR}/`） |
44
- | **compass（根）** | 范围、plans 表、验收、分支策略 | 长文探索正文（链到 workspace） |
41
+ | **`delivery-compass.md`** | 范围、plans 表、验收、分支策略、close 摘要 | 长文探索正文（链到 `guides/` / `specs/`） |
42
+ | **`guides/`** | 候选方案、调研、会议记录、实施过程说明 | 已锁定的仓库级规范 |
43
+ | **`specs/`** | 本迭代演进中的规格、迭代内契约草稿 | 已锁定、跨迭代 `{SPECS_DIR}/` 级权威（应升格或已在 `{SPECS_DIR}/`） |
44
+ | **`README.md`** | 本 package 内 documents 索引（单表即可） | 替代根 `{ITERATION_DIR}/README.md` |
45
45
 
46
- **何时用 workspace 而非单文件 working guide**：一篇 guide 不够时，**默认**用 `<iteration-id>/` 目录；单文件 `<iteration-id>-working-guide.md` 仍允许作轻量入口（可链接进 workspace）。
46
+ **索引**：
47
47
 
48
- **索引**：`{ITERATION_DIR}/README.md` 登记 compass 行 + workspace 目录行；workspace 内 `README.md` 列出 `guides/`、`specs/` 下文档。
48
+ - **`{ITERATION_DIR}/README.md`**：**一行 = 一次迭代**（指向 `<iteration-id>/` 目录，**不**再拆 compass 行 + workspace 行）。
49
+ - **`<iteration-id>/README.md`**：列出本目录下 `guides/`、`specs/`（及其它文档）；模板 → **`iteration-workspace-readme-template.md`**。
50
+
51
+ **Compass 解析顺序**（读）：
52
+
53
+ 1. `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`（canonical）
54
+ 2. Legacy flat：`{ITERATION_DIR}/<iteration-id>-delivery-compass.md`（仅兼容读；新写禁止）
55
+
56
+ **禁止（新写）**：根目录 `<iteration-id>-delivery-compass.md`、根目录 `<iteration-id>-working-guide.md`。轻量入口一律进 `<iteration-id>/guides/`。
49
57
 
50
58
  ## `{SPECS_DIR}/` 准入（仓库级长期）
51
59
 
52
- 写入 `{SPECS_DIR}/` 前须满足 **至少一条**（与 iteration workspace 区分）：
60
+ 写入 `{SPECS_DIR}/` 前须满足 **至少一条**（与 iteration package 区分）：
53
61
 
54
62
  - 决策**已锁定**，变更需显式评审
55
63
  - 跨 plan、跨迭代仍成立
@@ -59,21 +67,21 @@ compass 仍在根目录：`**{ITERATION_DIR}/<iteration-id>-delivery-compass.md*
59
67
 
60
68
  - 仍在迭代内演进的草案 → **`<iteration-id>/specs/`**
61
69
  - 探索 scratch → **`<iteration-id>/guides/`**
62
- - 实施踩坑（未整理）→ 留 workspace 或 plan 素材，**close 时 compound 提升**
70
+ - 实施踩坑（未整理）→ 留 package 或 plan 素材，**close 时 compound 提升**
63
71
 
64
72
  ## Knowledge 与 compound 提升
65
73
 
66
74
  - **`{KNOWLEDGE_DIR}/` 新增**：默认仅在 **iteration-close** §3.2 **`mstar-compound`**。
67
- - **提升来源（iteration-close）**：除 plan 实现/debug/review 素材外，**必须盘点** `{ITERATION_DIR}/<iteration-id>/**`（`guides/`、`specs/`、扁平文件）。值得跨迭代复用的内容 → 按 compound 双轨模板**重写**进 `{KNOWLEDGE_DIR}/`（非整文件复制）；细则 → **`mstar-compound`**「Iteration workspace promotion」。
68
- - **提升后**：在源文件顶部或 workspace `README.md` 标注 `Promoted to: {KNOWLEDGE_DIR}/...`；源文件**保留**为迭代历史（或迁入 `<iteration-id>/archived/` 若团队约定）。
69
- - **iteration-start §1.6**：product / architect **不得**向 `{KNOWLEDGE_DIR}/` **新增**；误写由 writing-specialist 迁回 **workspace**。
75
+ - **提升来源（iteration-close）**：除 plan 实现/debug/review 素材外，**必须盘点** `{ITERATION_DIR}/<iteration-id>/**`（`guides/`、`specs/`、扁平文件；**默认排除** `delivery-compass.md` 除非 PM 显式纳入）。值得跨迭代复用的内容 → 按 compound 双轨模板**重写**进 `{KNOWLEDGE_DIR}/`（非整文件复制）；细则 → **`mstar-compound`**「Iteration package promotion」。
76
+ - **提升后**：在源文件顶部或 package `README.md` 标注 `Promoted to: {KNOWLEDGE_DIR}/...`；源文件**保留**为迭代历史（或迁入 `<iteration-id>/archived/` 若团队约定）。
77
+ - **iteration-start §1.6**：product / architect **不得**向 `{KNOWLEDGE_DIR}/` **新增**；误写由 writing-specialist 迁回 **package**。
70
78
 
71
79
  ## §1.6 各角色编辑范围
72
80
 
73
81
  | 角色 | 必须编辑 | 禁止 |
74
82
  |------|----------|------|
75
83
  | **product-manager** | compass、plans、`{SPECS_DIR}/`、`{ITERATION_DIR}/<iteration-id>/`（guides/specs） | `{KNOWLEDGE_DIR}/` **新增**；迭代草案写入 `{SPECS_DIR}/` |
76
- | **architect** | 同上 + workspace `specs/` 技术向 | 同上；在 `{SPECS_DIR}/` 堆实施踩坑 |
84
+ | **architect** | 同上 + package `specs/` 技术向 | 同上；在 `{SPECS_DIR}/` 堆实施踩坑 |
77
85
  | **writing-specialist** | 当轮文档 + `{SPECS_DIR}/` corpus hygiene + 既有 knowledge 卫生 | 代替 compound **提升**；跳过 specs 全库审查 |
78
86
 
79
87
  Phase 2 执行期：各角色可继续向 **`<iteration-id>/`** 追加 guides/specs；**仍不**直写 `{KNOWLEDGE_DIR}/`。
@@ -83,12 +91,13 @@ Phase 2 执行期：各角色可继续向 **`<iteration-id>/`** 追加 guides/sp
83
91
  | 内容 | 挂接键 | 路径 |
84
92
  |------|--------|------|
85
93
  | 仓库级锁定规格 | `primary_spec` / `spec_refs` | `{SPECS_DIR}/` |
86
- | 迭代上下文 | `iteration_compass` / `iteration_refs` | compass + `{ITERATION_DIR}/<iteration-id>/...` |
94
+ | 迭代上下文 | `iteration_compass` / `iteration_refs` | `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` + 同目录下 docs |
87
95
  | 知识库（已有） | 仅历史链接 | `{KNOWLEDGE_DIR}/` — **start 不新增** |
88
96
 
89
97
  ## 反模式
90
98
 
91
99
  - 用 `{KNOWLEDGE_DIR}/` 存迭代探索（应进 `<iteration-id>/guides/`）
92
- - 把迭代 workspace 草案直接复制进 `{SPECS_DIR}/` 而不锁定评审
93
- - iteration-close **只做** plan 素材 compound、**不**盘点 `<iteration-id>/` workspace
100
+ - 把迭代 package 草案直接复制进 `{SPECS_DIR}/` 而不锁定评审
101
+ - iteration-close **只做** plan 素材 compound、**不**盘点 `<iteration-id>/` package
94
102
  - 提升时整文件复制到 knowledge（应 compound 结构化重写）
103
+ - 新写仍把 compass 放在 `{ITERATION_DIR}/` 根目录（应用 `<iteration-id>/delivery-compass.md`）
package/harness-skills/mstar-iteration/references/iteration-compass-template.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Iteration Compass Template
2
2
 
3
- Copy this template when creating a new iteration compass in `{ITERATION_DIR}/`.
3
+ Copy this template when creating `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`.
4
4
 
5
5
  ```markdown
6
6
  ---
@@ -71,19 +71,15 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
71
71
  |------|-----------|--------|------------|
72
72
  | <risk> | Low/Med/High | Low/Med/High | <mitigation> |
73
73
 
74
- ## Iteration workspace (optional)
74
+ ## Iteration package
75
75
 
76
- > 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`**.
76
+ > Sibling paths under `{ITERATION_DIR}/<iteration-id>/` — not in `{SPECS_DIR}/` or `{KNOWLEDGE_DIR}/`. Promoted to knowledge at iteration-close via **`mstar-compound`**.
77
77
 
78
78
  | Path | Purpose |
79
79
  |------|---------|
80
- | `<iteration-id>/guides/` | Exploration, process notes |
81
- | `<iteration-id>/specs/` | Iteration-scoped spec drafts |
82
- | `<iteration-id>/README.md` | Workspace index (recommended when non-trivial) |
83
-
84
- Link from compass when used:
85
-
86
- - Workspace: `<iteration-id>/` | <one-line purpose>
80
+ | `guides/` | Exploration, process notes |
81
+ | `specs/` | Iteration-scoped spec drafts |
82
+ | `README.md` | Package document index (recommended when non-trivial) |
87
83
 
88
84
  ## Quality Gate Summary
89
85
 
@@ -132,7 +128,7 @@ Notes:
132
128
  | `## Non-Goals` | Yes | Phase 1 |
133
129
  | `## Roadmap Position` | **Yes** | Phase 1（必填节，非散落于 general context prose）；Phase 3 §3.3（current iteration → `delivered`） |
134
130
  | `## Risk Register` | Optional | Phase 1, Phase 2 (update) |
135
- | Iteration workspace (`<iteration-id>/`) | Optional | Phase 1 §1.5.5 — `guides/` + `specs/`; index in `{ITERATION_DIR}/README.md` |
131
+ | Iteration package (`guides/` / `specs/`) | Optional | Phase 1 §1.5.5; root index one row → `{ITERATION_DIR}/README.md` |
136
132
  | `## Quality Gate Summary` | Yes | Phase 3 §3.4 |
137
133
  | `## Compound Round Summary` | Yes | Phase 3 §3.4 |
138
134
  | `## Iteration Retrospective` | Recommended | Phase 3 §3.4 |
@@ -141,5 +137,6 @@ Notes:
141
137
 
142
138
  若仓库中已有 compass **无** YAML frontmatter、**无** `## Roadmap Position`，或只有 prose completion status：
143
139
 
144
- - **新迭代**：Phase 1 必须按本模板重写，不延续 prose-only 惯例。
140
+ - **新迭代**：Phase 1 必须按本模板写入 **`{ITERATION_DIR}/<iteration-id>/delivery-compass.md`**，不延续 prose-only 或根目录 flat 文件惯例。
145
141
  - **收口时**：`mstar-iteration` §3.0.5 在 Phase 3 入口规范化，再执行 §3.3–§3.4。
142
+ - **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
@@ -1,51 +1,45 @@
1
- # iteration-start corpus hygiene（specs primary · knowledge read-only）
1
+ # Iteration corpus hygiene（writing-specialist · §1.6）
2
2
 
3
- > **When**: Phase 1 §1.6 — **writing-specialist** only, after product/architect landed compass / plans / `{SPECS_DIR}/` / **`{ITERATION_DIR}/<iteration-id>/`** workspace.
3
+ > **When**: Phase 1 §1.6 — **writing-specialist** only, after product/architect landed compass / plans / `{SPECS_DIR}/` / **`{ITERATION_DIR}/<iteration-id>/`** package.
4
4
  > **Boundaries**: **`iteration-artifact-boundaries.md`** — no `{KNOWLEDGE_DIR}/` adds @ start; iteration drafts → **`<iteration-id>/guides/`** or **`specs/`**.
5
5
 
6
- ## Scope (HARD)
6
+ ## Scope
7
7
 
8
- | Priority | Tree | Action |
9
- |----------|------|--------|
10
- | **Primary** | `{SPECS_DIR}/**` | Full active corpus review |
11
- | **Included** | `{ITERATION_DIR}/<iteration-id>/**` | Workspace guides/specs + compass cross-links |
12
- | **Secondary** | `{KNOWLEDGE_DIR}/**` (existing) | Archive / relocate only — **no** new docs |
13
- | **Included** | `{PLAN_DIR}/` plans touched this iteration | Spec refs, terminology |
8
+ | | Path | Notes |
9
+ |--|------|-------|
10
+ | **Primary** | `{SPECS_DIR}/**` | Full-tree hygiene (lock vs draft, naming, index) |
11
+ | **Included** | `{ITERATION_DIR}/<iteration-id>/**` | Package guides/specs + compass cross-links |
12
+ | **Existing only** | `{KNOWLEDGE_DIR}/**` | Archive / misplaced correction — **no** new knowledge docs |
13
+ | **Out of scope** | New `{KNOWLEDGE_DIR}/` writes | → **`mstar-compound`** @ iteration-close |
14
14
 
15
- **Out of scope**: compound promotion (iteration-close); per-plan review bundles (`{SDD_DIR}/review/`); code.
15
+ ## Placement corrections
16
16
 
17
- ## Misplaced content (relocate)
18
-
19
- | Found in | Target |
20
- |----------|--------|
17
+ | Found in | Misplaced as | Move to |
18
+ |----------|--------------|---------|
21
19
  | `{SPECS_DIR}/` | Iteration-only draft → `{ITERATION_DIR}/<iteration-id>/specs/` or `guides/` |
22
- | `{SPECS_DIR}/` | Implementation/debug notes → workspace `guides/` (compound @ close) |
20
+ | `{SPECS_DIR}/` | Implementation pitfall prose → package `guides/` or leave for compound |
23
21
  | `{KNOWLEDGE_DIR}/` | New exploration from start chain → `<iteration-id>/guides/` or archive |
24
- | Flat `{ITERATION_DIR}/*-working-guide.md` | OK as entry; or merge into `<iteration-id>/guides/` when workspace exists |
25
-
26
- ## Classification
27
-
28
- Same as before for specs + existing knowledge: Active / Superseded / Redundant / Obsolete / Unclear → archive under `archived/specs/` or `archived/knowledge/` with relative path preserved.
22
+ | Flat `{ITERATION_DIR}/*-working-guide.md`（legacy） | → `<iteration-id>/guides/` |
23
+ | Flat `{ITERATION_DIR}/*-delivery-compass.md`（legacy） | Prefer migrate to `<iteration-id>/delivery-compass.md` when touching that iteration |
29
24
 
30
- ## Index and metadata
25
+ ## Index updates（after edits）
31
26
 
32
- 1. `{SPECS_DIR}/README.md` — update as needed
33
- 2. `{KNOWLEDGE_DIR}/README.md` — archive rows only; no new iteration exploration rows
34
- 3. `{ITERATION_DIR}/README.md` — compass + **`<iteration-id>/` workspace** directory row
35
- 4. `{ITERATION_DIR}/<iteration-id>/README.md` — list guides/specs (create if non-trivial)
36
- 5. `plans[].metadata` — `primary_spec` / `spec_refs` → `{SPECS_DIR}/`; `iteration_refs` → workspace paths
27
+ 1. `{SPECS_DIR}/README.md`（若存在）— 规格索引
28
+ 2. `{KNOWLEDGE_DIR}/README.md` — Status / archive only（无新增行来自 start 链）
29
+ 3. `{ITERATION_DIR}/README.md` — **一行 = 一次迭代**（目录链接，非 compass+workspace 双行）
30
+ 4. `{ITERATION_DIR}/<iteration-id>/README.md` — Documents 单表列出 guides/specs（非 trivial 时创建）
37
31
 
38
- ## Evidence of done
32
+ ## Done signals
39
33
 
40
- - No iteration scratch left in `{SPECS_DIR}/`
41
- - Workspace used for iteration-level drafts (`<iteration-id>/guides|specs/`)
42
- - No new `{KNOWLEDGE_DIR}/` from §1.6 chain
43
- - Completion Report lists workspace paths + spec hygiene moves
34
+ - Specs tree hygiene complete（draft vs locked clear）
35
+ - Package used for iteration-level drafts (`<iteration-id>/guides|specs/`)
36
+ - Misplaced knowledge / specs moved or archived with index Status updated
37
+ - No new `{KNOWLEDGE_DIR}/` documents from this chain
44
38
 
45
- ## Distinction from compound @ iteration-close
39
+ ## Close vs start
46
40
 
47
- | | §1.6 hygiene | compound workspace promotion |
48
- |--|--------------|------------------------------|
49
- | When | iteration-start | iteration-close §3.2 |
41
+ | Tree | Start (§1.6) | Close (§3.2 compound） |
42
+ |------|--------------|------------------------|
43
+ | `{SPECS_DIR}/` | Hygiene + lock clarity | Usually unchanged |
50
44
  | `{ITERATION_DIR}/<id>/` | Create/edit drafts | **Inventory → promote** to `{KNOWLEDGE_DIR}/` |
51
- | `{KNOWLEDGE_DIR}/` | No new writes | Structured new docs |
45
+ | `{KNOWLEDGE_DIR}/` | Hygiene / archive only | **Primary write path** |
package/harness-skills/mstar-iteration/references/iteration-workspace-readme-template.md CHANGED
@@ -1,23 +1,19 @@
1
- # Iteration workspace README (template)
1
+ # Iteration package README (template)
2
2
 
3
- Optional index inside `{ITERATION_DIR}/<iteration-id>/`. Copy when the workspace has more than a few files.
3
+ Optional index inside `{ITERATION_DIR}/<iteration-id>/`. Copy when the package has more than a few files beyond `delivery-compass.md`.
4
4
 
5
5
  ```markdown
6
- # <iteration-id> workspace
6
+ # <iteration-id>
7
7
 
8
- Iteration-scoped **specs** and **guides** — not `{KNOWLEDGE_DIR}/`. Worthy content is **promoted** at iteration-close via `mstar-compound`.
8
+ Iteration package — `delivery-compass.md` + specs/guides. Not `{KNOWLEDGE_DIR}/`. Worthy content is **promoted** at iteration-close via `mstar-compound`.
9
9
 
10
- ## Guides
10
+ ## Documents
11
11
 
12
- | Document | Description | Status |
13
- |----------|-------------|--------|
14
- | [guides/<name>.md](guides/<name>.md) | <purpose> | draft / active / promoted |
15
-
16
- ## Specs (iteration-level)
17
-
18
- | Document | Description | Status |
19
- |----------|-------------|--------|
20
- | [specs/<name>.md](specs/<name>.md) | <purpose> | draft / locked-in-{SPECS_DIR} / promoted |
12
+ | Document | Kind | Description | Status |
13
+ |----------|------|-------------|--------|
14
+ | [delivery-compass.md](delivery-compass.md) | compass | Scope, plans, branch policy | active / locked / completed |
15
+ | [guides/<name>.md](guides/<name>.md) | guide | <purpose> | draft / active / promoted |
16
+ | [specs/<name>.md](specs/<name>.md) | spec | <purpose> | draft / locked-in-{SPECS_DIR} / promoted |
21
17
 
22
18
  ## Promotion log (filled at iteration-close)
23
19
 
@@ -26,4 +22,6 @@ Iteration-scoped **specs** and **guides** — not `{KNOWLEDGE_DIR}/`. Worthy con
26
22
  | | | | |
27
23
  ```
28
24
 
29
- **Status values**: `draft` | `active` | `promoted` (link knowledge path) | `superseded` | `snapshot-only`
25
+ **Kind**: `compass` | `guide` | `spec` | `other`
26
+
27
+ **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
@@ -13,26 +13,27 @@
13
13
  |------|----------|-------------|
14
14
  | **`docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
15
15
  | **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap — **跨迭代长期权威** | 产品/API 规范性最高权威；**iteration-start** 由 product/architect 主写 |
16
- | **`{ITERATION_DIR}`**（可选） | delivery compass + **`<iteration-id>/` workspace**（`guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
16
+ | **`{ITERATION_DIR}`**（可选） | **`<iteration-id>/` package**（`delivery-compass.md` + `guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
17
17
  | **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker — **经 `mstar-compound` 结晶** | Agent handoff；**不**在 iteration-start 由 product/architect 新增 |
18
18
  | **`{PLAN_DIR}/`** | 单 plan 主文件、durable gate summary、可选 `residuals/` | 计划执行与长期决策留档 |
19
19
 
20
20
 
21
21
  **不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC/QA 原始过程报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{SDD_DIR}/review/`；长期 gate 摘要回写主 plan。
22
22
 
23
- ## `{ITERATION_DIR}`（可选·迭代/版本级 compass）
23
+ ## `{ITERATION_DIR}`（可选·迭代/版本级 package）
24
24
 
25
25
  - **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.mstar/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列；legacy 项目可继续为 `.agents/iterations/`）。
26
- - **放什么**：delivery compass（根目录 `*-delivery-compass*.md`）；**`<iteration-id>/` 工作区** — `guides/`（探索、过程）、`specs/`（迭代级规格草案）；遗留规划快照。
26
+ - **放什么**：**`<iteration-id>/` package** — `delivery-compass.md`（迭代状态 SSOT）；`guides/`（探索、过程）；`specs/`（迭代级规格草案）；可选 package `README.md`；遗留规划快照。
27
27
  - **不放什么**：已锁定的仓库级规范（→ **`{SPECS_DIR}/`**）；已提升的跨迭代实施 SSOT（→ **`{KNOWLEDGE_DIR}/`**，经 compound）；单 plan QC/QA 原始报告（→ `{SDD_DIR}/review/`）。
28
- - **索引**：`**{ITERATION_DIR}/README.md**` 登记 compass + workspace 目录；`<iteration-id>/README.md` 登记工作区内文档。
29
- - **维护**：`@product-manager` / `@architect` 起草 workspace；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 workspace 并**提升**至 `{KNOWLEDGE_DIR}/`。
28
+ - **索引**：`**{ITERATION_DIR}/README.md**` **一行 = 一次迭代**（指向 `<iteration-id>/`）；`<iteration-id>/README.md` 登记 package 内文档（Documents 单表）。
29
+ - **维护**：`@product-manager` / `@architect` 起草 package；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 package 并**提升**至 `{KNOWLEDGE_DIR}/`。
30
+ - **Compass 路径**：canonical `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；legacy flat `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 仅兼容读。
30
31
 
31
32
  ## `{SPECS_DIR}`（可选·长期规格）
32
33
 
33
34
  - `{SPECS_DIR}` 解析：优先 `{HARNESS_DIR}/specs/`，否则 `{HARNESS_DIR}/designs/`；皆无则建议新建 `specs/`。
34
35
  - **放什么**：跨迭代有效、已锁定或待锁定的产品/API 规范、ADR、契约 — **iteration-start 主产出**（product/architect）。
35
- - **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ workspace 或 plan 素材，**close 时 compound 提升**）。
36
+ - **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ package 或 plan 素材，**close 时 compound 提升**）。
36
37
  - **索引**：非 trivial 树建议 `{SPECS_DIR}/README.md`；plan **`primary_spec` / `spec_refs`** 主要指向此处。
37
38
 
38
39
  ## `{KNOWLEDGE_DIR}`（可选·实施知识库）
@@ -46,7 +47,7 @@
46
47
 
47
48
  - 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
48
49
  - 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `{KNOWLEDGE_DIR}` 根（除非团队明确约定）。
49
- - 迭代 compass 文件名宜带版本/迭代标识，放在 `{ITERATION_DIR}/`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间。
50
+ - 迭代 compass 放在 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间；**不要**新写根目录 flat `*-delivery-compass.md`。
50
51
 
51
52
  ## 与 `status.json` 的链接
52
53
 
@@ -57,14 +58,14 @@
57
58
 
58
59
  1. **新增**：
59
60
  - **Specs（长期）**：`{SPECS_DIR}/` → spec 索引（若有）→ `plans[].metadata` 的 `primary_spec` / `spec_refs`
60
- - **迭代 workspace**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md` + workspace README → `iteration_refs`
61
- - **Knowledge**：**`mstar-compound`** @ iteration-close（含 workspace **提升**）→ `{KNOWLEDGE_DIR}/README.md`
61
+ - **迭代 package**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md`（目录一行）+ package README → `iteration_refs`
62
+ - **Knowledge**：**`mstar-compound`** @ iteration-close（含 package **提升**）→ `{KNOWLEDGE_DIR}/README.md`
62
63
  2. **阅读**：开发类 agent 在开始编码前，**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
63
64
  3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
64
65
  4. **归档**：
65
66
  - **iteration-start（强制）**：`writing-specialist` §1.6 以 **`{SPECS_DIR}/` 全库卫生为主**；对**既有** `{KNOWLEDGE_DIR}/` 仅归档/错放纠正，**不**新增 knowledge。细则 → **`mstar-iteration/references/iteration-corpus-hygiene.md`**。
66
67
  - **其它时机**：当文档内容已完全反映到已合并代码中、且非 iteration-start 扫库时：可将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`；可保留原位或迁入 `archived/knowledge/`。**不要**把知识库产物搬进 `{HARNESS_DIR}/archived/plans/`（该处用于**计划行**冷快照）。
67
- 5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` workspace 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
68
+ 5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` package 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
68
69
 
69
70
  ## 与 review bundle、`{PLAN_DIR}/residuals/` 的区分
70
71
 
@@ -72,7 +73,7 @@
72
73
  - `**主 plan gate summary**`：偏 **长期门禁决策摘要**（verdict、review range、R#、QA gate），随主 plan 追踪。
73
74
  - `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与根级 `**residual_findings**` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
74
75
  - `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
75
- - `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 compass 与规划快照，通常按版本索引而非按单 plan 长期复用。
76
+ - `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
76
77
  - review bundle、gate summary、residuals、knowledge、iterations 可互链，但职责不混写。
77
78
 
78
79
  ---
@@ -87,7 +88,7 @@
87
88
  | `**{SDD_DIR}/review/**` | QC / QA **流程临时证据**（`qc1.md` … `qc-consolidated.md`、`qa.md` 等），gitignored |
88
89
  | **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文** |
89
90
  | `**{KNOWLEDGE_DIR}/**` | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
90
- | `**{ITERATION_DIR}/**` | 迭代/版本级 compass；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
91
+ | `**{ITERATION_DIR}/**` | 迭代 package（`<id>/delivery-compass.md` 等）；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
91
92
 
92
93
 
93
94
  **文件命名（推荐）**：`<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
@@ -42,7 +42,7 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
42
42
  |------|------|
43
43
  | `docs/` | 人类文档：安装、贡献 |
44
44
  | `{SPECS_DIR}` | 冻结规格 / ADR |
45
- | `{ITERATION_DIR}` | 迭代 compass 快照 |
45
+ | `{ITERATION_DIR}` | 迭代 package（compass + guides/specs） |
46
46
  | `{KNOWLEDGE_DIR}` | 实现 SSOT、可复用设计 |
47
47
  | `{PLAN_DIR}/` | 主 plan、durable gate summaries、可选 residual prose |
48
48
 
package/harness-skills/mstar-plan-conventions/references/artifact-storage-paths.md CHANGED
@@ -16,9 +16,8 @@
16
16
  | **Review bundle（QC/QA 原始过程报告）** | `{HARNESS_DIR}/sdd/<plan-id>/review/`（gitignored；默认 `.mstar/sdd/<plan-id>/review/`） | `mstar-sdd`、`mstar-review-qc`、`qa-engineer` |
17
17
  | **SDD scratch** | `{HARNESS_DIR}/sdd/<plan-id>/`（gitignored；含 per-task handoff 与 `review/` bundle） | `mstar-sdd` |
18
18
  | **status.json** | `.mstar/status.json` | `mstar-plan-artifacts` |
19
- | **迭代 compass** | `.mstar/iterations/<iteration-id>-delivery-compass.md` | `mstar-iteration`（读写） |
20
- | **迭代工作区** | `.mstar/iterations/<iteration-id>/`（`guides/`、`specs/` 等） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读） |
21
- | **迭代索引** | `.mstar/iterations/README.md` | `mstar-iteration`（读写） |
19
+ | **迭代 package** | `.mstar/iterations/<iteration-id>/`（`delivery-compass.md`、`guides/`、`specs/`、可选 `README.md`） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读；默认排除 compass） |
20
+ | **迭代索引** | `.mstar/iterations/README.md`（一行 = 一次迭代） | `mstar-iteration`（读写） |
22
21
  | **规格** | `specs/`（优先），否则 `designs/` | `mstar-plan-artifacts` |
23
22
  | **archived residuals** | `.mstar/archived/residuals/<plan-id>.json` | `mstar-plan-artifacts` |
24
23
  | **archived knowledge** | `.mstar/archived/knowledge/`（保留原 `{KNOWLEDGE_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-plan-artifacts` |
@@ -41,7 +40,7 @@
41
40
  | 路径 | 说明 |
42
41
  |------|------|
43
42
  | `docs/` | 人类文档（安装、贡献指南等），知识产物不放此处 |
44
- | `{ITERATION_DIR}/` | 仅限迭代 compass，知识文档不放此处 |
43
+ | `{ITERATION_DIR}/` | 迭代 package（compass + guides/specs）；知识文档不放此处 |
45
44
  | `{SPECS_DIR}/` | 仅限冻结规格/ADR，运行时知识不放此处 |
46
45
  | `{PLAN_DIR}/reports/` | Legacy / explicit audit mode only；默认 QC/QA 原始过程报告进 `{SDD_DIR}/review/`，知识文档不放此处 |
47
46
 
package/harness-skills/mstar-roles/references/architect.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  **Always:** `mstar-harness-core`, `mstar-dispatch-gates`, `mstar-phase-gates` (Prepare: specify/clarify/plan), `mstar-plan-conventions` (`{PLAN_DIR}`, plan-writing path).
6
6
 
7
- **Typically:** `mstar-plan-artifacts` (specs, **`{ITERATION_DIR}/<id>/` workspace**); `mstar-design-md`; `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**.
7
+ **Typically:** `mstar-plan-artifacts` (specs, **`{ITERATION_DIR}/<id>/` package**); `mstar-design-md`; `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**.
8
8
 
9
9
  **On demand:** `mstar-branch-worktree` (when committing architecture docs to the business repo).
10
10
 
package/harness-skills/mstar-roles/references/product-manager.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  **Always:** `mstar-harness-core`, `mstar-dispatch-gates`, `mstar-phase-gates` (Prepare / clarify), `mstar-plan-conventions` (`{PLAN_DIR}`, plan-writing path).
6
6
 
7
- **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`**.
7
+ **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`**.
8
8
 
9
9
  **On demand:** `mstar-branch-worktree` (when committing product docs to the business repo).
10
10
 
package/harness-skills/mstar-roles/references/writing-specialist.md CHANGED
@@ -36,7 +36,7 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
36
36
  3. Marketing/copy writing
37
37
  4. Script writing
38
38
  5. Tone/style adaptation by audience
39
- 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.
39
+ 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.
40
40
 
41
41
  ## Scope Boundaries
42
42
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mstar-harness/opencode",
3
- "version": "1.2.1",
3
+ "version": "1.3.1",
4
4
  "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
5
5
  "license": "MIT",
6
6
  "repository": {