@modus-ai/modus 0.2.11 → 0.3.0

package/templates/commands/cr.md

@@ -1,6 +1,8 @@
 # /modus:cr — 代码评审（含文档一致性检查）
 
-**用途：** 基于技术方案文档（design.md / plan.md）和可选的 PRD，对代码变更进行「文档-代码一致性检查」与「代码质量 CR」，输出分级问题报告，可选自动创建 TAPD Bug 单。
+**用途：** 基于技术方案文档（`design.md` / `plan.md`）和可选的 PRD，对代码变更进行「文档-代码一致性检查」与「代码质量 CR」，输出分级问题报告，可选自动创建 TAPD Bug 单。
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 **借鉴自：** speckit.analyze（文档一致性自检）+ modus-reviewer（代码质量 CR 框架）+ opsx:apply（contextFiles 上下文加载）
 
@@ -20,9 +22,10 @@
 ## 使用示例
 
 ```
-/modus:cr --doc modus/plans/batch-export/design.md
-/modus:cr --doc modus/plans/batch-export/design.md --story https://tapd.cn/.../123
-/modus:cr --doc "modus/plans/feat/design.md modus/plans/feat/tasks.md"
+/modus:cr --doc modus/artifacts/{story_id}/design/design.md
+/modus:cr --doc modus/artifacts/{story_id}/design/design.md --story https://tapd.cn/.../123
+/modus:cr --doc "modus/artifacts/{story_id}/design/design.md modus/artifacts/{story_id}/code/plan.md"
+/modus:cr --doc modus/plans/batch-export/design.md     # 独立模式（不关联 Story）
 /modus:cr --quick --diff src/order/
 /modus:cr --doc modus/plans/refactor/design.md --diff src/payment/
 ```
@@ -39,12 +42,13 @@
 ⑥ 可选：自动创建 TAPD Bug 单（需配置 tapdProjectId）
 ```
 
-## 产出物
+## 产出物（v4.0）
 
-```
-modus/cr/{YYYYMMDD}-{feature-name}/
-└── cr-report.md    — 评审报告（HANDOFF 格式，含一致性摘要 + P1/P2/P3 问题）
-```
+**关联 Story时**：写入 `modus/artifacts/{story_id}/code/cr-report.md`
+
+**独立模式**：写入 `modus/cr/{YYYYMMDD}-{feature-name}/cr-report.md`
+
+报告格式与HANDOFF 一致，含一致性摘要 + P1/P2/P3 分级问题列表。
 
 ## 与 harness 内置 CR 的对比
 
@@ -71,4 +75,4 @@ modus/cr/{YYYYMMDD}-{feature-name}/
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-cr/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-cr/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/harness.md

@@ -1,6 +1,8 @@
 # /modus:harness — 双 Loop 全自动开发流程
 
-**用途：** 输入 TAPD Story URL，自动执行从需求分析到部署验证的完整开发流程。8 个专业 SubAgent 分工协作，双 Loop 质量闭环，最终将开发经验自动沉淀到知识库。
+**用途：** 输入 TAPD Story URL，自动执行从需求澄清、设计、开发到部署验证的完整开发流程。8 个专业 SubAgent 分工协作，双 Loop 质量闭环，最终将开发经验自动沉淀到知识库。
+
+> **路径范式版本：v4.0**（产出物废 `modus/plans/active/`，统一使用 `modus/artifacts/{story_id}/` 按 pid/design/code/archive 划分子目录；详见 `templates/paths-v4.md`）
 
 **借鉴自：** GitHub Actions Job/Step/Gate 模型 + Devin 多步骤 Agent 架构
 
@@ -50,13 +52,14 @@
 
 ```
 Loop 1（生产层）
-  INIT:   SubAgent 00 知识注入（更新相关 Skill 至最新）
-  SA 01:  需求分析 → 01-analysis.md
-  SA 02:  代码开发 → 02-sprint-contract.md + 代码变更
+  INIT:   SubAgent 00 知识注入（更新相关 domain 知识至最新）
+  SA 01:  需求澄清 → modus/artifacts/{story_id}/pid/prd.md + dialog/
+  SA 01.5: 设计评审 → modus/artifacts/{story_id}/design/design.md
+  SA 02:  代码开发 → modus/artifacts/{story_id}/code/sprint-contract.md + 代码变更
   Gate A: 编译验证（mvn clean compile）→ 失败重入 SA 02，最多 3 次
   SA 03+04+05: 并行（测试/性能/安全）
   Gate B: 三份报告全部 complete
