feat: reroute Advice Services from housing terminal to non-housing with subcategory selection and Citizens Advice floor

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: camlambert2000

__tests__/safeguarding.test.ts

@@ -487,6 +487,24 @@ describe('Non-Housing Terminal Path', () => {
 
 });
 
+// =============================================================================
+// ADVICE SUBCATEGORY ROUTING - Advice bypasses housing profiling
+// =============================================================================
+
+describe('Advice Subcategory Routing', () => {
+
+  test('selecting Advice at B5 routes to B5A_ADVICE_TYPE, not housing profiling', () => {
+    const session = sessionAt('B5_MAIN_SUPPORT_NEED', {
+      routeType: 'FULL',
+      localAuthority: 'Birmingham',
+    });
+    const result = select(session, 5); // Advice is option 5
+    expect(result.stateUpdates.currentGate).toBe('B5A_ADVICE_TYPE');
+    expect(result.options).toHaveLength(7);
+  });
+
+});
+
 // =============================================================================
 // DETAILED AGE/GENDER PRIORITY - detailedAge/detailedGender override basics
 // =============================================================================

lib/phrasebank.ts

@@ -334,6 +334,36 @@ Support with Benefits and Grants | Turn2us - https://www.turn2us.org.uk/`
     options: ["Emergency Housing or Other Accommodation", "Food", "Work", "Health Services", "Advice Services", "Drop In", "Financial Help", "Personal Items", "Personal Services", "Communications", "Training", "Activities"]
   },
 
+  // ============================================================
+  // ADVICE TYPE SELECTION
+  // ============================================================
+
+  B5A_ADVICE_TYPE: {
+    text: `What kind of advice are you looking for?
+
+1. Benefit advice
+2. Debt or financial problems
+3. Employment advice
+4. Immigration or asylum advice
+5. Health service advice
+6. Legal advice
+7. General support`,
+    options: ["Benefit advice", "Debt or financial problems", "Employment advice", "Immigration or asylum advice", "Health service advice", "Legal advice", "General support"]
+  },
+
+  B5A_ADVICE_TYPE__SUPPORTER: {
+    text: `What kind of advice are they looking for?
+
+1. Benefit advice
+2. Debt or financial problems
+3. Employment advice
+4. Immigration or asylum advice
+5. Health service advice
+6. Legal advice
+7. General support`,
+    options: ["Benefit advice", "Debt or financial problems", "Employment advice", "Immigration or asylum advice", "Health service advice", "Legal advice", "General support"]
+  },
+
   // ============================================================
   // CATEGORY-SPECIFIC PROFILING GATES
   // Asked based on which support need was selected

lib/serviceMatcher.ts

@@ -127,6 +127,17 @@ const needToCategoryMap: Record<string, string[]> = {
   'Activities': ['activities']
 };
 
+// Map advice subcategories to database category.sub values
+const adviceSubcategoryMap: Record<string, string[]> = {
+  'Advice:Benefits': ['benefits'],
+  'Advice:Debt': ['debt-financial-problems', 'money-management'],
+  'Advice:Employment': ['employment'],
+  'Advice:Immigration': ['immigration', 'asylum', 'refugees'],
+  'Advice:Health': ['health', 'mental-health'],
+  'Advice:Legal': ['legal'],
+  'Advice:General': ['general'],
+};
+
 // Needs where profile (gender, age, LGBTQ+, etc.) should affect filtering
 const profileRelevantNeeds = ['Health', 'Work', 'Financial', 'Training', 'Activities', 'Drop In'];
 
