chore: add Cursor rule for version-gated feature flags

Track repo-specific Cursor rule so contributors use validatedVersionGatedFeatureFlag
from app/util/remoteFeatureFlag instead of duplicating version-check helpers.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: asalsys

.cursor/rules/version-gated-feature-flags.mdc

@@ -0,0 +1,95 @@
+---
+description: Use shared version-gated feature flag helpers; never duplicate hasMinimumRequiredVersion or validatedVersionGatedFeatureFlag
+globs: app/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# Version-Gated Feature Flags
+
+## Canonical source (SSOT)
+
+All version-gated feature flag logic lives in `app/util/remoteFeatureFlag/index.ts`:
+
+- `validatedVersionGatedFeatureFlag` — preferred for remote flags shaped as `{ enabled, minimumVersion }` (or progressive-rollout wrappers)
+- `hasMinimumRequiredVersion` — version comparison only; import when needed, never redefine
+
+## Required patterns
+
+### ✅ Use `validatedVersionGatedFeatureFlag` in selectors
+
+```typescript
+import { validatedVersionGatedFeatureFlag, VersionGatedFeatureFlag } from '../../../util/remoteFeatureFlag';
+
+export const selectMyFeatureEnabled = createSelector(
+  selectRemoteFeatureFlags,
+  (remoteFeatureFlags) => {
+    const remoteFlag = remoteFeatureFlags?.myFeature as unknown as VersionGatedFeatureFlag;
+    return validatedVersionGatedFeatureFlag(remoteFlag) ?? false;
+  },
+);
+```
+
+### ✅ Non-standard flag shapes — map, don't duplicate
+
+Configs that use `active` instead of `enabled` (e.g. `depositConfig`) must map to the canonical shape and call the shared helper:
+
+```typescript
+import { validatedVersionGatedFeatureFlag } from '../../../util/remoteFeatureFlag';
+
+return (
+  validatedVersionGatedFeatureFlag({
+    enabled: depositConfig.active ?? false,
+    minimumVersion: depositConfig.minimumVersion ?? '',
+  }) ?? false
+);
+```
+
+### ✅ Import `hasMinimumRequiredVersion` only from the util
+
+```typescript
+import { hasMinimumRequiredVersion } from '../../../util/remoteFeatureFlag';
+```
+
+Never copy the `compare-versions` + `getVersion` pattern into feature modules.
+
+## Forbidden patterns
+
+### ❌ Do not define local version-gating helpers
+
+```typescript
+// FORBIDDEN — duplicate of app/util/remoteFeatureFlag
+function hasMinimumRequiredVersion(minVersion: string) { ... }
+const validatedVersionGatedFeatureFlag = (flag: unknown) => { ... }
+```
+
+### ❌ Do not inline version checks for feature flags
+
+```typescript
+// FORBIDDEN
+import { getVersion } from 'react-native-device-info';
+import compareVersions from 'compare-versions';
+
+const ok = compareVersions.compare(getVersion(), flag.minimumVersion, '>=');
+```
+
+### ❌ Do not add duplicate utils under feature folders
+
+Do not create files like:
+
+- `app/components/UI/**/utils/hasMinimumRequiredVersion.ts`
+- `app/core/redux/slices/**/hasMinimumRequiredVersion.ts`
+
+## Where logic belongs
+
+| Layer | Responsibility |
+|-------|----------------|
+| `RemoteFeatureFlagController` | Fetch/store raw flags — **no** client version gating |
+| `app/util/remoteFeatureFlag` | Version comparison + `validatedVersionGatedFeatureFlag` |
+| Selectors (`featureFlagController`, `**/selectors/featureFlags`) | Call shared helpers; return `boolean` |
+| Hooks / components | `useSelector(selectXEnabled)` — not local version math |
+
+## Enforcement
+
+- **REJECT** new local definitions of `hasMinimumRequiredVersion` or `validatedVersionGatedFeatureFlag`
+- **REJECT** new `compare-versions` + `getVersion` usage for feature-flag gating outside `app/util/remoteFeatureFlag`
+- **REQUIRE** imports from `app/util/remoteFeatureFlag` for all version-gated flag checks

.gitignore

@@ -217,10 +217,12 @@ release-signoffs.json
 .claude/skills/
 .claude/commands/
 .agents/skills/
-.cursor/rules/
+.cursor/rules/*
+!.cursor/rules/*.mdc
 .cursor/skills/
 .cursor/commands/
 # Carve-outs: IDE/bugbot config that must stay tracked
+!.cursor/rules/*.mdc
 !.cursor/BUGBOT.md
 !.cursor/hooks.json
 !.cursor/worktrees.json

AGENTS.md

@@ -115,6 +115,7 @@ General coding, UI, deeplink-handler, and PR-creation guidance now lives in the
 - **Components**: Design system first → `component-library` second → custom last
 - **Styling**: Use `useTailwind()` hook, `Box`/`Text` components, design tokens
 - **Testing**: Mandatory for all code, AAA pattern, mock everything external
+- **Version-gated feature flags**: Use shared helpers from `app/util/remoteFeatureFlag` — see [`.cursor/rules/version-gated-feature-flags.mdc`](.cursor/rules/version-gated-feature-flags.mdc)
 - **Commands**: ONLY use yarn (never npm/npx)
 
 ## Environment Setup