-  SA 06:  代码评审 → cr-report.md
+  SA 06:  代码评审 → modus/artifacts/{story_id}/code/cr-report.md
 
 Loop 2（修复层）
   Gate C: 读 cr-report.md 的 issues 列表
@@ -64,8 +67,8 @@ Loop 2（修复层）
   → 通过：进入收尾
 
 收尾
-  SA 07:  部署验证 → 07-deploy-status.md（prd 等待人工确认）
-  ARCHIVE: 知识提取回写 Skill + 更新 catalog
+  SA 07:  部署验证 → modus/artifacts/{story_id}/code/deploy-status.md（prd 等待人工确认）
+  ARCHIVE: 知识提取回写 modus/knowledge_base/domain/{d}/history/ + 更新 map.md
   Human Final Review: 人工确认后合入主干
 ```
 
@@ -85,18 +88,24 @@ Loop 2（修复层）
 [ARCH]  ✓ 知识沉淀 (2 [pitfall], 1 [decision] 回写)
 ```
 
-## 产出物
+## 产出物（v4.0）
 
 ```
-modus/plans/active/{story-id}/
-├── 01-analysis.md          ← SubAgent 01 产出，含 HANDOFF 块（影响范围、Sprint 拆分）
-├── 01.5-design-brief.md    ← SubAgent 01.5 产出，含架构决策
-├── 02-sprint-contract.md   ← SubAgent 02 产出，含代码变更清单（接口契约）
-├── 03-test-report.md       ← SubAgent 03 产出（单元测试报告）
-├── 04-perf-report.md       ← SubAgent 04 产出（性能审计 N+1/分页风险）
-├── 05-security-report.md   ← SubAgent 05 产出（安全审计 多租户/权限）
-├── cr-report.md            ← SubAgent 06 产出，含 HANDOFF.issues（P1/P2/P3）
-└── 07-deploy-status.md     ← SubAgent 07 产出（部署状态 各环境结果）
+modus/artifacts/{story_id}/
+├── pid/
+│   ├── prd.md                   ← SubAgent 01 (modus-analyst)产出
+│   └── dialog/                  ← 多轮澄清对话历史
+├── design/
+│   └── design.md                ← SubAgent 01.5 (modus-designer)产出
+├── code/
+│   ├── sprint-contract.md       ← SubAgent 02 (modus-developer)产出，含 HANDOFF
+│   ├── test-report.md           ← SubAgent 03 (modus-tester)
+│   ├── perf-report.md           ← SubAgent 04 (modus-perf-auditor)
+│   ├── security-report.md       ← SubAgent 05 (modus-security-auditor)
+│   ├── cr-report.md             ← SubAgent 06 (modus-reviewer)，含 HANDOFF.issues
+│   ├── deploy-status.md         ← SubAgent 07 (modus-deployer)
+│   └── .harness-state.yaml      ← 状态机
+└── archive/                     ← 上线后人工触发，输出 summary.md 与 key-scenarios/
 ```
 
 所有产出物头部包含 HANDOFF 块（schema v1.1，见 `modus/docs/protocol.md`）。
@@ -119,4 +128,4 @@ skill_refs: ["biz-track@v2.1"]
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-harness/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-harness/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/init.md

@@ -1,6 +1,8 @@
-# /modus:init — 业务知识库初始化
+# /modus:init — 业务知识库初始化（v4.0）
 
-**用途：** 扫描项目代码，按业务域分类，在 `modus/knowledge/` 下生成结构化 Skill 文件，作为后续所有 Modus 命令的知识底座。支持多项目工作区路由和多平台引用式适配。
+**用途：** 扫描项目代码，按业务域分类，在 `modus/knowledge_base/domain/` 下生成结构化知识，作为后续所有 Modus 命令的知识底座。支持多项目工作区路由、多平台引用式适配，以及 v3.2 → v4.0 路径迁移。
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 ## 参数说明
 
