@curdx/flow 2.3.11 → 3.1.0

package/gates/test-quality-gate.md

@@ -1,59 +0,0 @@
----
-gate: test-quality-gate
-category: standard-mode
-severity: blocking
-depends_on: []
----
-
-# Test Quality Gate
-
-A green test suite is not enough. Tests must exercise real behavior and fail for the right reason.
-
-## Blocking Findings
-
-Flag as blocking when a test is the only evidence for an FR/AC and any of these hold:
-
-1. **Mock-only behavior**
-   - Assertions only check mock calls (`toHaveBeenCalled`, `calledWith`, spy counts).
-   - The real module/function under test is never invoked.
-   - The test would still pass if the production implementation were empty.
-
-2. **Mock setup dominates evidence**
-   - Mock/stub/spy setup lines are more than 3x real behavioral assertions.
-   - The test mostly restates fixture wiring instead of asserting output, state, persistence, or user-visible behavior.
-
-3. **Skipped or inert tests**
-   - `it.skip`, `describe.skip`, `test.skip`, `xit`, `pending`, or equivalent on covered behavior.
-   - Test has no assertions and no meaningful side-effect check.
-
-4. **Implementation-biased regression**
-   - Test was added after implementation without evidence of RED failure when the task claims TDD.
-   - Test asserts internal private structure instead of externally observable behavior.
-
-5. **Missing cleanup for stateful mocks**
-   - Stateful mocks/spies are used across tests without `afterEach` cleanup (`restoreAllMocks`, `clearAllMocks`, sandbox restore, etc.).
-   - Shared mock state can leak between tests.
-
-## Acceptable Mock Usage
-
-Mocks are acceptable when they isolate a boundary and the assertion still verifies real behavior:
-
-- Network/payment/email provider mocked, but service logic and error handling are real.
-- Clock/randomness mocked to make deterministic assertions.
-- Database mocked only when a separate integration test covers persistence behavior.
-
-## Evidence Checklist
-
-For each FR/AC test evidence, record:
-
-- Test file and test name.
-- What real code path is invoked.
-- What behavioral assertion proves the requirement.
-- Whether the test was observed RED before GREEN when TDD is claimed.
-- Whether mocks are boundary-only or behavior-replacing.
-
-## Verdicts
-
-- `PASS`: Tests exercise real behavior with meaningful assertions.
-- `WARN`: Mock-heavy but supported by separate integration/e2e coverage.
-- `FAIL`: Mock-only/skipped/no-assertion test is used as primary evidence.

package/gates/verification-gate.md

