cc-devflow 2.4.6 → 4.1.0

package/.claude/skills/domain/using-git-worktrees/scripts/worktree-list.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# =============================================================================
+# worktree-list.sh - List all git worktrees
+# =============================================================================
+#
+# Usage: worktree-list.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --verbose, -v       Show detailed information
+#   --help, -h          Show help message
+#
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+JSON_MODE=false
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --json)
+            JSON_MODE=true
+            shift
+            ;;
+        --verbose|-v)
+            VERBOSE=true
+            shift
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: worktree-list.sh [OPTIONS]
+
+List all git worktrees.
+
+OPTIONS:
+  --json              Output in JSON format
+  --verbose, -v       Show detailed information
+  --help, -h          Show help message
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$1'. Use --help for usage." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# =============================================================================
+# Source Common Functions
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMMON_SH="$SCRIPT_DIR/../../../scripts/common.sh"
+
+if [[ -f "$COMMON_SH" ]]; then
+    source "$COMMON_SH"
+fi
+
+# =============================================================================
+# Get Main Repo
+# =============================================================================
+
+MAIN_REPO=$(git rev-parse --show-toplevel 2>/dev/null)
+if [[ -z "$MAIN_REPO" ]]; then
+    echo "ERROR: Not in a git repository" >&2
+    exit 1
+fi
+
+# =============================================================================
+# List Worktrees
+# =============================================================================
+
+if $JSON_MODE; then
+    echo "["
+    first=true
+    while IFS= read -r line; do
+        if [[ "$line" =~ ^worktree ]]; then
+            if ! $first; then
+                echo ","
+            fi
+            first=false
+            path="${line#worktree }"
+        elif [[ "$line" =~ ^HEAD ]]; then
+            head="${line#HEAD }"
+        elif [[ "$line" =~ ^branch ]]; then
+            branch="${line#branch refs/heads/}"
+            # Extract REQ_ID from path
+            req_id=""
+            if [[ "$path" =~ -([A-Z]+-[0-9]+)$ ]]; then
+                req_id="${BASH_REMATCH[1]}"
+            fi
+            printf '{"path":"%s","branch":"%s","head":"%s","req_id":"%s"}' \
+                "$path" "$branch" "$head" "$req_id"
+        elif [[ "$line" =~ ^detached ]]; then
+            branch="(detached)"
+            req_id=""
+            if [[ "$path" =~ -([A-Z]+-[0-9]+)$ ]]; then
+                req_id="${BASH_REMATCH[1]}"
+            fi
+            printf '{"path":"%s","branch":"%s","head":"%s","req_id":"%s"}' \
+                "$path" "$branch" "$head" "$req_id"
+        fi
+    done < <(git worktree list --porcelain)
+    echo ""
+    echo "]"
+else
+    echo "Git Worktrees:"
+    echo ""
+
+    if $VERBOSE; then
+        git worktree list --porcelain | while IFS= read -r line; do
+            if [[ "$line" =~ ^worktree ]]; then
+                path="${line#worktree }"
+                echo "Path:   $path"
+            elif [[ "$line" =~ ^HEAD ]]; then
+                echo "HEAD:   ${line#HEAD }"
+            elif [[ "$line" =~ ^branch ]]; then
+                echo "Branch: ${line#branch refs/heads/}"
+                echo ""
+            elif [[ "$line" =~ ^detached ]]; then
+                echo "Branch: (detached)"
+                echo ""
+            fi
+        done
+    else
+        git worktree list
+    fi
+fi