@@ -9,41 +11,72 @@
 
   --help                    显示完整帮助（中文）
   --project <name>          指定项目（多项目 workspace 使用）
-  --enhance <domain>        仅增量更新指定业务域（如 --enhance biz-track）
-  --enhance-all             重建所有业务域 Skill（保留框架 Skill）
-  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot）
+  --enhance <domain>        仅增量更新指定业务域（如 --enhance contract）
+  --enhance-all             重建所有业务域知识（保留 _conventions / _tech-wiki）
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot,codebuddy,continue）
   --dry-run                 预览将生成/修改的文件，不写入磁盘
   --force                   跳过所有确认提示，直接执行
-  --no-sync                 跳过多平台同步，仅生成 modus/knowledge/
-  --migrate                 迁移旧路径 .codebuddy/skills/modus-biz-* → modus/knowledge/
+  --no-sync                 跳过多平台同步，仅生成 modus/knowledge_base/
+  --migrate-v4              迁移 v3.2 路径 → v4.0（modus/knowledge/ → modus/knowledge_base/domain/<d>/code/，
+                            modus/stories/ → modus/artifacts/）
+  --migrate                 兼容旧版别名，等同 --migrate-v4
   --verbose                 输出详细扫描过程
-  --reset-maturity          重置所有 Skill 的 maturity 为 draft
+  --reset-maturity          重置所有业务域知识的 maturity 为 draft
 ```
 
 ## 使用示例
 
 ```
-/modus:init                          # 全量初始化（首次使用或大重构后）
-/modus:init --help                   # 查看帮助
-/modus:init --enhance biz-track      # 仅更新歌曲域知识
-/modus:init --migrate --dry-run      # 预览知识库路径迁移
-/modus:init --migrate                # 执行迁移（旧路径 → modus/knowledge/）
-/modus:init --enhance-all --no-sync  # 重建所有域，不同步平台
-/modus:init --project operations-job # 多项目时指定项目
+/modus:init                                # 全量初始化（首次使用或大重构后）
+/modus:init --help                         # 查看帮助
+/modus:init --enhance contract             # 仅更新合同域知识（v4 域名不再带 biz- 前缀）
+/modus:init --migrate-v4 --dry-run         # 预览 v3.2 → v4.0 迁移
+/modus:init --migrate-v4                   # 执行迁移
+/modus:init --enhance-all --no-sync        # 重建所有域，不同步平台
+/modus:init --project operations-job       # 多项目时指定项目
 ```
 
-## 产出物
+## 产出物（v4.0）
 
 ```
-modus/knowledge/
-├── _conventions/SKILL.md   — Layer 0-T 团队约定（融合各平台规则）
-├── _tech-wiki/SKILL.md     — Layer 1 技术知识骨架
-└── biz-{domain}/SKILL.md   — Layer 2 业务域知识（每个域一个）
+modus/knowledge_base/
+├── map.md                                 # L0 全景索引（替代旧 knowledge-catalog.md）
+├── service-graph.md                       # L0 全局服务调用图
+└── domain/
+    ├── _conventions/code/SKILL.md         # 团队约定（横切）
+    ├── _tech-wiki/code/SKILL.md           # 技术 Wiki（横切）
+    └── <domain>/                          # 普通业务域
+        ├── README.md                      # 域描述
+        ├── code/                          # 代码翻译层（强刷生成）
+        │   ├── SKILL.md                   # 入口（含 frontmatter）
+        │   ├── entities.md
+        │   ├── apis.md
+        │   ├── services.md
+        │   └── data-models.md
+        ├── business/                      # 业务规则（人工维护，不被覆盖）
+        ├── scenarios/                     # 测试场景（人工/spec 命令维护）
+        └── history/                       # 变更历史（追加）
+
+modus/workspace-catalog.md                 # 工作区顶层路由（多项目）
+
+# 命令源（中性层，所有平台共用）
+.modus/commands/*.md
+.modus/skills/*/                           # 团队自定义技能包
 
