@curdx/flow 3.0.0 → 3.1.0

package/cli/utils.js

@@ -1,40 +0,0 @@
-/**
- * Shared utilities for curdx-flow CLI.
- *
- * This module is kept as the stable public import surface for existing CLI
- * commands. Implementations live under cli/lib/ so each concern stays small.
- */
-
-export { VERSION } from "./lib/version.js";
-export { color, log } from "./lib/logging.js";
-export { has, resultLastLine, resultOutput, run, runSync } from "./lib/process.js";
-export {
-  confirm,
-  intro,
-  multiSelect,
-  multiselectClack,
-  note,
-  outro,
-  select,
-  spinner,
-  text,
-} from "./lib/prompts.js";
-export { readConfig, writeConfig } from "./lib/config.js";
-export {
-  claudeVersion,
-  findDuplicateMcps,
-  findPluginByRegistryEntry,
-  hasMarketplace,
-  listMcps,
-  listPluginMarketplaces,
-  listPlugins,
-  parseMcpList,
-  parsePluginListJson,
-  readUserMcpConfig,
-} from "./lib/claude.js";
-export {
-  ensureClaudeMemRuntimes,
-  ensureRuntimeInPath,
-  inspectClaudeMemRuntimes,
-  inspectRuntimeInPath,
-} from "./lib/runtime.js";

package/gates/adversarial-review-gate.md

