@curdx/flow 2.0.0-beta.5 → 2.0.0-beta.7

package/commands/implement.md

@@ -330,7 +330,7 @@ Prerequisites:
 
 ## Step 6: Progress Feedback
 
-Every 5 tasks or every wave, print status:
+At each wave boundary (or periodically during long linear runs), print status:
 
 ```
 ═════ Progress ═════

package/commands/review.md

@@ -16,8 +16,8 @@ Distinct from `/curdx-flow:verify`:
 | Flag | Default | Purpose |
 |------|---------|---------|
 | `--stage=<1\|2\|both>` | `both` | Stage 1 = spec compliance only. Stage 2 = code quality only. `both` = sequential. |
-| `--adversarial` | off | Add an adversarial review pass (6 dimensions × 2 sequential-thinking rounds). Zero-findings forbidden. |
-| `--edge-case` | off | Add edge-case hunting across the 7 categories. Produces a test-gap checklist. |
+| `--adversarial` | off | Add an adversarial review pass across applicable categories (zero findings requires proof-of-checking, not fabrication). |
+| `--edge-case` | off | Add edge-case hunting across applicable categories. Produces a test-gap checklist. |
 
 ## Preflight
 
@@ -65,7 +65,7 @@ Output: Stage-2 section of the report.
 ## Optional: adversarial review
 
 If `--adversarial`:
-Dispatch `flow-adversary`. It runs 6 dimensions × 2 rounds of `sequential-thinking`:
+Dispatch `flow-adversary`. It scans the applicable categories (Architecture / Implementation / Testing / Security / Maintainability / UX — skip N/A with reason) using `sequential-thinking` proportional to the residual uncertainty, probing:
 1. What's missing?
 2. What's overengineered?
 3. What would break first in production?
@@ -73,12 +73,12 @@ Dispatch `flow-adversary`. It runs 6 dimensions × 2 rounds of `sequential-think
 5. What decision locks us out of a future option?
 6. What would a skeptical reviewer reject?
 
-**Zero findings are forbidden** — if the agent reports "all good", re-dispatch with stronger skepticism. Per `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`.
+**Zero findings requires proof-of-checking, not fabrication** — honest "clean" verdicts are fine if the agent lists what it examined. Per `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`.
 
 ## Optional: edge-case hunting
 
 If `--edge-case`:
-Dispatch `flow-edge-hunter` across the 7 categories:
+Dispatch `flow-edge-hunter` across the applicable categories (skip N/A with one-line reason):
 1. Boundary values (0, MAX, empty, one-over-limit)
 2. Concurrency / race conditions
 3. Network failure / partial failure

package/commands/spec.md

