# Journey and readiness

## What it does

Journey describes the customer's current operational position. Readiness records explain
what the team knows and what still needs confirmation in seven parallel areas: Needs,
Relationship, Understanding, Loan, Cash, Decision Maker and Property fit.

These areas do not add new gates to the business flow:

- Attendance in any Stage 1 Session, across its Slots, qualifies the customer for Stage 2.
  The existing cumulative attendance duration bands remain unchanged. Membership is optional.
- A paid Membership adds financial preparation and member follow-up alongside Stage 2 eligibility.
- An active Project fee is the handoff to Stage 3, the existing Sales Projects opportunity.
  Consent, financial questions, WhoPay and the sales 1-1 continue there. Stage 2 displays the
  same preparation records; it does not create a second closing pipeline.

## How it works

`JourneyReadiness` reuses `ReadinessColumns` record evidence. This is explicitly the records
layer, not a new AI score and not the Overall verdict shown in the Leads list. No AI analysis,
task creation, customer message or database write happens when a board is viewed.

### Population and filters

The Preview and Project boards apply their existing visibility, date, Session, owner, node and
duration rules first. A board built **counts only** (no `jnode` — the first paint) has no readiness block at all.
With a roster, the seven gap counts are calculated over the selected group **before** pagination, but only when
asked: `jreadiness_counts=1` (the workspace's readiness toggle) or a chosen area. `jreadiness` selects an area whose records are not Ready. Its whitelist is
`ReadinessColumns::AREAS`; an unknown value is ignored. Counts overlap: one customer can need
several follow-ups. Internal staff do not enter customer gap counts.

Readiness is batched in groups of 1,000 for the cohort using the same record rules, without
generating full evidence text. Boolean states are cached only within one HTTP request (a lead met twice
in one GET is read once); there is no cross-request count cache. Stages no longer share them: the company
chart builds a roster — and so readiness — only for the selected board; its other boards are counts only. The visible page receives detailed evidence, shared FPA
progress and a next-action link. My Work shows row evidence, so it skips unshown cohort gap
counts unless a readiness filter is explicitly requested; its flow-node counts are unchanged.
Existing node totals and attendance classification do not change when a gap is selected.

Preview also exposes overlapping reference cohorts: `ready_unpaid` (Ready with no active Membership
receipt), `membership_paid`, `consent_pending`, `questionnaire_pending`, `report_pending`, and the member
consultation references `consultation_pending` (time needed), `consultation_booked` (scheduled or due),
`consultation_review` (check records) and `consultation_done` (held). The member references read active
Membership receipts for customers in the filtered company population; they are not funnel-attribution
revenue totals. Each preparation count reads the same paid-customer set and deduplicates the customer.

### Shared preparation and purchase-specific proof

`FpaProgress::forLeads()` remains the one definition of consent, questionnaire and report
completion. A signed consent remains signed after the invitation expiry. Placeholder financial
profiles and unparsed report links do not count as completed preparation. A report is not loan
approval. No personal consent tokens or report URLs are included in board DTOs.

Sales Projects enriches each engagement row separately, including cross-project lists where
the same lead appears more than once. An LO or selected unit from Project A cannot settle Loan
or Property fit for Project B. Multiple candidate projects on a Funnel row require choosing an
opportunity before purchase readiness can be confirmed. Cash figures and a spouse's name are
signals, not proof that this purchase is funded or agreed.

On a Journey roster, an existing open task in this funnel comes first. Otherwise the next action
follows the customer's actual node: invite an unregistered customer, offer another Session to a
no-show, review an AI callback already in progress, or continue the paid customer's unfinished
preparation. Selecting a readiness gap explains that gap alongside the current flow state; it
does not turn an automated wait or a stopped Journey into a newly assigned call. Sales Projects
continues to prioritize existing paid preparation before the missing readiness evidence.
Existing completed steps are reused. These links never contact the customer automatically.

### From the chart to work

The Funnel Journey tabs and the company Sales flow chart share `JourneyWorkQueue` and the same
contact / work components. The four work filters (`jwork=overdue|today|unassigned|suggested`)
apply to the selected node, duration and readiness cohort before pagination. They do not change
the flow-node totals. The company chart's `jowner` narrows every board to the same owner within
the viewer's Lead visibility; it never expands an agent's access.

- `work.counts` / `customer_counts` are **distinct customers**; `work.task_counts` are task rows for
  overdue / today / unassigned (a suggestion is not a task). A customer with an overdue task and
  another task without an effective assignee can appear in both filters. Selecting a filter
  shows that customer's most urgent matching task as the row's primary item.
- Only open `LeadActionItem` records of this funnel enter these counts: linked to this funnel's
  `FunnelJourney` with a matching `lead_id`, or a recorded contact whose `handoff_context.funnel_id`
  is this funnel. General tasks and tasks in another funnel remain on My Work. An assignee is
  effective only while active and still able to see the lead.
- Suggested follow-up means a suggestion context with no open covering task and no active recorded
  contact. The suggestion kinds are, on a Preview board, `registered` (invite), `human` (With a colleague —
  a suggestion while no task covers it), `no_show` and `ready`; on a Project board `eligible`, `human`,
  `no_show` and `attended` (`JourneyWorkQueue::kind()`). A contact recorded by anyone suppresses it for
  `funnel_journey.recontact_after_days` (D3). **Spoke to them** and **Cannot be reached** both close the
  contact: the item reads done ("Contact recorded" / "Cannot be reached") for that window, with no Record
  button — before 2026-10-13 a Cannot be reached read "Check the recorded result" in To do. Only a system
  result (not called in time, no longer needed) is left to check. It is not a promised deadline or an automatically generated
  assignment. Waiting, stopped, internal-staff and completed states remain distinct from those suggestions.
  After real tasks, suggestions are ordered human hand-off, attended-unpaid, no-show, Ready, then the
  rest (new invitations) — `JourneyWorkQueue::suggestionOrder()`. Within a group the lead id is the
  stable tiebreaker; this ordering does not manufacture a due date.
- Real task links open `/manage/my-work?task={uuid}` (`JourneyWorkQueue::row()`): My Work redirects a
  sales-flow task to its step in Sales steps. There is no `lead=` — that parameter opens the lead modal over the
  list. A super admin or `view-leads-all` viewer opening another manage user's task also receives
  `person={uuid}`. Other viewers open the lead's Action Items
  instead; unavailable assignees are sent there for assignment review. A task's outcome may be
  recorded by its holders and by the lead's account manager, the opportunity's sales owner and super
  admins (D5); an open Stage 1 task (`preview_invite` / `preview_call`) of a customer still in Stage 1, by any
  sales admin who can see the lead (D6, 2026-10-11 —
  [Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md)).
- My Work defaults to the viewer's assigned tasks, orders channels together by urgency, and
  focuses only tasks already visible on that person's board. A missing task may have been
  completed or reassigned. An empty personal board does not mean the whole company flow is done.
- Contact details and WhatsApp navigation reuse the existing Lead and channel permissions.
  The phone button records the call intent through the existing recorder flow; it does not
  auto-dial or complete the task. Outcomes are recorded through
  [Pending / Done](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md).
- After **Spoke to them** on an invitation, no-show or after-webinar contact, the same form offers the
  agreed-Session registration: the funnel's upcoming Sessions (after a Preview, also the Project funnels it
  feeds) for a viewer with `manage-events`, or the reason none can be offered. Such a registration starts no
  automation (D2). Read-only staff can share the Session landing page or ask its manager to arrange
  registration. The customer Journey itself remains a history / evidence view.

