ADR-0005: dev_pass flag for tier-gate bypass during development

• Status: Accepted
• Date: 2026-05-03
• Affected: user_profiles schema, server-side gates, <ProBadge />, Settings UI

Context

Tier gates (Pro, Family) and usage caps are real user-facing constraints. They have to be implemented before the app is usable for anyone but the free tier — but during pre-launch development, gating the developer’s own access slows iteration without testing anything. We want to:

• Develop with everything unlocked.
• Keep the gating implementation in place (so production behavior is what we ship, not what we add later).
• Visibly mark which features are premium so we don’t accidentally lose track of the gates.
• Be able to test the gated UX easily when we want to.

Options considered

Option A — Skip implementing gates until production

• Pros: Simplest now.
• Cons: We lose “ship the gate behavior” guarantee. Tier code becomes end-of-phase rework instead of incremental.

Option B — Env-var-controlled global override

• Pros: One flag flips everyone.
• Cons: Doesn’t let us test gated UX without a redeploy. Can’t be flipped per-user, so we can’t simulate “user A is free, user B is Pro” in dev.

Option C — Per-user dev_pass boolean (chosen)

• Pros: Each developer / tester carries their own flag. Toggle from Settings to test gated UX. Server gates honor it cleanly. Production prep is a one-line migration to flip the default.
• Cons: One more column on user_profiles. Marginal.

Decision

Add user_profiles.dev_pass boolean default true. Server gates (requirePro, consume_recording_seconds, consume_chat_call) short-circuit when set. Settings has an On/Off toggle. <ProBadge /> renders on premium features regardless — the badge is purely visual (“this would be gated in production”) and doesn’t correlate with the flag.

Consequences

• All gate implementations stay in code. dev_pass=false produces the real free-tier behavior; that’s how production runs.
• Pre-launch, the column default is true. Production prep needs:
  • A migration that flips the default to false.
  • A bulk UPDATE user_profiles SET dev_pass = false.
  • Wrap <DevPassSection /> in process.env.NODE_ENV !== "production" so the toggle disappears.
• Tracked in docs/03_PROGRESS.md under “Production prep”.

Notes

The badge has color and size deliberately matched to a “pill” style so it doesn’t fight with the rest of the UI. It says “Pro” even on Family features (Spaces is tagged Family); both nudge the same upgrade flow.