Antigravity × Feature Flags & Progressive Delivery — Reduce Release Risk to Near Zero with AI Agents

// feature-flags.ts — Type-safe Feature Flag system foundation
// Ask Antigravity: "Create a type-safe Feature Flag manager"
// and it will auto-generate a structure like this
 
type FlagType = 'release' | 'experiment' | 'ops' | 'permission';
 
interface FeatureFlag<T = boolean> {
  key: string;
  type: FlagType;
  defaultValue: T;
  description: string;
  owner: string;        // Responsible team (for lifecycle management)
  createdAt: string;
  expiresAt?: string;   // Release flags must always have an expiry
}
 
interface FlagEvaluationContext {
  userId: string;
  userAttributes: Record<string, string | number | boolean>;
  environment: 'production' | 'staging' | 'development';
  percentage?: number;  // For staged rollouts (0-100)
}
 
// Centralized flag definitions
const FLAGS = {
  newCheckoutFlow: {
    key: 'new-checkout-flow',
    type: 'release' as FlagType,
    defaultValue: false,
    description: 'New checkout flow UI',
    owner: 'payment-team',
    createdAt: '2026-03-30',
    expiresAt: '2026-04-30', // Must evaluate within 1 month
  },
  pricingExperiment: {
    key: 'pricing-experiment',
    type: 'experiment' as FlagType,
    defaultValue: 'control', // 'control' | 'variant-a' | 'variant-b'
    description: 'Pricing page A/B test',
    owner: 'growth-team',
    createdAt: '2026-03-30',
  },
  emergencyReadOnly: {
    key: 'emergency-read-only',
    type: 'ops' as FlagType,
    defaultValue: false,
    description: 'Emergency read-only mode',
    owner: 'sre-team',
    createdAt: '2026-03-30',
  },
} as const;
 
// Output:
// FLAGS.newCheckoutFlow.key → 'new-checkout-flow'
// FLAGS.pricingExperiment.type → 'experiment'

<!-- .antigravity/rules/feature-flags.md -->
# Feature Flag Rules
 
## Naming Convention
- Use kebab-case: `new-checkout-flow`
- Prefix by type: `exp-` (experiment), `ops-` (operations), `perm-` (permission)
- Release flags have no prefix
 
## Required Fields
- All flags must have `owner` and `createdAt`
- Release flags must have `expiresAt` (max 30 days)
- Experiment flags must define `variants` and `metrics`
 
## Flag Removal
- Expired flags must be removed in the next sprint
- Remove related test code when removing a flag

// hooks/useFeatureFlag.ts — Custom hook generated by Antigravity
// Agent prompt: "Create a Feature Flag hook using Cloudflare KV as backend"
 
import { useEffect, useState } from 'react';
 
interface FlagConfig {
  key: string;
  defaultValue: boolean;
  userId?: string;
}
 
export function useFeatureFlag({ key, defaultValue, userId }: FlagConfig): {
  enabled: boolean;
  loading: boolean;
} {
  const [enabled, setEnabled] = useState(defaultValue);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    const controller = new AbortController();
 
    async function fetchFlag() {
      try {
        const params = new URLSearchParams({ key });
        if (userId) params.append('userId', userId);
 
        const res = await fetch(`/api/flags?${params}`, {
          signal: controller.signal,
        });
 
        if (res.ok) {
          const data = await res.json();
          setEnabled(data.enabled);
        }
      } catch (err) {
        if (err instanceof DOMException && err.name === 'AbortError') return;
        console.warn(`Flag evaluation failed for ${key}, using default`);
      } finally {
        setLoading(false);
      }
    }
 
    fetchFlag();
    return () => controller.abort();
  }, [key, userId]);
 
  return { enabled, loading };
}
 
// Usage in a component:
// const { enabled: showNewUI, loading } = useFeatureFlag({
//   key: 'new-checkout-flow',
//   defaultValue: false,
//   userId: session.userId,
// });
// if (loading) return <Skeleton />;
// return showNewUI ? <NewCheckout /> : <LegacyCheckout />;

