@curdx/flow 2.1.0 → 2.2.3

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

package/knowledge/execution-strategies.md

@@ -65,8 +65,8 @@ The main agent reads tasks.md and **dispatches a fresh flow-executor subagent pe
 
 ```
 main agent
-  ├─ Task() → subagent(task 1) → TASK_COMPLETE
-  ├─ Task() → subagent(task 2) → TASK_COMPLETE
+  ├─ Agent() → subagent(task 1) → TASK_COMPLETE
+  ├─ Agent() → subagent(task 2) → TASK_COMPLETE
   └─ ...
    (each subagent has isolated context)
 ```
@@ -86,7 +86,7 @@ main agent
 ### Disadvantages
 - Dispatch overhead (each subagent reloads context)
 - Cross-task info sharing goes through files (.progress.md)
-- Not parallel (a single Task call is serial)
+- Not parallel (a single Agent call is serial)
 
 ### Enable
 ```bash
@@ -106,6 +106,8 @@ Or (default):
 - Main agent executes 1 task → ends naturally (Stop event)
 - `stop-watcher.sh` hook fires
 - Checks whether `.state.json` still has unfinished tasks
+- Cross-checks `tasks.md`; completion requires zero unchecked tasks as well as completed state
+- Allows stop when Claude Code reports `stop_hook_active=true` to avoid recursive stop-hook loops
 - If yes, it outputs `{"decision": "block", "reason": "continue task N"}`
 - Claude Code treats `decision=block` as "issue another response round", and the main agent automatically continues with the next task
 - Repeats until `TASK_FAILED` or `ALL_TASKS_COMPLETE`
@@ -119,6 +121,8 @@ main agent → task N → Stop → stop-watcher.sh
                    no tasks?     → allow stop
 ```
 
+Safety invariant: `ALL_TASKS_COMPLETE` is advisory, not authoritative. If `tasks.md` still has unchecked tasks, the hook blocks and tells the agent to continue those tasks instead of advancing to verify.
+
 ### When to use
 - ✓ Long task chains (20+)
 - ✓ Unattended execution (overnight automation)
@@ -149,7 +153,7 @@ main agent → task N → Stop → stop-watcher.sh
 ### How it works
 - Tasks in tasks.md marked `[P]` are "parallel-safe"
 - The main agent identifies consecutive `[P]` tasks as one wave
-- **In a single message**, it dispatches multiple Task() tool calls simultaneously
+- **In a single message**, it dispatches multiple Agent() tool calls simultaneously
 - All tasks within a wave run in parallel
 - Waves run serially relative to each other
 
@@ -175,7 +179,7 @@ main agent
 ### Disadvantages
 - Parallel conflict risk (e.g., two tasks editing the same file)
 - Requires flow-planner to have tagged `[P]` (Phase 1-generated tasks.md should)
-- Main agent manages many Task calls, high context pressure
+- Main agent manages many Agent calls, high context pressure
 
 ### Enable
 ```bash
@@ -219,6 +223,11 @@ return "linear"
 - `"auto"` — use the decision tree above (default)
 - Other concrete strategies
 
+Execution failure recovery is explicit:
+- `recovery_mode: "manual"` — default; never skip a failed task, retry from the first unchecked task after root-cause analysis.
+- `recovery_mode: "fix-task"` — insert a targeted `[FIX <task_id>]` task before retrying the original failure.
+- `max_fix_tasks_per_original` — hard ceiling for generated fix tasks per original task.
+
 ---
 
 ## Failure Handling (common to all strategies)
@@ -233,6 +242,19 @@ Step D: if ≥3 retries fail with no new hypothesis, stop and challenge the arch
 Step E: report TASK_FAILED
 ```
 
+If fix-task recovery is enabled, the coordinator turns a `TASK_FAILED` into a ledgered repair task before doing more work:
+
+```markdown
+- [ ] **<task_id>.<n>** [FIX <task_id>] Fix: <root cause>
+  - **Do**: <repair steps>
+  - **Files**: <same files as the original task or narrower>
+  - **Done when**: Original failure no longer reproduces
+  - **Verify**: <original verify command or tighter reproduction>
+  - **Commit**: `fix(<scope>): address <failure>`
+```
+
+The fix task must be written to `tasks.md` and tracked in `.state.json` `execute_state.fix_task_map` before it is executed. Executors do not invent and execute recovery work in the same turn.
+
 ### Extra protections for Stop-Hook strategy
 - 3 consecutive TASK_FAILED → stop-watcher.sh halts the loop
 - 10 consecutive Stop triggers with no progress → halt (anti-deadlock)
