@modus-ai/modus 0.2.10 → 0.3.0

package/templates/domain-history-readme.md

@@ -0,0 +1,60 @@
+# {Domain} — 知识演变历史（History）
+
+> **路径**：`modus/knowledge_base/domain/{domain}/history/`
+> **作用**：增量变更历史。**最新版本写入 `code/`**，旧版本归档于此，形成可追溯的演变链。
+> **维护**：`/modus:init` 强刷时自动归档旧版本；命令归档（`/modus:auto --archive`）时按 Story 写入。
+
+---
+
+## 文件命名规范
+
+```
+history/
+├── README.md
+├── 2026-05-22-init.md           # 首次初始化快照
+├── 2026-06-10-S12345.md         # 关联 Story 的变更
+├── 2026-07-01-refactor.md       # 重构变更
+└── snapshots/                   # 整目录快照（重大重构前）
+    └── 2026-08-15-pre-refactor/
+```
+
+---
+
+## 文件内容模板
+
+```markdown
+# {YYYY-MM-DD} — {Change Title}
+
+## 元信息
+- 触发：（init / story / refactor / manual）
+- 关联 Story：S-12345
+- 涉及文件：code/entities.md, code/apis.md
+- 变更摘要：
+
+## 关键 Diff（人类可读）
+- 新增：实体 `XxxBO`，字段 `yyy`
+- 修改：接口 `/api/v1/foo` 入参从 `bar` 改为 `baz`
+- 删除：废弃的 `OldService.process`
+
+## 业务影响
+（变更是否破坏向后兼容？是否需要灰度？）
+
+## 评审记录
+| 评审人 | 意见 |
+|-------|------|
+|  |  |
+```
+
+---
+
+## 检索方式
+
+| 场景 | 检索路径 |
+|------|---------|
+| 历史相似 Story | grep `S-XXXXX` history/*.md |
+| 某个实体的演变 | grep `EntityName` history/*.md |
+| 某段时间的所有变更 | ls history/2026-Q2-*.md |
+
+---
+
+> **维护提示**：本目录**只追加，不删除**（除非显式手工清理 snapshots/）。

package/templates/domain-scenarios-readme.md

@@ -0,0 +1,58 @@
+# {Domain} — 测试场景（Test Scenarios）
+
+> **路径**：`modus/knowledge_base/domain/{domain}/scenarios/`
+> **作用**：场景化接口调用链 + 端到端用例，供**测试团队消费**与**spec 阶段引用**。
+> **特性**：人工维护为主；命令也可写入（如 `/modus:spec` 完成时回写）。
+
+---
+
+## 文件组织
+
+```
+scenarios/
+├── README.md                  # 本文件
+├── e2e-{flow}.md              # 端到端流程（如 e2e-purchase.md）
+├── api-chain-{topic}.md       # 接口调用链（如 api-chain-checkout.md）
+├── data-prep.md               # 测试数据准备
+└── matrix.md                  # 兼容性/参数矩阵
+```
+
+---
+
+## 场景模板
+
+```markdown
+# Scenario: 新增专辑分发主流程
+
+## 前置数据
+- 用户：`uid=10086`，类型=个人
+- 专辑：`album_id=A001`，状态=待审核
+
+## 调用链
+
+| 步骤 | 接口 | 参数 | 预期返回 |
+|------|------|------|---------|
+| 1 | POST /api/album/submit | {...} | 200, status=pending |
+| 2 | GET /api/album/A001 | — | status=pending |
+| 3 | POST /admin/album/approve | {id: A001} | 200 |
+| 4 | GET /api/album/A001 | — | status=approved |
+
+## 验收点
+- [ ] 状态机正确流转
+- [ ] 审核日志写入
+- [ ] 通知发送
+```
+
+---
+
+## 与其他资产的关联
+
+| 关联 | 说明 |
+|------|------|
+| `../code/apis.md` | 场景使用的接口定义 |
+| `../business/` | 场景背后的业务规则 |
+| `modus/artifacts/<id>/code/spec/` | spec 命令产出的 Gherkin 场景 |
+
+---
+
+> **维护提示**：本目录优先服务于"测试团队、spec 阶段、回归测试"；命令侧仅在用户显式触发时写入。

package/templates/knowledge-base-map.md

@@ -0,0 +1,78 @@
+# Knowledge Base Map — 知识库地图（v4.0）
+
+> **路径**：`modus/knowledge_base/map.md`
+> **作用**：所有 Modus 命令的 Level 1 入口（~200 tokens 加载）；提供"部门 → 团队 → 项目 → 业务域"四层索引。
+> **维护**：由 `/modus:init` 自动生成与刷新；用户可手工补充团队/项目元信息。
+
+---
+
+## 1. 项目元信息
+
+```yaml
+project: ""                 # 项目英文名
+project_zh: ""              # 项目中文名
+department: ""              # 所属部门
+team: ""                    # 所属团队
+primary_stack: ""           # java | frontend | go | python | mixed
+modus_version: "4.0"
+last_init_at: ""
+```
+
+---
+
+## 2. 业务域索引（Domain Catalog）
+
+> 每个 domain 对应 `modus/knowledge_base/domain/<domain>/`。
+
+| Domain | 名称 | 入口 Skill | 业务规则 | 测试场景 | 历史 |
+|--------|------|-----------|---------|---------|------|
+| `_conventions` | 团队约定 | `domain/_conventions/code/SKILL.md` | — | — | — |
+| `_tech-wiki` | 技术 Wiki | `domain/_tech-wiki/code/SKILL.md` | — | — | — |
+| `<domain>` | （示例：合同域） | `domain/<domain>/code/SKILL.md` | `domain/<domain>/business/` | `domain/<domain>/scenarios/` | `domain/<domain>/history/` |
+
+---
+
+## 3. 服务调用全图
+
+> 详见 `modus/knowledge_base/service-graph.md`。本节仅作快速索引。
+
+- 当前注册服务数：N
+- 跨域调用关系：见 service-graph.md §2
+- 外部依赖：见 service-graph.md §3
+
+---
+
+## 4. 加载策略（命令执行时按需读取）
+
+```
+L0  modus/knowledge_base/map.md                              # ~200 tokens（必读）
+L1  modus/knowledge_base/domain/<d>/code/SKILL.md            # ~500 tokens（按域）
+L2  modus/knowledge_base/domain/<d>/code/{entities|apis|services|data-models}.md  # ~800 tokens/个（按需）
+L3  modus/knowledge_base/domain/<d>/business/                # 业务规则（仅业务约束相关任务）
+L4  modus/knowledge_base/domain/<d>/scenarios/               # 测试场景（仅 spec 阶段或测试）
+```
+
+---
+
+## 5. 与产物的关联
+
+| 阶段 | 产物路径 | 引用知识 |
+|------|---------|---------|
+| 需求澄清 | `modus/artifacts/<id>/pid/` | `domain/<d>/business/` |
+| 评估设计 | `modus/artifacts/<id>/design/` | `domain/<d>/code/`, `service-graph.md` |
+| 编码实施 | `modus/artifacts/<id>/code/` | 全部 |
+| 上线归档 | `modus/artifacts/<id>/archive/` | 反向写入 `domain/<d>/history/` |
+
+---
+
+## 6. 跨项目工作区路由（如适用）
+
+> 多项目工作区在仓库根有 `workspace-catalog.md`，列出每个子项目的 `modus/knowledge_base/map.md` 路径。
+
+| 子项目 | 路径 |
+|--------|------|
+|  | `<sub>/modus/knowledge_base/map.md` |
+
+---
+
+> **维护提示**：本文件由 `/modus:init` 强刷生成；如需手工补充，请使用 `> [人工补充]` 注释段落，避免被覆盖。

package/templates/knowledge-base-service-graph.md

@@ -0,0 +1,100 @@
+# Service Graph — 全局服务调用关系图（v4.0）
+
+> **路径**：`modus/knowledge_base/service-graph.md`
+> **作用**：L0 级全局视图，标识本项目所有服务的调用关系、外部依赖、数据流向。
+> **维护**：`/modus:init` 自动生成（基于代码扫描） + 人工微调（标注业务语义）。
+
+---
+
+## 元信息
+
+```yaml
+generated_at: ""
+generator: "modus-init"
+manual_overrides: []        # 人工手工修正的边的 ID 列表（防止被自动重写覆盖）
+```
+
+---
+
+## 1. 服务清单（Internal Services）
+
+| 服务名 | 类型 | 入口 | 出口 | 所属域 |
+|-------|------|------|------|-------|
+|  | HTTP/MQ/RPC/Job |  |  |  |
+
+---
+
+## 2. 调用关系图（Call Graph）
+
+```mermaid
+graph LR
+  subgraph 上游
+    Up1[上游系统A]
+    Up2[上游系统B]
+  end
+  subgraph 本项目
+    S1[服务1]
+    S2[服务2]
+  end
+  subgraph 下游
+    D1[下游系统A]
+    D2[下游系统B]
+  end
+
+  Up1 --> S1
+  Up2 --> S1
+  S1 --> S2
+  S2 --> D1
+  S2 --> D2
+```
+
+### 2.1 关键调用链（Top N）
+
+| 链路 ID | 链路描述 | QPS 估算 | 关键超时 |
+|---------|---------|---------|---------|
+| C-001 |  |  |  |
+
+---
+
+## 3. 外部依赖（External Dependencies）
+
+| 名称 | 类型 | 用途 | SLA | 兜底方案 |
+|------|------|------|-----|---------|
+|  | DB/Cache/MQ/3rd API |  |  |  |
+
+---
+
+## 4. 跨域调用（Cross-Domain Calls）
+
+> 标识不同 `domain/` 之间的调用关系，重点关注是否存在循环依赖。
+
+| 调用方域 | 被调方域 | 接口 | 是否合理 |
+|---------|---------|------|---------|
+|  |  |  |  |
+
+---
+
+## 5. 数据流向（Data Flow，可选）
+
+```mermaid
+flowchart LR
+  Source[数据源] --> Process1[处理1]
+  Process1 --> Storage[(存储)]
+  Storage --> Process2[处理2]
+  Process2 --> Sink[消费方]
+```
+
+---
+
+## 6. 演进历史
+
+| 日期 | 变更 | Story ID | 备注 |
+|------|------|---------|------|
+|  |  |  |  |
+
+---
+
+> **维护规则**：
+> 1. 自动生成部分（§1、§2 边）由 `/modus:init` 重写；人工标注的部分通过 `manual_overrides` 锁定。
+> 2. §3、§4、§5 主要由人工维护；自动扫描只能给出候选，人工确认后才写入。
+> 3. 任何架构级变更（新增服务、删除服务、调用方向反转）必须更新 §6。

package/templates/knowledge-catalog.md

@@ -1,71 +1,64 @@
-# Modus 知识全景目录 — {project-name}
-# 所有 Modus 命令启动时先读此文件（Level 1 加载，~200 tokens）
-# 框架版本：3.1.0 | 知识库路径：{project}/modus/knowledge/**（Single Source of Truth）
-# 多平台适配：CLAUDE.md / AGENTS.md / .cursor/rules/ 均为引用式，修改请直接编辑 modus/knowledge/ 下的文件
+# Modus 知识全景目录（兼容入口） — {project-name}
+# 框架版本：4.0.0
 #
-# 路由层级：
-#   workspace → modus/workspace-catalog.md（顶层，~100 tokens）
-#   project   → 本文件（~200 tokens）
-#   domain    → modus/knowledge/biz-*/SKILL.md（~3000 tokens/个，按需加载）
-# 按需再读完整 SKILL.md（Level 2，~3000 tokens/个）
-# 或直接读 Skill 引用的实际代码文件（Level 3，按需）
+# ⚠️ v4.0 起本文件已被 `modus/knowledge_base/map.md` 取代。
+# 为保证 v3.x 用户的脚本/Skill 仍可工作，本文件作为兼容入口被生成（指向 v4 路径）。
+# 新项目请直接使用 modus/knowledge_base/map.md。
+
+# 新主入口（请改用此路径）：
+#   modus/knowledge_base/map.md            — Level 1 全景索引（~200 tokens）
+#   modus/knowledge_base/service-graph.md  — Level 1 服务调用图
+
+# v4.0 渐进加载（4 级）：
+#   L1  modus/knowledge_base/map.md
+#   L2  modus/knowledge_base/domain/<d>/code/SKILL.md
+#   L3  modus/knowledge_base/domain/<d>/code/{entities|apis|services|data-models}.md
+#   L4  代码实际文件（按 key_files 索引）
 
 updated: {YYYY-MM-DD}
 
 ## 全局行为守卫 (Layer 0-G)
