cc-devflow 2.4.5 → 2.5.0

package/.claude/CLAUDE.md

@@ -10,6 +10,7 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 ├── agents/                    # Agent instruction files (research-type, invoked by commands)
 │   ├── checklist-agent.md     # Checklist generation logic [NEW: REQ-002]
 │   ├── clarify-analyst.md     # Requirements clarification
+│   ├── flow-researcher.md     # /flow-init mandatory research runner (subagent; file-based memory)
 │   ├── prd-writer.md          # PRD generation
 │   ├── tech-architect.md      # Technical design
 │   ├── planner.md             # EPIC/TASKS planning
@@ -19,7 +20,7 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 │
 ├── commands/                  # Slash command definitions
 │   ├── flow-checklist.md      # /flow-checklist command [NEW: REQ-002]
-│   ├── flow-init.md           # /flow-init (modified: Git Branch Creation moved to Stage 1.2)
+│   ├── flow-init.md           # /flow-init (modified: research delegated to flow-researcher subagent)
 │   ├── flow-clarify.md        # /flow-clarify
 │   ├── flow-prd.md            # /flow-prd
 │   ├── flow-tech.md           # /flow-tech
@@ -48,6 +49,11 @@ This directory contains Claude Code CLI extensions for the CC-DevFlow developmen
 │   │   └── SKILL.md
 │   ├── cc-devflow-orchestrator/
 │   │   └── SKILL.md           # Workflow router (modified: /flow-checklist, /flow-dev autonomous)
+│   ├── journey-coherence-checker/  # 跨需求一致性检查 [NEW: v2.4.0]
+│   │   ├── SKILL.md           # 检查协议：依赖满足、旅程完整、累积偏差
+│   │   └── pressure-scenarios.md  # TDD 压力测试场景
+│   ├── npm-release/              # NPM 包发布工作流
+│   │   └── SKILL.md           # 版本发布、Changelog 维护、原子化发布流程
 │   └── ...
 │
 └── docs/
@@ -132,7 +138,7 @@ Combine Ralph-Wiggum's autonomous iteration loop with Manus-style Planning-with-
 
 **Modified Files**:
 - `commands/flow-dev.md` - Merged Ralph Loop (Autonomous by default)
-- `commands/flow-init.md` - Added Manus method in Stage 2.5 Research
+- `commands/flow-init.md` - Research made mandatory via `flow-researcher` subagent (context-isolated)
 - `skills/cc-devflow-orchestrator/SKILL.md` - Updated routing for autonomous flow
 
 ### Attention Refresh Protocols

package/.claude/agents/flow-researcher.md

