@curdx/flow 2.1.0 → 2.2.3

package/schemas/spec-state.schema.json

@@ -17,7 +17,7 @@
     },
     "goal": {
       "type": "string",
-      "description": "One-sentence goal from /flow-start"
+      "description": "One-sentence goal from /curdx-flow:start"
     },
     "mode": {
       "type": "string",
@@ -29,6 +29,11 @@
       "enum": ["auto", "subagent", "stop-hook", "wave", "linear"],
       "default": "auto"
     },
+    "quickMode": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, execution hooks block AskUserQuestion and agents must record assumptions instead of asking."
+    },
     "phase": {
       "type": "string",
       "enum": [
@@ -39,7 +44,6 @@
         "execute",
         "verify",
         "review",
-        "ship",
         "completed"
       ]
     },
@@ -52,8 +56,7 @@
         "tasks": { "$ref": "#/definitions/phaseStatus" },
         "execute": { "$ref": "#/definitions/phaseStatus" },
         "verify": { "$ref": "#/definitions/phaseStatus" },
-        "review": { "$ref": "#/definitions/phaseStatus" },
-        "ship": { "$ref": "#/definitions/phaseStatus" }
+        "review": { "$ref": "#/definitions/phaseStatus" }
       }
     },
     "execute_state": {
@@ -68,7 +71,34 @@
         "total_tasks": { "type": "integer", "minimum": 0 },
         "task_iteration": { "type": "integer", "minimum": 1 },
         "global_iteration": { "type": "integer", "minimum": 1 },
-        "failed_attempts": { "type": "integer", "minimum": 0 }
+        "failed_attempts": { "type": "integer", "minimum": 0 },
+        "recovery_mode": {
+          "type": "string",
+          "enum": ["manual", "fix-task"],
+          "default": "manual"
+        },
+        "max_fix_tasks_per_original": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5,
+          "default": 2
+        },
+        "fix_task_map": {
+          "type": "object",
+          "description": "Per-original-task recovery attempts created by fix-task mode.",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["attempts", "fix_task_ids"],
+            "properties": {
+              "attempts": { "type": "integer", "minimum": 0 },
+              "fix_task_ids": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "last_error": { "type": "string" }
+            }
+          }
+        }
       }
     },
     "decisions": {

package/settings.json

@@ -0,0 +1,6 @@
+{
+  "subagentStatusLine": {
+    "type": "command",
+    "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh"
+  }
+}

package/skills/brownfield-index/SKILL.md

@@ -1,7 +1,31 @@
 ---
 name: brownfield-index
-description: Invoke when the user is new to an unfamiliar / legacy / brownfield codebase and wants a structural understanding — module map, component inventory, API surface, data flow. Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project".
-allowed-tools: [Read, Grep, Glob, Bash]
+description: Use when the user needs structural understanding of an unfamiliar, inherited, legacy, or brownfield codebase.
+when_to_use: Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project".
+argument-hint: "[path]"
+context: fork
+agent: flow-brownfield-analyst
+paths:
+  - "package.json"
+  - "pnpm-workspace.yaml"
+  - "turbo.json"
+  - "nx.json"
+  - "pyproject.toml"
+  - "requirements*.txt"
+  - "go.mod"
+  - "Cargo.toml"
+  - "Gemfile"
+  - "composer.json"
+  - "pom.xml"
+  - "build.gradle*"
+  - "mix.exs"
+  - "deno.json*"
+  - "src/**"
+  - "lib/**"
+  - "app/**"
+  - "apps/**"
+  - "packages/**"
+  - "services/**"
 ---
 
 # Brownfield Index
@@ -15,41 +39,14 @@ You are invoked when the user needs a structural map of an existing codebase the
 
 ## Workflow
 
-### Step 1: Detect project type
+This skill runs in a forked context through `flow-brownfield-analyst`, which will:
 
-Read `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` / `pom.xml` to classify the ecosystem and build tool. This determines which directory conventions to apply.
+1. Detect the actual stack from the repo's manifests.
+2. Scan structure, entry points, module boundaries, and developer-loop commands.
+3. Map API / CLI surfaces when they exist.
+4. Write `.flow/codebase-index.md` with concrete next actions.
 
-### Step 2: Scan directory structure
-
-Produce a top-level inventory:
-- **Entry points** (main / index / bin scripts)
-- **Module directories** (src/, lib/, internal/, pkg/ …)
-- **Test directories**
-- **Config files**
-- **Tooling** (CI, lint, format configs)
-
-### Step 3: Component inventory
-
-For each module directory, list:
-- Files and their apparent role (inferred from names + top-of-file comments)
-- Public exports / exported symbols
-- Third-party dependencies imported
-
-### Step 4: API surface
-
-If HTTP / RPC endpoints exist, index them: route → handler → middleware. For CLI tools, index commands → handlers.
-
-### Step 5: Write index document
-
-Output `.flow/codebase-index.md` containing:
-- **Overview** (project purpose, build tool, runtime)
-- **Directory tree** (with per-directory one-liner descriptions)
-- **Entry points** (where execution starts)
-- **Key abstractions** (core types, interfaces, classes that everything else hangs off)
-- **External dependencies** (grouped: prod runtime / dev tooling / transitive)
-- **Known gaps / red flags** (missing tests, TODOs, suspicious patterns)
-
-### Step 6: Hand off
+### Hand off
 
 Point the user at the next useful action:
 - "Looking to add a feature here? Run `/curdx-flow:start <name>` to begin a spec."
@@ -57,6 +54,6 @@ Point the user at the next useful action:
 
 ## Notes
 
-This skill uses Read + Grep + Glob + Bash with no specialized agent — general tools are enough for structural discovery. The index is meant to be quick (5–10 minutes), not exhaustive.
+The index is meant to be quick and decision-useful, not exhaustive.
 
 For deep research into a specific library or framework, use `context7` MCP directly.

package/skills/browser-qa/SKILL.md

@@ -1,7 +1,16 @@
 ---
 name: browser-qa
-description: Invoke when the user wants to test a UI/frontend in a real browser — accessibility, performance, console errors, network traffic, visual regression. Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot".
-allowed-tools: [Read, Write, Bash, Grep, Glob, WebFetch]
+description: Use when the user needs real-browser QA for a UI or frontend flow.
+when_to_use: Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot".
+argument-hint: "\"<url or user flow>\""
+context: fork
+agent: flow-qa-engineer
+paths:
+  - "**/*.{html,css,scss,sass,less,js,jsx,ts,tsx,vue,svelte,astro}"
+  - "app/**"
+  - "pages/**"
+  - "components/**"
+  - "public/**"
 ---
 
 # Browser QA
@@ -10,7 +19,7 @@ You are invoked when the user wants real-browser QA of a UI flow.
 
 ## Preconditions
 
-1. `chrome-devtools` MCP is available (`mcp__chrome-devtools__*`). If missing, fall back to a manual checklist.
+1. `chrome-devtools` MCP is available (`mcp__chrome_devtools__*`). If missing, fall back to a manual checklist.
 2. A URL (dev server or deployed) is available. Prompt for it if not provided.
 
 ## Workflow
@@ -22,11 +31,11 @@ Confirm with the user:
 - **Flow to test** (e.g., "sign up → dashboard → logout")
 - **What success looks like** (accessibility / performance / zero console errors / visual match)
 
-### Step 2: Dispatch `flow-qa-engineer`
+### Step 2: Run via `flow-qa-engineer`
 
-Delegate to the `flow-qa-engineer` agent. It will:
-1. Open the target URL via `mcp__chrome-devtools__new_page`
-2. Drive the flow with `mcp__chrome-devtools__click` / `fill` / `navigate`
+This skill executes in a forked context through `flow-qa-engineer`. The agent will:
+1. Open the target URL via `mcp__chrome_devtools__new_page`
+2. Drive the flow with `mcp__chrome_devtools__click` / `fill` / `navigate_page`
 3. Capture `list_console_messages`, `list_network_requests`, `take_screenshot`, optionally `lighthouse_audit`
 4. Compare against expected behavior
 

package/skills/cancel/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: cancel
+description: Stop the active CurDX-Flow execution loop safely. Optional --delete-spec --yes removes the spec directory.
+when_to_use: Use when the user wants to stop the current execution loop, abort a stuck run, or delete the active spec intentionally.
+argument-hint: "[spec-name] [--delete-spec --yes]"
+disable-model-invocation: true
+allowed-tools: [Read, Bash]
+---
+
+# CurdX-Flow Cancel
+
+Safely stop an active execution loop. Default behavior is non-destructive: preserve spec files, tasks, progress, and artifacts.
+
+## Target Resolution
+
+1. If `$ARGUMENTS` includes a spec name, use `.flow/specs/<name>`.
+2. Otherwise read `.flow/.active-spec`.
+3. If no target exists, print `No active spec to cancel` and stop.
+
+## Default: Cancel Execution Loop Only
+
+Default mode removes stop-hook/subagent execution state while preserving all human-readable artifacts:
+
+1. Read `.flow/specs/<target>/.state.json`.
+2. Use `Edit` or `Write` to set `phase` to `tasks`.
+3. Set `phase_status.execute` to `cancelled`.
+4. Remove `execute_state` and `strategy`.
+5. If the state file is missing, print `No execution state for <target>. Nothing to cancel.` and stop.
+
+Do not rewrite `.state.json` with a Bash heredoc or ad-hoc Python writer; use checkpoint-tracked `Edit`/`Write` operations.
+
+Append to `.progress.md`:
+
+```markdown
+## Execution Cancelled YYYY-MM-DD
+- Cancelled by: /curdx-flow:cancel
+- Preserved: research.md, requirements.md, design.md, tasks.md, progress, reports
+- Resume: /curdx-flow:implement --strategy=subagent or /curdx-flow:spec --phase=tasks --regenerate
+```
+
+## Destructive Mode
+
+Only delete the spec directory when both flags are present:
+
+```bash
+/curdx-flow:cancel <spec-name> --delete-spec --yes
+```
+
+If `--delete-spec` is present without `--yes`, do not delete. Print the exact command required.
+
+Destructive mode:
+
+1. Print target path and files that will be removed.
+2. Delete `.flow/specs/<target>`.
+3. If it was active, remove `.flow/.active-spec`.
+4. Do not delete `.flow/PROJECT.md`, `.flow/CONTEXT.md`, `.flow/STATE.md`, or other specs.
+
+## Output
+
+Default mode:
+
+```markdown
+✓ Cancelled execution loop: <spec-name>
+  State: execute → cancelled, phase → tasks
+  Preserved: spec artifacts and progress
+  Resume: /curdx-flow:implement --strategy=subagent
+```
+
+Destructive mode:
+
+```markdown
+✓ Deleted spec: <spec-name>
+  Removed: .flow/specs/<spec-name>
+  Active spec cleared: yes|no
+```
+
+## Safety Rules
+
+- Never delete a spec unless `--delete-spec --yes` is present.
+- Never delete project-level `.flow` files.
+- If state JSON is corrupt, rename it to `.state.json.corrupt.<timestamp>` instead of deleting it.
+- Prefer `/curdx-flow:status` after cancel to confirm recovery state.

package/skills/debug/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: debug
-description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); three failures trigger architectural questioning. Routes to flow-debugger.
+description: Debug bugs, test failures, and flaky behavior with a 4-phase root-cause workflow. Routes to flow-debugger.
+when_to_use: Use when the user reports a bug, failing test, regression, stack trace, flaky behavior, or wants root-cause analysis instead of trial-and-error edits.
 argument-hint: "\"<bug description>\""