// api/flags/route.ts — Edge-powered flag evaluation API
// Have Antigravity generate the scaffold, then add business logic
 
import { NextRequest, NextResponse } from 'next/server';
import { getCloudflareContext } from '@opennextjs/cloudflare';
 
interface FlagRule {
  enabled: boolean;
  percentage?: number;     // Staged rollout: 0-100
  allowList?: string[];    // Specific user whitelist
  startDate?: string;      // Scheduled release start
  endDate?: string;        // Scheduled release end
}
 
function hashUserId(userId: string, flagKey: string): number {
  // Deterministic hash: same user always gets the same result
  let hash = 0;
  const input = `${userId}:${flagKey}`;
  for (let i = 0; i < input.length; i++) {
    const char = input.charCodeAt(i);
    hash = ((hash << 5) - hash) + char;
    hash = hash & hash; // Convert to 32-bit integer
  }
  return Math.abs(hash) % 100;
}
 
export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const key = searchParams.get('key');
  const userId = searchParams.get('userId');
 
  if (!key) {
    return NextResponse.json({ error: 'key is required' }, { status: 400 });
  }
 
  try {
    const { env } = await getCloudflareContext();
    const raw = await env.FLAGS_KV.get(`flag:${key}`);
 
    if (!raw) {
      return NextResponse.json({ enabled: false, source: 'default' });
    }
 
    const rule: FlagRule = JSON.parse(raw);
 
    // Allowlist check
    if (userId && rule.allowList?.includes(userId)) {
      return NextResponse.json({ enabled: true, source: 'allowList' });
    }
 
    // Schedule check
    const now = new Date();
    if (rule.startDate && now < new Date(rule.startDate)) {
      return NextResponse.json({ enabled: false, source: 'scheduled' });
    }
    if (rule.endDate && now > new Date(rule.endDate)) {
      return NextResponse.json({ enabled: false, source: 'expired' });
    }
 
    // Percentage-based rollout
    if (rule.percentage !== undefined && userId) {
      const bucket = hashUserId(userId, key);
      const enabled = bucket < rule.percentage;
      return NextResponse.json({ enabled, source: 'percentage', bucket });
    }
 
    return NextResponse.json({ enabled: rule.enabled, source: 'rule' });
  } catch (err) {
    console.error('Flag evaluation error:', err);
    return NextResponse.json({ enabled: false, source: 'error' });
  }
}
 
// Example KV data:
// key: "flag:new-checkout-flow"
// value: {"enabled":true,"percentage":10,"allowList":["user-beta-1"]}
// → Shows new UI to 10% of users + beta testers

// scripts/bucket-independence.mjs — runs as-is on local Node.js
import crypto from 'crypto';
 
const N = 100_000;
const users = Array.from({ length: N }, () => crypto.randomUUID());
const keys = ['new-checkout-flow', 'exp-onboarding-copy', 'ops-image-pipeline',
              'perm-beta-widgets', 'release-dark-mode'];
 
// The 31-multiplier hash used earlier in this article
const naive = (u, k) => {
  let h = 0; const s = `${u}:${k}`;
  for (let i = 0; i < s.length; i++) { h = ((h << 5) - h) + s.charCodeAt(i); h = h & h; }
  return Math.abs(h) % 100;
};
 
const cohorts = keys.map(k => new Set(users.filter(u => naive(u, k) < 10)));
for (let i = 0; i < keys.length; i++) {
  for (let j = i + 1; j < keys.length; j++) {
    let overlap = 0;
    for (const u of cohorts[i]) if (cohorts[j].has(u)) overlap++;
    console.log(keys[i], 'x', keys[j], (overlap / N * 100).toFixed(2) + '%');
  }
}