package/.claude/skills/domain/using-git-worktrees/scripts/worktree-status.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# =============================================================================
+# worktree-status.sh - Check current worktree status
+# =============================================================================
+#
+# Usage: worktree-status.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --help, -h          Show help message
+#
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+JSON_MODE=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --json)
+            JSON_MODE=true
+            shift
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: worktree-status.sh [OPTIONS]
+
+Check current worktree status.
+
+OPTIONS:
+  --json              Output in JSON format
+  --help, -h          Show help message
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$1'. Use --help for usage." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# =============================================================================
+# Source Common Functions
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMMON_SH="$SCRIPT_DIR/../../../scripts/common.sh"
+
+if [[ -f "$COMMON_SH" ]]; then
+    source "$COMMON_SH"
+fi
+
+# =============================================================================
+# Gather Information
+# =============================================================================
+
+CURRENT_DIR=$(pwd)
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+
+if [[ -z "$GIT_ROOT" ]]; then
+    if $JSON_MODE; then
+        printf '{"error":"not_git_repo"}\n'
+    else
+        echo "ERROR: Not in a git repository" >&2
+    fi
+    exit 1
+fi
+
+# Check if in worktree
+IS_WORKTREE=false
+MAIN_REPO=""
+WORKTREE_COUNT=0
+
+# Get worktree info
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+if [[ "$GIT_DIR" == *".git/worktrees/"* ]]; then
+    IS_WORKTREE=true
+    # Extract main repo path from gitdir file
+    MAIN_REPO=$(cat "$GIT_ROOT/.git" 2>/dev/null | sed 's/gitdir: //' | sed 's|/.git/worktrees/.*||')
+else
+    MAIN_REPO="$GIT_ROOT"
+fi
+
+# Count worktrees
+WORKTREE_COUNT=$(git worktree list | wc -l | tr -d ' ')
+
+# Get current branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+
+# Extract REQ_ID from path or branch
+REQ_ID=""
+if [[ "$GIT_ROOT" =~ -([A-Z]+-[0-9]+)$ ]]; then
+    REQ_ID="${BASH_REMATCH[1]}"
+elif [[ "$BRANCH" =~ (REQ-[0-9]+|BUG-[0-9]+) ]]; then
+    REQ_ID="${BASH_REMATCH[1]}"
+fi
+
+# Check git status
+HAS_CHANGES=false
+if [[ -n $(git status --porcelain 2>/dev/null) ]]; then
+    HAS_CHANGES=true
+fi
+
+# =============================================================================
+# Output
+# =============================================================================
+
+if $JSON_MODE; then
+    printf '{"current_dir":"%s","git_root":"%s","is_worktree":%s,"main_repo":"%s","branch":"%s","req_id":"%s","worktree_count":%d,"has_changes":%s}\n' \
+        "$CURRENT_DIR" \
+        "$GIT_ROOT" \
+        "$IS_WORKTREE" \
+        "$MAIN_REPO" \
+        "$BRANCH" \
+        "$REQ_ID" \
+        "$WORKTREE_COUNT" \
+        "$HAS_CHANGES"
+else
+    echo "Worktree Status"
+    echo "==============="
+    echo ""
+    echo "Current Directory: $CURRENT_DIR"
+    echo "Git Root:          $GIT_ROOT"
+    echo "Is Worktree:       $IS_WORKTREE"
+    echo "Main Repo:         $MAIN_REPO"
+    echo "Branch:            $BRANCH"
+    if [[ -n "$REQ_ID" ]]; then
+        echo "Requirement ID:    $REQ_ID"
+    fi
+    echo "Total Worktrees:   $WORKTREE_COUNT"
+    echo "Has Changes:       $HAS_CHANGES"
+    echo ""
+
+    if $IS_WORKTREE; then
+        echo "You are in a worktree. Main repo is at: $MAIN_REPO"
+    else
+        echo "You are in the main repository."
+    fi
+fi

