cc-devflow 4.1.2 → 4.1.4

package/.claude/scripts/flow-workspace-start.sh

@@ -13,12 +13,90 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 WORKSPACE_DIR="$PROJECT_ROOT/devflow/workspace"
+COMMON_SH="$SCRIPT_DIR/common.sh"
+
+if [[ -f "$COMMON_SH" ]]; then
+    source "$COMMON_SH"
+fi
 
 # ============================================================================
-# Detect Developer
+# Parse Arguments
 # ============================================================================
 
-DEVELOPER="${1:-$(whoami)}"
+usage() {
+    cat << 'EOF'
+Usage: flow-workspace-start.sh [REQ_ID|DEVELOPER] [OPTIONS]
+
+Start a workspace session and recover context.
+
+Arguments:
+  REQ_ID               Optional requirement ID to activate (REQ-XXX / BUG-XXX)
+  DEVELOPER            Optional developer name (legacy positional style)
+
+Options:
+  --developer NAME     Explicit developer name
+  --req REQ_ID         Activate a specific requirement before recovery
+  --switch             Show switch recommendation to the target worktree
+  --cd                 Try to execute cd (effective only when script is sourced)
+  --help, -h           Show help
+
+Examples:
+  flow-workspace-start.sh
+  flow-workspace-start.sh REQ-123 --switch
+  source flow-workspace-start.sh REQ-123 --switch --cd
+EOF
+}
+
+DEVELOPER="${DEVFLOW_DEVELOPER:-$(whoami)}"
+REQ_OVERRIDE=""
+SHOW_SWITCH=false
+DO_CD=false
+POSITIONAL=()
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --developer)
+            DEVELOPER="$2"
+            shift 2
+            ;;
+        --req)
+            REQ_OVERRIDE="$2"
+            shift 2
+            ;;
+        --switch)
+            SHOW_SWITCH=true
+            shift
+            ;;
+        --cd)
+            DO_CD=true
+            shift
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        -*)
+            echo "ERROR: Unknown option '$1'. Use --help for usage." >&2
+            exit 1
+            ;;
+        *)
+            POSITIONAL+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Backward compatible positional parsing:
+# - if token looks like REQ/BUG -> requirement override
+# - else treat as developer
+for token in "${POSITIONAL[@]}"; do
+    if [[ "$token" =~ ^(REQ|BUG)-[0-9]+(-[0-9]+)?$ ]]; then
+        REQ_OVERRIDE=$(echo "$token" | tr '[:lower:]' '[:upper:]')
+    else
+        DEVELOPER="$token"
+    fi
+done
+
 DEV_WORKSPACE="$WORKSPACE_DIR/$DEVELOPER"
 
 if [[ ! -d "$DEV_WORKSPACE" ]]; then
@@ -35,16 +113,31 @@ echo "🔄 Session Recovery for $DEVELOPER"
 echo "=================================="
 echo ""
 
+if [[ -n "$REQ_OVERRIDE" ]]; then
+    if declare -f validate_req_id >/dev/null 2>&1; then
+        validate_req_id "$REQ_OVERRIDE" || exit 1
+    fi
+    echo "$REQ_OVERRIDE" > "$DEV_WORKSPACE/.current-req"
+    echo "📌 Requirement override: $REQ_OVERRIDE"
+fi
+
 # Read current requirement
 if [[ -f "$DEV_WORKSPACE/.current-req" ]]; then
     CURRENT_REQ=$(cat "$DEV_WORKSPACE/.current-req")
     echo "📋 Current Requirement: $CURRENT_REQ"
 
-    # Check if requirement directory exists
-    REQ_DIR="$PROJECT_ROOT/devflow/requirements/$CURRENT_REQ"
+    # Resolve requirement/bug directory by ID prefix
+    if [[ "$CURRENT_REQ" =~ ^BUG- ]]; then
+        REQ_DIR="$PROJECT_ROOT/devflow/bugs/$CURRENT_REQ"
+        STATUS_BASENAME="status.json"
+    else
+        REQ_DIR="$PROJECT_ROOT/devflow/requirements/$CURRENT_REQ"
+        STATUS_BASENAME="orchestration_status.json"
+    fi
+
     if [[ -d "$REQ_DIR" ]]; then
         # Read orchestration status