-# 所有命令 Step 0 加载，优先级：低于 constitution.hard_rules，高于 Skill 建议
 - **behavior-guard**: `modus/behavior-guard.md` — 五条全局行为约束
   (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution · Token Budget Guard)
   [由 /modus:init 生成，不随项目代码变化，手动维护]
 
 ## 团队约定 (Layer 0-T)
 - **_conventions**: {规范描述} [maturity: draft] 更新: {日期}
-  - 路径：`{project}/modus/knowledge/_conventions/SKILL.md`
+  - v4 路径：`{project}/modus/knowledge_base/domain/_conventions/code/SKILL.md`
+  - v3 兼容（已废弃）：`{project}/modus/knowledge/_conventions/SKILL.md`
 
 ## 技术知识 (Layer 1)
 - **_tech-wiki**: {技术栈描述} [maturity: draft] 更新: {日期}
-  - 路径：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
+  - v4 路径：`{project}/modus/knowledge_base/domain/_tech-wiki/code/SKILL.md`
 
 ## 业务知识 (Layer 2)
 <!-- 由 /modus:init 生成，由各模式工作流自动更新 -->
-- **biz-{domain}**: {中文域名} — {核心职责一句话} [maturity: draft] 最近引用: {日期}
-  - 路径：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
+- **{domain}**: {中文域名} — {核心职责一句话} [maturity: draft] 最近引用: {日期}
+  - v4 路径：`{project}/modus/knowledge_base/domain/{domain}/code/SKILL.md`（入口）
+  - 业务规则：`{project}/modus/knowledge_base/domain/{domain}/business/`
+  - 测试场景：`{project}/modus/knowledge_base/domain/{domain}/scenarios/`
+  - 历史变更：`{project}/modus/knowledge_base/domain/{domain}/history/`
 
 ## 域依赖图 (Dependency Graph)
 <!--
   格式：{下游域} --> {上游域1}, {上游域2}