@@ -1,179 +0,0 @@
----
-gate: verification-gate
-category: always-on
-severity: blocking
-depends_on: []
----
-
-# Verification Gate — Verification Required Before Completion
-
-> **Always enabled**. No evidence = no completion. Verification must be based on observed proof, not claimed completion.
-
----
-
-## Core Rule
-
-**Do not declare `done`, `fixed`, `passed`, `working`, `okay` unless there is fresh execution evidence.**
-
----
-
-## Trigger Timing
-
-- Before any agent outputs a "done/fixed/passed" conclusion
-- Before commit messages contain forbidden words
-- Before Phase transitions (research → requirements, requirements → design, etc.)
-
----
-
-## Forbidden Word List (English + Chinese)
-
-Fresh evidence required to use:
-
-**English**:
-- `done`, `fixed`, `working`, `passed`, `resolved`, `completed`
-- `should work`, `probably`, `likely`, `might work`
-- `seems to`, `appears to`, `looks good`, `looks right`
-- `great!`, `perfect!`, `all set`
-
-**Chinese**:
-- `完成`, `搞定`, `好了`, `可以了`, `修好了`
-- `应该`, `可能`, `大概`, `似乎`, `好像`
-- `看起来没问题`, `应该能工作`
-
----
-
-## Allowed Conclusions Must Carry Evidence
-
-✗ **Violation**:
-> I fixed the login bug
-
-✓ **Compliant**:
-> I fixed the login bug. Re-running `npm test -- auth/login` produced:
-> ```
-> ✓ login endpoint rejects empty email
-> ✓ login endpoint accepts valid credentials
-> Test Suites: 1 passed, Tests: 2 passed
-> ```
-
-✗ **Violation**:
-> The code looks fine
-
-✓ **Compliant**:
-> Ran `npx tsc --noEmit` → 0 errors
-> Ran `npx eslint src/auth/` → 0 errors, 0 warnings
-
----
-
-## Evidence Types
-
-| Claim | Required Evidence |
-|------|---------|
-| "Fixed X" | command reproducing X + execution output |
-| "Tests pass" | full `npm test` output including pass count |
-| "Code is valid" | `tsc --noEmit` exit code + output |
-| "API works" | `curl` response + status code |
-| "Deployment succeeded" | deployment log + health check response |
-| "User can log in" | browser / chrome-devtools test screenshot or log |
-| "Performance meets target" | benchmark command + numbers |
-
----
-
-## Checking Methods
-
-### Agent Built-in (self-check)
-
-Each agent runs an internal check before outputting:
-
-```
-For each conclusion sentence, ask yourself:
-1. Does this sentence contain a forbidden word?
-2. If so, do I have fresh evidence supporting it?
-3. Is the evidence from a just-executed command, or older / assumed?
-4. If the evidence is not fresh or does not exist, re-run or delete this sentence.
-```
-
-### flow-reviewer Agent (external check)
-
-Scan:
-- `commit messages` for forbidden words
-- declarative sentences in `.progress.md`
-- the conclusion section of agent output
-
----
-
-## Violation Handling
-
-### Severe (block)
-
-- commit message contains forbidden word without evidence
-- `.progress.md` says "done" but has no verify output
-
-**Actions**:
-- Block the commit (pre-commit hook, Phase 4+)
-- Or dispatch flow-executor to re-run Verify and update the record
-- Rewrite the commit message
-
-### Medium (warning)
-
-- Verbally saying "looks good" (not in commit or file)
-- Using "should" as a hypothetical statement (acceptable)
-
-**Action**: mark, non-blocking
-
----
-
-## Special Cases
-
-### "I already checked"
-
-Not enough. "Checked" is a subjective claim. You need **execution output**.
-
-```
-✗ "I checked that all tests pass"
-✓ "Ran npm test: Test Suites: 5 passed, Tests: 47 passed, Snapshots: 0 total"
-```
-
-### Partial Completion
-
-Do not describe partial completion as complete. Clearly categorize:
-
-```
-✓ Completed:
-  - FR-01 login endpoint: passed (test output)
-  - FR-02 password encryption: passed (test output)
-
-⚠ Partially completed:
-  - FR-03 Token refresh: code written but tests not yet run
-
-✗ Not started:
-  - FR-04 Logout
-```
-
----
-
-## Output Format
-
-```markdown
-## Verification Gate Check Result
-
-Scan range: commit abc123..def456
-Statements containing forbidden words: 3
-
-[V1] "Login bug fixed" (commit abc123)
-     Evidence: ✗ none (no corresponding test output or verify record found)
-     Verdict: block
-
-[V2] "All tests pass" (.progress.md line 12)
-     Evidence: ✓ "npm test: 47/47 passed" (same file, line 11)
-     Verdict: compliant
-
-[V3] "Should handle concurrency" (design.md AD-05)
-     Evidence: ⚠ "should" is hypothetical tone, acceptable
-     Verdict: warning (recommend adding a spike to verify)
-
-Blockers: 1
-Warnings: 1
-
-Fix recommendations:
-  V1: dispatch flow-executor to run tests, add evidence to the commit message body
-```

package/hooks/hooks.json

@@ -1,58 +0,0 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
-            "statusMessage": "Loading CurDX-Flow project context"
-          }
-        ]
-      },
-      {
-        "matcher": "startup|clear|compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/inject-karpathy.sh",
-            "statusMessage": "Injecting CurDX-Flow engineering baseline"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop-watcher.sh"
-          }
-        ]
-      }
-    ],
-    "SubagentStop": [
-      {
-        "matcher": "flow-(architect|brownfield-analyst|debugger|edge-hunter|executor|product-designer|planner|qa-engineer|researcher|reviewer|security-auditor|triage-analyst|ui-researcher|ux-designer|verifier|adversary)",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-artifact-guard.sh",
-            "statusMessage": "Checking curdx-flow artifact landing"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "AskUserQuestion",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quick-mode-guard.sh"
-          }
-        ]
-      }
-    ]
-  }
-}

package/hooks/scripts/common.sh

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-
-has_python3() {
-  command -v python3 >/dev/null 2>&1
-}
-
-env_flag_enabled() {
-  case "$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]')" in
-    1|true|yes|on) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-json_escape() {
-  local value="${1:-}"
-
-  if has_python3; then
-    printf '%s' "$value" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'
-    return
-  fi
-
-  printf '%s' "$value" \
-    | sed 's/\\/\\\\/g; s/"/\\"/g' \
-    | awk 'BEGIN{printf "\""} {printf "%s\\n", $0} END{printf "\""}'
-}
-
-emit_session_start_context() {
-  local context="${1:-}"
-  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' \
-    "$(json_escape "$context")"
-}
-
-emit_pretooluse_deny() {
-  local reason="${1:-}"
-  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' \
-    "$(json_escape "$reason")"
-}
-
-emit_stop_block() {
-  local reason="${1:-}"
-  printf '{"decision":"block","reason":%s}\n' "$(json_escape "$reason")"
-}
-
-emit_subagentstop_block() {
-  emit_stop_block "${1:-}"
-}

