@curdx/flow 2.2.0 → 2.2.4

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/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
 

package/hooks/scripts/subagent-artifact-guard.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# CurDX-Flow SubagentStop Hook
+# Blocks successful subagent completion if the expected artifact never landed on disk.
+#
+# Why:
+# - long markdown/report-writing agents can truncate near the end of a run
+# - users then see a cheerful success summary but the actual file is missing or tiny
+# - latest Claude Code hooks expose SubagentStop with agent_type + last_assistant_message,
+#   which lets us guard only "success-looking" exits while allowing genuine precondition failures
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+
+if ! has_python3; then
+  # Without JSON parsing, fail open rather than blocking subagents blindly.
+  exit 0
+fi
+
+export SUBAGENT_GUARD_INPUT="$INPUT"
+
+AGENT_TYPE="$(python3 -c 'import json, os
+try:
+    data = json.loads(os.environ["SUBAGENT_GUARD_INPUT"])
+    print(data.get("agent_type", ""))
+except Exception:
+    print("")
+' 2>/dev/null)"
+
+LAST_MESSAGE="$(python3 -c 'import json, os
+try:
+    data = json.loads(os.environ["SUBAGENT_GUARD_INPUT"])
+    print((data.get("last_assistant_message") or "").strip())
+except Exception:
+    print("")
+' 2>/dev/null)"
+
+looks_like_success() {
+  local msg="${1:-}"
+  printf '%s' "$msg" | grep -Eq '(^✓| generated$| generated\n|Wrote |Review complete|Requirements done|Research complete|UI Sketch generation complete|Report:|Next:|TASK_COMPLETE|ALL_TASKS_COMPLETE)'
+}
+
+active_spec_path() {
+  local file_name="$1"
+
+  [ ! -d ".flow" ] && return 1
+
+  local active
+  active="$(cat .flow/.active-spec 2>/dev/null)"
+  [ -z "$active" ] && return 1
+
+  printf '.flow/specs/%s/%s\n' "$active" "$file_name"
+}
+
+completed_task_id() {
+  local msg="${1:-}"
+  printf '%s' "$msg" | sed -nE 's/.*TASK_COMPLETE:[[:space:]]*([0-9]+(\.([0-9]+|VF|X(\+[0-9]+)?))*).*/\1/p' | head -1
+}
+
+artifact_target=""
+minimum_size=200
+
+case "$AGENT_TYPE" in
+  flow-researcher)
+    artifact_target="$(active_spec_path research.md)" || exit 0
+    minimum_size=400
+    ;;
+  flow-product-designer)
+    artifact_target="$(active_spec_path requirements.md)" || exit 0
+    minimum_size=400
+    ;;
+  flow-architect)
+    artifact_target="$(active_spec_path design.md)" || exit 0
+    minimum_size=400
+    ;;
+  flow-planner)
+    artifact_target="$(active_spec_path tasks.md)" || exit 0
+    minimum_size=400
+    ;;
+  flow-executor)
+    artifact_target="$(active_spec_path tasks.md)" || exit 0
+    if printf '%s' "$LAST_MESSAGE" | grep -q 'ALL_TASKS_COMPLETE'; then
+      exit 0
+    fi
+    task_id="$(completed_task_id "$LAST_MESSAGE")"
+    [ -z "$task_id" ] && exit 0
+    if grep -Eq "^- \\[x\\] \\*\\*${task_id//./\\.}\\*\\*" "$artifact_target" 2>/dev/null; then
+      exit 0
+    fi
+    emit_subagentstop_block "[CurDX-Flow subagent-artifact-guard] flow-executor emitted TASK_COMPLETE: ${task_id}, but ${artifact_target} does not mark that task as [x]. Update tasks.md and the spec progress/state before stopping."
+    exit 0
+    ;;
+  flow-debugger)
+    artifact_target="$(active_spec_path debug-report.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-triage-analyst)
+    artifact_target="$(active_spec_path triage-report.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-ux-designer)
+    artifact_target="$(active_spec_path ui-sketch.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-reviewer)
+    artifact_target="$(active_spec_path review-report.md)" || exit 0
+    minimum_size=300
+    ;;
+  flow-verifier)
+    artifact_target="$(active_spec_path verification-report.md)" || exit 0
+    minimum_size=300
+    ;;
+  flow-security-auditor)
+    artifact_target="$(active_spec_path security-audit.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-qa-engineer)
+    artifact_target="$(active_spec_path qa-report.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-edge-hunter)
+    artifact_target="$(active_spec_path edge-cases.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-adversary)
+    artifact_target="$(active_spec_path adversarial-review.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-ui-researcher)
+    artifact_target="$(active_spec_path ui-research.md)" || exit 0
+    minimum_size=250
+    ;;
+  flow-brownfield-analyst)
+    artifact_target=".flow/codebase-index.md"
+    minimum_size=250
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+if [ -f "$artifact_target" ]; then
+  size="$(wc -c < "$artifact_target" 2>/dev/null | tr -d ' ')"
+  if [ "${size:-0}" -ge "$minimum_size" ]; then
+    exit 0
+  fi
+fi
+
+if ! looks_like_success "$LAST_MESSAGE"; then
+  # The subagent appears to be stopping because of a real precondition failure,
+  # clarification request, or other non-success path. Let that response through.
+  exit 0
+fi
+
+emit_subagentstop_block "[CurDX-Flow subagent-artifact-guard] ${AGENT_TYPE} is stopping with a success summary, but ${artifact_target} is missing or too small. Write the full artifact to disk first, then respond with the minimal completion summary only."
+exit 0

