feat(cull-feature-flags): cull stale feature flags from a repo, on consent

bin.ts

@@ -72,6 +72,7 @@ import { mcpAnalyticsCommand } from './src/commands/mcp-analytics';
 import { replayVisionCommand } from './src/commands/replay-vision';
 import { aiObservabilityCommand } from './src/commands/ai-observability';
 import { metricsCommand } from './src/commands/metrics';
+import { cullFeatureFlagsCommand } from './src/commands/cull-feature-flags';
 import { auditCommand } from './src/commands/audit';
 import { doctorCommand } from './src/commands/doctor';
 import { migrateCommand } from './src/commands/migrate';
@@ -105,6 +106,7 @@ Wizard.use(basicIntegrationCommand)
   .use(replayVisionCommand)
   .use(aiObservabilityCommand)
   .use(metricsCommand)
+  .use(cullFeatureFlagsCommand)
   .use(cliCommand)
   .use(auditCommand)
   .use(doctorCommand)

e2e-harness/action-registry.ts

@@ -106,6 +106,7 @@ export const ACTION_REGISTRY: Partial<Record<ScreenName, DriverAction[]>> = {
   [ScreenId.SourceMapsIntro]: [confirmSetupAction],
   [ScreenId.MigrationIntro]: [confirmSetupAction],
   [ScreenId.AgentSkillIntro]: [confirmSetupAction],
+  [ScreenId.CullIntro]: [confirmSetupAction],
   [ScreenId.AiObservabilityIntro]: [confirmSetupAction],
   [ScreenId.MetricsIntro]: [confirmSetupAction],
   [ScreenId.AuditIntro]: [confirmSetupAction],

e2e-harness/e2e-profile.ts

@@ -281,6 +281,7 @@ export function decideE2eAction(
     case ScreenId.RevenueIntro:
     case ScreenId.MigrationIntro:
     case ScreenId.AgentSkillIntro:
+    case ScreenId.CullIntro:
     case ScreenId.AiObservabilityIntro:
     case ScreenId.MetricsIntro:
     case ScreenId.AuditIntro:

scripts/tui-host.no-jest.ts

@@ -17,6 +17,7 @@ import fs from 'fs';
 import net from 'net';
 import { spawnSync } from 'child_process';
 import { startTUI } from '@ui/tui/start-tui';
+import { initLocalDev } from '@lib/local-dev';
 import { VERSION } from '@lib/version';
 import {
   Program,
@@ -195,6 +196,15 @@ async function main() {
   // requires-interactive-mode the moment they need to ask a question.
   process.env.WIZARD_ASK_AUTODRIVE = '1';
 
+  // The session flags below only describe the run; `getSkillsBaseUrl` reads
+  // the process-wide targets that the CLI middleware normally sets from argv.
+  initLocalDev({
+    localDev: process.env.POSTHOG_WIZARD_LOCAL_DEV === 'true',
+    localMcp: envFlag('POSTHOG_WIZARD_LOCAL_MCP'),
+    localContextMill: envFlag('POSTHOG_WIZARD_LOCAL_CONTEXT_MILL'),
+    localPosthog: envFlag('POSTHOG_WIZARD_LOCAL_POSTHOG'),
+  });
+
   const { store } = startTUI(VERSION, programId);
   store.session = buildSession({
     installDir: process.env.APP_DIR!,

src/__tests__/programs-cli.test.ts

@@ -22,6 +22,7 @@ import { auditCommand } from '../commands/audit';
 import { migrateCommand } from '../commands/migrate';
 import { mcpAnalyticsCommand } from '../commands/mcp-analytics';
 import { replayVisionCommand } from '../commands/replay-vision';
+import { cullFeatureFlagsCommand } from '../commands/cull-feature-flags';
 import { revenueCommand } from '../commands/revenue';
 import { warehouseCommand } from '../commands/warehouse';
 import { uploadSourcemapsCommand } from '../commands/upload-sourcemaps';
@@ -91,6 +92,11 @@ describe('top-level command shapes', () => {
     expect(replayVisionCommand.children).toBeUndefined();
   });
 
+  test('cull-feature-flags is a flat skill command', () => {
+    expect(cullFeatureFlagsCommand.name).toBe('cull-feature-flags');
+    expect(cullFeatureFlagsCommand.children).toBeUndefined();
+  });
+
   test('warehouse is a flat skill command', () => {
     expect(warehouseCommand.name).toBe('warehouse');
     expect(warehouseCommand.children).toBeUndefined();

src/commands/cull-feature-flags.ts

@@ -0,0 +1,8 @@
+import { cullFeatureFlagsConfig } from '@lib/programs/cull-feature-flags/index';
+
+import type { Command } from './command';
+import { nativeCommandFactory } from './factories/native-command-factory';
+
+export const cullFeatureFlagsCommand: Command = nativeCommandFactory(
+  cullFeatureFlagsConfig,
+);

src/lib/agent/runner/switchboard/index.ts

@@ -134,6 +134,7 @@ export const PROGRAM_BINDINGS: Partial<Record<ProgramId, ProgramBinding>> = {
   'events-audit': DEFAULT_BINDING,
   'posthog-doctor': DEFAULT_BINDING,
   'web-analytics-doctor': DEFAULT_BINDING,
+  'cull-feature-flags': DEFAULT_BINDING,
   migration: DEFAULT_BINDING,
   'self-driving': DEFAULT_BINDING,
   'agent-skill': DEFAULT_BINDING,

src/lib/errors/catalog.ts

@@ -117,6 +117,12 @@ export const ERROR_CATALOG: Record<ErrorCode, ErrorCatalogEntry> = {
     retry: 'no',
     description: 'The project platform has no matching skill variant.',
   },
+  [ErrorCodes.DetectDirtyWorkingTree]: {
+    group: 'detect',
+    retry: 'yes',
+    description:
+      'The program edits project files and needs a clean git working tree so the edits stay revertable on their own.',
+  },
   [ErrorCodes.DetectNoPosthogSdk]: {
     group: 'detect',
     retry: 'no',

src/lib/errors/codes.ts

@@ -22,6 +22,7 @@ export const ErrorCodes = {
   DetectNoFramework: 'PHW_DETECT_NO_FRAMEWORK',
   DetectUnsupportedVersion: 'PHW_DETECT_UNSUPPORTED_VERSION',
   DetectUnsupportedPlatform: 'PHW_DETECT_UNSUPPORTED_PLATFORM',
+  DetectDirtyWorkingTree: 'PHW_DETECT_DIRTY_WORKING_TREE',
   DetectNoPosthogSdk: 'PHW_DETECT_NO_POSTHOG_SDK',
   DetectNoProjectFiles: 'PHW_DETECT_NO_PROJECT_FILES',
   DetectNoSources: 'PHW_DETECT_NO_SOURCES',

src/lib/oauth/program-scopes.ts

@@ -280,6 +280,9 @@ const PROGRAM_SCOPE_ADDITIONS: Partial<Record<ProgramId, readonly string[]>> = {
   ],
   slack: CONNECT_SLACK_SCOPE_ADDITIONS,
   'replay-vision': REPLAY_VISION_SCOPE_ADDITIONS,
+  // Disabling a flag needs feature_flag:write; the agent-skill set already
+  // carries the read/write pair.
+  'cull-feature-flags': AGENT_SKILL_SCOPE_ADDITIONS,
 };
 
 /**

src/lib/programs/__tests__/cull-feature-flags-classify.test.ts

@@ -0,0 +1,256 @@
+import { classifyFlags } from '@lib/programs/cull-feature-flags/classify';
+import type { FlagScanResult } from '@lib/programs/cull-feature-flags/scan';
+import type { FeatureFlag } from '@lib/programs/cull-feature-flags/types';
+
+let nextFlagId = 1;
+
+function flag(overrides: Partial<FeatureFlag> & { key: string }): FeatureFlag {
+  return {
+    id: nextFlagId++,
+    active: true,
+    archived: false,
+    deleted: false,
+    status: 'ACTIVE',
+    filters: { groups: [{ rollout_percentage: 50, properties: [] }] },
+    experiment_set: [],
+    is_remote_configuration: false,
+    has_encrypted_payloads: false,
+    ...overrides,
+  };
+}
+
+function rollout(percentage: number | null): FeatureFlag['filters'] {
+  return { groups: [{ rollout_percentage: percentage, properties: [] }] };
+}
+
+function site(key: string, file: string, line = 1) {
+  return { key, file, line, api: 'useFeatureFlagEnabled' };
+}
+
+function scan(overrides: Partial<FlagScanResult> = {}): FlagScanResult {
+  return {
+    callSites: [],
+    dynamicSites: [],
+    mentionSites: [],
+    usesBulkEvaluation: false,
+    reachableFiles: ['src/app/page.tsx', 'src/lib/flags.ts'],
+    filesScanned: 2,
+    truncated: false,
+    ...overrides,
+  };
+}
+
+function bucketOf(
+  flags: FeatureFlag[],
+  scanResult: FlagScanResult,
+  key: string,
+) {
+  const match = classifyFlags(flags, scanResult).find((c) => c.key === key);
+  return match ? [match.bucket, match.verdict] : undefined;
+}
+
+describe('classifyFlags', () => {
+  test('fully rolled out flag with a call site is stale', () => {
+    const flags = [flag({ key: 'new-checkout', filters: rollout(100) })];
+    const result = scan({
+      callSites: [site('new-checkout', 'src/app/page.tsx')],
+    });
+    expect(bucketOf(flags, result, 'new-checkout')).toEqual([
+      'fully-rolled-out',
+      'stale',
+    ]);
+  });
+
+  test('rollout null counts as 100 percent', () => {
+    const flags = [flag({ key: 'k', filters: rollout(null) })];
+    const result = scan({ callSites: [site('k', 'src/app/page.tsx')] });
+    expect(bucketOf(flags, result, 'k')).toEqual(['fully-rolled-out', 'stale']);
+  });
+
+  test('flag at 0% everywhere is stale but flagged as a possible rollback', () => {
+    const flags = [flag({ key: 'beta-dashboard', filters: rollout(0) })];
+    const result = scan({
+      callSites: [site('beta-dashboard', 'src/app/page.tsx')],
+    });
+    expect(bucketOf(flags, result, 'beta-dashboard')).toEqual([
+      'never-enabled',
+      'stale',
+    ]);
+    const [candidate] = classifyFlags(flags, result);
+    expect(candidate.area).toBe('Off for everyone');
+    expect(candidate.reason).toContain('may be a rollback');
+  });
+
+  test('archived flag still referenced is stale, archived and unreferenced is skipped', () => {
+    const flags = [
+      flag({
+        key: 'legacy-banner',
+        active: false,
+        archived: true,
+        filters: rollout(100),
+      }),
+      flag({ key: 'gone', active: false, archived: true }),
+    ];
+    const result = scan({
+      callSites: [site('legacy-banner', 'src/app/page.tsx')],
+    });
+    expect(bucketOf(flags, result, 'legacy-banner')).toEqual([
+      'archived-still-referenced',
+      'stale',
+    ]);
+    expect(bucketOf(flags, result, 'gone')).toBeUndefined();
+  });
+
+  test('disabled flag still referenced is stale', () => {
+    const flags = [flag({ key: 'off', active: false })];
+    const result = scan({ callSites: [site('off', 'src/app/page.tsx')] });
+    expect(bucketOf(flags, result, 'off')).toEqual([
+      'disabled-but-referenced',
+      'stale',
+    ]);
+  });
+
+  test('unreferenced flag is stale, comment-only mention is its own bucket', () => {
+    const flags = [
+      flag({ key: 'pricing-v2-experiment' }),
+      flag({ key: 'holiday-promo' }),
+    ];
+    const result = scan({
+      mentionSites: [
+        { key: 'holiday-promo', file: 'src/app/page.tsx', line: 17 },
+      ],
+    });
+    expect(bucketOf(flags, result, 'pricing-v2-experiment')).toEqual([
+      'unreferenced',
+      'stale',
+    ]);
+    expect(bucketOf(flags, result, 'holiday-promo')).toEqual([
+      'unreferenced-comment-only',
+      'stale',
+    ]);
+  });
+
+  test('call site only in an unreachable file is dead code, even when fully rolled out', () => {
+    const flags = [flag({ key: 'legacy-theme', filters: rollout(100) })];
+    const result = scan({
+      callSites: [site('legacy-theme', 'src/lib/unused/legacyTheme.ts')],
+    });
+    expect(bucketOf(flags, result, 'legacy-theme')).toEqual([
+      'dead-code-reference',
+      'stale',
+    ]);
+  });
+
+  test('key evaluated in code with no PostHog flag is stale', () => {
+    const result = scan({
+      callSites: [site('old-pricing-test', 'src/app/page.tsx')],
+    });
+    const [only] = classifyFlags([], result);
+    expect([only.bucket, only.verdict, only.flagId]).toEqual([
+      'deleted-still-referenced',
+      'stale',
+      undefined,
+    ]);
+  });
+
+  test('three or more files evaluating the same key directly is a warning', () => {
+    const flags = [flag({ key: 'ai-assistant' })];
+    const result = scan({
+      callSites: [
+        site('ai-assistant', 'src/app/page.tsx'),
+        site('ai-assistant', 'src/components/A.tsx'),
+        site('ai-assistant', 'src/components/B.tsx'),
+      ],
+      reachableFiles: [
+        'src/app/page.tsx',
+        'src/components/A.tsx',
+        'src/components/B.tsx',
+      ],
+    });
+    expect(bucketOf(flags, result, 'ai-assistant')).toEqual([
+      'multi-callsite-no-wrapper',
+      'warning',
+    ]);
+  });
+
+  test('partial rollout and multivariate flags with call sites are healthy', () => {
+    const flags = [
+      flag({ key: 'dark-mode', filters: rollout(30) }),
+      flag({
+        key: 'signup-cta-variant',
+        filters: {
+          groups: [{ rollout_percentage: 100, properties: [] }],
+          multivariate: { variants: [{ key: 'a' }, { key: 'b' }] },
+        },
+      }),
+      flag({
+        key: 'gated',
+        filters: {
+          groups: [{ rollout_percentage: 100, properties: [{ key: 'email' }] }],
+        },
+      }),
+    ];
+    const result = scan({
+      callSites: [
+        site('dark-mode', 'src/lib/flags.ts'),
+        site('signup-cta-variant', 'src/app/page.tsx'),
+        site('gated', 'src/app/page.tsx'),
+      ],
+    });
+    expect(bucketOf(flags, result, 'dark-mode')).toEqual([
+      'healthy',
+      'healthy',
+    ]);
+    expect(bucketOf(flags, result, 'signup-cta-variant')).toEqual([
+      'healthy',
+      'healthy',
+    ]);
+    expect(bucketOf(flags, result, 'gated')).toEqual(['healthy', 'healthy']);
+  });
+
+  test('experiment, remote config and encrypted payload flags are guarded to healthy', () => {
+    const flags = [
+      flag({ key: 'exp', filters: rollout(100), experiment_set: [1] }),
+      flag({ key: 'rc', filters: rollout(100), is_remote_configuration: true }),
+      flag({ key: 'enc', filters: rollout(100), has_encrypted_payloads: true }),
+    ];
+    const result = scan({
+      callSites: [
+        site('exp', 'src/app/page.tsx'),
+        site('rc', 'src/app/page.tsx'),
+      ],
+    });
+    const byKey = Object.fromEntries(
+      classifyFlags(flags, result).map((c) => [c.key, c]),
+    );
+    expect(byKey.exp.bucket).toBe('healthy');
+    expect(byKey.exp.reason).toContain('backs an experiment');
+    expect(byKey.rc.bucket).toBe('healthy');
+    expect(byKey.enc.bucket).toBe('healthy');
+  });
+
+  test('deleted flags are ignored and candidates carry ledger-ready fields', () => {
+    const flags = [
+      flag({ key: 'zombie', deleted: true }),
+      flag({
+        key: 'new-checkout',
+        name: 'New checkout',
+        filters: rollout(100),
+        status: 'ACTIVE',
+      }),
+    ];
+    const result = scan({
+      callSites: [site('new-checkout', 'src/app/page.tsx', 20)],
+    });
+    const candidates = classifyFlags(flags, result);
+    expect(candidates.map((c) => c.key)).toEqual(['new-checkout']);
+    expect(candidates[0]).toMatchObject({
+      proposedAction: 'keep on path, drop check, disable flag',
+      reason: 'rollout 100%, ACTIVE',
+      flagName: 'New checkout',
+      callSites: [
+        { file: 'src/app/page.tsx', line: 20, api: 'useFeatureFlagEnabled' },
+      ],
+    });
+  });
+});