+disable-model-invocation: true
 context: fork
 agent: flow-debugger
 ---
@@ -27,6 +29,7 @@ If `$ARGUMENTS` is empty, print `Usage: /curdx-flow:debug "<bug description>"` a
 
 - Read the error carefully (stack trace + message + location).
 - Build a minimal reproduction.
+- Append `## Reality Check (BEFORE)` to `.flow/specs/<active>/.progress.md` with the exact reproduction command, observed failure output, and timestamp before changing code.
 - Check recent changes that could have introduced the bug.
 - Trace the data flow from cause to symptom.
 - **Exit condition**: state the root cause in **one sentence**.
@@ -53,7 +56,8 @@ If `$ARGUMENTS` is empty, print `Usage: /curdx-flow:debug "<bug description>"` a
 2. Fix the root cause (not the symptom). Confirm the failing test now
    passes. Commit `fix(<scope>): green - ...`.
 3. Run the full regression suite; no regressions allowed.
-4. If Phase 2 classified as systemic, sweep for sibling occurrences and
+4. Re-run the original reproduction command and append `## Reality Check (AFTER)` to `.progress.md`; write `Verified: Issue resolved` only when BEFORE failed and AFTER passes or no longer shows the original failure.
+5. If Phase 2 classified as systemic, sweep for sibling occurrences and
    fix them in the same stage. Optional third commit
    `fix(<scope>): sweep - N similar cases`.
 