@@ -82,7 +82,7 @@ Output: `requirements.md` with user stories (US-NN), acceptance criteria (AC-N.N
 
 ### design → `flow-architect`
 Inputs: `research.md` + `requirements.md`.
-Output: `design.md` with architecture decisions (AD-NN), component boundaries, data models, error-path design, mermaid diagrams. Must use `sequential-thinking` MCP (≥8 thoughts).
+Output: `design.md` with architecture decisions (AD-NN), component boundaries, data models, error-path design, mermaid diagrams (when they clarify). Uses `sequential-thinking` MCP proportional to the genuine tradeoff surface.
 
 ### tasks → `flow-planner`
 Inputs: all three prior files + `.flow/PROJECT.md` tech stack.

package/gates/adversarial-review-gate.md

@@ -33,19 +33,19 @@ A reviewer agent's output of "everything looks fine, no issues found" is an **in
 - "Looks good" is usually confirmation bias (the agent only checked the obvious)
 - AI tends to please the user ("great job!") — fight this tendency
 
-**Forced actions**:
-1. If the agent outputs "no issues", automatically trigger a second round
-2. The second round requires the agent to perform deeper analysis via sequential-thinking
-3. If both rounds yield no findings, the agent must **prove** it checked:
-   - List the dimensions examined (at least 5)
-   - For each dimension, give the specific code/file locations inspected
-   - Provide counterfactual hypotheses of "what it would look like if there were a problem"
+**Forced actions when the agent reports "no issues"**:
+1. Automatically trigger a second round framed as "what would a senior skeptic reject in this PR?"
+2. If both rounds still honestly yield no findings, the agent must emit a **proof-of-checking report**:
+   - Every category it examined (with "N/A" for categories that don't apply)
+   - For each examined category, the specific code/file locations inspected
+   - Counterfactual hypotheses of "what this would look like if there were a problem" and why that signature is absent
+3. Fabricating findings to avoid the proof-of-checking step is a violation of L3 red line #2 (fact-driven). Better to emit "clean verdict with proof" than invent issues.
 
 ---
 
-### Rule 2: Findings in at Least 3 Categories
+### Rule 2: Coverage proportional to feature scope
 
-A complete adversarial review must cover (find issues in at least 3 of these categories):
+A complete adversarial review covers every category that applies to the feature, marks the rest as N/A with reason. Number of findings per category is proportional to real issues, not a quota:
 
 1. **Architecture layer**: Are decisions sound? Future-extensible? Lock-in risks?
 2. **Implementation layer**: Code quality? Error handling? Performance?
@@ -86,22 +86,22 @@ Not allowed:
 Input: object under review (code range / spec / PR diff)
   ↓
 Round 1 (agent self-analysis):
-  - Use sequential-thinking ≥ 6 rounds
-  - Scan all 6 categories
+  - Use sequential-thinking proportional to the surface being probed
+  - Scan each applicable category; mark N/A ones with reason
   - Output findings list
   ↓
 Decision:
-  - Findings ≥ 3? → output report
-  - Findings < 3? → force Round 2
+  - Any real findings? → output report with findings
+  - Zero findings after honest Round 1? → force Round 2 framed as skeptic
   ↓
 Round 2 (deep analysis):
-  - sequential-thinking for another 6 rounds
+  - sequential-thinking proportional to residual uncertainty
   - Focus on "seemingly no issues" parts (trust but verify)
-  - May introduce external perspectives (read issues from similar projects)
+  - Optionally introduce external perspectives (read issues from similar projects)
   ↓
 Decision:
-  - Still < 3? → agent must explicitly prove it checked
-  - Otherwise → output report
+  - Still zero findings? → agent must emit proof-of-checking report (NOT invent findings)
+  - Findings exist? → output report
   ↓
 Output: review-report.md
 ```
@@ -190,10 +190,10 @@ Fix loop:
 
 ## Failure Recovery
 
-If after 2 rounds there are still < 3 findings:
+If after Round 2 the honest verdict is still zero findings, emit a proof-of-checking report (do NOT fabricate to hit a quota — there is no quota):
 
 ```markdown
-## Adversarial Review — Insufficient Findings
+## Adversarial Review — Proof of Checking (zero findings)
 
 I have examined the following dimensions across 2 rounds of analysis:
 

package/gates/devex-gate.md

@@ -195,12 +195,12 @@ Reading these test names = reading API behavior documentation.
 
 ### Agent Automatic
 
-When `flow-ux-designer` / `flow-reviewer` applies this gate, use sequential-thinking ≥ 4 rounds to scan the 8 dimensions.
+When `flow-ux-designer` / `flow-reviewer` applies this gate, use sequential-thinking proportional to the complexity of the codebase being scanned.
 
 ### Human Review
 
 Attach a DevEx checklist at PR time:
-- [ ] Clear naming (reviewed at least 3 times)
+- [ ] Clear naming (re-read until obvious to a new maintainer)
 - [ ] Critical comments exist
 - [ ] Consistent structure
 - [ ] Actionable error messages
@@ -210,7 +210,7 @@ Attach a DevEx checklist at PR time:
 
 ## Scoring
 
-Each dimension 0-10 points:
+Score each **applicable** dimension 0-10 (N/A dimensions are excluded from the total):
 
 ```
 10 = best practice
@@ -220,8 +220,7 @@ Each dimension 0-10 points:
 0  = serious issue
 ```
 
-Total 40+ / 80 = pass (warning, non-blocking).
-Total < 40 = blocked, improvement required.
+Emit the per-dimension scores with evidence. The gate itself does not block on a numeric threshold; it surfaces the weaknesses for the user (or the reviewing agent) to decide whether any of them rise to a blocker. A single 0/10 on a material dimension is a blocker regardless of the total.
 
 ---
 

package/gates/edge-case-gate.md

@@ -104,7 +104,7 @@ Q4. If no test, what test should be added to cover it?
 Input: object under review (function / component / API) + requirements + tests
   ↓
 For each category (1-7):
-  1. Use sequential-thinking to list at least 3 possible edge scenarios
+  1. Use sequential-thinking to list every plausible edge scenario for this category — stop when you've covered the real risk surface, don't pad to a quota, don't fabricate scenarios that won't occur in production
   2. Check whether each scenario has corresponding coverage in tests
   3. Add uncovered ones to the "gap list"
   ↓

package/knowledge/execution-strategies.md

@@ -223,13 +223,14 @@ return "linear"
 
 ## Failure Handling (common to all strategies)
 
-`flow-executor` agent's 5-round retry mechanism:
+`flow-executor` agent's retry ladder — each step escalates only when the prior is honestly exhausted, not on a fixed count:
 
 ```
-Rounds 1-2: agent retries autonomously (edit code, rerun Verify)
-Round 3: sequential-thinking root-cause analysis ≥ 5 rounds
-Round 4: read related source + trace data flow
-Round 5: report TASK_FAILED
+Step A: autonomous retry (edit + rerun Verify) — only for shallow failures
+Step B: sequential-thinking root-cause analysis proportional to the hypothesis space
+Step C: read related source + trace data flow
+Step D: if ≥3 retries fail with no new hypothesis, stop and challenge the architecture (see preamble L3)
+Step E: report TASK_FAILED
 ```
 
 ### Extra protections for Stop-Hook strategy

package/knowledge/spec-driven-development.md

@@ -57,7 +57,7 @@ What's wasted isn't code — it's context tokens and decision fatigue from churn
 **Key behaviors** (flow-researcher agent):
 1. Read `.flow/PROJECT.md` and `.flow/CONTEXT.md` to understand project background
 2. Call `mcp__claude_mem__search` to retrieve relevant historical experience
-3. Use sequential-thinking for 5-8 rounds of problem understanding
+3. Use sequential-thinking proportional to the unknowns (1 thought for a trivial prototype, many for a novel domain)
 4. Scan the codebase for reusable modules
 5. Use `mcp__context7__*` to look up latest docs for relevant libraries
 6. When necessary, WebSearch for the latest technical trends
@@ -99,11 +99,12 @@ What's wasted isn't code — it's context tokens and decision fatigue from churn
 
 **Key behaviors** (flow-architect agent):
 1. Read `research.md` + `requirements.md`
-2. **Must use sequential-thinking for at least 8 rounds**:
-   - Rounds 1-2: constraints
-   - Rounds 3-5: comparison of options A/B
-   - Rounds 6-7: selection + trade-offs
-   - Round 8: rebut yourself
+2. **Use sequential-thinking proportional to the tradeoff surface** — the phases below are orientation, not a quota:
+   - Constraints (from NFR / tech stack)
+   - Option comparison (only when alternatives genuinely compete)
+   - Selection + accepted tradeoff
+   - Self-rebuttal
+   A well-known stack pick may finish in 1 thought; a distributed-system design may run many. Do not pad.
 3. Assign an `AD-NN` ID to each architectural decision
 4. Draw a data flow diagram (mermaid)
 5. Define component interfaces + error paths
@@ -125,7 +126,7 @@ What's wasted isn't code — it's context tokens and decision fatigue from churn
 3. Each task has 5 fields: `Do` / `Files` / `Done-when` / `Verify` / `Commit`
 4. **Multi-source coverage audit**: for each FR / AC / AD / decision, confirm there is a covering task (no omissions)
 5. Mark `[P]` (parallel-safe) and `[VERIFY]` (checkpoint)
-6. Simple decomposition doesn't need sequential-thinking, but reflect on coverage every 5 tasks
+6. Simple decomposition doesn't need sequential-thinking; run a coverage audit at the end (every FR/AC/AD has a task)
 
 **Deliverable**: `tasks.md`
 

package/knowledge/two-stage-review.md

@@ -113,17 +113,18 @@ Stage 2 applies all enabled Gates (from `.flow/config.json`):
 
 #### 2.5 (enterprise) Adversarial review (adversarial-review-gate)
 
-- ≥ 3 categories of issues found?
+- 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)
 
-- Did all 7 major categories pass?
+- Each applicable edge-case category addressed (N/A noted for the rest)?
 - Gap list has priorities?
 
 ### Stage 2 verdict
 
-- **EXCELLENT**: all enabled Gates pass, adversarial findings < 3 (high-quality code)
+- **EXCELLENT**: all enabled Gates pass, adversarial review clean or only low-severity findings
 - **GOOD**: all enabled Gates pass, but some warnings
 - **NEEDS_IMPROVEMENT**: Gate violations (blocking)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.5",
+  "version": "2.0.0-beta.7",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {

package/templates/config.json.tmpl

@@ -32,7 +32,7 @@
   "specs": {
     "directories": ["./.flow/specs"],
     "default_task_size": "fine",
-    "_task_size_options": "fine (40-60 tasks) | coarse (10-20 tasks)"
+    "_task_size_hint": "as-needed decomposition (no fixed count) — see agents/flow-planner.md"
   },
 
   "addons": {

package/templates/design.md.tmpl

@@ -9,155 +9,75 @@ depends_on: requirements.md
 
 # Technical Design: {{SPEC_NAME}}
 
-> Conclusions from the flow-architect agent using at least 8 rounds of `sequential-thinking` reasoning.
-> This document freezes the technical choices. Subsequent tasks / implementation strictly follow this design.
+> Conclusions from flow-architect. Sequential-thinking is invoked proportional to the genuine tradeoff surface — the chain lives in the thinking tool, not this document.
+>
+> **Fill only the sections that carry real design information for this feature.** Well-known stack assemblies legitimately compress to a stack list + data model + a few real ADs. Delete sections whose honest answer would be "N/A" or "standard for this stack". A forced 13-section template is the bloat pattern this is designed to prevent.
 
 ---
 
 ## Design Overview (one paragraph)
 
-<!-- One-sentence summary of the architecture -->
+<!-- One sentence summary of the approach. -->
 
 ## Architecture Decisions
 
-<!-- Each major decision gets an ID and is written to the decisions array in .flow/STATE.md -->
+<!-- Each real decision gets an AD-NN. If a decision is "obvious, no alternative worth listing," use one line and move on. -->
 
 ### AD-01: ...
-- **Decision**: Use X instead of Y
+- **Decision**: Use X
 - **Rationale**: ...
-- **Trade-off**: Accepted [downside] in exchange for [upside]
-- **sequentialthinking rounds**: rounds 3-5
-
-### AD-02: ...
-
-## System Architecture Diagram
-
-```mermaid
-flowchart TB
-  <!-- actual data flow generated by flow-architect -->
-  User[User] --> API[API Gateway]
-  API --> Auth[Auth Service]
-  Auth --> DB[(Database)]
-```
+- **Trade-off**: ... (omit if there is no genuine tradeoff)
 
 ## Component Design
 
-<!-- Each component is independently testable. Interfaces are explicit. -->
+<!-- Each component: responsibility, input type, output type, dependencies, error path. Skip if the feature is a single module with no internal boundaries worth naming. -->
 
-### Component: {{COMP_NAME_1}}
+### Component: {{COMP_NAME}}
 - **Responsibility**: ...
-- **Input**:
-  ```ts
-  interface Input {
-    field: Type;
-  }
-  ```
-- **Output**:
-  ```ts
-  interface Output {
-    field: Type;
-  }
-  ```
-- **Dependencies**: Component X, Library Y
-- **Errors**:
-  - `ErrorCode.X` — when ... happens
-  - `ErrorCode.Y` — when ... happens
-
-### Component: {{COMP_NAME_2}}
-<!-- ... -->
-
-## Data Model
-
-<!-- Database schema / data structures -->
-
-### Entity: ...
-```sql
-CREATE TABLE ... (
-  id UUID PRIMARY KEY,
-  ...
-);
-```
+- **Input**: `interface Input { ... }`
+- **Output**: `interface Output { ... }`
+- **Dependencies**: ...
+- **Errors**: ...
 
-### Or TypeScript types:
-```ts
-interface Entity {
-  id: string;
-  ...
-}
-```
+## Data Model (if the feature touches persistence or structured data)
 
-## State Machine (if applicable)
+<!-- SQL schema, TypeScript types, or API payload shape. Delete if the feature has no meaningful data shape. -->
+
+## Architecture Diagram (include only when it clarifies; prose often suffices)
 
 ```mermaid
-stateDiagram-v2
-  [*] --> Pending
-  Pending --> Active: approve
-  Pending --> Rejected: reject
-  Active --> Completed: finish
+flowchart TB
+  ...
 ```
 
-## Error Path Design
+## State Machine (include only if the feature has non-trivial state transitions)
 
-<!-- Full flow on failure -->
+## Error Path Design (include when error behavior is not obvious)
 
-| Scenario | Upstream Behavior | System Response | User-visible |
-|-----|--------|---------|---------|
-| DB connection lost | retry 3 times | return 503 | "Temporarily unavailable, retry in 1 minute" |
-| Rate limit hit | none | return 429 | "Too many requests, retry in 60 seconds" |
+| Scenario | System Response | User-visible |
+|-----|---------|---------|
+| ... | ... | ... |
 
-## API Contract
-
-<!-- If this is an API project -->
+## API Contract (include only if this feature exposes or changes an API)
 
 ```yaml
-POST /api/v1/...
-Request:
-  body:
-    field: string
-Response:
-  200:
-    body:
-      field: string
-  400:
-    body:
-      error: string
+...
 ```
 
-## Test Matrix
+## Test Matrix (brief — one line per layer)
 
 | Layer | Coverage | Tool |
 |---|-----|------|
-| Unit | All pure functions | vitest |
-| Integration | Between components | vitest + supertest |
-| E2E | Complete user flows | playwright / chrome-devtools MCP |
-
-### Key Test Scenarios
-1. Happy path: ...
-2. Edge case 1: ...
-3. Error recovery: ...
-
-## Suggested Implementation Order
-
-<!-- Reference for decomposition in the tasks phase -->
-
-1. Build skeleton first (Component A → empty implementation)
-2. Then wire up the real logic (core logic of Component A)
-3. Connect DB (persistence for Component A)
-4. Then do Component B ...
-
-## Risks and Mitigations
+| ... | ... | ... |
 
-| Risk | Level | Mitigation |
-|-----|-----|------|
-| ... | medium | ... |
+## Risks and Mitigations (include only if risks exist that aren't obvious from the ADs)
 
 ## Defer to Implementation
 
-<!-- Decisions not worth spending time on in the design phase -->
+<!-- Decisions explicitly deferred to when the executor writes the code. -->
 
-- Logging library choice → reuse project's existing one during implementation
-- Caching strategy → no caching initially, adjust based on data after launch
+- ...
 
 ---
 
-_Generated by flow-architect agent on {{CREATED_DATE}}. After user reviews and approves AD-01~N, proceed to the tasks phase._
+_Generated by flow-architect on {{CREATED_DATE}}._

package/templates/requirements.md.tmpl

@@ -9,86 +9,68 @@ depends_on: research.md
 
 # Requirements Spec: {{SPEC_NAME}}
 
-> **Recommended direction from the research phase**: {{RESEARCH_CONCLUSION}}
+> **Recommended direction from research**: {{RESEARCH_CONCLUSION}}
 >
-> This phase: translate "technically feasible" into "concrete behaviors users benefit from".
+> **Fill only the sections that carry real information for this feature.** Delete or collapse any section whose honest content would be "N/A" or "same as usual". Padding sections with "TBD" is worse than omitting them.
 
 ---
 
 ## User Stories
 
-<!-- Each story follows the format: As X, I want Y, so that Z -->
-
 ### US-01: ...
-**As** [user role],
-**I want** [capability],
-**so that** [business value].
+**As** [user role], **I want** [capability], **so that** [business value].
 
 **Acceptance criteria**:
 - AC-1.1: [verifiable behavior]
-- AC-1.2: [verifiable behavior]
-- AC-1.3: [edge case handling]
+- AC-1.2: ...
 
-### US-02: ...
-<!-- ... -->
+<!-- Add more US-NN blocks only if the feature genuinely has multiple independent user flows. -->
 
 ## Functional Requirements
 
-<!-- FR-NN format. Each FR must be a verifiable statement of "the system must X". -->
-
 - **FR-01**: The system must ...
-- **FR-02**: The system must ...
-- **FR-03**: ...
+- **FR-02**: ...
 
 ## Non-Functional Requirements
 
-### Performance
-- **NFR-P-01**: [e.g. P95 response time < 200ms]
-- **NFR-P-02**: ...
+<!--
+Include ONLY the NFR categories that this feature is actually constrained by.
+For a small internal CRUD feature, "Performance / Security / Maintainability / Compatibility" as a four-bucket grid is usually padding.
+Delete categories that have no real requirement, or collapse into one line: "NFR: standard for this stack, no special constraints."
+-->
 
-### Security
-- **NFR-S-01**: ...
-- **NFR-S-02**: ...
+### Performance (if applicable)
+- **NFR-P-01**: ...
 
-### Maintainability
-- **NFR-M-01**: ...
+### Security (if applicable)
+- **NFR-S-01**: ...
 
-### Compatibility
-- **NFR-C-01**: ...
+<!-- Delete Maintainability / Compatibility sections unless they carry a real constraint. -->
 
 ## Edge Cases and Error Handling
 
-<!-- Must be explicit: what happens on failure? how are abnormal inputs handled? -->
+<!-- Include rows only for scenarios that actually apply. -->
 
 | Scenario | Expected behavior |
 |-----|--------|
-| Network disconnected | ... |
-| Database exception | ... |
-| Invalid input | ... |
-| Concurrent conflict | ... |
+| ... | ... |
 
 ## Out of Scope
 
-<!-- Karpathy principle 2: simplicity first. Explicitly list "not this time" to prevent scope creep. -->
-
-- ✗ Feature A — deferred to the next version
-- ✗ Feature B — out of budget
-- ✗ Feature C — needs its own spec
+- ✗ ...
 
-## Success Metrics
+## Success Metrics (if the feature has measurable outcomes)
 
-<!-- Must be quantifiable -->
+<!-- Delete this section for internal tools or refactors with no user-visible metric. -->
 
-- Metric 1: [e.g. user signup completion rate > 80%]
-- Metric 2: [e.g. complaint rate < 1%]
+- Metric 1: ...
 
 ## Open Questions
 
-<!-- Questions that need user answers -->
+<!-- Include only if there are genuinely unresolved questions. Delete when empty. -->
 
-1. **Question 1**: ...
-2. **Question 2**: ...
+1. ...
 
 ---
 
-_Generated by flow-product-designer agent on {{CREATED_DATE}}. After user review, proceed to the design phase._
+_Generated by flow-product-designer on {{CREATED_DATE}}._