@curdx/flow 2.2.0 → 2.2.4

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

@@ -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)
@@ -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

@@ -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)

package/knowledge/review-feedback-intake.md

@@ -0,0 +1,57 @@
+# Review Feedback Intake — Verify Before Changing
+
+CurDX-Flow treats review feedback as technical input, not orders to blindly implement. The goal is to fix real issues while avoiding scope creep, regressions, and performative agreement.
+
+## Intake Pattern
+
+For each review item:
+
+1. **Read** the full finding, including severity, evidence, and suggested fix.
+2. **Restate** the technical requirement in one sentence.
+3. **Verify** against the codebase/spec:
+   - Is the finding true at the referenced path/line?
+   - Does it violate an FR, AC, AD, gate, test, or user decision?
+   - Does the suggested fix break existing behavior or platform constraints?
+4. **Classify**:
+   - `BLOCKER`: correctness, security, missing requirement, failing verify, broken CI.
+   - `IMPORTANT`: maintainability or test gap that should be fixed before ship.
+   - `SUGGESTION`: non-blocking improvement or preference.
+   - `PUSHBACK`: technically wrong, violates YAGNI, conflicts with D-NN, or lacks evidence.
+5. **Act one item at a time**:
+   - Fix blockers first.
+   - Run the smallest relevant verification after each fix.
+   - Record pushback with evidence instead of silently ignoring it.
+
+## Required Artifact
+
+When review produces any nontrivial feedback, append a section to `.flow/specs/<active>/.progress.md`:
+
+```markdown
+## Review Feedback Intake YYYY-MM-DD
+
+| Item | Source | Classification | Decision | Evidence | Follow-up |
+|---|---|---|---|---|---|
+| R-01 | review-report.md#... | BLOCKER | fix | `npm test` fails AC-2.1 | Task 4.4 |
+| R-02 | review-report.md#... | PUSHBACK | defer | D-07 says no CSV export | none |
+```
+
+## Pushback Rules
+
+Push back when the feedback:
+
+- Adds unused features or speculative architecture.
+- Conflicts with explicit user decisions (`D-NN`).
+- Breaks compatibility that the current code intentionally preserves.
+- Is unsupported by evidence and cannot be reproduced.
+- Optimizes style while leaving spec compliance unresolved.
+
+Pushback must be technical: cite code, tests, specs, or decisions. Do not use emotional language.
+
+## Fix Loop
+
+1. Intake review items.
+2. Convert accepted blockers/important issues into tasks or direct fixes.
+3. Run targeted verification per item.
+4. Re-run `/curdx-flow:verify` when behavior changed.
+5. Re-run `/curdx-flow:review` until blockers are gone.
+

package/knowledge/two-stage-review.md

@@ -111,13 +111,20 @@ Stage 2 applies all enabled Gates (from `.flow/config.json`):
 
 - All 4 sources (FR / AD / Research / Decisions) covered?
 
-#### 2.5 (enterprise) Adversarial review (adversarial-review-gate)
+#### 2.5 Test quality (test-quality-gate)
+
+- Do tests used as FR/AC evidence exercise real behavior, not only mocks/spies?
+- Are skipped/assertion-free tests excluded from evidence?
+- Are mock-heavy tests backed by integration/e2e coverage or a documented boundary rationale?
+- Are stateful mocks cleaned up between tests?
+
+#### 2.6 (enterprise) Adversarial review (adversarial-review-gate)
 
 - Every applicable category examined (N/A documented for the rest)?
 - Findings proportional to real issues (zero is OK with a proof-of-checking report)?
 - Each finding has evidence + recommendation?
 
-#### 2.6 (enterprise) Edge cases (edge-case-gate)
+#### 2.7 (enterprise) Edge cases (edge-case-gate)
 
 - Each applicable edge-case category addressed (N/A noted for the rest)?
 - Gap list has priorities?
@@ -168,9 +175,15 @@ When the review turns up issues, the typical flow:
   ↓
 4. /curdx-flow:review re-review
   ↓
-5. Until APPROVED → /curdx-flow:ship
+5. Until APPROVED → hand off with review-report.md + atomic commits
 ```
 
+Before implementing review feedback, apply `@${CLAUDE_PLUGIN_ROOT}/knowledge/review-feedback-intake.md`:
+- Verify each finding against code/spec reality.
+- Classify as `BLOCKER`, `IMPORTANT`, `SUGGESTION`, or `PUSHBACK`.
+- Fix accepted items one at a time with targeted verification.
+- Record technical pushback in `.progress.md` instead of silently ignoring feedback.
+
 ---
 
 ## Failure Modes of Two Stages
@@ -219,15 +232,15 @@ Some reviewers list 50 minor improvements — the user can't process.
      ↓                     ↓
      ↓              review-report.md
      ↓
-(optional) /curdx-flow:verify --strict  →  adversarial review + edge cases
+(optional) /curdx-flow:review --adversarial --edge-case
                     ↓
                     adversarial-review.md
                     edge-cases.md
      ↓
-/curdx-flow:ship  →  PR (Phase 6+)
+Ready for human PR/release handoff with verification + review evidence
 ```
 
-Verify is "did we implement the right thing", Review is "is the implementation good", Audit is "what else could be better".
+Verify is "did we implement the right thing", Review is "is the implementation good", Audit is "what else could be better". CurdX-Flow currently stops at evidence-backed handoff; do not reference non-existent ship/land commands.
 
 ---
 

