cc-devflow 4.2.0 → 4.3.0

package/.claude/scripts/validate-scope.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# [INPUT]: 依赖 proposal.md 和 Delta spec.md
+# [OUTPUT]: 生成 scope-creep-report.md
+# [POS]: 反扩散检查脚本，被 /flow:spec 和 /flow:verify 调用
+# [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+set -euo pipefail
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+
+REQ_ID="${1:-}"
+if [[ -z "$REQ_ID" ]]; then
+  error "Usage: validate-scope.sh <REQ-ID>"
+  exit 1
+fi
+
+REQ_DIR="devflow/requirements/${REQ_ID}"
+PROPOSAL_FILE="${REQ_DIR}/proposal.md"
+REPORT_FILE="${REQ_DIR}/scope-creep-report.md"
+
+# ============================================================================
+# Validation
+# ============================================================================
+
+if [[ ! -f "$PROPOSAL_FILE" ]]; then
+  error "proposal.md not found: $PROPOSAL_FILE"
+  exit 1
+fi
+
+# 查找所有 Delta spec.md 文件
+DELTA_SPECS=$(find "${REQ_DIR}/specs" -name "spec.md" 2>/dev/null || true)
+
+if [[ -z "$DELTA_SPECS" ]]; then
+  warn "No Delta specs found in ${REQ_DIR}/specs/"
+  exit 0
+fi
+
+# ============================================================================
+# Extract Original Intent
+# ============================================================================
+
+info "Extracting original intent from proposal.md..."
+
+# 提取 ## What 章节（原始需求描述）
+ORIGINAL_INTENT=$(awk '
+  /^## What/ { flag=1; next }
+  /^## / { flag=0 }
+  flag { print }
+' "$PROPOSAL_FILE" | sed '/^$/d')
+
+if [[ -z "$ORIGINAL_INTENT" ]]; then
+  warn "No 'What' section found in proposal.md"
+  ORIGINAL_INTENT="(No explicit requirements found)"
+fi
+
+# ============================================================================
+# Extract Delta Requirements
+# ============================================================================
+
+info "Extracting ADDED requirements from Delta specs..."
+
+ADDED_REQUIREMENTS=""
+SCOPE_CREEP_COUNT=0
+
+while IFS= read -r delta_file; do
+  module=$(basename "$(dirname "$delta_file")")
+
+  # 提取 ADDED Requirements 章节
+  added=$(awk '
+    /^## ADDED Requirements/ { flag=1; next }
+    /^## / { flag=0 }
+    flag && /^### Requirement:/ { print $0 }
+  ' "$delta_file")
+
+  if [[ -n "$added" ]]; then
+    ADDED_REQUIREMENTS+="
+### Module: $module
+$added
+"
+  fi
+done <<< "$DELTA_SPECS"
+
+# ============================================================================
+# Detect Scope Creep
+# ============================================================================
+
+info "Detecting scope creep..."
+
+# 简单启发式：检查 ADDED 需求中的关键词是否在原始意图中出现
+CREEP_ITEMS=""
+
+while IFS= read -r line; do
+  if [[ "$line" =~ ^###\ Requirement:\ (.+)$ ]]; then
+    req_name="${BASH_REMATCH[1]}"
+
+    # 提取关键词（去除常见词）
+    keywords=$(echo "$req_name" | tr '[:upper:]' '[:lower:]' | \
+      sed -e 's/the //g' -e 's/a //g' -e 's/an //g' -e 's/and //g' | \
+      tr -s ' ' '\n' | grep -v '^$')
+
+    # 检查关键词是否在原始意图中
+    found=false
+    while IFS= read -r keyword; do
+      if echo "$ORIGINAL_INTENT" | grep -qi "$keyword"; then
+        found=true
+        break
+      fi
+    done <<< "$keywords"
+
+    if [[ "$found" == "false" ]]; then
+      CREEP_ITEMS+="- ⚠️ $req_name (not mentioned in original intent)
+"
+      ((SCOPE_CREEP_COUNT++))
+    else
+      CREEP_ITEMS+="- ✅ $req_name
+"
+    fi
+  fi
+done <<< "$ADDED_REQUIREMENTS"
+
+# ============================================================================
+# Generate Report
+# ============================================================================
+
+info "Generating scope-creep-report.md..."
+
+cat > "$REPORT_FILE" <<EOF
+# Scope Creep Report - ${REQ_ID}
+
+> **Generated**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+> **Status**: $([ $SCOPE_CREEP_COUNT -eq 0 ] && echo "✅ No scope creep detected" || echo "⚠️ Potential scope creep detected")
+
+---
+
+## Original Intent (from proposal.md)
+
+${ORIGINAL_INTENT}
+
+---
+
+## Current Delta (from specs/)
+
+${ADDED_REQUIREMENTS:-No ADDED requirements found}
+
+---
+
+## Analysis
+
+${CREEP_ITEMS:-No requirements to analyze}
+
+---
+
+## Summary
+
+- **Total ADDED requirements**: $(echo "$ADDED_REQUIREMENTS" | grep -c "^### Requirement:" || echo 0)
+- **Potential scope creep**: ${SCOPE_CREEP_COUNT}
+
+## Recommendation
+
+EOF
+
+if [[ $SCOPE_CREEP_COUNT -eq 0 ]]; then
+  cat >> "$REPORT_FILE" <<EOF
+✅ All ADDED requirements align with original intent. Safe to proceed.
+EOF
+else
+  cat >> "$REPORT_FILE" <<EOF
+⚠️ ${SCOPE_CREEP_COUNT} requirement(s) may be beyond original scope.
+
+**Action Required**:
+1. Review each ⚠️ marked requirement
+2. If necessary, update proposal.md to include these features
+3. If not necessary, remove from Delta specs
+4. Consider creating separate REQs for additional features
+
+**Constitutional Reference**: Article X - Requirement Boundary
+EOF
+fi
+
+# ============================================================================
+# Output
+# ============================================================================
+
+success "Scope creep report generated: $REPORT_FILE"
+
+if [[ $SCOPE_CREEP_COUNT -gt 0 ]]; then
+  warn "⚠️ Potential scope creep detected: ${SCOPE_CREEP_COUNT} requirement(s)"
+  echo ""
+  echo "Review the report and confirm before proceeding:"
+  echo "  cat $REPORT_FILE"
+  exit 1
+else
+  success "✅ No scope creep detected"
+  exit 0
+fi

package/.claude/skills/{workflow/flow-init → flow-init}/SKILL.md

@@ -53,29 +53,50 @@ description: 'Initialize a requirement with harness state and context package. U
 ## Execution Steps
 
 1. 解析输入，提取 `REQ_ID`、`TITLE`、`PLAN_URLS`。
-2. 组装 goal 文本：
+
+2. **读取项目级 specs/ 了解当前系统状态**（v4.3 新增）：
+   - 读取 `devflow/specs/README.md` 了解模块结构
+   - 扫描 `devflow/specs/*/spec.md` 识别相关模块
+   - 记录当前系统状态到上下文
+
+3. 组装 goal 文本：
    - `Deliver <REQ_ID>: <TITLE>`
    - 若有 URL，追加 `Sources: <URLS>`。
-3. 运行初始化：
+
+4. 运行初始化：
 
 ```bash
 npm run harness:init -- --change-id "${REQ_ID}" --goal "${GOAL}"
 ```
 
-4. 运行上下文打包：
+5. 运行上下文打包：
 
 ```bash
 npm run harness:pack -- --change-id "${REQ_ID}" --goal "${GOAL}"
 ```
 
-5. 验证输出文件：
+6. **生成 proposal.md**（v4.3 新增，替代 PRD.md）：
+   - 基于 TITLE 和 PLAN_URLS 生成 proposal.md
+   - 格式：Why（为什么需要）+ What（要做什么）
+   - 使用 `.claude/docs/templates/PROPOSAL_TEMPLATE.md`
+   - 输出到 `devflow/requirements/${REQ_ID}/proposal.md`
+
+7. **创建 specs/ 目录**（v4.3 新增）：
+   - 创建 `devflow/requirements/${REQ_ID}/specs/` 目录
+   - 准备存放 Delta spec.md
+
+8. 验证输出文件：
    - `devflow/requirements/${REQ_ID}/harness-state.json`
    - `devflow/requirements/${REQ_ID}/context-package.md`
+   - `devflow/requirements/${REQ_ID}/proposal.md` ⭐ 新增
+   - `devflow/requirements/${REQ_ID}/specs/` 目录存在 ⭐ 新增
 
 ## Exit Criteria
 
 - `harness-state.json.status == "initialized"`
 - `context-package.md` 存在并包含 Next Commands 段落
+- `proposal.md` 存在且包含 Why 和 What 章节 ⭐ v4.3 新增
+- `specs/` 目录已创建 ⭐ v4.3 新增
 
 ## Next Step
 

package/.claude/skills/{workflow/flow-release → flow-release}/SKILL.md

@@ -23,25 +23,36 @@ description: 'Release a verified requirement and run runtime cleanup. Use only a
 
 1. 检查 `report-card.json`：
    - `overall` 必须为 `pass`
-2. 运行发布：
+
+2. **合并 Delta specs 到项目级 specs/**（v4.3 新增）：
+   - 检测 `devflow/requirements/${REQ_ID}/specs/` 目录
+   - 遍历所有模块的 Delta spec.md
+   - 调用 `delta-parser.ts merge` 合并到 `devflow/specs/{module}/spec.md`
+   - 自动更新项目级 spec.md 的版本号和时间戳
+   - 记录合并结果到 RELEASE_NOTE.md
+
+3. 运行发布：
 
 ```bash
 npm run harness:release -- --change-id "${REQ_ID}"
 ```
 
-3. 运行熵清理：
+4. 运行熵清理：
 
 ```bash
 npm run harness:janitor -- --hours ${HOURS}
 ```
 
-4. 验证输出：
+5. 验证输出：
    - `devflow/requirements/${REQ_ID}/RELEASE_NOTE.md`
    - `devflow/requirements/${REQ_ID}/harness-state.json` 中 `status == "released"`
+   - 项目级 `devflow/specs/{module}/spec.md` 已更新版本号 ⭐ v4.3 新增
 
 ## Exit Criteria
 
 - 发布文件存在且状态为 released
+- Delta specs 已成功合并到项目级 specs/ ⭐ v4.3 新增
+- 项目级 spec.md 版本号已更新 ⭐ v4.3 新增
 - janitor 执行成功
 
 ## Next Step

package/.claude/skills/{workflow/flow-spec → flow-spec}/SKILL.md

@@ -52,18 +52,46 @@ description: 'Generate and refresh task-manifest for a requirement. Use when con
 ## Execution Steps
 
 1. 解析 `REQ_ID` 和可选 `--overwrite`。
-2. 运行计划生成：
+
+2. **读取项目级 specs/ 了解当前系统状态**（v4.3 新增）：
+   - 读取 `devflow/specs/README.md` 了解模块结构
+   - 扫描 `devflow/specs/*/spec.md` 识别相关模块
+   - 记录当前系统状态到上下文
+
+3. **生成 design.md**（v4.3 新增，替代 TECH_DESIGN.md）：
+   - 基于 `proposal.md` 的 What 章节
+   - 基于项目级 `specs/` 的当前状态
+   - 输出到 `devflow/requirements/${REQ_ID}/design.md`
+   - 格式：How（技术方案）+ Implementation（实现细节）
+
+4. **生成 Delta specs/**（v4.3 新增）：
+   - 基于 `proposal.md` 和 `design.md`
+   - 为每个受影响的模块生成 Delta spec.md
+   - 输出到 `devflow/requirements/${REQ_ID}/specs/{module}/spec.md`
+   - 格式：ADDED/MODIFIED/REMOVED/RENAMED Requirements
+   - 使用 `.claude/docs/templates/SPEC_TEMPLATE_DELTA.md`
+
+5. **自动反扩散检查**（v4.3 新增）：
+   - 运行 `bash .claude/scripts/validate-scope.sh "${REQ_ID}"`
+   - 对比 `proposal.md` 原始意图与 Delta specs 的 ADDED 需求
+   - 生成 `scope-creep-report.md`
+   - 如检测到范围扩散，阻塞并要求人工确认
+
+6. 运行计划生成：
 
 ```bash
 npm run harness:plan -- --change-id "${REQ_ID}" [--overwrite]
 ```
 
-3. 校验输出：
+7. 校验输出：
    - `devflow/requirements/${REQ_ID}/task-manifest.json`
    - `tasks` 数组非空，`id/dependsOn/run` 字段完整
 
 ## Exit Criteria
 
+- `design.md` 存在且包含 How 和 Implementation 章节 ⭐ v4.3 新增
+- `specs/` 目录存在且至少有一个模块的 Delta spec.md ⭐ v4.3 新增
+- `scope-creep-report.md` 存在且无阻塞性警告 ⭐ v4.3 新增
 - `task-manifest.json` 可通过 schema 校验
 - 任务依赖图无自循环（由 planner 保障）
 

package/.claude/skills/utility/npm-release/CLAUDE.md

@@ -0,0 +1,55 @@
+# npm-release Skill
+
+Version management skill with semantic versioning enforcement.
+
+## Structure
+
+```
+npm-release/
+├── SKILL.md                           # Main workflow instructions
+├── scripts/
+│   ├── validate-version-sync.sh       # Check version consistency
+│   ├── version-decision-tree.sh       # Calculate next version
+│   └── atomic-version-bump.sh         # Atomic version update
+└── references/
+    └── version-decision-guide.md      # Detailed SemVer rules
+```
+
+## Purpose
+
+Prevents version chaos by enforcing:
+1. Semantic versioning rules (no arbitrary jumps)
+2. Atomic synchronization (package.json + CHANGELOG.md + git tags)
+3. Format consistency (vX.Y.Z everywhere)
+
+## Key Scripts
+
+### validate-version-sync.sh
+Checks that package.json, git tags, and CHANGELOG.md all have matching versions.
+
+### version-decision-tree.sh
+Enforces SemVer rules:
+- Breaking change → MAJOR (X.0.0)
+- New feature → MINOR (X.Y.0)
+- Bug fix → PATCH (X.Y.Z)
+
+### atomic-version-bump.sh
+Updates all version markers in one transaction, preventing inconsistencies.
+
+## Usage
+
+```bash
+# Validate current state
+bash scripts/validate-version-sync.sh
+
+# Calculate next version
+bash scripts/version-decision-tree.sh 4.2.0 minor
+# Output: 4.3.0
+
+# Atomic bump (recommended)
+bash scripts/atomic-version-bump.sh minor "Add export command"
+```
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/skills/utility/npm-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: npm-release
-description: Use when ready to publish a new version of cc-devflow npm package to npm registry
+description: Use when ready to publish a new version of cc-devflow npm package to npm registry. Enforces semantic versioning rules, prevents arbitrary version jumps (e.g., 3.0.1→7.0.0), and ensures atomic synchronization across package.json, CHANGELOG.md, and git tags.
 ---
 
 # NPM Release Workflow
@@ -9,7 +9,10 @@ description: Use when ready to publish a new version of cc-devflow npm package t
 
 Standardized release process for cc-devflow npm package ensuring consistent versioning, changelog maintenance, and safe publishing.
 
-**Core Principle**: Atomic release - all version markers (package.json, CHANGELOG.md, git tag) must stay in sync.
+**Core Principles**:
+1. **Atomic release** - All version markers (package.json, CHANGELOG.md, git tag) stay in sync
+2. **Semantic versioning enforcement** - Prevents arbitrary jumps and format inconsistencies
+3. **Decision tree validation** - Every version bump follows explicit SemVer rules
 
 ## When to Use
 
@@ -24,18 +27,57 @@ Don't use when:
 - ❌ Not on main branch
 - ❌ Pre-release/beta versions (needs adaptation)
 
-## Release Types
+## Version Decision Protocol
+
+**MANDATORY**: Before any version bump, determine change type using the decision tree.
+
+See [references/version-decision-guide.md](references/version-decision-guide.md) for detailed rules and examples.
+
+### Quick Decision Tree
+
+```
+Is this a breaking change?
+├─ YES → MAJOR bump (X.0.0)
+└─ NO → Is this a new feature?
+    ├─ YES → MINOR bump (X.Y.0)
+    └─ NO → PATCH bump (X.Y.Z)
+```
+
+### Release Types
 
 Follow [Semantic Versioning](https://semver.org/):
 
 | Type | Version Change | When |
 |------|---------------|------|
-| **Patch** | 2.4.3 → 2.4.4 | Bug fixes, minor improvements |
-| **Minor** | 2.4.4 → 2.5.0 | New features, backward compatible |
-| **Major** | 2.5.0 → 3.0.0 | Breaking changes |
+| **Patch** | 4.2.0 → 4.2.1 | Bug fixes, minor improvements |
+| **Minor** | 4.2.1 → 4.3.0 | New features, backward compatible |
+| **Major** | 4.3.0 → 5.0.0 | Breaking changes |
+
+### Anti-Patterns (FORBIDDEN)
+
+❌ **Arbitrary jumps**: 3.0.1 → 7.0.0 (no justification)
+❌ **Skipping versions**: 4.2.0 → 4.4.0 (skipped 4.3.0)
+❌ **Inconsistent formats**: v1.0, 1.0.0, release-1.0 (mixed formats)
 
 ## Complete Workflow
 
+### Phase 0: Version Validation (MANDATORY)
+
+**Before any changes**, validate current state and determine next version:
+
+```bash
+# 1. Validate version synchronization
+bash .claude/skills/utility/npm-release/scripts/validate-version-sync.sh
+
+# 2. Determine change type (patch/minor/major)
+# Use decision tree in references/version-decision-guide.md
+
+# 3. Calculate next version
+bash .claude/skills/utility/npm-release/scripts/version-decision-tree.sh $(grep -o '"version": *"[^"]*"' package.json | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+') <patch|minor|major>
+```
+
+**STOP if validation fails** - Fix inconsistencies before proceeding.
+
 ### Phase 1: Pre-Release Checks
 
 ```bash
@@ -45,7 +87,7 @@ git status
 
 # 2. Check current version
 cat package.json | grep version
-# e.g., "version": "2.4.3"
+# e.g., "version": "4.2.0"
 
 # 3. Review recent changes
 git log --oneline -10
@@ -56,9 +98,29 @@ git log --oneline -10
 - Uncommitted changes exist
 - Unpushed commits exist
 
-### Phase 2: Version Updates
+### Phase 2: Atomic Version Bump
+
+**Use the atomic bump script** (recommended):
+
+```bash
+# Automatically updates package.json + CHANGELOG.md
+bash .claude/skills/utility/npm-release/scripts/atomic-version-bump.sh <patch|minor|major> "Brief description"
+
+# Example:
+bash .claude/skills/utility/npm-release/scripts/atomic-version-bump.sh minor "Add export command"
+```
+
+**Or manual update** (if script unavailable):
+
+**Step 1: Update package.json**
+
+```bash
+npm version patch --no-git-tag-version  # For patch release
+npm version minor --no-git-tag-version  # For minor release
+npm version major --no-git-tag-version  # For major release
+```
 
-**Step 1: Update CHANGELOG.md**
+**Step 2: Update CHANGELOG.md**
 
 Add new version section at the top (after `---`):
 
@@ -78,22 +140,6 @@ Brief description of main changes.
 - ✅ Benefit 2
 ```
 
-**Step 2: Update package.json**
-
-```bash
-# Manually edit or use npm version
-npm version patch --no-git-tag-version  # For patch release
-npm version minor --no-git-tag-version  # For minor release
-npm version major --no-git-tag-version  # For major release
-```
-
-Or edit directly:
-```json
-{
-  "version": "X.Y.Z"
-}
-```
-
 ### Phase 3: Git Operations
 
 **Step 1: Create Release Commit**
@@ -188,56 +234,75 @@ npm view cc-devflow version
 
 | Step | Command | Purpose |
 |------|---------|---------|
+| **Validate sync** | `bash scripts/validate-version-sync.sh` | Check version consistency |
+| **Decide version** | `bash scripts/version-decision-tree.sh <current> <type>` | Calculate next version |
+| **Atomic bump** | `bash scripts/atomic-version-bump.sh <type> "desc"` | Update all markers |
 | Check status | `git status` | Verify clean state |
 | Check version | `grep version package.json` | Current version |
-| Bump version | Edit package.json | Update version number |
-| Update changelog | Edit CHANGELOG.md | Document changes |
 | Create commit | `git commit -m "chore(release): ..."` | Commit version bump |
 | Create tag | `git tag -a vX.Y.Z -m "..."` | Tag release |
 | Push commits | `git push origin main` | Push to GitHub |
 | Push tags | `git push origin vX.Y.Z` | Push tag to GitHub |
 | Publish npm | `npm publish` | Publish to registry |
 
+## Version Management Scripts
+
+Three scripts enforce version discipline:
+
+1. **validate-version-sync.sh** - Checks package.json, git tags, CHANGELOG.md consistency
+2. **version-decision-tree.sh** - Calculates next version following SemVer rules
+3. **atomic-version-bump.sh** - Updates all version markers atomically
+
+**Usage**:
+```bash
+# Check current state
+bash .claude/skills/utility/npm-release/scripts/validate-version-sync.sh
+
+# Calculate next version
+bash .claude/skills/utility/npm-release/scripts/version-decision-tree.sh 4.2.0 minor
+# Output: 4.3.0
+
+# Atomic bump (recommended)
+bash .claude/skills/utility/npm-release/scripts/atomic-version-bump.sh minor "Add export command"
+```
+
 ## Common Mistakes
 
-### ❌ Mistake 1: Forgetting to Update CHANGELOG.md
+### ❌ Mistake 1: Arbitrary Version Jumps
 
-**Problem**: Version bumped but no changelog entry
+**Problem**: Version jumps from 3.0.1 to 7.0.0 without justification
 
-**Fix**: Always update CHANGELOG.md BEFORE committing
+**Fix**: Use version-decision-tree.sh to calculate correct next version based on change type
 
 ### ❌ Mistake 2: Inconsistent Version Numbers
 
-**Problem**: package.json shows 2.4.4 but CHANGELOG.md shows 2.4.3
+**Problem**: package.json shows 4.2.1 but CHANGELOG.md shows 4.2.0
+
+**Fix**: Use atomic-version-bump.sh to update all markers simultaneously
+
+### ❌ Mistake 3: Forgetting to Update CHANGELOG.md
+
+**Problem**: Version bumped but no changelog entry
 
-**Fix**: Double-check all version numbers match before committing
+**Fix**: Always update CHANGELOG.md BEFORE committing (atomic-version-bump.sh does this automatically)
 
-### ❌ Mistake 3: Pushing Tag Before Commit
+### ❌ Mistake 4: Pushing Tag Before Commit
 
 **Problem**: Tag points to wrong commit
 
 **Fix**: Always commit first, then tag, then push both together
 
-### ❌ Mistake 4: Not Testing npm publish
+### ❌ Mistake 5: Not Testing npm publish
 
 **Problem**: Published package is broken
 
 **Fix**: Run `npm publish --dry-run` first to catch issues
 
-### ❌ Mistake 5: Network Timeout During Push
+### ❌ Mistake 6: Inconsistent Tag Format
 
-**Problem**: `Failed to connect to github.com port 443`
+**Problem**: Mixed formats like v1.0, 1.0.0, release-1.0
 
-**Fix**:
-```bash
-# Option 1: Retry after network stabilizes
-git push origin main
-git push origin vX.Y.Z
-
-# Option 2: Switch to SSH (if HTTPS blocked)
-git remote set-url origin git@github.com:Dimon94/cc-devflow.git
-git push origin main
-```
+**Fix**: Always use vX.Y.Z format (e.g., v4.2.0). validate-version-sync.sh detects format inconsistencies
 
 ## Network Troubleshooting