mspec-cli 4.0.14__tar.gz → 5.0.1__tar.gz

{mspec_cli-4.0.14/src/mspec_cli.egg-info → mspec_cli-5.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mspec-cli
-Version: 4.0.14
+Version: 5.0.1
 Summary: mspec-cli（Member Spec）- 会员组规范驱动开发工作流 CLI 工具
 Author-email: shirayner <team@mspec.io>
 License: MIT
@@ -45,7 +45,7 @@ Dynamic: license-file
 
 **mspec-cli**（Member Spec）- 会员组规范驱动开发工作流 CLI 工具
 
-通过交互式命令行澄清机制，实现结构化问题发现与澄清，提升需求明确度和开发效率。
+通过交互式命令行澄清机制，实现结构化问题发现与澄清；通过自发进化体系，使 AI 随着项目积累越来越了解你的项目。
 
 ## 特性
 
@@ -53,6 +53,7 @@ Dynamic: license-file
 - 🔄 **批量式澄清** - 一次性列出所有问题，统一回答，高效不拖沓
 - 💾 **断点续传** - 支持随时中断，下次自动恢复
 - 📚 **结构化问题分类** - 6个需求维度 + 7个设计维度
+- 🧬 **自发进化体系** - 使用越久，整个 spec coding 流程越精准
 - 🎨 **美观界面** - 使用 Rich 库提供彩色终端输出
 
 ## 文档
@@ -197,9 +198,59 @@ mspec doctor
 └─────────────────────────────────────┘
     │
     ▼
-实施 (apply)
+┌─────────────────────────────────────┐
+│  实施 (apply)                        │
+│  - 按任务清单逐步实施                │
+│  - 可选：记录实施中的轻量观察        │
+└─────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  归档 (archive) + 进化               │
+│  - 生成复盘报告（9个维度）           │
+│  - 更新项目知识库（ADR/词汇/风险）   │
+│  - 积累 3 次后自动触发进化分析       │
+└─────────────────────────────────────┘
 ```
 
+## 🧬 进化体系
+
+mspec 内置 3层8维度 的完整进化体系，无需额外命令，每次 archive 自动推进：
+
+### Layer A — 项目事实（每次立即更新）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/decisions/adr.md` | 技术决策账本 | 不重复讨论已决定的事 |
+| `openspec/glossary.md` | 领域词汇表 | 统一业务术语命名 |
+| `openspec/risk-map.md` | 风险图谱 | 已知高风险区和 bug 模式 |
+
+### Layer B — 流程模式（积累 3+ 次后自动触发）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/templates/*.md` | 进化后的问题分类学 | 精准识别项目特有问题 |
+| `openspec/task-patterns/` | 任务模板库 | 按 change 类型分解任务 |
+| `openspec/config.yaml` | 用户偏好档案 | 减少重复对齐 |
+
+### Layer C — 元信号（长期积累）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/specs/CHANGELOG.md` | 规格演化日志 | 揭示业务边界稳定性 |
+| `openspec/metrics.md` | 效率信号 | 发现系统性瓶颈 |
+
+### 预期效果
+
+| 时间点 | 效果 |
+|--------|------|
+| 第 1 次 archive | ADR 建立，词汇表开始填充 |
+| 第 3 次 archive | 首次触发进化，分类学开始个性化 |
+| 第 5-10 次 | 澄清轮次减少，apply 意外减少 |
+| 长期（20+次） | 项目知识库完备，AI 越来越了解项目 |
+
+
+
 ## 问题分类学
 
 ### 需求问题 (6个维度)

{mspec_cli-4.0.14 → mspec_cli-5.0.1}/README.md

@@ -6,7 +6,7 @@
 
 **mspec-cli**（Member Spec）- 会员组规范驱动开发工作流 CLI 工具
 
-通过交互式命令行澄清机制，实现结构化问题发现与澄清，提升需求明确度和开发效率。
+通过交互式命令行澄清机制，实现结构化问题发现与澄清；通过自发进化体系，使 AI 随着项目积累越来越了解你的项目。
 
 ## 特性
 
@@ -14,6 +14,7 @@
 - 🔄 **批量式澄清** - 一次性列出所有问题，统一回答，高效不拖沓
 - 💾 **断点续传** - 支持随时中断，下次自动恢复
 - 📚 **结构化问题分类** - 6个需求维度 + 7个设计维度
+- 🧬 **自发进化体系** - 使用越久，整个 spec coding 流程越精准
 - 🎨 **美观界面** - 使用 Rich 库提供彩色终端输出
 
 ## 文档
@@ -158,9 +159,59 @@ mspec doctor
 └─────────────────────────────────────┘
     │
     ▼
-实施 (apply)
+┌─────────────────────────────────────┐
+│  实施 (apply)                        │
+│  - 按任务清单逐步实施                │
+│  - 可选：记录实施中的轻量观察        │
+└─────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  归档 (archive) + 进化               │
+│  - 生成复盘报告（9个维度）           │
+│  - 更新项目知识库（ADR/词汇/风险）   │
+│  - 积累 3 次后自动触发进化分析       │
+└─────────────────────────────────────┘
 ```
 
+## 🧬 进化体系
+
+mspec 内置 3层8维度 的完整进化体系，无需额外命令，每次 archive 自动推进：
+
+### Layer A — 项目事实（每次立即更新）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/decisions/adr.md` | 技术决策账本 | 不重复讨论已决定的事 |
+| `openspec/glossary.md` | 领域词汇表 | 统一业务术语命名 |
+| `openspec/risk-map.md` | 风险图谱 | 已知高风险区和 bug 模式 |
+
+### Layer B — 流程模式（积累 3+ 次后自动触发）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/templates/*.md` | 进化后的问题分类学 | 精准识别项目特有问题 |
+| `openspec/task-patterns/` | 任务模板库 | 按 change 类型分解任务 |
+| `openspec/config.yaml` | 用户偏好档案 | 减少重复对齐 |
+
+### Layer C — 元信号（长期积累）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/specs/CHANGELOG.md` | 规格演化日志 | 揭示业务边界稳定性 |
+| `openspec/metrics.md` | 效率信号 | 发现系统性瓶颈 |
+
+### 预期效果
+
+| 时间点 | 效果 |
+|--------|------|
+| 第 1 次 archive | ADR 建立，词汇表开始填充 |
+| 第 3 次 archive | 首次触发进化，分类学开始个性化 |
+| 第 5-10 次 | 澄清轮次减少，apply 意外减少 |
+| 长期（20+次） | 项目知识库完备，AI 越来越了解项目 |
+
+
+
 ## 问题分类学
 
 ### 需求问题 (6个维度)

{mspec_cli-4.0.14 → mspec_cli-5.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mspec-cli"
-version = "4.0.14"
+version = "5.0.1"
 description = "mspec-cli（Member Spec）- 会员组规范驱动开发工作流 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}

{mspec_cli-4.0.14 → mspec_cli-5.0.1}/src/mspec/__init__.py

@@ -1,5 +1,5 @@
 """mspec（Member Spec）- 会员组规范驱动开发工作流 CLI 工具"""
 
-__version__ = "4.0.14"
+__version__ = "5.0.1"
 __author__ = "mspec Team"
 __email__ = "team@mspec.io"

mspec_cli-5.0.1/src/mspec/templates/adr.md

@@ -0,0 +1,23 @@
+# 技术决策账本（Architecture Decision Records）
+
+> **用途**: 记录项目中已做出的架构和技术决策，避免重复讨论已决定的事项。
+> **更新时机**: 每次 archive 时，自动从复盘报告提取新决策追加。
+>
+> **如何消费**:
+> - design 阶段：先查询此文件，已有决策不重复讨论
+> - explore 阶段：比较技术方案时直接引用
+> - propose 阶段：评估 Impact 时与已有决策对齐
+
+---
+
+<!-- 格式：
+## {决策标题} | 来源: {change-name} | 日期: {YYYY-MM-DD}
+
+**选择**: 选了什么方案
+**理由**: 为什么选择这个方案
+**备选**: 考虑过哪些其他方案
+**放弃原因**: 为什么放弃备选方案
+**状态**: active / superseded / deprecated
+-->
+
+*暂无决策记录。第一次 archive 后将自动填充。*

mspec_cli-5.0.1/src/mspec/templates/config.yaml

@@ -0,0 +1,454 @@
+schema: spec-driven
+
+# =============================================================================
+# OpenSpec 工作流增强配置 v5
+# 交互式命令行澄清机制 + 完整进化体系（3层8维度）- 寄生模式
+# =============================================================================
+# ⚠️ 重要：本配置采用"寄生模式"增强 OpenSpec 核心流程
+# 所有增强逻辑通过 context 和 rules 注入，不改变 OpenSpec schema
+# =============================================================================
+
+version: "5.0.1"
+language: zh
+
+# =============================================================================
+# 前置条件检查清单（寄生增强）
+# =============================================================================
+#
+# 以下检查项必须在创建对应 artifact 之前完成。
+# 如果检查不通过，禁止继续。
+#
+context: |
+  ## ⚠️ 强制前置检查清单（不完成禁止继续）
+
+  ### 前置检查 1: 需求澄清
+
+  **检查项**: `spec/requirement-issues.md` 必须存在且状态为 `clarified`
+
+  **检查方法**:
+  1. 检查文件 `openspec/changes/{change-name}/spec/requirement-issues.md` 是否存在
+  2. 检查文件中的状态标记是否为 `clarified`
+
+  **如果不通过，执行以下流程**:
+  ```
+  步骤 1: 读取 openspec/templates/requirement-issue-taxonomy.md
+  步骤 2: 分析需求，识别功能点（Capabilities）
+  步骤 3: 按 6 个维度检查每个功能点的问题
+  步骤 4: 创建 spec/requirement-issues.md，填充发现问题
+  步骤 5: 启动批量澄清（一次性提问）
+         - 将所有 High/Medium 问题组织为编号列表，一次性展示给用户
+         - 格式："需要确认 N 个问题，请一并回答：\n1. [问题]\n   选项：A) ... B) ...\n2. ..."
+         - 等待用户一次性回答所有问题，不要逐题单独提交
+         - 收到完整回答后，统一同步到 requirement-issues.md
+  步骤 6: 确认所有 High 问题已澄清后，更新状态为 clarified
+  ```
+
+  **阻塞条件**: requirement-issues.md 不存在 或 状态 ≠ clarified → 禁止创建 proposal
+
+  ### 前置检查 2: 设计澄清
+
+  **检查项**: `spec/design-issues.md` 必须存在且状态为 `clarified` 或 `resolved`
+
+  **执行时机**: AFTER creating design.md, BEFORE creating tasks
+
+  **如果不通过，执行类似的需求澄清流程**:
+  ```
+  步骤 1: 读取 openspec/templates/design-issue-taxonomy.md
+  步骤 2: 按 7 个维度分析 design.md 的不确定性
+  步骤 3: 创建 spec/design-issues.md
+  步骤 4: 【强制用户确认——无论是否发现问题都必须执行】
+         使用 AskUserQuestion 工具，将分析结果呈现给用户并请求确认：
+         - 如果发现 High/Medium 问题：将所有问题组织为编号列表，一次性展示：
+           格式："需要确认 N 个设计问题，请一并回答：\n1. [问题]\n   选项：A) ... B) ...\n2. ..."
+         - 如果未发现 High/Medium 问题：仍须展示分析摘要并确认：
+           格式："设计分析完成，未发现高优先级问题。主要设计决策摘要如下：\n[列出关键决策]\n请确认以上设计，或提出任何顾虑/补充："
+         - 等待用户回答，不得跳过此步骤
+         - 收到回答后，将用户意见同步到 design-issues.md
+  步骤 5: 根据澄清结果更新 design.md
+  步骤 6: 更新状态为 clarified
+  ```
+
+  **阻塞条件**: design-issues.md 不存在 或 状态 ∉ {clarified, resolved} → 禁止创建 tasks
+
+  ### 为什么这些检查是强制的？
+
+  mspec 采用"寄生模式"增强 OpenSpec 核心流程：
+  - 不改变 OpenSpec schema（宿主透明）
+  - 通过前置条件检查注入增强逻辑
+  - 目的是捕获需求/设计中的不确定性，避免返工
+
+  如果跳过澄清阶段：
+  - AI 会基于假设进行实现
+  - 假设可能在后续被发现错误
+  - 导致代码返工、设计变更
+  - 违反"理解先于编码"原则
+
+  ## 📚 问题分类学知识库（用于问题发现）
+
+  1. **需求问题分类学**: `openspec/templates/requirement-issue-taxonomy.md`
+     - 6 个维度：功能完整性、数据相关、用户体验、边界异常、集成依赖、优先级
+
+  2. **设计问题分类学**: `openspec/templates/design-issue-taxonomy.md`
+     - 7 个维度：架构决策、技术选型、接口设计、数据状态、安全合规、性能可靠性、部署运维
+
+  ## 🔄 澄清流程状态机
+
+  ```
+  需求澄清: discovering → clarifying → clarified → superseded
+  设计澄清: analyzing → clarifying → clarified → resolved
+  ```
+
+  ## 💬 交互式澄清配置
+
+  - **交互模式**: 批量提问——一次性列出所有 High/Medium 问题，等待用户统一回答
+  - **界面元素**: 编号问题列表，每题附带 2-4 个备选选项说明
+  - **同步策略**: 收到用户完整回答后，统一同步到问题清单（不在每题之后单独同步）
+  - **断点续传**: 支持 'q' 退出保存，下次自动从断点恢复
+  - **进度显示**: 在批量提问标题中显示总题数，如 "需要确认 5 个问题（2 High，3 Medium）"
+  - **操作指令**:
+    - 按编号回答每道题，一次性提交所有答案
+    - 输入 'q' 随时退出，进度将自动保存
+
+  ## 📋 问题清单模板位置
+
+  - 功能点问题清单: `openspec/templates/requirement-issues.md`
+  - 设计问题清单: `openspec/templates/design-issues.md`
+
+  ## ⚠️ 问题严重程度定义
+
+  - 🔴 High: 阻塞性问题，必须澄清后才能继续
+  - 🟡 Medium: 重要问题，建议澄清
+  - 🟢 Low: 建议性问题，可后续补充
+
+  ## 🧬 完整进化体系（v5）
+
+  mspec 的知识积累分为三层，在 archive 时自动推进——**使用越久，整个 spec coding 流程越精准**：
+
+  **Layer A（每次 archive 立即更新）— 项目事实积累**
+  - `openspec/decisions/adr.md`：技术决策账本，防止反复讨论已决定的事
+  - `openspec/glossary.md`：领域词汇表，统一业务术语命名
+  - `openspec/risk-map.md`：风险图谱，记录已知高风险区和 bug 模式
+
+  **Layer B（积累 3+ 复盘后自动触发）— 流程模式学习**
+  - `openspec/templates/`：基于跨 change 漏检/噪音模式优化问题分类学
+  - `openspec/task-patterns/`：按 change 类型积累的任务分解模板库
+  - `openspec/config.yaml` user_preferences：记录用户的稳定决策偏好
+
+  **Layer C（长期积累，元信号）— 系统性洞察**
+  - `openspec/specs/CHANGELOG.md`：规格演化历史，揭示业务边界稳定性
+  - `openspec/metrics.md`：工作流效率信号，支持系统性优化
+
+  **AI 在各阶段如何消费知识库**：
+  - `explore`：读 ADR + Glossary + Risk Map → 引用已有决策、使用正确术语
+  - `propose`：读 Glossary + Task Patterns → Capabilities 命名一致、工作量参考
+  - `specs`：读 Glossary + Spec Changelog → 标准术语写 Scenario、避免历史错误
+  - `design`：读 ADR + Risk Map + Taxonomy → 不重复已决策、优先检查已知风险
+  - `tasks`：读 Task Patterns + Risk Map → 选模板定制、高风险区增加验证步骤
+  - `apply`：读 ADR + Risk Map → 遵循已有决策、高风险区主动预警
+  - `archive`：读取全部 → 更新全部 → 自动触发进化分析
+
+# =============================================================================
+# 阶段规则（与前置检查配合使用）
+# =============================================================================
+
+rules:
+  # ===========================================================================
+  # 阶段 1: 需求澄清 (在 proposal 之前)
+  # ===========================================================================
+  proposal:
+    # 强制前置检查
+    - |
+      ⚠️ 强制性前置检查（MUST 执行）:
+
+      BEFORE creating proposal:
+      1. MUST 检查 spec/requirement-issues.md 是否存在
+      2. MUST 检查状态是否为 clarified
+      3. 如果不满足以上条件，MUST 先执行前置检查 1: 需求澄清流程
+      4. ONLY THEN 创建 proposal
+
+      检查失败时的处理:
+      - 停止 artifacts 创建流程
+      - 启动交互式需求澄清
+      - 等待澄清完成后再继续
+
+    # 引用澄清结果
+    - |
+      创建 proposal 时引用澄清结果：
+      - 在 "Why" 部分说明需求澄清中发现的核心问题和决策
+      - 在 "What Changes" 部分反映澄清后的功能范围
+      - 在 "Capabilities" 部分确保与功能点问题清单中的功能点 ID 一致
+      - 在 "Impact" 部分体现澄清后的约束和依赖
+
+    # 质量门禁
+    - "🚫 禁止跳过: 如果 requirement-issues.md 不存在，禁止创建 proposal"
+    - "🚫 禁止跳过: 如果状态不是 clarified，禁止创建 proposal"
+    - "✅ 必须引用: proposal 中必须提及需求澄清中的关键决策"
+
+  # ===========================================================================
+  # 阶段 2: 需求规格 (specs)
+  # ===========================================================================
+  specs:
+    - |
+      创建 specs 时：
+      1. 参考 requirement-issues.md 中的功能点定义
+      2. 确保每个功能点的规格与澄清结果一致
+      3. 对于需求变更（MODIFIED/REMOVED/RENAMED），在问题清单中记录变更原因
+
+  # ===========================================================================
+  # 阶段 3: 技术方案 (design)
+  # ===========================================================================
+  design:
+    # 设计内容要求
+    - |
+      创建 design.md 时：
+      1. 确保技术决策明确，不回避关键问题
+      2. 每个技术决策必须包含：
+         - 选择了什么方案
+         - 为什么选择这个方案（决策理由）
+         - 考虑过哪些其他方案（备选方案）
+         - 为什么放弃其他方案
+      3. 特别注意 requirement-issues.md 中澄清的约束条件
+
+    # 后置强制检查
+    - |
+      ⚠️ 强制性后置检查（MUST 执行）:
+
+      AFTER creating design.md:
+      1. MUST 检查 spec/design-issues.md 是否存在
+      2. MUST 检查状态是否为 clarified 或 resolved
+      3. 如果不满足以上条件，MUST 先执行前置检查 2: 设计澄清流程
+      4. 根据澄清结果更新 design.md
+      5. ONLY THEN 创建 tasks
+
+    # 质量门禁
+    - "🚫 禁止跳过: 如果 design-issues.md 不存在，禁止创建 tasks"
+    - "🚫 禁止跳过: 如果状态不是 clarified/resloved，禁止创建 tasks"
+
+  # ===========================================================================
+  # 阶段 4: 实施任务 (tasks)
+  # ===========================================================================
+  tasks:
+    # 前置检查（冗余声明，确保不被遗漏）
+    - |
+      ⚠️ 前置检查（再次确认）:
+      BEFORE creating tasks:
+      1. 检查 spec/requirement-issues.md 状态为 clarified ✓
+      2. 检查 spec/design-issues.md 状态为 clarified 或 resolved ✓
+      3. 两个检查都通过后才能创建 tasks
+
+    - |
+      创建 tasks 时：
+      1. 基于最终确定的技术方案创建任务
+      2. 确保任务覆盖 design-issues.md 中所有 🔴 High 严重程度的决策
+      3. 如果设计澄清导致 design.md 重大变更，相应调整任务列表
+      4. 在任务描述中引用相关的设计决策（方便追溯）
+
+  # ===========================================================================
+  # 阶段 5: 实施 (apply)
+  # ===========================================================================
+  apply:
+    - |
+      实施前阅读参考文档：
+      - spec/requirement-issues.md：了解需求澄清中的决策
+      - spec/design-issues.md：了解设计澄清中的决策
+
+    - |
+      实施过程中：
+      1. 严格遵循需求澄清和设计澄清中的决策
+      2. 如果在实施中发现新的问题：
+         - 暂停实施
+         - 评估问题类型（需求问题 / 设计问题）
+         - 更新相应的问题清单
+         - 【可选】启动交互式澄清补充确认
+         - 等待澄清后再继续
+      3. 完成每个任务后立即用 "- [x]" 标记完成
+
+    - |
+      实施完成后的总结：
+      - 对比实际实施与澄清决策的一致性
+      - 记录实施过程中的任何偏差及原因
+      - 归档问题清单作为项目知识资产
+
+    - |
+      实施中的轻量观察（选做，提升复盘质量）：
+      如果在实施过程中遇到以下情况，记录到 spec/retrospective-notes.md：
+      1. "当初澄清没有覆盖，但实际很重要"的问题 → 记录到【需求层面的意外】
+      2. "设计方案不明确，需要临时决策"的问题 → 记录到【设计层面的意外】
+      3. "某个澄清问题明确避免了返工" → 记录到【好的实践】
+      4. 发现高风险代码区域或意外的技术问题 → 记录到【风险事件】
+      这些记录将在归档时自动汇入复盘报告。
+
+  # ===========================================================================
+  # 阶段 6: 归档 (archive) — v5 进化体系
+  # ===========================================================================
+  archive:
+    # ─────────────────────────────────────────────────────────
+    # Step 1：生成复盘报告（MUST，归档前执行）
+    # ─────────────────────────────────────────────────────────
+    - |
+      BEFORE archiving，必须完成以下步骤：
+
+      1. 读取 spec/requirement-issues.md
+      2. 读取 spec/design-issues.md
+      3. 读取 spec/retrospective-notes.md（如存在）
+      4. 读取本次 design.md（用于提取技术决策）
+      5. 读取本次 proposal.md（用于提取新术语）
+      6. 在 openspec/retrospectives/ 目录下创建复盘报告：
+         文件名：{YYYY-MM-DD}-{change-name}.md
+         （目录不存在时先创建）
+      7. 复盘报告必须覆盖以下九个章节：
+
+         # 复盘报告 - {change-name}
+         **变更日期**: {YYYY-MM-DD}
+         **变更类型**: bug-fix / feature-add / refactor / config-update / 其他
+         **复盘状态**: `pending-review`
+
+         ## 一、变更概述
+         - **做了什么**: 简述需求
+         - **实际结果**: 实施了什么，与预期是否一致
+
+         ## 二、需求澄清质量（→ Layer B1 原料）
+         ### 命中的关键问题（避免了返工）
+         | # | 问题 | 维度 | 为什么重要 |
+         ### 无效问题（问了但实际不重要）
+         | # | 问题 | 维度 | 实际影响 |
+         ### 漏检问题（实施中才暴露）
+         | # | 问题 | 建议归入哪个维度 | 重要性 |
+
+         ## 三、设计澄清质量（→ Layer B1 原料）
+         ### 命中的关键决策
+         | # | 问题 | 维度 | 为什么重要 |
+         ### 过度担心的问题（实际无关紧要）
+         | # | 问题 | 维度 | 实际影响 |
+         ### 漏检的设计盲点（实施中才发现）
+         | # | 问题 | 建议归入哪个维度 | 涉及代码区域 |
+
+         ## 四、技术决策（→ Layer A1：ADR 更新原料）
+         | 决策 | 选择了什么 | 为什么 | 考虑过哪些备选 |
+
+         ## 五、领域词汇（→ Layer A2：词汇表更新原料）
+         | 术语 | 定义 | 首次出现场景 |
+
+         ## 六、风险事件（→ Layer A3：风险图谱更新原料）
+         | 事件描述 | 涉及代码区域/模块 | 问题类型 | 是否已在风险图谱中 |
+
+         ## 七、实施观察（来自 retrospective-notes.md）
+         {如有，复制 retrospective-notes.md 内容；无则填"无"}
+
+         ## 八、效率信号（→ Layer C2：指标原料）
+         | 项目 | 值 |
+         | 需求澄清轮次 | |
+         | 设计澄清轮次 | |
+         | apply 暂停次数 | |
+         | 最终任务总数 | |
+
+         ## 九、综合评分
+         | 维度 | 评分（1-5） |
+         | 需求识别准确率 | |
+         | 设计识别准确率 | |
+         | 澄清效率 | |
+         | 实施中意外问题数（越少越好） | |
+
+      8. 向用户展示复盘摘要（5-8 行），然后继续执行归档
+
+    # ─────────────────────────────────────────────────────────
+    # Step 2：Layer A 立即更新（每次 archive 执行）
+    # ─────────────────────────────────────────────────────────
+    - |
+      AFTER archiving，立即更新项目知识库：
+
+      A1. 技术决策账本（ADR）：
+          - 读取复盘报告"四、技术决策"章节
+          - 如有新决策，追加到 openspec/decisions/adr.md
+            格式：## {决策标题} | 来源: {change-name} | 日期: {date}
+                 **选择**: {选了什么}
+                 **理由**: {为什么}
+                 **备选**: {考虑过哪些}
+                 **状态**: active
+          - 如文件不存在，先创建（参考 openspec/templates/adr.md 格式）
+
+      A2. 领域词汇表：
+          - 读取复盘报告"五、领域词汇"章节
+          - 如有新术语，追加到 openspec/glossary.md
+          - 如文件不存在，先创建（参考 openspec/templates/glossary.md 格式）
+
+      A3. 风险图谱：
+          - 读取复盘报告"六、风险事件"章节
+          - 如有新风险事件，追加到 openspec/risk-map.md 的对应分区
+            （"代码热点"或"问题模式"）
+          - 如文件不存在，先创建（参考 openspec/templates/risk-map.md 格式）
+
+      C1. 规格演化日志（如本次有 delta spec sync）：
+          - 将 delta spec 的变更（改了什么 + 为什么）追加到 openspec/specs/CHANGELOG.md
+          - 如文件不存在，先创建并写入标题行
+
+      C2. 效率指标：
+          - 将复盘报告"八、效率信号"的数据追加到 openspec/metrics.md
+            格式：| {date} | {change-name} | {change-type} | {需求澄清轮次} | {设计澄清轮次} | {暂停次数} | {任务数} |
+          - 如文件不存在，先创建并写入表头
+
+    # ─────────────────────────────────────────────────────────
+    # Step 3：Layer B 模式分析（达到阈值时触发，完全自发）
+    # ─────────────────────────────────────────────────────────
+    - |
+      Layer B 进化分析（自发触发）：
+
+      1. 统计 openspec/retrospectives/ 下 pending-review 状态复盘文件数 N
+         （不含 accumulated-insights.md）
+
+      2. 如果 N < 3：
+         提示：「✅ 归档完成，项目知识库已更新。复盘已保存（第 N 个）。
+                还需 {3-N} 个复盘后将自动触发模式分析与进化。」
+         结束。
+
+      3. 如果 N ≥ 3，执行以下进化分析：
+
+         a. 读取所有 pending-review 复盘文件
+
+         b. 分析以下模式（仅当出现 2+ 次视为显著）：
+            - 【B1: 问题分类学】哪些"漏检问题"反复出现？哪些"无效问题"反复出现？
+            - 【B2: 任务模式】同类型 change 的任务结构是否有共性？哪些步骤总被遗漏？
+            - 【B3: 用户偏好】是否发现稳定的决策/交互偏好值得记录到 config.yaml？
+
+         c. 生成/更新 openspec/retrospectives/accumulated-insights.md
+            记录本次分析的发现和具体优化建议
+
+         d. 【强制用户确认】使用 AskUserQuestion 工具，展示进化提案：
+            「🧬 进化分析完成！基于 N 个复盘，发现以下优化机会：
+
+             📚 问题分类学优化（X 条）：
+             1. [新增到需求分类学/边界与异常] "XX" 问题（N 个复盘漏检）
+             2. [从设计分类学删除] "YY" 问题（N 个复盘均标记为噪音）
+             ...
+
+             📋 任务模板优化（Y 条）：
+             1. [新建 feature-add 任务模板]（基于 3 次 feature change 的共性结构）
+             2. [在 bug-fix 模板中增加"回归验证"步骤]（2 次被遗漏）
+             ...
+
+             ⚙️ 偏好/规则优化（Z 条）：
+             1. [建议记录用户偏好] 观察到你通常选择保守技术方案...
+             ...
+
+             是否现在应用以上优化？
+             A) 全部应用
+             B) 部分应用（请说明保留/跳过哪些）
+             C) 暂不应用（下次归档时再次提醒）」
+
+         e. 等待用户回答
+
+         f. 根据用户选择：
+            - A（全部应用）：
+              · 更新 openspec/templates/requirement-issue-taxonomy.md（B1）
+              · 更新 openspec/templates/design-issue-taxonomy.md（B1）
+              · 更新/创建 openspec/task-patterns/ 下对应文件（B2）
+              · 如有偏好建议：更新 openspec/config.yaml 的 user_preferences（B3）
+              · 将已分析复盘文件状态改为 incorporated
+              · 提示：「✅ 进化完成！知识库已更新，下次流程将更精准。」
+
+            - B（部分应用）：
+              · 仅应用用户确认的条目
+              · 未应用条目记入 accumulated-insights.md 的"待定区"
+
+            - C（暂不应用）：
+              · 保持 pending-review，下次归档时重新评估

