cc-devflow 1.0.1

package/.claude/schemas/constitution.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cc-devflow.claude/.claude/schemas/constitution.schema.json",
+  "title": "Devflow Constitution Tracking",
+  "type": "object",
+  "required": [
+    "articles"
+  ],
+  "properties": {
+    "articles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "article",
+          "status"
+        ],
+        "properties": {
+          "article": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "in_progress",
+              "approved",
+              "waived",
+              "rejected"
+            ]
+          },
+          "notes": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/.claude/scripts/analyze-upgrade-impact.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2312
+
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: scripts/bash/analyze-upgrade-impact.sh --req <requirement-dir|REQ-ID> [--compare version] [--format {text,json}]
+
+Produces PRD change detection and impact assessment reports under
+devflow/requirements/<REQ>/analysis/.
+USAGE
+}
+
+REQ=""
+COMPARE=""
+FORMAT="text"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --req)
+      shift
+      REQ="${1:-}"
+      ;;
+    --compare)
+      shift
+      COMPARE="${1:-}"
+      ;;
+    --format)
+      shift
+      FORMAT="${1:-text}"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+if [[ -z "$REQ" ]]; then
+  echo "Error: --req is required." >&2
+  usage
+  exit 1
+fi
+
+if [[ -d "$REQ" ]]; then
+  REQ_DIR="$(cd "$REQ" && pwd)"
+else
+  REQ_DIR="devflow/requirements/$REQ"
+fi
+
+if [[ ! -d "$REQ_DIR" ]]; then
+  echo "Error: requirement directory '$REQ_DIR' not found." >&2
+  exit 1
+fi
+
+python3 - "$REQ_DIR" "$COMPARE" "$FORMAT" <<'PY'
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Any
+
+req_dir = Path(sys.argv[1]).resolve()
+compare_version = sys.argv[2] or ""
+fmt = sys.argv[3]
+
+prd_current = req_dir / "PRD.md"
+if not prd_current.exists():
+    print(f"Error: {prd_current} not found.", file=sys.stderr)
+    sys.exit(1)
+
+versions_dir = req_dir / "versions"
+compare_path = None
+if compare_version:
+    compare_path = versions_dir / compare_version / "PRD.md"
+    if not compare_path.exists():
+        print(f"Warning: compare version {compare_version} not found; skipping diff.", file=sys.stderr)
+        compare_path = None
+
+current_lines = prd_current.read_text(encoding="utf-8").splitlines()
+previous_lines = compare_path.read_text(encoding="utf-8").splitlines() if compare_path else []
+
+analysis_dir = req_dir / "analysis"
+analysis_dir.mkdir(exist_ok=True, parents=True)
+timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+
+def diff_stats() -> Dict[str, Any]:
+    additions = sum(1 for line in current_lines if line.startswith("+") and "User Story" in line)
+    removals = sum(1 for line in previous_lines if line.startswith("+") and "User Story" in line)
+    breaking = 0
+    additive = 0
+    for line in current_lines:
+        if "[BREAKING]" in line or re.search(r"\bRemoved\b", line, re.IGNORECASE):
+            breaking += 1
+        if "User Story" in line or "API" in line:
+            additive += 1
+    return {
+        "userStoriesAdded": additions,
+        "userStoriesRemoved": removals,
+        "breakingMarkers": breaking,
+        "featureChanges": additive,
+    }
+
+stats = diff_stats()
+
+if stats["breakingMarkers"] > 0 or stats["userStoriesRemoved"] > 0:
+    recommendation = "MAJOR"
+elif stats["featureChanges"] > 1:
+    recommendation = "MINOR"
+else:
+    recommendation = "PATCH"
+
+change_report = analysis_dir / f"change_detection_{timestamp}.md"
+impact_report = analysis_dir / f"impact_assessment_{timestamp}.md"
+recommendation_report = analysis_dir / f"upgrade_recommendation_{timestamp}.md"
+
+change_report.write_text(
+    "\n".join(
+        [
+            f"# Change Detection — {req_dir.name}",
+            f"Generated: {datetime.now(timezone.utc).isoformat()}",
+            "",
+            f"- User stories added: {stats['userStoriesAdded']}",
+            f"- User stories removed: {stats['userStoriesRemoved']}",
+            f"- Breaking markers: {stats['breakingMarkers']}",
+            f"- Feature change mentions: {stats['featureChanges']}",
+        ]
+    )
+    + "\n",
+    encoding="utf-8",
+)
+
+impact_report.write_text(
+    "\n".join(
+        [
+            f"# Impact Assessment — {req_dir.name}",
+            "",
+            "## Code Areas Impacted",
+            "- TODO: map affected services/controllers.",
+            "",
+            "## Test Plan Impact",
+            "- TODO: identify regression suites requiring updates.",
+            "",
+            "## Deployment Considerations",
+            "- TODO: document rollout/rollback implications.",
+        ]
+    )
+    + "\n",
+    encoding="utf-8",
+)
+
+recommendation_report.write_text(
+    "\n".join(
+        [
+            f"# Upgrade Recommendation — {req_dir.name}",
+            "",
+            f"- Suggested version bump: **{recommendation}**",
+            "- Rationale:",
+            f"  * Breaking markers detected: {stats['breakingMarkers']}",
+            f"  * User stories added: {stats['userStoriesAdded']}",
+            f"  * User stories removed: {stats['userStoriesRemoved']}",
+        ]
+    )
+    + "\n",
+    encoding="utf-8",
+)
+
+summary = {
+    "requirement": req_dir.name,
+    "compareVersion": compare_version or None,
+    "recommendedBump": recommendation,
+    "statistics": stats,
+    "reports": {
+        "changeDetection": str(change_report.relative_to(req_dir)),
+        "impactAssessment": str(impact_report.relative_to(req_dir)),
+        "recommendation": str(recommendation_report.relative_to(req_dir)),
+    },
+}
+
+if fmt.lower() == "json":
+    print(json.dumps(summary, indent=2))
+else:
+    print(
+        f"Recommended bump: {recommendation}\n"
+        f"Reports:\n"
+        f"  - {summary['reports']['changeDetection']}\n"
+        f"  - {summary['reports']['impactAssessment']}\n"
+        f"  - {summary['reports']['recommendation']}"
+    )
+PY