-modus/knowledge-catalog.md  — 全景索引（所有命令的快速入口）
-modus/workspace-catalog.md  — 工作区顶层路由（多项目）
+# 平台引用桩（仅 1 行 @import 指向中性源）
+.codebuddy/ | .claude/ | .cursor/ | .continue/ ...
 ```
 
+## v3.2 → v4.0 迁移要点
+
+| v3.2 旧 | v4.0 新 |
+|---------|---------|
+| `modus/knowledge/biz-{d}/SKILL.md` | `modus/knowledge_base/domain/{d}/code/SKILL.md`（拆为 5 文件） |
+| `modus/knowledge-catalog.md` | `modus/knowledge_base/map.md` |
+| `modus/stories/{id}/...` | `modus/artifacts/{id}/...`（按 pid/design/code/archive 分目录） |
+
+详见 `templates/paths-v4.md`。
+
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-init/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-init/SKILL.md` 中的完整流程（中性源；平台目录如 `.codebuddy/skills/modus-init/SKILL.md` 为引用桩）。

package/templates/commands/modus.md

@@ -6,7 +6,7 @@
 
 | 命令 | 用途 | 常用参数 |
 |------|------|---------|
-| `/modus:init` | 扫描代码库，初始化/更新业务知识库 | `--enhance <domain>`, `--migrate`, `--dry-run` |
+| `/modus:init` | 扫描代码库，初始化/更新业务知识库 | `--enhance <domain>`, `--migrate-v4`, `--dry-run` |
 | `/modus:vibe` | 上下文感知日常编码（氛围编程） | `--domain <name>`, `--verbose` |
 | `/modus:plan` | 功能规划（设计文档 + Build 循环） | `--story <url>`, `--design`, `--quick` |
 | `/modus:spec` | 规范驱动开发（行为规格 + 验收标准） | `--story <url>`, `--lite`, `--testcase` |
@@ -43,22 +43,44 @@
 /modus:harness https://tapd.cn/.../stories/view/1234567890
 ```
 
-## 知识库路径（v3.2）
+## 知识库路径（v4.0）
 
 ```
-modus/knowledge/                   # Single Source of Truth（平台无关）
-├── _conventions/SKILL.md          # 团队约定（Layer 0-T）
-├── _tech-wiki/SKILL.md            # 技术知识（Layer 1）
-└── biz-{domain}/SKILL.md          # 业务域知识（Layer 2）
-
-modus/knowledge-catalog.md         # 项目知识目录（~200 tokens）
-modus/workspace-catalog.md         # 工作区顶层路由（多项目）
+modus/                                          # 顶层 Models 层
+├── template/                                    # 产出模板（pid/design/spec/plan/...）
+├── knowledge_base/                              # Single Source of Truth
+│   ├── map.md                                   # 全景索引（~200 tokens）
+│   ├── service-graph.md                         # L0 全局调用图
+│   └── domain/
+│       ├── _conventions/code/SKILL.md           # 团队约定
+│       ├── _tech-wiki/code/SKILL.md             # 技术知识
+│       └── <domain>/                            # 业务域
+│           ├── code/                            # 代码翻译层（自动生成）
+│           │   ├── SKILL.md
+│           │   ├── entities.md
+│           │   ├── apis.md
+│           │   ├── services.md
+│           │   └── data-models.md
+│           ├── business/                        # 业务规则（人工维护）
+│           ├── scenarios/                       # 测试场景
+│           └── history/                         # 变更历史
+└── artifacts/<STORY_ID>/                        # 产出区（按 Story 隔离）
+    ├── pid/                                     # 需求澄清
+    ├── design/                                  # 评估设计
+    ├── code/                                    # 编码实施（plan/spec/harness）
+    └── archive/                                 # 上线后人工归档
+
+.modus/                                         # CLI 中性层
+├── commands/                                    # 命令全集源头
+└── skills/                                      # 团队自定义技能包
+
+.codebuddy/ | .claude/ | .cursor/ | .continue/  # 平台引用桩（仅 1 行 @import）
 ```
 
 重新初始化或更新知识库：
 
 ```
-/modus:init --enhance biz-track    # 仅更新某个域
+/modus:init --enhance <domain>     # 仅更新某个域（v4 名不带 biz- 前缀）
 /modus:init --enhance-all          # 重建所有业务域
