cc-devflow 4.1.3 → 4.1.4

package/.claude/CLAUDE.md

@@ -52,7 +52,9 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 │   └── types/
 │       └── team-types.d.ts      # Team 状态类型定义 [NEW: v4.7]
 ├── scripts/                   # 共享脚本
-│   └── common.sh              # 通用函数 (含 worktree 辅助函数)
+│   ├── CLAUDE.md              # scripts 子目录地图（成员清单与职责边界）
+│   ├── common.sh              # 通用函数 (含 worktree 辅助函数)
+│   └── flow-workspace-switch.sh # workspace REQ 切换与 worktree 快捷切换
 └── docs/templates/            # 共享模板
     └── _shared/               # 共享模板组件 [NEW: v4.1]
         ├── CONSTITUTION_CHECK.md
@@ -1217,4 +1219,3 @@ ralph_loop:
 
 **Last Updated**: 2026-02-07
 **v4.7.0 Module**: Claude Team Integration
-

package/.claude/commands/flow/init.md

@@ -21,7 +21,7 @@ skill: workflow/flow-init
 | Stage | Purpose | Output |
 |-------|---------|--------|
 | 1 | Entry Gate | 参数验证 |
-| 1.2 | Git Branch | feature/REQ-xxx-title |
+| 1.2 | Git Worktree (默认) / Branch (--branch-only) | `../{repo}-{REQ_ID}` + `feature|bugfix/{REQ_ID}-{slug}` |
 | 1.5 | Context Loading | ROADMAP/ARCHITECTURE |
 | 2 | Directory Init | 目录结构 |
 | 2.3 | Brainstorming | BRAINSTORM.md |
@@ -29,6 +29,21 @@ skill: workflow/flow-init
 | 3 | README | README.md |
 | 4 | Exit Gate | 5-Level 验证 |
 
+## Worktree Naming
+
+- 默认模式会创建独立 worktree（不是只建分支）。
+- 目录命名：`{repo-name}-{REQ_ID}`（示例：`cc-devflow-REQ-123`）。
+- 分支命名：
+  - Requirement: `feature/{REQ_ID}-{slug(title)}`
+  - Bug: `bugfix/{REQ_ID}-{slug(title)}`
+- `--branch-only` 才会退回传统单仓库分支模式。
+
+## Session Continuity
+
+- 需求上下文由 `devflow/requirements/${REQ_ID}/` 下的文档和 `orchestration_status.json` 持久化。
+- REQ 识别优先级：`DEVFLOW_REQ_ID` → worktree 目录名 → 当前分支名。
+- 进入新会话时，应先进入目标 worktree 目录再继续命令；worktree 路径可按命名规则直接定位，或使用 `using-git-worktrees` 的切换脚本。
+
 ## Skill Location
 
 **Full Implementation**: `.claude/skills/workflow/flow-init/SKILL.md`

package/.claude/commands/flow/release.md

@@ -43,6 +43,13 @@ skills:
   - 是否需要 CI 验证 (生产代码 → PR)
 ```
 
+## 合并语义（关键）
+
+- `A) Fast-forward merge`：会在本地直接合并到 `main`。
+- `B) Create PR`：只创建/更新 PR，不会在当前步骤自动合并到 `main`。
+- `C) Squash and merge`：会通过 PR squash 合并到 `main`（通常在评审/CI 通过后执行）。
+- `D) Cleanup only`：不会合并，只清理分支/worktree。
+
 ## User Input
 ```text
 $ARGUMENTS = "REQ_ID?"
@@ -61,8 +68,12 @@ $ARGUMENTS = "REQ_ID?"
 4. 验证 Quality gate:
    → TEST_REPORT.md / SECURITY_REPORT.md 中的 Gate 均为 PASS
 5. Git 环境:
-   → 工作区干净、当前在 feature/bugfix 分支
+   → 当前在 feature/bugfix 分支
    → 分支已推送，若无 upstream 提示 push
+6. Commit 规范门禁（工作区不干净时）:
+   → 必须先执行 `/util/git-commit`（规则见 `.claude/commands/util/git-commit.md`）
+   → Commit message 必须遵循 Conventional Commits；多文件按同类变更拆分提交
+   → 提交完成后重新执行 Entry Gate，直到工作区干净
 ```
 
 ### 阶段 2: 发布上下文准备
@@ -92,17 +103,29 @@ Prompt 核心要求:
 
 ### 阶段 4: PR 创建与完结
 ```