// api/flags/lib/bucket.ts — bucket assignment that stays independent across flags
function fnv1a(input: string): number {
  let hash = 0x811c9dc5;
  for (let i = 0; i < input.length; i++) {
    hash ^= input.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash >>> 0;
}
 
// The murmur3 finalizer: mixes high bits down into the low bits
function avalanche(hash: number): number {
  hash ^= hash >>> 16;
  hash = Math.imul(hash, 0x85ebca6b) >>> 0;
  hash ^= hash >>> 13;
  hash = Math.imul(hash, 0xc2b2ae35) >>> 0;
  hash ^= hash >>> 16;
  return hash >>> 0;
}
 
export function bucketFor(userId: string, flagKey: string): number {
  // Put the flag key first, then mix before taking the modulo
  return avalanche(fnv1a(`${flagKey}:${userId}`)) % 100;
}

// scripts/canary-rollout.ts — Rollout script managed by Antigravity agents
// Prompt: "Create an automated canary rollout script"
 
interface RolloutStage {
  percentage: number;
  duration: string;      // How long to maintain this stage
  successCriteria: {
    maxErrorRate: number;  // Maximum acceptable error rate (%)
    maxLatencyP99: number; // Maximum P99 latency (ms)
    minSuccessRate: number; // Minimum success rate (%)
  };
}
 
const ROLLOUT_PLAN: RolloutStage[] = [
  {
    percentage: 1,
    duration: '30m',
    successCriteria: { maxErrorRate: 0.1, maxLatencyP99: 500, minSuccessRate: 99.9 },
  },
  {
    percentage: 5,
    duration: '1h',
    successCriteria: { maxErrorRate: 0.5, maxLatencyP99: 800, minSuccessRate: 99.5 },
  },
  {
    percentage: 25,
    duration: '2h',
    successCriteria: { maxErrorRate: 1.0, maxLatencyP99: 1000, minSuccessRate: 99.0 },
  },
  {
    percentage: 50,
    duration: '4h',
    successCriteria: { maxErrorRate: 1.0, maxLatencyP99: 1000, minSuccessRate: 99.0 },
  },
  {
    percentage: 100,
    duration: 'permanent',
    successCriteria: { maxErrorRate: 1.0, maxLatencyP99: 1200, minSuccessRate: 98.5 },
  },
];
 
async function evaluateMetrics(flagKey: string): Promise<{
  errorRate: number;
  latencyP99: number;
  successRate: number;
}> {
  // In practice, fetch from monitoring tools (Grafana, Datadog, etc.)
  // Antigravity generates implementation matching your monitoring stack
  const response = await fetch(`https://monitoring.example.com/api/metrics`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `feature_flag{key="${flagKey}"}`,
      range: '15m',
    }),
  });
  return response.json();
}
 
async function updateFlagPercentage(flagKey: string, percentage: number): Promise<void> {
  // Update the flag value in Cloudflare KV
  await fetch(`https://api.cloudflare.com/client/v4/accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/flag:${flagKey}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer YOUR_API_KEY`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ enabled: true, percentage }),
  });
}
 
async function rollback(flagKey: string, reason: string): Promise<void> {
  console.error(`🚨 ROLLBACK: ${flagKey} — ${reason}`);
  await updateFlagPercentage(flagKey, 0);
  // Send Slack / Discord notification
  // Ask Antigravity: "Add Slack notification support" for auto-implementation
}
 