package/knowledge/wave-execution.md

@@ -12,6 +12,12 @@
 
 A wave is **a consecutive run of `[P]`-marked tasks**. Within a wave, run in parallel; across waves, run serially.
 
+Hard limits:
+- Max 5 tasks per wave (`max_parallel` ceiling). More than 5 tasks must be split by a `[VERIFY]` checkpoint or a serial boundary.
+- Every task in a wave owns a disjoint `Files` set.
+- Shared config/barrel/registry files are serial by default: `package.json`, lockfiles, `tsconfig.*`, `index.ts`, router registries, migration manifests, generated schema registries.
+- Read-after-write is a conflict even when file paths differ: if task B imports, tests, or configures output from task A, B must run in a later wave.
+
 ```
 tasks.md:
   1.1 [P] create auth directory
@@ -82,9 +88,13 @@ def analyze_waves(tasks):
 def has_file_conflict(task, wave):
     """Do task's Files intersect any wave task's Files?"""
     task_files = set(task.files)
+    if touches_shared_serial_surface(task_files):
+        return True
     for other in wave:
         if task_files & set(other.files):
             return True
+        if has_read_after_write_dependency(task, other):
+            return True
     return False
 ```
 
@@ -92,6 +102,7 @@ Rules:
 - Two `[P]` tasks editing the same file → conflict, must split into different waves
 - Two `[P]` tasks creating different files → OK
 - One reads what another writes → **conflict** (reads aren't guaranteed to see latest)
+- More than 5 `[P]` tasks in one consecutive run → split the wave before dispatch
 
 ---
 
@@ -335,13 +346,17 @@ Progress: Wave 2/5 (60%)
   "execution": {
     "strategy": "wave",
     "max_parallel": 5,
-    "wave_fail_policy": "continue-on-single | stop-on-any"
+    "wave_fail_policy": "continue-on-single | stop-on-any",
+    "recovery_mode": "manual | fix-task",
+    "max_fix_tasks_per_original": 2
   }
 }
 ```
 
 - `max_parallel`: maximum parallel tasks per wave (default 5, to avoid API rate limits)
 - `wave_fail_policy`: default behavior on single task failure
+- `recovery_mode`: whether a failed wave task blocks for manual retry or creates a targeted `[FIX <task_id>]` task before retry
+- `max_fix_tasks_per_original`: maximum fix tasks generated for one original task
 
 ---
 

package/output-styles/curdx-evidence-first.md

@@ -0,0 +1,34 @@
+---
+name: CurdX Evidence-First
+description: Concise, engineering-focused replies with explicit validation status, assumptions, and next actions.
+keep-coding-instructions: true
+---
+
+# CurdX Evidence-First
+
+You are still Claude Code. Keep the default coding workflow, safety rules,
+tool usage behavior, and verification discipline.
+
+## Response priorities
+
+1. Lead with the concrete outcome or current state.
+2. State validation status explicitly:
+   - `Validated` when you actually ran checks and they passed
+   - `Unvalidated` when you did not run checks yet
+   - `Blocked` when validation could not be completed
+3. Separate observed facts from assumptions or proposals.
+4. Keep answers concise and operational; avoid filler and cheerleading.
+5. When work is incomplete, state the next highest-value action plainly.
+
+## Completion discipline
+
+- Never imply something is done without evidence.
+- If tests, builds, browser checks, or docs validation were not run, say so directly.
+- If you are making a best-effort inference, label it as an inference.
+- When relevant, point to the exact file paths or commands that support the claim.
+
+## Formatting
+
+- Use short section headers only when they improve scanability.
+- Prefer short bullet lists over long prose.
+- Match the user's language.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.2.0",
+  "version": "2.2.4",
   "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {
@@ -20,9 +20,11 @@
     "hooks/",
     "knowledge/",
     "agent-preamble/",
+    "output-styles/",
     "templates/",
     "schemas/",
     "skills/",
+    "settings.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -48,5 +50,9 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "ajv": "^8.18.0",
+    "yaml": "^2.8.3"
   }
 }

package/schemas/agent-frontmatter.schema.json

@@ -54,13 +54,6 @@
     "isolation": {
       "type": "string",
       "enum": ["worktree"]
-    },
-    "color": {
-      "type": "string",
-      "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"]
-    },
-    "initialPrompt": {
-      "type": "string"
     }
   }
 }

package/schemas/config.schema.json

@@ -40,6 +40,19 @@
           "type": "string",
           "enum": ["continue-on-single", "stop-on-any"],
           "default": "continue-on-single"
+        },
+        "recovery_mode": {
+          "type": "string",
+          "enum": ["manual", "fix-task"],
+          "default": "manual",
+          "description": "How /curdx-flow:implement handles TASK_FAILED during execution. manual blocks for retry; fix-task inserts targeted [FIX <task>] tasks before retrying."
+        },
+        "max_fix_tasks_per_original": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5,
+          "default": 2,
+          "description": "Maximum generated [FIX <task>] tasks allowed for a single original task when recovery_mode is fix-task."
         }
       }
     },
@@ -109,6 +122,7 @@
         "karpathy-gate",
         "verification-gate",
         "tdd-gate",
+        "test-quality-gate",
         "coverage-audit-gate",
         "adversarial-review-gate",
         "edge-case-gate",