mspec_cli-5.0.1/src/mspec/templates/glossary.md

@@ -0,0 +1,24 @@
+# 领域词汇表（Domain Glossary）
+
+> **用途**: 项目中稳定使用的业务术语、技术概念的标准定义，以及 Capability 命名规范。
+> **更新时机**: 每次 archive 时，自动从 proposal 的 Capabilities 章节提取新术语追加。
+>
+> **如何消费**:
+> - propose 阶段：Capabilities 命名时复用标准术语保持一致
+> - specs 阶段：Scenario 中使用标准术语，减少歧义
+> - 新成员加入时：快速建立项目语言认知
+
+---
+
+<!-- 格式：
+## {术语}
+
+**定义**: 一句话定义
+**首次出现**: {change-name}（{date}）
+**相关术语**: 与哪些其他术语有关联
+**备注**: 如有歧义或特殊用法说明
+
+---
+-->
+
+*暂无词汇记录。第一次 archive 后将自动填充。*

mspec_cli-5.0.1/src/mspec/templates/retrospective-notes.md

@@ -0,0 +1,40 @@
+# 实施观察笔记
+
+> **用途**: 在实施（apply）阶段记录轻量观察，归档时自动汇入复盘报告。
+> **何时填写**: 当以下情况发生时，随手记录。
+
+---
+
+## 需求层面的意外
+
+> 当初澄清没有覆盖，但实际很重要的问题。
+> 填写格式：描述问题 + 影响
+
+- （无）
+
+---
+
+## 设计层面的意外
+
+> 设计方案不明确，需要临时决策的问题。
+> 填写格式：描述问题 + 临时决策
+
+- （无）
+
+---
+
+## 好的实践
+
+> 某个澄清问题明确避免了返工的情况。
+> 填写格式：哪个问题 + 避免了什么
+
+- （无）
+
+---
+
+## 风险事件
+
+> 发现高风险代码区域或意外的技术问题。
+> 填写格式：描述问题 + 涉及区域/模块
+
+- （无）

