@curdx/flow 3.0.0 → 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,130 +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"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-title.sh",
-            "statusMessage": "Refreshing CurDX-Flow session title"
-          }
-        ]
-      }
-    ],
-    "CwdChanged": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/flow-context-watch.sh"
-          }
-        ]
-      }
-    ],
-    "FileChanged": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/flow-context-watch.sh"
-          }
-        ]
-      }
-    ],
-    "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"
-          }
-        ]
-      }
-    ],
-    "TaskCreated": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/task-lifecycle-guard.sh"
-          }
-        ]
-      }
-    ],
-    "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/task-lifecycle-guard.sh"
-          }
-        ]
-      }
-    ],
-    "TeammateIdle": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/teammate-idle-guard.sh"
-          }
-        ]
-      }
-    ],
-    "ConfigChange": [
-      {
-        "matcher": "project_settings|local_settings",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/config-change-guard.sh"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "AskUserQuestion",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quick-mode-guard.sh"
-          }
-        ]
-      }
-    ]
-  }
-}

package/hooks/scripts/common.sh

@@ -1,237 +0,0 @@
-#!/usr/bin/env bash
-
-has_python3() {
-  command -v python3 >/dev/null 2>&1
-}
-
-resolve_flow_root() {
-  local candidate="${1:-${PWD:-}}"
-
-  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}/.flow" ]; then
-    printf '%s\n' "${CLAUDE_PROJECT_DIR%/}"
-    return 0
-  fi
-
-  [ -n "$candidate" ] || candidate="$(pwd 2>/dev/null || printf '.')"
-
-  while [ -n "$candidate" ]; do
-    if [ -d "$candidate/.flow" ]; then
-      printf '%s\n' "$candidate"
-      return 0
-    fi
-
-    [ "$candidate" = "/" ] && break
-    candidate="$(dirname "$candidate")"
-  done
-
-  return 1
-}
-
-curdx_active_spec_name() {
-  local flow_root="${1:-${FLOW_ROOT:-}}"
-  [ -n "$flow_root" ] || return 1
-  [ -f "$flow_root/.flow/.active-spec" ] || return 1
-  cat "$flow_root/.flow/.active-spec" 2>/dev/null
-}
-
-curdx_active_spec_path() {
-  local flow_root="${1:-${FLOW_ROOT:-}}"
-  local file_name="${2:-}"
-  local active
-
-  [ -n "$flow_root" ] || return 1
-  [ -n "$file_name" ] || return 1
-
-  active="$(curdx_active_spec_name "$flow_root" 2>/dev/null || true)"
-  [ -n "$active" ] || return 1
-
-  printf '%s/.flow/specs/%s/%s\n' "$flow_root" "$active" "$file_name"
-}
-
-curdx_latest_epic_artifact_path() {
-  local flow_root="${1:-${FLOW_ROOT:-}}"
-
-  [ -n "$flow_root" ] || return 1
-  [ -d "$flow_root/.flow/_epics" ] || return 1
-  has_python3 || return 1
-
-  export CURDX_EPIC_DIR="$flow_root/.flow/_epics"
-  python3 <<'PY' 2>/dev/null
-import os
-from pathlib import Path
-
-base = Path(os.environ["CURDX_EPIC_DIR"])
-candidates = [path for path in base.glob("*/epic.md") if path.is_file()]
-if not candidates:
-    raise SystemExit(1)
-
-latest = max(candidates, key=lambda path: path.stat().st_mtime)
-print(str(latest))
-PY
-}
-
-curdx_epic_artifact_path_from_message() {
-  local flow_root="${1:-${FLOW_ROOT:-}}"
-  local msg="${2:-}"
-
-  [ -n "$flow_root" ] || return 1
-  has_python3 || return 1
-
-  export CURDX_EPIC_MSG="$msg"
-  export CURDX_FLOW_ROOT="$flow_root"
-  python3 <<'PY' 2>/dev/null
-import os
-import re
-
-msg = os.environ.get("CURDX_EPIC_MSG", "")
-match = re.search(r'(\.flow/_epics/[^/\s]+/epic\.md)\b', msg)
-if not match:
-    raise SystemExit(1)
-
-rel = match.group(1)
-if rel.startswith(".flow/"):
-    rel = rel[len(".flow/"):]
-
-print(os.path.join(os.environ["CURDX_FLOW_ROOT"], ".flow", rel))
-PY
-}
-
-curdx_resolve_artifact_contract() {
-  local agent_type="${1:-}"
-  local last_message="${2:-}"
-  local flow_root="${3:-${FLOW_ROOT:-}}"
-
-  CURDX_ARTIFACT_TARGET=""
-  CURDX_ARTIFACT_MIN_SIZE=0
-
-  [ -n "$agent_type" ] || return 1
-
-  case "$agent_type" in
-    flow-researcher)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" research.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-product-designer)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" requirements.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-architect)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" design.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-planner)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" tasks.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-executor)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" tasks.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-debugger)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" debug-report.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    flow-reviewer)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" review-report.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=300
-      ;;
-    flow-verifier)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" verification-report.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=300
-      ;;
-    flow-security-auditor)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" security-audit.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    flow-qa-engineer)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" qa-report.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    flow-edge-hunter)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" edge-cases.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    flow-adversary)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" adversarial-review.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    flow-ui-researcher)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" ui-research.md)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    flow-ux-designer)
-      CURDX_ARTIFACT_TARGET="$(curdx_active_spec_path "$flow_root" ui-sketch/index.html)" || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-triage-analyst)
-      CURDX_ARTIFACT_TARGET="$(curdx_epic_artifact_path_from_message "$flow_root" "$last_message" 2>/dev/null || true)"
-      if [ -z "$CURDX_ARTIFACT_TARGET" ]; then
-        CURDX_ARTIFACT_TARGET="$(curdx_latest_epic_artifact_path "$flow_root" 2>/dev/null || true)"
-      fi
-      [ -n "$CURDX_ARTIFACT_TARGET" ] || return 1
-      CURDX_ARTIFACT_MIN_SIZE=400
-      ;;
-    flow-brownfield-analyst)
-      [ -n "$flow_root" ] || return 1
-      CURDX_ARTIFACT_TARGET="$flow_root/.flow/codebase-index.md"
-      CURDX_ARTIFACT_MIN_SIZE=250
-      ;;
-    *)
-      return 1
-      ;;
-  esac
-
-  return 0
-}
-
-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_userprompt_submit_title() {
-  local title="${1:-}"
-  printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","sessionTitle":%s}}\n' \
-    "$(json_escape "$title")"
-}
-
-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:-}"
-}
-
-emit_configchange_block() {
-  local reason="${1:-}"
-  printf '{"decision":"block","reason":%s}\n' "$(json_escape "$reason")"
-}