async function executeRollout(flagKey: string): Promise<void> {
  for (const stage of ROLLOUT_PLAN) {
    console.log(`📊 Stage: ${stage.percentage}% rollout`);
    await updateFlagPercentage(flagKey, stage.percentage);
 
    // Wait for the specified duration to collect metrics
    const waitMs = parseDuration(stage.duration);
    if (waitMs === Infinity) break; // permanent = final stage
 
    await new Promise(resolve => setTimeout(resolve, waitMs));
 
    // Evaluate metrics
    const metrics = await evaluateMetrics(flagKey);
 
    if (metrics.errorRate > stage.successCriteria.maxErrorRate) {
      await rollback(flagKey, `Error rate ${metrics.errorRate}% exceeds threshold ${stage.successCriteria.maxErrorRate}%`);
      return;
    }
    if (metrics.latencyP99 > stage.successCriteria.maxLatencyP99) {
      await rollback(flagKey, `P99 latency ${metrics.latencyP99}ms exceeds threshold ${stage.successCriteria.maxLatencyP99}ms`);
      return;
    }
    if (metrics.successRate < stage.successCriteria.minSuccessRate) {
      await rollback(flagKey, `Success rate ${metrics.successRate}% below threshold ${stage.successCriteria.minSuccessRate}%`);
      return;
    }
 
    console.log(`✅ Stage ${stage.percentage}% passed — metrics OK`);
  }
 
  console.log('🎉 Rollout complete — 100% traffic');
}
 
function parseDuration(d: string): number {
  if (d === 'permanent') return Infinity;
  const match = d.match(/^(\d+)(m|h)$/);
  if (!match) throw new Error(`Invalid duration: ${d}`);
  const [, num, unit] = match;
  return parseInt(num) * (unit === 'h' ? 3600000 : 60000);
}
 
// Execution:
// executeRollout('new-checkout-flow');
// → 1% → 5% → 25% → 50% → 100% staged rollout
// → Automatic metrics check at each stage; instant rollback on anomalies

// lib/ab-testing.ts — A/B test management module
// Prompt: "Implement an A/B testing library with statistical significance testing"
 
interface Experiment {
  key: string;
  variants: string[];     // ['control', 'variant-a', 'variant-b']
  trafficAllocation: number; // Traffic percentage in the experiment (0-100)
  metrics: string[];      // Metric names to track
}
 
interface ExperimentResult {
  variant: string;
  sampleSize: number;
  conversions: number;
  conversionRate: number;
}
 
// Z-test for statistical significance
function calculateZScore(
  control: ExperimentResult,
  treatment: ExperimentResult
): { zScore: number; pValue: number; significant: boolean } {
  const p1 = control.conversionRate;
  const p2 = treatment.conversionRate;
  const n1 = control.sampleSize;
  const n2 = treatment.sampleSize;
 
  // Pooled proportion
  const pooled = (control.conversions + treatment.conversions) / (n1 + n2);
  const se = Math.sqrt(pooled * (1 - pooled) * (1 / n1 + 1 / n2));
 
  if (se === 0) return { zScore: 0, pValue: 1, significant: false };
 
  const zScore = (p2 - p1) / se;
 
  // Two-tailed p-value (approximation)
  const pValue = 2 * (1 - normalCDF(Math.abs(zScore)));
 
  return {
    zScore,
    pValue,
    significant: pValue < 0.05, // 95% confidence level
  };
}
 
function normalCDF(x: number): number {
  // Standard normal CDF (Abramowitz & Stegun approximation)
  const t = 1 / (1 + 0.2316419 * Math.abs(x));
  const d = 0.3989422804014327;
  const p =
    d * Math.exp(-x * x / 2) *
    (t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274)))));
  return x > 0 ? 1 - p : p;
}
 
// Pre-calculate required sample size
function requiredSampleSize(
  baselineRate: number,        // Current conversion rate
  minimumDetectableEffect: number, // Smallest effect you want to detect
  power: number = 0.8,         // Statistical power (typically 80%)
  alpha: number = 0.05         // Significance level (typically 5%)
): number {
  const zAlpha = 1.96;  // z-value for α=0.05
  const zBeta = 0.842;  // z-value for β=0.2 (power=0.8)
  const p1 = baselineRate;
  const p2 = baselineRate + minimumDetectableEffect;
  const pBar = (p1 + p2) / 2;
 
  const n = Math.ceil(
    (Math.pow(zAlpha + zBeta, 2) * (p1 * (1 - p1) + p2 * (1 - p2))) /
    Math.pow(p2 - p1, 2)
  );
 
  return n;
}
 
