cc-devflow 1.0.1

package/.claude/config/quality-rules.yml

@@ -0,0 +1,161 @@
+# ============================================================================
+# Quality Rules Configuration for /flow-checklist
+# ============================================================================
+# Version: 1.0.0
+# Purpose: Define checklist generation rules, gate thresholds, and quality
+#          dimensions for requirement quality validation.
+# Reference: TECH_DESIGN.md Section 3.2
+# ============================================================================
+
+# ============================================================================
+# Gate Thresholds
+# ============================================================================
+gate:
+  # Minimum completion percentage to pass Epic entry gate (0-100)
+  threshold: 80
+
+  # Allow --skip-gate to bypass gate check
+  allow_skip: true
+
+  # Require --reason when using --skip-gate
+  require_reason: true
+
+# ============================================================================
+# Checklist Types (6 Types - R001 Decision)
+# ============================================================================
+types:
+  ux:
+    name: "UX Requirements"
+    description: "User experience and interface requirements"
+    min_items: 15
+    max_items: 30
+    dimensions:
+      - Completeness
+      - Clarity
+      - Consistency
+      - Measurability
+      - Coverage
+
+  api:
+    name: "API Requirements"
+    description: "API endpoints and data contracts"
+    min_items: 15
+    max_items: 30
+    dimensions:
+      - Completeness
+      - Clarity
+      - Consistency
+      - Measurability
+      - Coverage
+
+  security:
+    name: "Security Requirements"
+    description: "Authentication, authorization, data protection"
+    min_items: 15
+    max_items: 30
+    dimensions:
+      - Completeness
+      - Clarity
+      - Consistency
+      - Measurability
+      - Coverage
+
+  performance:
+    name: "Performance Requirements"
+    description: "Response time, throughput, scalability"
+    min_items: 15
+    max_items: 30
+    dimensions:
+      - Completeness
+      - Clarity
+      - Consistency
+      - Measurability
+      - Coverage
+
+  data:
+    name: "Data Requirements"
+    description: "Data models, storage, validation"
+    min_items: 15
+    max_items: 30
+    dimensions:
+      - Completeness
+      - Clarity
+      - Consistency
+      - Measurability
+      - Coverage
+
+  general:
+    name: "General Requirements"
+    description: "Overall requirement quality"
+    min_items: 15
+    max_items: 30
+    dimensions:
+      - Completeness
+      - Clarity
+      - Consistency
+      - Measurability
+      - Coverage
+
+# ============================================================================
+# Quality Dimensions (5 Dimensions)
+# ============================================================================
+dimensions:
+  Completeness:
+    pattern: "Are .* defined|specified|documented"
+    anti_pattern: "Verify|Test|Check|Confirm"
+
+  Clarity:
+    pattern: "Is .* quantified|clarified with specific"
+    anti_pattern: "works|functions|renders"
+
+  Consistency:
+    pattern: "Are .* consistent between|across"
+    anti_pattern: "correctly|properly"
+
+  Measurability:
+    pattern: "Can .* be objectively measured|verified"
+    anti_pattern: "click|navigate|load"
+
+  Coverage:
+    pattern: "Are .* scenarios|cases addressed"
+    anti_pattern: "displays|shows|returns"
+
+# ============================================================================
+# Anti-Example Rules (R003 Decision)
+# ============================================================================
+# These patterns enforce "Unit Tests for English" - testing requirements
+# quality, NOT testing implementation behavior.
+# ============================================================================
+anti_example:
+  # Prohibited patterns (test implementation, not requirements)
+  prohibited:
+    - "^Verify"
+    - "^Test"
+    - "^Confirm"
+    - "^Check that"
+    - "works correctly"
+    - "functions properly"
+    - "displays correctly"
+    - "click|navigate|render|load|execute"
+
+  # Required patterns (test requirements quality)
+  required:
+    - "Are .* defined"
+    - "Are .* specified"
+    - "Are .* documented"
+    - "Is .* quantified"
+    - "Is .* clarified"
+    - "Can .* be measured"
+
+# ============================================================================
+# Output Formatting
+# ============================================================================
+output:
+  # Checklist item ID format (CHK + 3 digits)
+  id_format: "CHK{:03d}"
+
+  # Minimum dimension coverage (out of 5)
+  min_dimension_coverage: 4
+
+  # Traceability requirement (percentage of items with references)
+  min_traceability: 80

package/.claude/docs/SPEC_KIT_CONSTITUTION_ANALYSIS.md

