Care Proposals

Part of the Anaya Care Handbook — the source of truth for how the product must behave. When the product needs to change, change this document first, then make the system match it.

What this covers

A care proposal is the agency's priced offer of care for a prospective client. It bundles the client's information, a Simplified Routine Task Inventory, a written care plan, a service definition (type of care, value-added services, weekly schedule), and a rate calculation (priced from the base rates). The proposal moves through an internal review and approval workflow, is then emailed to the family's representative, and — once the representative signs and accepts it — is converted into a managed client, at which point the proposal enters service and its lifecycle ends.

The proposal's client information and assessment are the same shared intake shape used by the initial assessment and (later) the client record, so converting an initial assessment into a proposal — and the proposal into a client — carries everything across without re-entry.

Key terms

• Care proposal — the agency's complete, priced offer of care sent to a family for acceptance.
• Care Circle — everyone involved in the client's care other than the client (defined in full on Clients); it replaces the old "family contacts" list on the proposal.
• Responsible party — the one Care Circle member (or the client themselves) who authorizes the care plan and is the default recipient of the emailed proposal; resolved, never invented.
• Proposal addressee — the people the proposal's cover letter is written to (the client, one or more Care Circle members, or both); the choice sets the cover-letter tone.
• Cover letter / care goal / care areas — the parts of the AI-generated care plan: an opening cover letter, a care-goal statement, and nine care-area lists.
• Cover-letter tone — the voice of the cover letter, derived from the addressees: self-directed, collaborative, or surrogate-led. There is no manual tone picker.
• Representative — the portal login given to a Care Circle member so they can view the proposal, request changes, and sign to accept it. An account is created automatically for each addressed Care Circle member who has an email when the proposal is sent.
• Reviewer — an agency staff member assigned to check the proposal section by section before it can be approved.
• Flag — a reviewer's objection on one section of the proposal; every flag must be resolved before approval.
• Review round — one full cycle of review. Resolved flags from an earlier round never block a later round.
• Version snapshot — a frozen copy of the proposal taken at each milestone, so reviewers can see exactly what changed since they last looked.
• Content diff — the section-by-section comparison of two version snapshots (or a review's snapshot against the latest), surfaced with "Changed" badges during review.
• Word document (DOCX) — the canonical, Word-editable proposal artifact; every PDF (view, preview, signing, email, archive) is a conversion of it.
• Signed copy — the accepted proposal's Word original and its signed PDF rendering, both stored permanently once accepted.
• In Service — the final status of a successful proposal, reached when care actually begins for the client.

How it works

The five sections

Every proposal holds the same five sections: client information (including the Care Circle and a resolved responsible party), the Simplified Routine Task Inventory, the written care plan (a cover letter, a care goal, and nine care areas), the service definition, and the rate calculation. Every proposal gets its own assessment at creation — blank when created directly, or pre-filled when converted from an initial assessment. A proposal is complete when the client's first and last name, birth date, city, and region are filled in, there is at least one Care Circle member with a name, email, and relationship together with a resolved responsible party, the assessment is finished, a service type is chosen, and at least one active hourly rate exists.

AI generation of the care plan

The proposal's care plan — its cover letter, care goal, and nine care areas — can be drafted by a durable AI run. The run writes into the existing proposal (it never creates a new one), only one generation is allowed in flight per proposal, and it is tenant-scoped. It never fabricates: it is grounded only in the proposal's own intake, its Simplified Routine Task Inventory, and the business knowledge base, with the care manager's additional instructions taking priority. When a high-value clinical fact (mobility, cognition, continence, a diagnosis, or who the proposal is addressed to) is missing or ambiguous, the run pauses and asks the care manager one source-cited, choice-based clarifying question, then folds the answer back in before finishing — there is no separate approve/reject review gate. The cover-letter tone is derived automatically from the addressees: self-directed (addressed to the client), collaborative (client plus others), or surrogate-led (others only). Output is written to a Word document, from which every PDF is derived.

Lifecycle

• Draft — being written by its author.
• Pending Approval — submitted to a named group of reviewers.
• Approved — passed internal review; ready to send to the family.
• Sent to Representative — emailed to the family contact for a decision.
• Revisions Needed — sent back for changes, either by internal reviewers or by the representative (the history records which).
• Representative Accepted — signed by the family; ready to create the client record.
• Declined — the representative turned the proposal down outright (terminal).
• In Service — care has started; the proposal is finished (terminal).
• Cancelled — abandoned at any earlier point (terminal).

Authors and editors move proposals along the main path (submit, withdraw, resubmit). Approvers decide review outcomes and may cancel. Representatives can only accept, request changes, or decline. Which moves a person may make is resolved by permission, in precedence: Care Proposals Approve (admin roles — the full forward path, withdraw, and cancel) outranks Care Proposals Manage (sequential moves only, no skipping steps) outranks Care Proposals Respond (a representative — accept, request changes, or decline, and only from Sent to Representative). Four moves can never be picked by hand: Approved and the internal Revisions Needed only happen by submitting a review round, Sent to Representative only happens by successfully emailing the proposal, and In Service only happens by creating a client from an accepted proposal. The UI presents named actions (Submit for Approval, Send Email, Create Client Record, Accept, Request Changes, Decline…), never a raw status picker.

Internal review

The author submits the proposal naming one to twenty reviewers from their own agency. Reviewers go through the proposal section by section, approving or flagging each one, and then submit the round: if any flag is still open the proposal goes to Revisions Needed, otherwise it is Approved. The author resolves each flag by recording what was changed, and once every flag is resolved may re-request review, which returns the proposal to Pending Approval with the same reviewers. Each review is stamped with the version snapshot the reviewer was looking at, so the reviewer can later see a section-by-section comparison of what changed since they flagged it. This content diff is a first-class part of review — "Changed" badges, a show/hide-changes toggle, and separate client-info and assessment diff viewers let a reviewer compare their filed snapshot to the latest, or any two versions.

Sending, signing, and conversion

Once approved, staff email the proposal to its addressed Care Circle members. Each addressee who has an email automatically gets a representative account and a personal link to view the proposal online, and the email can attach the PDF and/or the Word file. Every send, and whether each email was delivered and opened, is recorded on the proposal. The representative either signs the proposal electronically — which stores both the signed PDF and the canonical signed Word document permanently, and triggers a welcome email to the responsible party — or requests changes, sending it back to Revisions Needed for the team to revise and re-send — or declines the proposal outright, which ends it permanently (who, when, and an optional reason are recorded; the agency is notified). Declining is for a firm "no" (the family is not going ahead), unlike requesting changes, which keeps the proposal alive for another round. A declined proposal can never be revived; if the family later changes their mind, staff duplicate it into a fresh Draft and start the lifecycle again.

After acceptance, staff create the client from the proposal. This creates a new client record in Draft status carrying the proposal's client details — including its Care Circle, responsible party, and care-decision involvement, with no re-entry — its assessment (the Simplified Routine Task Inventory is seeded already Completed), and its service type, but no shifts and no caregiver assignments; scheduling and staffing happen afterwards in Care Plans and Scheduling. Every Care Circle member with an email is automatically provisioned portal access. Creating the client links the two records and moves the proposal to In Service; the client stays Draft until its first care plan is published, which is what makes it Active.

Rules

Implementation status — audited against apps/backend/src/care-proposals, @anaya/shared/care-proposal-transitions.ts, the AI care-proposal agent (apps/backend/src/ai/agents/care-proposal), the DOCX/PDF services (apps/backend/src/docx, apps/backend/src/pdf), the platform activity log (apps/backend/src/platform-logs), and the shared intake/care-circle package on 2026-07-28. ✅ In code · ⚠️ Partial (built, but doesn't fully match the rule) · 🚧 Spec only (not yet built).

• CP-1 — A care proposal can be created in three ways: directly by agency staff, by converting a completed initial assessment (which can be converted only once, and only when Completed), or by duplicating an existing proposal. All three start the proposal in Draft. (✅ In code)
• CP-2 — Every proposal belongs to exactly one agency. Staff can only ever see or act on proposals of their own agency, including resolving and un-resolving review flags. (✅ In code)
• CP-3 — Every proposal gets its own assessment at creation: blank for directly created proposals, or a lossless clone of the whole intake for converted ones — client information (Care Circle, responsible party, addressees, care-decision involvement, benefits), service type, value-added services and weekly schedule, the rate computation (copied as-is, nothing recomputed), the narrative, and the assessment. Later edits to either side do not affect the other. (✅ In code)
• CP-4 — A proposal's status can only move along the lifecycle above, and only by a person whose permission allows that move. Moves resolve by precedence: Care Proposals Approve (full forward path, withdraw, cancel) > Care Proposals Manage (sequential moves, no skipping) > Care Proposals Respond (a representative — accept, request changes, or decline). Any other status change must be refused. (✅ In code)
• CP-5 — Submitting for approval requires naming 1–20 reviewers, each an active member of the same agency who is authorized to review proposals. (✅ In code)
• CP-6 — Every status change except cancellation and decline requires the proposal to be complete (see "The five sections"). Cancellation and decline are always allowed regardless of completeness, as is withdrawing a submitted proposal back to Draft (see CP-24). (✅ In code)
• CP-7 — Approved and the internal Revisions Needed can never be chosen by hand; they can only result from submitting a review round. (✅ In code)
• CP-8 — A review round cannot be submitted until at least one section has been reviewed, and a proposal cannot be approved while any flag in the current round is unresolved. (✅ In code)
• CP-9 — Only flagged sections can be resolved, and resolving always requires a written note saying what was changed. (✅ In code)
• CP-10 — Review can only be re-requested when the proposal is in Revisions Needed, the current round has at least one flag, and every flag has been resolved. Re-requesting returns the proposal to the same assigned reviewers unless new ones are named. (✅ In code)
• CP-11 — Each fresh submission for approval, and each fresh send to the representative after revisions, starts a new review round. Resends and withdrawals do not. Flags resolved in an earlier round never block a later round. (✅ In code)
• CP-12 — A reviewer can only edit or delete their own review comments. (✅ In code)
• CP-13 — A version snapshot must be taken at every milestone (submission, resubmission, approval, send, request for revisions, acceptance), and every review records which snapshot the reviewer saw. Reviews cannot be filed before the first snapshot exists. (✅ In code — snapshot creation is awaited; if it fails, the history entry and the current status are rolled back together (CP-35) so a proposal is never left in a reviewable status without a version stamp)
• CP-14 — Sent to Representative only happens as the result of successfully emailing an Approved, complete proposal with no unresolved flags. Every send and its delivery outcome is recorded on the proposal. (✅ In code — sending auto-moves an Approved proposal to Sent to Representative, and per-recipient delivery statuses are updated as they arrive)
• CP-15 — Emailing the proposal automatically creates a representative account for each addressed Care Circle member who has an email. People who are not Care Circle members never get an account. (✅ In code)
• CP-16 — Only a representative whose email matches an addressed Care Circle member can accept the proposal, request changes, or decline it. Responding to proposals is inherent to the Representative role and cannot be removed by permission configuration (ACCESS-35). (✅ In code — email match enforced for accept, request-changes, and decline)
• CP-17 — Accepting a proposal always requires the representative's electronic signature. Both the signed PDF and the canonical signed Word document are stored permanently with the proposal, and the responsible party receives a welcome email. (✅ In code)
• CP-18 — The proposal document — both the PDF and the Word file — can only be downloaded once the proposal is Approved, Sent to Representative, Representative Accepted, or In Service. A preview is always available to staff authorized to view the proposal. (⚠️ Partial — the download status gate is enforced server-side, but the preview is only gated in the web app, not the backend)
• CP-19 — A client can only be created from a proposal that is complete and Representative Accepted, and only by staff authorized to do so. Creating the client is the only path to In Service (there is no separate “Start Service” status action). The new client starts in Draft carrying the Care Circle, responsible party, and care-decision involvement (no re-entry), with its Simplified Routine Task Inventory seeded Completed and portal access provisioned for Care Circle members with an email — but no shifts and no caregiver assignments. The proposal moves to In Service and is linked to the client; the client stays Draft until its first care plan is published. If a client is already linked, re-calling create is idempotent and repairs the In Service transition. (✅ In code)
• CP-20 — In Service, Cancelled, and Declined are terminal: a proposal in any of these statuses can never change status again. (✅ In code)
• CP-21 — Only approver-level staff can cancel a proposal, from any non-terminal status. (✅ In code)
• CP-22 — Authorship can only be transferred to someone in the proposal's own agency who is allowed to create and edit care proposals, and never to the current author. Eligibility follows that permission rather than a list of role names, so staff on a custom role that authors proposals are eligible on the same terms as an Admin. The list offered and the check enforced are the same rule, so a name that appears can always be transferred to. (✅ In code)
• CP-23 — Visibility: staff with full view rights see every proposal in their agency; staff with limited view rights see only proposals they authored or were assigned to review — including each proposal's assessment; representatives see only proposals addressed to their email. (⚠️ Partial — the scoped visibility filter exists and covers the proposal list, but not every endpoint applies it; see Known gaps)
• CP-24 — The author can withdraw a submitted proposal back to Draft at any time before the review round is decided, and submit it again later. (✅ In code — withdrawal uses the Pending Approval → Draft move and is exempt from the completeness check, so a proposal that became incomplete after submission can still be withdrawn for editing)
• CP-25 — When two people try to change a proposal's status at the same time, only the first change succeeds; the second is refused and must be retried against the new status. (✅ In code — status changes are written atomically with the expected current status as a precondition)
• CP-26 — Deleting a proposal also deletes its own assessment, and either unlinks or (at the deleter's choice) deletes the originating initial assessment. (✅ In code)
• CP-27 — A representative may decline a proposal that is Sent to Representative. Declining records who declined, when, and an optional reason, and moves the proposal to Declined — a terminal status. No signature is collected, no client is created, and the proposal can never change status again; to try again, staff duplicate it into a new Draft. The agency is notified when a proposal is declined. (✅ In code)
• CP-28 — AI generation writes the care plan (cover letter, care goal, and nine care areas) into the existing proposal — never a new one — with only one run in flight per proposal, tenant-scoped, and it never fabricates content. (✅ In code)
• CP-29 — Generation's human-in-the-loop is clarification-only: the run pauses and asks the care manager a single source-cited, choice-based question when a high-value clinical fact is unclear, and folds the answer back in before finishing. There is no approve/reject review gate. (✅ In code)
• CP-30 — Generation is grounded only in the proposal's own intake, its Simplified Routine Task Inventory, and the business knowledge base (which fails soft), with the care manager's additional instructions taking priority. (✅ In code)
• CP-31 — The Word document is the canonical proposal artifact; every PDF (view, preview, signing, email attachment, archived copy) is a conversion of it, and both the PDF and the Word file may be sent or downloaded. (✅ In code)
• CP-32 — Client information is a Care Circle (everyone but the client) with a resolved responsible party; the responsible party is never auto-invented, and completion is blocked without one. (✅ In code — see Clients for the model)
• CP-33 — The cover-letter tone is derived from the proposal's addressees — self-directed (client only), collaborative (client plus others), or surrogate-led (others only). There is no manual tone picker. (✅ In code)
• CP-34 — The proposal rate is the matched city rate (else the global base rate), uplifted by the assessment score (0.1% per point, capped at +50%), with overtime blended above 8 hours a day, a flat live-in rate at 16 hours or more, and active value-added-service rates added on; the rate section is complete when at least one active hours bucket has a rate above zero. See Base Rates for the catalog. (✅ In code)
• CP-35 — A proposal's current status and its status history are one fact recorded two ways: the history is the ordered, user-visible record of every transition it has been through, oldest first, and the current status is always its newest entry. They can never disagree — a transition either records both or neither, and a rolled-back transition removes both. The proposal's own history is what the timeline shows and what review rounds are counted from; the platform activity log is a separate compliance record and is never read to build a proposal screen. (✅ In code)

Who can do what

Decisions needed

• Must every proposal originate from an initial assessment? Today direct creation is fully supported, yet the product's own wording suggests proposals start from an assessment. Options: keep all three creation paths, or require a completed initial assessment before a proposal can exist.
• Should deleting a proposal delete its client? Today deleting a proposal also deletes the linked client, even one already receiving care. Options: block deletion once a client exists, unlink instead of delete, or keep the cascade.
• What is the representative's mobile journey? Representatives are onboarded as mobile users and the welcome email promotes the mobile app, but reviewing and accepting a proposal only works on the web. Options: build a mobile acceptance flow, or stop steering representatives toward the mobile app.