-/modus:init --migrate              # 从旧路径迁移到 modus/knowledge/
+/modus:init --migrate-v4           # 从 v3.2 路径迁移
 ```

package/templates/commands/plan.md

@@ -1,6 +1,8 @@
 # /modus:plan — 功能规划（含 Build 执行与知识归档）
 
-**用途：** 针对一个具体需求，基于业务 Skill 上下文进行六维复杂度评估，提出 3 个精准澄清问题后生成结构化 `plan.md`，在用户确认后执行代码生成，最后自动回写新知识到 Skill 库。
+**用途：** 针对一个具体需求，基于业务知识库（`modus/knowledge_base/`）上下文进行六维复杂度评估，提出 3 个精准澄清问题后生成结构化 `plan.md`，在用户确认后执行代码生成，最后自动回写新知识到知识库。
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 **借鉴自：** Cursor Plan Mode（只读规划阶段 + 用户确认后执行）
 
@@ -36,8 +38,8 @@
 /modus:plan --design 评估版权对账系统的重构方案
 /modus:plan --design --story https://tapd.cn/.../123456        # 设计评审模式，关联 TAPD
 /modus:plan --continue my-feature                              # 评审通过，接力 harness 开发
-/modus:plan --code modus/plans/batch-export/design.md          # 按 design.md 任务清单编码（★ 新增）
-/modus:plan --code modus/plans/batch-export/                   # 自动定位目录下的设计文档（★ 新增）
+/modus:plan --code modus/artifacts/{story_id}/code/design.md   # 按 design.md 任务清单编码（v4 路径）
+/modus:plan --code modus/artifacts/{story_id}/code/             # 自动定位目录下的设计文档
 /modus:plan --quick 修复版权审核列表分页 bug
 /modus:plan --read-only 分析中央曲库同步的架构方案
 /modus:plan --resume batch-export 继续上次中断的规划
@@ -53,7 +55,7 @@
   ↓ 人工评审通过后（两种路径可选）
 
 路径 A：任务驱动编码（轻量，无 harness）
-  /modus:plan --code modus/plans/{name}/design.md
+  /modus:plan --code modus/artifacts/{story_id}/code/design.md
   ↓ 按 tasks.md 中的 T-ID 逐任务执行，`- [ ]` → `- [x]`
   ↓ 完成后建议 /modus:cr --doc
 
@@ -67,10 +69,10 @@
 ## 执行流程概览
 
 ```
-① 域匹配：基于 knowledge-catalog.md 判断涉及的业务域
+① 域匹配：基于 modus/knowledge_base/map.md 判断涉及的业务域
 ② 复杂度评估：六维评分 → simple / medium / complex 分级
    complex → 提示考虑升级为 /modus:spec 或 /modus:harness
-③ 两层知识检索：Skill 前置更新（hash 检查）→ 源码按需加载
+③ 两层知识检索：域入口 SKILL.md 前置更新（hash 检查）→ entities/apis/services/data-models 按需加载 → 源码按需加载
 ④ 精准 3 问：pitfall 关联问题 + 范围边界 + 优先级约束
 ⑤ 生成 plan.md：概述 / 关键约束 / 已知风险 / 方案对比 / Todos / 影响文件
    ⚠️ 规划阶段 — 此时尚未修改任何代码
@@ -78,25 +80,27 @@
 ⑦ 后置知识回写：技术决策 → [decision]，新风险 → [pitfall]
 ```
 
-## 产出物
+## 产出物（v4.0）
 
-**标准模式（无 --design）：**
+**Story 模式（含 --story）：**
 ```
-modus/plans/{name}/
-├── .modus-state.yaml   — 状态文件（含 complexity，支持断点续跑）
-└── plan.md             — 规划文档（概述/风险/方案对比/Todos/影响文件）
+modus/artifacts/{story_id}/
+├── design/design.md       — --design 模式产出
+└── code/
+    ├── plan.md            — 标准模式产出
+    ├── .modus-state.yaml  — 状态机，支持断点续跑
+    └── spec/              — （如后续接 /modus:spec）
 ```
 
-**--design 模式（多 artifact）：**
+**独立模式（不含 --story）：**
 ```
