Skip to content

SMS Journey Orchestration Contract

GiveCare reference note for the hard-cut Greenfield SMS journey contract in ../gc-sms/README.md, ../gc-sms/CODEMAP.md, ../gc-sms/docs/service-blueprint.md, ../gc-sms/docs/architecture.md, ../gc-sms/docs/domain-contract.md, ../gc-sms/docs/convex-runtime.md, ../gc-sms/convex/turns.ts, ../gc-sms/convex/mira.ts, ../gc-sms/convex/context.ts, ../gc-sms/convex/transport.ts, ../gc-sms/convex/http.ts, ../gc-sms/convex/followups.ts, ../gc-sms/convex/operator.ts, ../gc-sms/convex/learning.ts, ../gc-sms/convex/schema.ts, ../gc-sms/domain/index.ts, ../gc-sms/agent/piRunner.ts, ../gc-sms/agent/tools.ts, ../gc-sms/agent/finalReplyContract.ts, ../gc-sms/agent/miraSystemPrompt.ts, ../gc-sms/knowledge/catalog.ts, and ../gc-sms/knowledge/toolAdapters.ts.

Key information used in wiki

  • The current runtime is a Greenfield product kernel: Inbound -> Gate -> Context -> Reason -> Commit.
  • The caregiver experience is progressive and interruptible: signup asks who the caregiver supports, GC-SDOH-6 starts only after context and assent, immediate needs interrupt without discarding progress, and follow-up requires observed consent.
  • A low GC-SDOH-6 domain can derive a four-question GC-SDOH-30 refinement only after an ordinary support turn. MORE supplies assent; the refinement has no scheduled cadence.
  • The model is not the owner of compliance, safety, memory, transport, or proof. domain/index.ts owns deterministic gates, reply validation, and proposed intent validation; Convex commit decides what becomes durable.
  • convex/turns.ts owns inbound receipt, idempotent durable setup, gate events, turn phases, commit, intent application, review routing, failure routing, and scheduled Pi handoff.
  • convex/mira.ts owns the one Pi reasoning action: reserve the received turn, assemble context, run the Pi adapter, and commit/review/fail exactly once.
  • convex/context.ts assembles a minimal safe context from recent messages, memories, open loops, channel constraints, consent state, and model metadata.
  • agent/piRunner.ts, agent/tools.ts, agent/finalReplyContract.ts, and agent/miraSystemPrompt.ts define the Pi Agent Core adapter, approved tools, final structured output, trace redaction, and SMS prompt contract.
  • Generated knowledge is loaded from knowledge/generated/* through knowledge/catalog.ts; knowledge/toolAdapters.ts and agent/tools.ts expose benefits, resources, guidance cards, and strategy suggestions to Pi in-process. Public wiki pages should not describe live Convex knowledge tables or lookup queries.
  • The deterministic safety and compliance branch can commit without Pi. The Pi branch must pass final reply validation and intent validation before commit writes outbound, memory, loops, assessments, events, or proof signals.
  • Follow-up loops are caregiver-owned. A scheduled follow-up requires an allowed basis, observed consent, bounded future dueAt, and a stop condition before Convex schedules delivery.
  • Transport is an outbox. Commit writes queued work; convex/transport.ts, convex/twilio.ts, convex/http.ts, and convex/crons.ts handle sending, leases, callbacks, and stale-send recovery.
  • Operator and learning surfaces are projections over events and current state: convex/operator.ts, convex/partner.ts, and convex/learning.ts.
  • The retired BrownZip runtime exists in git history only. Current-tense wiki claims should not cite retired files such as convex/agent.ts, convex/scheduler.ts, convex/agentDb.ts, convex/outbound.ts, or src/*.