// Output:
// requiredSampleSize(0.03, 0.005)
// → Approximately 14,752 (samples needed per variant)
// To detect a 0.5 percentage point improvement from a 3% baseline CVR,
// you need ~15,000 samples per variant

// scripts/release-risk-analysis.ts — AI-driven release risk analysis
// Run in Antigravity's Agent mode for full codebase-aware analysis
 
interface RiskFactor {
  category: 'code' | 'dependency' | 'config' | 'database' | 'infrastructure';
  severity: 'low' | 'medium' | 'high' | 'critical';
  description: string;
  mitigation: string;
}
 
interface ReleaseRiskReport {
  overallRisk: 'low' | 'medium' | 'high' | 'critical';
  factors: RiskFactor[];
  recommendedRolloutStrategy: string;
  flagsToCreate: string[];
  testsCoverage: {
    newCode: number;      // Test coverage for new code
    modifiedCode: number; // Test coverage for modified code
  };
}
 
// Prompt template for Antigravity agent (add to AGENTS.md)
const RISK_ANALYSIS_PROMPT = `
## Release Risk Analysis Task
 
Analyze the code diff from the following perspectives and generate a risk report:
 
1. **Code Risk**
   - Impact scope (number of files, functions)
   - Complexity changes (cyclomatic complexity)
   - Error handling completeness
   - Type safety verification
 
2. **Dependency Risk**
   - New external dependencies added
   - Major version updates
   - Security advisories
 
3. **Configuration Risk**
   - Environment variable additions/changes
   - Infrastructure configuration changes
   - Feature Flag additions
 
4. **Database Risk**
   - Migrations present
   - Breaking schema changes
   - Data backfill requirements
 
5. **Recommended Rollout Strategy**
   - Staged rollout plan based on risk level
   - List of Feature Flags to create
   - Rollback procedure proposals
`;
 
// GitHub Actions config for automated risk analysis
// Have Antigravity generate .github/workflows/release-risk.yml

// lib/auto-rollback.ts — Metric monitoring and automated rollback
// Prompt: "Implement auto-rollback using Cloudflare Analytics API"
 
interface MetricThreshold {
  metric: string;
  operator: 'gt' | 'lt' | 'gte' | 'lte';
  value: number;
  window: string;  // Evaluation window: '5m', '15m', '1h'
}
 
interface RollbackPolicy {
  flagKey: string;
  thresholds: MetricThreshold[];
  cooldownMinutes: number;  // Re-enable lockout after rollback
  notifyChannels: string[];
}
 
const ROLLBACK_POLICIES: RollbackPolicy[] = [
  {
    flagKey: 'new-checkout-flow',
    thresholds: [
      { metric: 'error_rate', operator: 'gt', value: 2.0, window: '5m' },
      { metric: 'p99_latency_ms', operator: 'gt', value: 2000, window: '5m' },
      { metric: 'checkout_success_rate', operator: 'lt', value: 95, window: '15m' },
    ],
    cooldownMinutes: 60,
    notifyChannels: ['slack:payments-alerts', 'pagerduty:checkout'],
  },
];
 
async function monitorAndRollback(policy: RollbackPolicy): Promise<void> {
  const checkInterval = 60_000; // Check every minute
 
  while (true) {
    await new Promise(r => setTimeout(r, checkInterval));
 
    for (const threshold of policy.thresholds) {
      const currentValue = await getMetricValue(
        threshold.metric,
        threshold.window
      );
 
      const violated = evaluateThreshold(currentValue, threshold);
 
      if (violated) {
        console.error(
          `🚨 Threshold violated: ${threshold.metric} = ${currentValue} ` +
          `(${threshold.operator} ${threshold.value})`
        );
 
        // Immediate rollback
        await executeRollback(policy.flagKey);
 
        // Send notifications
        for (const channel of policy.notifyChannels) {
          await sendNotification(channel, {
            type: 'rollback',
            flagKey: policy.flagKey,
            reason: `${threshold.metric} = ${currentValue}`,
            timestamp: new Date().toISOString(),
          });
        }
 
        // Cooldown period
        console.log(`⏸️ Cooldown: ${policy.cooldownMinutes}m`);
        await new Promise(r =>
          setTimeout(r, policy.cooldownMinutes * 60_000)
        );
        break;
      }
    }
  }
}
 
