@curdx/flow 2.3.11 → 3.1.0

package/knowledge/two-stage-review.md

@@ -1,249 +0,0 @@
-# Two-Stage Review — Two-Stage Code Review
-
-> CurDX-Flow runtime contract for two-stage review.
->
-> 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 Test quality (test-quality-gate)
-
-- Do tests used as FR/AC evidence exercise real behavior, not only mocks/spies?
-- Are skipped/assertion-free tests excluded from evidence?
-- Are mock-heavy tests backed by integration/e2e coverage or a documented boundary rationale?
-- Are stateful mocks cleaned up between tests?
-
-#### 2.6 (enterprise) Adversarial review (adversarial-review-gate)
-
-- Every applicable category examined (N/A documented for the rest)?
-- Findings proportional to real issues (zero is OK with a proof-of-checking report)?
-- Each finding has evidence + recommendation?
-
-#### 2.7 (enterprise) Edge cases (edge-case-gate)
-
-- Each applicable edge-case category addressed (N/A noted for the rest)?
-- Gap list has priorities?
-
-#### 2.8 (enterprise) DevEx review (devex-gate)
-
-- Are naming, comments, and structure maintainable for the next engineer?
-- Is setup, typing, and test ergonomics acceptable without tribal knowledge?
-- Does the developer loop stay fast enough to keep future changes safe?
-
-### Stage 2 verdict
-
-- **EXCELLENT**: all enabled Gates pass, adversarial review clean or only low-severity findings
-- **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 → hand off with review-report.md + atomic commits
-```
-
-Before implementing review feedback, apply `@${CLAUDE_PLUGIN_ROOT}/knowledge/review-feedback-intake.md`:
-- Verify each finding against code/spec reality.
-- Classify as `BLOCKER`, `IMPORTANT`, `SUGGESTION`, or `PUSHBACK`.
-- Fix accepted items one at a time with targeted verification.
-- Record technical pushback in `.progress.md` instead of silently ignoring feedback.
-
----
-
-## 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:spec --phase=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:review --adversarial --edge-case --devex
-                    ↓
-                    adversarial-review.md
-                    edge-cases.md
-     ↓
-Ready for human PR/release handoff with verification + review evidence
-```
-
-Verify is "did we implement the right thing", Review is "is the implementation good", Audit is "what else could be better". CurdX-Flow currently stops at evidence-backed handoff; do not reference non-existent ship/land commands.

package/knowledge/wave-execution.md

@@ -1,403 +0,0 @@
-# Wave Execution — DAG Parallel Execution Strategy
-
-> One of Phase 2's 4 execution strategies. Identify parallel-safe task groups via `[P]` markers, dispatch multiple Agent 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.
-
-Hard limits:
-- Max 5 tasks per wave (`max_parallel` ceiling). More than 5 tasks must be split by a `[VERIFY]` checkpoint or a serial boundary.
-- Every task in a wave owns a disjoint `Files` set.
-- Shared config/barrel/registry files are serial by default: `package.json`, lockfiles, `tsconfig.*`, `index.ts`, router registries, migration manifests, generated schema registries.
-- Read-after-write is a conflict even when file paths differ: if task B imports, tests, or configures output from task A, B must run in a later wave.
-
-```
-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 Agent calls)
-  Wave 2: { 1.4 }                — serial (VERIFY breaks)
-  Wave 3: { 1.5 }                — serial (no [P])
-  Wave 4: { 1.6, 1.7 }           — parallel (2 Agent calls)
-```
-
----
-
-## 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)
-    if touches_shared_serial_surface(task_files):
-        return True
-    for other in wave:
-        if task_files & set(other.files):
-            return True
-        if has_read_after_write_dependency(task, other):
-            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)
-- More than 5 `[P]` tasks in one consecutive run → split the wave before dispatch
-
----
-
-## How Parallel Agent Dispatch Actually Works
-
-### Key: multiple Agent tool calls in a single message
-
-Claude Code's Agent 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:
-
-Agent(description="Task 1.1", prompt="...execute 1.1...")
-Agent(description="Task 1.2", prompt="...execute 1.2...")
-Agent(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:
-Agent(description="Task 1.1", ...)
-# wait for return
-# Next response:
-Agent(description="Task 1.2", ...)
-# wait for return
-# Next response:
-Agent(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 Agent tools at once.
-    results = await asyncio.gather([
-        Agent(
-            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 Agent calls 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 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 `npx @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
-
-Inspecting `.flow/specs/<name>/.progress.md` (or running `/curdx-flow:start --list`) 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 Agent calls in the current wave keep going (Claude Code's Agent tool starts independent work)
-- Next `/curdx-flow:start --resume` 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",
-    "recovery_mode": "manual | fix-task",
-    "max_fix_tasks_per_original": 2
-  }
-}
-```
-
-- `max_parallel`: maximum parallel tasks per wave (default 5, to avoid API rate limits)
-- `wave_fail_policy`: default behavior on single task failure
-- `recovery_mode`: whether a failed wave task blocks for manual retry or creates a targeted `[FIX <task_id>]` task before retry
-- `max_fix_tasks_per_original`: maximum fix tasks generated for one original task
-
----
-
-## 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:verify --strict`
-- Conflict detection as a safety net (validate Files before dispatch)
-
-### 2. A wave too large
-
-10+ parallel Agent calls 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: CurDX-Flow wave execution contract. This file defines the executable
-parallel-delivery rules used by the plugin runtime._

package/monitors/monitors.json

@@ -1,8 +0,0 @@
-[
-  {
-    "name": "flow-state",
-    "description": "Watch CurDX-Flow .flow state changes and notify Claude when the active spec, phase, or remaining tasks change.",
-    "command": "${CLAUDE_PLUGIN_ROOT}/monitors/scripts/flow-state-monitor.sh",
-    "when": "always"
-  }
-]