The optional Payment Item trigger **After payment · Financial preparation** sends the personal
next-step link using an explicitly configured approved template. See
[Payment automation](/docs/modules_handbook/manage/payments/payment-automation/readMe.md).
Existing receipt templates and their variable positions are unchanged. Enabling this rule does
not replay old purchases.

### Needs question setup

Preview Slots without an explicit human question set combine their current AI-profile fields
with the shared `StageOneNeedsQuestions` defaults: looking now, purpose, timing, current problem,
help requested, must-haves and purchase budget. An explicit Slot question set still wins.
AI Profiles exposes **Add Stage 1 Needs questions** to add missing extraction fields and a draft
prompt section without overwriting the existing profile. An administrator must review and save
that target profile through its normal Save & Sync flow before live AI calls use the additions.
A negative Need answer remains evidence; a purchase budget never proves available Cash.

### Answers recorded without a journey

A colleague's answers on a contact recorded where the customer has no automation journey (a historical registrant,
an invitation) are filed against the funnel: `funnel_journey_answers.funnel_journey_id` is null and
`event_funnel_id` names the funnel (migration `2026_10_08_191000_allow_funnel_journey_answers_without_journey`).
`ReadinessColumns` reads answers by `lead_id`, so they turn their area amber like any DATA answer. A reached
colleague call is Relationship evidence; an AI answer never is.

### Deployment

The readiness views need no schema migration of their own (answers without a journey need `2026_10_08_191000`,
above). After deploying the code, refresh the
existing Leads filter/sort cache with `php artisan leads:refresh-readiness`. This recalculates
record and verdict states; it does not run paid AI analysis or send customer messages.
Journey counts calculate current evidence directly and do not depend on that cache.

## Related files

- `src/Lead/Journey/JourneyReadiness.php`, `PreviewJourneyBoard.php`, `ProjectJourneyBoard.php`
- `src/Lead/Support/ReadinessColumns.php`, `ReadinessVerdict.php`
- `src/Fpa/Support/FpaProgress.php`
- `app/Http/Controllers/Manage/Engagements/SalesProjectsController.php`
- `resources/js/Pages/Manage/MyWork/Partials/SalesJourneyWorkspace.vue` (the funnel Journey tab and the company
  flow; `Events/Funnels/Partials/Tabs/FunnelJourneyWorkspace.vue` is its funnel wrapper)
- `resources/js/Components/Sales/EngagementTable.vue`
- [Shared readiness evidence component](/docs/modules_handbook/shared/readiness-summary/readMe.md)
- [Shared flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md)
- [Sales Projects](/docs/modules_handbook/manage/engagement/sales-projects.md)