-modus/plans/{name}/
-├── .modus-state.yaml   — 状态文件（含 artifacts DAG 状态）
-├── research.md         — 技术可行性研究（复杂度 ≥ medium 时生成）
-├── design.md           — 技术设计文档（9 节：5W1H/3方案/影响范围/API/数据模型/约束/风险/估时）
-└── tasks.md            — 任务清单（spec-kit T-ID 格式，供 --code 模式消费）
+modus/plans/{name}/        — 临时规划区（未关联 Story）
+├── .modus-state.yaml
+├── plan.md
+└── design.md / research.md / tasks.md  （仅 --design 模式）
 ```
 
-归档后移动到：`modus/plans/archive/{date}-{name}/`
+归档后移动到：`modus/artifacts/{story_id}/archive/`（Story 模式）或 `modus/plans/archive/{date}-{name}/`（独立模式）
 
 ## 与其他命令的对比
 
@@ -109,4 +113,4 @@ modus/plans/{name}/
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-plan/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-plan/SKILL.md` 中的完整流程（中性源；各平台目录下同名文件为引用桩）。

package/templates/commands/spec.md

@@ -2,6 +2,8 @@
 
 **用途：** 在 `/plan` 基础上增加行为规格（delta specs），用 GIVEN/WHEN/THEN 明确系统「WHAT」，规格可测试，归档时自动检测冲突并合并到主规格库（Source of Truth）。适用于有接口契约变更、需要可测试验收标准的场景。
 
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
+
 **借鉴自：** OpenSpec 规范 + Gherkin BDD（Cucumber）的 Feature/Scenario 格式
 
 ## 参数说明
@@ -36,11 +38,11 @@
 | 维度 | `/modus:plan` | `/modus:spec` |
 |------|--------------|----------------|
 | 产出物 | 单一 `plan.md` | `delta-specs.md` + `design.md` + `tasks.md` |
-| 目录 | `modus/plans/{name}/` | `modus/changes/{name}/` |
-| 行为规格 | 无 | 有（ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN） |
-| 验收标准 | 无 | 有（可测试 Scenario） |
-| 冲突检测 | 无 | 有（MODIFIED/REMOVED 目标必须存在于主库） |
-| 归档目标 | `modus/plans/archive/` | 合并到 `modus/specs/{domain}/spec.md` |
+| 目录 | `modus/artifacts/{story_id}/code/` 或 `modus/plans/{name}/` | `modus/artifacts/{story_id}/code/spec/` 或 `modus/changes/{name}/` |
+| 行为规格 | 无 | 有（ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN）|
+| 验收标准 | 无 | 有（可测试 Scenario）|
+| 冲突检测 | 无 | 有（MODIFIED/REMOVED 目标必须存在于主库）|
+| 归档目标 | `modus/artifacts/{id}/archive/` 或 `modus/plans/archive/` | 合并到 `modus/knowledge_base/domain/{d}/scenarios/` 或 `modus/specs/{domain}/spec.md` |
 
 ## Delta Specs 格式（Gherkin 风格）
 
@@ -60,22 +62,33 @@ Feature: 批量审批订单
   Then 系统返回 400 错误："批量操作上限 50 条"
 ```
 
-## 产出物
+## 产出物（v4.0）
 
+**Story 模式（含 --story）：**
+```
+modus/artifacts/{story_id}/
+├── design/design.md
+└── code/
+    ├── spec/                       — delta specs（ADDED/MODIFIED/REMOVED）
+    ├── spec-proposal.md            — 意图与范围
+    ├── tasks.md                    — 实现清单（追踪到 Scenario）
+    └── testcases.md                — QA 用例（--testcase 时生成）
+```
+
+**独立模式（不含 --story）：**
 ```
 modus/changes/{name}/