@@ -81,6 +85,7 @@ Recommended next step: <user action — review architecture, ship a
 - Prayer-driven programming (retry without a new hypothesis each round)
 - "Maybe it's ..." as a Phase 1 conclusion
 - A fix commit without a corresponding failing-test commit
+- A fix claim without BEFORE/AFTER reality verification in `.progress.md`
 - Masking the root cause with null checks / try-catch
 - Fixing multiple unrelated things in one commit (one task = one commit)
 

package/skills/epic/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: epic
-description: Invoke when user wants to break a large feature into multiple smaller specs with a dependency graph. Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "won't fit in one sprint", "needs splitting".
-allowed-tools: [Read, Write, Grep, Glob, Bash]
+description: Use when the user needs to decompose a large feature into smaller vertical-slice specs with dependencies.
+when_to_use: Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "won't fit in one sprint", "needs splitting".
+argument-hint: "\"<epic goal>\""
+context: fork
+agent: flow-triage-analyst
 ---
 
 # Epic Decomposition
@@ -22,9 +25,9 @@ Ask the user (or infer from context) for:
 - **One-sentence goal** of the whole epic
 - **Hard boundary**: what is explicitly out of scope for this epic
 
-### Step 2: Dispatch `flow-triage-analyst`
+### Step 2: Run via `flow-triage-analyst`
 