mspec_cli-5.0.1/src/mspec/templates/risk-map.md

@@ -0,0 +1,43 @@
+# 风险图谱（Risk Map）
+
+> **用途**: 记录项目中已知的高风险代码区域、高频 bug 模式，以及历史上实际发生的实施问题。
+> **更新时机**: 每次 archive 时，从复盘报告"六、风险事件"章节提取新发现追加。
+>
+> **如何消费**:
+> - design 阶段：优先检查已知风险区域
+> - tasks 阶段：高风险区任务自动细化粒度、增加验证步骤
+> - apply 阶段：进入高风险区时主动预警
+
+---
+
+## 代码热点
+
+> 历史上频繁变更或容易出问题的代码区域。
+
+<!-- 格式：
+### {模块/文件路径}
+
+**风险类型**: 频繁变更 / 并发问题 / 边界复杂 / 依赖脆弱 / 其他
+**历史问题**: 具体描述
+**首次记录**: {change-name}（{date}）
+**注意事项**: 处理时需要特别关注的点
+-->
+
+*暂无记录。第一次 archive 后将自动填充。*
+
+---
+
+## 问题模式
+
+> 在多个 change 中反复出现的问题类型。
+
+<!-- 格式：
+### {问题模式名称}
+
+**描述**: 什么情况下会触发
+**影响范围**: 影响哪些功能/模块
+**出现次数**: N 次（最近一次: {change-name}）
+**预防措施**: 如何在下次避免
+-->
+
+*暂无记录。第一次 archive 后将自动填充。*