function evaluateThreshold(
  value: number,
  threshold: MetricThreshold
): boolean {
  switch (threshold.operator) {
    case 'gt':  return value > threshold.value;
    case 'lt':  return value < threshold.value;
    case 'gte': return value >= threshold.value;
    case 'lte': return value <= threshold.value;
  }
}
 
async function getMetricValue(metric: string, window: string): Promise<number> {
  // Fetch from Cloudflare Analytics API or external monitoring tools
  // Implementation auto-generated by Antigravity based on your infra
  return 0;
}
 
async function executeRollback(flagKey: string): Promise<void> {
  // Disable the flag in KV
  console.log(`🔄 Rolling back flag: ${flagKey}`);
}
 
async function sendNotification(
  channel: string,
  payload: Record<string, string>
): Promise<void> {
  // Notify via Slack / PagerDuty / Discord
  console.log(`📢 Notification sent to ${channel}`);
}
 
// Output when rollback triggers:
// 🚨 Threshold violated: error_rate = 3.2 (gt 2.0)
// 🔄 Rolling back flag: new-checkout-flow
// 📢 Notification sent to slack:payments-alerts
// 📢 Notification sent to pagerduty:checkout
// ⏸️ Cooldown: 60m

# scripts/canary_power.py — runs with plain python3, no dependencies
import math
from math import comb
 
def binom_tail_ge(n, k, p):
    """Exact probability of k or more failures out of n"""
    if k <= 0:
        return 1.0
    if k > n:
        return 0.0
    return sum(comb(n, i) * p**i * (1 - p)**(n - i) for i in range(k, n + 1))
 
def min_k_exceeding(n, thr):
    """Smallest failure count whose ratio exceeds thr"""
    return math.floor(thr * n) + 1
 
def fire_prob(n, thr, p):
    """Chance a single window trips the threshold when the true rate is p"""
    return binom_tail_ge(n, min_k_exceeding(n, thr), p)
 
TRAFFIC_PER_MIN = 200   # total request volume
P0   = 0.01             # steady-state error rate
THR  = 0.02             # rollback threshold
WIN  = 5                # evaluation window, in minutes
EVAL = 60               # evaluations per hour, checking once a minute
 
for exposure in (0.01, 0.05, 0.25, 0.50, 1.00):
    n = int(TRAFFIC_PER_MIN * WIN * exposure)
    once  = fire_prob(n, THR, P0)          # trips while nothing is wrong
    hour  = 1 - (1 - once) ** EVAL         # trips at least once in an hour
    power = fire_prob(n, THR, 0.03)        # catches a genuine drop to 3%
    print(f"{exposure*100:5.0f}%  n={n:5d}  "
          f"failures needed={min_k_exceeding(n, THR):3d}  "
          f"false/eval={once*100:5.2f}%  per hour={hour*100:6.2f}%  power={power*100:5.2f}%")

// lib/auto-rollback.ts — thresholds that know their own denominator
interface MetricThreshold {
  metric: string;
  operator: 'gt' | 'lt' | 'gte' | 'lte';
  value: number;
  window: string;
  minSamples: number;            // windows below this are not judged at all
  consecutiveViolations: number; // how many breaches in a row before firing
}
 
const streaks = new Map<string, number>();
 