@@ -1,219 +0,0 @@
----
-gate: adversarial-review-gate
-category: enterprise-mode
-severity: warning
-depends_on: []
----
-
-# Adversarial Review Gate
-
-> Derived from BMAD-METHOD's "Adversarial Review Prompts".
->
-> **Core**: The reviewer must find problems. "Zero findings" triggers re-analysis. This forcibly breaks confirmation bias.
-
----
-
-## Trigger Timing
-
-- /curdx-flow:review command
-- Before Phase transitions (requirements → design, design → tasks)
-- Before code merge or human PR/release handoff
-- Enabled by default in Enterprise mode
-
----
-
-## Core Rules
-
-### Rule 1: Zero Findings Forbidden
-
-A reviewer agent's output of "everything looks fine, no issues found" is an **invalid conclusion**.
-
-**Reasons**:
-- Real systems inevitably contain trade-offs, boundaries, and risks
-- "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 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: Coverage proportional to feature scope
-
-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?
-3. **Test layer**: Coverage? Edge cases? Over-mocking?
-4. **Security layer**: Injection risks? Permission checks? Sensitive data leakage?
-5. **Maintainability layer**: Documentation? Naming? Readability?
-6. **User experience layer**: Error messages? Loading states? Accessibility?
-
----
-
-### Rule 3: Findings Must Have Evidence + Recommendation
-
-Format for each finding:
-
-```markdown
-### [Category] Issue Title
-
-**Location**: src/auth/login.ts:42
-
-**Observation**: <what was specifically seen>
-
-**Risk**: <what problem will this cause? High/Medium/Low?>
-
-**Evidence**: <code snippet / test output / scenario>
-
-**Recommendation**: <specifically how to fix>
-```
-
-Not allowed:
-- ✗ "The code could be better" (too vague)
-- ✗ "I think... maybe..." (no specific basis)
-
----
-
-## Execution Flow
-
-```
-Input: object under review (code range / spec / PR diff)
-  ↓
-Round 1 (agent self-analysis):
-  - Use sequential-thinking proportional to the surface being probed
-  - Scan each applicable category; mark N/A ones with reason
-  - Output findings list
-  ↓
-Decision:
-  - 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 proportional to residual uncertainty
-  - Focus on "seemingly no issues" parts (trust but verify)
-  - Optionally introduce external perspectives (read issues from similar projects)
-  ↓
-Decision:
-  - Still zero findings? → agent must emit proof-of-checking report (NOT invent findings)
-  - Findings exist? → output report
-  ↓
-Output: review-report.md
-```
-
----
-
-## Typical Finding Patterns (for agent reference)
-
-### Architecture
-- "New component X depends on Y, but Y is not mentioned in design.md → introduces implicit coupling"
-- "AD-03 chooses JWT, but does not handle token revocation → user logout is not thorough"
-
-### Implementation
-- "src/auth/login.ts:42 catches all exceptions and returns 500, but bcrypt timeout should return 429"
-- "Verify in tasks.md is `npm test`, no specific test file specified → may have run unrelated tests"
-
-### Testing
-- "login.test.ts has 5 tests, but AC-1.3 (empty password) is not covered"
-- "Tests use `jest.fn()` to mock DB; actual DB constraints are not tested → may fail in production"
-
-### Security
-- "Error message returns `User not found`, can be identified by enumeration attack for existence"
-- "JWT secret comes from process.env with no fallback → crashes when environment variable is missing"
-
----
-
-## Output Format
-
-```markdown
-## Adversarial Review Report
-
-Object under review: auth-system spec (commits abc..xyz)
-Review time: 2026-04-19
-Review rounds: 2 (Round 1 found 2, triggered Round 2)
-
-## Total findings: 5
-
-### [Architecture] Token revocation not designed
-Location: design.md AD-01
-Observation: stateless JWT was chosen, but requirements FR-04 requires "user logout immediately invalidates other sessions"
-Risk: High — violates an explicit requirement
-Evidence: AD-01 only says "use JWT", does not say how to revoke
-Recommendation: Add AD-06 explaining the use of Redis blacklist + check-on-each-request
-
-### [Implementation] bcrypt error handling missing
-Location: src/auth/login.ts:58
-Observation: await bcrypt.compare() has no try-catch
-Risk: Medium — bcrypt crash will cause 500 exposing internal stack
-Evidence: (code snippet omitted)
-Recommendation: wrap in try-catch, return 401
-
-### [Test] AC-1.3 not covered
-Location: login.test.ts
-Observation: requirements AC-1.3 requires "empty password returns 400", but there is no corresponding test
-Risk: Medium — regression risk
-Evidence: grep "empty password" → 0 matches
-Recommendation: add test("rejects empty password", ...)
-
-### [Security] User enumeration leak
-Location: src/auth/login.ts:45-50
-Observation: email not found → "User not found"; email found pwd wrong → "Wrong password"
-Risk: High — can be used to enumerate registered emails
-Evidence: (code snippet)
-Recommendation: unify error message to "Invalid credentials"
-
-### [Maintainability] Inconsistent log format
-Location: src/auth/login.ts:42 vs src/auth/logout.ts:18
-Observation: one uses `console.log`, the other uses `logger.info`
-Risk: Low — does not affect functionality, but future monitoring will be messy
-Evidence: grep log → 2 patterns
-Recommendation: unify to logger.info
-
-## Summary
-
-Blockers: 2 ([Architecture] token revocation, [Security] user enumeration)
-Warnings: 3
-
-Fix loop:
-1. Dispatch flow-executor to fix security + architecture (high priority)
-2. Add tests
-3. Unify log
-4. Re-run /curdx-flow:review for re-review
-```
-
----
-
-## Failure Recovery
-
-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 — Proof of Checking (zero findings)
-
-I have examined the following dimensions across 2 rounds of analysis:
-
-1. Architecture: checked AD-01~04 and corresponding implementations, no obvious issues found
-2. Implementation: checked src/auth/*.ts totaling 342 lines, no obvious issues found
-3. Tests: checked 15 tests, covered all ACs, no gaps found
-4. Security: checked input validation, error messages, secret management, no issues found
-5. Maintainability: naming and structure are consistent
-
-⚠ Note: this does not mean there are truly no issues. It may be that:
-- the object under review is indeed high quality
-- or my review capability has blind spots (e.g., specific domains)
-- or there are hidden issues that will only surface at runtime
-
-Recommendations:
-- Human review (at least walk through the diff once)
-- Consider the `browser-qa` skill for real browser/integration testing (Phase 5+)
-- Wait until deployment to staging to observe
-```
-
----
-
-_Source: BMAD-METHOD's adversarial review prompts._

package/gates/coverage-audit-gate.md

@@ -1,182 +0,0 @@
----
-gate: coverage-audit-gate
-category: standard-mode
-severity: blocking
-depends_on: []
----
-
-# Coverage Audit Gate — Multi-Source Coverage Audit
-
-> Rule: every claim in the spec must be covered by implementation/tests. Uncovered = missed = future bug.
-
----
-
-## Trigger Timing
-
-- End of the tasks phase (last step of flow-planner)
-- Before the execution phase completes (when /curdx-flow:verify runs)
-- Explicitly requested by /curdx-flow:verify --strict
-
----
-
-## Audit Sources (4 categories)
-
-### Source 1: Requirements (FR + AC)
-
-**Source**: `requirements.md`
-
-**Checks**:
-- Does every FR-NN have a corresponding task in tasks.md?
-- Does every AC-X.Y have a corresponding test in code?
-
-**Missing handling**:
-- Uncovered FR → block, must add task or exempt
-- Uncovered AC → warning, recommend adding test
-
----
-
-### Source 2: Design (AD + Components)
-
-**Source**: `design.md`
-
-**Checks**:
-- Does every AD-NN have a corresponding implementation task in tasks.md?
-- Does every Component have a skeleton task + core logic task in tasks.md?
-- Does every error path have a corresponding scenario in tests?
-
-**Missing handling**:
-- Uncovered AD → block (an architecture decision not landed = design failure)
-- Uncovered error path → warning
-
----
-
-### Source 3: Research recommendations
-
-**Source**: the "recommendations" section of `research.md`
-
-**Checks**:
-- Are the technical approaches recommended by research implemented in design.md?
-- Are the pitfalls found by research avoided in the implementation?
-
-**Missing handling**:
-- Recommended direction not adopted → warning (design.md must explain why not)
-- Pitfall not avoided → block
-
----
-
-### Source 4: Project-level decisions (D-NN)
-
-**Source**: the decisions array in `.flow/STATE.md`
-
-**Checks**:
-- Which D-NN are involved in this spec?
-- Is each relevant D-NN referenced in design.md / tasks.md?
-- Does the implementation comply with the decision?
-
-**Missing handling**:
-- Violates D-NN → block, must either return to the design phase to challenge the decision or modify the implementation
-- Not referenced but actually compliant → warning (prompt to add reference)
-
----
-
-## Execution Flow
-
-```python
-# pseudocode
-def audit(spec_name):
-    req = parse_requirements(spec_name)
-    design = parse_design(spec_name)
-    research = parse_research(spec_name)
-    state = parse_global_state()
-    tasks = parse_tasks(spec_name)
-    commits = git_log_for_spec(spec_name)
-    
-    missing = []
-    
-    # Source 1
-    for fr in req.functional_requirements:
-        if not any(fr.id in t.requirements_ref for t in tasks):
-            missing.append(("FR", fr.id, "no task covers"))
-    
-    for ac in req.acceptance_criteria:
-        if not any(ac.id in c.body for c in commits):
-            missing.append(("AC", ac.id, "no test covers"))
-    
-    # Source 2
-    for ad in design.architecture_decisions:
-        if not any(ad.id in t.design_ref for t in tasks):
-            missing.append(("AD", ad.id, "no task implements"))
-    
-    # Source 3
-    for rec in research.recommendations:
-        if rec not in design.chosen_approaches:
-            missing.append(("Research", rec.summary, "not adopted, no rationale"))
-    
-    # Source 4
-    relevant_decisions = [d for d in state.decisions if spec_touches(d)]
-    for d in relevant_decisions:
-        if not any(d.id in text for text in [design.content, tasks.content]):
-            missing.append(("D", d.id, "not referenced"))
-    
-    return missing
-```
-
----
-
-## Violation Levels
-
-| Missing Type | Level | Action |
-|---------|------|------|
-| FR uncovered | **block** | add task |
-| AC uncovered | warning | add test (recommended) |
-| AD uncovered | **block** | add implementation task |
-| Component uncovered | **block** | add skeleton + logic tasks |
-| Error path uncovered | warning | add error test |
-| Research recommendation not adopted | warning | add rejection rationale to design.md |
-| Project decision violated | **block** | challenge decision or fix implementation |
-
----
-
-## Output Format
-
-```markdown
-## Coverage Audit Report
-
-Spec: auth-system
-Audit time: 2026-04-19
-
-### Source 1: Requirements
-- FR-01 login: ✓ tasks 1.1, 1.2
-- FR-02 logout: ✓ tasks 2.1
-- FR-03 refresh token: ✗ **uncovered**
-- AC-1.1: ✓ test in tasks 3.1
-- AC-1.2: ⚠ no corresponding test
-- AC-2.1: ✓ test in tasks 3.2
-
-### Source 2: Design
-- AD-01 JWT vs Session: ✓ tasks 1.1
-- AD-02 bcrypt cost 12: ✓ tasks 1.2
-- AD-03 refresh rotation: ✗ **uncovered** (maps to FR-03)
-- Component TokenManager: ✗ **uncovered**
-- Error path: network fail: ⚠ no test
-
-### Source 3: Research
-- Recommendation: use Redis to store blacklist → ✓ adopted in design
-- Pitfall: bcrypt cost > 15 will be slow → ✓ design limits ≤ 12
-
-### Source 4: Decisions
-- D-07 session storage → ✓ referenced by AD-01
-- D-12 error log format → ⚠ not mentioned in design/tasks
-
-### Summary
-Blockers: 3 (FR-03, AD-03, Component TokenManager)
-Warnings: 3
-
-Fix recommendations:
-1. Add tasks to cover FR-03 / AD-03 / TokenManager, or
-2. Explicitly exempt in STATE.md (defer to next spec)
-```
-
----
-
-_Source: CurDX-Flow multi-source coverage audit contract._

package/gates/devex-gate.md

@@ -1,254 +0,0 @@
----
-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:spec --review=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 proportional to the complexity of the codebase being scanned.
-
-### Human Review
-
-Attach a DevEx checklist at PR time:
-- [ ] Clear naming (re-read until obvious to a new maintainer)
-- [ ] Critical comments exist
-- [ ] Consistent structure
-- [ ] Actionable error messages
-- [ ] Tests as docs
-
----
-
-## Scoring
-
-Score each **applicable** dimension 0-10 (N/A dimensions are excluded from the total):
-
-```
-10 = best practice
-8  = good
-5  = pass (production-usable)
-3  = needs improvement
-0  = serious issue
-```
-
-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.
-
----
-
-## 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._