feature-flag-management

export const FEATURE_FLAGS = {
  // Existing flags...
  
  NEW_FEATURE: {
    phase: 'DISABLED',  // Start with DISABLED for new features
    description: 'Brief description of what the feature does'
  }
};

import { isFeatureEnabled } from '@/core/features.js';

// In components/views
if (isFeatureEnabled('NEW_FEATURE', 'home')) {
  // Show feature on home page
}

// In services
if (isFeatureEnabled('NEW_FEATURE')) {
  // Enable backend behavior
}

describe('NEW_FEATURE Flag', () => {
  it('should return false when DISABLED', () => {
    expect(isFeatureEnabled('NEW_FEATURE')).toBe(false);
  });
  
  it('should return true when ENABLED', () => {
    // Mock flag as ENABLED
    vi.stubGlobal('localStorage', {
      getItem: () => 'ENABLED'
    });
    
    expect(isFeatureEnabled('NEW_FEATURE')).toBe(true);
  });
  
  it('should respect SETTINGS_ONLY phase', () => {
    // Mock flag as SETTINGS_ONLY
    vi.stubGlobal('localStorage', {
      getItem: () => 'SETTINGS_ONLY'
    });
    
    expect(isFeatureEnabled('NEW_FEATURE', 'settings')).toBe(true);
    expect(isFeatureEnabled('NEW_FEATURE', 'home')).toBe(false);
  });
});

# NEW_FEATURE Feature Flag

**Status:** DISABLED
**Created:** YYYY-MM-DD
**Phase:** DISABLED → SETTINGS_ONLY → ENABLED → REMOVED
**Remove When:** Feature is stable for 2+ weeks

## Purpose
Brief description of why this flag exists.

## Success Metrics
- [ ] Feature works as intended
- [ ] No performance impact
- [ ] User feedback positive
- [ ] Telemetry shows usage

## Removal Plan
When this flag is removed:
- [ ] Remove isFeatureEnabled() checks
- [ ] Simplify conditional logic
- [ ] Update/remove related tests
- [ ] Archive this documentation

| Flag | Status | Remove When | Document |
|------|--------|-------------|----------|
| NEW_FEATURE | DISABLED | 2 weeks after ENABLED | FLAG_NEW_FEATURE.md |

NEW_FEATURE: {
  phase: 'SETTINGS_ONLY',  // Updated
  description: '...'
}

// In SettingsView.js
if (isFeatureEnabled('NEW_FEATURE', 'settings')) {
  // Add settings toggle for user testing
}

NEW_FEATURE: {
  phase: 'ENABLED',  // Updated
  description: '...'
}

# From main repo directory
git worktree add ../saberloop-hygiene hygiene/remove-new-feature-flag

cd ../saberloop-hygiene
npm install

export const FEATURE_FLAGS = {
  // Remove NEW_FEATURE entry
};

// Before
if (isFeatureEnabled('NEW_FEATURE')) {
  doSomething();
}

// After
doSomething(); // Always execute

// Before
if (isFeatureEnabled('NEW_FEATURE')) {
  return enhancedVersion();
} else {
  return basicVersion();
}

// After
return enhancedVersion(); // Always use enhanced

npm test                    # Unit tests
npm run test:e2e            # E2E tests
npm run test:mutation        # Mutation testing
npm run arch:test           # Architecture validation
npm run typecheck           # TypeScript checking

git add -A
git commit -m "refactor(hygiene): remove NEW_FEATURE feature flag

- Remove isFeatureEnabled() checks for NEW_FEATURE
- Simplify conditional logic in [files]
- Remove flag from FEATURE_FLAGS object
- Update/remove related tests
- Archive flag documentation"

git push -u origin hygiene/remove-new-feature-flag

# Create PR after review
gh pr create --title "chore: remove NEW_FEATURE feature flag"

# From main repo
git worktree remove ../saberloop-hygiene
git branch -d hygiene/remove-new-feature-flag

// Phase 1: Settings only (user testing)
if (isFeatureEnabled('NEW_FEATURE', 'settings')) {
  showSettingsToggle();
}

// Phase 2: Limited exposure (telemetry gathering)
if (isFeatureEnabled('NEW_FEATURE', 'home')) {
  showFeatureOnHomePage();
}

// Phase 3: Full release
if (isFeatureEnabled('NEW_FEATURE')) {
  enableFeature();
}

// Use feature flag as guard during development
const enhancedFlow = isFeatureEnabled('NEW_FEATURE') 
  ? newEnhancedImplementation() 
  : existingImplementation();

// After flag removal, the enhanced implementation becomes default
const enhancedFlow = newEnhancedImplementation();

describe('FEATURE_NAME Flag', () => {
  it('should return false when DISABLED', () => {
    // Test default behavior
  });
  
  it('should return true when ENABLED', () => {
    // Test enabled behavior
  });
  
  it('should respect SETTINGS_ONLY phase', () => {
    // Test settings-only behavior
  });
  
  it('should handle test overrides', () => {
    // Test localStorage override capability
  });
});

test('feature flag settings toggle', async ({ page }) => {
  await page.goto('/settings');
  
  // Test settings-only flag visibility
  const toggle = page.locator('[data-testid="new-feature-toggle"]');
  await expect(toggle).toBeVisible();
  
  // Test toggle functionality
  await toggle.click();
  // Verify behavior changes
});

// For debugging, force a flag state
localStorage.setItem('__test_feature_NEW_FEATURE', 'ENABLED');
// Then test isFeatureEnabled('NEW_FEATURE')