package/.claude/skills/domain/using-git-worktrees/scripts/worktree-switch.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# =============================================================================
+# worktree-switch.sh - Switch to a worktree by REQ_ID
+# =============================================================================
+#
+# Usage: worktree-switch.sh REQ_ID
+#
+# This script outputs the path to switch to. Use with:
+#   cd $(worktree-switch.sh REQ-123)
+#
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -e
+
+REQ_ID=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --help|-h)
+            cat << 'EOF'
+Usage: worktree-switch.sh REQ_ID
+
+Switch to a worktree by REQ_ID.
+
+This script outputs the path to switch to. Use with:
+  cd $(worktree-switch.sh REQ-123)
+
+Or use the zw shell function:
+  zw REQ-123
+EOF
+            exit 0
+            ;;
+        -*)
+            echo "ERROR: Unknown option '$1'. Use --help for usage." >&2
+            exit 1
+            ;;
+        *)
+            REQ_ID="$1"
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$REQ_ID" ]]; then
+    echo "ERROR: REQ_ID is required. Use --help for usage." >&2
+    exit 1
+fi
+
+# Normalize to uppercase
+REQ_ID=$(echo "$REQ_ID" | tr '[:lower:]' '[:upper:]')
+
+# =============================================================================
+# Find Worktree
+# =============================================================================
+
+MAIN_REPO=$(git rev-parse --show-toplevel 2>/dev/null)
+if [[ -z "$MAIN_REPO" ]]; then
+    echo "ERROR: Not in a git repository" >&2
+    exit 1
+fi
+
+REPO_NAME=$(basename "$MAIN_REPO")
+WORKTREE_DIR="$(dirname "$MAIN_REPO")/${REPO_NAME}-${REQ_ID}"
+
+if [[ -d "$WORKTREE_DIR" ]]; then
+    echo "$WORKTREE_DIR"
+else
+    echo "ERROR: Worktree not found: $WORKTREE_DIR" >&2
+    exit 1
+fi

package/.claude/skills/skill-rules.json

@@ -264,6 +264,77 @@
                     "should I.*?(test first|write implementation)"
                 ]
             }
+        },
+        "journey-coherence-checker": {
+            "type": "domain",
+            "enforcement": "suggest",
+            "priority": "high",
+            "description": "Use when completing a requirement, checking milestone progress, or asking about project status. Detects gaps between requirements, unmet dependencies, and cumulative scope drift.",
+            "promptTriggers": {
+                "keywords": [
+                    "需求完成",
+                    "REQ完成",
+                    "里程碑",
+                    "milestone",
+                    "项目进度",
+                    "可以发布",
+                    "发布前检查",
+                    "全局检查",
+                    "M1进度",
+                    "M2进度",
+                    "M3进度",
+                    "M4进度",
+                    "所有需求",
+                    "依赖满足",
+                    "journey check",
+                    "coherence check"
+                ],
+                "intentPatterns": [
+                    "(需求|REQ|requirement).*?(完成|done|finished)",
+                    "(里程碑|milestone).*?(进度|status|完成)",
+                    "(项目|project).*?(进度|status|如何)",
+                    "(可以|ready).*?(发布|release)",
+                    "(所有|all).*?(需求|requirement).*?(完成|done)",
+                    "(检查|check).*?(全局|global|依赖|dependency)"
+                ]
+            },
+            "fileTriggers": {
+                "pathPatterns": [
+                    "devflow/ROADMAP.md",
+                    "devflow/requirements/**/orchestration_status.json"
+                ]
+            }
+        },
+        "npm-release": {
+            "type": "domain",
+            "enforcement": "suggest",
+            "priority": "high",
+            "description": "Standardized release process for cc-devflow npm package. Handles version bumping, changelog updates, and publishing checks.",
+            "promptTriggers": {
+                "keywords": [
+                    "publish npm",
+                    "release version",
+                    "npm publish",
+                    "bump version",
+                    "new release",
+                    "publish package",
+                    "update changelog",
+                    "release workflow"
+                ],
+                "intentPatterns": [
+                    "(publish|release).*?(npm|package|version)",
+                    "(bump|update).*?(version|semver)",
+                    "(create|generate).*?(release|changelog)",
+                    "ready to publish",
+                    "deploy to npm"
+                ]
+            },
+            "fileTriggers": {
+                "pathPatterns": [
+                    "package.json",
+                    "CHANGELOG.md"
+                ]
+            }
         }
     },
     "notes": {
@@ -285,4 +356,4 @@
             "skip_conditions": "All guardrails support session skip, file markers, and env override"
         }
     }
