kiro-spec-engine 1.2.3 → 1.3.0

package/template/.kiro/tools/quality_gate_enforcer.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""
+Quality Gate Enforcer - 质量门控组件
+
+负责在 Spec 创建工作流中强制执行质量标准
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+from ultrawork_enhancer_v3 import UltraworkEnhancerV3, EnhancementResult
+
+
+@dataclass
+class GateResult:
+    """质量门结果"""
+    passed: bool
+    score: float
+    threshold: float
+    enhancement_result: Optional[EnhancementResult] = None
+    message: str = ""
+
+
+class QualityGateEnforcer:
+    """
+    质量门控器 - 强制执行质量标准
+    
+    集成到 Spec 创建工作流，确保文档达到质量阈值
+    """
+    
+    def __init__(self, 
+                 requirements_threshold: float = 9.0,
+                 design_threshold: float = 9.0,
+                 tasks_threshold: float = 8.0):
+        """
+        初始化质量门控器
+        
+        Args:
+            requirements_threshold: Requirements 质量阈值
+            design_threshold: Design 质量阈值
+            tasks_threshold: Tasks 质量阈值
+        """
+        self.requirements_threshold = requirements_threshold
+        self.design_threshold = design_threshold
+        self.tasks_threshold = tasks_threshold
+        
+        # 创建增强器实例
+        self.enhancer = UltraworkEnhancerV3(
+            quality_threshold=requirements_threshold,
+            max_iterations=10,
+            plateau_iterations=3,
+            create_backups=True,
+            cleanup_backups_on_success=True
+        )
+    
+    def check_requirements_gate(self, requirements_path: str) -> GateResult:
+        """
+        检查 Requirements 质量门
+        
+        Args:
+            requirements_path: Requirements 文档路径
+        
+        Returns:
+            GateResult: 质量门结果
+        """
+        print(f"\n{'='*60}")
+        print(f"Quality Gate: Requirements")
+        print(f"Threshold: {self.requirements_threshold}/10")
+        print(f"{'='*60}\n")
+        
+        # 设置阈值
+        self.enhancer.set_quality_threshold(self.requirements_threshold)
+        
+        # 执行增强
+        result = self.enhancer.enhance_requirements_quality(requirements_path)
+        
+        # 检查是否通过
+        passed = result.final_score >= self.requirements_threshold
+        
+        if passed:
+            message = f"✓ Requirements quality gate PASSED ({result.final_score:.2f}/{self.requirements_threshold})"
+        else:
+            message = f"✗ Requirements quality gate FAILED ({result.final_score:.2f}/{self.requirements_threshold})"
+        
+        print(f"\n{message}\n")
+        
+        return GateResult(
+            passed=passed,
+            score=result.final_score,
+            threshold=self.requirements_threshold,
+            enhancement_result=result,
+            message=message
+        )
+    
+    def check_design_gate(self, design_path: str, requirements_path: str) -> GateResult:
+        """
+        检查 Design 质量门
+        
+        Args:
+            design_path: Design 文档路径
+            requirements_path: Requirements 文档路径
+        
+        Returns:
+            GateResult: 质量门结果
+        """
+        print(f"\n{'='*60}")
+        print(f"Quality Gate: Design")
+        print(f"Threshold: {self.design_threshold}/10")
+        print(f"{'='*60}\n")
+        
+        # 设置阈值
+        self.enhancer.set_quality_threshold(self.design_threshold)
+        
+        # 执行增强
+        result = self.enhancer.enhance_design_completeness(design_path, requirements_path)
+        
+        # 检查是否通过
+        passed = result.final_score >= self.design_threshold
+        
+        if passed:
+            message = f"✓ Design quality gate PASSED ({result.final_score:.2f}/{self.design_threshold})"
+        else:
+            message = f"✗ Design quality gate FAILED ({result.final_score:.2f}/{self.design_threshold})"
+        
+        print(f"\n{message}\n")
+        
+        return GateResult(
+            passed=passed,
+            score=result.final_score,
+            threshold=self.design_threshold,
+            enhancement_result=result,
+            message=message
+        )
+    
+    def check_tasks_gate(self, tasks_path: str) -> GateResult:
+        """
+        检查 Tasks 质量门
+        
+        Args:
+            tasks_path: Tasks 文档路径
+        
+        Returns:
+            GateResult: 质量门结果
+        """
+        print(f"\n{'='*60}")
+        print(f"Quality Gate: Tasks")
+        print(f"Threshold: {self.tasks_threshold}/10")
+        print(f"{'='*60}\n")
+        
+        # 执行验证
+        result = self.enhancer.validate_tasks_completeness(tasks_path)
+        
+        # 检查是否通过
+        passed = result.final_score >= self.tasks_threshold
+        
+        if passed:
+            message = f"✓ Tasks quality gate PASSED ({result.final_score:.2f}/{self.tasks_threshold})"
+        else:
+            message = f"✗ Tasks quality gate FAILED ({result.final_score:.2f}/{self.tasks_threshold})"
+        
+        print(f"\n{message}\n")
+        
+        return GateResult(
+            passed=passed,
+            score=result.final_score,
+            threshold=self.tasks_threshold,
+            enhancement_result=result,
+            message=message
+        )
+
+
+def main():
+    """命令行入口"""
+    import sys
+    
+    if len(sys.argv) < 3:
+        print("Usage: python quality_gate_enforcer.py <gate> <path> [requirements_path]")
+        print("Gates:")
+        print("  requirements <path>              - Check requirements quality gate")
+        print("  design <path> <requirements>     - Check design quality gate")
+        print("  tasks <path>                     - Check tasks quality gate")
+        sys.exit(1)
+    
+    gate = sys.argv[1]
+    path = sys.argv[2]
+    
+    enforcer = QualityGateEnforcer()
+    
+    if gate == 'requirements':
+        result = enforcer.check_requirements_gate(path)
+    elif gate == 'design':
+        if len(sys.argv) < 4:
+            print("Error: design gate requires requirements path")
+            sys.exit(1)
+        requirements_path = sys.argv[3]
+        result = enforcer.check_design_gate(path, requirements_path)
+    elif gate == 'tasks':
+        result = enforcer.check_tasks_gate(path)
+    else:
+        print(f"Error: Unknown gate '{gate}'")
+        sys.exit(1)
+    
+    # 返回退出码：0 = 通过，1 = 失败
+    sys.exit(0 if result.passed else 1)
+
+
+if __name__ == '__main__':
+    main()

