@curdx/flow 2.2.0 → 2.2.3

package/knowledge/execution-strategies.md

@@ -106,6 +106,8 @@ Or (default):
 - Main agent executes 1 task → ends naturally (Stop event)
 - `stop-watcher.sh` hook fires
 - Checks whether `.state.json` still has unfinished tasks
+- Cross-checks `tasks.md`; completion requires zero unchecked tasks as well as completed state
+- Allows stop when Claude Code reports `stop_hook_active=true` to avoid recursive stop-hook loops
 - If yes, it outputs `{"decision": "block", "reason": "continue task N"}`
 - Claude Code treats `decision=block` as "issue another response round", and the main agent automatically continues with the next task
 - Repeats until `TASK_FAILED` or `ALL_TASKS_COMPLETE`
@@ -119,6 +121,8 @@ main agent → task N → Stop → stop-watcher.sh
                    no tasks?     → allow stop
 ```
 
+Safety invariant: `ALL_TASKS_COMPLETE` is advisory, not authoritative. If `tasks.md` still has unchecked tasks, the hook blocks and tells the agent to continue those tasks instead of advancing to verify.
+
 ### When to use
 - ✓ Long task chains (20+)
 - ✓ Unattended execution (overnight automation)
@@ -219,6 +223,11 @@ return "linear"
 - `"auto"` — use the decision tree above (default)
 - Other concrete strategies
 
+Execution failure recovery is explicit:
+- `recovery_mode: "manual"` — default; never skip a failed task, retry from the first unchecked task after root-cause analysis.
+- `recovery_mode: "fix-task"` — insert a targeted `[FIX <task_id>]` task before retrying the original failure.
+- `max_fix_tasks_per_original` — hard ceiling for generated fix tasks per original task.
+
 ---
 
 ## Failure Handling (common to all strategies)
@@ -233,6 +242,19 @@ Step D: if ≥3 retries fail with no new hypothesis, stop and challenge the arch
 Step E: report TASK_FAILED
 ```
 
+If fix-task recovery is enabled, the coordinator turns a `TASK_FAILED` into a ledgered repair task before doing more work:
+
+```markdown
+- [ ] **<task_id>.<n>** [FIX <task_id>] Fix: <root cause>
+  - **Do**: <repair steps>
+  - **Files**: <same files as the original task or narrower>
+  - **Done when**: Original failure no longer reproduces
+  - **Verify**: <original verify command or tighter reproduction>
+  - **Commit**: `fix(<scope>): address <failure>`
+```
+
+The fix task must be written to `tasks.md` and tracked in `.state.json` `execute_state.fix_task_map` before it is executed. Executors do not invent and execute recovery work in the same turn.
+
 ### Extra protections for Stop-Hook strategy
 - 3 consecutive TASK_FAILED → stop-watcher.sh halts the loop
 - 10 consecutive Stop triggers with no progress → halt (anti-deadlock)
@@ -272,7 +294,7 @@ If you really must switch, do it manually:
 - Next `/curdx-flow:start <name>` (or `/curdx-flow:start --resume`) resumes from `task_index`
 
 ### Snapshots
-`/curdx-flow:save <label>` saves a checkpoint (Phase 5+ rollout).
+Claude Code checkpoints plus `.flow/specs/<name>/.progress.md` are the current recovery surface. Use `/curdx-flow:status` to inspect recoverability.
 
 ---
 

package/knowledge/planning-reviews.md

@@ -201,8 +201,8 @@ But for production-grade features, running through is strongly recommended.
 
 ## Difference from /curdx-flow:review
 
-- **/curdx-flow:review** (Phase 3): review **after code is finished** — Stage 1 compliance + Stage 2 quality
-- **/curdx-flow:plan-*** (Phase 5): review **before code starts** — targets design.md
+- **/curdx-flow:review**: review **after code is finished** — Stage 1 compliance + Stage 2 quality
+- **/curdx-flow:spec --review**: review **before code starts** — targets design.md
 
 The two don't overlap. Plan Review prevents "doing the wrong thing", Code Review ensures "the thing was done right".
 

