@curdx/flow 2.2.0 → 2.2.4

package/schemas/skill-frontmatter.schema.json

@@ -14,11 +14,11 @@
     "description": {
       "type": "string",
       "minLength": 1,
-      "description": "Concise trigger summary. Keep detailed trigger phrases in when_to_use."
+      "description": "Concise trigger summary. Front-load the key use case. Combined description + when_to_use text is truncated at 1536 characters in Claude Code's skill listing."
     },
     "when_to_use": {
       "type": "string",
-      "description": "Additional trigger phrases appended to description in the skill listing."
+      "description": "Additional trigger phrases appended to description in the skill listing. Counts toward the same 1536-character listing cap."
     },
     "argument-hint": {
       "type": "string"
@@ -33,7 +33,8 @@
       "type": "boolean"
     },
     "user-invocable": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "Controls whether the skill appears in the slash menu. Does not block model invocation; use disable-model-invocation for that."
     },
     "allowed-tools": {
       "oneOf": [
@@ -56,7 +57,7 @@
       "type": "string"
     },
     "hooks": {
-      "type": "object"
+      "$ref": "#/definitions/skillHooks"
     },
     "paths": {
       "oneOf": [
@@ -68,5 +69,109 @@
       "type": "string",
       "enum": ["bash", "powershell"]
     }
+  },
+  "definitions": {
+    "skillHooks": {
+      "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" }
+      }
+    },
+    "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/spec-state.schema.json

@@ -44,7 +44,6 @@
         "execute",
         "verify",
         "review",
-        "ship",
         "completed"
       ]
     },
@@ -57,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": {
@@ -73,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

@@ -2,7 +2,30 @@
 name: brownfield-index
 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".
-allowed-tools: [Read, Grep, Glob, Bash]
+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
@@ -16,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."
@@ -58,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

@@ -2,7 +2,15 @@
 name: browser-qa
 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".
-allowed-tools: [Read, Write, Bash, Grep, Glob, WebFetch]
+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
@@ -23,9 +31,9 @@ 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:
+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`

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,6 +1,7 @@
 ---
 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
@@ -28,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**.
@@ -54,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`.
 
@@ -82,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

@@ -2,7 +2,9 @@
 name: epic
 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".
-allowed-tools: [Read, Write, Grep, Glob, Bash]
+argument-hint: "\"<epic goal>\""
+context: fork
+agent: flow-triage-analyst
 ---
 
 # Epic Decomposition
@@ -23,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,6 +1,7 @@
 ---
 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>\""
 disable-model-invocation: true
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]

package/skills/help/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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]
@@ -10,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
@@ -49,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"
@@ -60,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
 
@@ -81,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
@@ -121,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:
@@ -140,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,6 +1,7 @@
 ---
 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]"
 disable-model-invocation: true
 allowed-tools: [Read, Write, Edit, Bash, Agent, Grep, Glob]
@@ -45,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")
 
@@ -88,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'
@@ -96,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)
@@ -184,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
@@ -218,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
 
@@ -233,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.
 ```