-1. 使用 gh CLI 创建或更新 PR
+1. PR 前提交检查:
+   → 若 `git status --porcelain` 非空，立即中止并回到 Entry Gate 第 6 步执行 `/util/git-commit`
+2. 使用 gh CLI 创建或更新 PR
    → 标题: "${REQ_ID}: ${TITLE}"
    → 正文采用 agent 输出
-2. 检查 CLAUDE.md：
+3. 检查 CLAUDE.md：
    → 若 TECH_DESIGN 引入新基础设施/重大变更，更新 "## Technical Architecture"（≤15 行）
-3. 状态更新:
+4. 状态更新:
    → orchestration_status.status = "release_complete"
    → completedSteps append "release"
    → prUrl 记录到状态文件
-4. EXECUTION_LOG 记录 PR 链接与发布时间
-5. 可选: {SCRIPT:generate_status} 生成状态报告
+5. EXECUTION_LOG 记录 PR 链接与发布时间
+6. 可选: {SCRIPT:generate_status} 生成状态报告
+```
+
+### 阶段 5: Worktree 清理策略
+```
+1. 若当前为 worktree 模式:
+   → 仅在分支已合并（或明确放弃该分支）后执行 `git worktree remove`
+2. 若仅创建 PR 且尚未合并:
+   → 默认保留 worktree，等待后续评审/CI
+3. 若已完成合并:
+   → 删除 worktree + 删除已合并分支
 ```
 
 ## 输出
@@ -118,6 +141,7 @@ Prompt 核心要求:
 - Quality Gate 失败或 Constitution ERROR → 立即终止，标记 status="release_failed"。
 - Git push/PR 创建失败 → 输出命令和日志，保持可重试状态。
 - CLAUDE.md 更新遗漏 → 阻断发布并提示补写。
+- 工作区存在未提交改动且未按 `/util/git-commit` 规则处理 → 阻断发布。
 
 ## 下一步
 1. 等待代码评审与 CI 通过。

package/.claude/commands/flow/workspace.md

@@ -20,13 +20,16 @@ Enables context recovery across sessions and tracks development progress.
 /flow-workspace init [developer]
 
 # Start session (recover context)
-/flow-workspace start
+/flow-workspace start [REQ-XXX|BUG-XXX]
+/flow-workspace start REQ-XXX --switch
+/flow-workspace start BUG-XXX --switch --cd  # 需 source/eval 场景
 
 # Record progress to journal
 /flow-workspace record "message"
 
 # Switch to different requirement
 /flow-workspace switch REQ-XXX
+/flow-workspace switch BUG-XXX --cd            # 需 source/eval 场景
 ```
 
 ## Subcommands
@@ -53,13 +56,20 @@ Start a new session, recovering context from previous session.
 
 ```bash
 /flow-workspace start
+/flow-workspace start REQ-008 --switch
+/flow-workspace start BUG-008 --switch
 ```
 
 Process:
 1. Read `.current-req` to get current requirement
 2. Read latest journal entries
-3. Display context summary
-4. Ready to continue work
+3. 校验并显示期望 worktree 路径（提示是否在正确目录）
+4. Display context summary
+5. Ready to continue work
+
+可选行为:
+- 传入 `REQ-XXX/BUG-XXX` 会先更新 `.current-req` 再恢复上下文
+- `--switch` 输出切换建议；`--cd` 在脚本被 `source` 时可直接切换目录
 
 ### record
 
@@ -77,9 +87,21 @@ Switch to a different requirement.
 
 ```bash
 /flow-workspace switch REQ-008
+/flow-workspace switch REQ-008 --cd
 ```
 
 Updates `.current-req` and creates a new journal entry.
+如果存在对应 worktree，建议立即切换到：
+```bash
+cd "$(bash .claude/skills/domain/using-git-worktrees/scripts/worktree-switch.sh REQ-008)"
+```
+
+更便捷的一步切换:
+```bash
+eval "$(bash .claude/scripts/flow-workspace-switch.sh REQ-008 --print-cd)"
+# 或
+source .claude/scripts/flow-workspace-switch.sh REQ-008 --cd
+```
 
 ## Workspace Structure
 
@@ -116,12 +138,15 @@ devflow/workspace/
 
 ### With flow-init
 
-When `/flow-init` creates a new requirement:
+When `/flow-init` creates a new requirement (and workspace already initialized):
 ```bash
 # Auto-update workspace
 echo "REQ-XXX" > devflow/workspace/{developer}/.current-req
 ```
 