-  含义：下游域的 Skill 中 upstream_skills 声明了对上游域的依赖。
-  当上游域 hash 变更时，下游域的 stale_cascade 自动置为 true（在 ⚠️ 标注处可见）。
-  由 /modus:init 自动生成，可手动补充跨域调用关系。
--->
-<!-- example:
-  payment --> order, user
-  notification --> order, payment
-  report --> order, payment, user
+  也参见 modus/knowledge_base/service-graph.md
 -->
 <!-- 当前依赖关系（/modus:init 扫描后填入）：
   {待填入}
 -->
 
-## 渐进加载说明
-
-启动任意 Modus 命令时的加载顺序：
-  Level 1（必须，~200 tokens）:  读本文件，了解有哪些知识可用
-  Level 2（按需，~3000 tokens）: 根据任务匹配相关域，读对应 SKILL.md
-  Level 3（按需，无上限）:       执行任务时读 Skill 引用的实际代码文件
-
-目标：不相关的 Skill 不加载，大幅降低 token 消耗。
-
 ## 框架命令（快速参考）
-- **modus:init** `--help` `--enhance [domain]` `--enhance-all` `--migrate` `--dry-run` `--force` `--platform [list]` `--no-sync` `--verbose` `--reset-maturity` `--project [name]`
+- **modus:init** `--help` `--enhance [domain]` `--enhance-all` `--migrate-v4` `--dry-run` `--force` `--platform [list]` `--no-sync` `--verbose` `--reset-maturity` `--project [name]`
 - **modus:vibe** `--help` `--domain [name]` `--project [name]` `--context [file]` `--no-skill` `--verbose` `--dry-run`