-├── .modus-state.yaml               — 状态文件（支持断点续跑）
-├── proposal.md                     — 意图与范围
-├── specs/{domain}/spec.md          — delta specs（ADDED/MODIFIED/REMOVED）
-├── design.md                       — 技术方案
-├── design-brief.md                 — 精确实现指南（Full 模式）
-├── tasks.md                        — 实现清单（追踪到 Scenario）
-└── testcases.md                    — QA 用例（--testcase 时生成）
-
-归档后：modus/changes/archive/{date}-{name}/
-主规格库：modus/specs/{domain}/spec.md（历次归档合并）
+├── .modus-state.yaml
+├── proposal.md
+├── specs/{domain}/spec.md
+├── design.md
+├── design-brief.md
+├── tasks.md
+└── testcases.md
 ```
 
+归档后：Story 模式合并到 `modus/knowledge_base/domain/{domain}/scenarios/`；独立模式合并到 `modus/specs/{domain}/spec.md`。
+
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-spec/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-spec/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/upgrade.md

@@ -33,8 +33,9 @@
 
 | 版本 | 主要变更 |
 |------|---------|
-| v4.0.0 | plan --design 设计评审节点；plan --continue + harness --from-plan 接力机制；HANDOFF protocol schema v1.3（plan 专用字段）；Progress Event Protocol（events.jsonl）；AGENTS.md 自动生成（modus update 驱动，不再手动维护） |
-| v3.2.0 | 跨 Skill 路径全面统一到 `modus/knowledge/biz-*/`；步骤编号规范化（禁止小数步骤）；modus-analyst 产出路径更正到 `modus/stories/{id}/harness/`；modus-plan 双路径产出规则（Story 模式 vs 独立模式） |
+| **v4.0.0** | 目录范式重构：`modus/knowledge/` → `modus/knowledge_base/domain/<d>/code/` (拆分 5 文件) + `business/` + `scenarios/` + `history/`；`modus/stories/` → `modus/artifacts/<id>/` (pid/design/code/archive)；`modus/knowledge-catalog.md` → `modus/knowledge_base/map.md`；新增 `modus/template/` 产出模板；新增 `.modus/commands/` + `.modus/skills/` 中立命令与团队技能包；平台目录全部降为引用桩 |
+| v3.3.0 | plan --design 设计评审节点；plan --continue + harness --from-plan 接力机制；HANDOFF protocol schema v1.3 (plan 专用字段)；Progress Event Protocol (events.jsonl)；AGENTS.md 自动生成 |
+| v3.2.0 | 跨 Skill 路径全面统一到 `modus/knowledge/biz-*/`；步骤编号规范化（禁止小数步骤）；modus-analyst 产出路径更正到 `modus/stories/{id}/harness/`；modus-plan 双路径产出规则 |
 | v3.1.0 | 知识库路径迁移：`.codebuddy/skills/modus-biz-*` → `modus/knowledge/biz-*`；新增工作区顶层路由 `modus/workspace-catalog.md`；HANDOFF 协议升级到 schema v1.1 |
 | v3.0.0 | 多项目工作区支持（modus-workspace.yaml）；引用式适配（不复制知识） |
 | v2.x | 初始版本 |
@@ -57,32 +58,43 @@
 ```
 Step 1: 备份
   创建 modus/backup/{YYYYMMDD}-v3.x/ 目录