-        STATUS_FILE="$REQ_DIR/orchestration_status.json"
+        STATUS_FILE="$REQ_DIR/$STATUS_BASENAME"
         if [[ -f "$STATUS_FILE" ]]; then
             STATUS=$(jq -r '.status' "$STATUS_FILE" 2>/dev/null || echo "unknown")
             echo "   Status: $STATUS"
@@ -57,6 +150,42 @@ if [[ -f "$DEV_WORKSPACE/.current-req" ]]; then
             DONE=$(grep -c '^\- \[x\]' "$TASKS_FILE" 2>/dev/null || echo "0")
             echo "   Tasks: $DONE/$TOTAL completed"
         fi
+
+        # Show expected worktree path and whether current session matches.
+        if declare -f get_worktree_dir_for_req >/dev/null 2>&1; then
+            EXPECTED_WORKTREE=$(get_worktree_dir_for_req "$CURRENT_REQ" 2>/dev/null || echo "")
+            CURRENT_GIT_ROOT=$(git -C "$PROJECT_ROOT" rev-parse --show-toplevel 2>/dev/null || echo "")
+
+            if [[ -n "$EXPECTED_WORKTREE" ]]; then
+                echo "   Expected Worktree: $EXPECTED_WORKTREE"
+                if [[ -d "$EXPECTED_WORKTREE" ]]; then
+                    if [[ "$CURRENT_GIT_ROOT" == "$EXPECTED_WORKTREE" ]]; then
+                        echo "   Worktree Match: yes"
+                    else
+                        echo "   Worktree Match: no"
+                        echo "   Action: cd $EXPECTED_WORKTREE"
+                    fi
+                else
+                    echo "   Worktree Match: missing"
+                fi
+
+                if $SHOW_SWITCH; then
+                    if [[ -d "$EXPECTED_WORKTREE" ]]; then
+                        if $DO_CD; then
+                            if [[ "${BASH_SOURCE[0]}" != "$0" ]]; then
+                                cd "$EXPECTED_WORKTREE"
+                                echo "   Auto Switched: yes ($PWD)"
+                            else
+                                echo "   Auto Switched: no (requires sourced execution)"
+                                echo "   Run: source .claude/scripts/flow-workspace-start.sh $CURRENT_REQ --switch --cd"
+                            fi
+                        else
+                            echo "   Switch Command: cd \"$EXPECTED_WORKTREE\""
+                        fi
+                    fi
+                fi
+            fi
+        fi
     else
         echo "   ⚠️  Requirement directory not found"
     fi
@@ -85,4 +214,4 @@ fi
 echo ""
 echo "Ready to continue. Use:"
 echo "  /flow-workspace record \"message\"  - Record progress"
-echo "  /flow-workspace switch REQ-XXX    - Switch requirement"
+echo "  /flow-workspace switch REQ-XXX|BUG-XXX - Switch requirement"

package/.claude/scripts/flow-workspace-switch.sh

