@mstar-harness/opencode 0.3.0 → 0.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 (10) hide show
  1. package/harness-skills/mstar-harness-core/SKILL.md +5 -1
  2. package/harness-skills/mstar-harness-core/references/branch-and-worktree.md +1 -1
  3. package/harness-skills/mstar-harness-core/references/open-harness-principles.md +5 -2
  4. package/harness-skills/mstar-harness-core/references/phase-gate-playbook.md +2 -1
  5. package/harness-skills/mstar-plan-conventions/SKILL.md +79 -18
  6. package/harness-skills/mstar-plan-conventions/references/harness-bootstrap-and-agents-layering.md +5 -4
  7. package/harness-skills/mstar-plan-conventions/references/knowledge-and-designs.md +33 -17
  8. package/harness-skills/mstar-plan-conventions/references/plan-files-and-reports.md +1 -1
  9. package/harness-skills/mstar-plan-conventions/references/status-and-residuals.md +5 -2
  10. package/package.json +1 -1
package/harness-skills/mstar-harness-core/SKILL.md CHANGED
@@ -63,6 +63,10 @@ description: Morning Star (启明星) harness 的**强制全局入口** ——
63
63
  - `clarify` — 关键歧义清单与结论；高影响歧义必须收敛，否则 `Blocked`。
64
64
  - **意图核对（Intent gate）**：区分**用户字面表述**与**待解决的真正问题**；手段与目标混淆须在此收敛。
65
65
  - **结构化澄清**：宿主提供 `question` 工具时优先使用；否则用结构化正文选项。宿主细节在各自的 `mstar-host` skill。
