@modus-ai/modus 0.2.11 → 0.3.0

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` 同步影响章节。

package/templates/rules/modus-workflow/RULE.mdc

@@ -1,59 +1,66 @@
 ---
-description: Modus workflow conventions. Load this rule when the user runs any /modus:* command or asks about Modus commands, Skills, Harness, plan/spec/vibe workflow, knowledge-catalog, or business Skills.
+description: Modus workflow conventions (v4.0). Load this rule when the user runs any /modus:* command or asks about Modus commands, Skills, Harness, plan/spec/vibe workflow, knowledge_base, artifacts, or business Skills.
 alwaysApply: false
 enabled: true
 ---
 
-# Modus 工作流规范
+# Modus 工作流规范（v4.0）
+
+> 完整路径范式见 `templates/paths-v4.md`。
 
 ## 核心目录结构
 
 ```
-.codebuddy/
-├── skills/
-│   ├── modus-init/SKILL.md          # /modus:init 执行规范
-│   ├── modus-vibe/SKILL.md          # /modus:vibe 执行规范
-│   ├── modus-plan/SKILL.md          # /modus:plan 执行规范
-│   ├── modus-spec/SKILL.md          # /modus:spec 执行规范
-│   ├── modus-harness/SKILL.md       # Harness 调度规范
-│   ├── modus-harness-0*-*/SKILL.md  # Harness SubAgent 规范
-│   ├── modus-team-conventions/      # 团队约定（Layer 0-T）
-│   ├── modus-tech-wiki/             # 技术知识（Layer 1）
-│   └── modus-biz-{domain}/         # 业务知识（Layer 2）
-└── agents/
-    └── modus-harness-0*.md          # Harness SubAgent 定义
-
-modus/
-├── config.yaml                      # 项目配置和 constitution
-├── knowledge-catalog.md             # 知识全景目录（Level 1 索引）
-├── specs/                           # 主规格库
-├── plans/
-│   ├── active/{story-id}/           # 进行中的 Harness 任务
-│   └── archive/                     # 已归档的计划
-├── changes/                         # /modus:spec 变更目录
-└── sessions/vibe-log.md             # /modus:vibe 会话日志
+<项目根>/
+├── .modus/                                      # CLI 中性层
+│   ├── commands/                                # 命令源（所有平台共用）
+│   └── skills/                                  # 团队自定义技能包（如查日志、查监控）
+│
+├── .codebuddy/ | .claude/ | .cursor/ | .continue/   # 平台引用桩（仅 1 行 @import）
+│
+└── modus/                                       # 顶层 Models 层
+    ├── config.yaml                              # 项目配置 + constitution
+    ├── template/                                # 产物模板（pid/design/spec/plan/...）
+    ├── knowledge_base/                          # 知识库（Single Source of Truth）
+    │   ├── map.md                               # L0 全景索引（替代旧 knowledge-catalog.md）
+    │   ├── service-graph.md                     # L0 服务调用图
+    │   └── domain/
+    │       ├── _conventions/code/SKILL.md       # 团队约定
+    │       ├── _tech-wiki/code/SKILL.md         # 技术 Wiki
+    │       └── <domain>/                        # 业务域
+    │           ├── code/                        # 自动生成层（SKILL.md + 4 子文件）
+    │           ├── business/                    # 业务规则（人工维护）
+    │           ├── scenarios/                   # 测试场景
+    │           └── history/                     # 变更历史
+    └── artifacts/<STORY_ID>/                    # 产物（按 Story 隔离）
+        ├── pid/                                 # 需求澄清
+        ├── design/                              # 评估设计
+        ├── code/                                # 编码实施（plan/spec/harness）
+        └── archive/                             # 上线归档
 ```
 
-## 三级渐进加载原则
+## 渐进加载原则（v4.0 四级）
 
 每次 Modus 命令启动时：
-1. **Level 1（必须，~200 tokens）**：读 `modus/knowledge-catalog.md`
-2. **Level 2（按需，~3000 tokens/个）**：基于任务匹配，读对应 `modus-biz-*/SKILL.md`
-3. **Level 3（按需，无限制）**：执行任务时读 Skill 引用的实际代码文件
+1. **Level 1（必须，~200 tokens）**：读 `modus/knowledge_base/map.md`
+2. **Level 2（按需，~500 tokens/域）**：基于任务匹配，读对应 `domain/<d>/code/SKILL.md`（入口含子文件索引）
+3. **Level 3（按需，~800 tokens/文件）**：按需读 `entities.md` / `apis.md` / `services.md` / `data-models.md`
+4. **Level 4（执行时，无上限）**：从知识中的 `key_files` 索引按需读取实际代码文件
 
-不相关的 Skill 不加载，大幅降低 token 消耗。
+不相关的域、子文件不加载，大幅降低 token 消耗。
 
-## 命令速查
+## 命令速查（v4.0 产物路径）
 
-| 命令 | 场景 | 产出物 |
+| 命令 | 场景 | 产出物（v4.0） |
 |------|------|--------|
-| `/modus:init` | 首次初始化或重建知识库 | `.codebuddy/skills/modus-biz-*/SKILL.md` |
-| `/modus:vibe` | 日常编码（含业务上下文） | 代码 + `modus/sessions/vibe-log.md` |
-| `/modus:plan` | 功能规划 | `modus/plans/{name}/proposal+design+tasks.md` |
-| `/modus:spec` | 规范驱动开发 | `modus/changes/{name}/specs/{domain}/spec.md` |
-| `/modus:harness` | 全自动 Harness 流程 | `modus/plans/active/{story-id}/0*.md` |
+| `/modus:init` | 首次初始化或重建知识库 | `modus/knowledge_base/domain/<d>/code/*` |
+| `/modus:vibe` | 日常编码（含业务上下文） | 代码 + `modus/sessions/vibe-log.md`（或 `artifacts/<id>/code/vibe-log.md`） |
+| `/modus:plan` | 功能规划 | `artifacts/<id>/code/plan.md`（Story 模式）/ `modus/plans/{name}/`（独立模式） |
+| `/modus:spec` | 规范驱动开发 | `artifacts/<id>/code/spec/`（Story 模式）/ `modus/changes/{name}/`（独立模式） |
+| `/modus:harness` | 全自动 Harness 流程 | `artifacts/<id>/{pid|design|code}/*` |
+| `/modus:cr` | 代码评审 | `artifacts/<id>/code/cr-report.md` 或 `modus/cr/{date}-{name}/` |
 
-## Skill 知识状态
+## 知识状态
 
 | maturity | 含义 | 衰减规则 |
 |----------|------|---------|

package/templates/skills/modus-agents/analyst/SKILL.md

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（`modus-harness`）  
 **输入：** TAPD Story URL + 相关业务 Skill 内容  
-**产出物：** `modus/stories/{story-id}/harness/01-analysis.md`
+**产出物：** `modus/artifacts/{story_id}/pid/prd.md`（v4.0 路径）
 
 ## 职责
 

package/templates/skills/modus-agents/developer/SKILL.md

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（Gate A0.5 通过后触发）  
 **输入：** `01-analysis.md` + `02-design-brief.md` + 业务 Skill 内容 + constitution  
-**产出物：** `modus/stories/{story-id}/harness/03-sprint-contract.md` + 代码变更
+**产出物：** `modus/artifacts/{story_id}/code/sprint-contract.md` + 代码变更（v4.0 路径）
 
 ## 职责
 

package/templates/skills/modus-agents/reviewer/SKILL.md

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（Gate B 通过后触发）  
 **输入：** 全部产出物（01-analysis.md 至 06-security-report.md）+ 代码变更  
-**产出物：** `modus/stories/{story-id}/harness/cr-report.md`
+**产出物：** `modus/artifacts/{story_id}/code/cr-report.md`（v4.0 路径）
 
 ## 职责
 

package/templates/skills/modus-agents/skill-creator/SKILL.md

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** `/modus:init` / `/modus:plan` 前置更新 / `/modus:spec` 前置更新 / Harness 后置更新 / Harness ARCHIVE 阶段  
 **输入：** 业务域信息 + 项目代码  
-**产出物：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md` / `modus-team-conventions/SKILL.md` / `modus-tech-wiki/SKILL.md` + `modus/knowledge-catalog.md` 更新
+**产出物：** `modus/knowledge_base/domain/{domain}/code/SKILL.md` （业务域入口） / `modus/knowledge_base/domain/_conventions/code/SKILL.md` / `modus/knowledge_base/domain/_tech-wiki/code/SKILL.md` + `modus/knowledge_base/map.md` 更新
 
 ## 职责
 
@@ -677,7 +677,7 @@ Step 4 扩展：upstream/downstream 双向同步（append-only，Git 无冲突
 
 ### Step 5：更新 knowledge-catalog.md
 
-每次写入 Skill 后，同步更新 `modus/knowledge-catalog.md`（使用升级后的条目格式）：
+每次写入知识后，同步更新 `modus/knowledge_base/map.md`（使用升级后的条目格式）：
 
 ```markdown
 - **modus-biz-order**: 订单域 — 创建/状态流转/查询
@@ -1055,7 +1055,7 @@ layer: "1"
 - 关键文件索引路径必须真实存在
 - 每条知识条目必须打上五类型标签之一：`[model]` `[decision]` `[guideline]` `[pitfall]` `[process]`
 - 更新时必须更新 `updated` 日期和 `last_referenced`
-- 模式 D 每次执行后必须同步更新 `modus/knowledge-catalog.md`
+- 模式 D 每次执行后必须同步更新 `modus/knowledge_base/map.md`
 - 统一使用 `status` 字段（不使用 `maturity`），枚举值：`draft | verified | proven | stale | archived`
 - 新生成的 Skill 默认写入 `format_version: v3`（17节标准格式）；存量 14 节 Skill 保留 `format_version: v2`；存量 7 节 Skill 迁移前标记 `format_version: v1`