async function evaluateWithGuard(
  flagKey: string,
  t: MetricThreshold
): Promise<'fire' | 'hold' | 'insufficient'> {
  const { value, samples } = await getMetricWithCount(t.metric, t.window);
  const streakKey = `${flagKey}:${t.metric}`;
 
  // Too few samples is not "healthy" — it is "unknown"
  if (samples < t.minSamples) {
    streaks.set(streakKey, 0);
    return 'insufficient';
  }
 
  if (!evaluateThreshold(value, t)) {
    streaks.set(streakKey, 0);
    return 'hold';
  }
 
  const streak = (streaks.get(streakKey) ?? 0) + 1;
  streaks.set(streakKey, streak);
  return streak >= t.consecutiveViolations ? 'fire' : 'hold';
}
 
// Change the metric itself as exposure grows, not just the threshold
const STAGE_THRESHOLDS: Record<number, MetricThreshold[]> = {
  1: [
    // Only events that carry meaning at a count of one
    { metric: 'fatal_crash_count', operator: 'gte', value: 1, window: '5m',
      minSamples: 1, consecutiveViolations: 1 },
  ],
  25: [
    { metric: 'error_rate', operator: 'gt', value: 2.0, window: '5m',
      minSamples: 500, consecutiveViolations: 3 },
    { metric: 'p99_latency_ms', operator: 'gt', value: 2000, window: '5m',
      minSamples: 500, consecutiveViolations: 3 },
  ],
};

// scripts/flag-hygiene.ts — Detect and remove expired flags
// Prompt: "Create a script that detects expired Feature Flags"
 
import { readFileSync, readdirSync } from 'fs';
import { join } from 'path';
 
interface FlagAuditResult {
  key: string;
  status: 'active' | 'expired' | 'stale' | 'orphaned';
  expiresAt?: string;
  usageCount: number;   // References in codebase
  lastModified: string; // Last modification date
  recommendation: string;
}
 
async function auditFlags(projectRoot: string): Promise<FlagAuditResult[]> {
  const results: FlagAuditResult[] = [];
  const now = new Date();
 
  // Load flag definitions
  const flagDefs = loadFlagDefinitions(projectRoot);
 
  for (const flag of flagDefs) {
    // Count references in codebase
    const usageCount = countFlagUsages(projectRoot, flag.key);
 
    // Determine status
    let status: FlagAuditResult['status'] = 'active';
    let recommendation = '';
 
    if (flag.expiresAt && new Date(flag.expiresAt) < now) {
      status = 'expired';
      recommendation = `Expired on ${flag.expiresAt}. Remove the flag and related code.`;
    } else if (usageCount === 0) {
      status = 'orphaned';
      recommendation = 'Not referenced in code. Delete the definition.';
    } else if (daysSince(flag.createdAt) > 90 && flag.type === 'release') {
      status = 'stale';
      recommendation = 'Release flag older than 90 days. Consider making permanent or removing.';
    }
 
    results.push({
      key: flag.key,
      status,
      expiresAt: flag.expiresAt,
      usageCount,
      lastModified: flag.createdAt,
      recommendation,
    });
  }
 
  return results;
}
 
function countFlagUsages(root: string, flagKey: string): number {
  // Count occurrences via grep
  // In practice, Antigravity agent searches the entire project
  let count = 0;
  const srcDir = join(root, 'src');
  // Recursively scan files and count flagKey occurrences
  return count;
}
 
function daysSince(dateStr: string): number {
  return Math.floor(
    (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24)
  );
}
 
function loadFlagDefinitions(root: string): any[] {
  // Load project's flag definitions
  return [];
}
 
// Run weekly in CI and post report to Slack:
// npx tsx scripts/flag-hygiene.ts
//
// Output:
// 🔍 Flag Audit Report — 2026-03-30
// ────────────────────────────────
// ❌ EXPIRED: new-checkout-flow (expired 2026-03-28)
//    → Remove the flag and related code
// ⚠️ STALE: legacy-api-fallback (created 120 days ago)
//    → Older than 90 days. Consider making permanent or removing
// ✅ ACTIVE: exp-pricing-v2 (expires 2026-04-15, 23 references)
// ✅ ACTIVE: ops-maintenance-mode (no expiry, 5 references)