package/hooks/scripts/subagent-statusline.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# CurDX-Flow subagentStatusLine command.
+# Reads the official subagent status-line JSON payload from stdin and emits
+# one JSON line per CurDX-Flow subagent row that should be overridden.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/common.sh"
+
+INPUT="$(cat 2>/dev/null || echo "{}")"
+
+if ! has_python3; then
+  exit 0
+fi
+
+export CURDX_SUBAGENT_STATUSLINE_INPUT="$INPUT"
+
+python3 <<'PY'
+import json
+import os
+from pathlib import Path
+
+try:
+    data = json.loads(os.environ.get("CURDX_SUBAGENT_STATUSLINE_INPUT", "{}"))
+except Exception:
+    raise SystemExit(0)
+
+columns = data.get("columns")
+try:
+    columns = int(columns)
+except Exception:
+    columns = 100
+columns = max(40, columns)
+
+
+def flow_type(task):
+    raw = str(task.get("type") or task.get("name") or task.get("label") or "")
+    if raw.startswith("curdx-flow:"):
+        raw = raw.split(":", 1)[1]
+    return raw
+
+
+def is_flow_task(task):
+    values = [
+        task.get("type"),
+        task.get("name"),
+        task.get("label"),
+        task.get("description"),
+    ]
+    return any(str(value or "").startswith(("flow-", "curdx-flow:flow-")) for value in values)
+
+
+def active_spec(cwd):
+    if not cwd:
+        return ""
+    try:
+        value = (Path(cwd) / ".flow" / ".active-spec").read_text(encoding="utf-8").strip()
+    except Exception:
+        return ""
+    return value[:40]
+
+
+def token_label(value):
+    try:
+        count = int(value)
+    except Exception:
+        return ""
+    if count >= 1000:
+        return f"{count / 1000:.1f}k tok"
+    return f"{count} tok"
+
+
+def clamp(text):
+    if len(text) <= columns:
+        return text
+    if columns <= 4:
+        return text[:columns]
+    return text[: columns - 3] + "..."
+
+
+for task in data.get("tasks") or []:
+    if not isinstance(task, dict) or not is_flow_task(task):
+        continue
+
+    task_id = task.get("id")
+    if not task_id:
+        continue
+
+    parts = ["[curdx-flow]", flow_type(task) or "flow-agent"]
+
+    status = str(task.get("status") or "").strip()
+    if status:
+        parts.append(status)
+
+    spec = active_spec(task.get("cwd"))
+    if spec:
+        parts.append(f"spec:{spec}")
+
+    tokens = token_label(task.get("tokenCount"))
+    if tokens:
+        parts.append(tokens)
+
+    print(json.dumps({"id": str(task_id), "content": clamp(" | ".join(parts))}, ensure_ascii=True))
+PY

package/knowledge/atomic-commits.md

@@ -230,7 +230,7 @@ PR review reads each commit's message.
 - Good commit message → reviewer finishes in 5 minutes
 - Bad commit message → reviewer either rubber-stamps or blocks without reading
 
-CurdX-Flow's `/curdx-flow:ship` command (Phase 6) will turn atomic commits into a clean PR description. Poor commit quality yields poor PR descriptions.
+CurdX-Flow's review handoff expects atomic commits plus verification/review reports. Poor commit quality yields poor PR descriptions and weak release evidence.
 
 ---