@curdx/flow 2.2.0 → 2.2.3

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

package/knowledge/claude-code-runtime-contracts.md

@@ -0,0 +1,203 @@
+# Claude Code Runtime Contracts — CurDX-Flow Notes
+
+CurDX-Flow depends on Claude Code's plugin, hook, skill, and subagent runtime surfaces. This page records the operational contracts we rely on so agents and maintainers do not drift from the current official behavior.
+
+## Source of Truth
+
+- Official docs entry: `https://code.claude.com/docs/en/overview`
+- Runtime-specific pages to re-check when changing behavior:
+  - Hooks: `/docs/en/hooks`
+  - Subagents: `/docs/en/sub-agents`
+  - Skills: `/docs/en/skills`
+  - Commands: `/docs/en/commands`
+  - Plugins: `/docs/en/plugins`
+  - Settings: `/docs/en/settings`
+  - Plugin manifest reference: `/docs/en/plugins-reference`
+  - Output styles: `/docs/en/output-styles`
+  - Status line: `/docs/en/statusline`
+  - Plugin dependency constraints: `/docs/en/plugin-dependencies`
+  - Routines / scheduled tasks: `/docs/en/routines`, `/docs/en/scheduled-tasks`
+
+When a behavior is unclear, prefer the official docs and `claude plugin validate .` over inferred behavior from older examples.
+
+## Hook Output Rules
+
+- `SessionStart` context injection must use:
+  - `hookSpecificOutput.hookEventName = "SessionStart"`
+  - `hookSpecificOutput.additionalContext = "..."`
+- Persistent environment for later hook/script invocations must be written to `CLAUDE_ENV_FILE` as shell exports. Do not invent a JSON top-level `environmentVariables` field.
+- `Stop` / `SubagentStop` continuation blocking uses top-level `decision: "block"` plus `reason`.
+- `PreToolUse` denial uses `hookSpecificOutput.permissionDecision = "deny"` and `permissionDecisionReason`.
+- `PreToolUse` also supports `hookSpecificOutput.permissionDecision = "defer"` for deferred tool handling in `-p` / SDK-style flows; do not assume deny/allow are the only valid permission outcomes.
+- `PermissionDenied` can return `{ "retry": true }` to let Claude try a different approach after an auto-mode classifier denial.
+- Hooks must fail open when runtime prerequisites are missing (`python3`, malformed stdin JSON, absent `.flow/` state). The exception is an explicit, success-looking subagent completion with a missing required artifact.
+
+## Subagent Artifact Discipline
+
+Subagents that produce long reports must write the artifact before producing the final assistant summary. The final summary should be short and point to the file path.
+
+Guarded artifact targets:
+
+| Agent | Expected artifact |
+| --- | --- |
+| `flow-researcher` | `.flow/specs/<active>/research.md` |
+| `flow-product-designer` | `.flow/specs/<active>/requirements.md` |
+| `flow-architect` | `.flow/specs/<active>/design.md` |
+| `flow-planner` | `.flow/specs/<active>/tasks.md` |
+| `flow-reviewer` | `.flow/specs/<active>/review-report.md` |
+| `flow-verifier` | `.flow/specs/<active>/verification-report.md` |
+| `flow-security-auditor` | `.flow/specs/<active>/security-audit.md` |
+| `flow-qa-engineer` | `.flow/specs/<active>/qa-report.md` |
+| `flow-edge-hunter` | `.flow/specs/<active>/edge-cases.md` |
+| `flow-adversary` | `.flow/specs/<active>/adversarial-review.md` |
+| `flow-ui-researcher` | `.flow/specs/<active>/ui-research.md` |
+| `flow-brownfield-analyst` | `.flow/codebase-index.md` |
+
+`flow-executor` is marker-driven rather than report-driven: it must update task state and end with `TASK_COMPLETE: <task_id>` or `TASK_FAILED: <task_id>`.
+
+## Agent Teams Compatibility
+
+- Official `agent-teams` behavior differs from regular subagent invocation in one critical way: when a subagent definition runs as a teammate, its `skills` and `mcpServers` frontmatter fields are not applied.
+- Team coordination tools remain available to teammates, but any agent that relies on a preloaded skill must also have access to the `Skill` tool so it can invoke that skill explicitly when used as a teammate.
+- A project file like `.claude/teams/teams.json` is not configuration. Official docs say team config lives under user scope, not project scope.
+
+## Skills and Frontmatter
+
+- Keep `SKILL.md` frontmatter minimal and schema-backed.
+- Use `description` for the concise trigger phrase; put longer trigger examples in `when_to_use`.
+- Use forked context and a named agent only when the skill's work benefits from isolation or a specialized role.
+- Avoid preloading broad tool access. Prefer the smallest useful tool set per skill/agent.
+- Do not make bundled skills or agents implicitly depend on runtime-gated tools such as `SendMessage`, `TeamCreate`, `TeamDelete`, or `ToolSearch` unless CurDX-Flow also ships the matching feature-flag/setup contract.
+
+## Plugin Settings
+
+- Claude Code plugin-root `settings.json` currently supports only `agent` and `subagentStatusLine`.
+- CurDX-Flow ships only `subagentStatusLine`, pointing at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh`.
+- The status-line script must fail open on malformed input or missing `python3`; UI decoration must never break agent execution.
+- Plugin-root references must never traverse outside the plugin directory. Installed marketplace plugins run from Claude Code's plugin cache, so parent-directory references are invalid even if they work in a development checkout.
+- If adding plugin settings, update `schemas/plugin-settings.schema.json`, `test/plugin-structure-contract.test.js`, `test/pack-tarball-smoke.test.js`, and `scripts/validate-plugin-contracts.mjs` in the same change.
+
+## Plugin Dependency Constraints
+
+- Official dependency version constraints require upstream plugin release tags in the `{plugin-name}--v{version}` format.
+- Do not add a version constraint to the `context7-plugin` dependency unless the Upstash marketplace has matching `context7-plugin--v*` tags. A semver range without those tags can disable dependency resolution.
+- Keep the CLI registry and `.claude-plugin/plugin.json` dependency entry aligned: Context7 remains a required companion plugin, while optional tools stay in `RECOMMENDED_PLUGINS`.
+
+## Shared Settings Guardrails
+
+- `.claude/settings.json` is a shared project surface. Keep machine-local scripts, secrets, and credential helpers out of it.
+- Official docs say these keys are ignored or not accepted at project scope and must live in user/local/managed settings instead:
+  - `autoMemoryDirectory`
+  - `autoMode`
+  - `useAutoModeDuringPlan`
+  - `permissions.skipDangerousModePermissionPrompt`
+  - `sshConfigs`
+  - `teammateMode` belongs in the global `~/.claude.json` config, not project `settings.json`.
+- Treat shared auto-approval settings as high risk:
+  - `enableAllProjectMcpServers`
+  - `enabledMcpjsonServers`
+- Treat shared hook and skill policy as behavior-changing:
+  - `disableSkillShellExecution: true` replaces inline shell output in project/plugin skills and commands with a disabled placeholder.
+  - Empty `allowedHttpHookUrls` blocks all HTTP hook targets.
+  - Empty `httpHookAllowedEnvVars` prevents HTTP hook header environment interpolation.
+- Treat shared `env` injection as behavior-changing when it flips Claude runtime modes:
+  - `CLAUDE_CODE_SIMPLE=1` puts Claude Code into bare/simple mode and disables hooks, skills, plugins, MCP discovery, auto memory, and `CLAUDE.md`.
+  - `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=1` keeps discovery enabled but swaps in the minimal Claude system prompt.
+  - `CLAUDE_CODE_EFFORT_LEVEL=low|medium` lowers reasoning for every collaborator session.
+  - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` enables experimental teammate surfaces for every collaborator session.
+  - Provider-specific pinned model IDs (`ANTHROPIC_DEFAULT_*_MODEL`, `ANTHROPIC_CUSTOM_MODEL_OPTION`) should usually be paired with `_SUPPORTED_CAPABILITIES` so Claude keeps effort / thinking feature detection.
+  - In CI / headless runs, `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` makes marketplace plugins available before the first turn; otherwise they can install in the background and miss turn one.
+  - `CLAUDE_CODE_PLUGIN_SEED_DIR` is the official way to pre-populate marketplace plugins in containers and CI images.
+- Treat shared sandbox policy as runtime-sensitive:
+  - `sandbox.failIfUnavailable: true` can fail Claude Code startup on unsupported hosts.
+  - `sandbox.filesystem.denyRead` / `denyWrite` must not block `.flow`, `.git`, or the project root.
+  - Empty `sandbox.network.allowedDomains` blocks outbound network access for sandboxed commands.
+- Prefer `attribution` over deprecated `includeCoAuthoredBy`.
+- Treat shared runtime blockers as high risk for CurDX-Flow:
+  - `disableAllHooks: true` disables stop-hook recovery, artifact guards, and custom status lines.
+  - `agent: "<name>"` routes the main thread through a named subagent, replacing the normal CurDX-Flow prompt, tool surface, and model for the whole session.
+  - `permissions.defaultMode: "dontAsk"` can auto-deny clarification and Agent dispatch prompts.
+  - `permissions.deny` rules for `Agent`, `AskUserQuestion`, CurDX-Flow `flow-*` agents, or broad `Bash` / `Monitor` / `Read` / `Write` / `Edit` / `Grep` / `Glob` tools can make workflows fail.
+  - `availableModels` must include the portable `sonnet` and `opus` aliases used by bundled agents.
+  - Shared `effortLevel: "low"` or `"medium"` may underpower main-thread planning/review turns; prefer `high` / `xhigh` for CurDX-Flow-heavy projects.
+  - `CLAUDE_CODE_SIMPLE=1` in the launch environment is a hard runtime blocker for CurDX-Flow because Claude stops discovering plugin assets and `CLAUDE.md`.
+  - `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=1` in the launch environment is not a hard blocker, but it weakens the normal Claude Code system prompt CurDX-Flow expects.
+  - Provider-specific model IDs in `ANTHROPIC_DEFAULT_*_MODEL` or `ANTHROPIC_CUSTOM_MODEL_OPTION` can disable feature detection for effort and thinking unless the matching `_SUPPORTED_CAPABILITIES` env var is declared.
+  - In CI / `claude -p` runs that depend on marketplace plugins, missing `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` (or a seeded plugin cache via `CLAUDE_CODE_PLUGIN_SEED_DIR`) can leave plugins unavailable on the first turn.
+  - Prefer `claude --bare -p` for CI / scripted runs so hooks, skills, plugins, MCP discovery, auto memory, and `CLAUDE.md` do not vary by machine; add `--plugin-dir`, `--settings`, and `--mcp-config` explicitly when needed.
+  - Do not depend on interactive `/curdx-flow:*` slash commands in `claude -p`; scripted runs should ask for the desired outcome directly.
+  - `settings.json` does not accept `effortLevel: "max"`; official docs reserve `max` for session-only `/effort` (or `CLAUDE_CODE_EFFORT_LEVEL`), so do not commit it to shared project settings.
+  - `enabledPlugins` entries set to `false` for `curdx-flow@curdx-flow-marketplace` or required companion plugins override user-level installs in that project.
+
+## Browser and UI Verification
+
+For UI-facing acceptance criteria, code inspection and DOM unit tests are not sufficient evidence. Use `chrome-devtools` MCP when available to drive the real browser, capture screenshots, list console messages, and inspect network requests. If the MCP is unavailable, mark UI-facing acceptance criteria as unverified instead of silently passing them.
+
+
+## Reality Verification Contract
+
+For fix/debug/regression specs, green tests alone do not prove the user-visible problem was fixed. The workflow must preserve a BEFORE/AFTER evidence trail:
+
+1. BEFORE: record the original reproduction command, observed failure output, and timestamp in `.progress.md` before changing code.
+2. FIX: change the smallest root cause and run the task's Verify command.
+3. AFTER: rerun the original reproduction command and compare output against BEFORE.
+4. COMPLETE: write `Verified: Issue resolved` only when the original failure is gone.
+
+Planner duties:
+- Add a `VF` task for fix/debug specs unless `STATE.md` has an explicit D-NN waiver.
+- Treat missing `VF` coverage as a coverage-audit gap.
+
+Executor duties:
+- Do not mark `VF` complete unless `.progress.md` has the BEFORE/AFTER comparison.
+- Use the same reproduction command for AFTER unless a documented D-NN explains why the command changed.
+
+Verifier duties:
+- Mark fix/debug specs `PARTIAL` when BEFORE/AFTER evidence is missing, even if the normal test suite is green.
+
+## Task Split Contract
+
+When a task is too broad, under-specified, or unsafe to complete surgically, the executor must stop rather than expand scope. It returns `TASK_FAILED` with a split proposal containing at most 3 replacement tasks, each with `Do`, `Files`, `Done when`, `Verify`, and `Commit` fields.
+
+The coordinator or planner owns updates to `tasks.md`. An executor must not create new tasks and execute them in the same turn.
+
+## Failure Recovery Contract
+
+Execution failure recovery is ledger-first:
+
+- Default `manual` recovery blocks progress past `TASK_FAILED`; retry the first unchecked task after root-cause analysis.
+- `fix-task` recovery may create one targeted `[FIX <task_id>]` task immediately after the failed task, but only before execution resumes.
+- `.state.json` `execute_state.fix_task_map` records attempts, generated fix task ids, and the last error per original task.
+- `max_fix_tasks_per_original` is a hard ceiling, not a suggestion.
+
+Generated fix tasks must include `Do`, `Files`, `Done when`, `Verify`, and `Commit`. A recovery task that cannot name a verification command is not actionable and should stop for user input rather than guessing.
+
+## Stop-Hook Recovery Contract
+
+The stop-hook strategy must never trust one source of completion by itself:
+
+- `.state.json` tracks execution cursor and phase.
+- `tasks.md` is the task ledger; unchecked tasks mean work remains.
+- `ALL_TASKS_COMPLETE` is a signal, not proof.
+
+Completion requires both completed state and zero unchecked tasks. If they disagree, continue `tasks.md`'s unchecked tasks and do not add new tasks. When Claude Code sends `stop_hook_active=true`, allow stop to prevent recursive stop-hook loops; resume from persisted state on the next turn.
+
+## Status / Cancel Contract
+
+`/curdx-flow:status` is read-only. It must compare both machine state (`.state.json`) and human task ledger (`tasks.md`) before reporting health. If they disagree, report `NEEDS_ATTENTION` and give one concrete recovery command.
+
+`/curdx-flow:cancel` is non-destructive by default. It cancels execution state while preserving spec artifacts, progress, reports, and project-level `.flow` files. Deleting a spec requires both `--delete-spec` and `--yes`.
+
+If state JSON is corrupt, preserve it by renaming to `.state.json.corrupt.<timestamp>` rather than deleting it. Recovery commands should prefer `/curdx-flow:status` followed by `/curdx-flow:implement --strategy=subagent`.
+
+## Test Quality Contract
+
+Tests used as FR/AC evidence must exercise real behavior. Mock-only tests are not proof of implementation.
+
+Blocking evidence problems:
+- The test only asserts mock/spies were called.
+- The real module/function under test is not invoked.
+- The test is skipped, assertion-free, or would pass with an empty implementation.
+- Mock setup overwhelms behavioral assertions and no integration/e2e backup exists.
+- Stateful mocks are not cleaned up between tests.
+
+Mocks are acceptable for boundaries (network, payment provider, clock/randomness) when the assertion still verifies production logic. If a requirement is backed only by weak tests, `/curdx-flow:verify` and `/curdx-flow:review` must not return full PASS.

package/knowledge/epic-decomposition.md

@@ -250,7 +250,7 @@ Week 5-6: Spec 4 (refund) + Spec 5 (query)
    /curdx-flow:review
      ↓
 5. All sub-specs done → Epic complete
-6. /curdx-flow:retro (Phase 6+) for Epic-level retrospective
+6. Record an epic-level retrospective in `.flow/_epics/<name>/epic.md`
 ```
 
 ---