+`/flow-workspace start` 会基于 REQ-ID 推导期望 worktree 路径：
+`../{repo-name}-{REQ_ID}`，并提示是否已在正确 worktree。
+
 ### With flow-dev
 
 During development, progress is automatically recorded:
@@ -138,6 +163,7 @@ Journal is read at Protocol 3 (Ralph iteration start) to maintain context.
 - `.claude/scripts/flow-workspace-init.sh` - Initialize workspace
 - `.claude/scripts/flow-workspace-start.sh` - Start session
 - `.claude/scripts/flow-workspace-record.sh` - Record progress
+- `.claude/scripts/flow-workspace-switch.sh` - Switch REQ pointer and worktree action
 
 ## Related
 

package/.claude/scripts/CLAUDE.md

@@ -0,0 +1,79 @@
+# scripts/
+> L2 | 父级: .claude/CLAUDE.md
+>
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+## 目录定位
+
+`.claude/scripts/` 是命令层与 Skill 层共享的执行脚本库，负责状态检测、质量门禁、需求目录操作与会话恢复。
+
+## 成员清单
+
+analyze-upgrade-impact.sh: 升级影响分析脚本。
+archive-requirement.sh: 需求归档与清理脚本。
+calculate-checklist-completion.sh: Checklist 完成度统计脚本。
+calculate-quarter.sh: 时间季度计算脚本。
+check-dependencies.sh: 依赖关系检查脚本。
+check-prerequisites.sh: 流程前置条件统一校验脚本。
+check-task-status.sh: TASKS 完成状态统计脚本。
+checklist-errors.sh: Checklist 错误码与诊断脚本。
+common.sh: 脚本公共函数库（REQ 识别、worktree 路径、日志工具等）。
+consolidate-research.sh: research 结果汇总脚本。
+create-requirement.sh: 创建需求目录与初始状态；同步 workspace 的 `.current-req`。
+delta-parser.ts: Delta 解析器。
+detect-file-conflicts.sh: 并行开发文件冲突检测脚本。
+export-contracts.sh: 合同文档导出脚本。
+extract-data-model.sh: 数据模型抽取脚本。
+flow-context-add.sh: context JSONL 条目追加脚本。
+flow-context-init.sh: context 目录初始化脚本。
+flow-context-validate.sh: context 路径验证脚本。
+flow-delta-apply.sh: Delta 应用脚本。
+flow-delta-archive.sh: Delta 归档脚本。
+flow-delta-create.sh: Delta 创建脚本。
+flow-delta-list.sh: Delta 列表脚本。
+flow-delta-status.sh: Delta 状态脚本。
+flow-quality-full.sh: 全量质量检查脚本。
+flow-quality-quick.sh: 快速质量检查脚本。
+flow-workspace-init.sh: 开发者 workspace 初始化脚本。
+flow-workspace-record.sh: workspace journal 追加记录脚本。
+flow-workspace-start.sh: workspace 会话恢复脚本；支持 REQ 覆盖与 worktree 切换提示。
+flow-workspace-switch.sh: workspace REQ 切换脚本；支持 `--print-cd` 与 `--cd`。
+generate-clarification-questions.sh: Clarify 问题生成脚本。
+generate-clarification-report.sh: Clarify 报告生成脚本。
+generate-quickstart.sh: quickstart 文档生成脚本。
+generate-research-tasks.sh: research 任务生成脚本。
+generate-status-report.sh: 状态报告聚合脚本。
+generate-tech-analysis.sh: 技术分析生成脚本。
+get-workflow-status.sh: 工作流状态读取脚本。
+locate-requirement-in-roadmap.sh: roadmap 需求定位脚本。
+manage-constitution.sh: Constitution 管理脚本。
+mark-task-complete.sh: 任务完成标记脚本。
+parse-task-dependencies.js: 任务依赖解析器。
+populate-research-tasks.sh: research 任务填充脚本。
+record-quality-error.sh: 质量错误记录脚本。
+recover-workflow.sh: 中断恢复脚本。
+run-clarify-scan.sh: Clarify 扫描执行脚本。
+run-high-review.sh: 高强度 review 执行脚本。
+run-problem-analysis.sh: 问题分析执行脚本。
+run-quality-gates.sh: 质量门禁执行脚本。
+setup-epic.sh: Epic 初始化脚本。
+setup-ralph-loop.sh: Ralph Loop 初始化脚本。
+sync-roadmap-progress.sh: roadmap 进度同步脚本。
+sync-task-marks.sh: TASKS 勾选同步脚本。
+team-dev-init.sh: Team 开发并行初始化脚本。
+team-state-recovery.sh: Team 状态恢复脚本。
+test-clarify-scan.sh: Clarify 扫描测试脚本。
+update-agent-context.sh: Agent 上下文更新脚本。
+validate-constitution.sh: Constitution 校验脚本。
+validate-hooks.sh: Hooks 校验脚本。
+validate-research.sh: research 质量校验脚本。
+validate-scope-boundary.sh: scope 边界校验脚本。
+verify-gate.sh: Gate 校验脚本。
+verify-setup.sh: 环境/安装验证脚本。
+workflow-status.ts: 工作流状态类型化读取器。
+
+## 设计约束
+
+- 需求识别统一复用 `common.sh`，避免多处正则分叉。
+- worktree 与 workspace 职责分离：代码隔离由 worktree 提供，连续上下文由 workspace 提供。
+- 新增脚本优先保持幂等与可重入，便于中断恢复。

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

