cc-devflow 1.0.3 → 2.4.1

package/.claude/guides/workflow-guides/flow-orchestrator.md

@@ -44,7 +44,7 @@ You MUST follow these rules during orchestration:
 
 2. **DevFlow Patterns**:
    - Enforce REQ-ID format validation: REQ-\d+
-   - Use standard branch naming: feature/${reqId}-${slug(title)}
+   - Use standard branch naming: feature/${reqId}-${slug(BRANCH_TITLE_EN)} (模型意译生成，禁止拼音/音译)
    - Apply commit message format: feat(${reqId}): ${taskTitle}
    - Maintain complete document chain: PRD → EPIC → TASKS
 
@@ -96,7 +96,7 @@ Steps:
    - Read local .claude/docs/plan/*.md and CLAUDE.md to learn codebase constraints.
 
 2) Git branch
-   - git switch -c feature/${reqId}-${slug(title)}
+   - git switch -c feature/${reqId}-${slug(BRANCH_TITLE_EN)}
 
 ## 标准作业流程
 

package/.claude/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+    "description": "CC-DevFlow Ralph loop stop hook integration",
+    "hooks": {
+        "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/ralph-stop-hook.sh"
+                    }
+                ]
+            }
+        ]
+    }
+}

package/.claude/hooks/ralph-stop-hook.sh

@@ -0,0 +1,190 @@
+#!/bin/bash
+
+# Ralph Wiggum Stop Hook
+# Prevents session exit when a ralph-loop is active
+# Feeds Claude's output back as input to continue the loop
+
+set -euo pipefail
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Check if ralph-loop is active
+RALPH_STATE_FILE=".claude/ralph-loop.local.md"
+
+if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+  # No active loop - allow exit
+  exit 0
+fi
+
+# Parse markdown frontmatter (YAML between ---) and extract values
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+# Extract REQ_ID for CC-DevFlow task status checking
+REQ_ID=$(echo "$FRONTMATTER" | grep '^req_id:' | sed 's/req_id: *//' | sed 's/^"\(.*\)"$/\1/' || echo "")
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Ralph loop: State file corrupted" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: 'iteration' field is not a valid number (got: '$ITERATION')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Ralph loop: State file corrupted" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: 'max_iterations' field is not a valid number (got: '$MAX_ITERATIONS')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check if max iterations reached
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
+
+if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
+  echo "⚠️  Ralph loop: Transcript file not found" >&2
+  echo "   Expected: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a Claude Code internal issue." >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Read last assistant message from transcript (JSONL format - one JSON per line)
+# First check if there are any assistant messages
+if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
+  echo "⚠️  Ralph loop: No assistant messages found in transcript" >&2
+  echo "   Transcript: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a transcript format issue" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Extract last assistant message with explicit error handling
+LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
+if [[ -z "$LAST_LINE" ]]; then
+  echo "⚠️  Ralph loop: Failed to extract last assistant message" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Parse JSON with error handling
+LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
+  .message.content |
+  map(select(.type == "text")) |
+  map(.text) |
+  join("\n")
+' 2>&1)
+
+# Check if jq succeeded
+if [[ $? -ne 0 ]]; then
+  echo "⚠️  Ralph loop: Failed to parse assistant message JSON" >&2
+  echo "   Error: $LAST_OUTPUT" >&2
+  echo "   This may indicate a transcript format issue" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ -z "$LAST_OUTPUT" ]]; then
+  echo "⚠️  Ralph loop: Assistant message contained no text content" >&2
+  echo "   Ralph loop is stopping." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check for completion promise (only if set)
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  # Extract text from <promise> tags using Perl for multiline support
+  # -0777 slurps entire input, s flag makes . match newlines
+  # .*? is non-greedy (takes FIRST tag), whitespace normalized
+  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
+
+  # Use = for literal string comparison (not pattern matching)
+  # == in [[ ]] does glob pattern matching which breaks with *, ?, [ characters
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "✅ Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
+    rm "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# CC-DevFlow specific: Check if all tasks completed
+if [[ -n "$REQ_ID" ]] && [[ -f ".claude/scripts/check-task-status.sh" ]]; then
+  remaining_count=$(bash .claude/scripts/check-task-status.sh --json 2>/dev/null | jq -r '.remaining' 2>/dev/null || echo "999")
+
+  if [[ "$remaining_count" == "0" ]]; then
+    echo "✅ Ralph loop: All tasks in TASKS.md completed!"
+    rm "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Extract prompt (everything after the closing ---)
+# Skip first --- line, skip until second --- line, then print everything after
+# Use i>=2 instead of i==2 to handle --- in prompt content
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "⚠️  Ralph loop: State file corrupted or incomplete" >&2
+  echo "   File: $RALPH_STATE_FILE" >&2
+  echo "   Problem: No prompt text found" >&2
+  echo "" >&2
+  echo "   This usually means:" >&2
+  echo "     • State file was manually edited" >&2
+  echo "     • File was corrupted during writing" >&2
+  echo "" >&2
+  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Update iteration in frontmatter (portable across macOS and Linux)
+# Create temp file, then atomically replace
+TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+
+# Build system message with iteration count and completion promise info
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when statement is TRUE - do not lie to exit!)"
+else
+  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | No completion promise set - loop runs infinitely"
+fi
+
+# Output JSON to block the stop and feed prompt back
+# The "reason" field contains the prompt that will be sent back to Claude
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+# Exit 0 for successful hook execution
+exit 0

