Feature Flags Audit

Feature Flags Audit

Produce a synthetic inventory of every feature flag declared in the Packmind codebase, with audience targeting, inferred functional descriptions, and orphan detection. The result is a single markdown table the user can scan at a glance.

Context

Packmind uses a custom feature flag system shared by both frontend and backend. There is no third-party library (LaunchDarkly, GrowthBook, PostHog, etc.). Flags are gated by email domain or exact email via a single central registry. There is no org-based, plan-based, or percentage-rollout mechanism — audience targeting is email-based only. One runtime override does exist: an FF_* env kill-switch (see below) can force a flag fully on or off regardless of the email rule.

Canonical source of truth: packages/feature-flags/src/registry.ts (the shared, browser-safe @packmind/feature-flags package)

This file exports:

• Flag key constants ending in _FEATURE_KEY (e.g. SPACES_MANAGEMENT_FEATURE_KEY = 'spaces-management').
• The FeatureFlagKey union of all valid flag string values.
• DEFAULT_FEATURE_DOMAIN_MAP: a Record<string, readonly string[]> mapping each flag's string value to a list of allowed entries. Entries starting with @ are domain rules (e.g. @packmind.com matches any user at that domain). Entries containing @ but not starting with @ are exact email matches.
• The isFeatureFlagEnabled() pure function used at call sites (defined in packages/feature-flags/src/isFeatureFlagEnabled.ts).

The registry is consumed on both sides: the frontend imports it via @packmind/ui (which re-exports the keys, DEFAULT_FEATURE_DOMAIN_MAP, and isFeatureFlagEnabled for back-compat; packages/ui/src/lib/components/content/PMFeatureFlag/PMFeatureFlag.tsx now holds only the PMFeatureFlag React wrapper component). The backend evaluates the same registry through the isFeatureEnabled(flag, { userEmail }) helper in @packmind/node-utils (packages/node-utils/src/featureFlags/isFeatureEnabled.ts), which layers the FF_* env kill-switch on top of the shared email-domain rule.

If a flag is not declared in DEFAULT_FEATURE_DOMAIN_MAP, it does not exist. Do not invent flags.

Workflow

Step 1 — Parse the canonical registry

Read packages/feature-flags/src/registry.ts. Extract:

1. Every exported constant whose name ends with _FEATURE_KEY, along with its string value. The string value is what appears as a key in DEFAULT_FEATURE_DOMAIN_MAP — keep the mapping (constant name ↔ string value) in memory.
2. The full DEFAULT_FEATURE_DOMAIN_MAP object. For each entry, record the flag's string value and its list of allowed domains/emails.

Build an internal list of flags with three fields so far: constant name, string value, audience (array of allowed entries).

Cross-check constants against the map. Every _FEATURE_KEY constant should have a matching entry in DEFAULT_FEATURE_DOMAIN_MAP, and every map entry should correspond to a declared constant. A mismatch is a real misconfiguration:

• A constant declared with no map entry produces a flag that is never enabled for anyone — dead code.
• A map entry whose string value isn't tied to any exported constant means call sites can't import it symbolically and are likely using the inlined string (fragile).

If you find either case, do not drop it from the inventory — include it and surface the mismatch in the Summary section.

Step 2 — Find usages for each flag

For each flag, search the codebase for where it is consumed. Use Grep:

• First pass: search for the constant name (e.g. SPACES_MANAGEMENT_FEATURE_KEY). This is the canonical import form and catches almost all usages.
• Second pass: search for the string value (e.g. 'spaces-management' or "spaces-management") as a safety net. Some usages may inline the string instead of importing the constant.
• Backend pass: search for isFeatureEnabled( (the backend helper call) across apps/api/**, apps/mcp-server/**, apps/cli/**, and packages/**. This is a plain async helper call, not an injected port — so search the function name, not an interface. A call looks like await isFeatureEnabled('some-flag', { userEmail }); the first argument tells you which flag is gated. (Backend call sites may currently be zero — the mechanism exists but the first real consumer may not have landed yet — so finding none is normal, not a bug.)

Scope the search to:

• apps/frontend/src/**
• apps/frontend/app/** — the React Router v7 file-based route tree. Route modules live here (e.g. apps/frontend/app/routes/org.$orgSlug._protected.settings.tsx), not under src/, and they gate flags too (typically via isFeatureFlagEnabled(...) to show/hide nav entries, routes, or whole pages). Omitting this directory will mis-report a live route-gated flag as an orphan.
• apps/api/**, apps/mcp-server/**, apps/cli/** — backend use cases may gate flags via isFeatureEnabled(flag, { userEmail }). Include these so a backend-gated flag is not mis-reported as an orphan.
• packages/** — includes the shared @packmind/feature-flags package (registry) and @packmind/node-utils (the backend helper); the registry definition files are excluded below.

Exclude:

• The canonical registry files themselves: packages/feature-flags/src/registry.ts and packages/feature-flags/src/isFeatureFlagEnabled.ts (plus the package barrel packages/feature-flags/src/index.ts, which only re-exports them).
• The backend helper definition itself: packages/node-utils/src/featureFlags/isFeatureEnabled.ts (it defines isFeatureEnabled; it is not a consumer). Count only call sites of the helper, not its declaration.
• The @packmind/ui back-compat re-export shim: packages/ui/src/lib/components/content/PMFeatureFlag/PMFeatureFlag.tsx (now only the React wrapper + re-exports) and its co-located test file PMFeatureFlag.test.tsx. (The parent barrel at packages/ui/src/lib/components/content/index.ts re-exports for back-compat but is not a real gate.)
• Test and spec files anywhere in the search scope: *.test.*, *.spec.*, and Storybook stories *.stories.*. A usage inside a test doesn't represent shipping behavior and would mislead a reader scanning the "Usage files" column. If a flag is only referenced from tests, treat it as an orphan (see Step 4) and note the test-only state in the description.
• Generated/build artifacts (dist/, node_modules/).

Record the list of files where each flag is actually consumed.

Step 3 — Infer a functional description

For each flag with at least one usage, open 1 to 3 of the most representative usage files and read enough context to understand what the flag actually gates from a user-facing perspective. Use these signals (in rough priority order):

1. The JSX wrapped inside <PMFeatureFlag featureKeys={[FLAG]}>...</PMFeatureFlag> — this is literally what appears or disappears.
2. The branch or value guarded by isFeatureFlagEnabled({ featureKeys: [FLAG] }) — often an "edit" / "create" / "delete" affordance, or an entire route/tab.
3. The component or file name hosting the gated code (e.g. SpacesManagementActions.tsx → space management actions).
4. Button labels, section titles, or surrounding comments near the gate.

Write one short sentence in the functional voice — describe what the user sees (or doesn't see) when the flag is off. Avoid technical framing.

Examples of good descriptions:

• "Reveals the 'Move to space' action and space management UI in the recipes list."
• "Enables inline editing of change proposals in review detail pages."
• "Adds 'Propose change' links from recipes and standards to the webapp review flow."

Examples of bad descriptions (do not write these):

• "Wrapped by the PMFeatureFlag component in SpacesManagementActions.tsx." (tells the reader nothing functional)
• "Feature flag for spaces management." (circular, just re-states the key)

If you cannot form a confident one-liner after reading the usage sites, write a shorter description prefixed with (uncertain) so the user knows to double-check.