-- **modus:plan** `--help` `--story [url]` `--design` `--quick` `--enhance` `--no-build` `--resume [name]` `--complexity [level]` `--project [name]`
+- **modus:plan** `--help` `--story [url]` `--design` `--code [path]` `--continue [name]` `--quick` `--enhance` `--no-build` `--resume [name]` `--complexity [level]` `--project [name]`
 - **modus:spec** `--help` `--story [url]` `--lite` `--delta` `--testcase` `--verify` `--resume [name]` `--no-archive` `--project [name]`
 - **modus:auto** `--help` `--force [mode]` `--no-confirm` `--show-scores` `--project [name]`
-- **modus:harness** `--help` `--story [url]` `--skip [agents]` `--loop1-only` `--resume` `--dry-run` `--force-rebuild-skill` `--no-deploy` `--max-loop2 [n]` `--notify [channel]` `--project [name]`
+- **modus:harness** `--help` `--story [url]` `--from-plan [name]` `--skip [agents]` `--loop1-only` `--resume` `--dry-run` `--force-rebuild-skill` `--no-deploy` `--max-loop2 [n]` `--notify [channel]` `--show-progress` `--project [name]`
+- **modus:cr** `--help` `--doc [path]` `--diff [scope]` `--story [url]` `--quick`
 - **modus:upgrade** `--help` `--check` `--dry-run` `--changelog` `--target [version]` `--project [name]`
 
