cc-devflow 1.0.2 → 2.4.0

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

@@ -0,0 +1,218 @@
+---
+name: flow-tdd
+description: "Enforces TDD Iron Law in flow-dev. NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST."
+---
+
+# Flow TDD - Test-Driven Development Enforcement
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+This is NON-NEGOTIABLE. No exceptions. No "just this once."
+
+## The TDD Cycle
+
+```
+RED:    Write a failing test
+        → Run it
+        → Confirm it FAILS
+        → If it passes immediately → ERROR (invalid test)
+
+GREEN:  Write minimal code to pass
+        → Only enough to make the test pass
+        → No extra features
+        → No "while I'm here" additions
+
+REFACTOR: Clean up
+        → Keep tests green
+        → Improve structure
+        → Remove duplication
+```
+
+## Enforcement in flow-dev
+
+### Phase 2: Tests First
+
+```yaml
+TASKS.md Phase 2 (Tests):
+  - Write contract tests
+  - Write integration tests
+  - Write unit tests
+  - Run all tests → ALL MUST FAIL
+
+⚠️ TEST VERIFICATION CHECKPOINT:
+  → Run: npm test (or equivalent)
+  → Expected: All new tests FAIL
+  → If any test passes immediately → STOP
+  → Passing test = invalid test or code already exists
+```
+
+### Phase 3: Implementation
+
+```yaml
+TASKS.md Phase 3 (Implementation):
+  - Implement to make tests pass
+  - One test at a time
+  - Minimal code only
+
+After each implementation:
+  → Run tests
+  → Verify previously failing test now passes
+  → Verify no regressions
+```
+
+## What If Code Already Exists?
+
+If you've written code before tests:
+
+```yaml
+Option A: DELETE AND RESTART (Recommended)
+  1. Delete the implementation code
+  2. Keep only the interface/contract
+  3. Write failing tests
+  4. Re-implement with TDD
+
+Option B: WRITE TESTS THAT FAIL FIRST
+  1. Comment out the implementation
+  2. Write tests
+  3. Run tests → verify they fail
+  4. Uncomment implementation
+  5. Run tests → verify they pass
+
+NEVER: Keep code and write passing tests
+  → This is "testing after" disguised as TDD
+  → Tests that pass immediately prove nothing
+```
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
+| "TDD slows me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "This is different because..." | No. This is rationalization. Follow the law. |
+| "Spirit not letter" | Violating letter IS violating spirit. No loopholes. |
+| "I'm being pragmatic, not dogmatic" | TDD IS pragmatic. Shortcuts = debugging in production = slower. |
+| "Just this once" | No exceptions. Rules exist for this exact moment. |
+
+## Red Flags - STOP
+
+If you find yourself:
+- Writing code before tests
+- Tests passing immediately
+- Saying "just this once"
+- Keeping "exploration" code
+- Writing tests that describe existing code
+
+**STOP. Delete the code. Write the test first.**
+
+## Test Quality Requirements
+
+```yaml
+Good Tests:
+  ✅ Test behavior, not implementation
+  ✅ Use realistic data
+  ✅ Cover edge cases
+  ✅ Independent (no shared state)
+  ✅ Fast (< 1 second each)
+  ✅ Descriptive names
+
+Bad Tests (Cheater Tests):
+  ❌ assert True
+  ❌ assert result is not None
+  ❌ Mock everything, test nothing
+  ❌ Test implementation details
+  ❌ Depend on execution order
+```
+
+## Error Recording Protocol
+
+当测试失败或构建错误发生时，必须立即记录到 ERROR_LOG.md:
+
+```yaml
+Error Recording Workflow:
+  1. Capture Error Context:
+     - Phase (flow-dev / T###)
+     - Error Type (Test Failure | Build Error | Runtime Error)
+     - Full error message
+     - Timestamp
+
+  2. Create ERROR_LOG.md if not exists:
+     → Use .claude/docs/templates/ERROR_LOG_TEMPLATE.md
+     → Location: devflow/requirements/${REQ_ID}/ERROR_LOG.md
+
+  3. Append Error Record:
+     ## [TIMESTAMP] E###: TITLE
+     **Phase**: flow-dev / T###
+     **Error Type**: Test Failure
+     **Error Message**:
+     ```
+     [完整错误信息]
+     ```
+     **Root Cause**: [分析后填写]
+     **Resolution**: [解决后填写]
+     **Prevention**: [可选]
+
+  4. Debug with Error Context:
+     → Read ERROR_LOG.md for similar past errors
+     → Apply attention refresh (Protocol 4)
+     → Fix the root cause, not symptoms
+
+  5. Update Record After Fix:
+     → Fill Root Cause
+     → Fill Resolution
+     → Add Prevention if applicable
+```
+
+### Error Recording Example
+
+```markdown
+## [2026-01-08T14:30:00] E001: Test Failure - User Login Validation
+
+**Phase**: flow-dev / T005
+**Error Type**: Test Failure
+**Error Message**:
+\`\`\`
+FAIL src/auth/login.test.ts
+  × should reject invalid email format
+    Expected: false
+    Received: true
+\`\`\`
+
+**Root Cause**: 正则表达式 `/^.+@.+$/` 过于宽松，接受了 `user@` 这样的无效邮箱
+**Resolution**: 更新正则为 `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` 要求至少有域名和顶级域
+**Prevention**: 扩充测试用例，添加边界情况（无域名、无顶级域、特殊字符等）
+```
+
+## Integration with Constitution
+
+- **Article I**: Complete implementation includes tests
+- **Article VI**: TDD Mandate (this skill)
+- **Article IX**: Integration-first testing
+
+## Integration with Attention Refresh
+
+- **Protocol 4**: Error Recovery 时读取 ERROR_LOG.md
+- 避免重复犯相同错误
+- 从历史错误中学习
+
+## Cross-Reference
+
+- [flow-attention-refresh](../flow-attention-refresh/SKILL.md) - Protocol 4
+- [ERROR_LOG_TEMPLATE.md](../../docs/templates/ERROR_LOG_TEMPLATE.md)
+- [rationalization-library.md](../../rules/rationalization-library.md#article-vi-test-first-development---rationalization-table)
+- [project-constitution.md](../../rules/project-constitution.md#article-vi-test-first-development-测试优先开发)
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

package/.claude/skills/fractal-docs-generator/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fractal-docs-generator
+description: 目录级 CLAUDE.md 生成。触发：mkdir、create directory、目录结构变更。
+---
+
+# 分形文档生成器
+
+触发：创建/移动/重命名目录，目录内文件变化。
+
+## 模板
+
+```markdown
+<!-- 若此目录变更，立即更新本文件 -->
+# {目录名} - {一句话定位}
+
+| 文件 | 地位 | 职责 |
+|------|------|------|
+| foo.ts | 入口 | 对外唯一接口 |
+```
+
+## 地位
+
+| 地位 | 典型文件 |
+|------|----------|
+| 入口 | index.ts, main.ts |
+| 核心 | service.ts, engine.ts |
+| 辅助 | utils.ts, helpers.ts |
+| 类型 | types.ts |
+| 配置 | config.ts |
+| 测试 | *.test.ts |
+
+## 示例
+
+```markdown
+<!-- 若此目录变更，立即更新本文件 -->
+# auth - 认证授权
+
+| 文件 | 地位 | 职责 |
+|------|------|------|
+| index.ts | 入口 | 导出 AuthService |
+| auth.service.ts | 核心 | 登录、令牌刷新 |
+| jwt.helper.ts | 辅助 | JWT 签发验证 |
+```
+
+协作：本 skill 管目录，file-header-guardian 管文件。

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

@@ -129,6 +129,81 @@
                 "envOverride": "SKIP_CONSTITUTION_CHECK"
             }
         },