package/template/.kiro/tools/quality_scorer.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""
+Quality Scorer - 质量评分组件
+
+负责计算文档质量分数，提供加权评分算法和详细评分分解
+"""
+
+from typing import Dict, Optional
+from dataclasses import dataclass, field
+from document_evaluator import DocumentEvaluator, QualityAssessment
+
+
+@dataclass
+class CriterionScore:
+    """单项评分标准"""
+    name: str
+    score: float  # 0-10
+    weight: float  # 0-1
+    weighted_score: float  # score * weight
+    max_score: float = 10.0
+    description: str = ""
+
+
+@dataclass
+class ScoringResult:
+    """评分结果"""
+    total_score: float  # 0-10
+    criterion_scores: Dict[str, CriterionScore] = field(default_factory=dict)
+    language: str = 'en'
+    scoring_breakdown: str = ""
+    assessment: Optional[QualityAssessment] = None
+
+
+class QualityScorer:
+    """
+    质量评分器 - 计算文档质量分数
+    
+    支持加权评分算法和详细评分分解
+    """
+    
+    # 默认权重配置
+    DEFAULT_REQUIREMENTS_WEIGHTS = {
+        'structure': 0.20,  # 20%
+        'ears_format': 0.20,  # 20%
+        'user_stories': 0.20,  # 20%
+        'acceptance_criteria': 0.20,  # 20%
+        'nfr_coverage': 0.10,  # 10%
+        'constraints': 0.10  # 10%
+    }
+    
+    DEFAULT_DESIGN_WEIGHTS = {
+        'structure': 0.25,  # 25%
+        'traceability': 0.20,  # 20%
+        'component_detail': 0.20,  # 20%
+        'diagrams': 0.15,  # 15%
+        'technology': 0.10,  # 10%
+        'nfr_design': 0.05,  # 5%
+        'interfaces': 0.05  # 5%
+    }
+    
+    def __init__(self):
+        self.evaluator = DocumentEvaluator()
+        self.requirements_weights = self.DEFAULT_REQUIREMENTS_WEIGHTS.copy()
+        self.design_weights = self.DEFAULT_DESIGN_WEIGHTS.copy()
+    
+    def configure_weights(self, weights: Dict[str, float]):
+        """
+        配置评分标准权重
+        
+        Args:
+            weights: 权重字典，格式为 {'criterion_name': weight}
+        """
+        # 验证权重总和为 1.0
+        total_weight = sum(weights.values())
+        if abs(total_weight - 1.0) > 0.01:
+            raise ValueError(f"Weights must sum to 1.0, got {total_weight}")
+        
+        # 更新权重
+        for criterion, weight in weights.items():
+            if criterion in self.requirements_weights:
+                self.requirements_weights[criterion] = weight
+            elif criterion in self.design_weights:
+                self.design_weights[criterion] = weight
+    
+    def score_requirements(self, content: str, language: Optional[str] = None) -> ScoringResult:
+        """
+        计算 Requirements 文档质量分数
+        
+        Args:
+            content: 文档内容
+            language: 语言 ('zh' 或 'en')，None 则自动检测
+        
+        Returns:
+            ScoringResult: 评分结果
+        """
+        # 使用 DocumentEvaluator 进行评估
+        assessment = self.evaluator.assess_requirements_quality(content, language)
+        
+        # 计算加权分数
+        criterion_scores = {}
+        total_score = 0.0
+        
+        for criterion, weight in self.requirements_weights.items():
+            raw_score = assessment.criteria_scores.get(criterion, 0.0)
+            weighted_score = raw_score * weight * 10.0  # 转换为 0-10 分制
+            
+            criterion_scores[criterion] = CriterionScore(
+                name=criterion,
+                score=raw_score * 10.0,  # 原始分数（0-10）
+                weight=weight,
+                weighted_score=weighted_score,
+                description=self._get_criterion_description(criterion, assessment.language)
+            )
+            
+            total_score += weighted_score
+        
+        # 生成评分分解说明
+        breakdown = self._generate_requirements_breakdown(
+            criterion_scores, 
+            total_score, 
+            assessment
+        )
+        
+        return ScoringResult(
+            total_score=min(total_score, 10.0),
+            criterion_scores=criterion_scores,
+            language=assessment.language,
+            scoring_breakdown=breakdown,
+            assessment=assessment
+        )
+    
+    def score_design(self, design_content: str, requirements_content: str, language: Optional[str] = None) -> ScoringResult:
+        """
+        计算 Design 文档质量分数
+        
+        Args:
+            design_content: 设计文档内容
+            requirements_content: 需求文档内容
+            language: 语言 ('zh' 或 'en')，None 则自动检测
+        
+        Returns:
+            ScoringResult: 评分结果
+        """
+        # 使用 DocumentEvaluator 进行评估
+        assessment = self.evaluator.assess_design_quality(
+            design_content, 
+            requirements_content, 
+            language
+        )
+        
+        # 计算加权分数
+        criterion_scores = {}
+        total_score = 0.0
+        
+        for criterion, weight in self.design_weights.items():
+            raw_score = assessment.criteria_scores.get(criterion, 0.0)
+            weighted_score = raw_score * weight * 10.0  # 转换为 0-10 分制
+            
+            criterion_scores[criterion] = CriterionScore(
+                name=criterion,
+                score=raw_score * 10.0,  # 原始分数（0-10）
+                weight=weight,
+                weighted_score=weighted_score,
+                description=self._get_criterion_description(criterion, assessment.language)
+            )
+            
+            total_score += weighted_score
+        
+        # 生成评分分解说明
+        breakdown = self._generate_design_breakdown(
+            criterion_scores, 
+            total_score, 
+            assessment
+        )
+        
+        return ScoringResult(
+            total_score=min(total_score, 10.0),
+            criterion_scores=criterion_scores,
+            language=assessment.language,
+            scoring_breakdown=breakdown,
+            assessment=assessment
+        )
+    
+    def _get_criterion_description(self, criterion: str, language: str) -> str:
+        """获取评分标准描述"""
+        descriptions_zh = {
+            'structure': '文档结构完整性',
+            'ears_format': 'EARS 格式验收标准',
+            'user_stories': '用户故事质量',
+            'acceptance_criteria': '验收标准完整性',
+            'nfr_coverage': '非功能需求覆盖',
+            'constraints': '约束条件说明',
+            'traceability': '需求追溯性',
+            'component_detail': '组件详细度',
+            'diagrams': '架构图和设计图',
+            'technology': '技术选型说明',
+            'nfr_design': '非功能需求设计',
+            'interfaces': '接口定义完整性'
+        }
+        
+        descriptions_en = {
+            'structure': 'Document Structure Completeness',
+            'ears_format': 'EARS Format Acceptance Criteria',
+            'user_stories': 'User Story Quality',
+            'acceptance_criteria': 'Acceptance Criteria Completeness',
+            'nfr_coverage': 'Non-functional Requirements Coverage',
+            'constraints': 'Constraints Description',
+            'traceability': 'Requirements Traceability',
+            'component_detail': 'Component Detail Level',
+            'diagrams': 'Architecture and Design Diagrams',
+            'technology': 'Technology Stack Explanation',
+            'nfr_design': 'Non-functional Requirements Design',
+            'interfaces': 'Interface Definition Completeness'
+        }
+        
+        if language == 'zh':
+            return descriptions_zh.get(criterion, criterion)
+        else:
+            return descriptions_en.get(criterion, criterion)
+    
+    def _generate_requirements_breakdown(self, criterion_scores: Dict[str, CriterionScore], total_score: float, assessment: QualityAssessment) -> str:
+        """生成 Requirements 评分分解说明"""
+        lang = assessment.language
+        
+        if lang == 'zh':
+            breakdown = f"## 评分分解\n\n"
+            breakdown += f"**总分**: {total_score:.2f}/10\n\n"
+            breakdown += f"### 各项评分\n\n"
+            
+            for criterion, score_obj in criterion_scores.items():
+                breakdown += f"- **{score_obj.description}** ({score_obj.weight*100:.0f}%): "
+                breakdown += f"{score_obj.score:.2f}/10 → 加权分 {score_obj.weighted_score:.2f}\n"
+            
+            if assessment.missing_sections:
+                breakdown += f"\n### 缺失章节\n\n"
+                for section in assessment.missing_sections:
+                    breakdown += f"- {section}\n"
+            
+            if assessment.issues:
+                breakdown += f"\n### 改进建议\n\n"
+                for issue in assessment.issues[:5]:  # 最多显示 5 个
+                    breakdown += f"- {issue}\n"
+        else:
+            breakdown = f"## Scoring Breakdown\n\n"
+            breakdown += f"**Total Score**: {total_score:.2f}/10\n\n"
+            breakdown += f"### Criterion Scores\n\n"
+            
+            for criterion, score_obj in criterion_scores.items():
+                breakdown += f"- **{score_obj.description}** ({score_obj.weight*100:.0f}%): "
+                breakdown += f"{score_obj.score:.2f}/10 → Weighted {score_obj.weighted_score:.2f}\n"
+            
+            if assessment.missing_sections:
+                breakdown += f"\n### Missing Sections\n\n"
+                for section in assessment.missing_sections:
+                    breakdown += f"- {section}\n"
+            
+            if assessment.issues:
+                breakdown += f"\n### Improvement Suggestions\n\n"
+                for issue in assessment.issues[:5]:  # Show max 5
+                    breakdown += f"- {issue}\n"
+        
+        return breakdown
+    
+    def _generate_design_breakdown(self, criterion_scores: Dict[str, CriterionScore], total_score: float, assessment: QualityAssessment) -> str:
+        """生成 Design 评分分解说明"""
+        lang = assessment.language
+        
+        if lang == 'zh':
+            breakdown = f"## 评分分解\n\n"
+            breakdown += f"**总分**: {total_score:.2f}/10\n\n"
+            breakdown += f"### 各项评分\n\n"
+            
+            for criterion, score_obj in criterion_scores.items():
+                breakdown += f"- **{score_obj.description}** ({score_obj.weight*100:.0f}%): "
+                breakdown += f"{score_obj.score:.2f}/10 → 加权分 {score_obj.weighted_score:.2f}\n"
+            
+            if assessment.missing_sections:
+                breakdown += f"\n### 缺失章节\n\n"
+                for section in assessment.missing_sections:
+                    breakdown += f"- {section}\n"
+            
+            if assessment.issues:
+                breakdown += f"\n### 改进建议\n\n"
+                for issue in assessment.issues[:5]:
+                    breakdown += f"- {issue}\n"
+        else:
+            breakdown = f"## Scoring Breakdown\n\n"
+            breakdown += f"**Total Score**: {total_score:.2f}/10\n\n"
+            breakdown += f"### Criterion Scores\n\n"
+            
+            for criterion, score_obj in criterion_scores.items():
+                breakdown += f"- **{score_obj.description}** ({score_obj.weight*100:.0f}%): "
+                breakdown += f"{score_obj.score:.2f}/10 → Weighted {score_obj.weighted_score:.2f}\n"
+            
+            if assessment.missing_sections:
+                breakdown += f"\n### Missing Sections\n\n"
+                for section in assessment.missing_sections:
+                    breakdown += f"- {section}\n"
+            
+            if assessment.issues:
+                breakdown += f"\n### Improvement Suggestions\n\n"
+                for issue in assessment.issues[:5]:
+                    breakdown += f"- {issue}\n"
+        
+        return breakdown

package/template/.kiro/tools/report_generator.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Report Generator - 报告生成器
+
+生成增强过程的详细报告
+注意：这是一个轻量级实现，基本报告功能已集成在 EnhancementResult 中
+"""
+
+from dataclasses import dataclass
+from typing import List, Dict, Optional
+from datetime import datetime
+
+
+@dataclass
+class EnhancementReport:
+    """增强报告数据结构"""
+    document_type: str
+    document_path: str
+    initial_score: float
+    final_score: float
+    improvement: float
+    iterations: int
+    stopping_reason: str
+    improvements_applied: List[Dict]
+    timestamp: str
+    gate_passed: Optional[bool] = None
+    gate_threshold: Optional[float] = None
+
+
+class ReportGenerator:
+    """
+    报告生成器
+    
+    生成 Markdown 格式的增强报告和质量摘要
+    """
+    
+    def generate_enhancement_report(self, report_data: EnhancementReport) -> str:
+        """
+        生成增强报告
+        
+        Args:
+            report_data: 报告数据
+        
+        Returns:
+            Markdown 格式的报告
+        """
+        lines = []
+        
+        # 标题
+        lines.append(f"# Enhancement Report: {report_data.document_type.upper()}")
+        lines.append(f"\n**Generated**: {report_data.timestamp}")
+        lines.append(f"**Document**: `{report_data.document_path}`\n")
+        lines.append("---\n")
+        
+        # 摘要
+        lines.append("## Summary\n")
+        lines.append(f"- **Initial Score**: {report_data.initial_score:.2f}/10")
+        lines.append(f"- **Final Score**: {report_data.final_score:.2f}/10")
+        lines.append(f"- **Improvement**: +{report_data.improvement:.2f}")
+        lines.append(f"- **Iterations**: {report_data.iterations}")
+        lines.append(f"- **Stopping Reason**: {report_data.stopping_reason}\n")
+        
+        # 质量门结果
+        if report_data.gate_passed is not None:
+            lines.append("## Quality Gate\n")
+            status = "✓ PASSED" if report_data.gate_passed else "✗ FAILED"
+            lines.append(f"- **Status**: {status}")
+            lines.append(f"- **Threshold**: {report_data.gate_threshold}/10")
+            lines.append(f"- **Final Score**: {report_data.final_score:.2f}/10\n")
+        
+        # 改进详情
+        if report_data.improvements_applied:
+            lines.append("## Improvements Applied\n")
+            for i, imp in enumerate(report_data.improvements_applied, 1):
+                lines.append(f"{i}. **{imp.get('type', 'Unknown')}**")
+                lines.append(f"   - Section: {imp.get('section', 'N/A')}")
+                lines.append(f"   - Priority: {imp.get('priority', 'N/A')}")
+                if imp.get('description'):
+                    lines.append(f"   - Description: {imp['description']}")
+                lines.append("")
+        
+        lines.append("---\n")
+        lines.append(f"*Report generated by Ultrawork Enhancement System*\n")
+        
+        return '\n'.join(lines)
+    
+    def generate_quality_summary(self, reports: List[EnhancementReport]) -> str:
+        """
+        生成质量摘要（多个文档）
+        
+        Args:
+            reports: 报告列表
+        
+        Returns:
+            Markdown 格式的摘要
+        """
+        lines = []
+        
+        # 标题
+        lines.append("# Quality Summary\n")
+        lines.append(f"**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        lines.append(f"**Documents**: {len(reports)}\n")
+        lines.append("---\n")
+        
+        # 总体统计
+        total_improvement = sum(r.improvement for r in reports)
+        avg_iterations = sum(r.iterations for r in reports) / len(reports) if reports else 0
+        passed_gates = sum(1 for r in reports if r.gate_passed)
+        
+        lines.append("## Overall Statistics\n")
+        lines.append(f"- **Total Improvement**: +{total_improvement:.2f}")
+        lines.append(f"- **Average Iterations**: {avg_iterations:.1f}")
+        if any(r.gate_passed is not None for r in reports):
+            lines.append(f"- **Quality Gates Passed**: {passed_gates}/{len(reports)}\n")
+        else:
+            lines.append("")
+        
+        # 各文档详情
+        lines.append("## Document Details\n")
+        for report in reports:
+            lines.append(f"### {report.document_type.upper()}\n")
+            lines.append(f"- **Path**: `{report.document_path}`")
+            lines.append(f"- **Score**: {report.initial_score:.2f} → {report.final_score:.2f} (+{report.improvement:.2f})")
+            lines.append(f"- **Iterations**: {report.iterations}")
+            
+            if report.gate_passed is not None:
+                status = "✓ PASSED" if report.gate_passed else "✗ FAILED"
+                lines.append(f"- **Quality Gate**: {status}")
+            
+            lines.append("")
+        
+        lines.append("---\n")
+        lines.append(f"*Summary generated by Ultrawork Enhancement System*\n")
+        
+        return '\n'.join(lines)
+    
+    def save_report(self, report: str, output_path: str):
+        """
+        保存报告到文件
+        
+        Args:
+            report: 报告内容
+            output_path: 输出路径
+        """
+        from pathlib import Path
+        
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write(report)
+
+
+# 注意：基本报告功能已集成在 ultrawork_enhancer_v3.py 的 EnhancementResult 中
+# 本类提供更详细的 Markdown 格式报告生成，可选使用