package/hooks/scripts/inject-karpathy.sh

@@ -1,53 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow SessionStart baseline injection
-# Injects the L1 baseline (Karpathy 4 principles + mandatory tool rules + 3 red lines)
-# as additionalContext at every session boot (startup, /clear, post-compact).
-#
-# Wired under SessionStart with matcher "startup|clear|compact" so the
-# baseline survives startup, /clear, and post-compact resume.
-
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-. "$SCRIPT_DIR/common.sh"
-
-CONTEXT='## CurDX-Flow Mind Baseline (L1 — always on)
-
-### 1. Think Before Coding
-- State assumptions before any non-trivial task
-- When uncertain, use AskUserQuestion — do not silently assume
-- When confused, stop — do not push forward
-
-### 2. Simplicity First
-- YAGNI: do not write features beyond what was requested
-- No single-use abstractions
-- If 200 lines suffice, do not write 1000
-
-### 3. Surgical Changes
-- Modify only the lines that must change
-- Match existing style
-- Do not delete pre-existing dead code
-
-### 4. Goal-Driven
-- Define a verifiable success criterion first
-- Forbidden to say done/fixed/working without evidence
-
-## Mandatory Tools (L2 — enforced)
-
-- library/framework questions → **context7 first** (`mcp__context7__*`); forbidden to rely on training memory
-- planning / design / architecture / review → **sequential-thinking first** (≥5 thoughts)
-- before any task → **claude-mem search** (if installed)
-- UI code → **frontend-design skill** (if installed)
-- browser QA → **chrome-devtools MCP**
-
-## Three Red Lines (L3 — inherited from pua, universal)
-
-1. **Closed loop**: claiming "done"? Provide evidence (build output / passing tests / curl result)
-2. **Fact-driven**: verify before saying "probably". An unverified attribution is blame-shifting
-3. **Exhaust everything**: before saying "I cannot", complete the systematic 4-stage debugging'
-
-if has_python3; then
-  emit_session_start_context "$CONTEXT"
-fi
-
-exit 0

package/hooks/scripts/quick-mode-guard.sh

