@curdx/flow 1.1.4 → 1.1.6

package/gates/devex-gate.md

@@ -0,0 +1,255 @@
+---
+gate: devex-gate
+category: enterprise-mode
+severity: warning
+depends_on: []
+---
+
+# DevEx Gate — Developer Experience Review
+
+> Optional in Enterprise mode. Reviews whether code is friendly to **the next maintainer**.
+
+---
+
+## Trigger Timing
+
+- When `/curdx-flow:plan-dx` runs (design phase)
+- When `/curdx-flow:review --devex` runs (code phase)
+- Enabled by default in open-source / multi-person collaboration scenarios
+
+---
+
+## Core Question
+
+**"Six months from now, can I (or my colleague) quickly take over this code?"**
+
+Not considering this → code becomes legacy → maintenance cost grows exponentially.
+
+---
+
+## 8 Dimensions
+
+### DX-01: Clear Naming
+
+Naming = the most important documentation.
+
+❌ Bad:
+```typescript
+function doStuff(x, y) { ... }
+const d = new Date()
+let flag = true
+```
+
+✓ Good:
+```typescript
+function validateEmailFormat(email: string): boolean { ... }
+const currentTimestamp = new Date()
+let isAuthenticationPending = true
+```
+
+**Checks**:
+- Abbreviations (`usr`, `pwd`, `addr`) should be expanded (unless domain-standard like `API`, `URL`)
+- Booleans use `is/has/can/should` prefix
+- Functions start with verbs
+- Variables use nouns
+- Single letters only in loops/lambdas (`i`, `x`)
+
+---
+
+### DX-02: Intent Comments
+
+Comments explain **why**, not **what**.
+
+❌ Bad (comment adds no value):
+```typescript
+// get the user
+const user = await getUser(id)
+
+// increment i by 1
+i++
+```
+
+✓ Good (comment explains why):
+```typescript
+// bcrypt.compare has fixed execution time; run it even when the user does not exist to prevent timing attacks
+const hash = user?.passwordHash ?? FAKE_HASH
+await bcrypt.compare(inputPwd, hash)
+```
+
+**Checks**:
+- Are there low-value comments (`// set x to 1`)?
+- Are there magic numbers / odd practices lacking explanation?
+- Do public APIs have doc comments?
+
+---
+
+### DX-03: Discoverable File Structure
+
+```
+src/auth/
+  ├── index.ts        ← export entry
+  ├── login.ts        ← business logic
+  ├── login.test.ts   ← tests (colocated)
+  ├── types.ts        ← types
+  └── __mocks__/      ← mocks (if any)
+```
+
+**Checks**:
+- Are new files placed in the right location (follow existing patterns)?
+- Naming conventions are consistent (don't mix `login.ts` with `LoginService.ts`)
+- Depth does not exceed 4 levels
+
+---
+
+### DX-04: Useful Error Messages
+
+❌ Bad:
+```
+Error: Failed
+Error: Validation error
+```
+
+✓ Good:
+```
+Error: Failed to send email to user@example.com (SMTP 554 - rejected)
+Error: email must match pattern /^[^@]+@[^@]+\.[^@]+$/, got ""
+```
+
+**Checks**:
+- Error messages include **where it went wrong**, **what went wrong**, and **what the user/developer can do**
+
+---
+
+### DX-05: Easy Setup
+
+After a newcomer clones the repo:
+
+```bash
+git clone ...
+cd project
+<single command to run>
+```
+
+Should start with one command (`npm install && npm run dev`).
+
+**Checks**:
+- README has a "Getting Started" section
+- No hidden dependencies ("must install PostgreSQL and create a user first")
+- Or a single docker-compose command
+
+---
+
+### DX-06: Clear Types
+
+TypeScript / Python with types:
+```typescript
+// ❌ any hell
+function process(data: any): any { ... }
+
+// ✓ explicit types
+function processUser(user: User): ProcessedUser { ... }
+```
+
+**Checks**:
+- `any` usage (the less the better)
+- `unknown` for boundary inputs
+- Interfaces / Types have meaningful names
+
+---
+
+### DX-07: Tests as Documentation
+
+```typescript
+describe("login endpoint", () => {
+  test("rejects empty email with 400", async () => { ... })
+  test("rejects invalid format email with 400", async () => { ... })
+  test("rejects unknown email with 401", async () => { ... })
+  test("rejects wrong password with 401", async () => { ... })
+  test("accepts valid credentials with 200 + JWT", async () => { ... })
+})
+```
+
+Reading these test names = reading API behavior documentation.
+
+**Checks**:
+- Test names describe **behavior** ("returns 400 for empty email"), not implementation ("calls validateEmail")
+- Tests cover happy + edge + error paths
+- Each test is independent (does not depend on order)
+
+---
+
+### DX-08: Fast Dev Loop
+
+- Is build time acceptable? (< 30s to change one line)
+- Is test time acceptable? (< 60s to run relevant tests)
+- Does HMR / live reload work?
+
+**Checks**:
+- tsc --watch / bundler configuration is reasonable
+- Test runner supports --watch
+- Non-critical tests are optional (e.g. E2E in CI, not on every commit)
+
+---
+
+## Checking Methods
+
+### Agent Automatic
+
+When `flow-ux-designer` / `flow-reviewer` applies this gate, use sequential-thinking ≥ 4 rounds to scan the 8 dimensions.
+
+### Human Review
+
+Attach a DevEx checklist at PR time:
+- [ ] Clear naming (reviewed at least 3 times)
+- [ ] Critical comments exist
+- [ ] Consistent structure
+- [ ] Actionable error messages
+- [ ] Tests as docs
+
+---
+
+## Scoring
+
+Each dimension 0-10 points:
+
+```
+10 = best practice
+8  = good
+5  = pass (production-usable)
+3  = needs improvement
+0  = serious issue
+```
+
+Total 40+ / 80 = pass (warning, non-blocking).
+Total < 40 = blocked, improvement required.
+
+---
+
+## Output Format
+
+```markdown
+## DevEx Gate Report
+
+Scores:
+  DX-01 naming:      7/10 — 2 abbreviations (usr, pwd)
+  DX-02 comments:    8/10 — magic number 42 not explained
+  DX-03 structure:   9/10 — consistent
+  DX-04 errors:      5/10 — 2 uninformative "Failed"
+  DX-05 Setup:       8/10 — README complete
+  DX-06 types:       7/10 — 3 instances of any
+  DX-07 tests:       6/10 — test names too implementation-detail
+  DX-08 dev loop:    9/10 — HMR works well
+
+Total: 59/80 (pass)
+
+Improvement recommendations:
+1. Replace usr/pwd with user/password
+2. Comment magic number 42 (reason for timeout=42s)
+3. Change error message "Failed" → specific reason
+4. Several any usages can be typed explicitly
+5. Rewrite test names with "behavior" descriptions
+```
+
+---
+
+_source: years of development experience + gstack's DX review philosophy._

package/gates/edge-case-gate.md

@@ -0,0 +1,194 @@
+---
+gate: edge-case-gate
+category: enterprise-mode
+severity: warning
+depends_on: []
+---
+
+# Edge Case Gate — Edge Case Hunter
+
+> Derived from BMAD-METHOD's "Edge Case Hunter".
+>
+> **Core**: specifically hunts for **non-happy-path** scenarios. User stories describe the happy path; the real world is full of edge cases.
+
+---
+
+## Trigger Timing
+
+- After the requirements phase ends (to supplement edge conditions)
+- After the design phase (to check error-path completeness)
+- After tests are written (to check whether only the happy path is covered)
+- Explicitly requested by /curdx-flow:audit
+
+---
+
+## 7 Categories
+
+Systematically inspect the object under review (function / component / API):
+
+### 1. Boundary Values
+
+- 0, -1, 1
+- INT_MAX, INT_MIN
+- Empty array `[]`, single-element array `[x]`, large array `[x...10000]`
+- Empty string `""`, single character `"a"`, extra-long string
+- First element / last element / middle element
+
+### 2. Nullish
+
+- `null`
+- `undefined`
+- Empty object `{}`
+- Object with missing fields (key does not exist in JSON)
+- Whether default parameters are actually applied
+
+### 3. Concurrency
+
+- Two requests arriving simultaneously
+- Write conflicts (optimistic / pessimistic lock)
+- Read-modify-write race
+- Cache invalidation timing
+- Distributed locks
+
+### 4. Error Recovery
+
+- Network outage → retry strategy?
+- DB unavailable → circuit breaker?
+- Disk full → degrade?
+- Permission revoked → graceful exit?
+- Dependency service 500 → fallback?
+
+### 5. Security
+
+- SQL/Command/XSS injection
+- Unauthorized access (use A's token to access B's resource)
+- Sensitive data leakage (logs / error messages / response)
+- Rate limiting bypass
+- CSRF / session fixation
+- Timing attack
+
+### 6. Internationalization (I18n)
+
+- Unicode (emoji, CJK, combining characters)
+- RTL (Arabic)
+- Time zones (UTC vs local, DST jumps)
+- Number formats (decimal point vs comma)
+- Sorting (locale-aware collation)
+
+### 7. Performance
+
+- N+1 queries
+- Slow queries (missing indexes)
+- Large responses (M/G scale)
+- Memory leaks (event listeners, closures)
+- Deadlocks / long-running transactions
+
+---
+
+## Required Question Checklist
+
+For each category, the agent must answer (via sequential-thinking):
+
+```
+Q1. What inputs/scenarios will this feature encounter for [category]?
+Q2. If the input is [extreme value], what will the current implementation do?
+Q3. Is there a test covering this scenario?
+Q4. If no test, what test should be added to cover it?
+```
+
+---
+
+## Execution Flow
+
+```
+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
+  2. Check whether each scenario has corresponding coverage in tests
+  3. Add uncovered ones to the "gap list"
+  ↓
+Output: edge-cases.md
+```
+
+---
+
+## Output Format
+
+```markdown
+## Edge Case Hunt Report
+
+Object under review: src/auth/login.ts + login.test.ts
+
+## Covered (✓)
+
+- Valid email + password → 200 + JWT
+- Invalid email format → 400
+- Non-existent user → 401
+- Wrong password → 401
+
+## Gap List (✗)
+
+### 1. Boundary Values
+- ✗ Extra-long email (>255) may cause DB errors
+  - Recommendation: test("rejects email >255 chars", ...)
+- ✗ Password containing NUL character (bcrypt has historical issue)
+  - Recommendation: test("handles NUL in password safely", ...)
+
+### 2. Nullish
+- ✗ email is empty string vs undefined
+  - Currently: both return 400 (via schema validation), but no test
+  - Recommendation: explicit test for both cases
+
+### 3. Concurrency
+- ✗ Same user with 2 concurrent logins
+  - Risk: token generation uniqueness?
+  - Recommendation: test("handles concurrent logins", async () => Promise.all([...]))
+
+### 4. Error Recovery
+- ✗ bcrypt.compare() timeout
+  - Currently: no timeout, will wait indefinitely
+  - Recommendation: add Promise.race + timeout test
+
+### 5. Security
+- ⚠ Error message leak (user enumeration)
+  - Already reported in adversarial review
+- ✗ Timing attack: response time difference between email existing vs not
+  - Recommendation: run bcrypt.compare() in both cases, test response time difference < 10ms
+
+### 6. Internationalization
+- ✗ Unicode email (RFC 6531)
+  - Currently: regex may reject legitimate Unicode emails
+  - Recommendation: test("accepts unicode email like ñ@example.com")
+
+### 7. Performance
+- ⚠ bcrypt cost 12 response time (~100ms) not tested
+  - Recommendation: benchmark test, expect < 200ms P99
+
+## Summary
+
+Covered: 4 scenarios
+Gaps: 9 scenarios
+Priority ranking: 1 (concurrency) > 4 (timeout) > 7 (timing attack) > others
+
+Fix recommendations:
+- High priority: add 4 tests (concurrency, timeout, timing attack, unicode email)
+- Medium priority: add edge-case-tests.test.ts to unify edge-case test management
+```
+
+---
+
+## Difference from Adversarial Review
+
+| Dimension | adversarial | edge-case |
+|------|-------------|-----------|
+| Goal | find **any** issue | find **edge-case** issues |
+| Scope | all dimensions (architecture/implementation/...) | inputs / scenarios |
+| Style | "attacker perspective" | "extreme case search" |
+| Output | issue list + fix recommendations | gap list + test recommendations |
+
+The two are complementary. Enterprise mode recommends enabling both.
+
+---
+
+_Source: BMAD-METHOD's edge-case-hunter._

package/gates/karpathy-gate.md

@@ -0,0 +1,130 @@
+---
+gate: karpathy-gate
+category: always-on
+severity: blocking
+depends_on: []
+---
+
+# Karpathy Gate — Thinking Baseline Check
+
+> **Always enabled**. This is the code-level enforcement of L1. Violations block immediately.
+
+This gate maps to Karpathy's 4 principles. All flow-executor and flow-reviewer agents must enforce it.
+
+---
+
+## Trigger Timing
+
+- Before code is written (pre-check)
+- Before commit (re-check)
+- When `/curdx-flow:review` runs (full review)
+
+---
+
+## 4 Checks
+
+### G1. Think Before Coding
+
+**Violation patterns**:
+- ✗ Code embodies unstated assumptions (e.g. default encoding, default pagination count, default permission scope)
+- ✗ User goal has multiple interpretations but the agent picked one without saying so
+- ✗ Business-relevant changes (data export, permission modification) were not confirmed with the user
+
+**Check method**:
+1. Read commit message + change scope
+2. Look in `.progress.md` for "assumption:" entries
+3. If a key assumption is not explicit, mark as violation
+
+**Auto-fix**: impossible. Report to user.
+
+---
+
+### G2. Simplicity First
+
+**Violation patterns**:
+- ✗ Introduces an abstraction with only one usage point (Strategy / Factory / Observer used in one place)
+- ✗ Code goes beyond task requirements (user asked for `A`, implemented `A` + `B` + `C`)
+- ✗ Over-defensive (error handling for cases that obviously won't happen)
+- ✗ Premature parameterization (hooks left "in case we need it later")
+- ✗ Tests changed to "always pass" to accommodate implementation
+
+**Check method**:
+1. Cross-reference with the FR list in requirements.md
+2. Check whether the commit's diff scope exceeds the FR description
+3. Scan new classes / interfaces / factories; only reasonable if used in > 1 place
+
+**Auto-fix**:
+- Dispatch flow-adversary agent to review, flag redundant code
+- Auto-deletion not allowed (may have reasons); list items and let the user decide
+
+---
+
+### G3. Surgical Changes
+
+**Violation patterns**:
+- ✗ Task only modifies `auth/login.ts`, but the commit contains changes in `utils/`
+- ✗ Task is to add a feature, but the commit contains "incidental" refactoring
+- ✗ Changed comments, quotes, or indentation unrelated to the task
+- ✗ Deleted pre-existing (not self-caused) "dead code"
+
+**Check method**:
+1. Read the Files field in tasks.md
+2. Compare to the commit's changed files
+3. If there is a difference (commit changed files not in Files), mark as violation
+
+**Auto-fix**:
+- Dispatch flow-executor to extract the "incidental changes" into a separate commit
+- Or roll back and redo
+
+---
+
+### G4. Goal-Driven Execution
+
+**Violation patterns**:
+- ✗ Commit message contains "should", "probably", "seems", "fixed" without verification evidence
+- ✗ The `Verify` field is skipped (claiming complete without running)
+- ✗ Tests were deleted instead of fixed (turning green into gray)
+- ✗ Claims "done" but AC-X.Y still cannot be verified via curl
+
+**Check method**:
+1. Grep commit messages for forbidden words
+2. Check .progress.md for Verify output records
+3. For each AC, confirm that an automated verification path can be found
+
+**Auto-fix**:
+- Trigger flow-verifier to run reverse verification
+- If AC is not met, send back for rework (dispatch flow-executor to fix)
+
+---
+
+## Violation Levels
+
+| Violation | Level | Block? |
+|------|------|-------|
+| G1 (unstated assumption) | Medium | warning, require user confirmation |
+| G2 (over-engineering) | Medium | warning + suggest simplification |
+| G3 (surgical failure) | High | **block**, must split the commit |
+| G4 (no evidence) | High | **block**, must run verification |
+
+---
+
+## Output Format
+
+```markdown
+## Karpathy Gate Check Result
+
+[G1] Think Before Coding: ✓ pass (3 explicit assumption records)
+[G2] Simplicity First:    ⚠ warning — src/auth/login-strategy.ts has a single-use Strategy pattern
+[G3] Surgical Changes:    ✗ violated — commit abc123 contains accidental changes in utils/
+[G4] Goal-Driven:         ✓ pass (all ACs have verification records)
+
+Blockers: 1
+Warnings: 1
+
+Fix recommendations:
+  G3: git reset HEAD~1, split commit abc123 into 2 atomic commits
+```
+
+---
+
+_Applied to: all agent preamble.md has this built in; this file contains the detailed rules for concrete checks._