-Delegate to the `flow-triage-analyst` agent with the epic name + goal + boundary. The agent returns:
+This skill executes in a forked context through `flow-triage-analyst`. The agent returns:
 - A vertical-slice decomposition (not horizontal by layer)
 - Dependency graph between slices
 - Shared interfaces that must be frozen before parallel work begins

package/skills/fast/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: fast
 description: Ultra-fast execution — skip all spec phases and implement directly per the description. Suited for one-shot small tasks.
+when_to_use: Use when the task is small, surgical, low-ambiguity, and not worth a full spec workflow.
 argument-hint: "\"<task description>\""
-allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
+disable-model-invocation: true
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 
 # Flow Fast — Ultra-Fast Execution

package/skills/help/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: help
 description: Show CurdX-Flow command list, workflow overview, or troubleshooting guide. With a command name, show that command's detail.
+when_to_use: Use when the user asks how CurdX-Flow works, which command to run, what a workflow does, or how to troubleshoot common issues.
 argument-hint: "[<command-name> | workflow | troubleshoot]"
+disable-model-invocation: true
 allowed-tools: [Read, Bash]
 ---
 
@@ -9,17 +11,19 @@ allowed-tools: [Read, Bash]
 
 ## No argument — quick overview
 
-Show the 9 core slash commands + 5 auto-invoked skills. Keep the table compact, use tabs for alignment.
+Show the 11 core slash commands + 5 auto-invoked skills. Keep the table compact, use tabs for alignment.
 
 ```
 🚀 CurdX-Flow v2 — Claude Code Discipline Layer
 
-  9 slash commands (explicit control)
+  11 slash commands (explicit control)
   ────────────────────────────────────
   /curdx-flow:init                  Initialize .flow/ in the current project
   /curdx-flow:start                 Create / resume / switch a feature spec
+  /curdx-flow:status                Show active spec, phase, task progress, recovery hints
   /curdx-flow:spec                  Write or refresh the spec (--phase, --review, --regenerate)
   /curdx-flow:implement             Execute the tasks (auto-routed strategy)
+  /curdx-flow:cancel                Cancel execution loop safely; optional spec deletion
   /curdx-flow:verify                Goal-backward verification — the differentiator
   /curdx-flow:review                Two-stage code review (+ --adversarial, --edge-case)
   /curdx-flow:fast                  Skip the spec — one-shot small task
@@ -48,7 +52,7 @@ Show the 9 core slash commands + 5 auto-invoked skills. Keep the table compact,
 
 ## `<command-name>` — command detail
 
-When the argument matches a slash name — one of the 9 primary workflows or one of the 5 auto-invoked skills — read the corresponding body and present it cleanly. The lookup tries the `skills/` layout first and falls back to the legacy `commands/` layout, which keeps help correct throughout the Phase 3 migration window:
+When the argument matches a slash name — one of the 11 slash commands or one of the 5 auto-invoked skills — read the corresponding body and present it cleanly. The lookup tries the `skills/` layout first and falls back to the legacy `commands/` layout for older installed bundles:
 
 ```bash
 CMD="$ARGUMENTS"
