@curdx/flow 1.1.4 → 1.1.6

package/knowledge/two-stage-review.md

@@ -0,0 +1,233 @@
+# Two-Stage Review — Two-Stage Code Review
+
+> CurDX-Flow version of Superpowers' code review skill.
+>
+> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md`.
+
+---
+
+## Why Two Stages
+
+One stage can't do it all. Separate "is it the right thing" from "is it done well":
+
+```
+Stage 1: Spec Compliance
+  Question: "Does the code actually implement what the spec asked for?"
+  Focus:   landing of FR / AC / AD
+
+Stage 2: Code Quality
+  Question: "Is the implementation done well?"
+  Focus:   style / tests / maintainability / performance
+```
+
+Downsides of reviewing them together:
+- Find quality issues → but the code doesn't implement the requirements → quality polish is wasted
+- Find missing requirements → quality advice drowns
+- Findings are numerous and unsorted → user doesn't know what to fix first
+
+Benefits of separation:
+- Stage 1 passing gates Stage 2 → saves time
+- Report is layered → user first fixes "not done right" then "not done well enough"
+
+---
+
+## Stage 1: Spec Compliance
+
+### Core question
+
+**Is this doing what the spec asked for?**
+
+### Checklist
+
+#### 1.1 FR coverage
+
+For each FR-NN (from requirements.md):
+- Can you find a corresponding implementation in the code?
+- Is it real or a stub (`throw new Error('not implemented')`)?
+- Does a commit reference this FR (footer `Requirements: FR-NN`)?
+
+#### 1.2 AC verifiable
+
+For each AC-X.Y:
+- Is there a corresponding test case?
+- Does the test actually run (not skipped)?
+- Does the test actually exercise the AC behavior, not just a placeholder?
+
+#### 1.3 AD landing
+
+For each AD-NN (from design.md):
+- Does the code reflect this decision?
+- Is the decision not violated?
+- If violated, was design.md bumped in version + new AD recorded?
+
+#### 1.4 Out-of-scope respected
+
+Against the "out of scope" list in requirements.md:
+- Does the code actually **not do** these?
+- If it does, was it an intentional extension (with an explanatory commit), or scope creep?
+
+#### 1.5 Error paths
+
+Against the "error paths" table in design.md:
+- Is each scenario handled?
+- Is there a corresponding test?
+
+### Stage 1 verdict
+
+- **PASS**: all FR / AD fully implemented, all AC have corresponding tests
+- **PARTIAL**: implemented, but some FR / AC lack tests
+- **FAIL**: some FR / AD not implemented, or out-of-scope leakage
+
+---
+
+## Stage 2: Code Quality
+
+### Core question
+
+**Is the implementation done well? Can a future maintainer pick it up?**
+
+### Dimensions
+
+Stage 2 applies all enabled Gates (from `.flow/config.json`):
+
+#### 2.1 Karpathy 4 principles (karpathy-gate)
+
+- Assumptions explicit?
+- Over-engineered?
+- Surgical?
+- Claims without evidence?
+
+#### 2.2 Verification baseline (verification-gate)
+
+- Do commit messages / `.progress.md` contain forbidden words?
+- Do claims have fresh evidence?
+
+#### 2.3 TDD discipline (tdd-gate)
+
+- Is there a `test(xxx): red -` before a `feat(xxx):` commit?
+- Are exemptions recorded in STATE.md?
+
+#### 2.4 Coverage completeness (coverage-audit-gate)
+
+- All 4 sources (FR / AD / Research / Decisions) covered?
+
+#### 2.5 (enterprise) Adversarial review (adversarial-review-gate)
+
+- ≥ 3 categories of issues found?
+- Each finding has evidence + recommendation?
+
+#### 2.6 (enterprise) Edge cases (edge-case-gate)
+
+- Did all 7 major categories pass?
+- Gap list has priorities?
+
+### Stage 2 verdict
+
+- **EXCELLENT**: all enabled Gates pass, adversarial findings < 3 (high-quality code)
+- **GOOD**: all enabled Gates pass, but some warnings
+- **NEEDS_IMPROVEMENT**: Gate violations (blocking)
+
+---
+
+## Combined Verdict
+
+```python
+def verdict(stage1, stage2):
+    # Stage 1 must pass to proceed to Stage 2
+    if stage1 == "FAIL":
+        return "BLOCKED_BY_SPEC"  # must go back to /curdx-flow:implement
+
+    if stage1 == "PARTIAL" and stage2 == "EXCELLENT":
+        return "APPROVED_WITH_WARNINGS"  # few tests but code is good
+
+    if stage2 == "NEEDS_IMPROVEMENT":
+        return "BLOCKED_BY_QUALITY"  # Gate violations must be fixed
+
+    if stage1 == "PASS" and stage2 == "EXCELLENT":
+        return "APPROVED"
+
+    return "APPROVED_WITH_WARNINGS"
+```
+
+---
+
+## Fix Loop
+
+When the review turns up issues, the typical flow:
+
+```
+1. Review returns NEEDS_FIXES
+  ↓
+2. User decides what must be fixed vs tolerated
+  ↓
+3. Fix:
+   - Spec class: /curdx-flow:implement --task=add a new task
+   - Quality class: /curdx-flow:implement rerun a task
+   - Miscellaneous: /curdx-flow:fast "fix X raised by review"
+  ↓
+4. /curdx-flow:review re-review
+  ↓
+5. Until APPROVED → /curdx-flow:ship
+```
+
+---
+
+## Failure Modes of Two Stages
+
+### Anti-pattern 1: "I'll just read the code"
+
+Some reviewers skip the spec comparison and read the code directly. Result:
+- "Code looks quality" → but doesn't implement the requirements
+- Missed key FRs
+- Over-focus on details, miss architectural decisions
+
+**Correction**: Stage 1 must walk through the FR/AC/AD checklist item by item.
+
+### Anti-pattern 2: "Close enough"
+
+Some reviewers find a missing FR but give APPROVED because the code quality is high.
+
+**Correction**: Stage 1 FAIL is BLOCKED. "Trading quality for compliance" is not allowed.
+
+### Anti-pattern 3: "Too many findings"
+
+Some reviewers list 50 minor improvements — the user can't process.
+
+**Correction**: tier them — blocker / warning / suggestion. User only needs to look at blockers.
+
+### Anti-pattern 4: "No evidence"
+
+"This could be improved" / "feels the code quality isn't high enough".
+
+**Correction**: every finding has **file:line + evidence + recommendation**.
+
+---
+
+## Relationship to Other Phases
+
+```
+/curdx-flow:tasks  →  tasks.md contains task list
+     ↓
+/curdx-flow:implement  →  code + tests + commits
+     ↓
+/curdx-flow:verify  →  Goal-backward verification (flow-verifier)
+     ↓                     ↓
+     ↓              verification-report.md
+     ↓
+/curdx-flow:review  →  Two-Stage Review (flow-reviewer)
+     ↓                     ↓
+     ↓              review-report.md
+     ↓
+(optional) /curdx-flow:audit  →  adversarial review + edge cases
+                    ↓
+                    adversarial-review.md
+                    edge-cases.md
+     ↓
+/curdx-flow:ship  →  PR (Phase 6+)
+```
+
+Verify is "did we implement the right thing", Review is "is the implementation good", Audit is "what else could be better".
+
+---
+
+_Source: superpowers' code-review two-stage design, extended with CurDX-Flow's Gate system._

package/knowledge/wave-execution.md

@@ -0,0 +1,387 @@
+# Wave Execution — DAG Parallel Execution Strategy
+
+> One of Phase 2's 4 execution strategies. Identify parallel-safe task groups via `[P]` markers, dispatch multiple Task tool calls **in a single message**, run in parallel within a wave and serially across waves.
+>
+> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`.
+
+---
+
+## Core Concepts
+
+### Wave = a group of parallel-safe tasks
+
+A wave is **a consecutive run of `[P]`-marked tasks**. Within a wave, run in parallel; across waves, run serially.
+
+```
+tasks.md:
+  1.1 [P] create auth directory
+  1.2 [P] create user directory
+  1.3 [P] create session directory
+  1.4 [VERIFY] verify directory structure
+  1.5     init index.ts (depends on 1.1-1.3)
+  1.6 [P] add README to auth
+  1.7 [P] add README to user
+
+Analysis:
+  Wave 1: { 1.1, 1.2, 1.3 }     — parallel (3 Tasks)
+  Wave 2: { 1.4 }                — serial (VERIFY breaks)
+  Wave 3: { 1.5 }                — serial (no [P])
+  Wave 4: { 1.6, 1.7 }           — parallel (2 Tasks)
+```
+
+---
+
+## DAG Analysis Algorithm
+
+```python
+def analyze_waves(tasks):
+    waves = []
+    current_wave = []
+
+    for task in tasks:
+        if task.status == 'completed':
+            continue
+
+        # markers that break parallelism
+        if task.has_flag('SEQUENTIAL') or task.has_flag('VERIFY'):
+            # end current wave
+            if current_wave:
+                waves.append(current_wave)
+                current_wave = []
+            # this task becomes its own wave
+            waves.append([task])
+            continue
+
+        # has [P] → candidate for current wave
+        if task.has_flag('P'):
+            # conflict detection: do Files intersect the current wave's files?
+            if has_file_conflict(task, current_wave):
+                # conflict → start a new wave
+                waves.append(current_wave)
+                current_wave = [task]
+            else:
+                current_wave.append(task)
+
+        # no [P] → own wave
+        else:
+            if current_wave:
+                waves.append(current_wave)
+                current_wave = []
+            waves.append([task])
+
+    # cleanup
+    if current_wave:
+        waves.append(current_wave)
+
+    return waves
+```
+
+### Conflict detection
+
+```python
+def has_file_conflict(task, wave):
+    """Do task's Files intersect any wave task's Files?"""
+    task_files = set(task.files)
+    for other in wave:
+        if task_files & set(other.files):
+            return True
+    return False
+```
+
+Rules:
+- Two `[P]` tasks editing the same file → conflict, must split into different waves
+- Two `[P]` tasks creating different files → OK
+- One reads what another writes → **conflict** (reads aren't guaranteed to see latest)
+
+---
+
+## How Parallel Task Dispatch Actually Works
+
+### Key: multiple Task tool calls in a single message
+
+Claude Code's Task tool runs in parallel **when multiple calls appear in the same message**.
+Across **separate messages** → runs sequentially.
+
+### Correct form (Wave strategy)
+
+```
+# In a single main-agent response:
+
+Task(description="Task 1.1", prompt="...execute 1.1...")
+Task(description="Task 1.2", prompt="...execute 1.2...")
+Task(description="Task 1.3", prompt="...execute 1.3...")
+
+# Wait for all to return before continuing to the next wave
+```
+
+### Incorrect form (degenerates to serial subagent)
+
+```
+# One response:
+Task(description="Task 1.1", ...)
+# wait for return
+# Next response:
+Task(description="Task 1.2", ...)
+# wait for return
+# Next response:
+Task(description="Task 1.3", ...)
+```
+
+This is not parallel — it's serial subagent. The Wave strategy loses its meaning.
+
+---
+
+## Full Wave Dispatch Flow
+
+```
+for wave_index, wave in enumerate(waves):
+
+    # === Step 1: show wave info ===
+    echo "▶ Wave $wave_index: parallel ${#wave} tasks"
+    for task in wave:
+        echo "  • $task.id $task.title"
+
+    # === Step 2: dispatch (key: within a single message) ===
+    # This is the main agent's response body. Call N Task tools at once.
+    results = await asyncio.gather([
+        Task(
+            description=f"execute {task.id}",
+            prompt=f"""
+              You are the flow-executor agent.
+              Full definition: ${CLAUDE_PLUGIN_ROOT}/agents/flow-executor.md
+
+              Execute single task:
+              spec_name: {spec_name}
+              task_id: {task.id}
+              quick_mode: {quick_mode}
+
+              You may only edit the following files:
+              {task.files}
+
+              Output TASK_COMPLETE / TASK_FAILED
+            """,
+        )
+        for task in wave
+    ])
+
+    # === Step 3: aggregate results ===
+    completed = [t for t, r in zip(wave, results) if "TASK_COMPLETE" in r]
+    failed = [t for t, r in zip(wave, results) if "TASK_FAILED" in r]
+
+    # === Step 4: post-hoc conflict check ===
+    # After wave tasks complete, check for unexpected edits
+    git_status = run("git status --short")
+    # For each task, confirm it only edited its declared Files
+    for task in completed:
+        declared_files = set(task.files)
+        actual_changed = get_changed_files_since_wave_start(task)
+        if actual_changed - declared_files:
+            # Unexpected edits
+            warn(f"Wave {wave_index} task {task.id} edited undeclared files: {actual_changed - declared_files}")
+            # Don't fail immediately, but record
+
+    # === Step 5: failure handling ===
+    if failed:
+        # Policy:
+        # - 1 failure: continue other waves, report after completion
+        # - ≥ 2 failures: stop execution, user intervenes
+        if len(failed) == 1:
+            record_failure(failed[0])
+            continue_to_next_wave()
+        else:
+            stop_and_report(failed)
+            return
+
+    # === Step 6: inter-wave synchronization point ===
+    # All Tasks complete = wave ends
+    # Before next wave starts, confirm git state is consistent
+
+# All waves done
+echo "ALL_TASKS_COMPLETE"
+```
+
+---
+
+## Three Kinds of File Conflicts
+
+### Case 1: no conflict (ideal)
+
+```
+Task 1.1 [P]: create src/auth/login.ts       (Files: auth/login.ts)
+Task 1.2 [P]: create src/user/profile.ts     (Files: user/profile.ts)
+Task 1.3 [P]: create src/session/token.ts    (Files: session/token.ts)
+```
+
+→ Same wave, parallel, no problem.
+
+### Case 2: same-file conflict (must split waves)
+
+```
+Task 2.1 [P]: modify src/index.ts to add auth export   (Files: index.ts)
+Task 2.2 [P]: modify src/index.ts to add user export   (Files: index.ts)
+```
+
+→ Both edit `index.ts`, editing concurrently **conflicts**.
+
+flow-planner should catch this and remove `[P]` from one of them.
+If the planner misses it, flow-implement's conflict detection should split the wave.
+
+### Case 3: read-write conflict (implicit)
+
+```
+Task 3.1 [P]: modify Order type definition       (Files: types/order.ts)
+Task 3.2 [P]: use Order to implement payment    (Files: payment/process.ts, imports types/order.ts)
+```
+
+→ 3.2 imports 3.1's change. Parallel → 3.2 may see the old Order.
+
+Such **implicit dependencies** are harder to detect. Best is for flow-planner to avoid `[P]` across such dependencies when generating tasks.
+
+---
+
+## Failure Handling Policies
+
+### Single task failure
+
+```
+Wave 1 contains { 1.1, 1.2, 1.3 }
+  1.1 → TASK_COMPLETE
+  1.2 → TASK_FAILED
+  1.3 → TASK_COMPLETE
+
+Decision:
+  - 1.2 marked failed, recorded to .state.json
+  - 1.1 and 1.3 commits retained
+  - Main agent decides:
+    A: continue to Wave 2 (skip 1.2, possible cascading failure)
+    B: dispatch David (flow-debugger) to fix 1.2, then continue
+    C: stop and report, let the user intervene
+
+  Default: A, but failed_attempts += 1; after threshold switch to C
+```
+
+### Entire wave failed
+
+```
+Wave 1 all TASK_FAILED
+
+Decision:
+  - Usually indicates an upstream environment problem (missing deps, tsc config wrong)
+  - Stop immediately
+  - Suggest user run /curdx-flow:doctor to diagnose
+```
+
+### Inter-wave dependency broken
+
+```
+Wave 1 output is depended on by Wave 2
+Wave 1 has failures → Wave 2 may also fail
+
+Decision:
+  - After Wave 1 fails, evaluate whether Wave 2 can still run
+  - If each Wave 2 task's Files are unrelated to failed Wave 1 task Files → continue
+  - Otherwise → stop
+```
+
+---
+
+## When to Choose the Wave Strategy
+
+### Suitable
+
+- ✓ `[P]` markers make up ≥ 40% of tasks.md
+- ✓ Task groups are independent (different modules, different components)
+- ✓ Shortest wall-clock time desired
+- ✓ You trust that planner-marked `[P]` is accurate
+
+### Not suitable
+
+- ✗ Many `[SEQUENTIAL]` in tasks (wave degenerates to linear)
+- ✗ Tasks depend on each other (use serial subagent)
+- ✗ Debugging (need to see the full process — use linear)
+- ✗ Parallel overhead > task duration (e.g., 1-second tasks with 10-second dispatch)
+
+---
+
+## Monitoring and Interruption
+
+### In-progress view
+
+`/curdx-flow:status` shows:
+```
+Spec: auth-system
+Strategy: wave
+Progress: Wave 2/5 (60%)
+  Wave 1 [P×3]: ✓✓✓
+  Wave 2 [P×2]: ●● (in progress)
+  Wave 3 [VERIFY]: ○
+  ...
+```
+
+### Ctrl+C interruption
+
+- Running Task calls in the current wave keep going (Claude Code's Task is an independent process)
+- Next `/curdx-flow:switch` shows some tasks already committed
+- Resume from the failing task
+
+---
+
+## Configuration
+
+`.flow/config.json`:
+
+```json
+{
+  "execution": {
+    "strategy": "wave",
+    "max_parallel": 5,
+    "wave_fail_policy": "continue-on-single | stop-on-any"
+  }
+}
+```
+
+- `max_parallel`: maximum parallel tasks per wave (default 5, to avoid API rate limits)
+- `wave_fail_policy`: default behavior on single task failure
+
+---
+
+## Mixing with Other Strategies
+
+Sometimes a single tasks.md doesn't fit one strategy. **Mixed strategies** are supported:
+
+```bash
+# Run fast waves first, fall back to linear single-task debugging on failure
+/curdx-flow:implement --strategy=wave
+# Wave strategy runs until a task fails repeatedly → stop
+/curdx-flow:implement --task=2.3 --strategy=linear
+# After fixing, continue with waves
+/curdx-flow:implement --strategy=wave
+```
+
+Phase 6+ will consider automatic fallback.
+
+---
+
+## Common Pitfalls
+
+### 1. `[P]` markers incorrect
+
+If the planner missed a dependency, `[P]` may be wrong. Solutions:
+- Before execution, confirm tasks coverage via `/curdx-flow:audit`
+- Conflict detection as a safety net (validate Files before dispatch)
+
+### 2. A wave too large
+
+10+ parallel Tasks may trigger API rate limits or context pressure. Solutions:
+- `max_parallel: 5` splits a big wave into several
+- flow-planner avoids making waves too large when generating
+
+### 3. Implicit cross-wave dependencies
+
+As in "Case 3" above. Solutions:
+- flow-planner should not mark cross-file import relationships as `[P]`
+- flow-implement does static analysis before execution (Phase 6+)
+
+---
+
+_Source: get-shit-done's wave execution. CurDX-Flow turns it from a concept into executable logic._

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@curdx/flow",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
-    "curdx-flow": "bin/curdx-flow.js"
+    "curdx-flow": "bin/curdx-flow.js",
+    "flow": "bin/curdx-flow.js"
   },
   "scripts": {
     "prepublishOnly": "node bin/curdx-flow.js --version"
@@ -12,8 +13,18 @@
   "files": [
     "bin/",
     "cli/",
+    ".claude-plugin/",
+    "agents/",
+    "gates/",
+    "commands/",
+    "hooks/",
+    "knowledge/",
+    "agent-preamble/",
     "templates/",
-    "README.md"
+    "schemas/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"