@curdx/flow 2.1.0 → 2.2.3

package/knowledge/review-feedback-intake.md

@@ -0,0 +1,57 @@
+# Review Feedback Intake — Verify Before Changing
+
+CurDX-Flow treats review feedback as technical input, not orders to blindly implement. The goal is to fix real issues while avoiding scope creep, regressions, and performative agreement.
+
+## Intake Pattern
+
+For each review item:
+
+1. **Read** the full finding, including severity, evidence, and suggested fix.
+2. **Restate** the technical requirement in one sentence.
+3. **Verify** against the codebase/spec:
+   - Is the finding true at the referenced path/line?
+   - Does it violate an FR, AC, AD, gate, test, or user decision?
+   - Does the suggested fix break existing behavior or platform constraints?
+4. **Classify**:
+   - `BLOCKER`: correctness, security, missing requirement, failing verify, broken CI.
+   - `IMPORTANT`: maintainability or test gap that should be fixed before ship.
+   - `SUGGESTION`: non-blocking improvement or preference.
+   - `PUSHBACK`: technically wrong, violates YAGNI, conflicts with D-NN, or lacks evidence.
+5. **Act one item at a time**:
+   - Fix blockers first.
+   - Run the smallest relevant verification after each fix.
+   - Record pushback with evidence instead of silently ignoring it.
+
+## Required Artifact
+
+When review produces any nontrivial feedback, append a section to `.flow/specs/<active>/.progress.md`:
+
+```markdown
+## Review Feedback Intake YYYY-MM-DD
+
+| Item | Source | Classification | Decision | Evidence | Follow-up |
+|---|---|---|---|---|---|
+| R-01 | review-report.md#... | BLOCKER | fix | `npm test` fails AC-2.1 | Task 4.4 |
+| R-02 | review-report.md#... | PUSHBACK | defer | D-07 says no CSV export | none |
+```
+
+## Pushback Rules
+
+Push back when the feedback:
+
+- Adds unused features or speculative architecture.
+- Conflicts with explicit user decisions (`D-NN`).
+- Breaks compatibility that the current code intentionally preserves.
+- Is unsupported by evidence and cannot be reproduced.
+- Optimizes style while leaving spec compliance unresolved.
+
+Pushback must be technical: cite code, tests, specs, or decisions. Do not use emotional language.
+
+## Fix Loop
+
+1. Intake review items.
+2. Convert accepted blockers/important issues into tasks or direct fixes.
+3. Run targeted verification per item.
+4. Re-run `/curdx-flow:verify` when behavior changed.
+5. Re-run `/curdx-flow:review` until blockers are gone.
+

package/knowledge/two-stage-review.md

@@ -111,13 +111,20 @@ Stage 2 applies all enabled Gates (from `.flow/config.json`):
 
 - All 4 sources (FR / AD / Research / Decisions) covered?
 
-#### 2.5 (enterprise) Adversarial review (adversarial-review-gate)
+#### 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.6 (enterprise) Edge cases (edge-case-gate)
+#### 2.7 (enterprise) Edge cases (edge-case-gate)
 
 - Each applicable edge-case category addressed (N/A noted for the rest)?
 - Gap list has priorities?
@@ -168,9 +175,15 @@ When the review turns up issues, the typical flow:
   ↓
 4. /curdx-flow:review re-review
   ↓
-5. Until APPROVED → /curdx-flow:ship
+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
@@ -219,15 +232,15 @@ Some reviewers list 50 minor improvements — the user can't process.
      ↓                     ↓
      ↓              review-report.md
      ↓
-(optional) /curdx-flow:verify --strict  →  adversarial review + edge cases
+(optional) /curdx-flow:review --adversarial --edge-case
                     ↓
                     adversarial-review.md
                     edge-cases.md
      ↓
-/curdx-flow:ship  →  PR (Phase 6+)
+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".
+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,6 +1,6 @@
 # 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.
+> 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`.
 
@@ -12,6 +12,12 @@
 
 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
@@ -23,10 +29,10 @@ tasks.md:
   1.7 [P] add README to user
 
 Analysis:
-  Wave 1: { 1.1, 1.2, 1.3 }     — parallel (3 Tasks)
+  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 Tasks)
+  Wave 4: { 1.6, 1.7 }           — parallel (2 Agent calls)
 ```
 
 ---
@@ -82,9 +88,13 @@ def analyze_waves(tasks):
 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
 ```
 
@@ -92,14 +102,15 @@ 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 Task Dispatch Actually Works
+## How Parallel Agent Dispatch Actually Works
 
-### Key: multiple Task tool calls in a single message
+### Key: multiple Agent tool calls in a single message
 
-Claude Code's Task tool runs in parallel **when multiple calls appear in the same 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)
@@ -107,9 +118,9 @@ Across **separate messages** → runs sequentially.
 ```
 # 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...")
+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
 ```
@@ -118,13 +129,13 @@ Task(description="Task 1.3", prompt="...execute 1.3...")
 
 ```
 # One response:
-Task(description="Task 1.1", ...)
+Agent(description="Task 1.1", ...)
 # wait for return
 # Next response:
-Task(description="Task 1.2", ...)
+Agent(description="Task 1.2", ...)
 # wait for return
 # Next response:
-Task(description="Task 1.3", ...)
+Agent(description="Task 1.3", ...)
 ```
 
 This is not parallel — it's serial subagent. The Wave strategy loses its meaning.
@@ -142,9 +153,9 @@ for wave_index, wave in enumerate(waves):
         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.
+    # This is the main agent's response body. Call N Agent tools at once.
     results = await asyncio.gather([
-        Task(
+        Agent(
             description=f"execute {task.id}",
             prompt=f"""
               You are the flow-executor agent.
@@ -193,7 +204,7 @@ for wave_index, wave in enumerate(waves):
             return
 
     # === Step 6: inter-wave synchronization point ===
-    # All Tasks complete = wave ends
+    # All Agent calls complete = wave ends
     # Before next wave starts, confirm git state is consistent
 
 # All waves done
@@ -320,7 +331,7 @@ Progress: Wave 2/5 (60%)
 
 ### Ctrl+C interruption
 
-- Running Task calls in the current wave keep going (Claude Code's Task is an independent process)
+- 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
 
@@ -335,13 +346,17 @@ Progress: Wave 2/5 (60%)
   "execution": {
     "strategy": "wave",
     "max_parallel": 5,
-    "wave_fail_policy": "continue-on-single | stop-on-any"
+    "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
 
 ---
 
@@ -372,7 +387,7 @@ If the planner missed a dependency, `[P]` may be wrong. Solutions:
 
 ### 2. A wave too large
 
-10+ parallel Tasks may trigger API rate limits or context pressure. Solutions:
+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
 

package/output-styles/curdx-evidence-first.md

@@ -0,0 +1,34 @@
+---
+name: CurdX Evidence-First
+description: Concise, engineering-focused replies with explicit validation status, assumptions, and next actions.
+keep-coding-instructions: true
+---
+
+# CurdX Evidence-First
+
+You are still Claude Code. Keep the default coding workflow, safety rules,
+tool usage behavior, and verification discipline.
+
+## Response priorities
+
+1. Lead with the concrete outcome or current state.
+2. State validation status explicitly:
+   - `Validated` when you actually ran checks and they passed
+   - `Unvalidated` when you did not run checks yet
+   - `Blocked` when validation could not be completed
+3. Separate observed facts from assumptions or proposals.
+4. Keep answers concise and operational; avoid filler and cheerleading.
+5. When work is incomplete, state the next highest-value action plainly.
+
+## Completion discipline
+
+- Never imply something is done without evidence.
+- If tests, builds, browser checks, or docs validation were not run, say so directly.
+- If you are making a best-effort inference, label it as an inference.
+- When relevant, point to the exact file paths or commands that support the claim.
+
+## Formatting
+
+- Use short section headers only when they improve scanability.
+- Prefer short bullet lists over long prose.
+- Match the user's language.

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@curdx/flow",
-  "version": "2.1.0",
+  "version": "2.2.3",
   "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
     "curdx-flow": "bin/curdx-flow.js"
   },
   "scripts": {
+    "validate:contracts": "node scripts/validate-plugin-contracts.mjs",
     "test": "node --test test/*.test.js",
-    "prepublishOnly": "node --test test/*.test.js && node bin/curdx-flow.js --version"
+    "prepublishOnly": "npm run validate:contracts && node --test test/*.test.js && node bin/curdx-flow.js --version"
   },
   "files": [
     "bin/",
@@ -19,9 +20,11 @@
     "hooks/",
     "knowledge/",
     "agent-preamble/",
+    "output-styles/",
     "templates/",
     "schemas/",
     "skills/",
+    "settings.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -47,5 +50,9 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "ajv": "^8.18.0",
+    "yaml": "^2.8.3"
   }
 }

package/schemas/agent-frontmatter.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/agent-frontmatter.schema.json",
+  "title": "CurdX-Flow Agent Frontmatter",
+  "description": "Supported YAML frontmatter fields for agents/*.md plugin subagent definitions.",
+  "type": "object",
+  "required": ["name", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "disallowedTools": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "model": {
+      "type": "string"
+    },
+    "effort": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "xhigh", "max"]
+    },
+    "maxTurns": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "skills": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "memory": {
+      "type": "string",
+      "enum": ["user", "project", "local"]
+    },
+    "background": {
+      "type": "boolean"
+    },
+    "isolation": {
+      "type": "string",
+      "enum": ["worktree"]
+    }
+  }
+}

package/schemas/config.schema.json

@@ -35,6 +35,24 @@
           "minimum": 1,
           "default": 8,
           "description": "Task count above which subagent strategy is preferred"
+        },
+        "wave_fail_policy": {
+          "type": "string",
+          "enum": ["continue-on-single", "stop-on-any"],
+          "default": "continue-on-single"
+        },
+        "recovery_mode": {
+          "type": "string",
+          "enum": ["manual", "fix-task"],
+          "default": "manual",
+          "description": "How /curdx-flow:implement handles TASK_FAILED during execution. manual blocks for retry; fix-task inserts targeted [FIX <task>] tasks before retrying."
+        },
+        "max_fix_tasks_per_original": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5,
+          "default": 2,
+          "description": "Maximum generated [FIX <task>] tasks allowed for a single original task when recovery_mode is fix-task."
         }
       }
     },
@@ -44,16 +62,16 @@
       "properties": {
         "always_on": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": { "$ref": "#/definitions/gateName" },
           "default": ["karpathy-gate", "verification-gate"]
         },
         "standard_mode": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": { "$ref": "#/definitions/gateName" }
         },
         "enterprise_mode": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": { "$ref": "#/definitions/gateName" }
         }
       }
     },
@@ -96,5 +114,21 @@
       "type": "string",
       "format": "date"
     }
+  },
+  "definitions": {
+    "gateName": {
+      "type": "string",
+      "enum": [
+        "karpathy-gate",
+        "verification-gate",
+        "tdd-gate",
+        "test-quality-gate",
+        "coverage-audit-gate",
+        "adversarial-review-gate",
+        "edge-case-gate",
+        "security-gate",
+        "devex-gate"
+      ]
+    }
   }
 }

package/schemas/gate-frontmatter.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/gate-frontmatter.schema.json",
+  "title": "CurdX-Flow Gate Frontmatter",
+  "description": "Supported YAML frontmatter fields for gates/*.md quality gate definitions.",
+  "type": "object",
+  "required": ["gate", "category", "severity", "depends_on"],
+  "additionalProperties": false,
+  "properties": {
+    "gate": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+    },
+    "category": {
+      "type": "string",
+      "enum": ["always-on", "standard-mode", "enterprise-mode"]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["blocking", "warning"]
+    },
+    "depends_on": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+      }
+    }
+  }
+}

package/schemas/hooks.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/hooks.schema.json",
+  "title": "CurdX-Flow Hook Configuration",
+  "description": "Supported event names and handler shape for hooks/hooks.json.",
+  "type": "object",
+  "required": ["hooks"],
+  "additionalProperties": false,
+  "properties": {
+    "hooks": {
+      "type": "object",
+      "propertyNames": {
+        "enum": [
+          "SessionStart",
+          "InstructionsLoaded",
+          "UserPromptSubmit",
+          "UserPromptExpansion",
+          "PreToolUse",
+          "PermissionRequest",
+          "PostToolUse",
+          "PostToolUseFailure",
+          "PostToolBatch",
+          "PermissionDenied",
+          "Notification",
+          "SubagentStart",
+          "SubagentStop",
+          "TaskCreated",
+          "TaskCompleted",
+          "Stop",
+          "StopFailure",
+          "TeammateIdle",
+          "ConfigChange",
+          "CwdChanged",
+          "FileChanged",
+          "WorktreeCreate",
+          "WorktreeRemove",
+          "PreCompact",
+          "PostCompact",
+          "Elicitation",
+          "ElicitationResult",
+          "SessionEnd"
+        ]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/definitions/matcherGroup" }
+      }
+    }
+  },
+  "definitions": {
+    "matcherGroup": {
+      "type": "object",
+      "required": ["hooks"],
+      "additionalProperties": false,
+      "properties": {
+        "matcher": { "type": "string" },
+        "hooks": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookHandler" }
+        }
+      }
+    },
+    "hookHandler": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["command", "http", "mcp_tool", "prompt", "agent"]
+        },
+        "if": { "type": "string" },
+        "timeout": { "type": "integer", "minimum": 1 },
+        "statusMessage": { "type": "string" },
+        "async": { "type": "boolean" },
+        "asyncRewake": { "type": "boolean" },
+        "once": { "type": "boolean" },
+        "command": { "type": "string" },
+        "shell": {
+          "type": "string",
+          "enum": ["bash", "powershell"]
+        },
+        "url": { "type": "string" },
+        "headers": { "type": "object" },
+        "allowedEnvVars": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "server": { "type": "string" },
+        "tool": { "type": "string" },
+        "input": { "type": "object" },
+        "prompt": { "type": "string" },
+        "model": { "type": "string" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "command" } } },
+          "then": { "required": ["command"] }
+        },
+        {
+          "if": { "properties": { "type": { "const": "http" } } },
+          "then": { "required": ["url"] }
+        },
+        {
+          "if": { "properties": { "type": { "const": "mcp_tool" } } },
+          "then": { "required": ["server", "tool"] }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["prompt", "agent"] } } },
+          "then": { "required": ["prompt"] }
+        }
+      ]
+    }
+  }
+}

package/schemas/output-style-frontmatter.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/output-style-frontmatter.schema.json",
+  "title": "CurdX-Flow Output Style Frontmatter",
+  "description": "Supported YAML frontmatter fields for output-styles/*.md.",
+  "type": "object",
+  "required": ["name", "description", "keep-coding-instructions"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "keep-coding-instructions": {
+      "type": "boolean"
+    }
+  }
+}