@@ -59,13 +63,13 @@ elif [ -f "${CLAUDE_PLUGIN_ROOT}/commands/${CMD}.md" ]; then
   cat "${CLAUDE_PLUGIN_ROOT}/commands/${CMD}.md"
 else
   echo "Unknown: ${CMD}"
-  echo "Workflows: init start spec implement verify review fast debug help"
+  echo "Workflows: init start status spec implement cancel verify review fast debug help"
   echo "Skills:    epic browser-qa ui-sketch security-audit brownfield-index"
   exit 1
 fi
 ```
 
-If the argument isn't a known slash name, the block above prints the 14 candidates.
+If the argument isn't a known slash name, the block above prints the 16 candidates.
 
 ## `workflow` — standard workflow
 
@@ -80,6 +84,7 @@ If the argument isn't a known slash name, the block above prints the 14 candidat
 
 3. Per feature — the main loop
    ├─ /curdx-flow:start my-feature "one-line goal"
+   ├─ /curdx-flow:status                        ← optional: see active spec + recovery hints
    ├─ /curdx-flow:spec                          ← research → requirements → design → tasks
    ├─ (optional) /curdx-flow:spec --review      ← add multi-dim planning review
    ├─ /curdx-flow:implement                     ← execute tasks
@@ -120,13 +125,15 @@ A: v1.1.5+ defaults to offline install (bundled plugin body).
    Force-online:   npx @curdx/flow install --online
 
 Q: claude-mem MCP keeps failing?
-A: It needs bun. Run: npx @curdx/flow doctor — it auto-symlinks bun if installed.
+A: It needs bun. Run: npx @curdx/flow doctor
+   If doctor reports bun/uv is installed but not on PATH, run:
+   npx @curdx/flow doctor --fix
 
 Q: /curdx-flow:init says .flow/ already exists?
 A: Use --force, or run /curdx-flow:start directly to begin a new spec in the existing .flow/.
 
 Q: Skills don't auto-invoke reliably?
-A: Invoke explicitly — every skill also has a /skill-name slash. E.g., /curdx-flow:security-audit.
+A: Invoke explicitly — plugin skills are namespaced. E.g., /curdx-flow:security-audit.
 
 Q: I want the old v1 commands (research, plan-ceo, party…).
 A: They're removed in v2. See MIGRATION.md for mappings, or stay on 1.x:
@@ -139,6 +146,10 @@ A: Your spec mode decides gate strictness. Lower via:
 Q: Where are decisions logged?
 A: .flow/STATE.md (D-NN entries). Edit directly — no slash command needed.
 
+Q: Stop-hook or execution loop seems stuck?
+A: Run /curdx-flow:status. If state/tasks disagree, run /curdx-flow:cancel, then resume with:
+   /curdx-flow:implement --strategy=subagent
+
 Q: File a bug / request feature
 A: https://github.com/curdx/curdx-flow/issues
 ```