@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow PreToolUse Hook for AskUserQuestion
-# Blocks AskUserQuestion when the active spec has quickMode=true.
-# This prevents quick execution loops from stalling waiting for user input.
-#
-# The hook reads Claude's PreToolUse input JSON from stdin. We only act when
-# the tool being invoked is AskUserQuestion.
-
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-. "$SCRIPT_DIR/common.sh"
-
-# Read input (Claude sends JSON on stdin for PreToolUse)
-INPUT=$(cat 2>/dev/null || echo "{}")
-
-if ! command -v python3 >/dev/null 2>&1; then
-  # Without JSON parsing, allow everything (fail open)
-  exit 0
-fi
-
-# Parse the tool name being invoked
-TOOL_NAME=$(echo "$INPUT" | python3 -c '
-import json, sys
-try:
-    d = json.load(sys.stdin)
-    print(d.get("tool_name", ""))
-except Exception:
-    print("")
-' 2>/dev/null)
-
-# We only guard AskUserQuestion
-if [ "$TOOL_NAME" != "AskUserQuestion" ]; then
-  exit 0
-fi
-
-# Check if we're in a flow project with quick mode enabled.
-[ ! -d ".flow" ] && exit 0
-
-ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
-[ -z "$ACTIVE" ] && exit 0
-
-STATE_FILE=".flow/specs/$ACTIVE/.state.json"
-[ ! -f "$STATE_FILE" ] && exit 0
-
-# Read quickMode. Pass STATE_FILE via env (NOT shell interpolation
-# into the python source) so an active-spec name containing quotes/$ cannot
-# inject python code.
-export STATE_FILE
-QUICK_MODE=$(python3 -c '
-import json, os
-try:
-    s = json.load(open(os.environ["STATE_FILE"]))
-    qm = s.get("quickMode", False)
-    print("true" if qm else "false")
-except Exception:
-    print("false")
-' 2>/dev/null)
-
-if [ "$QUICK_MODE" = "true" ]; then
-  # Block and inject guidance
-  MSG="[CurDX-Flow quick-mode-guard] Active spec '$ACTIVE' is in quick mode — AskUserQuestion is forbidden. Decide based on user preferences in .flow/CONTEXT.md plus the most reasonable assumption, and record your assumption in .progress.md."
-  emit_pretooluse_deny "$MSG"
-  exit 0
-fi
-
-# Allow
-exit 0

package/hooks/scripts/session-start.sh

@@ -1,90 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow SessionStart Hook
-# Duties:
-#   1. Daily dependency check — nudge user to `npx @curdx/flow install --all` if recommended plugins missing
-#   2. Load active spec progress into session context
-#   3. Persist stable CurDX-Flow environment hints for this session
-#
-# Design notes:
-#   - Idempotent: marker file tracks last check date
-#   - Silent when everything is healthy (no noise)
-#   - Graceful degradation: missing `claude` CLI doesn't break hook
-
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-. "$SCRIPT_DIR/common.sh"
-
-DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
-MARKER="$DATA_DIR/.deps-checked"
-TODAY="$(date +%Y-%m-%d)"
-ADDITIONAL_CONTEXT=""
-
-mkdir -p "$DATA_DIR" 2>/dev/null || true
-
-# ---------- 1. Dependency check (once per day) ----------
-LAST_CHECK=""
-[ -f "$MARKER" ] && LAST_CHECK="$(cat "$MARKER" 2>/dev/null)"
-
-if env_flag_enabled "${CLAUDE_PLUGIN_OPTION_DAILY_DEPENDENCY_CHECK:-1}" && [ "$LAST_CHECK" != "$TODAY" ]; then
-  MISSING=()
-
-  # Skip if `claude` CLI is not on PATH
-  if command -v claude >/dev/null 2>&1; then
-    INSTALLED="$(claude plugin list 2>/dev/null || true)"
-
-    # Names must stay in lockstep with cli/registry.js RECOMMENDED_PLUGINS.
-    # Drift is guarded by test/registry-session-start-parity.test.js.
-    echo "$INSTALLED" | grep -q 'pua'                 || MISSING+=("pua")
-    echo "$INSTALLED" | grep -q 'claude-mem'          || MISSING+=("claude-mem")
-    echo "$INSTALLED" | grep -q 'frontend-design'     || MISSING+=("frontend-design")
-    echo "$INSTALLED" | grep -q 'chrome-devtools-mcp' || MISSING+=("chrome-devtools-mcp")
-  fi
-
-  if [ "${#MISSING[@]}" -gt 0 ]; then
-    JOINED="$(IFS=,; echo "${MISSING[*]}")"
-    ADDITIONAL_CONTEXT+="## CurDX-Flow Recommended Plugins Check\n\nThe following recommended plugins were not detected: **${JOINED}**\n\nRun \`npx @curdx/flow install --all\` for interactive one-shot install. Run \`npx @curdx/flow doctor\` for the full health report.\n\n"
-  fi
-
-  { echo "$TODAY" > "$MARKER"; } 2>/dev/null || true
-fi
-
-# ---------- 2. Load .flow/ state (if project is a flow project) ----------
-if [ -d ".flow" ]; then
-  ADDITIONAL_CONTEXT+="## CurDX-Flow Project Active\n\n"
-  ADDITIONAL_CONTEXT+="- Plugin root: \`${CLAUDE_PLUGIN_ROOT:-unknown}\`\n"
-  ADDITIONAL_CONTEXT+="- Plugin data: \`${CLAUDE_PLUGIN_DATA:-$DATA_DIR}\`\n"
-  ADDITIONAL_CONTEXT+="- Best practice: write long agent artifacts to disk first; keep final assistant summaries short.\n\n"
-
-  if [ -f ".flow/PROJECT.md" ]; then
-    ADDITIONAL_CONTEXT+="### Project Vision\n$(head -80 .flow/PROJECT.md)\n\n"
-  fi
-
-  if [ -f ".flow/.active-spec" ]; then
-    ACTIVE="$(cat .flow/.active-spec 2>/dev/null)"
-    if [ -n "$ACTIVE" ] && [ -d ".flow/specs/$ACTIVE" ]; then
-      ADDITIONAL_CONTEXT+="### Active Spec: \`$ACTIVE\`\n\n"
-      if [ -f ".flow/specs/$ACTIVE/.progress.md" ]; then
-        ADDITIONAL_CONTEXT+="$(head -40 ".flow/specs/$ACTIVE/.progress.md")\n\n"
-      fi
-    fi
-  fi
-fi
-
-# ---------- 3. Persist session environment hints ----------
-if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
-  {
-    printf 'export CURDX_FLOW_PLUGIN_ROOT=%s\n' "$(json_escape "${CLAUDE_PLUGIN_ROOT:-}")"
-    printf 'export CURDX_FLOW_PLUGIN_DATA=%s\n' "$(json_escape "${CLAUDE_PLUGIN_DATA:-$DATA_DIR}")"
-    if [ -f ".flow/.active-spec" ]; then
-      printf 'export CURDX_FLOW_ACTIVE_SPEC=%s\n' "$(json_escape "$(cat .flow/.active-spec 2>/dev/null)")"
-    fi
-  } >> "$CLAUDE_ENV_FILE" 2>/dev/null || true
-fi
-
-# ---------- 4. Emit hook output ----------
-if [ -n "$ADDITIONAL_CONTEXT" ]; then
-  emit_session_start_context "$ADDITIONAL_CONTEXT"
-fi
-
-exit 0