package/.claude/rules/devflow-conventions.md

@@ -69,13 +69,15 @@ devflow/requirements/${reqId}/
 ### 分支命名
 ```bash
 # 标准格式
-feature/${reqId}-${slug(title)}
+feature/${reqId}-${slug(BRANCH_TITLE_EN)}
 
 # 示例
 feature/REQ-123-user-order-support
 feature/REQ-124-permission-management
 ```
 
+> BRANCH_TITLE_EN 为 TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
+
 ### 分支操作流程
 1. 检查当前在 main 分支且状态干净
 2. 创建特性分支

package/.claude/rules/project-constitution.md

@@ -1,8 +1,8 @@
 # CC-DevFlow Project Constitution
 
-> **Version**: v2.0.0
+> **Version**: v2.1.0
 > **Effective Date**: 2025-01-10
-> **Last Amended**: 2025-01-10
+> **Last Amended**: 2026-01-08
 > **Status**: Active
 > **Amendment Process**: See Section IX
 
@@ -24,6 +24,31 @@ This Constitution establishes the **immutable architectural DNA** of the CC-DevF
 
 **Principle**: Quality is the non-negotiable baseline.
 
+### The Iron Law
+
+```
+NO PARTIAL IMPLEMENTATION - COMPLETE OR NOTHING
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-i-quality-first---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "This is simplified for now" | CONSTITUTIONAL VIOLATION. Complete it or don't ship it. |
+| "Will complete in v2" | Future versions don't exist. Implement fully now. |
+| "80% is good enough" | 80% = broken for 20% of users. Not good enough. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "This is good enough for now"
+- "I'll fix it before PR"
+- "Core logic works, edge cases later"
+
+**STOP. You are rationalizing. Complete the implementation or don't ship.**
+
 ### I.1 Complete Implementation Mandate
 
 ```yaml
@@ -70,6 +95,31 @@ All code must pass:
 
 **Principle**: Maintain codebase uniformity and predictability.
 
+### The Iron Law
+
+```
+REUSE EXISTING CODE - NO DUPLICATION
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-ii-architectural-consistency---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Faster to rewrite" | Faster now = slower forever. Find and reuse. |
+| "Slightly different use case" | Extract common, parameterize difference. |
+| "I understand my version better" | Understand the shared version. That's your job. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "That code is messy, I'll write my own"
+- "I don't have time to search"
+- "It's just a small function"
+
+**STOP. Search the codebase. Reuse or refactor existing code.**
+
 ### II.1 No Code Duplication
 
 ```yaml
@@ -136,6 +186,31 @@ MODULE COHESION:
 
 **Principle**: Security is foundational, not an afterthought.
 
+### The Iron Law
+
+```
+NO HARDCODED SECRETS - ENVIRONMENT VARIABLES ONLY
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-iii-security-first---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "It's just for testing" | Commits are forever. Use env vars even for tests. |
+| "I'll remove it before commit" | You won't. You'll forget. Use env vars. |
+| "Local development only" | Local becomes production. Start secure. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "Nobody will see the repo"
+- "It's not a real secret"
+- "I'll rotate it later"
+
+**STOP. Never commit secrets. Use environment variables from the start.**
+
 ### III.1 No Hardcoded Secrets
 
 ```yaml
@@ -200,6 +275,31 @@ DEFAULT SECURITY:
 
 **Principle**: Performance is user experience; proactive optimization required.
 
+### The Iron Law
+
+```
+NO RESOURCE LEAKS - ALWAYS CLEANUP
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-iv-performance-accountability---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Garbage collector will handle it" | GC doesn't close files/connections. Explicit cleanup. |
+| "Small leak, won't matter" | Small leaks become big crashes. Fix now. |
+| "Framework handles it" | Verify that. Don't assume. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "It's a short-lived process"
+- "I'll add cleanup later"
+- "Only happens in edge case"
+
+**STOP. Add cleanup with creation. Edge cases run in production.**
+
 ### IV.1 No Resource Leaks
 
 ```yaml
@@ -272,6 +372,31 @@ INTELLIGENT CACHING:
 
 **Principle**: Code must be understandable, modifiable, and extensible.
 