+        "fractal-docs-generator": {
+            "type": "domain",
+            "enforcement": "suggest",
+            "priority": "high",
+            "description": "分形文档生成器。创建目录时自动生成目录级 CLAUDE.md，实现 GEB 式递归架构文档",
+            "promptTriggers": {
+                "keywords": [
+                    "创建目录",
+                    "新建文件夹",
+                    "mkdir",
+                    "add folder",
+                    "create directory",
+                    "目录结构",
+                    "CLAUDE.md",
+                    "架构文档",
+                    "分形文档"
+                ],
+                "intentPatterns": [
+                    "(创建|新建|添加).*?(目录|文件夹|folder|directory)",
+                    "(mkdir|create|add).*?(folder|directory|dir)",
+                    "目录.*?(结构|变更|调整)",
+                    "(更新|同步).*?CLAUDE\\.md"
+                ]
+            },
+            "fileTriggers": {
+                "pathPatterns": [
+                    "**/CLAUDE.md"
+                ]
+            }
+        },
+        "file-header-guardian": {
+            "type": "domain",
+            "enforcement": "suggest",
+            "priority": "high",
+            "description": "文件头注释守护者。创建/修改代码文件时确保 @input/@output/@pos 三行契约注释存在",
+            "promptTriggers": {
+                "keywords": [
+                    "创建文件",
+                    "新建文件",
+                    "write file",
+                    "create file",
+                    "add file",
+                    "文件头注释",
+                    "头注释",
+                    "@input",
+                    "@output",
+                    "@pos"
+                ],
+                "intentPatterns": [
+                    "(创建|新建|添加|编写).*?(文件|模块|组件)",
+                    "(create|write|add).*?(file|module|component)",
+                    "(检查|更新|添加).*?(头注释|header comment)",
+                    "文件.*?(注释|documentation)"
+                ]
+            },
+            "fileTriggers": {
+                "pathPatterns": [
+                    "**/*.ts",
+                    "**/*.tsx",
+                    "**/*.js",
+                    "**/*.jsx",
+                    "**/*.py",
+                    "**/*.go",
+                    "**/*.rs",
+                    "**/*.sh"
+                ],
+                "pathExclusions": [
+                    "**/*.test.ts",
+                    "**/*.spec.ts",
+                    "**/*.d.ts",
+                    "**/node_modules/**",
+                    "**/.claude/**"
+                ]
+            }
+        },
         "devflow-file-standards": {
             "type": "domain",
             "enforcement": "suggest",

package/.claude/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: verification-before-completion
+description: "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always"
+---
+
+# Verification Before Completion
+
+## Overview
+
+This skill enforces a critical discipline: **never claim completion without fresh verification evidence**.
+
+The most common failure mode for AI agents is claiming success without actually verifying. This skill prevents that by requiring explicit verification steps before any completion claim.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+## The Process
+
+### Before ANY Completion Claim
+
+```
+1. IDENTIFY: What command proves this claim?
+   → "Tests pass" requires: npm test / pytest / go test
+   → "Build succeeds" requires: npm run build / make
+   → "Lint clean" requires: npm run lint / eslint
+   → "Type check passes" requires: tsc --noEmit / mypy
+
+2. RUN: Execute the FULL command (fresh, complete)
+   → Not cached results
+   → Not partial output
+   → Not "I ran it earlier"
+
+3. READ: Full output, check exit code, count failures
+   → Exit code 0 = success
+   → Exit code non-zero = failure
+   → Count actual pass/fail numbers
+
+4. VERIFY: Does output confirm the claim?
+   → "All tests pass" = 0 failures in output
+   → "Build succeeds" = no errors, artifacts created
+   → "No lint errors" = 0 problems found
+
+5. ONLY THEN: Make the claim with evidence
+   → Quote the relevant output
+   → Include exit code
+   → Show pass/fail counts
+```
+
+## Verification Commands by Context
+
+### Flow Exit Gates
+
+| Flow | Verification Command | Success Criteria |
+|------|---------------------|------------------|
+| /flow-prd | `validate-constitution --type prd` | Exit 0, no violations |
+| /flow-epic | `validate-constitution --type epic` | Exit 0, no violations |
+| /flow-dev | `npm test && npm run build` | All tests pass, build succeeds |
+| /flow-qa | `npm test && npm run lint` | All pass, no blockers |
+| /flow-release | `gh pr checks` | All checks pass |
+
+### Common Development Tasks
+
+| Claim | Required Verification |
+|-------|----------------------|
+| "Tests pass" | Run full test suite, show output |
+| "Build succeeds" | Run build command, show output |
+| "Lint clean" | Run linter, show 0 errors |
+| "Type check passes" | Run type checker, show output |
+| "No regressions" | Run affected tests, compare before/after |
+| "Bug fixed" | Show failing test → fix → passing test |
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "I just ran it" | Run it again. Fresh evidence required. |
+| "It was passing before" | Before ≠ now. Verify current state. |
+| "The change is trivial" | Trivial changes break things. Verify. |
+| "I'm confident it works" | Confidence ≠ evidence. Run the command. |
+| "Tests are slow" | Slow tests > broken production. Run them. |
+| "I'll verify after commit" | Verify BEFORE commit. Always. |
+| "The CI will catch it" | You catch it first. Don't waste CI cycles. |
+| "It's just documentation" | Doc changes can break builds. Verify. |
+
+## Red Flags - STOP
+
+If you find yourself:
+- Saying "should work" without running verification
+- Claiming "tests pass" without showing output
+- Saying "I believe" instead of "I verified"
+- Skipping verification "just this once"
+- Trusting cached or stale results
+
+**STOP. Run the verification command. Show the evidence.**
+
+## Evidence Format
+
+When claiming completion, always include:
+
+```markdown
+## Verification Evidence
+
+**Command**: `npm test`
+**Exit Code**: 0
+**Output Summary**:
+- Tests: 42 passed, 0 failed
+- Coverage: 85%
+- Duration: 12.3s
+
+**Conclusion**: All tests pass. Ready for commit.
+```
+
+## Integration with CC-DevFlow
+
+### Every Flow Exit Gate
+
+```yaml
+Exit Gate Verification:
+  1. Identify required verification commands
+  2. Run each command fresh
+  3. Capture full output
+  4. Verify success criteria met
+  5. Document evidence in EXECUTION_LOG.md
+  6. Only then proceed to next stage
+```
+
+### Task Completion
+
+```yaml
+Task Completion Verification:
+  1. Run task-specific tests
+  2. Verify acceptance criteria met
+  3. Show evidence in task completion message
+  4. Mark task complete only with evidence
+```
+
+## The Discipline
+
+This skill is about **intellectual honesty**. It's easy to believe something works. It's harder to prove it.
+
+The discipline is:
+1. **Assume nothing** - Don't trust memory or intuition
+2. **Verify everything** - Run the actual commands
+3. **Show evidence** - Quote output, not beliefs
+4. **Fresh results only** - No stale or cached data
+
+## Cross-Reference
+
+- Constitution Article I: Quality First (complete implementation)
+- Constitution Article VI: Test-First Development (TDD)
+- rationalization-library.md: Cross-Article rationalizations
+
+---
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md

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

@@ -1 +1,2 @@
-1766298239	Edit	/Users/dimon/001Area/80-CodeWorld/002-devflow/cc-devflow/package.json	root
+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