v3/docs/adr/ADR-305-customer-lifecycle-funnel.md
RuFlo has millions of monthly package downloads and a large active user base, but relatively little product discovery beyond the CLI itself. Cognitum One (https://cognitum.one) offers adjacent paid capabilities — Meta LLM routing, hosted memory, premium agents, enterprise features — that most ruflo users never encounter.
The objective is a low-friction progression from open-source user to Cognitum customer without interrupting developer workflows. ADRs 301–304 define the individual touchpoints; this ADR defines the funnel they compose, its principles, and how success is measured.
Establish a lifecycle funnel integrated into natural product touchpoints:
npm install ruflo
↓
Initialization
↓
Optional capability enrollment (ADR-302)
↓
CLI usage
↓
Rotating status messages (ADR-301)
↓
Feature discovery
↓
Credit exhaustion guidance (ADR-303)
↓
Authentication (ruflo auth login)
↓
Local Meta Proxy (ADR-304)
↓
Multi-model routing
↓
Premium capabilities
↓
Enterprise adoption
Each stage is independently valuable to the user (a working install, a useful tip, a recovery path, a free local proxy) — conversion is a byproduct of delivered value, not a gate in front of it.
funnel.enabled: false (plus per-surface flags in ADRs 301–303) turns every touchpoint off; CI and non-TTY environments are always off.Suppression sources are strictly ordered. A lower-precedence source must never re-enable a higher-precedence disable.
1. RUFLO_FUNNEL=0 (environment — shells, dev containers, CI images, MDM-pushed profiles)
2. Enterprise managed policy (managed settings file deployed by endpoint management)
3. User config: funnel.enabled (claude-flow.config.json / user-level config)
4. Package default
5. Remote signed policy (only when the freshness feed is enabled; see kill switches below)
effectiveFunnelEnabled =
env !== false &&
enterprisePolicy !== false &&
userConfig !== false &&
packageDefault === true &&
remotePolicy !== false;
Enterprise documentation must cover: shell-environment deployment, dev-container configuration, CI environment defaults, MDM/endpoint-management deployment, air-gapped configuration, and audit verification (ruflo doctor prints the effective state and which source decided it).
Conversion numbers are meaningless unless they are reproducible. The following are defined before implementation, and no funnel event ships without them:
promo_impression, promo_dismiss, promo_open, enroll_shown, enroll_accept, enroll_skip, exhaustion_shown, exhaustion_accept, auth_login_started, auth_login_completed, proxy_installed, proxy_activated, cloud_routing_enabled, funnel_opt_out. New events require an ADR amendment.~/.ruflo/funnel-id) that is: not derived from hardware, account, email, or install path; rotated every 90 days; deleted on opt-out. It exists solely to deduplicate impressions and to join a signup back to its originating surface. It is never joined to the Cognitum account ID server-side beyond the attribution window.auth_login_completed occurs within 7 days of the surface event; proxy activation attributes to a signup within 30 days. Outside the window, the conversion counts as organic.funnel_opt_out (or telemetry off) stops emission immediately, deletes the local funnel ID, and triggers server-side deletion of that ID's raw events. Deletion is verifiable via a documented endpoint.Gates are ordered: a failure at any level makes the levels below it irrelevant. Growth metrics can never be traded against integrity metrics.
| Level | Gate | Threshold |
|---|---|---|
| 0 — Integrity | Security regressions | 0 |
| 0 — Integrity | Consent violations (any capability active without its ADR-302 receipt) | 0 |
| 1 — Product health | CLI latency p95 increase | < 10 ms |
| 1 — Product health | Command failure rate increase | < 0.1 percentage points |
| 2 — Trust | Opt-out rate | < 10% |
| 3 — Growth | Signup conversion | > 1% |
| 3 — Growth | Thirty-day activated retention | > 20% |
| 3 — Growth | Paid conversion (of activated accounts) | > 2% |
Level 3 targets are goals; levels 0–2 are hard gates.
The biggest failure mode is optimizing signup rate while degrading developer trust. Guardrails therefore act, not just report. But the transport matters: the ADR-174/177 signed helper channel is release-bound, not immediate — it propagates on the next installed upgrade, not on demand. Claiming "immediate fleet-wide shutdown" over that channel would be false. Two distinct mechanisms, each with its real latency:
| Release kill switch | Freshness kill switch | |
|---|---|---|
| Transport | Policy flag ships in the npm package (ADR-174/177 stamp propagates to initialized projects) | Optional signed remote fetch: GET /v1/funnel-policy (ADR-308) |
| Activation latency | Next installed upgrade | Bounded by polling interval |
| Works offline | Yes | No (falls back to last valid signed policy) |
| Default | On — the default mechanism for all users | Off — enabled only by explicit user or enterprise-administrator opt-in |
| Payload | Policy data in-package | Signed, schema-validated policy data — never executable code |
Policy:
ruflo doctor reports whether funnel surfaces are active, disabled by user config, disabled by enterprise policy, or disabled by guardrail — and which mechanism delivered the decision.Opt-in production telemetry cannot enforce release gates — its sample is biased (opt-outs correlate with telemetry-off), and correctness must be provable before shipping, not observed after. Measurement therefore splits into two planes:
Staged rollout (phases, cohort mechanics, promotion criteria, rollback discipline) and the full release-gate acceptance test are owned by ADR-310. In summary, the funnel does not ship until this passes end-to-end on an existing offline installation, upgraded in place, across TTY, non-TTY, CI, screen-reader/reduced-motion, and enterprise-disabled configurations:
statusline.cjs replaced) without running ruflo init.RUFLO_FUNNEL=0 suppresses every funnel surface (ADR-301, 302, 303).The same promotion framework can surface context-aware recommendations, such as suggesting GPU acceleration when local hardware is detected, enterprise features in team environments, or relevant MetaHarness integrations based on observed usage patterns. This creates a scalable discovery system while keeping the CLI experience lightweight and developer-focused.
Any such extension inherits this ADR's principles and guardrails and requires its own ADR before shipping.