@@ -0,0 +1,132 @@
+---
+name: flow-researcher
+description: Executes mandatory /flow-init deep research using MCP services (Context7/WebSearch/WebFetch) with file-based memory. Produces research artifacts under devflow/requirements/$REQ_ID/research/ and returns only a short summary + file paths (no long pastes).
+tools: Read, Write, Grep, Glob, WebFetch, WebSearch, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
+model: inherit
+---
+
+You are a requirement research runner invoked by `/flow-init`.
+
+Your job is to do **research work** without exhausting the main session context:
+- Put large content into files under `devflow/requirements/$REQ_ID/research/`
+- Return only a **short** summary + **paths**, never paste long docs into chat
+
+## MCP Research Requirement
+
+This agent MUST use **MCP services** to fetch external materials for deep research:
+- **Context7 MCP**: official documentation for detected frameworks/libraries (`mcp__context7__resolve-library-id` + `mcp__context7__get-library-docs`)
+- **WebSearch + WebFetch**: tutorials, guides, examples, case studies, and plan URLs
+
+All fetched content MUST be written to `research/mcp/YYYYMMDD/**` (not pasted into chat).
+
+## Hard Rules
+
+1. **NO USER INTERACTION**
+   - Never ask the user questions.
+   - If information is missing, record it under `## Unresolved Questions` in `research/research-summary.md`.
+
+2. **FILE-BASED MEMORY (MANDATORY)**
+   - Any fetched/long content must be written to files in `research/`.
+   - Chat output must stay small (decision bullets + file paths).
+
+3. **NO PLACEHOLDERS**
+   - Do not leave `TODO`, `FIXME`, `{{PLACEHOLDER}}`.
+   - Ensure `validate-research.sh --strict` passes.
+
+4. **TRACEABILITY**
+   - Every decision must include a concrete `Source` (file path + section/line if possible).
+
+## Input Contract (provided via prompt)
+
+You will receive a JSON payload in the prompt:
+
+```json
+{
+  "reqId": "REQ-123",
+  "reqDir": "devflow/requirements/REQ-123",
+  "title": "User Authentication",
+  "planUrls": ["https://..."],
+  "contextFiles": {
+    "brainstorm": "devflow/requirements/REQ-123/BRAINSTORM.md",
+    "roadmap": "devflow/ROADMAP.md",
+    "architecture": "devflow/ARCHITECTURE.md"
+  }
+}
+```
+
+## Required Outputs (MUST create/update)
+
+Under `${reqDir}/research/`:
+- `internal/codebase-overview.md`
+- `mcp/YYYYMMDD/official/*.md` (if applicable)
+- `mcp/YYYYMMDD/guides/*.md` (if applicable)
+- `mcp/YYYYMMDD/tutorials/*.md` (if applicable)
+- `mcp/YYYYMMDD/examples/*.md` (if applicable)
+- `research-summary.md` (human-readable decisions)
+- `tasks.json` (decision/rationale/alternatives filled)
+- `research.md` (consolidated, Decision/Rationale/Alternatives format)
+
+## Execution Procedure (follow in order)
+
+### Step 1: Validate Paths & Prepare Directories
+- Ensure `${reqDir}` exists.
+- Ensure `${reqDir}/research/` exists, create missing subfolders:
+  - `research/internal/`
+  - `research/mcp/YYYYMMDD/{official,guides,tutorials,examples}/`
+- Read `${reqDir}/BRAINSTORM.md` and `${reqDir}/README.md` if present.
+
+### Step 2: Internal Codebase Research (S0)
+Goal: produce a **useful** `research/internal/codebase-overview.md` with:
+- Repo tech stack snapshot (from `package.json`, lockfiles, etc.)
+- Relevant modules/entry points you will likely touch
+- Existing patterns for auth/data validation/error handling/tests
+- Constraints you must not violate (existing conventions, CI, tooling)
+
+### Step 3: External Research (Task 1-5)
+Do not paste docs into chat; store them as files.
+
+1) **Official docs (Context7 MCP)** for the detected key libraries/frameworks
+2) **Tutorials/guides (WebSearch + WebFetch)** for practical patterns
+3) **Examples/case studies (WebSearch + WebFetch)** similar to this requirement
+4) Write short per-source notes at top of each saved file:
+   - What it answers
+   - What it recommends
+   - Any caveats
+
+If planUrls exist:
+- Fetch each URL and store content under `research/mcp/YYYYMMDD/guides/plan-*.md` (or `tutorials/` if more appropriate).
+
+### Step 4: Write `research/research-summary.md`
+Use `.claude/docs/templates/RESEARCH_TEMPLATE.md` as the format baseline.
+- Create **at least 3** Decision blocks `### R001`, `### R002`, `### R003`.
+- Each decision must cite sources under `research/` (internal or external).
+- Add unresolved questions only when genuinely blocked.
+
+### Step 5: Generate & Fill `tasks.json`
+- Run:
+  - `bash .claude/scripts/generate-research-tasks.sh "${reqDir}"`
+- Ensure `tasks.json` contains at least **1** task.
+  - If the generator produced 0 tasks, append baseline tasks matching your decision blocks (`R001..R003`).
+- Fill each task's `decision`, `rationale`, `alternatives` based on `research-summary.md`.
+  - Prefer using `bash .claude/scripts/populate-research-tasks.sh "${reqDir}"` if it matches the ID format.
+
+### Step 6: Consolidate & Validate
+- Run:
+  - `bash .claude/scripts/consolidate-research.sh "${reqDir}"`
+  - `bash .claude/scripts/validate-research.sh "${reqDir}" --strict`
+- If validation fails:
+  - Fix the files (do not weaken validation).
+  - Re-run validation until it passes.
+
+## Return Format (chat output)
+
+Return ONLY:
+- 3–6 bullet decisions (R001..), one line each
+- Paths created/updated
+- Any unresolved questions (≤5)
+
+Never paste long fetched content.
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

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

@@ -219,85 +219,53 @@ Red Flags - STOP:
 
 ---
 
-### Stage 2.5: Research (MCP Mandatory Flow)
+### Stage 2.5: Research (Subagent Mandatory)
 
-**目标**: 收集"真实材料"，所有步骤 **MANDATORY**
+**目标**: 研究默认必跑，但将“研究型内容”隔离到 subagent，避免主会话上下文耗尽。
 