@@ -406,19 +417,21 @@ function calculateMatchScore(service: Service, profile: UserProfile): number {
  * Get services by category and location
  */
 export function getServicesByCategory(
-  localAuthority: string | null, 
-  categories: string[]
+  localAuthority: string | null,
+  categories: string[],
+  subcategories?: string[]
 ): Service[] {
   if (!localAuthority || categories.length === 0) return [];
-  
+
   const la = normalizeLA(localAuthority);
   const services = (servicesData as WMCAServicesData).services;
-  
+
   return services.filter(s => {
     const serviceLA = normalizeLA(s.local_authority);
     const matchesLA = serviceLA === la;
     const matchesCategory = categories.includes(s.category.parent);
-    return matchesLA && matchesCategory;
+    const matchesSub = !subcategories || subcategories.length === 0 || subcategories.includes(s.category.sub);
+    return matchesLA && matchesCategory && matchesSub;
   });
 }
 
@@ -500,8 +513,9 @@ export function getServicesForNeed(need: string, profile: UserProfile): MatchedS
   const categories = needToCategoryMap[need] || [];
   if (categories.length === 0) return [];
 
-  // Get services matching category and location
-  let services = getServicesByCategory(profile.localAuthority, categories);
+  // Get services matching category and location, with optional subcategory filtering
+  const subcategories = profile.adviceSubcategory ? adviceSubcategoryMap[profile.adviceSubcategory] : undefined;
+  let services = getServicesByCategory(profile.localAuthority, categories, subcategories);
 
   // Apply profile filtering if relevant for this need
   if (profileRelevantNeeds.includes(need)) {

lib/stateMachine.ts

@@ -99,6 +99,7 @@ export function createSession(sessionId: string): SessionState {
     ageCategory: null,
     gender: null,
     supportNeed: null,
+    adviceSubcategory: null,
     additionalNeeds: [],
     needCount: 0,
     homeless: null,
@@ -247,6 +248,9 @@ const needProfileRequirements: Record<string, string[]> = {
   // Drop In: Age (youth drop-ins), Gender (some gender-specific)
   'Drop In': ['age', 'gender'],
 
+  // Advice: subcategory selection provides targeting, no further profiling
+  'Advice': [],
+
   // Location-only needs - no profiling required
   'Food': [],
   'Items': [],
@@ -417,6 +421,14 @@ const nationalFallbacks: Record<string, Array<{name: string; phone?: string; web
       website: 'https://nationalcareers.service.gov.uk',
       description: 'Free careers advice, skills assessment and training information'
     }
+  ],
+  'Advice': [
+    {
+      name: 'Citizens Advice',
+      phone: '0800 144 8848',
+      website: 'https://www.citizensadvice.org.uk',
+      description: 'Free, confidential advice on benefits, debt, housing, legal and other issues'
+    }
   ]
 };
 
@@ -514,7 +526,7 @@ function buildNonHousingTerminal(session: SessionState): string {
 
 function buildTerminalServices(session: SessionState): string {
   // Check if this is a non-housing need
-  const housingRelatedNeeds = ['Emergency Housing', 'Advice'];
+  const housingRelatedNeeds = ['Emergency Housing'];
   if (session.supportNeed && !housingRelatedNeeds.includes(session.supportNeed)) {
     return buildNonHousingTerminal(session);
   }
@@ -1060,11 +1072,19 @@ export function processInput(session: SessionState, input: string): RoutingResul
     case 'B5_MAIN_SUPPORT_NEED':
       const needOptions = ['Emergency Housing', 'Food', 'Work', 'Health', 'Advice', 'Drop In', 'Financial', 'Items', 'Services', 'Comms', 'Training', 'Activities'];
       const need = choice ? needOptions[choice - 1] : null;
-      
-      // Housing-related needs require full profiling (age, gender, homelessness status, etc.)
-      const housingRelatedNeeds = ['Emergency Housing', 'Advice'];
+
+      // Advice routes to subcategory selection
+      if (need === 'Advice') {
+        return {
+          ...phrase('B5A_ADVICE_TYPE', session.isSupporter),
+          stateUpdates: { currentGate: 'B5A_ADVICE_TYPE', supportNeed: need, needCount: session.needCount + 1 }
+        };
+      }
+
+      // Housing needs require full profiling
+      const housingRelatedNeeds = ['Emergency Housing'];
       const needsFullProfiling = housingRelatedNeeds.includes(need || '');
-      
+
       if (needsFullProfiling) {
         // Continue to homelessness status question
         return {
@@ -1076,7 +1096,13 @@ export function processInput(session: SessionState, input: string): RoutingResul
         const updatedSession = { ...session, supportNeed: need, needCount: session.needCount + 1 };
         return routeToNextProfileQuestion(updatedSession);
       }
-    
+
+    case 'B5A_ADVICE_TYPE':
+      const adviceOptions = ['Advice:Benefits', 'Advice:Debt', 'Advice:Employment', 'Advice:Immigration', 'Advice:Health', 'Advice:Legal', 'Advice:General'];
+      const adviceSub = choice ? adviceOptions[choice - 1] : null;
+      const adviceSession = { ...session, adviceSubcategory: adviceSub };
+      return routeToNextProfileQuestion(adviceSession);
+
     // ============================================================
     // CATEGORY-SPECIFIC PROFILING GATES
     // ============================================================

lib/types.ts

@@ -26,6 +26,7 @@ export type GateType =
   | 'B3_AGE_CATEGORY'
   | 'B4_GENDER'
   | 'B5_MAIN_SUPPORT_NEED'
+  | 'B5A_ADVICE_TYPE'
   | 'B5_PROFILE_AGE'
   | 'B5_PROFILE_GENDER'
   | 'B5_PROFILE_LGBTQ'
@@ -107,6 +108,7 @@ export interface SessionState {
   ageCategory: string | null;
   gender: string | null;
   supportNeed: string | null;
+  adviceSubcategory: string | null;
   additionalNeeds: string[];
   needCount: number;
 
@@ -223,6 +225,7 @@ export interface UserProfile {
   publicFunds?: string | null;
   lgbtqServicePreference?: string | null;
   dv?: boolean;
+  adviceSubcategory?: string | null;
 }
 
 export interface ServiceCard {
@@ -260,5 +263,6 @@ export function toUserProfile(session: SessionState): UserProfile {
     publicFunds: session.publicFunds,
     lgbtqServicePreference: session.lgbtqServicePreference,
     dv: session.safeguardingType === 'DOMESTIC_ABUSE',
+    adviceSubcategory: session.adviceSubcategory,
   };
 }