package/skills/implement/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: implement
 description: Execute spec tasks — the Strategy Router picks linear/subagent/stop-hook/wave based on task characteristics. Atomic commit per task.
+when_to_use: Use when the active spec already has tasks and the user wants execution, optionally with a chosen strategy or a single task id.
 argument-hint: "[spec-name] [--strategy=auto|linear|subagent|stop-hook|wave] [--task=<id>] [--quick]"
-allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
+disable-model-invocation: true
+allowed-tools: [Read, Write, Edit, Bash, Agent, Grep, Glob]
 ---
 
 # Flow Implement — Execute Spec
@@ -44,9 +46,9 @@ DIR=".flow/specs/$SPEC_NAME"
 ## Step 2: Parse Task Characteristics from tasks.md
 
 ```bash
-TOTAL=$(grep -c "^- \[ \] \*\*" "$DIR/tasks.md")
-DONE=$(grep -c "^- \[x\] \*\*" "$DIR/tasks.md")
-REMAINING=$((TOTAL))
+TOTAL=$(grep -Ec "^- \[[ xX]\] \*\*" "$DIR/tasks.md")
+DONE=$(grep -Ec "^- \[[xX]\] \*\*" "$DIR/tasks.md")
+REMAINING=$((TOTAL - DONE))
 PARALLEL=$(grep -c "^- \[ \] \*\*.*\[P\]" "$DIR/tasks.md")
 SEQUENTIAL=$(grep -c "^- \[ \] \*\*.*\[SEQUENTIAL\]" "$DIR/tasks.md")
 
@@ -77,7 +79,7 @@ echo "✓ Selected strategy: $STRATEGY"
 
 **Decision tree explanation**:
 - Few tasks / strong dependencies → `linear` (main agent executes sequentially)
-- Many parallel opportunities → `wave` (parallel Task dispatch within a wave)
+- Many parallel opportunities → `wave` (parallel Agent dispatch within a wave)
 - Long chain + quick mode → `stop-hook` (auto-loop, requires hook support)
 - Medium scale → `subagent` (isolated context per task)
 
@@ -87,6 +89,13 @@ echo "✓ Selected strategy: $STRATEGY"
 import json
 p = f'.flow/specs/{SPEC_NAME}/.state.json'
 s = json.load(open(p))
+try:
+    cfg = json.load(open('.flow/config.json'))
+except Exception:
+    cfg = {}
+execution_cfg = cfg.get('execution', {}) if isinstance(cfg, dict) else {}
+recovery_mode = execution_cfg.get('recovery_mode', 'manual')
+max_fix_tasks = execution_cfg.get('max_fix_tasks_per_original', 2)
 s['phase'] = 'execute'
 s['strategy'] = STRATEGY
 s.setdefault('phase_status', {})['execute'] = 'in_progress'
@@ -95,6 +104,9 @@ s['execute_state'].setdefault('task_index', DONE)
 s['execute_state']['total_tasks'] = TOTAL
 s['execute_state'].setdefault('failed_attempts', 0)
 s['execute_state'].setdefault('global_iteration', 1)
+s['execute_state'].setdefault('recovery_mode', recovery_mode)
+s['execute_state'].setdefault('max_fix_tasks_per_original', max_fix_tasks)
+s['execute_state'].setdefault('fix_task_map', {})
 if QUICK:
     s['quickMode'] = True
 json.dump(s, open(p, 'w'), indent=2, ensure_ascii=False)
@@ -127,7 +139,7 @@ If there are 5 failures, stop + TASK_FAILED.
 For each remaining task, dispatch flow-executor:
 
 ```
