Skip to content

SMS Journey Orchestration Contract

GiveCare reference note for the current v2 SMS journey contract in ../gc-sms/CLAUDE.md, ../gc-sms/ARCHITECTURE.md, ../gc-sms/convex/agent.ts, ../gc-sms/convex/scheduler.ts, ../gc-sms/convex/admin.ts, ../gc-sms/convex/http.ts, ../gc-sms/convex/signup.ts, ../gc-sms/convex/signupDb.ts, ../gc-sms/convex/outbound.ts, ../gc-sms/convex/outboundDb.ts, ../gc-sms/convex/schema.ts, ../gc-sms/src/memoryKeys.ts, ../gc-sms/src/turn/pipeline.ts, ../gc-sms/src/policy.ts, ../gc-sms/src/classifier.ts, ../gc-sms/src/guidance.ts, ../gc-sms/src/prompt.ts, ../gc-sms/src/model.ts, ../gc-sms/src/tools.ts, ../gc-sms/src/navigation.ts, ../gc-sms/src/context.ts, ../gc-sms/src/evaluator.ts, and ../gc-sms/src/harnessReplay.ts.

Key information used in wiki

  • The current runtime uses two simple caregiver state axes instead of the archived v1 journeyPhase: caregivers.phase (onboarding, active, paused, crisis) and caregivers.loopStage (consent, profile, active).
  • The model is not the owner of compliance or safety. The harness runs STOP/HELP/SHARE, pending-consent YES, START, consent gating, and crisis detection before any model turn.
  • convex/scheduler.ts owns the async job queue for inbound, welcome, follow-up, and proactive turns, including quiet-hours deferral and outbound rate checks.
  • convex/agent.ts owns the turn sequence: policy -> context -> model -> evaluate -> postprocess -> commit -> scheduler enqueue. Unknown phone numbers are recorded in unknownInboundSms before receiving the signup nudge so Twilio retries dedupe and top-of-funnel SMS demand is measurable.
  • src/memoryKeys.ts centralizes the memory contract, while src/turn/pipeline.ts centralizes policy gate order and post-model assessment/benefits/profile side effects.
  • src/model.ts owns the Pi/Gemini interaction, including context transform, typed tool use, proactive single-shot turns, and compaction handling.
  • src/classifier.ts labels each turn with caregiver domain, risk, urgency, and missing context before the model branch; those labels are stored as trace flags.
  • src/guidance.ts turns classifier labels into a compact caregiver-first brief and loads the matching care-domain skill pack.
  • src/navigation.ts derives the active domain navigation frame, including typed known facts, missing slots, viable routes, outcome targets, and a compact care-state map. src/context.ts injects that frame as Pi context so the model gets legible pathing without introducing a second planner, graph runtime, or caregiver-facing taxonomy.
  • src/prompt.ts defines the SMS style-guide contract used by the default harness prompt: short SMS, memory awareness, caregiver-first posture, emotional tone, safety triage, resource/benefits lookup, escalation, follow-up cadence, and one next step.
  • src/evaluator.ts maps evaluator flags back to gc-bench A/B/C/D/F failure mode IDs so trace reports can speak the same language as the benchmark.
  • convex/admin.ts exposes harnessHealthReport and productionFlowReport; the latter summarizes pending/failed outbound messages, failed/expired jobs, open safety events, and fallback/human-review traces. getDailyMetrics exposes small source/sponsor/org rollups for growth and partner reporting.
  • convex/http.ts, convex/signup.ts, and convex/signupDb.ts preserve a small attribution object across web events, email leads, assessment handoffs, signup conversion, and caregiver records.
  • src/tools.ts defines the caregiver-owned tool surface, including trackCaregiverLoop and updateCaregiverLoop.
  • src/evaluator.ts blocks or falls back on unsafe replies, including crisis language, clinical claims, benefits/legal certainty, coercive tone, boundary claims, missing caregiver-first framing, missing operational next step, low-specificity replies, classifier-aware missing escalation, and obvious multi-step SMS replies.
  • tests/scenarios/sms-harness-smoke.json and src/harnessReplay.ts provide the seed product-QA scenario bank and deterministic replay adapter. Scenario rows include executable autofailPatterns that can block mocked drafts in replay without depending on exact model output; replay also injects the chief-of-staff brief and runs the pure postprocess step for approved memory writes and caregiver profile patch derivation. The same adapter can build a full model input and call an injected model runner, which lets tests use a fake runner and future operator scripts pass the live runMiraTurn runner without touching Twilio. The opt-in pnpm test:live-replay path is skipped unless RUN_LIVE_HARNESS_REPLAY=1 and GEMINI_API_KEY are available.
  • The archived v1 sms/turns/* runtime and richer journey-phase contract remain useful historical context, but current-tense wiki claims should cite the v2 files above.