feat/discovery

openedRef blocks hub re-launch after first open in same session

apps/platform/src/components/discovery/GuidedTour.tsx:92

GuidedTour mounts in the layout and never unmounts. openedRef.current is set to true on first open and never reset. A second hub re-launch (?tour=1) in the same session silently does nothing. Fix: if (!forced && openedRef.current) return; and reset openedRef.current = false on forced re-launch.

Anchor-locate and close() can double-invoke outcome report

apps/platform/src/components/discovery/GuidedTour.tsx:163

If locate() fires its last retry concurrently with a user clicking Skip, both paths call report(). Upsert is idempotent (COALESCE on clickedAt, additive deltas of 0), so no data corruption, but two requests fire.

tourSeen is user-scoped, not org-scoped

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

A user who saw the tour in org A has tourSeen=true in org B. Consistent with acknowledged cross-org staleness trade-off. Full fix: orgId on discovery_state (deferred).

?descubre URL param forwarded to API without client-side enum validation

apps/platform/src/components/discovery/FeatureSpotlight.tsx:52

Forwarded without safeParse. Server-side Zod rejects invalid values, so no data leakage. A client-side guard eliminates unnecessary round-trips.

NEXT_PUBLIC_VERCEL_ENV intentionally discloses deployment tier

apps/platform/next.config.ts

By design. No secret material. Comment in next.config.ts explains the tradeoff.

In-memory rate limit not shared across Lambda instances (pre-existing)

apps/platform/src/middleware

Pre-existing. recordOutcome endpoint callable in a tight loop across warm instances. Blast radius: inflated seenCount/dismissCount counters only.

console.error used instead of createShellLogger in cross-domain shells

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

getDiscoverySpotlightShell and getDiscoveryGapShell use console.error. The project's structured logger (createShellLogger) is the canonical pattern for domain shells.

recordSpotlightOutcomeShell omits outbox event emission

domains/core/src/discovery/discovery.shells.ts:42

ADR-016: every state-mutating shell writes entity + outbox event atomically. This shell mutates discovery_state but emits no outbox event. If intentional (no subscribers yet), document as an ADR exception.

upsertOutcome deviates from canonical query naming convention

domains/core/src/discovery/discovery.queries.ts:46

Canonical naming: insert, updateWithVersion, findBy{Field}. The new upsertOutcome name is semantically accurate but does not follow the prescribed pattern.

Shell JSDoc still describes stale FCIS fetch-then-decide flow

domains/core/src/discovery/discovery.shells.ts:38

JSDoc comment on recordSpotlightOutcomeShell describes the removed fetch step (1. FETCH, 2. DECIDE, 3. EXECUTE). The implementation skips the fetch entirely.

isBudgetSpent product_tour exclusion untested

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

The isBudgetSpent filter that excludes product_tour rows has no test. A regression would block every spotlight for every user who has taken the tour.

getDiscoveryGapShell tourSeen logic has zero test coverage

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

Both new behaviors in getDiscoveryGapShell (computing tourSeen from product_tour row, returning tourSeen:true for consumer orgs) are untested. A wrong value re-shows the tour every session or never shows it on first run.

GuidedTour state machine has no tests

apps/platform/src/components/discovery/GuidedTour.tsx

315-line component with non-trivial logic (openedRef guard, anchor retry loop, step navigation, forced re-launch, hazloAhora dispatch) has zero tests.

createSecret pending-deletion + tags combination path untested

packages/secrets/__tests__/unit/secrets-manager.createSecret.test.ts:77

Pending-deletion test has no tags variant. Source runs TagResourceCommand after Update when tags supplied. Compare: ResourceExists path has a tags variant.

resolveSpotlightPage and pathForPage have no unit tests

apps/platform/src/components/discovery/__tests__/spotlight-latch.test.ts

Pure functions with non-trivial edge cases (startsWith match, fallback path) called on every route change. The spotlight-latch test file only tests computeSpotlightLatch.

upsertOutcome dismissed path: lastSeenAt immutability not asserted in integration test

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

The core pacing invariant (a dismiss must not spend the daily budget) — lastSeenAt unchanged after dismiss — is not asserted at the DB level in the integration test.

spotlight-latch forceAdopt idempotent case not pinned

apps/platform/src/components/discovery/__tests__/spotlight-latch.test.ts:63

forceAdopt=true with the SAME key as the shown key is a silent no-op (hits prev.key guard first). Correct behavior but not pinned — a guard reordering breaks it without a test failing.

product_tour key hardcoded as string literal in cross-domain shell

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

TOUR_KEY is defined in tour-catalog.ts (frontend). Backend shell can't import it; string is duplicated. Should live in discovery-state.type.ts so renaming is caught at compile time.

DiscoveryTourSkippedEvent.properties typed as Record<string, never>

packages/analytics/src/events.ts

Rejects any property at compile time. Inconsistent with other tour events (started, completed, step_viewed) which carry contextual properties. Use properties?: { step?: string; stepIndex?: number }.

hazloAhora click-anchor path silently no-ops if anchor absent

apps/platform/src/components/discovery/GuidedTour.tsx:130

?.click() silently does nothing if the anchor isn't found. The anchor-retry loop emits discovery.spotlight_anchor_missing on miss; this path has no tripwire.

GuidedTour flagEnabled unsubscribe pattern inconsistent with siblings

apps/platform/src/components/discovery/GuidedTour.tsx:46

Returns posthog?.onFeatureFlags?.(cb) directly. DescubreMenu and FeatureSpotlight wrap it: () => unsubscribe?.(). Fragile if PostHog changes the return type.

Double-report when hazloAhora triggers

apps/platform/src/components/discovery/GuidedTour.tsx:124

onHazloAhora duplicates the report+track+setOpen sequence from close(). If close() gains cleanup logic, the hazloAhora path will silently miss it. Call close('completed') then apply the action.

cardPos useMemo reads window dimensions without resize dependency

apps/platform/src/components/discovery/GuidedTour.tsx:209

Resize listener updates rect but not window.innerWidth/innerHeight. On a vertical-only resize, placeBelow may be stale. Pre-existing in FeatureSpotlight; now in two card components.

Magic card-height estimate (190) inconsistent with FeatureSpotlight (180)

apps/platform/src/components/discovery/GuidedTour.tsx:214

190 may be too small for GuidedTour's taller layout (Hazlo ahora row + nav + skip). Should be a named constant; inconsistency with 180 should be documented.

tourSeen defaults to true on gap query failure

apps/platform/src/components/discovery/GuidedTour.tsx:70

Fail-safe and intentional (transient 500 suppresses first-run rather than re-showing on every error). Worth documenting in inline comment.

DescubreMenu navigates to TOUR_PAGE_PREFIX even when already there

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

Adds unnecessary history entry when already on /bills/contratos. router.replace or pathname check would avoid this.

CARD_WIDTH constants duplicated in GuidedTour (340) and FeatureSpotlight (320)

apps/platform/src/components/discovery/GuidedTour.tsx:31

Intentionally different values but no naming to signal the difference. Named constants (TOUR_CARD_WIDTH / SPOTLIGHT_CARD_WIDTH) would make the distinction explicit.