package/.claude/scripts/archive-requirement.sh

@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+# =============================================================================
+# archive-requirement.sh - 需求归档脚本
+# 将已完成或废弃的需求移动到归档目录
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# =============================================================================
+# 使用说明
+# =============================================================================
+usage() {
+    cat << 'EOF'
+Usage: archive-requirement.sh <REQ_ID> [OPTIONS]
+
+归档需求目录到 devflow/archive/{YYYY-MM}/ 下
+
+Arguments:
+  REQ_ID              需求编号 (e.g., REQ-003, BUG-001)
+
+Options:
+  --reason REASON     归档原因: completed (默认), deprecated, obsolete, superseded
+  --restore           恢复归档的需求到活跃目录
+  --list              列出所有归档的需求
+  --json              输出 JSON 格式
+  --dry-run           仅显示将执行的操作，不实际执行
+  --help, -h          显示帮助信息
+
+Examples:
+  archive-requirement.sh REQ-003                    # 归档已完成需求
+  archive-requirement.sh REQ-003 --reason deprecated  # 标记为废弃归档
+  archive-requirement.sh --list                     # 列出所有归档
+  archive-requirement.sh REQ-003 --restore          # 恢复归档需求
+EOF
+}
+
+# =============================================================================
+# 参数解析
+# =============================================================================
+REQ_ID=""
+REASON="completed"
+RESTORE=false
+LIST_MODE=false
+JSON_MODE=false
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --reason)
+            REASON="$2"
+            shift 2
+            ;;
+        --restore)
+            RESTORE=true
+            shift
+            ;;
+        --list)
+            LIST_MODE=true
+            shift
+            ;;
+        --json)
+            JSON_MODE=true
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        -*)
+            echo "ERROR: Unknown option: $1" >&2
+            usage
+            exit 1
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+REPO_ROOT=$(get_repo_root)
+
+# =============================================================================
+# 列出归档模式
+# =============================================================================
+if [[ "$LIST_MODE" == "true" ]]; then
+    if [[ "$JSON_MODE" == "true" ]]; then
+        # JSON 格式输出
+        archive_base="$REPO_ROOT/devflow/archive"
+        echo "["
+        first=true
+        if [[ -d "$archive_base" ]]; then
+            for month_dir in "$archive_base"/*/; do
+                [[ -d "$month_dir" ]] || continue
+                month=$(basename "$month_dir")
+                for req_dir in "$month_dir"*/; do
+                    [[ -d "$req_dir" ]] || continue
+                    req_id=$(basename "$req_dir")
+                    status_file="$req_dir/orchestration_status.json"
+                    reason="completed"
+                    archived_at=""
+                    title=""
+                    if [[ -f "$status_file" ]]; then
+                        reason=$(jq -r '.archivedReason // "completed"' "$status_file" 2>/dev/null)
+                        archived_at=$(jq -r '.archivedAt // ""' "$status_file" 2>/dev/null)
+                        title=$(jq -r '.title // ""' "$status_file" 2>/dev/null)
+                    fi
+                    if [[ "$first" == "true" ]]; then
+                        first=false
+                    else
+                        echo ","
+                    fi
+                    printf '  {"reqId": "%s", "title": "%s", "month": "%s", "reason": "%s", "archivedAt": "%s"}' \
+                        "$req_id" "$title" "$month" "$reason" "$archived_at"
+                done
+            done
+        fi
+        echo ""
+        echo "]"
+    else
+        # 人类可读格式
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo "📦 归档需求列表"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        printf "%-10s | %-12s | %-12s | %s\n" "月份" "需求ID" "归档原因" "标题"
+        echo "───────────────────────────────────────────────────────────────"
+        archive_base="$REPO_ROOT/devflow/archive"
+        found=false
+        if [[ -d "$archive_base" ]]; then
+            for month_dir in "$archive_base"/*/; do
+                [[ -d "$month_dir" ]] || continue
+                month=$(basename "$month_dir")
+                for req_dir in "$month_dir"*/; do
+                    [[ -d "$req_dir" ]] || continue
+                    req_id=$(basename "$req_dir")
+                    status_file="$req_dir/orchestration_status.json"
+                    reason="completed"
+                    title=""
+                    if [[ -f "$status_file" ]]; then
+                        reason=$(jq -r '.archivedReason // "completed"' "$status_file" 2>/dev/null)
+                        title=$(jq -r '.title // ""' "$status_file" 2>/dev/null)
+                    fi
+                    printf "%-10s | %-12s | %-12s | %s\n" "$month" "$req_id" "$reason" "$title"
+                    found=true
+                done
+            done
+        fi
+        if [[ "$found" == "false" ]]; then
+            echo "(暂无归档需求)"
+        fi
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    fi
+    exit 0
+fi
+
+# =============================================================================
+# 验证 REQ_ID
+# =============================================================================
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: 必须提供需求ID" >&2
+    usage
+    exit 1
+fi
+
+if ! validate_req_id "$REQ_ID"; then
+    exit 1
+fi
+
+# =============================================================================
+# 恢复模式
+# =============================================================================
+if [[ "$RESTORE" == "true" ]]; then
+    archived_path=$(find_archived_req "$REPO_ROOT" "$REQ_ID")
+
+    if [[ -z "$archived_path" ]]; then
+        echo "ERROR: 归档中未找到 $REQ_ID" >&2
+        exit 1
+    fi
+
+    # 确定目标目录
+    req_type=$(get_req_type "$REQ_ID")
+    if [[ "$req_type" == "bug" ]]; then
+        target_dir="$REPO_ROOT/devflow/bugs/$REQ_ID"
+    else
+        target_dir="$REPO_ROOT/devflow/requirements/$REQ_ID"
+    fi
+
+    # 检查目标是否已存在
+    if [[ -d "$target_dir" ]]; then
+        echo "ERROR: 目标目录已存在: $target_dir" >&2
+        echo "请先删除或重命名现有目录" >&2
+        exit 1
+    fi
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+        echo "[DRY-RUN] 将移动: $archived_path → $target_dir"
+        exit 0
+    fi
+
+    # 执行恢复
+    mkdir -p "$(dirname "$target_dir")"
+    mv "$archived_path" "$target_dir"
+
+    # 更新状态文件
+    status_file="$target_dir/orchestration_status.json"
+    if [[ -f "$status_file" ]]; then
+        # 恢复到归档前的状态
+        original_status=$(jq -r '.statusBeforeArchive // "release_complete"' "$status_file")
+        jq --arg status "$original_status" \
+           --arg updated "$(get_beijing_time_iso)" \
+           'del(.archivedAt, .archivedReason, .archiveLocation, .statusBeforeArchive) |
+            .status = $status |
+            .updatedAt = $updated' \
+           "$status_file" > "${status_file}.tmp" && mv "${status_file}.tmp" "$status_file"
+    fi
+
+    # 记录日志
+    log_event "$REQ_ID" "需求从归档恢复: $archived_path → $target_dir"
+
+    if [[ "$JSON_MODE" == "true" ]]; then
+        cat << EOF
+{
+  "action": "restore",
+  "reqId": "$REQ_ID",
+  "from": "$archived_path",
+  "to": "$target_dir",
+  "status": "success"
+}
+EOF
+    else
+        echo "✅ 需求 $REQ_ID 已从归档恢复"
+        echo "   位置: $target_dir"
+    fi
+    exit 0
+fi
+
+# =============================================================================
+# 归档模式
+# =============================================================================
+
+# 验证归档原因
+valid_reasons=("completed" "deprecated" "obsolete" "superseded")
+if [[ ! " ${valid_reasons[*]} " =~ " ${REASON} " ]]; then
+    echo "ERROR: 无效的归档原因: $REASON" >&2
+    echo "有效选项: ${valid_reasons[*]}" >&2
+    exit 1
+fi
+
+# 检查需求是否已归档
+if is_archived "$REPO_ROOT" "$REQ_ID"; then
+    archived_path=$(find_archived_req "$REPO_ROOT" "$REQ_ID")
+    echo "ERROR: $REQ_ID 已经在归档中: $archived_path" >&2
+    echo "如需重新归档，请先使用 --restore 恢复" >&2
+    exit 1
+fi
+
+# 获取当前需求目录
+source_dir=$(get_req_dir "$REPO_ROOT" "$REQ_ID")
+
+if [[ ! -d "$source_dir" ]]; then
+    echo "ERROR: 需求目录不存在: $source_dir" >&2
+    exit 1
+fi
+
+# 确定归档目标
+archive_month=$(TZ='Asia/Shanghai' date '+%Y-%m')
+archive_dir=$(get_archive_dir "$REPO_ROOT" "$archive_month")
+target_dir="$archive_dir/$REQ_ID"
+
+if [[ "$DRY_RUN" == "true" ]]; then
+    echo "[DRY-RUN] 将移动: $source_dir → $target_dir"
+    echo "[DRY-RUN] 归档原因: $REASON"
+    exit 0
+fi
+
+# 创建归档目录
+mkdir -p "$archive_dir"
+
+# 读取当前状态
+status_file="$source_dir/orchestration_status.json"
+current_status="unknown"
+if [[ -f "$status_file" ]]; then
+    current_status=$(jq -r '.status // "unknown"' "$status_file")
+fi
+
+# 移动目录
+mv "$source_dir" "$target_dir"
+
+# 更新状态文件
+status_file="$target_dir/orchestration_status.json"
+if [[ -f "$status_file" ]]; then
+    jq --arg reason "$REASON" \
+       --arg archived_at "$(get_beijing_time_iso)" \
+       --arg location "$target_dir" \
+       --arg prev_status "$current_status" \
+       --arg updated "$(get_beijing_time_iso)" \
+       '.status = "archived" |
+        .archivedReason = $reason |
+        .archivedAt = $archived_at |
+        .archiveLocation = $location |
+        .statusBeforeArchive = $prev_status |
+        .updatedAt = $updated' \
+       "$status_file" > "${status_file}.tmp" && mv "${status_file}.tmp" "$status_file"
+fi
+
+# 记录日志
+log_file="$target_dir/EXECUTION_LOG.md"
+if [[ -f "$log_file" ]]; then
+    cat >> "$log_file" << EOF
+
+### $(get_beijing_time)
+**需求归档**
+- 归档原因: $REASON
+- 归档位置: $target_dir
+- 归档前状态: $current_status
+EOF
+fi
+
+# 输出结果
+if [[ "$JSON_MODE" == "true" ]]; then
+    cat << EOF
+{
+  "action": "archive",
+  "reqId": "$REQ_ID",
+  "from": "$source_dir",
+  "to": "$target_dir",
+  "reason": "$REASON",
+  "previousStatus": "$current_status",
+  "archivedAt": "$(get_beijing_time_iso)",
+  "status": "success"
+}
+EOF
+else
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "✅ 需求 $REQ_ID 已归档"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "   原位置: $source_dir"
+    echo "   新位置: $target_dir"
+    echo "   归档原因: $REASON"
+    echo "   归档前状态: $current_status"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+fi