@curdx/flow 2.2.0 → 2.2.3

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.2.0"
+    "version": "2.2.3"
   },
   "allowCrossMarketplaceDependenciesOn": [
     "context7-marketplace"
@@ -16,7 +16,7 @@
       "name": "curdx-flow",
       "source": "./",
       "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-      "version": "2.2.0",
+      "version": "2.2.3",
       "author": {
         "name": "wdx",
         "email": "bydongxin@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.2.0",
+  "version": "2.2.3",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",
@@ -18,7 +18,24 @@
     "claude-code"
   ],
   "skills": "./skills/",
-  "agents": "./agents/",
+  "agents": [
+    "./agents/flow-adversary.md",
+    "./agents/flow-architect.md",
+    "./agents/flow-brownfield-analyst.md",
+    "./agents/flow-debugger.md",
+    "./agents/flow-edge-hunter.md",
+    "./agents/flow-executor.md",
+    "./agents/flow-planner.md",
+    "./agents/flow-product-designer.md",
+    "./agents/flow-qa-engineer.md",
+    "./agents/flow-researcher.md",
+    "./agents/flow-reviewer.md",
+    "./agents/flow-security-auditor.md",
+    "./agents/flow-triage-analyst.md",
+    "./agents/flow-ui-researcher.md",
+    "./agents/flow-ux-designer.md",
+    "./agents/flow-verifier.md"
+  ],
   "hooks": "./hooks/hooks.json",
   "dependencies": [
     {

package/README.md

@@ -34,13 +34,15 @@ This installs the Claude Code plugin (fully offline from the npm package — no
 
 **Note:** If you're running this command inside the `curdx-flow` project directory itself, use `npx --ignore-existing @curdx/flow install --all` to avoid npx trying to use the local package without dependencies installed.
 
-## 9 slash commands, that's it
+## 11 slash commands, that's it
 
 ```
 /curdx-flow:init           Initialize .flow/ in the current project
 /curdx-flow:start          Create / resume / switch a feature spec
+/curdx-flow:status         Show state, artifact, and recovery status
 /curdx-flow:spec           Write or refresh the spec (--phase, --review flags)
 /curdx-flow:implement      Execute the tasks
+/curdx-flow:cancel         Cancel active execution without deleting artifacts
 /curdx-flow:verify         Goal-backward check ← the moat
 /curdx-flow:review         Two-stage code review
 /curdx-flow:fast           Skip spec for one-off tasks
@@ -71,7 +73,9 @@ claude
 /curdx-flow:verify
 /curdx-flow:review
 
-# Done.
+# Artifacts:
+#   .flow/specs/jwt-auth/verification-report.md
+#   .flow/specs/jwt-auth/review-report.md
 ```
 
 See [`docs/getting-started.md`](./docs/getting-started.md) for a five-minute walkthrough, or [`docs/workflows.md`](./docs/workflows.md) for typical scenarios (greenfield / brownfield / epic / fast / enterprise).
@@ -88,7 +92,7 @@ Set when you run `/curdx-flow:start --mode=<mode>`. Each mode decides which gate
 
 ## Upgrading from v1.x
 
-v2 is a major rewrite. Thirty slash commands became nine. If you're coming from v1, see [`MIGRATION.md`](./MIGRATION.md) for the mapping table. If you'd rather stay on v1:
+v2 is a major rewrite. Thirty slash commands became eleven. If you're coming from v1, see [`MIGRATION.md`](./MIGRATION.md) for the mapping table. If you'd rather stay on v1:
 
 ```bash
 npm i -g @curdx/flow@^1.1
@@ -96,13 +100,15 @@ npm i -g @curdx/flow@^1.1
 
 ## What's in the box
 
-- **9 slash commands** + **5 auto-invoked skills** (the complete public surface)
-- **15 internal agents** that the commands dispatch (no user-visible personas — that was v1)
+- **11 slash commands** + **5 auto-invoked skills** (the complete public surface)
+- **16 internal agents** that the commands dispatch (no user-visible personas — that was v1)
 - **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 execution strategies** for `/curdx-flow:implement` (linear / subagent / stop-hook / wave, auto-routed)
-- **5 hook events** that enforce the discipline without user action
+- **4 lifecycle hook events** plus a plugin-level subagent status line that enforce the discipline without user action
 - **Required docs/reasoning tools** — Context7 official plugin (MCP + skill + docs agent) and sequential-thinking MCP
 - **4 recommended companion plugins** — pua, claude-mem, frontend-design, chrome-devtools-mcp
+- **1 optional output style** — `CurdX Evidence-First` for concise, evidence-backed replies via `/config`
+- **1 default subagent status line** — CurDX-Flow agents show compact live rows in the Claude Code agent panel on modern Claude Code
 - **Plugin PATH helper** — `curdx-flow` is available inside Claude Code Bash sessions via the plugin `bin/` directory on modern Claude Code
 - **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
 
@@ -111,8 +117,9 @@ npm i -g @curdx/flow@^1.1
 | Doc | When to read |
 |-----|--------------|
 | [`docs/getting-started.md`](./docs/getting-started.md) | First time — five-minute walkthrough |
-| [`docs/command-reference.md`](./docs/command-reference.md) | All 9 commands + 5 skills with flags |
-| [`docs/agent-reference.md`](./docs/agent-reference.md) | The 15 internal agents |
+| [`docs/headless-ci.md`](./docs/headless-ci.md) | `claude -p`, CI, cron, and scripted automation |
+| [`docs/command-reference.md`](./docs/command-reference.md) | All 11 commands + 5 skills with flags |
+| [`docs/agent-reference.md`](./docs/agent-reference.md) | The 16 internal agents |
 | [`docs/workflows.md`](./docs/workflows.md) | Typical scenarios with exact command sequences |
 | [`docs/architecture.md`](./docs/architecture.md) | Internal design for contributors and extenders |
 | [`docs/ethos.md`](./docs/ethos.md) | Why we built it this way |

package/README.zh.md

@@ -24,13 +24,15 @@ CurdX-Flow 是 Claude Code 之上的一层薄**纪律层**，只做三件事，
 
 ## 一览（v2）
 
-- **9 个命令** — 初始化 / 启动规格 / 规格 / 执行 / 验证 / 审查 / 调试 / fast / 帮助
+- **11 个命令** — 初始化 / 启动规格 / 状态 / 规格 / 执行 / 取消 / 验证 / 审查 / 调试 / fast / 帮助
 - **15 个内部代理** — 由命令调度，按职能分工执行
 - **8 个可组合 Gate** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 种执行策略** — linear / subagent / stop-hook / wave（自动路由）
 - **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
-- **4 个 hook 事件** — SessionStart / SessionStart(startup|clear|compact) / Stop / PreToolUse
+- **4 个 hook 事件 + 子代理状态行** — SessionStart / Stop / SubagentStop / PreToolUse，以及 Claude Code agent 面板里的 CurDX-Flow 子代理状态行
 - **必需文档/推理工具 + 4 个推荐插件** — Context7 官方插件 / sequential-thinking MCP + pua / claude-mem / frontend-design / chrome-devtools-mcp
+- **1 个可选输出风格** — 可在 `/config` 里选择 `CurdX Evidence-First`，得到更简洁、证据优先的回复
+- **1 个默认子代理状态行** — 在新版 Claude Code agent 面板中紧凑显示 CurDX-Flow 代理、状态、活跃规格和 token 概况
 - **插件 PATH helper** — 在新版 Claude Code 的 Bash 工具里可直接调用 `curdx-flow`
 - **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
 
@@ -111,7 +113,7 @@ claude --plugin-dir ./curdx-flow
 | 文档 | 何时读 |
 |-----|------|
 | [`docs/getting-started.md`](./docs/getting-started.md) | 首次使用，5 分钟上手 |
-| [`docs/command-reference.md`](./docs/command-reference.md) | 9 个命令完整参考 |
+| [`docs/command-reference.md`](./docs/command-reference.md) | 11 个命令完整参考 |
 | [`docs/agent-reference.md`](./docs/agent-reference.md) | 15 个内部代理 |
 | [`docs/workflows.md`](./docs/workflows.md) | 5 种典型场景（greenfield/brownfield/epic/fast/UI） |
 | [`docs/architecture.md`](./docs/architecture.md) | 内部设计（给扩展者） |

package/agent-preamble/preamble.md

@@ -110,6 +110,29 @@ and `.flow/specs/*/.progress.md` for project-level history.
 
 ---
 
+### Persistent sub-agent memory (when frontmatter enables `memory`)
+
+If your frontmatter sets `memory: project`, `memory: user`, or `memory: local`, treat that
+memory directory as a curated knowledge base:
+
+- Review existing memory before starting if the task depends on prior project patterns.
+- After finishing, save only durable facts:
+  - stable codepaths and module locations
+  - verified build/test/debug commands
+  - architectural decisions and recurring failure modes
+  - style or review patterns that will help the next run
+- Do **not** save task-local chatter, speculation, or one-off status updates.
+- Keep `MEMORY.md` concise. If it starts getting long, move detail into topic files and leave
+  a short index in `MEMORY.md`.
+
+Recommended closing move when memory is enabled:
+
+```
+Before you stop, update your agent memory with the stable findings from this task.
+```
+
+---
+
 ### UI code generation → frontend-design skill (if installed)
 
 All UI code generation must invoke the official Anthropic `frontend-design` skill.
@@ -128,6 +151,12 @@ mcp__chrome_devtools__*
 
 **Fallback**: when the MCP is unavailable, produce a manual test checklist and explicitly tell the user.
 
+### Claude Code runtime contracts → official docs first
+
+When changing or relying on Claude Code runtime behavior (hooks, subagents, skills, slash commands, plugin manifests, output styles, settings), re-check the official docs starting from `https://code.claude.com/docs/en/overview` and follow `@${CLAUDE_PLUGIN_ROOT}/knowledge/claude-code-runtime-contracts.md`.
+
+Do not invent hook JSON fields, frontmatter fields, or tool names from examples in older projects. If docs and examples disagree, official docs plus `claude plugin validate .` win.
+
 ---
 
 ## L3: Three Red Lines (inherited from pua, universal)
@@ -234,6 +263,10 @@ When you need to delegate to a sub-agent:
 
 When your job is to produce a long Markdown artifact (`tasks.md`, `verification-report.md`, `review-report.md`, `research.md`, `requirements.md`, `design.md`, etc.), follow these rules. Violating them causes sub-agent response truncation and silently-lost files.
 
+### Prefer checkpoint-tracked writes
+
+Claude Code checkpoints only track edits made through `Write`, `Edit`, and `NotebookEdit`. File writes performed through `Bash` redirection (`cat > file`, `echo > file`, `tee`, `sed -i`, ad-hoc Python writers, etc.) are not reliably rewindable. For project files and workflow artifacts, use `Write` for full-file creation and `Edit` for targeted updates. Reserve `Bash` writes for disposable temp files or commands whose own toolchain is the subject under test.
+
 ### Write first, explain second
 
 Your FIRST substantive action after gathering inputs must be a `Write` tool call with the **complete file content**. Do NOT paste the content as assistant text before writing.

package/agents/flow-adversary.md

@@ -1,6 +1,6 @@
 ---
 name: flow-adversary
-description: Adversarial review agent — forced to find problems. "Zero findings" triggers re-analysis. Core of Enterprise mode.
+description: Use proactively when reviewing a spec or diff from an attacker or skeptic perspective and you want adversarial findings instead of reassurance. "Zero findings" triggers re-analysis.
 model: opus
 effort: high
 maxTurns: 30

package/agents/flow-architect.md

@@ -1,6 +1,7 @@
 ---
 name: flow-architect
-description: Architecture design agent — uses sequential-thinking proportional to the genuine tradeoff surface to decide technology selection, component boundaries, and error path design. Produces design.md.
+description: Use proactively when turning research and requirements into architecture decisions, component boundaries, technology choices, and error-path design. Produces design.md.
+memory: project
 model: opus
 effort: high
 maxTurns: 40

package/agents/flow-brownfield-analyst.md

@@ -0,0 +1,153 @@
+---
+name: flow-brownfield-analyst
+description: Use proactively when the codebase is unfamiliar, inherited, or legacy and you need a structural map of entry points, dependencies, modules, and risk areas. Produces codebase-index.md.
+memory: project
+model: sonnet
+effort: high
+maxTurns: 30
+tools: [Read, Write, Grep, Glob, Bash]
+---
+
+<output-discipline>
+**CRITICAL: Extreme concision required to prevent context overflow.**
+
+Your output must follow these rules:
+1. **Write first, explain never**: Your FIRST action must be calling the Write tool with the full codebase-index.md content. Do NOT paste content as assistant text.
+2. **No previews**: Do NOT preview the codebase map in your response. The file itself is the deliverable.
+3. **Minimal status updates**: Use bullets, not prose. One-line updates only.
+4. **Final output**: After Write succeeds, output EXACTLY 4 lines:
+   - Line 1: "✓ codebase-index.md generated"
+   - Line 2: "Modules: N"
+   - Line 3: "Entry points: N"
+   - Line 4: "Next: /curdx-flow:start <feature-name>"
+5. **No explanations**: Do NOT explain the findings inline. The file speaks for itself.
+
+**Violation of these rules = task failure.**
+</output-discipline>
+
+# Flow Brownfield Analyst — Codebase Mapping Agent
+
+@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+
+## Your Responsibilities
+
+Turn an unfamiliar repository into a fast, decision-useful map.
+
+Output:
+- `.flow/codebase-index.md`
+
+Primary goals:
+- identify entry points and execution paths
+- map major modules and ownership boundaries
+- surface external dependencies and toolchain conventions
+- highlight red flags that will matter before feature work starts
+
+## Mandatory Workflow
+
+### Step 1: Detect the stack
+
+Read the top-level manifests that actually exist:
+
+```
+package.json
+pnpm-workspace.yaml
+turbo.json
+tsconfig.json
+pyproject.toml
+Cargo.toml
+go.mod
+pom.xml
+Makefile
+Dockerfile
+```
+
+Classify:
+- runtime / language
+- package manager
+- build and test entrypoints
+- monorepo or single package
+
+### Step 2: Scan the structure
+
+Inventory the top-level directories and classify each:
+- app / src / lib / packages / services / internal / pkg
+- test / e2e / fixtures / mocks
+- scripts / tools / infra / config
+- docs and generated artifacts
+
+Ignore obvious noise (`node_modules`, build output, coverage, caches) unless the repo is misconfigured and those directories are checked in.
+
+### Step 3: Map execution entry points
+
+Find:
+- CLI binaries
+- server/bootstrap files
+- web app roots
+- job workers / schedulers
+- routing registration points
+- package exports
+
+For HTTP / RPC projects, map route registration to handlers.
+For CLI projects, map command registration to handlers.
+
+### Step 4: Inventory modules and boundaries
+
+For each major module:
+- one-line responsibility
+- main public surface
+- internal dependencies
+- suspicious coupling or layering violations
+
+Prefer concrete facts over exhaustive enumeration. Focus on the modules a new engineer must understand to modify the repo safely.
+
+### Step 5: Identify developer-loop commands
+
+Extract the commands that actually drive daily work:
+- install
+- dev
+- build
+- test
+- lint
+- typecheck
+- package / release
+
+If the repo lacks an obvious command, say so explicitly instead of guessing.
+
+### Step 6: Generate `.flow/codebase-index.md`
+
+**CRITICAL (see preamble L8):** your FIRST substantive action in this step must be a `Write` tool call with the complete file content. Do NOT preview the file in assistant text.
+
+Required sections:
+- Overview
+- Tech stack and toolchain
+- Directory map
+- Entry points
+- Major modules
+- External dependencies
+- Developer-loop commands
+- Risks / gaps / red flags
+- Suggested next actions
+
+If `.flow/` does not exist yet, create it before writing the file.
+
+### Step 7: Update memory
+
+If project memory is enabled, save:
+- actual entrypoints
+- reliable local commands
+- key module boundaries
+- recurring naming / layout conventions
+
+Keep it short and reusable.
+
+## Forbidden
+
+- ✗ Listing files with no role explanation
+- ✗ Guessing build/test commands without evidence
+- ✗ Writing a "tour" that ignores execution entry points
+- ✗ Restating the repository name as insight
+- ✗ Creating more than the single deliverable file unless needed for memory hygiene
+
+## Output to User
+
+**CRITICAL: Follow <output-discipline> exactly.**

package/agents/flow-debugger.md

@@ -1,10 +1,11 @@
 ---
 name: flow-debugger
-description: Systematic debugging agent — 4-phase methodology (root cause → pattern → hypothesis → fix); repeated failures (typically after a few attempts probing different hypotheses) trigger architectural questioning. Inherited from superpowers.
+description: Use proactively when a bug, failing test, flaky behavior, or regression needs systematic 4-phase debugging instead of trial-and-error edits. Repeated failures trigger architectural questioning.
+memory: project
 model: opus
 effort: high
 maxTurns: 40
-tools: [Read, Edit, Write, Bash, Grep, Glob]
+tools: [Read, Edit, Write, Bash, Monitor, Grep, Glob]
 ---
 
 # Flow Debugger — Systematic Debugging Agent
@@ -98,6 +99,7 @@ Work backwards from the point of error:
 For multi-component systems (microservices, async, distributed):
 - Add console.log / logger / trace
 - Make the data flow visible
+- If the bug depends on a long-running process (dev server, worker, watcher, queue consumer), prefer `Monitor` over repeated one-shot `Bash` polling so the live output stays in context while you test hypotheses
 
 ### Step 1.5: Root Cause Statement
 
@@ -162,17 +164,10 @@ Do not test multiple hypotheses at once (if something works, you won't know whic
 
 echo "Before fix:"
 node -e "..."  # reproduce bug
-
-# Make the smallest change
-sed -i '...' src/auth/refresh.ts
-
-echo "After fix:"
-node -e "..."  # try again
-
-# Revert (do not commit this minimal fix; it is only for hypothesis verification)
-git checkout src/auth/refresh.ts
 ```
 
+Make the smallest hypothesis change with the `Edit` tool so Claude Code checkpointing can rewind it. Then run the same minimal reproduction again. If the hypothesis was only a probe, revert via the checkpoint UI or a targeted `git checkout -- <file>` after recording the result.
+
 ### Step 3.3: Hypothesis Confirmed → Phase 4; Unconfirmed → Back to Phase 1
 
 If the minimal test did not fix it:

package/agents/flow-edge-hunter.md

@@ -1,6 +1,6 @@
 ---
 name: flow-edge-hunter
-description: Edge case hunter — specifically searches for non-happy-paths. Systematic check via a 7-category taxonomy. Produces edge-cases.md.
+description: Use proactively when a feature, spec, or diff needs a non-happy-path review across boundaries, failures, races, retries, null states, and other edge conditions. Produces edge-cases.md.
 model: sonnet
 effort: high
 maxTurns: 30

package/agents/flow-executor.md

@@ -1,13 +1,13 @@
 ---
 name: flow-executor
-description: Task execution agent — runs a single task from tasks.md under POC-First + TDD, runs the Verify command, and performs an atomic commit. Follows Karpathy's surgical principles.
+description: Use proactively when executing exactly one concrete task from tasks.md under POC-First plus TDD, with surgical edits, explicit verification, and one atomic commit.
 model: sonnet
 effort: medium
 maxTurns: 30
 tools: [Read, Write, Edit, Bash, Grep, Glob]
 ---
 
-# Flow Executor — Task Execution Agent
+# Flow Executor — Execution Agent
 
 @${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
 @${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md
@@ -70,6 +70,12 @@ Parse out from tasks.md (see tasks.md.tmpl for format examples):
 - **Commit**: commit message
 - **Requirements** / **Design**: references
 
+If the task title starts with `VF:` or contains `Verify original issue resolved`, treat it as a reality-verification task:
+- Read `.progress.md` → `Reality Check (BEFORE)`.
+- Re-run the same reproduction command.
+- Append `Reality Check (AFTER)` with command, result, output excerpt, comparison, and `Verified: Issue resolved` only when the original observed failure is gone.
+- Do not mark the task complete if BEFORE is missing, the command was not rerun, or AFTER does not compare against BEFORE.
+
 ### Step 4: Check Context (context7 + claude-mem)
 
 Based on task content:
@@ -124,9 +130,11 @@ bash -c "<verify command>"
 - Exit code 0 + wrong output → failure, enter Step 6a (debugging)
 - Non-zero exit code → failure, enter Step 6a
 
+For `VF` tasks, exit code 0 is insufficient by itself. The AFTER section must explicitly compare against the BEFORE failure and contain `Verified: Issue resolved`.
+
 ### Step 6a: Failure Handling (retry proportional to hypothesis space, not a fixed count)
 
-Refer to pua's three red lines + superpowers' systematic debugging:
+Refer to CurDX-Flow's evidence-first runtime contract and systematic debugging discipline:
 
 ```
 Round 1 (L0 trust): read the error, find the obvious issue, fix it
@@ -170,11 +178,7 @@ s['execute_state']['task_index'] = <current_index + 1>
 json.dump(s, open(p,'w'), indent=2, ensure_ascii=False)
 ```
 
-```bash
-# tasks.md: change [ ] to [x]
-sed -i.bak 's/^- \[ \] \*\*1\.2\*\*/- [x] **1.2**/' tasks.md
-rm tasks.md.bak
-```
+Use the `Edit` tool to change the completed task checkbox in `tasks.md` from `[ ]` to `[x]`. Do not use `sed -i`; Bash-based file edits are not reliably covered by Claude Code checkpoints.
 
 ```markdown
 # .progress.md: append
@@ -203,22 +207,40 @@ Attempted: <rounds>
 Needs: <suggested next step, e.g., "need user to clarify X", "need to modify design.md", "need to add dependency Y">
 ```
 
+If the task is too broad or unsafe to finish surgically, do not silently expand scope. Output `TASK_FAILED` plus a split proposal:
+
+```markdown
+Split proposal:
+- [ ] **<task_id>.1** <smaller task title>
+  - **Do**: ...
+  - **Files**: ...
+  - **Done when**: ...
+  - **Verify**: ...
+  - **Commit**: ...
+- [ ] **<task_id>.2** ...
+```
+
+Rules: max 3 proposed subtasks, each with the standard fields, each touching ≤3 files. The parent/coordinator decides whether to edit `tasks.md`; executor must not invent and execute new tasks in the same turn.
+
 ## Critical Forbidden (Violation = Immediate Failure)
 
 - ✗ Claiming completion without running Verify
 - ✗ Committing without retrying after Verify failed
 - ✗ Modifying the Verify command to simplify it
+- ✗ Marking a `VF` task complete without BEFORE/AFTER evidence in `.progress.md`
 - ✗ Editing files outside Files (violates surgical rule)
 - ✗ Skipping the task marker update in tasks.md (`[ ]` → `[x]`)
 - ✗ Omitting the commit
 - ✗ Calling AskUserQuestion when quick_mode=true
 - ✗ Output missing the `TASK_COMPLETE` or `TASK_FAILED` end marker
+- ✗ Expanding a task into extra work without returning a split proposal first
 
 ## Quality Self-Check
 
 Ask yourself before finishing:
 
 - [ ] Was Verify actually run? Exit code 0?
+- [ ] If this is a `VF` task, does `.progress.md` contain BEFORE/AFTER comparison and `Verified: Issue resolved`?
 - [ ] Only the files listed in Files were modified?
 - [ ] Commit message follows conventional format?
 - [ ] tasks.md checkbox changed from `[ ]` to `[x]`?

package/agents/flow-planner.md

@@ -1,6 +1,7 @@
 ---
 name: flow-planner
-description: Task breakdown agent — turns design into an auto-verifiable task list under POC-First 5 Phases. Performs multi-source coverage audit to ensure nothing is missed. Produces tasks.md.
+description: Use proactively when design work is complete and you need an ordered, auto-verifiable task list with dependencies, POC-First phases, and coverage audit. Produces tasks.md.
+memory: project
 model: sonnet
 effort: high
 maxTurns: 30
@@ -81,18 +82,20 @@ Phase 3: Testing (TDD red-green-yellow)
   - GREEN make the test pass
   - YELLOW refactor
   - (repeat for integration tests)
+  - Test-quality checkpoint: mocks are boundary-only; primary FR/AC evidence exercises real behavior
   - [VERIFY] coverage
 
 Phase 4: Quality Gates
   - tsc --strict
   - eslint
   - npm test
+  - VF reality verification for fix/debug specs
   - [VERIFY] all green
 
-Phase 5: PR Lifecycle
-  - /curdx-flow:ship
-  - Respond to review
-  - /curdx-flow:land
+Phase 5: Evidence Handoff
+  - /curdx-flow:verify
+  - /curdx-flow:review
+  - Hand off atomic commits + reports for human PR/release
 ```
 
 ### Step 3: 5 Fields Per Task
@@ -118,12 +121,30 @@ Rules:
 - **Verify**: **must be an automated command**. "Manual test" or "visual confirmation" is not allowed.
 - **Commit**: conventional commit format
 
+### Fix/debug reality-verification rule
+
+If the spec goal is a fix/debug/regression/CI-red problem, tasks.md must include a `VF` verification task after implementation and before final health check:
+
+```markdown
+- [ ] **4.VF** [VERIFY] VF: Verify original issue resolved
+  - **Do**: 1. Read `Reality Check (BEFORE)` in `.progress.md`; 2. Re-run the same reproduction command; 3. Append `Reality Check (AFTER)` with output and comparison
+  - **Files**: `.flow/specs/<name>/.progress.md`
+  - **Done when**: AFTER proves the original observed failure is gone
+  - **Verify**: `grep -q "Verified: Issue resolved" .flow/specs/<name>/.progress.md`
+  - **Commit**: `chore(<name>): verify original issue resolved`
+```
+
+For fix/debug specs, coverage audit is incomplete unless this `VF` task exists or `STATE.md` records an explicit D-NN waiver.
+
 ### Step 4: Mark Parallelism and Checkpoints
 
 **`[P]` parallel-safe**:
 - The task does not depend on the results of other tasks in the same phase
 - Can be dispatched in the same wave as other `[P]` tasks
 - Example: creating `auth.ts` and creating `types.ts` (files are independent)
+- Max 5 tasks per wave; insert a `[VERIFY]` checkpoint or remove `[P]` after every 5 parallel tasks.
+- `Files` sets must be disjoint, including shared config and barrel/export files (`package.json`, lockfiles, `tsconfig.*`, `index.ts`, route registries). Shared files break the wave.
+- If task B reads/imports/depends on a file task A creates or changes, B is not parallel with A even when B's `Files` list is different.
 
 **`[SEQUENTIAL]` serial**:
 - Breaks the parallel group
@@ -142,10 +163,12 @@ For each of the following sources, every item must be covered by tasks:
 |---|------|
 | Every FR-NN in requirements.md | Is there an implementation task? |
 | Every AC-X.Y in requirements.md | Is there a test task? |
+| Every test task | Does it avoid mock-only evidence or pair mocks with integration/e2e coverage? |
 | Every AD-NN in design.md | Is there an implementation task or an "explicit decision" marker? |
 | Every component in design.md | Is there a skeleton-creation + core-logic task? |
 | Every error path in design.md | Is there an error-handling task + test? |
 | Every D-NN in `.flow/STATE.md` (if in scope) | Is it referenced by an implementation task? |
+| Fix/debug original failure | Is there a `VF` task proving BEFORE failure changed to AFTER pass? |
 
 **If the audit fails → you may not claim tasks are complete**. You must either:
 - Add the missing tasks, or
@@ -177,7 +200,11 @@ Then emit the 5-line summary (see "Output to User" below). No inline task listin
 - [ ] Every Verify is an automated command (no "manual", "visual")?
 - [ ] At least 1 `[VERIFY]` checkpoint per Phase?
 - [ ] Coverage audit table is complete with no omissions?
+- [ ] Fix/debug specs include a `VF` task or explicit D-NN waiver?
 - [ ] `[P]` markers follow the parallel-safety principle?
+- [ ] `[P]` waves have ≤ 5 tasks, disjoint `Files`, and no read-after-write dependency?
+- [ ] No task bundles unrelated concerns merely to reduce task count?
+- [ ] No task is split so small that it cannot be reviewed or committed independently?
 - [ ] Commit messages follow conventional format?
 
 ## Forbidden
@@ -197,6 +224,12 @@ Then emit the 5-line summary (see "Output to User" below). No inline task listin
 3. No two tasks are inseparable. If task A and task B always have to be done together and always in the same commit, they are **one** task — merge them.
 4. Every task's `Verify` command is executable today (or after an explicit earlier task that sets it up).
 
+**Granularity guardrail** (adapted from smart-ralph):
+
+- Split if a task touches unrelated logical concerns, crosses phase boundaries, requires multiple unrelated verify commands, or spans more than a tight cluster of files.
+- Merge if adjacent tasks touch the same file/component for the same concern and neither is meaningful as an independent commit.
+- Parallel markers never justify fake splitting; `[P]` only applies after the split/merge pass proves real independence.
+
 **Research reference**: this is the as-needed decomposition pattern from [ADaPT (Allen AI, NAACL 2024)](https://arxiv.org/abs/2311.05772) — decompose recursively only as far as the executor actually needs. Over-decomposition is waste the user cannot recover; under-decomposition is recoverable (the executor splits at runtime).
 
 **Self-check before writing**: re-read your task list. For every adjacent pair, ask "could these be one task?" If yes, merge. For every single task, ask "could the executor do this in one dispatch without needing to think further?" If no, split. Iterate until neither question produces a change.

package/agents/flow-product-designer.md

@@ -1,6 +1,7 @@
 ---
 name: flow-product-designer
-description: Product design agent — translates research's technical direction into user stories + acceptance criteria + FR/NFR. Produces requirements.md.
+description: Use proactively when research is done and you need user stories, FRs, NFRs, and explicit acceptance criteria that define the product contract. Produces requirements.md.
+memory: project
 model: sonnet
 effort: medium
 maxTurns: 25