cc-devflow 4.3.0 → 4.4.1

package/.claude/skills/flow-init/scripts/populate-research-tasks.sh

@@ -1,284 +0,0 @@
-#!/usr/bin/env bash
-# shellcheck disable=SC2312
-
-set -euo pipefail
-
-# ============================================================================
-# populate-research-tasks.sh - 智能填充 tasks.json 的决策信息
-# ============================================================================
-# 功能: 从 research-summary.md 和其他研究材料中提取决策信息，
-#       填充 tasks.json 的 decision/rationale/alternatives 字段
-#
-# 使用场景:
-#   - generate-research-tasks.sh 生成基础 tasks.json 后
-#   - consolidate-research.sh 运行前
-#   - 确保 research.md 不包含 TODO 占位符
-# ============================================================================
-
-usage() {
-  cat <<'USAGE'
-Usage: .claude/scripts/populate-research-tasks.sh <requirement-dir>
-
-Populates tasks.json with decision/rationale/alternatives fields extracted
-from research-summary.md and other research materials.
-
-This script bridges the gap between generate-research-tasks.sh (which creates
-basic task structure) and consolidate-research.sh (which expects complete tasks).
-
-Example:
-  .claude/scripts/populate-research-tasks.sh devflow/requirements/REQ-123
-
-USAGE
-}
-
-if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
-  usage
-  exit 0
-fi
-
-if [[ $# -lt 1 ]]; then
-  echo "❌ Error: requirement directory is required." >&2
-  usage
-  exit 1
-fi
-
-REQ_DIR="$1"
-if [[ ! -d "$REQ_DIR" ]]; then
-  echo "❌ Error: requirement directory '$REQ_DIR' does not exist." >&2
-  exit 1
-fi
-
-python3 - "$REQ_DIR" <<'PY'
-from __future__ import annotations
-
-import json
-import re
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Dict, List, Optional
-
-req_dir = Path(sys.argv[1]).resolve()
-research_dir = req_dir / "research"
-tasks_path = research_dir / "tasks.json"
-summary_path = research_dir / "research-summary.md"
-
-# ============================================================================
-# 核心提取逻辑
-# ============================================================================
-
-def extract_task_sections(markdown_content: str) -> List[Dict[str, str]]:
-    """
-    从 research-summary.md 中提取任务章节信息。
-
-    期望格式:
-    ### R001 — 输入框架构重构
-    - **Decision**: 全面重构方案
-    - **Rationale**:
-      - 当前实现仅207行...
-    - **Alternatives Considered**:
-      - 渐进式增强...
-    """
-    sections = []
-    current_section = None
-    current_field = None
-
-    # 匹配任务标题（兼容历史 RT-001）:
-    # - ### R001 — Title
-    # - ### R001: Title
-    # - ### R001 - Title
-    # - ### RT-001: Title  (legacy)
-    task_header = re.compile(r"^###\s+(?P<id>R\d{3}|RT-\d{3})\s*(?:[:—-])\s*(?P<title>.+)$")
-
-    # 匹配字段头（兼容是否带 bullet）:
-    # - - **Decision**: xxx
-    # - - **Rationale**:
-    # - - **Alternatives Considered**:
-    field_header = re.compile(
-        r"^(?:[-*]\s*)?\*\*(?P<label>决策|Decision|理由|Rationale|备选方案|Alternatives(?:\s+Considered)?|来源|Source)\*\*:\s*(?P<value>.*)$"
-    )
-
-    def normalize_task_id(raw: str) -> str:
-        if raw.startswith("RT-"):
-            return f"R{raw.split('-', 1)[1]}"
-        return raw
-
-    def normalize_list_item(line: str) -> str:
-        line = line.strip()
-        line = re.sub(r"^[-*]\s+", "", line)
-        return line.strip()
-
-    for line in markdown_content.splitlines():
-        raw_line = line
-        line = line.strip()
-
-        # 检测新任务章节
-        task_match = task_header.match(line)
-        if task_match:
-            if current_section:
-                sections.append(current_section)
-            current_field = None
-            current_section = {
-                "id": normalize_task_id(task_match.group("id")),
-                "title": task_match.group("title"),
-                "decision": "",
-                "rationale": "",
-                "alternatives": "",
-            }
-            continue
-
-        if not current_section:
-            continue
-
-        # 检测字段头
-        field_match = field_header.match(line)
-        if field_match:
-            label = field_match.group("label").strip().lower()
-            value = (field_match.group("value") or "").strip()
-
-            if label in {"来源", "source"}:
-                current_field = None
-                continue
-            if label in {"决策", "decision"}:
-                current_field = "decision"
-            elif label in {"理由", "rationale"}:
-                current_field = "rationale"
-            else:
-                current_field = "alternatives"
-
-            if value:
-                current_section[current_field] = value
-            continue
-
-        # 累积字段内容（支持列表项）
-        if current_field and line:
-            item = normalize_list_item(raw_line)
-            if not item:
-                continue
-            if current_section[current_field]:
-                current_section[current_field] += "\n" + item
-            else:
-                current_section[current_field] = item
-
-    # 添加最后一个章节
-    if current_section:
-        sections.append(current_section)
-
-    return sections
-
-def load_tasks_json() -> Dict:
-    """加载现有的 tasks.json"""
-    if not tasks_path.exists():
-        print(f"❌ Error: {tasks_path} does not exist.", file=sys.stderr)
-        print(f"   Run generate-research-tasks.sh first.", file=sys.stderr)
-        sys.exit(1)
-
-    try:
-        return json.loads(tasks_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as e:
-        print(f"❌ Error: {tasks_path} is not valid JSON: {e}", file=sys.stderr)
-        sys.exit(1)
-
-def load_research_summary() -> Optional[str]:
-    """加载 research-summary.md 内容"""
-    if not summary_path.exists():
-        print(f"⚠️  Warning: {summary_path} does not exist.", file=sys.stderr)
-        print(f"   Will generate basic fallback content.", file=sys.stderr)
-        return None
-
-    return summary_path.read_text(encoding="utf-8")
-
-def generate_fallback_content(task: Dict) -> Dict[str, str]:
-    """
-    为任务生成后备内容（如果 research-summary.md 不存在或解析失败）
-    """
-    task_type = task.get("type", "clarification")
-    prompt = task.get("prompt", "")
-
-    if task_type == "clarification":
-        return {
-            "decision": f"基于需求分析和代码库调研，明确了 {prompt} 的具体方案",
-            "rationale": "通过分析现有代码库和需求文档，结合技术栈特点，确定了最适合的实现路径",
-            "alternatives": "考虑了多种替代方案，包括第三方库集成、自主实现、复刻现有方案等，最终选择了与项目技术栈最契合的方案",
-        }
-    elif task_type == "best_practices":
-        return {
-            "decision": f"遵循 {prompt} 的行业最佳实践",
-            "rationale": "结合项目实际情况和团队经验，采用成熟稳定的技术方案",
-            "alternatives": "评估了社区主流方案和定制化方案，选择了可维护性和扩展性最佳的实现",
-        }
-    else:
-        return {
-            "decision": f"针对 {prompt} 制定了具体实施方案",
-            "rationale": "基于需求优先级和技术可行性分析做出的决策",
-            "alternatives": "权衡了多种技术路线的利弊后的最优选择",
-        }
-
-# ============================================================================
-# 主逻辑
-# ============================================================================
-
-# 1. 加载 tasks.json
-tasks_data = load_tasks_json()
-tasks = tasks_data.get("tasks", [])
-
-if not tasks:
-    print("⚠️  Warning: No tasks found in tasks.json", file=sys.stderr)
-    sys.exit(0)
-
-# 2. 加载 research-summary.md 并提取章节
-summary_content = load_research_summary()
-extracted_sections = {}
-
-if summary_content:
-    sections = extract_task_sections(summary_content)
-    extracted_sections = {section["id"]: section for section in sections}
-    print(f"📖 Extracted {len(extracted_sections)} section(s) from research-summary.md", file=sys.stderr)
-else:
-    print("⚠️  Using fallback content generation", file=sys.stderr)
-
-# 3. 填充 tasks.json 的 decision/rationale/alternatives 字段
-updated_count = 0
-fallback_count = 0
-
-for task in tasks:
-    task_id = task.get("id", "")
-
-    # 如果已经有完整的 decision/rationale/alternatives，跳过
-    has_decision = bool(task.get("decision") and task.get("decision") != "TODO - fill decision outcome")
-    has_rationale = bool(task.get("rationale") and task.get("rationale") != "TODO - explain why this decision was chosen")
-    has_alternatives = bool(task.get("alternatives") and task.get("alternatives") != "TODO - list evaluated alternatives")
-
-    if has_decision and has_rationale and has_alternatives:
-        continue
-
-    # 尝试从提取的章节中获取信息
-    if task_id in extracted_sections:
-        section = extracted_sections[task_id]
-        task["decision"] = section["decision"] or task.get("decision", "")
-        task["rationale"] = section["rationale"] or task.get("rationale", "")
-        task["alternatives"] = section["alternatives"] or task.get("alternatives", "")
-        updated_count += 1
-        print(f"✅ Updated {task_id} from research-summary.md", file=sys.stderr)
-    else:
-        # 生成后备内容
-        fallback = generate_fallback_content(task)
-        task["decision"] = fallback["decision"]
-        task["rationale"] = fallback["rationale"]
-        task["alternatives"] = fallback["alternatives"]
-        fallback_count += 1
-        print(f"⚠️  Generated fallback for {task_id} (not found in research-summary.md)", file=sys.stderr)
-
-# 4. 保存更新后的 tasks.json
-tasks_data["updatedAt"] = datetime.now(timezone.utc).isoformat()
-tasks_path.write_text(json.dumps(tasks_data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-
-# 5. 输出统计信息
-total = len(tasks)
-print("", file=sys.stderr)
-print(f"✅ Populated {total} task(s):", file=sys.stderr)
-print(f"   - {updated_count} from research-summary.md", file=sys.stderr)
-print(f"   - {fallback_count} using fallback content", file=sys.stderr)
-print(f"", file=sys.stderr)
-print(f"Next step: Run consolidate-research.sh to generate research.md", file=sys.stderr)
-PY

package/.claude/skills/flow-init/scripts/validate-research.sh

@@ -1,340 +0,0 @@
-#!/usr/bin/env bash
-# =============================================================================
-# validate-research.sh - Research.md 质量验证脚本
-# =============================================================================
-# Purpose: 验证 research.md 是否符合 spec-kit Decision/Rationale/Alternatives 格式
-#          确保无 TODO 占位符、无空章节、格式完整
-#
-# Usage:
-#   validate-research.sh <REQ_DIR> [--strict]
-#
-# Exit Codes:
-#   0 - 验证通过
-#   1 - 验证失败（输出具体错误）
-#
-# Constitution Compliance:
-#   - Article X.1 (Forced Clarification): 检查 NEEDS CLARIFICATION 标记
-#   - Article X.2 (No Speculation): 禁止推测性技术细节
-#   - Article I.1 (Complete Implementation): 禁止 TODO/PLACEHOLDER
-# =============================================================================
-
-set -euo pipefail
-
-# ────────────────────────────────────────────────────────────────────────────
-# Configuration
-# ────────────────────────────────────────────────────────────────────────────
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-
-# shellcheck source=.claude/scripts/common.sh
-COMMON_SH="$SCRIPT_DIR/common.sh"
-if [[ ! -f "$COMMON_SH" ]]; then
-  COMMON_SH="$SCRIPT_DIR/../../../../scripts/common.sh"
-fi
-if [[ ! -f "$COMMON_SH" ]]; then
-  echo "ERROR: common.sh not found (checked local + .claude/scripts)" >&2
-  exit 1
-fi
-source "$COMMON_SH"
-
-STRICT_MODE=false
-
-# ────────────────────────────────────────────────────────────────────────────
-# Usage
-# ────────────────────────────────────────────────────────────────────────────
-
-usage() {
-  cat <<'USAGE'
-Usage: validate-research.sh <REQ_DIR> [--strict]
-
-Validates research.md quality and structure:
-  - Checks for mandatory sections (Research Summary, Decisions, etc.)
-  - Validates Decision/Rationale/Alternatives blocks
-  - Detects TODO placeholders and empty content
-  - Verifies NEEDS CLARIFICATION markers
-
-Arguments:
-  REQ_DIR    Path to requirement directory (e.g., devflow/requirements/REQ-123)
-  --strict   Exit with code 1 if any validation fails (default: warnings only)
-
-Examples:
-  validate-research.sh devflow/requirements/REQ-123
-  validate-research.sh devflow/requirements/REQ-123 --strict
-USAGE
-}
-
-# ────────────────────────────────────────────────────────────────────────────
-# Argument Parsing
-# ────────────────────────────────────────────────────────────────────────────
-
-if [[ $# -lt 1 ]] || [[ "${1:-}" == "-h" ]] || [[ "${1:-}" == "--help" ]]; then
-  usage
-  exit 0
-fi
-
-REQ_DIR="$1"
-shift
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --strict)
-      STRICT_MODE=true
-      shift
-      ;;
-    *)
-      echo "❌ Unknown option: $1" >&2
-      usage
-      exit 1
-      ;;
-  esac
-done
-
-# ────────────────────────────────────────────────────────────────────────────
-# Validation Functions
-# ────────────────────────────────────────────────────────────────────────────
-
-validate_file_exists() {
-  local research_md="$REQ_DIR/research/research.md"
-
-  if [[ ! -f "$research_md" ]]; then
-    echo "❌ LEVEL 1 FAILED: research.md not found at $research_md"
-    return 1
-  fi
-
-  echo "✅ LEVEL 1 PASSED: research.md exists"
-  return 0
-}
-
-validate_structure() {
-  local research_md="$REQ_DIR/research/research.md"
-  local errors=0
-
-  echo "🔍 LEVEL 2: Validating structure..."
-
-  # 必需章节检查
-  local required_sections=(
-    "Research Summary"
-    "Decisions"
-  )
-
-  for section in "${required_sections[@]}"; do
-    if ! grep -qE "^##\s+$section" "$research_md"; then
-      echo "  ❌ Missing section: ## $section"
-      ((errors++))
-    else
-      echo "  ✅ Found section: ## $section"
-    fi
-  done
-
-  # 检查至少有一个 Decision block
-  if ! grep -qE "^###\s+R[0-9]+" "$research_md"; then
-    echo "  ❌ No Decision blocks found (expected ### R001, R002, etc.)"
-    ((errors++))
-  else
-    local decision_count
-    decision_count=$(grep -cE "^###\s+R[0-9]+" "$research_md" || echo 0)
-    echo "  ✅ Found $decision_count Decision block(s)"
-  fi
-
-  if [[ $errors -eq 0 ]]; then
-    echo "✅ LEVEL 2 PASSED: Structure valid"
-    return 0
-  else
-    echo "❌ LEVEL 2 FAILED: $errors structure error(s)"
-    return 1
-  fi
-}
-
-validate_content_quality() {
-  local research_md="$REQ_DIR/research/research.md"
-  local errors=0
-
-  echo "🔍 LEVEL 3: Validating content quality..."
-
-  # 检查 TODO 占位符
-  local todo_count
-  todo_count=$(grep -ciE "TODO|FIXME|XXX|PLACEHOLDER" "$research_md" 2>/dev/null || echo "0")
-  todo_count=$(echo "$todo_count" | head -1)  # 只取第一行
-  if [[ $todo_count -gt 0 ]]; then
-    echo "  ❌ Found $todo_count TODO/PLACEHOLDER marker(s):"
-    grep -niE "TODO|FIXME|XXX|PLACEHOLDER" "$research_md" | head -5 | while IFS= read -r line; do
-      echo "     $line"
-    done
-    ((errors++))
-  else
-    echo "  ✅ No TODO/PLACEHOLDER markers"
-  fi
-
-  # 检查 {{PLACEHOLDER}} 格式
-  local placeholder_count
-  placeholder_count=$(grep -coE '\{\{[^}]+\}\}' "$research_md" 2>/dev/null || echo "0")
-  placeholder_count=$(echo "$placeholder_count" | head -1)  # 只取第一行
-  if [[ $placeholder_count -gt 0 ]]; then
-    echo "  ❌ Found $placeholder_count {{PLACEHOLDER}} marker(s)"
-    grep -nE '\{\{[^}]+\}\}' "$research_md" | head -5 | while IFS= read -r line; do
-      echo "     $line"
-    done
-    ((errors++))
-  else
-    echo "  ✅ No {{PLACEHOLDER}} markers"
-  fi
-
-  # 检查 Decision/Rationale/Alternatives 完整性
-  local decision_blocks
-  decision_blocks=$(grep -cE "^###\s+R[0-9]+" "$research_md" 2>/dev/null || echo "0")
-  decision_blocks=$(echo "$decision_blocks" | head -1)  # 只取第一行
-
-  if [[ $decision_blocks -gt 0 ]]; then
-    echo "  🔍 Checking $decision_blocks Decision block(s)..."
-
-    local incomplete_blocks=0
-    while IFS= read -r block_line; do
-      local block_num
-      block_num=$(echo "$block_line" | grep -oE "R[0-9]+")
-
-      # 检查该 block 是否有 Decision/Rationale/Alternatives
-      local has_decision has_rationale has_alternatives
-      has_decision=$(grep -cE "^- Decision:|^- \*\*Decision\*\*:" "$research_md" 2>/dev/null || echo "0")
-      has_decision=$(echo "$has_decision" | head -1)
-      has_rationale=$(grep -cE "^- Rationale:|^- \*\*Rationale\*\*:" "$research_md" 2>/dev/null || echo "0")
-      has_rationale=$(echo "$has_rationale" | head -1)
-      has_alternatives=$(grep -cE "^- Alternatives considered:|^- \*\*Alternatives Considered\*\*:" "$research_md" 2>/dev/null || echo "0")
-      has_alternatives=$(echo "$has_alternatives" | head -1)
-
-      if [[ $has_decision -eq 0 ]] || [[ $has_rationale -eq 0 ]] || [[ $has_alternatives -eq 0 ]]; then
-        echo "     ❌ Block $block_num: incomplete (missing Decision/Rationale/Alternatives)"
-        ((incomplete_blocks++))
-      fi
-    done < <(grep -nE "^###\s+R[0-9]+" "$research_md")
-
-    if [[ $incomplete_blocks -gt 0 ]]; then
-      echo "  ❌ $incomplete_blocks block(s) incomplete"
-      ((errors++))
-    else
-      echo "  ✅ All Decision blocks complete"
-    fi
-  fi
-
-  # 检查空章节
-  if grep -qE "^##.*\n\n_No research" "$research_md"; then
-    echo "  ⚠️  Found empty sections (acceptable if research not started)"
-  fi
-
-  if [[ $errors -eq 0 ]]; then
-    echo "✅ LEVEL 3 PASSED: Content quality valid"
-    return 0
-  else
-    echo "❌ LEVEL 3 FAILED: $errors content error(s)"
-    return 1
-  fi
-}
-
-validate_constitution() {
-  local research_md="$REQ_DIR/research/research.md"
-  local errors=0
-
-  echo "🔍 LEVEL 4: Constitution compliance check..."
-
-  # Article X.1 (Forced Clarification)
-  local needs_clarification_count
-  needs_clarification_count=$(grep -ciE "NEEDS CLARIFICATION" "$research_md" 2>/dev/null || echo "0")
-  needs_clarification_count=$(echo "$needs_clarification_count" | head -1)  # 只取第一行
-  if [[ $needs_clarification_count -gt 0 ]]; then
-    echo "  ✅ Article X.1: Found $needs_clarification_count NEEDS CLARIFICATION marker(s)"
-  else
-    echo "  ℹ️  Article X.1: No unresolved questions (acceptable if research complete)"
-  fi
-
-  # Article X.2 (No Speculation) - 检查推测性语言
-  local speculation_patterns=(
-    "might|maybe|probably|possibly|perhaps"
-    "could be|should be|would be"
-    "in the future|future-proof|预留|扩展性"
-  )
-
-  for pattern in "${speculation_patterns[@]}"; do
-    if grep -qiE "$pattern" "$research_md"; then
-      echo "  ⚠️  Article X.2: Found speculative language: '$pattern'"
-      echo "     (Review context - acceptable if explaining rationale)"
-    fi
-  done
-
-  # Article I.1 (Complete Implementation)
-  if grep -qiE "暂时|临时|简化版|simplified|temporary|partial" "$research_md"; then
-    echo "  ❌ Article I.1: Found partial implementation language"
-    ((errors++))
-  else
-    echo "  ✅ Article I.1: No partial implementation markers"
-  fi
-
-  if [[ $errors -eq 0 ]]; then
-    echo "✅ LEVEL 4 PASSED: Constitution compliant"
-    return 0
-  else
-    echo "❌ LEVEL 4 FAILED: $errors constitution violation(s)"
-    return 1
-  fi
-}
-
-# ────────────────────────────────────────────────────────────────────────────
-# Main Execution
-# ────────────────────────────────────────────────────────────────────────────
-
-main() {
-  echo "════════════════════════════════════════════════════════════════════════"
-  echo "Research.md Quality Validation"
-  echo "════════════════════════════════════════════════════════════════════════"
-  echo "REQ_DIR: $REQ_DIR"
-  echo "MODE: $(if $STRICT_MODE; then echo "STRICT (fail on errors)"; else echo "LENIENT (warnings only)"; fi)"
-  echo ""
-
-  local total_errors=0
-
-  # Run all validation levels
-  validate_file_exists || ((total_errors++))
-  echo ""
-
-  validate_structure || ((total_errors++))
-  echo ""
-
-  validate_content_quality || ((total_errors++))
-  echo ""
-
-  validate_constitution || ((total_errors++))
-  echo ""
-
-  # ──────────────────────────────────────────────────────────────────────────
-  # Final Report
-  # ──────────────────────────────────────────────────────────────────────────
-
-  echo "════════════════════════════════════════════════════════════════════════"
-  if [[ $total_errors -eq 0 ]]; then
-    echo "✅ ALL VALIDATIONS PASSED"
-    echo "research.md is ready for /flow:spec"
-    echo "════════════════════════════════════════════════════════════════════════"
-    return 0
-  else
-    echo "❌ VALIDATION FAILED: $total_errors level(s) failed"
-    echo ""
-    echo "Next Steps:"
-    echo "  1. Review errors above"
-    echo "  2. Update research.md to fix issues"
-    echo "  3. Re-run: validate-research.sh $REQ_DIR"
-    echo ""
-    echo "Common Fixes:"
-    echo "  - Remove TODO markers → Fill with actual decisions"
-    echo "  - Add missing sections → Use RESEARCH_TEMPLATE.md"
-    echo "  - Complete Decision blocks → Add Rationale + Alternatives"
-    echo "════════════════════════════════════════════════════════════════════════"
-
-    if $STRICT_MODE; then
-      return 1
-    else
-      echo "⚠️  Running in LENIENT mode - returning success despite errors"
-      return 0
-    fi
-  fi
-}
-
-main