cc-devflow 4.1.6 → 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/cc-devflow-orchestrator/SKILL.md

@@ -19,6 +19,29 @@ Guide users to the correct command/skill without duplicating detailed implementa
 /core:style        → STYLE.md
 ```
 
+## Project-Level Harness Protocol (Long-running)
+
+For `/core:*` commands, enforce a two-session model before declaring completion:
+
+1. Initializer session
+   - establish/update `devflow/.core-harness/<command>/checklist.json`, `progress.md`, `session-handoff.md`
+   - convert high-level goal into structured acceptance checks (default all failing)
+2. Worker session(s)
+   - resume from `session-handoff.md` + `progress.md`
+   - execute one smallest deliverable per session
+   - update checklist status only after command-specific validation
+3. Completion gate
+   - completion is allowed only when checklist is fully passing and command validation gates pass
+   - never declare success from “looks complete”; require artifact evidence
+
+### Core Route Defaults
+
+- no `devflow/ROADMAP.md` → route to `/core:roadmap` (initializer first)
+- roadmap exists but architecture missing/stale → route to `/core:architecture`
+- architecture exists but guidelines missing/stale → route to `/core:guidelines`
+- style missing/stale → route to `/core:style`
+- interrupted core command → rerun same command from handoff (`/core:roadmap --resume` if supported; otherwise run command again and continue from `session-handoff.md`)
+
 ### Requirement-Level Canonical Mainline (v6)
 
 ```text
@@ -140,5 +163,7 @@ This skill only does routing:
 - Which command to run next
 - Which gate blocks progress
 - Which migration path applies for deprecated commands
+- Prefer incremental convergence over one-shot generation
+- Require artifact-backed completion for long-running sessions
 
 Detailed quality standards stay in command files and workflow skills.

package/.claude/skills/flow-dev/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: flow-dev
+description: 'Execute task-manifest with dependency-aware parallel dispatch and checkpoint recovery. Use when implementing planned tasks for a requirement.'
+---
+
+# Flow-Dev Skill
+
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+执行 `task-manifest.json` 中的任务，默认并行调度并写入 checkpoint/events 供恢复。
+
+## Long-Running Harness Protocol（Initializer/Worker/Done Gate）
+
+`/flow:dev` 是最长链路阶段，必须严格执行“先读状态、再增量、后留证据”。
+
+### Session Start（禁止盲跑）
+
+每个窗口开始时先同步以下信息：
+- `devflow/requirements/${REQ_ID}/session-checklist.json`（若存在）
+- `devflow/requirements/${REQ_ID}/session-progress.md`（若存在）
+- `devflow/requirements/${REQ_ID}/session-handoff.md`（若存在）
+- `devflow/requirements/${REQ_ID}/task-manifest.json`
+- `.harness/runtime/${REQ_ID}/**/checkpoint.json` 与 `events.jsonl`（若存在）
+
+然后执行一次基础健康检查：
+1. 不存在损坏的 `running` 残留状态
+2. 上轮失败任务与失败原因可定位
+
+### Worker Session（最小可执行前沿）
+
+单窗口仅推进一个最小前沿：
+- 仅处理当前 `dependsOn` 已满足的一组任务
+- 每完成一组任务即写入 checkpoint/events
+- 遇到失败立即收敛原因并记录，不并行扩散新的失败面
+
+会话收尾必须：
+1. 更新 `task-manifest.json` 状态
+2. 更新 `session-progress.md` 与 `session-handoff.md`
+3. 推荐提交一个可回滚的最小 git commit（若仓库策略允许）
+
+### Done Gate
+
+仅当以下条件满足才标记 `flow:dev` 完成：
+- 全部任务为 `passed` 或 `skipped`
+- 无 `running`/`failed` 残留
+- `session-checklist.json` 中 `flow:dev.passes == true`
+
+## Input Format
+
+```bash
+/flow:dev "REQ_ID" [--parallel N] [--resume] [--max-retries N]
+```
+
+## Execution Steps
+
+1. 解析参数：
+   - 默认 `parallel = 3`
+   - 默认不 resume
+2. 分支执行：
+   - 普通执行：
+
+```bash
+npm run harness:dispatch -- --change-id "${REQ_ID}" --parallel ${PARALLEL} [--max-retries ${MAX_RETRIES}]
+```
+
+   - 恢复执行：
+
+```bash
+npm run harness:resume -- --change-id "${REQ_ID}" --parallel ${PARALLEL} [--max-retries ${MAX_RETRIES}]
+```
+
+3. 检查执行结果：
+   - `task-manifest.json` 状态更新
+   - `.harness/runtime/${REQ_ID}/<TASK_ID>/events.jsonl`
+   - `.harness/runtime/${REQ_ID}/<TASK_ID>/checkpoint.json`
+
+## Exit Criteria
+
+- 所有任务状态为 `passed` 或 `skipped`
+- 没有 `running` 残留状态
+
+## Failure Handling
+
+- 若存在 `failed` 任务：
+  1. 修复失败原因
+  2. 重新运行 `--resume`
+
+## Next Step
+
+```bash
+/flow:verify "${REQ_ID}"
+```

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

