feat/discovery

Toast fires spuriously when query cycles through loading state mid-session

apps/platform/src/components/discovery/DescubreMenu.tsx:100

When ok flips false (loading/error) then true (data arrived), the useEffect early-returns on `if (!ok) return` without updating prevRef.current. On the next render when data arrives, prev.keys holds the stale snapshot and current holds new data, so a spurious 'completed step' toast fires if items differ. prevRef should be updated even on the !ok early-return path, or depend on a stable isSuccess flag.

status: done discloses org setup booleans — intentional, bounded by auth+RLS

packages/api/src/schemas/discovery.schemas.ts

Each item's status field reveals whether the org completed a setup step. Intentional UX; bounded by withAuth + RLS (no cross-org leakage). Worth re-evaluating if the signal set ever expands to sensitive commercial state (payment status, contract financials).

ChecklistItem local type in DescubreMenu is an unsafe cast — no structural alignment

apps/platform/src/components/discovery/DescubreMenu.tsx:47

A local ChecklistItem type is hand-written then cast with `as ReadonlyArray<ChecklistItem>`. If DiscoveryChecklistItem gains or renames a field, the cast silently succeeds while the component uses stale types. Better: derive from DiscoveryGapResponse['items'][number] (already client-bundle-safe from @batu/api schemas), giving compile-time proof the alias matches the wire schema.

DiscoveryChecklistStatusSchema missing satisfies z.ZodType<DiscoveryChecklistStatus>

packages/api/src/schemas/discovery.schemas.ts:46

Per the covariance-gotcha in api-patterns.md: z.enum(['done','available']) needs `satisfies z.ZodType<DiscoveryChecklistStatus>` to catch a future widening of the domain type (e.g. adding 'locked') that leaves the runtime enum stale with no TypeScript error. Add the annotation and import DiscoveryChecklistStatus from @batu/cross-domain.

discoveryActive: true hardcoded in shell — derive from orgSegment instead

domains/cross-domain/src/feature-discovery.shells.ts:197

The providers success path emits `discoveryActive: true` as a constant. If a second segment ('enterprise') is ever enabled, this constant stays true silently. Prefer `discoveryActive: input.orgSegment === 'providers'` — stays correct as segments expand and is self-documenting.

export_columns partial-done state untested in listDiscoveryChecklist

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:384

export_columns uses asymmetric predicates: eligible uses OR (missing either config = eligible), adopted uses AND (both configs needed = done). The partial state — one view configured, not both — should yield 'available'. This is explicitly called out in decisions.ts comments but has no test in the listDiscoveryChecklist suite. The decideSpotlight suite covers it but the checklist function is a separate code path. A future refactor swapping || for && in adopted would regress silently.

payment_monitoring available-but-not-done state never asserted in checklist suite

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:384

The checklist test verifies payment_monitoring is UNDEFINED when hasMonitored=false (locked). But the unlock transition — hasMonitored=true, hasPaymentMonitored=false → 'available' — is never asserted in the listDiscoveryChecklist suite. Also no test for the adopted direction: hasPaymentMonitored=true should yield 'done' regardless of hasMonitored. Both are exercised in decideSpotlight tests but not the dedicated listDiscoveryChecklist describe block.

internal_site_ids checklist status never directly asserted in any test

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:384

The base-signals test checks cfe_setup, add_contract, monitoring, export_columns, api_keys, and payment_monitoring — but not internal_site_ids. baseSignals has contractCount=10 >= SCALE_SIGNAL_MIN_CONTRACTS and hasInternalSiteIds=false, so expected status is 'available'. The all-adopted test sets hasInternalSiteIds=true but only asserts items.every(done). A bug that dropped internal_site_ids from output would not be caught.

getDiscoveryGapShell integration test absent — discoveryActive unwired at DB/RLS level

domains/cross-domain/src/__tests__/feature-discovery.integration.test.ts

The existing integration tests exercise getDiscoverySpotlightShell and recordSpotlightOutcomeShell with real DB + RLS, but getDiscoveryGapShell (which calls listDiscoveryChecklist) has no integration test. discoveryActive: true/false and tourSeen from the exposures query are never asserted at the DB layer.

Retirement-ignore invariant has no test — architecturally safe but undocumented

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:372

listDiscoveryChecklist doesn't accept exposures (making retirement impossible to introduce), but no test documents the intent. A test asserting that a user with 2 dismissals on monitoring still sees 'available' in the checklist would document the deliberate divergence from listEligibleSpotlights.

`ok` is too terse for a variable gating three derived values

apps/platform/src/components/discovery/DescubreMenu.tsx:88

`ok` guards discoveryActive, items, and a useEffect dependency. The name carries no domain meaning. `checklistReady` or `checklistLoaded` would make intent obvious without adding length.

Tour re-entry reachability: verify fully-onboarded providers still see Descubre button

apps/platform/src/components/DashboardHeader.tsx:178

ProductTourMenuItem removed; tour re-entry now lives inside DescubreMenu. DescubreMenu is persistent for providers (discoveryActive=true regardless of checklist fullness), so the button should always be reachable. Verify manually: a provider with all items 'done' still sees the Descubre button and can re-launch the tour — this is the core UX promise of v3.1.