@@ -0,0 +1,234 @@
+#!/bin/bash
+# [INPUT]: 依赖 common.sh、workspace/.current-req、journal-*.md
+# [OUTPUT]: 更新当前开发者的 REQ 指针，并输出/执行 worktree 切换动作
+# [POS]: scripts 的 workspace 切换脚本，被 /flow-workspace switch 与 start --switch 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+WORKSPACE_DIR="$PROJECT_ROOT/devflow/workspace"
+COMMON_SH="$SCRIPT_DIR/common.sh"
+
+if [[ -f "$COMMON_SH" ]]; then
+    source "$COMMON_SH"
+fi
+
+# ============================================================================
+# Usage
+# ============================================================================
+
+usage() {
+    cat << 'EOF'
+Usage: flow-workspace-switch.sh REQ_ID [OPTIONS]
+
+Switch workspace context to a target requirement.
+
+Arguments:
+  REQ_ID                 Requirement ID (REQ-XXX or BUG-XXX)
+
+Options:
+  --developer NAME       Developer name (default: DEVFLOW_DEVELOPER or current user)
+  --print-cd             Print `cd "<worktree>"` for eval-style switching
+  --cd                   Try to execute cd (effective only when script is sourced)
+  --json                 Output in JSON format
+  --help, -h             Show help
+
+Examples:
+  flow-workspace-switch.sh REQ-123
+  flow-workspace-switch.sh REQ-123 --print-cd
+  eval "$(flow-workspace-switch.sh REQ-123 --print-cd)"
+  source flow-workspace-switch.sh REQ-123 --cd
+EOF
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+REQ_ID=""
+DEVELOPER="${DEVFLOW_DEVELOPER:-$(whoami)}"
+PRINT_CD=false
+DO_CD=false
+JSON_MODE=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --developer)
+            DEVELOPER="$2"
+            shift 2
+            ;;
+        --print-cd)
+            PRINT_CD=true
+            shift
+            ;;
+        --cd)
+            DO_CD=true
+            shift
+            ;;
+        --json)
+            JSON_MODE=true
+            shift
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        -*)
+            echo "ERROR: Unknown option '$1'. Use --help for usage." >&2
+            exit 1
+            ;;
+        *)
+            if [[ -z "$REQ_ID" ]]; then
+                REQ_ID="$1"
+            else
+                echo "ERROR: Too many arguments. Use --help for usage." >&2
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: REQ_ID is required. Use --help for usage." >&2
+    exit 1
+fi
+
+# Normalize and validate REQ_ID
+REQ_ID=$(echo "$REQ_ID" | tr '[:lower:]' '[:upper:]')
+if declare -f validate_req_id >/dev/null 2>&1; then
+    validate_req_id "$REQ_ID" || exit 1
+fi
+
+# ============================================================================
+# Resolve Workspace
+# ============================================================================
+
+DEV_WORKSPACE="$WORKSPACE_DIR/$DEVELOPER"
+if [[ ! -d "$DEV_WORKSPACE" ]]; then
+    echo "ERROR: Workspace not found for '$DEVELOPER': $DEV_WORKSPACE" >&2
+    echo "Run '/flow-workspace init $DEVELOPER' first." >&2
+    exit 1
+fi
+
+# Update current requirement pointer
+echo "$REQ_ID" > "$DEV_WORKSPACE/.current-req"
+
+# Append a lightweight journal entry
+LATEST_JOURNAL=$(ls -1 "$DEV_WORKSPACE"/journal-*.md 2>/dev/null | sort -V | tail -1)
+if [[ -z "$LATEST_JOURNAL" ]]; then
+    LATEST_JOURNAL="$DEV_WORKSPACE/journal-1.md"
+    cat > "$LATEST_JOURNAL" << EOF
+---
+developer: "$DEVELOPER"
+journal_number: 1
+created_at: "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+---
+
+# Developer Journal: $DEVELOPER
+
+> **[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md
+
+---
+EOF
+fi
+
+TIMESTAMP=$(date +"%Y-%m-%d %H:%M")
+cat >> "$LATEST_JOURNAL" << EOF
+## [$TIMESTAMP] Requirement Switch
+
+**REQ**: $REQ_ID
+
+Switched workspace pointer to \`$REQ_ID\`.
+
+---
+EOF
+
+# Resolve worktree path
+WORKTREE_DIR=""
+WORKTREE_EXISTS=false
+if declare -f get_worktree_dir_for_req >/dev/null 2>&1; then
+    WORKTREE_DIR=$(get_worktree_dir_for_req "$REQ_ID" 2>/dev/null || echo "")
+fi
+if [[ -n "$WORKTREE_DIR" && -d "$WORKTREE_DIR" ]]; then
+    WORKTREE_EXISTS=true
+fi
+
+# Source detection: cd can only affect caller shell when sourced
+IS_SOURCED=false
+if [[ "${BASH_SOURCE[0]}" != "$0" ]]; then
+    IS_SOURCED=true
+fi
+
+CD_EXECUTED=false
+if $DO_CD; then
+    if ! $WORKTREE_EXISTS; then
+        echo "ERROR: Worktree not found for $REQ_ID: $WORKTREE_DIR" >&2
+        exit 1
+    fi
+
+    if $IS_SOURCED; then
+        cd "$WORKTREE_DIR"
+        CD_EXECUTED=true
+    fi
+fi
+
+# ============================================================================
+# Output
+# ============================================================================
+
+if $JSON_MODE; then
+    printf '{"developer":"%s","req_id":"%s","workspace":"%s","worktree_dir":"%s","worktree_exists":%s,"cd_executed":%s}\n' \
+        "$DEVELOPER" \
+        "$REQ_ID" \
+        "$DEV_WORKSPACE" \
+        "$WORKTREE_DIR" \
+        "$WORKTREE_EXISTS" \
+        "$CD_EXECUTED"
+    return 0 2>/dev/null || exit 0
+fi
+
+if $PRINT_CD; then
+    if $WORKTREE_EXISTS; then
+        printf 'cd "%s"\n' "$WORKTREE_DIR"
+        return 0 2>/dev/null || exit 0
+    fi
+    echo "ERROR: Worktree not found for $REQ_ID: $WORKTREE_DIR" >&2
+    exit 1
+fi
+
+echo "✅ Workspace switched"
+echo "Developer:         $DEVELOPER"
+echo "Current REQ:       $REQ_ID"
+echo "Workspace:         $DEV_WORKSPACE"
+if [[ -n "$WORKTREE_DIR" ]]; then
+    echo "Expected Worktree: $WORKTREE_DIR"
+fi
+echo "Worktree Exists:   $WORKTREE_EXISTS"
+
+if $DO_CD; then
+    if $CD_EXECUTED; then
+        echo "Directory switched to: $PWD"
+    else
+        echo ""
+        echo "⚠️  --cd 未生效（脚本以子进程运行，无法修改父 Shell 目录）"
+        echo "Use one of:"
+        echo "  source .claude/scripts/flow-workspace-switch.sh $REQ_ID --cd"
+        echo "  eval \"\$(.claude/scripts/flow-workspace-switch.sh $REQ_ID --print-cd)\""
+    fi
+elif $WORKTREE_EXISTS; then
+    echo ""
+    echo "Next:"
+    echo "  cd \"$WORKTREE_DIR\""
+else
+    echo ""
+    echo "Worktree is missing. Create it with flow-init (default mode) or worktree-create script."
+fi
+
+return 0 2>/dev/null || exit 0

package/.claude/scripts/generate-status-report.sh

@@ -124,8 +124,8 @@ get_phase_display_name() {
         epic_complete) echo "Epic完成" ;;
         development) echo "开发中" ;;
         dev_complete) echo "开发完成" ;;
-        qa) echo "质量保证" ;;
-        qa_complete) echo "QA完成" ;;
+        quality|qa) echo "质量验证" ;;
+        quality_complete|qa_complete) echo "质量完成" ;;
         release) echo "发布中" ;;
         release_complete) echo "发布完成" ;;
         completed) echo "已完成" ;;
@@ -143,8 +143,8 @@ get_phase_percentage() {
         epic_complete) echo "30" ;;
         development) echo "40" ;;
         dev_complete) echo "70" ;;
-        qa) echo "80" ;;
-        qa_complete) echo "90" ;;
+        quality|qa) echo "80" ;;
+        quality_complete|qa_complete) echo "90" ;;
         release|release_complete) echo "95" ;;
         completed) echo "100" ;;
         *) echo "0" ;;
@@ -520,4 +520,4 @@ main() {
     fi
 }
 
-main
+main

package/.claude/scripts/recover-workflow.sh

@@ -28,7 +28,7 @@ usage() {
 
 选项:
   -h, --help              显示此帮助信息
-  --from STAGE            从指定阶段重新开始 (init/prd/epic/dev/qa/release)
+  --from STAGE            从指定阶段重新开始 (init/prd/epic/dev/quality/release, qa 兼容)
   --force                 强制恢复，跳过安全检查
   --dry-run               显示恢复计划但不执行
   --verbose               显示详细信息
@@ -38,7 +38,7 @@ usage() {
   prd       - PRD生成阶段
   epic      - Epic规划阶段
   dev       - 开发执行阶段
-  qa        - 质量保证阶段
+  quality   - 质量验证阶段
   release   - 发布管理阶段
 
 示例:
@@ -251,17 +251,17 @@ analyze_recovery_strategy() {
                     echo -e "${CYAN}建议: 继续开发 (恢复未完成任务)${NC}"
                     echo "dev"
                 else
-                    echo -e "${CYAN}建议: 进入 QA 阶段${NC}"
-                    echo "qa"
+                    echo -e "${CYAN}建议: 进入质量验证阶段${NC}"
+                    echo "quality"
                 fi
             else
                 echo -e "${CYAN}建议: 从开发阶段开始${NC}"
                 echo "dev"
             fi
             ;;
-        qa|qa_complete)
-            echo -e "${CYAN}建议: 从 QA 阶段开始${NC}"
-            echo "qa"
+        quality|quality_complete|qa|qa_complete)
+            echo -e "${CYAN}建议: 从质量验证阶段开始${NC}"
+            echo "quality"
             ;;
         release|release_complete)
             echo -e "${CYAN}建议: 从发布阶段开始${NC}"
@@ -284,12 +284,12 @@ validate_stage() {
     local stage="$1"
 
     case "$stage" in
-        init|prd|epic|dev|qa|release)
+        init|prd|epic|dev|quality|qa|release)
             return 0
             ;;
         *)
             echo -e "${RED}错误: 无效的阶段 '$stage'${NC}"
-            echo -e "${YELLOW}有效阶段: init, prd, epic, dev, qa, release${NC}"
+            echo -e "${YELLOW}有效阶段: init, prd, epic, dev, quality, release (qa 兼容)${NC}"
             exit 1
             ;;
     esac
@@ -315,19 +315,19 @@ generate_recovery_plan() {
     local stages=()
     case "$start_stage" in
         init)
-            stages=("init" "prd" "epic" "dev" "qa" "release")
+            stages=("init" "prd" "epic" "dev" "quality" "release")
             ;;
         prd)
-            stages=("prd" "epic" "dev" "qa" "release")
+            stages=("prd" "epic" "dev" "quality" "release")
             ;;
         epic)
-            stages=("epic" "dev" "qa" "release")
+            stages=("epic" "dev" "quality" "release")
             ;;
         dev)
-            stages=("dev" "qa" "release")
+            stages=("dev" "quality" "release")
             ;;
-        qa)
-            stages=("qa" "release")
+        quality|qa)
+            stages=("quality" "release")
             ;;
         release)
             stages=("release")
@@ -351,8 +351,8 @@ generate_recovery_plan() {
             dev)
                 command="/flow-dev \"$REQ_ID\" --resume"
                 ;;
-            qa)
-                command="/flow-qa \"$REQ_ID\" --full"
+            quality)
+                command="/flow-quality \"$REQ_ID\""
                 ;;
             release)
                 command="/flow-release \"$REQ_ID\""
@@ -397,29 +397,29 @@ execute_recovery() {
             echo "/flow-prd \"$REQ_ID\""
             echo "/flow-epic \"$REQ_ID\""
             echo "/flow-dev \"$REQ_ID\""
-            echo "/flow-qa \"$REQ_ID\" --full"
+            echo "/flow-quality \"$REQ_ID\""
             echo "/flow-release \"$REQ_ID\""
             ;;
         prd)
             echo "/flow-prd \"$REQ_ID\""
             echo "/flow-epic \"$REQ_ID\""
             echo "/flow-dev \"$REQ_ID\""
-            echo "/flow-qa \"$REQ_ID\" --full"
+            echo "/flow-quality \"$REQ_ID\""
             echo "/flow-release \"$REQ_ID\""
             ;;
         epic)
             echo "/flow-epic \"$REQ_ID\""
             echo "/flow-dev \"$REQ_ID\""
-            echo "/flow-qa \"$REQ_ID\" --full"
+            echo "/flow-quality \"$REQ_ID\""
             echo "/flow-release \"$REQ_ID\""
             ;;
         dev)
             echo "/flow-dev \"$REQ_ID\" --resume"
-            echo "/flow-qa \"$REQ_ID\" --full"
+            echo "/flow-quality \"$REQ_ID\""
             echo "/flow-release \"$REQ_ID\""
             ;;
-        qa)
-            echo "/flow-qa \"$REQ_ID\" --full"
+        quality|qa)
+            echo "/flow-quality \"$REQ_ID\""
             echo "/flow-release \"$REQ_ID\""
             ;;
         release)
@@ -463,4 +463,4 @@ main() {
 }
 
 # 运行主逻辑
-main
+main

package/.claude/skills/workflow/flow-init/SKILL.md

@@ -50,7 +50,14 @@ description: 'Initialize requirement structure with brainstorming and research.
 # 计算路径
 REPO_NAME=$(basename $(git rev-parse --show-toplevel))
 WORKTREE_DIR="../${REPO_NAME}-${REQ_ID}"
-BRANCH_NAME="feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}"
+
+# 分支前缀按类型决定
+if [[ "${REQ_ID}" =~ ^BUG- ]]; then
+  BRANCH_PREFIX="bugfix"
+else
+  BRANCH_PREFIX="feature"
+fi
+BRANCH_NAME="${BRANCH_PREFIX}/${REQ_ID}-${slug(BRANCH_TITLE_EN)}"
 
 # 创建 worktree + 分支
 git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR"

package/.claude/skills/workflow/flow-quality/SKILL.md

@@ -70,6 +70,9 @@ version: 3.0.0
   ✓ Lint Check
   ✓ Type Check
   ✓ Unit Tests
+Reports Generated (when REQ-ID resolved):
+  - TEST_REPORT.md
+  - SECURITY_REPORT.md
 ```
 
 ### Full Mode
@@ -79,6 +82,7 @@ Reports Generated:
   - SPEC_REVIEW.md
   - CODE_QUALITY_REVIEW.md
   - SECURITY_REPORT.md
+  - TEST_REPORT.md
 ```
 
 ## Deprecation Notice

package/.claude/skills/workflow/flow-release/SKILL.md

@@ -29,12 +29,19 @@ description: 'Create PR and manage release. Usage: /flow-release "REQ-123" or /f
 | C) Squash merge | 多提交合并为一 | `gh pr merge --squash` |
 | D) Cleanup only | 工作被废弃 | `git branch -D` |
 
+## Merge Semantics
+
+- A) Fast-forward: 直接合并到 `main`
+- B) Create PR: 仅创建/更新 PR，不自动合并
+- C) Squash merge: 通过 PR squash 合并到 `main`
+- D) Cleanup only: 不合并，仅清理
+
 ## Entry Gate
 
 1. **PRD.md, TECH_DESIGN.md, EPIC.md, TASKS.md** 存在
 2. **TEST_REPORT.md, SECURITY_REPORT.md** Gate 均为 PASS
-3. **Status**: `qa_complete` 或 `release_failed`
-4. **Git**: 工作区干净，在 feature/bugfix 分支
+3. **Status**: `quality_complete`（兼容 `qa_complete`）或 `release_failed`
+4. **Git**: 当前在 feature/bugfix 分支；若工作区不干净，必须先按 `.claude/commands/util/git-commit.md` 完成提交（Conventional Commits + 按同类变更拆分）再继续
 
 ## Execution Flow
 
@@ -51,13 +58,19 @@ description: 'Create PR and manage release. Usage: /flow-release "REQ-123" or /f
 - 生成 RELEASE_PLAN.md
 - 生成 PR 描述草稿
 
-### Stage 3: PR Creation
+### Stage 3: Commit Gate (MANDATORY)
+
+- 检查 `git status --porcelain`
+- 若存在未提交变更，必须先执行 `/util/git-commit`（规则文件 `.claude/commands/util/git-commit.md`）
+- 提交完成后再次确认工作区干净，再进入 PR 创建
+
+### Stage 4: PR Creation
 
 使用 `gh` CLI:
 - 标题: `${REQ_ID}: ${TITLE}`
 - 正文: agent 输出
 
-### Stage 4: Worktree/Branch Cleanup
+### Stage 5: Worktree/Branch Cleanup
 
 **Worktree 模式**:
 ```bash
@@ -91,7 +104,7 @@ git merge --ff-only "$BRANCH_NAME"
 git branch -d "$BRANCH_NAME"
 ```
 
-### Stage 5: Exit Gate
+### Stage 6: Exit Gate
 
 1. RELEASE_PLAN.md 存在
 2. PR 创建成功