mspec-cli 4.0.1__tar.gz → 4.0.5__tar.gz

{mspec_cli-4.0.1/src/mspec_cli.egg-info → mspec_cli-4.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mspec-cli
-Version: 4.0.1
+Version: 4.0.5
 Summary: mspec-cli - 成员规范驱动开发工作流 CLI 工具
 Author-email: shirayner <team@mspec.io>
 License: MIT
@@ -57,8 +57,29 @@ Dynamic: license-file
 
 ## 文档
 
-- [EVOLUTION.md](docs/EVOLUTION.md) - mspec 演进历程 (v1 → v4)
-- [SPEC-ARCHIVE.md](docs/SPEC-ARCHIVE.md) - 完整技术规范参考
+📚 **[完整文档 →](docs/)**
+
+### 新手入门
+- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
+- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
+- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程
+
+### 完整指南
+- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
+- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
+- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档
+
+### 实战教程
+- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目
+
+### 参考手册
+- [📖 CLI 命令速查](docs/reference/cli-reference.md)
+- [⚙️ 配置参考](docs/reference/config-reference.md)
+- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)
+
+### 其他
+- [❓ 常见问题 (FAQ)](docs/faq.md)
+- [🐛 故障排除](docs/troubleshooting.md)
 
 ## 快速开始
 

{mspec_cli-4.0.1 → mspec_cli-4.0.5}/README.md

@@ -18,8 +18,29 @@
 
 ## 文档
 
-- [EVOLUTION.md](docs/EVOLUTION.md) - mspec 演进历程 (v1 → v4)
-- [SPEC-ARCHIVE.md](docs/SPEC-ARCHIVE.md) - 完整技术规范参考
+📚 **[完整文档 →](docs/)**
+
+### 新手入门
+- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
+- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
+- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程
+
+### 完整指南
+- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
+- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
+- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档
+
+### 实战教程
+- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目
+
+### 参考手册
+- [📖 CLI 命令速查](docs/reference/cli-reference.md)
+- [⚙️ 配置参考](docs/reference/config-reference.md)
+- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)
+
+### 其他
+- [❓ 常见问题 (FAQ)](docs/faq.md)
+- [🐛 故障排除](docs/troubleshooting.md)
 
 ## 快速开始
 