66
+ - **`clarify` 核心纪律（Prepare）**：对 plan/方案的**每个方面**持续核对，直到与用户达成**共享理解**；沿**设计决策树**逐枝下行，**一次只收敛一个决策点**及其依赖，再进入下一枝。
67
+ 1. **能查库则查库**：若问题可通过探索代码库（实现、配置、`{SPECS_DIR}`、`{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 等）得到答案，**先探索、不向用户提问**。
68
+ 2. **每问带推荐**：每个仍需用户确认的问题，须给出**推荐答案**（及简短理由），便于快速对齐。
69
+ 3. **收口摘要**：`clarify` 结束前列出：已决事项、仍 open 的假设、对 `plan` 的约束。
66
70
  - `plan` — 技术方案、模块边界/接口契约、风险与回滚点、验证计划。
67
71
  - **意图门禁**：锁 plan 前须能书面写清**真实目标 / 成功判据 / 非目标**三项；否则 Prepare 未通过。
68
72
 
@@ -245,7 +249,7 @@ description: Morning Star (启明星) harness 的**强制全局入口** ——
245
249
  | Skill | 职责范围 |
246
250
  |---|---|
247
251
  | **本 skill `mstar-harness-core`** | 总入口与不变量：状态机、Spec-Driven 双阶段门禁、Task category、`@explore` 边界、并行规则、Git 分支 / worktree、QC-QA 检出对齐、调度防串扰、升级触发、反模式、**Context7 共享检索协议**、宿主入口、最小交付循环 |
248
- | `mstar-plan-conventions` | `{HARNESS_DIR}` / `{PLAN_DIR}` 发现与初始化、`status.json` SSOT、residual findings（severity 枚举 / 生命周期 / 归档）、`notes.json`、`tech_debt_summary`、`knowledge/` 开发知识库、reports 命名、QC 三审触发时机、Done 瘦身 Profile A/B、工期预估（agent-oriented only） |
252
+ | `mstar-plan-conventions` | `{HARNESS_DIR}` / `{PLAN_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` 发现与初始化、`docs/` 与 harness 子树内容边界、`status.json` SSOT、residual findings（severity 枚举 / 生命周期 / 归档）、`notes.json`、`tech_debt_summary`、reports 命名、QC 三审触发时机、Done 瘦身 Profile A/B、工期预估（agent-oriented only） |
249
253
  | `mstar-roles` | 角色提示词总线：`agents/*.md` 仅保留 frontmatter + 参数绑定；完整角色正文在 `mstar-roles` skill 的 `references/`（含重复角色共享 reference） |
250
254
  | `mstar-review-qc` | QC 审查基线：工作流、清单、标准报告 Markdown 模板（YAML frontmatter + Findings 三档 + Summary + Verdict）、高危变更最小检查、门禁（Approve / Request Changes / Needs Discussion）、CI 门禁、residual 留档 |
251
255
  | `mstar-coding-behavior` | 跨角色通用编码行为：Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution |
package/harness-skills/mstar-harness-core/references/branch-and-worktree.md CHANGED
@@ -108,7 +108,7 @@
108
108
 
109
109
  - **语义区分（必须理解）**：开发阶段可以存在 **多个** `Worktree path`（每条约流一条检出目录）；**一轮**正式 QC 三审及与之 **逐字对齐** 的 QA 验证，在 harness 中仍只对应 **一套** `Review cwd` / `Worktree path` + **`Working branch`** + **`Review range` / `Diff basis`**（三票 QC 与 QA **共用且逐字相同**）。**不要**把「多个开发 worktree」误解成「QC 应轮流进多个目录各审一半」。
110
110
  - **推荐默认编排：先建 plan 集成分支，再挂各 worktree（PM；强推荐）**：在 **同仓**、**同一 plan** 且 **≥2 条可写并行轨** 时，按下列顺序编排可最大幅度降低 QC/QA 误用单一开发目录的风险。**此为推荐套路，不是唯一合法 Git 拓扑**；若采用其它拓扑，仍须满足本节下文 **强制**条款（派 QC 前 **单一**待审 `HEAD` + 一套对齐字段）。
111
- 1. **先起集成分支（再挂 worktree）**：在派发各轨 **实现** Assignment 之前，PM 与用户确认 **`Branch policy`**，并建立 **plan 集成分支**（Assignment 使用 **`Working branch: create <plan-integration-branch> from <base>`** 或等价明确写法；`<base>` 通常为 `origin/main` 或团队既定主线，**不得**未授权假设）。**分支名由 PM 指定**；下文 **`feature/<plan-id>-integrate`**、**`integrate/<plan-id>`** 仅为命名示例，**非强制**。
111
+ 1. **先起集成分支（再挂 worktree）**：在派发各轨 **实现** Assignment 之前，PM 与用户确认 **`Branch policy`**，并建立 **plan 集成分支**（Assignment 使用 **`Working branch: create <plan-integration-branch> from <base>`** 或等价明确写法；`<base>` 通常为 `origin/main` 或团队既定主线，**不得**未授权假设）。**分支名由 PM 指定**；下文 **`feature/<plan-id>-integrate`**、**`integrate/<plan-id>`** 仅为命名示例，**非强制**。**多 `plan_id` 同源一条 `primary_spec`（Spec 文档）时**：该集成分支在计划语义上即 **Spec 集成分支**；各 Plan 的 feature 线 merge 回此线，**全部 Plans 完成后** 合入默认保护分支须 **走 PR**（见 `mstar-plan-conventions` SKILL.md「Spec 文档驱动的分支模型」）。
112
112
  2. **再挂各轨 worktree**：为每条并行轨分配 **独立** `git worktree` + **`Worktree path`**；各轨 **`Working branch`** 一般为 **从集成分支出** 的 topic 分支（`create <topic-i> from <plan-integration-branch>`）或 PM 书面约定的等价结构（例如从同一 `<base>` 出 topic、但 **书面指定** 合并时 **以集成分支为靶**）。**禁止**承接方擅自把未授权功能提交直接堆在 `main`/`master`。
113
113
  3. **进 QC 之前**：将全部 **须同一轮三审覆盖** 的提交 **merge / rebase / cherry-pick**（以 PM 指定的团队方式）**归并**到 **同一条** PM 将作为 QC **`Working branch`** 的分支的 **`HEAD`**（**通常即 plan 集成分支**；若 PM 已将集成分支重命名或快进为最终 `feature/*`，以 Assignment 为准）。**在此**解决冲突；**勿**在 QC Assignment 仍指向「只含部分轨」的旧 `HEAD` 时派三审。
114
114
  4. **QC / QA 的 `Working branch` 与合并主线**：派发 QC 三审与对齐的 QA 时，**`Working branch`** **即为**上一步 **已含全部待审提交** 的那条分支（常见为 plan 集成分支）。**`Review range` / `Diff basis`** 通常相对 **尚未合并 feature 的** 主线参照（例如 `merge-base: origin/main` + `tip: HEAD`），审查的是 **「feature 线 vs 主线」** 的差异；**默认不要求**在 QC **通过前** 已把该分支 merge 进 `main`（除非 **`Branch policy`** 或用户明确约定 trunk 式例外）。
package/harness-skills/mstar-harness-core/references/open-harness-principles.md CHANGED
@@ -10,6 +10,7 @@
10
10
  |------|------|----------------|
11
11
  | **意图优先于字面** | 先弄清「用户真正要达成什么」，再分类与分派 | `mstar-harness-core` SKILL.md「意图门禁」；PM「第一性原理」与 `clarify` |
12
12
  | **先准备再实现** | 访谈式规划、锁范围、再写代码 | Prepare：`specify -> clarify -> plan`；Execute：`plan locked -> tasks -> implement` |
13
+ | **`clarify` 核心纪律** | 逐方面核对至共享理解；沿设计树逐枝、一次一决；能探索代码库则先探索；每问带推荐答案 | `mstar-harness-core` SKILL.md Prepare · `clarify`；`phase-gate-playbook.md` |
13
14
  | **按任务类别选能力与模型** | 视觉/深读/快改/硬逻辑等用不同强项 | `mstar-harness-core` SKILL.md「Task category」；Assignment 字段 **`Task category`**；宿主侧按角色配置 model（如 OpenCode 的 `opencode.json`） |
14
15
  | **可验证编辑** | 减少「凭记忆 Patch」导致的漂移与损坏 | `mstar-harness-core` SKILL.md「可验证编辑与上下文纪律」：读后再改、失败则重读 |
15
16
  | **持续推进与可核对完成** | 长任务有清单、有关门证据，避免空转 | `mstar-superpowers-align` 的 `verification-before-completion`；PM 对 `tasks`/Phase Gate 的拉回 |
@@ -44,7 +45,8 @@
44
45
  |------|----------------|
45
46
  | 详细计划状态、阻塞列表、当前 sprint 叙述 | `{HARNESS_DIR}/status.json`（及可选 `{HARNESS_DIR}/notes.json` 程序时间线） |
46
47
  | 规格正文、枚举定义、API 契约全文 | 项目约定的冻结规格目录（如 `docs/spec/`、`.agents/designs/...`，名称自定） |
47
- | 某一 plan 的评审稿、gap 分析、实施笔记 | `{HARNESS_DIR}/knowledge/`（并维护索引 README，见 `mstar-plan-conventions`） |
48
+ | 迭代/版本级 delivery compass、program 范围快照 | `{ITERATION_DIR}`（并维护索引 README，见 `mstar-plan-conventions`） |
49
+ | 某一 plan 的评审稿、gap 分析、跨版本实施 SSOT | `{KNOWLEDGE_DIR}`（并维护索引 README，见 `mstar-plan-conventions`） |
48
50
  | 临时 workaround、仅本轮有效的结论 | 主 plan 文件或 knowledge，收口后提炼再考虑进 `AGENTS.md` |
49
51
 
50
52
  ### 更新前自检（避免污染单一权威）
@@ -61,7 +63,8 @@
61
63
  1. **冻结规格 / 设计权威**（版本化、显式变更流程）
62
64
  2. **根 `AGENTS.md`** — 项目级规则与约定
63
65
  3. **`{HARNESS_DIR}/status.json`** — 当前执行状态与 open residual 的 SSOT
64
- 4. **`{HARNESS_DIR}/knowledge/`** — 支撑实施的上下文文档
66
+ 4. **`{ITERATION_DIR}`** — 迭代/版本级 compass（可选）
67
+ 5. **`{KNOWLEDGE_DIR}`** — 支撑实施的上下文文档（可选）
65
68
 
66
69
  若 `AGENTS.md` 与冻结规格冲突，**以规格为准**，并修订 `AGENTS.md` 对齐。细节分工与可到达性要求见 `mstar-plan-conventions`。
67
70
 
package/harness-skills/mstar-harness-core/references/phase-gate-playbook.md CHANGED
@@ -21,6 +21,7 @@
21
21
  - 最小产物：歧义清单 + 结论；若未收敛则 `blocked`。
22
22
  - **意图**：区分字面请求与真实目标；手段/目标混淆须在此收敛（见本 skill `SKILL.md` Intent gate）。
23
23
  - **结构化澄清**：与用户核对歧义或决策时，`@project-manager`（及直接与用户对话的角色）在**宿主支持**时优先用 `question` 类能力拉齐输入；否则用等价结构化正文。宿主差异细则见当前宿主的 `mstar-host` skill。
24
+ - **`clarify` 核心纪律**（见 `mstar-harness-core` SKILL.md Prepare · `clarify`）：逐方面核对至共享理解；沿设计树逐枝、一次一决；能探索代码库则先探索；每问附推荐答案；阶段末汇总已决与仍 open 假设。
24
25
  - `plan`
25
26
  - 目标：给出可执行技术方案与风险控制。
26
27
  - 最小产物：方案、模块边界/接口契约、风险与回滚、验证计划。
@@ -42,7 +43,7 @@
42
43
  - 最小产物：实现 diff、自检证据、回报与 handoff。
43
44
  - **行为准则**：执行中遵循 `mstar-coding-behavior`（不静默假设、优先简单方案、只做与任务直接相关的手术式改动、按 `Step -> verify` 推进）。
44
45
  - **编辑纪律**：改文件前以磁盘为准重读；Patch 失败则重读、缩小步长，禁止盲试（见 `SKILL.md`「可验证编辑与上下文纪律」）。
45
- - **知识库**：若项目启用 `{HARNESS_DIR}/knowledge/` 且当前计划在 `{HARNESS_DIR}/status.json` 的 `plans[].metadata` 中登记了 `primary_spec` / `spec_refs`，**开工前**须阅读并在回报中说明已对齐；规则见 `mstar-plan-conventions`「`{HARNESS_DIR}/knowledge/` 开发过程知识库」。
46
+ - **知识库 / 迭代 compass**：若项目在 `plans[].metadata` 中登记了 `primary_spec` / `spec_refs` / `iteration_compass` / `iteration_refs`，**开工前**须阅读并在回报中说明已对齐；规则见 `mstar-plan-conventions` 与 `references/knowledge-and-designs.md`（`{KNOWLEDGE_DIR}`、`{ITERATION_DIR}`）。
46
47
 
47
48
  ## 角色职责
48
49
 
package/harness-skills/mstar-plan-conventions/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mstar-plan-conventions
3
- description: Morning Star (启明星) harness 的计划目录约定 —— {HARNESS_DIR} 与 {PLAN_DIR} 的发现与初始化、status.json 的 SSOT 结构与状态权限、residual findings 登记/归档/生命周期、severity 枚举（SSOT，机器字段）、notes.json 程序时间线、tech_debt_summary 技术债一览、knowledge/ 开发过程知识库、reports/ 审查留档命名、QC 三审触发时机、主 plan Done 标记、archived/plans Profile A/B、工期预估（仅 agent-oriented）。任何角色在读写 .agents/、创建/更新 plan 文件、登记 residual finding、QC/QA 报告入库、Done 收口、写工期预估时必读；`@project-manager` 编排任一含 plan 的任务前必读；实现角色开工前须读本 skill 以对齐 metadata.primary_spec/spec_refs 与 knowledge 目录。
3
+ description: Morning Star (启明星) harness 的计划目录约定 —— {HARNESS_DIR}、{PLAN_DIR}、{ITERATION_DIR}、{KNOWLEDGE_DIR}、{SPECS_DIR} 的发现与初始化、docs/ 与 harness 子树内容边界、status.json 的 SSOT 结构与状态权限、residual findings 登记/归档/生命周期、severity 枚举（SSOT，机器字段）、notes.json 程序时间线、tech_debt_summary 技术债一览、reports/ 审查留档命名、QC 三审触发时机、主 plan Done 标记、archived/plans Profile A/B、工期预估（仅 agent-oriented）、**Spec 集成分支 + 多 Plan 实现分支** 的 Git 对齐与 **Spec 完成后须经 PR 合入 main** 门禁。任何角色在读写 .agents/、创建/更新 plan 文件、登记 residual finding、QC/QA 报告入库、Done 收口、写工期预估时必读；`@project-manager` 编排任一含 plan 的任务前必读；实现角色开工前须读本 skill 以对齐 metadata.primary_spec/spec_refs 与 knowledge/iterations 目录。
4
4
  ---
5
5
 
6
6
  ## Load order（必读顺序）
@@ -15,11 +15,21 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
15
15
 
16
16
  ## Harness 与 Plan 目录发现
17
17
 
18
- 引入 **Harness 根目录** `{HARNESS_DIR}`、**计划文件目录** `{PLAN_DIR}` 与 **规格目录别名** `{SPECS_DIR}` 三层概念：
18
+ 引入 **Harness 根目录** 与若干**路径符号**（与 Nexus 等采用 Morning Star 的业务仓库对齐；项目可在 `{HARNESS_DIR}/AGENTS.md` 复述下表并声明本地偏差）：
19
19
 
20
- - **`{HARNESS_DIR}`**：agent 计划与编排产物的根（默认 **`.agents/`**）。承载 SSOT、时间线、知识库、归档、冻结规格等**非「单文件 plan 正文 + 审查报告」**类资产。
20
+ | 符号 | 含义 | 默认路径 |
21
+ |------|------|----------|
22
+ | `{HARNESS_DIR}` | Agent 计划与编排产物根 | `.agents/` |
23
+ | `{PLAN_DIR}` | 主 plan 正文与按 `plan-id` 的审查留档 | `{HARNESS_DIR}/plans/` |
24
+ | `{ITERATION_DIR}` | 迭代/版本级 program compass、交付范围与遗留规划快照 | `{HARNESS_DIR}/iterations/` |
25
+ | `{KNOWLEDGE_DIR}` | 实施细节 SSOT、可复用技术设计（**不**替代冻结规格） | `{HARNESS_DIR}/knowledge/` |
26
+ | `{SPECS_DIR}` | 冻结规格目录别名（见下节解析） | `{HARNESS_DIR}/specs/` 或 `{HARNESS_DIR}/designs/` |
27
+
28
+ - **`{HARNESS_DIR}`**：承载 SSOT、时间线、迭代 compass、知识库、归档、冻结规格等**非「单文件 plan 正文 + 审查报告」**类资产。
21
29
  - **`{PLAN_DIR}`**：**仅**存放主 plan Markdown、按 `plan-id` 分目录的 **`reports/`** 等**计划与审查留档**；**默认** `{PLAN_DIR} = {HARNESS_DIR}/plans/`。
22
- - **`{SPECS_DIR}`**：规格文档目录别名。用于统一表示 `{HARNESS_DIR}/specs` 与 `{HARNESS_DIR}/designs` 两种标准，减少规则与模板中的硬编码路径。
30
+ - **`{ITERATION_DIR}`**（可选）：**迭代/版本维度**的交付罗盘（如 `*-delivery-compass-*.md`、`*-program-compass-*.md`）、gap 分析、遗留 `v1.*` 规划快照；**不**放可跨版本复用的实现 SSOT（那些进 `{KNOWLEDGE_DIR}`）。须维护 **`{ITERATION_DIR}/README.md`** 索引（见 `references/knowledge-and-designs.md`）。
31
+ - **`{KNOWLEDGE_DIR}`**（可选）：**实现向**长寿命技术上下文（架构细则、契约说明、跨版本 tracker、性能基线等）；须维护 **`{KNOWLEDGE_DIR}/README.md`** 索引。下文凡写 `knowledge/` 均指 **`{KNOWLEDGE_DIR}`**。
32
+ - **`{SPECS_DIR}`**：规格文档目录别名，用于统一表示 `{HARNESS_DIR}/specs` 与 `{HARNESS_DIR}/designs` 两种标准，减少规则与模板中的硬编码路径。
23
33
 
24
34
  ### `{SPECS_DIR}` 解析规则
25
35
 
@@ -38,7 +48,21 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
38
48
 
39
49
  **并存目录**：若仓库中**同时**存在 **`.agents/`** 与 **`.plans/`**（或根目录 **`plans/`**），仍按上表**优先级 1** 采用 **`.agents/`** 作为 **`{HARNESS_DIR}`**；其余路径可能为迁移残留，宜合并或重命名，避免误读两套 harness。
40
50
 
41
- > **约定**：下文凡写 **`{HARNESS_DIR}/…`**、**`{PLAN_DIR}/…`** 均指上表解析后的实际路径。推荐布局下 **`{PLAN_DIR}` 绝不等于** 仓库根，而是 **`{HARNESS_DIR}` 下的 `plans/` 子目录**。
51
+ > **约定**：下文凡写 **`{HARNESS_DIR}/…`**、**`{PLAN_DIR}/…`**、**`{ITERATION_DIR}/…`**、**`{KNOWLEDGE_DIR}/…`** 均指上表解析后的实际路径。推荐布局下 **`{PLAN_DIR}` 绝不等于** 仓库根，而是 **`{HARNESS_DIR}` 下的 `plans/` 子目录**。
52
+
53
+ ## 内容边界：`docs/` 与 harness 子树（推荐）
54
+
55
+ 与 Nexus harness 分层一致；项目根 `AGENTS.md` 宜用短表指向本节，避免在多处维护长文。
56
+
57
+ | 区域 | 典型内容 | 受众 / 权威 |
58
+ |------|----------|-------------|
59
+ | **`docs/`**（或项目约定的用户文档根） | 安装、quickstart、稳定架构概览、贡献指南 | 人类贡献者与终端用户；clone 后应可读 |
60
+ | **`{SPECS_DIR}`**（可选） | 冻结 **v1-spec**、ADR、program **roadmap** — 产品/API 行为最高权威 | 全员；变更须显式版本/评审流程 |
61
+ | **`{ITERATION_DIR}`**（可选） | 某交付版本/迭代的 **compass**（范围、里程碑、验收、风险）、gap 分析、遗留规划快照 | Agent handoff；**不**替代 `{SPECS_DIR}` |
62
+ | **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、可复用技术设计、跨版本 tracker | Agent handoff；**不**覆盖 `{SPECS_DIR}` 中的规范性条款 |
63
+ | **`{PLAN_DIR}/`** | 单 plan 执行：主 plan、`reports/`、可选 `residuals/` | 计划级 SSOT 与审查留档 |
64
+
65
+ **不应**放入 `docs/` 的内容：作为**特定 plan 输入/输出**的评审结论、迭代 compass 正文、未稳定规格草案、QC 报告 —— 分别落 `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}`、`{SPECS_DIR}` 或 `{PLAN_DIR}/reports/`（见 `references/knowledge-and-designs.md`）。
42
66
 
43
67
  ## 目录布局（推荐）
44
68
 
@@ -50,7 +74,9 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
50
74
  ├── notes.json # 可选：程序里程碑 / 时间线（减轻 status.json 体积）
51
75
  ├── specs/ # 可选：规格主目录（推荐）；若存在则作为 {SPECS_DIR}
52
76
  ├── designs/ # 可选：兼容旧目录；当 specs/ 不存在时可作为 {SPECS_DIR}
53
- ├── knowledge/ # 可选：开发过程知识库（见 references/knowledge-and-designs.md）
77
+ ├── iterations/ # 可选：{ITERATION_DIR} — 迭代/版本级 compass（见 references/knowledge-and-designs.md）
78
+ │ └── README.md
79
+ ├── knowledge/ # 可选：{KNOWLEDGE_DIR} — 实施知识库（见 references/knowledge-and-designs.md）
54
80
  │ └── README.md
55
81
  ├── archived/ # 可选：已关闭 residual、Done 计划行冷快照
56
82
  │ ├── residuals/
@@ -72,7 +98,8 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
72
98
  - **主计划**：技术方案、任务清单、Sign-off 仍以 **`{PLAN_DIR}/<plan-id>-<plan-name>.md`** 与 **`{HARNESS_DIR}/status.json`** 为权威。
73
99
  - **`{PLAN_DIR}/reports/`**：架构评审、QC 分报告、QC 汇总结论；**视为只读历史**，不在此反复改写同一结论（修正走新报告或回写主计划 / `status.json`）。
74
100
  - **`{PLAN_DIR}/residuals/<plan-id>/`**（可选）：对仍 **open** 的 residual 提供**长于 JSON 字段**的散文说明；**不替代**根级 `residual_findings` 的 SSOT（见上文「`status.json` 与 open residual」），见 `references/knowledge-and-designs.md`「open residual 散文详情」。
75
- - **`{HARNESS_DIR}/knowledge/`**：规格修订、架构评审产出、设计决策与 gap 分析等**实施上下文**；与面向用户的 `docs/` 分工见 `references/knowledge-and-designs.md`。
101
+ - **`{ITERATION_DIR}`**：**版本/迭代维度**的交付罗盘与规划快照；与 `{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 分工见上文「内容边界」与 `references/knowledge-and-designs.md`。
102
+ - **`{KNOWLEDGE_DIR}`**：规格修订、架构评审产出、设计决策与 gap 分析等**实施上下文**（**非**迭代 compass 的首选落点）；与 `docs/`、`{ITERATION_DIR}` 分工见 `references/knowledge-and-designs.md`。
76
103
  - **`{SPECS_DIR}`**（可选）：规格目录别名，支持 `{HARNESS_DIR}/specs/` 与 `{HARNESS_DIR}/designs/`；用于冻结规格、少变基线或可对外参考文档（具体分工见 `references/knowledge-and-designs.md`）。
77
104
  - **residual findings（未关闭）**：**当前仍待跟踪**的条目写在 **`{HARNESS_DIR}/status.json`** 根级 `residual_findings[<plan-id>]`（canonical 见上文）；**已验证关闭**的条目迁出至 **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**，避免 `status.json` 无限膨胀。详见 `references/status-and-residuals.md`。
78
105
 
@@ -88,7 +115,7 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
88
115
  - **不得**引用仅在本机存在、被 `.gitignore` 排除、或 **`git clone` 后默认不存在**的路径；读者按文内引用应能在仓库内打开对应文件。
89
116
  - **不得**引用**本仓库根目录以外**的路径（例如 `~/.config/...`、用户主目录绝对路径、任意未作为子模块/子树纳入的「兄弟目录」）。若必须依赖外部上下文：**将要点摘入本仓库**，或给出**稳定、可公开访问**的 URL（并注明适用范围与版本）。
90
117
  - 违反上述约定会破坏 **onboarding** 与跨环境交接；若项目将 **`{HARNESS_DIR}`**（或遗留模式下整个 `{PLAN_DIR}`）**整体**加入 `.gitignore`，则已提交的 `docs/`、`README`、`AGENTS.md` 等**不得**把被忽略路径下的文件当作**唯一**权威引用。
91
- - 需要 handoff 的 plan / `{PLAN_DIR}/reports/` / **`{HARNESS_DIR}/knowledge/`** 宜 **Git 跟踪**；若某路径刻意不提交，则不要在已提交文档中写死为必读单一来源。
118
+ - 需要 handoff 的 plan / `{PLAN_DIR}/reports/` / **`{ITERATION_DIR}`** / **`{KNOWLEDGE_DIR}`** 宜 **Git 跟踪**；若某路径刻意不提交，则不要在已提交文档中写死为必读单一来源。
92
119
 
93
120
  ## 初始化 Plan 目录
94
121
 
@@ -100,12 +127,45 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
100
127
  4. 可选：创建 **`{HARNESS_DIR}/notes.json`**：可复制 **`templates/notes.empty.json`**（或空 `entries: []`），用于程序里程碑，避免日后向 `status.json` 堆日志。模板索引见 **`templates/README.md`**。
101
128
  5. 创建 **`{PLAN_DIR}/reports/README.md`**，用途与命名约定与仓库内其它说明一致即可。
102
129
  6. 可选：若采用 **`{PLAN_DIR}/residuals/<plan-id>/`** 散文详情，在**首次**需要长文补充某 open R# 时再创建对应 **`residuals/<plan-id>/`** 子目录；无需为空 plan 预建占位目录。
103
- 7. 若启用 **`{HARNESS_DIR}/knowledge/`**：创建目录及 **`knowledge/README.md`** 空索引表（见 `references/knowledge-and-designs.md`）。
104
- 8. 可选：创建 **`{HARNESS_DIR}/specs/`**（推荐）或 **`{HARNESS_DIR}/designs/`**（兼容），并维护简短 **`README.md`**；后续统一按 `{SPECS_DIR}` 引用。
105
- 9. **Git 策略（与项目 `AGENTS.md` 一致）**
130
+ 7. 若启用 **`{KNOWLEDGE_DIR}`**：创建目录及 **`{KNOWLEDGE_DIR}/README.md`** 空索引表（见 `references/knowledge-and-designs.md`）。
131
+ 8. 若启用 **`{ITERATION_DIR}`**：创建目录及 **`{ITERATION_DIR}/README.md`** 空索引表（delivery compass / program compass 等；见 `references/knowledge-and-designs.md`）。
132
+ 9. 可选：创建 **`{HARNESS_DIR}/specs/`**（推荐）或 **`{HARNESS_DIR}/designs/`**（兼容），并维护简短 **`README.md`**；后续统一按 `{SPECS_DIR}` 引用。
133
+ 10. **Git 策略（与项目 `AGENTS.md` 一致）**
106
134
  - **推荐（团队交付 / agent handoff）**：**不要**将 **`{HARNESS_DIR}`** 整体加入 `.gitignore`，以便 clone 后计划与报告路径可达。
107
135
  - **仅本机私密**：若必须 ignore 整个 **`{HARNESS_DIR}`**，则按上文「可到达性」约束已提交文档；敏感片段另用密钥或私密渠道管理。
108
- 10. 如果项目已有 **`.plans/`** 或 **`plans/`** 目录（遗留同目录布局），**不要再创建** **`.agents/`**，直接使用已有目录作为 **`{HARNESS_DIR} = {PLAN_DIR}`**，并视需要补建 **`reports/`**、**`residuals/`**、**`knowledge/`**、**`archived/residuals/`**、可选 **`notes.json`** 与 `metadata` 结构。
136
+ 11. 如果项目已有 **`.plans/`** 或 **`plans/`** 目录（遗留同目录布局），**不要再创建** **`.agents/`**，直接使用已有目录作为 **`{HARNESS_DIR} = {PLAN_DIR}`**，并视需要补建 **`reports/`**、**`residuals/`**、**`{KNOWLEDGE_DIR}`**、**`{ITERATION_DIR}`**、**`archived/residuals/`**、可选 **`notes.json`** 与 `metadata` 结构。
137
+
138
+ ## Spec 文档驱动的分支模型（多 Plan 归属同一 Spec）
139
+
140
+ 当 **`metadata.primary_spec`**（及可选 **`spec_refs`**）指向**单一规格主线**，且 PM 将工作拆成 **多个 `plan_id`** 并行或串行交付时，业务仓库的 Git 拓扑建议按下述对齐，避免「实现分支直接打 main」与「多 Plan 无集成靶」两类漂移。**同仓 worktree、QC 前归并到单一 `HEAD` 等强制条款**仍以 **`mstar-harness-core`** `references/branch-and-worktree.md` 为准；本节只补充 **Spec ↔ 分支** 的命名级契约。
141
+
142
+ ### 分支角色
143
+
144
+ | 概念 | 含义 |
145
+ |------|------|
146
+ | **Spec 文档** | 该次交付冻结或主规格（常为 `{SPECS_DIR}` / `knowledge/` 下路径；与 `primary_spec` 对齐）。 |
147
+ | **Spec 集成分支** | **一条**与「该 Spec 所覆盖的全部 Plans」对应的 **集成线**：各 Plan 实现成果 **merge 回** 此分支后，才视为该 Spec 在代码侧已集成。 |
148
+ | **Plan 实现分支** | **每个 `plan_id`** 一条（或 PM 书面拆分的子轨）；**仅**承载该 Plan 范围内的提交与 QC/QA 前归并。 |
149
+
150
+ ### 工作流（默认推荐）
151
+
152
+ 1. **开线**：由 **`@project-manager`** 与用户确认后，建立 **Spec 集成分支**（Assignment 写明 `Working branch: create <spec-integration-branch> from <base>` 或等价；`<base>` 见 `branch-and-worktree.md`，**禁止**未授权默认）。
153
+ 2. **拆 Plan**：每个从该 Spec 拆出的 plan 使用 **各自的 Plan 实现分支**（通常 `create <plan-feature-branch> from <spec-integration-branch>` 或 PM 规定的等价拓扑）；**实现 / QA / 运维等可写角色**在本 Plan 周期内 **只操作 Assignment 写明的该 Plan 分支**（及 PM 授权的 worktree 检出），**不得**擅自把未授权提交直接堆到默认保护分支。
154
+ 3. **Plan 收口**：该 Plan 完成 **QC 三审 + QA** 等 harness 要求后，将其变更 **merge（或团队书面约定的 rebase/cherry-pick）回 Spec 集成分支**；**不是**在「仅完成单个 Plan」时默认直接 merge 进 `main`/`master`，除非 Assignment 含显式 **`Branch policy`** 例外。
155
+ 4. **与 `mstar-harness-core` 的「plan 集成分支」关系**：**同仓、同一 plan、多并行轨**时，该 skill 推荐的 **plan 集成分支** 在「多 Plan、同源 Spec」场景下 **即** 本条所述 **Spec 集成分支**；各 Plan 的 topic 线 **merge 靶** 优先为 **Spec 集成分支**，而非彼此随意交叉除非 PM 书面约定。
156
+
157
+ ### 合入默认保护分支（main）：必须经 PR
158
+
159
+ 当 **归属该 Spec 的全部 Plans** 已在计划状态上完成（且代码变更已按团队流程 **汇总到 Spec 集成分支**）时：
160
+
161
+ - **禁止**将 Spec 集成分支 **直接本地 merge / fast-forward push** 到 **`main`/`master`**（或项目约定的其它默认保护分支）作为**常规完成路径**。
162
+ - **必须**通过 **Pull Request（或宿主平台等价的受控合入流程）** 将 Spec 集成分支合入默认分支，以满足 **审查、CI、权限与审计** 等团队门禁。
163
+
164
+ **窄例外**（须 **Assignment 显式** **`Branch policy: direct on <branch> — <reason>`**，与 `mstar-harness-core` 一致）：例如已批准的热修、或用户与团队书面采用的无 PR 流程。**不得**由 agent 自行认定「可以跳过 PR」。
165
+
166
+ ### 登记建议
167
+
168
+ 在 **`{HARNESS_DIR}/status.json`** 的 **`plans[].metadata`**（或根级 **`metadata.versioning`** 等团队约定节）中记录 **`spec_integration_branch`**、各 plan 的 **`working_branch`**，以及 **`merge_target`**（对 Plan 实现分支通常为 **Spec 集成分支名**，而非 `main`）。字段表见 `references/status-and-residuals.md`。
109
169
 
110
170
  ## Harness 初始化蓝图（含 `AGENTS.md` 分层策略）
111
171
 
@@ -119,7 +179,7 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
119
179
 
120
180
  ### `.agents/AGENTS.md` 应保存什么
121
181
 
122
- - harness 结构与路径契约：`{HARNESS_DIR}`、`{PLAN_DIR}`、`{SPECS_DIR}` 的实际路径约定。
182
+ - harness 结构与路径契约：`{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 的实际路径约定；`docs/` 与 harness 子树内容边界（可引用本 skill「内容边界」表）。
123
183
  - plan/status 生命周期门禁：`Todo/InProgress/InReview/Blocked/Done` 的推进与角色权限映射。
124
184
  - QC/QA 证据契约：三审独立性、同一 `plan_id` + `Review range` 对齐、报告落盘目录与命名。
125
185
  - residual 管理契约：severity 枚举、open/closed/archived 流转、归档路径。
@@ -142,7 +202,7 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
142
202
 
143
203
  上游 **Superpowers** 插件自带的 `writing-plans` 技能默认将计划保存到 `docs/superpowers/plans/`，与本 skill `{PLAN_DIR}` 约定冲突。
144
204
 
145
- **Harness 门限（优于技能正文中的保存路径）**：任一角色在加载并执行 **`writing-plans`** 时，须将新计划写入按上文解析到的 **`{PLAN_DIR}`**（推荐文件名 **`<plan-id>-<plan-name>.md`**，或与项目既有 plan 命名一致；亦可用 `YYYY-MM-DD-<feature-name>.md` 等可追溯形式），**禁止**在业务仓库中默认使用 `docs/superpowers/plans/`。需要新建 **`{HARNESS_DIR}`** / **`{PLAN_DIR}`**、**`{HARNESS_DIR}/status.json`**、可选 **`{HARNESS_DIR}/notes.json`**、**`{PLAN_DIR}/reports/README.md`**、可选 **`{HARNESS_DIR}/knowledge/README.md`**、Git 策略时，按上文 **「初始化 Plan 目录」**；`status.json` 的登记与状态仍由 `@project-manager` 负责。
205
+ **Harness 门限（优于技能正文中的保存路径）**：任一角色在加载并执行 **`writing-plans`** 时，须将新计划写入按上文解析到的 **`{PLAN_DIR}`**（推荐文件名 **`<plan-id>-<plan-name>.md`**，或与项目既有 plan 命名一致；亦可用 `YYYY-MM-DD-<feature-name>.md` 等可追溯形式），**禁止**在业务仓库中默认使用 `docs/superpowers/plans/`。需要新建 **`{HARNESS_DIR}`** / **`{PLAN_DIR}`**、**`{HARNESS_DIR}/status.json`**、可选 **`{HARNESS_DIR}/notes.json`**、**`{PLAN_DIR}/reports/README.md`**、可选 **`{KNOWLEDGE_DIR}/README.md`** / **`{ITERATION_DIR}/README.md`**、Git 策略时，按上文 **「初始化 Plan 目录」**；`status.json` 的登记与状态仍由 `@project-manager` 负责。
146
206
 
147
207
  各角色提示词中对本门限有短引用（见 `mstar-roles` skill 的 `project-manager` 角色、`product-manager.md`、`architect.md`）；完整消解表见 `mstar-superpowers-align`。
148
208
 
@@ -207,7 +267,7 @@ Assignment 模板中的 **`Parallelism`** 行应与上表 **`Parallelism`** / **
207
267
  | 阶段 | 含义 | 典型产物 |
208
268
  |------|------|----------|
209
269
  | `Todo` | 已登记，未开工 | 主 plan 文件 + `status.json` 条目 |
210
- | `InProgress` | 实现或准备阶段进行中 | 更新的主 plan、`tasks` 勾选；编码前已读 `metadata` 指向的 **`knowledge/`** 文档（若有） |
270
+ | `InProgress` | 实现或准备阶段进行中 | 更新的主 plan、`tasks` 勾选；编码前已读 `metadata` 指向的 **`{KNOWLEDGE_DIR}`** / **`{ITERATION_DIR}`** / `{SPECS_DIR}` 文档（若有） |
211
271
  | `InReview` | 审查与验证中 | `{PLAN_DIR}/reports/<plan-id>/` 下 `*-review.md`、`*-qc*.md`、`*-qc-consolidated.md`（见 `references/plan-files-and-reports.md`） |
212
272
  | `Done` | 已合并/收口 | 主 plan Sign-off、**`{HARNESS_DIR}/status.json`** 的 `done_at`；仍 open 的 R# 留在根级 `residual_findings`（见本 SKILL 开篇），已关闭的已迁入 **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`** |
213
273
  | `Blocked` | 等待外部输入或决策 | 顶层 `notes` + 建议填 `plans[].metadata.blocked_*` / `blocked_by_plan_id` |
@@ -223,8 +283,8 @@ Assignment 模板中的 **`Parallelism`** 行应与上表 **`Parallelism`** / **
223
283
 
224
284
  ## 各角色与 Plan 的关系
225
285
 
226
- - **`@project-manager`**：负责发现 plan 目录、创建/登记 plan、分配任务、推进状态、Done 收口。分配时须告知 subagent plan 目录的实际路径；涉及业务 Git 仓库写操作时须在 Assignment 中写明 **`Working branch`** 或 **`Branch policy`**（见 `mstar-harness-core` `references/branch-and-worktree.md`）。启用 **`knowledge/`** 时维护索引 README，并在 Assignment 中点名 **`primary_spec` / `spec_refs`**（若本轮依赖知识库）。**维护 `status.json` 时**：若存在 **`InReview`** 行，每轮 Status Update **自检**是否对该 `plan_id` 已派或未派 QC；派发前 **Read `mstar-review-qc`**。
227
- - **`@architect`** / **`@product-manager`**：产出规格或评审结论若适合跨会话复用，写入 **`{HARNESS_DIR}/knowledge/`**（或 `{SPECS_DIR}`）并更新对应 **README**，建议由 PM 在 `plans[].metadata` 挂接路径。
286
+ - **`@project-manager`**：负责发现 plan 目录、创建/登记 plan、分配任务、推进状态、Done 收口。分配时须告知 subagent plan 目录的实际路径；涉及业务 Git 仓库写操作时须在 Assignment 中写明 **`Working branch`** 或 **`Branch policy`**（见 `mstar-harness-core` `references/branch-and-worktree.md`）。启用 **`{KNOWLEDGE_DIR}`** / **`{ITERATION_DIR}`** 时维护对应 **README** 索引，并在 Assignment 中点名 **`primary_spec` / `spec_refs`**（及本轮相关的 iteration compass 路径，若适用）。**多 Plan 归属同一 Spec 时**：按上文 **「Spec 文档驱动的分支模型」** 声明 **Spec 集成分支**、各 **Plan 实现分支** 与 **merge 靶**；在 `status.json` 登记 **`spec_integration_branch` / `merge_target`**（见 `references/status-and-residuals.md`）；**全部 Plans 完成后** 合入 `main`/`master` **走 PR**，不得默认直接 merge。**维护 `status.json` 时**：若存在 **`InReview`** 行，每轮 Status Update **自检**是否对该 `plan_id` 已派或未派 QC；派发前 **Read `mstar-review-qc`**。
287
+ - **`@architect`** / **`@product-manager`**：产出规格或评审结论若适合跨会话复用，写入 **`{KNOWLEDGE_DIR}`**、**`{ITERATION_DIR}`**（迭代 compass）或 **`{SPECS_DIR}`**（冻结规格），并更新对应 **README**；建议由 PM 在 `plans[].metadata` 挂接路径。
228
288
  - **可写盘 agent**（dev / qa / ops）：完成任务后更新主 plan 中**本人负责**的任务 checkbox（见 `references/plan-files-and-reports.md`）、相关 Sign-off 栏位，并更新 `status.json`（权限见上）。**实现前**若 `plans[].metadata` 含 `primary_spec` / `spec_refs`，须先阅读对应文件（见 `references/knowledge-and-designs.md`）。
229
289
  - **`@product-manager`**：可更新 plan 文档中需求/验收/用户故事等产品负责部分，并在交付后勾选**与之对应**的主 plan 任务 checkbox；**不得**将 `status.json` 中计划状态设为 `Done`；如需改 `progress`/`notes`，以 Assignment 为准或交由 PM 收口。
230
290
  - **`@architect`**：可更新 plan 文档中架构、接口契约、技术里程碑等章节，并在交付后勾选**与之对应**的主 plan 任务 checkbox；**不得**将 `status.json` 中计划状态设为 `Done`；一般不擅自将整条计划改为 `InReview`（与 PM 对齐）。
@@ -233,8 +293,9 @@ Assignment 模板中的 **`Parallelism`** 行应与上表 **`Parallelism`** / **
233
293
 
234
294
  ## References
235
295
 
296
+ - 本 SKILL **「Spec 文档驱动的分支模型（多 Plan 归属同一 Spec）」** — Spec 集成分支、Plan 实现分支、merge 回集成线、**全部完成后经 PR 合入 main**（与 `mstar-harness-core` `references/branch-and-worktree.md` 并用）。
236
297
  - `references/status-and-residuals.md` — `{HARNESS_DIR}/status.json` SSOT 结构、`plans[].metadata` 标准字段、根级 `metadata` 字段、residual findings 的 **severity** 枚举（SSOT）、生命周期（open → closed → archived）、`notes.json` 程序时间线、`tech_debt_summary` 技术债一览、常用 jq 查询。
237
- - `references/knowledge-and-designs.md` — `{HARNESS_DIR}/knowledge/` 开发过程知识库（目录、索引、命名、维护）、`{SPECS_DIR}`（`specs/` or `designs/`）规格目录、`{PLAN_DIR}/residuals/<plan-id>/` open residual 散文详情、与 `reports/` 的分工。
298
+ - `references/knowledge-and-designs.md` — `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{SPECS_DIR}` 分工与索引、`{PLAN_DIR}/residuals/<plan-id>/` open residual 散文详情、与 `reports/` 的分工。
238
299
  - `references/plan-files-and-reports.md` — 主 plan 文件命名、审查报告命名表、QC 分报告与 consolidated 保留原则、**QC 三审触发时机（单 plan · 多 batch）**、**多 `plan_id` 同时 `InReview` 的 QC 编排**、residual findings 权威位置与顺序、主 plan Markdown checkbox 规则、Done 标记方式、QC 落盘宿主权限。
239
300
  - `references/done-compaction.md` — `Done` 计划行冷快照（`{HARNESS_DIR}/archived/plans/`）、Profile A（瘦 Done 行）/ Profile B（不留 Done 行）、原子更新约束、仓库级采用声明模板、合并前 SSOT 与事实一致门禁。
240
301
  - `references/effort-estimation.md` — Agent-oriented 工期与工作量预估（T 恤尺码 + agent 会话带）；**禁止**混入人天 / FTE / 人类日历；Assignment / PRD / 架构文档字段名建议。
package/harness-skills/mstar-plan-conventions/references/harness-bootstrap-and-agents-layering.md CHANGED
@@ -15,9 +15,10 @@
15
15
  1. 创建 `{HARNESS_DIR}`（推荐 `.agents/`）与 `{PLAN_DIR}`（推荐 `.agents/plans/`）。
16
16
  2. 初始化 `status.json`：推荐从 **`mstar-plan-conventions/templates/status.empty.json`** 复制；residual canonical 见 **`mstar-plan-conventions` SKILL.md** 开篇，字段与生命周期见 `status-and-residuals.md`。
17
17
  3. 初始化可选 `notes.json`（可复制 **`mstar-plan-conventions/templates/notes.empty.json`**）与 `plans/reports/README.md`。
18
- 4. 创建 `.agents/AGENTS.md`（harness 子树规则）。
19
- 5. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `.agents/AGENTS.md` 作为 harness SSOT。
20
- 6. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
18
+ 4. 可选：创建 `{ITERATION_DIR}`（`iterations/` + `README.md`）与 `{KNOWLEDGE_DIR}`（`knowledge/` + `README.md`）；内容边界见 `mstar-plan-conventions` SKILL.md 与 `references/knowledge-and-designs.md`。
19
+ 5. 创建 `.agents/AGENTS.md`（harness 子树规则）：符号表可复述 `{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 与 `docs/` 分工（参考 Nexus `.agents/AGENTS.md`）。
20
+ 6. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `.agents/AGENTS.md` 作为 harness SSOT。
21
+ 7. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
21
22
 
22
23
  ## 三层 `AGENTS.md` 职责切分
23
24
 
@@ -28,7 +29,7 @@
28
29
 
29
30
  ### `.agents/AGENTS.md`（harness 层）
30
31
 
31
- - 放：`{HARNESS_DIR}`/`{PLAN_DIR}` 契约、状态推进门禁、QC/QA 对齐规则、residual 生命周期、Done compaction profile。
32
+ - 放：`{HARNESS_DIR}`/`{PLAN_DIR}`/`{ITERATION_DIR}`/`{KNOWLEDGE_DIR}`/`{SPECS_DIR}` 契约、`docs/` 与 harness 子树内容边界、状态推进门禁、QC/QA 对齐规则、residual 生命周期、Done compaction profile。
32
33
  - 不放：语言/框架编码细节、业务模块实现约束。
33
34
 
34
35
  ### `<subdir>/AGENTS.md`（边界层）
package/harness-skills/mstar-plan-conventions/references/knowledge-and-designs.md CHANGED
@@ -1,42 +1,55 @@
1
- # `{HARNESS_DIR}/knowledge/` 开发过程知识库与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
1
+ # `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
2
2
 
3
- > **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 `mstar-harness-core/references/branch-and-worktree.md`）。冲突以 **`mstar-harness-core`** 为准。
3
+ > **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 迭代 compass / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 `mstar-harness-core/references/branch-and-worktree.md`）。冲突以 **`mstar-harness-core`** 为准。
4
+
5
+ **路径符号（默认）**：`**{KNOWLEDGE_DIR}** = **{HARNESS_DIR}/knowledge/**`；`**{ITERATION_DIR}** = **{HARNESS_DIR}/iterations/**`。完整符号表见 `mstar-plan-conventions` SKILL.md「Harness 与 Plan 目录发现」。
4
6
 
5
7
  本节将「用户文档」与「agent / 实施用知识」分开，**与具体业务仓库无关**；项目可在根目录 `AGENTS.md` 用一小段指向本 reference 或复述分界关键词，避免重复维护长文。
6
8
 
7
9
  ## 与公开文档目录的分工（典型为 `docs/`）
8
10
 
9
11
 
10
- | 区域 | 典型内容 | 受众 |
11
- | -------------------------------- | ----------------------------------------------- | ---------------------------------------- |
12
- | `**docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
13
- | `**{HARNESS_DIR}/knowledge/**` | 架构评审报告、规格修订稿、gap 分析、约束清单、**某一 plan 的输入/输出设计材料** | Agent handoff、跨会话连续；**不**默认当作对外产品文档 |
14
- | `**{SPECS_DIR}`**（可选） | 规格主目录（支持 `{HARNESS_DIR}/specs/` 或 `{HARNESS_DIR}/designs/`） | 与 `knowledge/` 分工由团队定义；**不**默认替代 `docs/` |
12
+ | 区域 | 典型内容 | 受众 / 权威 |
13
+ |------|----------|-------------|
14
+ | **`docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
15
+ | **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap | 产品/API 规范性最高权威；变更须显式流程 |
16
+ | **`{ITERATION_DIR}`**（可选） | `*-delivery-compass-*`、`*-program-compass-*`、版本范围/验收/风险、遗留 `v1.*` 规划快照 | Agent handoff；**不**替代 `{SPECS_DIR}` |
17
+ | **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker、性能基线 | Agent handoff；**不**覆盖 `{SPECS_DIR}` 中的规范性条款 |
18
+ | **`{PLAN_DIR}/`** | 单 plan 主文件、`reports/`、可选 `residuals/` | 计划执行与审查留档 |
15
19
 
16
20
 
17
- **不应**放入用户文档树的内容（宜放 `knowledge/`、`{SPECS_DIR}` 或主 plan）：作为**特定 plan 的输入/输出**的评审结论、实施笔记、未稳定的规格草案。
21
+ **不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC 报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{PLAN_DIR}/reports/`。
18
22
 
19
- ## 目录与索引
23
+ ## `{ITERATION_DIR}`（可选·迭代/版本级 compass）
20
24
 
21
- - `{SPECS_DIR}` 定义：优先 `{HARNESS_DIR}/specs/`，否则 `{HARNESS_DIR}/designs/`；若两者都不存在，建议新建 `{HARNESS_DIR}/specs/`。
25
+ - **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.agents/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列）。
26
+ - **放什么**：某一**交付版本或迭代**的范围、里程碑、验收、风险、program 备注；命名示例 `v1.15-delivery-compass-v1.md`、`*-program-compass-*.md`；遗留非标准 `v1.*` 规划快照可保留于此并列入索引。
27
+ - **不放什么**：可跨版本复用的实现 SSOT（进 `{KNOWLEDGE_DIR}`）；冻结产品/API 规范（进 `{SPECS_DIR}`）；单 plan 的 QC 留档（进 `{PLAN_DIR}/reports/`）。
28
+ - **索引**：**必须**维护 `**{ITERATION_DIR}/README.md**`：至少 **Document**、**Version / iteration**、**Description**；可按「Delivery compasses」与「Legacy artifacts」分表（参考 Nexus `.agents/iterations/README.md`）。
29
+ - **与 plan 的链接**：在 `**plans[].metadata**` 中可用 `**iteration_compass**`（单文件）或 `**iteration_refs**`（`string[]`）登记仓库内相对路径；PM 在 Assignment 点名本轮须读的 compass。
30
+ - **维护**：`@product-manager` / `@architect` 起草；`**@project-manager**` 维护 README 与 metadata 挂接；compass 定稿后**少改多版本**（新版本优先新文件名 `v<N>` 或新 compass 文件）。
22
31
 
23
- - 知识库物理路径：`**{HARNESS_DIR}/knowledge/`**（推荐布局下常为 `**.agents/knowledge/**`，与 `**{PLAN_DIR}**` 并列）。
24
- - **必须**维护 `**{HARNESS_DIR}/knowledge/README.md`** 作为**目录索引**：至少包含表格列 **Document（链接）**、**Source Plan（`plans[].id`）**、**Description**、**Status**（如 `Active` / `Superseded by implementation (<plan-id>)` / `Archived`）。
32
+ ## `{KNOWLEDGE_DIR}`（可选·实施知识库）
33
+
34
+ - `{SPECS_DIR}` 定义：优先 `{HARNESS_DIR}/specs/`，否则 `{HARNESS_DIR}/designs/`；若两者都不存在，建议新建 `{HARNESS_DIR}/specs/`。
35
+ - **必须**维护 `**{KNOWLEDGE_DIR}/README.md**` 作为**目录索引**：至少包含表格列 **Document（链接）**、**Source Plan（`plans[].id`）**、**Description**、**Status**（如 `Active` / `Superseded by implementation (<plan-id>)` / `Archived`）。
36
+ - 可选：目录级 `**{KNOWLEDGE_DIR}/AGENTS.md**` 承载命名、维护节奏、与 `{SPECS_DIR}` 的权威边界（Nexus 模式）；harness 宽规则仍以 `mstar-plan-conventions` 与本 reference 为准。
25
37
  - 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
26
38
 
27
39
  ## 文件命名
28
40
 
29
41
  - 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
30
- - 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `knowledge/` 根（除非团队明确约定）。
42
+ - 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `{KNOWLEDGE_DIR}` 根（除非团队明确约定）。
43
+ - 迭代 compass 文件名宜带版本/迭代标识，放在 `{ITERATION_DIR}/`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间。
31
44
 
32
45
  ## 与 `status.json` 的链接
33
46
 
34
- - 某 plan 的**权威设计输入**在知识库或规格目录中时，在 `**plans[].metadata`** 中登记路径，推荐使用已列标准键：`**primary_spec**`（单文件）或 `**spec_refs**`（`string[]`）。路径为**仓库内相对路径**（推荐布局下常写作 `**.agents/knowledge/....md`** 或 `**.agents/specs/....md`**；兼容旧目录时也可为 `**.agents/designs/....md**`）。
47
+ - 某 plan 的**权威设计输入**在知识库、迭代 compass 或规格目录中时，在 `**plans[].metadata**` 中登记路径，推荐使用已列标准键：`**primary_spec**`（单文件）、`**spec_refs**`（`string[]`）、`**iteration_compass**` / `**iteration_refs**`（迭代级，可选）。路径为**仓库内相对路径**（推荐布局下常写作 `**.agents/knowledge/....md**`、`**.agents/iterations/....md**` 或 `**.agents/specs/....md**`；兼容旧目录时也可为 `**.agents/designs/....md**`）。
35
48
  - 执行方在 **implement 前**须按 metadata 读取这些文件，并与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
36
49
 
37
50
  ## 维护规则
38
51
 
39
- 1. **新增**：按命名规则添加 `.md` → 在 `knowledge/README.md` 索引表增加一行 → 在相关 `plans[].metadata` 更新 `primary_spec` / `spec_refs`（若该文档为本 plan 输入/输出）。
52
+ 1. **新增**：按命名规则添加 `.md` → 在 `{KNOWLEDGE_DIR}/README.md` 或 `{ITERATION_DIR}/README.md` 索引表增加一行 → 在相关 `plans[].metadata` 更新 `primary_spec` / `spec_refs` / `iteration_*`（若该文档为本 plan 输入/输出）。
40
53
  2. **阅读**：开发类 agent 在开始编码前，**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
41
54
  3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
42
55
  4. **归档**：当文档内容已完全反映到已合并代码中时：**保留文件不删除**（保留设计考据）；将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`。**不要**把知识库产物搬进 `**{HARNESS_DIR}/archived/plans/`**（该处用于**计划行**冷快照）；知识库用索引状态表达生命周期即可。
@@ -45,7 +58,9 @@
45
58
 
46
59
  - `**reports/<plan-id>/`**：偏 **审查流程留档**（review、QC1/2/3、consolidated），只读历史。
47
60
  - `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与根级 `**residual_findings**` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
48
- - `**knowledge/**`：偏 **可复用的设计上下文**（规格、决策、分析），可被后续 plan 或多会话反复引用；三者可互链，但职责不混写。
61
+ - `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
62
+ - `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 compass 与规划快照，通常按版本索引而非按单 plan 长期复用。
63
+ - 四者（reports / residuals / knowledge / iterations）可互链，但职责不混写。
49
64
 
50
65
  ---
51
66
 
@@ -58,7 +73,8 @@
58
73
  | ----------------------------------------- | --------------------------------------------------------------------- |
59
74
  | `**{PLAN_DIR}/reports/<plan-id>/**` | QC / review **流程留档**（`-qc*.md`、consolidated 等），只读历史链 |
60
75
  | **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文** |
61
- | `**{HARNESS_DIR}/knowledge/`** | 可跨 plan 复用的**设计**上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + 本目录为跟踪权威） |
76
+ | `**{KNOWLEDGE_DIR}/**` | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
77
+ | `**{ITERATION_DIR}/**` | 迭代/版本级 compass；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
62
78
 
63
79
 
64
80
  **文件命名（推荐）**：`<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/references/plan-files-and-reports.md CHANGED
@@ -36,7 +36,7 @@
36
36
  - **batch 之间**：依赖实现方 **`verification-before-completion`**、主 plan 任务勾选与 PM 协调；需要书面中间意见时，用对话、主 plan 批注或**非三审**的定向检查（如单审、架构 review），**不**默认等同「又一轮完整三审」。
37
37
  - **Request Changes 后复验**：若须再跑一轮完整三审，使用**新文件名**落盘，避免覆盖首轮报告，例如 `<plan-id>-qc1-rev2.md` … `<plan-id>-qc3-rev2.md`（或团队约定的 `wave2-` 前缀）；`@project-manager` 在 `QC Consolidated Decision` 中写明**当前以哪一波次为准**。
38
38
  - **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用子范围专用标签或子目录，避免与「整 plan 终局」那套 `-qc*.md` 混名。
39
- - **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-harness-core` `references/branch-and-worktree.md` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
39
+ - **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-harness-core` `references/branch-and-worktree.md` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 合入 `main`/`master` **须走 PR**，见 `mstar-plan-conventions` SKILL.md **「Spec 文档驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
40
40
 
41
41
  ### 多 `plan_id` 同时 `InReview`（PM 编排）
42
42
 
package/harness-skills/mstar-plan-conventions/references/status-and-residuals.md CHANGED
@@ -116,7 +116,8 @@ QC 报告模板见 `mstar-review-qc`。把 finding 登记进根级 `**residual_f
116
116
  | 键 | 类型 | 用途 |
117
117
  | --------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
118
118
  | `working_branch` | string | 本 plan 实现所用分支名，与 Assignment `**Working branch`** 对齐（SSOT） |
119
- | `merge_target` | string | 预期合并目标分支（如 `main`）；默认分支以项目约定为准 |
119
+ | `spec_integration_branch` | string | （多 Plan 同源 **Spec** 时推荐）该 Spec 对应的 **集成分支** 名；各 Plan 实现分支收口时应 merge 回此线，而非默认直接进 `main`（见 `mstar-plan-conventions` SKILL.md「Spec 文档驱动的分支模型」） |
120
+ | `merge_target` | string | 本 plan 成果 **下一跳** 预期合并到的分支：多 Plan + Spec 模型下 **通常为 `spec_integration_branch`**；最终进 `main` 仍走 **PR**（同 skill）。单 plan / 无 Spec 集成线时可为 `main` 或团队约定名 |
120
121
  | `branch_policy` | string | 与 `mstar-harness-core` 一致的一行策略说明（如 `direct on main — <reason>` 或 `create feature/x from main`） |
121
122
  | `phase` | string | 程序/路线图阶段标签（如 `Phase 0`、`v1.0`） |
122
123
  | `priority` | `high` | `medium` | `low` | PM 编排优先级 |
@@ -127,7 +128,9 @@ QC 报告模板见 `mstar-review-qc`。把 finding 登记进根级 `**residual_f
127
128
  | `blocked_by_plan_id` | string | 若阻塞来自另一计划，填对方 `**plans[].id`** |
128
129
  | `dependency` | string | 其它依赖说明（接口、外部团队）；与 `blocked_by_plan_id` 互补 |
129
130
  | `next_action` | string | 当前解锁后或审查后的下一步（给谁、做什么） |
130
- | `primary_spec` | string | 主规格/设计文档路径（仓库内相对路径；**常为** `{HARNESS_DIR}/knowledge/...` 或 `{SPECS_DIR}/...`，其中 `{SPECS_DIR}` 支持 `specs/` 与 `designs/`）；多文档可用 `spec_refs`（string[]） |
131
+ | `primary_spec` | string | 主规格/设计文档路径（仓库内相对路径；**常为** `{KNOWLEDGE_DIR}/...` 或 `{SPECS_DIR}/...`，其中 `{SPECS_DIR}` 支持 `specs/` 与 `designs/`）；多文档可用 `spec_refs`（string[]） |
132
+ | `iteration_compass` | string | 可选：本轮依赖的迭代/版本 compass（`{ITERATION_DIR}/...`） |
133
+ | `iteration_refs` | string[] | 可选：多个迭代 compass 或 program 快照路径 |
131
134
  | `qc_status` / `tests` / `commits` | string | **InReview / Done** 前后的可验证快照（结论摘要、测试统计、commit 提示），**非**替代正式报告文件 |
132
135
 
133
136
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mstar-harness/opencode",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
5
5
  "license": "MIT",
6
6
  "repository": {