-}
+}

package/.claude/skills/utility/journey-checker/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: journey-coherence-checker
+description: "Use when completing a requirement, checking milestone progress, or asking about project status. Detects gaps between requirements, unmet dependencies, and cumulative scope drift."
+---
+
+# Journey Coherence Checker
+
+## The Iron Law
+
+```
+STATUS COMPLETE ≠ DEPENDENCY SATISFIED
+CODE EXISTS ≠ JOURNEY WORKS
+REQUIREMENTS DONE ≠ VISION ACHIEVED
+```
+
+## Overview
+
+单需求验证只检查"这个需求内部是否一致"。
+本 Skill 检查"所有需求加起来是否等于愿景"。
+
+```
+问题:
+  REQ-001 ✅ + REQ-002 ✅ + REQ-003 ✅ = 愿景 ❓
+
+现实:
+  每个需求"稍微偏差" × N = 巨大偏差
+  需求间的"空隙"没人负责
+  最终产品 ≠ 初始愿景
+```
+
+## When to Use
+
+```dot
+digraph when {
+    "触发场景" [shape=box];
+    "需求完成时" [shape=box];
+    "检查里程碑时" [shape=box];
+    "询问项目进度时" [shape=box];
+    "发布前" [shape=box];
+
+    "触发场景" -> "需求完成时";
+    "触发场景" -> "检查里程碑时";
+    "触发场景" -> "询问项目进度时";
+    "触发场景" -> "发布前";
+}
+```
+
+**触发关键词**:
+- "需求完成了"、"REQ-XXX 做完了"
+- "M1/M2/M3/M4 进度"、"里程碑完成了吗"
+- "项目进度如何"、"可以发布了吗"
+- "所有需求都完成了"
+
+## Coherence Check Protocol
+
+### Step 1: 读取最小上下文 (< 200 tokens)
+
+```yaml
+read:
+  - ROADMAP.md: 只读 Milestone 的 Success Criteria 段落
+  - orchestration_status.json: 只读 status, dependencies, roadmap_item 字段
+  - PRD.md: 只读 User Stories 标题列表（不读内容）
+```
+
+**禁止**: 读取完整文档。上下文越多，偏差越大。
+
+### Step 2: 依赖满足检查
+
+```
+对于每个声明的依赖:
+  1. 找到依赖的 REQ
+  2. 读取依赖 REQ 的 contracts/ 或 TECH_DESIGN.md 的"输出"章节
+  3. 读取当前 REQ 的 PRD.md 的"输入假设"章节
+  4. 比较: 输出 ⊇ 输入期望？
+
+  如果不匹配:
+    → 报告: "依赖 RM-XXX 的输出不满足 REQ-YYY 的输入期望"
+    → 具体说明: 期望 X，实际提供 Y
+```
+
+### Step 3: 旅程完整性检查
+
+```
+对于 ROADMAP 中的每个 Milestone:
+  1. 读取 Success Criteria
+  2. 对于每个 Criterion:
+     - 找到负责的 REQ
+     - 验证 REQ 的实现是否满足 Criterion
+     - 不是看状态，是看实际输出
+
+  如果有 Criterion 未满足:
+    → 报告: "M4 Success Criteria 'X' 未满足"
+    → 具体说明: 需要 A，实际只有 B
+```
+
+### Step 4: 空隙检测
+
+```
+对于 ROADMAP 中的每个用户旅程:
+  1. 列出旅程的所有步骤
+  2. 对于每个步骤:
+     - 找到负责的 REQ
+     - 如果没有 REQ 负责 → 空隙
+  3. 对于相邻步骤:
+     - 检查步骤 N 的输出是否是步骤 N+1 的输入
+     - 如果不匹配 → 空隙
+
+  如果发现空隙:
+    → 报告: "旅程步骤 X 和 Y 之间存在空隙"
+    → 具体说明: X 输出 A，Y 期望 B，没有 REQ 负责转换
+```
+
+### Step 5: 累积偏差检测
+
+```
+对于每个 Milestone:
+  1. 读取 ROADMAP 中的原始 Deliverables
+  2. 读取每个 REQ 的 PRD 中的实际 Scope
+  3. 计算: 实际覆盖 / 原始计划
+
+  如果覆盖率 < 80%:
+    → 报告: "M4 累积偏差 40%，原始计划 7 项，实际覆盖 4 项"
+    → 列出: 被削减的 Deliverables
+```
+
+## Output Format
+
+```markdown
+## Journey Coherence Report
+
+### 依赖满足 ✅/❌
+| 依赖 | 期望输入 | 实际输出 | 状态 |
+|------|---------|---------|------|
+| RM-007 | CommandEmitter API | ✅ 提供 | PASS |
+| RM-006 | AdapterRegistry | ✅ 提供 | PASS |
+
+### 旅程完整性 ✅/❌
+| 旅程 | 步骤 | 负责 REQ | 状态 |
+|------|------|---------|------|
+| 开发者旅程 | /flow-init | REQ-001 | ✅ |
+| 开发者旅程 | /flow-prd | REQ-002 | ✅ |
+| 开发者旅程 | /flow-dev → /flow-release | ❓ | ⚠️ 空隙 |
+
+### Success Criteria ✅/❌
+| Milestone | Criterion | 验证结果 | 状态 |
+|-----------|-----------|---------|------|
+| M4 | 4 platforms execute core workflows | 2/4 platforms | ❌ FAIL |
+| M4 | Integration tests passing | 未运行 | ❌ FAIL |
+
+### 累积偏差
+| Milestone | 原始计划 | 实际覆盖 | 偏差率 |
+|-----------|---------|---------|--------|
+| M4 | 7 deliverables | 4 deliverables | 43% |
+
+### 建议
+1. 补充 RM-009/010/011/012 的实现
+2. 添加端到端集成测试
+3. 定义 /flow-dev → /flow-release 的衔接 REQ
+```
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "依赖已经标记完成了" | 完成 ≠ 满足。检查实际输出是否匹配期望输入。 |
+| "每个需求都通过了验证" | 单需求验证 ≠ 全局一致性。部分之和 ≠ 整体。 |
+| "ROADMAP 是规划，不是承诺" | Success Criteria 是承诺。不满足就是未完成。 |
+| "这超出了我的检查范围" | 这正是你的检查范围。全局一致性是隐含要求。 |
+| "状态是 complete" | 状态是自我声明。验证是外部检查。 |
+| "代码存在" | 存在 ≠ 能跑。运行验证才算数。 |
+| "用户没有要求检查全局" | 全局检查是隐含要求。用户问"完成了吗"就是在问全局。 |
+| "我已经检查了很多了" | 检查多 ≠ 检查对。按 Protocol 检查。 |
+
+## Red Flags - STOP
+
+如果你发现自己：
+- 只看 `orchestration_status.json` 的 `status` 字段就说"完成了"
+- 没有比较依赖的输出和当前需求的输入期望
+- 没有验证 Success Criteria 的每一条
+- 没有检查旅程步骤之间的衔接
+- 数 REQ 数量而不是验证实际功能
+
+**STOP。执行 Coherence Check Protocol。**
+
+## Integration
+
+### 触发点
+- `/flow-release` Exit Gate（发布前强制检查）
+- `/flow-verify --global`（全局验证模式）
+- 用户询问里程碑进度时
+
+### 与其他 Skill 的关系
+- `flow-verify`: 单需求内部一致性 → 本 Skill: 跨需求全局一致性
+- `constitution-guardian`: 代码质量 → 本 Skill: 业务完整性
+- `flow-attention-refresh`: 防止单需求目标遗忘 → 本 Skill: 防止全局愿景遗忘
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md