+### The Iron Law
+
+```
+NO DEAD CODE - USE IT OR DELETE IT
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-v-maintainability---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Might need it later" | Git history exists. Delete now, retrieve if needed. |
+| "It's just commented out" | Commented code = noise. Delete it. |
+| "Too risky to delete" | Tests exist. If tests pass after delete, it's safe. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "Reference for future work"
+- "Someone else might need it"
+- "I worked hard on this"
+
+**STOP. Sunk cost fallacy. Delete dead code. Git remembers.**
+
 ### V.1 No Dead Code
 
 ```yaml
@@ -340,6 +465,33 @@ SIZE CONSTRAINTS:
 
 **Principle**: Tests define behavior; implementation makes tests pass.
 
+### The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-vi-test-first-development---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "TDD slows me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "This is different because..." | No. This is rationalization. Follow the law. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "Just this once"
+- "I'm being pragmatic, not dogmatic"
+- "Spirit not letter"
+- "Need to explore first" (without deleting exploration code)
+
+**STOP. You are rationalizing. Delete the code. Write the test first.**
+
 ### VI.1 TDD Mandate (NON-NEGOTIABLE)
 
 ```yaml
@@ -399,6 +551,31 @@ TEST QUALITY:
 
 **Principle**: Default to simplicity; complexity requires justification.
 
+### The Iron Law
+
+```
+MAXIMUM 3 PROJECTS - JUSTIFY ANY ADDITIONAL COMPLEXITY
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-vii-simplicity-gate---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Microservices are better" | For your scale? Monolith is simpler. Start there. |
+| "Future scalability" | YAGNI. Scale when you need to. |
+| "Best practices say..." | Best practices assume scale you don't have. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "Separation of concerns" (as justification for new project)
+- "Team autonomy"
+- "We might need it"
+
+**STOP. Build for now. Refactor when needed. Complexity is the enemy.**
+
 ### VII.1 Project Count Limit
 
 ```yaml
@@ -434,6 +611,31 @@ YAGNI ENFORCEMENT:
 
 **Principle**: Trust frameworks; avoid unnecessary wrapping.
 
+### The Iron Law
+
+```
+USE FRAMEWORKS DIRECTLY - NO UNNECESSARY WRAPPERS
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-viii-anti-abstraction---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Abstraction for future flexibility" | YAGNI. You won't switch frameworks. |
+| "Cleaner interface" | Framework interface IS clean. Learn it. |
+| "Easier testing" | Mock the framework. Don't wrap it. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "Hide implementation details"
+- "Consistent with other projects"
+- "Best practice pattern"
+
+**STOP. Use the framework directly. Wrappers add complexity, not value.**
+
 ### VIII.1 Direct Framework Usage
 
 ```yaml
@@ -470,6 +672,31 @@ ONE ENTITY, ONE REPRESENTATION:
 
 **Principle**: Test with real environments, not mocks.
 
+### The Iron Law
+
+```
+CONTRACTS FIRST - REAL ENVIRONMENTS
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-ix-integration-first-testing---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "Unit tests are faster" | Fast wrong tests waste time. Integration tests catch real bugs. |
+| "Mocks are simpler" | Mocks hide integration issues. Real databases find them. |
+| "In-memory database works" | In-memory differs from production. Test with real DB. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "CI is slow"
+- "Docker is complex"
+- "We can mock this"
+
+**STOP. Production bugs are expensive. Test with real environments.**
+
 ### IX.1 Contract-First
 
 ```yaml
@@ -507,6 +734,32 @@ INTEGRATION TESTING:
 
 **Principle**: Implement what's requested, nothing more.
 
+### The Iron Law
+
+```
+IMPLEMENT WHAT'S REQUESTED, NOTHING MORE
+```
+
+### Rationalization Defense
+
+> See [rationalization-library.md](./rationalization-library.md#article-x-requirement-boundary---rationalization-table) for full table.
+
+| Excuse | Reality |
+|--------|---------|
+| "User might need this later" | User didn't ask. Don't add. YAGNI. |
+| "It's just a small addition" | Small additions compound. Scope creep. |
+| "I'm being helpful" | Helpful = following spec. Unhelpful = scope creep. |
+
+### Red Flags - STOP
+
+If you find yourself thinking:
+- "While I'm here anyway"
+- "It's only 5 more lines"
+- "User will thank me"
+- "This is a natural extension"
+
+**STOP. Stay on task. Create separate requirement for extensions.**
+
 ### X.1 Forced Clarification
 
 ```yaml
@@ -744,5 +997,6 @@ This Constitution is the **architectural DNA** of CC-DevFlow. All templates, age
 *CC-DevFlow Project Constitution - Ensuring Excellence, Rejecting Compromise*
 
 **Version History**:
+- v2.1.0 (2026-01-08): Added Iron Law + Rationalization Defense + Red Flags to all 10 Articles
 - v2.0.0 (2025-10-09): Article-based restructure, enforcement mechanisms, amendment process
 - v1.0.0 (2025-01-20): Initial version with five core principles