@@ -0,0 +1,426 @@
+# Spec-Kit Constitution 严格遵守机制深度分析
+
+## 核心发现
+
+Spec-Kit 通过**四层强制机制**确保 Constitution 的严格遵守，而非依赖 AI 的"自觉性"。
+
+---
+
+## 一、Constitution 的核心特性
+
+### 1.1 作为项目DNA (Architectural DNA)
+
+```text
+The constitution acts as the architectural DNA of the system,
+ensuring that every generated implementation maintains
+consistency, simplicity, and quality.
+```
+
+**关键特性**:
+- **不可变性 (Immutable)**: 原则保持恒定，不随时间改变
+- **普遍约束 (Universal Constraints)**: 适用于所有代码生成
+- **架构DNA**: 每次生成都遵循相同的设计基因
+
+### 1.2 九大条款 (Nine Articles)
+
+| Article | 原则 | 强制机制 |
+|---------|------|---------|
+| **I**   | Library-First | 功能必须先作为库存在 |
+| **II**  | CLI Interface | 所有库必须有CLI接口 |
+| **III** | Test-First (NON-NEGOTIABLE) | 测试先于实现，无例外 |
+| **IV**  | Integration Testing | 优先集成测试而非mocks |
+| **V**   | Observability | 文本I/O确保可观测性 |
+| **VI**  | Versioning | 语义化版本控制 |
+| **VII** | Simplicity | ≤3项目，无未来优化 |
+| **VIII**| Anti-Abstraction | 直接用框架，无封装 |
+| **IX**  | Integration-First | 真实环境测试 |
+
+---
+
+## 二、四层强制机制
+
+### Layer 1: 模板硬约束 (Template Hard Constraints)
+
+#### 机制1.1: Phase -1 Gates (预防性闸门)
+
+**位置**: `plan-template.md`
+
+```markdown
+### Phase -1: Pre-Implementation Gates
+
+#### Simplicity Gate (Article VII)
+- [ ] Using ≤3 projects?
+- [ ] No future-proofing?
+
+#### Anti-Abstraction Gate (Article VIII)
+- [ ] Using framework directly?
+- [ ] Single model representation?
+
+#### Integration-First Gate (Article IX)
+- [ ] Contracts defined?
+- [ ] Contract tests written?
+```
+
+**强制原理**:
+- **时机**: 在技术设计**之前**执行，不是事后检查
+- **阻断**: 未通过则无法继续设计
+- **证明**: 违规必须在 Complexity Tracking 表中证明
+
+**效果**: AI 无法"悄悄"添加复杂度，必须明文记录
+
+#### 机制1.2: Complexity Tracking Table (复杂度追踪)
+
+```markdown
+### Complexity Tracking
+
+*Fill ONLY if Constitution Check has violations*
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| 4th project | Frontend + Backend + Mobile + Admin | 3 projects can't serve 4 platforms |
+| Repository Pattern | Need PostgreSQL + MongoDB | Direct ORM couples logic to DB |
+```
+
+**强制原理**:
+- **强制证明**: 不能只说"需要"，必须证明"为什么简单方案不够"
+- **透明度**: 所有复杂度都可见、可追溯
+- **问责制**: 复杂度有明确的负责人和理由
+
+#### 机制1.3: File Creation Order (文件创建顺序)
+
+```markdown
+### File Creation Order
+1. Create `contracts/` with API specifications
+2. Create test files in order: contract → integration → e2e → unit
+3. Create source files to make tests pass
+```
+
+**强制原理**:
+- **顺序约束**: 强制 TDD 顺序，无法跳过
+- **契约优先**: 先定义接口，再实现
+- **测试驱动**: 测试在前，实现在后
+
+### Layer 2: 命令级强制 (Command-Level Enforcement)
+
+#### 机制2.1: /speckit.constitution 命令
+
+**功能**: 创建或更新 Constitution，并自动同步到所有依赖文档
+
+**执行流程**:
+```text
+1. Load existing constitution template
+2. Collect/derive values for placeholders
+3. Draft updated constitution content
+4. Consistency propagation checklist:
+   - Update plan-template.md (Phase -1 Gates)
+   - Update spec-template.md (scope constraints)
+   - Update tasks-template.md (task categories)
+   - Update command files (agent references)
+   - Update runtime guidance docs
+5. Produce Sync Impact Report (HTML comment)
+6. Validation before output:
+   - No unexplained bracket tokens
+   - Principles declarative and testable
+   - Dates ISO format
+7. Write back to constitution.md
+8. Output summary with version bump
+```
+
+**关键机制**:
+- **一致性传播 (Consistency Propagation)**: Constitution 变更自动更新所有模板
+- **影响报告 (Sync Impact Report)**: 明确列出哪些文件需要更新
+- **版本管理 (Versioning)**: 语义化版本号 (MAJOR.MINOR.PATCH)
+
+#### 机制2.2: /speckit.analyze 命令
+
+**功能**: 跨文档一致性和覆盖率分析
+
+**检查项**:
+```text
+- Constitution alignment
+- Spec ↔ Plan consistency
+- Plan ↔ Tasks traceability
+- Test coverage gaps
+- Principle violation detection
+```
+
+### Layer 3: 代理级约束 (Agent-Level Constraints)
+
+#### 机制3.1: 代理指令嵌入 Constitution 引用
+
+**prd-writer 示例**:
+```markdown
+6. **Constitution** (.claude/constitution/):
+   - **Quality First**: Ensure PRD completeness, no partial requirements
+   - **Security First**: Identify and document security requirements
+   - **Architecture Consistency**: Align with existing system architecture
+```
+
+**planner 示例**:
+```markdown
+### Gate Enforcement Sequence
+1. Load PRD: Extract user stories, requirements, constraints
+2. Execute Phase -1 Gates: BEFORE designing architecture
+   - Simplicity Gate (Article VII)
+   - Anti-Abstraction Gate (Article VIII)
+   - Integration-First Gate (Article IX)
+3. Complexity Tracking: Document violations with justification
+4. Proceed ONLY if gates pass or violations justified
+```
+
+**强制原理**:
+- **嵌入指令**: Constitution 原则直接写入代理的系统提示
+- **必须检查**: 代理无法跳过 Constitution 检查
+- **输出格式**: 代理输出必须包含 Constitution Check 章节
+
+#### 机制3.2: 代理输出格式强制
+
+每个代理的输出文档必须包含:
+```markdown
+## Constitution Check
+
+### Simplicity Gate (Article VII)
+- [ ] Using ≤3 projects?
+- [ ] No future-proofing?
+
+### Anti-Abstraction Gate (Article VIII)
+- [ ] Using framework directly?
+- [ ] Single model representation?
+
+### Complexity Tracking
+| Violation | Why Needed | Simpler Alternative Rejected |
+|-----------|------------|------------------------------|
+| ...       | ...        | ...                          |
+```
+
+### Layer 4: 验证脚本 (Validation Scripts)
+
+#### 机制4.1: 自动化Constitution合规检查
+
+**伪代码**:
+```bash
+validate_constitution_compliance() {
+  # 检查 plan.md
+  check_phase_minus_one_gates_exist()
+  check_simplicity_gate_passed()
+  check_anti_abstraction_gate_passed()
+  check_integration_first_gate_passed()
+  check_complexity_tracking_filled_if_violations()
+
+  # 检查 tasks.md
+  check_file_creation_order(contracts_first, tests_before_impl)
+  check_tdd_order(phase2_tests, phase3_impl)
+
+  # 检查代码实现
+  check_test_first_compliance()
+  check_no_hardcoded_secrets()
+  check_resource_cleanup()
+}
+```
+
+---
+
+## 三、强制机制的核心原理
+
+### 3.1 时间线强制 (Timeline Enforcement)
+
+```text
+传统模式: 设计 → 实现 → 事后检查 Constitution (太晚)
+Spec-Kit:  Phase -1 Gates → 设计 → Phase 2 Tests → Phase 3 Impl
+          ↑ 预防性      ↑ 受约束  ↑ 强制TDD    ↑ 让测试通过
+```
+
+**原理**: 在**能够违规之前**就阻止，而非事后检查
+
+### 3.2 证明责任 (Burden of Proof)
+
+```text
+传统模式: 默认允许复杂度，简单度需要证明
+Spec-Kit:  默认简单，复杂度需要证明
+```
+
+**原理**:
+- **Simplicity by Default**: 简单是默认的，复杂需要证明
+- **Explicit Justification**: 所有复杂度都有明确的"为什么"
+- **Alternative Analysis**: 必须说明"为什么简单方案不够"
+
+### 3.3 一致性传播 (Consistency Propagation)
+
+```text
+Constitution 变更
+    ↓
+自动同步到:
+  - plan-template.md (Phase -1 Gates)
+  - spec-template.md (scope constraints)
+  - tasks-template.md (task categories)
+  - 所有代理指令
+  - 验证脚本
+```
+
+**原理**: Constitution 是**单一真相源 (Single Source of Truth)**
+
+### 3.4 分层防御 (Defense in Depth)
+
+```text
+Layer 1: 模板约束 (防止AI生成违规内容)
+    ↓
+Layer 2: 命令强制 (确保一致性传播)
+    ↓
+Layer 3: 代理约束 (嵌入系统提示)
+    ↓
+Layer 4: 验证脚本 (自动化检查)
+```
+
+**原理**: 多层防御，任何一层失效都有后备
+
+---
+
+## 四、与传统方法的对比
+
+| 维度 | 传统Constitution | Spec-Kit Constitution |
+|------|-----------------|----------------------|
+| **执行时机** | 事后检查 | Phase -1 预防 |
+| **强制机制** | 人工审查 | 模板硬约束 |
+| **违规处理** | 警告 | 阻断 + 强制证明 |
+| **一致性** | 手动同步 | 自动传播 |
+| **可追溯性** | 无 | Complexity Tracking |
+| **AI遵守** | 依赖"自觉" | 嵌入指令 + 输出格式 |
+
+---
+
+## 五、关键成功因素
+
+### 5.1 不可变性 (Immutability)
+
+```text
+"While implementation details can evolve,
+ the core principles remain constant."
+```
+
+**原理**:
+- 原则不变 → AI 每次生成都遵循相同规则
+- 应用演进 → 通过 Amendment Process 正式修订
+
+### 5.2 可测试性 (Testability)
+
+所有原则都是**可验证的**:
+- "≤3 projects" - 可数
+- "Tests before implementation" - 可检查文件创建时间
+- "No future-proofing" - 可检查代码中的抽象层
+
+### 5.3 透明度 (Transparency)
+
+所有违规都**可见**:
+- Complexity Tracking 表格
+- Sync Impact Report
+- Phase -1 Gates checklist
+
+### 5.4 问责制 (Accountability)
+
+每个复杂度都有**负责人和理由**:
+```markdown
+| Violation | Why Needed | Simpler Alternative Rejected |
+| 4th project | Need admin panel | Can't reuse frontend for admin |
+```
+
+---
+
+## 六、移植到 CC-DevFlow 的策略
+
+### 6.1 必须保留的机制
+
+1. **Phase -1 Gates** - 已完成 ✅
+2. **Complexity Tracking Table** - 已完成 ✅
+3. **File Creation Order** - 需要添加到 TASKS_TEMPLATE
+4. **Consistency Propagation** - 需要创建 `/flow-constitution` 命令
+5. **Validation Scripts** - 需要扩展 validate-scope-boundary.sh
+
+### 6.2 需要适配的部分
+
+1. **九大条款**:
+   - Spec-Kit 专注于库开发
+   - CC-DevFlow 适用于任意项目
+   - 需要提取通用原则 (Simplicity, Anti-Abstraction, Test-First)
+
+2. **自动化同步**:
+   - Spec-Kit 用 `/speckit.constitution` 命令
+   - CC-DevFlow 创建 `/flow-constitution` 命令
+
+3. **代理嵌入**:
+   - 所有代理指令都引用 Constitution Articles
+   - 输出格式强制包含 Constitution Check
+
+---
+
+## 七、实施优先级
+
+### P0 (立即实施)
+1. ✅ Phase -1 Gates (已完成)
+2. ✅ Complexity Tracking Table (已完成)
+3. 完善 Constitution 文档结构 (Article 编号)
+4. 更新所有模板引用 Articles
+
+### P1 (近期实施)
+5. 创建 `/flow-constitution` 命令
+6. 添加 File Creation Order 约束
+7. 扩展验证脚本检查 Constitution 合规性
+
+### P2 (后续优化)
+8. 自动化一致性传播
+9. Constitution 变更影响分析
+10. Amendment Process 流程化
+
+---
+
+## 八、核心洞察
+
+### 洞察1: Constitution 不是文档，是约束系统
+
+```text
+传统: Constitution = 文档 (建议性)
+Spec-Kit: Constitution = 约束系统 (强制性)
+```
+
+**实现**: 通过模板、命令、代理指令、验证脚本四层强制
+
+### 洞察2: 预防 > 检测 > 修复
+
+```text
+Phase -1 Gates: 在设计前阻止 (预防)
+Complexity Tracking: 强制证明 (检测)
+Validation Scripts: 自动检查 (修复)
+```
+
+**实现**: 时间线上的分层防御
+
+### 洞察3: 简单度需要证明复杂度
+
+```text
+传统: 默认允许复杂，简单需证明
+Spec-Kit: 默认简单，复杂需证明
+```
+
+**实现**: Complexity Tracking 的"为什么简单方案不够"列
+
+### 洞察4: 一致性是自动化的，不是约定
+
+```text
+传统: 人工同步 Constitution 到各文档
+Spec-Kit: Constitution 变更自动传播
+```
+
+**实现**: `/speckit.constitution` 命令的 Consistency Propagation
+
+---
+
+## 九、总结
+
+Spec-Kit 的 Constitution 严格遵守机制的精髓在于:
+
+1. **时机**: Phase -1 Gates 预防性阻止
+2. **证明**: Complexity Tracking 强制证明
+3. **嵌入**: 代理指令直接包含 Constitution
+4. **自动化**: 一致性自动传播，不依赖人工
+5. **透明**: 所有违规可见、可追溯、有理由
+
+这是一个**系统工程**，而非单个文档。