@@ -402,6 +402,18 @@ if ! $SKIP_GIT && has_git; then
     export DEVFLOW_REQ_ID="$REQ_ID"
 fi
 
+# Sync developer workspace pointer when workspace is initialized.
+# This keeps follow-up sessions aligned to the same requirement.
+DEVELOPER="${DEVFLOW_DEVELOPER:-$(whoami)}"
+DEV_WORKSPACE_DIR="$REPO_ROOT/devflow/workspace/$DEVELOPER"
+if [[ -d "$DEV_WORKSPACE_DIR" ]]; then
+    echo "$REQ_ID" > "$DEV_WORKSPACE_DIR/.current-req"
+    log_event "$REQ_ID" "Workspace pointer updated: $DEVELOPER -> $REQ_ID"
+    if ! $JSON_MODE; then
+        echo "Updated workspace current requirement: $DEVELOPER -> $REQ_ID" >&2
+    fi
+fi
+
 # Output results
 if $JSON_MODE; then
     printf '{"req_id":"%s","req_type":"%s","req_dir":"%s","title":"%s","git_branch":"%s","created_at":"%s"}\n' \

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/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-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**: `quality_complete`（兼容 `qa_complete`）或 `release_failed`
-4. **Git**: 工作区干净，在 feature/bugfix 分支
+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 创建成功

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.1.4] - 2026-02-08
+
+### 🧭 Workspace Worktree Session Recovery & Release Flow Clarity
+
+v4.1.4 strengthens workspace-to-worktree continuity so developers can resume a requirement reliably across sessions, and clarifies flow init/release semantics in command and skill docs.
+
+#### Added
+
+- **Workspace switch script**
+  - Added `.claude/scripts/flow-workspace-switch.sh`
+  - Supports `REQ/BUG` pointer updates, journal logging, `--print-cd`, and sourced `--cd` switching
+
+- **Scripts architecture map**
+  - Added `.claude/scripts/CLAUDE.md` as L2 directory map for script responsibilities
+
+#### Changed
+
+- **Workspace start behavior**
+  - `.claude/scripts/flow-workspace-start.sh` now accepts `REQ-XXX/BUG-XXX` override
+  - Added `--switch` and sourced `--cd` behavior for faster worktree handoff
+  - Added BUG status file compatibility (`devflow/bugs/*/status.json`)
+
+- **Requirement initialization linkage**
+  - `.claude/scripts/create-requirement.sh` now syncs `devflow/workspace/{developer}/.current-req` when workspace exists
+
+- **Flow docs and skills alignment**
+  - Updated flow init/release/workspace command docs and workflow skills to reflect:
+    - default worktree naming semantics
+    - merge semantics by release strategy
+    - workspace continuity expectations
+
+#### Benefits
+
+- ✅ New session recovery can target the intended REQ/BUG directly
+- ✅ Worktree switching is faster and less error-prone via generated `cd` commands
+- ✅ Flow release semantics are clearer when deciding between PR-only vs merge paths
+
 ## [4.1.3] - 2026-02-08
 
 ### 🔧 Flow Quality Default Path + AGENTS.md Safe Emit

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.1.3",
+    "version": "4.1.4",
     "description": "DevFlow CLI tool",
     "main": "bin/cc-devflow.js",
     "bin": {