feat(enterprise) adoption recommendations

[St0rmz1]

Summary

Adds an adoption Recommendations feature to the Enterprise usage analytics view. For Enterprise organizations, the feature-adoption page now surfaces actionable suggestions for getting more out of features the org already uses (for example: add a security focus to Code Reviewer, turn on a merge gate, enable Security Agent SLAs, reconnect a broken integration, set up SSO, invite members to unused seats). Recommendations are grouped into Open, Completed, and Dismissed tabs, and owners can dismiss or restore them.

The recommendation set is computed in code from the organization's current state, so there is no per-recommendation storage. The only new persisted data is which recommendations an org has dismissed.

Changes

• New rule engine in recommendations.ts. buildRecommendations is a pure function over an org's RecommendationState; each rule reports open (gap exists), completed (good state reached), or is omitted when the feature is not enabled. getRecommendationState and getOrganizationRecommendations gather the state from the DB and apply dismissals. Non-enterprise orgs return an empty result.
• New RecommendationsView.tsx component with Open/Completed/Dismissed tabs, per-recommendation deep links, owner-only dismiss/restore, and an undo toast on dismiss.
• New StatusDonutChart.tsx (recharts), used by both the recommendations view and the feature-adoption card.
• FeatureAdoptionView now renders the status donut and switches between the feature-adoption and recommendations queries based on its compact prop. UsageAnalyticsDashboard renders RecommendationsView below the adoption view, passing canDismiss only for owners.
• New tRPC procedures on the organization usage-details router: getRecommendations (member access), and dismissRecommendation / restoreRecommendation (owner-only mutations). All three are gated to the Enterprise plan.
• New organization_recommendation_dismissals table (migration 0172 plus schema), unique on (organization, recommendation key). dismissed_by_user_id is nullable and set to null on user delete so dismissals persist. softDeleteUser now nulls these actor references.
• getOrganizationSeatUsage reworked to count seats with direct aggregate queries: active non-bot, non-billing-manager members plus pending (unaccepted, unexpired) non-billing-manager invitations. Previously it only counted loaded members. This feeds the unused-seats recommendation. Note: pending invitations now count toward used seats.
• Exported getFeatureAdoptionState and FeatureAdoptionState from feature-adoption.ts, and featureIcons from FeatureAdoptionView, for reuse by the recommendation code.
• Tests added for the rule engine, seat-usage counting, soft-delete actor nulling, and the new router procedures.

Verification

• [ ]

Visual Changes

Before	After

Reviewer Notes

• The seat-usage change alters existing behavior: pending non-billing-manager invitations now count as used seats. Worth confirming that matches the intended seat accounting.
• The recommendation merge-gate rule is suppressed for GitHub-only orgs on the read-only ("lite") app, since that app cannot gate PRs; the upgrade is covered by a separate org-github-lite-app rule.
• All recommendation read/write paths are Enterprise-gated, and dismiss/restore are owner-only.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (2 files)

• apps/web/src/lib/organizations/recommendations.ts
• apps/web/src/routers/organizations/organization-usage-details-router.test.ts

Previous Review Summary (commit 545fd5f)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 545fd5f)

Status: 1 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/organizations/recommendations.ts	512	Missing NOT_FOUND handling for deleted or missing organizations

Files Reviewed (17 files)

• apps/web/src/components/usage-analytics/FeatureAdoptionView.tsx - 0 issues
• apps/web/src/components/usage-analytics/RecommendationsView.tsx - 0 issues
• apps/web/src/components/usage-analytics/StatusDonutChart.tsx - 0 issues
• apps/web/src/components/usage-analytics/UsageAnalyticsDashboard.tsx - 0 issues
• apps/web/src/lib/organizations/feature-adoption.ts - 0 issues
• apps/web/src/lib/organizations/organization-seats.test.ts - 0 issues
• apps/web/src/lib/organizations/organization-seats.ts - 0 issues
• apps/web/src/lib/organizations/recommendations.test.ts - 0 issues
• apps/web/src/lib/organizations/recommendations.ts - 1 issue
• apps/web/src/lib/user/index.test.ts - 0 issues
• apps/web/src/lib/user/index.ts - 0 issues
• apps/web/src/routers/organizations/organization-usage-details-router.test.ts - 0 issues
• apps/web/src/routers/organizations/organization-usage-details-router.ts - 0 issues
• packages/db/src/migrations/0172_boring_ghost_rider.sql - 0 issues
• packages/db/src/migrations/meta/0172_snapshot.json - 0 issues
• packages/db/src/migrations/meta/_journal.json - 0 issues
• packages/db/src/schema.ts - 0 issues

---

_{Reviewed by gpt-5.4-2026-03-05 · Input: 85.8K · Output: 4.3K · Cached: 143.3K}

_{Review guidance: REVIEW.md from base branch main}