-## Skill status 生命周期
+## Knowledge status 生命周期
 
 | status    | 含义                    | 升级方式                          |
 |-----------|-------------------------|-----------------------------------|
@@ -85,11 +78,13 @@ updated: {YYYY-MM-DD}
 
 ## 防腐机制核心字段
 
-每个 Skill frontmatter 必须包含以下字段，缺一不可：
-- **last_referenced**: 最后引用时间（每次被命令加载时更新）
-- **usage_count**: 使用次数（每次完成真实开发任务后 +1）
-- **last_hash**: 全局 SHA-1（对每个文件单独计算 SHA-1，将「路径:SHA-1」对按文件路径字母序排序后拼接，再整体计算 SHA-1，禁止内容直接拼接）；引用时快速比对，不一致则展开 file_hashes 逐文件定位
-- **file_hashes**: 文件级 hash map（`{路径: SHA-1}`）；全局 hash 不一致时使用，精准输出变更文件清单
-- **key_files**: 关键源文件列表（最多 20 个，用于 hash 计算）
+每个域 `code/SKILL.md` frontmatter 必须包含以下字段，缺一不可：
+- **last_referenced**: 最后引用时间
+- **usage_count**: 使用次数
+- **last_hash**: 全局 SHA-1（详见 modus-init Skill）
+- **file_hashes**: 文件级 hash map
+- **key_files**: 关键源文件列表
+
+详见：`templates/skills/modus-init/SKILL.md`「防腐机制总览」。
 
-详细说明见：modus/templates/skills/modus-init/SKILL.md「防腐机制总览」章节
+> **维护提示**：本文件被生成器视为旧版兼容入口；权威源在 `modus/knowledge_base/map.md`。

package/templates/paths-v4.md