-Task:
+Agent:
   subagent_type: general-purpose
   description: "Execute $SPEC_NAME task $TASK_ID"
   prompt: |
@@ -162,11 +174,11 @@ After the agent completes, read the output marker:
 See `skills/implement/references/wave-execution.md` for the full walkthrough.
 Knowledge-layer canonical algorithm: `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`.
 
-**Core**: consecutive `[P]` tasks form a wave; dispatch multiple Tasks in parallel within a single response; serial across waves. The execution loop is:
+**Core**: consecutive `[P]` tasks form a wave; dispatch multiple Agent calls in parallel within a single response; serial across waves. The execution loop is:
 
 1. **DAG analysis** — group remaining `[ ]` tasks by `[P]` / `[SEQUENTIAL]` / `[VERIFY]` tags; conflicting `Files` sets split into a new wave.
 2. **Pre-conflict detection** — within each wave, assert per-task `Files` are disjoint; auto-split if not.
-3. **Dispatch** — list multiple `Task(...)` tool calls in a single main-agent response (splitting across responses = serial degradation; nested `Task` dispatches forbidden). Each Task prompt follows the subagent strategy's uniform format (see `references/wave-execution.md` Step 3).
+3. **Dispatch** — list multiple `Agent(...)` tool calls in a single main-agent response (splitting across responses = serial degradation; nested `Agent` dispatches forbidden). Each Agent prompt follows the subagent strategy's uniform format (see `references/wave-execution.md` Step 3).
 4. **Aggregate** — parse each result for `TASK_COMPLETE` / `TASK_FAILED`; run post-hoc conflict detection via git diff to confirm executors only touched declared files.
 5. **Failure handling** — 0 failed → next wave; 1 failed → `config.wave_fail_policy` (`continue-on-single` or `stop-on-any`); ≥2 failed → likely environment issue, stop immediately; cumulative `failed_attempts >= 3` → stop, user intervention.
 6. **Progress feedback** — print a wave summary after each wave (see `references/wave-execution.md` Step 6).
@@ -183,6 +195,8 @@ Configuration under `.flow/config.json.execution`: `strategy: "wave"`, `max_para
 5. Repeat until ALL_TASKS_COMPLETE or 3 failures
 ```
 
+Stop-hook completion is double-checked: `.state.json` must say execute is complete AND `tasks.md` must have zero unchecked tasks. If either disagrees, the hook blocks and resumes the first unchecked task. During a stop-hook continuation, `stop_hook_active=true` is only a context signal; the hook still evaluates transcript signals, `.state.json`, and `tasks.md` parity before deciding whether to continue or stop.
+
 Prerequisites:
 - `--quick` must be set (otherwise AskUserQuestion will block the loop)
 - `.flow/config.json` or `.state.json` must have strategy=stop-hook
@@ -217,9 +231,27 @@ if all tasks done:
 ## Error Recovery
 
 - Verify field in tasks.md is "manual" → stop, suggest re-running `/curdx-flow:spec --phase=tasks --regenerate` to fix
