prd-workflow-cli 1.3.4 → 1.4.0

package/docs/RULE-SYSTEM-ROADMAP.md

@@ -0,0 +1,286 @@
+# 规则系统改造路线图
+
+> 创建时间：2024-12-29
+> 目标：让规则从"自然语言"升级为"机器可检验的契约"
+
+---
+
+## 📊 改造进度总览
+
+| 阶段 | 任务数 | 已完成 | 进度 |
+|------|--------|--------|------|
+| P0 - 基础设施 | 3 | 3 | 100% ✅ |
+| P1 - 程序校验 | 6 | 6 | 100% ✅ |
+| P2 - AI 自检强化 | 4 | 4 | 100% ✅ |
+| P3 - 可观测性 | 2 | 2 | 100% ✅ |
+| **合计** | **15** | **15** | **100%** 🎉 |
+
+---
+
+## 🎯 P0 - 基础设施（必须先完成）
+
+### T001 - 创建规则索引文件 `rules/index.json`
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P0
+- **描述**：创建结构化的规则索引，包含 rule_id、scope、severity、validator 等字段
+- **输出物**：`prd-cli/rules/index.json`（37 条规则、12 个校验器、9 个分类）
+- **依赖**：无
+- **工作量**：小
+
+### T002 - 创建 A2UI JSON Schema
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P0
+- **描述**：定义 A2UI 组件的 JSON Schema，用于校验生成的 JSON 结构
+- **输出物**：
+  - `prd-cli/rules/schemas/a2ui.schema.json`（21 种组件类型的完整定义）
+  - `prd-cli/rules/schemas/rules.schema.json`（规则索引 Schema）
+- **依赖**：无
+- **工作量**：中
+
+### T003 - 创建 `prd check` 命令框架
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P0
+- **描述**：新增 CLI 命令 `prd check`，作为规则校验的入口
+- **输出物**：
+  - `prd-cli/commands/check.js`（含 CheckResult 类、3 个校验器）
+  - `bin/prd-cli.js` 已注册命令
+- **依赖**：T001
+- **工作量**：中
+- **已实现校验器**：
+  - `checkFrozenStatus` - 冻结状态检查 (D001-D004)
+  - `checkFlowOrder` - 流程顺序检查 (F001-F003)
+  - `checkA2UIFiles` - A2UI 文件检查 (V003-V006)
+
+---
+
+## 🔧 P1 - 程序校验（核心功能）
+
+### T101 - 实现冻结状态保护 (D001-D004)
+- **状态**：✅ 已完成（已合并到 T003）
+- **完成时间**：2024-12-29
+- **优先级**：P1
+- **描述**：检查 `.prd-config.json` 的冻结状态，对冻结文档的写入进行告警/拦截
+- **覆盖规则**：D001, D002, D003, D004
+- **输出物**：`prd-cli/commands/check.js` 中的 `checkFrozenStatus()` 函数
+- **依赖**：T003
+- **工作量**：小
+
+### T102 - 实现流程顺序检查 (F001-F003)
+- **状态**：✅ 已完成（已合并到 T003）
+- **完成时间**：2024-12-29
+- **优先级**：P1
+- **描述**：检查是否存在必要的前置文档（如 B3 前必须有 R1）
+- **覆盖规则**：F001, F002, F003
+- **输出物**：`prd-cli/commands/check.js` 中的 `checkFlowOrder()` 函数
+- **依赖**：T003
+- **工作量**：中
+
+### T103 - 实现 A2UI 双文件检查 (V004)
+- **状态**：✅ 已完成（已合并到 T003）
+- **完成时间**：2024-12-29
+- **优先级**：P1
+- **描述**：检查 C1_UI原型 目录下 .json 和 .html 是否成对存在
+- **覆盖规则**：V004, V006
+- **输出物**：`prd-cli/commands/check.js` 中的 `checkA2UIFiles()` 函数
+- **依赖**：T003
+- **工作量**：小
+
+### T104 - 实现 A2UI 文件命名检查 (V005)
+- **状态**：✅ 已完成（已合并到 T003）
+- **完成时间**：2024-12-29
+- **优先级**：P1
+- **描述**：检查原型文件名是否符合 `REQ-XXX-名称` 格式
+- **覆盖规则**：V005
+- **输出物**：`prd-cli/commands/check.js` 中的 `checkA2UIFiles()` 函数
+- **依赖**：T003
+- **工作量**：小
+
+### T105 - 实现 A2UI JSON Schema 校验 (V007)
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P1
+- **描述**：使用组件类型白名单校验 A2UI JSON 结构
+- **覆盖规则**：V007
+- **输出物**：`prd-cli/commands/check.js` 中的 `findInvalidComponentTypes()` 函数
+- **依赖**：T002, T003
+- **工作量**：中
+- **实现方式**：递归遍历 JSON，检查所有 `type` 字段是否在白名单内
+
+### T106 - 实现需求范围检查 (S002-S003)
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P1
+- **描述**：对比 C0/C1 需求与 B2/B3 范围，发现超出时告警
+- **覆盖规则**：S002, S003
+- **输出物**：`prd-cli/commands/check.js` 中的 `checkRequirementScope()` 函数
+- **依赖**：T003
+- **工作量**：大
+- **实现方式**：
+  - S002: 检查配置中的批次信息，提醒确保范围正确
+  - S003: 从 B3 提取 REQ-XXX 模式，与 C1 目录文件对比
+
+---
+
+## 🧠 P2 - AI 自检强化
+
+### T201 - 改造 workflow 文件头部，注入规则子集表
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P2
+- **描述**：在每个 workflow 文件开头添加"本阶段必须遵守的规则"表格
+- **覆盖规则**：所有无法程序校验的规则
+- **输出物**：
+  - `prd-cli/scripts/inject-rules.js`（规则注入工具）
+  - 已注入 6 个 workflow 文件
+- **依赖**：T001
+- **工作量**：中
+
+### T202 - 设计强制输出模板（自检清单格式）
+- **状态**：✅ 已完成（合并到 T201）
+- **完成时间**：2024-12-29
+- **优先级**：P2
+- **描述**：定义 AI 在关键节点必须输出的自检清单格式
+- **输出物**：每个 workflow 文件中的“自检清单模板”代码块
+- **依赖**：T201
+- **工作量**：小
+
+### T203 - 更新 `.cursorrules` 和 `.antigravity/rules.md`
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P2
+- **描述**：添加规则系统概述，引用 rules/index.json
+- **输出物**：修改后的规则文件
+- **依赖**：T001, T201
+- **工作量**：中
+
+### T204 - 实现违规信息结构化回喂机制
+- **状态**：✅ 已完成（已在 T003 实现）
+- **完成时间**：2024-12-29
+- **优先级**：P2
+- **描述**：当 `prd check` 发现违规时，输出结构化 JSON 供 AI 读取并修复
+- **输出物**：`prd check --json` 输出格式
+- **依赖**：T003, P1 全部
+- **工作量**：小
+
+---
+
+## 📈 P3 - 可观测性（长期）
+
+### T301 - 实现规则校验日志记录
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P3
+- **描述**：每次 `prd check` 执行后记录日志，便于统计分析
+- **输出物**：
+  - `CheckResult.saveLog()` 方法
+  - 日志文件 `.prd-logs/check-history.json`
+  - `--no-log` 选项
+- **依赖**：P1 全部
+- **工作量**：中
+
+### T302 - 实现规则遗漏统计报告
+- **状态**：✅ 已完成
+- **完成时间**：2024-12-29
+- **优先级**：P3
+- **描述**：基于日志生成统计报告，识别高频遗漏规则
+- **输出物**：
+  - `prd-cli/commands/stats.js`
+  - `prd stats` 命令（包含通过率、高频违规 Top 5、7天趋势）
+- **依赖**：T301
+- **工作量**：中
+
+---
+
+## 📋 完整规则清单索引
+
+### 全局红线 (G)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| G001 | 所有回复必须使用简体中文 | ❌ | T201 |
+| G002 | 禁止未经对话就填充文档 | ❌ | T201 |
+| G003 | 禁止替 PM 做决策 | ❌ | T201 |
+| G004 | 禁止"快速完成"跳过流程 | ❌ | T201 |
+
+### 文档状态 (D)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| D001 | 禁止修改已冻结的 B3 文档 | ✅ | T101 |
+| D002 | 禁止修改已冻结的 C3 文档 | ✅ | T101 |
+| D003 | B3 冻结后禁止修改 B1、B2 | ✅ | T101 |
+| D004 | C3 冻结后禁止修改 C0、C1 | ✅ | T101 |
+| D005 | 状态变更后同步 .prd-config.json | ✅ | T101 |
+
+### 流程顺序 (F)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| F001 | B2 后必须 R1 才能 B3 | ✅ | T102 |
+| F002 | C1 后必须 R2 才能 C3 | ✅ | T102 |
+| F003 | 创建迭代后必须先 R1 启动检查 | ✅ | T102 |
+| F004 | R1 必须有 5 维度分析 | ⚠️ | T102 |
+| F005 | 每批次必须完整 C0→C1→R2→C3 | ⚠️ | T102 |
+
+### 需求范围 (S)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| S001 | C1 禁止加新需求 | ⚠️ | T106 |
+| S002 | C0 只含首批需求 | ✅ | T106 |
+| S003 | C1 需求必须在 B3 范围内 | ✅ | T106 |
+| S004 | 新需求流程：A2→新迭代→B1 | ❌ | T201 |
+
+### A2UI 可视化 (V)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| V001 | 描述系统结构时生成架构图 | ❌ | T201 |
+| V002 | 描述界面时生成原型 | ❌ | T201 |
+| V003 | JSON 必须写入 current.json | ✅ | T103 |
+| V004 | 确认后保存 .json + .html | ✅ | T103 |
+| V005 | 命名规范 REQ-XXX-名称 | ✅ | T104 |
+| V006 | 保存后更新 index.md | ✅ | T103 |
+| V007 | 只使用定义的组件 | ✅ | T105 |
+
+### 分段保存 (I)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| I001 | 确认一个需求立即写入 | ❌ | T201 |
+| I002 | 禁止一次性写入 | ❌ | T201 |
+| I003 | 里程碑保存点 | ❌ | T201 |
+| I004 | 切换主题前保存 | ❌ | T201 |
+
+### 用户角度 (U)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| U001 | B2 必须提 3 个用户质疑 | ❌ | T201 |
+| U002 | C1 必须用户角度审计 | ❌ | T201 |
+| U003 | 禁止不质疑直接记录 | ❌ | T201 |
+
+### 完整性检查 (C)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| C001 | PM 说完成时 5 维度检查 | ❌ | T201 |
+| C002 | 5 维度定义 | - | - |
+| C003 | 禁止不追问遗漏 | ❌ | T201 |
+
+### 工作启动 (W)
+| ID | 描述 | 可程序校验 | 覆盖任务 |
+|----|------|------------|----------|
+| W001 | 开始前查看项目状态 | ❌ | T201 |
+| W002 | 开始前确认冻结状态 | ✅ | T101 |
+
+---
+
+## 📝 变更日志
+
+| 日期 | 变更内容 |
+|------|----------|
+| 2024-12-29 | 创建文档，定义 15 个任务，37 条规则 |
+
+---
+
+## 🚀 下一步
+
+执行顺序：**T001 → T002 → T003 → T101 → T103 → T104 → T105**
+
+确认后开始执行 T001。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prd-workflow-cli",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "产品需求管理规范 CLI 工具 - 基于 A→R→B→C 流程，集成 PM 确认机制和对话归档的需求管理命令行工具",
   "main": "index.js",
   "bin": {
@@ -48,10 +48,12 @@
     "bin/",
     "commands/",
     "scripts/",
+    "rules/",
     "a2ui-viewer/",
     ".agent/",
     ".antigravity/",
     "templates/",
+    "docs/",
     ".cursorrules",
     "README.md",
     "GUIDE.md"