@@ -0,0 +1,156 @@
+---
+schema_version: "4.0"
+title: "Modus v4.0 路径权威定义（Single Source of Truth）"
+status: "active"
+supersedes: ["v3.2 路径表"]
+last_updated: "2026-05-22"
+---
+
+# Modus v4.0 目录范式（Single Source of Truth）
+
+> **本文件是 Modus 框架内所有命令、Skill、Agent、Generator 的"路径唯一权威"。**
+> 任何对路径的引用必须以本文件为准；文件之间发生冲突时，以本文件为准。
+
+---
+
+## 1. 顶层目录骨架（用户项目侧）
+
+```
+<项目根目录>/
+├── .modus/                              # CLI 中性层（命令 & 团队技能包）
+│   ├── commands/                        # 命令全集（所有平台共建入口）
+│   └── skills/                          # 团队自定义技能包（如查日志、查监控）
+│
+├── .codebuddy/                          # 平台特定（仅做引用桩）
+├── .claude/                             # 平台特定（仅做引用桩）
+├── .cursor/                             # 平台特定（仅做引用桩）
+├── .continue/                           # 平台特定（仅做引用桩）
+│
+└── modus/                               # 顶层 Models 层（所有产物 + 知识统一入口）
+    ├── template/                        # 标准产物模板（命令 / 节点产物）
+    │   ├── pid.md                       # 需求澄清模板
+    │   ├── design.md                    # 评估设计模板
+    │   ├── spec.md                      # Gherkin 验收模板
+    │   ├── plan.md                      # 实施计划模板
+    │   ├── analysis.md                  # 分析报告模板（Harness Loop1）
+    │   └── sprint-contract.md           # Sprint 契约模板（Harness Loop2）
+    │
+    ├── knowledge_base/                  # 知识库（代码知识 + 业务知识 + 测试场景 + 历史）
+    │   ├── service-graph.md             # L0 全局服务调用关系图
+    │   ├── map.md                       # 知识库地图（部门 → 团队 → 项目三层索引）
+    │   └── domain/                      # 按业务域划分
+    │       ├── _conventions/            # 团队约定（横切，无 business/scenarios）
+    │       │   └── code/SKILL.md
+    │       ├── _tech-wiki/              # 技术知识（横切，无 business/scenarios）
+    │       │   └── code/SKILL.md
+    │       └── <domain>/                # 普通业务域（如 contract, copyright, library）
+    │           ├── README.md            # 域描述与上下游关系
+    │           ├── code/                # 代码翻译层（脚本自动提取，可强刷）
+    │           │   ├── SKILL.md         # 入口（frontmatter + 摘要 + 索引）
+    │           │   ├── entities.md      # 业务实体
+    │           │   ├── apis.md          # 接口列表
+    │           │   ├── services.md      # 服务调用图
+    │           │   └── data-models.md   # 数据模型
+    │           ├── business/            # 人工确认层（业务规则，独立维护，不被强刷覆盖）
+    │           │   └── README.md
+    │           ├── scenarios/           # 场景化接口调用链（供测试团队消费）
+    │           │   └── README.md
+    │           └── history/             # 增量变更历史（最新覆盖，旧版归档于此）
+    │               └── README.md
+    │
+    └── artifacts/                       # 产物目录（以 Story ID 为维度隔离）
+        └── <STORY_ID>/
+            ├── pid/                     # 需求澄清阶段
+            │   ├── prd.md               # 需求文档（产品原文 + Agent 增强标注）
+            │   └── dialog/              # 多轮澄清对话历史（不可变）
+            │       └── *.md
+            ├── design/                  # 评估设计阶段
+            │   └── design.md            # 技术方案（边界/状态流转/接口超时）
+            ├── code/                    # 代码开发阶段（plan/spec/harness 实施）
+            │   ├── plan.md              # 实施计划
+            │   ├── spec/                # Gherkin 规格（可多文件）
+            │   ├── sprint-contract.md   # Harness Loop2 契约
+            │   ├── vibe-log.md          # 编码日志
+            │   ├── cr-report.md         # CR 报告
+            │   └── .harness-state.yaml  # Harness 状态机
+            └── archive/                 # 上线验收后人工触发归档
+                ├── summary.md           # 精简版人阅读摘要
+                └── key-scenarios/       # 关键场景快照（供后续迭代检索）
+                    └── *.md
+```
+
+---
+
+## 2. 路径迁移映射（v3.2 → v4.0）
+
+| 维度 | v3.2 旧路径 | v4.0 新路径 |
+|------|------------|------------|
+| 全景索引 | `modus/knowledge-catalog.md` | `modus/knowledge_base/map.md` |
+| 团队约定 | `modus/knowledge/_conventions/SKILL.md` | `modus/knowledge_base/domain/_conventions/code/SKILL.md` |
+| 技术知识 | `modus/knowledge/_tech-wiki/SKILL.md` | `modus/knowledge_base/domain/_tech-wiki/code/SKILL.md` |
+| 业务域知识 | `modus/knowledge/biz-{d}/SKILL.md` | `modus/knowledge_base/domain/{d}/code/SKILL.md`（拆分） |
+| 业务规则 | —（无） | `modus/knowledge_base/domain/{d}/business/` |
+| 测试场景 | —（无） | `modus/knowledge_base/domain/{d}/scenarios/` |
+| 知识历史 | —（无） | `modus/knowledge_base/domain/{d}/history/` |
+| 服务图谱 | —（无） | `modus/knowledge_base/service-graph.md` |
+| 需求澄清 | `modus/stories/{id}/harness/01-analysis.md` | `modus/artifacts/{id}/pid/prd.md` |
+| 设计文档 | `modus/stories/{id}/harness/02-design-brief.md` | `modus/artifacts/{id}/design/design.md` |
+| 实施计划 | `modus/stories/{id}/plan.md` | `modus/artifacts/{id}/code/plan.md` |
+| Gherkin | `modus/stories/{id}/spec/` | `modus/artifacts/{id}/code/spec/` |
+| Sprint 契约 | `modus/stories/{id}/harness/03-sprint-contract.md` | `modus/artifacts/{id}/code/sprint-contract.md` |
+| 编码日志 | `modus/stories/{id}/vibe-log.md` | `modus/artifacts/{id}/code/vibe-log.md` |
+| CR 报告 | `modus/stories/{id}/harness/cr-report.md` | `modus/artifacts/{id}/code/cr-report.md` |
+| Harness 状态 | `modus/stories/{id}/harness/.harness-state.yaml` | `modus/artifacts/{id}/code/.harness-state.yaml` |
+| 命令源 | `templates/commands/*.md` | `.modus/commands/*.md`（用户侧）；模板侧仍在 `templates/commands/` |
+| 团队 Skill | `.codebuddy/skills/team-*/` 等分散 | `.modus/skills/team-*/`（中性源），平台目录留引用桩 |
+
+---
+
+## 3. 读写规则（命令必须遵守）
+
+### 3.1 读取顺序（按需加载）
+1. **L0 必读**：`modus/knowledge_base/map.md`（~200 tokens）
+2. **L1 按域**：`modus/knowledge_base/domain/{domain}/code/SKILL.md`（入口，~500 tokens）
+3. **L2 按文件**：根据 Skill 入口的索引，按需加载 `entities.md` / `apis.md` / `services.md` / `data-models.md`（~800 tokens/个）
+4. **L3 业务规则**：仅当任务涉及业务约束时读 `business/`
+5. **L4 场景**：仅测试同学或 spec 阶段读 `scenarios/`
+
+### 3.2 写入规则
+- **code/** 由 `/modus:init` 强刷生成，**禁止手工编辑**（手工编辑会被覆盖）
+- **business/、scenarios/、history/** 由人工或专项命令维护，**强刷不会覆盖**
+- **artifacts/** 全部由命令产出，按 Story ID 隔离
+
+### 3.3 平台引用桩规则
+- 用户运行 `/modus:init` 时，CLI 同时生成：
+  - 中性源：`modus/knowledge_base/...` 和 `.modus/commands/...`、`.modus/skills/...`
+  - 平台桩：`.codebuddy/`、`.claude/`、`.cursor/`、`.continue/` 下的 SKILL.md/RULE.mdc 仅含 1 行 `@import` 或 frontmatter，指向中性源
+- 修改知识：**只改中性源**（`modus/knowledge_base/`、`.modus/`），桩自动复用
+
+### 3.4 命令同步规则
+- `.modus/commands/*.md` 是命令源
+- 默认情况下，CLI 把命令也复制一份到平台目录（如 `.codebuddy/commands/`）以便平台原生识别 slash command
+- 用户也可只在 `.modus/commands/` 维护，由各平台读取（取决于平台是否支持中性目录）
+
+---
+
+## 4. 关键不变量（Invariants）
+
+1. `modus/knowledge_base/domain/<domain>/code/SKILL.md` **必须存在**且包含 frontmatter
+2. 同一 Story 的所有产物（pid/design/code/archive）共享同一个 `<STORY_ID>` 目录
+3. `archive/` 只在用户**显式归档**时生成（命令：`/modus:auto --archive` 或手动触发）
+4. `history/` 文件按时间倒序命名：`YYYY-MM-DD-{change-id}.md`
+5. 任何脚本/命令读取业务域知识时，**入口必须是 `code/SKILL.md`**（其内的索引指向 entities/apis/services/data-models）
+
+---
+
+## 5. 与旧版的兼容策略
+
+- `/modus:init --migrate-v4`：自动迁移 v3.2 → v4.0
+  - `modus/knowledge/` → `modus/knowledge_base/domain/`（按 biz-* 拆 domain）
+  - `modus/stories/` → `modus/artifacts/`（按子目录拆 pid/design/code）
+  - 旧 `SKILL.md` 整体内容拆到 `code/SKILL.md`（保留摘要） + `entities.md` / `apis.md` / `services.md` / `data-models.md`
+- 命令读取时优先 v4 路径，找不到时降级到 v3.2 路径并提示用户运行 migrate
+
+---
+
+> **维护提示**：本文件被 `templates/commands/*.md`、`templates/skills/*/SKILL.md`、`src/commands/init.ts`、`src/generators/*.ts` 以及 `skills/modus-framework/SKILL.md` 引用。修改本文件时，需触发 `modus-skill-keeper` 同步影响章节。