package/hooks/scripts/config-change-guard.sh

@@ -1,94 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow ConfigChange Hook
-# Blocks mid-execute settings changes that would disable CurDX's runtime spine.
-
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-. "$SCRIPT_DIR/common.sh"
-
-INPUT="$(cat 2>/dev/null || echo "{}")"
-FLOW_ROOT="$(resolve_flow_root 2>/dev/null || true)"
-
-[ -n "$FLOW_ROOT" ] || exit 0
-has_python3 || exit 0
-
-export CURDX_CONFIG_CHANGE_INPUT="$INPUT"
-
-SOURCE="$(python3 -c 'import json, os
-try:
-    data = json.loads(os.environ["CURDX_CONFIG_CHANGE_INPUT"])
-    print(data.get("source", ""))
-except Exception:
-    print("")
-' 2>/dev/null)"
-
-case "$SOURCE" in
-  project_settings|local_settings) ;;
-  *) exit 0 ;;
-esac
-
-FILE_PATH="$(python3 -c 'import json, os
-try:
-    data = json.loads(os.environ["CURDX_CONFIG_CHANGE_INPUT"])
-    print(data.get("file_path", ""))
-except Exception:
-    print("")
-' 2>/dev/null)"
-
-[ -n "$FILE_PATH" ] || exit 0
-[ -f "$FILE_PATH" ] || exit 0
-[ -f "$FLOW_ROOT/.flow/.active-spec" ] || exit 0
-
-ACTIVE="$(cat "$FLOW_ROOT/.flow/.active-spec" 2>/dev/null)"
-[ -n "$ACTIVE" ] || exit 0
-
-STATE_FILE="$FLOW_ROOT/.flow/specs/$ACTIVE/.state.json"
-[ -f "$STATE_FILE" ] || exit 0
-
-export STATE_FILE
-PHASE="$(python3 -c 'import json, os
-try:
-    state = json.load(open(os.environ["STATE_FILE"]))
-    print(state.get("phase", ""))
-except Exception:
-    print("")
-' 2>/dev/null)"
-
-[ "$PHASE" = "execute" ] || exit 0
-
-export CURDX_CONFIG_CHANGE_FILE="$FILE_PATH"
-BLOCK_REASONS="$(python3 <<'PY' 2>/dev/null
-import json
-import os
-
-file_path = os.environ["CURDX_CONFIG_CHANGE_FILE"]
-try:
-    parsed = json.load(open(file_path))
-except Exception:
-    raise SystemExit(0)
-
-reasons = []
-
-if parsed.get("disableAllHooks") is True:
-    reasons.append("disableAllHooks would disable CurDX-Flow stop/recovery hooks and status lines")
-
-agent = parsed.get("agent")
-if isinstance(agent, str):
-    agent = agent.strip()
-    if agent and agent != "flow-orchestrator":
-        reasons.append(f'agent would reroute the main thread through subagent "{agent}"')
-
-enabled_plugins = parsed.get("enabledPlugins")
-if isinstance(enabled_plugins, dict) and enabled_plugins.get("curdx-flow@curdx-flow-marketplace") is False:
-    reasons.append("enabledPlugins would disable curdx-flow@curdx-flow-marketplace for this project")
-
-if reasons:
-    print(" | ".join(reasons))
-PY
-)"
-
-[ -n "$BLOCK_REASONS" ] || exit 0
-
-emit_configchange_block "[CurDX-Flow config-change-guard] Blocking ${SOURCE} update while spec '${ACTIVE}' is in execute: ${BLOCK_REASONS}. Finish or cancel the active implementation first, then reapply the settings change after execute ends."
-exit 0