@@ -272,7 +294,7 @@ If you really must switch, do it manually:
 - Next `/curdx-flow:start <name>` (or `/curdx-flow:start --resume`) resumes from `task_index`
 
 ### Snapshots
-`/curdx-flow:save <label>` saves a checkpoint (Phase 5+ rollout).
+Claude Code checkpoints plus `.flow/specs/<name>/.progress.md` are the current recovery surface. Use `/curdx-flow:status` to inspect recoverability.
 
 ---
 

package/knowledge/planning-reviews.md

@@ -149,7 +149,7 @@ Essentially runs `flow-architect` again — but this time not to generate the de
 
 A new agent `flow-devex-reviewer`, or reuse `flow-reviewer` by passing in the devex-gate.
 
-Phase 5 implementation: reuse `flow-reviewer` + `@gates/devex-gate.md`.
+Phase 5 implementation: reuse `flow-reviewer` + `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md`.
 
 ---
 
@@ -160,7 +160,7 @@ Phase 5 implementation: reuse `flow-reviewer` + `@gates/devex-gate.md`.
 ```
 
 Workflow:
-1. In parallel (single-message multi-Task), dispatch 4 reviews
+1. In parallel (single-message multi-Agent), dispatch 4 reviews
 2. Wait for all to return
 3. Merge findings, sort by priority
 4. Present to the user for decision
@@ -201,8 +201,8 @@ But for production-grade features, running through is strongly recommended.
 
 ## Difference from /curdx-flow:review
 
-- **/curdx-flow:review** (Phase 3): review **after code is finished** — Stage 1 compliance + Stage 2 quality
-- **/curdx-flow:plan-*** (Phase 5): review **before code starts** — targets design.md
+- **/curdx-flow:review**: review **after code is finished** — Stage 1 compliance + Stage 2 quality
+- **/curdx-flow:spec --review**: review **before code starts** — targets design.md
 
 The two don't overlap. Plan Review prevents "doing the wrong thing", Code Review ensures "the thing was done right".
 

package/knowledge/poc-first-workflow.md

@@ -1,6 +1,6 @@
 # POC-First Workflow — 5 Phases
 
-> Step-by-step methodology for the execution phase: get it running → clean up → add tests → pass quality gates → ship PR.
+> Step-by-step methodology for the execution phase: get it running → clean up → add tests → pass quality gates → hand off review-ready evidence.
 >
 > Agents reference this file via `@${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md`.
 
@@ -15,7 +15,7 @@ Phase 1: Make It Work    → end-to-end running; hard-coding allowed
 Phase 2: Refactoring     → clean up structure, behavior unchanged
 Phase 3: Testing (TDD)   → red-green-yellow loop to backfill tests
 Phase 4: Quality Gates   → tsc + lint + test all green
-Phase 5: PR Lifecycle    → open PR, address review, merge
+Phase 5: Evidence Handoff → verify, review, prepare PR/release evidence
 ```
 
 ---
@@ -153,10 +153,10 @@ Each item produces **0 errors, 0 warnings** (warnings are not tolerated since th
 
 ---
 
-## Phase 5: PR Lifecycle
+## Phase 5: Evidence Handoff
 
 ### Goal
-Code merged to main, feature shipped.
+Feature is verified, reviewed, and ready for a human PR/release decision.
 
 ### Steps
 
@@ -165,7 +165,7 @@ Code merged to main, feature shipped.
    - Commit message follows conventional format
    - Squash if there are too many WIP commits
 
-2. **Create PR**
+2. **Prepare PR/release evidence**
    - Clear title (< 70 chars)
    - Summary 3-5 lines covering why & what
    - Include a test plan (checklist)
@@ -180,9 +180,9 @@ Code merged to main, feature shipped.
    - Wait for CI green after every push
    - Fix red immediately — don't pile up
 
-5. **Merge**
+5. **Hand off**
    - Squash vs merge vs rebase: per project convention
-   - Deploy: if a `/curdx-flow:land` command exists, use it
+   - Use the host project's normal PR, merge, and release process
 
 ### Pitfalls
 - **PR too large** → reviewer gives up. Split anything > 500 changed lines.
@@ -198,7 +198,7 @@ Code merged to main, feature shipped.
 - Skip Refactoring / Testing / Quality Gates
 
 ### Fast mode (one-off task)
-- Only Phase 1 + Phase 5 (PR means ship)
+- Only Phase 1 + Phase 5 (handoff evidence stays lightweight)
 - Suitable for: fixing a typo, adding a log, changing a constant
 
 ### Standard mode (default)