-**Manus 研究方法** (Planning-with-files 融合):
+**Iron Law**: 大内容落盘，主会话只返回「决策摘要 + 文件路径」。
 
-```yaml
-原则 1: 大内容存文件
-  → 抓取的文档存 research/mcp/$(date +%Y%m%d)/
-  → 上下文只保留路径引用
-  → 避免塞满上下文窗口
-
-原则 2: 决策前读取
-  → 每次做研究决策前，先读 research/research.md Decisions 章节
-  → 确保不重复已有决策
-  → 注意力刷新，目标回到窗口
-
-原则 3: 失败尝试记录
-  → 研究中放弃的方案写入 research/attempts/
-  → 说明放弃原因和学习（见 ATTEMPT_TEMPLATE 格式）
-  → 失败是学习数据，不要隐藏
-
-原则 4: 增量追加
-  → 使用 append 而非 rewrite
-  → 保持研究历史完整
-  → 避免覆盖已有信息
-```
-
-```
-S0: Internal Codebase Research (必需)
-→ 分析现有代码库，生成 research/internal/codebase-overview.md
+#### ✅ Mandatory: Call `flow-researcher` Subagent
 
-Task 1-5: External Learning Materials (MCP)
-1. Official Documentation (Context7)
-2. Domain Tutorials (Web Search)
-3. Core Materials (WebFetch)
-4. Case Studies/Examples (Web Search + WebFetch)
-5. Summary & Recommendations
+> subagent 负责内部/外部研究、落盘、任务回填、研究整合与质量验证；主 agent 只做编排与最终 Gate。
 
-→ 详见 {TEMPLATE:flow} Stage 2.5
+```
+Task tool call:
+  description: "Run mandatory research for /flow-init (file-based memory)"
+  subagent_type: "flow-researcher"
+  model: "inherit"
+  prompt: (JSON)
+    {
+      "reqId": "${REQ_ID}",
+      "reqDir": "devflow/requirements/${REQ_ID}",
+      "title": "${TITLE}",
+      "planUrls": ["..."],
+      "contextFiles": {
+        "brainstorm": "devflow/requirements/${REQ_ID}/BRAINSTORM.md",
+        "roadmap": "devflow/ROADMAP.md",
+        "architecture": "devflow/ARCHITECTURE.md"
+      }
+    }
 ```
 
-**输出**:
-- `research/internal/codebase-overview.md`
-- `research/mcp/$(date +%Y%m%d)/official/*`
-- `research/mcp/$(date +%Y%m%d)/guides/*`
-- `research/mcp/$(date +%Y%m%d)/tutorials/*`
-- `research/mcp/$(date +%Y%m%d)/examples/*`
-- `research/research-summary.md`
+**期望输出** (由 subagent 写入):
+- `devflow/requirements/${REQ_ID}/research/internal/codebase-overview.md`
+- `devflow/requirements/${REQ_ID}/research/mcp/$(date +%Y%m%d)/**`
+- `devflow/requirements/${REQ_ID}/research/research-summary.md`
+- `devflow/requirements/${REQ_ID}/research/tasks.json` (decision/rationale/alternatives 完整)
+- `devflow/requirements/${REQ_ID}/research/research.md` (可通过 validate-research)
 
 ---
 
 ### Stage 2.6: Research Consolidation
 
-```
-研究决策整合:
-1. Generate research tasks
-   → Run: {SCRIPT:research_tasks} "${REQ_DIR}"
-   → Output: research/tasks.json
-
-2. Populate task decisions
-   → Run: {SCRIPT:populate_tasks} "${REQ_DIR}"
-   → Fill decision/rationale/alternatives from research
-
-3. Consolidate research
-   → Run: {SCRIPT:consolidate} "${REQ_DIR}"
-   → Output: research/research.md
-   → Format: Decision/Rationale/Alternatives/Source
+> 该阶段由 `flow-researcher` subagent 执行（包含 tasks 生成/回填/整合/校验）。
 
-4. Update status
-   → orchestration_status.json.phase0_complete = true
-
-→ 详见 {TEMPLATE:flow} Stage 2.6
-```
+主 agent 在 Exit Gate 中只做最终验证与状态更新：
+- Run: `{SCRIPT:validate_research} "${REQ_DIR}" --strict`
+- `orchestration_status.json.phase0_complete = true`
 
 ---
-
-
-
 ### Stage 3: README Generation
 
 ```
@@ -317,7 +285,7 @@ Level 1: File Existence Check
 → 验证所有必需文件已创建
 
 Level 2: Research.md Structure Validation
-→ Run: {SCRIPT:validate_research} "${REQ_DIR}"
+→ Run: {SCRIPT:validate_research} "${REQ_DIR}" --strict
 → 检查 research.md 结构
 
 Level 3: Research.md Content Quality

package/.claude/docs/templates/INIT_FLOW_TEMPLATE.md

@@ -93,55 +93,32 @@ devflow/requirements/${REQ_ID}/
 
 ---
 
-## Stage 2.5: Research (MCP Mandatory Flow)
+## Stage 2.5: Research (Subagent Mandatory)
 
-**目标**: 收集"真实材料"，所有步骤 **MANDATORY**
+**目标**: 研究默认必跑，但研究过程必须“隔离上下文”。
 
-### S0: Internal Codebase Research (必需)
-```bash
-→ 分析现有代码库
-→ 生成 research/internal/codebase-overview.md
-```
-
-### Task 1-5: External Learning Materials (MCP)
-```
-1. Official Documentation (Context7)
-   → research/mcp/$(date +%Y%m%d)/official/
+**规则**: 大内容写入 `research/`，主会话只保留路径引用与决策摘要。
 
-2. Domain Tutorials (Web Search)
-   → research/mcp/$(date +%Y%m%d)/guides/
+### Mandatory: Call `flow-researcher` Subagent
 
-3. Core Materials (WebFetch)
-   → research/mcp/$(date +%Y%m%d)/tutorials/
-
-4. Case Studies/Examples (Web Search + WebFetch)
-   → research/mcp/$(date +%Y%m%d)/examples/
-
-5. Summary & Recommendations
-   → research/research-summary.md
+```
+Task tool call:
+  subagent_type: "flow-researcher"
+  prompt: (JSON) reqId/reqDir/title/planUrls/contextFiles
 ```
 
+**产物** (由 subagent 写入):
+- `research/internal/codebase-overview.md`
+- `research/mcp/$(date +%Y%m%d)/**`
+- `research/research-summary.md`
+- `research/tasks.json`
+- `research/research.md`
+
 ---
 
 ## Stage 2.6: Research Consolidation
 
-```bash
-# 1. Generate research tasks
-bash {SCRIPT:research_tasks} "${REQ_DIR}"
-→ Output: research/tasks.json
-
-# 2. Populate task decisions
-bash {SCRIPT:populate_tasks} "${REQ_DIR}"
-→ Fill decision/rationale/alternatives from research
-
-# 3. Consolidate research
-bash {SCRIPT:consolidate} "${REQ_DIR}"
-→ Output: research/research.md
-→ Format: Decision/Rationale/Alternatives/Source
-
-# 4. Update status
-orchestration_status.json.phase0_complete = true
-```
+> 该阶段由 `flow-researcher` subagent 执行（含 tasks 生成/回填/整合/校验）。
 
 ---
 
@@ -166,7 +143,7 @@ orchestration_status.json.phase0_complete = true
 
 ### Level 2: Research.md Structure Validation
 ```bash
-bash {SCRIPT:validate_research} "${REQ_DIR}"
+bash {SCRIPT:validate_research} "${REQ_DIR}" --strict
 → 检查 research.md 结构
 ```
 

package/.claude/scripts/populate-research-tasks.sh

@@ -72,24 +72,44 @@ def extract_task_sections(markdown_content: str) -> List[Dict[str, str]]:
     从 research-summary.md 中提取任务章节信息。
 
     期望格式:
-    ### RT-001: 输入框架构重构
-    **决策**: 全面重构方案
-    **理由**: 当前实现仅207行...
-    **备选方案**: 1. 渐进式增强...
+    ### R001 — 输入框架构重构
+    - **Decision**: 全面重构方案
+    - **Rationale**:
+      - 当前实现仅207行...
+    - **Alternatives Considered**:
+      - 渐进式增强...
     """
     sections = []
     current_section = None
-
-    # 匹配任务标题: ### RT-001: 任务标题
-    task_header = re.compile(r'^###\s+(RT-\d+):\s+(.+)$')
-    # 匹配决策行: **决策**: xxx 或 **Decision**: xxx
-    decision_line = re.compile(r'^\*\*(?:决策|Decision)\*\*:\s*(.+)$')
-    # 匹配理由行: **理由**: xxx 或 **Rationale**: xxx
-    rationale_line = re.compile(r'^\*\*(?:理由|Rationale)\*\*:\s*(.+)$')
-    # 匹配备选方案行: **备选方案**: xxx 或 **Alternatives**: xxx
-    alternatives_line = re.compile(r'^\*\*(?:备选方案|Alternatives)\*\*:\s*(.+)$')
+    current_field = None
+
+    # 匹配任务标题（兼容历史 RT-001）:
+    # - ### R001 — Title
+    # - ### R001: Title
+    # - ### R001 - Title
+    # - ### RT-001: Title  (legacy)
+    task_header = re.compile(r"^###\s+(?P<id>R\d{3}|RT-\d{3})\s*(?:[:—-])\s*(?P<title>.+)$")
+
+    # 匹配字段头（兼容是否带 bullet）:
+    # - - **Decision**: xxx
+    # - - **Rationale**:
+    # - - **Alternatives Considered**:
+    field_header = re.compile(
+        r"^(?:[-*]\s*)?\*\*(?P<label>决策|Decision|理由|Rationale|备选方案|Alternatives(?:\s+Considered)?|来源|Source)\*\*:\s*(?P<value>.*)$"
+    )
+
+    def normalize_task_id(raw: str) -> str:
+        if raw.startswith("RT-"):
+            return f"R{raw.split('-', 1)[1]}"
+        return raw
+
+    def normalize_list_item(line: str) -> str:
+        line = line.strip()
+        line = re.sub(r"^[-*]\s+", "", line)
+        return line.strip()
 
     for line in markdown_content.splitlines():
+        raw_line = line
         line = line.strip()
 
         # 检测新任务章节
@@ -97,9 +117,10 @@ def extract_task_sections(markdown_content: str) -> List[Dict[str, str]]:
         if task_match:
             if current_section:
                 sections.append(current_section)
+            current_field = None
             current_section = {
-                "id": task_match.group(1),
-                "title": task_match.group(2),
+                "id": normalize_task_id(task_match.group("id")),
+                "title": task_match.group("title"),
                 "decision": "",
                 "rationale": "",
                 "alternatives": "",
@@ -109,31 +130,35 @@ def extract_task_sections(markdown_content: str) -> List[Dict[str, str]]:
         if not current_section:
             continue
 
-        # 提取决策
-        decision_match = decision_line.match(line)
-        if decision_match:
-            current_section["decision"] = decision_match.group(1).strip()
-            continue
-
-        # 提取理由
-        rationale_match = rationale_line.match(line)
-        if rationale_match:
-            current_section["rationale"] = rationale_match.group(1).strip()
+        # 检测字段头
+        field_match = field_header.match(line)
+        if field_match:
+            label = field_match.group("label").strip().lower()
+            value = (field_match.group("value") or "").strip()
+
+            if label in {"来源", "source"}:
+                current_field = None
+                continue
+            if label in {"决策", "decision"}:
+                current_field = "decision"
+            elif label in {"理由", "rationale"}:
+                current_field = "rationale"
+            else:
+                current_field = "alternatives"
+
+            if value:
+                current_section[current_field] = value
             continue
 
-        # 提取备选方案
-        alternatives_match = alternatives_line.match(line)
-        if alternatives_match:
-            current_section["alternatives"] = alternatives_match.group(1).strip()
-            continue
-
-        # 继续累积多行理由（如果上一行是理由）
-        if current_section.get("rationale") and line and not line.startswith("**"):
-            current_section["rationale"] += " " + line.strip()
-
-        # 继续累积多行备选方案
-        if current_section.get("alternatives") and line and not line.startswith("**"):
-            current_section["alternatives"] += " " + line.strip()
+        # 累积字段内容（支持列表项）
+        if current_field and line:
+            item = normalize_list_item(raw_line)
+            if not item:
+                continue
+            if current_section[current_field]:
+                current_section[current_field] += "\n" + item
+            else:
+                current_section[current_field] = item
 
     # 添加最后一个章节
     if current_section:

package/.claude/skills/journey-coherence-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

package/.claude/skills/journey-coherence-checker/pressure-scenarios.md

@@ -0,0 +1,164 @@
+# Journey Coherence Checker - Pressure Scenarios
+
+## Purpose
+TDD RED Phase: Define scenarios to test agent behavior WITHOUT the skill.
+
+---
+
+## Scenario 1: Dependency Not Satisfied
+
+**Setup**:
+- REQ-007 declares `dependencies: ["RM-006", "RM-007"]`
+- RM-006 (REQ-004) is `release_complete`
+- RM-007 (REQ-005) is `release_complete`
+- But REQ-005's actual output doesn't match what REQ-007 expects
+
+**Pressure**:
+```
+User: "REQ-007 开发完成了，请帮我检查一下"
+```
+
+**Expected Baseline Behavior (WITHOUT skill)**:
+- Agent only checks REQ-007's internal consistency
+- Agent doesn't verify RM-007's output matches REQ-007's input expectation
+- Agent says "PASS" even though there's a gap
+
+**Desired Behavior (WITH skill)**:
+- Agent reads REQ-007's `dependencies` field
+- Agent reads REQ-005's actual output (from TECH_DESIGN or contracts)
+- Agent compares expected vs actual
+- Agent reports mismatch if found
+
+---
+
+## Scenario 2: Milestone Success Criteria Not Met
+
+**Setup**:
+- M4 Success Criteria: "All 4 platforms can execute core workflows"
+- REQ-004, REQ-005, REQ-006 are `release_complete`
+- But only 2 platforms actually work (Claude + Codex)
+
+**Pressure**:
+```
+User: "M4 完成了吗？"
+```
+
+**Expected Baseline Behavior (WITHOUT skill)**:
+- Agent checks individual REQ status
+- Agent sees all REQs are complete
+- Agent says "M4 完成了"
+
+**Desired Behavior (WITH skill)**:
+- Agent reads M4's Success Criteria from ROADMAP.md
+- Agent verifies each criterion against actual implementation
+- Agent reports "2/4 platforms working, M4 not complete"
+
+---
+
+## Scenario 3: Cumulative Scope Reduction
+
+**Setup**:
+- ROADMAP M4 originally planned 7 deliverables (RM-007 to RM-013)
+- Each REQ's PRD "slightly simplified" the scope
+- Final implementation covers only 60% of original vision
+
+**Pressure**:
+```
+User: "M4 的所有需求都开发完了，可以发布了吗？"
+```
+
+**Expected Baseline Behavior (WITHOUT skill)**:
+- Agent checks each REQ's status
+- Agent sees all are `release_complete`
+- Agent says "可以发布"
+
+**Desired Behavior (WITH skill)**:
+- Agent compares ROADMAP deliverables vs actual PRD scope
+- Agent calculates coverage percentage
+- Agent reports "60% coverage, 40% scope reduction detected"
+
+---
+
+## Scenario 4: Journey Gap (Missing Glue)
+
+**Setup**:
+- User journey: `/flow-init` → `/flow-prd` → `/flow-epic` → `/flow-dev` → `/flow-release`
+- REQ-005 implements `/flow-dev` improvements
+- REQ-006 implements compiler
+- But there's no REQ connecting them (the "glue" is missing)
+
+**Pressure**:
+```
+User: "从 /flow-init 到 /flow-release 的完整流程能跑通吗？"
+```
+
+**Expected Baseline Behavior (WITHOUT skill)**:
+- Agent checks individual command implementations
+- Agent doesn't test end-to-end flow
+- Agent says "应该可以"
+
+**Desired Behavior (WITH skill)**:
+- Agent identifies the user journey
+- Agent traces through each step
+- Agent finds the gap between REQ-005 and REQ-006
+- Agent reports "Gap found: no integration between X and Y"
+
+---
+
+## Scenario 5: Orphan Requirement
+
+**Setup**:
+- REQ-008 exists but is not mapped to any ROADMAP item
+- REQ-008 is `release_complete`
+- But it doesn't contribute to any Milestone
+
+**Pressure**:
+```
+User: "所有需求都完成了，项目进度如何？"
+```
+
+**Expected Baseline Behavior (WITHOUT skill)**:
+- Agent counts completed REQs
+- Agent reports "X/Y REQs complete"
+- Agent doesn't notice REQ-008 is orphan
+
+**Desired Behavior (WITH skill)**:
+- Agent maps REQs to ROADMAP items
+- Agent identifies REQ-008 as orphan
+- Agent reports "REQ-008 not mapped to any Milestone"
+
+---
+
+## Test Execution Plan
+
+### Phase 1: Baseline Testing (RED)
+1. Create mock REQ-007 with unmet dependency
+2. Ask agent to verify REQ-007
+3. Document agent's response verbatim
+4. Identify rationalizations used
+
+### Phase 2: Skill Writing (GREEN)
+1. Write skill addressing baseline failures
+2. Re-run scenarios
+3. Verify agent now catches issues
+
+### Phase 3: Refinement (REFACTOR)
+1. Find new rationalizations
+2. Add explicit counters
+3. Re-test until bulletproof
+
+---
+
+## Key Rationalizations to Watch For
+
+| Potential Excuse | Counter |
+|------------------|---------|
+| "依赖已经标记完成了" | 完成 ≠ 满足。检查实际输出。 |
+| "每个需求都通过了验证" | 单需求验证 ≠ 全局一致性。 |
+| "ROADMAP 是规划，不是承诺" | Success Criteria 是承诺。 |
+| "这超出了我的检查范围" | 这正是你的检查范围。 |
+| "用户没有要求检查全局" | 全局检查是隐含要求。 |
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

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/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.5.0] - 2026-01-25
+
+### 🚀 新增 Skills：一致性检查与发版自动化
+
+v2.5.0 引入了两个强大的新 Skills，分别解决了跨需求一致性检查和 NPM 包发版自动化的问题。
+
+#### Added
+
+- **Journey Coherence Checker Skill** - 跨需求一致性检查
+  - 检查依赖满足情况 (Dependency Satisfaction)
+  - 验证里程碑 Success Criteria
+  - 检测累积偏差 (Cumulative Scope Drift)
+  - 发现用户旅程空隙 (Journey Gaps)
+  - 集成到发布门禁 (`/flow-release`)
+
+- **NPM Release Skill** - NPM 发版流程自动化
+  - 标准化发版工作流 (Patch/Minor/Major)
+  - 自动更新 CHANGELOG.md
+  - 自动创建并验证 Git Tags
+  - 发布前安全检查
+
+## [2.4.6] - 2026-01-12
+
+### flow-init 工作流精简：研究步骤抽离为 subagent
+
+将研究型内容从主流程中拆分到独立 subagent，减少上下文消耗，并同步更新命令、模板、脚本与文档。
+
+#### Added
+
+- **flow-researcher agent** - 执行 `/flow-init` 深度研究并写入 `devflow/requirements/$REQ_ID/research/`
+
+#### Changed
+
+- **flow-init command** - 重组流程，研究部分改由 subagent 执行
+- **INIT_FLOW_TEMPLATE.md** - 精简初始化模板
+- **populate-research-tasks.sh** - 更新 research tasks 填充逻辑
+- **flow-init docs** - 同步更新中英文文档
+
+#### Benefits
+
+- **更省上下文**: 主会话仅保留关键决策与路径
+- **更可追溯**: 研究产物落盘，便于审计与复用
+
+---
+
 ## [2.4.5] - 2026-01-10
 
 ### 🛠️ Skills 增强：新增开发辅助工具

package/docs/commands/flow-init.md

@@ -47,6 +47,9 @@ Stage 1: Prerequisites validation
   ├─ Check devflow/ directory
   └─ Verify REQ-ID uniqueness
   ↓
+Stage 1.2: Git branch creation
+  └─ Create feature/REQ-XXX-english-slug branch (model-translated, not pinyin)
+  ↓
 Stage 1.5: Roadmap & Architecture context loading (NEW)
   ├─ Check ROADMAP.md existence
   ├─ Locate requirement in roadmap
@@ -64,13 +67,15 @@ Stage 2: Directory structure creation
   ├─ Initialize orchestration_status.json
   └─ Create EXECUTION_LOG.md
   ↓
-Stage 2.6: Research task dispatch & decision integration
-  ├─ Generate research tasks
-  ├─ Populate research decisions
-  └─ Consolidate research findings
+Stage 2.3: Brainstorming (skill)
+  └─ Generate devflow/requirements/REQ-XXX/BRAINSTORM.md as the “North Star”
   ↓
-Stage 3: Git branch creation
-  └─ Create feature/REQ-XXX-english-slug branch (model-translated, not pinyin)
+Stage 2.5: Research (subagent, mandatory, context-isolated)
+  ├─ Run internal codebase research → research/internal/codebase-overview.md
+  ├─ Capture external sources into files → research/mcp/YYYYMMDD/**
+  ├─ Produce decisions → research/research-summary.md
+  ├─ Fill tasks → research/tasks.json (decision/rationale/alternatives)
+  └─ Consolidate → research/research.md (validated; no TODO/PLACEHOLDER)
 ```
 
 ## 💡 Examples
@@ -124,10 +129,9 @@ Stage 3: Git branch creation
 
 ## 📂 Output
 
-- `devflow/requirements/REQ-XXX/` complete directory
-- `orchestration_status.json`
-- `EXECUTION_LOG.md`
-- Roadmap and architecture context (if exists)
+- `devflow/requirements/REQ-XXX/` initialized directory (includes `BRAINSTORM.md` + `research/`)
+- `orchestration_status.json` + `EXECUTION_LOG.md`
+- Roadmap and architecture context display (if exists)
 
 ## 🔗 Related Commands
 

package/docs/commands/flow-init.zh-CN.md

@@ -43,6 +43,9 @@ Stage 1: 前置条件验证
   ├─ 检查 devflow/ 目录
   └─ 验证 REQ-ID 唯一性
   ↓
+Stage 1.2: Git 分支创建
+  └─ 创建 feature/REQ-XXX-english-slug 分支（标题英文意译，非拼音）
+  ↓
 Stage 1.5: 路线图与架构上下文加载（NEW）
   ├─ 检查 ROADMAP.md 存在性
   ├─ 定位需求在路线图中的位置
@@ -57,17 +60,19 @@ Stage 1.5: 路线图与架构上下文加载（NEW）
   ↓
 Stage 2: 目录结构创建
   ├─ 创建 devflow/requirements/REQ-123/
-  ├─ 创建子目录 tasks/, research/
+  ├─ 创建子目录 research/
   ├─ 初始化 orchestration_status.json
   └─ 初始化 EXECUTION_LOG.md
   ↓
-Stage 2.6: 调研任务分派与决策整合（FIXED）
-  ├─ 生成研究任务 (generate-research-tasks.sh)
-  ├─ 填充研究决策 (populate-research-tasks.sh)
-  └─ 整合研究结论 (consolidate-research.sh)
+Stage 2.3: 头脑风暴（skill）
+  └─ 生成 devflow/requirements/REQ-XXX/BRAINSTORM.md 作为需求「北极星」
   ↓
-Stage 3: Git 分支创建
-  └─ 创建 feature/REQ-123-user-auth 分支（标题英文意译，非拼音）
+Stage 2.5: 调研（subagent，默认必跑，上下文隔离）
+  ├─ 内部代码库调研 → research/internal/codebase-overview.md
+  ├─ 外部资料落盘 → research/mcp/YYYYMMDD/**
+  ├─ 决策摘要 → research/research-summary.md
+  ├─ 任务回填 → research/tasks.json（decision/rationale/alternatives 完整）
+  └─ 研究整合 → research/research.md（通过校验，无 TODO/PLACEHOLDER）
 ```
 
 ## 💡 示例
@@ -129,7 +134,6 @@ Stage 3: Git 分支创建
 devflow/requirements/REQ-123/
 ├── orchestration_status.json    # 状态管理
 ├── EXECUTION_LOG.md             # 审计轨迹
-├── tasks/                       # 任务产物目录
 ├── research/                    # 研究材料目录
 └── (等待后续阶段生成其他文档)
 ```

package/package.json

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

package/.claude/tsc-cache/6e64f818-6398-49ca-8623-581a9af85c44/edited-files.log

@@ -1 +0,0 @@
-1766046071	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root

package/.claude/tsc-cache/748c64fa-9e5f-4a1d-9db8-efb8415a6183/affected-repos.txt

@@ -1 +0,0 @@
-root

package/.claude/tsc-cache/748c64fa-9e5f-4a1d-9db8-efb8415a6183/edited-files.log

@@ -1 +0,0 @@
-1768013595	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root

package/.claude/tsc-cache/777aa1de-497e-411b-a40f-13b74efcec58/edited-files.log

@@ -1,2 +0,0 @@
-1766298649	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root
-1766298660	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root

package/.claude/tsc-cache/795ba6e3-b98a-423b-bab2-51aa62812569/edited-files.log

@@ -1 +0,0 @@
-1766132827	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root

package/.claude/tsc-cache/ae335694-be5a-4ba4-a1a0-b676c09a7906/edited-files.log

@@ -1 +0,0 @@
-1766112103	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/.gitignore	root

package/.claude/tsc-cache/f903e5df-3c39-4958-b26b-724808f32956/affected-repos.txt

@@ -1 +0,0 @@
-root

package/.claude/tsc-cache/f903e5df-3c39-4958-b26b-724808f32956/edited-files.log

@@ -1,2 +0,0 @@
-1768012783	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root
-1768012988	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/.gitignore	root