@curdx/flow 2.1.0 → 2.2.3

package/cli/lib/frontmatter.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+
+function formatYamlErrors(errors) {
+  return errors.map((error) => error.message).join("; ");
+}
+
+export function extractFrontmatterBlock(text, sourceLabel = "frontmatter") {
+  const match = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) {
+    throw new Error(`${sourceLabel}: missing YAML frontmatter`);
+  }
+
+  return match[1];
+}
+
+export function parseFrontmatterBlock(block, sourceLabel = "frontmatter") {
+  const document = YAML.parseDocument(block, {
+    strict: true,
+    uniqueKeys: true,
+  });
+
+  if (document.errors.length > 0) {
+    throw new Error(`${sourceLabel}: invalid YAML (${formatYamlErrors(document.errors)})`);
+  }
+
+  const value = document.toJS();
+  if (value == null) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${sourceLabel}: frontmatter must parse to an object`);
+  }
+
+  return value;
+}
+
+export function readFrontmatter(filePath) {
+  const text = readFileSync(filePath, "utf-8");
+  const block = extractFrontmatterBlock(text, filePath);
+  return parseFrontmatterBlock(block, filePath);
+}
+
+export function readFrontmatterFields(filePath) {
+  return Object.keys(readFrontmatter(filePath));
+}

package/cli/lib/json-schema.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import Ajv from "ajv";
+
+const ajv = new Ajv({
+  allErrors: true,
+  allowUnionTypes: true,
+  strict: false,
+});
+
+const validatorCache = new Map();
+
+function formatParams(params = {}) {
+  if (params.missingProperty) return ` missingProperty=${params.missingProperty}`;
+  if (params.additionalProperty) return ` additionalProperty=${params.additionalProperty}`;
+  return "";
+}
+
+export function readJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+
+export function formatAjvErrors(errors = []) {
+  return errors.map((error) => {
+    const where = error.instancePath || error.schemaPath || "(root)";
+    return `${where}: ${error.message}${formatParams(error.params)}`;
+  });
+}
+
+function getSchemaValidator(schemaPath) {
+  const absPath = resolve(schemaPath);
+  if (validatorCache.has(absPath)) return validatorCache.get(absPath);
+
+  const schema = readJsonFile(absPath);
+  const validate = ajv.compile(schema);
+  const entry = { absPath, schema, validate };
+  validatorCache.set(absPath, entry);
+  return entry;
+}
+
+export function validateAgainstSchemaFile(schemaPath, data) {
+  const { validate } = getSchemaValidator(schemaPath);
+  const valid = Boolean(validate(data));
+  return {
+    valid,
+    errors: valid ? [] : formatAjvErrors(validate.errors),
+  };
+}
+
+export function validateSchemaFile(schemaPath) {
+  const schema = readJsonFile(resolve(schemaPath));
+  const valid = ajv.validateSchema(schema);
+  return {
+    valid,
+    errors: valid ? [] : formatAjvErrors(ajv.errors),
+  };
+}

package/cli/lib/runtime.js

@@ -52,15 +52,18 @@ function findSymlinkDir() {
   return null;
 }
 
-export function ensureRuntimeInPath(cmd, candidates) {
+function getRuntimeStatus(cmd, candidates, { repair = false } = {}) {
   if (has(cmd)) return { status: "ok" };
-
   const realPath = findRuntime(candidates);
   if (!realPath) return { status: "missing" };
 
   const linkDir = findSymlinkDir();
   if (!linkDir) return { status: "path-unwritable", path: realPath };
 
+  if (!repair) {
+    return { status: "linkable", path: realPath, link: join(linkDir, cmd) };
+  }
+
   const linkPath = join(linkDir, cmd);
   if (existsSync(linkPath)) {
     try {
@@ -81,6 +84,21 @@ export function ensureRuntimeInPath(cmd, candidates) {
   }
 }
 
+export function inspectRuntimeInPath(cmd, candidates) {
+  return getRuntimeStatus(cmd, candidates, { repair: false });
+}
+
+export function ensureRuntimeInPath(cmd, candidates) {
+  return getRuntimeStatus(cmd, candidates, { repair: true });
+}
+
+export function inspectClaudeMemRuntimes() {
+  return {
+    bun: inspectRuntimeInPath("bun", BUN_CANDIDATES),
+    uv: inspectRuntimeInPath("uv", UV_CANDIDATES),
+  };
+}
+
 export function ensureClaudeMemRuntimes() {
   return {
     bun: ensureRuntimeInPath("bun", BUN_CANDIDATES),

package/cli/lib/semver.js

@@ -0,0 +1,95 @@
+function normalizeVersionToken(token) {
+  return /^\d+$/.test(token) ? Number(token) : token;
+}
+
+function parseVersion(version) {
+  const normalized = String(version || "").trim().replace(/^v/i, "");
+  const [coreRaw = "0", prereleaseRaw] = normalized.split("-", 2);
+  const core = coreRaw.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const prerelease = prereleaseRaw
+    ? prereleaseRaw.split(/[.-]/).filter(Boolean).map(normalizeVersionToken)
+    : [];
+
+  return { core, prerelease };
+}
+
+function compareIdentifier(left, right) {
+  if (left === right) {
+    return 0;
+  }
+
+  const leftIsNumber = typeof left === "number";
+  const rightIsNumber = typeof right === "number";
+
+  if (leftIsNumber && rightIsNumber) {
+    return left > right ? 1 : -1;
+  }
+
+  if (leftIsNumber) {
+    return -1;
+  }
+
+  if (rightIsNumber) {
+    return 1;
+  }
+
+  return left > right ? 1 : -1;
+}
+
+export function compareVersions(leftVersion, rightVersion) {
+  const left = parseVersion(leftVersion);
+  const right = parseVersion(rightVersion);
+  const coreLength = Math.max(left.core.length, right.core.length);
+
+  for (let index = 0; index < coreLength; index += 1) {
+    const leftPart = left.core[index] ?? 0;
+    const rightPart = right.core[index] ?? 0;
+    if (leftPart !== rightPart) {
+      return leftPart > rightPart ? 1 : -1;
+    }
+  }
+
+  const leftHasPrerelease = left.prerelease.length > 0;
+  const rightHasPrerelease = right.prerelease.length > 0;
+
+  if (!leftHasPrerelease && !rightHasPrerelease) {
+    return 0;
+  }
+
+  if (!leftHasPrerelease) {
+    return 1;
+  }
+
+  if (!rightHasPrerelease) {
+    return -1;
+  }
+
+  const prereleaseLength = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < prereleaseLength; index += 1) {
+    const leftPart = left.prerelease[index];
+    const rightPart = right.prerelease[index];
+
+    if (leftPart === undefined) {
+      return -1;
+    }
+
+    if (rightPart === undefined) {
+      return 1;
+    }
+
+    const comparison = compareIdentifier(leftPart, rightPart);
+    if (comparison !== 0) {
+      return comparison;
+    }
+  }
+
+  return 0;
+}
+
+export function isVersionNewer(latestVersion, currentVersion) {
+  return compareVersions(latestVersion, currentVersion) > 0;
+}
+
+export function isVersionAtLeast(version, minimumVersion) {
+  return compareVersions(version, minimumVersion) >= 0;
+}

package/cli/utils.js

@@ -29,6 +29,12 @@ export {
   listPluginMarketplaces,
   listPlugins,
   parseMcpList,
+  parsePluginListJson,
   readUserMcpConfig,
 } from "./lib/claude.js";
-export { ensureClaudeMemRuntimes, ensureRuntimeInPath } from "./lib/runtime.js";
+export {
+  ensureClaudeMemRuntimes,
+  ensureRuntimeInPath,
+  inspectClaudeMemRuntimes,
+  inspectRuntimeInPath,
+} from "./lib/runtime.js";

package/gates/adversarial-review-gate.md

@@ -17,7 +17,7 @@ depends_on: []
 
 - /curdx-flow:review command
 - Before Phase transitions (requirements → design, design → tasks)
-- Before code merge (/curdx-flow:ship)
+- Before code merge or human PR/release handoff
 - Enabled by default in Enterprise mode
 
 ---

package/gates/security-gate.md

@@ -14,7 +14,7 @@ depends_on: []
 ## Trigger Timing
 
 - When the `security-audit` skill runs
-- Before `/curdx-flow:ship` (auto-triggered, Phase 6+)
+- Before human PR/release handoff, after `/curdx-flow:verify` and `/curdx-flow:review`
 - When committing specs involving auth / payments / PII
 
 ---
@@ -154,7 +154,7 @@ pnpm audit
 
 ### Blocking Items
 
-- If SR-01 ~ SR-05 are found → block immediately, prohibit `/curdx-flow:ship`
+- If SR-01 ~ SR-05 are found → block immediately; do not hand off for PR/release
 - Must fix or explicitly exempt (record in STATE.md as tech debt + commitment to fix before release)
 
 ### Warning Items

package/gates/test-quality-gate.md

@@ -0,0 +1,59 @@
+---
+gate: test-quality-gate
+category: standard-mode
+severity: blocking
+depends_on: []
+---
+
+# Test Quality Gate
+
+A green test suite is not enough. Tests must exercise real behavior and fail for the right reason.
+
+## Blocking Findings
+
+Flag as blocking when a test is the only evidence for an FR/AC and any of these hold:
+
+1. **Mock-only behavior**
+   - Assertions only check mock calls (`toHaveBeenCalled`, `calledWith`, spy counts).
+   - The real module/function under test is never invoked.
+   - The test would still pass if the production implementation were empty.
+
+2. **Mock setup dominates evidence**
+   - Mock/stub/spy setup lines are more than 3x real behavioral assertions.
+   - The test mostly restates fixture wiring instead of asserting output, state, persistence, or user-visible behavior.
+
+3. **Skipped or inert tests**
+   - `it.skip`, `describe.skip`, `test.skip`, `xit`, `pending`, or equivalent on covered behavior.
+   - Test has no assertions and no meaningful side-effect check.
+
+4. **Implementation-biased regression**
+   - Test was added after implementation without evidence of RED failure when the task claims TDD.
+   - Test asserts internal private structure instead of externally observable behavior.
+
+5. **Missing cleanup for stateful mocks**
+   - Stateful mocks/spies are used across tests without `afterEach` cleanup (`restoreAllMocks`, `clearAllMocks`, sandbox restore, etc.).
+   - Shared mock state can leak between tests.
+
+## Acceptable Mock Usage
+
+Mocks are acceptable when they isolate a boundary and the assertion still verifies real behavior:
+
+- Network/payment/email provider mocked, but service logic and error handling are real.
+- Clock/randomness mocked to make deterministic assertions.
+- Database mocked only when a separate integration test covers persistence behavior.
+
+## Evidence Checklist
+
+For each FR/AC test evidence, record:
+
+- Test file and test name.
+- What real code path is invoked.
+- What behavioral assertion proves the requirement.
+- Whether the test was observed RED before GREEN when TDD is claimed.
+- Whether mocks are boundary-only or behavior-replacing.
+
+## Verdicts
+
+- `PASS`: Tests exercise real behavior with meaningful assertions.
+- `WARN`: Mock-heavy but supported by separate integration/e2e coverage.
+- `FAIL`: Mock-only/skipped/no-assertion test is used as primary evidence.

package/hooks/hooks.json

@@ -5,7 +5,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
+            "statusMessage": "Loading CurDX-Flow project context"
           }
         ]
       },
@@ -14,7 +15,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/inject-karpathy.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/inject-karpathy.sh",
+            "statusMessage": "Injecting CurDX-Flow engineering baseline"
           }
         ]
       }
@@ -29,6 +31,18 @@
         ]
       }
     ],
+    "SubagentStop": [
+      {
+        "matcher": "flow-(architect|brownfield-analyst|debugger|edge-hunter|executor|product-designer|planner|qa-engineer|researcher|reviewer|security-auditor|triage-analyst|ui-researcher|ux-designer|verifier|adversary)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-artifact-guard.sh",
+            "statusMessage": "Checking curdx-flow artifact landing"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "AskUserQuestion",

package/hooks/scripts/common.sh

@@ -33,3 +33,7 @@ emit_stop_block() {
   local reason="${1:-}"
   printf '{"decision":"block","reason":%s}\n' "$(json_escape "$reason")"
 }
+
+emit_subagentstop_block() {
+  emit_stop_block "${1:-}"
+}

package/hooks/scripts/quick-mode-guard.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # CurDX-Flow PreToolUse Hook for AskUserQuestion
-# Blocks AskUserQuestion when the active spec has quickMode=true or mode=autonomous.
-# This prevents the autonomous loop from stalling waiting for user input.
+# Blocks AskUserQuestion when the active spec has quickMode=true.
+# This prevents quick execution loops from stalling waiting for user input.
 #
 # The hook reads Claude's PreToolUse input JSON from stdin. We only act when
 # the tool being invoked is AskUserQuestion.
@@ -34,7 +34,7 @@ if [ "$TOOL_NAME" != "AskUserQuestion" ]; then
   exit 0
 fi
 
-# Check if we're in a flow project with quick mode enabled
+# Check if we're in a flow project with quick mode enabled.
 [ ! -d ".flow" ] && exit 0
 
 ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
@@ -43,7 +43,7 @@ ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
 STATE_FILE=".flow/specs/$ACTIVE/.state.json"
 [ ! -f "$STATE_FILE" ] && exit 0
 
-# Read quickMode + mode. Pass STATE_FILE via env (NOT shell interpolation
+# Read quickMode. Pass STATE_FILE via env (NOT shell interpolation
 # into the python source) so an active-spec name containing quotes/$ cannot
 # inject python code.
 export STATE_FILE
@@ -52,15 +52,14 @@ import json, os
 try:
     s = json.load(open(os.environ["STATE_FILE"]))
     qm = s.get("quickMode", False)
-    mode = s.get("mode", "")
-    print("true" if (qm or mode == "autonomous") else "false")
+    print("true" if qm else "false")
 except Exception:
     print("false")
 ' 2>/dev/null)
 
 if [ "$QUICK_MODE" = "true" ]; then
   # Block and inject guidance
-  MSG="[CurDX-Flow quick-mode-guard] Active spec '$ACTIVE' is in quick mode or autonomous mode — AskUserQuestion is forbidden. Decide autonomously based on user preferences in .flow/CONTEXT.md plus the most reasonable assumption, and record your assumption in .progress.md."
+  MSG="[CurDX-Flow quick-mode-guard] Active spec '$ACTIVE' is in quick mode — AskUserQuestion is forbidden. Decide based on user preferences in .flow/CONTEXT.md plus the most reasonable assumption, and record your assumption in .progress.md."
   emit_pretooluse_deny "$MSG"
   exit 0
 fi

package/hooks/scripts/session-start.sh

@@ -3,6 +3,7 @@
 # Duties:
 #   1. Daily dependency check — nudge user to `npx @curdx/flow install --all` if recommended plugins missing
 #   2. Load active spec progress into session context
+#   3. Persist stable CurDX-Flow environment hints for this session
 #
 # Design notes:
 #   - Idempotent: marker file tracks last check date
@@ -45,12 +46,15 @@ if [ "$LAST_CHECK" != "$TODAY" ]; then
     ADDITIONAL_CONTEXT+="## CurDX-Flow Recommended Plugins Check\n\nThe following recommended plugins were not detected: **${JOINED}**\n\nRun \`npx @curdx/flow install --all\` for interactive one-shot install. Run \`npx @curdx/flow doctor\` for the full health report.\n\n"
   fi
 
-  echo "$TODAY" > "$MARKER" 2>/dev/null || true
+  { echo "$TODAY" > "$MARKER"; } 2>/dev/null || true
 fi
 
 # ---------- 2. Load .flow/ state (if project is a flow project) ----------
 if [ -d ".flow" ]; then
   ADDITIONAL_CONTEXT+="## CurDX-Flow Project Active\n\n"
+  ADDITIONAL_CONTEXT+="- Plugin root: \`${CLAUDE_PLUGIN_ROOT:-unknown}\`\n"
+  ADDITIONAL_CONTEXT+="- Plugin data: \`${CLAUDE_PLUGIN_DATA:-$DATA_DIR}\`\n"
+  ADDITIONAL_CONTEXT+="- Best practice: write long agent artifacts to disk first; keep final assistant summaries short.\n\n"
 
   if [ -f ".flow/PROJECT.md" ]; then
     ADDITIONAL_CONTEXT+="### Project Vision\n$(head -80 .flow/PROJECT.md)\n\n"
@@ -67,7 +71,18 @@ if [ -d ".flow" ]; then
   fi
 fi
 
-# ---------- 3. Emit hook output ----------
+# ---------- 3. Persist session environment hints ----------
+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
+  {
+    printf 'export CURDX_FLOW_PLUGIN_ROOT=%s\n' "$(json_escape "${CLAUDE_PLUGIN_ROOT:-}")"
+    printf 'export CURDX_FLOW_PLUGIN_DATA=%s\n' "$(json_escape "${CLAUDE_PLUGIN_DATA:-$DATA_DIR}")"
+    if [ -f ".flow/.active-spec" ]; then
+      printf 'export CURDX_FLOW_ACTIVE_SPEC=%s\n' "$(json_escape "$(cat .flow/.active-spec 2>/dev/null)")"
+    fi
+  } >> "$CLAUDE_ENV_FILE" 2>/dev/null || true
+fi
+
+# ---------- 4. Emit hook output ----------
 if [ -n "$ADDITIONAL_CONTEXT" ]; then
   emit_session_start_context "$ADDITIONAL_CONTEXT"
 fi

package/hooks/scripts/stop-watcher.sh

@@ -57,7 +57,7 @@ fi
 # the stop-hook strategy never activated.
 export STATE_FILE
 
-read STRATEGY PHASE TASK_INDEX TOTAL_TASKS FAILED ROUNDS <<EOF
+read STRATEGY PHASE TASK_INDEX TOTAL_TASKS FAILED ROUNDS RECOVERY_MODE MAX_FIX_TASKS <<EOF
 $(python3 <<'PY'
 import json, os, sys
 p = os.environ.get("STATE_FILE")
@@ -72,7 +72,9 @@ ti = ex.get("task_index", 0)
 tt = ex.get("total_tasks", 0)
 failed = ex.get("failed_attempts", 0)
 rounds = ex.get("global_iteration", 0)
-print(strategy, phase, ti, tt, failed, rounds)
+recovery_mode = ex.get("recovery_mode", "manual")
+max_fix_tasks = ex.get("max_fix_tasks_per_original", 2)
+print(strategy, phase, ti, tt, failed, rounds, recovery_mode, max_fix_tasks)
 PY
 )
 EOF
@@ -81,7 +83,7 @@ EOF
 [ "$STRATEGY" != "stop-hook" ] && allow_stop
 [ "$PHASE" != "execute" ] && allow_stop
 
-# ---------- 5. Check for completion signal in transcript ----------
+# ---------- 5. Check hook input + completion signal in transcript ----------
 # Claude Code passes transcript path via stdin as JSON: {"transcript_path": "/path/..."}
 # We read stdin to detect ALL_TASKS_COMPLETE or TASK_FAILED
 INPUT=$(cat 2>/dev/null || echo "{}")
@@ -89,6 +91,19 @@ TRANSCRIPT_PATH=$(echo "$INPUT" | python3 -c 'import json,sys;
 try: print(json.load(sys.stdin).get("transcript_path",""))
 except: print("")' 2>/dev/null)
 
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | python3 -c 'import json,sys;
+try: print("true" if json.load(sys.stdin).get("stop_hook_active", False) else "false")
+except: print("false")' 2>/dev/null)
+
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  # Claude Code sets stop_hook_active during a stop-hook continuation.
+  # Treat it as context only: the final decision still comes from transcript
+  # signals, state-file progress, and tasks.md parity. Unconditionally allowing
+  # stop here can terminate an in-flight stop-hook loop after the first
+  # continuation, leaving remaining tasks stranded.
+  echo "[CurDX-Flow stop-hook] stop_hook_active=true; evaluating transcript/state before deciding" >&2
+fi
+
 TRANSCRIPT_TAIL=""
 if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
   # Read last 50KB only (efficiency)
@@ -100,22 +115,54 @@ fi
 # python source text. Previously a spec name containing single quotes or
 # $-signs could break the script or inject arbitrary code.
 
-# Check for explicit completion signals
-if echo "$TRANSCRIPT_TAIL" | grep -q "ALL_TASKS_COMPLETE"; then
-  # Cleanup: mark phase completed
+# Helper: count unchecked tasks in tasks.md. If tasks.md is absent, return 0
+# to avoid blocking recovery for partially-initialized specs.
+unchecked_task_count() {
+  local tasks_file="$SPEC_DIR/tasks.md"
+  [ ! -f "$tasks_file" ] && { echo 0; return; }
+  grep -Ec '^- \[ \] \*\*[0-9]+(\.[0-9]+|\.VF|\.X|\.X\+1)*\*\*' "$tasks_file" 2>/dev/null || echo 0
+}
+
+last_task_signal() {
+  local msg="${1:-}"
+  printf '%s' "$msg" \
+    | grep -Eo 'ALL_TASKS_COMPLETE|TASK_(COMPLETE|FAILED):[[:space:]]*[0-9]+(\.([0-9]+|VF|X(\+[0-9]+)?))*' \
+    | tail -1
+}
+
+failed_task_id() {
+  local msg="${1:-}"
+  printf '%s' "$msg" | sed -nE 's/.*TASK_FAILED:[[:space:]]*([0-9]+(\.([0-9]+|VF|X(\+[0-9]+)?))*).*/\1/p' | tail -1
+}
+
+mark_execute_complete() {
   python3 <<'PY' 2>/dev/null
 import json, os
 p = os.environ["STATE_FILE"]
 s = json.load(open(p))
 s.setdefault("phase_status", {})["execute"] = "completed"
-s["phase"] = "verify"  # move to verify phase
+s["phase"] = "verify"
 json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
 PY
+}
+
+# Check for explicit completion signals
+LAST_TASK_SIGNAL="$(last_task_signal "$TRANSCRIPT_TAIL")"
+
+if [ "$LAST_TASK_SIGNAL" = "ALL_TASKS_COMPLETE" ]; then
+  UNCHECKED="$(unchecked_task_count)"
+  if [ "${UNCHECKED:-0}" -gt 0 ]; then
+    block_continue "[CurDX-Flow stop-hook] ALL_TASKS_COMPLETE was emitted, but tasks.md still has ${UNCHECKED} unchecked task(s). Read .flow/specs/${ACTIVE}/tasks.md, complete only the remaining unchecked tasks, update tasks.md, then emit ALL_TASKS_COMPLETE again."
+  fi
+  mark_execute_complete
   allow_stop
 fi
 
-# Check for fail signal (accumulate; actual stop decision below)
-if echo "$TRANSCRIPT_TAIL" | grep -q "TASK_FAILED"; then
+# Check for the latest fail signal (accumulate; actual stop decision below)
+if printf '%s' "$LAST_TASK_SIGNAL" | grep -q "^TASK_FAILED"; then
+  FAILED_TASK="$(failed_task_id "$LAST_TASK_SIGNAL")"
+  [ -z "$FAILED_TASK" ] && FAILED_TASK="the current task"
+
   # Increment failed_attempts
   python3 <<'PY' 2>/dev/null
 import json, os
@@ -127,6 +174,14 @@ json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
 PY
   # Re-read — again via os.environ, no shell interpolation into python.
   FAILED=$(python3 -c 'import json, os; print(json.load(open(os.environ["STATE_FILE"]))["execute_state"]["failed_attempts"])' 2>/dev/null || echo 0)
+
+  if [ "${FAILED:-0}" -lt 3 ]; then
+    if [ "${RECOVERY_MODE:-manual}" = "fix-task" ]; then
+      block_continue "[CurDX-Flow stop-hook] TASK_FAILED observed for ${FAILED_TASK}. Do not skip it. Recovery mode is fix-task: insert one targeted [FIX ${FAILED_TASK}] task immediately after the failed task in tasks.md (max ${MAX_FIX_TASKS:-2} fix task(s) per original), update .state.json execute_state.fix_task_map, then execute the fix task before retrying ${FAILED_TASK}. The fix task must include Do, Files, Done when, Verify, and Commit fields."
+    fi
+
+    block_continue "[CurDX-Flow stop-hook] TASK_FAILED observed for ${FAILED_TASK}. Do not advance past the failed task. Re-read tasks.md, perform root-cause analysis, retry the first unchecked task, and emit TASK_COMPLETE only after its Verify command passes. failed_attempts=${FAILED}/3."
+  fi
 fi
 
 # ---------- 6. Safety brakes ----------
@@ -142,15 +197,11 @@ fi
 
 # Check if all tasks done
 if [ "$TASK_INDEX" -ge "$TOTAL_TASKS" ] && [ "$TOTAL_TASKS" -gt 0 ]; then
-  # Mark complete
-  python3 <<'PY' 2>/dev/null
-import json, os
-p = os.environ["STATE_FILE"]
-s = json.load(open(p))
-s.setdefault("phase_status", {})["execute"] = "completed"
-s["phase"] = "verify"
-json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
-PY
+  UNCHECKED="$(unchecked_task_count)"
+  if [ "${UNCHECKED:-0}" -gt 0 ]; then
+    block_continue "[CurDX-Flow stop-hook] State says execute is complete (${TASK_INDEX}/${TOTAL_TASKS}), but tasks.md still has ${UNCHECKED} unchecked task(s). Continue with the first unchecked task; do not add new tasks."
+  fi
+  mark_execute_complete
   allow_stop
 fi