package/knowledge/poc-first-workflow.md

@@ -1,6 +1,6 @@
 # POC-First Workflow — 5 Phases
 
-> Step-by-step methodology for the execution phase: get it running → clean up → add tests → pass quality gates → ship PR.
+> Step-by-step methodology for the execution phase: get it running → clean up → add tests → pass quality gates → hand off review-ready evidence.
 >
 > Agents reference this file via `@${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md`.
 
@@ -15,7 +15,7 @@ Phase 1: Make It Work    → end-to-end running; hard-coding allowed
 Phase 2: Refactoring     → clean up structure, behavior unchanged
 Phase 3: Testing (TDD)   → red-green-yellow loop to backfill tests
 Phase 4: Quality Gates   → tsc + lint + test all green
-Phase 5: PR Lifecycle    → open PR, address review, merge
+Phase 5: Evidence Handoff → verify, review, prepare PR/release evidence
 ```
 
 ---
@@ -153,10 +153,10 @@ Each item produces **0 errors, 0 warnings** (warnings are not tolerated since th
 
 ---
 
-## Phase 5: PR Lifecycle
+## Phase 5: Evidence Handoff
 
 ### Goal
-Code merged to main, feature shipped.
+Feature is verified, reviewed, and ready for a human PR/release decision.
 
 ### Steps
 
@@ -165,7 +165,7 @@ Code merged to main, feature shipped.
    - Commit message follows conventional format
    - Squash if there are too many WIP commits
 
-2. **Create PR**
+2. **Prepare PR/release evidence**
    - Clear title (< 70 chars)
    - Summary 3-5 lines covering why & what
    - Include a test plan (checklist)
@@ -180,9 +180,9 @@ Code merged to main, feature shipped.
    - Wait for CI green after every push
    - Fix red immediately — don't pile up
 
-5. **Merge**
+5. **Hand off**
    - Squash vs merge vs rebase: per project convention
-   - Deploy: if a `/curdx-flow:land` command exists, use it
+   - Use the host project's normal PR, merge, and release process
 
 ### Pitfalls
 - **PR too large** → reviewer gives up. Split anything > 500 changed lines.
@@ -198,7 +198,7 @@ Code merged to main, feature shipped.
 - Skip Refactoring / Testing / Quality Gates
 
 ### Fast mode (one-off task)
-- Only Phase 1 + Phase 5 (PR means ship)
+- Only Phase 1 + Phase 5 (handoff evidence stays lightweight)
 - Suitable for: fixing a typo, adding a log, changing a constant
 
 ### Standard mode (default)

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

@@ -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
@@ -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,6 +102,7 @@ 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
 
 ---
 
@@ -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
 
 ---
 

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,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.2.0",
+  "version": "2.2.3",
   "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
@@ -20,9 +20,11 @@
     "hooks/",
     "knowledge/",
     "agent-preamble/",
+    "output-styles/",
     "templates/",
     "schemas/",
     "skills/",
+    "settings.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -48,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

@@ -54,13 +54,6 @@
     "isolation": {
       "type": "string",
       "enum": ["worktree"]
-    },
-    "color": {
-      "type": "string",
-      "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"]
-    },
-    "initialPrompt": {
-      "type": "string"
     }
   }
 }

package/schemas/config.schema.json

@@ -40,6 +40,19 @@
           "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."
         }
       }
     },
@@ -109,6 +122,7 @@
         "karpathy-gate",
         "verification-gate",
         "tdd-gate",
+        "test-quality-gate",
         "coverage-audit-gate",
         "adversarial-review-gate",
         "edge-case-gate",

package/schemas/hooks.schema.json

@@ -63,7 +63,7 @@
     "hookHandler": {
       "type": "object",
       "required": ["type"],
-      "additionalProperties": true,
+      "additionalProperties": false,
       "properties": {
         "type": {
           "type": "string",
@@ -72,12 +72,44 @@
         "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"
+    }
+  }
+}