@@ -0,0 +1,105 @@
+---
+name: flow-init
+description: 'Initialize a requirement with harness state and context package. Use when starting a new REQ/BUG and preparing deterministic execution context for the next stages.'
+---
+
+# Flow-Init Skill
+
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+初始化需求目录的 harness 运行状态，并生成可执行上下文包。
+
+## Long-Running Harness Protocol（Initializer/Worker/Done Gate）
+
+为与 `/core:*` 保持一致，`/flow:init` 也采用会话分层协议。
+
+### Initializer Session（为后续窗口建立可恢复上下文）
+
+在执行 `harness:init + harness:pack` 后，确保以下工件存在：
+- `devflow/requirements/${REQ_ID}/session-checklist.json`
+  - 至少包含 `flow:init/flow:spec/flow:dev/flow:verify/flow:release` 五个阶段，默认 `passes=false`
+- `devflow/requirements/${REQ_ID}/session-progress.md`
+  - 记录本窗口完成内容、风险和阻塞
+- `devflow/requirements/${REQ_ID}/session-handoff.md`
+  - 明确下一窗口唯一优先动作（通常是 `/flow:spec "${REQ_ID}"`）
+
+### Worker Session（只做 init 的原子闭环）
+
+每次仅执行一个最小闭环：
+1. 读取 `session-progress.md` 与 `session-handoff.md`
+2. 运行 `harness:init`
+3. 运行 `harness:pack`
+4. 验证产物并更新 session 工件
+
+### Done Gate（禁止口头完成）
+
+仅当以下条件同时满足才允许标记 `flow:init` 为完成：
+- `harness-state.json.status == "initialized"`
+- `context-package.md` 存在且包含 Next Commands
+- `session-checklist.json` 中 `flow:init.passes == true`
+
+## Input Format
+
+```bash
+/flow:init "REQ_ID|TITLE|PLAN_URLS?"
+```
+
+- `REQ_ID`: `REQ-123` 或 `BUG-123`
+- `TITLE`: 需求标题
+- `PLAN_URLS`: 可选，逗号分隔
+
+## Execution Steps
+
+1. 解析输入，提取 `REQ_ID`、`TITLE`、`PLAN_URLS`。
+
+2. **读取项目级 specs/ 了解当前系统状态**（v4.3 新增）：
+   - 读取 `devflow/specs/README.md` 了解模块结构
+   - 扫描 `devflow/specs/*/spec.md` 识别相关模块
+   - 记录当前系统状态到上下文
+
+3. 组装 goal 文本：
+   - `Deliver <REQ_ID>: <TITLE>`
+   - 若有 URL，追加 `Sources: <URLS>`。
+
+4. 运行初始化：
+
+```bash
+npm run harness:init -- --change-id "${REQ_ID}" --goal "${GOAL}"
+```
+
+5. 运行上下文打包：
+
+```bash
+npm run harness:pack -- --change-id "${REQ_ID}" --goal "${GOAL}"
+```
+
+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
+
+```bash
+/flow:spec "${REQ_ID}"
+```

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/flow-spec/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: flow-spec
+description: 'Generate and refresh task-manifest for a requirement. Use when converting requirement context into dependency-aware executable tasks.'
+---
+
+# Flow-Spec Skill
+
+> [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+
+## Purpose
+
+将需求上下文转换为 `task-manifest.json`，作为后续执行唯一任务源。
+
+## Long-Running Harness Protocol（Initializer/Worker/Done Gate）
+
+`/flow:spec` 必须以“可恢复、可验证”的增量方式生成计划，而不是一次性黑箱产出。
+
+### Session Start（先同步上下文，再规划）
+
+每个窗口启动先读取：
+- `devflow/requirements/${REQ_ID}/session-checklist.json`（若存在）
+- `devflow/requirements/${REQ_ID}/session-progress.md`（若存在）
+- `devflow/requirements/${REQ_ID}/session-handoff.md`（若存在）
+- `devflow/requirements/${REQ_ID}/context-package.md`
+- 旧版 `task-manifest.json`（若存在）
+
+### Worker Session（一次只收敛一个规划目标）
+
+每轮只完成一个最小目标，例如：
+- 修正一个依赖子图
+- 补齐一组缺失的 `run` 指令
+- 处理一次 `--overwrite` 下的清理重建
+
+完成后必须：
+1. 运行 `harness:plan` 生成/刷新 manifest
+2. 校验 schema 与依赖无环
+3. 更新 progress/handoff，写明下一轮唯一目标
+
+### Done Gate
+
+仅当以下条件满足才标记 `flow:spec` 完成：
+- `task-manifest.json` 存在且 `tasks` 非空
+- `id/dependsOn/run` 字段完整且无自循环
+- `session-checklist.json` 中 `flow:spec.passes == true`
+
+## Input Format
+
+```bash
+/flow:spec "REQ_ID" [--overwrite]
+```
+
+## Execution Steps
+
+1. 解析 `REQ_ID` 和可选 `--overwrite`。
+
+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]
+```
+
+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 保障）
+
+## Next Step
+
+```bash
+/flow:dev "${REQ_ID}"
+```

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