{mspec_cli-4.0.14 → mspec_cli-5.0.1/src/mspec_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mspec-cli
-Version: 4.0.14
+Version: 5.0.1
 Summary: mspec-cli（Member Spec）- 会员组规范驱动开发工作流 CLI 工具
 Author-email: shirayner <team@mspec.io>
 License: MIT
@@ -45,7 +45,7 @@ Dynamic: license-file
 
 **mspec-cli**（Member Spec）- 会员组规范驱动开发工作流 CLI 工具
 
-通过交互式命令行澄清机制，实现结构化问题发现与澄清，提升需求明确度和开发效率。
+通过交互式命令行澄清机制，实现结构化问题发现与澄清；通过自发进化体系，使 AI 随着项目积累越来越了解你的项目。
 
 ## 特性
 
@@ -53,6 +53,7 @@ Dynamic: license-file
 - 🔄 **批量式澄清** - 一次性列出所有问题，统一回答，高效不拖沓
 - 💾 **断点续传** - 支持随时中断，下次自动恢复
 - 📚 **结构化问题分类** - 6个需求维度 + 7个设计维度
+- 🧬 **自发进化体系** - 使用越久，整个 spec coding 流程越精准
 - 🎨 **美观界面** - 使用 Rich 库提供彩色终端输出
 
 ## 文档
@@ -197,9 +198,59 @@ mspec doctor
 └─────────────────────────────────────┘
     │
     ▼
-实施 (apply)
+┌─────────────────────────────────────┐
+│  实施 (apply)                        │
+│  - 按任务清单逐步实施                │
+│  - 可选：记录实施中的轻量观察        │
+└─────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  归档 (archive) + 进化               │
+│  - 生成复盘报告（9个维度）           │
+│  - 更新项目知识库（ADR/词汇/风险）   │
+│  - 积累 3 次后自动触发进化分析       │
+└─────────────────────────────────────┘
 ```
 
+## 🧬 进化体系
+
+mspec 内置 3层8维度 的完整进化体系，无需额外命令，每次 archive 自动推进：
+
+### Layer A — 项目事实（每次立即更新）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/decisions/adr.md` | 技术决策账本 | 不重复讨论已决定的事 |
+| `openspec/glossary.md` | 领域词汇表 | 统一业务术语命名 |
+| `openspec/risk-map.md` | 风险图谱 | 已知高风险区和 bug 模式 |
+
+### Layer B — 流程模式（积累 3+ 次后自动触发）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/templates/*.md` | 进化后的问题分类学 | 精准识别项目特有问题 |
+| `openspec/task-patterns/` | 任务模板库 | 按 change 类型分解任务 |
+| `openspec/config.yaml` | 用户偏好档案 | 减少重复对齐 |
+
+### Layer C — 元信号（长期积累）
+
+| 文件 | 内容 | 作用 |
+|------|------|------|
+| `openspec/specs/CHANGELOG.md` | 规格演化日志 | 揭示业务边界稳定性 |
+| `openspec/metrics.md` | 效率信号 | 发现系统性瓶颈 |
+
+### 预期效果
+
+| 时间点 | 效果 |
+|--------|------|
+| 第 1 次 archive | ADR 建立，词汇表开始填充 |
+| 第 3 次 archive | 首次触发进化，分类学开始个性化 |
+| 第 5-10 次 | 澄清轮次减少，apply 意外减少 |
+| 长期（20+次） | 项目知识库完备，AI 越来越了解项目 |
+
+
+
 ## 问题分类学
 
 ### 需求问题 (6个维度)

{mspec_cli-4.0.14 → mspec_cli-5.0.1}/src/mspec_cli.egg-info/SOURCES.txt

@@ -13,11 +13,15 @@ src/mspec/core/__init__.py
 src/mspec/core/config.py
 src/mspec/core/openspec_manager.py
 src/mspec/core/template.py
+src/mspec/templates/adr.md
 src/mspec/templates/config.yaml
 src/mspec/templates/design-issue-taxonomy.md
 src/mspec/templates/design-issues.md
+src/mspec/templates/glossary.md
 src/mspec/templates/requirement-issue-taxonomy.md
 src/mspec/templates/requirement-issues.md
+src/mspec/templates/retrospective-notes.md
+src/mspec/templates/risk-map.md
 src/mspec/utils/__init__.py
 src/mspec/utils/console.py
 src/mspec_cli.egg-info/PKG-INFO

mspec_cli-4.0.14/src/mspec/templates/config.yaml

@@ -1,243 +0,0 @@
-schema: spec-driven
-
-# =============================================================================
-# OpenSpec 工作流增强配置 v4
-# 交互式命令行澄清机制 - 寄生模式
-# =============================================================================
-# ⚠️ 重要：本配置采用"寄生模式"增强 OpenSpec 核心流程
-# 所有增强逻辑通过 context 和 rules 注入，不改变 OpenSpec schema
-# =============================================================================
-
-version: "4.0.0"
-language: zh
-
-# =============================================================================
-# 前置条件检查清单（寄生增强）
-# =============================================================================
-#
-# 以下检查项必须在创建对应 artifact 之前完成。
-# 如果检查不通过，禁止继续。
-#
-context: |
-  ## ⚠️ 强制前置检查清单（不完成禁止继续）
-
-  ### 前置检查 1: 需求澄清
-
-  **检查项**: `spec/requirement-issues.md` 必须存在且状态为 `clarified`
-
-  **检查方法**:
-  1. 检查文件 `openspec/changes/{change-name}/spec/requirement-issues.md` 是否存在
-  2. 检查文件中的状态标记是否为 `clarified`
-
-  **如果不通过，执行以下流程**:
-  ```
-  步骤 1: 读取 openspec/templates/requirement-issue-taxonomy.md
-  步骤 2: 分析需求，识别功能点（Capabilities）
-  步骤 3: 按 6 个维度检查每个功能点的问题
-  步骤 4: 创建 spec/requirement-issues.md，填充发现问题
-  步骤 5: 启动批量澄清（一次性提问）
-         - 将所有 High/Medium 问题组织为编号列表，一次性展示给用户
-         - 格式："需要确认 N 个问题，请一并回答：\n1. [问题]\n   选项：A) ... B) ...\n2. ..."
-         - 等待用户一次性回答所有问题，不要逐题单独提交
-         - 收到完整回答后，统一同步到 requirement-issues.md
-  步骤 6: 确认所有 High 问题已澄清后，更新状态为 clarified
-  ```
-
-  **阻塞条件**: requirement-issues.md 不存在 或 状态 ≠ clarified → 禁止创建 proposal
-
-  ### 前置检查 2: 设计澄清
-
-  **检查项**: `spec/design-issues.md` 必须存在且状态为 `clarified` 或 `resolved`
-
-  **执行时机**: AFTER creating design.md, BEFORE creating tasks
-
-  **如果不通过，执行类似的需求澄清流程**:
-  ```
-  步骤 1: 读取 openspec/templates/design-issue-taxonomy.md
-  步骤 2: 按 7 个维度分析 design.md 的不确定性
-  步骤 3: 创建 spec/design-issues.md
-  步骤 4: 【强制用户确认——无论是否发现问题都必须执行】
-         使用 AskUserQuestion 工具，将分析结果呈现给用户并请求确认：
-         - 如果发现 High/Medium 问题：将所有问题组织为编号列表，一次性展示：
-           格式："需要确认 N 个设计问题，请一并回答：\n1. [问题]\n   选项：A) ... B) ...\n2. ..."
-         - 如果未发现 High/Medium 问题：仍须展示分析摘要并确认：
-           格式："设计分析完成，未发现高优先级问题。主要设计决策摘要如下：\n[列出关键决策]\n请确认以上设计，或提出任何顾虑/补充："
-         - 等待用户回答，不得跳过此步骤
-         - 收到回答后，将用户意见同步到 design-issues.md
-  步骤 5: 根据澄清结果更新 design.md
-  步骤 6: 更新状态为 clarified
-  ```
-
-  **阻塞条件**: design-issues.md 不存在 或 状态 ∉ {clarified, resolved} → 禁止创建 tasks
-
-  ### 为什么这些检查是强制的？
-
-  mspec 采用"寄生模式"增强 OpenSpec 核心流程：
-  - 不改变 OpenSpec schema（宿主透明）
-  - 通过前置条件检查注入增强逻辑
-  - 目的是捕获需求/设计中的不确定性，避免返工
-
-  如果跳过澄清阶段：
-  - AI 会基于假设进行实现
-  - 假设可能在后续被发现错误
-  - 导致代码返工、设计变更
-  - 违反"理解先于编码"原则
-
-  ## 📚 问题分类学知识库（用于问题发现）
-
-  1. **需求问题分类学**: `openspec/templates/requirement-issue-taxonomy.md`
-     - 6 个维度：功能完整性、数据相关、用户体验、边界异常、集成依赖、优先级
-
-  2. **设计问题分类学**: `openspec/templates/design-issue-taxonomy.md`
-     - 7 个维度：架构决策、技术选型、接口设计、数据状态、安全合规、性能可靠性、部署运维
-
-  ## 🔄 澄清流程状态机
-
-  ```
-  需求澄清: discovering → clarifying → clarified → superseded
-  设计澄清: analyzing → clarifying → clarified → resolved
-  ```
-
-  ## 💬 交互式澄清配置
-
-  - **交互模式**: 批量提问——一次性列出所有 High/Medium 问题，等待用户统一回答
-  - **界面元素**: 编号问题列表，每题附带 2-4 个备选选项说明
-  - **同步策略**: 收到用户完整回答后，统一同步到问题清单（不在每题之后单独同步）
-  - **断点续传**: 支持 'q' 退出保存，下次自动从断点恢复
-  - **进度显示**: 在批量提问标题中显示总题数，如 "需要确认 5 个问题（2 High，3 Medium）"
-  - **操作指令**:
-    - 按编号回答每道题，一次性提交所有答案
-    - 输入 'q' 随时退出，进度将自动保存
-
-  ## 📋 问题清单模板位置
-
-  - 功能点问题清单: `openspec/templates/requirement-issues.md`
-  - 设计问题清单: `openspec/templates/design-issues.md`
-
-  ## ⚠️ 问题严重程度定义
-
-  - 🔴 High: 阻塞性问题，必须澄清后才能继续
-  - 🟡 Medium: 重要问题，建议澄清
-  - 🟢 Low: 建议性问题，可后续补充
-
-# =============================================================================
-# 阶段规则（与前置检查配合使用）
-# =============================================================================
-
-rules:
-  # ===========================================================================
-  # 阶段 1: 需求澄清 (在 proposal 之前)
-  # ===========================================================================
-  proposal:
-    # 强制前置检查
-    - |
-      ⚠️ 强制性前置检查（MUST 执行）:
-
-      BEFORE creating proposal:
-      1. MUST 检查 spec/requirement-issues.md 是否存在
-      2. MUST 检查状态是否为 clarified
-      3. 如果不满足以上条件，MUST 先执行前置检查 1: 需求澄清流程
-      4. ONLY THEN 创建 proposal
-
-      检查失败时的处理:
-      - 停止 artifacts 创建流程
-      - 启动交互式需求澄清
-      - 等待澄清完成后再继续
-
-    # 引用澄清结果
-    - |
-      创建 proposal 时引用澄清结果：
-      - 在 "Why" 部分说明需求澄清中发现的核心问题和决策
-      - 在 "What Changes" 部分反映澄清后的功能范围
-      - 在 "Capabilities" 部分确保与功能点问题清单中的功能点 ID 一致
-      - 在 "Impact" 部分体现澄清后的约束和依赖
-
-    # 质量门禁
-    - "🚫 禁止跳过: 如果 requirement-issues.md 不存在，禁止创建 proposal"
-    - "🚫 禁止跳过: 如果状态不是 clarified，禁止创建 proposal"
-    - "✅ 必须引用: proposal 中必须提及需求澄清中的关键决策"
-
-  # ===========================================================================
-  # 阶段 2: 需求规格 (specs)
-  # ===========================================================================
-  specs:
-    - |
-      创建 specs 时：
-      1. 参考 requirement-issues.md 中的功能点定义
-      2. 确保每个功能点的规格与澄清结果一致
-      3. 对于需求变更（MODIFIED/REMOVED/RENAMED），在问题清单中记录变更原因
-
-  # ===========================================================================
-  # 阶段 3: 技术方案 (design)
-  # ===========================================================================
-  design:
-    # 设计内容要求
-    - |
-      创建 design.md 时：
-      1. 确保技术决策明确，不回避关键问题
-      2. 每个技术决策必须包含：
-         - 选择了什么方案
-         - 为什么选择这个方案（决策理由）
-         - 考虑过哪些其他方案（备选方案）
-         - 为什么放弃其他方案
-      3. 特别注意 requirement-issues.md 中澄清的约束条件
-
-    # 后置强制检查
-    - |
-      ⚠️ 强制性后置检查（MUST 执行）:
-
-      AFTER creating design.md:
-      1. MUST 检查 spec/design-issues.md 是否存在
-      2. MUST 检查状态是否为 clarified 或 resolved
-      3. 如果不满足以上条件，MUST 先执行前置检查 2: 设计澄清流程
-      4. 根据澄清结果更新 design.md
-      5. ONLY THEN 创建 tasks
-
-    # 质量门禁
-    - "🚫 禁止跳过: 如果 design-issues.md 不存在，禁止创建 tasks"
-    - "🚫 禁止跳过: 如果状态不是 clarified/resloved，禁止创建 tasks"
-
-  # ===========================================================================
-  # 阶段 4: 实施任务 (tasks)
-  # ===========================================================================
-  tasks:
-    # 前置检查（冗余声明，确保不被遗漏）
-    - |
-      ⚠️ 前置检查（再次确认）:
-      BEFORE creating tasks:
-      1. 检查 spec/requirement-issues.md 状态为 clarified ✓
-      2. 检查 spec/design-issues.md 状态为 clarified 或 resolved ✓
-      3. 两个检查都通过后才能创建 tasks
-
-    - |
-      创建 tasks 时：
-      1. 基于最终确定的技术方案创建任务
-      2. 确保任务覆盖 design-issues.md 中所有 🔴 High 严重程度的决策
-      3. 如果设计澄清导致 design.md 重大变更，相应调整任务列表
-      4. 在任务描述中引用相关的设计决策（方便追溯）
-
-  # ===========================================================================
-  # 阶段 5: 实施 (apply)
-  # ===========================================================================
-  apply:
-    - |
-      实施前阅读参考文档：
-      - spec/requirement-issues.md：了解需求澄清中的决策
-      - spec/design-issues.md：了解设计澄清中的决策
-
-    - |
-      实施过程中：
-      1. 严格遵循需求澄清和设计澄清中的决策
-      2. 如果在实施中发现新的问题：
-         - 暂停实施
-         - 评估问题类型（需求问题 / 设计问题）
-         - 更新相应的问题清单
-         - 【可选】启动交互式澄清补充确认
-         - 等待澄清后再继续
-      3. 完成每个任务后立即用 "- [x]" 标记完成
-
-    - |
-      实施完成后的总结：
-      - 对比实际实施与澄清决策的一致性
-      - 记录实施过程中的任何偏差及原因
-      - 归档问题清单作为项目知识资产