{mspec_cli-4.0.1 → mspec_cli-4.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mspec-cli"
-version = "4.0.1"
+version = "4.0.5"
 description = "mspec-cli - 成员规范驱动开发工作流 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}

{mspec_cli-4.0.1 → mspec_cli-4.0.5}/src/mspec/commands/doctor.py

@@ -9,6 +9,7 @@ import click
 from rich.console import Console
 from rich.table import Table
 
+from mspec.core.openspec_manager import OpenspecManager, OpenspecStatus
 from mspec.utils.console import print_error, print_success, print_warning
 
 console = Console()
@@ -27,6 +28,7 @@ def doctor_cmd() -> None:
 
     checks = [
         ("Python 版本", _check_python_version),
+        ("openspec CLI", _check_openspec_cli),
         ("openspec/ 目录", _check_openspec_dir),
         ("config.yaml", _check_config_file),
         ("模板文件", _check_template_files),
@@ -83,6 +85,27 @@ def _check_python_version() -> dict:
     return {"ok": True, "message": f"{sys.version.split()[0]}"}
 
 
+def _check_openspec_cli() -> dict:
+    """检查 openspec CLI 是否安装"""
+    manager = OpenspecManager()
+    status = manager.check()
+
+    if status == OpenspecStatus.INSTALLED:
+        version = manager.get_version()
+        version_str = f" ({version})" if version else ""
+        return {"ok": True, "message": f"已安装{version_str}"}
+    elif status == OpenspecStatus.NPX_AVAILABLE:
+        return {
+            "ok": True,
+            "message": "未全局安装，但可通过 npx 运行",
+        }
+    else:
+        return {
+            "ok": False,
+            "message": "未安装。运行 `npm install -g @fission-ai/openspec` 安装",
+        }
+
+
 def _check_openspec_dir() -> dict:
     """检查 openspec 目录"""
     if not Path("openspec").exists():

{mspec_cli-4.0.1 → mspec_cli-4.0.5}/src/mspec/commands/init.py

@@ -12,6 +12,7 @@ from rich.panel import Panel
 from rich.table import Table
 
 from mspec.core.config import ConfigManager
+from mspec.core.openspec_manager import OpenspecManager, OpenspecStatus
 from mspec.core.template import TemplateManager
 from mspec.utils.console import print_error, print_success
 
@@ -117,27 +118,67 @@ def init_cmd(
             console.print(f"  [red]• {error}[/red]")
 
 
-def _run_openspec_init(target_path: Path) -> None:
-    """调用 openspec init 初始化 OpenSpec 目录结构"""
-    console.print("\n[dim]正在调用 openspec init...[/dim]")
+def _run_openspec_init(target_path: Path) -> bool:
+    """调用 openspec init 初始化 OpenSpec 目录结构
+
+    支持自动检测 openspec，如未安装则尝试使用 npx 或自动安装
+
+    Args:
+        target_path: 目标目录路径
+
+    Returns:
+        bool: 是否成功调用 openspec init
+    """
+    manager = OpenspecManager()
+
+    # 1. 检查当前状态
+    status = manager.check()
+
+    if status == OpenspecStatus.INSTALLED:
+        console.print("[dim]检测到 openspec 已安装[/dim]")
+    elif status == OpenspecStatus.NPX_AVAILABLE:
+        console.print("[dim]openspec 未全局安装，将使用 npx 运行[/dim]")
+    else:
+        # 检查 npm 是否安装
+        import shutil
+
+        if not shutil.which("npm"):
+            manager.print_npm_not_found_guide()
+            # 询问是否继续（不使用 openspec）
+            continue_anyway = questionary.confirm(
+                "是否继续初始化（跳过 openspec）?", default=True
+            ).ask()
+            return continue_anyway
+
+        console.print("[yellow]openspec 未安装，正在尝试自动安装...[/yellow]")
+        if manager.install():
+            # 重新检测
+            status = manager.check()
+        else:
+            # 安装失败，打印指引
+            manager.print_install_guide()
+            # 询问是否继续（不使用 openspec）
+            continue_anyway = questionary.confirm(
+                "是否继续初始化（跳过 openspec）?", default=True
+            ).ask()
+            return continue_anyway
+
+    # 2. 执行 openspec init
+    console.print("[dim]正在调用 openspec init...[/dim]")
     try:
-        result = subprocess.run(
-            ["openspec", "init"],
-            cwd=str(target_path),
-            capture_output=True,
-            text=True,
-        )
+        result = manager.run(["init"], cwd=target_path)
         if result.returncode == 0:
-            console.print("[dim]openspec init 完成[/dim]")
+            console.print("[green]✓ openspec init 完成[/green]")
+            return True
         else:
-            console.print(
-                f"[yellow]⚠ openspec init 返回非零退出码，继续执行...[/yellow]"
-            )
-    except FileNotFoundError:
-        console.print(
-            "[yellow]⚠ openspec 未安装，跳过 openspec init。"
-            "请手动执行 `openspec init` 以完成完整初始化。[/yellow]"
-        )
+            if result.stderr:
+                console.print(f"[yellow]⚠ openspec init 返回警告: {result.stderr}[/yellow]")
+            else:
+                console.print("[yellow]⚠ openspec init 返回非零退出码，继续执行...[/yellow]")
+            return True  # 仍视为成功，继续执行
+    except Exception as e:
+        console.print(f"[yellow]⚠ openspec init 执行异常: {e}[/yellow]")
+        return True  # 仍视为成功，继续执行
 
 
 def _show_dry_run(files: dict, target_path: Path) -> None:

mspec_cli-4.0.5/src/mspec/core/openspec_manager.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""openspec 管理模块
+
+负责检测、安装和调用 openspec
+"""
+
+import platform
+import shutil
+import subprocess
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+
+console = Console()
+
+
+class OpenspecStatus(Enum):
+    """openspec 状态"""
+
+    INSTALLED = "installed"  # 已全局安装
+    NPX_AVAILABLE = "npx"  # 可通过 npx 运行
+    NOT_FOUND = "not_found"  # 未安装且无法自动安装
+
+
+class OpenspecManager:
+    """openspec 管理器
+
+    负责检测、安装和调用 openspec
+    """
+
+    PACKAGE_NAME = "@fission-ai/openspec"
+
+    def __init__(self):
+        self._status: Optional[OpenspecStatus] = None
+
+    def check(self) -> OpenspecStatus:
+        """检查 openspec 可用状态
+
+        Returns:
+            OpenspecStatus: 当前状态
+        """
+        if self._status is not None:
+            return self._status
+
+        # 1. 检查全局安装
+        # Windows 上优先检查 openspec.cmd，因为 npm 会安装 openspec.cmd
+        if self._is_windows():
+            if shutil.which("openspec.cmd") or shutil.which("openspec"):
+                self._status = OpenspecStatus.INSTALLED
+                return self._status
+        else:
+            if shutil.which("openspec"):
+                self._status = OpenspecStatus.INSTALLED
+                return self._status
+
+        # 2. 检查 npx 是否可用
+        if shutil.which("npx"):
+            self._status = OpenspecStatus.NPX_AVAILABLE
+            return self._status
+
+        self._status = OpenspecStatus.NOT_FOUND
+        return self._status
+
+    def _is_windows(self) -> bool:
+        """检查是否为 Windows 系统"""
+        return platform.system() == "Windows"
+
+    def is_available(self) -> bool:
+        """检查是否可用（已安装或可通过 npx 运行）"""
+        return self.check() != OpenspecStatus.NOT_FOUND
+
+    def _get_openspec_cmd(self) -> List[str]:
+        """获取正确的 openspec 命令
+
+        在 Windows 上，npm 会安装三个文件：
+        - openspec (无扩展名的 shell script，Unix 兼容)
+        - openspec.cmd (Windows batch 文件)
+        - openspec.ps1 (PowerShell 脚本)
+
+        Windows 无法直接执行无扩展名的 shell script，
+        所以需要优先使用 .cmd 版本。
+
+        Returns:
+            List[str]: 命令列表，如 ["openspec"] 或 ["openspec.cmd"]
+        """
+        # Windows 优先使用 openspec.cmd
+        if self._is_windows():
+            # 先尝试直接找 openspec.cmd
+            cmd_path = shutil.which("openspec.cmd")
+            if cmd_path:
+                return [cmd_path]
+
+            # 如果没找到，但找到了 openspec（无扩展名），
+            # 尝试在同一目录下找 openspec.cmd
+            openspec_path = shutil.which("openspec")
+            if openspec_path:
+                # 构建 openspec.cmd 的完整路径
+                base_path = openspec_path.replace("/openspec", "/openspec.cmd")
+                base_path = base_path.replace("\\openspec", "\\openspec.cmd")
+                if Path(base_path).exists():
+                    return [base_path]
+
+        # 非 Windows 或找不到 .cmd，使用默认命令
+        openspec_path = shutil.which("openspec")
+        if openspec_path:
+            return [openspec_path]
+
+        return ["openspec"]
+
+    def run(self, args: list, cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+        """运行 openspec 命令
+
+        Args:
+            args: 命令参数
+            cwd: 工作目录
+
+        Returns:
+            subprocess.CompletedProcess: 执行结果
+
+        Raises:
+            RuntimeError: 当 openspec 不可用时
+        """
+        status = self.check()
+
+        if status == OpenspecStatus.INSTALLED:
+            cmd = self._get_openspec_cmd() + args
+        elif status == OpenspecStatus.NPX_AVAILABLE:
+            cmd = ["npx", self.PACKAGE_NAME] + args
+        else:
+            raise RuntimeError("openspec 不可用")
+
+        return subprocess.run(
+            cmd,
+            cwd=str(cwd) if cwd else None,
+            capture_output=True,
+            text=True,
+        )
+
+    def install(self, global_install: bool = True) -> bool:
+        """安装 openspec
+
+        Args:
+            global_install: 是否全局安装
+
+        Returns:
+            bool: 是否安装成功
+        """
+        if not shutil.which("npm"):
+            console.print("[red]✗ npm 未安装，无法自动安装 openspec[/red]")
+            return False
+
+        try:
+            cmd = ["npm", "install"]
+            if global_install:
+                cmd.append("-g")
+            cmd.append(self.PACKAGE_NAME)
+
+            console.print(f"[dim]正在执行: {' '.join(cmd)}[/dim]")
+
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=180,  # 3分钟超时
+            )
+
+            if result.returncode == 0:
+                # 清除缓存，重新检测
+                self._status = None
+                console.print("[green]✓ openspec 安装成功[/green]")
+                return True
+            else:
+                # 检查是否是权限问题
+                if "EACCES" in result.stderr or "permission" in result.stderr.lower():
+                    console.print("[yellow]⚠ 权限不足，无法全局安装[/yellow]")
+                else:
+                    console.print(f"[red]✗ 安装失败: {result.stderr}[/red]")
+                return False
+
+        except subprocess.TimeoutExpired:
+            console.print("[red]✗ 安装超时[/red]")
+            return False
+        except Exception as e:
+            console.print(f"[red]✗ 安装出错: {e}[/red]")
+            return False
+
+    def print_install_guide(self):
+        """打印安装指引"""
+        console.print("\n[bold yellow]⚠ openspec 未安装[/bold yellow]")
+        console.print("\n请执行以下命令安装:")
+        console.print(f"  [cyan]npm install -g {self.PACKAGE_NAME}[/cyan]")
+        console.print("\n[dim]如果权限不足，请尝试:[/dim]")
+        console.print(f"  [cyan]sudo npm install -g {self.PACKAGE_NAME}[/cyan]")
+        console.print("\n或使用 npx（无需安装）:")
+        console.print(f"  [cyan]npx {self.PACKAGE_NAME} init[/cyan]")
+
+    def print_npm_not_found_guide(self):
+        """打印 npm 未安装的指引"""
+        console.print("\n[bold red]✗ npm 未安装[/bold red]")
+        console.print("\n[yellow]openspec 需要 Node.js 环境，请安装 Node.js:[/yellow]")
+        console.print("  https://nodejs.org/")
+        console.print("\n[dim]安装后请重新运行 mspec init[/dim]")
+
+    def print_permission_guide(self):
+        """打印权限问题的解决指引"""
+        console.print("\n[yellow]⚠ npm 全局安装权限不足[/yellow]")
+        console.print("\n解决方案 1 - 使用 npx（推荐，无需安装）:")
+        console.print(f"  [cyan]npx {self.PACKAGE_NAME} init[/cyan]")
+        console.print("\n解决方案 2 - 修改 npm 权限:")
+        console.print("  https://docs.npmjs.com/resolving-eacces-permissions-errors")
+        console.print("\n解决方案 3 - 使用 sudo:")
+        console.print(f"  [cyan]sudo npm install -g {self.PACKAGE_NAME}[/cyan]")
+
+    def get_version(self) -> Optional[str]:
+        """获取 openspec 版本
+
+        Returns:
+            Optional[str]: 版本号，如果未安装则返回 None
+        """
+        if not self.is_available():
+            return None
+
+        try:
+            result = self.run(["--version"])
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception:
+            pass
+
+        return None

{mspec_cli-4.0.1 → mspec_cli-4.0.5}/src/mspec/templates/config.yaml

@@ -2,16 +2,82 @@ schema: spec-driven
 
 # =============================================================================
 # OpenSpec 工作流增强配置 v4
-# 交互式命令行澄清机制
+# 交互式命令行澄清机制 - 寄生模式
+# =============================================================================
+# ⚠️ 重要：本配置采用"寄生模式"增强 OpenSpec 核心流程
+# 所有增强逻辑通过 context 和 rules 注入，不改变 OpenSpec schema
 # =============================================================================
 
 version: "4.0.0"
 language: zh
 
+# =============================================================================
+# 前置条件检查清单（寄生增强）
+# =============================================================================
+#
+# 以下检查项必须在创建对应 artifact 之前完成。
+# 如果检查不通过，禁止继续。
+#
 context: |
-  ## OpenSpec v4 工作流配置 - 交互式命令行澄清
+  ## ⚠️ 强制前置检查清单（不完成禁止继续）
+
+  ### 前置检查 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 问题逐个询问
+         - 每题提供 2-4 个选项 + 自定义输入
+         - 用户回答后立即同步到 requirement-issues.md
+         - 显示进度 "问题 3/10"
+         - 支持 'q' 退出保存，'s' 跳过 Low 问题
+  步骤 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: 交互式澄清（一问一答）
+  步骤 5: 根据澄清结果更新 design.md
+  步骤 6: 更新状态为 clarified
+  ```
+
+  **阻塞条件**: design-issues.md 不存在 或 状态 ∉ {clarified, resolved} → 禁止创建 tasks
+
+  ### 为什么这些检查是强制的？
+
+  mspec 采用"寄生模式"增强 OpenSpec 核心流程：
+  - 不改变 OpenSpec schema（宿主透明）
+  - 通过前置条件检查注入增强逻辑
+  - 目的是捕获需求/设计中的不确定性，避免返工
+
+  如果跳过澄清阶段：
+  - AI 会基于假设进行实现
+  - 假设可能在后续被发现错误
+  - 导致代码返工、设计变更
+  - 违反"理解先于编码"原则
+
+  ## 📚 问题分类学知识库（用于问题发现）
 
   1. **需求问题分类学**: `openspec/templates/requirement-issue-taxonomy.md`
      - 6 个维度：功能完整性、数据相关、用户体验、边界异常、集成依赖、优先级
@@ -19,14 +85,14 @@ context: |
   2. **设计问题分类学**: `openspec/templates/design-issue-taxonomy.md`
      - 7 个维度：架构决策、技术选型、接口设计、数据状态、安全合规、性能可靠性、部署运维
 
-  ### 🔄 澄清流程
+  ## 🔄 澄清流程状态机
 
   ```
   需求澄清: discovering → clarifying → clarified → superseded
   设计澄清: analyzing → clarifying → clarified → resolved
   ```
 
-  ### 💬 交互式澄清配置
+  ## 💬 交互式澄清配置
 
   - **交互模式**: 一问一答的引导式交互
   - **界面元素**: 问题描述 + 2-4个备选选项 + 自定义输入
@@ -38,43 +104,40 @@ context: |
     - 输入 'q' 随时退出，进度将自动保存
     - 输入 's' 跳过当前问题（仅 Low 优先级）
 
-  ### 📋 问题清单模板
+  ## 📋 问题清单模板位置
 
   - 功能点问题清单: `openspec/templates/requirement-issues.md`
   - 设计问题清单: `openspec/templates/design-issues.md`
 
-  ### ⚠️ 问题严重程度
+  ## ⚠️ 问题严重程度定义
 
   - 🔴 High: 阻塞性问题，必须澄清后才能继续
   - 🟡 Medium: 重要问题，建议澄清
   - 🟢 Low: 建议性问题，可后续补充
 
+# =============================================================================
+# 阶段规则（与前置检查配合使用）
+# =============================================================================
+
 rules:
   # ===========================================================================
   # 阶段 1: 需求澄清 (在 proposal 之前)
   # ===========================================================================
   proposal:
-    # 前置：交互式需求问题澄清
+    # 强制前置检查
     - |
+      ⚠️ 强制性前置检查（MUST 执行）:
+
       BEFORE creating proposal:
-      1. 读取 openspec/templates/requirement-issue-taxonomy.md
-      2. 提取需求中的功能点（对应 OpenSpec Capabilities）
-      3. 按功能点维度，使用分类学检查每个维度的潜在问题
-      4. 创建/更新 spec/requirement-issues.md
-         - 按功能点组织
-         - 每个功能点下按 6 个分类维度列出问题
-         - 标记严重程度（High/Medium/Low）
-         - 初始状态为 discovering
-      5. 【交互式澄清】启动命令行交互界面：
-         - 展示 High 和 Medium 问题，一问一答
-         - 每个问题提供 2-4 个预设选项 + 自定义输入
-         - 用户选择/输入后确认，立即同步到问题清单
-         - 显示进度 "问题 3/10"
-         - 支持 'q' 退出保存，下次自动恢复；'s' 跳过 Low 问题
-      6. 迭代检查：澄清后是否暴露新问题？
-         - 如果有新问题，更新清单并继续澄清
-         - 如果没有新问题，将状态设为 clarified
-      7. 只有在 requirement-issues.md 状态为 clarified 后才创建 proposal
+      1. MUST 检查 spec/requirement-issues.md 是否存在
+      2. MUST 检查状态是否为 clarified
+      3. 如果不满足以上条件，MUST 先执行前置检查 1: 需求澄清流程
+      4. ONLY THEN 创建 proposal
+
+      检查失败时的处理:
+      - 停止 artifacts 创建流程
+      - 启动交互式需求澄清
+      - 等待澄清完成后再继续
 
     # 引用澄清结果
     - |
@@ -84,10 +147,10 @@ rules:
       - 在 "Capabilities" 部分确保与功能点问题清单中的功能点 ID 一致
       - 在 "Impact" 部分体现澄清后的约束和依赖
 
-    # 质量要求
-    - "proposal 中引用的所有功能点必须在 requirement-issues.md 中有对应条目"
-    - "确保所有 🔴 High 严重程度的问题都已澄清"
-    - "对于 Clarifications 中记录的决策，在 proposal 中明确引用"
+    # 质量门禁
+    - "🚫 禁止跳过: 如果 requirement-issues.md 不存在，禁止创建 proposal"
+    - "🚫 禁止跳过: 如果状态不是 clarified，禁止创建 proposal"
+    - "✅ 必须引用: proposal 中必须提及需求澄清中的关键决策"
 
   # ===========================================================================
   # 阶段 2: 需求规格 (specs)
@@ -114,45 +177,33 @@ rules:
          - 为什么放弃其他方案
       3. 特别注意 requirement-issues.md 中澄清的约束条件
 
-    # 后置：交互式设计问题澄清
+    # 后置强制检查
     - |
+      ⚠️ 强制性后置检查（MUST 执行）:
+
       AFTER creating design.md:
-      1. 读取 openspec/templates/design-issue-taxonomy.md
-      2. 按设计维度（7 个维度）分析技术方案中的不确定性
-      3. 创建/更新 spec/design-issues.md
-         - 按设计维度组织（架构决策、技术选型...）
-         - 每个维度下列出具体问题
-         - 标记严重程度（High/Medium/Low）
-         - 初始状态为 analyzing
-      4. 【交互式澄清】启动命令行交互界面：
-         - 展示 High 和 Medium 设计问题，一问一答
-         - 每个问题提供 2-4 个预设选项 + 自定义输入
-         - 用户选择/输入后确认，立即同步到问题清单
-         - 显示进度 "问题 3/10"
-         - 支持 'q' 退出保存，下次自动恢复；'s' 跳过 Low 问题
-      5. 根据澄清结果更新 design.md
-         - 修改设计方案以反映澄清后的决策
-         - 在 design.md 中记录设计变更历史
-      6. 迭代检查：设计变更是否引入新问题？
-         - 如果有新问题，更新 design-issues.md 并继续澄清
-         - 如果没有新问题，将状态设为 clarified
-      7. 只有在 design-issues.md 状态为 clarified 或 resolved 后才创建 tasks
+      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/design-issues.md 是否存在
-      2. 验证状态为 clarified 或 resolved
-      3. 确认 design.md 已根据澄清更新
-      4. 如果 design-issues.md 不存在或状态不对：
-         - 触发设计问题发现流程
-         - 等待澄清完成后再继续
-
-    # 任务内容
+      1. 检查 spec/requirement-issues.md 状态为 clarified ✓
+      2. 检查 spec/design-issues.md 状态为 clarified 或 resolved ✓
+      3. 两个检查都通过后才能创建 tasks
+
     - |
       创建 tasks 时：
       1. 基于最终确定的技术方案创建任务

{mspec_cli-4.0.1 → mspec_cli-4.0.5/src/mspec_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mspec-cli
-Version: 4.0.1
+Version: 4.0.5
 Summary: mspec-cli - 成员规范驱动开发工作流 CLI 工具
 Author-email: shirayner <team@mspec.io>
 License: MIT
@@ -57,8 +57,29 @@ Dynamic: license-file
 
 ## 文档
 
-- [EVOLUTION.md](docs/EVOLUTION.md) - mspec 演进历程 (v1 → v4)
-- [SPEC-ARCHIVE.md](docs/SPEC-ARCHIVE.md) - 完整技术规范参考
+📚 **[完整文档 →](docs/)**
+
+### 新手入门
+- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
+- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
+- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程
+
+### 完整指南
+- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
+- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
+- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档
+
+### 实战教程
+- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目
+
+### 参考手册
+- [📖 CLI 命令速查](docs/reference/cli-reference.md)
+- [⚙️ 配置参考](docs/reference/config-reference.md)
+- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)
+
+### 其他
+- [❓ 常见问题 (FAQ)](docs/faq.md)
+- [🐛 故障排除](docs/troubleshooting.md)
 
 ## 快速开始
 

{mspec_cli-4.0.1 → mspec_cli-4.0.5}/src/mspec_cli.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/mspec/commands/init.py
 src/mspec/commands/update.py
 src/mspec/core/__init__.py
 src/mspec/core/config.py
+src/mspec/core/openspec_manager.py
 src/mspec/core/template.py
 src/mspec/templates/config.yaml
 src/mspec/templates/design-issue-taxonomy.md