-  复制所有现有 Skill 文件和 config.yaml 到备份目录
-
-Step 2: HANDOFF 格式兼容检查
-  扫描 modus/stories/*/harness/*.md 中的旧版 HTML 注释块（<!--HANDOFF...-->）
-  自动转换为 YAML frontmatter 格式（schema v1.1 → v1.2/v1.3）
-  输出：「已迁移 N 个产物文件到 YAML frontmatter 格式」
-
-Step 3: plan 产物字段补全
-  扫描 modus/plans/*/plan.md
-  在 HANDOFF frontmatter 中补充新字段（design_mode/status/continue_token/risk_level/estimated_effort）
-  默认值：design_mode=false, status=complete, continue_token=""
-
-Step 4: harness 命令 Skill 更新
-  更新 modus-harness Skill：添加 --from-plan 处理逻辑
-  更新 modus-plan Skill：添加 --design 分支 + --continue 接力逻辑
-  输出：「已更新 modus-harness / modus-plan Skill 模板」
-
-Step 5: 初始化进度事件目录
-  创建 modus/sessions/ 目录（若不存在）
-  创建 modus/sessions/events.jsonl（若不存在，初始化为空文件）
-  输出：「已初始化 Progress Event 日志：modus/sessions/events.jsonl」
-
-Step 6: AGENTS.md 自动生成（Codex 平台）
-  若 config.yaml platforms 含 codex，重新生成 AGENTS.md：
-  融合：workspace-catalog + constitution.hard_rules + 最新命令参数集
-  输出：「AGENTS.md 已重新生成（Codex 平台适配）」
+  复制所有现有知识与产物文件到备份目录
+
+Step 2: 知识库重构
+  modus/knowledge/biz-{d}/SKILL.md
+    → modus/knowledge_base/domain/{d}/code/SKILL.md  (仅保留 frontmatter 与摘要)
+    → 拆分原内容到 entities.md / apis.md / services.md / data-models.md
+    → 创建空的 business/ + scenarios/ + history/子目录
+  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-catalog.md
+    → modus/knowledge_base/map.md  (结构重生成)
+  生成 modus/knowledge_base/service-graph.md  (基于代码扫描)
+
+Step 3: 产出区重构
+  modus/stories/{id}/
+    ├─ harness/01-analysis.md       → modus/artifacts/{id}/pid/prd.md
+    ├─ harness/02-design-brief.md   → modus/artifacts/{id}/design/design.md
+    ├─ plan.md                      → modus/artifacts/{id}/code/plan.md
+    ├─ spec/                        → modus/artifacts/{id}/code/spec/
+    ├─ harness/03-sprint-contract   → modus/artifacts/{id}/code/sprint-contract.md
+    ├─ harness/cr-report.md         → modus/artifacts/{id}/code/cr-report.md
+    └─ harness/.harness-state.yaml  → modus/artifacts/{id}/code/.harness-state.yaml
+  创建空的 archive/ 子目录
+
+Step 4: 产出模板与中性命令源
+  将 templates/template/ 复制到项目下 modus/template/
+  将现有命令同步到 .modus/commands/  (中性源)
+  将团队资源迁移到 .modus/skills/  (如某些所谓的「查日志」Skill)
+
+Step 5: 平台目录降为引用桩
+  重写 .codebuddy/skills/modus-*/SKILL.md 为仅 1 行 @import，指向 .modus/skills/
+  .claude/, .cursor/, .continue/ 同理
+
+Step 6: HANDOFF schema 升级与路径调整
+  扫描 modus/artifacts/*/code/*.md 中的旧 HANDOFF 块，路径字段调整为 v4 路径
 
 Step 7: 更新 modus/config.yaml
   将 modus_version 更新为 "4.0.0"
@@ -95,20 +107,20 @@ Step 7: 更新 modus/config.yaml
 ✅ Modus v4.0.0 升级完成
 
 迁移内容：
-  ✓ HANDOFF 格式：N 个产物文件已转换为 YAML frontmatter
-  ✓ plan 产物：M 个 plan.md 已补充 v4.0 专用字段
-  ✓ Skill 更新：modus-harness / modus-plan 已更新
-  ✓ 进度事件：modus/sessions/events.jsonl 已初始化
-  ✓ AGENTS.md：已重新生成（若 codex 已启用）
+  ✓ 知识库：N 个业务域拆分为 code/{entities|apis|services|data-models}.md
+  ✓ 产出区：M 个 Story 从 stories/ 迁移到 artifacts/<id>/{pid|design|code|archive}/
+  ✓ 中性命令源：.modus/commands/ + .modus/skills/ 已生成
+  ✓ 平台目录：.codebuddy / .claude / .cursor / .continue 已重写为引用桩
+  ✓ 模板：modus/template/ 生成（6 个产出模板）
 
 备份位置：modus/backup/{YYYYMMDD}-v3.x/
 
-新功能使用方式：
-  设计评审模式：/modus:plan --design [story-url]
-  接力开发：   /modus:plan --continue {name}
-  进度监控：   /modus:harness ... --show-progress
+后续手动步骤：
+  1. 人工检查 modus/knowledge_base/domain/<d>/business/ 并补充业务规则
+  2. 人工检查 modus/knowledge_base/service-graph.md 并修正调用关系
+  3. 运行 /modus:init --enhance-all 验证迁移后知识是否可重生成
 ```
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-upgrade/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-upgrade/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。