+- `TASK_FAILED` default (`recovery_mode: manual`) → do not skip the task; root-cause, retry the first unchecked task, stop at 3 failures
+- `TASK_FAILED` with `recovery_mode: fix-task` → insert one targeted `[FIX <task_id>]` task immediately after the failed task, update `execute_state.fix_task_map`, execute that fix task, then retry the original task; never exceed `max_fix_tasks_per_original`
 - 3 consecutive TASK_FAILED → stop, prompt for user intervention
 - git operation failure → stop immediately, do not continue (avoid state corruption)
 - Test framework not found (npm test not found) → stop, suggest running npx @curdx/flow doctor
+- State says complete but tasks.md still has unchecked tasks → trust tasks.md, continue remaining unchecked tasks only
+
+### Fix-Task Recovery Format
+
+When enabled, generated recovery tasks must be narrowly scoped and traceable:
+
+```markdown
+- [ ] **<task_id>.<n>** [FIX <task_id>] Fix: <short root cause>
+  - **Do**: <specific repair steps>
+  - **Files**: <same declared files or narrower>
+  - **Done when**: Original failure no longer reproduces
+  - **Verify**: <original verify command or tighter reproduction>
+  - **Commit**: `fix(<scope>): address <failure>`
+```
+
+Do not execute a newly generated fix task in the same breath that creates it unless the task is already written to `tasks.md` and `fix_task_map` has been updated. The ledger stays ahead of execution.
 
 ## Output to User
 
@@ -232,9 +264,9 @@ Commits:        M atomic commits
 Verify passed:  K / K
 
 Next steps:
-  - /curdx-flow:verify  — goal-driven reverse verification (after Phase 3 ships)
-  - If verify is not needed, go directly to /curdx-flow:ship (after Phase 6 ships)
+  - /curdx-flow:verify  — goal-driven reverse verification
+  - /curdx-flow:review   — two-stage code review after verification
 
-Phase 3 (Gates & Review) has not yet shipped.
-You may manually review .flow/specs/$SPEC_NAME/ and git log to confirm quality.
+Do not claim the feature is shipped from execute alone. Execute completes tasks;
+verify proves user-visible goals; review checks implementation quality.
 ```

package/skills/implement/references/wave-execution.md

@@ -5,7 +5,7 @@ implement skill routes to the `wave` strategy. The knowledge-layer canonical
 algorithm lives in `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`;
 this file is the walkthrough the skill itself embeds for implementers.
 
-**Core**: consecutive `[P]` tasks form a wave, dispatch multiple Tasks in
+**Core**: consecutive `[P]` tasks form a wave, dispatch multiple Agent calls in
 parallel within a single message, serial across waves.
 
 ## Step 1: DAG Analysis
@@ -51,13 +51,13 @@ If the planner mis-tagged `[P]` (modifies the same file), split the wave automat
 ## Step 3: Dispatch a Single Wave (key: within a single response)
 
 ```
-# List multiple Task tool calls in one response of the main agent:
-Task(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
-Task(description="Execute 1.2", prompt=<...flow-executor + task_id=1.2...>)
-Task(description="Execute 1.3", prompt=<...flow-executor + task_id=1.3...>)
+# List multiple Agent tool calls in one response of the main agent:
+Agent(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
+Agent(description="Execute 1.2", prompt=<...flow-executor + task_id=1.2...>)
+Agent(description="Execute 1.3", prompt=<...flow-executor + task_id=1.3...>)
 ```
 
-Each Task prompt follows a uniform format (similar to subagent strategy):
+Each Agent prompt follows a uniform format (similar to subagent strategy):
 
 ```
 You are the flow-executor agent. Full definition:
@@ -82,12 +82,12 @@ Output:
 ```
 
 **Not allowed**:
-- Splitting multiple Task calls across multiple responses (that is serial degradation)
-- Nesting another Task dispatch inside a Task
+- Splitting multiple Agent calls across multiple responses (that is serial degradation)
+- Nesting another Agent dispatch inside an Agent
 
 ## Step 4: Aggregate Wave Results
 
-Wait for all Tasks to return:
+Wait for all Agent calls to return:
 
 ```python
 completed = []; failed = []